Automation Configuration Encryption

Online (KMIP)

Online mode is best for environments with KMIP infrastructure. The master key resides in an external KMIP-compatible HSM and never touches disk. A separate bootstrap key secures the KMIP certificate credentials locally, enabling unattended restarts.

To use online mode, set encryptionMethod to ONLINE_KMS and provide your KMIP server details.

{
  "configEncryption": {
    "encryptionMethod": "ONLINE_KMS",
    "kmip": {
      "serverName": "<hostname>",
      "port": 5696,
      "serverCAFile": "<path-unix>",
      "serverCAFileWindows": "<path-windows>",
      "clientCertificateFile": "<path-unix>",
      "clientCertificateFileWindows": "<path-windows>",
      "clientCertificatePassword": "<password>",
      "keyIdentifier": "<optional-uuid>",
      "useLegacyProtocol": false
    }
  }
}

Offline

Offline mode is best for air-gapped or standalone environments. The agent derives an encryption key from a customer-provided UUID combined with physical machine parameters. This method requires no external dependencies.

To use offline mode, set encryptionMethod to OFFLINE_SOFTWARE and provide the following parameter:

{
  "configEncryption": {
    "encryptionMethod": "OFFLINE_SOFTWARE",
    "dynamicSalt": "<UUID>"
  }
}

Default

If Encryption at Rest (security.enableEncryption) is enabled for any process in the deployment, offline encryption activates automatically without requiring explicit configuration. Otherwise, the configuration remains unencrypted.

Via the Ops Manager UI

Configure encryption at the project level in Ops Manager.

Via the Public API

You can manage automation config encryption through the Ops Manager automation config endpoint.

Endpoint: PUT /groups/{PROJECT-ID}/automationConfig

Include the configEncryption object in the automation config request body. To learn more about the full request and response, see Update the Automation Configuration.

You must have the Project Automation Admin role to use this endpoint.

{
  "configEncryption": {
    "encryptionMethod": "ONLINE_KMS",
    "kmip": {
      "serverName": "kmip.example.com",
      "serverCAFile": "/path/to/ca.pem",
      "clientCertificateFile": "/path/to/client.pem"
    }
  }
}

{
  "configEncryption": {
    "encryptionMethod": "OFFLINE_SOFTWARE",
    "dynamicSalt": "<UUID>"
  }
}

Disable Encryption

To disable automation config encryption, set the encryption method to Default.

Manual Rotation

To manually rotate encryption keys, use the following triggers:

Automatic Rotation

The agent automatically rotates encryption keys when:

• The agent process restarts.

• The agent version changes (upgrade or downgrade).

When to Rotate

Rotate keys in the following situations:

• Suspected key compromise

• Scheduled rotation per your organization's security policy

• Personnel changes involving infrastructure access

Cryptographic Algorithms

The following table lists the cryptographic algorithms used at each stage of the encryption process.

Security Properties

The automation config encryption system provides the following security guarantees.

• Online mode bootstrap: A separate locally wrapped key protects the KMIP certificate credentials stored in the config. This enables the agent to authenticate to your KMIP server during unattended restarts without storing plaintext secrets on disk.

• Atomic writes: The agent writes configuration and key files using a crash-safe atomic pattern. The agent can fully recover from a failure at any point during the write.

• No plaintext secrets on disk: When you enable encryption, the agent replaces all credential fields in the backup file with encrypted values. The master.key file contains only wrapped (encrypted) keys.

Security Best Practices

Follow these recommendations to strengthen your automation config encryption deployment.

• Prefer Online (KMIP) when KMIP infrastructure is available. It provides the strongest security.

• Use KMIP 1.2 (default) over the legacy protocol. The master key never leaves the HSM.

• Rotate keys regularly per your organization's policy.

• Restrict filesystem access to the agent's config directory.

• Ensure Ops Manager connectivity before hardware changes or VM migrations in Offline mode. The agent recovers automatically by fetching fresh configuration on the next successful poll.

Common Issues

The following table lists common symptoms, their likely causes, and resolution steps.

Forced Recovery

If the agent cannot decrypt its local backup and Ops Manager is reachable, you can reset the encryption state.

To disable encryption as part of recovery, see Disable Encryption.

Log Tags

The following log tags identify encryption-related events in the agent logs.