MdePkg/Include/Protocol/Tls.h: pack structures from the TLS RFC
[mirror_edk2.git] / MdePkg / Include / Protocol / Tls.h
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 #pragma pack (1)
145 typedef struct {
146 UINT8 Data1;
147 UINT8 Data2;
148 } EFI_TLS_CIPHER;
149 #pragma pack ()
150
151 ///
152 /// EFI_TLS_COMPRESSION
153 /// Note: The value of EFI_TLS_COMPRESSION definition is from "RFC 3749".
154 ///
155 typedef UINT8 EFI_TLS_COMPRESSION;
156
157 ///
158 /// EFI_TLS_EXTENSION
159 /// Note: The definition of EFI_TLS_EXTENSION if from "RFC 5246 A.4.1.
160 /// Hello Messages".
161 ///
162 #pragma pack (1)
163 typedef struct {
164 UINT16 ExtensionType;
165 UINT16 Length;
166 UINT8 Data[1];
167 } EFI_TLS_EXTENSION;
168 #pragma pack ()
169
170 ///
171 /// EFI_TLS_VERIFY
172 /// Use either EFI_TLS_VERIFY_NONE or EFI_TLS_VERIFY_PEER, the last two options
173 /// are 'ORed' with EFI_TLS_VERIFY_PEER if they are desired.
174 ///
175 typedef UINT32 EFI_TLS_VERIFY;
176 ///
177 /// No certificates will be sent or the TLS/SSL handshake will be continued regardless
178 /// of the certificate verification result.
179 ///
180 #define EFI_TLS_VERIFY_NONE 0x0
181 ///
182 /// The TLS/SSL handshake is immediately terminated with an alert message containing
183 /// the reason for the certificate verification failure.
184 ///
185 #define EFI_TLS_VERIFY_PEER 0x1
186 ///
187 /// TLS session will fail peer certificate is absent.
188 ///
189 #define EFI_TLS_VERIFY_FAIL_IF_NO_PEER_CERT 0x2
190 ///
191 /// TLS session only verify client once, and doesn't request certificate during
192 /// re-negotiation.
193 ///
194 #define EFI_TLS_VERIFY_CLIENT_ONCE 0x4
195
196 ///
197 /// EFI_TLS_RANDOM
198 /// Note: The definition of EFI_TLS_RANDOM is from "RFC 5246 A.4.1.
199 /// Hello Messages".
200 ///
201 #pragma pack (1)
202 typedef struct {
203 UINT32 GmtUnixTime;
204 UINT8 RandomBytes[28];
205 } EFI_TLS_RANDOM;
206 #pragma pack ()
207
208 ///
209 /// EFI_TLS_MASTER_SECRET
210 /// Note: The definition of EFI_TLS_MASTER_SECRET is from "RFC 5246 8.1.
211 /// Computing the Master Secret".
212 ///
213 #pragma pack (1)
214 typedef struct {
215 UINT8 Data[48];
216 } EFI_TLS_MASTER_SECRET;
217 #pragma pack ()
218
219 ///
220 /// EFI_TLS_SESSION_ID
221 /// Note: The definition of EFI_TLS_SESSION_ID is from "RFC 5246 A.4.1. Hello Messages".
222 ///
223 #define MAX_TLS_SESSION_ID_LENGTH 32
224 #pragma pack (1)
225 typedef struct {
226 UINT16 Length;
227 UINT8 Data[MAX_TLS_SESSION_ID_LENGTH];
228 } EFI_TLS_SESSION_ID;
229 #pragma pack ()
230
231 ///
232 /// EFI_TLS_SESSION_STATE
233 ///
234 typedef enum {
235 ///
236 /// When a new child of TLS protocol is created, the initial state of TLS session
237 /// is EfiTlsSessionNotStarted.
238 ///
239 EfiTlsSessionNotStarted,
240 ///
241 /// The consumer can call BuildResponsePacket() with NULL to get ClientHello to
242 /// start the TLS session. Then the status is EfiTlsSessionHandShaking.
243 ///
244 EfiTlsSessionHandShaking,
245 ///
246 /// During handshake, the consumer need call BuildResponsePacket() with input
247 /// data from peer, then get response packet and send to peer. After handshake
248 /// finish, the TLS session status becomes EfiTlsSessionDataTransferring, and
249 /// consumer can use ProcessPacket() for data transferring.
250 ///
251 EfiTlsSessionDataTransferring,
252 ///
253 /// Finally, if consumer wants to active close TLS session, consumer need
254 /// call SetSessionData to set TLS session state to EfiTlsSessionClosing, and
255 /// call BuildResponsePacket() with NULL to get CloseNotify alert message,
256 /// and sent it out.
257 ///
258 EfiTlsSessionClosing,
259 ///
260 /// If any error happen during parsing ApplicationData content type, EFI_ABORT
261 /// will be returned by ProcessPacket(), and TLS session state will become
262 /// EfiTlsSessionError. Then consumer need call BuildResponsePacket() with
263 /// NULL to get alert message and sent it out.
264 ///
265 EfiTlsSessionError,
266
267 EfiTlsSessionStateMaximum
268
269 } EFI_TLS_SESSION_STATE;
270
271 ///
272 /// EFI_TLS_FRAGMENT_DATA
273 ///
274 typedef struct {
275 ///
276 /// Length of data buffer in the fragment.
277 ///
278 UINT32 FragmentLength;
279 ///
280 /// Pointer to the data buffer in the fragment.
281 ///
282 VOID *FragmentBuffer;
283 } EFI_TLS_FRAGMENT_DATA;
284
285 ///
286 /// EFI_TLS_CRYPT_MODE
287 ///
288 typedef enum {
289 ///
290 /// Encrypt data provided in the fragment buffers.
291 ///
292 EfiTlsEncrypt,
293 ///
294 /// Decrypt data provided in the fragment buffers.
295 ///
296 EfiTlsDecrypt,
297 } EFI_TLS_CRYPT_MODE;
298
299 /**
300 Set TLS session data.
301
302 The SetSessionData() function set data for a new TLS session. All session data should
303 be set before BuildResponsePacket() invoked.
304
305 @param[in] This Pointer to the EFI_TLS_PROTOCOL instance.
306 @param[in] DataType TLS session data type.
307 @param[in] Data Pointer to session data.
308 @param[in] DataSize Total size of session data.
309
310 @retval EFI_SUCCESS The TLS session data is set successfully.
311 @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
312 This is NULL.
313 Data is NULL.
314 DataSize is 0.
315 @retval EFI_UNSUPPORTED The DataType is unsupported.
316 @retval EFI_ACCESS_DENIED If the DataType is one of below:
317 EfiTlsClientRandom
318 EfiTlsServerRandom
319 EfiTlsKeyMaterial
320 @retval EFI_NOT_READY Current TLS session state is NOT
321 EfiTlsSessionStateNotStarted.
322 @retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated.
323 **/
324 typedef
325 EFI_STATUS
326 (EFIAPI *EFI_TLS_SET_SESSION_DATA) (
327 IN EFI_TLS_PROTOCOL *This,
328 IN EFI_TLS_SESSION_DATA_TYPE DataType,
329 IN VOID *Data,
330 IN UINTN DataSize
331 );
332
333 /**
334 Get TLS session data.
335
336 The GetSessionData() function return the TLS session information.
337
338 @param[in] This Pointer to the EFI_TLS_PROTOCOL instance.
339 @param[in] DataType TLS session data type.
340 @param[in, out] Data Pointer to session data.
341 @param[in, out] DataSize Total size of session data. On input, it means
342 the size of Data buffer. On output, it means the size
343 of copied Data buffer if EFI_SUCCESS, and means the
344 size of desired Data buffer if EFI_BUFFER_TOO_SMALL.
345
346 @retval EFI_SUCCESS The TLS session data is got successfully.
347 @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
348 This is NULL.
349 DataSize is NULL.
350 Data is NULL if *DataSize is not zero.
351 @retval EFI_UNSUPPORTED The DataType is unsupported.
352 @retval EFI_NOT_FOUND The TLS session data is not found.
353 @retval EFI_NOT_READY The DataType is not ready in current session state.
354 @retval EFI_BUFFER_TOO_SMALL The buffer is too small to hold the data.
355 **/
356 typedef
357 EFI_STATUS
358 (EFIAPI *EFI_TLS_GET_SESSION_DATA) (
359 IN EFI_TLS_PROTOCOL *This,
360 IN EFI_TLS_SESSION_DATA_TYPE DataType,
361 IN OUT VOID *Data, OPTIONAL
362 IN OUT UINTN *DataSize
363 );
364
365 /**
366 Build response packet according to TLS state machine. This function is only valid for
367 alert, handshake and change_cipher_spec content type.
368
369 The BuildResponsePacket() function builds TLS response packet in response to the TLS
370 request packet specified by RequestBuffer and RequestSize. If RequestBuffer is NULL and
371 RequestSize is 0, and TLS session status is EfiTlsSessionNotStarted, the TLS session
372 will be initiated and the response packet needs to be ClientHello. If RequestBuffer is
373 NULL and RequestSize is 0, and TLS session status is EfiTlsSessionClosing, the TLS
374 session will be closed and response packet needs to be CloseNotify. If RequestBuffer is
375 NULL and RequestSize is 0, and TLS session status is EfiTlsSessionError, the TLS
376 session has errors and the response packet needs to be Alert message based on error
377 type.
378
379 @param[in] This Pointer to the EFI_TLS_PROTOCOL instance.
380 @param[in] RequestBuffer Pointer to the most recently received TLS packet. NULL
381 means TLS need initiate the TLS session and response
382 packet need to be ClientHello.
383 @param[in] RequestSize Packet size in bytes for the most recently received TLS
384 packet. 0 is only valid when RequestBuffer is NULL.
385 @param[out] Buffer Pointer to the buffer to hold the built packet.
386 @param[in, out] BufferSize Pointer to the buffer size in bytes. On input, it is
387 the buffer size provided by the caller. On output, it
388 is the buffer size in fact needed to contain the
389 packet.
390
391 @retval EFI_SUCCESS The required TLS packet is built successfully.
392 @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
393 This is NULL.
394 RequestBuffer is NULL but RequestSize is NOT 0.
395 RequestSize is 0 but RequestBuffer is NOT NULL.
396 BufferSize is NULL.
397 Buffer is NULL if *BufferSize is not zero.
398 @retval EFI_BUFFER_TOO_SMALL BufferSize is too small to hold the response packet.
399 @retval EFI_NOT_READY Current TLS session state is NOT ready to build
400 ResponsePacket.
401 @retval EFI_ABORTED Something wrong build response packet.
402 **/
403 typedef
404 EFI_STATUS
405 (EFIAPI *EFI_TLS_BUILD_RESPONSE_PACKET) (
406 IN EFI_TLS_PROTOCOL *This,
407 IN UINT8 *RequestBuffer, OPTIONAL
408 IN UINTN RequestSize, OPTIONAL
409 OUT UINT8 *Buffer, OPTIONAL
410 IN OUT UINTN *BufferSize
411 );
412
413 /**
414 Decrypt or encrypt TLS packet during session. This function is only valid after
415 session connected and for application_data content type.
416
417 The ProcessPacket () function process each inbound or outbound TLS APP packet.
418
419 @param[in] This Pointer to the EFI_TLS_PROTOCOL instance.
420 @param[in, out] FragmentTable Pointer to a list of fragment. The caller will take
421 responsible to handle the original FragmentTable while
422 it may be reallocated in TLS driver. If CryptMode is
423 EfiTlsEncrypt, on input these fragments contain the TLS
424 header and plain text TLS APP payload; on output these
425 fragments contain the TLS header and cipher text TLS
426 APP payload. If CryptMode is EfiTlsDecrypt, on input
427 these fragments contain the TLS header and cipher text
428 TLS APP payload; on output these fragments contain the
429 TLS header and plain text TLS APP payload.
430 @param[in] FragmentCount Number of fragment.
431 @param[in] CryptMode Crypt mode.
432
433 @retval EFI_SUCCESS The operation completed successfully.
434 @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
435 This is NULL.
436 FragmentTable is NULL.
437 FragmentCount is NULL.
438 CryptoMode is invalid.
439 @retval EFI_NOT_READY Current TLS session state is NOT
440 EfiTlsSessionDataTransferring.
441 @retval EFI_ABORTED Something wrong decryption the message. TLS session
442 status will become EfiTlsSessionError. The caller need
443 call BuildResponsePacket() to generate Error Alert
444 message and send it out.
445 @retval EFI_OUT_OF_RESOURCES No enough resource to finish the operation.
446 **/
447 typedef
448 EFI_STATUS
449 (EFIAPI *EFI_TLS_PROCESS_PACKET) (
450 IN EFI_TLS_PROTOCOL *This,
451 IN OUT EFI_TLS_FRAGMENT_DATA **FragmentTable,
452 IN UINT32 *FragmentCount,
453 IN EFI_TLS_CRYPT_MODE CryptMode
454 );
455
456 ///
457 /// The EFI_TLS_PROTOCOL is used to create, destroy and manage TLS session.
458 /// For detail of TLS, please refer to TLS related RFC.
459 ///
460 struct _EFI_TLS_PROTOCOL {
461 EFI_TLS_SET_SESSION_DATA SetSessionData;
462 EFI_TLS_GET_SESSION_DATA GetSessionData;
463 EFI_TLS_BUILD_RESPONSE_PACKET BuildResponsePacket;
464 EFI_TLS_PROCESS_PACKET ProcessPacket;
465 };
466
467 extern EFI_GUID gEfiTlsServiceBindingProtocolGuid;
468 extern EFI_GUID gEfiTlsProtocolGuid;
469
470 #endif // __EFI_TLS_PROTOCOL_H__
471