Vault configuration

Use this page to understand the Vault service and Vault instance configuration fields for Ripple Custody. The example shows one possible configuration shape; your KMS platform, certificates, credentials, resource values, and vault topology depend on your deployment.

This page applies to on-premise deployments only. For current defaults and the full supported schema, use the configuration packaged with your release.

For platform selection guidance, see Key management planning. For platform-specific procedures, see Integrate a key management system.

What this config controls

The Vault service manages cryptographic key operations through a KMS, HSM, or MPC backend. A deployment can define one or more Vault instances under harmonize.vaults, each with its own platform configuration.

Vault service fields

Image

Location: vault.image

Field	Description
`repository`	Vault image repository.
`tag`	Vault image tag.

Platform-specific sidecar images are selected from the platform value unless your release exposes explicit image overrides.

Environment variables

Variable	Description	Default	Required
`VAULT_ID`	Unique Vault identifier.	-	Yes
`VAULT_LOGLEVEL`	Vault core log level.	`info`	No
`VAULT_TRUSTED_SIG`	Notary public key for message verification.	-	Yes

Other Vault environment variables are managed by the release package unless explicitly exposed.

Resources

Location: vault.resources

Field	Default	Description
`limits.cpu`	`200m`	CPU limit for the Vault pod.
`limits.memory`	`64Mi`	Memory limit for the Vault pod.
`requests.cpu`	`20m`	CPU request for the Vault pod.
`requests.memory`	`32Mi`	Memory request for the Vault pod.

Resource values are workload-dependent. Set them based on expected signing volume and observed runtime behavior.

Probes

Location: vault.probes

Field	Default	Description
`liveness.enabled`	`false`	Enables the Vault liveness probe.
`readiness.enabled`	`false`	Enables the Vault readiness probe.
`startup.custom`	`true`	Uses a custom startup probe.
`startup.spec`	`pgrep supervisord`	Startup probe command specification.

Persistence

Location: vault.persistence

Field	Description
`config.enabled`	Enables a configuration volume. Used by Luna HSM certificate configuration.
`config.name`	Name of the configuration volume source.
`config.type`	Configuration volume type, such as `secret`.
`config.mountPath`	Mount path for platform configuration.
`temp.enabled`	Enables a temporary volume.
`temp.mountPath`	Mount path for temporary files.
`temp.size`	Temporary volume size.
`temp.type`	Temporary volume type, such as `emptyDir`.

Vault instance fields

Location: harmonize.vaults.<vault-id>

Field	Type	Description
`enabled`	boolean	Enables this Vault instance.
`platform`	string	Selects the KMS, HSM, or MPC backend.
`notary_public_key`	string	Notary public key used for message verification. Format: `<algorithm>:<public_key_hex>`.
`<platform configuration>`	object	Platform-specific configuration block, such as `kms_luna`, `kms_aws`, or `kms_mpc`.

Supported notary_public_key algorithm prefixes documented in this reference:

Prefix	Description
`ed25519`	EdDSA using Curve25519.
`secp256k1`	ECDSA using secp256k1. Documented for AWS CloudHSM examples.

Platform values

Platform value	Description
`kms_luna`	Thales Luna HSM through KMS Connect.
`kms_blocksafe`	BlockSafe HSM through KMS Connect.
`kms_aws`	AWS CloudHSM through KMS Connect.
`kms_mpc`	Multi-party computation.
`kms_ibm` / `ibm`	IBM LinuxONE or IBM Hyper Protect Crypto Services. Existing draft content uses both values; confirm the exact value against your release configuration before using IBM fields.

Platform-specific fields

Location: harmonize.vaults.<vault-id>.kms_luna

Field	Description
`host`	Luna HSM hostname or IP address.
`port`	Luna HSM port. Common value: `1792`.
`slot`	HSM partition slot number.
`pin`	HSM partition PIN.
`client.certificate`	Client certificate in PEM format.
`client.key`	Client private key in PEM format.
`server.certificate`	Server certificate in PEM format.

Constraints and relationships

Each Vault instance key under harmonize.vaults is a Vault UUID.
Each enabled Vault instance needs a platform, a valid notary_public_key, and the fields required by its platform.
The Notary public key is returned during Genesis. See Installation and initialization.
Platform credentials and certificates should come from your deployment secret-management process.
KMS platform setup is performed in the platform-specific integration guides, not in this reference page.

Example

This example shows one Vault instance using AWS CloudHSM and one set of Vault service settings:

vault:
  resources:
    limits:
      cpu: 200m
      memory: 64Mi
    requests:
      cpu: 20m
      memory: 32Mi
  probes:
    liveness:
      enabled: false
    readiness:
      enabled: false
    startup:
      custom: true
      spec:
        exec:
          command: ["pgrep", "supervisord"]
        failureThreshold: 10
        periodSeconds: 3
  persistence:
    temp:
      enabled: true
      mountPath: /tmp
      size: 200Mi
      type: emptyDir

harmonize:
  vaults:
    "00000000-0000-0000-0000-000000000000":
      enabled: true
      platform: kms_aws
      notary_public_key: "secp256k1:<notary-public-key>"
      kms_aws:
        aws_cloud_hsm_crypto_user_username: "crypto-user"
        aws_cloud_hsm_crypto_user_password: "<cloudhsm-password>"
        aws_cloud_hsm_cluster_eni_ip: "10.0.1.100"
        aws_cloud_hsm_customer_certificate: |
          -----BEGIN CERTIFICATE-----
          <certificate-data>
          -----END CERTIFICATE-----