You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
* Fix for ETSI client to properly detect socket error with non-blocking connect.
* Added EtsiKey struct and modified the wolfEtsiClientGet() API.
* Implemented some ETSI key helpers.
* Added stub API's for future push/find with callbacks.
* Progress with handling key expiration data and other key types.
Copy file name to clipboardExpand all lines: README.md
+97-67Lines changed: 97 additions & 67 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,6 +1,6 @@
1
1
# wolf Key Manager
2
2
3
-
This is a secure service for Key management using ETSI specification.
3
+
This is a secure service for Key management based on ETSI Enterprise Transport Security specification. Provides middle-box decryption of TLS traffic.
4
4
5
5
For a demo package showing use with Apache httpd and the wolfSSL sniffer please email [email protected].
6
6
@@ -24,7 +24,7 @@ Based on:
24
24
* sock_mgr.c: The libevent socket manager
25
25
* svc_[]: Services exposed (ETSI)
26
26
* mod_[]: Modules for support (HTTP, TLS, Socket, ETSI)
27
-
* wkm_[]: Generic wolfKeyManager functions
27
+
* wkm_[]: Generic wolf / KeyManager functions
28
28
29
29
## ETSI Design
30
30
@@ -35,12 +35,100 @@ Server Side
35
35
4) Key expiration and notification of new key to peers
36
36
37
37
Client side
38
-
1)Generating ETSI HTTP request
38
+
1)Encoding ETSI HTTP request
39
39
2) Parsing HTTP response
40
40
3) Unbundling asymmetric key
41
41
42
+
## ETSI Security
42
43
43
-
## Installation
44
+
All communication between consumer and ETSI Key Manager will use TLS v1.3.
45
+
46
+
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.
47
+
48
+
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.
49
+
50
+
An organization can rotate their keys as frequently as they choose.
51
+
52
+
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.
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.
61
+
62
+
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.
63
+
64
+
c) The key manager shall return an appropriate HTTP error code if there is not at least one matching public/private key pair [12].
65
+
66
+
Example:
67
+
68
+
```
69
+
GET /.well-known/enterprise-transport-security/keys?fingerprints=00010203040506070809,09080706050403020100
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.
78
+
79
+
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.
80
+
81
+
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.
82
+
83
+
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.
84
+
85
+
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.
86
+
87
+
Example:
88
+
89
+
```
90
+
GET /.well-known/enterprise-transport-security/keys?groups=0x0018,0x001d&certs=0x0401:0x0809,0x0503:0x0503
91
+
Accept: application/pkcs8
92
+
```
93
+
94
+
### ETSI Push (HTTPS PUT)
95
+
96
+
The key consumer shall support receiving a key package via an HTTP PUT request to a request-target, given here in origin-form, of:
97
+
`/enterprise-transport-security/keys`
98
+
99
+
### Asymmetric Key Packages (RFC 5958)
100
+
101
+
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:
102
+
103
+
a) a static Diffie-Hellman key pair, hereafter referred to as Type A elements; or
104
+
b) a private signing key and a certificate, hereafter referred to as Type B elements.
105
+
106
+
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.
107
+
With reference to clause 2 of IETF RFC 5958 [3], the Type A OneAsymmetricKey element used to store each key pair
108
+
in the Asymmetric Key Package shall have the following fields set as follows:
109
+
110
+
1) Version shall be set to version 2 (integer value of 1).
111
+
2) privateKeyAlgorithm shall be set to the key pair algorithm identifier (see below).
112
+
3) privateKey shall be set to the Diffie-Hellman private key encoded as an octet string.
113
+
4) publicKey shall be set to the Diffie-Hellman public key encoded as a bit string.
114
+
5) Attributes shall include a validity period for the key pair using the attribute defined in clause 15 of IETF RFC 7906 [4].
115
+
116
+
### Server Certificate Visibility
117
+
118
+
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.
119
+
120
+
```
121
+
VisibilityInformation ::= SEQUENCE {
122
+
fingerprint OCTET STRING (SIZE(10)),
123
+
accessDescription UTF8String }
124
+
```
125
+
126
+
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.
127
+
128
+
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".
129
+
130
+
131
+
## Key Manager Installation
44
132
45
133
1. Install libevent version 2.0+
46
134
@@ -91,6 +179,7 @@ $ sudo make install
91
179
92
180
Note: A custom install location can be specified using: `./configure --prefix=/opt/local`
93
181
182
+
94
183
## Key Manager and ETSI Client Command Line Help
95
184
96
185
Help using `-?`:
@@ -126,15 +215,15 @@ etsi_client 0.3
126
215
-l <num> Log Level (1=Error to 4=Debug), default 4
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.
202
-
203
-
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.
204
-
205
-
c) The key manager shall return an appropriate HTTP error code if there is not at least one matching public/private key pair [12].
206
-
207
-
Example:
208
-
209
-
```
210
-
GET /.well-known/enterprise-transport-security/keys?fingerprints=00010203040506070809,09080706050403020100
211
-
Accept: application/pkcs8, application/cms
212
-
```
213
-
214
-
### ETSI Push (HTTPS PUT)
215
-
216
-
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`.
217
-
218
-
219
-
### Asymmetric Key Packages (RFC 5958)
220
-
221
-
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:
222
-
223
-
a) a static Diffie-Hellman key pair, hereafter referred to as Type A elements; or
224
-
b) a private signing key and a certificate, hereafter referred to as Type B elements.
225
-
226
-
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.
227
-
With reference to clause 2 of IETF RFC 5958 [3], the Type A OneAsymmetricKey element used to store each key pair
228
-
in the Asymmetric Key Package shall have the following fields set as follows:
229
-
230
-
1) Version shall be set to version 2 (integer value of 1).
231
-
2) privateKeyAlgorithm shall be set to the key pair algorithm identifier (see below).
232
-
3) privateKey shall be set to the Diffie-Hellman private key encoded as an octet string.
233
-
4) publicKey shall be set to the Diffie-Hellman public key encoded as a bit string.
234
-
5) Attributes shall include a validity period for the key pair using the attribute defined in clause 15 of IETF RFC 7906 [4].
235
-
236
-
### Server Certificate Visibility
237
-
238
-
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.
239
-
240
-
```
241
-
VisibilityInformation ::= SEQUENCE {
242
-
fingerprint OCTET STRING (SIZE(10)),
243
-
accessDescription UTF8String }
244
-
```
245
-
246
-
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.
247
-
248
-
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".
249
-
250
-
## Outstanding Features
251
-
252
-
1) Add example for HTTP server "VisibilityInformation" extension.
253
-
254
284
## Support
255
285
256
-
For questions or to request an evaluation package please email [email protected]
286
+
For questions or to request an evaluation package please email [email protected]
0 commit comments