Call for Contributions

This section needs improvements, examples and explanations.

Please take a look at the Contributing Guide for our Write Documentation.

PKI

VyOS 1.4 changed the way in how encrytion keys or certificates are stored on the system. In the pre VyOS 1.4 era, certificates got stored under /config and every service referenced a file. That made copying a running configuration from system A to system B a bit harder, as you had to copy the files and their permissions by hand.

T3642 describes a new CLI subsystem that serves as a “certstore” to all services requiring any kind of encryption key(s). In short, public and private certificates are now stored in PKCS#8 format in the regular VyOS CLI. Keys can now be added, edited, and deleted using the regular set/edit/delete CLI commands.

VyOS not only can now manage certificates issued by 3rd party Certificate Authorities, it can also act as a CA on its own. You can create your own root CA and sign keys with it by making use of some simple op-mode commands.

Don’t be afraid that you need to re-do your configuration. Key transformation is handled, as always, by our migration scripts, so this will be a smooth transition for you!

Key Generation

Certificate Authority (CA)

VyOS now also has the ability to create CAs, keys, Diffie-Hellman and other keypairs from an easy to access operational level command.

generate pki ca
Create a new CA and output the CAs public and private key on the console.
generate pki ca install <name>

Create a new CA and output the CAs public and private key on the console.

Note

In addition to the command above, the output is in a format which can be used to directly import the key into the VyOS CLI by simply copy-pasting the output from op-mode into configuration mode.

name is used for the VyOS CLI command to identify this key. This key name is then used in the CLI configuration to reference the key instance.

generate pki ca sign <ca-name>
Create a new subordinate CA and sign it using the private key referenced by ca-name.
generate pki ca sign <ca-name> install <name>

Create a new subordinate CA and sign it using the private key referenced by name.

Note

In addition to the command above, the output is in a format which can be used to directly import the key into the VyOS CLI by simply copy-pasting the output from op-mode into configuration mode.

name is used for the VyOS CLI command to identify this key. This key name is then used in the CLI configuration to reference the key instance.

Certificates

generate pki certificate
Create a new public/private keypair and output the certificate on the console.
generate pki certificate install <name>

Create a new public/private keypair and output the certificate on the console.

Note

In addition to the command above, the output is in a format which can be used to directly import the key into the VyOS CLI by simply copy-pasting the output from op-mode into configuration mode.

name is used for the VyOS CLI command to identify this key. This key name is then used in the CLI configuration to reference the key instance.

generate pki certificate self-signed
Create a new self-signed certificate. The public/private is then shown on the console.
generate pki certificate self-signed install <name>

Create a new self-signed certificate. The public/private is then shown on the console.

Note

In addition to the command above, the output is in a format which can be used to directly import the key into the VyOS CLI by simply copy-pasting the output from op-mode into configuration mode.

name is used for the VyOS CLI command to identify this key. This key name is then used in the CLI configuration to reference the key instance.

generate pki certificate sign <ca-name>
Create a new public/private keypair which is signed by the CA referenced by ca-name. The signed certificate is then output to the console.
generate pki certificate sign <ca-name> install <name>

Create a new public/private keypair which is signed by the CA referenced by ca-name. The signed certificate is then output to the console.

Note

In addition to the command above, the output is in a format which can be used to directly import the key into the VyOS CLI by simply copy-pasting the output from op-mode into configuration mode.

name is used for the VyOS CLI command to identify this key. This key name is then used in the CLI configuration to reference the key instance.

Diffie-Hellman parameters

generate pki dh

Generate a new set of DH parameters. The key size is requested by the CLI and defaults to 2048 bit.

The generated parameters are then output to the console.

generate pki dh install <name>

Generate a new set of DH parameters. The key size is requested by the CLI and defaults to 2048 bit.

Note

In addition to the command above, the output is in a format which can be used to directly import the key into the VyOS CLI by simply copy-pasting the output from op-mode into configuration mode.

name is used for the VyOS CLI command to identify this key. This key name is then used in the CLI configuration to reference the key instance.

OpenVPN

generate pki openvpn shared-secret
Genearate a new OpenVPN shared secret. The generated secred is the output to the console.
generate pki openvpn shared-secret install <name>

Genearate a new OpenVPN shared secret. The generated secred is the output to the console.

Note

In addition to the command above, the output is in a format which can be used to directly import the key into the VyOS CLI by simply copy-pasting the output from op-mode into configuration mode.

name is used for the VyOS CLI command to identify this key. This key name is then used in the CLI configuration to reference the key instance.

WireGuard

generate pki wireguard key-pair
Generate a new WireGuard public/private key portion and output the result to the console.
generate pki wireguard key-pair install <interface>

Generate a new WireGuard public/private key portion and output the result to the console.

Note

In addition to the command above, the output is in a format which can be used to directly import the key into the VyOS CLI by simply copy-pasting the output from op-mode into configuration mode.

interface is used for the VyOS CLI command to identify the WireGuard interface where this private key is to be used.

generate pki wireguard pre-shared-key
Generate a WireGuard pre-shared secret used for peers to communicate.
generate pki wireguard pre-shared-key install <peer>

Generate a WireGuard pre-shared secret used for peers to communicate.

Note

In addition to the command above, the output is in a format which can be used to directly import the key into the VyOS CLI by simply copy-pasting the output from op-mode into configuration mode.

peer is used for the VyOS CLI command to identify the WireGuard peer where this secred is to be used.

Key usage (CLI)

CA (Certificate Authority)

set pki ca <name> certificate

Add the public CA certificate for the CA named name to the VyOS CLI.

Note

When loading the certificate you need to manually strip the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- tags. Also, the certificate/key needs to be presented in a single line without line breaks (\n), this can be done using the following shell command:

$ tail -n +2 ca.pem | head -n -1 | tr -d '\n'

set pki ca <name> crl
Certificate revocation list in PEM format.
set pki ca <name> description
A human readable description what this CA is about.
set pki ca <name> private key

Add the CAs private key to the VyOS CLI. This should never leave the system, and is only required if you use VyOS as your certificate generator as mentioned above.

Note

When loading the certificate you need to manually strip the -----BEGIN KEY----- and -----END KEY----- tags. Also, the certificate/key needs to be presented in a single line without line breaks (\n), this can be done using the following shell command:

$ tail -n +2 ca.key | head -n -1 | tr -d '\n'

set pki ca <name> private password-protected
Mark the CAs private key as password protected. User is asked for the password when the key is referenced.

Server Certificate

After we have imported the CA certificate(s) we can now import and add certificates used by services on this router.

set pki certificate <name> certificate

Add public key portion for the certificate named name to the VyOS CLI.

Note

When loading the certificate you need to manually strip the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- tags. Also, the certificate/key needs to be presented in a single line without line breaks (\n), this can be done using the following shell command:

$ tail -n +2 cert.pem | head -n -1 | tr -d '\n'

set pki certificate <name> description
A human readable description what this certificate is about.
set pki certificate <name> private key

Add the private key portion of this certificate to the CLI. This should never leave the system as it is used to decrypt the data.

Note

When loading the certificate you need to manually strip the -----BEGIN KEY----- and -----END KEY----- tags. Also, the certificate/key needs to be presented in a single line without line breaks (\n), this can be done using the following shell command:

$ tail -n +2 cert.key | head -n -1 | tr -d '\n'

set pki certificate <name> private password-protected
Mark the private key as password protected. User is asked for the password when the key is referenced.
set pki certificate <name> revoke
If CA is present, this certificate will be included in generated CRLs

Operation

VyOS operational mode commands are not only available for generating keys but also to display them.

show pki ca

Show a list of installed CA certificates.

vyos@vyos:~$ show pki ca
Certificate Authorities:
Name            Subject                                                  Issuer CN          Issued               Expiry               Private Key    Parent
--------------  -------------------------------------------------------  -----------------  -------------------  -------------------  -------------  --------------
DST_Root_CA_X3  CN=ISRG Root X1,O=Internet Security Research Group,C=US  CN=DST Root CA X3  2021-01-20 19:14:03  2024-09-30 18:14:03  No             N/A
R3              CN=R3,O=Let's Encrypt,C=US                               CN=ISRG Root X1    2020-09-04 00:00:00  2025-09-15 16:00:00  No             DST_Root_CA_X3
vyos_rw         CN=VyOS RW CA,O=VyOS,L=Some-City,ST=Some-State,C=GB      CN=VyOS RW CA      2021-07-05 13:46:03  2026-07-04 13:46:03  Yes            N/A
show pki ca <name>
Show only information for specified Certificate Authority.
show pki certificates

Show a list of installed certificates

vyos@vyos:~$ show pki certificate
Certificates:
Name       Type    Subject CN             Issuer CN      Issued               Expiry               Revoked    Private Key    CA Present
---------  ------  ---------------------  -------------  -------------------  -------------------  ---------  -------------  -------------
ac2        Server  CN=ac2.vyos.net        CN=R3          2021-07-05 07:29:59  2021-10-03 07:29:58  No         Yes            Yes (R3)
rw_server  Server  CN=VyOS RW             CN=VyOS RW CA  2021-07-05 13:48:02  2022-07-05 13:48:02  No         Yes            Yes (vyos_rw)
show pki certificates <name>
Show only information for specified certificate.
show pki crl
Show a list of installed CRLs.