Create a connection for the DSP Kafka SSL Connector

Use the DSP Kafka SSL Connector to get data from an Apache or Confluent Kafka server. The Kafka SSL Connector supports two-way SSL authentication where the client and server authenticate each other using the SSL/TLS protocol. For information about getting data from Kafka without using SSL, see Create a connection for the DSP Apache Kafka Connector without authentication.

To use a connector, you must create a connection. You can reuse the Kafka connection for both the Read from Kafka source function and the Write to Kafka sink function.

Prerequisites

Before you can create a Kafka SSL connection, you must have the following:

• At least one Kafka server that has SSL enabled and is running one of the following Kafka versions:
  • Apache Kafka version 1.0 or higher
  • Confluent Kafka version 3.0 or higher
• A Java keystore and truststore on each Kafka server with all certificates signed by a Certificate Authority (CA).
• A client private key, a client certificate, and the CA certificate used to sign the client certificate.

If you haven't yet created a Kafka client keystore to interact with your SSL-enabled Kafka server, follow the instructions in this topic to create a Kafka client keystore and then extract the key and certificates in the format required for the Kafka SSL connection.

If you already have a Kafka client keystore where the RSA algorithm was used to generate the key/certificate pair, and the client certificate was signed by the same CA certificate used to sign the server certificate, then skip to the section titled "Export the key and certificates in PEM format".

Create the client keystore

1. From a command line interface, use the Java keytool command to create the client keystore.

   keytool -keystore client.keystore.jks -alias localhost -validity 365 -genkey -keyalg RSA
   

2. When prompted, set a password and enter some optional metadata for the keystore. You can set any password and metadata. You can choose to leave the metadata fields blank.

After entering the required information, a client.keystore.jks file is saved in your directory.

Sign the client certificate with a CA certificate

Sign the client certificate with the same CA certificate you used to sign the Kafka server certificate in the server keystore file. In this example, the CA certificate is in PEM format in a file named ca-cert, and the certificate starts with -----BEGIN CERTIFICATE-----. The CA key is in PEM format in a file named ca-key, and the key starts with -----BEGIN ENCRYPTED PRIVATE KEY-----.

1. Export the client certificate so that it can be signed.

   keytool -keystore client.keystore.jks -alias localhost -certreq -file cert-file

2. Sign the client certificate with the CA certificate. When running this command, replace <ca-password> with the passphrase for the CA key.

   openssl x509 -req -CA ca-cert -CAkey ca-key -in cert-file -out cert-signed -days 365 -CAcreateserial -passin pass:<ca-password>

3. Add the CA certificate to the keystore.
   

   keytool -keystore client.keystore.jks -alias CARoot -import -file ca-cert

4. Add the signed client certificate to the keystore.
   

   keytool -keystore client.keystore.jks -alias localhost -import -file cert-signed

Export the key and certificates in PEM format

Export the signed client certificate, the CA certificate that was used to sign it, and the client private key from your keystore. You need to upload these exported files to DSP when creating a Kafka SSL connection.

1. If your keystore is not already in PKCS12 (.p12) format, then convert it to that format. Make sure to use the same password for both the original keystore and the converted keystore. If you created your keystore based on the instructions in this topic, then you need to convert your keystore from JKS (.jks) format to PKCS12 (.p12) format using the following command.

   keytool -importkeystore -srckeystore client.keystore.jks -destkeystore client.keystore.p12  -srcstoretype jks -deststoretype pkcs12

2. Export the client private key unencrypted in PEM format, and convert it to RSA format. Save the formatted private key to the file privkey.pem. When running the following command, replace <keystore-password> with the password for your keystore.

   openssl pkcs12 -in client.keystore.p12 -nocerts -nodes -passin pass:<keystore-password> | openssl rsa -out privkey.pem
   

3. Export the certificates to the file certs.pem. When running the following command, replace <keystore-password> with the password for your keystore.

   openssl pkcs12 -in client.keystore.p12 -nokeys -out certs.pem -passin pass:<keystore-password>

4. Copy the signed client certificate and the CA certificate into separate files:
   1. Open the certs.pem file in a text editor, and then copy the signed client certificate into a new text file and save it. If you created your keystore and certificates based on the instructions in this topic, the signed client certificate is labeled as friendlyName: localhost.
   2. From the certs.pem file, copy the CA certificate into a new text file and save it. If you created your keystore and certificates based on the instructions in this topic, the CA certificate is labeled as friendlyName: CAroot.

Configure the Kafka SSL connection in the Data Stream Processor UI

Now that you have the required certificates and keys, create a connection in the Data Stream Processor UI.

If you are editing a connection that's being used by an active pipeline, you must reactivate that pipeline after making your changes.

1. Navigate to the Data Stream Processor UI. From the Data Management page, select the Connections tab.
2. Click Create New Connection.
3. Select Apache Kafka Connector using SSL and then click Next.
4. Complete the following fields:

   Field	Description
   Connection Name	A unique name for your connection.
   Description	(Optional) A description of your connection.
   Kafka Brokers	A comma-separated list of your Kafka brokers. You must enter at least one broker.
   Client Private Key	The file containing the client private key, beginning with -----BEGIN RSA PRIVATE KEY----- and ending with -----END RSA PRIVATE KEY-----. This file is created as privkey.pem during step 2 of "Export the key and certificates in PEM format".
   Client Certificate	The file containing the client certificate, beginning with -----BEGIN CERTIFICATE----- and ending with -----END CERTIFICATE-----. This file is created using the localhost certificate during step 4a of "Export the key and certificates in PEM format".
   CA or Kafka Server Cert	The file containing the original CA certificate. You can also use the file that is created using the CAroot certificate during step 4b of "Export the key and certificates in PEM format".
   Kafka properties	(Optional) Enter any consumer properties by which you want to delimit your data. To enter more than one property, click Add input for every new property you want to add. The Kafka source and sink functions that use this connection automatically set a list of Kafka properties that can't be overwritten. See the "Kafka properties set by DSP" section of this topic.

   The data uploaded when creating the Kafka SSL connection is transmitted securely by HTTPS. The client private key is encrypted and stored securely in a secrets manager.

   If your data fails to get into DSP, check the fields again to make sure you have the correct name, Kafka brokers, client private key, client certificate, CA or Kafka Server Cert, and Kafka properties for your Kafka SSL connection. DSP doesn't run a check to see if you enter the valid credentials.

5. Click Save.

You can now use your Kafka SSL connection in a data pipeline. See Deserialize and send Kafka data from a DSP pipeline.

Kafka properties set by DSP

When using the Kafka SSL connector, the Read from Kafka function automatically sets the following Kafka properties:

ssl.truststore.location=/local/path/to/kafka.client.truststore.jks
ssl.truststore.password=<randomized-password>
ssl.keystore.location=/local/path/to/kafka.client.keystore.jks
ssl.keystore.password=<randomized-password>
ssl.key.password=<randomized-password>
ssl.keystore.type=JKS
ssl.truststore.type=JKS
security.protocol=SSL

You can't overwrite any of the properties in this list when connecting to Kafka using SSL.