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 //
  95 // Callback data for HTTP_PARSER_CALLBACK()
  96 //
  97 typedef struct {
  98   UINTN                         ParseDataLength;
  99   VOID                          *ParseData;
 100   VOID                          *Wrap;
 101 } HTTP_CALLBACK_DATA;
 102
 103 typedef struct _HTTP_PROTOCOL {
 104   UINT32                        Signature;
 105   EFI_HTTP_PROTOCOL             Http;
 106   EFI_HANDLE                    Handle;
 107   HTTP_SERVICE                  *Service;
 108   LIST_ENTRY                    Link;   // Link to all HTTP instance from the service.
 109   BOOLEAN                       InDestroy;
 110   INTN                          State;
 111   EFI_HTTP_METHOD               Method;
 112
 113   UINTN                         StatusCode;
 114
 115   EFI_EVENT                     TimeoutEvent;
 116
 117   EFI_HANDLE                    Tcp4ChildHandle;
 118   EFI_TCP4_PROTOCOL             *Tcp4;
 119   EFI_TCP4_CONFIG_DATA          Tcp4CfgData;
 120   EFI_TCP4_OPTION               Tcp4Option;
 121
 122   EFI_TCP4_CONNECTION_TOKEN     Tcp4ConnToken;
 123   BOOLEAN                       IsTcp4ConnDone;
 124   EFI_TCP4_CLOSE_TOKEN          Tcp4CloseToken;
 125   BOOLEAN                       IsTcp4CloseDone;
 126   CHAR8                         *RemoteHost;
 127   UINT16                        RemotePort;
 128   EFI_IPv4_ADDRESS              RemoteAddr;
 129
 130   EFI_HANDLE                    Tcp6ChildHandle;
 131   EFI_TCP6_PROTOCOL             *Tcp6;
 132   EFI_TCP6_CONFIG_DATA          Tcp6CfgData;
 133   EFI_TCP6_OPTION               Tcp6Option;
 134
 135   EFI_TCP6_CONNECTION_TOKEN     Tcp6ConnToken;
 136   BOOLEAN                       IsTcp6ConnDone;
 137   EFI_TCP6_CLOSE_TOKEN          Tcp6CloseToken;
 138   BOOLEAN                       IsTcp6CloseDone;
 139   EFI_IPv6_ADDRESS              RemoteIpv6Addr;
 140
 141   //
 142   // Rx4Token or Rx6Token used for receiving HTTP header.
 143   //
 144   EFI_TCP4_IO_TOKEN             Rx4Token;
 145   EFI_TCP4_RECEIVE_DATA         Rx4Data;
 146   EFI_TCP6_IO_TOKEN             Rx6Token;
 147   EFI_TCP6_RECEIVE_DATA         Rx6Data;
 148   BOOLEAN                       IsRxDone;
 149
 150   CHAR8                         **EndofHeader;
 151   CHAR8                         **HttpHeaders;
 152   CHAR8                         *CacheBody;
 153   CHAR8                         *NextMsg;
 154   UINTN                         CacheLen;
 155   UINTN                         CacheOffset;
 156
 157   //
 158   // HTTP message-body parser.
 159   //
 160   VOID                          *MsgParser;
 161   HTTP_CALLBACK_DATA            CallbackData;
 162
 163   EFI_HTTP_VERSION              HttpVersion;
 164   UINT32                        TimeOutMillisec;
 165   BOOLEAN                       LocalAddressIsIPv6;
 166
 167   EFI_HTTPv4_ACCESS_POINT       IPv4Node;
 168   EFI_HTTPv6_ACCESS_POINT       Ipv6Node;
 169
 170   NET_MAP                       TxTokens;
 171   NET_MAP                       RxTokens;
 172
 173   CHAR8                         *Url;
 174
 175   //
 176   // Https Support
 177   //
 178   BOOLEAN                          UseHttps;
 179
 180   EFI_SERVICE_BINDING_PROTOCOL     *TlsSb;
 181   EFI_HANDLE                       TlsChildHandle; /// Tls ChildHandle
 182   TLS_CONFIG_DATA                  TlsConfigData;
 183   EFI_TLS_PROTOCOL                 *Tls;
 184   EFI_TLS_CONFIGURATION_PROTOCOL   *TlsConfiguration;
 185   EFI_TLS_SESSION_STATE            TlsSessionState;
 186
 187   //
 188   // TlsTxData used for transmitting TLS related messages.
 189   //
 190   EFI_TCP4_IO_TOKEN                Tcp4TlsTxToken;
 191   EFI_TCP4_TRANSMIT_DATA           Tcp4TlsTxData;
 192   EFI_TCP6_IO_TOKEN                Tcp6TlsTxToken;
 193   EFI_TCP6_TRANSMIT_DATA           Tcp6TlsTxData;
 194   BOOLEAN                          TlsIsTxDone;
 195
 196   //
 197   // TlsRxData used for receiving TLS related messages.
 198   //
 199   EFI_TCP4_IO_TOKEN                Tcp4TlsRxToken;
 200   EFI_TCP4_RECEIVE_DATA            Tcp4TlsRxData;
 201   EFI_TCP6_IO_TOKEN                Tcp6TlsRxToken;
 202   EFI_TCP6_RECEIVE_DATA            Tcp6TlsRxData;
 203   BOOLEAN                          TlsIsRxDone;
 204 } HTTP_PROTOCOL;
 205
 206 typedef struct {
 207   EFI_HTTP_TOKEN                *HttpToken;
 208   HTTP_PROTOCOL                 *HttpInstance;
 209   HTTP_TCP_TOKEN_WRAP           TcpWrap;
 210 } HTTP_TOKEN_WRAP;
 211
 212
 213 #define HTTP_PROTOCOL_SIGNATURE  SIGNATURE_32('H', 't', 't', 'P')
 214
 215 #define HTTP_INSTANCE_FROM_PROTOCOL(a) \
 216   CR ( \
 217   (a), \
 218   HTTP_PROTOCOL, \
 219   Http, \
 220   HTTP_PROTOCOL_SIGNATURE \
 221   )
 222
 223 /**
 224   The common notify function used in HTTP driver.
 225
 226   @param[in]  Event   The event signaled.
 227   @param[in]  Context The context.
 228
 229 **/
 230 VOID
 231 EFIAPI
 232 HttpCommonNotify (
 233   IN EFI_EVENT  Event,
 234   IN VOID       *Context
 235   );
 236
 237 /**
 238   Create events for the TCP connection token and TCP close token.
 239
 240   @param[in]  HttpInstance       Pointer to HTTP_PROTOCOL structure.
 241
 242   @retval EFI_SUCCESS            The events are created successfully.
 243   @retval others                 Other error as indicated.
 244
 245 **/
 246 EFI_STATUS
 247 HttpCreateTcpConnCloseEvent (
 248   IN  HTTP_PROTOCOL        *HttpInstance
 249   );
 250
 251 /**
 252   Close events in the TCP connection token and TCP close token.
 253
 254   @param[in]  HttpInstance   Pointer to HTTP_PROTOCOL structure.
 255
 256 **/
 257 VOID
 258 HttpCloseTcpConnCloseEvent (
 259   IN  HTTP_PROTOCOL        *HttpInstance
 260   );
 261
 262 /**
 263   Create event for the TCP transmit token.
 264
 265   @param[in]  Wrap               Point to HTTP token's wrap data.
 266
 267   @retval EFI_SUCCESS            The events is created successfully.
 268   @retval others                 Other error as indicated.
 269
 270 **/
 271 EFI_STATUS
 272 HttpCreateTcpTxEvent (
 273   IN  HTTP_TOKEN_WRAP      *Wrap
 274   );
 275
 276 /**
 277   Create event for the TCP receive token which is used to receive HTTP header.
 278
 279   @param[in]  HttpInstance       Pointer to HTTP_PROTOCOL structure.
 280
 281   @retval EFI_SUCCESS            The events is created successfully.
 282   @retval others                 Other error as indicated.
 283
 284 **/
 285 EFI_STATUS
 286 HttpCreateTcpRxEventForHeader (
 287   IN  HTTP_PROTOCOL        *HttpInstance
 288   );
 289
 290 /**
 291   Create event for the TCP receive token which is used to receive HTTP body.
 292
 293   @param[in]  Wrap               Point to HTTP token's wrap data.
 294
 295   @retval EFI_SUCCESS            The events is created successfully.
 296   @retval others                 Other error as indicated.
 297
 298 **/
 299 EFI_STATUS
 300 HttpCreateTcpRxEvent (
 301   IN  HTTP_TOKEN_WRAP      *Wrap
 302   );
 303
 304 /**
 305   Close Events for Tcp Receive Tokens for HTTP body and HTTP header.
 306
 307   @param[in]  Wrap               Pointer to HTTP token's wrap data.
 308
 309 **/
 310 VOID
 311 HttpCloseTcpRxEvent (
 312   IN  HTTP_TOKEN_WRAP      *Wrap
 313   );
 314
 315 /**
 316   Intiialize the HTTP_PROTOCOL structure to the unconfigured state.
 317
 318   @param[in, out]  HttpInstance         Pointer to HTTP_PROTOCOL structure.
 319   @param[in]       IpVersion            Indicate us TCP4 protocol or TCP6 protocol.
 320
 321   @retval EFI_SUCCESS       HTTP_PROTOCOL structure is initialized successfully.
 322   @retval Others            Other error as indicated.
 323
 324 **/
 325 EFI_STATUS
 326 HttpInitProtocol (
 327   IN OUT HTTP_PROTOCOL           *HttpInstance,
 328   IN     BOOLEAN                 IpVersion
 329   );
 330
 331 /**
 332   Clean up the HTTP child, release all the resources used by it.
 333
 334   @param[in]  HttpInstance       The HTTP child to clean up.
 335
 336 **/
 337 VOID
 338 HttpCleanProtocol (
 339   IN  HTTP_PROTOCOL          *HttpInstance
 340   );
 341
 342 /**
 343   Establish TCP connection with HTTP server.
 344
 345   @param[in]  HttpInstance       The HTTP instance private data.
 346
 347   @retval EFI_SUCCESS            The TCP connection is established.
 348   @retval Others                 Other error as indicated.
 349
 350 **/
 351 EFI_STATUS
 352 HttpCreateConnection (
 353   IN  HTTP_PROTOCOL        *HttpInstance
 354   );
 355
 356 /**
 357   Close existing TCP connection.
 358
 359   @param[in]  HttpInstance       The HTTP instance private data.
 360
 361   @retval EFI_SUCCESS            The TCP connection is closed.
 362   @retval Others                 Other error as indicated.
 363
 364 **/
 365 EFI_STATUS
 366 HttpCloseConnection (
 367   IN  HTTP_PROTOCOL        *HttpInstance
 368   );
 369
 370 /**
 371   Configure TCP4 protocol child.
 372
 373   @param[in]  HttpInstance       The HTTP instance private data.
 374   @param[in]  Wrap               The HTTP token's wrap data.
 375
 376   @retval EFI_SUCCESS            The TCP4 protocol child is configured.
 377   @retval Others                 Other error as indicated.
 378
 379 **/
 380 EFI_STATUS
 381 HttpConfigureTcp4 (
 382   IN  HTTP_PROTOCOL        *HttpInstance,
 383   IN  HTTP_TOKEN_WRAP      *Wrap
 384   );
 385
 386 /**
 387   Configure TCP6 protocol child.
 388
 389   @param[in]  HttpInstance       The HTTP instance private data.
 390   @param[in]  Wrap               The HTTP token's wrap data.
 391
 392   @retval EFI_SUCCESS            The TCP6 protocol child is configured.
 393   @retval Others                 Other error as indicated.
 394
 395 **/
 396 EFI_STATUS
 397 HttpConfigureTcp6 (
 398   IN  HTTP_PROTOCOL        *HttpInstance,
 399   IN  HTTP_TOKEN_WRAP      *Wrap
 400   );
 401
 402 /**
 403   Check existing TCP connection, if in error state, recover TCP4 connection. Then,
 404   connect one TLS session if required.
 405
 406   @param[in]  HttpInstance       The HTTP instance private data.
 407
 408   @retval EFI_SUCCESS            The TCP connection is established.
 409   @retval EFI_NOT_READY          TCP4 protocol child is not created or configured.
 410   @retval Others                 Other error as indicated.
 411
 412 **/
 413 EFI_STATUS
 414 HttpConnectTcp4 (
 415   IN  HTTP_PROTOCOL        *HttpInstance
 416   );
 417
 418 /**
 419   Check existing TCP connection, if in error state, recover TCP6 connection. Then,
 420   connect one TLS session if required.
 421
 422   @param[in]  HttpInstance       The HTTP instance private data.
 423
 424   @retval EFI_SUCCESS            The TCP connection is established.
 425   @retval EFI_NOT_READY          TCP6 protocol child is not created or configured.
 426   @retval Others                 Other error as indicated.
 427
 428 **/
 429 EFI_STATUS
 430 HttpConnectTcp6 (
 431   IN  HTTP_PROTOCOL        *HttpInstance
 432   );
 433
 434 /**
 435   Send the HTTP or HTTPS message through TCP4 or TCP6.
 436
 437   @param[in]  HttpInstance       The HTTP instance private data.
 438   @param[in]  Wrap               The HTTP token's wrap data.
 439   @param[in]  TxString           Buffer containing the HTTP message string.
 440   @param[in]  TxStringLen        Length of the HTTP message string in bytes.
 441
 442   @retval EFI_SUCCESS            The HTTP message is queued into TCP transmit queue.
 443   @retval Others                 Other error as indicated.
 444
 445 **/
 446 EFI_STATUS
 447 HttpTransmitTcp (
 448   IN  HTTP_PROTOCOL    *HttpInstance,
 449   IN  HTTP_TOKEN_WRAP  *Wrap,
 450   IN  UINT8            *TxString,
 451   IN  UINTN            TxStringLen
 452   );
 453
 454 /**
 455   Check whether the user's token or event has already
 456   been enqueue on HTTP Tx or Rx Token list.
 457
 458   @param[in]  Map                The container of either user's transmit or receive
 459                                  token.
 460   @param[in]  Item               Current item to check against.
 461   @param[in]  Context            The Token to check againist.
 462
 463   @retval EFI_ACCESS_DENIED      The token or event has already been enqueued in IP
 464   @retval EFI_SUCCESS            The current item isn't the same token/event as the
 465                                  context.
 466
 467 **/
 468 EFI_STATUS
 469 EFIAPI
 470 HttpTokenExist (
 471   IN NET_MAP                *Map,
 472   IN NET_MAP_ITEM           *Item,
 473   IN VOID                   *Context
 474   );
 475
 476 /**
 477   Check whether the HTTP message associated with TxToken or Tx6Token is already sent out.
 478
 479   @param[in]  Map                The container of TxToken.
 480   @param[in]  Item               Current item to check against.
 481   @param[in]  Context            The Token to check againist.
 482
 483   @retval EFI_NOT_READY          The HTTP message is still queued in the list.
 484   @retval EFI_SUCCESS            The HTTP message has been sent out.
 485
 486 **/
 487 EFI_STATUS
 488 EFIAPI
 489 HttpTcpNotReady (
 490   IN NET_MAP                *Map,
 491   IN NET_MAP_ITEM           *Item,
 492   IN VOID                   *Context
 493   );
 494
 495 /**
 496   Initialize Http session.
 497
 498   @param[in]  HttpInstance       The HTTP instance private data.
 499   @param[in]  Wrap               The HTTP token's wrap data.
 500   @param[in]  Configure          The Flag indicates whether need to initialize session.
 501   @param[in]  TlsConfigure       The Flag indicates whether it's the new Tls session.
 502
 503   @retval EFI_SUCCESS            The initialization of session is done.
 504   @retval Others                 Other error as indicated.
 505
 506 **/
 507 EFI_STATUS
 508 HttpInitSession (
 509   IN  HTTP_PROTOCOL    *HttpInstance,
 510   IN  HTTP_TOKEN_WRAP  *Wrap,
 511   IN  BOOLEAN          Configure,
 512   IN  BOOLEAN          TlsConfigure
 513   );
 514
 515 /**
 516   Transmit the HTTP or HTTPS mssage by processing the associated HTTP token.
 517
 518   @param[in]  Map                The container of TxToken or Tx6Token.
 519   @param[in]  Item               Current item to check against.
 520   @param[in]  Context            The Token to check againist.
 521
 522   @retval EFI_OUT_OF_RESOURCES   Failed to allocate resources.
 523   @retval EFI_SUCCESS            The HTTP message is queued into TCP transmit
 524                                  queue.
 525
 526 **/
 527 EFI_STATUS
 528 EFIAPI
 529 HttpTcpTransmit (
 530   IN NET_MAP                *Map,
 531   IN NET_MAP_ITEM           *Item,
 532   IN VOID                   *Context
 533   );
 534
 535 /**
 536   Receive the HTTP response by processing the associated HTTP token.
 537
 538   @param[in]  Map                The container of Rx4Token or Rx6Token.
 539   @param[in]  Item               Current item to check against.
 540   @param[in]  Context            The Token to check againist.
 541
 542   @retval EFI_SUCCESS            The HTTP response is queued into TCP receive
 543                                  queue.
 544   @retval Others                 Other error as indicated.
 545
 546 **/
 547 EFI_STATUS
 548 EFIAPI
 549 HttpTcpReceive (
 550   IN NET_MAP                *Map,
 551   IN NET_MAP_ITEM           *Item,
 552   IN VOID                   *Context
 553   );
 554
 555 /**
 556   Receive the HTTP header by processing the associated HTTP token.
 557
 558   @param[in]       HttpInstance    The HTTP instance private data.
 559   @param[in, out]  SizeofHeaders   The HTTP header length.
 560   @param[in, out]  BufferSize      The size of buffer to cacahe the header message.
 561   @param[in]       Timeout         The time to wait for receiving the header packet.
 562
 563   @retval EFI_SUCCESS              The HTTP header is received.
 564   @retval Others                   Other errors as indicated.
 565
 566 **/
 567 EFI_STATUS
 568 HttpTcpReceiveHeader (
 569   IN  HTTP_PROTOCOL         *HttpInstance,
 570   IN  OUT UINTN             *SizeofHeaders,
 571   IN  OUT UINTN             *BufferSize,
 572   IN  EFI_EVENT             Timeout
 573   );
 574
 575 /**
 576   Receive the HTTP body by processing the associated HTTP token.
 577
 578   @param[in]  Wrap               The HTTP token's wrap data.
 579   @param[in]  HttpMsg            The HTTP message data.
 580
 581   @retval EFI_SUCCESS            The HTTP body is received.
 582   @retval Others                 Other error as indicated.
 583
 584 **/
 585 EFI_STATUS
 586 HttpTcpReceiveBody (
 587   IN  HTTP_TOKEN_WRAP       *Wrap,
 588   IN  EFI_HTTP_MESSAGE      *HttpMsg
 589   );
 590
 591 /**
 592   Clean up Tcp Tokens while the Tcp transmission error occurs.
 593
 594   @param[in]  Wrap               Pointer to HTTP token's wrap data.
 595
 596 **/
 597 VOID
 598 HttpTcpTokenCleanup (
 599   IN  HTTP_TOKEN_WRAP      *Wrap
 600   );
 601
 602 /**
 603   The work function of EfiHttpResponse().
 604
 605   @param[in]  Wrap                Pointer to HTTP token's wrap data.
 606
 607   @retval EFI_SUCCESS             Allocation succeeded.
 608   @retval EFI_OUT_OF_RESOURCES    Failed to complete the opration due to lack of resources.
 609   @retval EFI_NOT_READY           Can't find a corresponding TxToken.
 610
 611 **/
 612 EFI_STATUS
 613 HttpResponseWorker (
 614   IN  HTTP_TOKEN_WRAP           *Wrap
 615   );
 616
 617 #endif