Secret encryption

Itential Automation Gateway (IAG) leverages secrets management by writing encrypted data into its backend store. Itential uses asymmetric encryption with zero trust of the server/iagctl. IAG encrypts secrets with an encryption-file that you must create and use for encryption and decryption.

Encryption with IAG

Data is encrypted using AES (Advanced Encryption Standard) in GCM (Galois/Counter Mode). The key for AES is generated by PBKDF2 from a provided encryption file and a random salt, which makes each stored secret distinct, even if they are using the same encryption file. The salt and encrypted data are stored as a base64 encoded string.

Create a secret key

To encrypt and decrypt secrets, you need a private key for the IAG instances that will decrypt the secrets.

The following procedures demonstrate how to generate a private key with an openssl package:

openssl rand -base64 256 > /somedir/my_private.key

Inspecting the key produces the following result:

cat /somedir/my_private.key
UM/mOfv5iQqF6Cp1u8k+0MFVTq44NIPQii1wkTgacS1GnOGiI4iBMFeFJSJQT80A
Lso1VmL0wr3MqG9wgvov32y5Oddjay9j5RqMIbQpJuJDJtrodzWi+6B+yo0NBoHz
sgfLr6oL16oFrwSRq+ZSELJLr/aL9V9fdMluHYCGOHJrQtxojoQX41kF7OS6dSNk
BbCRKKJrpJtOmZY1nz7CLcGWxA80PDdjGwozdN/vwxo84Ohpl6/R7pDVZOIXfbyh
xMibYbvLM01A2/eJ72PU4zfiWRdiovnmLlsifMnDwobs0WHY5lAgGpdENs6v577e
YK2U8HlKOWczjPsXjK7RBA==

To ensure security, run:

chmod 400 /somedir/my_private.key

Use secret key for encryption and decryption

After you generate the key, you can tell IAG to use the generated key for encryption and decryption in the following ways:

IAG config

[secrets]
encrypt_key_file = "/somedir/my_private.key"

Environment variable

export GATEWAY_SECRETS_ENCRYPT_KEY_FILE="/somedir/my_private.key"

For more information, see Secret Variables.

Storing Keys

There are many use cases for secrets, but this section focuses on the main use case of using the secret store to store SSH keys that you'll use for Git repositories.

Create a key for Git repository

Use ssh-keygen to generate a key specifically for use with IAG:

ssh-keygen                                                                              
Generating public/private ed25519 key pair.
Enter file in which to save the key (/Users/username/.ssh/id_ed25519): ./iagctl
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in ./iagctl
Your public key has been saved in ./iagctl.pub
The key fingerprint is:
SHA256:CqPZH763k3ktyGB5JcGH1j97CQzr2bg3h6I0Vm4j4+Q jared@Jareds-MacBook-Pro-2.local
The key's randomart image is:
+--[ED25519 256]--+
|       . o       |
|        = +      |
|       . o =     |
|        . o =    |
|    o  .S+.+ + . |
|   + o+..o+ o o  |
|  o ..o+B++o o   |
|     o BB==.= .  |
|      +oE= + o   |
+----[SHA256]-----+

In the output, you can see that the system generates the private and public SSH key in a folder:

ls | grep tor                                                                        
gateway
gateway.pub

You need to place the file content from gateway.pub in GitLab as a new authentication key. This key is public. The other key, gateway, is the private key that you'll use later to add to your secret store.

If you are using a repository with an ssh key then you can add the private ssh key to the gateway secret store. When you view GitLab SSH Settings, you can see all the keys that are listed.

Figure 1: SSH Key GitLab

Add secret key to secret store

After the public key is in GitLab, you need to add the private key so that it can be used in the IAG Gateway. Run the following command where the private key is located:

iagctl create secret git-key --value "@/path/to/new/ssh/key/for/iagctl"
Successfully created secret
Name:   git-key

The above command leverages the @ symbol to indicate that this is a file that contains the full path to the private key, which in this case was the gateway file created by the openssl command.

If desired, you can also view the contents of the secret. To maintain security, the system displays the secret in your default editor when you view it on the command line. Because you hold the file needed for decryption, the secret appears as clear text.

export EDITOR=nano

iagctl describe secret git-key

After running the describe command, a new window displays your secret. When you close the window, the system deletes the file. This is useful for viewing the secret for troubleshooting.

Figure 2: View Secret Key

You can now pass the name of the secret into any of the Git repositories you create. This allows a secure clone of the repository when you run a service.

Add secret key to repository

When you create a repository, you can pass in the secret key as follows:

iagctl create repository some-private-repo --url git@gitlab.com:example/automations/example-automations.git --reference devel --description "For basic demo capabilities" --tag demo --tag itential --private-key-name git-key
Successfully created the repository

Name:             some-private-repo
Description:      For basic demo capabilities
Url:              git@gitlab.com:example/automations/example-automations.git
Reference:        devel
Tags:             demo, itential
Private Key Name: git-key

Learn more

For related hostkeys commands, see iagctl hostkeys.