Java Agents 2023.11.1

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.

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

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:

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 command:

    $ agentadmin --getEncryptKey

  3. In AgentKey.properties, set the value of am.encryption.pwd to the new value.

  4. Encrypt the agent profile password, using the agentadmin --encrypt command:

    $ agentadmin --encrypt agent-instance password-file

    The agent encrypts the password by using the value of Encryption Key/Salt from AgentKey.properties.

  5. In AgentKey.properties, set the value of Encrypted Agent Password to the new value.

  6. Restart the agent instance.

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. 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 command:

    • Unix

    • Windows

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

  1. Create a cookie signing key.

  2. In AgentKey.properties, set the value of org.forgerock.agents.cookie.signing.value to the key value.

  3. Restart the agent instance.