NetworkPkg/Dhcp6Dxe/Dhcp6Impl.h

   1 /** @file
   2   Dhcp6 internal data structure and definition declaration.
   3
   4   Copyright (c) 2009 - 2017, Intel Corporation. All rights reserved.<BR>
   5
   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_DHCP6_IMPL_H__
  17 #define __EFI_DHCP6_IMPL_H__
  18
  19
  20 #include <Uefi.h>
  21
  22 #include <IndustryStandard/Dhcp.h>
  23
  24 #include <Protocol/Dhcp6.h>
  25 #include <Protocol/Udp6.h>
  26 #include <Protocol/Ip6Config.h>
  27 #include <Protocol/ServiceBinding.h>
  28 #include <Protocol/DriverBinding.h>
  29
  30 #include <Library/UdpIoLib.h>
  31 #include <Library/DebugLib.h>
  32 #include <Library/BaseMemoryLib.h>
  33 #include <Library/MemoryAllocationLib.h>
  34 #include <Library/UefiBootServicesTableLib.h>
  35 #include <Library/UefiRuntimeServicesTableLib.h>
  36 #include <Library/UefiLib.h>
  37 #include <Library/BaseLib.h>
  38 #include <Library/NetLib.h>
  39 #include <Library/PrintLib.h>
  40 #include <Guid/ZeroGuid.h>
  41
  42
  43 typedef struct _DHCP6_IA_CB    DHCP6_IA_CB;
  44 typedef struct _DHCP6_INF_CB   DHCP6_INF_CB;
  45 typedef struct _DHCP6_TX_CB    DHCP6_TX_CB;
  46 typedef struct _DHCP6_SERVICE  DHCP6_SERVICE;
  47 typedef struct _DHCP6_INSTANCE DHCP6_INSTANCE;
  48
  49 #include "Dhcp6Utility.h"
  50 #include "Dhcp6Io.h"
  51 #include "Dhcp6Driver.h"
  52
  53 #define DHCP6_SERVICE_SIGNATURE   SIGNATURE_32 ('D', 'H', '6', 'S')
  54 #define DHCP6_INSTANCE_SIGNATURE  SIGNATURE_32 ('D', 'H', '6', 'I')
  55
  56 #define DHCP6_PACKET_ALL          0
  57 #define DHCP6_PACKET_STATEFUL     1
  58 #define DHCP6_PACKET_STATELESS    2
  59
  60 #define DHCP6_BASE_PACKET_SIZE    1024
  61
  62 #define DHCP6_PORT_CLIENT         546
  63 #define DHCP6_PORT_SERVER         547
  64
  65 #define DHCP_CHECK_MEDIA_WAITING_TIME    EFI_TIMER_PERIOD_SECONDS(20)
  66
  67 #define DHCP6_INSTANCE_FROM_THIS(Instance) CR ((Instance), DHCP6_INSTANCE, Dhcp6, DHCP6_INSTANCE_SIGNATURE)
  68 #define DHCP6_SERVICE_FROM_THIS(Service)   CR ((Service), DHCP6_SERVICE, ServiceBinding, DHCP6_SERVICE_SIGNATURE)
  69
  70 extern EFI_IPv6_ADDRESS           mAllDhcpRelayAndServersAddress;
  71 extern EFI_IPv6_ADDRESS           mAllDhcpServersAddress;
  72 extern EFI_DHCP6_PROTOCOL         gDhcp6ProtocolTemplate;
  73
  74 //
  75 // Control block for each IA.
  76 //
  77 struct _DHCP6_IA_CB {
  78   EFI_DHCP6_IA                  *Ia;
  79   UINT32                        T1;
  80   UINT32                        T2;
  81   UINT32                        AllExpireTime;
  82   UINT32                        LeaseTime;
  83 };
  84
  85 //
  86 // Control block for each transmitted message.
  87 //
  88 struct _DHCP6_TX_CB {
  89   LIST_ENTRY                    Link;
  90   UINT32                        Xid;
  91   EFI_DHCP6_PACKET              *TxPacket;
  92   EFI_DHCP6_RETRANSMISSION      RetryCtl;
  93   UINT32                        RetryCnt;
  94   UINT32                        RetryExp;
  95   UINT32                        RetryLos;
  96   UINT32                        TickTime;
  97   UINT16                        *Elapsed;
  98   BOOLEAN                       SolicitRetry;
  99 };
 100
 101 //
 102 // Control block for each info-request message.
 103 //
 104 struct _DHCP6_INF_CB {
 105   LIST_ENTRY                    Link;
 106   UINT32                        Xid;
 107   EFI_DHCP6_INFO_CALLBACK       ReplyCallback;
 108   VOID                          *CallbackContext;
 109   EFI_EVENT                     TimeoutEvent;
 110 };
 111
 112 //
 113 // Control block for Dhcp6 instance, it's per configuration data.
 114 //
 115 struct _DHCP6_INSTANCE {
 116   UINT32                        Signature;
 117   EFI_HANDLE                    Handle;
 118   DHCP6_SERVICE                 *Service;
 119   LIST_ENTRY                    Link;
 120   EFI_DHCP6_PROTOCOL            Dhcp6;
 121   EFI_EVENT                     Timer;
 122   EFI_DHCP6_CONFIG_DATA         *Config;
 123   EFI_DHCP6_IA                  *CacheIa;
 124   DHCP6_IA_CB                   IaCb;
 125   LIST_ENTRY                    TxList;
 126   LIST_ENTRY                    InfList;
 127   EFI_DHCP6_PACKET              *AdSelect;
 128   UINT8                         AdPref;
 129   EFI_IPv6_ADDRESS              *Unicast;
 130   volatile EFI_STATUS           UdpSts;
 131   BOOLEAN                       InDestroy;
 132   BOOLEAN                       MediaPresent;
 133   //
 134   // StartTime is used to calculate the 'elapsed-time' option. Refer to RFC3315,
 135   // the elapsed-time is amount of time since the client began its current DHCP transaction.
 136   //
 137   UINT64                        StartTime;
 138 };
 139
 140 //
 141 // Control block for Dhcp6 service, it's per Nic handle.
 142 //
 143 struct _DHCP6_SERVICE {
 144   UINT32                        Signature;
 145   EFI_HANDLE                    Controller;
 146   EFI_HANDLE                    Image;
 147   EFI_SERVICE_BINDING_PROTOCOL  ServiceBinding;
 148   EFI_SIMPLE_NETWORK_PROTOCOL   *Snp;
 149   EFI_IP6_CONFIG_PROTOCOL       *Ip6Cfg;
 150   EFI_DHCP6_DUID                *ClientId;
 151   UDP_IO                        *UdpIo;
 152   UINT32                        Xid;
 153   LIST_ENTRY                    Child;
 154   UINTN                         NumOfChild;
 155 };
 156
 157 /**
 158   Starts the DHCPv6 standard S.A.R.R. process.
 159
 160   The Start() function starts the DHCPv6 standard process. This function can
 161   be called only when the state of Dhcp6 instance is in the Dhcp6Init state.
 162   If the DHCP process completes successfully, the state of the Dhcp6 instance
 163   will be transferred through Dhcp6Selecting and Dhcp6Requesting to the
 164   Dhcp6Bound state.
 165   Refer to rfc-3315 for precise state transitions during this process. At the
 166   time when each event occurs in this process, the callback function that was set
 167   by EFI_DHCP6_PROTOCOL.Configure() will be called and the user can take this
 168   opportunity to control the process.
 169
 170   @param[in]  This              The pointer to Dhcp6 protocol.
 171
 172   @retval EFI_SUCCESS           The DHCPv6 standard process has started, or it
 173                                 completed when CompletionEvent was NULL.
 174   @retval EFI_ACCESS_DENIED     The EFI DHCPv6 Child instance hasn't been configured.
 175   @retval EFI_INVALID_PARAMETER This is NULL.
 176   @retval EFI_OUT_OF_RESOURCES  Required system resources could not be allocated.
 177   @retval EFI_TIMEOUT           The DHCPv6 configuration process failed because no
 178                                 response was received from the server within the
 179                                 specified timeout value.
 180   @retval EFI_ABORTED           The user aborted the DHCPv6 process.
 181   @retval EFI_ALREADY_STARTED   Some other Dhcp6 instance already started the DHCPv6
 182                                 standard process.
 183   @retval EFI_DEVICE_ERROR      An unexpected system or network error occurred.
 184
 185 **/
 186 EFI_STATUS
 187 EFIAPI
 188 EfiDhcp6Start (
 189   IN EFI_DHCP6_PROTOCOL        *This
 190   );
 191
 192 /**
 193   Stops the DHCPv6 standard S.A.R.R. process.
 194
 195   The Stop() function is used to stop the DHCPv6 standard process. After this
 196   function is called successfully, the state of Dhcp6 instance is transferred
 197   into the Dhcp6Init. EFI_DHCP6_PROTOCOL.Configure() needs to be called
 198   before DHCPv6 standard process can be started again. This function can be
 199   called when the Dhcp6 instance is in any state.
 200
 201   @param[in]  This              The pointer to the Dhcp6 protocol.
 202
 203   @retval EFI_SUCCESS           The Dhcp6 instance is now in the Dhcp6Init state.
 204   @retval EFI_INVALID_PARAMETER This is NULL.
 205
 206 **/
 207 EFI_STATUS
 208 EFIAPI
 209 EfiDhcp6Stop (
 210   IN EFI_DHCP6_PROTOCOL        *This
 211   );
 212
 213 /**
 214   Returns the current operating mode data for the Dhcp6 instance.
 215
 216   The GetModeData() function returns the current operating mode and
 217   cached data packet for the Dhcp6 instance.
 218
 219   @param[in]  This              The pointer to the Dhcp6 protocol.
 220   @param[out] Dhcp6ModeData     The pointer to the Dhcp6 mode data.
 221   @param[out] Dhcp6ConfigData   The pointer to the Dhcp6 configure data.
 222
 223   @retval EFI_SUCCESS           The mode data was returned.
 224   @retval EFI_INVALID_PARAMETER This is NULL.
 225   @retval EFI_ACCESS_DENIED     The EFI DHCPv6 Protocol instance has not
 226                                 been configured when Dhcp6ConfigData is
 227                                 not NULL.
 228 **/
 229 EFI_STATUS
 230 EFIAPI
 231 EfiDhcp6GetModeData (
 232   IN  EFI_DHCP6_PROTOCOL       *This,
 233   OUT EFI_DHCP6_MODE_DATA      *Dhcp6ModeData      OPTIONAL,
 234   OUT EFI_DHCP6_CONFIG_DATA    *Dhcp6ConfigData    OPTIONAL
 235   );
 236
 237 /**
 238   Initializes, changes, or resets the operational settings for the Dhcp6 instance.
 239
 240   The Configure() function is used to initialize or clean up the configuration
 241   data of the Dhcp6 instance:
 242   - When Dhcp6CfgData is not NULL and Configure() is called successfully, the
 243     configuration data will be initialized in the Dhcp6 instance and the state
 244     of the configured IA will be transferred into Dhcp6Init.
 245   - When Dhcp6CfgData is NULL and Configure() is called successfully, the
 246     configuration data will be cleaned up and no IA will be associated with
 247     the Dhcp6 instance.
 248   To update the configuration data for an Dhcp6 instance, the original data
 249   must be cleaned up before setting the new configuration data.
 250
 251   @param[in]  This                   The pointer to the Dhcp6 protocol
 252   @param[in]  Dhcp6CfgData           The pointer to the EFI_DHCP6_CONFIG_DATA.
 253
 254   @retval EFI_SUCCESS           The Dhcp6 is configured successfully with the
 255                                 Dhcp6Init state, or cleaned up the original
 256                                 configuration setting.
 257   @retval EFI_ACCESS_DENIED     The Dhcp6 instance has been already configured
 258                                 when Dhcp6CfgData is not NULL.
 259                                 The Dhcp6 instance has already started the
 260                                 DHCPv6 S.A.R.R when Dhcp6CfgData is NULL.
 261   @retval EFI_INVALID_PARAMETER Some of the parameter is invalid.
 262   @retval EFI_OUT_OF_RESOURCES  Required system resources could not be allocated.
 263   @retval EFI_DEVICE_ERROR      An unexpected system or network error occurred.
 264
 265 **/
 266 EFI_STATUS
 267 EFIAPI
 268 EfiDhcp6Configure (
 269   IN EFI_DHCP6_PROTOCOL        *This,
 270   IN EFI_DHCP6_CONFIG_DATA     *Dhcp6CfgData    OPTIONAL
 271   );
 272
 273 /**
 274   Request configuration information without the assignment of any
 275   Ia addresses of the client.
 276
 277   The InfoRequest() function is used to request configuration information
 278   without the assignment of any IPv6 address of the client. Client sends
 279   out Information Request packet to obtain the required configuration
 280   information, and DHCPv6 server responds with Reply packet containing
 281   the information for the client. The received Reply packet will be passed
 282   to the user by ReplyCallback function. If user returns EFI_NOT_READY from
 283   ReplyCallback, the Dhcp6 instance will continue to receive other Reply
 284   packets unless timeout according to the Retransmission parameter.
 285   Otherwise, the Information Request exchange process will be finished
 286   successfully if user returns EFI_SUCCESS from ReplyCallback.
 287
 288   @param[in]  This              The pointer to the Dhcp6 protocol.
 289   @param[in]  SendClientId      If TRUE, the DHCPv6 protocol instance will build Client
 290                                 Identifier option and include it into Information Request
 291                                 packet. Otherwise, Client Identifier option will not be included.
 292   @param[in]  OptionRequest     The pointer to the buffer of option request options.
 293   @param[in]  OptionCount       The option number in the OptionList.
 294   @param[in]  OptionList        The list of appended options.
 295   @param[in]  Retransmission    The pointer to the retransmission of the message.
 296   @param[in]  TimeoutEvent      The event of timeout.
 297   @param[in]  ReplyCallback     The callback function when a reply was received.
 298   @param[in]  CallbackContext   The pointer to the parameter passed to the callback.
 299
 300   @retval EFI_SUCCESS           The DHCPv6 information request exchange process
 301                                 completed when TimeoutEvent is NULL. Information
 302                                 Request packet has been sent to DHCPv6 server when
 303                                 TimeoutEvent is not NULL.
 304   @retval EFI_NO_RESPONSE       The DHCPv6 information request exchange process failed
 305                                 because of no response, or not all requested-options
 306                                 are responded to by DHCPv6 servers when Timeout happened.
 307   @retval EFI_ABORTED           The DHCPv6 information request exchange process was aborted
 308                                 by the user.
 309   @retval EFI_INVALID_PARAMETER Some parameter is NULL.
 310   @retval EFI_OUT_OF_RESOURCES  Required system resources could not be allocated.
 311   @retval EFI_DEVICE_ERROR      An unexpected system or network error occurred.
 312
 313 **/
 314 EFI_STATUS
 315 EFIAPI
 316 EfiDhcp6InfoRequest (
 317   IN EFI_DHCP6_PROTOCOL        *This,
 318   IN BOOLEAN                   SendClientId,
 319   IN EFI_DHCP6_PACKET_OPTION   *OptionRequest,
 320   IN UINT32                    OptionCount,
 321   IN EFI_DHCP6_PACKET_OPTION   *OptionList[]    OPTIONAL,
 322   IN EFI_DHCP6_RETRANSMISSION  *Retransmission,
 323   IN EFI_EVENT                 TimeoutEvent     OPTIONAL,
 324   IN EFI_DHCP6_INFO_CALLBACK   ReplyCallback,
 325   IN VOID                      *CallbackContext OPTIONAL
 326   );
 327
 328 /**
 329   Manually extend the valid and preferred lifetimes for the IPv6 addresses
 330   of the configured IA and update other configuration parameters by sending
 331   Renew or Rebind packet.
 332
 333   The RenewRebind() function is used to manually extend the valid and preferred
 334   lifetimes for the IPv6 addresses of the configured IA and update other
 335   configuration parameters by sending a Renew or Rebind packet.
 336   - When RebindRequest is FALSE and the state of the configured IA is Dhcp6Bound,
 337     it will send Renew packet to the previously DHCPv6 server and transfer the
 338     state of the configured IA to Dhcp6Renewing. If valid Reply packet received,
 339     the state transfers to Dhcp6Bound and the valid and preferred timer restarts.
 340     If fails, the state transfers to Dhcp6Bound but the timer continues.
 341   - When RebindRequest is TRUE and the state of the configured IA is Dhcp6Bound,
 342     it will send a Rebind packet. If a valid Reply packet is received, the state transfers
 343     to Dhcp6Bound, and the valid and preferred timer restarts. If it fails, the state
 344     transfers to Dhcp6Init, and the IA can't be used.
 345
 346   @param[in]  This              The pointer to the Dhcp6 protocol.
 347   @param[in]  RebindRequest     If TRUE, Rebind packet will be sent and enter Dhcp6Rebinding state.
 348                                 Otherwise, Renew packet will be sent and enter Dhcp6Renewing state.
 349
 350   @retval EFI_SUCCESS           The DHCPv6 renew/rebind exchange process
 351                                 completed and at least one IPv6 address of the
 352                                 configured IA was bound again when
 353                                 EFI_DHCP6_CONFIG_DATA.IaInfoEvent was NULL.
 354                                 The EFI DHCPv6 Protocol instance has sent Renew
 355                                 or Rebind packet when
 356                                 EFI_DHCP6_CONFIG_DATA.IaInfoEvent is not NULL.
 357   @retval EFI_ACCESS_DENIED     The Dhcp6 instance hasn't been configured, or the
 358                                 state of the configured IA is not in Dhcp6Bound.
 359   @retval EFI_ALREADY_STARTED   The state of the configured IA has already entered
 360                                 Dhcp6Renewing when RebindRequest is FALSE.
 361                                 The state of the configured IA has already entered
 362                                 Dhcp6Rebinding when RebindRequest is TRUE.
 363   @retval EFI_ABORTED           The DHCPv6 renew/rebind exchange process aborted
 364                                 by user.
 365   @retval EFI_NO_RESPONSE       The DHCPv6 renew/rebind exchange process failed
 366                                 because of no response.
 367   @retval EFI_NO_MAPPING        No IPv6 address has been bound to the configured
 368                                 IA after the DHCPv6 renew/rebind exchange process.
 369   @retval EFI_INVALID_PARAMETER Some parameter is NULL.
 370   @retval EFI_DEVICE_ERROR      An unexpected system or network error occurred.
 371
 372 **/
 373 EFI_STATUS
 374 EFIAPI
 375 EfiDhcp6RenewRebind (
 376   IN EFI_DHCP6_PROTOCOL        *This,
 377   IN BOOLEAN                   RebindRequest
 378   );
 379
 380 /**
 381   Inform that one or more addresses assigned by a server are already
 382   in use by another node.
 383
 384   The Decline() function is used to manually decline the assignment of
 385   IPv6 addresses, which have been already used by another node. If all
 386   IPv6 addresses of the configured IA are declined through this function,
 387   the state of the IA will switch through Dhcp6Declining to Dhcp6Init.
 388   Otherwise, the state of the IA will restore to Dhcp6Bound after the
 389   declining process. The Decline() can only be called when the IA is in
 390   Dhcp6Bound state. If the EFI_DHCP6_CONFIG_DATA.IaInfoEvent is NULL,
 391   this function is a blocking operation. It will return after the
 392   declining process finishes, or aborted by user.
 393
 394   @param[in]  This              The pointer to the Dhcp6 protocol.
 395   @param[in]  AddressCount      The number of declining addresses.
 396   @param[in]  Addresses         The pointer to the buffer stored the declining
 397                                 addresses.
 398
 399   @retval EFI_SUCCESS           The DHCPv6 decline exchange process completed
 400                                 when EFI_DHCP6_CONFIG_DATA.IaInfoEvent was NULL.
 401                                 The Dhcp6 instance has sent Decline packet when
 402                                 EFI_DHCP6_CONFIG_DATA.IaInfoEvent is not NULL.
 403   @retval EFI_ACCESS_DENIED     The Dhcp6 instance hasn't been configured, or the
 404                                 state of the configured IA is not in Dhcp6Bound.
 405   @retval EFI_ABORTED           The DHCPv6 decline exchange process was aborted by the user.
 406   @retval EFI_NOT_FOUND         Any specified IPv6 address is not correlated with
 407                                 the configured IA for this instance.
 408   @retval EFI_INVALID_PARAMETER Some parameter is NULL.
 409   @retval EFI_DEVICE_ERROR      An unexpected system or network error occurred.
 410
 411 **/
 412 EFI_STATUS
 413 EFIAPI
 414 EfiDhcp6Decline (
 415   IN EFI_DHCP6_PROTOCOL        *This,
 416   IN UINT32                    AddressCount,
 417   IN EFI_IPv6_ADDRESS          *Addresses
 418   );
 419
 420 /**
 421   Release one or more addresses associated with the configured Ia
 422   for the current instance.
 423
 424   The Release() function is used to manually release the one or more
 425   IPv6 address. If AddressCount is zero, it will release all IPv6
 426   addresses of the configured IA. If all IPv6 addresses of the IA are
 427   released through this function, the state of the IA will switch
 428   through Dhcp6Releasing to Dhcp6Init, otherwise, the state of the
 429   IA will restore to Dhcp6Bound after the releasing process.
 430   The Release() can only be called when the IA is in a Dhcp6Bound state.
 431   If the EFI_DHCP6_CONFIG_DATA.IaInfoEvent is NULL, the function is
 432   a blocking operation. It will return after the releasing process
 433   finishes, or aborted by user.
 434
 435   @param[in]  This              The pointer to the Dhcp6 protocol.
 436   @param[in]  AddressCount      The number of releasing addresses.
 437   @param[in]  Addresses         The pointer to the buffer stored the releasing
 438                                 addresses.
 439   @retval EFI_SUCCESS           The DHCPv6 release exchange process has
 440                                 completed when EFI_DHCP6_CONFIG_DATA.IaInfoEvent
 441                                 is NULL. The Dhcp6 instance has sent Release
 442                                 packet when EFI_DHCP6_CONFIG_DATA.IaInfoEvent
 443                                 is not NULL.
 444   @retval EFI_ACCESS_DENIED     The Dhcp6 instance hasn't been configured, or the
 445                                 state of the configured IA is not in Dhcp6Bound.
 446   @retval EFI_ABORTED           The DHCPv6 release exchange process was aborted by the user.
 447   @retval EFI_NOT_FOUND         Any specified IPv6 address is not correlated with
 448                                 the configured IA for this instance.
 449   @retval EFI_INVALID_PARAMETER Some parameter is NULL.
 450   @retval EFI_DEVICE_ERROR      An unexpected system or network error occurred.
 451
 452 **/
 453 EFI_STATUS
 454 EFIAPI
 455 EfiDhcp6Release (
 456   IN EFI_DHCP6_PROTOCOL        *This,
 457   IN UINT32                    AddressCount,
 458   IN EFI_IPv6_ADDRESS          *Addresses
 459   );
 460
 461 /**
 462   Parse the option data in the Dhcp6 packet.
 463
 464   The Parse() function is used to retrieve the option list in the DHCPv6 packet.
 465
 466   @param[in]      This              The pointer to the Dhcp6 protocol.
 467   @param[in]      Packet            The pointer to the Dhcp6 packet.
 468   @param[in, out] OptionCount       The number of option in the packet.
 469   @param[out]     PacketOptionList  The array of pointers to the each option in the packet.
 470
 471   @retval EFI_SUCCESS           The packet was successfully parsed.
 472   @retval EFI_INVALID_PARAMETER Some parameter is NULL.
 473   @retval EFI_BUFFER_TOO_SMALL  *OptionCount is smaller than the number of options
 474                                 that were found in the Packet.
 475
 476 **/
 477 EFI_STATUS
 478 EFIAPI
 479 EfiDhcp6Parse (
 480   IN EFI_DHCP6_PROTOCOL        *This,
 481   IN EFI_DHCP6_PACKET          *Packet,
 482   IN OUT UINT32                *OptionCount,
 483   OUT EFI_DHCP6_PACKET_OPTION  *PacketOptionList[]  OPTIONAL
 484   );
 485
 486 #endif