Keys and secrets

PingGateway uses cryptographic keys for encryption, signing, and securing network connections, and passwords. The following sections describe how to secure keys and secrets in your deployment.

About secrets

PingGateway uses the Commons Secrets API to manage secrets, such as passwords and cryptographic keys.

Repositories of secrets are managed through secret stores, provided to the configuration by the SecretsProvider object or secrets object.

Learn more from:

Secret types

PingGateway uses the following secret types:

GenericSecret

An opaque blob of bytes, such as a password or API key, without any metadata.

A GenericSecret cannot be used to perform cryptographic operations.

CryptoKey

A secret that contains either a private or shared key, and/or a public certificate. A CryptoKey contains the secret material itself and its metadata; for example, the associated algorithm or key type.

This secret type can be used for cryptographic operations. For example:

A Base64EncodedSecretStore can only serve secrets of the GenericSecret type.
An HsmSecretStore can only server secrets of the CryptoKey type.
A FileSystemSecretStore can serve secrets of both types.

Secret terminology

PingGateway uses the following terms to describe secrets:

Secret ID

A label to indicate the purpose of a secret. A secret ID is generally associated with one or more aliases of a key in a keystore or HSM.

Stable ID

A label to identify a secret. The stable ID corresponds to the following values in each type of secret store:

Base64EncodedSecretStore: The value of secret-id in the "secret-id": "string" pair.
FileSystemSecretStore: The filename of a file in the specified directory, without the prefix/suffix defined in the store configuration.
HsmSecretStore: The value of an alias in a secret-id/aliases mapping.
JwkSetSecretStore: The value of the kid of a JWK stored in a JwkSetSecretStore.
KeyStoreSecretStore: The value of an alias in a secret-id/aliases mapping.
SystemAndEnvSecretStore: The name of a system property or environment. variable

Valid secret

A secret whose purpose matches the secret ID and any purpose constraints. Constraints can include requirements for the following:

Secret type, such as signing key or encryption key
Cryptographic algorithm, such as Diffie-Hellman and RSA
Signature algorithm, such as ES256 and ES384

Constraints are defined when the secret is generated, and cannot be added after.

Named secret

A valid secret that a secret store can find by using a secret ID and stable ID.

Active secret

A valid secrets that’s considered eligible at the time of use. The way that the active secret is chosen is determined by the type of secret store. For more information, refer to Secrets,

About keys and certificates

The examples in this documentation use self-signed certificates, but your deployment is likely to use certificates issued by a certificate authority (CA certificates).

The way to obtain CA certificates depends on the certificate authority that you are using, and is not described in this document. As an example, refer to Let’s Encrypt.

Integrate CA certificates by using secret stores:

For PEM files, use a FileSystemSecretStore and PemPropertyFormat
For PKCS12 keystores, use a KeyStoreSecretStore

For examples, refer to Serve the same certificate for TLS connections to all server names.

Note the following points about using secrets:

When PingGateway starts up, it listens for HTTPS connections, using the ServerTlsOptions configuration in admin.json. The keys and certificates are fetched at startup.
Keys and certificates must be present at startup.
If keys or certificates change, you must to restart PingGateway.
When the autoRefresh property of FileSystemSecretStore or KeyStoreSecretStore is enabled, the secret store is automatically reloaded when the filesystem or keystore is changed.

For information about secret stores provided in PingGateway, refer to Secrets.

Validate the signature of signed tokens

PingGateway validates the signature of signed tokens as described here.

Named secret resolution

If a JWT contains a kid, PingGateway queries the secret stores declared in secretsProvider or secrets to find a named secret, identified by a secret ID and stable ID.

If a named secret is found, PingGateway then uses the named secret to try to validate the signature. If the named secret can’t validate the signature, the token is considered as invalid.

If a named secret isn’t found, PingGateway tries valid secret resolution.

Valid secret resolution

PingGateway uses the value of verificationSecretId as the secret ID, and queries the declared secret stores to find all secrets that match the provided secret ID.

All matching secrets are returned as valid secrets, in the order that the secret stores are declared, and for KeyStoreSecretStore and HsmSecretStore, in the order defined by the mappings.

PingGateway tries to verify the signature with each valid secret, starting with the first valid secret, and stopping when it succeeds.

If no valid secrets are returned, or if none of the valid secrets can verify the signature, the token is considered as invalid.

For examples where a StatelessAccessTokenResolver uses a secret store to validate the signature of signed tokens, refer to the example sections of JwkSetSecretStore and KeyStoreSecretStore.

Algorithms for elliptic curve digital signatures

When the Elliptic Curve Digital Signature Algorithm (ECDSA) is used for signing, and both of the following conditions are met, JWTs are signed with a deterministic ECDSA:

Bouncy Castle is installed.
The system property org.forgerock.secrets.preferDeterministicEcdsa is true, which is its default value.

Otherwise, when ECDSA is used for signing, JWTs are signed with a non-deterministic ECDSA.

A non-deterministic ECDSA signature can be verified by the equivalent deterministic algorithm.

For information about deterministic ECDSA, refer to RFC 6979. For information about Bouncy Castle, refer to The Legion of the Bouncy Castle.

Update cryptography

Different algorithms and methods are discovered and tested over time, and communities of experts decide which are the most secure for different uses. Use up-to-date cryptographic methods and algorithms to generate keys.

Legacy keystore types such as JKS and JCEKS are supported but aren’t secure. Consider using the PKCS#12 keystore type.

Use strong keys

Small keys are easily compromised. Use at least the recommended key size.

In JVM, the default ephemeral Diffie-Hellman (DH) key size is 1024 bits. To support stronger ephemeral DH keys, and protect against weak keys, consider setting the following system property to increase the DH key size: jdk.tls.ephemeralDHKeySize=2048.

For more information, refer to Customizing size of ephemeral Diffie-Hellman keys

Rotate keys

Rotate keys regularly to:

Limit the amount of data protected by a single key.
Reduce dependence on specific keys, making it easier to migrate to stronger algorithms.
Prepare for when a key is compromised. The first time you try key rotation shouldn’t be during a real-time recovery.
Conform to internal business compliance requirements.

For more information, refer to Rotate keys.

PingGateway 2024.11