Skip to main content

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-----

A CA certificate that this version of Nebula does not support, such as one from a newer certificate version or with an unknown curve, is skipped with a warning instead of failing the whole bundle. Expired CA certificates are logged with a warning. Nebula refuses to start, or fails the reload, only when no valid CA certificate remains.

pki.cert​

Required Reloadable
note

A new certificate takes effect on reload as long as its networks and curve match the running certificate. All other properties of the certificate can be changed. A certificate with different networks or a different curve, or removing a v2 certificate whose networks differ from the remaining v1 certificate, is refused until Nebula is restarted.

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. A certificate that this version of Nebula does not support, such as one from a newer certificate version, is skipped with a warning, so a bundle prepared for a future upgrade can be deployed ahead of time. Nebula refuses to start only if no usable certificate remains.

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. Entries are not case sensitive. An entry that is not a 64 character hex fingerprint fails startup. On reload the valid entries are still applied, but the reload is reported as failed.

Tunnels to a blocklisted host are always torn down, regardless of pki.disconnect_invalid. Handshakes from blocklisted hosts are logged at the debug level and counted in the handshake_manager.rejected.blocklisted metric.

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, and setting it to 1 without a v1 certificate is an error.

The default does not change on its own. 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.