Use RSA instead of DSA by default for the OpenFlow PKI.
[sliver-openvswitch.git] / utilities / ofp-pki.8.in
index 3e0aaee..3680347 100644 (file)
@@ -6,7 +6,7 @@ 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:
+Stand\-alone commands with their arguments:
 .br
 \fBofp\-pki\fR \fBinit\fR
 .br
@@ -39,7 +39,16 @@ Each \fITYPE\fR above is a certificate type, either \fBswitch\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]
+[\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
@@ -62,13 +71,21 @@ 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
+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
@@ -76,27 +93,40 @@ 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.
+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
+\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.
+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
+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
+\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.
 
@@ -105,10 +135,10 @@ 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
+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
+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.
 
@@ -116,9 +146,9 @@ safely be made public.
 \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
+\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
+\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.
 
@@ -129,23 +159,23 @@ 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
+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
+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
+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)
+.BR ofp\-pki\-cgi (8)
 and a web server such as Apache:
 
 .IP \(bu
@@ -160,7 +190,7 @@ 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
+\fIFINGERPRINT\fB\-req.pem\fR, which \fIFINGERPRINT\fR is the SHA\-1
 hash of the file.
 
 .IP \(bu
@@ -204,7 +234,7 @@ 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
+verify that it is correct.  (The \fB\-b\fR or \fB\-\^\-batch\fR option
 suppresses the verification step.)
 
 .TP
@@ -223,34 +253,62 @@ older than \fIAGE\fR, which must in one of the forms \fIN\fBs\fR,
 
 .SH OPTIONS
 .TP
-[\fB-d\fR \fIDIR\fR | \fB--dir=\fR\fIDIR\fR]
+\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]
+\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,
+\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.
+hierarchy.  Default: \fBofp\-pki.log\fR.
 
 .TP
-[\fB-h\fR | \fB--help\fR]
+\fB\-h\fR | \fB\-\^\-help\fR
 Prints a help usage message and exits.
 
 .SH "SEE ALSO"
 
-.BR ofp-pki-cgi (8),
+.BR ofp\-pki\-cgi (8),
 .BR dpctl (8),
 .BR switch (8),
 .BR secchan (8),