Key rotation

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

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.

Stop the web server.
View a list of Web Agents Documentation instances, using the agentadmin --l command.

Rotate the keys for a Web Agents Documentation 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.

Web Agents 2024.3

Key rotation

Considerations if key rotation fails