X-Git-Url: http://git.cascardo.eti.br/?a=blobdiff_plain;f=utilities%2Fovs-pki.8.in;h=9c3019ba82480f5b88b2298c3d66e59b7f7cfd61;hb=HEAD;hp=0f1c4540f62257c71d5fc13c02a6221a2ab15b03;hpb=d65349ea28bb67a0062a9b4b60ff97538206373b;p=cascardo%2Fovs.git diff --git a/utilities/ovs-pki.8.in b/utilities/ovs-pki.8.in index 0f1c4540f..9c3019ba8 100644 --- a/utilities/ovs-pki.8.in +++ b/utilities/ovs-pki.8.in @@ -1,42 +1,35 @@ -.TH ovs\-pki 8 "May 2008" "Open vSwitch" "Open vSwitch Manual" +.de IQ +. br +. ns +. IP "\\$1" +.. +.TH ovs\-pki 8 "@VERSION@" "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] +Each command takes the form: .sp -Stand\-alone commands with their arguments: +\fBovs\-pki\fR [\fIoptions\fR] \fIcommand\fR [\fIargs\fR] +.sp +The implemented commands and their arguments are: .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 +\fBovs\-pki\fR \fBreq\fR \fIname\fR .br -\fBovs\-pki\fR \fBself-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] +\fBovs\-pki\fR \fBsign\fR \fIname\fR [\fItype\fR] .br -\fBovs\-pki\fR \fBreject\fR \fIPREFIX\fR [\fITYPE\fR] +\fBovs\-pki\fR \fBreq+sign\fR \fIname\fR [\fItype\fR] .br -\fBovs\-pki\fR \fBapprove\fR \fIPREFIX\fR [\fITYPE\fR] +\fBovs\-pki\fR \fBverify\fR \fIname\fR [\fItype\fR] .br -\fBovs\-pki\fR \fBprompt\fR [\fITYPE\fR] +\fBovs\-pki\fR \fBfingerprint\fR \fIfile\fR .br -\fBovs\-pki\fR \fBexpire\fR [\fIAGE\fR] +\fBovs\-pki\fR \fBself\-sign\fR \fIname\fR .sp -Each \fITYPE\fR above is a certificate type, either \fBswitch\fR +Each \fItype\fR above is a certificate type, either \fBswitch\fR (default) or \fBcontroller\fR. .sp The available options are: @@ -101,14 +94,14 @@ The files \fBpki/controllerca/private/cakey.pem\fR and 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. +\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 +\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. @@ -128,14 +121,14 @@ hierarchy (but not to other files in that tree). By default, 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. +\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 +\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 +\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. @@ -147,17 +140,17 @@ 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 +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] +\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. @@ -167,111 +160,32 @@ 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 +\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 +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 +\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 \fINAME\fB\-cert.pem\fR. The input files should have +\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 \fIname\fB\-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 +.IP "\fB\-k\fR \fItype\fR" +.IQ "\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, @@ -280,8 +194,8 @@ 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 +.IP "\fB\-B\fR \fInbits\fR" +.IQ "\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. @@ -290,41 +204,35 @@ command. The value must be at least 1024. The default is 2048. -.TP -\fB\-D\fR \fIfile\fR | \fB\-\^\-dsaparam=\fIfile\fR +.IP "\fB\-D\fR \fIfile\fR" +.IQ "\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 +.IP "\fB\-b\fR" +.IQ "\fB\-\^\-batch\fR" Suppresses the interactive verification of fingerprints that the -\fBsign\fR and \fBapprove\fR commands by default require. +\fBsign\fR command by default requires. -.TP -\fB\-d\fR \fIdir\fR | \fB\-\^\-dir=\fR\fIdir\fR +.IP "\fB\-d\fR \fIdir\fR" +.IQ "\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 +.IP "\fB\-f\fR" +.IQ "\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 +.IP "\fB\-l\fR \fIfile\fR" +.IQ "\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 +.IP "\fB\-h\fR" +.IQ "\fB\-\^\-help\fR" Prints a help usage message and exits. - -.SH "SEE ALSO" - -.BR ovs\-controller (8), -.BR ovs\-openflowd (8), -.BR ovs\-pki\-cgi (8)