Secrets in Yandex Lockbox

SecretSecret

A secret is a set of versions that store your data, such as API keys, passwords, or tokens. A version contains sets of keys and values. A key is a non-secret name that identifies a value. The value is your secret data.

You can set up access to secrets using Yandex Identity and Access Management. The roles available for different use cases are described in the Access management in Yandex Lockbox section.

A secret can be either active or deactivated. When a secret is active, it enables access to both its metadata and content (key-value pairs). When deactivated, it allows access only to its metadata, with the secret content being inaccessible.

Secret typeSecret type

Yandex Lockbox allows creating two types of secrets: generated secrets and user secrets.

• A generated secret is an automatically generated sequence of random characters. You can configure generation parameters, such as length and character set. Generated secrets are good for passwords you do not have to set manually as well as for passwords with frequent rotation, e.g., for database access, microservice level authentication, in CI/CD systems, and for other program interactions.

  You can also use generated secrets to store data on connections to PostgreSQL, MySQL®, and ClickHouse® databases via Yandex Connection Manager. In which case the secret is created in Yandex Connection Manager and stored in Yandex Lockbox.

• A user secret is created manually. It is suitable for externally generated secrets. You can specify not only a string but also a file for your user secret's confidential value.

  If a file is used as the confidential value, the returned secret content will be Base64 encoded. To decode the file, use the base64 Python module or other suitable tools.

VersionVersion

Yandex Lockbox stores secrets as versions. Each version contains metadata and one or more key-value pairs, which allows you to track changes and manage a secret's lifecycle.

Once created, a version cannot be changed. If you need to change key-value pairs, you will need to create a new version. Apart from creating a new version of a secret, you can create a version based on an existing one with new values.

Only one version of a secret can be valid at a time. You can manage a valid version of a secret by adding new versions or rolling back to previous ones.

You can set up access to versions of a secret in addition to access to the secret itself. To do this, you need to assign the lockbox.admin or lockbox.payloadViewer role. For more information about managing access, see Yandex Lockbox access management: What roles do I need.

Secret encryption using Yandex Key Management ServiceSecret encryption using Yandex Key Management Service

With Yandex Key Management Service, you can create and manage encryption keys that are used to secure secrets in Yandex Lockbox.

By default, all secrets are encrypted with a common key. However, when creating a secret, you can specify your own Yandex Key Management Service key for encrypting the secret. Using your own key has the following benefits:

• It mitigates the risk of the common key being compromised.
• You can rotate your key on your own and manage its versions.
• You can delete your key, if needed, to block access to your encrypted data.
• You can get audit logs of events connected to encryption key usage. To do this, use Yandex Audit Trails.

If you specified your KMS key when creating a secret, assign the kms.keys.encrypterDecrypter and lockbox.payloadViewer roles to your secret. They are required to access the key, as well as encrypt and decrypt it.

See alsoSee also

• Access management in Yandex Lockbox
• Yandex Lockbox tutorials
• Yandex Lockbox pricing policy