Skip to main content
Learn how to rotate leaf certificates and encryption keys in the Halo Cross-Media Measurement System. Rotation limits the risk of compromise by regularly changing cryptographic materials.

​
Background

The Halo CMMS uses asymmetric cryptography for secure communication and data protection:
  • X.509 certificates for Transport Layer Security (TLS) and digital signatures
  • Hybrid encryption for encrypting sensitive data
Each scheme has a public component (presented to recipients) and a private component (kept secret by the sender).

​
Certificate Trust Model

The CMMS uses a private Certificate Authority (CA) model:
1

Root certificates

Each entity operates their own private CA with a self-signed root certificate:
  • Very long validity period (e.g., 10 years)
  • Exchanged out-of-band between entities
  • Private key must be kept extremely secure
Root Certificate SecurityRoot certificates are very difficult to rotate. The private key should be managed by a CA service such as:
  • Google Cloud Certificate Authority Service
  • AWS Private CA
Never use OpenSSL as a CA in production - it’s only suitable for testing.
2

Certificate chains

The path from a leaf certificate to a trusted root is called a certificate chain. Validation includes:
  • Verifying the chain to a trust anchor
  • Checking the validity period (not expired)
  • Determining revocation status
3

Server TLS

For server TLS:
  • Server presents its certificate to the client
  • Server proves ownership via private key
  • Client verifies the certificate is signed by a trusted root
  • Client checks hostname matches Subject Alternative Name (SAN)
4

Mutual TLS (mTLS)

For mutual TLS (client authentication):
  • Client additionally presents its own certificate
  • Server verifies it’s signed by a trusted root
  • Server uses the Authority Key Identifier (AKID) to map the certificate to the client’s identity

​
Asymmetric Encryption

For hybrid encryption:
  1. Sender encrypts data using the recipient’s public key
  2. Recipient decrypts data using their private key

​
TLS Certificate Rotation

Rotate the certificate presented by the server (server TLS) or client (client TLS).

​
Kubernetes Secret Update

In Kubernetes deployments, TLS certificates are stored in Secret resources.
1

Update certificate files

Overwrite the certificate and matching private key files in your Kustomization directory.
2

Apply changes

Run kubectl apply to update the Secret in your cluster:
kubectl apply -k path/to/kustomization
See the update guide for more information on managing Kustomization directories.

​
API Certificate Rotation

Rotating certificates used within the Halo public API requires two steps:
1

Register new Certificate resource

Create a new Certificate resource by calling the CreateCertificate method:
# Example using CLI tools
./create-certificate \
  --parent=dataProviders/abc123 \
  --certificate-file=new_cert.pem
2

Update PublicKey sub-resource

If the parent resource has a PublicKey sub-resource, update it to reference the new Certificate:
  1. Sign the EncryptionPublicKey with the new certificate’s private key
  2. Call the UpdatePublicKey method with the signed key
You can rotate the encryption public key at the same time. See Encryption Public Key Rotation.

​
CLI Tools

Use the MeasurementSystem and EncryptionPublicKeys CLI tools to assist with certificate rotation.

​
Encryption Public Key Rotation

Rotate encryption keys by calling the UpdatePublicKey method.
1

Generate new encryption key pair

Create a new hybrid encryption key pair using your cryptographic library.
2

Sign the public key

Generate a signature for the new encryption public key using the private key that matches your Certificate resource.
3

Update via API

Call UpdatePublicKey with the new signed encryption public key.
Use the MeasurementSystem and EncryptionPublicKeys CLI tools to streamline this process.

​
Handling Compromise

If a certificate or encryption key has been compromised, simple rotation is not sufficient. Additional mitigation steps are required.

​
Certificate Compromise

Impact: All digital signatures using the compromised certificate must be considered invalid. This is similar to certificate expiration.
For example, Measurement results utilizing the compromised certificate can no longer be trusted. New Measurements may need to be created to obtain trustable results.

​
Mitigation Steps

1

Revoke the certificate

Prevents use of the certificate for anything new:
  1. Update the Certificate resource revocation status
  2. Call the RevokeCertificate method
# Example revocation
./revoke-certificate \
  --name=dataProviders/abc123/certificates/xyz789 \
  --revocation-state=REVOKED
2

Rotate to new certificate

Follow the API Certificate Rotation steps to deploy a new certificate.
3

Assess impact

Determine which data and operations were signed with the compromised certificate and take appropriate action.

​
Encryption Key Compromise

Impact: All data encrypted with the compromised key is no longer private to the intended recipient.

​
Mitigation Steps

1

Re-encrypt data with new key

For example, if a MeasurementConsumer key was compromised:
  • Request that DataProviders re-encrypt any EventGroup metadata
  • Update all ongoing measurements to use the new key
2

Limit access to ciphertexts

For immutable encrypted data (e.g., RequisitionSpec or Measurement.Result):
  • Further restrict access to the encrypted data
  • Consider deleting the data based on risk assessment
  • Contact the Kingdom operator to delete Measurements using the internal API if necessary

​
Rotation Best Practices

Regular Rotation Schedule
  • Establish a regular rotation schedule (e.g., every 90 days for certificates, every 30 days for encryption keys)
  • Automate rotation where possible
  • Maintain an audit trail of all rotations
  • Test rotation procedures in non-production environments first
Planning for Rotation
  • Ensure all parties have updated trust stores before rotating
  • Coordinate rotation windows with all participants
  • Have rollback procedures ready
  • Monitor for authentication failures after rotation

Build docs developers (and LLMs) love

Get started for freeTalk to us