345 lines
11 KiB
Bash
Executable file
345 lines
11 KiB
Bash
Executable file
#! /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 Common 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.
|
|
|
|
=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<--req-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<--sign-only>.
|
|
|
|
=item B<-s>, B<--sign-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<--req-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
|