Importing external certificates to Stork

Certificate management

The Stork server generates its CA (Certificate Authority) and will use it to then generate its own server certificate and also any certificates needed for agents that will connect to it. This is done automatically and does not require any user intervention. The typical user does not need to interact with the PKI in any way.

However, in some environments, the administrator may prefer to generate the certificates externally and import them into Stork. This might be preferable due to a policy requirement to avoid self-signed certificates, for example. This article explains how to do this.

Step 1: Generating CA certificate

The following example uses OpenSSL to generate the certificates.

The first step is to generate the CA private key and CA cert using the OpenSSL config file (ca_gen_config.cfg) like this:

[ req ]
default_md         = sha256
default_keyfile    = ca.key
encrypt_key        = no
prompt             = no
distinguished_name = req_distinguished_name
x509_extensions    = req_x509_extensions

[ req_distinguished_name ]
C  = US
O  = ISC Stork
CN = Root CA

[ req_x509_extensions ]
basicConstraints     = critical, CA:true, pathlen:1
keyUsage             = critical, digitalSignature, keyCertSign
extendedKeyUsage     = serverAuth, clientAuth
subjectKeyIdentifier = hash

Some of the fields can be tweaked. However, it is essential that the keyUsage contain digitalSignature, and keyCertSign. The Stork server must be able to generate certificates for new Stork agents. Also, the serverAuth and clientAuth options must be allowed, as the Stork server (acting as a TLS client) must be able to connect to Stork agent (acting as a TLS server).

The actual private key and certificate can be generated using a command similar to this:

$ openssl req -x509 -new -config ca_gen_config.cfg -out ca.crt  -newkey ec:<(openssl ecparam -name prime256v1) -days 10950

The generated certificate can be inspected by a command such as this:

$ openssl x509 -noout -text -in ca.crt

Certificate:
    Data:
        Version: 3 (0x2)
        Serial Number:
            20:18:b9:c0:27:3c:dc:02:4c:ac:ca:1c:b2:af:2a:88:d0:7c:b4:99
        Signature Algorithm: ecdsa-with-SHA256
        Issuer: C=US, O=ISC Stork, CN=Root CA
        Validity
            Not Before: Mar 22 09:21:44 2024 GMT
            Not After : Mar 15 09:21:44 2054 GMT
        Subject: C=US, O=ISC Stork, CN=Root CA
        Subject Public Key Info:
            Public Key Algorithm: id-ecPublicKey
                Public-Key: (256 bit)
                pub:
                    04:68:89:6f:cf:62:5b:16:e1:55:93:96:85:57:38:
                    3f:93:a6:93:18:f2:be:c9:0e:3b:33:84:8a:e0:d3:
                    85:8f:8a:76:43:11:58:b6:1f:82:61:da:51:d3:4c:
                    24:90:d4:e7:08:e3:a2:3b:87:c6:fb:99:19:d5:50:
                    90:e6:b0:78:0a
                ASN1 OID: prime256v1
                NIST CURVE: P-256
        X509v3 extensions:
            X509v3 Basic Constraints: critical
                CA:TRUE, pathlen:1
            X509v3 Key Usage: critical
                Digital Signature, Certificate Sign
            X509v3 Extended Key Usage: 
                TLS Web Server Authentication, TLS Web Client Authentication
            X509v3 Subject Key Identifier: 
                3D:49:5A:8A:FA:65:0D:15:66:10:33:8A:8F:B7:DC:03:61:D4:85:5F
    Signature Algorithm: ecdsa-with-SHA256
    Signature Value:
        30:44:02:20:46:92:22:2f:6b:42:90:ef:b2:ce:9b:de:a4:c6:
        5e:df:04:ed:d2:2f:89:bf:1a:30:18:bd:af:d3:eb:e1:1b:f2:
        02:20:20:67:fa:8a:71:02:2f:de:ee:ed:53:34:9e:c3:eb:9d:
        e5:a2:d6:1d:ee:eb:2d:03:ff:63:44:1b:d2:e2:71:a5

Step 2: Generating Server CSR

The next step is to generate the server certificates by creating a CSR (certificate signing request), for which a config file (server_gen_config.cfg) similar to the following is needed:

[ req ]
default_bits       = 2048
default_md         = sha256
default_keyfile    = srv.key
encrypt_key        = no
prompt             = no
distinguished_name = req_distinguished_name
req_extensions     = my_req_extensions

[ req_distinguished_name ]
C  = US
O  = ISC Stork
OU = server
CN = mydomain.example.com

[ my_req_extensions ]
subjectAltName        = @subject_alt_names
extendedKeyUsage     = serverAuth, clientAuth
subjectKeyIdentifier = hash

[ subject_alt_names ]
IP.1 = 127.0.0.1

The actual signing request can be generated with this command:

$ openssl req -config server_gen_config.cfg -out server.csr  -newkey ec:<(openssl ecparam -name prime256v1)

Step 3: Generating the Server certificate

Once the server.csr is in place, the next step is to sign it to get the actual server certificate. The following signing configuration (sign_config.cfg) can be used for this purpose:

[ ca ]
default_ca = my_ca

[ my_ca ]
default_md      = sha256
policy          = my_policy

# This is the CA private key we have previously generated.
private_key     = ./ca.key

# This is the CA certificate we have previously generated.
certificate     = ./ca.crt

# The newcerts directory must exist or be created: mkdir newcerts
new_certs_dir   = ./newcerts

# This file must exist but is initially empty: touch index.txt
database        = ./index.txt

# The serial file must exist and should be initialized: echo '01' > serial
serial          = ./serial

default_days    = 365
copy_extensions = copy

[ my_policy ]
countryName            = match
organizationName       = supplied
organizationalUnitName = supplied
commonName             = supplied

Prior to generating the new certificate, setup the directory for the certificates to be stored in, create a database (index file) for the certificates and a file holding the initial certificate serial number:

$ mkdir newcerts
$ touch index.txt
$ echo '01' > serial

Then, the server certificate can be finally generated and signed:

$ openssl ca -notext -config sign_config.cfg -extfile server_gen_config.cfg -out server.crt -infiles server.csr

Step 4: Importing certificates to Stork server

The certificates should be imported when the server is not running. The last step is to import the certificates and keys into the Stork server:

$ stork-tool cert-import -f cakey -i ca.key
$ stork-tool cert-import -f cacert -i ca.crt
$ stork-tool cert-import -f srvkey -i server.key
$ stork-tool cert-import -f srvcert -i server.crt

Don't forget to restart the Stork server when you are finished.