NetworkPkg/HttpDxe/HttpProto.h

   1 /** @file
   2   The header files of miscellaneous routines for HttpDxe driver.
   3
   4 Copyright (c) 2015 - 2017, 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_HANDLE                       TlsChildHandle; /// Tls ChildHandle
 171   TLS_CONFIG_DATA                  TlsConfigData;
 172   EFI_TLS_PROTOCOL                 *Tls;
 173   EFI_TLS_CONFIGURATION_PROTOCOL   *TlsConfiguration;
 174   EFI_TLS_SESSION_STATE            TlsSessionState;
 175
 176   //
 177   // TlsTxData used for transmitting TLS related messages.
 178   //
 179   EFI_TCP4_IO_TOKEN                Tcp4TlsTxToken;
 180   EFI_TCP4_TRANSMIT_DATA           Tcp4TlsTxData;
 181   EFI_TCP6_IO_TOKEN                Tcp6TlsTxToken;
 182   EFI_TCP6_TRANSMIT_DATA           Tcp6TlsTxData;
 183   BOOLEAN                          TlsIsTxDone;
 184
 185   //
 186   // TlsRxData used for receiving TLS related messages.
 187   //
 188   EFI_TCP4_IO_TOKEN                Tcp4TlsRxToken;
 189   EFI_TCP4_RECEIVE_DATA            Tcp4TlsRxData;
 190   EFI_TCP6_IO_TOKEN                Tcp6TlsRxToken;
 191   EFI_TCP6_RECEIVE_DATA            Tcp6TlsRxData;
 192   BOOLEAN                          TlsIsRxDone;
 193 } HTTP_PROTOCOL;
 194
 195 typedef struct {
 196   EFI_HTTP_TOKEN                *HttpToken;
 197   HTTP_PROTOCOL                 *HttpInstance;
 198   HTTP_TCP_TOKEN_WRAP           TcpWrap;
 199 } HTTP_TOKEN_WRAP;
 200
 201
 202 #define HTTP_PROTOCOL_SIGNATURE  SIGNATURE_32('H', 't', 't', 'P')
 203
 204 #define HTTP_INSTANCE_FROM_PROTOCOL(a) \
 205   CR ( \
 206   (a), \
 207   HTTP_PROTOCOL, \
 208   Http, \
 209   HTTP_PROTOCOL_SIGNATURE \
 210   )
 211
 212 /**
 213   The common notify function used in HTTP driver.
 214
 215   @param[in]  Event   The event signaled.
 216   @param[in]  Context The context.
 217
 218 **/
 219 VOID
 220 EFIAPI
 221 HttpCommonNotify (
 222   IN EFI_EVENT  Event,
 223   IN VOID       *Context
 224   );
 225
 226 /**
 227   Create events for the TCP connection token and TCP close token.
 228
 229   @param[in]  HttpInstance       Pointer to HTTP_PROTOCOL structure.
 230
 231   @retval EFI_SUCCESS            The events are created successfully.
 232   @retval others                 Other error as indicated.
 233
 234 **/
 235 EFI_STATUS
 236 HttpCreateTcpConnCloseEvent (
 237   IN  HTTP_PROTOCOL        *HttpInstance
 238   );
 239
 240 /**
 241   Close events in the TCP connection token and TCP close token.
 242
 243   @param[in]  HttpInstance   Pointer to HTTP_PROTOCOL structure.
 244
 245 **/
 246 VOID
 247 HttpCloseTcpConnCloseEvent (
 248   IN  HTTP_PROTOCOL        *HttpInstance
 249   );
 250
 251 /**
 252   Create event for the TCP transmit token.
 253
 254   @param[in]  Wrap               Point to HTTP token's wrap data.
 255
 256   @retval EFI_SUCCESS            The events is created successfully.
 257   @retval others                 Other error as indicated.
 258
 259 **/
 260 EFI_STATUS
 261 HttpCreateTcpTxEvent (
 262   IN  HTTP_TOKEN_WRAP      *Wrap
 263   );
 264
 265 /**
 266   Create event for the TCP receive token which is used to receive HTTP header.
 267
 268   @param[in]  HttpInstance       Pointer to HTTP_PROTOCOL structure.
 269
 270   @retval EFI_SUCCESS            The events is created successfully.
 271   @retval others                 Other error as indicated.
 272
 273 **/
 274 EFI_STATUS
 275 HttpCreateTcpRxEventForHeader (
 276   IN  HTTP_PROTOCOL        *HttpInstance
 277   );
 278
 279 /**
 280   Create event for the TCP receive token which is used to receive HTTP body.
 281
 282   @param[in]  Wrap               Point to HTTP token's wrap data.
 283
 284   @retval EFI_SUCCESS            The events is created successfully.
 285   @retval others                 Other error as indicated.
 286
 287 **/
 288 EFI_STATUS
 289 HttpCreateTcpRxEvent (
 290   IN  HTTP_TOKEN_WRAP      *Wrap
 291   );
 292
 293 /**
 294   Close Events for Tcp Receive Tokens for HTTP body and HTTP header.
 295
 296   @param[in]  Wrap               Pointer to HTTP token's wrap data.
 297
 298 **/
 299 VOID
 300 HttpCloseTcpRxEvent (
 301   IN  HTTP_TOKEN_WRAP      *Wrap
 302   );
 303
 304 /**
 305   Intiialize the HTTP_PROTOCOL structure to the unconfigured state.
 306
 307   @param[in, out]  HttpInstance         Pointer to HTTP_PROTOCOL structure.
 308   @param[in]       IpVersion            Indicate us TCP4 protocol or TCP6 protocol.
 309
 310   @retval EFI_SUCCESS       HTTP_PROTOCOL structure is initialized successfully.
 311   @retval Others            Other error as indicated.
 312
 313 **/
 314 EFI_STATUS
 315 HttpInitProtocol (
 316   IN OUT HTTP_PROTOCOL           *HttpInstance,
 317   IN     BOOLEAN                 IpVersion
 318   );
 319
 320 /**
 321   Clean up the HTTP child, release all the resources used by it.
 322
 323   @param[in]  HttpInstance       The HTTP child to clean up.
 324
 325 **/
 326 VOID
 327 HttpCleanProtocol (
 328   IN  HTTP_PROTOCOL          *HttpInstance
 329   );
 330
 331 /**
 332   Establish TCP connection with HTTP server.
 333
 334   @param[in]  HttpInstance       The HTTP instance private data.
 335
 336   @retval EFI_SUCCESS            The TCP connection is established.
 337   @retval Others                 Other error as indicated.
 338
 339 **/
 340 EFI_STATUS
 341 HttpCreateConnection (
 342   IN  HTTP_PROTOCOL        *HttpInstance
 343   );
 344
 345 /**
 346   Close existing TCP connection.
 347
 348   @param[in]  HttpInstance       The HTTP instance private data.
 349
 350   @retval EFI_SUCCESS            The TCP connection is closed.
 351   @retval Others                 Other error as indicated.
 352
 353 **/
 354 EFI_STATUS
 355 HttpCloseConnection (
 356   IN  HTTP_PROTOCOL        *HttpInstance
 357   );
 358
 359 /**
 360   Configure TCP4 protocol child.
 361
 362   @param[in]  HttpInstance       The HTTP instance private data.
 363   @param[in]  Wrap               The HTTP token's wrap data.
 364
 365   @retval EFI_SUCCESS            The TCP4 protocol child is configured.
 366   @retval Others                 Other error as indicated.
 367
 368 **/
 369 EFI_STATUS
 370 HttpConfigureTcp4 (
 371   IN  HTTP_PROTOCOL        *HttpInstance,
 372   IN  HTTP_TOKEN_WRAP      *Wrap
 373   );
 374
 375 /**
 376   Configure TCP6 protocol child.
 377
 378   @param[in]  HttpInstance       The HTTP instance private data.
 379   @param[in]  Wrap               The HTTP token's wrap data.
 380
 381   @retval EFI_SUCCESS            The TCP6 protocol child is configured.
 382   @retval Others                 Other error as indicated.
 383
 384 **/
 385 EFI_STATUS
 386 HttpConfigureTcp6 (
 387   IN  HTTP_PROTOCOL        *HttpInstance,
 388   IN  HTTP_TOKEN_WRAP      *Wrap
 389   );
 390
 391 /**
 392   Check existing TCP connection, if in error state, recover TCP4 connection. Then,
 393   connect one TLS session if required.
 394
 395   @param[in]  HttpInstance       The HTTP instance private data.
 396
 397   @retval EFI_SUCCESS            The TCP connection is established.
 398   @retval EFI_NOT_READY          TCP4 protocol child is not created or configured.
 399   @retval Others                 Other error as indicated.
 400
 401 **/
 402 EFI_STATUS
 403 HttpConnectTcp4 (
 404   IN  HTTP_PROTOCOL        *HttpInstance
 405   );
 406
 407 /**
 408   Check existing TCP connection, if in error state, recover TCP6 connection. Then,
 409   connect one TLS session if required.
 410
 411   @param[in]  HttpInstance       The HTTP instance private data.
 412
 413   @retval EFI_SUCCESS            The TCP connection is established.
 414   @retval EFI_NOT_READY          TCP6 protocol child is not created or configured.
 415   @retval Others                 Other error as indicated.
 416
 417 **/
 418 EFI_STATUS
 419 HttpConnectTcp6 (
 420   IN  HTTP_PROTOCOL        *HttpInstance
 421   );
 422
 423 /**
 424   Send the HTTP or HTTPS message through TCP4 or TCP6.
 425
 426   @param[in]  HttpInstance       The HTTP instance private data.
 427   @param[in]  Wrap               The HTTP token's wrap data.
 428   @param[in]  TxString           Buffer containing the HTTP message string.
 429   @param[in]  TxStringLen        Length of the HTTP message string in bytes.
 430
 431   @retval EFI_SUCCESS            The HTTP message is queued into TCP transmit queue.
 432   @retval Others                 Other error as indicated.
 433
 434 **/
 435 EFI_STATUS
 436 HttpTransmitTcp (
 437   IN  HTTP_PROTOCOL    *HttpInstance,
 438   IN  HTTP_TOKEN_WRAP  *Wrap,
 439   IN  UINT8            *TxString,
 440   IN  UINTN            TxStringLen
 441   );
 442
 443 /**
 444   Check whether the user's token or event has already
 445   been enqueue on HTTP Tx or Rx Token list.
 446
 447   @param[in]  Map                The container of either user's transmit or receive
 448                                  token.
 449   @param[in]  Item               Current item to check against.
 450   @param[in]  Context            The Token to check againist.
 451
 452   @retval EFI_ACCESS_DENIED      The token or event has already been enqueued in IP
 453   @retval EFI_SUCCESS            The current item isn't the same token/event as the
 454                                  context.
 455
 456 **/
 457 EFI_STATUS
 458 EFIAPI
 459 HttpTokenExist (
 460   IN NET_MAP                *Map,
 461   IN NET_MAP_ITEM           *Item,
 462   IN VOID                   *Context
 463   );
 464
 465 /**
 466   Check whether the HTTP message associated with TxToken or Tx6Token is already sent out.
 467
 468   @param[in]  Map                The container of TxToken.
 469   @param[in]  Item               Current item to check against.
 470   @param[in]  Context            The Token to check againist.
 471
 472   @retval EFI_NOT_READY          The HTTP message is still queued in the list.
 473   @retval EFI_SUCCESS            The HTTP message has been sent out.
 474
 475 **/
 476 EFI_STATUS
 477 EFIAPI
 478 HttpTcpNotReady (
 479   IN NET_MAP                *Map,
 480   IN NET_MAP_ITEM           *Item,
 481   IN VOID                   *Context
 482   );
 483
 484 /**
 485   Initialize Http session.
 486
 487   @param[in]  HttpInstance       The HTTP instance private data.
 488   @param[in]  Wrap               The HTTP token's wrap data.
 489   @param[in]  Configure          The Flag indicates whether need to initialize session.
 490   @param[in]  TlsConfigure       The Flag indicates whether it's the new Tls session.
 491
 492   @retval EFI_SUCCESS            The initialization of session is done.
 493   @retval Others                 Other error as indicated.
 494
 495 **/
 496 EFI_STATUS
 497 HttpInitSession (
 498   IN  HTTP_PROTOCOL    *HttpInstance,
 499   IN  HTTP_TOKEN_WRAP  *Wrap,
 500   IN  BOOLEAN          Configure,
 501   IN  BOOLEAN          TlsConfigure
 502   );
 503
 504 /**
 505   Transmit the HTTP or HTTPS mssage by processing the associated HTTP token.
 506
 507   @param[in]  Map                The container of TxToken or Tx6Token.
 508   @param[in]  Item               Current item to check against.
 509   @param[in]  Context            The Token to check againist.
 510
 511   @retval EFI_OUT_OF_RESOURCES   Failed to allocate resources.
 512   @retval EFI_SUCCESS            The HTTP message is queued into TCP transmit
 513                                  queue.
 514
 515 **/
 516 EFI_STATUS
 517 EFIAPI
 518 HttpTcpTransmit (
 519   IN NET_MAP                *Map,
 520   IN NET_MAP_ITEM           *Item,
 521   IN VOID                   *Context
 522   );
 523
 524 /**
 525   Receive the HTTP response by processing the associated HTTP token.
 526
 527   @param[in]  Map                The container of Rx4Token or Rx6Token.
 528   @param[in]  Item               Current item to check against.
 529   @param[in]  Context            The Token to check againist.
 530
 531   @retval EFI_SUCCESS            The HTTP response is queued into TCP receive
 532                                  queue.
 533   @retval Others                 Other error as indicated.
 534
 535 **/
 536 EFI_STATUS
 537 EFIAPI
 538 HttpTcpReceive (
 539   IN NET_MAP                *Map,
 540   IN NET_MAP_ITEM           *Item,
 541   IN VOID                   *Context
 542   );
 543
 544 /**
 545   Receive the HTTP header by processing the associated HTTP token.
 546
 547   @param[in]       HttpInstance    The HTTP instance private data.
 548   @param[in, out]  SizeofHeaders   The HTTP header length.
 549   @param[in, out]  BufferSize      The size of buffer to cacahe the header message.
 550   @param[in]       Timeout         The time to wait for receiving the header packet.
 551
 552   @retval EFI_SUCCESS              The HTTP header is received.
 553   @retval Others                   Other errors as indicated.
 554
 555 **/
 556 EFI_STATUS
 557 HttpTcpReceiveHeader (
 558   IN  HTTP_PROTOCOL         *HttpInstance,
 559   IN  OUT UINTN             *SizeofHeaders,
 560   IN  OUT UINTN             *BufferSize,
 561   IN  EFI_EVENT             Timeout
 562   );
 563
 564 /**
 565   Receive the HTTP body by processing the associated HTTP token.
 566
 567   @param[in]  Wrap               The HTTP token's wrap data.
 568   @param[in]  HttpMsg            The HTTP message data.
 569
 570   @retval EFI_SUCCESS            The HTTP body is received.
 571   @retval Others                 Other error as indicated.
 572
 573 **/
 574 EFI_STATUS
 575 HttpTcpReceiveBody (
 576   IN  HTTP_TOKEN_WRAP       *Wrap,
 577   IN  EFI_HTTP_MESSAGE      *HttpMsg
 578   );
 579
 580 /**
 581   Clean up Tcp Tokens while the Tcp transmission error occurs.
 582
 583   @param[in]  Wrap               Pointer to HTTP token's wrap data.
 584
 585 **/
 586 VOID
 587 HttpTcpTokenCleanup (
 588   IN  HTTP_TOKEN_WRAP      *Wrap
 589   );
 590
 591 /**
 592   The work function of EfiHttpResponse().
 593
 594   @param[in]  Wrap                Pointer to HTTP token's wrap data.
 595
 596   @retval EFI_SUCCESS             Allocation succeeded.
 597   @retval EFI_OUT_OF_RESOURCES    Failed to complete the opration due to lack of resources.
 598   @retval EFI_NOT_READY           Can't find a corresponding TxToken.
 599
 600 **/
 601 EFI_STATUS
 602 HttpResponseWorker (
 603   IN  HTTP_TOKEN_WRAP           *Wrap
 604   );
 605
 606 #endif