Nebula certificate

A Nebula certificate is the signed identity of a host: a small file, signed by the network’s certificate authority, that records the host’s name, its overlay IP addresses, and its groups. Hosts show their certificates to each other during the handshake, and a host only accepts a peer whose certificate was signed by a CA it trusts.

What’s in a certificate

A host certificate holds:

• the host’s name
• its overlay networks, meaning its IP addresses on the overlay
• its groups, which in Managed Nebula are its role and tags, so firewall rules can match on them
• its unsafe networks, the subnets it can route traffic to, for a route’s router
• its public key, the dates it’s valid between, and which CA issued it

Changing any field breaks the CA’s signature, which is why a host can’t give itself another host’s address or a role it doesn’t have. Certificates are signed with Ed25519 by default, or ECDSA P-256 on networks created with Use P-256 elliptic curve cryptography checked.

In Managed Nebula you never handle certificates yourself. When a machine enrolls, DNClient generates the key pair and Defined Networking signs the certificate. Defined Networking also issues a new certificate whenever a host’s name, role, or tags change, and rotates certificates before they expire. DNClient picks them up on its own. Blocking or deleting a host adds its certificate to the network’s blocklist. See PKI for how the pieces fit together.

Version 1 and version 2 certificates

Nebula has two certificate formats. A version 1 certificate holds a single IPv4 address. Version 2, added in Nebula 1.10, holds several IPv4 and IPv6 addresses, which is what an IPv6 overlay and a dual-stack network need. Hosts have to run a Nebula version that understands version 2 before they can use it.

In Managed Nebula the version is set per network, shown as certVersion in the API:

• Version 2: every network created since IPv6 support. These networks always have an IPv6 range, can add an IPv4 range, and can use a managed lighthouse.
• Version 1: older IPv4-only networks. They can’t use managed lighthouses.

To move a version 1 network to version 2, update every host to DNClient 0.9.3 or later and Mobile Nebula 0.10.0 or later, then click Update network on the network’s Edit network page. The network keeps its IPv4 range and gains an IPv6 range, and each host gets an IPv6 address the next time it checks in. This can’t be undone. See Managed lighthouses for the steps.

If you manage hosts through the API, hosts on version 2 networks use the newer host operations, such as Create host and Edit host. The older version 1 operations return ERR_CERT_VERSION_2_INCOMPATIBLE for them.