SSL Auth

This document describes how to set up mutual SSL authentication between Airkit (the client) and an external server.

Overview

Secure SSL authentication requires a successful SSL handshake, during which both client and server establish the secret keys that they will use to communicate. Airkit handles most of the client-side process under the hood and only requires three additional values in order to establish a secure connection with an appropriately configured client:

• Certification Authority - certificate chains in PEM format. One certificate chain is expected per Client-Side Private Key. Each certificate chain must consist of the PEM-formatted certificate for a provided Private Key, followed by the PEM formatted intermediate certificates (if any), in order, and not including the root Certification Authority, which must be pre-known to the peer. If the intermediate certificates are not provided, the peer will not be able to validate the certificate, and the handshake will fail.

• Client-Side Private Key - designates an OpenSSL engine to get private key from.

• Client-Side Certificate - list of supported signature algorithms. This list can contain digest algorithms (SHA256, MD5 etc.), public key algorithms (RSA-PSS, ECDSA etc.), combination of both (e.g 'RSA+SHA384') or TLS v1.3 scheme names (e.g. rsa_pss_pss_sha512).

The Certification Authority, client-side private key, and client-side certificate can be configured in the Airkit platform in two ways. If required in only one-off HTTP request, they can be configured directly in the Studio, in the HTTP Request Data Operation. Best practice, however, is to configure them as part of a Console-level Integration, which this encrypts the value of the keys and certificates.

Configuring within a Data Operation

To configure a Certification Authority, client-side private key, and client-side certificate within an individual HTTP Request, do so in the Studio > Connections Builder > Data Flows > HTTP Request Data Operation.

🚧 When the Certification Authority, client-side private key, and client-side certificate are configured as part of an HTTP Request Data Operation, they are necessarily stored as plaintext. To store their values in an encrypted database, as is commonly best practice for security purposes, you will need to configure them as a Console-level integration. The Certification Authority, client-side private key, and client-side certificate must be entered in their corresponding fields within the Data Operation:

Configuring as a Console-Level Integration

To configure a Certification Authority, client-side private key, and client-side certificate as a Console-level integration, do so in the **Console > Integrations > Connected Accounts**. This stores the Certification Authority, client-side private key, and client-side certificate in an encrypted database.

When creating a new integration or editing an established one, the Certification Authority, client-side private key, and client-side certificate must be entered in their corresponding fields within the Inspector. The following example shows what it looks like to edit the Private Key of an existing integration. For security purposes, the Certificate Authority and Private Key have been censored:

Once the Certification Authority, client-side private key, and client-side certificate have been configured as a Console-level integration, they can be referenced as part of the integration in multiple applications.

🚧 If a Console-level integration with relevant SSL Authentication information is used to make an HTTP Request via a Data Operation, the Certification Authority, Client-Side Private Key, and Client-Side Certificate fields should be left blank within the Data Operation. Any values provided in fields within the Data Operation will take precedence over the corresponding information saved at in the Console-level integration.