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.

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.

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"