# a brief man-page for create-cert.sh
# $Id: create-cert.txt 2660 2009-07-24 18:49:52Z alexeb $

NAME
        create-cert.sh - generate a signed X.509 certificate

SYNOPSIS
        create-cert.sh -t server [options] <hostname>
        create-cert.sh -t client [options] <hostname>
        create-cert.sh -t user   [options] <username>

DESCRIPTION
        The create-cert.sh script creates the configuration files necessary
        for generating a signed X.509 certificate, creates a certificate
        signing request using these configuration files, and signs that request
        using the root CA key so that it is trusted by anything that has
        imported the CA certificate.

OPTIONS
    -h, --help
        Prints out a short synopsis of the arguments that this script takes.

    -t, --type {server|client|user}
        This argument is mandatory. create-cert.sh can create three types of
        X.509 certificate: server, client, and user. These differ in the
        X.509v3 extensions present, and in the uses the certificate is trusted
        for.

        Server certificates are used for securing SSL/TLS services, such as
        TLS-encrypted LDAP connections or SSL HTTP. In this case the <hostname>
        argument is used for the Common Name in the certificate, and any
        additional alternative names supplied by -n are added to the X.509v3 
        "SubjectAltName" extension.

        Client certificates are used for authenticating to SSL/TLS services.
        For the most part they will be used by automated systems to identify
        and authenticate to services they interact with.

        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.

    -c, --comment "COMMENT"
        This argument sets the "Netscape Comment" X.509 extension.

    -n, --alt-name HOSTNAME
        This argument adds an alternative hostname to the "SubjectAltName"
        X.509v3 extension. It may be supplied multiple times to add more than
        one additional hostname.

    -l, --location LOCATION
        This argument sets the "Location" field of the certificate's
        distinguished name. Syggested values are "Maybrook House" and 
        "Jackson House", but the field is freeform text.

    -o, --org-unit TEAMNAME
        This argument sets the "Organisational Unit" field of the certificate's
        distinguished name. Ideally this should begin with "Manchester STG Lab"
        for consistency's sake, for example:
            
            Manchester STG Lab Systems and Network Infrastructure
            Manchester STG Lab Testing
            Manchester STG Lab Starlight Development

    -e, --email EMAIL
        This argument sets the "E-Mail Address" field of the certificate's
        distinguished name. As per current X.509 standards this is actually
        removed from the DN of the CSR and placed into the "SubjectAltName"
        extension in the signed certificate. In general it should be a team
        alias rather than an individual's address for server and client certs.

    -r, --csr-only
        This argument causes create-cert.sh to only generate a new CSR. It will
        not generate the request configuration files in cfg/ unless --tpl-only
        is also passed; in this case it will just create the configuration
        files instead. This allows you to re-generate a CSR after manually
        tweaking the configuration files.

    -s, --crt-only
        This argument causes create-cert.sh to only sign an existing CSR. As
        with --csr-only, it will not generate extension configuration files
        unless --tpl-only is also passed; again in this case it will just
        create the configuration files so that you can re-sign the same CSR
        with new extensions.

    -t, --tpl-only
        This argument modifies the behaviour of the previous two options when
        passed with them, as described above. On it's own it causes
        create-cert.sh to generate both sets of configuration files, but
        not generate either the signing request or the signed certificate.

DEFAULTS
        * The LOCATION defaults to "Maybrook House"
        * The TEAM defaults to "Manchester STG Lab Systems and Network Infrastructure"
        * The EMAIL defaults to "mcr_lab_lsni@wwpdl.vnet.ibm.com"
        * There is no COMMENT set by default