Skip to content

Commit 4da7f62

Browse files
edmocostaedmocosta
authored
Standardize and add SSL settings (#168)
This commit made the plugin SSL settings consistent with the naming convention defined in the meta issue: elastic/logstash#14905. It added the following SSL settings: ssl_enabled: Enable/disable the SSL settings. If not provided, the value is inferred from the hosts' scheme ssl_certificate: OpenSSL-style X.509 certificate file to authenticate the client ssl_key: OpenSSL-style RSA private key that corresponds to the ssl_certificate ssl_truststore_path: The JKS truststore to validate the server's certificate ssl_truststore_type: The format of the truststore file ssl_truststore_password: The truststore password ssl_keystore_path: The keystore used to present a certificate to the server ssl_keystore_type: The format of the keystore file ssl_keystore_password: The keystore password ssl_cipher_suites: The list of cipher suites to use ssl_supported_protocols: Supported protocols with versions ssl_verification_mode: Defines how to verify the certificates presented by another party in the TLS connection And deprecated: ssl in favor of ssl_enabled ca_file in favor of ssl_certificate_authorities keystore in favor of ssl_keystore_path keystore_password in favor of ssl_keystore_password
1 parent 6ff00f0 commit 4da7f62

File tree

9 files changed

+669
-71
lines changed

9 files changed

+669
-71
lines changed

‎.ci/logstash-run.sh‎

Lines changed: 8 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -24,9 +24,14 @@ wait_for_es() {
2424
}
2525

2626
if [[ "$INTEGRATION" != "true" ]]; then
27-
jruby -rbundler/setup -S rspec -fd -t ~integration spec/filters
27+
bundle exec rspec --format=documentation spec/filters --tag ~integration --tag ~secure_integration
2828
else
29-
extra_tag_args="-t integration"
29+
if [[ "$SECURE_INTEGRATION" == "true" ]]; then
30+
extra_tag_args="--tag secure_integration"
31+
else
32+
extra_tag_args="--tag ~secure_integration --tag integration"
33+
fi
34+
3035
wait_for_es
31-
jruby -rbundler/setup -S rspec -fd $extra_tag_args -t es_version:$ELASTIC_STACK_VERSION spec/filters/integration
36+
bundle exec rspec --format=documentation $extra_tag_args --tag update_tests:painless --tag es_version:$ELASTIC_STACK_VERSION spec/filters/integration
3237
fi

‎CHANGELOG.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,23 @@
1+
## 3.15.0
2+
- Added SSL settings for: [#168](https://github.com/logstash-plugins/logstash-filter-elasticsearch/pull/168)
3+
- `ssl_enabled`: Enable/disable the SSL settings. If not provided, the value is inferred from the hosts scheme
4+
- `ssl_certificate`: OpenSSL-style X.509 certificate file to authenticate the client
5+
- `ssl_key`: OpenSSL-style RSA private key that corresponds to the `ssl_certificate`
6+
- `ssl_truststore_path`: The JKS truststore to validate the server's certificate
7+
- `ssl_truststore_type`: The format of the truststore file
8+
- `ssl_truststore_password`: The truststore password
9+
- `ssl_keystore_path`: The keystore used to present a certificate to the server
10+
- `ssl_keystore_type`: The format of the keystore file
11+
- `ssl_keystore_password`: The keystore password
12+
- `ssl_cipher_suites`: The list of cipher suites to use
13+
- `ssl_supported_protocols`: Supported protocols with versions
14+
- `ssl_verification_mode`: Defines how to verify the certificates presented by another party in the TLS connection
15+
- Reviewed and deprecated SSL settings to comply with Logstash's naming convention
16+
- Deprecated `ssl` in favor of `ssl_enabled`
17+
- Deprecated `ca_file` in favor of `ssl_certificate_authorities`
18+
- Deprecated `keystore` in favor of `ssl_keystore_path`
19+
- Deprecated `keystore_password` in favor of `ssl_keystore_password`
20+
121
## 3.14.0
222
- Added support for configurable retries with new `retry_on_failure` and `retry_on_status` options [#160](https://github.com/logstash-plugins/logstash-filter-elasticsearch/pull/160)
323

‎docs/index.asciidoc‎

Lines changed: 189 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -121,14 +121,13 @@ The `monitoring` permission at cluster level is necessary to perform periodic co
121121
[id="plugins-{type}s-{plugin}-options"]
122122
==== Elasticsearch Filter Configuration Options
123123

124-
This plugin supports the following configuration options plus the <<plugins-{type}s-{plugin}-common-options>> described later.
124+
This plugin supports the following configuration options plus the <<plugins-{type}s-{plugin}-common-options>> and the <<plugins-{type}s-{plugin}-deprecated-options>> described later.
125125

126126
[cols="<,<,<",options="header",]
127127
|=======================================================================
128128
|Setting |Input type|Required
129129
| <<plugins-{type}s-{plugin}-aggregation_fields>> |<<hash,hash>>|No
130130
| <<plugins-{type}s-{plugin}-api_key>> |<<password,password>>|No
131-
| <<plugins-{type}s-{plugin}-ca_file>> |a valid filesystem path|No
132131
| <<plugins-{type}s-{plugin}-ca_trusted_fingerprint>> |<<string,string>>|No
133132
| <<plugins-{type}s-{plugin}-cloud_auth>> |<<password,password>>|No
134133
| <<plugins-{type}s-{plugin}-cloud_id>> |<<string,string>>|No
@@ -143,11 +142,22 @@ This plugin supports the following configuration options plus the <<plugins-{typ
143142
| <<plugins-{type}s-{plugin}-query_template>> |<<string,string>>|No
144143
| <<plugins-{type}s-{plugin}-result_size>> |<<number,number>>|No
145144
| <<plugins-{type}s-{plugin}-retry_on_failure>> |<<number,number>>|No
146-
| <<plugins-{type}s-{plugin}-result_on_status_>> |<<number,number list>>|No
145+
| <<plugins-{type}s-{plugin}-retry_on_status>> |<<number,number list>>|No
147146
| <<plugins-{type}s-{plugin}-sort>> |<<string,string>>|No
148-
| <<plugins-{type}s-{plugin}-ssl>> |<<boolean,boolean>>|No
149-
| <<plugins-{type}s-{plugin}-keystore>> |a valid filesystem path|No
150-
| <<plugins-{type}s-{plugin}-keystore_password>> |<<password,password>>|No
147+
| <<plugins-{type}s-{plugin}-ssl>> |<<boolean,boolean>>|__Deprecated__
148+
| <<plugins-{type}s-{plugin}-ssl_certificate>> |<<path,path>>|No
149+
| <<plugins-{type}s-{plugin}-ssl_certificate_authorities>> |list of <<path,path>>|No
150+
| <<plugins-{type}s-{plugin}-ssl_cipher_suites>> |list of <<string,string>>|No
151+
| <<plugins-{type}s-{plugin}-ssl_enabled>> |<<boolean,boolean>>|No
152+
| <<plugins-{type}s-{plugin}-ssl_key>> |<<path,path>>|No
153+
| <<plugins-{type}s-{plugin}-ssl_keystore_password>> |<<password,password>>|No
154+
| <<plugins-{type}s-{plugin}-ssl_keystore_path>> |<<path,path>>|No
155+
| <<plugins-{type}s-{plugin}-ssl_keystore_type>> |<<string,string>>|No
156+
| <<plugins-{type}s-{plugin}-ssl_supported_protocols>> |<<string,string>>|No
157+
| <<plugins-{type}s-{plugin}-ssl_truststore_password>> |<<password,password>>|No
158+
| <<plugins-{type}s-{plugin}-ssl_truststore_path>> |<<path,path>>|No
159+
| <<plugins-{type}s-{plugin}-ssl_truststore_type>> |<<string,string>>|No
160+
| <<plugins-{type}s-{plugin}-ssl_verification_mode>> |<<string,string>>, one of `["full", "none"]`|No
151161
| <<plugins-{type}s-{plugin}-tag_on_failure>> |<<array,array>>|No
152162
| <<plugins-{type}s-{plugin}-user>> |<<string,string>>|No
153163
|=======================================================================
@@ -182,19 +192,11 @@ Example:
182192
* There is no default value for this setting.
183193

184194
Authenticate using Elasticsearch API key. Note that this option also requires
185-
enabling the `ssl` option.
195+
enabling the <<plugins-{type}s-{plugin}-ssl_enabled>> option.
186196

187197
Format is `id:api_key` where `id` and `api_key` are as returned by the
188198
Elasticsearch {ref}/security-api-create-api-key.html[Create API key API].
189199

190-
[id="plugins-{type}s-{plugin}-ca_file"]
191-
===== `ca_file`
192-
193-
* Value type is <<path,path>>
194-
* There is no default value for this setting.
195-
196-
SSL Certificate Authority file
197-
198200
[id="plugins-{type}s-{plugin}-ca_trusted_fingerprint"]
199201
===== `ca_trusted_fingerprint`
200202

@@ -364,30 +366,140 @@ Which HTTP Status codes to consider for retries (in addition to connection error
364366

365367
Comma-delimited list of `<field>:<direction>` pairs that define the sort order
366368

367-
[id="plugins-{type}s-{plugin}-ssl"]
368-
===== `ssl`
369+
[id="plugins-{type}s-{plugin}-ssl_certificate"]
370+
===== `ssl_certificate`
371+
* Value type is <<path,path>>
372+
* There is no default value for this setting.
369373

370-
* Value type is <<boolean,boolean>>
371-
* Default value is `false`
374+
SSL certificate to use to authenticate the client. This certificate should be an OpenSSL-style X.509 certificate file.
372375

373-
SSL
376+
NOTE: This setting can be used only if <<plugins-{type}s-{plugin}-ssl_key>> is set.
374377

375-
[id="plugins-{type}s-{plugin}-keystore"]
376-
===== `keystore`
378+
[id="plugins-{type}s-{plugin}-ssl_certificate_authorities"]
379+
===== `ssl_certificate_authorities`
380+
381+
* Value type is a list of <<path,path>>
382+
* There is no default value for this setting
383+
384+
The .cer or .pem files to validate the server's certificate.
385+
386+
NOTE: You cannot use this setting and <<plugins-{type}s-{plugin}-ssl_truststore_path>> at the same time.
387+
388+
[id="plugins-{type}s-{plugin}-ssl_cipher_suites"]
389+
===== `ssl_cipher_suites`
390+
* Value type is a list of <<string,string>>
391+
* There is no default value for this setting
392+
393+
The list of cipher suites to use, listed by priorities.
394+
Supported cipher suites vary depending on the Java and protocol versions.
395+
396+
397+
[id="plugins-{type}s-{plugin}-ssl_enabled"]
398+
===== `ssl_enabled`
399+
400+
* Value type is <<boolean,boolean>>
401+
* There is no default value for this setting.
402+
403+
Enable SSL/TLS secured communication to Elasticsearch cluster.
404+
Leaving this unspecified will use whatever scheme is specified in the URLs listed in <<plugins-{type}s-{plugin}-hosts>> or extracted from the <<plugins-{type}s-{plugin}-cloud_id>>.
405+
If no explicit protocol is specified plain HTTP will be used.
377406

407+
[id="plugins-{type}s-{plugin}-ssl_key"]
408+
===== `ssl_key`
378409
* Value type is <<path,path>>
379410
* There is no default value for this setting.
380411

381-
The keystore used to present a certificate to the server. It can be either .jks or .p12
412+
OpenSSL-style RSA private key that corresponds to the <<plugins-{type}s-{plugin}-ssl_certificate>>.
382413

383-
[id="plugins-{type}s-{plugin}-keystore_password"]
384-
===== `keystore_password`
414+
NOTE: This setting can be used only if <<plugins-{type}s-{plugin}-ssl_certificate>> is set.
415+
416+
[id="plugins-{type}s-{plugin}-ssl_keystore_password"]
417+
===== `ssl_keystore_password`
385418

386419
* Value type is <<password,password>>
387420
* There is no default value for this setting.
388421

389422
Set the keystore password
390423

424+
[id="plugins-{type}s-{plugin}-ssl_keystore_path"]
425+
===== `ssl_keystore_path`
426+
427+
* Value type is <<path,path>>
428+
* There is no default value for this setting.
429+
430+
The keystore used to present a certificate to the server.
431+
It can be either `.jks` or `.p12`
432+
433+
NOTE: You cannot use this setting and <<plugins-{type}s-{plugin}-ssl_certificate>> at the same time.
434+
435+
[id="plugins-{type}s-{plugin}-ssl_keystore_type"]
436+
===== `ssl_keystore_type`
437+
438+
* Value can be any of: `jks`, `pkcs12`
439+
* If not provided, the value will be inferred from the keystore filename.
440+
441+
The format of the keystore file. It must be either `jks` or `pkcs12`.
442+
443+
[id="plugins-{type}s-{plugin}-ssl_supported_protocols"]
444+
===== `ssl_supported_protocols`
445+
446+
* Value type is <<string,string>>
447+
* Allowed values are: `'TLSv1.1'`, `'TLSv1.2'`, `'TLSv1.3'`
448+
* Default depends on the JDK being used. With up-to-date Logstash, the default is `['TLSv1.2', 'TLSv1.3']`.
449+
`'TLSv1.1'` is not considered secure and is only provided for legacy applications.
450+
451+
List of allowed SSL/TLS versions to use when establishing a connection to the Elasticsearch cluster.
452+
453+
For Java 8 `'TLSv1.3'` is supported only since **8u262** (AdoptOpenJDK), but requires that you set the
454+
`LS_JAVA_OPTS="-Djdk.tls.client.protocols=TLSv1.3"` system property in Logstash.
455+
456+
NOTE: If you configure the plugin to use `'TLSv1.1'` on any recent JVM, such as the one packaged with Logstash,
457+
the protocol is disabled by default and needs to be enabled manually by changing `jdk.tls.disabledAlgorithms` in
458+
the *$JDK_HOME/conf/security/java.security* configuration file. That is, `TLSv1.1` needs to be removed from the list.
459+
460+
[id="plugins-{type}s-{plugin}-ssl_truststore_password"]
461+
===== `ssl_truststore_password`
462+
463+
* Value type is <<password,password>>
464+
* There is no default value for this setting.
465+
466+
Set the truststore password
467+
468+
[id="plugins-{type}s-{plugin}-ssl_truststore_path"]
469+
===== `ssl_truststore_path`
470+
471+
* Value type is <<path,path>>
472+
* There is no default value for this setting.
473+
474+
The truststore to validate the server's certificate.
475+
It can be either `.jks` or `.p12`.
476+
477+
NOTE: You cannot use this setting and <<plugins-{type}s-{plugin}-ssl_certificate_authorities>> at the same time.
478+
479+
[id="plugins-{type}s-{plugin}-ssl_truststore_type"]
480+
===== `ssl_truststore_type`
481+
482+
* Value can be any of: `jks`, `pkcs12`
483+
* If not provided, the value will be inferred from the truststore filename.
484+
485+
The format of the truststore file. It must be either `jks` or `pkcs12`.
486+
487+
[id="plugins-{type}s-{plugin}-ssl_verification_mode"]
488+
===== `ssl_verification_mode`
489+
490+
* Value can be any of: `full`, `none`
491+
* Default value is `full`
492+
493+
Defines how to verify the certificates presented by another party in the TLS connection:
494+
495+
`full` validates that the server certificate has an issue date that’s within
496+
the not_before and not_after dates; chains to a trusted Certificate Authority (CA), and
497+
has a hostname or IP address that matches the names within the certificate.
498+
499+
`none` performs no certificate validation.
500+
501+
WARNING: Setting certificate verification to `none` disables many security benefits of SSL/TLS, which is very dangerous. For more information on disabling certificate verification please read https://www.cs.utexas.edu/~shmat/shmat_ccs12.pdf
502+
391503
[id="plugins-{type}s-{plugin}-tag_on_failure"]
392504
===== `tag_on_failure`
393505

@@ -405,5 +517,57 @@ Tags the event on failure to look up previous log event information. This can be
405517
Basic Auth - username
406518

407519

520+
[id="plugins-{type}s-{plugin}-deprecated-options"]
521+
==== Elasticsearch Filter Deprecated Configuration Options
522+
523+
This plugin supports the following deprecated configurations.
524+
525+
WARNING: Deprecated options are subject to removal in future releases.
526+
527+
[cols="<,<,<",options="header",]
528+
|=======================================================================
529+
|Setting|Input type|Replaced by
530+
| <<plugins-{type}s-{plugin}-ca_file>> |a valid filesystem path|<<plugins-{type}s-{plugin}-ssl_certificate_authorities>>
531+
| <<plugins-{type}s-{plugin}-keystore>> |a valid filesystem path|<<plugins-{type}s-{plugin}-ssl_keystore_path>>
532+
| <<plugins-{type}s-{plugin}-keystore_password>> |<<password,password>>|<<plugins-{type}s-{plugin}-ssl_keystore_password>>
533+
|=======================================================================
534+
535+
[id="plugins-{type}s-{plugin}-ca_file"]
536+
===== `ca_file`
537+
deprecated[3.15.0, Replaced by <<plugins-{type}s-{plugin}-ssl_certificate_authorities>>]
538+
539+
* Value type is <<path,path>>
540+
* There is no default value for this setting.
541+
542+
SSL Certificate Authority file
543+
544+
[id="plugins-{type}s-{plugin}-ssl"]
545+
===== `ssl`
546+
deprecated[3.15.0, Replaced by <<plugins-{type}s-{plugin}-ssl_enabled>>]
547+
548+
* Value type is <<boolean,boolean>>
549+
* Default value is `false`
550+
551+
SSL
552+
553+
[id="plugins-{type}s-{plugin}-keystore"]
554+
===== `keystore`
555+
deprecated[3.15.0, Replaced by <<plugins-{type}s-{plugin}-ssl_keystore_path>>]
556+
557+
* Value type is <<path,path>>
558+
* There is no default value for this setting.
559+
560+
The keystore used to present a certificate to the server. It can be either .jks or .p12
561+
562+
[id="plugins-{type}s-{plugin}-keystore_password"]
563+
===== `keystore_password`
564+
deprecated[3.15.0, Replaced by <<plugins-{type}s-{plugin}-ssl_keystore_password>>]
565+
566+
* Value type is <<password,password>>
567+
* There is no default value for this setting.
568+
569+
Set the keystore password
570+
571+
408572
[id="plugins-{type}s-{plugin}-common-options"]
409573
include::{include_path}/{type}.asciidoc[]

0 commit comments

Comments
 (0)