Certificates

Certificates

Brane uses X.509 certificates for mutual TLS authentication between nodes. Each worker domain has its own certificate authority (CA) and issues certificates to verify identity during data transfers.

Certificate Types

Certificate	Purpose	Generated By
CA certificate (ca.pem)	Root of trust for a domain	branectl generate certs
Server certificate (server.pem)	Proves domain identity to incoming connections	branectl generate certs server
Client certificate (client-id.pem)	Proves identity when connecting to another domain	branectl generate certs client

Generating Server Certificates

Every worker node needs a CA and server certificate. Generate both at once:

branectl generate certs -f -p ./config/certs server <LOCATION_ID> -H <HOSTNAME>

Parameters:

• <LOCATION_ID> — Your domain’s unique identifier
• <HOSTNAME> — The hostname other nodes use to reach you

Example:

branectl generate certs -f -p ./config/certs server hospital-a -H hospital-a.example.com

This creates:

• ./config/certs/ca.pem — Your CA certificate (share with the central node)
• ./config/certs/server.pem — Your server certificate (keep private)

Note

Certificate generation uses cfssl, which branectl downloads automatically. A checksum is verified to ensure the binary’s integrity.

Generating Client Certificates

Client certificates allow one domain to authenticate to another when downloading data. Generate them from the domain that will be receiving the connection:

cd ./config/certs
branectl generate certs client <CLIENT_LOCATION_ID> -H <CLIENT_HOSTNAME> -f -p ./client-certs

Caution

Always use the -f -p ./client-certs flags to write client certificates to a subdirectory. Generating client certificates in the same folder as server certificates will overwrite the ca.pem file.

Example: Domain hospital-a generates a client certificate for hospital-b:

branectl generate certs client hospital-b -H 192.0.2.2 -f -p ./client-certs

Share the resulting ca.pem and client-id.pem files with hospital-b.

Distributing Certificates

Central Node

The central node needs each worker’s CA certificate:

1. Receive ca.pem from each worker
2. Create a directory per worker in ./config/certs/
3. Place each worker’s ca.pem in the corresponding directory

mkdir -p ./config/certs/hospital-a
cp hospital-a-ca.pem ./config/certs/hospital-a/ca.pem

Worker Nodes

Workers that need to exchange data with other workers need client certificates from those domains:

mkdir -p ./config/certs/hospital-b
cp hospital-b-ca.pem ./config/certs/hospital-b/ca.pem
cp hospital-b-client-id.pem ./config/certs/hospital-b/client-id.pem

Certificate Security

• Keep server certificates and private keys secure. Never share them.
• Share only ca.pem files with the central node.
• Client certificates grant access. Treat them like passwords. If a client certificate is compromised, revoke the user’s permissions through the policy system rather than regenerating all certificates.
• Rotate certificates periodically for production deployments.

Troubleshooting

“Certificate verification failed”

• Ensure the ca.pem in the central node’s cert directory matches the worker’s CA
• Verify that the hostname in the certificate matches the actual hostname

“No client certificate found”

• Check that client certificates are in the correct directory under config/certs/<domain_id>/
• Verify file names are exactly ca.pem and client-id.pem