diff --git a/bin/ca-create-cert b/bin/ca-create-cert index b9997b2..e1da464 100755 --- a/bin/ca-create-cert +++ b/bin/ca-create-cert @@ -11,6 +11,8 @@ MAKE_P12=0 # XXX: in the ca_extension_policy section of ca-config.tpl it states that the # C= and O= DN values in a CSR have to match those of the CA # should we have options here to change them when it will cause breakage? +# XXX: Should we provide a -q option to disable the automatic qualification of +# host and user names with CA_DOMAIN? It might irritate people... usage() { cat <<__EOT__ Usage: @@ -22,9 +24,9 @@ Options: -h, --help Print this helpful message! -c, --encrypt Encrypt certificate private key with Triple-DES -f, --config FILE Use config file instead of $CONFFILE - -t, --type Certificate type: "server", "client" or "user" + -t, --type TYPE Certificate type: "server", "client" or "user" -d, --days DAYS Certificate is valid for DAYS days instead of 365 - -n, --alt-name Alternative host name (can be provided multiple times) + -n, --alt-name NAME Alternative host name (can be provided multiple times) -p, --pkcs12 Create PKCS#12 certificate archive from generated cert -r, --csr-only Only generate CSR, don't sign it -s, --crt-only Only sign certificate, requires CSR in place @@ -33,7 +35,7 @@ Options: --state Certificate DN -- ST --loc Certificate DN -- L --org Certificate DN -- O - --org-unit Certificate DN -- OU + --ounit Certificate DN -- OU --email Certificate DN -- E --comment Certificate nsComment field @@ -42,7 +44,7 @@ __EOT__ short='hcf:t:n:prsx' long='help,encrypt,config:,type:,alt-name:,pkcs12,csr-only,crt-only,cnf-only' -long="$long,country:,state:,loc:,org:,org-unit:,email:,comment:" +long="$long,country:,state:,loc:,org:,ounit:,email:,comment:" opts=$( getopt -o "$short" -l "$long" -n "$PROGNAME" -- "$@" ) if [ 0 -ne $? ]; then echo; usage; exit 1; fi eval set -- "$opts"; @@ -63,7 +65,7 @@ while :; do --state) shift; CA_CRT_ST="$1"; shift;; --location) shift; CA_CRT_L="$1"; shift;; --org) shift; CA_CRT_O="$1"; shift;; - --org-unit) shift; CA_CRT_OU="$1"; shift;; + --ounit) shift; CA_CRT_OU="$1"; shift;; --email) shift; CA_CRT_E="$1"; shift;; --comment) shift; CA_CRT_COMMENT="$1"; shift;; --) shift; break;; @@ -129,10 +131,10 @@ if [ 1 -ne "$CRT_ONLY" ]; then if [ 1 -eq "$CNF_ONLY" -o "$CSR_ONLY" -eq "$CNF_ONLY" ]; then # dirty logic here that probably needs commenting! # generate a *new* certificate request configuration if... - # a) --tpl-only is set, i.e. we only want to generate a config - # b) both --tpl-only and --csr-only are unset, i.e. + # a) --cnf-only is set, i.e. we only want to generate a config + # b) both --cnf-only and --csr-only are unset, i.e. # we're just generating a csr/crt as per usual - # c) both --tpl-only and --csr-only are set, i.e. + # c) both --cnf-only and --csr-only are set, i.e. # we're just generating the config and not the csr itself ca_template "req-config" "$CA_HOME/cnf/$CNF_NAME.req.cnf" fi @@ -141,7 +143,7 @@ if [ 1 -ne "$CRT_ONLY" ]; then error "Couldn't find CSR config $CA_HOME/cnf/$CNF_NAME.req.cnf!" fi # the above logic means that if you pass --csr-only but not - # --tpl-only, you can re-use a pre-existing config to generate + # --cnf-only, you can re-use a pre-existing config to generate # a new csr, should you wish to do so... openssl req -new $CRYPTKEY -config "$CA_HOME/cnf/$CNF_NAME.req.cnf" \ -keyout "$CA_HOME/key/$CNF_NAME.key" \ diff --git a/doc/ca-create-cert.1 b/doc/ca-create-cert.1 new file mode 100644 index 0000000..fd53b7f --- /dev/null +++ b/doc/ca-create-cert.1 @@ -0,0 +1,164 @@ +.TH "ca-create-cert" "1" "16 October 2009" "ca-scripts version 0.9" "SSL Certificate Authority utilities" +.SH NAME +ca-create-cert \- generate a signed X.509 SSL certificate +. +.SH SYNOPSIS +. +.SY ca-create-cert +\-t type +.OP \-cprsx +.OP \-f config +.OP \-d days +.OP \-n name +.OP options + +. +.SY ca-create-cert +.OP \-h +| +.OP \-\-help +.YS +. +.SH DESCRIPTION +. +.BR ca-create-cert (1) +creates an openssl configuration necessary for generating a signed X.509 SSL +certificate, generates a certificate signing request using these configuration +files, and signs that request using the CA private key so that it may be +considered as trusted by anything that has imported the CA certificate. +. +.SH OPTIONS +. +.SS The host or user name +This argument to \fBca-create-cert\fR is mandatory, and specifies the common +name of the certificate. Depending on the type of certificate being created, +it is interpreted as either a host name or a user name. Host names are treated +as unqualified if they do not contain any dots and are fully qualified with +the value of CA_DOMAIN in this case, though the unqualified name is preserved +as an additional DNS name in the X.509v3 subjectAltName extension. User names +are treated as unqualified if they do not contain an "@" symbol and are fully +qualified with the value of CA_DOMAIN in this case, yielding a CN like +\fIuser@example.com\fR assuming CA_DOMAIN was set to "example.com". +. +.SS General options +.TP +\fB\-h\fR, \fB\-\-help\fR +Prints out a short synopsis of the options to \fBca-create-cert\fR. +. +.TP +\fB\-t \fITYPE\fR, \fB\-\-type \fITYPE\fR +This argument is mandatory. \fBca-create-cert\fR can create three types of +X.509 certificate: \fIserver\fR, \fIclient\fR, and \fIuser\fR. These differ +in the X.509v3 extensions present in the signed certificate, and in the uses +the certificate is trusted for. See +.BR x509 (1ssl) +and +.BR x509v3_config (5ssl) +for more details about X.509 extensions, and the \fBCERTIFICATE TYPES\fR +section of this manual for more details on the exact differences between the +certificate types. +. +.TP +\fB\-c\fR, \fB\-\-encrypt\fR +Encrypt the generated private key with 3DES. This is not recommended for +\fIserver\fR or \fIclient\fR type certificates, but is probably a good idea for +\fIuser\fR certs. +. +.TP +\fB\-f \fIFILE\fR, \fB\-\-config \fIFILE\fR +Load the ca-scripts configuration from \fIFILE\fR instead of +\fI/etc/ca-scripts.conf\fR. +. +.TP +\fB\-d \fIDAYS\fR, \fB\-\-days \fIDAYS\fR +Sign the certificate to be valid for \fIDAYS\fR days instead of the default of +one year. +. +.TP +\fB\-n \fINAME\fR, \fB\-\-alt-name \fINAME\fR +Only valid for \fIserver\fR type certificates. Specifies an alternative host +name to add to the X.509v3 \fIsubjectAltName\fR extension field, which will +also be recognised as a valid host name for the certificate. May be provided +multiple times to add multiple host names. +. +.TP +\fB\-p\fR, \fB\-\-pkcs12\fR +Generate a PKCS#12 format certificate archive containing the new certificate +and private key along with the CA certificate. See +.BR pkcs12 (1ssl) +for more details about PKCS#12 archives. +. +.TP +\fB\-r\fR, \fB\-\-csr-only\fR +Causes \fBca-create-cert\fR to generate just the X.509 certificate signing +request (CSR) from a pre-existing openssl request configuration, without +signing it to create a valid certificate. When used in conjunction with +\fB\-\-cnf-only\fR, \fBca-create-cert\fR only generates the openssl request +configuration, allowing the user to modify it before creating the CSR. Mutually +exclusive to \fB\-\-crt-only\fR. +. +.TP +\fB\-s\fR, \fB\-\-crt-only\fR +Causes \fBca-create-cert\fR to sign a pre-existing CSR using a pre-existing +X.509 extensions configuration, creating a valid certificate. When used in +conjunction with \fB\-\-cnf-only\fR, \fBca-create-cert\fR only generates the +X.509 extensions configuration, allowing the user to modify it before signing +the certificate. Mutually exclusive to \fB\-\-csr-only\fR. +. +.TP +\fB\-x\fR, \fB\-\-cnf-only\fR +Causes \fBca-create-cert\fR to generate the openssl request and X.509 +extensions configurations, without creating a CSR or signing it. When used in +conjunction with either of the previous two options, causes only one of the two +configuration files to be generated. +. +.SS Distinguished Name (DN) options +These options allow the user to change the value of various DN fields. Be careful +about changing the C and O fields, as by default the CA configuration requires +these to match the fields in the CA certificate when the CSR is signed. By +default these values are taken from the ca-scripts configuration file, and will +match those of the CA certificate. The certificate's common name (CN) is set by +the mandatory host or user name parameter. +. +.TP +\fB\-\-country \fI"STRING"\fR +Sets the country (C) field of the DN. +.TP +\fB\-\-state \fI"STRING"\fR +Sets the state (ST) field of the DN. +.TP +\fB\-\-loc \fI"STRING"\fR +Sets the locality (L) field of the DN. +.TP +\fB\-\-org \fI"STRING"\fR +Sets the organization (O) field of the DN. +.TP +\fB\-\-ounit \fI"STRING"\fR +Sets the organizational unit (OU) field of the DN. +.TP +\fB\-\-email \fI"STRING"\fR +Sets the e-mail address (E) field of the DN. +.TP +\fB\-\-comment \fI"STRING"\fR +Sets the nsComment X.509 extension. +. +.SH CERTIFICATE TYPES +.SS Server certificates +.PP +\fIServer\fR certificates are used for securing SSL/TLS services, such as +TLS-encrypted LDAP connections or HTTPS. In this case the \fIhostname\fR +argument is used for the Common Name in the certificate, and any additional +alternative names supplied by \fB-n\fR are added to the X.509v3 +\fIsubjectAltName\fR extension field. + + +.SS Client certificates +.PP +\fIClient\fR certificates are used for authenticating to SSL/TLS services. +For the most part they are intended to be used by automated systems to identify +and authenticate themselves to services they interact with. +.PP +.SS User certificates +\fIUser\fR certificates are for individuals to authenticate themselves to +SSL/TLS services in the same manner as client certificates, but they may also +be used for S/MIME e-mail encryption and code signing. diff --git a/doc/ca-init.1 b/doc/ca-init.1 index 545ab43..0b0176d 100644 --- a/doc/ca-init.1 +++ b/doc/ca-init.1 @@ -1,6 +1,6 @@ .TH "ca-init" "1" "16 October 2009" "ca-scripts version 0.9" "SSL Certificate Authority utilities" .SH NAME -ca-init \- initialise an SSL CA and generate certificates +ca-init \- initialise an X.509 SSL CA and generate CA certificate . .SH SYNOPSIS . @@ -18,11 +18,10 @@ ca-init \- initialise an SSL CA and generate certificates . .SH DESCRIPTION . -\fBca-init\fR reads the ca-scripts configuration file passed to the \fB\-f\fR -or \fB\-\-config\fR option, or \fI/etc/ca-scripts.conf\fR by default, and uses -the information there to generate an +.BR ca-init (1) +reads the ca-scripts configuration file and generates an .BR openssl (1) -configuration file and a certificate and private key suitable for use as an +configuration file and an X.509 certificate and key suitable for use as an .BR x509 (1) certificate authority. The format of the ca-scripts configuration file is documented in @@ -32,8 +31,7 @@ documented in . .TP \fB\-h\fR, \fB\-\-help\fR -Prints out a short synopsis of the options to -.BR ca-init (1). +Prints out a short synopsis of the options to \fBca-init\fR. . .TP \fB\-c\fR, \fB\-\-encrypt\fR diff --git a/doc/create-p12.txt b/doc/create-p12.txt deleted file mode 100644 index 4fee2ed..0000000 --- a/doc/create-p12.txt +++ /dev/null @@ -1,17 +0,0 @@ -# a brief man-page for create-p12.sh -# $Id: create-p12.txt 2660 2009-07-24 18:49:52Z alexeb $ - -NAME - create-p12.sh - create a PKCS#12 archive of a certificate and key - -SYNOPSIS - create-p12.sh /path/to/certificate - create-p12.sh - -DESCRIPTION - This script exports a PKCS#12 archive containing a user's certificate, - private key, and the CA certificate. It will prompt for a password to - lock the archive with, and then place it in p12/. - -OPTIONS - This script takes no options.