diff --git a/doc/ca-create-cert.1 b/doc/ca-create-cert.1 deleted file mode 100644 index fd53b7f..0000000 --- a/doc/ca-create-cert.1 +++ /dev/null @@ -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 - -. -.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. diff --git a/doc/ca-create-cert.pod b/doc/ca-create-cert.pod new file mode 100755 index 0000000..7c7a217 --- /dev/null +++ b/doc/ca-create-cert.pod @@ -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 -t I [B<-cprsx>] [B<-f> I] [B<-d> I] +[B<-n> I] [I] + +B [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 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 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. + +=item B<-t> I, B<--type> I + +This argument is mandatory. B can create three types of +X.509 certificate: I, I, and I. 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 +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 or I type certificates, but is probably a good idea for +I certs. + +=item B<-f> I, B<--config> I + +Load the ca-scripts configuration from I instead of +I. + +=item B<-d> I, B<--days> I + +Sign the certificate to be valid for I days instead of the default of +one year. + +=item B<-n> I, B<--alt-name> I + +Only valid for I type certificates. Specifies an alternative host +name to add to the X.509v3 I 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 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 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 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 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 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 certificates are used for securing SSL/TLS services, such as +TLS-encrypted LDAP connections or HTTPS. In this case the I 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 extension +field. + +=head2 Client certificates + +I 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 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 diff --git a/doc/ca-init.1 b/doc/ca-init.1 deleted file mode 100644 index 0b0176d..0000000 --- a/doc/ca-init.1 +++ /dev/null @@ -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). -. diff --git a/doc/ca-init.pod b/doc/ca-init.pod new file mode 100755 index 0000000..865ab1b --- /dev/null +++ b/doc/ca-init.pod @@ -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 [B<-csx>] [B<-f> I] [B<-i> I