psi-jack/ca-scripts
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity

WIP update of documentation changes

Browse source
This commit is contained in:
Alex Bramley 2009-11-02 16:22:45 +00:00
parent a8999ae0ee
commit 1d37f83385
4 changed files with 180 additions and 33 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

20
bin/ca-create-cert
View file

@ -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" \

164
doc/ca-create-cert.1 Normal file
View file

@ -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
<host or user name>
.
.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.

12
doc/ca-init.1
View file

@ -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

17
doc/create-p12.txt
View file

@ -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 <username>
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.