README

Private Certification Authority
===============================

PCA is not what some might call an Enterprise grade Certification Authority,
it's intended as a enhanced replacement for something like easy-rsa.

Important characteristics:

 * Developed on Ubuntu 20.04 using GNU TLS 3.6.13
 * Written as a dash compatible Bourne shell script (trivially adaptable)
 * Only has limited error handling
 * Has not been exhaustively tested
 * Has not been audited by a third party (but should be fairly easy to audit)
 * Depends on GNU TLS' certtool
 * Only handles basic revocation through a CRL (no built-in OCSP support)

Critical considerations for use:

 * Consider operating an authority from a LUKS encrypted partition
 * Consider operating an authority from a machine that is permanently air gapped from your network
 * You need to verify the correct operation of the script on your particular system
 * You need to trust GNU TLS' private key generation
 * You need to trust your systems entropy handling
   Consider looking into using a hardware entropy source like a ChaosKey (from Altus Metrum)
   Particularly for generating the authorities themselves (as these are long lived private keys)


Basic Usage
-----------

Download and install:

$ sudo apt-get install gnutls-bin gnupg
$ sudo wget https://raw.githubusercontent.com/pmjdebruijn/pca/master/pca -o /usr/local/bin/pca
$ sudo chmod 755 /usr/local/bin/pca

$ pca -h

Create a root certificate authority:

$ pca -a RSA -o 'ACME Corporation' -c 'US' root ACME

Create an intermediate certificate authority for infrastructure purposes:

$ pca -a RSA -o 'ACME Corporation' -c 'US' inter ACME Infrastructure

Generate a server certificate with a single domain name:

$ pca -a RSA -o 'ACME Corporation' -c 'US' server ACME/Infrastructure example.org

Generate a server certificate including the www subdomain (which is common for commercial authorities):

$ pca -a RSA -o 'ACME Corporation' -c 'US' -d www.example.org server ACME/Infrastructure example.org

Generate a server certificate including multiple subdomains (sold as SAN certificates by commercial authorities):

$ pca -a RSA -o 'ACME Corporation' -c 'US' -d 'www.example.org www2.example.org' server ACME/Infrastructure example.org

Generate multiple certificates for the same domain name:

$ pca -a RSA -o 'ACME Corporation' -c 'US' -d 'www.example.org' -n 'example.org' server ACME/Infrastructure example.org.1
$ pca -a RSA -o 'ACME Corporation' -c 'US' -d 'www.example.org' -n 'example.org' server ACME/Infrastructure example.org.2
$ pca -a RSA -o 'ACME Corporation' -c 'US' -d 'www.example.org' -n 'example.org' server ACME/Infrastructure example.org.3

Generate a wildcard server certificate:

$ pca -a RSA -o 'ACME Corporation' -c 'US' server ACME/Infrastructure '*.dev.example.org'

Create an intermediate certificate authority for customers:

$ pca -a RSA -o 'ACME Corporation' -c 'US' inter ACME Customer

Generate a client certificate for a customer:

$ pca -a RSA -o 'ACME Corporation' -c 'US' client ACME/Customer othercorp.com

Create an intermediate certificate authority for identity verification purposes:

$ pca -a RSA -o 'ACME Corporation' -c 'US' inter ACME Identity

Generate an email certificate:

$ pca -a RSA -o 'ACME Corporation' -c 'US' -n 'John Doe' email ACME/Identity john@example.org

Generate an email certificate including a secondary email address:

$ pca -a RSA -o 'ACME Corporation' -c 'US' -n 'John Doe' -e 'j.doe@example.org' email ACME/Identity john@example.org

Create an intermediate certificate authority for code signing:

$ pca -a RSA -o 'ACME Corporation' -c 'US' inter ACME 'Code Signing'

Generate a code signing certificate:

$ pca -a RSA -o 'ACME Corporation' -c 'US' codesign ACME/'Code Signing' 'ACME Software'

Remotely generate a CSR:

$ openssl req -nodes -newkey rsa:2048 -sha256 -keyout example-org.key -out example-org.csr -subj "/C=US/ST=California/L=Sacramento/O=ACME Corporation/CN=example.org"

Place the CSR for signing:

$ mkdir -p acme/infrastructure/example-org; cp example-org.csr acme/infrastructure/example-org

Sign the CSR with your authority:

$ pca -x server acme/infrastructure example-org

Revoke a certificate:

$ pca -r revoke acme/infrastructure example.org

Show certification authority hierarchical structure:

$ find -type d acme
acme
acme/codesigning
acme/codesigning/acmesoftware
acme/customer
acme/customer/othercorp-com
acme/identity
acme/identity/john-at-example-org
acme/infrastructure
acme/infrastructure/example-org
acme/infrastructure/wildcard-dev-example-org

Note that the last parameter is used for a certificates' CN as-is, including capitilisation and spaces if quoted are used.
The script also uses the last parameter for its directory structure (but applies some normalisation, like caps removal).
Therefore the authorities can be referred to using their normalised names after they have been created.