Notary configuration

Use this page to understand the Notary configuration fields for Ripple Custody. The examples show possible configuration shapes; your KMS platform, credentials, certificates, resource values, and rollout process 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.

What this config controls

The Notary handles approval signing through a KMS or HSM backend. The Vault uses the Notary public key to verify Notary signatures.

Protocol fields

Location: harmonize.notary

Parameter	Type	Default	Description
`protocol`	string	`grpc`	Communication protocol between Notary Bridge and Notary. Possible values: `grpc`, `http`.

Protocol notes:

Protocol	Notes
`grpc`	Supports gRPC communication between Notary Bridge and Notary.
`http`	Supports HTTP communication between Notary Bridge and Notary.

Component fields

Location: components.notary

Field	Description
`platform`	Selects the KMS/HSM backend used by the Notary.
`resources`	CPU and memory requests and limits for the Notary component.
`persistence`	Persistent state configuration, where exposed by your release.
`env`	Environment-variable overrides exposed by your release.
`<platform configuration>`	Platform-specific configuration block, such as `kms_luna` or `kms_ibm`.

Image references, internal ports, and inter-service wiring are managed by the release package unless explicitly exposed.

Hot failover fields

Starting in version 1.43, the approval-notary chart can deploy a standby notary. You don't deploy notaries that run in enclaves with Helm, so these fields don't apply to them. Instead, configure the second instance as a standby in your enclave deployment. For the procedure, see Set up notary hot failover.

Field	Default	Description
`standby.enabled`	`false`	Deploys a second notary that takes over when the serving notary is silent for the bridge's exclusivity period. Requires an anti-rewind mode of `BALANCED` or `DISABLED`. The chart refuses to render `standby.enabled` together with `antiRewind.seedMode: STRICT`.
`standby.nodeSelector`	The other notary's node selector	Pod node selector for the standby notary only, so that you can place it in another availability zone.
`standby.extraEnv`	`{}`	Extra environment variables for the standby notary only, layered over the other notary's.
`antiRewind.seedMode`	Empty	Break-glass declaration of the anti-rewind mode on the notary host: `STRICT`, `BALANCED`, or `DISABLED`. The notary reads it only when its anti-rewind file holds no mode. Leave it empty so that the mode comes from Genesis or the `v0_SetSystemProperty` intent. Replaces `HMZ_NOTARY_ALLOW_EMPTY_COLS`.

The bridge controls when a takeover happens:

Environment variable	Default	Description
`HMZ_NOTARY_BRIDGE_EXCLUSIVITY_PERIOD`	`15m`	How long the serving notary can be silent before the standby notary can take its place. You can set any value of 10 minutes or more. A takeover is final, so keep this longer than any restart or node reboot. Below 10 minutes, the bridge doesn't start.
`HMZ_NOTARY_BRIDGE_TAKEOVER_WARNING_RATIO`	`0.5`	How far into the exclusivity period the bridge logs a warning that a takeover is approaching.

Retirement of HMZ_NOTARY_ALLOW_EMPTY_COLS

Version 1.43 retires HMZ_NOTARY_ALLOW_EMPTY_COLS. If antiRewind.seedMode is empty, the notary reads HMZ_NOTARY_ALLOW_EMPTY_COLS=true as BALANCED. Replace it with antiRewind.seedMode, or set the mode with an intent.

Platform values

Platform value	Type	Description
`luna`, `kms_luna`, `kms-luna`	Hardware HSM	Thales Luna HSM through KMS Connect.
`kms_blocksafe`, `kms-blocksafe`	Hardware HSM	BlockSafe HSM through KMS Connect.
`kms_ibm`	Hardware HSM	IBM LinuxONE or IBM Hyper Protect Crypto Services integration.
`kms_securosys`, `kms-securosys`	Hardware HSM	Securosys Primus HSM through KMS Connect.

Platform-specific fields

Field	Description
`kms_luna.host`	Luna HSM hostname or IP address.
`kms_luna.port`	Luna HSM port. Common value: `1792`.
`kms_luna.slot`	HSM partition slot number.
`kms_luna.pin`	HSM partition password.
`kms_luna.client.certificate`	Client certificate for mutual TLS.
`kms_luna.client.key`	Client private key for mutual TLS.
`kms_luna.server.certificate`	Luna HSM server certificate.
`kms_luna.existingSecret`	Existing secret containing Luna credentials and certificates.

When existingSecret is set for Luna HSM, the secret must contain these keys:

Secret key	Description
`pin`	HSM partition password.
`client-cert`	Client certificate.
`client-key`	Client private key.
`server-cert`	Server certificate.

Inline pin, client.certificate, client.key, and server.certificate values are ignored when existingSecret is set.

Constraints and relationships

The Notary should use a platform value supported by the KMS/HSM integration you deploy.
The Vault needs the Notary public key in harmonize.vaults.<vault-id>.notary_public_key.
The Notary public key is returned during Genesis. See Installation and initialization.
The Notary and Vault KMS choices should be planned together. See Key management planning.
A standby notary is a second instance of the same notary, with the same notary keys and KMS/HSM configuration. It takes the serving notary's configuration, except for standby.nodeSelector and standby.extraEnv, and needs its own storage for its anti-rewind file and identity file. Plan its access to the KMS/HSM and to the bridge from the zone where you place it.
standby.enabled requires an anti-rewind mode of BALANCED or DISABLED. See Set up notary hot failover.

Example

This example shows a Notary configured with Luna HSM and an existing secret:

harmonize:
  notary:
    protocol: grpc
  vaults:
    "00000000-0000-0000-0000-000000000000":
      notary_public_key: "ed25519:<notary-public-key>"

components:
  notary:
    platform: kms_luna
    kms_luna:
      host: "luna-hsm.example.com"
      port: "1792"
      slot: "0"
      existingSecret: "notary-luna-credentials"