Managing Secret Keys

Secret Encryption

Secrets management is leveraged in IAG5 via writing encrypted data into its backend store. Itential leverages asymmetrical encryption with zero trust of the server/iagctl. IAG5 encrypts secrets with an encryption-file that must be created and utilized for encryption and decryption.

Encryption with Gateway

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.

Creating a Secret Key

For a secret to be encrypted and decrypted you will need to have a private key only for those IAG5 instances that need to perform a decrypt of the secret.

Generating a private key can be done with an openssl package as follows:

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

Inspecting the key would result in the following:

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

To ensure security you will need to run:

chmod 400 /somedir/my_private.key

Using Secret Key for Encryption/Decryption

Once the key is generated, there are a couple of ways to tell IAG5 to use the generated key for encryption/decryption, as referenced below.

IAG5 Config

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

Environment Variable

export GATEWAY_SECRETS_ENCRYPT_KEY_FILE="/somedir/my_private.key"

Once the key is set in gateway, you can begin to create and get secrets.

Storing Keys

There are many use cases for secrets, but this section will focus on the main use case of using the secret store to store SSH keys that will be used for git repositories.

Create a Key for Git Repository

Use ssh-keygen to generate a key specifically for usage with IAG5.

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 private and public ssh key is generated in a folder.

ls | grep tor                                                                        
gateway
gateway.pub

The file content from gateway.pub will need to be placed in GitLab as a new Authentication key. This key is public. The other key, which is gateway, is the private key that will be used later to add to your secret store.

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

Figure 1: SSH Key GitLab

Adding Secret Key to Secret Store

Once the public key is in GitLab you will need to add the private key so that it can be used in the IAG5 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

In the command above you leveraged the @ symbol to state 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 secret will be displayed in your default editor when viewed on the command line. The reason for this is that since you hold the file needed for decryption, the secret will be clear text.

export EDITOR=nano

iagctl describe secret git-key

After running the command a new window is displayed with your secret. Once the window is closed the file is deleted. This is useful for viewing the secret for troubleshooting.

Figure 2: View Secret Key

The name of the secret can now be passed into any of the git repositories that you create. This will allow a secure clone of the repository when you run a service.

Adding Secret Key to Repository

When creating 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

CLI References

For related hostkeys commands see → iagctl hostkeys

For command references see → Command References Index