PeCR
====

The Perl Certificate Requests (PeCR) provide a way of requesting certificates from the command line. The ability to request multiple requests in one go ("Bulk" requests) and multiple SANs is a key feature.

Downloading and Installing
##########################

Get the code from SourceForge SVN

.. code-block:: shell

    svn checkout svn://svn.code.sf.net/p/ukngi/svn/PeCR/trunk PeCR

Running the command line scripts below will warn you of any missing dependencies. You can also do this yourselves directly by running perl Build.PL. The current dependencies (and one recommendation) are:

.. code-block:: perl

    my %base_requires = (
        'Getopt::Long' => 2.35,
        'Pod::Usage' => 1.14,
        'DateTime' => 0.53,
        'Carp' => 1.04,
        'LWP::UserAgent' => 2.033,
        'LWP::Protocol::https' => 0,
        'LWP::ConnCache' => 0.01,
        'Module::Load' => 0.16,
        'Math::BigInt' => 1.87,
        'IO::Socket::SSL' => 1.33,
        'Net::SSLeay' => 1.21,
        'XML::XPath' => 1.13,
        'AppConfig' => 1.56,
        'Digest::SHA' => 5.47,
    );
    my %base_recommends = (
        'Math::BigInt::GMP' => 0,
    );

Usage for single requests
#########################

Requesting a new certificate
****************************

To request a new personal UK eScience Certificate

.. code-block:: shell

    bin/cli request --cn "john kewley" -c PeCR.cfg --pin "pinforuser" --keyout ./newuserkey.pem
    # You'll now be prompted for a passphrase. CA Policy requires a min of 16 characters

Requesting a new Host Certificate requires a valid personal certificate (referenced using authcert and authkey: see the Configuration File section).

.. code-block:: shell

    bin/cli request --server --cn "rjavig6.dl.ac.uk" -c PeCR.cfg --pin "pinforhost" --keyout ./newhostkey.pem
    # You'll now be prompted for a passphrase (and conformation) to protect ./newhostkey.pem
    # and then the passphrase for the private key specified in authkey in the Config File.
    # CA Policy requires a min of 16 characters for passphrases that protect private keys
    # You may also just press <ENTER> when prompted for a host password since that they
    # are usually installed without password protection, instead relying on filesystem security

Once the request has been approved AND the certificate signed it can then be downloaded as described under "Retrieving a Certificate"

Retrieving a certifciate
************************

To retrieve a personal UK eScience Certificate

.. code-block:: shell

    bin/cli retrieve -c PeCR.cfg --certout ./newusercert.pem --keyin ./newuserkey.pem
    # You'll now be prompted for the passphrase that protects ./newuserkey.pem
    # that you provided when you made your request.

To retrieve a Host Certificate

.. code-block:: shell

    # This is the same as for a User certificate except we have provided
    # matching names to the host request to facilitate cut+paste
    bin/cli retrieve -c PeCR.cfg --certout ./newhostcert.pem --keyin ./newhostkey.pem
    # You'll now be prompted for the passphrase provided when you made your request.

Renewing a certificate
**********************

To renew a personal UK eScience Certificate

.. code-block:: shell

    bin/cli renew -c PeCR.cfg --keyout ./newuserkey.pem --pin 1234567890 --authkey ~/.globus/userkey.pem --authcert ~/.globus/usercert.pem
    # You'll now be prompted for a passphrase. CA Policy requires a min of 16 characters

To renew a Host Certificate

.. code-block:: shell

    bin/cli renew -c PeCR.cfg --keyout ./newhostkey.pem --pin 1234567890 --server --authkey ./hostkey.pem --authcert ./hostcert.pem
    # You can now just press ENTER/RETURN instead of entering a passphrase as it is a server key

Once the request has been approved AND the certificate signed it can then be downloaded as described under "Retrieving a Certificate"

Revoking a certificate
**********************

If a certificate needs revoking and you still have access to the private key then you can request this revocation as follows.

.. code-block:: shell

    bin/cli revoke -c PeCR.cfg --authcert cert.pem --authkey key.pem --reason "appropriate reason"
    # You'll now be prompted for the passphrase that protects the private key.

Bulk scripts
############

There are two additional components of PeCR for Bulk requests. One is a file containing a list of FQDNs (to be used as certificate subject names / CNs) and the other is a directory or directories into which ALL the keys (and respectively certs) of the Bulk will be placed, or indeed obtained from in the case of a Bulk Renew. Care should be taken that previous values are not overwritten when doing such a Renew. The respective key and certificate directories can be set in the config file as well as on the command line.

The FQDNs.txt file should contain one FQDN per line, no additional whitespace.

You should also set the authkey and authcert (your personal certificate) in your config file if you're doing new bulkrequests.

A new feature of the CA Portal is that your RA Operator has a "Manage Bulk" link to facilitate the approval of Bulks.

Keys are expected to have the name FQDN_key.pem and certificates FQDN_cert.pem

Restrictions
************
- All certificates in the Bulk must be within the same RA's domain (i.e. the same as your personal certificate) and their FQDNs must be within the same domain.
- To save you having to type in the same password (or just return) lots of times, we assume that the passphrases of private keys for the certificates to be renewed are identical; likewise we encrypt with a single password (or return) for all new keys generated.
- There is a maximum of 1000 requests in one bulk - please contact if this is insufficient for your needs.
- You won't currently get a reminder when your certificates are ready to download (to avoid inundating you with emails). We are hoping to sort this in the future, but in the meantime expect the certificates to be ready by close of play on the day after your RA Operator has approved them.
- You won't currently get a reminder when the certificates in your Bulk are about to expire. We are hoping to sort this in the future, but in any case it is good practice to setup your own reminders using tools such as Nagios.
- Once a bulk is created you can't add to it [although you can do Bulkrenews with a FQDNs.txt for certificates of several Bulks, and some that aren't in a Bulk - the scripts will treat them as they are, but your RA will have to do one approval for each Bulk and one for each standalone].
- There is no Bulkrevoke script and there are no plans to add it in the future.

New bulk requests
*****************

.. code-block:: shell

    # keydir and certdir must exist and be set in your config file if they aren't present on the commandline

   bin/cli bulkrequest -c PeCR.cfg --cnfile FQDNs.txt --pin "pinforbulk"

    # You'll now be prompted for the passphrase (and conformation) to protect all the keys that are stored in keydir
    #   * They must all have the same passphrase.
    #   * You may just press <ENTER> when prompted for these passphrases since they are usually installed
    #      without password protection, instead relying on filesystem security.
    # You'll then be asked for the passphrase for your certificate's private key (authkey in the Config File).
    #    NB: a 500 error usually means wrong passphrase for your personal certificate's private key.

Once the requests have all been approved (using the RA Operator's Manage Bulk i/f) AND the corresponding certificates signed (see Restrictions above) they can be downloaded as described under "Bulk Retrievals" below.

Bulk retrievals
***************

.. code-block:: shell

    # For retrieving after a NEW request then you can just use the directories in your config file
    # For renewals, to avoid overwriting old certificates, you should provide them as shown

    bin/cli bulkretrieve -c PeCR.cfg --cnfile FQDNs.txt --keydir new_bulkreqs --certdir new_bulkreqs

    # You'll now be prompted for the passphrase provided when you made your request.

Bulk renewals
*************

If you have a number of certificates that are already part of a Bulk (including under the previous regime) then they can be renewed together. 
Your RA Operator will again be able to take advantage of the new "Manage Bulk" i/f to make his/her job easier. 
They'll need gathering and placing in the same directory, in separate key and certificate .pem files with the name format described above.

.. code-block:: shell

    # keydir and certdir must exist and be set in your config file if they aren't present on the commandline (like below)
    # The files in keydir and certdir (regardless of whether you have separate directories or not) must have correct
    # permissions for hostkeys and hostcerts and be named according to the style described above

    bin/cli bulkrenew -c PeCR.cfg --server --cnfile FQDNs.txt --renewkeydir new_bulkreqs --keydir old_keydir --certdir old_certdir

    # You'll now be prompted for the passphrase (and conformation) to protect all the keys that are stored in
    #   your renewkeydir (they must all have the same passphrase).
    # You'll then be prompted for the passphrase for the private keys of the certs being renewed (again they
    #   must all be the same).
    # You may also just press <ENTER> when prompted for these passphrases since they
    #   are usually installed without password protection, instead relying on filesystem security.
    # A 500 error usually means you've got entered the wrong passphrase for the certificates being renewed.

Reference
#########

Most of the options are common for the various commands above.

``-c config-file``

Use config-file as the configuration file (see Config File).

``--cn lowercase-name``

Use lowercase-name as the Common Name (CN) in new user and host certificate requests. Renewals get their CN from the existing certificate.

``--cnfile cnfilename``

The cnfilename is the file containing a list of FQDNs (to be used as certificate subject names / CNs). These should be one per line with no whitespace, not even blank lines.

``--pin alphanumeric-PIN``

The alphanumeric-PIN should be at least 10 alphanumeric characters and will be used as the PIN that you have to provide to your RA Operator for new user and host certificate requests.

``--authcert certfilename``

Use the file certfilename as the certificate for renewals. See also --authkey.

``--authkey keyfilename``

Use the file keyfilename as the private key used for renewals. See also --authcert.

``--keyin keyfilename``

Use the file keyfilename to get the private key (created with the --keyout option during the corresponding request or rewnew) to match the certificate being downloaded during retrieval.

``--keyout keyfilename``

Use keyfilename as the filename to store the private key generated in a new or renew request. This will then need to be provided in the --keyin option during retrieval.

``--keydir keydirname``

Use keydirname as the directory in which to store the private keys generated by bulk new requests. Also the directory from which to get the previous key when doing a renewal.

``--certdir certdirname``

Use certdirname as the directory in which to store the certificates downloaded during bulk retrieval. Also the directory from which to get the previous certificate when doing a renewal.

``--renewkeydir renewkeydirname``

Use renewkeydirname as the directory in which to store the private keys generated by bulk renew requests. It is only used by Bulkrenew, keydir and certdir being used at retrieval.

``--server``

This is used for new requests to state that a host certificate is required.

``-d``

Provides some debugging information about the requests being made and the options used.

``--reason "appropriate reason"``

For revocation requests you must give an appropriate reason for why you are requesting your certificate is revoked. Since this is likely to be more than a single word it is likely that you'll have to enclose it in quotes to protect the embedded spaces from the shell.

Example config file
###################

.. code-block:: ini

    [general]
    # Certificate location for generating new host requests (.pem format)
    # authcert = ~/.globus/usercert.pem

    # Private key location for generating new host requests (.pem format)
    # authkey = ~/.globus/userkey.pem

    # Debug info
    verbose off

    # Email address for annual renewal reminders.
    # This may be different from the one stored in "authcert"
    # email = email@address-here.co.uk

    # Directory to store keys for bulk requests
    #keydir=

    # Directory into which to place retrieved certificates in bulk requests
    # Defaults to keydir if not specified
    #certdir=

    [ca]
    # Location of the live CA Server
    server = cwiz-live.ca.ngs.ac.uk:443

    # Default keysize: 2048 strongly recommended
    keybits = 2048

    # The Institution's RA (of the form /C=UK/O=eScience/OU=XXX/L=YYY) that
    # will be used to approve your request and which will form most
    # of the requested certificate's DN
    # ra = /C=UK/O=eScience/OU=XXX/L=RAL

    [ssl]
    # The openssl executable to use.
    executable = /usr/bin/openssl

    # Directory containing the trusted roots store
    cacertdir = /etc/grid-security/certificates