Class SecretsUtils

java.lang.Object
org.forgerock.openam.secrets.SecretsUtils

@EvolvingAll public class SecretsUtils extends Object
Utility methods for dealing with secrets.
Since:
AM 6.5.0
  • Constructor Details

    • SecretsUtils

      public SecretsUtils()
  • Method Details

    • writeSecretFile

      public static Path writeSecretFile(Path secretsPath, String purposeLabel, byte[] content) throws IOException
      Writes an encrypted password file to the given secret file location. The password will be encrypted using the AM encryption key and file permissions locked down to owner-read-only.
      Parameters:
      secretsPath - the path to the directory for storing secrets.
      purposeLabel - the purpose for this secret.
      content - the content to write.
      Returns:
      the Path of the secret file written by this method.
      Throws:
      IOException - if the password file cannot be written or permissions cannot be set.
    • createKeyStorePurposeMapping

      public static void createKeyStorePurposeMapping(org.forgerock.openam.secrets.config.SecretIdRegistry secretIdRegistry, org.forgerock.openam.secrets.config.KeyStoreSecretStore keyStore, String purposeLabel, List<String> aliases, Optional<Realm> realm, SSOToken authorizationToken) throws SMSException, SSOException
      Creates a global purpose and adds a mapping for it to the given key alias in the given keystore.
      Parameters:
      secretIdRegistry - the secret ID registry.
      keyStore - the keystore to add the mapping to.
      purposeLabel - the purpose to add the mapping for.
      aliases - the keystore alias list to map the purpose to.
      Throws:
      SMSException - if the global purpose cannot be read.
      SSOException - if a permission error occurs.
    • purposeMapping

      public static PurposeMapping purposeMapping(String label, List<String> aliases)
      Create a purpose mapping for the label and alias valid from the current time.
      Parameters:
      label - The label.
      aliases - The alias list.
      Returns:
      The mapping.
    • encryptSecret

      public static byte[] encryptSecret(char[] secret)
      Encrypt a secret ready to be stored in a file that will be read by a FileSystemSecretStore using the PropertyFormat.ENCRYPTED_PLAIN format.
      Parameters:
      secret - The secret.
      Returns:
      The bytes containing the encrypted, base64-encoded secret.
    • encodeAndEncryptSecret

      public static byte[] encodeAndEncryptSecret(byte[] secret)
      Encrypt a secret ready to be stored in a file that will be read by a FileSystemSecretStore using the PropertyFormat.ENCRYPTED_BASE64 and PropertyFormat.ENCRYPTED_HMAC_KEY formats.
      Parameters:
      secret - The secret.
      Returns:
      The bytes containing the encrypted, base64-encoded secret.
    • fileSystemSecretStore

      public static org.forgerock.openam.secrets.config.FileSystemSecretStore fileSystemSecretStore(String id, Path path, PropertyFormat propertyFormat)
      Create a FileSystemSecretStore ready to persist in the AnnotatedServiceRegistry. The store will use the provided property format, suitable for use with files created with encryptSecret(char[]) or encodeAndEncryptSecret(byte[]) depending on the property format.
      Parameters:
      id - The store ID.
      path - The path that files will be found in.
      propertyFormat - The format that the file is in.
      Returns:
      An instance of the interface.
    • realmQualifiedEncryptionPurpose

      public static Purpose<KeyEncryptionKey> realmQualifiedEncryptionPurpose(String realm, String rootPurpose)
      Returns the purpose to use at the global scope for looking up a realm-specific encryption key. The purpose label will be qualified by the realm name to allow different keys to be configured for each realm.
      Parameters:
      realm - the realm name (path).
      rootPurpose - the basic purpose, e.g. "PersistentCookieEncryption".
      Returns:
      the purpose to use for encryption in that realm.
    • realmQualifiedPurposeLabel

      public static String realmQualifiedPurposeLabel(String realm, String label)
      Creates a variant of the given purpose label that is qualified to the given realm.
      Parameters:
      realm - The realm.
      label - The original label.
      Returns:
      The realm-qualified label.
    • getDefaultKeyStore

      public static org.forgerock.openam.secrets.config.KeyStoreSecretStore getDefaultKeyStore(AnnotatedServiceRegistry serviceRegistry) throws SMSException, SSOException
      Gets the default keystore from the global scope.
      Parameters:
      serviceRegistry - the service registry.
      Returns:
      the default keystore.
      Throws:
      SMSException - if the configuration cannot be read.
      SSOException - if a permissions error occurs.
    • secretId

      public static String secretId(String secretIdFormat, String instanceName)
      Returns the secret ID formatted to include the sanitized instance name as well.
      Parameters:
      secretIdFormat - The string to format.
      instanceName - The instance name to be sanitized and included.
      Returns:
      The secret ID that is sanitized and includes the config instance's name.
    • sanitisePurposeLabel

      public static String sanitisePurposeLabel(String label)
      Remove illegal characters from a purpose label.
      Parameters:
      label - the label
      Returns:
      the sanitised label
    • lockDownFilePermissions

      public static void lockDownFilePermissions(Path file) throws IOException
      Ensure that the given file is only readable by ourselves.
      Parameters:
      file - the file to lockdown permissions for.
      Throws:
      IOException
    • getStaticId

      public static String getStaticId(String keyUse, String internalId, PublicKey key)
      Create the static ID for an asymmetric key secret by combining it's internal ID
      Parameters:
      keyUse - The usage for the secret that is represented.
      internalId - The internal ID of the secret, e.g. the alias in the keystore.
      key - The public key.
      Returns:
      The static ID.
    • getKeyStoreKeyIdProvider

      public static KeyStoreKeyIdProvider getKeyStoreKeyIdProvider()
      Obtains a new instance of the configured keystore key ID provider implementation.
      Returns:
      A new keystore key ID provider instance.
    • convertRawEncryptionKey

      public static Key convertRawEncryptionKey(CryptoKey cryptoKey, JweAlgorithm jweAlgorithm, EncryptionMethod encryptionMethod) throws NoSuchSecretException
      Converts symmetric encryption key that was created using the RAW algorithm to a more suitable key, but only if the key material is available. Asymmetric encryption keys are left unchanged. This is necessary, because AM by default creates RAW secret key entries in its keystore during installation, and the JDK's crypto implementation verifies that the key's algorithm matches with the encryption operation to be performed.
      Parameters:
      cryptoKey - The cryptographic key to be converted.
      jweAlgorithm - The encryption algorithm.
      encryptionMethod - The encryption method.
      Returns:
      Either the converted symmetric key instance, or the original asymmetric key.
      Throws:
      NoSuchSecretException - If the key could not be exported.