Deprecated and added new SSL settings

Author: edmocosta

CHANGELOG.md

@@ -1,3 +1,13 @@
+## 11.14.0
+ - Reviewed and deprecated SSL settings to comply with Logstash's naming convention [#1115](https://github.com/logstash-plugins/logstash-output-elasticsearch/pull/1115)
+   - Deprecated `ssl` in favor of `ssl_enabled`
+   - Deprecated `cacert` in favor of `ssl_certificate_authorities`
+   - Deprecated `keystore` in favor of `ssl_keystore_path`
+   - Deprecated `keystore_password` in favor of `ssl_keystore_password`
+   - Deprecated `truststore` in favor of `ssl_truststore_path`
+   - Deprecated `truststore_password` in favor of `ssl_truststore_password`
+   - Deprecated `ssl_certificate_verification` in favor of `ssl_verification_mode`
+
 ## 11.13.1
  - Avoid crash by ensuring ILM settings are injected in the correct location depending on the default (or custom) template format, template_api setting and ES version [#1102](https://github.com/logstash-plugins/logstash-output-elasticsearch/pull/1102)
 

docs/index.asciidoc

@@ -307,7 +307,7 @@ This plugin supports the following configuration options plus the
 | <<plugins-{type}s-{plugin}-action>> |<<string,string>>|No
 | <<plugins-{type}s-{plugin}-api_key>> |<<password,password>>|No
 | <<plugins-{type}s-{plugin}-bulk_path>> |<<string,string>>|No
-| <<plugins-{type}s-{plugin}-cacert>> |a valid filesystem path|No
+| <<plugins-{type}s-{plugin}-cacert>> |a valid filesystem path|__Deprecated__
 | <<plugins-{type}s-{plugin}-ca_trusted_fingerprint>> |<<string,string>>|No
 | <<plugins-{type}s-{plugin}-cloud_auth>> |<<password,password>>|No
 | <<plugins-{type}s-{plugin}-cloud_id>> |<<string,string>>|No
@@ -333,8 +333,8 @@ This plugin supports the following configuration options plus the
 | <<plugins-{type}s-{plugin}-ilm_policy>> |<<string,string>>|No
 | <<plugins-{type}s-{plugin}-ilm_rollover_alias>> |<<string,string>>|No
 | <<plugins-{type}s-{plugin}-index>> |<<string,string>>|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>> |a valid filesystem path|__Deprecated__
+| <<plugins-{type}s-{plugin}-keystore_password>> |<<password,password>>|__Deprecated__
 | <<plugins-{type}s-{plugin}-silence_errors_in_log>> |<<array,array>>|No
 | <<plugins-{type}s-{plugin}-manage_template>> |<<boolean,boolean>>|No
 | <<plugins-{type}s-{plugin}-parameters>> |<<hash,hash>>|No
@@ -358,16 +358,23 @@ This plugin supports the following configuration options plus the
 | <<plugins-{type}s-{plugin}-sniffing>> |<<boolean,boolean>>|No
 | <<plugins-{type}s-{plugin}-sniffing_delay>> |<<number,number>>|No
 | <<plugins-{type}s-{plugin}-sniffing_path>> |<<string,string>>|No
-| <<plugins-{type}s-{plugin}-ssl>> |<<boolean,boolean>>|No
-| <<plugins-{type}s-{plugin}-ssl_certificate_verification>> |<<boolean,boolean>>|No
+| <<plugins-{type}s-{plugin}-ssl>> |<<boolean,boolean>>|__Deprecated__
+| <<plugins-{type}s-{plugin}-ssl_certificate_authorities>> |list of <<path,path>>|No
+| <<plugins-{type}s-{plugin}-ssl_certificate_verification>> |<<boolean,boolean>>|__Deprecated__
+| <<plugins-{type}s-{plugin}-ssl_enabled>> |<<boolean,boolean>>|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_supported_protocols>> |<<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_verification_mode>> |<<string,string>>, one of `["full", "none"]`|No
 | <<plugins-{type}s-{plugin}-template>> |a valid filesystem path|No
 | <<plugins-{type}s-{plugin}-template_api>> |<<string,string>>, one of `["auto", "legacy", "composable"]`|No
 | <<plugins-{type}s-{plugin}-template_name>> |<<string,string>>|No
 | <<plugins-{type}s-{plugin}-template_overwrite>> |<<boolean,boolean>>|No
 | <<plugins-{type}s-{plugin}-timeout>> |<<number,number>>|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>> |a valid filesystem path|__Deprecated__
+| <<plugins-{type}s-{plugin}-truststore_password>> |<<password,password>>|__Deprecated__
 | <<plugins-{type}s-{plugin}-upsert>> |<<string,string>>|No
 | <<plugins-{type}s-{plugin}-user>> |<<string,string>>|No
 | <<plugins-{type}s-{plugin}-validate_after_inactivity>> |<<number,number>>|No
@@ -424,8 +431,9 @@ this defaults to a concatenation of the path parameter and "_bulk"
 
 [id="plugins-{type}s-{plugin}-cacert"]
 ===== `cacert`
+deprecated[8.8.0, Replaced by <<plugins-{type}s-{plugin}-ssl_certificate_authorities>>]
 
-  * Value type is <<path,path>>
+  * Value type is a list of <<path,path>>
   * There is no default value for this setting.
 
 The .cer or .pem file to validate the server's certificate.
@@ -771,6 +779,7 @@ formats] and the `@timestamp` field of each event is being used as source for th
 
 [id="plugins-{type}s-{plugin}-keystore"]
 ===== `keystore`
+deprecated[8.8.0, Replaced by <<plugins-{type}s-{plugin}-ssl_keystore_path>>]
 
   * Value type is <<path,path>>
   * There is no default value for this setting.
@@ -780,6 +789,7 @@ It can be either .jks or .p12
 
 [id="plugins-{type}s-{plugin}-keystore_password"]
 ===== `keystore_password`
+deprecated[8.8.0, Replaced by <<plugins-{type}s-{plugin}-ssl_keystore_password>>]
 
   * Value type is <<password,password>>
   * There is no default value for this setting.
@@ -1036,6 +1046,7 @@ do not use full URL here, only paths, e.g. "/sniff/_nodes/http"
 
 [id="plugins-{type}s-{plugin}-ssl"]
 ===== `ssl`
+deprecated[8.8.0, Replaced by <<plugins-{type}s-{plugin}-ssl_enabled>>]
 
   * Value type is <<boolean,boolean>>
   * There is no default value for this setting.
@@ -1044,8 +1055,17 @@ Enable SSL/TLS secured communication to Elasticsearch cluster.
 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>>.
 If no explicit protocol is specified plain HTTP will be used.
 
+[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 files to validate the server's certificate.
+
 [id="plugins-{type}s-{plugin}-ssl_certificate_verification"]
 ===== `ssl_certificate_verification`
+deprecated[8.8.0, Replaced by <<plugins-{type}s-{plugin}-ssl_verification_mode>>]
 
   * Value type is <<boolean,boolean>>
   * Default value is `true`
@@ -1054,6 +1074,33 @@ Option to validate the server's certificate. Disabling this severely compromises
 For more information on disabling certificate verification please read
 https://www.cs.utexas.edu/~shmat/shmat_ccs12.pdf
 
+[id="plugins-{type}s-{plugin}-ssl_enabled"]
+===== `ssl_enabled`
+
+  * Value type is <<boolean,boolean>>
+  * There is no default value for this setting.
+
+Enable SSL/TLS secured communication to Elasticsearch cluster.
+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>>.
+If no explicit protocol is specified plain HTTP will be used.
+
+[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_supported_protocols"]
 ===== `ssl_supported_protocols`
 
@@ -1071,6 +1118,40 @@ 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.
+Use either `:truststore` or `:cacert`.
+
+[id="plugins-{type}s-{plugin}-ssl_verification_mode"]
+===== `ssl_verification_mode`
+
+  * Value can be any of: `full`, `none`
+  * Default value is `["full"]`
+
+Defines how to verify the certificates presented by another party in the TLS connection:
+
+`full` validates that the server certificate has an issue date that’s within
+the not_before and not_after dates; chains to a trusted Certificate Authority (CA), and
+has a hostname or IP address that matches the names within the certificate.
+
+`none` performs no certificate validation.
+
+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
+
 [id="plugins-{type}s-{plugin}-template"]
 ===== `template`
 
@@ -1141,6 +1222,7 @@ a timeout occurs, the request will be retried.
 
 [id="plugins-{type}s-{plugin}-truststore"]
 ===== `truststore`
+deprecated[8.8.0, Replaced by <<plugins-{type}s-{plugin}-ssl_truststore_path>>]
 
   * Value type is <<path,path>>
   * There is no default value for this setting.
@@ -1151,6 +1233,7 @@ Use either `:truststore` or `:cacert`.
 
 [id="plugins-{type}s-{plugin}-truststore_password"]
 ===== `truststore_password`
+deprecated[8.8.0, Replaced by <<plugins-{type}s-{plugin}-ssl_truststore_password>>]
 
   * Value type is <<password,password>>
   * There is no default value for this setting.

lib/logstash/outputs/elasticsearch.rb

@@ -96,10 +96,14 @@ class LogStash::Outputs::ElasticSearch < LogStash::Outputs::Base
   require "logstash/outputs/elasticsearch/data_stream_support"
   require 'logstash/plugin_mixins/ecs_compatibility_support'
   require 'logstash/plugin_mixins/deprecation_logger_support'
+  require 'logstash/plugin_mixins/normalize_config_support'
 
   # Protocol agnostic methods
   include(LogStash::PluginMixins::ElasticSearch::Common)
 
+  # Config normalization helpers
+  include(LogStash::PluginMixins::NormalizeConfigSupport)
+
   # Methods for ILM support
   include(LogStash::Outputs::ElasticSearch::Ilm)
 
@@ -279,6 +283,7 @@ class LogStash::Outputs::ElasticSearch < LogStash::Outputs::Base
   def initialize(*params)
     super
     setup_ecs_compatibility_related_defaults
+    setup_ssl_params
   end
 
   def register
@@ -622,6 +627,52 @@ def setup_template_manager_defaults(data_stream_enabled)
     end
   end
 
+  def setup_ssl_params
+    @ssl_enabled = normalize_config(:ssl_enabled) do |normalize|
+      normalize.with_deprecated_alias(:ssl)
+    end
+
+    @ssl_certificate_authorities = normalize_config(:ssl_certificate_authorities) do |normalize|
+      normalize.with_deprecated_mapping(:cacert) do |cacert|
+        [cacert]
+      end
+    end
+
+    @ssl_keystore_path =  normalize_config(:ssl_keystore_path) do |normalize|
+      normalize.with_deprecated_alias(:keystore)
+    end
+
+    @ssl_keystore_password = normalize_config(:ssl_keystore_password) do |normalize|
+      normalize.with_deprecated_alias(:keystore_password)
+    end
+
+    @ssl_truststore_path = normalize_config(:ssl_truststore_path) do |normalize|
+      normalize.with_deprecated_alias(:truststore)
+    end
+
+    @ssl_truststore_password =  normalize_config(:ssl_truststore_password) do |normalize|
+      normalize.with_deprecated_alias(:truststore_password)
+    end
+
+    @ssl_verification_mode = normalize_config(:ssl_verification_mode) do |normalize|
+      normalize.with_deprecated_mapping(:ssl_certificate_verification) do |ssl_certificate_verification|
+        if ssl_certificate_verification == true
+          "full"
+        else
+          "none"
+        end
+      end
+    end
+
+    params['ssl_enabled'] = @ssl_enabled unless @ssl_enabled.nil?
+    params['ssl_certificate_authorities'] = @ssl_certificate_authorities unless @ssl_certificate_authorities.nil?
+    params['ssl_keystore_path'] = @ssl_keystore_path unless @ssl_keystore_path.nil?
+    params['ssl_keystore_password'] = @ssl_keystore_password unless @ssl_keystore_password.nil?
+    params['ssl_truststore_path'] = @ssl_truststore_path unless @ssl_truststore_path.nil?
+    params['ssl_truststore_password'] = @ssl_truststore_password unless @ssl_truststore_password.nil?
+    params['ssl_verification_mode'] = @ssl_verification_mode unless @ssl_verification_mode.nil?
+  end
+
   # To be overidden by the -java version
   VALID_HTTP_ACTIONS = ["index", "delete", "create", "update"]
   def valid_actions

lib/logstash/outputs/elasticsearch/http_client_builder.rb

@@ -107,36 +107,42 @@ def self.create_http_client(options)
     end
 
     def self.setup_ssl(logger, params)
-      params["ssl"] = true if params["hosts"].any? {|h| h.scheme == "https" }
-      return {} if params["ssl"].nil?
+      params["ssl_enabled"] = true if params["hosts"].any? {|h| h.scheme == "https" }
+      return {} if params["ssl_enabled"].nil?
 
-      return {:ssl => {:enabled => false}} if params["ssl"] == false
+      return {:ssl => {:enabled => false}} if params["ssl_enabled"] == false
 
-      cacert, truststore, truststore_password, keystore, keystore_password =
-        params.values_at('cacert', 'truststore', 'truststore_password', 'keystore', 'keystore_password')
+      ssl_certificate_authorities, ssl_truststore_path, ssl_truststore_password, ssl_keystore_path, ssl_keystore_password, ssl_verification_mode =
+        params.values_at('ssl_certificate_authorities', 'ssl_truststore_path', 'ssl_truststore_password', 'ssl_keystore_path', 'ssl_keystore_password', 'ssl_verification_mode')
 
-      if cacert && truststore
-        raise(LogStash::ConfigurationError, "Use either \"cacert\" or \"truststore\" when configuring the CA certificate") if truststore
+      if ssl_certificate_authorities && ssl_truststore_path
+        raise(LogStash::ConfigurationError, "Use either \"ssl_certificate_authorities\" or \"ssl_truststore_path\" when configuring the CA certificate")
       end
 
       ssl_options = {:enabled => true}
 
-      if cacert
-        ssl_options[:ca_file] = cacert
-      elsif truststore
-        ssl_options[:truststore_password] = truststore_password.value if truststore_password
+      if ssl_certificate_authorities&.any?
+        raise(LogStash::ConfigurationError, "Multiple \"ssl_certificate_authorities\" files are not supported") if ssl_certificate_authorities.size > 1
+        ssl_options[:ca_file] = ssl_certificate_authorities.first
+      elsif ssl_truststore_path
+        ssl_options[:truststore_password] = ssl_truststore_password.value if ssl_truststore_password
       end
 
-      ssl_options[:truststore] = truststore if truststore
-      if keystore
-        ssl_options[:keystore] = keystore
-        ssl_options[:keystore_password] = keystore_password.value if keystore_password
+      ssl_options[:truststore] = ssl_truststore_path if ssl_truststore_path
+      if ssl_keystore_path
+        ssl_options[:keystore] = ssl_keystore_path
+        ssl_options[:keystore_password] = ssl_keystore_password.value if ssl_keystore_password
       end
 
-      if !params["ssl_certificate_verification"]
-        logger.warn "You have enabled encryption but DISABLED certificate verification, " +
-                    "to make sure your data is secure remove `ssl_certificate_verification => false`"
-        ssl_options[:verify] = :disable # false accepts self-signed but still validates hostname
+      unless ssl_verification_mode.nil?
+        case ssl_verification_mode
+          when 'none'
+            logger.warn "You have enabled encryption but DISABLED certificate verification, " +
+                          "to make sure your data is secure set `ssl_verification_mode => full`"
+            ssl_options[:verify] = :disable
+          else
+            ssl_options[:verify] = :strict
+        end
       end
 
       ssl_options[:trust_strategy] = params["ssl_trust_strategy"] if params.include?("ssl_trust_strategy")