Standardize SSL settings

CHANGELOG.md

@@ -1,3 +1,11 @@
+## 5.6.0
+  - Added standardized SSL settings and deprecates their non-standard counterparts. Deprecated settings will continue to work, and will provide pipeline maintainers with guidance toward using their standardized counterparts [#140](https://github.com/logstash-plugins/logstash-output-http/pull/140)
+  - Added new `ssl_truststore_path`, `ssl_truststore_password`, and `ssl_truststore_type` settings for configuring SSL-trust using a PKCS-12 or JKS trust store, deprecating their `truststore`, `truststore_password`, and `truststore_type` counterparts.
+  - Added new `ssl_certificate_authorities` setting for configuring SSL-trust using a PEM-formatted list certificate authorities, deprecating its `cacert` counterpart.
+  - Added new `ssl_keystore_path`, `ssl_keystore_password`, and `ssl_keystore_type` settings for configuring SSL-identity using a PKCS-12 or JKS key store, deprecating their `keystore`, `keystore_password`, and `keystore_type` counterparts.
+  - Added new `ssl_certificate` and `ssl_key` settings for configuring SSL-identity using a PEM-formatted certificate/key pair, deprecating their `client_cert` and `client_key` counterparts. 
+  - Added the `ssl_cipher_suites` option
+
 ## 5.5.0
   - Feat: added `ssl_supported_protocols` option [#131](https://github.com/logstash-plugins/logstash-output-http/pull/131)
 

docs/index.asciidoc

@@ -74,9 +74,9 @@ This plugin supports the following configuration options plus the <<plugins-{typ
 |=======================================================================
 |Setting |Input type|Required
 | <<plugins-{type}s-{plugin}-automatic_retries>> |<<number,number>>|No
-| <<plugins-{type}s-{plugin}-cacert>> |a valid filesystem path|No
-| <<plugins-{type}s-{plugin}-client_cert>> |a valid filesystem path|No
-| <<plugins-{type}s-{plugin}-client_key>> |a valid filesystem path|No
+| <<plugins-{type}s-{plugin}-cacert>> |a valid filesystem path|__Deprecated__
+| <<plugins-{type}s-{plugin}-client_cert>> |a valid filesystem path|__Deprecated__
+| <<plugins-{type}s-{plugin}-client_key>> |a valid filesystem path|__Deprecated__
 | <<plugins-{type}s-{plugin}-connect_timeout>> |<<number,number>>|No
 | <<plugins-{type}s-{plugin}-content_type>> |<<string,string>>|No
 | <<plugins-{type}s-{plugin}-cookies>> |<<boolean,boolean>>|No
@@ -87,9 +87,9 @@ This plugin supports the following configuration options plus the <<plugins-{typ
 | <<plugins-{type}s-{plugin}-http_method>> |<<string,string>>, one of `["put", "post", "patch", "delete", "get", "head"]`|Yes
 | <<plugins-{type}s-{plugin}-ignorable_codes>> |<<number,number>>|No
 | <<plugins-{type}s-{plugin}-keepalive>> |<<boolean,boolean>>|No
-| <<plugins-{type}s-{plugin}-keystore>> |a valid filesystem path|No
-| <<plugins-{type}s-{plugin}-keystore_password>> |<<password,password>>|No
-| <<plugins-{type}s-{plugin}-keystore_type>> |<<string,string>>|No
+| <<plugins-{type}s-{plugin}-keystore>> |a valid filesystem path|__Deprecated__
+| <<plugins-{type}s-{plugin}-keystore_password>> |<<password,password>>|__Deprecated__
+| <<plugins-{type}s-{plugin}-keystore_type>> |<<string,string>>|__Deprecated__
 | <<plugins-{type}s-{plugin}-mapping>> |<<hash,hash>>|No
 | <<plugins-{type}s-{plugin}-message>> |<<string,string>>|No
 | <<plugins-{type}s-{plugin}-pool_max>> |<<number,number>>|No
@@ -100,11 +100,20 @@ This plugin supports the following configuration options plus the <<plugins-{typ
 | <<plugins-{type}s-{plugin}-retry_non_idempotent>> |<<boolean,boolean>>|No
 | <<plugins-{type}s-{plugin}-retryable_codes>> |<<number,number>>|No
 | <<plugins-{type}s-{plugin}-socket_timeout>> |<<number,number>>|No
+| <<plugins-{type}s-{plugin}-ssl_certificate>> |<<path,path>>|No
+| <<plugins-{type}s-{plugin}-ssl_certificate_authorities>> |list of <<path,path>>|No
+| <<plugins-{type}s-{plugin}-ssl_cipher_suites>> |list of <<string,string>>|No
+| <<plugins-{type}s-{plugin}-ssl_keystore_password>> |<<password,password>>|No
+| <<plugins-{type}s-{plugin}-ssl_keystore_path>> |<<path,path>>|No
+| <<plugins-{type}s-{plugin}-ssl_keystore_type>> |<<string,string>>|No
 | <<plugins-{type}s-{plugin}-ssl_supported_protocols>> |<<string,string>>|No
-| <<plugins-{type}s-{plugin}-ssl_verification_mode>> |<<string,string>>|No
-| <<plugins-{type}s-{plugin}-truststore>> |a valid filesystem path|No
-| <<plugins-{type}s-{plugin}-truststore_password>> |<<password,password>>|No
-| <<plugins-{type}s-{plugin}-truststore_type>> |<<string,string>>|No
+| <<plugins-{type}s-{plugin}-ssl_truststore_password>> |<<password,password>>|No
+| <<plugins-{type}s-{plugin}-ssl_truststore_path>> |<<path,path>>|No
+| <<plugins-{type}s-{plugin}-ssl_truststore_type>> |<<string,string>>|No
+| <<plugins-{type}s-{plugin}-ssl_verification_mode>> |<<string,string>>, one of `["full", "none"]`|No
+| <<plugins-{type}s-{plugin}-truststore>> |a valid filesystem path|__Deprecated__
+| <<plugins-{type}s-{plugin}-truststore_password>> |<<password,password>>|__Deprecated__
+| <<plugins-{type}s-{plugin}-truststore_type>> |<<string,string>>|__Deprecated__
 | <<plugins-{type}s-{plugin}-url>> |<<string,string>>|Yes
 | <<plugins-{type}s-{plugin}-validate_after_inactivity>> |<<number,number>>|No
 |=======================================================================
@@ -127,6 +136,7 @@ See <<plugins-{type}s-{plugin}-retry_policy,Retry Policy>> for more information.
 
 [id="plugins-{type}s-{plugin}-cacert"]
 ===== `cacert` 
+deprecated[5.6.0, Replaced by <<plugins-{type}s-{plugin}-ssl_certificate_authorities>>]
 
   * Value type is <<path,path>>
   * There is no default value for this setting.
@@ -135,6 +145,7 @@ If you need to use a custom X.509 CA (.pem certs) specify the path to that here
 
 [id="plugins-{type}s-{plugin}-client_cert"]
 ===== `client_cert` 
+deprecated[5.6.0, Replaced by <<plugins-{type}s-{plugin}-ssl_certificate>>]
 
   * Value type is <<path,path>>
   * There is no default value for this setting.
@@ -143,6 +154,7 @@ If you'd like to use a client certificate (note, most people don't want this) se
 
 [id="plugins-{type}s-{plugin}-client_key"]
 ===== `client_key` 
+deprecated[5.6.0, Replaced by <<plugins-{type}s-{plugin}-ssl_key>>]
 
   * Value type is <<path,path>>
   * There is no default value for this setting.
@@ -254,6 +266,7 @@ one with this to fix interactions with broken keepalive implementations.
 
 [id="plugins-{type}s-{plugin}-keystore"]
 ===== `keystore` 
+deprecated[5.6.0, Replaced by <<plugins-{type}s-{plugin}-ssl_keystore_path>>]
 
   * Value type is <<path,path>>
   * There is no default value for this setting.
@@ -262,6 +275,7 @@ If you need to use a custom keystore (`.jks`) specify that here. This does not w
 
 [id="plugins-{type}s-{plugin}-keystore_password"]
 ===== `keystore_password` 
+deprecated[5.6.0, Replaced by <<plugins-{type}s-{plugin}-ssl_keystore_password>>]
 
   * Value type is <<password,password>>
   * There is no default value for this setting.
@@ -270,7 +284,8 @@ Specify the keystore password here.
 Note, most .jks files created with keytool require a password!
 
 [id="plugins-{type}s-{plugin}-keystore_type"]
-===== `keystore_type` 
+===== `keystore_type`
+deprecated[5.6.0, Replaced by <<plugins-{type}s-{plugin}-ssl_keystore_type>>]
 
   * Value type is <<string,string>>
   * Default value is `"JKS"`
@@ -379,6 +394,67 @@ See <<plugins-{type}s-{plugin}-retry_policy,Retry Policy>> for more information.
 
 Timeout (in seconds) to wait for data on the socket. Default is `10s`
 
+[id="plugins-{type}s-{plugin}-ssl_certificate"]
+===== `ssl_certificate`
+  * Value type is <<path,path>>
+  * There is no default value for this setting.
+
+SSL certificate to use to authenticate the client. This certificate should be an OpenSSL-style X.509 certificate file.
+
+NOTE: This setting can be used only if <<plugins-{type}s-{plugin}-ssl_key>> is set.
+
+[id="plugins-{type}s-{plugin}-ssl_certificate_authorities"]
+===== `ssl_certificate_authorities`
+
+  * Value type is a list of <<path,path>>
+  * There is no default value for this setting
+
+The .cer or .pem CA files to validate the server's certificate.
+
+[id="plugins-{type}s-{plugin}-ssl_cipher_suites"]
+===== `ssl_cipher_suites`
+
+  * Value type is a list of <<string,string>>
+  * There is no default value for this setting
+
+The list of cipher suites to use, listed by priorities.
+Supported cipher suites vary depending on the Java and protocol versions.
+
+[id="plugins-{type}s-{plugin}-ssl_key"]
+===== `ssl_key`
+
+  * Value type is <<path,path>>
+  * There is no default value for this setting.
+
+OpenSSL-style RSA private key that corresponds to the <<plugins-{type}s-{plugin}-ssl_certificate>>.
+
+NOTE: This setting can be used only if <<plugins-{type}s-{plugin}-ssl_certificate>> is set.
+
+[id="plugins-{type}s-{plugin}-ssl_keystore_password"]
+===== `ssl_keystore_password`
+
+  * Value type is <<password,password>>
+  * There is no default value for this setting.
+
+Set the keystore password
+
+[id="plugins-{type}s-{plugin}-ssl_keystore_path"]
+===== `ssl_keystore_path`
+
+  * Value type is <<path,path>>
+  * There is no default value for this setting.
+
+The keystore used to present a certificate to the server.
+It can be either `.jks` or `.p12`
+
+[id="plugins-{type}s-{plugin}-ssl_keystore_type"]
+===== `ssl_keystore_type`
+
+  * Value can be any of: `jks`, `pkcs12`
+  * If not provided, the value will be inferred from the keystore filename.
+
+The format of the keystore file. It must be either `jks` or `pkcs12`.
+
 [id="plugins-{type}s-{plugin}-ssl_supported_protocols"]
 ===== `ssl_supported_protocols`
 
@@ -396,6 +472,31 @@ NOTE: If you configure the plugin to use `'TLSv1.1'` on any recent JVM, such as
 the protocol is disabled by default and needs to be enabled manually by changing `jdk.tls.disabledAlgorithms` in
 the *$JDK_HOME/conf/security/java.security* configuration file. That is, `TLSv1.1` needs to be removed from the list.
 
+[id="plugins-{type}s-{plugin}-ssl_truststore_password"]
+===== `ssl_truststore_password`
+
+  * Value type is <<password,password>>
+  * There is no default value for this setting.
+
+Set the truststore password
+
+[id="plugins-{type}s-{plugin}-ssl_truststore_path"]
+===== `ssl_truststore_path`
+
+  * Value type is <<path,path>>
+  * There is no default value for this setting.
+
+The truststore to validate the server's certificate.
+It can be either `.jks` or `.p12`.
+
+[id="plugins-{type}s-{plugin}-ssl_truststore_type"]
+===== `ssl_truststore_type`
+
+  * Value can be any of: `jks`, `pkcs12`
+  * If not provided, the value will be inferred from the truststore filename.
+
+The format of the truststore file. It must be either `jks` or `pkcs12`.
+
 [id="plugins-{type}s-{plugin}-ssl_verification_mode"]
 ===== `ssl_verification_mode`
 
@@ -414,6 +515,7 @@ Using `none`  in production environments is strongly discouraged.
 
 [id="plugins-{type}s-{plugin}-truststore"]
 ===== `truststore` 
+deprecated[5.6.0, Replaced by <<plugins-{type}s-{plugin}-ssl_truststore_path>>]
 
   * Value type is <<path,path>>
   * There is no default value for this setting.
@@ -422,6 +524,7 @@ If you need to use a custom truststore (`.jks`) specify that here. This does not
 
 [id="plugins-{type}s-{plugin}-truststore_password"]
 ===== `truststore_password` 
+deprecated[5.6.0, Replaced by <<plugins-{type}s-{plugin}-ssl_truststore_password>>]
 
   * Value type is <<password,password>>
   * There is no default value for this setting.
@@ -431,6 +534,7 @@ Note, most .jks files created with keytool require a password!
 
 [id="plugins-{type}s-{plugin}-truststore_type"]
 ===== `truststore_type` 
+deprecated[5.6.0, Replaced by <<plugins-{type}s-{plugin}-ssl_truststore_type>>]
 
   * Value type is <<string,string>>
   * Default value is `"JKS"`

lib/logstash/outputs/http.rb

@@ -7,7 +7,7 @@
 require "zlib"
 
 class LogStash::Outputs::Http < LogStash::Outputs::Base
-  include LogStash::PluginMixins::HttpClient
+  include LogStash::PluginMixins::HttpClient[:with_deprecated => true]
 
   concurrency :shared
 

logstash-output-http.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name            = 'logstash-output-http'
-  s.version         = '5.5.0'
+  s.version         = '5.6.0'
   s.licenses        = ['Apache License (2.0)']
   s.summary         = "Sends events to a generic HTTP or HTTPS endpoint"
   s.description     = "This gem is a Logstash plugin required to be installed on top of the Logstash core pipeline using $LS_HOME/bin/logstash-plugin install gemname. This gem is not a stand-alone program"
@@ -20,7 +20,7 @@ Gem::Specification.new do |s|
 
   # Gem dependencies
   s.add_runtime_dependency "logstash-core-plugin-api", ">= 1.60", "<= 2.99"
-  s.add_runtime_dependency "logstash-mixin-http_client", ">= 7.2.0", "< 8.0.0"
+  s.add_runtime_dependency "logstash-mixin-http_client", ">= 7.3.0", "< 8.0.0"
 
   s.add_development_dependency 'logstash-devutils'
   s.add_development_dependency 'sinatra'