Encryption (Key Management)

monetr supports encrypting secrets before they are stored in PostgreSQL. Other data may support encryption in the future but at the moment only Plaid credentials are encrypted.

To that end, monetr supports a few different providers. An outline of the configuration for key management:

config.yaml

keyManagement:
  provider: "<plaintext|aws|openbao|vault>" # KMS provider, must be one of these values
  aws: { ... }     # AWS KMS specific configuration, only used when `provider: aws`
  openbao: { ... } # OpenBao specific configuration, only used when `provider: openbao`
  vault: { ... }   # Hashicorp Vault configuration, only used when `provider: vault`

If you are using the plaintext provider (which is the default), no additional options needs to be provided for the key management configuration.

Plaintext

When plaintext is specified as the provider, monetr will not encrypt any secrets and all items in the secrets table will be stored in plain text. This is fine for self hosted deployments or development environments.

AWS KMS Configuration

The AWS KMS will encrypt secrets using AWS’s key management API. There is also an option to run a local version of AWS KMS for the local development environment for monetr.

config.yaml

keyManagement:
  aws:
    region: "us-east1"
    accessKey: "..."
    secretKey: "..."
    keyID: "..."
    endpoint: "..." # Only used in development, but can still be specified if you want.

Name	Type	Default	Description
`region`	String		The AWS region to use for the client. May be required depending on your configuration.
`accessKey`	String		The Access Key that monetr should use to access the AWS KMS API.
`secretKey`	String		The Secret Key that monetr should use to access the AWS KMS API.
`keyID`	String		The actual Key ID in AWS, this must be the ID of the key to use for encryption and decryption and should not be changed. If this ID is changed then values encrypted with another key will not be able to be decrypted with this new key.
`endpoint`	String	`null`	The AWS KMS API endpoint, this is intended to be used only for local development environments.

OpenBao Transit Configuration

OpenBao is a self-hostable option for encryption. OpenBao keeps track of the encryption keys themselves while monetr leverages the Transit secrets engine to encrypt and decrypt data.

When running inside Kubernetes, monetr can use the kubernetes authentication method to access OpenBao. When this is configured, monetr will automatically renew its OpenBao credentials a few moments before they expire. Other authentication methods may require a non-expiring token such as the root token.

config.yaml

keyManagement:
  openbao:
    keyID: monetr
    authMethod: kubernetes
    role: monetr
    endpoint: https://your-openbao-server.local:8200
    tlsCertificatePath: /etc/monetr/openbao/tls.crt
    tlsKeyPath: /etc/monetr/openbao/tls.key
    tlsCAPath: /etc/monetr/openbao/ca.crt
    insecureSkipVerify: false

Name	Type	Default	Description
`keyID`	String		Name of the transit mount to use for KMS.
`authMethod`	String		Valid values are: - `token`: Use a hardcoded token to authenticate OpenBao. - `kubernetes`: Use the container’s Kubernetes Service Account Token. - `userpass`: Provide a username and password.
`token`	String		When using token authentication, you can provide the raw token here.
`tokenFile`	String		As an alternative to providing the token directly in the config file, specify a path to a file containing the token itself.
`username`	String		If you are using `userpass` authentication, then this field and the `password` field must be specified.
`password`	String		If you are using `userpass` authentication, then this field and the `username` field must be specified.
`role`	String		Role in OpenBao that monetr should authenticate for, decides what permissions monetr has.
`endpoint`	String		The URL that OpenBao API requests should be made to, should be the complete URL including protocol (https), as well as port if non-standard and path if the API is on a sub-route.
`tlsCertificatePath`	String		Path to the TLS certificate file, used if OpenBao is being hosted with a self signed certificate.
`tlsKeyPath`	String		Path to the TLS key file, used if OpenBao is being hosted with a self signed certificate.
`tlsCAPath`	String		Path to the Certificate Authority file, used if OpenBao is being hosted with a self signed certificate.
`insecureSkipVerify`	Boolean	`false`	When `true`, monetr will not verify the TLS certificate of the OpenBao server, less secure.

Vault Transit Configuration

⚠️

The Vault Transit KMS provider is being deprecated in an upcoming monetr release. If you are currently using the Vault Transit KMS provider then please follow the Migration Guide as soon as possible to avoid future problems.

Hashicorp Vault is a self-hostable option for encryption. Vault keeps track of the encryption keys themselves while monetr leverages the Transit secrets engine to encrypt and decrypt data.

When running inside Kubernetes, monetr can use the kubernetes authentication method to access Vault. When this is configured, monetr will automatically renew its Vault credentials a few moments before they expire. Other authentication methods may require a non-expiring token such as the root token.

config.yaml

keyManagement:
  vault:
    keyID: monetr
    authMethod: kubernetes
    role: monetr
    endpoint: https://your-vault-server.local:8200
    tlsCertificatePath: /etc/monetr/vault/tls.crt
    tlsKeyPath: /etc/monetr/vault/tls.key
    tlsCAPath: /etc/monetr/vault/ca.crt
    insecureSkipVerify: false

Name	Type	Default	Description
`keyID`	String		Name of the transit mount to use for KMS.
`authMethod`	String		Valid values are: - `token`: Use a hardcoded token to authenticate Vault. - `kubernetes`: Use the container’s Kubernetes Service Account Token. - `userpass`: Provide a username and password.
`token`	String		When using token authentication, you can provide the raw token here.
`tokenFile`	String		As an alternative to providing the token directly in the config file, specify a path to a file containing the token itself.
`username`	String		If you are using `userpass` authentication, then this field and the `password` field must be specified.
`password`	String		If you are using `userpass` authentication, then this field and the `username` field must be specified.
`role`	String		Role in Vault that monetr should authenticate for, decides what permissions monetr has.
`endpoint`	String		The URL that Vault API requests should be made to, should be the complete URL including protocol (https), as well as port if non-standard and path if the API is on a sub-route.
`tlsCertificatePath`	String		Path to the TLS certificate file, used if Vault is being hosted with a self signed certificate.
`tlsKeyPath`	String		Path to the TLS key file, used if Vault is being hosted with a self signed certificate.
`tlsCAPath`	String		Path to the Certificate Authority file, used if Vault is being hosted with a self signed certificate.
`insecureSkipVerify`	Boolean	`false`	When `true`, monetr will not verify the TLS certificate of the Vault server, less secure.

Migrate Between KMS Providers

Email/SMTP Links

Encryption (Key Management)

Plaintext

AWS KMS Configuration

OpenBao Transit Configuration

Vault Transit Configuration

Related Topics