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