1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
|
:lastproofread: 2021-09-01
.. 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 <name> install
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 pre-shared-key
Generate a WireGuard pre-shared secret used for peers to communicate.
.. opcmd:: 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)
--------------------------
.. 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'H``
.. 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'H``
.. 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'H``
.. 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'H``
.. 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
=========
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 certificates
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 crl
Show a list of installed :abbr:`CRLs (Certificate Revocation List)`.
|
