]>
Commit | Line | Data |
---|---|---|
b38c8945 JW |
1 | /** @file |
2 | EFI TLS Protocols as defined in UEFI 2.5. | |
3 | ||
4 | The EFI TLS Service Binding Protocol is used to locate EFI TLS Protocol drivers | |
5 | to create and destroy child of the driver to communicate with other host using | |
6 | TLS protocol. | |
7 | The EFI TLS Protocol provides the ability to manage TLS session. | |
8 | ||
9 | Copyright (c) 2016, Intel Corporation. All rights reserved.<BR> | |
10 | This program and the accompanying materials | |
11 | are licensed and made available under the terms and conditions of the BSD License | |
12 | which accompanies this distribution. The full text of the license may be found at | |
13 | http://opensource.org/licenses/bsd-license.php | |
14 | ||
15 | THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, | |
16 | WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. | |
17 | ||
18 | @par Revision Reference: | |
19 | This Protocol is introduced in UEFI Specification 2.5 | |
20 | ||
21 | **/ | |
22 | ||
23 | #ifndef __EFI_TLS_PROTOCOL_H__ | |
24 | #define __EFI_TLS_PROTOCOL_H__ | |
25 | ||
26 | /// | |
27 | /// The EFI TLS Service Binding Protocol is used to locate EFI TLS Protocol drivers to | |
28 | /// create and destroy child of the driver to communicate with other host using TLS | |
29 | /// protocol. | |
30 | /// | |
31 | #define EFI_TLS_SERVICE_BINDING_PROTOCOL_GUID \ | |
32 | { \ | |
33 | 0x952cb795, 0xff36, 0x48cf, {0xa2, 0x49, 0x4d, 0xf4, 0x86, 0xd6, 0xab, 0x8d } \ | |
34 | } | |
35 | ||
36 | /// | |
37 | /// The EFI TLS protocol provides the ability to manage TLS session. | |
38 | /// | |
39 | #define EFI_TLS_PROTOCOL_GUID \ | |
40 | { \ | |
41 | 0xca959f, 0x6cfa, 0x4db1, {0x95, 0xbc, 0xe4, 0x6c, 0x47, 0x51, 0x43, 0x90 } \ | |
42 | } | |
43 | ||
44 | typedef struct _EFI_TLS_PROTOCOL EFI_TLS_PROTOCOL; | |
45 | ||
46 | /// | |
47 | /// EFI_TLS_SESSION_DATA_TYPE | |
48 | /// | |
49 | typedef enum { | |
50 | /// | |
51 | /// Session Configuration | |
52 | /// | |
53 | ||
54 | /// | |
55 | /// TLS session Version. The corresponding Data is of type EFI_TLS_VERSION. | |
56 | /// | |
57 | EfiTlsVersion, | |
58 | /// | |
59 | /// TLS session as client or as server. The corresponding Data is of | |
60 | /// EFI_TLS_CONNECTION_END. | |
61 | /// | |
62 | EfiTlsConnectionEnd, | |
63 | /// | |
64 | /// A priority list of preferred algorithms for the TLS session. | |
65 | /// The corresponding Data is a list of EFI_TLS_CIPHER. | |
66 | /// | |
67 | EfiTlsCipherList, | |
68 | /// | |
69 | /// TLS session compression method. | |
70 | /// The corresponding Data is of type EFI_TLS_COMPRESSION. | |
71 | /// | |
72 | EfiTlsCompressionMethod, | |
73 | /// | |
74 | /// TLS session extension data. | |
75 | /// The corresponding Data is a list of type EFI_TLS_EXTENSION . | |
76 | /// | |
77 | EfiTlsExtensionData, | |
78 | /// | |
79 | /// TLS session verify method. | |
80 | /// The corresponding Data is of type EFI_TLS_VERIFY. | |
81 | /// | |
82 | EfiTlsVerifyMethod, | |
83 | /// | |
84 | /// TLS session data session ID. | |
85 | /// For SetSessionData(), it is TLS session ID used for session resumption. | |
86 | /// For GetSessionData(), it is the TLS session ID used for current session. | |
87 | /// The corresponding Data is of type EFI_TLS_SESSION_ID. | |
88 | /// | |
89 | EfiTlsSessionID, | |
90 | /// | |
91 | /// TLS session data session state. | |
92 | /// The corresponding Data is of type EFI_TLS_SESSION_STATE. | |
93 | /// | |
94 | EfiTlsSessionState, | |
95 | ||
96 | /// | |
97 | /// Session information | |
98 | /// | |
99 | ||
100 | /// | |
101 | /// TLS session data client random. | |
102 | /// The corresponding Data is of type EFI_TLS_RANDOM. | |
103 | /// | |
104 | EfiTlsClientRandom, | |
105 | /// | |
106 | /// TLS session data server random. | |
107 | /// The corresponding Data is of type EFI_TLS_RANDOM. | |
108 | /// | |
109 | EfiTlsServerRandom, | |
110 | /// | |
111 | /// TLS session data key material. | |
112 | /// The corresponding Data is of type EFI_TLS_MASTER_SECRET. | |
113 | /// | |
114 | EfiTlsKeyMaterial, | |
115 | ||
116 | EfiTlsSessionDataTypeMaximum | |
117 | ||
118 | } EFI_TLS_SESSION_DATA_TYPE; | |
119 | ||
120 | /// | |
121 | /// EFI_TLS_VERSION | |
122 | /// Note: The TLS version definition is from SSL3.0 to the latest TLS (e.g. 1.2). | |
123 | /// SSL2.0 is obsolete and should not be used. | |
124 | /// | |
125 | typedef struct { | |
126 | UINT8 Major; | |
127 | UINT8 Minor; | |
128 | } EFI_TLS_VERSION; | |
129 | ||
130 | /// | |
131 | /// EFI_TLS_CONNECTION_END to define TLS session as client or server. | |
132 | /// | |
133 | typedef enum { | |
134 | EfiTlsClient, | |
135 | EfiTlsServer, | |
136 | } EFI_TLS_CONNECTION_END; | |
137 | ||
138 | /// | |
139 | /// EFI_TLS_CIPHER | |
140 | /// Note: The definition of EFI_TLS_CIPHER definition is from "RFC 5246, A.4.1. | |
141 | /// Hello Messages". The value of EFI_TLS_CIPHER is from TLS Cipher | |
142 | /// Suite Registry of IANA. | |
143 | /// | |
144 | typedef struct { | |
145 | UINT8 Data1; | |
146 | UINT8 Data2; | |
147 | } EFI_TLS_CIPHER; | |
148 | ||
149 | /// | |
150 | /// EFI_TLS_COMPRESSION | |
151 | /// Note: The value of EFI_TLS_COMPRESSION definition is from "RFC 3749". | |
152 | /// | |
153 | typedef UINT8 EFI_TLS_COMPRESSION; | |
154 | ||
155 | /// | |
156 | /// EFI_TLS_EXTENSION | |
157 | /// Note: The definition of EFI_TLS_EXTENSION if from "RFC 5246 A.4.1. | |
158 | /// Hello Messages". | |
159 | /// | |
160 | typedef struct { | |
161 | UINT16 ExtensionType; | |
162 | UINT16 Length; | |
163 | UINT8 Data[1]; | |
164 | } EFI_TLS_EXTENSION; | |
165 | ||
166 | /// | |
167 | /// EFI_TLS_VERIFY | |
168 | /// Use either EFI_TLS_VERIFY_NONE or EFI_TLS_VERIFY_PEER, the last two options | |
169 | /// are 'ORed' with EFI_TLS_VERIFY_PEER if they are desired. | |
170 | /// | |
171 | typedef UINT32 EFI_TLS_VERIFY; | |
172 | /// | |
173 | /// No certificates will be sent or the TLS/SSL handshake will be continued regardless | |
174 | /// of the certificate verification result. | |
175 | /// | |
176 | #define EFI_TLS_VERIFY_NONE 0x0 | |
177 | /// | |
178 | /// The TLS/SSL handshake is immediately terminated with an alert message containing | |
179 | /// the reason for the certificate verification failure. | |
180 | /// | |
181 | #define EFI_TLS_VERIFY_PEER 0x1 | |
182 | /// | |
183 | /// TLS session will fail peer certificate is absent. | |
184 | /// | |
185 | #define EFI_TLS_VERIFY_FAIL_IF_NO_PEER_CERT 0x2 | |
186 | /// | |
187 | /// TLS session only verify client once, and doesn't request certificate during | |
188 | /// re-negotiation. | |
189 | /// | |
190 | #define EFI_TLS_VERIFY_CLIENT_ONCE 0x4 | |
191 | ||
192 | /// | |
193 | /// EFI_TLS_RANDOM | |
194 | /// Note: The definition of EFI_TLS_RANDOM is from "RFC 5246 A.4.1. | |
195 | /// Hello Messages". | |
196 | /// | |
197 | typedef struct { | |
198 | UINT32 GmtUnixTime; | |
199 | UINT8 RandomBytes[28]; | |
200 | } EFI_TLS_RANDOM; | |
201 | ||
202 | /// | |
203 | /// EFI_TLS_MASTER_SECRET | |
204 | /// Note: The definition of EFI_TLS_MASTER_SECRET is from "RFC 5246 8.1. | |
205 | /// Computing the Master Secret". | |
206 | /// | |
207 | typedef struct { | |
208 | UINT8 Data[48]; | |
209 | } EFI_TLS_MASTER_SECRET; | |
210 | ||
211 | /// | |
212 | /// EFI_TLS_SESSION_ID | |
213 | /// Note: The definition of EFI_TLS_SESSION_ID is from "RFC 5246 A.4.1. Hello Messages". | |
214 | /// | |
215 | #define MAX_TLS_SESSION_ID_LENGTH 32 | |
216 | typedef struct { | |
217 | UINT16 Length; | |
218 | UINT8 Data[MAX_TLS_SESSION_ID_LENGTH]; | |
219 | } EFI_TLS_SESSION_ID; | |
220 | ||
221 | /// | |
222 | /// EFI_TLS_SESSION_STATE | |
223 | /// | |
224 | typedef enum { | |
225 | /// | |
226 | /// When a new child of TLS protocol is created, the initial state of TLS session | |
227 | /// is EfiTlsSessionNotStarted. | |
228 | /// | |
229 | EfiTlsSessionNotStarted, | |
230 | /// | |
231 | /// The consumer can call BuildResponsePacket() with NULL to get ClientHello to | |
232 | /// start the TLS session. Then the status is EfiTlsSessionHandShaking. | |
233 | /// | |
234 | EfiTlsSessionHandShaking, | |
235 | /// | |
236 | /// During handshake, the consumer need call BuildResponsePacket() with input | |
237 | /// data from peer, then get response packet and send to peer. After handshake | |
238 | /// finish, the TLS session status becomes EfiTlsSessionDataTransferring, and | |
239 | /// consumer can use ProcessPacket() for data transferring. | |
240 | /// | |
241 | EfiTlsSessionDataTransferring, | |
242 | /// | |
243 | /// Finally, if consumer wants to active close TLS session, consumer need | |
244 | /// call SetSessionData to set TLS session state to EfiTlsSessionClosing, and | |
245 | /// call BuildResponsePacket() with NULL to get CloseNotify alert message, | |
246 | /// and sent it out. | |
247 | /// | |
248 | EfiTlsSessionClosing, | |
249 | /// | |
250 | /// If any error happen during parsing ApplicationData content type, EFI_ABORT | |
251 | /// will be returned by ProcessPacket(), and TLS session state will become | |
252 | /// EfiTlsSessionError. Then consumer need call BuildResponsePacket() with | |
253 | /// NULL to get alert message and sent it out. | |
254 | /// | |
255 | EfiTlsSessionError, | |
256 | ||
257 | EfiTlsSessionStateMaximum | |
258 | ||
259 | } EFI_TLS_SESSION_STATE; | |
260 | ||
261 | /// | |
262 | /// EFI_TLS_FRAGMENT_DATA | |
263 | /// | |
264 | typedef struct { | |
265 | /// | |
266 | /// Length of data buffer in the fragment. | |
267 | /// | |
268 | UINT32 FragmentLength; | |
269 | /// | |
270 | /// Pointer to the data buffer in the fragment. | |
271 | /// | |
272 | VOID *FragmentBuffer; | |
273 | } EFI_TLS_FRAGMENT_DATA; | |
274 | ||
275 | /// | |
276 | /// EFI_TLS_CRYPT_MODE | |
277 | /// | |
278 | typedef enum { | |
279 | /// | |
280 | /// Encrypt data provided in the fragment buffers. | |
281 | /// | |
282 | EfiTlsEncrypt, | |
283 | /// | |
284 | /// Decrypt data provided in the fragment buffers. | |
285 | /// | |
286 | EfiTlsDecrypt, | |
287 | } EFI_TLS_CRYPT_MODE; | |
288 | ||
289 | /** | |
290 | Set TLS session data. | |
291 | ||
292 | The SetSessionData() function set data for a new TLS session. All session data should | |
293 | be set before BuildResponsePacket() invoked. | |
294 | ||
295 | @param[in] This Pointer to the EFI_TLS_PROTOCOL instance. | |
296 | @param[in] DataType TLS session data type. | |
297 | @param[in] Data Pointer to session data. | |
298 | @param[in] DataSize Total size of session data. | |
299 | ||
300 | @retval EFI_SUCCESS The TLS session data is set successfully. | |
301 | @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE: | |
302 | This is NULL. | |
303 | Data is NULL. | |
304 | DataSize is 0. | |
305 | @retval EFI_UNSUPPORTED The DataType is unsupported. | |
306 | @retval EFI_ACCESS_DENIED If the DataType is one of below: | |
307 | EfiTlsClientRandom | |
308 | EfiTlsServerRandom | |
309 | EfiTlsKeyMaterial | |
310 | @retval EFI_NOT_READY Current TLS session state is NOT | |
311 | EfiTlsSessionStateNotStarted. | |
312 | @retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated. | |
313 | **/ | |
314 | typedef | |
315 | EFI_STATUS | |
316 | (EFIAPI *EFI_TLS_SET_SESSION_DATA) ( | |
317 | IN EFI_TLS_PROTOCOL *This, | |
318 | IN EFI_TLS_SESSION_DATA_TYPE DataType, | |
319 | IN VOID *Data, | |
320 | IN UINTN DataSize | |
321 | ); | |
322 | ||
323 | /** | |
324 | Get TLS session data. | |
325 | ||
326 | The GetSessionData() function return the TLS session information. | |
327 | ||
328 | @param[in] This Pointer to the EFI_TLS_PROTOCOL instance. | |
329 | @param[in] DataType TLS session data type. | |
330 | @param[in, out] Data Pointer to session data. | |
331 | @param[in, out] DataSize Total size of session data. On input, it means | |
332 | the size of Data buffer. On output, it means the size | |
333 | of copied Data buffer if EFI_SUCCESS, and means the | |
334 | size of desired Data buffer if EFI_BUFFER_TOO_SMALL. | |
335 | ||
336 | @retval EFI_SUCCESS The TLS session data is got successfully. | |
337 | @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE: | |
338 | This is NULL. | |
339 | DataSize is NULL. | |
340 | Data is NULL if *DataSize is not zero. | |
341 | @retval EFI_UNSUPPORTED The DataType is unsupported. | |
342 | @retval EFI_NOT_FOUND The TLS session data is not found. | |
343 | @retval EFI_NOT_READY The DataType is not ready in current session state. | |
344 | @retval EFI_BUFFER_TOO_SMALL The buffer is too small to hold the data. | |
345 | **/ | |
346 | typedef | |
347 | EFI_STATUS | |
348 | (EFIAPI *EFI_TLS_GET_SESSION_DATA) ( | |
349 | IN EFI_TLS_PROTOCOL *This, | |
350 | IN EFI_TLS_SESSION_DATA_TYPE DataType, | |
351 | IN OUT VOID *Data, OPTIONAL | |
352 | IN OUT UINTN *DataSize | |
353 | ); | |
354 | ||
355 | /** | |
356 | Build response packet according to TLS state machine. This function is only valid for | |
357 | alert, handshake and change_cipher_spec content type. | |
358 | ||
359 | The BuildResponsePacket() function builds TLS response packet in response to the TLS | |
360 | request packet specified by RequestBuffer and RequestSize. If RequestBuffer is NULL and | |
361 | RequestSize is 0, and TLS session status is EfiTlsSessionNotStarted, the TLS session | |
362 | will be initiated and the response packet needs to be ClientHello. If RequestBuffer is | |
363 | NULL and RequestSize is 0, and TLS session status is EfiTlsSessionClosing, the TLS | |
364 | session will be closed and response packet needs to be CloseNotify. If RequestBuffer is | |
365 | NULL and RequestSize is 0, and TLS session status is EfiTlsSessionError, the TLS | |
366 | session has errors and the response packet needs to be Alert message based on error | |
367 | type. | |
368 | ||
369 | @param[in] This Pointer to the EFI_TLS_PROTOCOL instance. | |
370 | @param[in] RequestBuffer Pointer to the most recently received TLS packet. NULL | |
371 | means TLS need initiate the TLS session and response | |
372 | packet need to be ClientHello. | |
373 | @param[in] RequestSize Packet size in bytes for the most recently received TLS | |
374 | packet. 0 is only valid when RequestBuffer is NULL. | |
375 | @param[out] Buffer Pointer to the buffer to hold the built packet. | |
376 | @param[in, out] BufferSize Pointer to the buffer size in bytes. On input, it is | |
377 | the buffer size provided by the caller. On output, it | |
378 | is the buffer size in fact needed to contain the | |
379 | packet. | |
380 | ||
381 | @retval EFI_SUCCESS The required TLS packet is built successfully. | |
382 | @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE: | |
383 | This is NULL. | |
384 | RequestBuffer is NULL but RequestSize is NOT 0. | |
385 | RequestSize is 0 but RequestBuffer is NOT NULL. | |
386 | BufferSize is NULL. | |
387 | Buffer is NULL if *BufferSize is not zero. | |
388 | @retval EFI_BUFFER_TOO_SMALL BufferSize is too small to hold the response packet. | |
389 | @retval EFI_NOT_READY Current TLS session state is NOT ready to build | |
390 | ResponsePacket. | |
391 | @retval EFI_ABORTED Something wrong build response packet. | |
392 | **/ | |
393 | typedef | |
394 | EFI_STATUS | |
395 | (EFIAPI *EFI_TLS_BUILD_RESPONSE_PACKET) ( | |
396 | IN EFI_TLS_PROTOCOL *This, | |
397 | IN UINT8 *RequestBuffer, OPTIONAL | |
398 | IN UINTN RequestSize, OPTIONAL | |
399 | OUT UINT8 *Buffer, OPTIONAL | |
400 | IN OUT UINTN *BufferSize | |
401 | ); | |
402 | ||
403 | /** | |
404 | Decrypt or encrypt TLS packet during session. This function is only valid after | |
405 | session connected and for application_data content type. | |
406 | ||
407 | The ProcessPacket () function process each inbound or outbound TLS APP packet. | |
408 | ||
409 | @param[in] This Pointer to the EFI_TLS_PROTOCOL instance. | |
410 | @param[in, out] FragmentTable Pointer to a list of fragment. The caller will take | |
411 | responsible to handle the original FragmentTable while | |
412 | it may be reallocated in TLS driver. If CryptMode is | |
413 | EfiTlsEncrypt, on input these fragments contain the TLS | |
414 | header and plain text TLS APP payload; on output these | |
415 | fragments contain the TLS header and cipher text TLS | |
416 | APP payload. If CryptMode is EfiTlsDecrypt, on input | |
417 | these fragments contain the TLS header and cipher text | |
418 | TLS APP payload; on output these fragments contain the | |
419 | TLS header and plain text TLS APP payload. | |
420 | @param[in] FragmentCount Number of fragment. | |
421 | @param[in] CryptMode Crypt mode. | |
422 | ||
423 | @retval EFI_SUCCESS The operation completed successfully. | |
424 | @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE: | |
425 | This is NULL. | |
426 | FragmentTable is NULL. | |
427 | FragmentCount is NULL. | |
428 | CryptoMode is invalid. | |
429 | @retval EFI_NOT_READY Current TLS session state is NOT | |
430 | EfiTlsSessionDataTransferring. | |
431 | @retval EFI_ABORTED Something wrong decryption the message. TLS session | |
432 | status will become EfiTlsSessionError. The caller need | |
433 | call BuildResponsePacket() to generate Error Alert | |
434 | message and send it out. | |
435 | @retval EFI_OUT_OF_RESOURCES No enough resource to finish the operation. | |
436 | **/ | |
437 | typedef | |
438 | EFI_STATUS | |
439 | (EFIAPI *EFI_TLS_PROCESS_PACKET) ( | |
440 | IN EFI_TLS_PROTOCOL *This, | |
441 | IN OUT EFI_TLS_FRAGMENT_DATA **FragmentTable, | |
442 | IN UINT32 *FragmentCount, | |
443 | IN EFI_TLS_CRYPT_MODE CryptMode | |
444 | ); | |
445 | ||
446 | /// | |
447 | /// The EFI_TLS_PROTOCOL is used to create, destroy and manage TLS session. | |
448 | /// For detail of TLS, please refer to TLS related RFC. | |
449 | /// | |
450 | struct _EFI_TLS_PROTOCOL { | |
451 | EFI_TLS_SET_SESSION_DATA SetSessionData; | |
452 | EFI_TLS_GET_SESSION_DATA GetSessionData; | |
453 | EFI_TLS_BUILD_RESPONSE_PACKET BuildResponsePacket; | |
454 | EFI_TLS_PROCESS_PACKET ProcessPacket; | |
455 | }; | |
456 | ||
457 | extern EFI_GUID gEfiTlsServiceBindingProtocolGuid; | |
458 | extern EFI_GUID gEfiTlsProtocolGuid; | |
459 | ||
460 | #endif // __EFI_TLS_PROTOCOL_H__ |