Aeron Transport Security (ATS)

Overview

Aeron Transport Security (ATS) is a premium feature of the Aeron transport protocol, designed to secure Aeron frames on the network using industry-proven technologies. ATS ensures that data packets traversing various systems are protected from unintended parties, providing the highest level of security with minimal latency.

Key Features

  • Lightning Fast Cryptography: ATS leverages OpenSSL cryptography, a standard across countless industries, to deliver superior performance by utilizing the power of modern hardware.

  • Secure by Default: Aeron publications and subscriptions are secured by default, ensuring that all communications are protected unless explicitly opted out.

  • Versatile Stream Support: ATS supports unicast, multicast, and multi-destination-cast, making it adaptable to various network configurations.

  • Public Key Authentication: Each ATS-enabled driver has a public/private key pair and can be configured with other public keys for secure communication. Only drivers aware of each other’s keys and passing signature validation can communicate.

ATS is supported in the Aeron C driver only, and requires OpenSSL 3.0.0.

How to get ATS

ATS is a Premium Aeron component. You can find pre-compiled bundles of the C Media Driver that include ATS for popular Linux distributions under aeron-transport-security in the Adaptive Artifactory.

How to enable ATS

To integrate the ATS bindings into an Aeron C media driver, it is necessary to set the AERON_UDP_CHANNEL_OUTGOING_INTERCEPTORS and AERON_UDP_CHANNEL_INCOMING_INTERCEPTORS environment variables to contain the name of the bindings, aeron_transport_security_channel_interceptor_load upon driver initialization. e.g.

$ export AERON_UDP_CHANNEL_OUTGOING_INTERCEPTORS="aeron_transport_security_channel_interceptor_load"
$ export AERON_UDP_CHANNEL_INCOMING_INTERCEPTORS="aeron_transport_security_channel_interceptor_load"

For this to work the libaeron_transport_security.so must be loaded via LD_PRELOAD, or via the driver by setting AERON_DRIVER_DYNAMIC_LIBRARIES.

The script in aeron-transport-security/scripts/aeronmd-aeron-transport-security will start up a media driver and load the bindings appropriately.

When loading, the bindings will attempt to find a configuration file containing, at a minimum, an RSA private key. If the default configuration file, ats.conf, is not found, the user running aeronmd must specify the configuration file name and optionally, the configuration directory. See section below.

When enabled for a media driver, ATS is secure-by-default in that it is automatically enabled for all publications and subscriptions unless explicitly disabled via ats=false in the URI for the channel.

URIs for subscription and publication channels MAY contain the ats param. Subscriptions can include ats=false to indicate it must not be in use, but that any supported driver configuration can be used. Usage of the ats param will generate an error if the driver is not configured for ATS usage, i.e. no configured interceptors for security. The Java driver will always error on ats usage.

General Operation

  • ATS is configurable per transport/channel.

  • Publications and Subscriptions can specify an ats param in their URIs. Mainly to turn ATS off for a transport/channel. An ATS enabled transport/channel is in conflict with one that does not have it enabled. Thus, if a publication or subscription disables ATS and attempts to use an existing channel/transport that has it enabled, then an error will be generated to the client and the connection disallowed. Same with the reverse - existing ATS disabled channel/transport with a new ATS enabled channel/transport URI.

  • RSA keys are mandatory for subscriptions and publications. For an ATS enabled driver, an RSA private key must be configured for the driver. The RSA private key is driver-wide.

  • While configuration-wise, usage of ATS is transport/channel scoped. The actual keys, algorithms, parameters, etc. are specific to each session and stream.

  • Publication operation

    • ATS_SETUP holds ATS headers after main SETUP header

      • ATS Headers include (unicast):

        • ATS Cipher Suite

        • RSA Public Key in DER Format

        • RSA Public Key Fingerprint ID

        • EC Public Key in DER Format

        • Signature of EC Public Key in DER Format signed with RSA Private Key

      • ATS Headers include (multicast or MDC):

        • ATS Cipher Suite

        • RSA Public Key in DER Format

        • RSA Public Key Fingerprint ID

        • EC Public Key in DER Format

        • Signature of EC Public Key in DER Format signed with RSA Private Key

        • Encrypted Secret Key for a receiver

    • Receiving a SETUP-eliciting ATS_SM, the ATS headers in the ATS_SM hold subscriptions RSA Public Key (or fingerprint) and EC Public Key. The publication then sends an ATS_SETUP with its RSA Public Key (or fingerprint) and EC Public Key and, in the case of multicast or MDC, the stream shared key encrypted from a key derived via the EC keys of the publication and ATS_SM EC public key.

    • Receiving a SETUP-eliciting SM (not an ATS_SM) must be dropped.

    • For the unicast case, the EC public key from both sender and receiver allows Elliptic Curve Diffie-Hellman to be used for key derivation.

  • Subscription operation

    • ATS_SM holds ATS headers after main SM header

      • ATS Headers include (unicast and multicast and MDC):

        • ATS Cipher Suite

        • RSA Public Key in DER Format

        • RSA Public Key Fingerprint ID

        • EC Public Key in DER Format

        • Signature of EC Public Key in DER Format signed with RSA Private Key

    • Upon ATS_DATA or ATS_SETUP reception, the subscription must send an SETUP-eliciting ATS_SM containing the subscriptions RSA Public Key (or fingerprint) and EC Public Key. The subscription must then wait for an ATS_SETUP that contains the publications RSA Public Key (or fingerprint) and EC Public key and, in the case of multicast or MDC, the stream shared key encrypted.

    • Filter and drop SETUPs and DATA that do not contain sufficient ATS headers (i.e. continue to elicit SETUPs via SMs if necessary).

    • Non-SETUP-eliciting `ATS_SM`s, contain subscriptions RSA Public Key (and fingerprint) and EC Public Key.

  • Key Derivation

    • Key Derivation from any source uses HKDF RFC 5869. The salt and label values must be provided.

    • Shared secret key for multicast and MDC are sent in the ATS_SETUP. This key is encrypted by the cipher suite in use (AES 256 GCM) via a key derived from the EC public keys of the publication and subscription and passed through the HKDF before use.

  • Data Header and Data Framing

    • ATS_DATA header starts frame. This frame is a normal DATA frame in the clear with term offset set to 0 and term id set to initial term id. The frame length is the entire frame length. This header is used as an AAD for GCM.

    • Initialization Vector (IV) and HMAC tag follow the AAD ATS_DATA Frame header depending on ATS Cipher Suite in use.

    • Rest of the datagram is encrypted and contains the actual Aeron Data Frames.

RSA Public Key Management

  • Each ATS capable driver must have an RSA Private Key unique to it.

  • Each ATS capable driver can be configured with the RSA Public Keys of other drivers.

Generating RSA Private and Public Keys

OpenSSL is used for key operations.

To generate a private RSA key of 4096-bits in length and output in PEM format:

    $ openssl genrsa 4096 > key1.pem

To take this key and output just the public key in PEM format:

    $ openssl pkey -in key1.pem -pubout > public-key1.pem

ATS can handle multiple public keys in a file concatenated together.

ATS Configuration File

ATS requires a configuration file to operate. The AERON_TRANSPORT_SECURITY_CONF_FILE environment variable holds the configuration file.If the environment variable AERON_TRANSPORT_SECURITY_CONF_DIR is set then all filenames in the configuration file and the configuration file are relative to it.

ATS Configuration File Parameters

  • private.key.file (REQUIRED): File that contains the ATS-capable media drivers RSA private key in PEM format.

  • public.key.file (OPTIONAL): File that contains one or more RSA public keys in PEM format.

ATS Configuration File Example

private.key.file=private-key.pem
public.key.file=public-keys.pem

Protocol Operation

SETUP-ATS = SETUP with ATS header containing publication public key and signatures
SETUP-ATS-KEY = SETUP with ATS header(s) containing publication public key and signatures and shared key ecnrypted with subscription public key
STATUS-SETUP-ATS = SM with S flag set and ATS header(s) containing subscription key and signatures
STATUS-ATS = SM with blank ATS header (indicates subscription is now secure)

Sender: +[SETUP-ATS | DATA]     +SETUP-ATS-KEY
                    \           /           \
Receiver:        +STATUS-SETUP-ATS         +STATUS-ATS

Working with previous Aeron versions

  • Publication with ATS and old Subscription (also non-ATS drivers)

    • Publication SETUP and DATA frames use ATS_SETUP and ATS_DATA. Old versions do not understand this and thus do not create an image and do not insert frames. In other words, the subscription will not see the session.

    • This is the same for non-ATS drivers, such as the Java driver and C driver without ATS.

  • Subscription with ATS and old Publication (also non-ATS drivers and ats=false Publications)

    • ATS_SETUP and ATS_DATA not sent. These will be filtered by ATS when the transport is ATS enabled. Thus, the session will not be seen.

    • This is the same for non-ATS drivers, such as the Java driver and C driver without ATS.

    • This is the same for ats=false transport/channel in use by Publications with ATS capable drivers.

ATS Aeron Headers

  • ATS_DATA (HDR_TYPE_ATS_DATA)

    • Formatted as a normal DATA/PAD header but with term offset of 0 and term id of initial term id. After this header, the cipher suite indicates the format.

  • ATS_SETUP (HDR_TYPE_ATS_SETUP)

    • Formatted as SETUP with 1 (or more) option header after main SETUP header

  • ATS_SM (HDR_TYPE_ATS_SM)

    • Formatted as SM with 1 (or more) option header after main SM header

Option header

An option header is used for adding options to other frames. More than one option can be chained after a normal Aeron frame up to the frame length. A header always starts on a 4 byte boundary.

The general format of the header is as follows. The option header is not specific to ATS.

     0                   1                   2                   3
     0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    |         Header Length         |I|           Type              |
    +-------------------------------+-+-----------------------------+
    |                       Depends on Type                        ...

  • Header Length: (15 = max 65546 bytes) Length of Header. Including header.

  • (I)gnore: (1) Header can be ignored if type unknown. If NOT set, then entire frame should be dropped if not understood.

  • Type: (15) Indicates the type of header and any format after header.

Option Header Types

Type Value(s) Description

OPT_HDR_TYPE_RES

0x0000

RESERVED: Reserved.

OPT_HDR_TYPE_ATS

0x0001 - 0x02FF

Aeron Transport Security (ATS): Range used for ATS.

OPT_HDR_TYPE_ATS_SUITE

0x0001

ATS Cipher Suite: Cipher Suite information

OPT_HDR_TYPE_ATS_RSA_KEY

0x0002

RSA Public Key: encoded in DER

OPT_HDR_TYPE_ATS_RSA_KEY_ID

0x0003

RSA Public Key Fingerprint ID: SHA256 fingerprint of RSA public key

OPT_HDR_TYPE_ATS_EC_KEY

0x0004

Elliptic Curve (EC) Public Key: encoded in DER

OPT_HDR_TYPE_ATS_EC_SIG

0x0005

Signature of EC Public Key:

OPT_HDR_TYPE_ATS_SECRET

0x0006

Encrypted Secret Key: Public key encrypted with receivers RSA key

OPT_HDR_TYPE_COMP

0x0300 - 0x03FF

Aeron Compression: Range reserved for Compression.

OPT_HDR_TYPE_EXT

0x7FFF

Extension Header: Used to extend more options as well as extensions (TBD).

ATS Option Headers

Cipher Suite (OPT_HDR_TYPE_ATS_SUITE)

     0                   1                   2                   3
     0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    |         Header Length         |I|           Type              |
    +-------------------------------+-+-----------------------------+
    |          Cipher Suite         |        Key Agreement          |
    +---------------------------------------------------------------+

  • Header Length: always 8.

  • (I)gnore: always 0.

  • Type: always OPT_HDR_TYPE_ATS_SUITE.

  • Cipher Suite: (16) TLS Cipher Suite value. AES_256_GCM_SHA384 is \{ 0x13, 0x02}. See IANA and RFC 8446.

  • Key Agreement: (16) Type of Key Agreement.

Key Agreement Value(s) Description

KEY_AGREEMENT_TYPE_RES

0x0000

RESERVED: Reserved.

KEY_AGREEMENT_TYPE_ECDHE

0x0001

Ephemeral Elliptic Curve Diffie Hellman

KEY_AGREEMENT_TYPE_SHARED

0x0100

Shared: Key is determined by sender and encrypted with receivers EC public key.

KEY_AGREEMENT_TYPE_EXT

0xFFFF

Extension Type: Used to extend more options as well as extensions (TBD).

RSA Public Key (OPT_HDR_TYPE_ATS_RSA_KEY)

     0                   1                   2                   3
     0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    |         Header Length         |I|           Type              |
    +-------------------------------+-+-----------------------------+
    |                    RSA Public Key in DER format              ...
   ...                                                              |
    +---------------------------------------------------------------+

  • Header Length: Varies based on key length.

  • (I)gnore: always 0.

  • Type: always OPT_HDR_TYPE_ATS_RSA_KEY.

  • RSA Public Key: (Varies) RSA Public Key in DER format.

RSA Public Key Fingerprint ID (OPT_HDR_TYPE_ATS_RSA_KEY_ID)
     0                   1                   2                   3
     0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    |         Header Length         |I|           Type              |
    +-------------------------------+-+-----------------------------+
    |                    RSA Pubic Key Fingerprint ID              ...
   ...                                                              |
    +---------------------------------------------------------------+

  • Header Length: always 36.

  • (I)gnore: always 0.

  • Type: always OPT_HDR_TYPE_ATS_RSA_KEY_ID.

  • RSA Public Key Fingerprint ID: (256) SHA256 value of RSA Public Key in DER format.

Elliptic Curve Public Key (OPT_HDR_TYPE_ATS_EC_KEY)

     0                   1                   2                   3
     0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    |         Header Length         |I|           Type              |
    +-------------------------------+-+-----------------------------+
    |            Elliptic Curve Public Key in DER format           ...
   ...                                                              |
    +-------------------------------+-------------------------------+

  • Header Length: Varies based on key length.

  • (I)gnore: always 0.

  • Type: always OPT_HDR_TYPE_ATS_EC_KEY.

  • Elliptic Curve (EC) Public Key: (Varies) EC Public Key in DER format.

Elliptic Curve Public Key Signature (OPT_HDR_TYPE_ATS_EC_SIG)

     0                   1                   2                   3
     0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    |         Header Length         |I|           Type              |
    +-------------------------------+-+-----------------------------+
    |            Elliptic Curve Public Key Signature               ...
   ...                                                              |
    +-------------------------------+-------------------------------+

  • Header Length: Varies based on RSA public key length.

  • (I)gnore: always 0.

  • Type: always OPT_HDR_TYPE_ATS_EC_SIG.

  • Elliptic Curve (EC) Public Key Signature: (Varies) Signature of EC Public Key.

Encrypted Secret Key Secret (OPT_HDR_TYPE_ATS_SECRET)

     0                   1                   2                   3
     0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    |         Header Length         |I|           Type              |
    +-------------------------------+-+-----------------------------+
    |                Receiver EC Pubic Key Fingerprint ID         ...
   ...                                                              |
    +---------------------------------------------------------------+
    |                       Encrypted Secret Key                   ...
   ...                                                              |
    +---------------------------------------------------------------+

  • Header Length: Varies based on key length.

  • (I)gnore: always 0.

  • Type: always OPT_HDR_TYPE_ATS_SECRET.

  • Receiver EC Public Key Fingerprint ID: (256) SHA256 ID of the EC Public Key that encrypted the key.

  • Encrypted Secret Key: (Varies) Secret Key encrypted via key derived by parties EC keys. Receiver is indicated in the fingerprint ID field.

API Support

  • ats URI param