|
| 1 | +# wolf Key Manager |
| 2 | + |
| 3 | +This is an secure service for Key and Certificate management. |
| 4 | + |
| 5 | +Based on: |
| 6 | +* ETSI TS 103 523-3 V1.3.1 (2019-08) |
| 7 | +* IETF RFC 5958 |
| 8 | + |
| 9 | +## Features |
| 10 | + |
| 11 | +* Protection of key material / sensitive data: |
| 12 | +* Provisioning keys using an asymmetric key package request |
| 13 | +* Provisioning a trusted certificate using a CSR. |
| 14 | + |
| 15 | +## Design |
| 16 | + |
| 17 | +* Low level socket handling using libevent, which is a portable framework for handling sockets. |
| 18 | +* An HTTPS server supports GET requests using HTTP/1.1. |
| 19 | +* A TLS server supports custom commands for CSR signing and Generic hash signatures using a trusted CA. |
| 20 | +* The CA key can be local PKCS #8 (simple password/encrypted), PKCS #11 HSM or TPM 2.0. |
| 21 | +* Generated key and certificate material is encrypted with AES XTS and indexed. |
| 22 | +* Uses stdint.h types. |
| 23 | +* TLS v1.3 is used for securing connections to server |
| 24 | + |
| 25 | +## Layout of files |
| 26 | + |
| 27 | +* keymanager.c: The main entry point |
| 28 | +* sock_mgr.c: The libevent socket manager |
| 29 | +* svc_[]: Services exposed (ETSI or CERT) |
| 30 | +* mod_[]: Modules for support (HTTPS) |
| 31 | +* wkm_[]: Generic wolfKeyManager functions |
| 32 | + |
| 33 | +## ETSI Design |
| 34 | + |
| 35 | +Server Side |
| 36 | +1) KeyGen (Gen Key) |
| 37 | +2) Formatting the KeyGen (asymmetric key package) |
| 38 | +3) Sending Wire format (HTTPS) |
| 39 | + |
| 40 | +Client side |
| 41 | +1) Unbundling format |
| 42 | +2) Unbundling key gen |
| 43 | + |
| 44 | +## ETSI (Enterprise Transport Security) |
| 45 | + |
| 46 | +### ETSI GET Request Case 1 |
| 47 | + |
| 48 | +`GET /.well-known/enterprise-transport-security/keys?fingerprints=[fingerprints]`, where: |
| 49 | + |
| 50 | +a) `fingerprints` shall be present and its value, `[fingerprints]`, shall be either empty or shall be a comma-separated list of the hexadecimal string representation where each entry in the list is the static Diffie-Hellman public key fingerprint, as defined in clause 4.3.3, for which the corresponding public/private key pairs are being requested. |
| 51 | + |
| 52 | +b) The key manager shall return a key package that contains the corresponding public/private key pair for each fingerprint for which it has a record. In the unlikely case that the key manager has more than one public/private key pair corresponding to a given fingerprint, it shall return all of them in the key package. If `[fingerprints]` is empty, the actions of the implementation are out of scope of the present document. |
| 53 | + |
| 54 | +c) The key manager shall return an appropriate HTTP error code if there is not at least one matching public/private key pair [12]. |
| 55 | + |
| 56 | +Example: |
| 57 | + |
| 58 | +``` |
| 59 | +GET /.well-known/enterprise-transport-security/keys?fingerprints=00010203040506070809,09080706050403020100 |
| 60 | +Accept: application/pkcs8, application/cms |
| 61 | +``` |
| 62 | + |
| 63 | +### ETSI GET Request Case 2 |
| 64 | + |
| 65 | +`GET /.well-known/enterprise-transport-security/keys?groups=[groups]&certs=[sigalgs]&context=contextstr`, where: |
| 66 | + |
| 67 | +a) `groups` shall be non-empty and its value, `[groups]`, shall be a comma-separated list where each entry in the list is a NamedGroup value defined in clause 4.2.7 in IETF RFC 8446 [2], represented in hexadecimal notation, for which an associated static Diffie-Hellman key pair is being requested. |
| 68 | + |
| 69 | +b) `certs` may be included. If certs is included, its value, `[sigalgs]`, shall be a comma-separated list where each entry is a colon-separated pair of SignatureScheme values defined in clause B.3.1.3 in IETF RFC 8446 [2], in hexadecimal notation. The first value in the pair shall indicate the requested algorithm for the certificate issuer to use to sign the certificate. The second value in the pair shall indicate the requested algorithm to be used to generate the certificate subject's signing key pair. If certs is included, then for each entry in the list, the key consumer shall request one additional server certificate using that scheme, which is bound to all returned key pairs. If certs is not included, then no certificates are being requested, and so none shall be provided by the key manager. |
| 70 | + |
| 71 | +c) `context` may be included. If `context` is included, its value, contextstr, is a free string that the key manager shall use to determine what key pair and certificate contents to return. The structure of contextstr is not specified in the present document. |
| 72 | + |
| 73 | +d) The key manager shall return a key package containing a static Diffie-Hellman key pair for each group listed in `[groups]` that the key manager supports. For each static Diffie-Hellman key pair in the key package, the key manager shall also return a corresponding server certificate for each given signature algorithm pair listed in `[sigalgs]` that it supports. |
| 74 | + |
| 75 | +e) If no group in `[groups]` is supported by the key manager, the key manager shall return an appropriate HTTP error code as defined in clause 6 of IETF RFC 7231 [12]. If the key manager is unable to use contextstr, the key manager may return an appropriate HTTP error code, as defined in clause 6 of IETF RFC 7231 [12], or it may handle the error itself in a way outside the scope of the present document. |
| 76 | + |
| 77 | +Example: |
| 78 | + |
| 79 | +``` |
| 80 | +GET /.well-known/enterprise-transport-security/keys?groups=0x0018,0x001d&certs=0x0401:0x0809,0x0503:0x0503 |
| 81 | +Accept: application/pkcs8 |
| 82 | +``` |
| 83 | + |
| 84 | +### ETSI Push (HTTPS PUT) |
| 85 | + |
| 86 | +The key consumer shall support receiving a key package via an HTTP PUT request to a request-target, given here in origin-form, of `/enterprise-transport-security/keys`. |
| 87 | + |
| 88 | + |
| 89 | +## Asymmetric Key Packages (RFC 5958) |
| 90 | + |
| 91 | +When an Enterprise Transport Security static Diffie-Hellman public/private key pair are sent from the key manager to a key consumer, they shall be packaged using the Asymmetric Key Package defined in IETF RFC 5958 [3]. Each Asymmetric Key Package shall contain one or more OneAsymmetricKey elements. Such an element will be one of either: |
| 92 | + |
| 93 | +a) a static Diffie-Hellman key pair, hereafter referred to as Type A elements; or |
| 94 | +b) a private signing key and a certificate, hereafter referred to as Type B elements. |
| 95 | + |
| 96 | +First the case is defined where elements are static Diffie-Hellman key pairs, and so the Asymmetric Key Package shall contain fields and attributes pertaining to these key pairs, defined below. Though certificates are not sent in the same OneAsymmetricKey element as a static key pair, each Asymmetric Key Package may contain one or more Type B elements (server certificates and corresponding private signing keys). Where such Type B elements are sent, all certificates in the Asymmetric Key Package shall be bound to all of the static Diffie-Hellman key pairs in the Asymmetric Key Package. The use of multiple certificates is intended for the situation where it is necessary to provide certificates with different signature algorithms. |
| 97 | +With reference to clause 2 of IETF RFC 5958 [3], the Type A OneAsymmetricKey element used to store each key pair |
| 98 | +in the Asymmetric Key Package shall have the following fields set as follows: |
| 99 | + |
| 100 | +1) Version shall be set to version 2 (integer value of 1). |
| 101 | +2) privateKeyAlgorithm shall be set to the key pair algorithm identifier (see below). |
| 102 | +3) privateKey shall be set to the Diffie-Hellman private key encoded as an octet string. |
| 103 | +4) publicKey shall be set to the Diffie-Hellman public key encoded as a bit string. |
| 104 | +5) Attributes shall include a validity period for the key pair using the attribute defined in clause 15 of IETF RFC 7906 [4]. |
| 105 | + |
| 106 | + |
| 107 | +## Installation |
| 108 | + |
| 109 | +1. Install libevent version 2.0+ |
| 110 | + |
| 111 | +```sh |
| 112 | +$ ./configure |
| 113 | +$ make |
| 114 | +$ make check # (optional, but highly recommended) |
| 115 | +$ sudo make install |
| 116 | +``` |
| 117 | + |
| 118 | +2. Install wolfssl version 3.4.2+ |
| 119 | + |
| 120 | +```sh |
| 121 | +$ ./configure --enable-certservice --enable-sniffer CFLAGS="-DWOLFSSL_DH_EXTRA" |
| 122 | +$ make |
| 123 | +$ make check # (optional, but highly recommended) |
| 124 | +$ sudo make install |
| 125 | +``` |
| 126 | + |
| 127 | +Notes: |
| 128 | +* To enable all Intel speedups use `--enable-intelasm --enable-sp --enable-sp-asm` |
| 129 | +* To enable all Aarch64 speedups use `--enable-armasm --enable-sp --enable-sp-asm` |
| 130 | + |
| 131 | +3. Building wolfKeyMgr on *nix from git repository |
| 132 | + |
| 133 | + Run the autogen script to generate configure, you'll need the autoconf tools |
| 134 | + installed, then proceed to the next step. |
| 135 | + |
| 136 | +```sh |
| 137 | +$ ./autogen.sh |
| 138 | +``` |
| 139 | + |
| 140 | +4. Building wolfKeyMgr on *nix from a release |
| 141 | + |
| 142 | +```sh |
| 143 | +$ ./configure |
| 144 | +$ make |
| 145 | +$ make check # (optional, but highly recommended) |
| 146 | +$ sudo make install |
| 147 | +``` |
| 148 | + |
| 149 | +Note: A custom install location can be specified using: `./configure --prefix=/opt/local` |
| 150 | + |
| 151 | +## Running |
| 152 | + |
| 153 | +``` |
| 154 | +$ ./src/wolfkeymgr |
| 155 | +$ ./examples/cert_client/cert_client |
| 156 | +``` |
| 157 | + |
| 158 | +## Server Certificate Visibility |
| 159 | + |
| 160 | +The ETSI specification part 3 section 4.3.3 requires the TLS server to present a "visibility" information field indicating "Enterrpise Transport Security" is being used. |
| 161 | + |
| 162 | +``` |
| 163 | +VisibilityInformation ::= SEQUENCE { |
| 164 | + fingerprint OCTET STRING (SIZE(10)), |
| 165 | + accessDescription UTF8String } |
| 166 | +``` |
| 167 | + |
| 168 | +where the SHA-256 digest of the static Diffie-Hellman public key as transmitted in the key_share extension of the ServerHello message shall be represented as the vector of 32-bit words (H0, H1,..., H7) as defined in FIPS 180-4 [11]. The fingerprint field shall be set to H0||H1||(H2>>16), which is the first 80 bits of the digest vector read in big-endian format. The accessDescription field shall be a human-readable text string that identifies, either generally or specifically, the controlling or authorizing entities or roles or domains, or any combination of these, of any middleboxes that may be allowed access to the Enterprise Transport Security static Diffie-Hellman private key. |
| 169 | + |
| 170 | +See Recommendation ITU-T X.509 (10/2016) | ISO/IEC 9594-8: "Information technology - Open Systems Interconnection - The Directory: Public-key and attribute certificate frameworks". |
| 171 | + |
| 172 | +## Support |
| 173 | + |
| 174 | +For questions or to request an evaluation package please email [email protected] |
0 commit comments