CASSANDRA-13971 Automatic certificate management using Vault WIP

conf/cassandra.yaml

@@ -944,6 +944,7 @@ dynamic_snitch_badness_threshold: 0.1
 # The passwords used in these options must match the passwords used when generating
 # the keystore and truststore.  For instructions on generating these files, see:
 # http://download.oracle.com/javase/8/docs/technotes/guides/security/jsse/JSSERefGuide.html#CreateKeystore
+# The keystore will be checked for changes periodically and reloaded dynamically if needed.
 #
 server_encryption_options:
     # set to true for allowing secure incoming connections
@@ -959,6 +960,7 @@ server_encryption_options:
     keystore_password: cassandra
     truststore: conf/.truststore
     truststore_password: cassandra
+    #ca_file: conf/ca.pem
     # More advanced defaults below:
     # protocol: TLS
     # store_type: JKS
@@ -982,6 +984,44 @@ client_encryption_options:
     # store_type: JKS
     # cipher_suites: [TLS_RSA_WITH_AES_128_CBC_SHA,TLS_RSA_WITH_AES_256_CBC_SHA,TLS_DHE_RSA_WITH_AES_128_CBC_SHA,TLS_DHE_RSA_WITH_AES_256_CBC_SHA,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA]
 
+# Experimental support for dynamic certificate management
+# Enabling a certificate issuer for server (inter-node) or client (native transport) connections
+# will allow automatic certificate creation at runtime. Implementations will request certificates from an
+# external PKI and renew (possibly short lived) certificates as needed.
+
+# VaultCertificateIssuer
+# See https://www.vaultproject.io/docs/secrets/pki/index.html
+# Make sure to also enable a VaultAuthenticator in the Vault section below.
+#server_certificate_issuer:
+#  - class_name: org.apache.cassandra.vault.VaultCertificateIssuer
+#    parameters:
+#        # URI prefix where the Vault PKI backend has been mounted
+#      - pki_path: /v1/pki/cas-cluster
+#        # Role mapped to policy used to generate credentials
+#        role: cluster_node
+#        # How many days before certificate expiration should we start trying to acquire a new certificate?
+#        # Omitting the value or setting it to < 0 will disable certificate renewal
+#        renew_days_before_expire: 5
+#        # Indicates if credentials should be stored in the local keystore configured above
+#        use_keystore: true
+#        # Common name the certificate should be issued for (required)
+#        common_name: cassandra1.vlan1
+#        # It's recommended to add an IP naming extension, as the hostname will not always be available
+#        ip_sans: 10.1.2.3
+#        # Optional alternative names
+#        alt_names: cassandra1.local
+#
+#client_certificate_issuer:
+#  - class_name: org.apache.cassandra.vault.VaultCertificateIssuer
+#    parameters:
+#      - pki_path: /v1/pki/cas-cluster
+#        role: cluster_node
+#        renew_days_before_expire: 5
+#        use_keystore: true
+#        common_name: cassandra1.vlan1
+#        ip_sans: 10.1.2.3
+#        alt_names: cassandra1.local
+
 # internode_compression controls whether traffic between nodes is
 # compressed.
 # Can be:
@@ -1168,3 +1208,17 @@ back_pressure_strategy:
 # The full query log will recrusively delete the contents of this path at
 # times. Don't place links in this directory to other parts of the filesystem.
 #full_query_log_dir: /tmp/cassandrafullquerylog
+
+# Vault settings #
+# Address of Vault instance that should be used for certificate and key management.
+#vault_address: https://vault.example:8200
+# File at least a single PEM formatted certificate that is used for ssl endpoint verification. This should either be
+# the Vault certificate (as configured as "tls_cert_file") or a signing CA certificate.
+#vault_cert_file: /etc/cassandra/vault-cert.pem
+
+# Authenticator to be used for obtaining a client access token from Vault.
+#vault_authenticator:
+#    - class_name: org.apache.cassandra.vault.AppRoleAuthenticator
+#      parameters:
+#        # properties file with role_id and optional secret_id value
+#        - id_file_path: /etc/cassandra/vault_approle.properties

doc/source/operating/certificate_management/index.rst

@@ -0,0 +1,27 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+.. or more contributor license agreements.  See the NOTICE file
+.. distributed with this work for additional information
+.. regarding copyright ownership.  The ASF licenses this file
+.. to you under the Apache License, Version 2.0 (the
+.. "License"); you may not use this file except in compliance
+.. with the License.  You may obtain a copy of the License at
+..
+..     http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+
+.. highlight:: none
+
+Certificate Handling
+====================
+
+.. toctree::
+   :maxdepth: 2
+
+   integrated
+   vault
+

doc/source/operating/certificate_management/integrated.rst

@@ -0,0 +1,54 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+.. or more contributor license agreements.  See the NOTICE file
+.. distributed with this work for additional information
+.. regarding copyright ownership.  The ASF licenses this file
+.. to you under the Apache License, Version 2.0 (the
+.. "License"); you may not use this file except in compliance
+.. with the License.  You may obtain a copy of the License at
+..
+..     http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+
+.. highlight:: none
+
+Integrated Certificate Management
+---------------------------------
+
+Motivation
+^^^^^^^^^^
+
+Cassandra can be configured to make use of SSL encryption before sending data over the network. Until recently, the only way to enable SSL was to setup a local keystore containing the required certificates. The actual steps for setting up such a keystore are not much different from the key and certificate creation process for other servers, such as Apache or other datastores. It can either be done manually using the keystore or openssl tools, or done automatically by a configuration management solution, such as puppet. In both cases, there are some challenges for securely deploying such credentials that operators need to be aware of.
+
+*Confidentiality of private keys*. Not only must the key be protected in the local filesystem, but also securely provisioned. Generating the private key locally on a developer system and copying it to the server is not the safest option. Manually creating keys for a large cluster will be tedious and solutions such as Puppet or Ansible can help with that. But it's not trivial to setup the provisioning process in a secure way.
+
+*Establishing a root of trust*. Each node must be able to verify that other nodes are to be trusted. This is taking place during the SSL handshake protocol by inspecting the certificate of the other node and checking if the certificate is either present in the local truststore or signed by a trusted CA. There are many practical and security considerations that can influence your decision which way to go.
+
+*Dealing with certificate expiration*. Some people feel slightly uncomfortable when using certificates for their backend systems, as there's always the risk that certificates may expire before they have been replaced. Cassandra operators don't like the idea of getting paged late at night, because the cluster suddenly stopped working with tons of SSLHandshakeException errors in the log file. Therefor it's important to deal with certificate renewal in one way or another.
+
+As a consequence of the pitfalls listed above, it's not uncommon to see people using certificates with long validation periods. Once deployed securely, the certificate will be used for a long time before having to go through the more or less painful renewal process again. Even if your ansible scripts are still working two years later, replacing certificates for each node in your cluster is not the most popular tasks to sign up for. So people try to avoid it, which is unfortunately not a good thing from the security perspective.
+
+Ideally the opposite should happen. Certificates should be replaced on regular basis after a short time. This will make sure that certificates and keys will become automatically invalid shortly after they have been compromised. This is especially important since such persistent compromises are very hard to detect. An automatic certificate handling process will also be less disruptive from a operational perspective and therefor less risky to potential incidents.
+
+Pluggable Certificate Management API
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Automatic certificate handling can be enabled by choosing one of the available implementations in the cassandra.yaml configuration. Currently only a Vault based implementation is available. But users can provide their own implementation by add a jar file with the new classes to the Cassandra lib directory and configuring the actual `CertificateIssuer <https://github.com/apache/cassandra/blob/trunk/src/java/org/apache/cassandra/vault/VaultCertificateIssuer.java>`__ implementation in the ``cassandra.yaml`` file.
+
+.. note:: Contributions of additional implementations are most welcome!
+
+Vault Support
+^^^^^^^^^^^^^
+
+About Vault:
+
+    Vault secures, stores, and tightly controls access to tokens, passwords, certificates, API keys, and other secrets in modern computing. Vault handles leasing, key revocation, key rolling, and auditing. Through a unified API, users can access an encrypted Key/Value store and network encryption-as-a-service, or generate AWS IAM/STS credentials, SQL/NoSQL databases, X.509 certificates, SSH credentials, and more. https://www.vaultproject.io/
+
+In other words, Vault is a toolbox with different security features that can be accessed through a remote API. Certificate handling in Cassandra is implemented by making use of the `PKI backend <https://www.vaultproject.io/docs/secrets/pki/index.html>`__ functionality.
+
+See :doc:`vault` guide for more details.
+