Package org.forgerock.opendj.security

Class DeploymentKey

  • public final class DeploymentKey
extends Object
    A deployment key is a string protected by a password from which a root CA key-pair can be derived. It is meant to facilitate bootstrapping of public key infrastructure to secure server-to-server and client-to-server communication within a deployment. It allows to easily distribute a root CA certificate and CA-signed SSL key-pairs to all the deployment applications. It also makes SSL key-pair rotation easier.
    The typical workflow to secure a deployment with a deployment key is as follows:
    1. Generate a new deployment key with generateDeploymentKey(char[]) and store the key as returned by toString() in a secure place.
    2. For each deployment application:
    3. Repeat when the deployment root CA is about to expire.

    • Field Detail

      • DEFAULT_CA_CERT_VALIDITY

        public static final Duration DEFAULT_CA_CERT_VALIDITY
        The default root CA certificate validity duration.

      • DEFAULT_SSL_CERT_VALIDITY

        public static final Duration DEFAULT_SSL_CERT_VALIDITY
        The default SSL certificate validity duration.

      • DEFAULT_CA_ALIAS

        public static final String DEFAULT_CA_ALIAS
        The default alias for a deployment-key-generated CA certificate.
        See Also:
        Constant Field Values

      • DEFAULT_SSL_KEY_PAIR_ALIAS

        public static final String DEFAULT_SSL_KEY_PAIR_ALIAS
        The default alias for a deployment-key-generated SSL key-pair.
        See Also:
        Constant Field Values

      • DEFAULT_MASTER_KEY_PAIR_ALIAS

        public static final String DEFAULT_MASTER_KEY_PAIR_ALIAS
        The default alias for the master key pair.
        See Also:
        Constant Field Values

      • MIN_DEPLOYMENT_KEY_VALIDITY

        public static final Duration MIN_DEPLOYMENT_KEY_VALIDITY
        The minimum deployment key validity duration.

      • MAX_DEPLOYMENT_KEY_VALIDITY

        public static final Duration MAX_DEPLOYMENT_KEY_VALIDITY
        The maximum deployment key validity duration, approximately 90 years.

    • Method Detail

      • generateDeploymentKey

        public static DeploymentKey generateDeploymentKey​(char[] password)
        Generates a new deployment key whose root CA certificate will be valid from now for ten years.
        Parameters:
        password - An arbitrary password that will be used to protect this deployment key.
        Returns:
        A new deployment key.

      • generateDeploymentKey

        public static DeploymentKey generateDeploymentKey​(char[] password,
                                                  Instant notBefore,
                                                  Duration validity)
        Generates a new deployment key whose root CA certificate will be valid from notBefore for the provided duration rounded down to days. validity must be in range [MIN_DEPLOYMENT_KEY_VALIDITY, MAX_DEPLOYMENT_KEY_VALIDITY] inclusive.
        Parameters:
        password - An arbitrary password that will be used to protect this deployment key.
        notBefore - The date from which the root CA certificate associated with this deployment key will be valid.
        validity - The duration for which the root CA certificate associated with this deployment key will be valid.
        Returns:
        A new deployment key.
        Throws:
        IllegalArgumentException - If validity is outside the range of acceptable values.

      • valueOf

        public static DeploymentKey valueOf​(String deploymentKey,
                                    char[] password)
                             throws DecodeException,
                                    NoSuchProviderException
        Parses the provided deployment key and creates the associated root CA key-pair.
        Parameters:
        deploymentKey - The deployment key to be parsed.
        password - The deployment key password.
        Returns:
        The deployment key.
        Throws:
        DecodeException - If the combination of deployment key and password is invalid.
        NoSuchProviderException - If the key-pair generator implementation associated with the deployment key is not available on this JRE. This can happen when the deployment key is generated on one JRE implementation and parsed on another.

      • toString

        public String toString()
        Returns the string representation of this deployment key, it can be reused to re-create the same deployment key instance with valueOf(String, char[]). The string representation only contains URL safe characters. The key returned by this method is a sensitive piece of information because, when used in combination with the deployment key password, it allows to recreate at will the deployment root CA key-pair, therefore care must be taken when storing this key.
        Overrides:
        toString in class Object
        Returns:
        The string representation of this deployment key.

      • getRootCaCertificate

        public X509Certificate getRootCaCertificate()
        Returns the self-signed CA certificate associated with this deployment key. It can be used as the trusted CA certificate within a deployment.
        Returns:
        This deployment key root CA certificate.

      • generateSslKeyPair

        public Pair<PrivateKey,​X509Certificate> generateSslKeyPair​(Dn subjectDn,
                                                                 Collection<String> dnsNames)
                                                          throws LocalizedIllegalArgumentException
        Generates an SSL private key and an SSL certificate signed by the root CA certificate associated with this deployment key. The SSL certificate will be valid for one year from the generation date. The DNS names will appear in the certificate subject alternative names extension. The SSL key-pair can be used by a client or a server application hence is suitable for implementing mutual TLS.
        Parameters:
        subjectDn - The SSL certificate subject DN.
        dnsNames - The DNS names, must not be empty.
        Returns:
        The generated SSL key-pair.
        Throws:
        LocalizedIllegalArgumentException - If at least one of the provided DNS names is not valid.

      • generateSslKeyPair

        public Pair<PrivateKey,​X509Certificate> generateSslKeyPair​(Dn subjectDn,
                                                                 Collection<String> dnsNames,
                                                                 Instant notBefore,
                                                                 Duration validity)
                                                          throws LocalizedIllegalArgumentException
        Generates an SSL private key and an SSL certificate signed by the root CA certificate associated with this deployment key. The SSL certificate will be valid from notBefore for the provided duration rounded down to seconds. The provided DNS names will appear in the certificate subject alternative names extension. The SSL key-pair can be used by a client or a server application hence is suitable for implementing mutual TLS.
        Parameters:
        subjectDn - The SSL certificate subject DN.
        dnsNames - The DNS names, must not be empty.
        notBefore - The date from which the SSL certificate will be valid.
        validity - The duration for which the SSL certificate will be valid.
        Returns:
        The generated SSL key-pair.
        Throws:
        LocalizedIllegalArgumentException - If at least one of the provided DNS names is not valid.

      • getMasterKeyPair

        public Pair<PrivateKey,​X509Certificate> getMasterKeyPair()
        Returns the master public/private key-pair associated with this deployment key. The master key-pair will be the same on all instances in the deployment. It will ONLY be used for encrypting secrets such as symmetric keys stored in the crypto manager. Specifically, this key-pair WILL NOT be used for securing TLS connections.

        NOTE: The KeyStore API requires that the public key be encoded as an X509 certificate. The certificate details do not matter since it is not used for signing or validation. We're only interested in the public key.

        Returns:
        The generated master key-pair.

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class Object