#! /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(1)" < $0
elif [ "$1" == "text" ]; then
  exec /usr/bin/pod2text -o $0
fi
echo "Unrecognised output format '$1', try man, html, or text."
exit 1

=pod

=head1 NAME

ca-create-cert - generate a signed X.509 SSL certificate

=head1 SYNOPSIS

B<ca-create-cert> [B<-cpqrsx>] [B<-f> I<config>] [B<-t> I<type>] [B<-d> I<days>]
[B<-b> I<bits>] [B<-n> I<name>] [I<options>] <common name>

B<ca-create-cert> [B<-h>] | [B<--help>]

=head1 DESCRIPTION

B<ca-create-cert> 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 B<CA_DOMAIN> in this case, though the unqualified name is preserved
as an additional DNS name in the X.509v3 I<subjectAltName> extension. User names
are treated as unqualified if they do not contain an "@" symbol and are fully
qualified with the value of B<CA_DOMAIN> in this case, yielding a CN like
I<user@example.com> assuming B<CA_DOMAIN> was set to I<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>

B<ca-create-cert> can create three types of X.509 certificate: I<server>,
I<client>, and I<user>. The type can also be set using the config variable
B<CA_CRT_TYPE>; it defaults to I<server> in the absence of either the command
line or config variable being present. Certificate types 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
B<CA_CRT_DAYS> set in the configuration file.

=item B<-b> I<BITS>, B<--bits> I<BITS>

Generate a I<BITS>-bit certificate instead of the default B<CA_CRT_BITS> set in
the configuration file. Traditionally this is a power of two, e.g. 1024 or 2048.

=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<-q>, B<--no-qualify>

Disable qualifying of the certificate's common name (and alternative names) with
B<CA_DOMAIN>.

Host names for I<server> and I<client> certificates are treated as unqualified
if they do not contain any dots and qualified to I<common name>.B<CA_DOMAIN>.
The unqualified name is preserved as an additional DNS name in the X.509v3
I<subjectAltName> extension in this case. User names are treated as unqualified
if they do not contain an "@" symbol and are qualified to I<common
name>@B<CA_DOMAIN>.

=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. As per the X.509 spec, this field
is removed from the DN and placed in the X.509v3 I<subjectAltName> extension
when the certificate is signed.

=item B<--comment> I<"STRING">

Sets the nsComment X.509 extension.

=back

=head1 CERTIFICATE TYPES

B<ca-create-cert> generates three types of certificates, differentiated by the
SSL extensions present in the signed cert. It will always generate X.509v3
certificates; creating a v1 certificate is not supported. All certificate types
have the following extensions present:

=over

=item basicConstraints = critical, CA:FALSE

Prevents the certificate from being used as a CA.

=item nsRevocationUrl = B<CA_CRL_URI>

Points to the world-accessible CRL distribution point for the CA.

=item issuerAltName = issuer:copy

Records the issuing CA certificate's I<subjectAltName> extension as
I<issuerAltName>.

=item subjectKeyIdentifier = hash

Records the certificate's fingerprint as the information used to uniquely
identify the certificate.

=item authorityKeyIdentifier = keyid;issuer:always

Records the issuing CA certificate's fingerprint, DN, and serial for
verification purposes.

=item authorityInfoAccess = caIssuers;URI:B<CA_CRT_URI>

Points to the world-accessible CA certificate distribution point.

=item crlDistributionPoints = URI:B<CA_CRL_URI>

Points to the world-accessible CRL distribution point for the CA.

=back

=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.

I<Server> certificates contain the following extensions:

=over

=item nsCertType = server

Marks the certificate as valid for server authentication. This is the old
Netscape SSL extension, but many things still rely on it.

=item keyUsage = critical, keyEncipherment, keyAgreement

Allows the certificate to be used for key negotiation and encryption.

=item extendedKeyUsage = serverAuth

Marks the certificate as valid for server authentication. This is the newer
X.509v3 extension.

=item subjectAltName = @server_altname

Includes the templated [server_altname] extensions section as the X.509v3
I<subjectAltName>. This extension contains alternate DNS entries for the server as
provided to the B<--alt-name> option, as well as the CA certificate URI and the
e-mail address provided to the B<--email> option.

=back

=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.

I<Client> certificates contain the following extensions:

=over

=item nsCertType = client

Marks the certificate as valid for client authentication. This is the old
Netscape SSL extension, but many things still rely on it.

=item keyUsage = critical, keyEncipherment, keyAgreement, digitalSignature

Allows the certificate to be used for key negotiation, encryption and creating
digital signatures. The latter option is useful for e.g. automatically creating
signed tarballs for distribution.

=item extendedKeyUsage = clientAuth, timeStamping

Marks the certificate as valid for client authentication and digital time
stamping. This is the newer X.509v3 extension.

=item subjectAltName = @client_altname

Includes the templated [client_altname] extensions section as the X.509v3
I<subjectAltName>. This extension contains the CA certificate URI and the e-mail
address provided to the B<--email> option.

=back

=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, data encryption and code signing.

I<User> certificates contain the following extensions:

=over

=item nsCertType = client

Marks the certificate as valid for client authentication. This is the old
Netscape SSL extension, but many things still rely on it.

=item keyUsage = critical, keyEncipherment, keyAgreement, digitalSignature, nonRepudiation, dataEncipherment

Allows the certificate to be used for key negotiation and encryption; creating
digital signatures; validating the source of signed data; and encrypting data.

=item extendedKeyUsage = clientAuth, codeSigning, emailProtection

Marks the certificate as valid for client authentication, code signing, and
S/MIME e-mail encryption. This is the newer X.509v3 extension.

=item subjectAltName = @user_altname

Includes the templated [user_altname] extensions section as the X.509v3
I<subjectAltName>. This extension contains the CA certificate URI and the e-mail
address provided to the B<--email> option.

=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 B<ca-create-cert>
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-init(1), ca-renew-cert(1), ca-revoke-cert(1), ca-scripts.conf(5),
openssl(1ssl), ca(1ssl), req(1ssl), x509(1ssl), config(5ssl), and
x509v3_config(5ssl).

=cut