|
| 1 | +# wolf Key Manager ETSI Reference |
| 2 | + |
| 3 | +Based on [ETSI TS 103 523-3 V1.3.1](https://www.etsi.org/deliver/etsi_ts/103500_103599/10352303/01.03.01_60/ts_10352303v010301p.pdf) |
| 4 | + |
| 5 | +## Components |
| 6 | + |
| 7 | + |
| 8 | + |
| 9 | +* Key Manager (`src/wolfkeymgr`) |
| 10 | +* Enterprise Transport Security Server (`examples/https/server` or Apache httpd, nginx, etc...) |
| 11 | +* Middlebox Decryption (`examples/middlebox/decrypt` using wolfSSL sniffer) |
| 12 | +* TLS v1.3 client (browser or `examples/https/client`) |
| 13 | +* Asymmetric Key Package (RFC 5958 - PKCS8) |
| 14 | + |
| 15 | +## ETSI Security |
| 16 | + |
| 17 | +All communication between consumer and ETSI Key Manager will use TLS v1.3 with mutual authentication. |
| 18 | + |
| 19 | +The Enterprise Transport Security profile does not provide per-session forward secrecy. Knowledge of a given static private key can be used to decrypt all sessions encrypted with that key, and forward secrecy for all of those sessions begins when all copies of that static private key have been destroyed. |
| 20 | + |
| 21 | +Typically an organization will use standard TLS 1.3 to connect with external clients to the enterprise network or data centre. For connections within its own data center and could deployments the Enterprise Transport Security profile can be used. |
| 22 | + |
| 23 | +An organization can rotate their keys as frequently as they choose. |
| 24 | + |
| 25 | +The use of X.509 Visibility Information in the TLS server certificate should be used, but is not required for private internal use. The visibility information OID 0.4.0.3523.3.1 provides a public way to indicate the ETSI security profile is being used. |
| 26 | + |
| 27 | +## ETSI (Enterprise Transport Security) |
| 28 | + |
| 29 | +### ETSI Request Case (HTTPS GET) |
| 30 | + |
| 31 | +`GET /.well-known/enterprise-transport-security/keys?fingerprints=[fingerprints]`, where: |
| 32 | + |
| 33 | +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. |
| 34 | + |
| 35 | +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. |
| 36 | + |
| 37 | +c) The key manager shall return an appropriate HTTP error code if there is not at least one matching public/private key pair [12]. |
| 38 | + |
| 39 | +Example: |
| 40 | + |
| 41 | +``` |
| 42 | +GET /.well-known/enterprise-transport-security/keys?fingerprints=00010203040506070809,09080706050403020100 |
| 43 | +Accept: application/pkcs8, application/cms |
| 44 | +``` |
| 45 | + |
| 46 | +### ETSI Request with Groups (key type) |
| 47 | + |
| 48 | +`GET /.well-known/enterprise-transport- security/keys?groups=[groups]&certs=[sigalgs]&context=contextstr`, where: |
| 49 | + |
| 50 | +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. |
| 51 | + |
| 52 | +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. |
| 53 | + |
| 54 | +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. |
| 55 | + |
| 56 | +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. |
| 57 | + |
| 58 | +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. |
| 59 | + |
| 60 | +Example: |
| 61 | + |
| 62 | +``` |
| 63 | +GET /.well-known/enterprise-transport-security/keys?groups=0x0018,0x001d&certs=0x0401:0x0809,0x0503:0x0503 |
| 64 | +Accept: application/pkcs8 |
| 65 | +``` |
| 66 | + |
| 67 | +### ETSI Push (HTTPS PUT) |
| 68 | + |
| 69 | +The key consumer shall support receiving a key package via an HTTP PUT request to a request-target, given here in origin-form, of: |
| 70 | +`/enterprise-transport-security/keys` |
| 71 | + |
| 72 | +### Asymmetric Key Packages (RFC 5958) |
| 73 | + |
| 74 | +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: |
| 75 | + |
| 76 | +a) a static Diffie-Hellman key pair, hereafter referred to as Type A elements; or |
| 77 | +b) a private signing key and a certificate, hereafter referred to as Type B elements. |
| 78 | + |
| 79 | +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. |
| 80 | +With reference to clause 2 of IETF RFC 5958 [3], the Type A OneAsymmetricKey element used to store each key pair |
| 81 | +in the Asymmetric Key Package shall have the following fields set as follows: |
| 82 | + |
| 83 | +1) Version shall be set to version 2 (integer value of 1). |
| 84 | +2) privateKeyAlgorithm shall be set to the key pair algorithm identifier (see below). |
| 85 | +3) privateKey shall be set to the Diffie-Hellman private key encoded as an octet string. |
| 86 | +4) publicKey shall be set to the Diffie-Hellman public key encoded as a bit string. |
| 87 | +5) Attributes shall include a validity period for the key pair using the attribute defined in clause 15 of IETF RFC 7906 [4]. |
| 88 | + |
| 89 | +### Server Certificate Visibility |
| 90 | + |
| 91 | +The ETSI specification part 3 section 4.3.3 requires the TLS server to present a "visibility" information field indicating "Enterprise Transport Security" is being used. |
| 92 | + |
| 93 | +``` |
| 94 | +VisibilityInformation ::= SEQUENCE { |
| 95 | + fingerprint OCTET STRING (SIZE(10)), |
| 96 | + accessDescription UTF8String } |
| 97 | +``` |
| 98 | + |
| 99 | +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 middle-boxes that may be allowed access to the Enterprise Transport Security static Diffie-Hellman private key. |
| 100 | + |
| 101 | +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". |
0 commit comments