pki

Defines the path of each file required for a Nebula host: CA certificate, host certificate, and host key. Each of these files can also be stored inline as YAML multiline strings.

pki:
  ca: /etc/nebula/ca.crt
  cert: /etc/nebula/host.crt
  key: /etc/nebula/host.key
  blocklist:
    - c99d4e650533b92061b09918e838a5a0a6aaee21eed1d12fd937682865936c72

pki.ca

Required Reloadable

The ca is a collection of one or more certificate authorities this host should trust. In the above example, /etc/nebula/ca.crt contains PEM-encoded data for each CA we should trust, concatenated into a single file. The following example shows a CA cert inlined as a YAML multiline string.

pki:
  ca: |
    -----BEGIN NEBULA CERTIFICATE-----
    CkgKFlRoZSBPbmUtSG91ciBOZWJ1bGEgQ0Eo/pL7jAYwjq/7jAY6IDIi7yqkRV9F
    1+tozxvnHCmuuuwdArt7YbMMdCR4AYm/QAESQHBitbcetbJ06RQckqGi+hXJXd/U
    TXKEul4TxP4Qxmd7g+cHDE6oYZhRwup+1xg/Sv9bMg2E2/LNXKV3rNf1Yw8=
    -----END NEBULA CERTIFICATE-----

CA certificates that this version of Nebula does not support, such as one from a newer certificate version, are skipped.

pki.cert

Required Reloadable

Note

A new certificate takes effect on reload as long as its networks and curve match the running certificate of the same version. All other properties of the certificate can be changed. Adding a certificate of the other version also works on reload, but networks it adds are not used until Nebula restarts. Removing the v2 certificate only works on reload when the remaining v1 certificate has the same networks.

The cert is a certificate unique to every host on a Nebula network. The certificate identifies a host’s IP address, name, and group membership within a Nebula network. The certificate is signed by a certificate authority when created, which informs other hosts on whether to trust a particular host certificate.

pki.cert may contain one v1 and one v2 certificate. Certificates that this version of Nebula does not support are skipped, so a bundle prepared for a future upgrade can be deployed ahead of time.

pki.key

Required Reloadable

The key is a private key unique to every host on a Nebula network. It is used in conjunction with the host certificate to prove a host’s identity to other members of the Nebula network. The private key should never be shared with other hosts.

PKCS11 support

Added in v1.10

It is possible to use a PKCS11 URL as a reference to your private key, like in this example:

pki:
  key: 'pkcs11:id=1234;object=nebula%20key?module-path=/usr/lib64/pkcs11/my-module.so&pin-source=/path/to/pin-file'
  # or, you can specify the pin directly
  # key: "pkcs11:id=1234;object=nebula%20key?module-path=/usr/lib64/pkcs11/my-module.so&pin-value=1234"

In order to use PKCS11 with Nebula, a few pre-requisites must be met.

• nebula must be built from source, with the cgo and pkcs11 tags. make bin-pkcs11 will accomplish this for you.
• Today, only P256 is supported with PKCS11. You cannot use Nebula's default Curve25519.
• Your key must be able to be uniquely identified via the id and object parameters of the PKCS11 URL.
• Your key's CKA_DERIVE attribute must be CK_TRUE
• Derivations must be possible via the CKM_ECDH1_DERIVE mechanism
• Your HSM must permit the output of the derivation to be extracted (CKA_EXTRACTABLE == CK_TRUE). Nebula is not capable of using the HSM for symmetric cryptography, and we do not plan to add support for this.

Note

Why is Curve25519 not supported?

If you're using PKCS11, it's probably because you need to be NIST compliant, and if you need to be NIST compliant, you (at time of writing) cannot use Curve25519 for key agreement. Even if you aren't bound by this restriction, your HSM likely is. If you have the need for Curve25519, PKCS11, and Nebula, please get in touch and we can discuss adding support!

pki.blocklist

Reloadable

Note

The blocklist is not distributed via lighthouses. To ensure access to your entire network is blocked you must distribute the full blocklist to every host in your network. This is typically done via tooling such as Ansible, Chef, or Puppet.

The blocklist contains a list of individual hosts' certificate fingerprints which should be blocked even if the certificate is otherwise valid (signed by a trusted CA and unexpired.) This should be used if a host's credentials are stolen or compromised.

Each entry is the hex SHA-256 fingerprint shown by nebula-cert print. Tunnels to a blocklisted host are always torn down, regardless of pki.disconnect_invalid. Rejected handshakes are counted in the handshake_manager.rejected.blocklisted metric.

Since v1.12.0, an entry that isn't a hex SHA-256 fingerprint stops Nebula from starting, and fails a reload. The valid entries in a failed reload are still blocked.

pki.disconnect_invalid

Default: true Reloadable

disconnect_invalid is a toggle to force a client to be disconnected if the certificate is expired or invalid.

pki.initiating_version

Default: 1 with a v1 certificate, otherwise 2 Reloadable Added in v1.10.0

pki.initiating_version determines which nebula cert version to use when initiating new connections. Valid values are 1 and 2. This setting only matters if both a v1 and a v2 certificate are configured, in which case it defaults to 1. If only a v2 certificate is configured it defaults to 2.

Once all hosts in the mesh are configured with both a v1 and v2 certificate, set it to 2. After all hosts in the mesh are using a v2 certificate then v1 certificates are no longer needed.

In most instances this config option should not be needed, as Nebula will automatically select the correct certificate version to use.