# 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

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

BlockSafe HSM
| Field | Description |
|  --- | --- |
| `kms_blocksafe.device` | BlockSafe device connection string. Existing format: `port@host`. |
| `kms_blocksafe.slot` | HSM slot number. |
| `kms_blocksafe.pin` | HSM PIN. |


IBM LinuxONE / HPCS
| Field | Description |
|  --- | --- |
| `kms_ibm.system` | IBM system type. |
| `kms_ibm.instance` | IBM instance identifier or CRN. |
| `kms_ibm.endpoint` | IBM endpoint. |
| `kms_ibm.apikey` | IBM API key. |


Securosys Primus HSM
| Field | Description |
|  --- | --- |
| `kms_securosys.host` | Securosys Primus HSM host. |
| `kms_securosys.port` | Securosys Primus HSM port. |
| `kms_securosys.user` | Securosys user. |
| `kms_securosys.setupPassword` | Securosys setup password. |


## 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](/products/custody/v1.36/deployment/install/first-time-installation).
- The Notary and Vault KMS choices should be planned together. See [Key management planning](/products/custody/v1.36/deployment/planning/key-management).


## Example

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


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

## Related topics

- [Vault configuration](/products/custody/v1.36/deployment/reference/kms-vault)
- [Networking configuration](/products/custody/v1.36/deployment/reference/networking)
- [Key management planning](/products/custody/v1.36/deployment/planning/key-management)
- [Luna HSM integration](/products/custody/v1.36/deployment/integrate-kms/on-premise-hsm/thales-luna)
- [AWS CloudHSM integration](/products/custody/v1.36/deployment/integrate-kms/cloud-hsm/aws-cloudhsm)
- [BlockSafe HSM integration](/products/custody/v1.36/deployment/integrate-kms/on-premise-hsm/blocksafe)
- [IBM HPCS integration](/products/custody/v1.36/deployment/integrate-kms/on-premise-hsm/ibm-linuxone)
- [MPC integration](/products/custody/v1.36/deployment/integrate-kms/mpc/overview)