Package org.forgerock.secrets

Class Purpose<T extends Secret>

  • Type Parameters:
    T - the type of secret that this purpose requires.
    public final class Purpose<T extends Secret>
extends Object
    A purpose encapsulates both a name for a function that requires access to secrets, together with a hint as to the intended usage of those secrets. A purpose by itself may not uniquely identify a particular secret, as the secret for that purpose may change over time. A collection of general purposes are exposed by this class, but application developers are encouraged to create specific purpose instances that better describe the usage of a secret or key.

    • Field Detail

      • LABEL_PATTERN

        public static final Pattern LABEL_PATTERN
        The regular expression to use when validating purpose labels.

      • SIGN

        public static final Purpose<SigningKey> SIGN
        Indicates a key intended for creating digital signatures or message authentication codes (MACs).

      • VERIFY

        public static final Purpose<VerificationKey> VERIFY
        Indicates a key intended for verifying digital signatures or message authentication codes.

      • DATA_ENCRYPTION

        public static final Purpose<DataEncryptionKey> DATA_ENCRYPTION
        Indicates a key intended for encrypting data.

      • DATA_DECRYPTION

        public static final Purpose<DataDecryptionKey> DATA_DECRYPTION
        Indicates a key intended for decrypting data.

      • KEY_ENCRYPTION

        public static final Purpose<KeyEncryptionKey> KEY_ENCRYPTION
        Indicates a key intended for encrypting ("wrapping") other keys. Often used to encrypt a temporary symmetric session key with a public key.

      • KEY_DECRYPTION

        public static final Purpose<KeyDecryptionKey> KEY_DECRYPTION
        Indicates a key intended for decrypting ("unwrapping") other keys.

      • KEY_AGREEMENT

        public static final Purpose<KeyAgreementKey> KEY_AGREEMENT
        Indicates a key intended for an interactive key agreement protocol, such as Diffie-Hellman (DH) or the elliptic curve equivalent (ECDH). Note that the agreed key should not be used directly, but typically passed through some key derivation process.

      • PASSWORD

        public static final Purpose<GenericSecret> PASSWORD
        Indicates a secret intended to be used as a password for authentication to some service.

    • Method Detail

      • purpose

        @SafeVarargs
public static <T extends Secret> Purpose<T> purpose​(String label,
                                                    Class<T> type,
                                                    SecretConstraint<? super T>... constraints)
        Constructs a purpose object.
        Type Parameters:
        T - the type of secret.
        Parameters:
        label - the symbolic label to identify this purpose. Must consist only of alphanumeric and dot characters.
        type - the type of secret that this purpose requires.
        constraints - constraints on the secrets that can be used for this purpose.
        Returns:
        the purpose object.

      • purpose

        public static <T extends Secret> Purpose<T> purpose​(String label,
                                                    Class<T> type)
        Constructs a purpose object.
        Type Parameters:
        T - the type of secret.
        Parameters:
        label - the symbolic label to identify this purpose. Must consist only of alphanumeric and dot characters.
        type - the type of secret that this purpose requires.
        Returns:
        the purpose object.

      • getSecretType

        public Class<T> getSecretType()
        Returns the type of secrets that this purpose requires.
        Returns:
        the type of secrets.

      • getLabel

        public String getLabel()
        Returns a symbolic label for this purpose that can be used in routing requests for secrets.
        Returns:
        the symbolic label for this purpose.

      • getConstraints

        public Set<SecretConstraint<? super T>> getConstraints()
        Returns the set of constraints that should apply to any secrets that match this purpose.
        Returns:
        the set of constraints to apply for this purpose.

      • withConstraints

        @SafeVarargs
public final Purpose<T> withConstraints​(SecretConstraint<? super T>... constraints)
        Constructs a new purpose that is identical to this purpose but which imposes additional constraints on the secrets that can satisfy it.
        Parameters:
        constraints - the additional constraints to apply.
        Returns:
        a new purpose with the additional constraints applied.

      • isSatisfiedBy

        public boolean isSatisfiedBy​(T secret)
        Determines whether all of the constraints for this purpose are satisfied by the given secret.
        Parameters:
        secret - the secret.
        Returns:
        true if the secret satisfies all constraints for this purpose.

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class Object