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.