+.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
+.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-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]
+
+.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.
+
+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.
+
+\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
+\fBofp\-pki\fR \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.
+
+.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-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-b\fR | \fB--batch\fR]
+Suppresses the interactive verification of fingerprints that the
+\fBsign\fR command by default requires.
+
+.TP
+[\fB-l\fR \fIFILE\fR | \fB--log=\fIFILE\fR]
+Sets the log file to \fIFILE\fR. If \fIFILE\fR starts with \fB/\fR,
+it is taken as an absolute path; otherwise it is relative to the PKI
+hierarchy. Default: \fBofp-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)