NetworkPkg/Dhcp6Dxe/Dhcp6Impl.h

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