flakm / spki

A bash script wrapper for OpenSSL that generates and manages a simple PKI suitable for small deployments

Simple PKI

spki is a bash script wrapper for OpenSSL that generates and manages a simple PKI suitable for small deployments. It supports both CRL's and OCSP.

The wrapper is based on Jamie Nguyen's guide: OpenSSL Certificate Authority

Installation

Copy spki to a location in your path. Releases use semantic versioning to identify backwards-incompatible changes.

Configuration

The top of the script contains several configuration variables; the defaults correspond to the guide. External configuration methods that do not require script modification are also supported (see below).

ROOT_DIR - The base directory where all PKI files are stored

ROOT_PREFIX - Prefix for all Root CA files

INTRMDT_PREFIX - Prefix for all Intermediate CA files

Certificate Revocation List (CRL)

CRL's are automatically generated during initialization if either or both of the DP variables are set. The Intermedate CA Certificate will use the Root CRL DP; all other generated certificates use the Intermediate CRL DP. CRL's are automatically updated on revocation. CRL's served over http should not use https. Since the CRL files are frequently regenerated, it is recommended to serve the file directly from the spki root folder, for example by using a soft link. Furthermore, the CRL's are checked during initialization and certificate creation, so it is recommended to prepare the server in advance.

ROOT_CRL_DP - CRL Distribution Point for the Root CA (e.g. 'URI:http://domain.com/my.crl,URI:http://backup.domain.com/my.crl')

INTRMDT_CRL_DP - CRL Distribution Point for the Intermediate CA (e.g. 'URI:http://domain.com/my.crl,URI:http://backup.domain.com/my.crl')

Online Certificate Status Protocol (OCSP)

OCSP signing keys are automatically generated during initialization if either or both of the OCSP variables are set.

ROOT_OCSP - Root CA OCSP Server (e.g. 'URI:http://ocsp.domain.com')

INTRMDT_OCSP- Intermediate CA OCSP (e.g. 'URI:http://ocsp.domain.com')

External Configuration

Configuration can be specified externally, without modifying the script, via environment variables. The precedence order of the configuration methods is:

1. Configuration File
2. Environment Variables
3. In-script Variables

Configuration File

The configuration file can be specified in the environment variable SPKI_CONFIG_FILE. This file is loaded directly by bash and should contain a list of local variable definitions such as

ROOT_DIR=/root/ca
ROOT_PREFIX=root

#
# below properties are optional and used to provide reasonable defaults for openssl
# you will be still promped to input actual values 
#
countryName=PL
stateOrProvinceName=Warsaw
localityName=Warsaw
organizationalUnitName=R&D
organizationName=Company Ltd
[email protected]

Note: If this file is loaded, all other environment variables are ignored.

Environment Variables

The variables in the script itself can be overriden by environment variables. The environment variable name should be those in the script but prefixed with SPKI_ (e.g. SPKI_ROOT_DIR and SPKI_ROOT_CRL_DP).

Usage

• spki init - Initialize the PKI. This process first sets up the default Subject fields in the OpenSSL configuration files, then generates the Root CA, Intermediate CA, and a combined CA chain file. CRL's and OCSP certificates are also generated

• spki create (server | user | client_server) <file-prefix> - Create and sign a key pair with the Intermediate CA. server, user or client_server specifies particular extensions to use. These can be modified by changing the configuration files after initialization. The file-prefix is prepended to various file extensions (.key.pem, .cert.pem, .csr.pem)

  • server

    • nsCertType = server
    • authorityKeyIdentifier = keyid,issuer:always
    • keyUsage = critical, digitalSignature, keyEncipherment
    • extendedKeyUsage = serverAuth

  • user

    • nsCertType = client, email
    • authorityKeyIdentifier = keyid,issuer
    • keyUsage = critical, nonRepudiation, digitalSignature, keyEncipherment
    • extendedKeyUsage = clientAuth, emailProtection

  • client_server

    • nsCertType = client, server
    • authorityKeyIdentifier = keyid,issuer
    • keyUsage = critical, nonRepudiation, digitalSignature, keyEncipherment
    • extendedKeyUsage = clientAuth, serverAuth

• spki create-intermediate - Recreate the Intermediate CA key and certificate. This command also regenerates the Intermediate CRL if necessary

• spki sign (server | user | client_server) <CSR> <certificate> - Sign a specified CSR file with the server, user or client_server extensions (see above). certificate specifies the output file

• spki list - List all of the certificates signed by the Intermediate CA, including expiration times and revocation times

• spki verify (certificate | file-prefix) - Dump the certificate information and verify the chain of trust using the Root CA->Intermediate CA chain. Can be specified as a file or as the prefix used in spki create

• spki export-pkcs12 <file-prefix> - Export the key, certificate, and CA chain file to pkcs12 format

• spki export-truststore <file-prefix> - Export CA chain file to pkcs12 format compatible with java expectations. Requires keytool (bundled with java)

• spki revoke (certificate | file-prefix) [reason] - Revoke the specified certificate. reason can be one of: unspecified, keyCompromise, CACompromise, affiliationChanged, superseded, cessationOfOperation, certificateHold. This command automatically regenerates the Intermediate CRL

• spki revoke-intermediate [reason] - Revoke the Intermediate CA certificate. reason can be one of the options above. This command automatically regenerates the Root CRL

• spki list-crl - Dump information about the CRL's and the revoked certificates

• spki generate-crl [-rootca] - Generate the Intermediate CRL file. This should be run regularly. Pass -rootca to generate the Root CRL file

• spki generate-ocsp [-rootca] - Generate the Intermediate OCSP signing pair. Pass -rootca to generate the Root OCSP signing pair

• spki ocsp-responder <port> [-rootca] - Start an OCSP responder on the specified port using openssl ocsp. The command by default uses the Intermediate CA database, but can be changed to the Root CA database by passing -rootca. This can be turned into a service by using systemd, for example, but the OpenSSL OCSP responder may not be suitable for high traffic.

• spki ocsp-query <url> (certificate | file-prefix) [-rootca] - Send an OCSP query for the specified certificate to the specified url (e.g. http://127.0.0.1:12345). The command uses the full chain file by default, suitable for verifying certificates signed by the Intermediate CA. Specify -rootca to use just the Root CA, suitable for verifying the Intermediate CA certificate.

• spki update-config - Regenerate the openssl configuration files. This allows the configuration variables, such as CRL or OCSP to be updated. It re-prompts for the certificate defaults.

Providing automated inputs

Provided that you prepare config file named config with default DN names (countryName,stateOrProvinceName,localityName,organizationalUnitName,organizationName and emailAddress) ie:

ROOT_DIR=/tmp/spki/
countryName=PL
stateOrProvinceName=Warsaw
localityName=Warsaw
organizationalUnitName=Developers
organizationName=Company Ltd
[email protected]

You can use following script to create all stores in one go:

SPKI_CONFIG_FILE=$(pwd)/config
export SPKI_CONFIG_FILE

source $SPKI_CONFIG_FILE

CA_PRIVATE_KEY_PASSWORD="changeit"
CA_COMMON_NAME="ca"
CA_COUNTRY_NAME="$countryName"
CA_PROVINCE_NAME="$stateOrProvinceName"
CA_LOCALITY_NAME="$localityName"
CA_ORGANIZATION_NAME="$organizationName"
CA_ORGANIZATIONAL_UNIT_NAME="$organizationalUnitName"
CA_MAIL="$emailAddress"

INTERMEDIATE_COMMON_NAME="intermediete"
INTERMEDIATE_COUNTRY_NAME="$countryName"
INTERMEDIATE_PROVINCE_NAME="$stateOrProvinceName"
INTERMEDIATE_LOCALITY_NAME="$localityName"
INTERMEDIATE_ORGANIZATION_NAME="$organizationName"
INTERMEDIATE_ORGANIZATIONAL_UNIT_NAME="$organizationalUnitName"
INTERMEDIATE_MAIL="$emailAddress"

INTERMEDIATE_PRIVATE_KEY_PASSWORD="changeit2"

ANYKEY="k"
YES="y"

./spki init <<EOF
$CA_PRIVATE_KEY_PASSWORD
$CA_PRIVATE_KEY_PASSWORD
$CA_COMMON_NAME
$CA_COUNTRY_NAME
$CA_PROVINCE_NAME
$CA_LOCALITY_NAME
$CA_ORGANIZATION_NAME
$CA_ORGANIZATIONAL_UNIT_NAME
$CA_MAIL
$ANYKEY$INTERMEDIATE_PRIVATE_KEY_PASSWORD
$INTERMEDIATE_PRIVATE_KEY_PASSWORD
$INTERMEDIATE_COMMON_NAME
$INTERMEDIATE_COUNTRY_NAME
$INTERMEDIATE_PROVINCE_NAME
$INTERMEDIATE_LOCALITY_NAME
$INTERMEDIATE_ORGANIZATION_NAME
$INTERMEDIATE_ORGANIZATIONAL_UNIT_NAME
$INTERMEDIATE_MAIL
$YES
$YES
$ANYKEY
EOF


BROKER_PRIVATE_KEY_PASSWORD="changeit"
BROKER_COMMON_NAME="broker"
./spki create client_server broker -SAN "IP:127.0.0.1" <<EOF
$BROKER_PRIVATE_KEY_PASSWORD
$BROKER_PRIVATE_KEY_PASSWORD
$BROKER_COMMON_NAME
$CA_COUNTRY_NAME
$CA_PROVINCE_NAME
$CA_LOCALITY_NAME
$CA_ORGANIZATION_NAME
$CA_ORGANIZATIONAL_UNIT_NAME
$CA_MAIL
$INTERMEDIATE_PRIVATE_KEY_PASSWORD
$YES
$YES
$ANYKEY
EOF

Examples

• spki init

• spki create, spki revoke

• spki ocsp-responder, spki ocsp-query