Skip to main content

Encryption and secrets

This guide describes the various encryption and secret vault settings that must be defined in MintPress's values.yaml file before installing MintPress, along with their default values.

warning

Your values.yaml file might come with settings that are not mentioned in this document, these are internal MintPress configuration and SHOULD NOT be modified unless explicitly recommended to do so.

Mandatory deployment settings​

The following setting must also be defined in the env section of your values.yaml file before installing MintPress, otherwise Helm's chart schema validation will fail.

Variable nameDescriptionKey length
OPSCHAIN_VERSIONThe MintPress container image tag to deploy. Refer to the MintPress chart version section for the required format.N/A

Mandatory encryption and password settings​

The settings to secure your MintPress installation as well as sensitive credentials must be provided before installing the application. These are unique keys that should not be modified after the initial installation and not shared with anyone. All these keys should be alpha-numeric and should not contain any special characters.

Generating keys and passwords

You can generate a random key of specific <key_length> for the following settings with:

openssl rand -hex $((<key_length>/2))

You can then copy the value and paste it into your setting's field value inside the values.yaml file. DO NOT reuse the same value for different settings and avoid creating keys longer than 512 characters.

When using MintPress in high availability mode, these values must be the same across all instances.

Encryption keys​

The settings that secure your MintPress installation. These settings are located in the .env section in your values.yaml file.

Variable nameDescriptionKey length
OPSCHAIN_DETERMINISTIC_KEYThe key MintPress will use for encrypting its data32 characters
OPSCHAIN_ENCRYPTION_SEED_KEYThe key MintPress will use for seeding the encryption of sensitive data, and for deriving the MintPress transportable key32 characters
OPSCHAIN_KEY_DERIVATION_SALTThe key MintPress will use for generating its cryptography keys32 characters
OPSCHAIN_PRIMARY_KEYThe primary key MintPress will use for encryption32 characters
OPSCHAIN_TOKEN_SECRET_KEYCreates the keys MintPress signs tokens, API keys, artifact links and logs with when it is installed. MintPress keeps those keys in its database, where they can be rotated. Keep this value unchanged after installation64 characters
danger

Modifying any of these settings after installation will result in data loss, so the chart refuses an upgrade that changes them. Keep them with your backups.

MintPress transportable key​

MintPress encrypts properties, settings, secrets and sensitive input arguments with the MintPress transportable key. The key is stored in the mintpress-transportable-key Kubernetes secret, and is created when you first install MintPress:

  • if mintPressTransportableKey is set in your values.yaml file, MintPress uses that key
  • otherwise, MintPress derives the key from OPSCHAIN_ENCRYPTION_SEED_KEY

To use an existing MintPress key, set mintPressTransportableKey (outside the .env section) to the base64 encoded contents of your MintPress localKey file:

base64 -w0 ~/.limepoint/localKey

If the value of mintPressTransportableKey is not a key MintPress can use, MintPress derives the key from OPSCHAIN_ENCRYPTION_SEED_KEY instead, and the opschain-transportable-key job log records that the supplied key was replaced.

You must set at least one of OPSCHAIN_ENCRYPTION_SEED_KEY and mintPressTransportableKey; helm install and helm upgrade fail if neither is set. In high availability mode, set OPSCHAIN_ENCRYPTION_SEED_KEY. If you set only mintPressTransportableKey, it is not a key MintPress can use, and MintPress does not already have a usable key, the opschain-transportable-key job fails, because there is no OPSCHAIN_ENCRYPTION_SEED_KEY to derive a key from.

If your values.yaml file sets neither, set OPSCHAIN_ENCRYPTION_SEED_KEY before you upgrade. If you previously set it and later removed it, restore the original value, otherwise use a new value:

  • if your installation already has a usable transportable key, MintPress keeps that key
  • otherwise, MintPress derives a new key from OPSCHAIN_ENCRYPTION_SEED_KEY

Once the key has been created, it does not change:

  • a later change to mintPressTransportableKey is ignored, and the job log records a warning
  • a later change to OPSCHAIN_ENCRYPTION_SEED_KEY fails the helm upgrade, with the error OPSCHAIN_ENCRYPTION_SEED_KEY has changed since the transportable key was derived from it. Restore the original value and run the upgrade again.

In high availability mode, every instance derives the same key from the same OPSCHAIN_ENCRYPTION_SEED_KEY.

Values that an earlier MintPress version encrypted with the MintPress built-in key remain readable, and are not re-encrypted.

If you run MintPress outside MintPress, for example on your target hosts, and it needs to decrypt values that MintPress encrypted, copy the key to its localKey file:

kubectl -n ${KUBERNETES_NAMESPACE} get secret mintpress-transportable-key -o jsonpath='{.data.localKey}' | base64 -d > ~/.limepoint/localKey
danger

Do not delete the mintpress-transportable-key secret, and do not roll back to a MintPress version whose chart creates the secret itself. Either one replaces the key, and the values encrypted with it can no longer be decrypted.

Credentials​

The credentials used across MintPress and its services. All of these settings are in the .env section in your values.yaml file.

Variable nameDescriptionKey length
OPSCHAIN_DOCKER_PASSWORDThe DockerHub password that MintPress should use when communicating with the external DockerHub registry. Provided with your licence.At least 8 characters long
OPSCHAIN_DOCKER_USERThe DockerHub username that MintPress should use when communicating with the external DockerHub registry. Provided with your licence.At least 8 characters long
trow.trow.passwordThe password that MintPress should use when communicating with its internal image registry. This setting is set in the trow.trow.password field in your values.yaml file - outside the .env section.At least 8 characters long
OPSCHAIN_LDAP_PASSWORDThe password that MintPress will use when communicating with its internal LDAP serverAt least 8 characters long
PGPASSWORDThe password for accessing MintPress's databaseAt least 8 characters long
danger

The chart refuses an upgrade that changes PGPASSWORD, unless you follow changing the database password. Keep it with your backups.

Backup encryption key​

Database backups are encrypted. Scheduled backups are enabled by default. While scheduled or pre-deploy backups are enabled, you must set db.backup.encryption.publicKey in your values.yaml. Without it, helm install and helm upgrade fail. Generate the key pair outside the cluster and keep the private key offline, as described in backup encryption.

Mandatory secret vault settings​

MintPress always installs its own secret vault, the bundled secret vault, and uses it as the global default. You must define a seal key for it by configuring the secretVault.unsealKey setting in your values.yaml file. The key must be 32 random bytes, base64 encoded, which makes a 44 character string. Any other value fails the install. The key must be the same across all MintPress instances in a high availability setup, and it cannot be changed after installation. You can use the following command to generate a random key:

openssl rand -base64 32
OpsChain secret vault token

Be aware that the seal key is NOT the same as the token used to access the secret vault. A root token will be generated and stored, encrypted, in the MintPress database when the MintPress application starts up for the first time. Refer to secret vault root token for how to retrieve it.

When MintPress uses LDAP authentication, users can also sign in to the OpsChain secret vault with their LDAP credentials, and MintPress superusers administer it. See secret vault LDAP login.

You must also must define the hostname that its UI will be accessible at, as described in the TLS/HTTPS configuration guide.

External secret vaults​

The bundled secret vault cannot be disabled or replaced as the global default. To keep the secrets of some projects, environments, assets or templates in a vault of your own, register it once MintPress is running and assign it with the vault.code setting. The cascading settings system applies, so a vault assigned to a project is used by its environments and assets unless they choose another.

What to do next​

  • Configure TLS/HTTPS to secure communications between MintPress, its services and clients.