{"id":19579744,"url":"https://github.com/wolfssl/wolfkeymgr","last_synced_at":"2025-04-27T08:31:53.964Z","repository":{"id":38719725,"uuid":"332082390","full_name":"wolfSSL/wolfKeyMgr","owner":"wolfSSL","description":"Secure key management service for middle-box decryption of TLS traffic","archived":false,"fork":false,"pushed_at":"2024-09-04T17:59:48.000Z","size":2546,"stargazers_count":14,"open_issues_count":0,"forks_count":6,"subscribers_count":19,"default_branch":"main","last_synced_at":"2025-04-04T23:11:12.468Z","etag":null,"topics":["apache","enterprise-transport-security","ets","key-management","security","ssl","tls","wolfcrypt","wolfssl"],"latest_commit_sha":null,"homepage":"https://www.wolfssl.com","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wolfSSL.png","metadata":{"files":{"readme":"README.md","changelog":"ChangeLog.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-01-22T23:00:29.000Z","updated_at":"2024-10-22T11:35:18.000Z","dependencies_parsed_at":"2022-09-08T14:23:13.166Z","dependency_job_id":null,"html_url":"https://github.com/wolfSSL/wolfKeyMgr","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wolfSSL%2FwolfKeyMgr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wolfSSL%2FwolfKeyMgr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wolfSSL%2FwolfKeyMgr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wolfSSL%2FwolfKeyMgr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wolfSSL","download_url":"https://codeload.github.com/wolfSSL/wolfKeyMgr/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251112532,"owners_count":21538162,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["apache","enterprise-transport-security","ets","key-management","security","ssl","tls","wolfcrypt","wolfssl"],"created_at":"2024-11-11T07:18:51.778Z","updated_at":"2025-04-27T08:31:49.921Z","avatar_url":"https://github.com/wolfSSL.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# wolf Key Manager for Enterprise Transport Security (ETS)\n\nThis is a secure key management service for providing middle-box decryption of TLS traffic.\n\nThe library includes examples to demonstrate full passive decryption of an HTTPS server. We also have a demo package for Apache httpd available by request.\n\n## Design\n\nBased on:\n* ETSI TS 103 523-3 V1.3.1 (2019-08)\n* IETF RFC 5958\n\n## Features\n\n* Generation of keys using an asymmetric key package request\n* Low level socket handling using libevent, which is a portable framework for handling sockets\n* HTTPS server supports GET/PUT requests using HTTP/1.1\n* The CA key can be local PKCS #8 (simple password/encrypted), PKCS #11 HSM or TPM 2.0\n* TLS v1.3 is used for securing connections to server\n* Secure key vault protected with RSA and AES GCM\n\n## Layout of files\n\n* keymanager.c: The main entry point\n* sock_mgr.c: The libevent socket manager\n* svc_[]: Services exposed (ETS)\n* mod_[]: Modules for support (HTTP, TLS, Socket, ETS and Vault)\n* wkm_[]: Generic wolf / KeyManager functions\n\n## ETS Design\n\nServer Side\n1) KeyGen (Gen Key)\n2) Formatting the KeyGen (asymmetric key package)\n3) Sending Wire format (HTTPS)\n4) Key expiration and notification of new key to peers\n\nClient side\n1) Encoding ETS HTTP request\n2) Parsing HTTP response\n3) Unbundling asymmetric key\n\n\n## Key Manager Build and Install\n\n1. Install wolfssl version v4.8.0+\n\n```sh\n$ ./autogen.sh\n$ git clone https://github.com/wolfssl/wolfssl\n$ cd wolfssl\n$ ./autogen.sh\n$ ./configure --enable-sniffer --enable-curve25519 --enable-curve448 --enable-enckeys CFLAGS=\"-DWOLFSSL_DH_EXTRA\"\n$ make\n$ make check   # (optional, but highly recommended)\n$ sudo make install\n```\n\nNotes:\n\n* To enable all Intel (AESNI/AVX) speedups use `--enable-intelasm --enable-sp --enable-sp-asm`\n* To enable all ARMv8 (aarch64) speedups use `--enable-armasm --enable-sp --enable-sp-asm`\n\n* Requires at least wolfSSL v5.0.0 with PR:\n   - https://github.com/wolfSSL/wolfssl/pull/4522 (required for Curve448)\n\n2. Install libevent version 2.0+\n\nMost platforms have a `libevent-dev` package available.\nExample: `sudo apt install libevent-dev`.\n\nTo build manually:\n\n```sh\n$ curl -o libevent-2.1.12-stable.tar.gz -L https://github.com/libevent/libevent/releases/download/release-2.1.12-stable/libevent-2.1.12-stable.tar.gz\n$ tar xzvf libevent-2.1.12-stable.tar.gz\n$ cd libevent-2.1.12-stable\n$ ./configure --disable-openssl\n$ make\n$ make check   # (optional, but highly recommended)\n$ sudo make install\n```\n\n3. Install libpcap for middle-box decryption example (or build with `--disable-sniffer`)\n\n* Mac OS/X: `brew install libpcap`\n* Debian/Ubuntu: `sudo apt install libpcap-dev`\n* RedHat/CentOS: 'sudo yum install libpcap-dev`\n* Windows: Download and install `WinPcap`\n\n4. Building wolfKeyMgr on *nix\n\n```sh\n$ ./autogen.sh # if cloned from git repository\n$ ./configure\n$ make\n$ make check   # (optional, but highly recommended)\n$ sudo make install\n```\n\nNotes:\n* A custom install location can be specified using: `./configure --prefix=/opt/local`\n* `autogen.sh` is script to generate configure, you'll need the autoconf tools\ninstalled, then proceed to the next step.\n* `src/wolfkeymgr` is the key manager service / daemon. A make install will typically put it into `/usr/local/bin/wolfkeymgr` or ``/usr/bin/wolfkeymgr`.\n\n## Examples\n\nThe wolf Key Manager includes examples for ETS client tests, HTTPS server / client and middle-box decryption.\n\nAll test parameters for these examples are in the `examples/test_config.h`.\n\n### Key Manager Service\n\nThis application handles secure distribution and optional storage of the generated ephemeral keys.\n\n```sh\n$ ./src/wolfkeymgr -?\nwolfKeyManager 1.1\n-?          Help, print this usage\n-i          Do not chdir / in daemon mode\n-b          Daemon mode, run in background\n-p \u003cstr\u003e    Pid File name, default ./wolfkeymgr.pid\n-P \u003cport\u003e   Listener port, default 8119\n-l \u003cnum\u003e    Log Level (1=Error to 4=Debug), default 4\n-f \u003cstr\u003e    Log file name, default None\n-o \u003cnum\u003e    Max open files, default  1024\n-s \u003cnum\u003e    Seconds to timeout non-push connections, default 60\n-r \u003cnum\u003e    Key renewal timeout, default 3600\n-u \u003cnum\u003e    Key renewal max use count, default 100\n-t \u003cnum\u003e    Thread pool size, default  16\n-k \u003cpem\u003e    TLS Server TLS Key, default ./certs/server-rsa-key.pem\n-w \u003cpass\u003e   TLS Server Key Password, default wolfssl\n-c \u003cpem\u003e    TLS Server Certificate, default ./certs/server-rsa-cert.pem\n-A \u003cpem\u003e    TLS CA Certificate, default ./certs/ca-cert.pem\n-K \u003ckeyt\u003e   Key Type: SECP256R1, FFDHE_2048, X25519 or X448 (default SECP256R1)\n-v \u003cfile\u003e   Vault file for key storage, default ./wolfkeymgr.vault\n```\n\nTo exit the key manager use ctrl+c.\n\n### ETS Test client\n\nThis demonstrates secure interactions with the key manager service using the ETS HTTPS GET/PUT commands for different key types.\n\n```sh\n$ ./examples/ets_test/ets_test -?\nets_test 1.1\n-?          Help, print this usage\n-e          Error mode, force error response\n-h \u003cstr\u003e    Host to connect to, default localhost\n-p \u003cnum\u003e    Port to connect to, default 8119\n-t \u003cnum\u003e    Thread pool size (stress test), default  0\n-l \u003cnum\u003e    Log Level (1=Error to 4=Debug), default 4\n-r \u003cnum\u003e    Requests per thread, default 1\n-f \u003cfile\u003e   \u003cfile\u003e to store ETS response\n-u          Use ETS Push (default is get)\n-s \u003csec\u003e    Timeout seconds (default 10)\n-k \u003cpem\u003e    TLS Client TLS Key, default certs/client-key.pem\n-w \u003cpass\u003e   TLS Client Key Password, default wolfssl\n-c \u003cpem\u003e    TLS Client Certificate, default certs/client-cert.pem\n-A \u003cpem\u003e    TLS CA Certificate, default certs/ca-cert.pem\n-K \u003ckeyt\u003e   Key Type: SECP256R1, FFDHE_2048, X25519 or X448 (default SECP256R1)\n-F \u003cfprint\u003e Fingerprint to find (first 80-bit of pkey hash as hex string)\n-C \u003cname\u003e   Unique key name (used for multiple servers)\n```\n\nThis client also support stress testing options:\n* Use the thread pool \"-t\" to spin up more threads.\n* Use the ETS test client \"-r\" to make additional requests per thread.\n* Use the \"-F\" argument to get key for specific fingerprint (hex string of hash of public key - first 80 bits / 10 bytes)\n* Use the \"-C\" command to include context string (used for multiple servers).\n\n#### ETS Fingerprint\n\nThe fingerprint is a SHA-256 hash of the ephemeral public key with the first 80 bits (10 bytes) in big endian format. If the fingerprint is blank the current active key for that TLS group will be returned (assuming it is within the expiration and use count restrictions).\n\nThe fingerprint is used to lookup an ephemeral key based on public key using the following scheme:\n* ECC: Public X and Y hashed with SHA256 (first 10 bytes)\n* DH: Public key hashed with SHA256 (first 10 bytes)\n\n#### ETS Context String\n\nThe context string is used to specify additional information to the key manager to distribute keys for multiple servers.\n\n### HTTP Server / Client\n\nWe have included a simple HTTPS server to show getting the static ephemeral key using the ETS client and key manager.\n\n```\n./examples/https/server\n\nHTTPS Server: Port 443\n\nJun 15 14:26:54 2021: [INFO] Connected to ETS service\nJun 15 14:26:54 2021: [INFO] Sent get request (117 bytes)\nJun 15 14:26:54 2021: [DEBUG] HTTP HTTP/1.1\nJun 15 14:26:54 2021: [DEBUG] \tCode 200: OK\nJun 15 14:26:54 2021: [DEBUG] \tHeaders: 4\nJun 15 14:26:54 2021: [DEBUG] \t\tContent-Type: : application/pkcs8\nJun 15 14:26:54 2021: [DEBUG] \t\tConnection: : Keep-Alive\nJun 15 14:26:54 2021: [DEBUG] \t\tExpires: : Tue, 15 Jun 2021 15:26:46 PDT\nJun 15 14:26:54 2021: [DEBUG] \t\tContent-Length: : 121\nJun 15 14:26:54 2021: [DEBUG] \tBody Size: 121\nJun 15 14:26:54 2021: [INFO] Got ETS response (121 bytes)\nGot ETS static ephemeral key (121 bytes)\nJun 15 14:26:54 2021: [INFO] SECP256R1: E24EF332747DF70CD4E5\n\nTLS Accept 127.0.0.1\nJun 15 14:27:01 2021: [DEBUG] HTTP GET\nJun 15 14:27:01 2021: [DEBUG] \tVersion: HTTP/1.1\nJun 15 14:27:01 2021: [DEBUG] \tURI: /\nJun 15 14:27:01 2021: [DEBUG] \tHeaders: 6\nJun 15 14:27:01 2021: [DEBUG] \t\tHost: : localhost\nJun 15 14:27:01 2021: [DEBUG] \t\tAccept: : text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8\nJun 15 14:27:01 2021: [DEBUG] \t\tAccept-Language: : en-us\nJun 15 14:27:01 2021: [DEBUG] \t\tConnection: : keep-alive\nJun 15 14:27:01 2021: [DEBUG] \t\tAccept-Encoding: : gzip, deflate, br\nJun 15 14:27:01 2021: [DEBUG] \t\tUser-Agent: : Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.1 Safari/605.1.15\n\nETS Key Cached (valid for 3585 sec)\n```\n\n### Middle-Box Decryption of TLS traffic\n\nThis is a passive way to decrypt TLS traffic including Perfect Forward Secrecy (PFS) TLS v1.3 where a new ephemeral key is used for each session.\n\nThis can be run in a real-time mode capturing ethernet traffic on a port for one or more server interfaces. It can also be run passing a previously captured pcap file.\n\n```sh\n$ ./examples/middlebox/decrypt -?\ndecrypt 1.1\nusage: ./decrypt or ./decrypt pcapFile keyServerURL [server] [port] [password]\n-?           Help, print this usage\npcapFile     A previously saved pcap file\nkeyServerURL Key Manager URL or private key as PEM (default https://localhost:8119)\nserver       The server’s IP address (v4 or v6) (default 127.0.0.1)\nport         The server port to sniff (default 443)\npassword     Private Key Password if required\n```\n\n\n## Demo Usage\n\n1. Start the key manager: `./src/wolfkeymgr`\n2. Run the HTTPS server `./examples/https/server`\n3. Run the middle-box decryption `./examples/middlebox/decrypt` and use the default parameters.\n4. Open a web browser to `https://localhost` or run the HTTP client example `./examples/https/client`.\n5. In the middle-box decryption window you will see the decrypted HTTPS traffic.\n\nNotes:\n\n1) Most browsers will show a security warning because the certificate common name for localhost is a security risk. Here is not to bypass this for each browser:\n* FireFox: \"Warning: Potential Security Risk Ahead\". Click \"Advanced\". Click \"Accept the Risk and Continue\"\n* Chrome: Launch Chrome browser and then visit: `chrome://flags/#allow-insecure-localhost`. Using “Allow invalid certificates for resources loaded from localhost” drop-down change the setting from Disabled to Enabled. Relaunch Chrome browser to enable the feature. Doing this will “Allow insecure connections on localhost in Chrome” and fix the issue.\n\n2) Some browsers behave different with localhost and will not send the SNI extension, which may cause issues. Switching to a physical ethernet interface and IP address (example https://192.168.0.4:443) may work better.\n\n3) To generate a different common name in the self-signed certificate see `wolfKeyMgr/certs/gen-certs.sh` and modify `CN=` then re-run `./certs/gen-certs.sh` or manually run the following command:\n`openssl req -new -x509 -nodes -key ./certs/test-key.pem -out ./certs/test-cert.pem -sha256 -days 7300 -batch -subj \"/C=US/ST=CA/L=Seattle/O=wolfSSL/OU=Development/CN=localhost/emailAddress=info@wolfssl.com\"`. For testing it might be useful to setup a fake domain in `/etc/hosts`.\n\n4) If you get \"Permission denied\" errors try adding `sudo` to the commands.\n\n\n### Demo example output\n\n```\n% ./src/wolfkeymgr\nAug 03 15:05:21 2021: [INFO] Starting Key Manager\nAug 03 15:05:21 2021: [INFO] \tTo exit use ctrl+c\nAug 03 15:05:21 2021: [INFO] loaded CA certificate file ./certs/ca-cert.pem\nAug 03 15:05:21 2021: [INFO] loaded key file ./certs/server-rsa-key.pem\nAug 03 15:05:21 2021: [INFO] loaded certificate file ./certs/server-rsa-cert.pem\nAug 03 15:05:21 2021: [ERRO] Vault open failed, creating new\nAug 03 15:05:21 2021: [INFO] Vault ./wolfkeymgr.vault opened (0 bytes)\nAug 03 15:05:21 2021: [INFO] Version: 1\nAug 03 15:05:21 2021: [INFO] Header Size: 296\nAug 03 15:05:21 2021: [INFO] Item Count: 0\nAug 03 15:05:21 2021: [INFO] Total Size: 0\nAug 03 15:05:21 2021: [WARN] Generating new SECP256R1 key\nAug 03 15:05:21 2021: [INFO] Binding listener :::8119\nAug 03 15:05:21 2021: [INFO] Setting up new ETS conn item pool\nAug 03 15:05:21 2021: [INFO] Growing ETS service conn pool\nAug 03 15:05:21 2021: [INFO] Growing ETS service conn pool\nAug 03 15:05:21 2021: [INFO] SECP256R1: E24EF332747DF70CD4E5\nAug 03 15:05:21 2021: [WARN] Vault Auth: Setting up new encryption key\nAug 03 15:05:21 2021: [INFO] Next key renewal 3600 seconds\n```\n\n```\n % ./examples/https/server\nHTTPS Server: Port 443\nAug 03 15:09:50 2021: [INFO] Connected to ETS service\n```\n\n```\n % ./examples/middlebox/decrypt\n1. lo0 (No description available)\n2. en0 (No description available)\nEnter the interface number (1-2) [default: 1]:\nserver = 127.0.0.1\nserver = ::1\nserver = fe80::1\nEnter the port to scan [default: 443]:\nEnter the server key [default: https://localhost:8119]:\nAug 03 15:07:33 2021: [INFO] Connected to ETS service\n...\n\nGot ETS static ephemeral key (121 bytes)\nAug 03 15:07:33 2021: [INFO] SECP256R1: E24EF332747DF70CD4E5\nLoaded key for fe80::1:443\nSSL App Data(30:323):GET / HTTP/1.1\nHost: localhost\nAccept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8\nAccept-Language: en-us\nConnection: keep-alive\nAccept-Encoding: gzip, deflate, br\nUser-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.1 Safari/605.1.15\n\n\nSSL App Data(32:132):HTTP/1.1 200 OK\nContent-Type: text/html\nConnection: keep-alive\nContent-Length: 44\n\n\u003chtml\u003e\u003cbody\u003e\u003ch1\u003eIt works!\u003c/h1\u003e\u003c/body\u003e\u003c/html\u003e\n```\n\n## Features Missing\n\n* Find error response message (currently disconnects with socket FIN)\n* X509 Visibility support\n* TLS v1.2 ephemeral key support\n\n\n## Support\n\nFor questions or to request an evaluation package please email facts@wolfssl.com\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwolfssl%2Fwolfkeymgr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwolfssl%2Fwolfkeymgr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwolfssl%2Fwolfkeymgr/lists"}