Web Agents 2024.11

Rotate keys

Key rotation is the process of generating a new version of a key, assigning that version, and then deprovisioning the old key.

Why and when to rotate keys

Regular key rotation is a security consideration that is sometimes required for internal business compliance. Regularly rotate keys 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.

Key revocation is a type of key rotation done exceptionally if you suspect that a key has been compromised. To decide when to revoke a key, consider the following points:

  • If limited use of the old keys can be tolerated, provision the new keys and then deprovision the old keys. Messages produced before the new keys are provisioned are impacted.

  • If use of the old keys can’t be tolerated, deprovision the old keys before you provision the new keys. The system is unusable until new keys are provisioned.

Steps for rotating keys

  1. Stop the web server.

  2. View a list of Web Agent instances, using the agentadmin --l command.

  3. Rotate the keys for a Web Agent instance, using the agentadmin --k --rotate agent-instance command.

    The following example rotates keys for the instance agent_3:

    • Unix

    • Windows

    $ cd /path/to/web_agents/apache24_agent/bin/
$ ./agentadmin --k --rotate agent_3

Performing key rotation for instance: agent_3

Instance config directory: /path/to/web_agents/apache24_agent/instances/agent_3
Loading agent.conf…​done
Loading current credentials…​done
Generating new encryption key…​done
Encrypting current credentials with new encryption key:
	- Encrypting agent profile password with new key…​done
	- Encrypting certificate password with new key…​done
	- Encrypting http proxy password with new key…​done
Performing file operations:
Gathering file information for agent-key.conf
Gathering file information for agent-password.conf
Backing up key file to agent-key.conf.bak
Backing up password file to agent-password.conf.bak
Writing new key to agent-key.conf…​done
Writing new ciphertexts to agent-password.conf…​done
Successfully wrote new key and passwords to disk

Removing backup agent-key.conf.bak…​done
Removing backup agent-password.conf.bak…​done

Key rotation was successful for instance: agent_3
    C:\> cd web_agents\iis_agent\bin
C:\web_agents\iis_agent\bin> agentadmin.exe --k --rotate agent_3

Performing key rotation for instance: agent_3

Instance config directory: …​
Loading agent.conf…​done
Loading current credentials…​done
Generating new encryption key…​done
Encrypting current credentials with new encryption key:
	- Encrypting agent profile password with new key…​done
	- Encrypting certificate password with new key…​done
	- Encrypting http proxy password with new key…​done
Backing up key file to agent-key.conf.bak
Backing up password file to agent-password.conf.bak
Writing new key to agent-key.conf…​done
Writing new ciphertexts to agent-password.conf…​done
Successfully wrote new key and passwords to disk

Removing backup agent-key.conf.bak…​done
Removing backup agent-password.conf.bak…​done

Key rotation was successful for instance: agent_3

Considerations if key rotation fails

  • If key rotation fails while the agent is updating agent-password.conf or agent-key.conf, the rotate command tries to revert to the original files.

  • If the rotate command can’t revert to the original files, manually move agent-password.conf.bak and agent-key.conf.bak to agent-password.conf and agent-key.conf.

  • After a failed key rotation on Windows, look for and delete .bak files. Windows can’t rename a file as .bak if a .bak file already exists.

Copyright © 2010-2024 ForgeRock, all rights reserved.