# 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](/products/custody/deployment/planning/key-management). For platform-specific procedures, see [Integrate a key management system](/products/custody/deployment/integrate-kms/overview).

## 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

Luna HSM
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. |


BlockSafe HSM
Location: `harmonize.vaults.<vault-id>.kms_blocksafe`

| Field | Description |
|  --- | --- |
| `secretRef` | Optional reference to a secret containing BlockSafe values. |
| `device` | Device connection string. Existing format: `port@hostname`. |
| `slot` | HSM slot number. |
| `pin` | HSM PIN. |


When `secretRef` is used, the secret values shown in the draft reference are:

| Secret key | Description |
|  --- | --- |
| `device` | Device connection string. |
| `slot` | HSM slot number. |
| `pin` | HSM PIN. |


AWS CloudHSM
Location: `harmonize.vaults.<vault-id>.kms_aws`

| Field | Description |
|  --- | --- |
| `aws_cloud_hsm_crypto_user_username` | AWS CloudHSM crypto user username. |
| `aws_cloud_hsm_crypto_user_password` | AWS CloudHSM crypto user password. |
| `aws_cloud_hsm_cluster_eni_ip` | AWS CloudHSM cluster ENI IP address. |
| `aws_cloud_hsm_customer_certificate` | AWS CloudHSM customer certificate in PEM format. |


IBM LinuxONE / HPCS
Location: `harmonize.vaults.<vault-id>.ibm`

| Field | Description |
|  --- | --- |
| `hpcssecrets` | JSON string containing IBM HPCS secret values. |


The documented `hpcssecrets` JSON keys are:

| JSON key | Description |
|  --- | --- |
| `trustedSigKey` | Base64-encoded trusted signature key in PEM form. |
| `hpcsApiKey` | IBM Cloud API key. |
| `hpcsEndpoint` | HPCS EP11 endpoint. |
| `hpcsInstanceID` | HPCS instance ID. |


Multi-party computation (MPC)
Location: `harmonize.vaults.<vault-id>.kms_mpc`

| Field | Description |
|  --- | --- |
| `url` | MPC node HTTP endpoint. |
| `threshold` | Minimum number of MPC parties required for signing. |


MPC node metadata is configured separately:

| Field | Description |
|  --- | --- |
| `harmonize.mpc.nodes[].name` | MPC node name. |
| `harmonize.mpc.nodes[].public_key` | MPC node public key. |


## 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](/products/custody/deployment/install/first-time-installation).
- 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:


```yaml
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-----
```

## Related topics

- [Key management planning](/products/custody/deployment/planning/key-management)
- [Integrate a key management system](/products/custody/deployment/integrate-kms/overview)
- [Luna HSM integration](/products/custody/deployment/integrate-kms/on-premise-hsm/thales-luna)
- [AWS CloudHSM integration](/products/custody/deployment/integrate-kms/cloud-hsm/aws-cloudhsm)
- [BlockSafe HSM integration](/products/custody/deployment/integrate-kms/on-premise-hsm/blocksafe)
- [IBM HPCS integration](/products/custody/deployment/integrate-kms/on-premise-hsm/ibm-linuxone)
- [MPC integration](/products/custody/deployment/integrate-kms/mpc/overview)
- [Notary configuration](/products/custody/deployment/reference/kms-notary)