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

Writing nroff directly was interesting but ultimately a Bad Idea. Use pod instead, and generate man/text/html from them.

Browse source
This commit is contained in:
Alex Bramley 2010-02-12 09:35:54 +00:00
parent 4a85aae505
commit a560f2e713
4 changed files with 337 additions and 328 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

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

@ -1,164 +0,0 @@
.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.

183
doc/ca-create-cert.pod Executable file
View file

@ -0,0 +1,183 @@
#! /bin/sh
if [ -z "$1" -o "$1" == "man" ]; then
exec /usr/bin/pod2man -n CA-CREATE-CERT -s 1 -d "12 February 2010" \
-r "ca-scripts version 0.9" -c "SSL Certificate Authority utilities" $0
elif [ "$1" == "html" ]; then
exec /usr/bin/pod2html --title "ca-create-cert" < $0
elif [ "$1" == "text" ]; then
exec /usr/bin/pod2text -o $0
fi
=pod
=head1 NAME
ca-create-cert - generate a signed X.509 SSL certificate
=head1 SYNOPSIS
B<ca-create-cert> -t I<type> [B<-cprsx>] [B<-f> I<config>] [B<-d> I<days>]
[B<-n> I<name>] [I<options>] <host or user name>
B<ca-create-cert> [B<-h>] | [B<--help>]
=head1 DESCRIPTION
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.
=head1 OPTIONS
=head2 The host or user name
This argument to B<ca-create-cert> 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
I<user@example.com> assuming CA_DOMAIN was set to "example.com".
=head2 General options
=over
=item B<-h>, B<--help>
Prints out a short synopsis of the options to B<ca-create-cert>.
=item B<-t> I<TYPE>, B<--type> I<TYPE>
This argument is mandatory. B<ca-create-cert> can create three types of
X.509 certificate: I<server>, I<client>, and I<user>. These differ
in the X.509v3 extensions present in the signed certificate, and in the uses
the certificate is trusted for. See x509(1ssl) and x509v3_config(5ssl)
for more details about X.509 extensions, and the B<CERTIFICATE TYPES>
section of this manual for more details on the exact differences between the
certificate types.
=item B<-c>, B<--encrypt>
Encrypt the generated private key with 3DES. This is not recommended for
I<server> or I<client> type certificates, but is probably a good idea for
I<user> certs.
=item B<-f> I<FILE>, B<--config> I<FILE>
Load the ca-scripts configuration from I<FILE> instead of
I</etc/ca-scripts.conf>.
=item B<-d> I<DAYS>, B<--days> I<DAYS>
Sign the certificate to be valid for I<DAYS> days instead of the default of
one year.
=item B<-n> I<NAME>, B<--alt-name> I<NAME>
Only valid for I<server> type certificates. Specifies an alternative host
name to add to the X.509v3 I<subjectAltName> 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.
=item B<-p>, B<--pkcs12>
Generate a PKCS#12 format certificate archive containing the new certificate
and private key along with the CA certificate. See pkcs12(1ssl) for more
details about PKCS#12 archives.
=item B<-r>, B<--csr-only>
Causes B<ca-create-cert> 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
B<--cnf-only>, B<ca-create-cert> only generates the openssl request
configuration, allowing the user to modify it before creating the CSR.
Mutually exclusive to B<--crt-only>.
=item B<-s>, B<--crt-only>
Causes B<ca-create-cert> to sign a pre-existing CSR using a pre-existing
X.509 extensions configuration, creating a valid certificate. When used in
conjunction with B<--cnf-only>, B<ca-create-cert> only generates the
X.509 extensions configuration, allowing the user to modify it before signing
the certificate. Mutually exclusive to B<--csr-only>.
=item B<-x>, B<--cnf-only>
Causes B<ca-create-cert> 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.
=back
=head2 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.
=over
=item B<--country> I<"STRING">
Sets the country (C) field of the DN.
=item B<--state> I<"STRING">
Sets the state (ST) field of the DN.
=item B<--loc> I<"STRING">
Sets the locality (L) field of the DN.
=item B<--org> I<"STRING">
Sets the organization (O) field of the DN.
=item B<--ounit> I<"STRING">
Sets the organizational unit (OU) field of the DN.
=item B<--email> I<"STRING">
Sets the e-mail address (E) field of the DN.
=item B<--comment> I<"STRING">
Sets the nsComment X.509 extension.
=back
=head1 CERTIFICATE TYPES
=head2 Server certificates
I<Server> certificates are used for securing SSL/TLS services, such as
TLS-encrypted LDAP connections or HTTPS. In this case the I<hostname> argument
is used for the Common Name in the certificate, and any additional alternative
names supplied by B<-n> are added to the X.509v3 I<subjectAltName> extension
field.
=head2 Client certificates
I<Client> 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.
=head2 User certificates
I<User> 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.
=cut

164
doc/ca-init.1
View file

@ -1,164 +0,0 @@
.TH "ca-init" "1" "16 October 2009" "ca-scripts version 0.9" "SSL Certificate Authority utilities"
.SH NAME
ca-init \- initialise an X.509 SSL CA and generate CA certificate
.
.SH SYNOPSIS
.
.SY ca-init
.OP \-csx
.OP \-f config
.OP \-i template
.OP \-o output
.
.SY ca-init
.OP \-h
|
.OP \-\-help
.YS
.
.SH DESCRIPTION
.
.BR ca-init (1)
reads the ca-scripts configuration file and generates an
.BR openssl (1)
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
.BR ca-scripts.conf (5).
.
.SH OPTIONS
.
.TP
\fB\-h\fR, \fB\-\-help\fR
Prints out a short synopsis of the options to \fBca-init\fR.
.
.TP
\fB\-c\fR, \fB\-\-encrypt\fR
Encrypt the private key generated for the certificate authority with 3DES.
.
.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\-i \fIFILE\fR, \fB\-\-template \fIFILE\fR
Use the index.html template in \fIFILE\fR rather than the standard one
provided with ca-scripts. See the \fBTEMPLATING\fR section of
.BR ca-scripts.conf (5)
for more details of the templating system. Hint: it's
.BR sed (1)
based...
.
.TP
\fB\-o \fIFILE\fR, \fB\-\-output \fIFILE\fR
Generate a HTML page in \fIFILE\fR suitable for serving your CA certificate and
revocation lists via HTTP. The default template is basic but provides MD5 and
SHA1 fingerprints of both files for verification purposes.
.
.TP
\fB\-s\fR, \fB\-\-crt-only\fR
Generate the CA certificate and private key from a previously-created openssl
configuration. May only be used after having run \fBca-init\fR with the
\fB\-\-cnf-only\fR option, and mutually exclusive to that option.
.
.TP
\fB\-x\fR, \fB\-\-cnf-only\fR
Create initial CA directory structure and openssl configuration, but do not
generate CA certificate and private key. Using this option in conjunction with
\fB\-\-crt-only\fR allows the user to manually customise the openssl config
before generating the certificates. Mutually exclusive to \fB\-\-crt-only\fR.
.
.SH THE CA DIRECTORY STRUCTURE
.
\fBca-init\fR creates a number of subdirectories under the path specified in
the mandatory configuration variable \fICA_HOME\fR. This path must exist before
\fBca-init\fR will run correctly. All files and directories under this path
will be created with a restrictive umask of 0027, and in particular the CA
private key will be created with permissions of 0400.
.PP
It is recommended but not required that a non-privileged system "ssl" user and
group are created for running the ca-scripts suite of utilities, and that any
local services needing access to a certificate are added to the "ssl" group.
Access to generate certificates can be bestowed to individuals on a multi-user
system by adding them to the same group and allowing them to run ca-scripts
utilities via
.BR sudo (8).
.PP
The directories \fBca-init\fR creates are as follows:
.TP
\fIcnf/\fR
Contains a cache of openssl configuration files created by the various
ca-scripts utilities from templates.
.
.TP
\fIcrl/\fR
Contains the certificate revocation list for the CA in both PEM and DER forms.
.
.TP
\fIcrt/\fR
Contains the signed certificates generated by
.BR ca-create-cert (1).
.
.TP
\fIcsr/\fR
Contains the unsigned certificate signing requests generated by
.BR ca-create-cert (1).
.
.TP
\fIdb/\fR
Contains internal
.BR openssl (1ssl)
database files required for certificate authority management.
.
.TP
\fIidx/\fR
Contains signed certificates indexed by serial number to make certificate
revocation simpler.
.
.TP
\fIkey/\fR
Contains the private keys associated with the certificates in \fIcrt/\fR.
.
.TP
\fIp12/\fR
Contains any generated PKCS#12 certificate archives created by
.BR ca-create-cert (1).
.
.SH BUGS
Probably. Of particular note is that the default openssl configuration file
requires the C (country) and O (organisation) fields of all generated
certificates to match those in the CA certificate, but
.BR ca-create-cert (1)
allows these fields to be changed.
.
.SH AVAILABILITY
New releases of the ca-scripts utilities can be found at
.UR http://\:www.pl0rt.org/\:code/\:ca-scripts
the developer's website.
.UE .
A
.UR git://\:git.pl0rt.org/\:alex/\:code/\:ca-scripts
git repository
.UE
for development versions also exists.
.
.SH AUTHORS
.
Copyright \(co 2009
.MT a.bramley@gmail.com
Alex Bramley
.ME .
.
.SH SEE ALSO
.
.BR ca-create-cert (1),
.BR ca-scripts.conf (5),
.BR openssl (1ssl),
.BR ca (1ssl),
.BR req (1ssl),
.BR x509 (1ssl),
.BR config (5ssl), and
.BR x509v3_config (5ssl).
.

154
doc/ca-init.pod Executable file
View file

@ -0,0 +1,154 @@
#! /bin/sh
if [ -z "$1" -o "$1" == "man" ]; then
exec /usr/bin/pod2man -n CA-INIT -s 1 -d "12 February 2010" \
-r "ca-scripts version 0.9" -c "SSL Certificate Authority utilities" $0
elif [ "$1" == "html" ]; then
exec /usr/bin/pod2html --title "ca-init" < $0
elif [ "$1" == "text" ]; then
exec /usr/bin/pod2text -o $0
fi
=pod
=head1 NAME
ca-init - initialise an X.509 SSL CA and generate CA certificate
=head1 SYNOPSIS
B<ca-init> [B<-csx>] [B<-f> I<config>] [B<-i> I<template>] [B<-o> I<output>]
B<ca-init> [B<-h>] | [B<--help>]
=head1 DESCRIPTION
ca-init(1) reads the ca-scripts configuration file and generates an openssl(1)
configuration file and an X.509 certificate and key suitable for use as an
x509(1) certificate authority. The format of the ca-scripts configuration file
is documented in ca-scripts.conf(5).
=head1 OPTIONS
=over
=item B<-h>, B<--help>
Prints out a short synopsis of the options to B<ca-init>.
=item B<-c>, B<--encrypt>
Encrypt the private key generated for the certificate authority with 3DES.
=item B<-f> I<FILE>, B<--config> I<FILE>
Load the ca-scripts configuration from I<FILE> instead of
I</etc/ca-scripts.conf>.
=item B<-i> I<FILE>, B<--template> I<FILE>
Use the index.html template in I<FILE> rather than the standard one provided
with ca-scripts. See the B<TEMPLATING> section of ca-scripts.conf(5) for more
details of the templating system. Hint: it's sed(1) based...
=item B<-o> I<FILE>, B<--output> I<FILE>
Generate a HTML page in I<FILE> suitable for serving your CA certificate and
revocation lists via HTTP. The default template is basic but provides MD5 and
SHA1 fingerprints of both files for verification purposes.
=item B<-s>, B<--crt-only>
Generate the CA certificate and private key from a previously-created openssl
configuration. May only be used after having run B<ca-init> with the
B<--cnf-only> option, and mutually exclusive to that option.
=item B<-x>, B<--cnf-only>
Create initial CA directory structure and openssl configuration, but do not
generate CA certificate and private key. Using this option in conjunction with
B<--crt-only> allows the user to manually customise the openssl config
before generating the certificates. Mutually exclusive to B<--crt-only>.
=back
=head1 THE CA DIRECTORY STRUCTURE
B<ca-init> creates a number of subdirectories under the path specified in
the mandatory configuration variable I<CA_HOME>. This path must exist before
B<ca-init> will run correctly. All files and directories under this path
will be created with a restrictive umask of 0027, and in particular the CA
private key will be created with permissions of 0400.
It is recommended but not required that a non-privileged system "ssl" user and
group are created for running the ca-scripts suite of utilities, and that any
local services needing access to a certificate are added to the "ssl" group.
Access to generate certificates can be bestowed to individuals on a multi-user
system by adding them to the same group and allowing them to run ca-scripts
utilities via sudo(8).
The directories B<ca-init> creates are as follows:
=over
=item I<cnf/>
Contains a cache of openssl configuration files created by the various
ca-scripts utilities from templates.
=item I<crl/>
Contains the certificate revocation list for the CA in both PEM and DER forms.
=item I<crt/>
Contains the signed certificates generated by ca-create-cert(1).
=item I<csr/>
Contains the unsigned certificate signing requests generated by
ca-create-cert(1).
=item I<db/>
Contains internal openssl(1ssl) database files required for certificate
authority management.
=item I<idx/>
Contains signed certificates indexed by serial number to make certificate
revocation simpler.
=item I<key/>
Contains the private keys associated with the certificates in I<crt/>.
=item I<p12/>
Contains any PKCS#12 certificate archives created by ca-create-cert(1).
=back
=head1 BUGS
Probably. Of particular note is that the default openssl configuration file
requires the C (country) and O (organisation) fields of all generated
certificates to match those in the CA certificate, but ca-create-cert(1)
allows these fields to be changed.
=head1 AVAILABILITY
New releases of the ca-scripts utilities can be found at
L<the developer's website|http://www.pl0rt.org/code/ca-scripts>.
A L<git repository|git://git.pl0rt.org/alex/code/ca-scripts>
for development versions also exists.
=head1 AUTHORS
Copyright 2009, 2010 Alex Bramley a.bramley@gmail.com
=head1 SEE ALSO
ca-create-cert(1), ca-scripts.conf(5), openssl(1ssl), ca(1ssl), req(1ssl),
x509(1ssl), config(5ssl), and x509v3_config(5ssl).