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

pki.cert​

Required Reloadable
note

A new certificate will only take effect after a reload if the IP address has not changed, but all other properties of the certificate can be changed.

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

pki.disconnect_invalid​

Default: False Reloadable

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

pki.initiating_version​

Default: 0 Added in v1.10.0

pki.initiating_version determines which nebula cert version to use when initiating new connections. This setting only applies if both a v1 and a v2 certificate are configured, in which case it will default to 1. Once all hosts in the mesh are configured with both a v1 and v2 certificate then this will default 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.