Package org.forgerock.secrets.keys

Class CryptoKey

java.lang.Object
org.forgerock.secrets.Secret
org.forgerock.secrets.keys.CryptoKey
All Implemented Interfaces:
AutoCloseable
Direct Known Subclasses:
CertificateVerificationKey, DataDecryptionKey, DataEncryptionKey, KeyAgreementKey, KeyDecryptionKey, KeyEncryptionKey, SigningKey, VerificationKey
public abstract class CryptoKey extends Secret
Base class for all secrets that are used as keys for cryptographic operations. This class roughly corresponds to the CryptoKey interface in the WebCrypto standard.

  • Method Details

    • getKeyType

      public KeyType getKeyType()
      Returns an indication of the type of key this is.
      Returns:
      the type of key.

    • getKeyAlgorithm

      public String getKeyAlgorithm()
      Returns the algorithm used by the underlying key, for instance "RSA" or "EC".
      Returns:
      the key algorithm.

    • export

      public <T> T export(KeyFormat<T> format) throws NoSuchSecretException
      Exports the key material in the given format.
      Type Parameters:
      T - the type of result returned.
      Parameters:
      format - the format to export the key material in.
      Returns:
      the exported key material.
      Throws:
      NoSuchSecretException - if the secret could not be exported.

    • revealAndClose

      public <T> T revealAndClose(Function<Key,T> function)
      Reveals the secret temporarily and then scrubs the secret material from memory.
      Type Parameters:
      T - the type of object returned by the consumer.
      Parameters:
      function - the consumer function to reveal the secret to.
      Returns:
      the result of the consumer function.
      See Also:

    • reveal

      public <T> T reveal(Function<Key,T> function)
      Reveals the secret's Key temporarily, allowing it to be used for its intended purpose. Note that the consumer should not make any assumptions about the availability of the key after the function returns. They may be cleared or destroyed. The CryptoKey object is not destroyed by this method and so can be reused. Use revealAndClose(Function) to also close the CryptoKey itself after the method completes.
      Type Parameters:
      T - the type of object returned by the consumer.
      Parameters:
      function - the consumer function to reveal the key to.
      Returns:
      the result of the consumer function.

    • getCertificate

      public <T extends Certificate> Optional<T> getCertificate(Class<T> certificateType)
      Returns the certificate of the given type if one is available. This is the first certificate in the certificate chain if one exists and the certificate is of the correct type.
      Type Parameters:
      T - the type of certificate.
      Parameters:
      certificateType - the type of certificate to get.
      Returns:
      the certificate of the given type, or empty if none available.

    • getCertificate

      public Optional<Certificate> getCertificate()
      Returns any certificate associated with this key. This is the first certificate in the certificate chain if one exists.
      Returns:
      the certificate associated with this key, if one is available.

    • getCertificateChain

      public List<? extends Certificate> getCertificateChain()
      Gets the certificate chain associated with this secret. If non-empty then the first certificate in the chain is always identical to the result of getCertificate().
      Returns:
      the certificate chain associated with this secret, or an empty list if not available.

    • getCertificateChain

      public <T extends Certificate> List<T> getCertificateChain(Class<T> certificateType)
      Gets the certificate chain associated with this secret as a list of the given certificate type. If any certificate in the chain is not of the required type then an empty result is returned. If the result is non-empty then the first certificate will be identical to the result of getCertificate().
      Type Parameters:
      T - The generic type of certificates.
      Parameters:
      certificateType - The type of certificates expected.
      Returns:
      the certificate chain associated with this secret, or empty if not available or if all certificates in the chain are not of the given type.

    • getPublicKey

      public <T extends PublicKey> Optional<T> getPublicKey(Class<T> keyType)
      Returns the public key associated with this secret, if one is available. Note that if a public key has not been directly associated with this key then currently no attempt is made to derive it from any secret key material.
      Type Parameters:
      T - the type of public key.
      Parameters:
      keyType - the type of public key to return.
      Returns:
      the public key, if available.

    • getPublicKey

      public Optional<PublicKey> getPublicKey()
      Returns the public key associated with this secret, if one is available. Note that if a public key has not been directly associated with this key then currently no attempt is made to derive it from any secret key material.
      Returns:
      the public key, if available.

    • getKeyUsages

      public Set<KeyUsage> getKeyUsages()
      Returns the key usages that the key can be used for.
      Returns:
      the set of key usages that are allowed for this key.

    • allowsAlgorithm

      public boolean allowsAlgorithm(String algorithm)
      Checks whether this key is allowed to be used with the given algorithm. The algorithm name is application-specific, such as a JWS signing algorithm (e.g., ES256) or a Java Cipher algorithm name (e.g., RSA/ECB/PKCS1Padding).
      Parameters:
      algorithm - the algorithm to check if this key can be used with.
      Returns:
      true if the algorithm is allowed to be used with this key.

    • isExtractable

      public boolean isExtractable()
      Indicates whether the raw key material can be extracted for this key. Note that some aspects of the key may still be exported even if the key itself is not extractable, for instance a public certificate. The main reason why a key is not extractable is because it is stored in secure storage such as a Hardware Security Module (HSM) or on a remote server.
      Returns:
      whether the raw key material can be extracted or not.

    • close

      public void close()
      Marks this CryptoKey as closed, without relinquishing any underlying resources. This method is invoked automatically on objects managed by the try-with-resources statement.

      In this implementation the resource is marked as closed, allowing calling code to determine the state using the method isClosed() thereby maintaining the original API contract.

      In the original design this method called Destroyable.destroy(), if applicable, on the underlying key. This feature of closing secrets has been removed to avoid synchronization issues where the Secret may be accessed by multiple threads.

      In a future release it is anticipated that Secret will no longer implement AutoCloseable and therefore this method will be deprecated.

      Specified by:
      close in interface AutoCloseable
      Overrides:
      close in class Secret

    • isClosed

      public boolean isClosed()
      Description copied from class: Secret
      Indicates whether this secret has been closed by calling the Secret.close() method. A secret that has been closed should be considered invalid and re-fetched from the SecretsProvider.
      Overrides:
      isClosed in class Secret
      Returns:
      true if the secret has been closed.

    • toBuilder

      public SecretBuilder toBuilder()
      Converts the key back into a SecretBuilder, pre-initialized with the fields of this CryptoKey object.
      Returns:
      a SecretBuilder that can be used to build a copy of this key.

    • toString

      public String toString()
      Overrides:
      toString in class Secret