org.forgerock.openam.secrets

Class SecretsUtils

java.lang.Object

org.forgerock.openam.secrets.SecretsUtils

public class SecretsUtils
extends Object

Utility methods for dealing with secrets.

Since:

AM 6.5.0

Warning: Evolving API

This type (including all methods, constructors and fields) is continuing to evolve and so should be expected to change, potentially in backwards-incompatible ways even in a minor release. Changes are documented at the time of product release.

Constructor Summary

Constructors

Constructor and Description
SecretsUtils()

Method Summary

Modifier and Type	Method and Description
static Key	convertRawEncryptionKey(CryptoKey cryptoKey, JweAlgorithm jweAlgorithm, EncryptionMethod encryptionMethod) Converts symmetric encryption key that was created using the RAW algorithm to a more suitable key, but only if the key material is available.
static void	createKeyStorePurposeMapping(SecretIdRegistry secretIdRegistry, KeyStoreSecretStore keyStore, String purposeLabel, List<String> aliases, Optional<Realm> realm, SSOToken authorizationToken) Creates a global purpose and adds a mapping for it to the given key alias in the given keystore.
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.
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.
static FileSystemSecretStore	fileSystemSecretStore(String id, Path path, PropertyFormat propertyFormat) Create a FileSystemSecretStore ready to persist in the AnnotatedServiceRegistry.
static KeyStoreSecretStore	getDefaultKeyStore(AnnotatedServiceRegistry serviceRegistry) Gets the default keystore from the global scope.
static KeyStoreKeyIdProvider	getKeyStoreKeyIdProvider() Obtains a new instance of the configured keystore key ID provider implementation.
static String	getStaticId(KeyUse keyUse, String internalId, PublicKey key) Create the static ID for an asymmetric key secret by combining it's internal ID
static void	lockDownFilePermissions(Path file) Ensure that the given file is only readable by ourselves.
static PurposeMapping	purposeMapping(String label, List<String> aliases) Create a purpose mapping for the label and alias valid from the current time.
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.
static String	realmQualifiedPurposeLabel(String realm, String label) Creates a variant of the given purpose label that is qualified to the given realm.
static String	sanitisePurposeLabel(String label) Remove illegal characters from a purpose label.
static String	secretId(String secretIdFormat, String instanceName) Returns the secret ID formatted to include the sanitized instance name as well.
static void	writeSecretFile(Path secretsPath, String purposeLabel, byte[] content) Writes an encrypted password file to the given secret file location.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SecretsUtils

public SecretsUtils()

Method Detail

writeSecretFile

public static void 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.

Throws:

IOException - if the password file cannot be written or permissions cannot be set.

createKeyStorePurposeMapping

public static void createKeyStorePurposeMapping(SecretIdRegistry secretIdRegistry,
                                                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 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 SecretsUtils.encryptSecret(char[]) or SecretsUtils.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 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(KeyUse 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.