[GitHub] [cassandra] maulin-vasavada commented on a change in pull request #1441: Documentation for CASSANDRA-16950 and CASSANDRA-17031

[GitBox <gi...@apache.org>]

maulin-vasavada commented on a change in pull request #1441:
URL: https://github.com/apache/cassandra/pull/1441#discussion_r802970915



##########
File path: doc/modules/cassandra/pages/operating/security.adoc
##########
@@ -43,20 +43,91 @@ not involve changing encryption settings in cassandra.yaml. See
 https://docs.oracle.com/javase/8/docs/technotes/guides/security/jsse/FIPS.html[the
 java document on FIPS] for more details.
 
-For information on generating the keystore and truststore files used in
-SSL communications, see the
+Cassandra provides flexibility of using Java based key material or
+completely customizing the SSL context. You can choose any keystore
+format supported by Java (JKS, PKCS12 etc) as well as other standards
+like PEM. You can even customize the SSL context creation to use Cloud
+Native technologies like Kuberenetes Secrets for storing the key
+material or to integrate with your inhouse Key Management System.
+
+For information on generating the keystore and truststore files
+required with the Java supported keystores used in SSL communications,
+see the
 http://download.oracle.com/javase/6/docs/technotes/guides/security/jsse/JSSERefGuide.html#CreateKeystore[java
-documentation on creating keystores]
+documentation on creating keystores].
+
+For customizing the SSL context creation you can implement
+https://github.com/apache/cassandra/blob/trunk/src/java/org/apache/cassandra/security/ISslContextFactory.java[ISslContextCreationFactory]
+interface or extend one of it's public subclasses appropriately. You
+can then use the `ssl_context_factory` setting for
+`server_encryption_options` or `client_encryption_options` sections
+appropriately. See https://github.com/apache/cassandra/tree/trunk/examples/ssl-factory[ssl-factory examples]
+for details. Refer to the below class diagram to understand the
+class hierarchy,
+
+image::Cassandra-SslContextFactory-PEM.png[SslContextFactory Class Diagram]
+
+=== Using PEM based key material
+
+You can use the inbuilt class `PEMBasedSSLContextFactory` as the
+`ssl_context_factory` setting for the PEM based key material.
+
+You can configure this factory with either inline PEM data or with the
+files having the required PEM data as shown below,
+
+* Configuration: PEM keys/certs defined inline (mind the spaces in the
+YAML!)
+
+....
+   client/server_encryption_options:
+     ssl_context_factory:
+        class_name: org.apache.cassandra.security.PEMBasedSslContextFactory
+        parameters:
+            private_key: |
+             -----BEGIN ENCRYPTED PRIVATE KEY----- OR -----BEGIN PRIVATE KEY-----
+             <your base64 encoded private key>
+             -----END ENCRYPTED PRIVATE KEY----- OR -----END PRIVATE KEY-----
+             -----BEGIN CERTIFICATE-----
+             <your base64 encoded certificate chain>
+             -----END CERTIFICATE-----
+
+            private_key_password: "<your password if the private key is encrypted with a password>"
+
+            trusted_certificates: |
+              -----BEGIN CERTIFICATE-----
+              <your base64 encoded certificate>
+              -----END CERTIFICATE-----
+....
+
+* Configuration: PEM keys/certs defined in files
+....
+    client/server_encryption_options:
+     ssl_context_factory:
+        class_name: org.apache.cassandra.security.PEMBasedSslContextFactory
+     keystore: <file path to the keystore file in the PEM format with the private key and the certificate chain>
+     keystore_password: "<your password if the private key is encrypted with a password>"
+     truststore: <file path to the truststore file in the PEM format>
+....
 
 == SSL Certificate Hot Reloading
 
 Beginning with Cassandra 4, Cassandra supports hot reloading of SSL
-Certificates. If SSL/TLS support is enabled in Cassandra, the node
-periodically polls the Trust and Key Stores specified in cassandra.yaml.
-When the files are updated, Cassandra will reload them and use them for
-subsequent connections. Please note that the Trust & Key Store passwords
-are part of the yaml so the updated files should also use the same
-passwords. The default polling interval is 10 minutes.
+Certificates. If SSL/TLS support is enabled in Cassandra and you are
+using default file based key material, the node periodically polls the
+Trust and Key Stores specified in cassandra.yaml. When the files are
+updated, Cassandra will reload them and use them for subsequent
+connections. Please note that the Trust & Key Store passwords are part
+of the yaml so the updated files should also use the same passwords.
+The default polling interval is 10 minutes.

Review comment:
       Good point! Currently this default is not overridable. So we have to change the documentation to make that clearer.




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: pr-unsubscribe@cassandra.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: pr-unsubscribe@cassandra.apache.org
For additional commands, e-mail: pr-help@cassandra.apache.org