SSL/TLS Encryption

Many stages can use SSL/TLS encryption to securely connect to the external system.

Some stages always use SSL/TLS to securely connect to the external system - you don't need to configure them to do so. For example, most external systems managed by a cloud service provider, such as Amazon S3 or Google Cloud Storage, use well-known public root certificates. As a result, stages can automatically use SSL/TLS encryption to connect to these systems.

However, other stages require that you configure SSL/TLS properties to securely connect to the external system. For example, external systems that you manage, such as a Cassandra or Oracle database or an SFTP server, might use private certificates. As a result, you must configure stages connecting to these systems to use the required SSL/TLS properties. You might be able to enable client certificate authorization or specify a custom truststore file.

For stages that allow you to customize SSL/TLS properties, you can generally configure the properties on the TLS tab of the stage. The properties that are available depend on the stage that you are configuring. The TLS tab can include the following properties:

  • Keystore properties
  • Truststore properties
  • TLS protocols
  • Cipher suites
Note: You can also enable HTTPS for Data Collector to configure the Control Hub web browser to use direct engine REST APIs to communicate with Data Collector. For more information, see Enabling HTTPS in the Data Collector documentation.
You can enable SSL/TLS type properties in the following stages and locations:
  • Aerospike Client destination - The destination requires configuring the SDC_JAVA_OPTS environment variable. For more information, see Enabling SSL/TLS in the destination documentation.
  • Aurora PostgreSQL CDC Client origin - This origin requires certificate files rather than keystore and truststore files. For more information, see SSL/TLS Encryption in the origin documentation.
  • Cassandra destination
  • CONNX origin and CONNX CDC origin - These stages require configuring the SDC_JAVA_OPTS environment variable. For more information, see SSL/TLS in CONNX Stages.
  • Control Hub API processor
  • Couchbase Lookup processor and Couchbase destination
  • Databricks Job Launcher executor
  • gRPC Client origin
  • HTTP Client origin, processor, and destination
  • HTTP Server origin
  • Jira origin and destination
  • Kafka Multitopic Consumer origin and Kafka Producer destination - These stages require configuring additional Kafka properties. For more information, see Security in Kafka Stages.
  • MongoDB origin and destination, MongoDB Oplog origin, and MongoDB Lookup processor - These stages require configuring the SDC_JAVA_OPTS environment variable. For more information, see "Enabling SSL/TLS" in the stage documentation.
  • MongoDB Atlas origin and destination - These stages require certificate files rather than keystore and truststore files. For more information, see "Enabling SSL/TLS" in the stage documentation.
  • MQTT Subscriber origin and MQTT Publisher destination
  • OPC UA Client origin
  • Oracle Multitable Consumer origin - This origin requires certificate files rather than keystore and truststore files.
  • PostgreSQL CDC Client origin - This origin requires certificate files rather than keystore and truststore files. For more information, see SSL/TLS Encryption in the origin documentation.
  • Pulsar Consumer (Legacy) origin and Pulsar Producer destination - These stages require certificate files rather than keystore and truststore files. For more information, see "Enabling Security" in the stage documentation.
  • RabbitMQ Consumer origin and RabbitMQ Producer destination
  • REST Service origin
  • Salesforce origin, lookup, and destination, and the Tableau CRM destination
  • SFTP/FTP/FTPS Client origin and destination
  • Splunk destination
  • Start Jobs origin and processor
  • Syslog destination - This destination requires configuring the SDC_JAVA_OPTS environment variable. For more information, see Enabling SSL/TLS in the destination documentation.
  • TCP Server origin
  • Wait for Jobs processor
  • Web Client origin, processor, and destination
  • WebSocket Client origin and destination
  • WebSocket Server origin
  • Pipeline error handling, when writing error records to another pipeline

Keystore and Truststore Configuration

When SSL/TLS is enabled in a stage, you can also enable the use of a keystore and a truststore.

Though similar in many ways, a keystore contains a private key and public certificates that are used to verify the identity of the client upon a request from an SSL/TLS server. In contrast, a truststore generally contains certificates from trusted certificate authorities that an SSL/TLS client uses to verify the identity of an SSL/TLS server.

You can configure most stages to use a keystore or truststore in the following ways:
  • Load the keystore or truststore from a local file.
  • Load the contents of the keystore or truststore from a remote credential store.

Local Keystore and Truststore

You can configure stages to load the keystore or truststore from a local file stored on the Data Collector machine.

When you configure a local keystore or truststore, you configure the following properties:
Keystore/truststore type
You can use the following types of keystores and truststores:
  • Java Keystore File (JKS)
  • PKCS #12 (p12 file)
File and location
When specifying the name and location of the keystore or truststore file, you can either use an absolute path to the file or use the following expression to define the file stored in the Data Collector resources directory:

${runtime:resourcesDirPath()}/keystore.jks

Password
A password is optional for keystore and truststore files, but highly recommended.
Algorithm
Data Collector uses the SunX509 key exchange algorithm by default. You can use any algorithm compatible with your keystore/truststore file that is supported by your JVM.

Remote Keystore and Truststore

You can configure stages to load the contents of the keystore or truststore from a remote credential store or from values entered in the stage properties. The stage builds the keystore or truststore from the private key and certificates retrieved from the credential store or entered in the stage properties.

To provide a remote keystore or truststore, you select the Use Remote Keystore or Use Remote Truststore property after enabling SSL/TLS for the stage. You then configure the following properties:
Private key
The private key used in the remote keystore. Enter the key in one of the following ways:
  • Use a credential function to access the key defined in a credential store. For more information, see Using a Credential Store.
  • Enter the contents of the key in the property.
Certificates
Each PEM certificate used in the remote keystore or truststore. Using simple or bulk edit mode, click the Add icon to add additional certificates. For a keystore certificate chain, the certificates must be listed in the order of the chain, with the first certificate being the keystore certificate and the last being the CA certificate.
Enter each certificate in one of the following ways:
  • Use a credential function to access the PEM certificate defined in a credential store. For more information, see Using a Credential Store.
  • Enter the contents of the PEM certificate in the property.
Algorithm
Data Collector uses the SunX509 key exchange algorithm by default. You can use any algorithm compatible with your keystore/truststore file that is supported by your JVM.

Using a Credential Store

You can define keystore/truststore private keys and certificates in a credential store, then call the appropriate key and certificate from a stage that uses SSL/TLS encryption. The stage builds the keystore or truststore from the specified private key and certificates.

Important: To use a credential store for remote keystores and truststores, make sure that Data Collector is configured to use a supported credential store. For a list of supported credential stores and instructions on enabling each credential store, see Credential Stores in the Data Collector documentation.

Defining keys and certificates in a credential store allows you to securely store the sensitive information. For an additional layer of security, you can require group access to credential store secrets. For more information, see Group Access to Secrets in the Data Collector documentation.

Using a credential store also makes it easy to update keystores and truststores without having to edit the stages that use them. This can simplify tasks such as recycling keystores and truststores or migrating pipelines to production.

When using a credential store for the private key, store the key as a secret in any of the supported credential stores and then use the credential:get() function to retrieve the key.

When using a credential store for a PEM certificate, you can use either of the following methods:
  • Store the contents of the certificate as a secret in any of the supported credential stores and then use the credential:get() function to retrieve the secret.
  • Store the certificate in Microsoft Azure Key Vault and then use the credential:getWithOptions() function using the credentialType=certificate option to retrieve the certificate from Azure Key Vault.

    Azure Key Vault supports storing PEM certificates directly in the vault. For more information about using Azure Key Vault as a credential store, see Microsoft Azure Key Vault in the Data Collector documentation.

Transport Protocols

When SSL/TLS is enabled in a stage, you can configure the transport protocol to use.

Data Collector uses TLSv1.2 by default. You can specify one or more other protocols, but versions prior to TLSv1.2 are not as secure.

Cipher Suites

When SSL/TLS is enabled in a stage, you can configure the cipher suites to use to perform the SSL/TLS handshake.

By default, a stage can use any of the following cipher suites:
Supported Cipher Suite Java Secure Socket Extension (JSSE) Name
ECDHE-ECDSA-AES256-GCM-SHA384 TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384
ECDHE-RSA-AES256-GCM-SHA384 TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
ECDHE-ECDSA-AES128-GCM-SHA256 TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
ECDHE-RSA-AES128-GCM-SHA256 TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
ECDHE-ECDSA-AES256-SHA384 TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384
ECDHE-RSA-AES256-SHA384 TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
ECDHE-ECDSA-AES128-SHA256 TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
ECDHE-RSA-AES128-SHA256 TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256