Apache Cassandra | Apache Cassandra Documentation

This article discusses how to configure Apache Cassandra 4.1 and beyond to use your PEM-encoded security credentials like your private key, corresponding certificate chain, and trusted CA certificates.

What is PEM?

PEM stands for Privacy Enhanced Mail. It is a popular data-formatting standard for your cryptographic keys, certificates, and other data. Being a text-based encoding standard, PEM makes it easier to transport, transfer, and even edit the data with simple text editors. It is easy to copy and paste and combine different PEM encoded artifacts (for example: build a certificate chain and combine with corresponding private key) to create new ones.

An Interesting fact about PEM is that—as the name suggests—it was designed to be used for electronic mail systems but became popular for encoding cryptographic data while other standards like S/MIME saw a better success with emails. Below is an example from ssl.com of a X.509 Certificate represented in PEM format,

Why do we need support for PEM if we have JKS support?

Most Java-based systems allow storing/reading security credentials in/from Java Keystore using a .jks file extension. You can create your keystore and truststore in JKS format using the keytool utility from Java. Apache Cassandra, being Java-based, supports keystore and truststore in JKS format. You can read the Apache Cassandra 4.0 documentation for more details on this.

However, if you have your security credentials already in PEM format and use them in other systems, it would be an operational overhead to convert from PEM format to JKS just for Apache Cassandra. This conversion requires converting security credentials to first PKCS#12 format and then to JKS. The Apache Cassandra community agreed that it should support widely adopted standards like PEM out-of-box with its ‘batteries-included’ philosophy and has worked on delivering this. Apache Cassandra 4.1, targeted to freeze in May 2022 and a release in July 2022, will enable you to do exactly that.

Using PEM-encoded security credentials with Apache Cassandra 4.1

Apache Cassandra 4.1 introduces a pluggable configuration for customizing the SSL context for TLS encryption. It also offers built-in support for PEM-based security credentials. For the PEM-based key material, you can use the built-in class PEMBasedSSLContextFactory as the ssl_context_factory setting.

You can configure the PEM-based factory with either in-line PEM data or files with the required PEM data, as shown below. Here the PEM encoded private key is expected to be in PKCS#8 format. Just remember the spaces and indentations in the YAML.

Defining PEM keys/certs in-line to the configuration

client/server_encryption_options:
    ssl_context_factory:
         class_name: org.apache.cassandra.security.PEMBasedSslContextFactory
         parameters:
             private_key: |
             -----BEGIN ENCRYPTED PRIVATE KEY-----
             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
             FujZhqbKUDbYAcqTkoQ=
             -----END ENCRYPTED PRIVATE KEY-----
             -----BEGIN CERTIFICATE-----
             MIIDkTCCAnmgAwIBAgIETxH5JDANBgkqhkiG9w0BAQsFADB5MRAwDgYDVQQGEwdV
             bmtub3duMRAwDgYDVQQIEwdVbmtub3duMRAwDgYDVQQHEwdVbmtub3duMRAwDgYD
             VQQKEwdVbmtub3duMRQwEgYDVQQLDAtzc2xfdGVzdGluZzEZMBcGA1UEAxMQQXBh
             Y2hlIENhc3NhbmRyYTAeFw0xNjAzMTgyMTI4MDJaFw0xNjA2MTYyMTI4MDJaMHkx
             EDAOBgNVBAYTB1Vua25vd24xEDAOBgNVBAgTB1Vua25vd24xEDAOBgNVBAcTB1Vu
             a25vd24xEDAOBgNVBAoTB1Vua25vd24xFDASBgNVBAsMC3NzbF90ZXN0aW5nMRkw
             FwYDVQQDExBBcGFjaGUgQ2Fzc2FuZHJhMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A
             MIIBCgKCAQEAjkmVX/HS49cS8Hn6o26IGwMIcEV3d7ZhH0GNcx8rnSRd10dU9F6d
             ugSjbwGFMcWUQzYNejN6az0Wb8JIQyXRPTWjfgaWTyVGr0bGTnxg6vwhzfI/9jzy
             q59xv29OuSY1dxmY31f0pZ9OOw3mabWksjoO2TexfKoxqsRHJ8PrM1f8E84Z4xo2
             TJXGzpuIxRkAJ+sVDqKEAhrKAfRYMSgdJ7zRt8VXv9ngjX20uA2m092NcH0Kmeto
             TmuWUtK8E/qcN7ULN8xRWNUn4hu6mG6mayk4XliGRqI1VZupqh+MgNqHznuTd0bA
             YrQsFPw9HaZ2hvVnJffJ5l7njAekZNOL+wIDAQABoyEwHzAdBgNVHQ4EFgQUcdiD
             N6aylI91kAd34Hl2AzWY51QwDQYJKoZIhvcNAQELBQADggEBAG9q29ilUgCWQP5v
             iHkZHj10gXGEoMkdfrPBf8grC7dpUcaw1Qfku/DJ7kPvMALeEsmFDk/t78roeNbh
             IYBLJlzI1HZN6VPtpWQGsqxltAy5XN9Xw9mQM/tu70ShgsodGmE1UoW6eE5+/GMv
             6Fg+zLuICPvs2cFNmWUvukN5LW146tJSYCv0Q/rCPB3m9dNQ9pBxrzPUHXw4glwG
             qGnGddXmOC+tSW5lDLLG1BRbKv4zxv3UlrtIjqlJtZb/sQMT6WtG2ihAz7SKOBHa
             HOWUwuPTetWIuJCKP7P4mWWtmSmjLy+BFX5seNEngn3RzJ2L8uuTJQ/88OsqgGru
             n3MVF9w=
             -----END CERTIFICATE-----
             private_key_password: "cassandra"
             trusted_certificates: |
              -----BEGIN CERTIFICATE-----
              MIIDkTCCAnmgAwIBAgIETxH5JDANBgkqhkiG9w0BAQsFADB5MRAwDgYDVQQGEwdV
              bmtub3duMRAwDgYDVQQIEwdVbmtub3duMRAwDgYDVQQHEwdVbmtub3duMRAwDgYD
              VQQKEwdVbmtub3duMRQwEgYDVQQLDAtzc2xfdGVzdGluZzEZMBcGA1UEAxMQQXBh
              Y2hlIENhc3NhbmRyYTAeFw0xNjAzMTgyMTI4MDJaFw0xNjA2MTYyMTI4MDJaMHkx
              EDAOBgNVBAYTB1Vua25vd24xEDAOBgNVBAgTB1Vua25vd24xEDAOBgNVBAcTB1Vu
              a25vd24xEDAOBgNVBAoTB1Vua25vd24xFDASBgNVBAsMC3NzbF90ZXN0aW5nMRkw
              FwYDVQQDExBBcGFjaGUgQ2Fzc2FuZHJhMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A
              MIIBCgKCAQEAjkmVX/HS49cS8Hn6o26IGwMIcEV3d7ZhH0GNcx8rnSRd10dU9F6d
              ugSjbwGFMcWUQzYNejN6az0Wb8JIQyXRPTWjfgaWTyVGr0bGTnxg6vwhzfI/9jzy
              q59xv29OuSY1dxmY31f0pZ9OOw3mabWksjoO2TexfKoxqsRHJ8PrM1f8E84Z4xo2
              TJXGzpuIxRkAJ+sVDqKEAhrKAfRYMSgdJ7zRt8VXv9ngjX20uA2m092NcH0Kmeto
              TmuWUtK8E/qcN7ULN8xRWNUn4hu6mG6mayk4XliGRqI1VZupqh+MgNqHznuTd0bA
              YrQsFPw9HaZ2hvVnJffJ5l7njAekZNOL+wIDAQABoyEwHzAdBgNVHQ4EFgQUcdiD
              N6aylI91kAd34Hl2AzWY51QwDQYJKoZIhvcNAQELBQADggEBAG9q29ilUgCWQP5v
              iHkZHj10gXGEoMkdfrPBf8grC7dpUcaw1Qfku/DJ7kPvMALeEsmFDk/t78roeNbh
              IYBLJlzI1HZN6VPtpWQGsqxltAy5XN9Xw9mQM/tu70ShgsodGmE1UoW6eE5+/GMv
              6Fg+zLuICPvs2cFNmWUvukN5LW146tJSYCv0Q/rCPB3m9dNQ9pBxrzPUHXw4glwG
              qGnGddXmOC+tSW5lDLLG1BRbKv4zxv3UlrtIjqlJtZb/sQMT6WtG2ihAz7SKOBHa
              HOWUwuPTetWIuJCKP7P4mWWtmSmjLy+BFX5seNEngn3RzJ2L8uuTJQ/88OsqgGru
              n3MVF9w=
              -----END CERTIFICATE-----

Defining PEM keys/certs in files

Configuration

client/server_encryption_options:
    ssl_context_factory:
        class_name: org.apache.cassandra.security.PEMBasedSslContextFactory
    internode_encryption: none
    keystore: conf/cassandra_ssl_test.keystore.pem
    keystore_password: cassandra
    truststore: conf/cassandra_ssl_test.truststore.pem

Keystore file

Location: conf/cassandra_ssl_test.keystore.pem

Truststore file

Location: conf/cassandra_ssl_test.truststore.pem

Kubernetes and K8s Pod configuration

If you’re on Kubernetes, we have an example built for that already. Let’s walk through the POD configuration and cassandra.yaml configuration considering the example class’s availability. In the pod.yaml, below, we are configuring secrets-based environment variables for the PEM private key, including the corresponding certificate chain, private key’s password, and the trusted certificates. Kubernetes secrets-based environment variables provide equivalent in-line PEM content (which we mentioned in the previous section). The last-updated-timestamps for keystore and truststore are mounted as secrets to be able to hot-reload security credentials upon changes to them. You can also use Kubernetes secrets for file-based PEM content, assuming you make appropriate changes in the example code.

Note: We’ve omitted repeating the same PEM content from the previous sections for the data for creating Kubernetes secrets required here.

apiVersion: v1
kind: Pod
metadata:
  name: my-pod
  labels:
    app: my-app
spec:
  containers:
  - name: my-app
    image: my-app:latest
    imagePullPolicy: Always
    env:
      - name: PRIVATE_KEY
        valueFrom:
          secretKeyRef:
            name: my-ssl-store
            key: private-key
      - name: PRIVATE_KEY_PASSWORD
        valueFrom:
          secretKeyRef:
            name: my-ssl-store
            key: private-key-password
      - name: TRUSTED_CERTIFICATES
        valueFrom:
          secretKeyRef:
            name: my-ssl-store
            key: trusted-certificates
    volumeMounts:
    - name: my-ssl-store
      mountPath: "/etc/my-ssl-store"
      readOnly: true
  volumes:
  - name: my-ssl-store
    secret:
      secretName: my-ssl-store
      items:
        - key: keystore-last-updatedtime
          path: keystore-last-updatedtime
        - key: truststore-last-updatedtime
          path: truststore-last-updatedtime

cassandra.yaml configuration

In the configuration below, we provide appropriate secret names and paths for the security credentials required by the example class.

client/server_encryption_options:
  internode_encryption: none
  ssl_context_factory:
    class_name: org.apache.cassandra.security.KubernetesSecretsPEMSslContextFactory
    parameters:
      PRIVATE_KEY_ENV_VAR: PRIVATE_KEY
      PRIVATE_KEY_PASSWORD_ENV_VAR: PRIVATE_KEY_PASSWORD
      KEYSTORE_UPDATED_TIMESTAMP_PATH: /etc/my-ssl-store/keystore-last-updatedtime
      TRUSTED_CERTIFICATES_ENV_VAR: TRUSTED_CERTIFICATES
      TRUSTSTORE_UPDATED_TIMESTAMP_PATH: /etc/my-ssl-store/truststore-last-updatedtime

And there you have it; you can now enjoy PEM secrets on Apache Cassandra!

Can Apache Cassandra take my PEM keys?

March 10, 2022 | Maulin Vasavada