Encryption and secrets

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

warning

Your values.yaml file might come with settings that are not mentioned in this document, these are internal OpsChain 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 OpsChain, otherwise Helm's chart schema validation will fail.

Variable name	Description	Key length
OPSCHAIN_VERSION	The OpsChain container image tag to deploy. Refer to the OpsChain chart version section for the required format.	N/A

Mandatory encryption and password settings

The settings to secure your OpsChain 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 OpsChain in high availability mode, these values must be the same across all instances.

Encryption keys

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

Variable name	Description	Key length
OPSCHAIN_DETERMINISTIC_KEY	The key OpsChain will use for encrypting its data	32 characters
OPSCHAIN_ENCRYPTION_SEED_KEY	The key OpsChain will use for seeding the encryption of sensitive data, and for deriving the MintPress transportable key	32 characters
OPSCHAIN_KEY_DERIVATION_SALT	The key OpsChain will use for generating its cryptography keys	32 characters
OPSCHAIN_PRIMARY_KEY	The primary key OpsChain will use for encryption	32 characters
OPSCHAIN_TOKEN_SECRET_KEY	The key OpsChain will use for generating bearer tokens for authentication, and from which it derives the key that signs artifact links. Changing it invalidates existing bearer tokens and artifact links	64 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

OpsChain 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 OpsChain:

• if mintPressTransportableKey is set in your values.yaml file, OpsChain uses that key
• otherwise, OpsChain 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, OpsChain 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 OpsChain 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, OpsChain keeps that key
• otherwise, OpsChain 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 OpsChain version encrypted with the MintPress built-in key remain readable, and are not re-encrypted.

If you run MintPress outside OpsChain, for example on your target hosts, and it needs to decrypt values that OpsChain 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 an OpsChain 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 OpsChain and its services. All of these settings are in the .env section in your values.yaml file.

Variable name	Description	Key length
OPSCHAIN_DOCKER_PASSWORD	The DockerHub password that OpsChain should use when communicating with the external DockerHub registry. Provided with your licence.	At least 8 characters long
OPSCHAIN_DOCKER_USER	The DockerHub username that OpsChain should use when communicating with the external DockerHub registry. Provided with your licence.	At least 8 characters long
trow.trow.password	The password that OpsChain 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_PASSWORD	The password that OpsChain will use when communicating with its internal LDAP server	At least 8 characters long
PGPASSWORD	The password for accessing OpsChain's database	At least 8 characters long

danger

PGPASSWORD cannot be changed after installation: the chart refuses an upgrade that changes it. 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

OpsChain 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 OpsChain 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 OpsChain database when the OpsChain application starts up for the first time. Refer to secret vault root token for how to retrieve it.

When OpsChain uses LDAP authentication, users can also sign in to the OpsChain secret vault with their LDAP credentials, and OpsChain 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 OpsChain 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 OpsChain, its services and clients.