Package org.forgerock.secrets

Class SecretBuilder

  • public class SecretBuilder
extends Object
    Provides a uniform way for secrets providers to construct secrets and keys. All Secret subtypes should supply a one-argument constructor that takes an instance of this class. Secrets providers can then supply all relevant secret material and individual types of secrets can request the material that they need. For instance, a signature verification key would request only a public key, while the signing key would request the corresponding private key.

    • Constructor Detail

      • SecretBuilder

        public SecretBuilder()

    • Method Detail

      • clock

        public SecretBuilder clock​(Clock clock)
        Set the source of time for the default (relative) secret expiry time.
        Parameters:
        clock - The clock to use for obtaining expiry time.
        Returns:
        This builder.

      • stableId

        public SecretBuilder stableId​(String id)
        Sets the stable id of this secret.
        Parameters:
        id - the stable id of the secret.
        Returns:
        this builder object.

      • expiresAt

        public SecretBuilder expiresAt​(Instant expiry)
        Sets the secret to expire at the given time.
        Parameters:
        expiry - the expiry time of the secret.
        Returns:
        this builder object.

      • expiresIn

        public SecretBuilder expiresIn​(long deadline,
                               TemporalUnit unit,
                               Clock clock)
        Sets the secret to expire in deadline units from now.
        Parameters:
        deadline - the amount of time that this secret should be valid for.
        unit - the units of the deadline.
        clock - The clock to use for obtaining the expiry time.
        Returns:
        this builder object.

      • password

        public SecretBuilder password​(char[] password)
        Sets the raw data of this secret object to the UTF-8 bytes of the given password.
        Parameters:
        password - the password.
        Returns:
        this builder object.

      • rawData

        public SecretBuilder rawData​(byte[] rawData)
        Sets the raw data of the secret object. Typically only used for GenericSecrets.
        Parameters:
        rawData - the raw secret data.
        Returns:
        this builder object.

      • secretKey

        public SecretBuilder secretKey​(Key key)
        Sets the secret key for this object. This may be either a symmetric secret key or an asymmetric private key.
        Parameters:
        key - the key object.
        Returns:
        this builder object.

      • provider

        public SecretBuilder provider​(Provider provider)
        Sets the provider associated with this secret.
        Parameters:
        provider - the provider associated with this secret
        Returns:
        this builder object.

      • publicKey

        public SecretBuilder publicKey​(PublicKey key)
        Sets the public key associated with this secret.
        Parameters:
        key - the public key.
        Returns:
        this builder object.

      • certificate

        public SecretBuilder certificate​(Certificate certificate)
        Sets the certificate associated with this secret. The public key in the certificate should correspond to any private key associated with this secret. This method is equivalent to calling certificateChain(Certificate...) with the single certificate argument.
        Parameters:
        certificate - the certificate.
        Returns:
        this builder object.

      • certificateChain

        public SecretBuilder certificateChain​(List<? extends Certificate> chain)
        Sets the certificate chain associated with this secret. The first certificate in the chain (if the chain is not empty) should be the leaf certificate that corresponds to any private key associated with this secret.
        Parameters:
        chain - the certificate chain.
        Returns:
        this builder object.

      • certificateChain

        public SecretBuilder certificateChain​(Certificate... chain)
        Sets the certificate chain associated with this secret. The first certificate in the chain (if the chain is not empty) should be the leaf certificate that corresponds to any private key associated with this secret.
        Parameters:
        chain - the certificate chain.
        Returns:
        this builder object.

      • keyUsages

        public SecretBuilder keyUsages​(Set<KeyUsage> keyUsages)
        Sets the allowed key usages for this key. A null value is treated as allowing any key usage.
        Parameters:
        keyUsages - the allowed key usages.
        Returns:
        this builder object.

      • allowedAlgorithms

        public SecretBuilder allowedAlgorithms​(Predicate<String> allowedAlgorithmsTest)
        Sets the cryptographic algorithms that can be used with this key. The format and processing of algorithm names is unspecified.
        Parameters:
        allowedAlgorithmsTest - a predicate to test whether a given algorithm is allowed to be used with this key.
        Returns:
        this builder object.

      • allowedAlgorithms

        public SecretBuilder allowedAlgorithms​(Collection<String> allowedAlgorithms)
        Sets the cryptographic algorithms that can be used with this key. The format and processing of algorithm names is unspecified. Algorithms will be tested by calling the Collection.contains(Object) method on the supplied collection, so a case-insensitive comparison can be used by specifying a case-insensitive collection. It is recommended to use a case-insensitive collection unless case-sensitivity is mandatory for a particular set of algorithms. The collection is not copied, so the passed collection should not be modified after calling this method.

        It is recommended that this is populated with at least the following algorithm names as a default:

        • The Java Cryptography Architecture/Extensions standard name, such as SHA256WithRSA or AES/GCM/NoPadding
        • The JOSE/WebCrypto name, such as ES256 or A256KW. Note: in the case of JWE with a symmetric key that is intended for direct encryption (alg=dir it is recommended to also include the names of the relevant enc content encryption algorithms the key is intended to be used with, such as A256GCM or A128CBC-HS256.
        Parameters:
        allowedAlgorithms - the set of allowed algorithms that can be used with this key.
        Returns:
        this builder object.

      • combine

        public SecretBuilder combine​(SecretBuilder that)
        Returns a fresh SecretBuilder that combines the data from this secret builder and the argument. In most cases the first field that has a non-null value is chosen, where this SecretBuilder takes precedence over the argument SecretBuilder. For the key usage and allowed algorithm fields, the logical union of the two builders is returned so that the resulting secret can be used for any operation that a constituent secret could be used for. The minimum of the two expiry times is used as the combined expiry time.

        This method is primarily useful when combining the output of multiple SecretDecoder steps.

        Parameters:
        that - the other secret builder to combine with this one.
        Returns:
        a new secret builder that combines the fields of this secret builder with the supplied secret builder.

      • getAllowedKeyUsages

        public Set<KeyUsage> getAllowedKeyUsages()
        The allowed key usages of this key.
        Returns:
        the allowed key uses of this key.

      • getAllowedAlgorithms

        public Predicate<String> getAllowedAlgorithms()
        Returns a predicate that can be used to test whether a given algorithm can be used with this key. The default predicate always returns true for any input.
        Returns:
        the allowed algorithms predicate.

      • getStableId

        public String getStableId()
        Returns the stable id for this secret..
        Returns:
        the stable id for this secret.

      • getExpiry

        public Instant getExpiry()
        Returns the expiry time for this secret.
        Returns:
        the expiry time for this secret.

      • getRawData

        public byte[] getRawData()
                  throws NoSuchSecretException
        Returns the raw secret data, or null if the raw data is not available.
        Returns:
        the raw secret data, or null if the raw data is not available.
        Throws:
        NoSuchSecretException - if the raw secret cannot be extracted.

      • getSecretKey

        public Key getSecretKey()
                 throws NoSuchSecretException
        Returns the secret (or private) key associated with this secret, or null if not specified.
        Returns:
        the secret (or private) key associated with this secret, or null if not specified.
        Throws:
        NoSuchSecretException - if the secret cannot be extracted.

      • getPublicKey

        public PublicKey getPublicKey()
        Returns the public key associated with this secret, or null if not available.
        Returns:
        the public key associated with this secret, or null if not available.

      • getProvider

        public Provider getProvider()
        Returns the security provider associated with this secret, or null if not specified.
        Returns:
        the security provider associated with this secret, or null if not specified.

      • getCertificate

        public Certificate getCertificate()
        Returns the certificate associated with this secret, or null if not available. The public key associated with the certificate will be identical to that returned by getPublicKey().
        Returns:
        the certificate associated with this secret, or null if not available.

      • getCertificateChain

        public List<? extends Certificate> getCertificateChain()
        Returns the certificate chain associated with this secret, or an empty list if not available. If a certificate exists then the first certificate in the list will be the leaf certificate and identical to the result of getCertificate(). The returned list is unmodifiable.
        Returns:
        the certificate chain associated with this secret, or an empty list if not available.

      • build

        @Deprecated
public <T extends Secret> T build​(Class<T> secretType)
                           throws NoSuchSecretException
        Deprecated.
        Use build(Purpose) instead.
        Builds a secret of the given type.
        Type Parameters:
        T - the type of secret to build.
        Parameters:
        secretType - the type of secret to build.
        Returns:
        the constructed secret object.
        Throws:
        NoSuchSecretException - If the secret could not be built, or one of the secrets used to unlock this secret could not be obtained.

      • build

        public <T extends Secret> T build​(Purpose<T> purpose)
                           throws NoSuchSecretException
        Builds a secret of the given type, enforcing any constraints attached to the purpose.
        Type Parameters:
        T - the type of secret to build.
        Parameters:
        purpose - the purpose to build the secret for.
        Returns:
        the constructed secret object.
        Throws:
        NoSuchSecretException - If the secret could not be built, or one of the secrets used to unlock this secret could not be obtained, or if the secret does not satisfy the constraints attached to the purpose.

      • buildWithExpirer

        public <T extends Secret> SecretBuilder.SecretAndExpirer<T> buildWithExpirer​(Purpose<T> purpose)
                                                                      throws NoSuchSecretException
        Builds a secret of the given type, enforcing any constraints attached to the purpose. This method also returns an expirer which is a handle to set the secret as immediately expired.
        Type Parameters:
        T - the type of secret to build.
        Parameters:
        purpose - the purpose to build the secret for.
        Returns:
        the constructed secret object and its associated expirer.
        Throws:
        NoSuchSecretException - If the secret could not be built, or one of the secrets used to unlock this secret could not be obtained, or if the secret does not satisfy the constraints attached to the purpose.