---
title: Keys and secrets
description: Java Agent uses cryptographic keys for encryption, signing, and securing network connections, and passwords. The following sections discuss how to secure keys and secrets in your deployment.
component: java-agents
version: 2025.11
page_id: java-agents:security-guide:keys
canonical_url: https://docs.pingidentity.com/java-agents/2025.11/security-guide/keys.html
section_ids:
  use-strong-keys: Use strong keys
  rotate-keys: Create and rotate keys
  rotate-encryption-keys: Rotate the agent profile password
  create-cookie-signing-keys: Create a cookie signing key
  change-cookie-signing-keys: Rotate cookie signing keys
---

# Keys and secrets

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

## 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, installations in Tomcat 8.5.37 and later versions use the Tomcat default DH key size of 2048-bit.

Increase the DH key size to protect against weak keys. 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)

## Create and 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.

### Rotate the agent profile password

During installation, the agent requests the path to a file containing the agent profile password. The agent then uses the following properties to encrypt and store the password:

* `am.encryption.pwd` in the [AgentKey.properties](../user-guide/about.html#agentkey-properties) file

* `Encrypted Agent Password` in the [AgentPassword.properties](../user-guide/about.html#agentPassword-properties) file

If the path is empty, the installation terminates with a configuration error.

The following steps describe how to rotate the agent profile password:

1. Change the profile password for your agent instance. For example, in the AM admin UI, change the password as follows:

   1. Select Realms > *Realm Name* > Applications > Agents > Java.

   2. Select your agent.

   3. In the Global tab, enter a new password in the Password field.

2. Generate an encryption key for the agent profile password, using the [agentadmin --getEncryptKey](../installation-guide/agentadmin.html#agentadmin-getEncryptKey) command:

   ```bash
   $ agentadmin --getEncryptKey
   ```

3. In [AgentKey.properties](../user-guide/about.html#agentkey-properties), set the value of `am.encryption.pwd` to the new value.

4. Encrypt the agent profile password, using the [agentadmin --encrypt](../installation-guide/agentadmin.html#agentadmin-encrypt) command:

   ```bash
   $ agentadmin --encrypt agent-instance password-file
   ```

   The agent encrypts the password by using the value of `Encryption Key/Salt` from [AgentKey.properties](../user-guide/about.html#agentkey-properties).

5. In [AgentKey.properties](../user-guide/about.html#agentkey-properties), set the value of `Encrypted Agent Password` to the new value.

6. Restart the agent instance.

### Create a cookie signing key

During installation, the agent requests the path to a file containing the cookie signing key, and then uses the key to configure the property `org.forgerock.agents.cookie.signing.value` in [AgentKey.properties](../user-guide/about.html#agentkey-properties). If the path is empty, cookie signing is disabled.

The key must be at least 64 characters long. If it is shorter, the agent rejects it and leaves cookies unsigned. For security, use a key of at least 80 characters.

1. Generate an 80-character key, using the [agentadmin --key](../installation-guide/agentadmin.html#agentadmin-key) command:

   * Unix

   * Windows

   ```
   $ agentadmin --key 80
   ZRY...xXO
   ```

   ```
   C:> agentadmin --key 80
   ZRY...xXO
   ```

### Rotate cookie signing keys

1. [Create a cookie signing key](#create-cookie-signing-keys).

2. In [AgentKey.properties](../user-guide/about.html#agentkey-properties), set the value of [org.forgerock.agents.cookie.signing.value](../properties-reference/org.forgerock.agents.cookie.signing.value.html) to the key value.

3. Restart the agent instance.