1ovs-pki(8) Open vSwitch Manual ovs-pki(8)
2
6 ovs-pki - OpenFlow public key infrastructure management utility
7
10 Each command takes the form:
11 ovs-pki [options] command [args]
13 The implemented commands and their arguments are:
15 ovs-pki init
16 ovs-pki req name
17 ovs-pki sign name [type]
18 ovs-pki req+sign name [type]
19 ovs-pki verify name [type]
20 ovs-pki fingerprint file
21 ovs-pki self-sign name
22 Each type above is a certificate type, either switch (default) or con‐
24 troller.
25 The available options are:
27 [-k type | --key=type]
28 [-B nbits | --bits=nbits]
29 [-D file | --dsaparam=file]
30 [-b | --batch]
31 [-f | --force]
32 [-d dir | --dir=dir]
33 [-l file | --log=file]
34 [-u | --unique]
35 [-h | --help]
36 Some options do not apply to every command.
38
41 The ovs-pki program sets up and manages a public key infrastructure for
42 use with OpenFlow. It is intended to be a simple interface for organi‐
43 zations that do not have an established public key infrastructure.
44 Other PKI tools can substitute for or supplement the use of ovs-pki.
45 ovs-pki uses openssl(1) for certificate management and key generation.
47
50 The following ovs-pki commands support manual PKI administration:
51 init Initializes a new PKI (by default in directory /var/lib/open‐
54 vswitch/pki) and populates it with a pair of certificate author‐
55 ities for controllers and switches.
56 This command should ideally be run on a high-security machine
58 separate from any OpenFlow controller or switch, called the CA
59 machine. The files pki/controllerca/cacert.pem and
60 pki/switchca/cacert.pem that it produces will need to be copied
61 over to the OpenFlow switches and controllers, respectively.
62 Their contents may safely be made public.
63 By default, ovs-pki generates 2048-bit RSA keys. The -B or
65 --bits option (see below) may be used to override the key
66 length. The -k dsa or --key=dsa option may be used to use DSA
67 in place of RSA. If DSA is selected, the dsaparam.pem file gen‐
68 erated in the new PKI hierarchy must be copied to any machine on
69 which the req command (see below) will be executed. Its con‐
70 tents may safely be made public.
71 Other files generated by init may remain on the CA machine. The
73 files pki/controllerca/private/cakey.pem and pki/switchca/pri‐
74 vate/cakey.pem have particularly sensitive contents that should
75 not be exposed.
76 req name
79 Generates a new private key named name-privkey.pem and corre‐
80 sponding certificate request named name-req.pem. The private
81 key can be intended for use by a switch or a controller.
82 This command should ideally be run on the switch or controller
84 that will use the private key to identify itself. The file
85 name-req.pem must be copied to the CA machine for signing with
86 the sign command (below).
87 This command will output a fingerprint to stdout as its final
89 step. Write down the fingerprint and take it to the CA machine
90 before continuing with the sign step.
91 When RSA keys are in use (as is the default), req, unlike the
93 rest of ovs-pki's commands, does not need access to a PKI hier‐
94 archy created by ovs-pki init. The -B or --bits option (see
95 below) may be used to specify the number of bits in the gener‐
96 ated RSA key.
97 When DSA keys are used (as specified with --key=dsa), req needs
99 access to the dsaparam.pem file created as part of the PKI hier‐
100 archy (but not to other files in that tree). By default,
101 ovs-pki looks for this file in /var/lib/open‐
102 vswitch/pki/dsaparam.pem, but the -D or --dsaparam option (see
103 below) may be used to specify an alternate location.
104 name-privkey.pem has sensitive contents that should not be
106 exposed. name-req.pem may be safely made public.
107 sign name [type]
110 Signs the certificate request named name-req.pem that was pro‐
111 duced in the previous step, producing a certificate named
112 name-cert.pem. type, either switch (default) or controller,
113 indicates the use for which the key is being certified.
114 This command must be run on the CA machine.
116 The command will output a fingerprint to stdout and request that
118 you verify that it is the same fingerprint output by the req
119 command. This ensures that the request being signed is the same
120 one produced by req. (The -b or --batch option suppresses the
121 verification step.)
122 The file name-cert.pem will need to be copied back to the switch
124 or controller for which it is intended. Its contents may safely
125 be made public.
126 req+sign name [type]
129 Combines the req and sign commands into a single step, out‐
130 putting all the files produced by each. The name-privkey.pem
131 and name-cert.pem files must be copied securely to the switch or
132 controller. name-privkey.pem has sensitive contents and must
133 not be exposed in transit. Afterward, it should be deleted from
134 the CA machine.
135 This combined method is, theoretically, less secure than the
137 individual steps performed separately on two different machines,
138 because there is additional potential for exposure of the pri‐
139 vate key. However, it is also more convenient.
140 verify name [type]
143 Verifies that name-cert.pem is a valid certificate for the given
144 type of use, either switch (default) or controller. If the cer‐
145 tificate is valid for this use, it prints the message
146 ``name-cert.pem: OK''; otherwise, it prints an error message.
147 fingerprint file
150 Prints the fingerprint for file. If file is a certificate, then
151 this is the SHA-1 digest of the DER encoded version of the cer‐
152 tificate; otherwise, it is the SHA-1 digest of the entire file.
153 self-sign name
156 Signs the certificate request named name-req.pem using the pri‐
157 vate key name-privkey.pem, producing a self-signed certificate
158 named name-cert.pem. The input files should have been produced
159 with ovs-pki req.
160 Some controllers accept such self-signed certificates.
162
165 -k type
166 --key=type
167 For the init command, sets the public key algorithm to use for
168 the new PKI hierarchy. For the req and req+sign commands, sets
169 the public key algorithm to use for the key to be generated,
170 which must match the value specified on init. With other com‐
171 mands, the value has no effect.
172 The type may be rsa (the default) or dsa.
174 -B nbits
177 --bits=nbits
178 Sets the number of bits in the key to be generated. When RSA
179 keys are in use, this option affects only the init, req, and
180 req+sign commands, and the same value should be given each time.
181 With DSA keys are in use, this option affects only the init com‐
182 mand.
183 The value must be at least 1024. The default is 2048.
185 -D file
188 --dsaparam=file
189 Specifies an alternate location for the dsaparam.pem file
190 required by the req and req+sign commands. This option affects
191 only these commands, and only when DSA keys are used.
192 The default is dsaparam.pem under the PKI hierarchy.
194 -b
197 --batch
198 Suppresses the interactive verification of fingerprints that the
199 sign command by default requires.
200 -d dir
203 --dir=dir
204 Specifies the location of the PKI hierarchy to be used or cre‐
205 ated by the command (default: /var/lib/openvswitch/pki). All
206 commands, except req, need access to a PKI hierarchy.
207 -f
210 --force
211 By default, ovs-pki will not overwrite existing files or direc‐
212 tories. This option overrides this behavior.
213 -l file
216 --log=file
217 Sets the log file to file. Default: /var/log/open‐
218 vswitch/ovs-pki.log.
219 -u
222 --unique
223 Changes the format of the certificate's Common Name (CN) field;
224 by default, this field has the format "<name> id:<uuid-or-
225 date>", this option causes the provided name to be treated as
226 unique and changes the format of the CN field to be simply
227 "<name>".
228 -h
231 --help Prints a help usage message and exits.
232Open vSwitch 2.10.1 ovs-pki(8)