diff options
| -rw-r--r-- | docs/configuration/pki/index.rst | 109 | ||||
| -rw-r--r-- | docs/configuration/system/login.rst | 12 |
2 files changed, 110 insertions, 11 deletions
diff --git a/docs/configuration/pki/index.rst b/docs/configuration/pki/index.rst index e1d0fe35..cd47e43f 100644 --- a/docs/configuration/pki/index.rst +++ b/docs/configuration/pki/index.rst @@ -1,4 +1,4 @@ -:lastproofread: 1970-01-01 +:lastproofread: 2021-09-01 .. include:: /_include/need_improvement.txt @@ -6,14 +6,21 @@ PKI ### -VyOS 1.4 changed the way in how encrytions keys/certificates are stored on the -running system. In the pre VyOS 1.4 era, certificates got stored under /config -ans 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. +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. -VyOS 1.4 comes with a new approach where the keys are stored on the CLI and are -simply referenced by their name. +: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 @@ -156,8 +163,90 @@ WireGuard ``peer`` is used for the VyOS CLI command to identify the WireGuard peer where this secred is to be used. -Configuration -============= +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 Operation ========= diff --git a/docs/configuration/system/login.rst b/docs/configuration/system/login.rst index 09b6e68b..89ef7e2f 100644 --- a/docs/configuration/system/login.rst +++ b/docs/configuration/system/login.rst @@ -74,6 +74,14 @@ The third part is simply an identifier, and is for your own reference. .. note:: You can assign multiple keys to the same user by using a unique identifier per SSH key. +.. cfgcmd:: set system login user <username> authentication public-keys + <identifier> options <options> + + Set the options for this public key. See the ssh ``authorized_keys`` man page + for details of what you can specify here. To place a ``"`` character in the + options field, use ``"``, for example ``from="10.0.0.0/24"`` + to restrict where the user may connect from when using this key. + .. cfgcmd:: loadkey <username> <location> **Deprecation notice:** ``loadkey`` has been deprecated in favour of @@ -96,12 +104,14 @@ Example ------- In the following example, both `User1` and `User2` will be able to SSH into -VyOS as user ``vyos`` using their very own keys. +VyOS as user ``vyos`` using their very own keys. `User1` is restricted to only +be able to connect from a single IP address. .. code-block:: none set system login user vyos authentication public-keys 'User1' key "AAAAB3Nz...KwEW" set system login user vyos authentication public-keys 'User1' type ssh-rsa + set system login user vyos authentication public-keys 'User1' options "from="192.168.0.100"" set system login user vyos authentication public-keys 'User2' key "AAAAQ39x...fbV3" set system login user vyos authentication public-keys 'User2' type ssh-rsa |