# Secrets management planning

This page outlines methods for securely handling sensitive configuration data during a full on-premises deployment. Examples include passwords, database credentials, and API keys for external systems. The goal is to secure these configurations while minimizing the risk of storing them directly in deployment files.

## Methods available for managing secrets

The platform deployment supports two primary strategies for secrets injection: using native Kubernetes capabilities or integrating with an external enterprise-grade secrets manager.

### Kubernetes secrets (default method)

The default approach involves defining sensitive configuration data directly within the Kubernetes cluster, leveraging native Kubernetes Secrets functionality.

In a full on-premises deployment, components are deployed using Kubernetes and the Helm package manager. Configuration is managed through the Helm chart's `values.yaml` file. For example, you specify credentials like the username and password for authenticating with the indexer for supported blockchain networks (such as Bitcoin and its forks) directly within the network configuration block. Helm uses this data to create and inject Kubernetes secrets into the necessary components during deployment.

### External secrets manager (recommended)

We consider using an external secrets manager the best practice for securing credentials and sensitive data. This method involves integrating the platform with specialized external vault solutions, such as HashiCorp Vault or Conjur, for centralized secret storage.

This approach significantly enhances security by delegating the storage, rotation, and lifecycle management of secrets to a dedicated and auditable solution. Integration allows you to configure connectivity to external account providers, such as connected exchanges. Credentials and API keys are fetched from the external manager, often by referencing environment variables. This increases flexibility and security in managing secrets.

## Categories of credentials and secrets

Deployment and operation require provisioning various sensitive credentials and access tokens, managed by the client.

| Component/Connection | Required Credentials/Secrets | Notes |
|  --- | --- | --- |
| Data Layer | Credentials (username/password) to allow OpenShift cluster access to the PostgreSQL Database. | See [Database planning](/products/custody/v1.34/deployment/planning/database) |
| Messaging Layer | Credentials (username/password) to allow OpenShift cluster access to the AMQP Message Broker (normally RabbitMQ). | See [Message Queue planning](/products/custody/v1.34/deployment/planning/messaging) |
| Container Image Access | Credentials (ID and passcode) to authenticate and download container images from the Ripple registry (`metaco.azurecr.io`) or the client's internal repository. | Provided by Ripple during onboarding |
| Blockchain Indexers | Credentials required for specific ledgers, such as username and password for Bitcoin and its forks, or a passphrase for Stellar and Solana. | See [Indexers reference](/products/custody/v1.34/deployment/reference/indexers) |
| KMS/HSM Access | PKCS11 Login username and password (HSM crypto user credentials) required to authenticate the vault component to the key management system (KMS). | See [KMS Integration guides](/products/custody/v1.34/how-to/integrate-kms/overview) |
| External Systems | API keys and credentials for connectivity to external account providers or connected exchanges. | Provider-specific |
| Observability | OTEL Username and Password if you configure basic authentication for telemetry data transmission to the OTEL Collector. | See [Telemetry configuration](/products/custody/v1.34/deployment/reference/telemetry-configuration) |


## Management of cryptographic key material

Isolated secure components and the external key management system (KMS) manage the most critical secrets, the cryptographic keys.

1. **Blockchain account keys**: The vault uses these keys to sign transactions. The custodian generates and stores these keys securely using their preferred KMS (HSM or MPC). The system deterministically derives keys from a master seed, where applicable. Keys are stored in the database wrapped with the master seed.
2. **Notary keys**: The notary uses these keys to sign application data, authenticate messages to external components, and sign the root of the Merkle tree to secure the system state. The system generates these keys during deployment.
3. **User keys**: Users use these keys to sign user decisions (intent submissions, approvals). The platform never receives the user private key. Users store it externally in a highly secure environment (e.g., mobile phone secure enclave, YubiKey, or KMS). Users register the corresponding public key with the platform.


## Maintenance and lifecycle management

You are responsible for the ongoing maintenance and management of all core platform dependencies and infrastructure.

1. **Dependency lifecycle management**: You are fully responsible for the end-to-end deployment, backup, replication, and lifecycle management of core dependencies. This includes the PostgreSQL Database and the AMQP Message Broker (normally RabbitMQ).
2. **External secrets management**: Leveraging an external secrets manager delegates the lifecycle management of secrets to the specialized solution.
3. **TLS certificate management**: Generate and apply TLS assets (CA certificate, server certificate, and key) for all Ingress endpoints. Proactively manage these before expiration.
4. **Platform upgrades**: Long-Term Support (LTS) releases for on-premises customers occur approximately every six months and are supported for 12 months. Track API deprecations, which are announced with a minimum of one year notice for breaking changes.


## Key rotation procedures

You manage the rotation of critical cryptographic material through dedicated governance or component redeployment procedures.

| Key Type | Rotation/Maintenance Procedure | Link/Notes/Recommendations |
|  --- | --- | --- |
| User keys (for signing decisions/intents) | Lock the existing user and create a new user with the rotated public key. Users never share the user private key with the platform. | No dedicated procedure. See [Key management overview](/products/custody/v1.34/overview/key-management). |
| Notary keys | Redeploy the notary component. Rotate notary keys via a chain-of-trust process. Then follow the disaster recovery (DR) procedure to recover and rebuild the anti-rewind file (ARF). This satisfies compliance requirements (e.g., DORA). | See [Notary key rotation and migration](/products/custody/v1.34/system-management/notary-key-operation) |
| Vault keys (for signing transactions) | Not currently supported. Vault key rotation is planned for a future release, with IBM HSM on-premise support targeted first, followed by MPC. Contact Ripple for the latest roadmap. | See your KMS guide in [KMS Integration](/products/custody/v1.34/how-to/integrate-kms/overview). |
| Blockchain keys (account keys) | Achieved by on-chain address sweeping. This involves transferring funds to a new account derived from a new key. Retain access to old keys, as funds may still be sent to previous addresses. | No dedicated procedure. Blockchain-specific; coordinate with your operations team. |
| State review authority key | You can rotate this public key, critical for ARF recovery, using an update intent (`v0_SetSystemProperty`) and submitting the new key with a revision field. | See [Register the state review authority public key](/products/custody/v1.34/system-management/disaster-recovery/register-key#rotate-the-key) |
| Standard credentials (DB, MQ, External Systems) | Manage automatically using the rotation and lifecycle management features of an external secrets manager. | See [Advanced secret management](/products/custody/v1.34/how-to/integrate-kms/advanced-secret-management) |
| TLS/mTLS certificates | For mTLS-enabled deployments (Luna, BlockSafe), generate new certificates using vendor tools, update Kubernetes secrets, and perform a rolling update. | See [Certificate Rotation](/products/custody/v1.34/how-to/integrate-kms/production-best-practices#certificate-rotation) |


## Checklist: Before you proceed

### Decisions made

- [ ] **Secrets strategy**: Kubernetes Secrets (default) OR External Secrets Manager (recommended).
- [ ] **External manager**: If using external, vendor selected (HashiCorp Vault, Conjur, etc.).
- [ ] **Key rotation policy**: Rotation frequency defined for each credential category.


### Artifacts ready

**All required credentials provisioned**

| Category | Credential | Provisioned | Storage Location |
|  --- | --- | --- | --- |
| Database | PostgreSQL username/password | [ ] |  |
| Message Queue | RabbitMQ username/password | [ ] |  |
| Container Registry | Ripple registry credentials | [ ] |  |
| Container Registry | Private registry credentials (if applicable) | [ ] |  |
| KMS/HSM | PKCS#11 crypto user credentials | [ ] |  |
| Blockchain Indexers | Per-chain credentials (BTC, Stellar, etc.) | [ ] |  |
| External Systems | Exchange API keys (if applicable) | [ ] |  |
| Telemetry | OTEL collector credentials (if applicable) | [ ] |  |


**If using external secrets manager**

- [ ] Secrets manager deployed and accessible from K8s cluster
- [ ] All credentials stored in secrets manager
- [ ] Kubernetes integration configured (External Secrets Operator, etc.)


### Configuration references

- See [KMS Integration](/products/custody/v1.34/how-to/integrate-kms/overview) for key management and secrets integration.
- See [Advanced secret management](/products/custody/v1.34/how-to/integrate-kms/advanced-secret-management) for advanced topics on secrets management.


## Next step

**Next:** [Installation environment setup](/products/custody/v1.34/deployment/install/helm-charts) - For preparing your Kubernetes and Helm environment for a successful production installation.