Integrating with secrets management services

As of server version 6.4, Aerospike Database Enterprise Edition can fetch sensitive configurations from secrets management services, using an intermediate process called Secret Agent. The agent acts as a proxy between Aerospike server and one or more external secrets management services, such as AWS Secrets Manager.

Secret Agent can be deployed on the same host where the Aerospike cluster node is running, or on a different host. To learn more, refer to the Secret Agent reference page. While multiple Aerospike servers can use a single Secret Agent process, we recommend avoiding a single point of failure by running a Secret Agent process locally with each Aerospike cluster node.

Aerospike Secret Agent integrates with AWS Secrets Manager, GCP Secrets Manager and Hashicorp Vault Secrets Manager. Additional services will be added in the future, independently of server releases.

Encoding Secrets

The Aerospike server expects a fetched secret value in base64 encoded format. If secrets in the external secret management service are saved as plain text then set the Secret Agent's configuration parameter convert-to-base64 to true to return all the fetched secrets in base64 encoded format.

Users may want to save secrets in base64-encoded format to avoid potential non-printable and control characters.

danger

Embedding non-trailing whitespace in base64-encoded secrets is not supported. For instance, when using base64 command-line utility, do base64 -w0 to prevent the default line break every 76 characters.

danger

For AWS Secret Manager, multi-line secret values (like tls certificates) should be stored in base64 encoded format only. This is not necessary when using GCP Secret Manager. For GCP Secret Manager, secret values can be stored as plain text and use Secret Agent's configuration parameter convert-to-base64.

Connecting to Aerospike Secret Agent

Aerospike Secret Agent acts as a proxy layer between Aerospike server and one or more external secrets management services, fetching secrets on behalf of the server.

Aerospike server can communicate with Secret Agent with the following connection methods:

1. TCP connection (plain or TLS)
2. Unix Domain Socket (UDS)

note

Both TCP and UDS cannot be configured at the same time in an Aerospike server configuration.

Using a TCP connection

For a plain TCP connection, set the Secret Agent's IP address and port in the secrets-address-port configuration parameter.

service {
  ...   
  secrets-address-port 127.0.0.1 3005
  ...
}

Configuring TLS

To use TLS over a TCP connection:

1. In the network context, create a TLS sub-context with a ca-file or ca-path specified. If mutual authentication is needed between the Aerospike server and the Secret Agent then additionally add cert-file and key-file configuration parameters along with ca-file or ca-path in the TLS sub-context.

2. Add a third parameter in secrets-address-port, which is used as the TLS name. The TLS name should be either the common name or one of the Subject Alternate Names (SAN) in the TLS certificate.

3. Configure secrets-tls-context, and specify the TLS sub-context name.

All the other configuration parameters (including protocols and cipher-suite) allowed in the TLS sub-context are honored.

Sample Aerospike configuration file for one way authentication (Aerospike Server authenticates Secret Agent).

service {
  ...
  secrets-address-port 127.0.0.1 3005 secretagent #'secretagent' is a TLS name.
  secrets-tls-context secrets-tls
  ...
}

network {  
  ... 
  tls secrets-tls {
      ca-file /path/to/ca-file.pem
  }
  ...
}

Sample Aerospike configuration file for mutual authentication between Aerospike Server and Secret Agent.

service {
  ...
  secrets-address-port 127.0.0.1 3005 secretagent #'secretagent' is a TLS name.
  secrets-tls-context secrets-tls
  ...
}

network {  
  ... 
  tls secrets-tls {
      cert-file /path/to/cert-file.pem
      key-file /path/to/key-file.pem
      ca-file /path/to/ca-file.pem     
  }
  ...
}

Using a Unix Domain Socket (UDS)

Unix Domain Sockets (UDS) enable inter-process communication (IPC) between processes running on the same host with less overhead than network protocols, using file system paths instead of network addresses.

UDS Considerations:

• Aerospike server and Secret Agent should run on the same host, with the same user and group ownership for both processes.

• The same UDS path should be provided in both Aerospike server and Secret Agent's configuration file.

• The socket file which used for communication between Aerospike Server and Secret Agent is created with 660 file permissions (read/write access for owner and group) when Secret Agent starts.

service {
  ...  
  secrets-uds-path /path/to/uds.sock
  ...
}

Supported configuration parameters

The following configuration parameter values can be fetched from an external secret manager:

• auth-password-file
• cert-file
• encryption-key-file
• encryption-old-key-file
• feature-key-file
• key-file
• key-file-password
• query-user-password-file

note

The ca-file parameter cannot be fetched from the external secret manager.

To fetch secret values for the supported configuration parameters from the external secret manager like AWS, GCP and Hashicorp Vault, a user must specify that configuration value in secrets:[resource:]key format.

1. secrets:- A required prefix. It indicates that the configuration parameter value will be fetched from the external secret manager.

2. resource- Resource name in Secret Agent's configuration file. This is an optional field if a single resource name is mentioned in the Secret Agent's configuration file. Otherwise, it is required. The secret will be fetched from the path corresponding to the resource name.

   Refer to the Secret Agent configuration documentation for more information.

3. key - Required field. It identifies the secret to be fetched.

   AWS and Hashicorp Vault allows multiple key-values in one secret. key field determines which key-value will be fetched.

   GCP allows single value in one secret. key field is used only to cross-check that it is a substring of the resource path to avoid user mistakes.

Following is a sample configuration file to fetch the feature-key-file configuration parameter value from an external secret manager.

service {
  ...  
  secrets-address-port 127.0.0.1 3005
  feature-key-file secrets:TestingSecret:FeatureKey
  ...
}

In the above example, TestingSecret is an alias for a resource in Secret Agent's configuration file. FeatureKey is an identifier for the actual feature-key file stored in an external secret manager.

note

The example above uses a plain TCP connection to connect to Secret Agent. You can also use TLS over TCP connection or UDS instead.