This page contains information related to upcoming products, features, and functionality. It is important to note that the information presented is for informational purposes only. Please do not rely on this information for purchasing or planning purposes. The development, release, and timing of any products, features, or functionality may be subject to change or delay and remain at the sole discretion of GitLab Inc.
Status Authors Coach DRIs Owning Stage Created
proposed devops verify -

GitLab Secrets Manager ADR 001: Use envelope encryption


To store secrets securely in the GitLab Secrets Manager, we need a system that can prevent unencrypted secrets from being leaked in the event of a security breach to a GitLab system.


Use envelope encryption. GitLab Rails will store the encrypted secret at rest, along with an encrypted data key. In order to decrypt the secret, GitLab Rails will need to make a decryption request to the GCP key manager through GitLab Secrets Service and obtain the decrypted data key. The data key is then used to decrypt the encrypted secret.

sequenceDiagram participant A as Client participant B as GitLab Rails participant C as GitLab Secrets Service Note over B,C: Initialize vault for project/group/organization B->>C: Initialize vault - create key pair C->>B: Returns vault public key B->>B: Stores vault public key Note over A,C: Creating a new secret A->>B: Create new secret B->>B: Generate new symmetric data key B->>B: Encrypts secret with data key B->>B: Encrypts data key with vault public key B->>B: Stores envelope (encrypted secret + encrypted data key) B-->>B: Discards plain-text data key B->>A: Success Note over A,C: Retrieving a secret A->>B: Get secret B->>B: Retrieves envelope (encrypted secret + encrypted data key) B->>C: Decrypt data key C->>C: Decrypt data key using vault private key C->>B: Returns plain-text data key B->>B: Decrypts secret B-->>B: Discards plain-text data key B->>A: Returns secret


With this approach, an actor that gains access to the GitLab database containing the envelope will not be able to decrypt the content of the secret as the private key required is not stored with it.

We also need to consider how to securely generate and store the asymmetric keypair used for each vault.

In addition, the following resources would be required:

  1. Multiple asymmetric keypairs. A unique asymmetric keypair is needed per vault, belonging to a project, group or an organization.
  2. Multiple symmetric keys. A unique key is needed per secret.


We considered performing the encryption and decryption of the secret in the GitLab Secrets Service, while storing the encrypted data in GitLab Rails. However, this means that there would be a time where the secret and the encryption keys exist at the same time in GitLab Secrets Service.