1 files changed, 323 insertions, 0 deletions
diff --git a/utilities/ovs-pki.8.in b/utilities/ovs-pki.8.in
new file mode 100644
index 000000000..35bf0ea41
--- /dev/null
+++ b/utilities/ovs-pki.8.in
@@ -0,0 +1,323 @@
+.TH ovs\-pki 8 "May 2008" "Open vSwitch" "Open vSwitch Manual"
+
+.SH NAME
+ovs\-pki \- OpenFlow public key infrastructure management utility
+
+.SH SYNOPSIS
+\fBovs\-pki\fR [\fIOPTIONS\fR] \fICOMMAND\fR [\fIARGS\fR]
+.sp
+Stand\-alone commands with their arguments:
+.br
+\fBovs\-pki\fR \fBinit\fR
+.br
+\fBovs\-pki\fR \fBreq\fR \fINAME\fR
+.br
+\fBovs\-pki\fR \fBsign\fR \fINAME\fR [\fITYPE\fR]
+.br
+\fBovs\-pki\fR \fBreq+sign\fR \fINAME\fR [\fITYPE\fR]
+.br
+\fBovs\-pki\fR \fBverify\fR \fINAME\fR [\fITYPE\fR]
+.br
+\fBovs\-pki\fR \fBfingerprint\fR \fIFILE\fR
+.br
+\fBovs\-pki\fR \self-sign\fR \fINAME\fR
+.sp
+The following additional commands manage an online PKI:
+.br
+\fBovs\-pki\fR \fBls\fR [\fIPREFIX\fR] [\fITYPE\fR]
+.br
+\fBovs\-pki\fR \fBflush\fR [\fITYPE\fR]
+.br
+\fBovs\-pki\fR \fBreject\fR \fIPREFIX\fR [\fITYPE\fR]
+.br
+\fBovs\-pki\fR \fBapprove\fR \fIPREFIX\fR [\fITYPE\fR]
+.br
+\fBovs\-pki\fR \fBprompt\fR [\fITYPE\fR]
+.br
+\fBovs\-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 \fBovs\-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 \fBovs\-pki\fR.
+
+\fBovs\-pki\fR uses \fBopenssl\fR(1) for certificate management and key
+generation.
+
+.SH "OFFLINE COMMANDS"
+
+The following \fBovs\-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, \fBovs\-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 \fBovs\-pki\fR's commands, does not need access to a PKI
+hierarchy created by \fBovs\-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,
+\fBovs\-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 \fBovs\-pki req\fR.
+
+Some controllers accept such self-signed certificates.
+
+.SH "ONLINE COMMANDS"
+
+An OpenFlow PKI can be administered online, in conjunction with
+.BR ovs\-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
+\fBovs\-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 \fBovs\-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 \fBovs\-pki\fR commands support online administration:
+
+.TP
+\fBovs\-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
+\fBovs\-pki\fR \fBflush\fR [\fITYPE\fR]
+Deletes all certificate requests of the given \fITYPE\fR.
+
+.TP
+\fBovs\-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
+\fBovs\-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
+\fBovs\-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
+\fBovs\-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, \fBovs\-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@/ovs\-pki.log\fR.
+
+.TP
+\fB\-h\fR | \fB\-\^\-help\fR
+Prints a help usage message and exits.
+
+.SH "SEE ALSO"
+
+.BR controller (8),
+.BR ovs\-pki\-cgi (8),
+.BR secchan (8)