Standardize SSL settings (logstash-plugins#470)

This commit added the `ssl_enabled` and `ssl_client_authentication` configs. It also deprecates the following settings to comply with Logstash's SSL naming convention:
- `ssl` was deprecated in favor of `ssl_enabled`
- `ssl_verify_mode` was deprecated  in favor of `ssl_client_authentication`

In addition to the new settings, it also changes:
- Using `ssl_verify_mode` should keep the current behavior as it is. Once upgraded to `ssl_client_authentication`, it will validate and reject configurations with `ssl_certificate_authorities` set and `ssl_client_authentication = > none`.  The current `ssl_verify_mode` behavior is to silently ignore the `none` value and use `force_peer/required`.
- Fixed `ssl_peer_metadata` when `ssl_enabled => false`
- Added tests for the new and existing `SslContextBuilder` methods.

Author: edmocosta

CHANGELOG.md

@@ -1,3 +1,8 @@
+## 6.6.0
+ - Reviewed and deprecated SSL settings to comply with Logstash's naming convention [#470](https://github.com/logstash-plugins/logstash-input-beats/pull/470)
+   - Deprecated `ssl` in favor of `ssl_enabled`
+   - Deprecated `ssl_verify_mode` in favor of `ssl_client_authentication`
+
 ## 6.5.0
  - An enrichment `enrich` option added to control ECS passthrough. `ssl_peer_metadata` and `include_codec_tag` configurations are deprecated and can be managed through the `enrich`  [#464](https://github.com/logstash-plugins/logstash-input-beats/pull/464)
 

VERSION

@@ -1 +1 @@
-6.5.0
+6.6.0

docs/index.asciidoc

@@ -221,15 +221,18 @@ This plugin supports the following configuration options plus the <<plugins-{typ
 | <<plugins-{type}s-{plugin}-host>> |<<string,string>>|No
 | <<plugins-{type}s-{plugin}-include_codec_tag>> |<<boolean,boolean>>|__Deprecated__
 | <<plugins-{type}s-{plugin}-port>> |<<number,number>>|Yes
-| <<plugins-{type}s-{plugin}-ssl>> |<<boolean,boolean>>|No
+| <<plugins-{type}s-{plugin}-ssl>> |<<boolean,boolean>>|__Deprecated__
 | <<plugins-{type}s-{plugin}-ssl_certificate>> |a valid filesystem path|No
 | <<plugins-{type}s-{plugin}-ssl_certificate_authorities>> |<<array,array>>|No
+| <<plugins-{type}s-{plugin}-ssl_cipher_suites>> |<<array,array>>|No
+| <<plugins-{type}s-{plugin}-ssl_client_authentication>> |<<string,string>>, one of `["none", "optional", "required"]`|No
+| <<plugins-{type}s-{plugin}-ssl_enabled>> |<<boolean,boolean>>|No
 | <<plugins-{type}s-{plugin}-ssl_handshake_timeout>> |<<number,number>>|No
 | <<plugins-{type}s-{plugin}-ssl_key>> |a valid filesystem path|No
 | <<plugins-{type}s-{plugin}-ssl_key_passphrase>> |<<password,password>>|No
 | <<plugins-{type}s-{plugin}-ssl_peer_metadata>> |<<boolean,boolean>>|__Deprecated__
 | <<plugins-{type}s-{plugin}-ssl_supported_protocols>> |<<array,array>>|No
-| <<plugins-{type}s-{plugin}-ssl_verify_mode>> |<<string,string>>, one of `["none", "peer", "force_peer"]`|No
+| <<plugins-{type}s-{plugin}-ssl_verify_mode>> |<<string,string>>, one of `["none", "peer", "force_peer"]`|__Deprecated__
 | <<plugins-{type}s-{plugin}-tls_max_version>> |<<number,number>>|__Deprecated__
 | <<plugins-{type}s-{plugin}-tls_min_version>> |<<number,number>>|__Deprecated__
 |=======================================================================
@@ -384,6 +387,7 @@ The port to listen on.
 
 [id="plugins-{type}s-{plugin}-ssl"]
 ===== `ssl`
+deprecated[6.6.0, Replaced by <<plugins-{type}s-{plugin}-ssl_enabled>>]
 
   * Value type is <<boolean,boolean>>
   * Default value is `false`
@@ -408,8 +412,8 @@ SSL certificate to use.
 
 Validate client certificates against these authorities.
 You can define multiple files or paths. All the certificates will
-be read and added to the trust store. You need to configure the `ssl_verify_mode`
-to `peer` or `force_peer` to enable the verification.
+be read and added to the trust store. You need to configure the <<plugins-{type}s-{plugin}-ssl_client_authentication>>
+to `optional` or `required` to enable the verification.
 
 [id="plugins-{type}s-{plugin}-ssl_cipher_suites"]
 ===== `ssl_cipher_suites`
@@ -422,6 +426,27 @@ This default list applies for OpenJDK 11.0.14 and higher.
 For older JDK versions, the default list includes only suites supported by that version.
 For example, the ChaCha20 family of ciphers is not supported in older versions.
 
+[id="plugins-{type}s-{plugin}-ssl_client_authentication"]
+===== `ssl_client_authentication`
+
+* Value can be any of: `none`, `optional`, `required`
+* Default value is `"none"`
+
+Controls the server's behavior in regard to requesting a certificate from client connections:
+`required` forces a client to present a certificate, while `optional` requests a client certificate
+but the client is not required to present one. Defaults to `none`, which disables the client authentication.
+
+NOTE: This setting can be used only if <<plugins-{type}s-{plugin}-ssl_certificate_authorities>> is set.
+
+[id="plugins-{type}s-{plugin}-ssl_enabled"]
+===== `ssl_enabled`
+
+  * Value type is <<boolean,boolean>>
+  * Default value is `false`
+
+Events are by default sent in plain text. You can enable encryption by setting `ssl_enabled` to true and configuring
+the <<plugins-{type}s-{plugin}-ssl_certificate>> and <<plugins-{type}s-{plugin}-ssl_key>> options.
+
 [id="plugins-{type}s-{plugin}-ssl_handshake_timeout"]
 ===== `ssl_handshake_timeout`
 
@@ -464,7 +489,7 @@ deprecated[6.5.0, Replaced by <<plugins-{type}s-{plugin}-enrich>>]
 
 Enables storing client certificate information in event's metadata.
 
-This option is only valid when `ssl_verify_mode` is set to `peer` or `force_peer`.
+This option is only valid when <<plugins-{type}s-{plugin}-ssl_client_authentication>> is set to `optional` or `required`.
 
 [id="plugins-{type}s-{plugin}-ssl_supported_protocols"]
 ===== `ssl_supported_protocols`
@@ -485,19 +510,21 @@ the *$JDK_HOME/conf/security/java.security* configuration file. That is, `TLSv1.
 
 [id="plugins-{type}s-{plugin}-ssl_verify_mode"]
 ===== `ssl_verify_mode`
+deprecated[6.6.0, Replaced by <<plugins-{type}s-{plugin}-ssl_client_authentication>>]
 
   * Value can be any of: `none`, `peer`, `force_peer`
   * Default value is `"none"`
 
-By default the server doesn't do any client verification.
+By default, the server doesn't do any client verification. If the <<plugins-{type}s-{plugin}-ssl_certificate_authorities>>
+is configured, and no value or `none` is provided for this option, it defaults to `force_peer` instead of `none`.
 
 `peer` will make the server ask the client to provide a certificate.
 If the client provides a certificate, it will be validated.
 
 `force_peer` will make the server ask the client to provide a certificate.
 If the client doesn't provide a certificate, the connection will be closed.
 
-This option needs to be used with `ssl_certificate_authorities` and a defined list of CAs.
+This option needs to be used with <<plugins-{type}s-{plugin}-ssl_certificate_authorities>> and a defined list of CAs.
 
 [id="plugins-{type}s-{plugin}-tls_max_version"]
 ===== `tls_max_version`