PEMBasedSslContextFactory.java
/*
* 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.
*/
package org.apache.cassandra.security;
import java.io.IOException;
import java.nio.file.Files;
import java.security.GeneralSecurityException;
import java.security.KeyStore;
import java.security.PrivateKey;
import java.security.cert.Certificate;
import java.util.ArrayList;
import java.util.List;
import java.util.Map;
import javax.net.ssl.KeyManagerFactory;
import javax.net.ssl.SSLException;
import javax.net.ssl.TrustManagerFactory;
import org.apache.commons.lang3.StringUtils;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.apache.cassandra.io.util.File;
/**
* SslContextFactory for the <a href="">PEM standard</a> encoded PKCS#8 private keys and X509 certificates/public-keys.
* It parses the key material based on the standard defined in the <a href="https://datatracker.ietf.org/doc/html/rfc7468">RFC 7468</a>.
* It creates <a href="https://datatracker.ietf.org/doc/html/rfc5208">PKCS# 8</a> based private key and X509 certificate(s)
* for the public key to build the required keystore and the truststore managers that are used for the SSL context creation.
* Internally it builds Java {@link KeyStore} with <a href="https://datatracker.ietf.org/doc/html/rfc7292">PKCS# 12</a> <a href="https://docs.oracle.com/en/java/javase/11/docs/specs/security/standard-names.html#keystore-types">store type</a>
* to be used for keystore and the truststore managers.
* <p>
* This factory also supports 'hot reloading' of the key material, the same way as defined by {@link FileBasedSslContextFactory},
* <b>if it is file based</b>. This factory ignores the existing 'store_type' configuration used for other file based store
* types like JKS.
* <p>
* You can configure this factory with either inline PEM data or with the files having the required PEM data as shown
* below,
*
* <b>Configuration: PEM keys/certs defined inline (mind the spaces in the YAML!)</b>
* <pre>
* 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-----
* </pre>
*
* <b>Configuration: PEM keys/certs defined in files</b>
* <pre>
* 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>
* </pre>
*/
public final class PEMBasedSslContextFactory extends FileBasedSslContextFactory
{
public static final String DEFAULT_TARGET_STORETYPE = "PKCS12";
private static final Logger logger = LoggerFactory.getLogger(PEMBasedSslContextFactory.class);
private PEMBasedKeyStoreContext pemEncodedTrustCertificates;
private PEMBasedKeyStoreContext pemEncodedKeyContext;
private PEMBasedKeyStoreContext pemEncodedOutboundKeyContext;
public PEMBasedSslContextFactory()
{
}
private void validatePasswords()
{
boolean shouldThrow = !keystoreContext.passwordMatchesIfPresent(pemEncodedKeyContext.password)
|| !outboundKeystoreContext.passwordMatchesIfPresent(pemEncodedOutboundKeyContext.password);
boolean outboundPasswordMismatch = !outboundKeystoreContext.passwordMatchesIfPresent(pemEncodedOutboundKeyContext.password);
String keyName = outboundPasswordMismatch ? "outbound_" : "";
if (shouldThrow)
{
final String msg = String.format("'%skeystore_password' and '%skey_password' both configurations are given and the values do not match", keyName, keyName);
throw new IllegalArgumentException(msg);
}
}
public PEMBasedSslContextFactory(Map<String, Object> parameters)
{
super(parameters);
final String pemEncodedKey = getString(ConfigKey.ENCODED_KEY.getKeyName());
final String pemEncodedKeyPassword = StringUtils.defaultString(getString(ConfigKey.KEY_PASSWORD.getKeyName()), keystoreContext.password);
pemEncodedKeyContext = new PEMBasedKeyStoreContext(pemEncodedKey, pemEncodedKeyPassword, StringUtils.isEmpty(pemEncodedKey), keystoreContext);
final String pemEncodedOutboundKey = StringUtils.defaultString(getString(ConfigKey.OUTBOUND_ENCODED_KEY.getKeyName()), pemEncodedKey);
final String outboundKeyPassword = StringUtils.defaultString(StringUtils.defaultString(getString(ConfigKey.OUTBOUND_ENCODED_KEY_PASSWORD.getKeyName()),
outboundKeystoreContext.password), pemEncodedKeyPassword);
pemEncodedOutboundKeyContext = new PEMBasedKeyStoreContext(pemEncodedKey, outboundKeyPassword, StringUtils.isEmpty(pemEncodedOutboundKey), outboundKeystoreContext);
validatePasswords();
if (!StringUtils.isEmpty(trustStoreContext.password))
{
logger.warn("PEM based truststore should not be using password. Ignoring the given value in " +
"'truststore_password' configuration.");
}
final String pemEncodedCerts = getString(ConfigKey.ENCODED_CERTIFICATES.getKeyName());
pemEncodedTrustCertificates = new PEMBasedKeyStoreContext(pemEncodedCerts, null, StringUtils.isEmpty(pemEncodedCerts), trustStoreContext);
enforceSinglePrivateKeySource();
enforceSingleTurstedCertificatesSource();
}
/**
* Decides if this factory has a keystore defined - key material specified in files or inline to the configuration.
*
* @return {@code true} if there is a keystore defined; {@code false} otherwise
*/
@Override
public boolean hasKeystore()
{
return pemEncodedKeyContext.maybeFilebasedKey
? keystoreContext.hasKeystore()
: !StringUtils.isEmpty(pemEncodedKeyContext.key);
}
/**
* Decides if this factory has an outbound keystore defined - key material specified in files or inline to the configuration.
*
* @return {@code true} if there is an outbound keystore defined; {@code false} otherwise
*/
@Override
public boolean hasOutboundKeystore()
{
return pemEncodedOutboundKeyContext.maybeFilebasedKey
? outboundKeystoreContext.hasKeystore()
: !StringUtils.isEmpty(pemEncodedOutboundKeyContext.key);
}
/**
* Decides if this factory has a truststore defined - key material specified in files or inline to the
* configuration.
*
* @return {@code true} if there is a truststore defined; {@code false} otherwise
*/
private boolean hasTruststore()
{
return pemEncodedTrustCertificates.maybeFilebasedKey ? truststoreFileExists() :
!StringUtils.isEmpty(pemEncodedTrustCertificates.key);
}
/**
* Checks if the truststore file exists.
*
* @return {@code true} if truststore file exists; {@code false} otherwise
*/
private boolean truststoreFileExists()
{
return trustStoreContext.filePath != null && new File(trustStoreContext.filePath).exists();
}
/**
* This enables 'hot' reloading of the key/trust stores based on the last updated timestamps if they are file based.
*/
@Override
public synchronized void initHotReloading()
{
List<HotReloadableFile> fileList = new ArrayList<>();
if (pemEncodedKeyContext.maybeFilebasedKey && hasKeystore())
{
fileList.add(new HotReloadableFile(keystoreContext.filePath));
}
if (pemEncodedOutboundKeyContext.maybeFilebasedKey && hasOutboundKeystore())
{
fileList.add(new HotReloadableFile(outboundKeystoreContext.filePath));
}
if (pemEncodedTrustCertificates.maybeFilebasedKey && hasTruststore())
{
fileList.add(new HotReloadableFile(trustStoreContext.filePath));
}
if (!fileList.isEmpty())
{
hotReloadableFiles = fileList;
}
}
/**
* Builds required KeyManagerFactory from the PEM based keystore. It also checks for the PrivateKey's certificate's
* expiry and logs {@code warning} for each expired PrivateKey's certitificate.
*
* @return KeyManagerFactory built from the PEM based keystore.
* @throws SSLException if any issues encountered during the build process
*/
@Override
protected KeyManagerFactory buildKeyManagerFactory() throws SSLException
{
return buildKeyManagerFactory(pemEncodedKeyContext, keystoreContext);
}
@Override
protected KeyManagerFactory buildOutboundKeyManagerFactory() throws SSLException
{
return buildKeyManagerFactory(pemEncodedOutboundKeyContext, outboundKeystoreContext);
}
private KeyManagerFactory buildKeyManagerFactory(PEMBasedKeyStoreContext pemBasedKeyStoreContext, FileBasedStoreContext keyStoreContext) throws SSLException
{
try
{
if (pemBasedKeyStoreContext.hasKey())
{
if (pemBasedKeyStoreContext.maybeFilebasedKey)
{
pemBasedKeyStoreContext.key = readPEMFile(keyStoreContext.filePath); // read PEM from the file
}
KeyManagerFactory kmf = KeyManagerFactory.getInstance(
algorithm == null ? KeyManagerFactory.getDefaultAlgorithm() : algorithm);
KeyStore ks = buildKeyStore(pemBasedKeyStoreContext.key, pemBasedKeyStoreContext.password);
if (!keyStoreContext.checkedExpiry)
{
checkExpiredCerts(ks);
keyStoreContext.checkedExpiry = true;
}
kmf.init(ks, pemBasedKeyStoreContext.password != null ? pemBasedKeyStoreContext.password.toCharArray() : null);
return kmf;
}
else
{
throw new SSLException("Must provide outbound_keystore or outbound_private_key in configuration for PEMBasedSSlContextFactory");
}
}
catch (Exception e)
{
throw new SSLException("Failed to build key manager store for secure connections", e);
}
}
/**
* Builds TrustManagerFactory from the PEM based truststore.
*
* @return TrustManagerFactory from the PEM based truststore
* @throws SSLException if any issues encountered during the build process
*/
@Override
protected TrustManagerFactory buildTrustManagerFactory() throws SSLException
{
try
{
if (hasTruststore())
{
if (pemEncodedTrustCertificates.maybeFilebasedKey)
{
pemEncodedTrustCertificates.key = readPEMFile(trustStoreContext.filePath); // read PEM from the file
}
TrustManagerFactory tmf = TrustManagerFactory.getInstance(
algorithm == null ? TrustManagerFactory.getDefaultAlgorithm() : algorithm);
KeyStore ts = buildTrustStore();
tmf.init(ts);
return tmf;
}
else
{
throw new SSLException("Must provide truststore or trusted_certificates in configuration for " +
"PEMBasedSSlContextFactory");
}
}
catch (Exception e)
{
throw new SSLException("Failed to build trust manager store for secure connections", e);
}
}
private String readPEMFile(String file) throws IOException
{
return new String(Files.readAllBytes(File.getPath(file)));
}
/**
* Builds KeyStore object given the {@link #DEFAULT_TARGET_STORETYPE} out of the PEM formatted private key material.
* It uses {@code cassandra-ssl-keystore} as the alias for the created key-entry.
*/
private static KeyStore buildKeyStore(final String pemEncodedKey, final String keyPassword) throws GeneralSecurityException, IOException
{
char[] keyPasswordArray = keyPassword != null ? keyPassword.toCharArray() : null;
PrivateKey privateKey = PEMReader.extractPrivateKey(pemEncodedKey, keyPassword);
Certificate[] certChainArray = PEMReader.extractCertificates(pemEncodedKey);
if (certChainArray == null || certChainArray.length == 0)
{
throw new SSLException("Could not read any certificates for the certChain for the private key");
}
KeyStore keyStore = KeyStore.getInstance(DEFAULT_TARGET_STORETYPE);
keyStore.load(null, null);
keyStore.setKeyEntry("cassandra-ssl-keystore", privateKey, keyPasswordArray, certChainArray);
return keyStore;
}
/**
* Builds KeyStore object given the {@link #DEFAULT_TARGET_STORETYPE} out of the PEM formatted certificates/public-key
* material.
* <p>
* It uses {@code cassandra-ssl-trusted-cert-<numeric-id>} as the alias for the created certificate-entry.
*/
private KeyStore buildTrustStore() throws GeneralSecurityException, IOException
{
Certificate[] certChainArray = PEMReader.extractCertificates(pemEncodedTrustCertificates.key);
if (certChainArray == null || certChainArray.length == 0)
{
throw new SSLException("Could not read any certificates from the given PEM");
}
KeyStore keyStore = KeyStore.getInstance(DEFAULT_TARGET_STORETYPE);
keyStore.load(null, null);
for (int i = 0; i < certChainArray.length; i++)
{
keyStore.setCertificateEntry("cassandra-ssl-trusted-cert-" + (i + 1), certChainArray[i]);
}
return keyStore;
}
/**
* Enforces that the configuration specified a sole source of loading private keys - either {@code keystore} (the
* actual file must exist) or {@code private_key}, not both.
*/
private void enforceSinglePrivateKeySource()
{
if (keystoreContext.hasKeystore() && !StringUtils.isEmpty(pemEncodedKeyContext.key))
{
throw new IllegalArgumentException("Configuration must specify value for either keystore or private_key, " +
"not both for PEMBasedSSlContextFactory");
}
if (outboundKeystoreContext.hasKeystore() && !StringUtils.isEmpty(pemEncodedOutboundKeyContext.key))
{
throw new IllegalArgumentException("Configuration must specify value for either outbound_keystore or outbound_private_key, " +
"not both for PEMBasedSSlContextFactory");
}
}
/**
* Enforces that the configuration specified a sole source of loading trusted certificates - either {@code
* truststore} (actual file must exist) or {@code trusted_certificates}, not both.
*/
private void enforceSingleTurstedCertificatesSource()
{
if (truststoreFileExists() && !StringUtils.isEmpty(pemEncodedTrustCertificates.key))
{
throw new IllegalArgumentException("Configuration must specify value for either truststore or " +
"trusted_certificates, not both for PEMBasedSSlContextFactory");
}
}
public static class PEMBasedKeyStoreContext
{
public String key;
public final String password;
public final boolean maybeFilebasedKey;
public final FileBasedStoreContext filebasedKeystoreContext;
public PEMBasedKeyStoreContext(final String encodedKey, final String getEncodedKeyPassword,
final boolean maybeFilebasedKey, final FileBasedStoreContext filebasedKeystoreContext)
{
this.key = encodedKey;
this.password = getEncodedKeyPassword;
this.maybeFilebasedKey = maybeFilebasedKey;
this.filebasedKeystoreContext = filebasedKeystoreContext;
}
public boolean hasKey()
{
return maybeFilebasedKey
? filebasedKeystoreContext.hasKeystore()
: !StringUtils.isEmpty(key);
}
}
public enum ConfigKey
{
ENCODED_KEY("private_key"),
KEY_PASSWORD("private_key_password"),
OUTBOUND_ENCODED_KEY("outbound_private_key"),
OUTBOUND_ENCODED_KEY_PASSWORD("outbound_private_key_password"),
ENCODED_CERTIFICATES("trusted_certificates");
final String keyName;
ConfigKey(String keyName)
{
this.keyName = keyName;
}
String getKeyName()
{
return keyName;
}
}
}