Aranya Documentation An overview of the Aranya project

Certificates

Since Aranya 7.0, daemons authenticate each other with mutual TLS (mTLS) when they sync over QUIC. Every daemon needs:

  • One or more trusted root CA certificates.
  • A device certificate signed by one of those CAs.
  • The device certificate’s private key.

The daemon loads these at startup and will not start if any are missing or invalid. PSK seeds, which earlier releases used to secure sync, are no longer used (see Upgrading from 6.x).

Daemon Configuration

The certificate paths are set in the [sync.quic] table of the daemon config file:

[sync.quic]
enable = true
addr = "0.0.0.0:4321"
root_certs_dir = "/etc/aranya/certs/ca"
device_cert = "/etc/aranya/certs/device.crt.pem"
device_key = "/etc/aranya/certs/device.key.pem"
  • root_certs_dir is a directory of trusted CA certificates in PEM format. Only files ending in .pem are loaded, and files ending in .key.pem are skipped. The directory must contain at least one certificate.
  • device_cert is the device’s certificate in PEM format. It may contain a certificate chain.
  • device_key is the device’s private key in PEM format (PKCS#8 or SEC1). Keep this file readable only by the daemon’s user.

The same device certificate is used both when the daemon accepts sync connections and when it connects to peers, so it must allow both server and client authentication.

The Subject Alternative Name Rule

When a daemon syncs with a peer, it uses the host part of the peer’s address as the TLS server name. The peer’s certificate must have a subject alternative name (SAN) that matches that host exactly.

In practice, each device’s certificate SAN must be the IP address or DNS name that other devices pass to add_sync_peer for that device. For example, if peers add a device as 10.0.0.5:4321, its certificate needs the IP SAN 10.0.0.5. If they add it as device1.example.com:4321, it needs the DNS SAN device1.example.com.

If the SAN doesn’t match, the TLS handshake fails and the devices can’t sync.

A certificate may have more than one SAN, for example if peers reach a device by different addresses. The handshake succeeds if any one of the SANs matches the host that was dialed. DNS SANs may also be wildcards such as *.example.com. aranya-certgen only writes a single SAN, so use your own CA if you need more.

Generating Certificates With aranya-certgen

The aranya-certgen tool creates a root CA and device certificates with P-256 ECDSA keys. Build it from the aranya repo:

$ cargo build --release -p aranya-certgen --features cli

Create a root CA once for the team. This writes ca.crt.pem and ca.key.pem:

$ aranya-certgen ca --cn "My Team CA" --output ca --days 365

Keep ca.key.pem off the devices. Anyone who has it can issue certificates that every device on the team will trust.

Create a certificate for each device. The --cn value is also written as the certificate’s only SAN, so set it to the address other devices will dial (see the SAN rule). An IP address becomes an IP SAN and anything else becomes a DNS SAN:

$ aranya-certgen signed ca --cn 10.0.0.5 --output device1 --days 365

This writes device1.crt.pem and device1.key.pem. A certificate from aranya-certgen can’t cover more than one address.

Then, on each device:

  1. Copy ca.crt.pem into the directory set as root_certs_dir.
  2. Copy the device’s .crt.pem and .key.pem files to the paths set as device_cert and device_key.
  3. Start (or restart) the daemon.

You can check a device certificate against the CA before deploying it:

$ openssl verify -CAfile ca.crt.pem device1.crt.pem
$ openssl x509 -in device1.crt.pem -noout -ext subjectAltName

Using Your Own CA

You can use certificates from an existing PKI instead of aranya-certgen. Each device certificate must:

  • Chain to a CA certificate in every peer’s root_certs_dir.
  • Have at least one SAN that follows the SAN rule. Multiple SANs are allowed. The CN is ignored.
  • Include both the serverAuth and clientAuth extended key usages.

The aranya-certgen README has an equivalent openssl command.

Renewing and Rotating Certificates

Certificates generated by aranya-certgen are valid for 365 days by default. Plan to renew them before they expire. Once a certificate expires, peers reject its TLS handshakes and the device stops syncing.

The daemon reads certificates only at startup. After replacing any certificate or key, restart the daemon.

To renew a device certificate, issue a new one from the same CA, copy it into place and restart the daemon. Peers that trust the CA accept it without any change on their side.

To rotate the CA without an outage:

  1. Create the new CA with a different output prefix, so the old one isn’t overwritten.
  2. Add the new CA certificate to every device’s root_certs_dir, next to the old one, and restart each daemon.
  3. Issue new device certificates from the new CA, deploy them and restart each daemon.
  4. Remove the old CA certificate from every root_certs_dir and restart each daemon.

Limitations

  • No revocation. The daemon doesn’t check certificate revocation lists. Removing a device from the team doesn’t stop its certificate from completing a TLS handshake with other devices. Policy rejects any new commands from the removed device, but until its certificate expires it can still connect to peers and sync the team’s graph. To cut a device off completely, rotate the CA and leave that device out.
  • One certificate per daemon. A daemon presents the same certificate for every team it belongs to.

Upgrading from 6.x

In 6.x, the team owner generated a PSK seed and shared it with each new device out of band. In 7.x:

  • The PSK seed APIs (CreateTeamQuicSyncConfig, AddTeamQuicSyncConfig, seed_ikm, wrapped_seed, gen_seed, encrypt_psk_seed_for_peer and their C equivalents) are deprecated and do nothing. Remove them from your application.
  • AddTeamConfig only needs the team ID.
  • Every daemon config needs root_certs_dir, device_cert and device_key in [sync.quic], and every device needs a certificate as described above.