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. As with all projects, the items mentioned on this page are subject to change or delay. The development, release, and timing of any products, features, or functionality remain at the sole discretion of GitLab Inc.
Status Authors Coach DRIs Owning Stage Created
proposed devops verify -

GitLab Secrets Manager ADR 002: Use GCP Key Management Service

Context

Following from ADR 001: Use envelope encryption, we need to find a solution to securely store asymmetric keys belonging to each vault.

Decision

We decided to rely on Google CLoud Platform (GCP) Key Management Service (KMS) to manage the asymmetric keys used by the GitLab Secrets Manager vaults.

Using GCP provides a few advantages:

  1. Avoid implementing our own secure storage of cryptographic keys.
  2. Support for Hardware Security Modules (HSM).
GCP Key Management ServiceGitLab Secrets ServiceGitLab RailsClientGCP Key Management ServiceGitLab Secrets ServiceGitLab RailsClientInitialize vault for project/group/organizationIncurs cost per keyCreating a new secretRetrieving a secretIncurs cost per decryption requestInitialize vault - create key pairCreate new asymmetric keyReturns public keyReturns vault public keyStores vault public keyCreate new secretGenerate new symmetric data keyEncrypts secret with data keyEncrypts data key with vault public keyStores envelope (encrypted secret + encrypted data key)Discards plain-text data keySuccessGet secretRetrieves envelope (encrypted secret + encrypted data key)Decrypt data keyDecrypt data keyReturns plain-text data keyReturns plain-text data keyDecrypts secretDiscards plain-text data keyReturns secret

For security purpose, we decided to use Hardware Security Module (HSM) to protect the keys in GCP KMS.

Consequences

Authentication

With keys stored in GCP KMS, we need to de-multiplex between identities configured in GCP KMS and identities defined in GitLab so that decryption requests can be authenticated accordingly.

Cost

With the use of GCP KMS, we need to account for the following cost:

  1. Number of keys required
  2. Number of key operations
  3. HSM Protection level

The number of keys required would be dependent on the number of projects, groups, and organizations using this feature. A single asymmetric key is required for each project, group or organization.

Each cryptographic key operation would also incur cost and it varies per protection level. Based on the proposed design above, this would incur cost at each secret decryption request.

We may implement a multi-tier protection level, supporting different protection types for different users.

The pricing table of GCP KMS can be found here.

Feature availability for Self-Managed customers

Using GCP KMS as a backend means that this solution cannot be deployed into self-managed environments. To make this feature available to Self-Managed customers, this feature needs to be a GitLab Cloud Connector feature.

Alternatives

We considered generating and storing private keys within GitLab Secrets Service, but this would not meet the requirements for FIPS Compliance.

On the other hand, GCP HSM Keys comply with FIPS 140-2 Level 3.