Writing nroff directly was interesting but ultimately a Bad Idea. Use pod instead, and generate man/text/html from them.
This commit is contained in:
Alex Bramley
parent
4a85aae505
commit
a560f2e713
4 changed files with 337 additions and 328 deletions
|
|
@ -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
183
doc/ca-create-cert.pod
Executable 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
164
doc/ca-init.1
|
|
@ -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
154
doc/ca-init.pod
Executable 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).
|
||||
|
||||
Loading…
Reference in a new issue