1ovs-pki(8)                    Open vSwitch Manual                   ovs-pki(8)
2
3
4

NAME

6       ovs-pki - OpenFlow public key infrastructure management utility
7
8

SYNOPSIS

10       Each command takes the form:
11
12       ovs-pki [options] command [args]
13
14       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
23       Each  type above is a certificate type, either switch (default) or con‐
24       troller.
25
26       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       [-h | --help]
35
36       Some options do not apply to every command.
37
38

DESCRIPTION

40       The ovs-pki program sets up and manages a public key infrastructure for
41       use with OpenFlow.  It is intended to be a simple interface for organi‐
42       zations that do not have  an  established  public  key  infrastructure.
43       Other PKI tools can substitute for or supplement the use of ovs-pki.
44
45       ovs-pki uses openssl(1) for certificate management and key generation.
46
47

OFFLINE COMMANDS

49       The following ovs-pki commands support manual PKI administration:
50
51
52       init   Initializes  a  new  PKI (by default in directory /var/lib/open‐
53              vswitch/pki) and populates it with a pair of certificate author‐
54              ities for controllers and switches.
55
56              This  command  should  ideally be run on a high-security machine
57              separate from any OpenFlow controller or switch, called  the  CA
58              machine.      The    files    pki/controllerca/cacert.pem    and
59              pki/switchca/cacert.pem that it produces will need to be  copied
60              over  to  the  OpenFlow  switches and controllers, respectively.
61              Their contents may safely be made public.
62
63              By default, ovs-pki generates 2048-bit  RSA  keys.   The  -B  or
64              --bits  option  (see  below)  may  be  used  to override the key
65              length.  The -k dsa or --key=dsa option may be used to  use  DSA
66              in place of RSA.  If DSA is selected, the dsaparam.pem file gen‐
67              erated in the new PKI hierarchy must be copied to any machine on
68              which  the  req  command (see below) will be executed.  Its con‐
69              tents may safely be made public.
70
71              Other files generated by init may remain on the CA machine.  The
72              files  pki/controllerca/private/cakey.pem  and pki/switchca/pri‐
73              vate/cakey.pem have particularly sensitive contents that  should
74              not be exposed.
75
76
77       req name
78              Generates  a  new  private key named name-privkey.pem and corre‐
79              sponding certificate request named  name-req.pem.   The  private
80              key can be intended for use by a switch or a controller.
81
82              This  command  should ideally be run on the switch or controller
83              that will use the private key  to  identify  itself.   The  file
84              name-req.pem  must  be copied to the CA machine for signing with
85              the sign command (below).
86
87              This command will output a fingerprint to stdout  as  its  final
88              step.   Write down the fingerprint and take it to the CA machine
89              before continuing with the sign step.
90
91              When RSA keys are in use (as is the default),  req,  unlike  the
92              rest  of ovs-pki's commands, does not need access to a PKI hier‐
93              archy created by ovs-pki init.  The -B  or  --bits  option  (see
94              below)  may  be used to specify the number of bits in the gener‐
95              ated RSA key.
96
97              When DSA keys are used (as specified with --key=dsa), req  needs
98              access to the dsaparam.pem file created as part of the PKI hier‐
99              archy (but not to  other  files  in  that  tree).   By  default,
100              ovs-pki     looks    for    this    file    in    /var/lib/open‐
101              vswitch/pki/dsaparam.pem, but the -D or --dsaparam  option  (see
102              below) may be used to specify an alternate location.
103
104              name-privkey.pem  has  sensitive  contents  that  should  not be
105              exposed.  name-req.pem may be safely made public.
106
107
108       sign name [type]
109              Signs the certificate request named name-req.pem that  was  pro‐
110              duced  in  the  previous  step,  producing  a  certificate named
111              name-cert.pem.  type, either  switch  (default)  or  controller,
112              indicates the use for which the key is being certified.
113
114              This command must be run on the CA machine.
115
116              The command will output a fingerprint to stdout and request that
117              you verify that it is the same fingerprint  output  by  the  req
118              command.  This ensures that the request being signed is the same
119              one produced by req.  (The -b or --batch option  suppresses  the
120              verification step.)
121
122              The file name-cert.pem will need to be copied back to the switch
123              or controller for which it is intended.  Its contents may safely
124              be made public.
125
126
127       req+sign name [type]
128              Combines  the  req  and  sign  commands into a single step, out‐
129              putting all the files produced by  each.   The  name-privkey.pem
130              and name-cert.pem files must be copied securely to the switch or
131              controller.  name-privkey.pem has sensitive  contents  and  must
132              not be exposed in transit.  Afterward, it should be deleted from
133              the CA machine.
134
135              This combined method is, theoretically,  less  secure  than  the
136              individual steps performed separately on two different machines,
137              because there is additional potential for exposure of  the  pri‐
138              vate key.  However, it is also more convenient.
139
140
141       verify name [type]
142              Verifies that name-cert.pem is a valid certificate for the given
143              type of use, either switch (default) or controller.  If the cer‐
144              tificate   is   valid  for  this  use,  it  prints  the  message
145              ``name-cert.pem: OK''; otherwise, it prints an error message.
146
147
148       fingerprint file
149              Prints the fingerprint for file.  If file is a certificate, then
150              this  is the SHA-1 digest of the DER encoded version of the cer‐
151              tificate; otherwise, it is the SHA-1 digest of the entire file.
152
153
154       self-sign name
155              Signs the certificate request named name-req.pem using the  pri‐
156              vate  key  name-privkey.pem, producing a self-signed certificate
157              named name-cert.pem.  The input files should have been  produced
158              with ovs-pki req.
159
160              Some controllers accept such self-signed certificates.
161
162

OPTIONS

164       -k type
165       --key=type
166              For  the  init command, sets the public key algorithm to use for
167              the new PKI hierarchy.  For the req and req+sign commands,  sets
168              the  public  key  algorithm  to use for the key to be generated,
169              which must match the value specified on init.  With  other  com‐
170              mands, the value has no effect.
171
172              The type may be rsa (the default) or dsa.
173
174
175       -B nbits
176       --bits=nbits
177              Sets  the  number  of bits in the key to be generated.  When RSA
178              keys are in use, this option affects only  the  init,  req,  and
179              req+sign commands, and the same value should be given each time.
180              With DSA keys are in use, this option affects only the init com‐
181              mand.
182
183              The value must be at least 1024.  The default is 2048.
184
185
186       -D file
187       --dsaparam=file
188              Specifies  an  alternate  location  for  the  dsaparam.pem  file
189              required by the req and req+sign commands.  This option  affects
190              only these commands, and only when DSA keys are used.
191
192              The default is dsaparam.pem under the PKI hierarchy.
193
194
195       -b
196       --batch
197              Suppresses the interactive verification of fingerprints that the
198              sign command by default requires.
199
200
201       -d dir
202       --dir=dir
203              Specifies the location of the PKI hierarchy to be used  or  cre‐
204              ated  by  the  command (default: /var/lib/openvswitch/pki).  All
205              commands, except req, need access to a PKI hierarchy.
206
207
208       -f
209       --force
210              By default, ovs-pki will not overwrite existing files or  direc‐
211              tories.  This option overrides this behavior.
212
213
214       -l file
215       --log=file
216              Sets   the   log   file   to   file.    Default:  /var/log/open‐
217              vswitch/ovs-pki.log.
218
219
220       -h
221       --help Prints a help usage message and exits.
222
223

SEE ALSO

225       ovs-controller(8).
226
227
228
229Open vSwitch                         2.0.0                          ovs-pki(8)
Impressum