326 lines
12 KiB
Plaintext
326 lines
12 KiB
Plaintext
.TH ofp\-pki 8 "May 2008" "OpenFlow" "OpenFlow Manual"
|
|
|
|
.SH NAME
|
|
ofp\-pki \- OpenFlow public key infrastructure management utility
|
|
|
|
.SH SYNOPSIS
|
|
\fBofp\-pki\fR [\fIOPTIONS\fR] \fICOMMAND\fR [\fIARGS\fR]
|
|
.sp
|
|
Stand\-alone commands with their arguments:
|
|
.br
|
|
\fBofp\-pki\fR \fBinit\fR
|
|
.br
|
|
\fBofp\-pki\fR \fBreq\fR \fINAME\fR
|
|
.br
|
|
\fBofp\-pki\fR \fBsign\fR \fINAME\fR [\fITYPE\fR]
|
|
.br
|
|
\fBofp\-pki\fR \fBreq+sign\fR \fINAME\fR [\fITYPE\fR]
|
|
.br
|
|
\fBofp\-pki\fR \fBverify\fR \fINAME\fR [\fITYPE\fR]
|
|
.br
|
|
\fBofp\-pki\fR \fBfingerprint\fR \fIFILE\fR
|
|
.br
|
|
\fBofp\-pki\fR \self-sign\fR \fINAME\fR
|
|
.sp
|
|
The following additional commands manage an online PKI:
|
|
.br
|
|
\fBofp\-pki\fR \fBls\fR [\fIPREFIX\fR] [\fITYPE\fR]
|
|
.br
|
|
\fBofp\-pki\fR \fBflush\fR [\fITYPE\fR]
|
|
.br
|
|
\fBofp\-pki\fR \fBreject\fR \fIPREFIX\fR [\fITYPE\fR]
|
|
.br
|
|
\fBofp\-pki\fR \fBapprove\fR \fIPREFIX\fR [\fITYPE\fR]
|
|
.br
|
|
\fBofp\-pki\fR \fBprompt\fR [\fITYPE\fR]
|
|
.br
|
|
\fBofp\-pki\fR \fBexpire\fR [\fIAGE\fR]
|
|
.sp
|
|
Each \fITYPE\fR above is a certificate type, either \fBswitch\fR
|
|
(default) or \fBcontroller\fR.
|
|
.sp
|
|
The available options are:
|
|
.br
|
|
[\fB\-k\fR \fItype\fR | \fB\-\^\-key=\fItype\fR]
|
|
[\fB\-B\fR \fInbits\fR | \fB\-\^\-bits=\fInbits\fR]
|
|
[\fB\-D\fR \fIfile\fR | \fB\-\^\-dsaparam=\fIfile\fR]
|
|
[\fB\-b\fR | \fB\-\^\-batch\fR]
|
|
[\fB\-f\fR | \fB\-\^\-force\fR]
|
|
[\fB\-d\fR \fIdir\fR | \fB\-\^\-dir=\fR\fIdir\fR]
|
|
[\fB\-l\fR \fIfile\fR | \fB\-\^\-log=\fIfile\fR]
|
|
[\fB\-h\fR | \fB\-\^\-help\fR]
|
|
.br
|
|
Some options do not apply to every command.
|
|
|
|
.SH DESCRIPTION
|
|
The \fBofp\-pki\fR program sets up and manages a public key
|
|
infrastructure for use with OpenFlow. It is intended to be a simple
|
|
interface for organizations that do not have an established public key
|
|
infrastructure. Other PKI tools can substitute for or supplement the
|
|
use of \fBofp\-pki\fR.
|
|
|
|
\fBofp\-pki\fR uses \fBopenssl\fR(1) for certificate management and key
|
|
generation.
|
|
|
|
.SH "OFFLINE COMMANDS"
|
|
|
|
The following \fBofp\-pki\fR commands support manual PKI
|
|
administration:
|
|
|
|
.TP
|
|
\fBinit\fR
|
|
Initializes a new PKI (by default in directory \fB@PKIDIR@\fR) and populates
|
|
it with a pair of certificate authorities for controllers and
|
|
switches.
|
|
|
|
This command should ideally be run on a high\-security machine separate
|
|
from any OpenFlow controller or switch, called the CA machine. The
|
|
files \fBpki/controllerca/cacert.pem\fR and
|
|
\fBpki/switchca/cacert.pem\fR that it produces will need to be copied
|
|
over to the OpenFlow switches and controllers, respectively. Their
|
|
contents may safely be made public.
|
|
|
|
By default, \fBofp\-pki\fR generates 2048\-bit RSA keys. The \fB\-B\fR
|
|
or \fB\-\^\-bits\fR option (see below) may be used to override the key
|
|
length. The \fB\-k dsa\fR or \fB\-\^\-key=dsa\fR option may be used to use
|
|
DSA in place of RSA. If DSA is selected, the \fBdsaparam.pem\fR file
|
|
generated in the new PKI hierarchy must be copied to any machine on
|
|
which the \fBreq\fR command (see below) will be executed. Its
|
|
contents may safely be made public.
|
|
|
|
Other files generated by \fBinit\fR may remain on the CA machine.
|
|
The files \fBpki/controllerca/private/cakey.pem\fR and
|
|
\fBpki/switchca/private/cakey.pem\fR have particularly sensitive
|
|
contents that should not be exposed.
|
|
|
|
.TP
|
|
\fBreq\fR \fINAME\fR
|
|
Generates a new private key named \fINAME\fR\fB\-privkey.pem\fR and
|
|
corresponding certificate request named \fINAME\fR\fB\-req.pem\fR.
|
|
The private key can be intended for use by a switch or a controller.
|
|
|
|
This command should ideally be run on the switch or controller that
|
|
will use the private key to identify itself. The file
|
|
\fINAME\fR\fB\-req.pem\fR must be copied to the CA machine for signing
|
|
with the \fBsign\fR command (below).
|
|
|
|
This command will output a fingerprint to stdout as its final step.
|
|
Write down the fingerprint and take it to the CA machine before
|
|
continuing with the \fBsign\fR step.
|
|
|
|
When RSA keys are in use (as is the default), \fBreq\fR, unlike the
|
|
rest of \fBofp\-pki\fR's commands, does not need access to a PKI
|
|
hierarchy created by \fBofp\-pki init\fR. The \fB\-B\fR or
|
|
\fB\-\^\-bits\fR option (see below) may be used to specify the number of
|
|
bits in the generated RSA key.
|
|
|
|
When DSA keys are used (as specified with \fB\-\^\-key=dsa\fR), \fBreq\fR
|
|
needs access to the \fBdsaparam.pem\fR file created as part of the PKI
|
|
hierarchy (but not to other files in that tree). By default,
|
|
\fBofp\-pki\fR looks for this file in \fB@PKIDIR@/dsaparam.pem\fR, but
|
|
the \fB\-D\fR or \fB\-\^\-dsaparam\fR option (see below) may be used to
|
|
specify an alternate location.
|
|
|
|
\fINAME\fR\fB\-privkey.pem\fR has sensitive contents that should not be
|
|
exposed. \fINAME\fR\fB\-req.pem\fR may be safely made public.
|
|
|
|
.TP
|
|
\fBsign\fR \fINAME\fR [\fITYPE\fR]
|
|
Signs the certificate request named \fINAME\fR\fB\-req.pem\fR that was
|
|
produced in the previous step, producing a certificate named
|
|
\fINAME\fR\fB\-cert.pem\fR. \fITYPE\fR, either \fBswitch\fR (default) or
|
|
\fBcontroller\fR, indicates the use for which the key is being
|
|
certified.
|
|
|
|
This command must be run on the CA machine.
|
|
|
|
The command will output a fingerprint to stdout and request that you
|
|
verify that it is the same fingerprint output by the \fBreq\fR
|
|
command. This ensures that the request being signed is the same one
|
|
produced by \fBreq\fR. (The \fB\-b\fR or \fB\-\^\-batch\fR option
|
|
suppresses the verification step.)
|
|
|
|
The file \fINAME\fR\fB\-cert.pem\fR will need to be copied back to the
|
|
switch or controller for which it is intended. Its contents may
|
|
safely be made public.
|
|
|
|
.TP
|
|
\fBreq+sign\fR \fINAME\fR [\fITYPE\fR]
|
|
Combines the \fBreq\fR and \fBsign\fR commands into a single step,
|
|
outputting all the files produced by each. The
|
|
\fINAME\fR\fB\-privkey.pem\fR and \fINAME\fR\fB\-cert.pem\fR files must
|
|
be copied securely to the switch or controller.
|
|
\fINAME\fR\fB\-privkey.pem\fR has sensitive contents and must not be
|
|
exposed in transit. Afterward, it should be deleted from the CA
|
|
machine.
|
|
|
|
This combined method is, theoretically, less secure than the
|
|
individual steps performed separately on two different machines,
|
|
because there is additional potential for exposure of the private
|
|
key. However, it is also more convenient.
|
|
|
|
.TP
|
|
\fBverify\fR \fINAME\fR [\fITYPE\fR]
|
|
Verifies that \fINAME\fR\fB\-cert.pem\fR is a valid certificate for the
|
|
given \fITYPE\fR of use, either \fBswitch\fR (default) or
|
|
\fBcontroller\fR. If the certificate is valid for this use, it prints
|
|
the message ``\fINAME\fR\fB\-cert.pem\fR: OK''; otherwise, it prints an
|
|
error message.
|
|
|
|
.TP
|
|
\fBfingerprint\fR \fIFILE\fR
|
|
Prints the fingerprint for \fIFILE\fR. If \fIFILE\fR is a
|
|
certificate, then this is the SHA\-1 digest of the DER encoded version
|
|
of the certificate; otherwise, it is the SHA\-1 digest of the entire
|
|
file.
|
|
|
|
.TP
|
|
\fBself-sign\fR \fINAME\fR
|
|
Signs the certificate request named \fINAME\fB\-req.pem\fR using the
|
|
private key \fINAME\fB-privkey.pem\fR, producing a self-signed
|
|
certificate named \fINAMEfB\-cert.pem\fR. The input files should have
|
|
been produced with \fBofp\-pki req\fR.
|
|
|
|
Some controllers accept such self-signed certificates.
|
|
|
|
.SH "ONLINE COMMANDS"
|
|
|
|
An OpenFlow PKI can be administered online, in conjunction with
|
|
.BR ofp\-pki\-cgi (8)
|
|
and a web server such as Apache:
|
|
|
|
.IP \(bu
|
|
The web server exports the contents of the PKI via HTTP. All files in
|
|
a PKI hierarchy files may be made public, except for the files
|
|
\fBpki/controllerca/private/cakey.pem\fR and
|
|
\fBpki/switchca/private/cakey.pem\fR, which must not be exposed.
|
|
|
|
.IP \(bu
|
|
\fBofp\-pki\-cgi\fR allows newly generated certificate requests for
|
|
controllers and switches to be uploaded into the
|
|
\fBpki/controllerca/incoming\fR and \fBpki/switchca/incoming\fR
|
|
directories, respectively. Uploaded certificate requests are stored
|
|
in those directories under names of the form
|
|
\fIFINGERPRINT\fB\-req.pem\fR, which \fIFINGERPRINT\fR is the SHA\-1
|
|
hash of the file.
|
|
|
|
.IP \(bu
|
|
These \fBofp\-pki\fR commands allow incoming certificate requests to
|
|
be approved or rejected, in a form are suitable for use by humans or
|
|
other software.
|
|
|
|
.PP
|
|
The following \fBofp\-pki\fR commands support online administration:
|
|
|
|
.TP
|
|
\fBofp\-pki\fR \fBls\fR [\fIPREFIX\fR] [\fITYPE\fR]
|
|
Lists all of the incoming certificate requests of the given \fITYPE\fR
|
|
(either \fBswitch\fR, the default, or \fBcontroller\fR). If
|
|
\fIPREFIX\fR, which must be at least 4 characters long, is specified,
|
|
it causes the list to be limited to files whose names begin with
|
|
\fIPREFIX\fR. This is useful, for example, to avoid typing in an
|
|
entire fingerprint when checking that a specific certificate request
|
|
has been received.
|
|
|
|
.TP
|
|
\fBofp\-pki\fR \fBflush\fR [\fITYPE\fR]
|
|
Deletes all certificate requests of the given \fITYPE\fR.
|
|
|
|
.TP
|
|
\fBofp\-pki\fR \fBreject\fR \fIPREFIX\fR [\fITYPE\fR]
|
|
Rejects the certificate request whose name begins with \fIPREFIX\fR,
|
|
which must be at least 4 characters long, of the given type (either
|
|
\fBswitch\fR, the default, or \fBcontroller\fR). \fIPREFIX\fR must
|
|
match exactly one certificate request; its purpose is to allow the
|
|
user to type fewer characters, not to match multiple certificate
|
|
requests.
|
|
|
|
.TP
|
|
\fBofp\-pki\fR \fBapprove\fR \fIPREFIX\fR [\fITYPE\fR]
|
|
Approves the certificate request whose name begins with \fIPREFIX\fR,
|
|
which must be at least 4 characters long, of the given \fITYPE\fR
|
|
(either \fBswitch\fR, the default, or \fBcontroller\fR). \fIPREFIX\fR
|
|
must match exactly one certificate request; its purpose is to allow
|
|
the user to type fewer characters, not to match multiple certificate
|
|
requests.
|
|
|
|
The command will output a fingerprint to stdout and request that you
|
|
verify that it is correct. (The \fB\-b\fR or \fB\-\^\-batch\fR option
|
|
suppresses the verification step.)
|
|
|
|
.TP
|
|
\fBofp\-pki\fR \fBprompt\fR [\fITYPE\fR]
|
|
Prompts the user for each incoming certificate request of the given
|
|
\fITYPE\fR (either \fBswitch\fR, the default, or \fBcontroller\fR).
|
|
Based on the certificate request's fingerprint, the user is given the
|
|
option of approving, rejecting, or skipping the certificate request.
|
|
|
|
.TP
|
|
\fBofp\-pki\fR \fBexpire\fR [\fIAGE\fR]
|
|
|
|
Rejects all the incoming certificate requests, of either type, that is
|
|
older than \fIAGE\fR, which must in one of the forms \fIN\fBs\fR,
|
|
\fIN\fBmin\fR, \fIN\fBh\fR, \fIN\fBday\fR. The default is \fB1day\fR.
|
|
|
|
.SH OPTIONS
|
|
.TP
|
|
\fB\-k\fR \fItype\fR | \fB\-\^\-key=\fItype\fR
|
|
For the \fBinit\fR command, sets the public key algorithm to use for
|
|
the new PKI hierarchy. For the \fBreq\fR and \fBreq+sign\fR commands,
|
|
sets the public key algorithm to use for the key to be generated,
|
|
which must match the value specified on \fBinit\fR. With other
|
|
commands, the value has no effect.
|
|
|
|
The \fItype\fR may be \fBrsa\fR (the default) or \fBdsa\fR.
|
|
|
|
.TP
|
|
\fB\-B\fR \fInbits\fR | \fB\-\^\-bits=\fInbits\fR
|
|
Sets the number of bits in the key to be generated. When RSA keys are
|
|
in use, this option affects only the \fBinit\fR, \fBreq\fR, and
|
|
\fBreq+sign\fR commands, and the same value should be given each time.
|
|
With DSA keys are in use, this option affects only the \fBinit\fR
|
|
command.
|
|
|
|
The value must be at least 1024. The default is 2048.
|
|
|
|
.TP
|
|
\fB\-D\fR \fIfile\fR | \fB\-\^\-dsaparam=\fIfile\fR
|
|
Specifies an alternate location for the \fBdsaparam.pem\fR file
|
|
required by the \fBreq\fR and \fBreq+sign\fR commands. This option
|
|
affects only these commands, and only when DSA keys are used.
|
|
|
|
The default is \fBdsaparam.pem\fR under the PKI hierarchy.
|
|
|
|
.TP
|
|
\fB\-b\fR | \fB\-\^\-batch\fR
|
|
Suppresses the interactive verification of fingerprints that the
|
|
\fBsign\fR and \fBapprove\fR commands by default require.
|
|
|
|
.TP
|
|
\fB\-d\fR \fIdir\fR | \fB\-\^\-dir=\fR\fIdir\fR
|
|
Specifies the location of the PKI hierarchy to be used or created by
|
|
the command (default: \fB@PKIDIR@\fR). All commands, except \fBreq\fR,
|
|
need access to a PKI hierarchy.
|
|
|
|
.TP
|
|
\fB\-f\fR | \fB\-\^\-force\fR
|
|
By default, \fBofp\-pki\fR will not overwrite existing files or
|
|
directories. This option overrides this behavior.
|
|
|
|
.TP
|
|
\fB\-l\fR \fIfile\fR | \fB\-\^\-log=\fIfile\fR
|
|
Sets the log file to \fIfile\fR. Default:
|
|
\fB@LOGDIR@/ofp\-pki.log\fR.
|
|
|
|
.TP
|
|
\fB\-h\fR | \fB\-\^\-help\fR
|
|
Prints a help usage message and exits.
|
|
|
|
.SH "SEE ALSO"
|
|
|
|
.BR ofp\-pki\-cgi (8),
|
|
.BR dpctl (8),
|
|
.BR switch (8),
|
|
.BR secchan (8),
|
|
.BR controller (8)
|