utilities/ofp-pki.8

   1 .TH ofp-pki 8 "May 2008" "OpenFlow" "OpenFlow Manual"
   2
   3 .SH NAME
   4 ofp\-pki \- OpenFlow public key infrastructure management utility
   5
   6 .SH SYNOPSIS
   7 \fBofp\-pki\fR [\fIOPTIONS\fR] \fICOMMAND\fR [\fIARGS\fR]
   8 .sp
   9 Commands with their arguments:
  10 .br
  11 \fBofp\-pki\fR \fBnew-pki\fR
  12 .br
  13 \fBofp\-pki\fR \fBreq\fR \fINAME\fR
  14 .br
  15 \fBofp\-pki\fR \fBsign\fR \fINAME\fR \fITYPE\fR
  16 .br
  17 \fBofp\-pki\fR \fBreq+sign\fR \fINAME\fR \fITYPE\fR
  18 .br
  19 \fBofp\-pki\fR \fBverify\fR \fINAME\fR \fITYPE\fR
  20 .sp
  21 The available options are:
  22 .br
  23 [\fB-d\fR \fIDIR\fR | \fB--dir=\fR\fIDIR\fR] [\fB-f\fR | \fB--force\fR] [\fB-b\fR | \fB--batch\fR] [\fB-l\fR \fIFILE\fR | \fB--log=\fIFILE\fR] [\fB-h\fR | \fB--help\fR]
  24
  25 .SH DESCRIPTION
  26 The \fBofp-pki\fR program sets up and manages a public key
  27 infrastructure for use with OpenFlow.  It is intended to be a simple
  28 interface for organizations that do not have an established public key
  29 infrastructure.  Other PKI tools can substitute for or supplement the
  30 use of \fBofp-pki\fR.
  31
  32 \fBofp-pki\fR uses \fBopenssl\fR(1) for certificate management and key
  33 generation.
  34
  35 The commands supported by \fBofp-pki\fR are:
  36
  37 .TP
  38 \fBnew-pki\fR
  39 Creates a new PKI directory (by default named \fBpki\fR) and populates
  40 it with a pair of certificate authorities for controllers and
  41 switches.
  42
  43 This command should ideally be run on a high-security machine separate
  44 from any OpenFlow controller or switch, called the CA machine.  The
  45 files \fBpki/controllerca/cacert.pem\fR and
  46 \fBpki/switchca/cacert.pem\fR that it produces will need to be copied
  47 over to the OpenFlow switches and controllers, respectively.  Their
  48 contents may safely be made public.
  49
  50 Other files generated by \fBnew-pki\fR may remain on the CA machine.
  51 The files \fBpki/controllerca/private/cakey.pem\fR and
  52 \fBpki/switchca/private/cakey.pem\fR have particularly sensitive
  53 contents that should not be exposed.
  54
  55 .TP
  56 \fBreq\fR \fINAME\fR
  57 Generates a new private key named \fINAME\fR\fB-privkey.pem\fR and
  58 corresponding certificate request named \fINAME\fR\fB-req.pem\fR.
  59 The private key can be intended for use by a switch or a controller.
  60
  61 This command should ideally be run on the switch or controller that
  62 will use the private key to identify itself.  The file
  63 \fINAME\fR\fB-req.pem\fR must be copied to the CA machine for signing
  64 with the \fBsign\fR command (below).
  65
  66 This command will output a fingerprint to stdout as its final step.
  67 Write down the fingerprint and take it to the CA machine before
  68 continuing with the \fBsign\fR step.
  69
  70 \fINAME\fR\fB-privkey.pem\fR has sensitive contents that should not be
  71 exposed.  \fINAME\fR\fB-req.pem\fR may be safely made public.
  72
  73 .TP
  74 \fBsign\fR \fINAME\fR \fITYPE\fR
  75 Signs the certificate request named \fINAME\fR\fB-req.pem\fR that was
  76 produced in the previous step, producing a certificate named
  77 \fINAME\fR\fB-cert.pem\fR.  \fITYPE\fR, which must be \fBswitch\fR or
  78 \fBcontroller\fR, indicates the use for which the key is being
  79 certified.
  80
  81 This command must be run on the CA machine.
  82
  83 The command will output a fingerprint to stdout and request that you
  84 verify that it is the same fingerprint output by the \fBreq\fR
  85 command.  This ensures that the request being signed is the same one
  86 produced by \fBreq\fR.
  87
  88 The file \fINAME\fR\fB-cert.pem\fR will need to be copied back to the
  89 switch or controller for which it is intended.  Its contents may
  90 safely be made public.
  91
  92 .TP
  93 \fBreq+sign\fR \fINAME\fR \fITYPE\fR
  94 Combines the \fBreq\fR and \fBsign\fR commands into a single step,
  95 outputting all the files produced by each.  The
  96 \fINAME\fR\fB-privkey.pem\fR and \fINAME\fR\fB-cert.pem\fR files must
  97 be copied securely to the switch or controller.
  98 \fINAME\fR\fB-privkey.pem\fR has sensitive contents and must not be
  99 exposed in transit.  Afterward, it should be deleted from the CA
 100 machine.
 101
 102 This combined method is, theoretically, less secure than the
 103 individual steps performed separately on two different machines,
 104 because there is additional potential for exposure of the private
 105 key.  However, it is also more convenient.
 106
 107 .TP
 108 \fBverify\fR \fINAME\fR \fITYPE\fR
 109 Verifies that \fINAME\fR\fB-cert.pem\fR is a valid certificate for the
 110 given \fITYPE\fR of use (either \fBswitch\fR or \fBcontroller\fR).  If
 111 the certificate is valid for this use, it prints the message
 112 ``\fINAME\fR\fB-cert.pem\fR: OK''; otherwise, it prints an error
 113 message.
 114
 115 .SH OPTIONS
 116 .TP
 117 [\fB-d\fR \fIDIR\fR | \fB--dir=\fR\fIDIR\fR]
 118 Specifies the location of the PKI hierarchy to be used or created by
 119 the command (default: \fBpki\fR under the current directory).  The
 120 \fBreq\fR command does not need access to a PKI hierarchy.
 121
 122 .TP
 123 [\fB-f\fR | \fB--force\fR]
 124 By default, \fBofp-pki\fR will not overwrite existing files or
 125 directories.  This option overrides this behavior.
 126
 127 .TP
 128 [\fB-b\fR | \fB--batch\fR]
 129 Suppresses the interactive verification of fingerprints that the
 130 \fBsign\fR command by default requires.
 131
 132 .TP
 133 [\fB-l\fR \fIFILE\fR | \fB--log=\fIFILE\fR]
 134 Sets the log file to \fIFILE\fR (default: ofp-pki.log).
 135
 136 .TP
 137 [\fB-h\fR | \fB--help\fR]
 138 Prints a help usage message and exits.
 139
 140 .SH "SEE ALSO"
 141
 142 .BR dpctl (8),
 143 .BR switch (8),
 144 .BR secchan (8),
 145 .BR controller (8)