> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.itential.com/itential-gateway/5/configure-secret-store/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server.

# Configure Gateway secret store

Itential Gateway enables you to store encrypted secret information within its backend data store. Gateway leverages asymmetrical encryption with zero trust of the server. Gateway encrypts secrets with an encryption file that you must create and use for encryption and decryption.

This topic covers **local** secrets, which are encrypted and stored directly in the gateway's data store.

You can use secrets in the following scenarios:

* [Use SSH keys to clone git repositories](/itential-gateway/5/clone-git-repositories-ssh)
* [Inject secret data into services](/itential-gateway/5/inject-secrets-into-services)
* [Authenticate with PyPi or Ansible Galaxy registries](/itential-gateway/5/dependency-registries)

Itential Gateway also supports retrieving credentials directly from external secrets managers such as HashiCorp Vault and CyberArk at runtime, without storing values locally. If you need to connect to an external secrets manager, see [External secrets overview](./secrets/external-secrets/overview).

## Encryption in Gateway

Gateway encrypts data using **AES** (Advanced Encryption Standard) in **GCM** (Galois/Counter Mode). The system generates the AES key using **PBKDF2** from a provided encryption file and a random salt. This approach makes each stored secret distinct, even if secrets use the same encryption file. The system stores the salt and encrypted data as a base64 encoded string.

## Configure Gateway secret store

#### Create an encryption key

You need to create an encryption key before you can encrypt and decrypt secrets. If you run Gateway in a cluster, all instances in that cluster need access to the same encryption key.

Generate an encryption key using the `openssl` package:

```bash
openssl rand -base64 256 > /etc/gateway/gateway_secrets_encryption.key
```

Verify key creation:

```bash
cat /etc/gateway/gateway_secrets_encryption.key
UM/mOfv5iQqF6Cp1u8k+0MFVTq44NIPQii1wkTgacS1GnOGiI4iBMFeFJSJQT80A
Lso1VmL0wr3MqG9wgvov32y5Oddjay9j5RqMIbQpJuJDJtrodzWi+6B+yo0NBoHz
sgfLr6oL16oFrwSRq+ZSELJLr/aL9V9fdMluHYCGOHJrQtxojoQX41kF7OS6dSNk
BbCRKKJrpJtOmZY1nz7CLcGWxA80PDdjGwozdN/vwxo84Ohpl6/R7pDVZOIXfbyh
xMibYbvLM01A2/eJ72PU4zfiWRdiovnmLlsifMnDwobs0WHY5lAgGpdENs6v577e
YK2U8HlKOWczjPsXjK7RBA==
```

(Optional) Set the encryption key file to owner-read-only to prevent unauthorized access:

```bash
chmod 400 /etc/gateway/gateway_secrets_encryption.key
```

Keep this key secure. If you lose the key, you cannot recover any data encrypted with it.

#### Configure Gateway to use encryption key

After you generate the key, tell Gateway the location of your encryption key. You can configure the key location using either a `gateway.conf` file or an environment variable.

**gateway.conf file**

```toml
[secrets]
encrypt_key_file = "/etc/gateway/gateway_secrets_encryption.key"
```

**Environment variable**

```bash
export GATEWAY_SECRETS_ENCRYPT_KEY_FILE="/etc/gateway/gateway_secrets_encryption.key"
```

If you use a distributed Gateway cluster, you need to use the same key on all nodes to encrypt and decrypt information.

#### Create your first secret

Once your encryption key is set, you can create a secret:

```bash
iagctl create secret my-secret --prompt-value
```

View that the secret exists in the store:

```bash
iagctl get secrets
NAME
my-secret
```

View the contents of the secret using the describe command:

```bash
iagctl describe secret my-secret
```

To securely output the decrypted data, the system saves the secret in a temporary location and displays it in your default editor. If you don't set an editor, Gateway defaults to vim. The editor is determined by your `$EDITOR` environment variable. To set a different `$EDITOR`:

```bash
export EDITOR=nano
```

When you close your editor, the system deletes the file that displayed your secret's contents.

You've now created a secret within Gateway's data store. Keep your encryption key file secure.