NetworkPkg/HttpDxe/HttpProto.h

   1 /** @file
   2   The header files of miscellaneous routines for HttpDxe driver.
   3
   4 Copyright (c) 2015 - 2018, Intel Corporation. All rights reserved.<BR>
   5 (C) Copyright 2016 Hewlett Packard Enterprise Development LP<BR>
   6 This program and the accompanying materials
   7 are licensed and made available under the terms and conditions of the BSD License
   8 which accompanies this distribution.  The full text of the license may be found at
   9 http://opensource.org/licenses/bsd-license.php
  10
  11 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  12 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  13
  14 **/
  15
  16 #ifndef __EFI_HTTP_PROTO_H__
  17 #define __EFI_HTTP_PROTO_H__
  18
  19 #define DEF_BUF_LEN                         2048
  20
  21 #define HTTP_SERVICE_SIGNATURE  SIGNATURE_32('H', 't', 't', 'S')
  22
  23 #define HTTP_SERVICE_FROM_PROTOCOL(a) \
  24   CR ( \
  25   (a), \
  26   HTTP_SERVICE, \
  27   ServiceBinding, \
  28   HTTP_SERVICE_SIGNATURE \
  29   )
  30
  31
  32 //
  33 // The state of HTTP protocol. It starts from UNCONFIGED.
  34 //
  35 #define HTTP_STATE_UNCONFIGED        0
  36 #define HTTP_STATE_HTTP_CONFIGED     1
  37 #define HTTP_STATE_TCP_CONFIGED      2
  38 #define HTTP_STATE_TCP_UNCONFIGED    3
  39 #define HTTP_STATE_TCP_CONNECTED     4
  40 #define HTTP_STATE_TCP_CLOSED        5
  41
  42 //
  43 // TCP configured data.
  44 //
  45 #define HTTP_TOS_DEAULT              8
  46 #define HTTP_TTL_DEAULT              255
  47 #define HTTP_BUFFER_SIZE_DEAULT      65535
  48 #define HTTP_MAX_SYN_BACK_LOG        5
  49 #define HTTP_CONNECTION_TIMEOUT      60
  50 #define HTTP_RESPONSE_TIMEOUT        5
  51 #define HTTP_DATA_RETRIES            12
  52 #define HTTP_FIN_TIMEOUT             2
  53 #define HTTP_KEEP_ALIVE_PROBES       6
  54 #define HTTP_KEEP_ALIVE_TIME         7200
  55 #define HTTP_KEEP_ALIVE_INTERVAL     30
  56
  57 #define HTTP_URL_BUFFER_LEN          4096
  58
  59 typedef struct _HTTP_SERVICE {
  60   UINT32                        Signature;
  61   EFI_SERVICE_BINDING_PROTOCOL  ServiceBinding;
  62   EFI_HANDLE                    Ip4DriverBindingHandle;
  63   EFI_HANDLE                    Ip6DriverBindingHandle;
  64   EFI_HANDLE                    ControllerHandle;
  65   EFI_HANDLE                    Tcp4ChildHandle;
  66   EFI_HANDLE                    Tcp6ChildHandle;
  67   LIST_ENTRY                    ChildrenList;
  68   UINTN                         ChildrenNumber;
  69   INTN                          State;
  70 } HTTP_SERVICE;
  71
  72 typedef struct {
  73   EFI_TCP4_IO_TOKEN             Tx4Token;
  74   EFI_TCP4_TRANSMIT_DATA        Tx4Data;
  75   EFI_TCP6_IO_TOKEN             Tx6Token;
  76   EFI_TCP6_TRANSMIT_DATA        Tx6Data;
  77   EFI_TCP4_IO_TOKEN             Rx4Token;
  78   EFI_TCP4_RECEIVE_DATA         Rx4Data;
  79   EFI_TCP6_IO_TOKEN             Rx6Token;
  80   EFI_TCP6_RECEIVE_DATA         Rx6Data;
  81   BOOLEAN                       IsTxDone;
  82   BOOLEAN                       IsRxDone;
  83   UINTN                         BodyLen;
  84   EFI_HTTP_METHOD               Method;
  85 } HTTP_TCP_TOKEN_WRAP;
  86
  87 typedef struct {
  88   EFI_TLS_VERSION               Version;
  89   EFI_TLS_CONNECTION_END        ConnectionEnd;
  90   EFI_TLS_VERIFY                VerifyMethod;
  91   EFI_TLS_SESSION_STATE         SessionState;
  92 } TLS_CONFIG_DATA;
  93
  94 typedef struct _HTTP_PROTOCOL {
  95   UINT32                        Signature;
  96   EFI_HTTP_PROTOCOL             Http;
  97   EFI_HANDLE                    Handle;
  98   HTTP_SERVICE                  *Service;
  99   LIST_ENTRY                    Link;   // Link to all HTTP instance from the service.
 100   BOOLEAN                       InDestroy;
 101   INTN                          State;
 102   EFI_HTTP_METHOD               Method;
 103
 104   UINTN                         StatusCode;
 105
 106   EFI_EVENT                     TimeoutEvent;
 107
 108   EFI_HANDLE                    Tcp4ChildHandle;
 109   EFI_TCP4_PROTOCOL             *Tcp4;
 110   EFI_TCP4_CONFIG_DATA          Tcp4CfgData;
 111   EFI_TCP4_OPTION               Tcp4Option;
 112
 113   EFI_TCP4_CONNECTION_TOKEN     Tcp4ConnToken;
 114   BOOLEAN                       IsTcp4ConnDone;
 115   EFI_TCP4_CLOSE_TOKEN          Tcp4CloseToken;
 116   BOOLEAN                       IsTcp4CloseDone;
 117   CHAR8                         *RemoteHost;
 118   UINT16                        RemotePort;
 119   EFI_IPv4_ADDRESS              RemoteAddr;
 120
 121   EFI_HANDLE                    Tcp6ChildHandle;
 122   EFI_TCP6_PROTOCOL             *Tcp6;
 123   EFI_TCP6_CONFIG_DATA          Tcp6CfgData;
 124   EFI_TCP6_OPTION               Tcp6Option;
 125
 126   EFI_TCP6_CONNECTION_TOKEN     Tcp6ConnToken;
 127   BOOLEAN                       IsTcp6ConnDone;
 128   EFI_TCP6_CLOSE_TOKEN          Tcp6CloseToken;
 129   BOOLEAN                       IsTcp6CloseDone;
 130   EFI_IPv6_ADDRESS              RemoteIpv6Addr;
 131
 132   //
 133   // Rx4Token or Rx6Token used for receiving HTTP header.
 134   //
 135   EFI_TCP4_IO_TOKEN             Rx4Token;
 136   EFI_TCP4_RECEIVE_DATA         Rx4Data;
 137   EFI_TCP6_IO_TOKEN             Rx6Token;
 138   EFI_TCP6_RECEIVE_DATA         Rx6Data;
 139   BOOLEAN                       IsRxDone;
 140
 141   CHAR8                         **EndofHeader;
 142   CHAR8                         **HttpHeaders;
 143   CHAR8                         *CacheBody;
 144   CHAR8                         *NextMsg;
 145   UINTN                         CacheLen;
 146   UINTN                         CacheOffset;
 147
 148   //
 149   // HTTP message-body parser.
 150   //
 151   VOID                          *MsgParser;
 152
 153   EFI_HTTP_VERSION              HttpVersion;
 154   UINT32                        TimeOutMillisec;
 155   BOOLEAN                       LocalAddressIsIPv6;
 156
 157   EFI_HTTPv4_ACCESS_POINT       IPv4Node;
 158   EFI_HTTPv6_ACCESS_POINT       Ipv6Node;
 159
 160   NET_MAP                       TxTokens;
 161   NET_MAP                       RxTokens;
 162
 163   CHAR8                         *Url;
 164
 165   //
 166   // Https Support
 167   //
 168   BOOLEAN                          UseHttps;
 169
 170   EFI_SERVICE_BINDING_PROTOCOL     *TlsSb;
 171   EFI_HANDLE                       TlsChildHandle; /// Tls ChildHandle
 172   TLS_CONFIG_DATA                  TlsConfigData;
 173   EFI_TLS_PROTOCOL                 *Tls;
 174   EFI_TLS_CONFIGURATION_PROTOCOL   *TlsConfiguration;
 175   EFI_TLS_SESSION_STATE            TlsSessionState;
 176
 177   //
 178   // TlsTxData used for transmitting TLS related messages.
 179   //
 180   EFI_TCP4_IO_TOKEN                Tcp4TlsTxToken;
 181   EFI_TCP4_TRANSMIT_DATA           Tcp4TlsTxData;
 182   EFI_TCP6_IO_TOKEN                Tcp6TlsTxToken;
 183   EFI_TCP6_TRANSMIT_DATA           Tcp6TlsTxData;
 184   BOOLEAN                          TlsIsTxDone;
 185
 186   //
 187   // TlsRxData used for receiving TLS related messages.
 188   //
 189   EFI_TCP4_IO_TOKEN                Tcp4TlsRxToken;
 190   EFI_TCP4_RECEIVE_DATA            Tcp4TlsRxData;
 191   EFI_TCP6_IO_TOKEN                Tcp6TlsRxToken;
 192   EFI_TCP6_RECEIVE_DATA            Tcp6TlsRxData;
 193   BOOLEAN                          TlsIsRxDone;
 194 } HTTP_PROTOCOL;
 195
 196 typedef struct {
 197   EFI_HTTP_TOKEN                *HttpToken;
 198   HTTP_PROTOCOL                 *HttpInstance;
 199   HTTP_TCP_TOKEN_WRAP           TcpWrap;
 200 } HTTP_TOKEN_WRAP;
 201
 202
 203 #define HTTP_PROTOCOL_SIGNATURE  SIGNATURE_32('H', 't', 't', 'P')
 204
 205 #define HTTP_INSTANCE_FROM_PROTOCOL(a) \
 206   CR ( \
 207   (a), \
 208   HTTP_PROTOCOL, \
 209   Http, \
 210   HTTP_PROTOCOL_SIGNATURE \
 211   )
 212
 213 /**
 214   The common notify function used in HTTP driver.
 215
 216   @param[in]  Event   The event signaled.
 217   @param[in]  Context The context.
 218
 219 **/
 220 VOID
 221 EFIAPI
 222 HttpCommonNotify (
 223   IN EFI_EVENT  Event,
 224   IN VOID       *Context
 225   );
 226
 227 /**
 228   Create events for the TCP connection token and TCP close token.
 229
 230   @param[in]  HttpInstance       Pointer to HTTP_PROTOCOL structure.
 231
 232   @retval EFI_SUCCESS            The events are created successfully.
 233   @retval others                 Other error as indicated.
 234
 235 **/
 236 EFI_STATUS
 237 HttpCreateTcpConnCloseEvent (
 238   IN  HTTP_PROTOCOL        *HttpInstance
 239   );
 240
 241 /**
 242   Close events in the TCP connection token and TCP close token.
 243
 244   @param[in]  HttpInstance   Pointer to HTTP_PROTOCOL structure.
 245
 246 **/
 247 VOID
 248 HttpCloseTcpConnCloseEvent (
 249   IN  HTTP_PROTOCOL        *HttpInstance
 250   );
 251
 252 /**
 253   Create event for the TCP transmit token.
 254
 255   @param[in]  Wrap               Point to HTTP token's wrap data.
 256
 257   @retval EFI_SUCCESS            The events is created successfully.
 258   @retval others                 Other error as indicated.
 259
 260 **/
 261 EFI_STATUS
 262 HttpCreateTcpTxEvent (
 263   IN  HTTP_TOKEN_WRAP      *Wrap
 264   );
 265
 266 /**
 267   Create event for the TCP receive token which is used to receive HTTP header.
 268
 269   @param[in]  HttpInstance       Pointer to HTTP_PROTOCOL structure.
 270
 271   @retval EFI_SUCCESS            The events is created successfully.
 272   @retval others                 Other error as indicated.
 273
 274 **/
 275 EFI_STATUS
 276 HttpCreateTcpRxEventForHeader (
 277   IN  HTTP_PROTOCOL        *HttpInstance
 278   );
 279
 280 /**
 281   Create event for the TCP receive token which is used to receive HTTP body.
 282
 283   @param[in]  Wrap               Point to HTTP token's wrap data.
 284
 285   @retval EFI_SUCCESS            The events is created successfully.
 286   @retval others                 Other error as indicated.
 287
 288 **/
 289 EFI_STATUS
 290 HttpCreateTcpRxEvent (
 291   IN  HTTP_TOKEN_WRAP      *Wrap
 292   );
 293
 294 /**
 295   Close Events for Tcp Receive Tokens for HTTP body and HTTP header.
 296
 297   @param[in]  Wrap               Pointer to HTTP token's wrap data.
 298
 299 **/
 300 VOID
 301 HttpCloseTcpRxEvent (
 302   IN  HTTP_TOKEN_WRAP      *Wrap
 303   );
 304
 305 /**
 306   Intiialize the HTTP_PROTOCOL structure to the unconfigured state.
 307
 308   @param[in, out]  HttpInstance         Pointer to HTTP_PROTOCOL structure.
 309   @param[in]       IpVersion            Indicate us TCP4 protocol or TCP6 protocol.
 310
 311   @retval EFI_SUCCESS       HTTP_PROTOCOL structure is initialized successfully.
 312   @retval Others            Other error as indicated.
 313
 314 **/
 315 EFI_STATUS
 316 HttpInitProtocol (
 317   IN OUT HTTP_PROTOCOL           *HttpInstance,
 318   IN     BOOLEAN                 IpVersion
 319   );
 320
 321 /**
 322   Clean up the HTTP child, release all the resources used by it.
 323
 324   @param[in]  HttpInstance       The HTTP child to clean up.
 325
 326 **/
 327 VOID
 328 HttpCleanProtocol (
 329   IN  HTTP_PROTOCOL          *HttpInstance
 330   );
 331
 332 /**
 333   Establish TCP connection with HTTP server.
 334
 335   @param[in]  HttpInstance       The HTTP instance private data.
 336
 337   @retval EFI_SUCCESS            The TCP connection is established.
 338   @retval Others                 Other error as indicated.
 339
 340 **/
 341 EFI_STATUS
 342 HttpCreateConnection (
 343   IN  HTTP_PROTOCOL        *HttpInstance
 344   );
 345
 346 /**
 347   Close existing TCP connection.
 348
 349   @param[in]  HttpInstance       The HTTP instance private data.
 350
 351   @retval EFI_SUCCESS            The TCP connection is closed.
 352   @retval Others                 Other error as indicated.
 353
 354 **/
 355 EFI_STATUS
 356 HttpCloseConnection (
 357   IN  HTTP_PROTOCOL        *HttpInstance
 358   );
 359
 360 /**
 361   Configure TCP4 protocol child.
 362
 363   @param[in]  HttpInstance       The HTTP instance private data.
 364   @param[in]  Wrap               The HTTP token's wrap data.
 365
 366   @retval EFI_SUCCESS            The TCP4 protocol child is configured.
 367   @retval Others                 Other error as indicated.
 368
 369 **/
 370 EFI_STATUS
 371 HttpConfigureTcp4 (
 372   IN  HTTP_PROTOCOL        *HttpInstance,
 373   IN  HTTP_TOKEN_WRAP      *Wrap
 374   );
 375
 376 /**
 377   Configure TCP6 protocol child.
 378
 379   @param[in]  HttpInstance       The HTTP instance private data.
 380   @param[in]  Wrap               The HTTP token's wrap data.
 381
 382   @retval EFI_SUCCESS            The TCP6 protocol child is configured.
 383   @retval Others                 Other error as indicated.
 384
 385 **/
 386 EFI_STATUS
 387 HttpConfigureTcp6 (
 388   IN  HTTP_PROTOCOL        *HttpInstance,
 389   IN  HTTP_TOKEN_WRAP      *Wrap
 390   );
 391
 392 /**
 393   Check existing TCP connection, if in error state, recover TCP4 connection. Then,
 394   connect one TLS session if required.
 395
 396   @param[in]  HttpInstance       The HTTP instance private data.
 397
 398   @retval EFI_SUCCESS            The TCP connection is established.
 399   @retval EFI_NOT_READY          TCP4 protocol child is not created or configured.
 400   @retval Others                 Other error as indicated.
 401
 402 **/
 403 EFI_STATUS
 404 HttpConnectTcp4 (
 405   IN  HTTP_PROTOCOL        *HttpInstance
 406   );
 407
 408 /**
 409   Check existing TCP connection, if in error state, recover TCP6 connection. Then,
 410   connect one TLS session if required.
 411
 412   @param[in]  HttpInstance       The HTTP instance private data.
 413
 414   @retval EFI_SUCCESS            The TCP connection is established.
 415   @retval EFI_NOT_READY          TCP6 protocol child is not created or configured.
 416   @retval Others                 Other error as indicated.
 417
 418 **/
 419 EFI_STATUS
 420 HttpConnectTcp6 (
 421   IN  HTTP_PROTOCOL        *HttpInstance
 422   );
 423
 424 /**
 425   Send the HTTP or HTTPS message through TCP4 or TCP6.
 426
 427   @param[in]  HttpInstance       The HTTP instance private data.
 428   @param[in]  Wrap               The HTTP token's wrap data.
 429   @param[in]  TxString           Buffer containing the HTTP message string.
 430   @param[in]  TxStringLen        Length of the HTTP message string in bytes.
 431
 432   @retval EFI_SUCCESS            The HTTP message is queued into TCP transmit queue.
 433   @retval Others                 Other error as indicated.
 434
 435 **/
 436 EFI_STATUS
 437 HttpTransmitTcp (
 438   IN  HTTP_PROTOCOL    *HttpInstance,
 439   IN  HTTP_TOKEN_WRAP  *Wrap,
 440   IN  UINT8            *TxString,
 441   IN  UINTN            TxStringLen
 442   );
 443
 444 /**
 445   Check whether the user's token or event has already
 446   been enqueue on HTTP Tx or Rx Token list.
 447
 448   @param[in]  Map                The container of either user's transmit or receive
 449                                  token.
 450   @param[in]  Item               Current item to check against.
 451   @param[in]  Context            The Token to check againist.
 452
 453   @retval EFI_ACCESS_DENIED      The token or event has already been enqueued in IP
 454   @retval EFI_SUCCESS            The current item isn't the same token/event as the
 455                                  context.
 456
 457 **/
 458 EFI_STATUS
 459 EFIAPI
 460 HttpTokenExist (
 461   IN NET_MAP                *Map,
 462   IN NET_MAP_ITEM           *Item,
 463   IN VOID                   *Context
 464   );
 465
 466 /**
 467   Check whether the HTTP message associated with TxToken or Tx6Token is already sent out.
 468
 469   @param[in]  Map                The container of TxToken.
 470   @param[in]  Item               Current item to check against.
 471   @param[in]  Context            The Token to check againist.
 472
 473   @retval EFI_NOT_READY          The HTTP message is still queued in the list.
 474   @retval EFI_SUCCESS            The HTTP message has been sent out.
 475
 476 **/
 477 EFI_STATUS
 478 EFIAPI
 479 HttpTcpNotReady (
 480   IN NET_MAP                *Map,
 481   IN NET_MAP_ITEM           *Item,
 482   IN VOID                   *Context
 483   );
 484
 485 /**
 486   Initialize Http session.
 487
 488   @param[in]  HttpInstance       The HTTP instance private data.
 489   @param[in]  Wrap               The HTTP token's wrap data.
 490   @param[in]  Configure          The Flag indicates whether need to initialize session.
 491   @param[in]  TlsConfigure       The Flag indicates whether it's the new Tls session.
 492
 493   @retval EFI_SUCCESS            The initialization of session is done.
 494   @retval Others                 Other error as indicated.
 495
 496 **/
 497 EFI_STATUS
 498 HttpInitSession (
 499   IN  HTTP_PROTOCOL    *HttpInstance,
 500   IN  HTTP_TOKEN_WRAP  *Wrap,
 501   IN  BOOLEAN          Configure,
 502   IN  BOOLEAN          TlsConfigure
 503   );
 504
 505 /**
 506   Transmit the HTTP or HTTPS mssage by processing the associated HTTP token.
 507
 508   @param[in]  Map                The container of TxToken or Tx6Token.
 509   @param[in]  Item               Current item to check against.
 510   @param[in]  Context            The Token to check againist.
 511
 512   @retval EFI_OUT_OF_RESOURCES   Failed to allocate resources.
 513   @retval EFI_SUCCESS            The HTTP message is queued into TCP transmit
 514                                  queue.
 515
 516 **/
 517 EFI_STATUS
 518 EFIAPI
 519 HttpTcpTransmit (
 520   IN NET_MAP                *Map,
 521   IN NET_MAP_ITEM           *Item,
 522   IN VOID                   *Context
 523   );
 524
 525 /**
 526   Receive the HTTP response by processing the associated HTTP token.
 527
 528   @param[in]  Map                The container of Rx4Token or Rx6Token.
 529   @param[in]  Item               Current item to check against.
 530   @param[in]  Context            The Token to check againist.
 531
 532   @retval EFI_SUCCESS            The HTTP response is queued into TCP receive
 533                                  queue.
 534   @retval Others                 Other error as indicated.
 535
 536 **/
 537 EFI_STATUS
 538 EFIAPI
 539 HttpTcpReceive (
 540   IN NET_MAP                *Map,
 541   IN NET_MAP_ITEM           *Item,
 542   IN VOID                   *Context
 543   );
 544
 545 /**
 546   Receive the HTTP header by processing the associated HTTP token.
 547
 548   @param[in]       HttpInstance    The HTTP instance private data.
 549   @param[in, out]  SizeofHeaders   The HTTP header length.
 550   @param[in, out]  BufferSize      The size of buffer to cacahe the header message.
 551   @param[in]       Timeout         The time to wait for receiving the header packet.
 552
 553   @retval EFI_SUCCESS              The HTTP header is received.
 554   @retval Others                   Other errors as indicated.
 555
 556 **/
 557 EFI_STATUS
 558 HttpTcpReceiveHeader (
 559   IN  HTTP_PROTOCOL         *HttpInstance,
 560   IN  OUT UINTN             *SizeofHeaders,
 561   IN  OUT UINTN             *BufferSize,
 562   IN  EFI_EVENT             Timeout
 563   );
 564
 565 /**
 566   Receive the HTTP body by processing the associated HTTP token.
 567
 568   @param[in]  Wrap               The HTTP token's wrap data.
 569   @param[in]  HttpMsg            The HTTP message data.
 570
 571   @retval EFI_SUCCESS            The HTTP body is received.
 572   @retval Others                 Other error as indicated.
 573
 574 **/
 575 EFI_STATUS
 576 HttpTcpReceiveBody (
 577   IN  HTTP_TOKEN_WRAP       *Wrap,
 578   IN  EFI_HTTP_MESSAGE      *HttpMsg
 579   );
 580
 581 /**
 582   Clean up Tcp Tokens while the Tcp transmission error occurs.
 583
 584   @param[in]  Wrap               Pointer to HTTP token's wrap data.
 585
 586 **/
 587 VOID
 588 HttpTcpTokenCleanup (
 589   IN  HTTP_TOKEN_WRAP      *Wrap
 590   );
 591
 592 /**
 593   The work function of EfiHttpResponse().
 594
 595   @param[in]  Wrap                Pointer to HTTP token's wrap data.
 596
 597   @retval EFI_SUCCESS             Allocation succeeded.
 598   @retval EFI_OUT_OF_RESOURCES    Failed to complete the opration due to lack of resources.
 599   @retval EFI_NOT_READY           Can't find a corresponding TxToken.
 600
 601 **/
 602 EFI_STATUS
 603 HttpResponseWorker (
 604   IN  HTTP_TOKEN_WRAP           *Wrap
 605   );
 606
 607 #endif