CryptoPkg/Include/Library/TlsLib.h

   1 /** @file
   2   Defines TLS Library APIs.
   3
   4 Copyright (c) 2016 - 2017, Intel Corporation. All rights reserved.<BR>
   5 SPDX-License-Identifier: BSD-2-Clause-Patent
   6
   7 **/
   8
   9 #ifndef __TLS_LIB_H__
  10 #define __TLS_LIB_H__
  11
  12 /**
  13   Initializes the OpenSSL library.
  14
  15   This function registers ciphers and digests used directly and indirectly
  16   by SSL/TLS, and initializes the readable error messages.
  17   This function must be called before any other action takes places.
  18
  19   @retval TRUE   The OpenSSL library has been initialized.
  20   @retval FALSE  Failed to initialize the OpenSSL library.
  21
  22 **/
  23 BOOLEAN
  24 EFIAPI
  25 TlsInitialize (
  26   VOID
  27   );
  28
  29 /**
  30   Free an allocated SSL_CTX object.
  31
  32   @param[in]  TlsCtx    Pointer to the SSL_CTX object to be released.
  33
  34 **/
  35 VOID
  36 EFIAPI
  37 TlsCtxFree (
  38   IN   VOID                  *TlsCtx
  39   );
  40
  41 /**
  42   Creates a new SSL_CTX object as framework to establish TLS/SSL enabled
  43   connections.
  44
  45   @param[in]  MajorVer    Major Version of TLS/SSL Protocol.
  46   @param[in]  MinorVer    Minor Version of TLS/SSL Protocol.
  47
  48   @return  Pointer to an allocated SSL_CTX object.
  49            If the creation failed, TlsCtxNew() returns NULL.
  50
  51 **/
  52 VOID *
  53 EFIAPI
  54 TlsCtxNew (
  55   IN     UINT8                    MajorVer,
  56   IN     UINT8                    MinorVer
  57   );
  58
  59 /**
  60   Free an allocated TLS object.
  61
  62   This function removes the TLS object pointed to by Tls and frees up the
  63   allocated memory. If Tls is NULL, nothing is done.
  64
  65   @param[in]  Tls    Pointer to the TLS object to be freed.
  66
  67 **/
  68 VOID
  69 EFIAPI
  70 TlsFree (
  71   IN     VOID                     *Tls
  72   );
  73
  74 /**
  75   Create a new TLS object for a connection.
  76
  77   This function creates a new TLS object for a connection. The new object
  78   inherits the setting of the underlying context TlsCtx: connection method,
  79   options, verification setting.
  80
  81   @param[in]  TlsCtx    Pointer to the SSL_CTX object.
  82
  83   @return  Pointer to an allocated SSL object.
  84            If the creation failed, TlsNew() returns NULL.
  85
  86 **/
  87 VOID *
  88 EFIAPI
  89 TlsNew (
  90   IN     VOID                     *TlsCtx
  91   );
  92
  93 /**
  94   Checks if the TLS handshake was done.
  95
  96   This function will check if the specified TLS handshake was done.
  97
  98   @param[in]  Tls    Pointer to the TLS object for handshake state checking.
  99
 100   @retval  TRUE     The TLS handshake was done.
 101   @retval  FALSE    The TLS handshake was not done.
 102
 103 **/
 104 BOOLEAN
 105 EFIAPI
 106 TlsInHandshake (
 107   IN     VOID                     *Tls
 108   );
 109
 110 /**
 111   Perform a TLS/SSL handshake.
 112
 113   This function will perform a TLS/SSL handshake.
 114
 115   @param[in]       Tls            Pointer to the TLS object for handshake operation.
 116   @param[in]       BufferIn       Pointer to the most recently received TLS Handshake packet.
 117   @param[in]       BufferInSize   Packet size in bytes for the most recently received TLS
 118                                   Handshake packet.
 119   @param[out]      BufferOut      Pointer to the buffer to hold the built packet.
 120   @param[in, out]  BufferOutSize  Pointer to the buffer size in bytes. On input, it is
 121                                   the buffer size provided by the caller. On output, it
 122                                   is the buffer size in fact needed to contain the
 123                                   packet.
 124
 125   @retval EFI_SUCCESS             The required TLS packet is built successfully.
 126   @retval EFI_INVALID_PARAMETER   One or more of the following conditions is TRUE:
 127                                   Tls is NULL.
 128                                   BufferIn is NULL but BufferInSize is NOT 0.
 129                                   BufferInSize is 0 but BufferIn is NOT NULL.
 130                                   BufferOutSize is NULL.
 131                                   BufferOut is NULL if *BufferOutSize is not zero.
 132   @retval EFI_BUFFER_TOO_SMALL    BufferOutSize is too small to hold the response packet.
 133   @retval EFI_ABORTED             Something wrong during handshake.
 134
 135 **/
 136 EFI_STATUS
 137 EFIAPI
 138 TlsDoHandshake (
 139   IN     VOID                     *Tls,
 140   IN     UINT8                    *BufferIn  OPTIONAL,
 141   IN     UINTN                    BufferInSize  OPTIONAL,
 142      OUT UINT8                    *BufferOut  OPTIONAL,
 143   IN OUT UINTN                    *BufferOutSize
 144   );
 145
 146 /**
 147   Handle Alert message recorded in BufferIn. If BufferIn is NULL and BufferInSize is zero,
 148   TLS session has errors and the response packet needs to be Alert message based on error type.
 149
 150   @param[in]       Tls            Pointer to the TLS object for state checking.
 151   @param[in]       BufferIn       Pointer to the most recently received TLS Alert packet.
 152   @param[in]       BufferInSize   Packet size in bytes for the most recently received TLS
 153                                   Alert packet.
 154   @param[out]      BufferOut      Pointer to the buffer to hold the built packet.
 155   @param[in, out]  BufferOutSize  Pointer to the buffer size in bytes. On input, it is
 156                                   the buffer size provided by the caller. On output, it
 157                                   is the buffer size in fact needed to contain the
 158                                   packet.
 159
 160   @retval EFI_SUCCESS             The required TLS packet is built successfully.
 161   @retval EFI_INVALID_PARAMETER   One or more of the following conditions is TRUE:
 162                                   Tls is NULL.
 163                                   BufferIn is NULL but BufferInSize is NOT 0.
 164                                   BufferInSize is 0 but BufferIn is NOT NULL.
 165                                   BufferOutSize is NULL.
 166                                   BufferOut is NULL if *BufferOutSize is not zero.
 167   @retval EFI_ABORTED             An error occurred.
 168   @retval EFI_BUFFER_TOO_SMALL    BufferOutSize is too small to hold the response packet.
 169
 170 **/
 171 EFI_STATUS
 172 EFIAPI
 173 TlsHandleAlert (
 174   IN     VOID                     *Tls,
 175   IN     UINT8                    *BufferIn  OPTIONAL,
 176   IN     UINTN                    BufferInSize  OPTIONAL,
 177      OUT UINT8                    *BufferOut  OPTIONAL,
 178   IN OUT UINTN                    *BufferOutSize
 179   );
 180
 181 /**
 182   Build the CloseNotify packet.
 183
 184   @param[in]       Tls            Pointer to the TLS object for state checking.
 185   @param[in, out]  Buffer         Pointer to the buffer to hold the built packet.
 186   @param[in, out]  BufferSize     Pointer to the buffer size in bytes. On input, it is
 187                                   the buffer size provided by the caller. On output, it
 188                                   is the buffer size in fact needed to contain the
 189                                   packet.
 190
 191   @retval EFI_SUCCESS             The required TLS packet is built successfully.
 192   @retval EFI_INVALID_PARAMETER   One or more of the following conditions is TRUE:
 193                                   Tls is NULL.
 194                                   BufferSize is NULL.
 195                                   Buffer is NULL if *BufferSize is not zero.
 196   @retval EFI_BUFFER_TOO_SMALL    BufferSize is too small to hold the response packet.
 197
 198 **/
 199 EFI_STATUS
 200 EFIAPI
 201 TlsCloseNotify (
 202   IN     VOID                     *Tls,
 203   IN OUT UINT8                    *Buffer,
 204   IN OUT UINTN                    *BufferSize
 205   );
 206
 207 /**
 208   Attempts to read bytes from one TLS object and places the data in Buffer.
 209
 210   This function will attempt to read BufferSize bytes from the TLS object
 211   and places the data in Buffer.
 212
 213   @param[in]      Tls           Pointer to the TLS object.
 214   @param[in,out]  Buffer        Pointer to the buffer to store the data.
 215   @param[in]      BufferSize    The size of Buffer in bytes.
 216
 217   @retval  >0    The amount of data successfully read from the TLS object.
 218   @retval  <=0   No data was successfully read.
 219
 220 **/
 221 INTN
 222 EFIAPI
 223 TlsCtrlTrafficOut (
 224   IN     VOID                     *Tls,
 225   IN OUT VOID                     *Buffer,
 226   IN     UINTN                    BufferSize
 227   );
 228
 229 /**
 230   Attempts to write data from the buffer to TLS object.
 231
 232   This function will attempt to write BufferSize bytes data from the Buffer
 233   to the TLS object.
 234
 235   @param[in]  Tls           Pointer to the TLS object.
 236   @param[in]  Buffer        Pointer to the data buffer.
 237   @param[in]  BufferSize    The size of Buffer in bytes.
 238
 239   @retval  >0    The amount of data successfully written to the TLS object.
 240   @retval <=0    No data was successfully written.
 241
 242 **/
 243 INTN
 244 EFIAPI
 245 TlsCtrlTrafficIn (
 246   IN     VOID                     *Tls,
 247   IN     VOID                     *Buffer,
 248   IN     UINTN                    BufferSize
 249   );
 250
 251 /**
 252   Attempts to read bytes from the specified TLS connection into the buffer.
 253
 254   This function tries to read BufferSize bytes data from the specified TLS
 255   connection into the Buffer.
 256
 257   @param[in]      Tls           Pointer to the TLS connection for data reading.
 258   @param[in,out]  Buffer        Pointer to the data buffer.
 259   @param[in]      BufferSize    The size of Buffer in bytes.
 260
 261   @retval  >0    The read operation was successful, and return value is the
 262                  number of bytes actually read from the TLS connection.
 263   @retval  <=0   The read operation was not successful.
 264
 265 **/
 266 INTN
 267 EFIAPI
 268 TlsRead (
 269   IN     VOID                     *Tls,
 270   IN OUT VOID                     *Buffer,
 271   IN     UINTN                    BufferSize
 272   );
 273
 274 /**
 275   Attempts to write data to a TLS connection.
 276
 277   This function tries to write BufferSize bytes data from the Buffer into the
 278   specified TLS connection.
 279
 280   @param[in]  Tls           Pointer to the TLS connection for data writing.
 281   @param[in]  Buffer        Pointer to the data buffer.
 282   @param[in]  BufferSize    The size of Buffer in bytes.
 283
 284   @retval  >0    The write operation was successful, and return value is the
 285                  number of bytes actually written to the TLS connection.
 286   @retval <=0    The write operation was not successful.
 287
 288 **/
 289 INTN
 290 EFIAPI
 291 TlsWrite (
 292   IN     VOID                     *Tls,
 293   IN     VOID                     *Buffer,
 294   IN     UINTN                    BufferSize
 295   );
 296
 297 /**
 298   Set a new TLS/SSL method for a particular TLS object.
 299
 300   This function sets a new TLS/SSL method for a particular TLS object.
 301
 302   @param[in]  Tls         Pointer to a TLS object.
 303   @param[in]  MajorVer    Major Version of TLS/SSL Protocol.
 304   @param[in]  MinorVer    Minor Version of TLS/SSL Protocol.
 305
 306   @retval  EFI_SUCCESS           The TLS/SSL method was set successfully.
 307   @retval  EFI_INVALID_PARAMETER The parameter is invalid.
 308   @retval  EFI_UNSUPPORTED       Unsupported TLS/SSL method.
 309
 310 **/
 311 EFI_STATUS
 312 EFIAPI
 313 TlsSetVersion (
 314   IN     VOID                     *Tls,
 315   IN     UINT8                    MajorVer,
 316   IN     UINT8                    MinorVer
 317   );
 318
 319 /**
 320   Set TLS object to work in client or server mode.
 321
 322   This function prepares a TLS object to work in client or server mode.
 323
 324   @param[in]  Tls         Pointer to a TLS object.
 325   @param[in]  IsServer    Work in server mode.
 326
 327   @retval  EFI_SUCCESS           The TLS/SSL work mode was set successfully.
 328   @retval  EFI_INVALID_PARAMETER The parameter is invalid.
 329   @retval  EFI_UNSUPPORTED       Unsupported TLS/SSL work mode.
 330
 331 **/
 332 EFI_STATUS
 333 EFIAPI
 334 TlsSetConnectionEnd (
 335   IN     VOID                     *Tls,
 336   IN     BOOLEAN                  IsServer
 337   );
 338
 339 /**
 340   Set the ciphers list to be used by the TLS object.
 341
 342   This function sets the ciphers for use by a specified TLS object.
 343
 344   @param[in]  Tls          Pointer to a TLS object.
 345   @param[in]  CipherId     Array of UINT16 cipher identifiers. Each UINT16
 346                            cipher identifier comes from the TLS Cipher Suite
 347                            Registry of the IANA, interpreting Byte1 and Byte2
 348                            in network (big endian) byte order.
 349   @param[in]  CipherNum    The number of cipher in the list.
 350
 351   @retval  EFI_SUCCESS           The ciphers list was set successfully.
 352   @retval  EFI_INVALID_PARAMETER The parameter is invalid.
 353   @retval  EFI_UNSUPPORTED       No supported TLS cipher was found in CipherId.
 354   @retval  EFI_OUT_OF_RESOURCES  Memory allocation failed.
 355
 356 **/
 357 EFI_STATUS
 358 EFIAPI
 359 TlsSetCipherList (
 360   IN     VOID                     *Tls,
 361   IN     UINT16                   *CipherId,
 362   IN     UINTN                    CipherNum
 363   );
 364
 365 /**
 366   Set the compression method for TLS/SSL operations.
 367
 368   This function handles TLS/SSL integrated compression methods.
 369
 370   @param[in]  CompMethod    The compression method ID.
 371
 372   @retval  EFI_SUCCESS        The compression method for the communication was
 373                               set successfully.
 374   @retval  EFI_UNSUPPORTED    Unsupported compression method.
 375
 376 **/
 377 EFI_STATUS
 378 EFIAPI
 379 TlsSetCompressionMethod (
 380   IN     UINT8                    CompMethod
 381   );
 382
 383 /**
 384   Set peer certificate verification mode for the TLS connection.
 385
 386   This function sets the verification mode flags for the TLS connection.
 387
 388   @param[in]  Tls           Pointer to the TLS object.
 389   @param[in]  VerifyMode    A set of logically or'ed verification mode flags.
 390
 391 **/
 392 VOID
 393 EFIAPI
 394 TlsSetVerify (
 395   IN     VOID                     *Tls,
 396   IN     UINT32                   VerifyMode
 397   );
 398
 399 /**
 400   Set the specified host name to be verified.
 401
 402   @param[in]  Tls           Pointer to the TLS object.
 403   @param[in]  Flags         The setting flags during the validation.
 404   @param[in]  HostName      The specified host name to be verified.
 405
 406   @retval  EFI_SUCCESS           The HostName setting was set successfully.
 407   @retval  EFI_INVALID_PARAMETER The parameter is invalid.
 408   @retval  EFI_ABORTED           Invalid HostName setting.
 409
 410 **/
 411 EFI_STATUS
 412 EFIAPI
 413 TlsSetVerifyHost (
 414   IN     VOID                     *Tls,
 415   IN     UINT32                   Flags,
 416   IN     CHAR8                    *HostName
 417   );
 418
 419 /**
 420   Sets a TLS/SSL session ID to be used during TLS/SSL connect.
 421
 422   This function sets a session ID to be used when the TLS/SSL connection is
 423   to be established.
 424
 425   @param[in]  Tls             Pointer to the TLS object.
 426   @param[in]  SessionId       Session ID data used for session resumption.
 427   @param[in]  SessionIdLen    Length of Session ID in bytes.
 428
 429   @retval  EFI_SUCCESS           Session ID was set successfully.
 430   @retval  EFI_INVALID_PARAMETER The parameter is invalid.
 431   @retval  EFI_UNSUPPORTED       No available session for ID setting.
 432
 433 **/
 434 EFI_STATUS
 435 EFIAPI
 436 TlsSetSessionId (
 437   IN     VOID                     *Tls,
 438   IN     UINT8                    *SessionId,
 439   IN     UINT16                   SessionIdLen
 440   );
 441
 442 /**
 443   Adds the CA to the cert store when requesting Server or Client authentication.
 444
 445   This function adds the CA certificate to the list of CAs when requesting
 446   Server or Client authentication for the chosen TLS connection.
 447
 448   @param[in]  Tls         Pointer to the TLS object.
 449   @param[in]  Data        Pointer to the data buffer of a DER-encoded binary
 450                           X.509 certificate or PEM-encoded X.509 certificate.
 451   @param[in]  DataSize    The size of data buffer in bytes.
 452
 453   @retval  EFI_SUCCESS             The operation succeeded.
 454   @retval  EFI_INVALID_PARAMETER   The parameter is invalid.
 455   @retval  EFI_OUT_OF_RESOURCES    Required resources could not be allocated.
 456   @retval  EFI_ABORTED             Invalid X.509 certificate.
 457
 458 **/
 459 EFI_STATUS
 460 EFIAPI
 461 TlsSetCaCertificate (
 462   IN     VOID                     *Tls,
 463   IN     VOID                     *Data,
 464   IN     UINTN                    DataSize
 465   );
 466
 467 /**
 468   Loads the local public certificate into the specified TLS object.
 469
 470   This function loads the X.509 certificate into the specified TLS object
 471   for TLS negotiation.
 472
 473   @param[in]  Tls         Pointer to the TLS object.
 474   @param[in]  Data        Pointer to the data buffer of a DER-encoded binary
 475                           X.509 certificate or PEM-encoded X.509 certificate.
 476   @param[in]  DataSize    The size of data buffer in bytes.
 477
 478   @retval  EFI_SUCCESS             The operation succeeded.
 479   @retval  EFI_INVALID_PARAMETER   The parameter is invalid.
 480   @retval  EFI_OUT_OF_RESOURCES    Required resources could not be allocated.
 481   @retval  EFI_ABORTED             Invalid X.509 certificate.
 482
 483 **/
 484 EFI_STATUS
 485 EFIAPI
 486 TlsSetHostPublicCert (
 487   IN     VOID                     *Tls,
 488   IN     VOID                     *Data,
 489   IN     UINTN                    DataSize
 490   );
 491
 492 /**
 493   Adds the local private key to the specified TLS object.
 494
 495   This function adds the local private key (PEM-encoded RSA or PKCS#8 private
 496   key) into the specified TLS object for TLS negotiation.
 497
 498   @param[in]  Tls         Pointer to the TLS object.
 499   @param[in]  Data        Pointer to the data buffer of a PEM-encoded RSA
 500                           or PKCS#8 private key.
 501   @param[in]  DataSize    The size of data buffer in bytes.
 502
 503   @retval  EFI_SUCCESS     The operation succeeded.
 504   @retval  EFI_UNSUPPORTED This function is not supported.
 505   @retval  EFI_ABORTED     Invalid private key data.
 506
 507 **/
 508 EFI_STATUS
 509 EFIAPI
 510 TlsSetHostPrivateKey (
 511   IN     VOID                     *Tls,
 512   IN     VOID                     *Data,
 513   IN     UINTN                    DataSize
 514   );
 515
 516 /**
 517   Adds the CA-supplied certificate revocation list for certificate validation.
 518
 519   This function adds the CA-supplied certificate revocation list data for
 520   certificate validity checking.
 521
 522   @param[in]  Data        Pointer to the data buffer of a DER-encoded CRL data.
 523   @param[in]  DataSize    The size of data buffer in bytes.
 524
 525   @retval  EFI_SUCCESS     The operation succeeded.
 526   @retval  EFI_UNSUPPORTED This function is not supported.
 527   @retval  EFI_ABORTED     Invalid CRL data.
 528
 529 **/
 530 EFI_STATUS
 531 EFIAPI
 532 TlsSetCertRevocationList (
 533   IN     VOID                     *Data,
 534   IN     UINTN                    DataSize
 535   );
 536
 537 /**
 538   Gets the protocol version used by the specified TLS connection.
 539
 540   This function returns the protocol version used by the specified TLS
 541   connection.
 542
 543   If Tls is NULL, then ASSERT().
 544
 545   @param[in]  Tls    Pointer to the TLS object.
 546
 547   @return  The protocol version of the specified TLS connection.
 548
 549 **/
 550 UINT16
 551 EFIAPI
 552 TlsGetVersion (
 553   IN     VOID                     *Tls
 554   );
 555
 556 /**
 557   Gets the connection end of the specified TLS connection.
 558
 559   This function returns the connection end (as client or as server) used by
 560   the specified TLS connection.
 561
 562   If Tls is NULL, then ASSERT().
 563
 564   @param[in]  Tls    Pointer to the TLS object.
 565
 566   @return  The connection end used by the specified TLS connection.
 567
 568 **/
 569 UINT8
 570 EFIAPI
 571 TlsGetConnectionEnd (
 572   IN     VOID                     *Tls
 573   );
 574
 575 /**
 576   Gets the cipher suite used by the specified TLS connection.
 577
 578   This function returns current cipher suite used by the specified
 579   TLS connection.
 580
 581   @param[in]      Tls         Pointer to the TLS object.
 582   @param[in,out]  CipherId    The cipher suite used by the TLS object.
 583
 584   @retval  EFI_SUCCESS           The cipher suite was returned successfully.
 585   @retval  EFI_INVALID_PARAMETER The parameter is invalid.
 586   @retval  EFI_UNSUPPORTED       Unsupported cipher suite.
 587
 588 **/
 589 EFI_STATUS
 590 EFIAPI
 591 TlsGetCurrentCipher (
 592   IN     VOID                     *Tls,
 593   IN OUT UINT16                   *CipherId
 594   );
 595
 596 /**
 597   Gets the compression methods used by the specified TLS connection.
 598
 599   This function returns current integrated compression methods used by
 600   the specified TLS connection.
 601
 602   @param[in]      Tls              Pointer to the TLS object.
 603   @param[in,out]  CompressionId    The current compression method used by
 604                                    the TLS object.
 605
 606   @retval  EFI_SUCCESS           The compression method was returned successfully.
 607   @retval  EFI_INVALID_PARAMETER The parameter is invalid.
 608   @retval  EFI_ABORTED           Invalid Compression method.
 609   @retval  EFI_UNSUPPORTED       This function is not supported.
 610
 611 **/
 612 EFI_STATUS
 613 EFIAPI
 614 TlsGetCurrentCompressionId (
 615   IN     VOID                     *Tls,
 616   IN OUT UINT8                    *CompressionId
 617   );
 618
 619 /**
 620   Gets the verification mode currently set in the TLS connection.
 621
 622   This function returns the peer verification mode currently set in the
 623   specified TLS connection.
 624
 625   If Tls is NULL, then ASSERT().
 626
 627   @param[in]  Tls    Pointer to the TLS object.
 628
 629   @return  The verification mode set in the specified TLS connection.
 630
 631 **/
 632 UINT32
 633 EFIAPI
 634 TlsGetVerify (
 635   IN     VOID                     *Tls
 636   );
 637
 638 /**
 639   Gets the session ID used by the specified TLS connection.
 640
 641   This function returns the TLS/SSL session ID currently used by the
 642   specified TLS connection.
 643
 644   @param[in]      Tls             Pointer to the TLS object.
 645   @param[in,out]  SessionId       Buffer to contain the returned session ID.
 646   @param[in,out]  SessionIdLen    The length of Session ID in bytes.
 647
 648   @retval  EFI_SUCCESS           The Session ID was returned successfully.
 649   @retval  EFI_INVALID_PARAMETER The parameter is invalid.
 650   @retval  EFI_UNSUPPORTED       Invalid TLS/SSL session.
 651
 652 **/
 653 EFI_STATUS
 654 EFIAPI
 655 TlsGetSessionId (
 656   IN     VOID                     *Tls,
 657   IN OUT UINT8                    *SessionId,
 658   IN OUT UINT16                   *SessionIdLen
 659   );
 660
 661 /**
 662   Gets the client random data used in the specified TLS connection.
 663
 664   This function returns the TLS/SSL client random data currently used in
 665   the specified TLS connection.
 666
 667   @param[in]      Tls             Pointer to the TLS object.
 668   @param[in,out]  ClientRandom    Buffer to contain the returned client
 669                                   random data (32 bytes).
 670
 671 **/
 672 VOID
 673 EFIAPI
 674 TlsGetClientRandom (
 675   IN     VOID                     *Tls,
 676   IN OUT UINT8                    *ClientRandom
 677   );
 678
 679 /**
 680   Gets the server random data used in the specified TLS connection.
 681
 682   This function returns the TLS/SSL server random data currently used in
 683   the specified TLS connection.
 684
 685   @param[in]      Tls             Pointer to the TLS object.
 686   @param[in,out]  ServerRandom    Buffer to contain the returned server
 687                                   random data (32 bytes).
 688
 689 **/
 690 VOID
 691 EFIAPI
 692 TlsGetServerRandom (
 693   IN     VOID                     *Tls,
 694   IN OUT UINT8                    *ServerRandom
 695   );
 696
 697 /**
 698   Gets the master key data used in the specified TLS connection.
 699
 700   This function returns the TLS/SSL master key material currently used in
 701   the specified TLS connection.
 702
 703   @param[in]      Tls            Pointer to the TLS object.
 704   @param[in,out]  KeyMaterial    Buffer to contain the returned key material.
 705
 706   @retval  EFI_SUCCESS           Key material was returned successfully.
 707   @retval  EFI_INVALID_PARAMETER The parameter is invalid.
 708   @retval  EFI_UNSUPPORTED       Invalid TLS/SSL session.
 709
 710 **/
 711 EFI_STATUS
 712 EFIAPI
 713 TlsGetKeyMaterial (
 714   IN     VOID                     *Tls,
 715   IN OUT UINT8                    *KeyMaterial
 716   );
 717
 718 /**
 719   Gets the CA Certificate from the cert store.
 720
 721   This function returns the CA certificate for the chosen
 722   TLS connection.
 723
 724   @param[in]      Tls         Pointer to the TLS object.
 725   @param[out]     Data        Pointer to the data buffer to receive the CA
 726                               certificate data sent to the client.
 727   @param[in,out]  DataSize    The size of data buffer in bytes.
 728
 729   @retval  EFI_SUCCESS             The operation succeeded.
 730   @retval  EFI_UNSUPPORTED         This function is not supported.
 731   @retval  EFI_BUFFER_TOO_SMALL    The Data is too small to hold the data.
 732
 733 **/
 734 EFI_STATUS
 735 EFIAPI
 736 TlsGetCaCertificate (
 737   IN     VOID                     *Tls,
 738   OUT    VOID                     *Data,
 739   IN OUT UINTN                    *DataSize
 740   );
 741
 742 /**
 743   Gets the local public Certificate set in the specified TLS object.
 744
 745   This function returns the local public certificate which was currently set
 746   in the specified TLS object.
 747
 748   @param[in]      Tls         Pointer to the TLS object.
 749   @param[out]     Data        Pointer to the data buffer to receive the local
 750                               public certificate.
 751   @param[in,out]  DataSize    The size of data buffer in bytes.
 752
 753   @retval  EFI_SUCCESS             The operation succeeded.
 754   @retval  EFI_INVALID_PARAMETER   The parameter is invalid.
 755   @retval  EFI_NOT_FOUND           The certificate is not found.
 756   @retval  EFI_BUFFER_TOO_SMALL    The Data is too small to hold the data.
 757
 758 **/
 759 EFI_STATUS
 760 EFIAPI
 761 TlsGetHostPublicCert (
 762   IN     VOID                     *Tls,
 763   OUT    VOID                     *Data,
 764   IN OUT UINTN                    *DataSize
 765   );
 766
 767 /**
 768   Gets the local private key set in the specified TLS object.
 769
 770   This function returns the local private key data which was currently set
 771   in the specified TLS object.
 772
 773   @param[in]      Tls         Pointer to the TLS object.
 774   @param[out]     Data        Pointer to the data buffer to receive the local
 775                               private key data.
 776   @param[in,out]  DataSize    The size of data buffer in bytes.
 777
 778   @retval  EFI_SUCCESS             The operation succeeded.
 779   @retval  EFI_UNSUPPORTED         This function is not supported.
 780   @retval  EFI_BUFFER_TOO_SMALL    The Data is too small to hold the data.
 781
 782 **/
 783 EFI_STATUS
 784 EFIAPI
 785 TlsGetHostPrivateKey (
 786   IN     VOID                     *Tls,
 787   OUT    VOID                     *Data,
 788   IN OUT UINTN                    *DataSize
 789   );
 790
 791 /**
 792   Gets the CA-supplied certificate revocation list data set in the specified
 793   TLS object.
 794
 795   This function returns the CA-supplied certificate revocation list data which
 796   was currently set in the specified TLS object.
 797
 798   @param[out]     Data        Pointer to the data buffer to receive the CRL data.
 799   @param[in,out]  DataSize    The size of data buffer in bytes.
 800
 801   @retval  EFI_SUCCESS             The operation succeeded.
 802   @retval  EFI_UNSUPPORTED         This function is not supported.
 803   @retval  EFI_BUFFER_TOO_SMALL    The Data is too small to hold the data.
 804
 805 **/
 806 EFI_STATUS
 807 EFIAPI
 808 TlsGetCertRevocationList (
 809   OUT    VOID                     *Data,
 810   IN OUT UINTN                    *DataSize
 811   );
 812
 813 #endif // __TLS_LIB_H__