IBM Verify Antenna configuration

Assume that the following folder structure is present in the configuration loading path.

|-- server
|   `-- pg_stg.yml
`-- storage.yml

In this example, server/pg_stg.yml is a simple configuration file with the following content.

name: pg_stg
type: postgresql
hosts:
  - hostname: pg_stg.ibm.com
    hostport: 6390
credential:
  username:
  password: "OBF:U2FsdGVkX18rz1DFhOzHmrG5GKCRQJsEMmTcN/5VxSA="

In the configuration file storage.yml, the contents of server/pg_stg.yml is included by specifying "@server/pg_stg.yml" as a value.

server_connections:
  - "@server/pg_stg.yml"

It is equivalent to embedding the full content of pg_stg.yml directly within storage.yml.

server_connections:
  - name: pg_stg
    type: postgresql
    hosts:
     - hostname: pg_stg.ibm.com
       hostport: 6390
    credential:
      username:
      password: "OBF:U2FsdGVkX18rz1DFhOzHmrG5GKCRQJsEMmTcN/5VxSA="

Generate the base64-encoded representation of the file. On UNIX-like systems, use the base64 command.

base64 -w 0 -i server_cert.pem

In the configuration, the output can be placed on a single line that is preceded by the B64: prefix.

keystores:
    name: rt_profile
    type: pem
    certificate:
      - label: trusted_cert01
        content:  "B64:LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUYvRENDQStTZ0F3SU..."

It is equivalent to embedding the full content within the configuration data.

keystores:
    name: rt_profile
    type: pem
    certificate:
      - label: trusted_cert01
        content: |
          -----BEGIN CERTIFICATE-----
          MIIF/DCCA+SgAwIBAgIBATANBgkqhkiG9w0BAQsFADBgMQswCQYDVQQGEwJTRzES
          MBAGA1UEBwwJU2luZ2Fwb3JlMREwDwYDVQQKDAhPdmVybG9yZDERMA8GA1UECwwI
          ...

The following example shows the data p@ssw0rd being encrypted with the secret abcdef:

echo -n "p@ssw0rd"| openssl enc -aes256 \ 
    -pbkdf2 -pass pass:"abcdef" -md sha512 \
    -base64

OpenSSL 1.1.1 or newer is required for the previous command.

This command produces a base64-encoded string. Due to salting, this command produces a different result each time it is run. The resulting obfuscated base64-encoded string can be used with the OBF: prefix:

server_connections:
  - name: pg_stg
    type: postgresql
    database_name: postgres
    hosts:
      - hostname: pg.example.com
        hostport: 5432
    credential:
      username: postgres
      password: "OBF:U2FsdGVkX1+0aFOU6f+0y7k6H6slVT0L7ztjRaHL7Sc="

To use RSA encryption, generate a private certificate.

openssl genrsa -out private.pem 2048

This private certificate is used to decrypt the entries and must be provided in the configuration. To create encrypted entries, generate a corresponding public key that is used for the encryption operations.

openssl rsa -pubout -in private.pem -out public.pem

The following example shows the data p@ssw0rd being encrypted with the public key public.pem and base64-encoded.

echo -n "p@ssw0rd"| openssl rsautl -encrypt -inkey public.pem -pubin | base64

This command produces a base64-encoded string. The encrypted base64-encoded string can be used with the ENC: prefix.

server_connections:
  - name: pg_stg
    type: postgresql
    database_name: postgres
    hosts:
      - hostname: pg.example.com
        hostport: 5432
    credential:
      username: postgres
      password: "ENC:L2qQGwwPFqLzUK3..."

Assuming e that the following folder structure is present in the configuration loading path.

|-- secrets
|   `-- database.yml
`-- storage.yml

In this example, secrets/database.yml is a simple YAML file with the content.

username: admin
password: postgres

In the configuration file storage.yml

• The username from secrets/database.yml is included by specifying yaml:secrets/database.yml:username.
• The password from secrets/database.yml is included by specifying yaml:secrets/database.yml:password

server_connections:
  - name: postgresql
    type: postgresql
    database_name: postgres
    hosts:
      - hostname: pg.example.com
        hostport: 5432
    credential:
      username: "yaml:secrets/pg.yml:username"
      password: "yaml:secrets/pg.yml:password"

It is equivalent to embedding the full content within the configuration data.

server_connections:
  - name: postgresql
    type: postgresql
    database_name: postgres
    hosts:
      - hostname: pg.example.com
        hostport: 5432
    credential:
      username: "admin"
      password: "postgres"

In a Kubernetes environment, the following special types are also supported.

Type	Syntax
Kubernetes ConfigMap	configmap:<configmap name>/<configmap field>
Kubernetes Secret	secret:<secret name>/<secret field>

The following ConfigMap named storage contains the fields pg.yml.

kind: ConfigMap
apiVersion: v1
metadata:
  name: storage
data:
  pg.yml: |
      name: pg_stg
      type: postgresql
      hosts:
        - hostname: pg_stg.ibm.com
          hostport: 6390
      credential:
        username:
        password: "OBF:U2FsdGVkX18rz1DFhOzHmrG5GKCRQJsEMmTcN/5VxSA="

To reference these values within the configuration, use the syntax for the Kubernetes ConfigMap type.

server_connections:
  - "configmap:storage/pg.yml"

During bootstrapping, IBM Verify Antenna retrieves the ConfigMap and substitutes it into the configuration.

server_connections:
  - name: pg_stg
    type: postgresql
    hosts:
      - hostname: pg_stg.ibm.com
        hostport: 6390
    credential:
      username:
      password: "OBF:U2FsdGVkX18rz1DFhOzHmrG5GKCRQJsEMmTcN/5VxSA="

The following secret that is named keystore contains the fields rt_profile_trusted_cert01 and rt_profile_key01.

kind: Secret
apiVersion: v1
metadata:
  name: keystore
data:
  rt_profile_trusted_cert01: >-
    LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUYvRENDQSt...
  rt_profile_key01: >-
    LS0tLS1CRUdJTiBQUklWQVRFIEtFWS0tLS0tCk1JSUpRUUlCQUR...
type: Opaque

To reference these values within the configuration, use the syntax for the Kubernetes Secret type.

keystores:
    name: rt_profile
    type: pem
    certificate:
      - label: trusted_cert01
        content: secret:keystore/rt_profile_trusted_cert01
    key:
      - label: key01
        content: secret:keystore/rt_profile_key01

During bootstrapping, IBM Verify Antenna retrieves the secret, base64-decodes the data, and substitutes it into the configuration.

keystores:
    name: rt_profile
    type: pem
    certificate:
      - label: trusted_cert01
        content: |
          -----BEGIN CERTIFICATE-----
          MIIF/DCCA+SgAwIBAgIBATANBgkqhkiG9w0BAQsFADBgMQswCQYDVQQGEwJTRzES
          MBAGA1UEBwwJU2luZ2Fwb3JlMREwDwYDVQQKDAhPdmVybG9yZDERMA8GA1UECwwI
          ...
    key:
      - label: key01
        content: |
          -----BEGIN PRIVATE KEY-----
          MIIJQQIBADANBgkqhkiG9w0BAQEFAASCCSswggknAgEAAoICAQC077CzbElrvwNg
          t4HTQwGbcjsMZgCSBWhM5K9qc3OfGBUhwm06eWLDk19PBN5asPPZw8MeeX1X8Lo0
          ...

To generate an obfuscated value, use the following command (it requires OpenSSL 1.1.1 or later).

echo -n "<value to obfuscate>" | openssl enc -aes256 \
    -pbkdf2 -pass pass:"<obfuscation key>" -md sha512 \
    -base64

Include the obfuscation key and the obfuscated value in the YAML configuration file. For example,

secrets:
  obf_key: "<obfuscation key>"

keystores:
  - name: ks1
    type: p12
    content: "B64:<encoded_p12>"
    password: "OBF:<obfuscated_p12_password>"

To generate the RSA private key

openssl genrsa -out private.pem 2048

To generate the corresponding public key

openssl rsa -pubout -in private.pem -out public.pem

An encrypted entry can be generated with the following command by using the public key.

echo -n "<configuration entry>" | openssl rsautl
    -encrypt -inkey public.pem -pubin | base64

Include the encryption key and the encrypted key value in the YAML configuration file. For example,

secrets:
  enc_key: "@private.pem"

keystores:
  - name: ks1
    type: p12
    content: "B64:<encoded_p12>"
    password: "ENC:<encrypted_p12_password>

IBM Verify Antenna supports the following types of key or certificate formats.

• pem
• p12

You can define these files by using the following methods.

• <inline PEM> embeds the file content directly in the configuration. For more information, see <inline PEM> in the following example.
• Base64-encoded file content embeds the Base64-encoded file content in the configuration. For more information, see B64: in the following example.
• File reference references the file directly. Place the files relative to the /configs directory and reference the relative path in the configuration. For more information, see @<file> in the following example.

keystore:
  - name: ks1
    type: p12
    content: "B64:<encoded_p12>"
    password: "OBF:<obfuscated_p12_password>"
  - name: ks2
    type: pem
    certificate:
      - label: cert01
        content: "B64:<encoded PEM>"
      - label: cert02
        content: "@<file>"
      - label: cert03
        content: |
          <inline PEM>
    key:
      - label: key01
        content: "B64:<encoded PEM>"
      - label: key02
        content: "@<file>"
      - label: key03
        content: |
          <inline PEM>
  - name: ks3
    type: path
    content: "relative/path/to/keystore4/contents"
  - name: postgres_keys
    type: zip
    content: "B64:<encoded zip>"
  - name: rt_profile_keys
    type: pem
    certificate:
      - label: postgres
        content: "B64:<encoded PEM>"
      - label: ca
        content: "@<file>"
    key:
      - label: postgres
        content: "B64:<encoded PEM>"

You can reference a predefined keystore in configurations that require a key or certificate. Use one of the following methods.

ks method

ks: Represents a keystore that is already defined in the keystores property.

database:
  name: mypq
    ...
    ssl:
    certificate:
        - ks:postgres_keys
    mutual_auth:
        key: ks:rt_profile_keys/postgres
        certificate: ks:rt_profile_keys/postgres
        ca:
          - ks:rt_profile_keys/ca
    disable_hostname_verification: false

The trusted certificates are read from the keystore named postgres_keys.

For mutual SSL connections,

• The key is read from keystore rt_profile_keys key label postgres.
• The leaf certificate is read from keystore rt_profile_keys certificate label postgres.
• The CA certificate is read from keystore rt_profile_keys certificate label ca.

@ method

@ Represents a file. Use the @ prefix to reference a PEM-encoded file. The path is relative to the /configs directory.

database:
  name: mypq
  ...yaml
  ssl:
    certificate:
      - "@postgres_keys/postgres.crt"                     
    mutual_auth:
      key: "@rt_profile_keys/postgres_key.pem"
      certificate: "@rt_profile_keys/postgres.pem"
      ca:                                                 
        - "@rt_profile_keys/postgres-intermediate.pem"    
    disable_hostname_verification: false

The certificate postgres.crt is read from /configs/postgres_keys/postgres.crt and for mutual SSL connections, the key postgres.pem is read from /configs/postgres_keys/postgres_key.pem. Similarly, the other properties are self-explanatory.

B64 method

B64: Represents a base64-encoded certificate or key.

database: 
  name: mypq
  ...
  ssl:
    certificate:
      - "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="                                 
    ...

Generate private key PEM

To generate an RSA private key, use the following openssl command.

openssl genrsa -out rsa2048.pem 2048 # suitable for RS or PS signing algorithm

To generate an EC private key, use the following openssl commands.

openssl ecparam -genkey -name prime256v1 -noout -out ec256.pem # suitable for ES256 signing algorithm
openssl ecparam -genkey -name secp384r1 -noout -out ec384.pem  # suitable for ES384 signing algorithm
openssl ecparam -genkey -name secp521r1 -noout -out ec521.pem  # suitable for ES512 signing algorithm

HTTPS server certificate

For application HTTPS servers, the server configuration must contain the key and the certificate files.

To generate an RSA private key, use the following command.

openssl genrsa -out httpserverkey.pem 2048

To generate a self-signed certificate, use the following command.

openssl req -new -x509 -key httpserverkey.pem -out httpservercert.pem -days 360

To create the keystore directory:

mkdir https_keys
cd https_keys
mkdir personal
mkdir signer

To copy the files into the path:

cp httpservercert.pem https_keys/signer/
cp httpserverkey.pem https_keys/personal/

To configure the keystores:

keystores:
  - name: https_keys
    type: pem
    certificate:
      - label: httpservercert
        content: "@https_keys/signer/httpservercert.pem"
    key:
      - label: httpserverkey
        content: "@https_keys/personal/httpserverkey.pem"

To configure the server to reference the keystore:

server:
  ssl:
    key: ks:https_keys/httpserverkey
    certificate: ks:https_keys/httpservercert

When in transmitter mode, the following databases are required.

config

Stores configuration data, including the Streams.

raw_2_ssf

Stores ingested data before it is converted to events.

ssf_2_set

Stores events before they are converted to SETs.

poll_stage

Stores SETs that will be returned during the next poll.