--- title: PingGateway keys and secrets description: Manage cryptographic keys and secrets in PingGateway, including secret types, key validation, ECDSA signing algorithms, and key rotation component: pinggateway version: 2026 page_id: pinggateway:security-guide:keys canonical_url: https://docs.pingidentity.com/pinggateway/2026/security-guide/keys.html revdate: 2025-04-01T17:53:34Z keywords: ["Security", "Account", "Authorization", "Keys", "Cryptographic Keys", "Key Rotation"] section_ids: about-secrets: About secrets secret-types: Secret types secret-terminology: Secret terminology using-certs-in-examples: About keys and certificates secret-valid-signature: Validate the signature of signed tokens named-secret-resolution: Named secret resolution valid_secret_resolution: Valid secret resolution secret-signature-generation: Algorithms for elliptic curve digital signatures update-cryptography: Update cryptography use-strong-keys: Use strong keys rotate-keys: Rotate keys --- # PingGateway 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: * [PingGateway secrets](../reference/secrets.html) * [SecretsProvider](../reference/SecretsProvider.html) ### 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 [PingGateway secrets](../reference/secrets.html), ## 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](https://letsencrypt.org/getting-started.html). Integrate CA certificates by using secret stores: * For PEM files, use a [FileSystemSecretStore](../reference/FileSystemSecretStore.html) and [PemPropertyFormat](../reference/PemPropertyFormat.html) * For PKCS12 keystores, use a [KeyStoreSecretStore](../reference/KeyStoreSecretStore.html) For examples, refer to [Serve the same certificate for TLS connections to all server names](../installation-guide/envvar-sysprop.html#server-side-tls-keyManager). 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 [PingGateway secrets](../reference/secrets.html). ## 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](../reference/JwkSetSecretStore.html#JwkSetSecretStore-example) and [KeyStoreSecretStore](../reference/KeyStoreSecretStore.html#KeyStoreSecretStore-example). ## 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](https://www.rfc-editor.org/rfc/rfc6979). For information about Bouncy Castle, refer to [The Legion of the Bouncy Castle](https://www.bouncycastle.org). ## 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](https://wiki.mozilla.org/Security/Server_Side_TLS#Intermediate_compatibility_.28recommended.29). 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](https://docs.oracle.com/javase/8/docs/technotes/guides/security/jsse/JSSERefGuide.html#customizing_dh_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 [Rotating PingGateway encryption and signing keys](../maintenance-guide/rotate-keys.html).