SSL

Configuring SSL is a complex task, but many options have been provided to make it accessible and flexible.

Library selection

ProSA through traits:

• SslStore to handle specific library certificate Store.
• SslConfigContext to handle specific client/server SSL context for TLS negociation.

allows the use of OpenSSL and later more SSL libraries.

By default, ProSA will use OpenSSL, but if you want, you can use the following features to change it:

• openssl: Use OpenSSL by default
• openssl-vendored: Vendored OpenSSL that compiles and statically links to the OpenSSL library

Store

You have two options to configure an SSL store:

• Specify a store path that will include all certificates found within the folder and its subfolders
• Specify individual certificates directly in PEM format

Store path

When you declare a store path, the system scans the folder and subfolders to load all .pem and .der certificates it finds.

To configure it, just specify the path:

store:
  path: "/etc/ssl/certs/"

Store certificates

If you prefer to include your certificates directly in the configuration (in PEM format), you can do so as follows:

store:
  certs:
    - |
        -----BEGIN CERTIFICATE-----
        MIICGzCCAaGgAwIBAgIQQdKd0XLq7qeAwSxs6S+HUjAKBggqhkjOPQQDAzBPMQsw
        CQYDVQQGEwJVUzEpMCcGA1UEChMgSW50ZXJuZXQgU2VjdXJpdHkgUmVzZWFyY2gg
        R3JvdXAxFTATBgNVBAMTDElTUkcgUm9vdCBYMjAeFw0yMDA5MDQwMDAwMDBaFw00
        MDA5MTcxNjAwMDBaME8xCzAJBgNVBAYTAlVTMSkwJwYDVQQKEyBJbnRlcm5ldCBT
        ZWN1cml0eSBSZXNlYXJjaCBHcm91cDEVMBMGA1UEAxMMSVNSRyBSb290IFgyMHYw
        EAYHKoZIzj0CAQYFK4EEACIDYgAEzZvVn4CDCuwJSvMWSj5cz3es3mcFDR0HttwW
        +1qLFNvicWDEukWVEYmO6gbf9yoWHKS5xcUy4APgHoIYOIvXRdgKam7mAHf7AlF9
        ItgKbppbd9/w+kHsOdx1ymgHDB/qo0IwQDAOBgNVHQ8BAf8EBAMCAQYwDwYDVR0T
        AQH/BAUwAwEB/zAdBgNVHQ4EFgQUfEKWrt5LSDv6kviejM9ti6lyN5UwCgYIKoZI
        zj0EAwMDaAAwZQIwe3lORlCEwkSHRhtFcP9Ymd70/aTSVaYgLXTWNLxBo1BfASdW
        tL4ndQavEi51mI38AjEAi/V3bNTIZargCyzuFJ0nN6T5U6VR5CmD1/iQMVtCnwr1
        /q4AaOeMSQ+2b1tbFfLn
        -----END CERTIFICATE-----

This method is primarily used for inline certificates embedded in the code.

SslConfig

SslConfig is the main configuration object for SSL.

It allows configuring:

• Store
• Certificate, key, or PKCS#12 bundle
• ALPN (Application-Layer Protocol Negotiation)
• Modern security flag as per Mozilla guidelines
• SSL timeout for negociations

PKCS#12

To configure SSL with a PKCS#12 bundle:

ssl_config:
  store:
    path: "/etc/ssl/certs/"
  pkcs12: "/opt/cert.p12"
  passphrase: "p12_passphrase"

PEM/DER certificates

For traditional PEM certificates:

ssl_config:
  store:
    path: "/etc/ssl/certs/"
  cert: "/opt/cert.pem"
  key: "/opt/cert.key"
  passphrase: "key_passphrase"
  alpn:
    - "h2"
    - "http/1.1"
  modern_security: true
  ssl_timeout: 3000

If you specify a certificate with a .der extention, it will be read as DER-encoded.

Self signed certificate

If your server connection is SSL (with the ssl:// or the +ssl:// suffixed protocol) and you don't specify a certificate and its private key, it'll generate a self-signed certificate.

If you want to retrieve the generated certificate because you need to trust it from a remote, you can specify a certificate path where the certificate will be written:

ssl_config:
  cert: "/opt/self_signed_cert.pem"

Usage

The SslConfig applies both to server and client configurations.

If you specify a store, it'll be used:

• On the client-side, to validate server certificates
• On the server-side, to validate client certificates

Similarly, if you own a certificate (with a private key), it can be used as either a client or server certificate.