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   Shutdown a TLS connection.
 299
 300   Shutdown the TLS connection without releasing the resources, meaning a new
 301   connection can be started without calling TlsNew() and without setting
 302   certificates etc.
 303
 304   @param[in]       Tls            Pointer to the TLS object to shutdown.
 305
 306   @retval EFI_SUCCESS             The TLS is shutdown successfully.
 307   @retval EFI_INVALID_PARAMETER   Tls is NULL.
 308   @retval EFI_PROTOCOL_ERROR      Some other error occurred.
 309 **/
 310 EFI_STATUS
 311 EFIAPI
 312 TlsShutdown (
 313   IN     VOID  *Tls
 314   );
 315
 316 /**
 317   Set a new TLS/SSL method for a particular TLS object.
 318
 319   This function sets a new TLS/SSL method for a particular TLS object.
 320
 321   @param[in]  Tls         Pointer to a TLS object.
 322   @param[in]  MajorVer    Major Version of TLS/SSL Protocol.
 323   @param[in]  MinorVer    Minor Version of TLS/SSL Protocol.
 324
 325   @retval  EFI_SUCCESS           The TLS/SSL method was set successfully.
 326   @retval  EFI_INVALID_PARAMETER The parameter is invalid.
 327   @retval  EFI_UNSUPPORTED       Unsupported TLS/SSL method.
 328
 329 **/
 330 EFI_STATUS
 331 EFIAPI
 332 TlsSetVersion (
 333   IN     VOID   *Tls,
 334   IN     UINT8  MajorVer,
 335   IN     UINT8  MinorVer
 336   );
 337
 338 /**
 339   Set TLS object to work in client or server mode.
 340
 341   This function prepares a TLS object to work in client or server mode.
 342
 343   @param[in]  Tls         Pointer to a TLS object.
 344   @param[in]  IsServer    Work in server mode.
 345
 346   @retval  EFI_SUCCESS           The TLS/SSL work mode was set successfully.
 347   @retval  EFI_INVALID_PARAMETER The parameter is invalid.
 348   @retval  EFI_UNSUPPORTED       Unsupported TLS/SSL work mode.
 349
 350 **/
 351 EFI_STATUS
 352 EFIAPI
 353 TlsSetConnectionEnd (
 354   IN     VOID     *Tls,
 355   IN     BOOLEAN  IsServer
 356   );
 357
 358 /**
 359   Set the ciphers list to be used by the TLS object.
 360
 361   This function sets the ciphers for use by a specified TLS object.
 362
 363   @param[in]  Tls          Pointer to a TLS object.
 364   @param[in]  CipherId     Array of UINT16 cipher identifiers. Each UINT16
 365                            cipher identifier comes from the TLS Cipher Suite
 366                            Registry of the IANA, interpreting Byte1 and Byte2
 367                            in network (big endian) byte order.
 368   @param[in]  CipherNum    The number of cipher in the list.
 369
 370   @retval  EFI_SUCCESS           The ciphers list was set successfully.
 371   @retval  EFI_INVALID_PARAMETER The parameter is invalid.
 372   @retval  EFI_UNSUPPORTED       No supported TLS cipher was found in CipherId.
 373   @retval  EFI_OUT_OF_RESOURCES  Memory allocation failed.
 374
 375 **/
 376 EFI_STATUS
 377 EFIAPI
 378 TlsSetCipherList (
 379   IN     VOID    *Tls,
 380   IN     UINT16  *CipherId,
 381   IN     UINTN   CipherNum
 382   );
 383
 384 /**
 385   Set the compression method for TLS/SSL operations.
 386
 387   This function handles TLS/SSL integrated compression methods.
 388
 389   @param[in]  CompMethod    The compression method ID.
 390
 391   @retval  EFI_SUCCESS        The compression method for the communication was
 392                               set successfully.
 393   @retval  EFI_UNSUPPORTED    Unsupported compression method.
 394
 395 **/
 396 EFI_STATUS
 397 EFIAPI
 398 TlsSetCompressionMethod (
 399   IN     UINT8  CompMethod
 400   );
 401
 402 /**
 403   Set peer certificate verification mode for the TLS connection.
 404
 405   This function sets the verification mode flags for the TLS connection.
 406
 407   @param[in]  Tls           Pointer to the TLS object.
 408   @param[in]  VerifyMode    A set of logically or'ed verification mode flags.
 409
 410 **/
 411 VOID
 412 EFIAPI
 413 TlsSetVerify (
 414   IN     VOID    *Tls,
 415   IN     UINT32  VerifyMode
 416   );
 417
 418 /**
 419   Set the specified host name to be verified.
 420
 421   @param[in]  Tls           Pointer to the TLS object.
 422   @param[in]  Flags         The setting flags during the validation.
 423   @param[in]  HostName      The specified host name to be verified.
 424
 425   @retval  EFI_SUCCESS           The HostName setting was set successfully.
 426   @retval  EFI_INVALID_PARAMETER The parameter is invalid.
 427   @retval  EFI_ABORTED           Invalid HostName setting.
 428
 429 **/
 430 EFI_STATUS
 431 EFIAPI
 432 TlsSetVerifyHost (
 433   IN     VOID    *Tls,
 434   IN     UINT32  Flags,
 435   IN     CHAR8   *HostName
 436   );
 437
 438 /**
 439   Sets a TLS/SSL session ID to be used during TLS/SSL connect.
 440
 441   This function sets a session ID to be used when the TLS/SSL connection is
 442   to be established.
 443
 444   @param[in]  Tls             Pointer to the TLS object.
 445   @param[in]  SessionId       Session ID data used for session resumption.
 446   @param[in]  SessionIdLen    Length of Session ID in bytes.
 447
 448   @retval  EFI_SUCCESS           Session ID was set successfully.
 449   @retval  EFI_INVALID_PARAMETER The parameter is invalid.
 450   @retval  EFI_UNSUPPORTED       No available session for ID setting.
 451
 452 **/
 453 EFI_STATUS
 454 EFIAPI
 455 TlsSetSessionId (
 456   IN     VOID    *Tls,
 457   IN     UINT8   *SessionId,
 458   IN     UINT16  SessionIdLen
 459   );
 460
 461 /**
 462   Adds the CA to the cert store when requesting Server or Client authentication.
 463
 464   This function adds the CA certificate to the list of CAs when requesting
 465   Server or Client authentication for the chosen TLS connection.
 466
 467   @param[in]  Tls         Pointer to the TLS object.
 468   @param[in]  Data        Pointer to the data buffer of a DER-encoded binary
 469                           X.509 certificate or PEM-encoded X.509 certificate.
 470   @param[in]  DataSize    The size of data buffer in bytes.
 471
 472   @retval  EFI_SUCCESS             The operation succeeded.
 473   @retval  EFI_INVALID_PARAMETER   The parameter is invalid.
 474   @retval  EFI_OUT_OF_RESOURCES    Required resources could not be allocated.
 475   @retval  EFI_ABORTED             Invalid X.509 certificate.
 476
 477 **/
 478 EFI_STATUS
 479 EFIAPI
 480 TlsSetCaCertificate (
 481   IN     VOID   *Tls,
 482   IN     VOID   *Data,
 483   IN     UINTN  DataSize
 484   );
 485
 486 /**
 487   Loads the local public certificate into the specified TLS object.
 488
 489   This function loads the X.509 certificate into the specified TLS object
 490   for TLS negotiation.
 491
 492   @param[in]  Tls         Pointer to the TLS object.
 493   @param[in]  Data        Pointer to the data buffer of a DER-encoded binary
 494                           X.509 certificate or PEM-encoded X.509 certificate.
 495   @param[in]  DataSize    The size of data buffer in bytes.
 496
 497   @retval  EFI_SUCCESS             The operation succeeded.
 498   @retval  EFI_INVALID_PARAMETER   The parameter is invalid.
 499   @retval  EFI_OUT_OF_RESOURCES    Required resources could not be allocated.
 500   @retval  EFI_ABORTED             Invalid X.509 certificate.
 501
 502 **/
 503 EFI_STATUS
 504 EFIAPI
 505 TlsSetHostPublicCert (
 506   IN     VOID   *Tls,
 507   IN     VOID   *Data,
 508   IN     UINTN  DataSize
 509   );
 510
 511 /**
 512   Adds the local private key to the specified TLS object.
 513
 514   This function adds the local private key (DER-encoded or PEM-encoded or PKCS#8 private
 515   key) into the specified TLS object for TLS negotiation.
 516
 517   @param[in]  Tls         Pointer to the TLS object.
 518   @param[in]  Data        Pointer to the data buffer of a DER-encoded or PEM-encoded
 519                           or PKCS#8 private key.
 520   @param[in]  DataSize    The size of data buffer in bytes.
 521   @param[in]  Password    Pointer to NULL-terminated private key password, set it to NULL
 522                           if private key not encrypted.
 523
 524   @retval  EFI_SUCCESS     The operation succeeded.
 525   @retval  EFI_UNSUPPORTED This function is not supported.
 526   @retval  EFI_ABORTED     Invalid private key data.
 527
 528 **/
 529 EFI_STATUS
 530 EFIAPI
 531 TlsSetHostPrivateKeyEx (
 532   IN     VOID   *Tls,
 533   IN     VOID   *Data,
 534   IN     UINTN  DataSize,
 535   IN     VOID   *Password  OPTIONAL
 536   );
 537
 538 /**
 539   Adds the local private key to the specified TLS object.
 540
 541   This function adds the local private key (DER-encoded or PEM-encoded or PKCS#8 private
 542   key) into the specified TLS object for TLS negotiation.
 543
 544   @param[in]  Tls         Pointer to the TLS object.
 545   @param[in]  Data        Pointer to the data buffer of a DER-encoded or PEM-encoded
 546                           or PKCS#8 private key.
 547   @param[in]  DataSize    The size of data buffer in bytes.
 548
 549   @retval  EFI_SUCCESS     The operation succeeded.
 550   @retval  EFI_UNSUPPORTED This function is not supported.
 551   @retval  EFI_ABORTED     Invalid private key data.
 552
 553 **/
 554 EFI_STATUS
 555 EFIAPI
 556 TlsSetHostPrivateKey (
 557   IN     VOID   *Tls,
 558   IN     VOID   *Data,
 559   IN     UINTN  DataSize
 560   );
 561
 562 /**
 563   Adds the CA-supplied certificate revocation list for certificate validation.
 564
 565   This function adds the CA-supplied certificate revocation list data for
 566   certificate validity checking.
 567
 568   @param[in]  Data        Pointer to the data buffer of a DER-encoded CRL data.
 569   @param[in]  DataSize    The size of data buffer in bytes.
 570
 571   @retval  EFI_SUCCESS     The operation succeeded.
 572   @retval  EFI_UNSUPPORTED This function is not supported.
 573   @retval  EFI_ABORTED     Invalid CRL data.
 574
 575 **/
 576 EFI_STATUS
 577 EFIAPI
 578 TlsSetCertRevocationList (
 579   IN     VOID   *Data,
 580   IN     UINTN  DataSize
 581   );
 582
 583 /**
 584   Set the signature algorithm list to used by the TLS object.
 585
 586   This function sets the signature algorithms for use by a specified TLS object.
 587
 588   @param[in]  Tls                Pointer to a TLS object.
 589   @param[in]  Data               Array of UINT8 of signature algorithms. The array consists of
 590                                  pairs of the hash algorithm and the signature algorithm as defined
 591                                  in RFC 5246
 592   @param[in]  DataSize           The length the SignatureAlgoList. Must be divisible by 2.
 593
 594   @retval  EFI_SUCCESS           The signature algorithm list was set successfully.
 595   @retval  EFI_INVALID_PARAMETER The parameters are invalid.
 596   @retval  EFI_UNSUPPORTED       No supported TLS signature algorithm was found in SignatureAlgoList
 597   @retval  EFI_OUT_OF_RESOURCES  Memory allocation failed.
 598
 599 **/
 600 EFI_STATUS
 601 EFIAPI
 602 TlsSetSignatureAlgoList (
 603   IN     VOID   *Tls,
 604   IN     UINT8  *Data,
 605   IN     UINTN  DataSize
 606   );
 607
 608 /**
 609   Set the EC curve to be used for TLS flows
 610
 611   This function sets the EC curve to be used for TLS flows.
 612
 613   @param[in]  Tls                Pointer to a TLS object.
 614   @param[in]  Data               An EC named curve as defined in section 5.1.1 of RFC 4492.
 615   @param[in]  DataSize           Size of Data, it should be sizeof (UINT32)
 616
 617   @retval  EFI_SUCCESS           The EC curve was set successfully.
 618   @retval  EFI_INVALID_PARAMETER The parameters are invalid.
 619   @retval  EFI_UNSUPPORTED       The requested TLS EC curve is not supported
 620
 621 **/
 622 EFI_STATUS
 623 EFIAPI
 624 TlsSetEcCurve (
 625   IN     VOID   *Tls,
 626   IN     UINT8  *Data,
 627   IN     UINTN  DataSize
 628   );
 629
 630 /**
 631   Gets the protocol version used by the specified TLS connection.
 632
 633   This function returns the protocol version used by the specified TLS
 634   connection.
 635
 636   If Tls is NULL, then ASSERT().
 637
 638   @param[in]  Tls    Pointer to the TLS object.
 639
 640   @return  The protocol version of the specified TLS connection.
 641
 642 **/
 643 UINT16
 644 EFIAPI
 645 TlsGetVersion (
 646   IN     VOID  *Tls
 647   );
 648
 649 /**
 650   Gets the connection end of the specified TLS connection.
 651
 652   This function returns the connection end (as client or as server) used by
 653   the specified TLS connection.
 654
 655   If Tls is NULL, then ASSERT().
 656
 657   @param[in]  Tls    Pointer to the TLS object.
 658
 659   @return  The connection end used by the specified TLS connection.
 660
 661 **/
 662 UINT8
 663 EFIAPI
 664 TlsGetConnectionEnd (
 665   IN     VOID  *Tls
 666   );
 667
 668 /**
 669   Gets the cipher suite used by the specified TLS connection.
 670
 671   This function returns current cipher suite used by the specified
 672   TLS connection.
 673
 674   @param[in]      Tls         Pointer to the TLS object.
 675   @param[in,out]  CipherId    The cipher suite used by the TLS object.
 676
 677   @retval  EFI_SUCCESS           The cipher suite was returned successfully.
 678   @retval  EFI_INVALID_PARAMETER The parameter is invalid.
 679   @retval  EFI_UNSUPPORTED       Unsupported cipher suite.
 680
 681 **/
 682 EFI_STATUS
 683 EFIAPI
 684 TlsGetCurrentCipher (
 685   IN     VOID    *Tls,
 686   IN OUT UINT16  *CipherId
 687   );
 688
 689 /**
 690   Gets the compression methods used by the specified TLS connection.
 691
 692   This function returns current integrated compression methods used by
 693   the specified TLS connection.
 694
 695   @param[in]      Tls              Pointer to the TLS object.
 696   @param[in,out]  CompressionId    The current compression method used by
 697                                    the TLS object.
 698
 699   @retval  EFI_SUCCESS           The compression method was returned successfully.
 700   @retval  EFI_INVALID_PARAMETER The parameter is invalid.
 701   @retval  EFI_ABORTED           Invalid Compression method.
 702   @retval  EFI_UNSUPPORTED       This function is not supported.
 703
 704 **/
 705 EFI_STATUS
 706 EFIAPI
 707 TlsGetCurrentCompressionId (
 708   IN     VOID   *Tls,
 709   IN OUT UINT8  *CompressionId
 710   );
 711
 712 /**
 713   Gets the verification mode currently set in the TLS connection.
 714
 715   This function returns the peer verification mode currently set in the
 716   specified TLS connection.
 717
 718   If Tls is NULL, then ASSERT().
 719
 720   @param[in]  Tls    Pointer to the TLS object.
 721
 722   @return  The verification mode set in the specified TLS connection.
 723
 724 **/
 725 UINT32
 726 EFIAPI
 727 TlsGetVerify (
 728   IN     VOID  *Tls
 729   );
 730
 731 /**
 732   Gets the session ID used by the specified TLS connection.
 733
 734   This function returns the TLS/SSL session ID currently used by the
 735   specified TLS connection.
 736
 737   @param[in]      Tls             Pointer to the TLS object.
 738   @param[in,out]  SessionId       Buffer to contain the returned session ID.
 739   @param[in,out]  SessionIdLen    The length of Session ID in bytes.
 740
 741   @retval  EFI_SUCCESS           The Session ID was returned successfully.
 742   @retval  EFI_INVALID_PARAMETER The parameter is invalid.
 743   @retval  EFI_UNSUPPORTED       Invalid TLS/SSL session.
 744
 745 **/
 746 EFI_STATUS
 747 EFIAPI
 748 TlsGetSessionId (
 749   IN     VOID    *Tls,
 750   IN OUT UINT8   *SessionId,
 751   IN OUT UINT16  *SessionIdLen
 752   );
 753
 754 /**
 755   Gets the client random data used in the specified TLS connection.
 756
 757   This function returns the TLS/SSL client random data currently used in
 758   the specified TLS connection.
 759
 760   @param[in]      Tls             Pointer to the TLS object.
 761   @param[in,out]  ClientRandom    Buffer to contain the returned client
 762                                   random data (32 bytes).
 763
 764 **/
 765 VOID
 766 EFIAPI
 767 TlsGetClientRandom (
 768   IN     VOID   *Tls,
 769   IN OUT UINT8  *ClientRandom
 770   );
 771
 772 /**
 773   Gets the server random data used in the specified TLS connection.
 774
 775   This function returns the TLS/SSL server random data currently used in
 776   the specified TLS connection.
 777
 778   @param[in]      Tls             Pointer to the TLS object.
 779   @param[in,out]  ServerRandom    Buffer to contain the returned server
 780                                   random data (32 bytes).
 781
 782 **/
 783 VOID
 784 EFIAPI
 785 TlsGetServerRandom (
 786   IN     VOID   *Tls,
 787   IN OUT UINT8  *ServerRandom
 788   );
 789
 790 /**
 791   Gets the master key data used in the specified TLS connection.
 792
 793   This function returns the TLS/SSL master key material currently used in
 794   the specified TLS connection.
 795
 796   @param[in]      Tls            Pointer to the TLS object.
 797   @param[in,out]  KeyMaterial    Buffer to contain the returned key material.
 798
 799   @retval  EFI_SUCCESS           Key material was returned successfully.
 800   @retval  EFI_INVALID_PARAMETER The parameter is invalid.
 801   @retval  EFI_UNSUPPORTED       Invalid TLS/SSL session.
 802
 803 **/
 804 EFI_STATUS
 805 EFIAPI
 806 TlsGetKeyMaterial (
 807   IN     VOID   *Tls,
 808   IN OUT UINT8  *KeyMaterial
 809   );
 810
 811 /**
 812   Gets the CA Certificate from the cert store.
 813
 814   This function returns the CA certificate for the chosen
 815   TLS connection.
 816
 817   @param[in]      Tls         Pointer to the TLS object.
 818   @param[out]     Data        Pointer to the data buffer to receive the CA
 819                               certificate data sent to the client.
 820   @param[in,out]  DataSize    The size of data buffer in bytes.
 821
 822   @retval  EFI_SUCCESS             The operation succeeded.
 823   @retval  EFI_UNSUPPORTED         This function is not supported.
 824   @retval  EFI_BUFFER_TOO_SMALL    The Data is too small to hold the data.
 825
 826 **/
 827 EFI_STATUS
 828 EFIAPI
 829 TlsGetCaCertificate (
 830   IN     VOID   *Tls,
 831   OUT    VOID   *Data,
 832   IN OUT UINTN  *DataSize
 833   );
 834
 835 /**
 836   Gets the local public Certificate set in the specified TLS object.
 837
 838   This function returns the local public certificate which was currently set
 839   in the specified TLS object.
 840
 841   @param[in]      Tls         Pointer to the TLS object.
 842   @param[out]     Data        Pointer to the data buffer to receive the local
 843                               public certificate.
 844   @param[in,out]  DataSize    The size of data buffer in bytes.
 845
 846   @retval  EFI_SUCCESS             The operation succeeded.
 847   @retval  EFI_INVALID_PARAMETER   The parameter is invalid.
 848   @retval  EFI_NOT_FOUND           The certificate is not found.
 849   @retval  EFI_BUFFER_TOO_SMALL    The Data is too small to hold the data.
 850
 851 **/
 852 EFI_STATUS
 853 EFIAPI
 854 TlsGetHostPublicCert (
 855   IN     VOID   *Tls,
 856   OUT    VOID   *Data,
 857   IN OUT UINTN  *DataSize
 858   );
 859
 860 /**
 861   Gets the local private key set in the specified TLS object.
 862
 863   This function returns the local private key data which was currently set
 864   in the specified TLS object.
 865
 866   @param[in]      Tls         Pointer to the TLS object.
 867   @param[out]     Data        Pointer to the data buffer to receive the local
 868                               private key data.
 869   @param[in,out]  DataSize    The size of data buffer in bytes.
 870
 871   @retval  EFI_SUCCESS             The operation succeeded.
 872   @retval  EFI_UNSUPPORTED         This function is not supported.
 873   @retval  EFI_BUFFER_TOO_SMALL    The Data is too small to hold the data.
 874
 875 **/
 876 EFI_STATUS
 877 EFIAPI
 878 TlsGetHostPrivateKey (
 879   IN     VOID   *Tls,
 880   OUT    VOID   *Data,
 881   IN OUT UINTN  *DataSize
 882   );
 883
 884 /**
 885   Gets the CA-supplied certificate revocation list data set in the specified
 886   TLS object.
 887
 888   This function returns the CA-supplied certificate revocation list data which
 889   was currently set in the specified TLS object.
 890
 891   @param[out]     Data        Pointer to the data buffer to receive the CRL data.
 892   @param[in,out]  DataSize    The size of data buffer in bytes.
 893
 894   @retval  EFI_SUCCESS             The operation succeeded.
 895   @retval  EFI_UNSUPPORTED         This function is not supported.
 896   @retval  EFI_BUFFER_TOO_SMALL    The Data is too small to hold the data.
 897
 898 **/
 899 EFI_STATUS
 900 EFIAPI
 901 TlsGetCertRevocationList (
 902   OUT    VOID   *Data,
 903   IN OUT UINTN  *DataSize
 904   );
 905
 906 /**
 907   Derive keying material from a TLS connection.
 908
 909   This function exports keying material using the mechanism described in RFC
 910   5705.
 911
 912   @param[in]      Tls          Pointer to the TLS object
 913   @param[in]      Label        Description of the key for the PRF function
 914   @param[in]      Context      Optional context
 915   @param[in]      ContextLen   The length of the context value in bytes
 916   @param[out]     KeyBuffer    Buffer to hold the output of the TLS-PRF
 917   @param[in]      KeyBufferLen The length of the KeyBuffer
 918
 919   @retval  EFI_SUCCESS             The operation succeeded.
 920   @retval  EFI_INVALID_PARAMETER   The TLS object is invalid.
 921   @retval  EFI_PROTOCOL_ERROR      Some other error occurred.
 922
 923 **/
 924 EFI_STATUS
 925 EFIAPI
 926 TlsGetExportKey (
 927   IN     VOID        *Tls,
 928   IN     CONST VOID  *Label,
 929   IN     CONST VOID  *Context,
 930   IN     UINTN       ContextLen,
 931   OUT    VOID        *KeyBuffer,
 932   IN     UINTN       KeyBufferLen
 933   );
 934
 935 #endif // __TLS_LIB_H__