.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
.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
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
.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.
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.
\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.
.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
\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
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
.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),
force=no
batch=no
log=ofp-pki.log
+keytype=rsa
+bits=2048
for option; do
# This option-parsing mechanism borrowed from a Autoconf-generated
# configure script under the following license:
Each TYPE above is a certificate type: 'switch' (default) or 'controller'.
-The valid OPTIONS are:
+Options for 'init', 'req', and 'req+sign' only:
+ -k, --key=rsa|dsa Type of keys to use (default: rsa)
+ -B, --bits=NBITS Number of bits in keys (default: 2048). For DSA keys,
+ this has an effect only on 'init'.
+ -D, --dsaparam=FILE File with DSA parameters (DSA only)
+ (default: dsaparam.pem within PKI directory)
+Options for use with the 'sign' and 'approve' commands:
+ -b, --batch Skip fingerprint verification
+Options that apply to any command:
-d, --dir=DIR Directory where the PKI is located
(default: $pkidir)
-f, --force Continue even if file or directory already exists
- -b, --batch Skip fingerprint verification
-l, --log=FILE Log openssl output to FILE (default: ofp-log.log)
-h, --help Print this usage message.
EOF
exit 0
;;
- --d*=*)
+ --di*=*)
pkidir=$optarg
;;
- --d*|-d)
+ --di*|-d)
prev=pkidir
;;
+ --k*=*)
+ keytype=$optarg
+ ;;
+ --k*|-k)
+ prev=keytype
+ ;;
+ --bi*=*)
+ bits=$optarg
+ ;;
+ --bi*|-B)
+ prev=bits
+ ;;
+ --ds*=*)
+ dsaparam=$optarg
+ ;;
+ --ds*|-D)
+ prev=dsaparam
+ ;;
--l*=*)
log=$optarg
;;
--force|-f)
force=yes
;;
- --batch|-b)
+ --ba*|-b)
batch=yes
;;
-*)
echo "$0: missing command name; use --help for help" >&2
exit 1
fi
+if test "$keytype" != rsa && test "$keytype" != dsa; then
+ echo "$0: argument to -k or --key must be rsa or dsa"
+ exit 1
+fi
+if test "$bits" -lt 1024; then
+ echo "$0: argument to -B or --bits must be at least 1024"
+ exit 1
+fi
+if test -z "$dsaparam"; then
+ dsaparam=$pkidir/dsaparam.pem
+fi
if test "$command" = "init"; then
if test -e "$pkidir" && test "$force" != "yes"; then
- echo "$0: $pkidir already exists" >&2
+ echo "$0: $pkidir already exists and --force not specified" >&2
exit 1
fi
cd "$pkidir"
exec 3>>$log
- if test ! -e dsaparam.pem; then
+ if test $keytype = dsa && test ! -e dsaparam.pem; then
echo "Generating DSA parameters, please wait..." >&2
- openssl dsaparam -out dsaparam.pem 2048 1>&3 2>&3
- fi
-
- # Create the request configuration.
- if test ! -e req.cnf; then
- cat > req.cnf <<EOF
-[ req ]
-prompt = no
-distinguished_name = req_distinguished_name
-
-[ req_distinguished_name ]
-C = US
-ST = CA
-L = Palo Alto
-O = OpenFlow
-OU = OpenFlow certifier
-CN = OpenFlow certificate
-EOF
+ openssl dsaparam -out dsaparam.pem $bits 1>&3 2>&3
fi
# Create the CAs.
test -e serial || echo 01 > serial
# Put DSA parameters in directory.
- if test ! -e dsaparam.pem; then
+ if test $keytype = dsa && test ! -e dsaparam.pem; then
cp ../dsaparam.pem .
fi
fi
# Create certificate authority.
+ if test $keytype = dsa; then
+ newkey=dsa:dsaparam.pem
+ else
+ newkey=rsa:$bits
+ fi
openssl req -config ca.cnf -nodes \
- -newkey dsa:dsaparam.pem -keyout private/cakey.pem -out careq.pem \
+ -newkey $newkey -keyout private/cakey.pem -out careq.pem \
1>&3 2>&3
openssl ca -config ca.cnf -create_serial -out cacert.pem \
-days 1095 -batch -keyfile private/cakey.pem -selfsign \
make_request() {
must_not_exist "$arg1-privkey.pem"
must_not_exist "$arg1-req.pem"
- pkidir_must_exist
- openssl req -config "$pkidir/req.cnf" -text -nodes \
- -newkey "dsa:$pkidir/dsaparam.pem" -keyout "$1-privkey.pem" \
- -out "$1-req.pem" 1>&3 2>&3
+ make_tmpdir
+ cat > "$TMP/req.cnf" <<EOF
+[ req ]
+prompt = no
+distinguished_name = req_distinguished_name
+
+[ req_distinguished_name ]
+C = US
+ST = CA
+L = Palo Alto
+O = OpenFlow
+OU = OpenFlow certifier
+CN = OpenFlow certificate for $arg1
+EOF
+ if test $keytype = rsa; then
+ newkey=rsa:$bits
+ else
+ must_exist "$dsaparam"
+ newkey=dsa:$dsaparam
+ fi
+ openssl req -config "$TMP/req.cnf" -text -nodes \
+ -newkey $newkey -keyout "$1-privkey.pem" -out "$1-req.pem" 1>&3 2>&3
}
sign_request() {
one_or_two_args
check_type "$arg2"
+ pkidir_must_exist
make_request "$arg1"
sign_request "$arg1-req.pem" "$arg1-cert.pem"
fingerprint "$arg1-req.pem"
projects / openvswitch / commitdiff