TKM

The Trusted Key Manager (TKM) is a minimal Trusted Computing Base which implements security-critical functions of the IKEv2 protocol. It is implemented using the Ada programming language. The TKM works in conjunction with the strongSwan IKEv2 daemon charon-tkm to provide key management services for IPsec.

IPsec can be used to protect data flows between hosts or security gateways. ^[1]

The underlying concept of IKE disaggregation and the design of TKM and all related components is presented in detail in the project report, see documentation.

To support automatic setup and rekeying of IPsec connections the xfrm-proxy component is used. It forwards XFRM Acquire and Expire events from the Linux kernel to the IKE daemon. The following diagram illustrates the main components of the system and how they communicate:

The trusted key manager uses the tkm-rpc library to communicate with the augmented strongSwan charon daemon (charon-tkm) in the untrusted part. The tkm-rpc library is also written in Ada.

For x509 certificate processing, the x509/Ada library is used and for communication with the Linux kernel’s XFRM subsystem the XFRM/Ada library is employed.

Diffie-Hellman key agreement and RSA signature generation and validation are implemented using the big number arithmetic provided by the GMPAda binding.

TKM is considered a prototype implementation and a technology demonstrator of the IKE disaggregation concept. We do not consider it to be fit for production use in its current form.

Features

The following features are implemented by TKM:

PKCS#1 (RSA) key and X.509 certificate processing
Public key authentication using RSA-PKCS1-SHA1
Certificate trustchain validation using RSA-PKCS1-SHA256
Diffie-Hellman key exchange using groups DH-MODP-3072 and DH-MODP-4096
IKE and ESP key derivation using HMAC-SHA512
IKE en-/decryption using AES-CBC-256 and HMAC-SHA512

The following table lists the supported transforms with their IANA identifiers:

Table 1. Supported IKEv2 transforms
ID	Transform Type
12	Encryption algorithm
7	Pseudo-random Function
14	Integrity Algorithm
15	Diffie-Hellman Group
16	Diffie-Hellman Group
1	Authentication method

A complete list of all IKEv2 IANA identifiers can be found here: https://www.iana.org/assignments/ikev2-parameters/.

Documentation

To give a brief overview of the project, its abstract is reproduced here:

The IPsec protocol relies on the correct operation of the IKE key exchange to meet its security goals. The implementation of the IKE protocol is a non-trivial task and results in a large and complex code base. This makes it hard to gain a high degree of confidence in the correct operation of the code.

We propose a component-based approach by disaggregating the IKE key management system into trusted and untrusted components to attain a higher level of security. By formulating desired security properties and identifying the critical components of the IKE protocol, a concept to split the key management system into an untrusted and trusted part is presented. The security-critical part represents a trusted computing base (TCB) and is termed Trusted Key Manager (TKM). Care was taken to only extract the functionality that is absolutely necessary to ensure the desired security properties. Thus, the presented interface between the untrusted IKE processing component and TKM allows for a small and robust implementation of the TCB. The splitting of the protocol guarantees that even if the untrusted side is completely subverted by an attacker, the trusted components uphold the proposed security goals.

The viability of the design has been validated through a prototypical implementation of the presented system. The untrusted parts of the IKE daemon have been implemented by extending the existing strongSwan IKE implementation. The trusted components have been implemented from scratch using the Ada programming language, which is well suited for the development of robust software. The new Design-by-Contract feature of Ada 2012 has been used for the implementation of state machines, to augment the confidence of operation according to the specification.

The full report about IKEv2 Separation can be found here: https://www.codelabs.ch/tkm/ike-separation.pdf.

Information about the strongSwan project can be found on the project’s website: https://www.strongswan.org.

Unfortunately the Linux kernel’s XFRM subsystem is not well documented. A brief overview is given on the following website: https://www.linuxfoundation.org/collaborate/workgroups/networking/ipsec-overview.

Download

The TKM sources are available through its git repository:

$ git clone https://git.codelabs.ch/git/tkm.git

A browsable version of the repository is also available here: https://git.codelabs.ch/?p=tkm.git

Installation

This section describes the steps needed to build, install and use the Trusted Key Manager in conjunction with strongSwan to provide IKEv2 key management services on a Linux host.

Requirements

To compile the TKM components on your system, you need to have the following software installed:

Git version control tool: https://git-scm.com/
GNAT compiler: https://www.gnu.org/software/gnat/gnat.html
gprbuild (part of AdaCore’s GNAT GPL Edition): https://libre.adacore.com/tools/
Anet (Version 0.2.2 or above): https://www.codelabs.ch/anet/
Alog (Version 0.4 or above): https://www.codelabs.ch/alog/
GMPAda (Ada GMP binding): http://nicolas.boulenguez.free.fr/
XML/Ada (Version 4.1 or above): https://libre.adacore.com/tools/xmlada/

If you want to run the unit tests before installation of a TKM component (which is recommended) you furthermore need to have the following installed:

Ahven (Test-Framework): https://ahven.stronglytyped.org/

Preparatory steps

It is expected that the GNAT project files of the installed Ada libraries are accessible on the system by exporting the ADA_PROJECT_PATH environment variable. If you have installed the libraries under $HOME/libraries/ the following command will allow their use:

$ export ADA_PROJECT_PATH=$HOME/libraries/lib/gnat

If you expect to compile Ada code more frequently you can append the previous line to your $HOME/.profile file so it is set automatically.

XFRM/Ada library

The first step is to compile and install the needed libraries. Compile and install XFRM/Ada:

$ git clone https://git.codelabs.ch/git/xfrm-ada.git
$ cd xfrm-ada
$ make install

X509/Ada library

Compile and install X509/Ada:

$ git clone https://git.codelabs.ch/git/x509-ada.git
$ cd x509-ada
$ make tests
$ make install

TKM-RPC library

After these dependencies have been met, the TKM-RPC library is next:

$ git clone https://git.codelabs.ch/git/tkm-rpc.git
$ cd tkm-rpc
$ make tests
$ make install

libsparkcrypto

To encrypt IKE packets, the libsparkcrypto library is required:

$ git clone https://git.codelabs.ch/spark-crypto.git
$ cd spark-crypto
$ make NO_SPARK=1 NO_TESTS=1 NO_APIDOC=1
$ make NO_SPARK=1 NO_TESTS=1 NO_APIDOC=1 DESTDIR=$HOME/libraries/lib/gnat install

strongSwan

Next up is the charon-tkm daemon, which is part of the strongSwan project:

$ git clone git://git.strongswan.org/strongswan.git
$ cd strongswan

After that the daemon can be compiled and installed. A different installation location than the default /usr/local/ can be specified using the --prefix option:

$ ./autogen.sh
$ ./configure [--prefix=/path/to/install] \
    --disable-defaults      \
    --enable-ikev2          \
    --enable-kernel-netlink \
    --enable-pem            \
    --enable-pkcs1          \
    --enable-random         \
    --enable-sha1           \
    --enable-socket-default \
    --enable-swanctl        \
    --enable-tkm            \
    --enable-x509
$ make install

For additional build instructions for strongSwan, the reader is directed to the project’s documentation. ^[2]

strongSwan requires specific kernel modules to be enabled ^[3]

TKM

Once the IKEv2 daemon is ready the TKM component can be compiled:

$ git clone https://git.codelabs.ch/git/tkm.git
$ cd tkm
$ make tests
$ make install

xfrm-proxy

For XFRM Acquire and Expire processing, the xfrm-proxy component must be compiled and installed:

$ git clone https://git.codelabs.ch/git/xfrm-proxy.git
$ cd xfrm-proxy
$ make install

Certificates

X509 certificates are needed for mutual authentication. The strongSwan PKI tool can be used to setup a simple CA with user certificates ^[4]. The generated CA certificate must be placed in strongSwan’s certificate directory, which is /usr/local/etc/swanctl/x509ca/ by default. Likewise the user certificate containing the public key of the local identity used for authentication, must be copied to /usr/local/etc/swanctl/x509/.

Configuration

Now a suitable configuration must be generated using the tkm_cfgtool. The tool takes an XML file as input and creates an IKE and a TKM configuration file:

$ tkm_cfgtool -c config.xml -i swanctl.conf -t tkm.conf -s /path/to/schema

The XML config file format is quite simple and an example configuration file is available in the TKM source code, see data/refconfig.xml.

The swanctl.conf file must be copied to strongSwan’s configuration directory. By default this is located at /usr/local/etc/swanctl.

$ cp swanctl.conf /usr/local/etc/swanctl

Putting it all together

Now that everything is in place the TKM can be started:

$ sudo tkm_keymanager -c tkm.conf -k privKey.der -r ca.der:1

The TKM binary tkm_keymanager opens a Netlink socket to the XFRM subsystem of the Linux kernel to install XFRM policies and XFRM state (IPsec keys etc), which requires root permissions.

The private key and CA certificate in ASN.1/DER format should have already been generated. TKM uses the given private key to assert the local identity to the peer(s) and the CA certificate to verify the trust chain of peer certificates.

Once the Trusted Key Manager has been started successfully the IKE daemon can be started:

$ sudo /usr/local/libexec/ipsec/charon-tkm

The connections and certificates are loaded via swanctl:

$ sudo swanctl --load-all

This command could also be configured as start script in strongswan.conf.

The syslog log file can be checked to verify that the IKE daemon is up and running. Additionally all configured connections are shown when displaying IKE’s status information:

$ sudo swanctl --list-conns

For automated setup and rekeying of connections the xfrm-proxy must be started. Since it opens a Netlink socket to the kernel’s XFRM subsystem it must run as root:

$ sudo xfrm_proxy

If all components have been started successfully, an IPsec connection should be setup automatically when trying to ping the peer. To inquire information about active connections of the IKE daemon issue the following command:

$ sudo swanctl --list-sas

The status of the kernel’s XFRM subsystem can be inquired using the ip tool. To display all installed XFRM policies issue the following command:

$ sudo ip xfrm policy show

To display all installed XFRM states including the keys used for encryption and integrity protection of the IPsec connection, issue the following command:

$ sudo ip xfrm state show

Limitations

Since the TKM was developed as a prototype, it is still missing some functionality. Currently the following limitations exist:

Only basic certificate validation is performed during trustchain validation. Additional checks, such as mandated by RFC 5280, are currently missing.
Authentication of the local identity is restricted to a single private key.
Cryptographic algorithms to protect IKE and IPsec SAs are restricted to AES-CBC-256/HMAC-SHA512.
/dev/urandom is used as random source and is non-configurable.
Not all memory containing security critical data, such as Diffie-Hellman shared secrets are scrubbed after use.
The implementation of the cryptographic algorithms may be susceptible to timing side channel attacks.
The IKE splitting and the designed protocol between IKE and TKM has not (yet) been formally proven.

More detailed information is available in the project report in chapter 6.2, see documentation.

Licence

Copyright (C) 2020-2021 Tobias Brunner <tobias@codelabs.ch>
Copyright (C) 2012-2015 Reto Buerki <reet@codelabs.ch>
Copyright (C) 2012-2015 Adrian-Ken Rueegsegger <ken@codelabs.ch>

This program is free software: you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free Software
Foundation, either version 3 of the License, or (at your option) any later
version.

1. https://en.wikipedia.org/wiki/IPsec

2. https://docs.strongswan.org/docs/5.9/install/install.html

3. https://docs.strongswan.org/docs/5.9/install/kernelModules.html

4. https://docs.strongswan.org/docs/5.9/pki/pkiQuickstart.html