mirror of
https://github.com/vyos/vyos-documentation.git
synced 2025-10-26 08:41:46 +01:00
337 lines
11 KiB
ReStructuredText
337 lines
11 KiB
ReStructuredText
:lastproofread: 2024-01-05
|
|
|
|
.. include:: /_include/need_improvement.txt
|
|
|
|
###
|
|
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.
|
|
|
|
:vytask:`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.
|
|
|
|
.. opcmd:: generate pki ca
|
|
|
|
Create a new :abbr:`CA (Certificate Authority)` and output the CAs public and
|
|
private key on the console.
|
|
|
|
.. opcmd:: generate pki ca install <name>
|
|
|
|
Create a new :abbr:`CA (Certificate Authority)` and output the CAs public and
|
|
private key on the console.
|
|
|
|
.. include:: pki_cli_import_help.txt
|
|
|
|
.. opcmd:: generate pki ca sign <ca-name>
|
|
|
|
Create a new subordinate :abbr:`CA (Certificate Authority)` and sign it using
|
|
the private key referenced by `ca-name`.
|
|
|
|
.. opcmd:: generate pki ca sign <ca-name> install <name>
|
|
|
|
Create a new subordinate :abbr:`CA (Certificate Authority)` and sign it using
|
|
the private key referenced by `name`.
|
|
|
|
.. include:: pki_cli_import_help.txt
|
|
|
|
Certificates
|
|
------------
|
|
|
|
.. opcmd:: generate pki certificate
|
|
|
|
Create a new public/private keypair and output the certificate on the console.
|
|
|
|
.. opcmd:: generate pki certificate install <name>
|
|
|
|
Create a new public/private keypair and output the certificate on the console.
|
|
|
|
.. include:: pki_cli_import_help.txt
|
|
|
|
.. opcmd:: generate pki certificate self-signed
|
|
|
|
Create a new self-signed certificate. The public/private is then shown on the
|
|
console.
|
|
|
|
.. opcmd:: generate pki certificate self-signed install <name>
|
|
|
|
Create a new self-signed certificate. The public/private is then shown on the
|
|
console.
|
|
|
|
.. include:: pki_cli_import_help.txt
|
|
|
|
.. opcmd:: 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.
|
|
|
|
.. opcmd:: 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.
|
|
|
|
.. include:: pki_cli_import_help.txt
|
|
|
|
Diffie-Hellman parameters
|
|
-------------------------
|
|
|
|
.. opcmd:: generate pki dh
|
|
|
|
Generate a new set of :abbr:`DH (Diffie-Hellman)` parameters. The key size
|
|
is requested by the CLI and defaults to 2048 bit.
|
|
|
|
The generated parameters are then output to the console.
|
|
|
|
.. opcmd:: generate pki dh install <name>
|
|
|
|
Generate a new set of :abbr:`DH (Diffie-Hellman)` parameters. The key size
|
|
is requested by the CLI and defaults to 2048 bit.
|
|
|
|
.. include:: pki_cli_import_help.txt
|
|
|
|
OpenVPN
|
|
-------
|
|
|
|
.. opcmd:: generate pki openvpn shared-secret
|
|
|
|
Genearate a new OpenVPN shared secret. The generated secred is the output to
|
|
the console.
|
|
|
|
.. opcmd:: generate pki openvpn shared-secret install <name>
|
|
|
|
Genearate a new OpenVPN shared secret. The generated secred is the output to
|
|
the console.
|
|
|
|
.. include:: pki_cli_import_help.txt
|
|
|
|
WireGuard
|
|
---------
|
|
|
|
.. opcmd:: generate pki wireguard key-pair
|
|
|
|
Generate a new WireGuard public/private key portion and output the result to
|
|
the console.
|
|
|
|
.. opcmd:: 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.
|
|
|
|
.. opcmd:: generate pki wireguard preshared-key
|
|
|
|
Generate a WireGuard pre-shared secret used for peers to communicate.
|
|
|
|
.. opcmd:: generate pki wireguard preshared-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)
|
|
--------------------------
|
|
|
|
.. cfgcmd:: 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'``
|
|
|
|
.. cfgcmd:: set pki ca <name> crl
|
|
|
|
Certificate revocation list in PEM format.
|
|
|
|
.. cfgcmd:: set pki ca <name> description
|
|
|
|
A human readable description what this CA is about.
|
|
|
|
.. cfgcmd:: 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'``
|
|
|
|
.. cfgcmd:: 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.
|
|
|
|
.. cfgcmd:: 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'``
|
|
|
|
.. cfgcmd:: set pki certificate <name> description
|
|
|
|
A human readable description what this certificate is about.
|
|
|
|
.. cfgcmd:: 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'``
|
|
|
|
.. cfgcmd:: 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.
|
|
|
|
.. cfgcmd:: set pki certificate <name> revoke
|
|
|
|
If CA is present, this certificate will be included in generated CRLs
|
|
|
|
ACME
|
|
^^^^
|
|
|
|
The VyOS PKI subsystem can also be used to automatically retrieve Certificates
|
|
using the :abbr:`ACME (Automatic Certificate Management Environment)` protocol.
|
|
|
|
.. cfgcmd:: set pki certificate <name> acme domain-name <name>
|
|
|
|
Domain names to apply, multiple domain-names can be specified.
|
|
|
|
This is a mandatory option
|
|
|
|
.. cfgcmd:: set pki certificate <name> acme email <address>
|
|
|
|
Email used for registration and recovery contact.
|
|
|
|
This is a mandatory option
|
|
|
|
.. cfgcmd:: set pki certificate <name> acme listen-address <address>
|
|
|
|
The address the server listens to during http-01 challenge
|
|
|
|
.. cfgcmd:: set pki certificate <name> acme rsa-key-size <2048 | 3072 | 4096>
|
|
|
|
Size of the RSA key.
|
|
|
|
This options defaults to 2048
|
|
|
|
.. cfgcmd:: set pki certificate <name> acme url <url>
|
|
|
|
ACME Directory Resource URI.
|
|
|
|
This defaults to https://acme-v02.api.letsencrypt.org/directory
|
|
|
|
.. note:: During initial deployment we recommend using the staging API
|
|
of LetsEncrypt to prevent and blacklisting of your system. The API
|
|
endpoint is https://acme-staging-v02.api.letsencrypt.org/directory
|
|
|
|
Operation
|
|
=========
|
|
|
|
VyOS operational mode commands are not only available for generating keys but
|
|
also to display them.
|
|
|
|
.. opcmd:: show pki ca
|
|
|
|
Show a list of installed :abbr:`CA (Certificate Authority)` certificates.
|
|
|
|
.. code-block:: none
|
|
|
|
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
|
|
|
|
.. opcmd:: show pki ca <name>
|
|
|
|
Show only information for specified Certificate Authority.
|
|
|
|
.. opcmd:: show pki certificate
|
|
|
|
Show a list of installed certificates
|
|
|
|
.. code-block:: none
|
|
|
|
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)
|
|
|
|
.. opcmd:: show pki certificate <name>
|
|
|
|
Show only information for specified certificate.
|
|
|
|
.. opcmd:: show pki crl
|
|
|
|
Show a list of installed :abbr:`CRLs (Certificate Revocation List)`.
|
|
|
|
.. opcmd:: renew certbot
|
|
|
|
Manually trigger certificate renewal. This will be done twice a day.
|