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__ 461