wolfKeyMgr: Decrypt Internal TLS 1.3 Traffic Without Breaking It

    • TLS 1.3 made per-session forward secrecy the default. That is a win for privacy on the open internet, but inside your own data center it leaves monitoring, compliance, and intrusion-detection tools blind to the traffic they are meant to watch. wolfKeyMgr is wolfSSL’s answer.

    What wolfKeyMgr Does

     
    wolfKeyMgr is a secure key management service for Enterprise Transport Security (ETS), the middle-box decryption profile from ETSI TS 103 523-3. It centrally generates, distributes, stores, and expires the static Diffie-Hellman keys that let authorized tools passively decrypt internal TLS traffic, with no proprietary appliance and no weakened crypto.

    How ETS Works

     
    ETS servers use static key-exchange keys that your organization manages and rotates centrally, instead of the ephemeral keys negotiated per connection. wolfKeyMgr supports static finite-field DH and ECDHE, including the X25519 and X448 curves. A designated middle-box holding the matching private key can then passively decrypt the traffic it is authorized to see.

    It is meant for internal traffic only. You still use standard TLS 1.3 with full forward secrecy for external clients, and forward secrecy returns for a set of sessions once every copy of the static key is destroyed. The X.509 Visibility Information OID 0.4.0.3523.3.1 publicly signals that the ETS profile is in use.

    Feature Highlights

     

    • Implements the ETSI TS 103 523-3 ETS profile, with keys packaged as RFC 5958 Asymmetric Key Packages (PKCS #8).
    • TLS 1.3 with mutual authentication on every connection.
    • Encrypted key vault protected with RSA and AES-GCM.
    • CA key in a local PKCS #8 file, a PKCS #11 HSM, or a TPM 2.0 device.
    • Standard HTTP/1.1 GET and PUT requests against the /.well-known/enterprise-transport-security/keys endpoint.
    • Key expiration plus push of new keys to peers.
    • Portable, event-driven core built on libevent.
    • Working examples for ETS clients, an HTTPS server and client, and middle-box passive decryption using the wolfSSL sniffer.

    Build It

     
    Build wolfSSL, then build wolfKeyMgr.

    git clone https://github.com/wolfSSL/wolfssl
cd wolfssl && ./autogen.sh
./configure --enable-sniffer --enable-curve25519 --enable-curve448 \
            --enable-enckeys CFLAGS="-DWOLFSSL_DH_EXTRA"
make && sudo make install
cd ../wolfKeyMgr && ./autogen.sh
./configure && make && sudo make install

    This installs the wolfkeymgr daemon, typically to /usr/local/bin/wolfkeymgr.

    Try It in Two Terminals

     
    Start the key manager:

    ./src/wolfkeymgr -p 8119

    Run the ETS client. It opens a mutually authenticated TLS 1.3 connection, sends an ETS GET request, and receives a key package:

    ./examples/ets_test/ets_test -h localhost -p 8119

    [INFO] Connected to ETS service
[INFO] Sent get request (117 bytes)
[INFO] Got ETS response (121 bytes)
[INFO] SECP256R1: 77EDAA745F7758A5DC9A

    That fingerprint is the first 80 bits of the static public key hash, exactly what a middle-box uses to request the matching private key and decrypt a captured session. Point the bundled decrypt example at a captured ETS session to watch it recover the plaintext.

    Tested and Current

     
    wolfKeyMgr builds cleanly and passes its test suite against both the latest stable wolfSSL 5.9.1 release and the current master branch, so you can pin to a release or follow the leading edge with confidence.

    Get Started

     
    wolfKeyMgr is open source at github.com/wolfSSL/wolfKeyMgr, and the docs/ directory includes a full ETS reference.

    Questions about wolfKeyMgr, Enterprise Transport Security, or middle-box decryption, or want the Apache httpd ETS demo package? Contact us at facts@wolfssl.com or +1 425 245 8247. For technical support, reach out at support@wolfssl.com.

    Download wolfSSL Now