Key Management

Overview

IBM Security Verify Access OIDC Provider (ISVAOP) uses keys and certificates for these purposes:

Starting up HTTPS Server
JSON Web Token (JWT) signing and encryption processing
Communication with external servers such as database, LDAP, Redis, and HTTP call-out.

Referencing keys and certificates

ISVAOP offers three options for key management:

Using a packaged keystore that contains a prescribed directory structure for personal and signer certificates. It also allows the use of a packaged p12 file. This is illustrated below:

/var/isvaop/config/
  |
  - keystore
    |
    <keystore-name>
        |
        - personal
        |   |
        |   - <privatekey1>.pem
        |   - ...
        |   - <privatekeyn>.pem
        |
        - signer
            |
            - <publickey1>.pem
            - ...
            - <publickeyn>.pem

Using direct file references: Here the file may be placed relative to the /var/isvaop/config directory and the relative path may be directly referneces in the YAML configuration.
Using base64-encoded PEM directly embedded in the YAML configuration.

It is recommended that keystores be used for CAs and other trusted certificates. Also, the use of p12 makes it convenient to package and distribute the keystore. However, for self-signed certificates and other such simpler cases, use direct file reference.

Referencing the source

This is a standard notation used for certificates and keys in the ISVAOP configuration. As described, there are three methods of referencing certificates and they are shown below:

ks: Represents a keystore which is a collection of certificate and key files, the file system path that it will look under is /var/isvaop/config/keystore. If its used for a private key property, the PEM encoded file is looked up under /var/isvaop/config/keystore/<keystore-name>/personal/ folder. If its used for a public key/signer certificate, the equivalent PEM encoded file is looked up under /var/isvaop/config/keystore/<keystore-name>/signer/ folder. Note that the files must end with the ".pem" extension. A sample is provided below, where the PostgreSQL connection is being configured.
```
server_connections:                                       # Server connections
- name: mypq                                              # Connection name
    ...
    ssl:
    certificate:                                          # The SSL connection certificate array.
        - ks:postgres_keys                                # The SSL keystore to be used for SSL connections. ks: indicates keystore.
    mutual_auth:
        key: ks:rt_profile_keys/postgres                  # When mutual TLS is needed, specify the keystore and label that contains the client's private key.
        certificate: ks:rt_profile_keys/postgres          # When mutual TLS is needed, specify the keystore and label of the client's leaf certificate.
        ca:
        - ks:rt_profile_keys/ca                           # When mutual TLS is needed, specify the keystore and label of the client's CA certificate.
    disable_hostname_verification: false                  # The SSL connection validates the hostname.
```
- The trusted certificates are read from the keystore named "postgres_keys". All signer certificates are enumerated from /var/isvaop/config/keystore/postgres_keys/signer.
- For Mutual SSL connections, the key postgres.pem is read from /var/isvaop/config/keystore/rt_profile_keys/personal.
- For Mutual SSL connections, the leaf certificate postgres.pem is read from /var/isvaop/config/keystore/rt_profile_keys/signer.
- For Mutual SSL connections, the CA certificates are read from /var/isvaop/config/keystore/rt_profile_keys/signer.

@ represents a file. The file path follows @ and is relative to /var/isvaop/config/. Any PEM encoded certificate may be used. The file extension can be anything. This is illustrated below.

server_connections:                                       # Server connections
- name: mypq                                              # Connection name
  ...
  ssl:
    certificate:                                          # The SSL connection certificate array.
      - "@postgres_keys/postgres.crt"                     
    mutual_auth:
      key: "@rt_profile_keys/postgres.pem"
      certificate: "@rt_profile_keys/postgres.pem"
      ca:                                                 
        - "@rt_profile_keys/postgres-intermediate.pem"    
    disable_hostname_verification: false

Certificate postgres.crt is read from /var/isvaop/config/postgres_keys/.
For Mutual SSL connections, the key postgres.pem is read from /var/isvaop/config/rt_profile_keys/. The other properties are similarly self-explanatory.

B64: represents a base64-encoded certificate or key. This is illustrated below:

server_connections:                                       # Server connections
- name: mypq                                              # Connection name
  ...
  ssl:
    certificate:                                          # The SSL connection certificate array.
      - "B64:MIIFQTCCAymgAwIBAgIUFMfsweA+VShaX3JHFF7xUQZajzIwDQYJKoZIhvcNAQELBQAwMDETMBEGA1UEAwwKcG9zdGdyZXNxbDEMMAoGA1UECgwDaWJtMQswCQYDVQQGEwJ1czAeFw0yMjA3MDUxMDEyMzZaFw0zMjA3MDIxMDEyMzZaMDAxEzARBgNVBAMMCnBvc3RncmVzcWwxDDAKBgNVBAoMA2libTELMAkGA1UEBhMCdXMwggIiMA0GCSqGSIb3DQEBAQUAA4ICDwAwggIKAoICAQCl1jX1Gf7v2EZ1cuCJaix0Y0FM82Wi5jApvCOyCYSxm7rB76rVtZ6hQMidCvMxxoUf4eWZx9FSCUC4HyfAuTT6kr/v/Y14PokxqQCXEPbA2c3qE3/aOjnozjMuV9tvBxSQw9rF15A/AF+AICz47gGiA0s02DiqW+TPW/fMbgUQNTgBPvl/xuBpCeaixUP/D+FjscWfgYXCt02h7WzholjHTJhGn3ax/Nmyvt3hHK3Q+F0fwcU2fkcMLBWQfC5h2lg2qHOd2IkSFHv0Nis7VEZMkB+vrhgLvoZDekdzz84xr3JltSByYt15tDEw346E93coJSk50ZQkG9oOfuD+XR4XmsUK2aylqc9poy7qK5yVgYNDuNaudFPOjQ7z4Zh+K3ONWbK2phdp23F5wXJkytib0uU/l0sipHQ4tOUMvK5Hi/ga8vyUMl8Jrdvqo/TVQP0UzJkie12WHv2Q/OLeEKcducUUDU5OEhKAUhZYP9UXessCr+qS8rmSbO0uMgR8MWefkabLWohDxxJxpKdWashLSt8nc9awO8o0pbdSmKbGn+jlxUmJflbWoNQp2X/hPQvIV9SlYK9QC34tk+fIA8EXyR20PBtMYz5x+QsaGps5V9VNerXhUimu2yy6X/7I344OdNtvYIeZU2fL+Ay9k6T1K0mkN0GdGfUuzzWafXbBHwIDAQABo1MwUTAdBgNVHQ4EFgQUnQckXogCljsKIv1ts5seidp2eaIwHwYDVR0jBBgwFoAUnQckXogCljsKIv1ts5seidp2eaIwDwYDVR0TAQH/BAUwAwEB/zANBgkqhkiG9w0BAQsFAAOCAgEATHqt1sehfpBDKmkccy87ALxjIjezFqhA3FfhiTJyN4LBmOwezQf0t0eOS7KeCeuR05qMRyTFC3aPka1hUvTug1WwRCrdXwOWe3ga6epm9gAEi9BTqkjG3eHRObmvA3cEzz/ug+OaI35l+vEVWfn4wBsZmXYH4LkYK21+E9Yr6D9TH3Ebkic+wn48YY8HGO5OzROq2NmW4xirmfR5bT/aabOxPIull/RDoSg05x280tfa6QpjpiizRZcokEYMJ+yDzllRG6aQY+6vNyailJcIYtr+LxgB13mRYnGT9MOYM9hUrc4PRnsKCKq7hwrvS5JFp607/O5ztn6EQGHHj5hfrzPxk0fifgO+gg4kjT1JpYstmiVq1DathoOh5kI4p0dKMKNJUgJruJZplI4CC+EhxxhCaJMnfTy4P6dPn0pirtQsIcmSu1Dm0UbqvsO2b/4tkwZ4f4Gza9jD6xfTmxO0hYJUixNgIe5vRrzqB6xQUa46zuETT7I3JVDih1h/ATYRKR85z0rLt1oocNR9csIwi6Ny9XiLhvLgrJNUFwbUw2sXL+oHLnE8HNvcJcmrZxA3t7DNXTjs88z6LUAzt3Py9jXxpX4voUBy4hHK1jUjflupL4OhldCe5U6NuoLmmZe3ucoTA8peHOll+PiE67oaEZb+PVOcDJrnbChOyJNaars="

Using PFX keystores

For better protection of the private keys, a p12/pfx format may be used instead of storing individual PEM files under the keystore directory. The p12 file is generally protected by a passphrase. This can be added to a file named the same as the p12 file but with the ".obf" extension. The passphrase can be obfuscated using the obf_key.

Useful commands

This section provides a set of useful openssl commands to generate certificates and keys.

Generate Private Key PEM

You can use openssl to generate private keys.

To generate RSA private key, you can use the following command:

[demouser@demovm ~]$ openssl genrsa -out rsa2048.pem 2048 # suitable for RS or PS signing algorithm

To generate EC private key, you can use the following command:

[demouser@demovm ~]$ openssl ecparam -genkey -name prime256v1 -noout -out ec256.pem # suitable for ES256 signing algorithm
[demouser@demovm ~]$ openssl ecparam -genkey -name secp384r1 -noout -out ec384.pem  # suitable for ES384 signing algorithm
[demouser@demovm ~]$ openssl ecparam -genkey -name secp521r1 -noout -out ec521.pem  # suitable for ES512 signing algorithm

These private keys may be used, for example, to sign provider-issued JSON Web Tokens, such as the ID token.

HTTPS Server Key and Certificate

For IBM Security Verify Access OIDC Provider container to start the server configuration needs to contain the key and the ceritificate files.

server:
  ssl:
    key: ks:https_keys/httpserverkey                       # Name of the keystore/key for the ISVAOP HTTPS server.
    certificate: ks:https_keys/httpservercert              # Name of the keystore/certificate for the ISVAOP HTTPS server.
    ca:
      - ks:https_keys/httpserverca                         # Name of the keystore/CA for the ISVAOP HTTPS server.

To generate RSA private key, you can use the following command:
```
[demouser@demovm ~]$ openssl genrsa -out httpserverkey.pem 2048 
```

To generate self-signed certificate, you can use the following command:

[demouser@demovm ~]$ openssl req -new -x509 -key httpserverkey.pem -out httpservercert.pem -days 360

Create the keystore directory :

[demouser@demovm ~]$ mkdir https_keys

[demouser@demovm ~]$ cd https_keys

[demouser@demovm ~]$ mkdir personal

[demouser@demovm ~]$ mkdir signer

Copy the files into the path:

[demouser@demovm ~]$ cp httpservercert.pem https_keys/signer/

[demouser@demovm ~]$ cp httpserverkey.pem https_keys/personal

📘
Note
You can also use path referencing and embedded base64-encoded PEM content in place of using a keystore.

Overview

Referencing keys and certificates

Referencing the source

Using PFX keystores

Useful commands

Generate Private Key PEM

HTTPS Server Key and Certificate

📘Note

📘
Note