Configuring Private Keystores#

As opposed to adding new certificates to the configuration, adding a keystore with a private key involves other actions than adding a certificate with just a public key, as a private key is usually transported with some layer of protection. There are two approaches for adding a new keystore to the configuration. The first method interacts with the configuration service, that validates and adds a given keystore into a running configuration. The other method is for preparing a keystore to be used in an XML-snippet that can be loaded by the server when it is configuring.

Both methods rely on starting with a private key that is stored in a base64-encoded PKCS12 or JKS file format.

You can use tools like openssl to convert between existing keystore formats, or to create new key pairs. If you need to create a new RSA key pair, for example, you can use the following commands to create a new PKCS12 keystore with a 2048 bits RSA key pair, that is base64-encoded:

$ openssl req -x509 -sha256 -newkey rsa:2048 -keyout curity.key -out curity.crt -days 365
$ openssl pkcs12 -export -name curity -in curity.crt -inkey curity.key -out curity.p12
$ openssl base64 -in curity.p12 -out curity.p12-b64

Using an Action to Add a Keystore#

A keystore can be added through the CLI.

Before getting into the CLI, prepare the base64-encoded file with the keystore to eliminate chunked lines and make it a one-liner. You can do that using the tr command line tool to do this:

$ tr -d '\n' < curity.p12-b64

The output is something you want to copy into your clipboard for use in the CLI.

Next, get into the CLI. Once you have connected, enter the following command to add the new signing key:

request facilities crypto add-signing-key-keystore id new-signing-key-alias

Replace new-signing-key-alias with the desired id of the new keystore.

The CLI will ask for a value for keystore; here you should paste the contents of the base64-encoded keystore (e.g. the contents of the curity.p12-b64 file). Also enter the password that protects the PKCS12 keystore. The interaction should look something like this:

admin@my-host% request facilities crypto add-signing-key-keystore id new-signing-key-alias-from-cli
Value for 'keystore' (<string, min: 1 chars>): MIILAAIBAzCCCsYGCSqGSIb3DQEHAaC....qA7KxkOQQIsHfJOFKfsQECAggA
Value for 'password' (<string, min: 1 chars>): Password1
status true

(keystore contents abbreviated for readability).

For a list of all possible actions that can be used to manage (i.e. add/replace) keystores, type request facilities crypto in the CLI and then press tab for autocomplete. This will list actions with their descriptions.

admin@my-host% request facilities crypto
Possible completions:
  add-decryption-key-keystore    - This action adds a new Server SSL key to the configuration
  add-encryption-key-keystore    - This action adds a new Server SSL key to the configuration
  add-signature-verification-key - This action adds a new Signature verification key to the configuration
  add-signer-truststore          - This action adds a new signer truststore to the configuration
  add-signing-key-keystore       - This action adds a new signing key to the configuration
  add-ssl-client-keystore        - This action adds a new SSL client key to the configuration
  add-ssl-client-truststore      - This action adds a new Client SSL truststore to the configuration
  add-ssl-server-keystore        - This action adds a new Server SSL key to the configuration
  add-ssl-server-truststore      - This action adds a new Server SSL truststore to the configuration
  apply-csr-response             - This action sets a certificate chain into a key store
  generate-csr                   - This action generates a CSR (Certificate Signing Request) from a keystore with a private key and a certificate
  generate-signing-key-keystore  - This action creates and adds a new signing key to the configuration
  generate-ssl-server-keystore   - This action creates and adds a new Server SSL key to the configuration

These actions can also be invoked using the RESTCONF API. See the Invoking YANG Actions Using RESTCONF section for more information on how to do that.

Preparing the Keystore for Embedding in an XML Configuration Document#

In case you are preparing an XML configuration file, you can use the conversion tools to process a PKCS12 keystore into the data that can be used to configure the crypto facilities of the Identity Server. See the section on Converting keystores (keystore-entry) into correct PKCS#12 format .

The output of the conversion, a base64-encoded string, can be used in an XML-snippet:

<config xmlns="http://tail-f.com/ns/config/1.0">
    <facilities xmlns="https://curity.se/ns/conf/base">
        <crypto>
            <signing-keys>
                <signing-key>
                    <id>default-signing-key</id>
                    <keystore>MIILAAIBAzCCCsYGCSqGSIb3DQEHAaC....qA7KxkOQQIsHfJOFKfsQECAggA</keystore>
                </signing-key>
            </signing-keys>
        </crypto>
    </facilities>
</config>

(keystore contents abbreviated for readability).

This XML can be added to the configuration in $IDSVR_HOME/etc/init and reloaded using the normal procedure.

Was this helpful?