NetworkPkg/IpSecDxe/IpSecImpl.h

   1 /** @file
   2   The definitions related to IPsec protocol implementation.
   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 _IP_SEC_IMPL_H_
  11 #define _IP_SEC_IMPL_H_
  12
  13 #include <Uefi.h>
  14 #include <Library/UefiLib.h>
  15 #include <Library/NetLib.h>
  16 #include <Library/BaseMemoryLib.h>
  17 #include <Library/UefiBootServicesTableLib.h>
  18 #include <Library/MemoryAllocationLib.h>
  19 #include <Protocol/IpSec.h>
  20 #include <Protocol/IpSecConfig.h>
  21 #include <Protocol/Dpc.h>
  22 #include <Protocol/ComponentName.h>
  23 #include <Protocol/ComponentName2.h>
  24
  25 typedef struct _IPSEC_PRIVATE_DATA IPSEC_PRIVATE_DATA;
  26 typedef struct _IPSEC_SPD_ENTRY IPSEC_SPD_ENTRY;
  27 typedef struct _IPSEC_PAD_ENTRY IPSEC_PAD_ENTRY;
  28 typedef struct _IPSEC_SPD_DATA IPSEC_SPD_DATA;
  29
  30 #define IPSEC_PRIVATE_DATA_SIGNATURE        SIGNATURE_32 ('I', 'P', 'S', 'E')
  31
  32 #define IPSEC_PRIVATE_DATA_FROM_IPSEC(a)    CR (a, IPSEC_PRIVATE_DATA, IpSec, IPSEC_PRIVATE_DATA_SIGNATURE)
  33 #define IPSEC_PRIVATE_DATA_FROM_UDP4LIST(a) CR (a, IPSEC_PRIVATE_DATA, Udp4List, IPSEC_PRIVATE_DATA_SIGNATURE)
  34 #define IPSEC_PRIVATE_DATA_FROM_UDP6LIST(a) CR (a, IPSEC_PRIVATE_DATA, Udp6List, IPSEC_PRIVATE_DATA_SIGNATURE)
  35 #define IPSEC_UDP_SERVICE_FROM_LIST(a)      BASE_CR (a, IKE_UDP_SERVICE, List)
  36 #define IPSEC_SPD_ENTRY_FROM_LIST(a)        BASE_CR (a, IPSEC_SPD_ENTRY, List)
  37 #define IPSEC_SAD_ENTRY_FROM_LIST(a)        BASE_CR (a, IPSEC_SAD_ENTRY, List)
  38 #define IPSEC_PAD_ENTRY_FROM_LIST(a)        BASE_CR (a, IPSEC_PAD_ENTRY, List)
  39 #define IPSEC_SAD_ENTRY_FROM_SPD(a)         BASE_CR (a, IPSEC_SAD_ENTRY, BySpd)
  40
  41 #define IPSEC_STATUS_DISABLED       0
  42 #define IPSEC_STATUS_ENABLED        1
  43 #define IPSEC_ESP_PROTOCOL          50
  44 #define IPSEC_AH_PROTOCOL           51
  45 #define IPSEC_DEFAULT_VARIABLE_SIZE 0x100
  46
  47 //
  48 // Internal Structure Definition
  49 //
  50 #pragma pack(1)
  51 typedef struct _EFI_AH_HEADER {
  52   UINT8   NextHeader;
  53   UINT8   PayloadLen;
  54   UINT16  Reserved;
  55   UINT32  Spi;
  56   UINT32  SequenceNumber;
  57 } EFI_AH_HEADER;
  58
  59 typedef struct _EFI_ESP_HEADER {
  60   UINT32  Spi;
  61   UINT32  SequenceNumber;
  62 } EFI_ESP_HEADER;
  63
  64 typedef struct _EFI_ESP_TAIL {
  65   UINT8 PaddingLength;
  66   UINT8 NextHeader;
  67 } EFI_ESP_TAIL;
  68 #pragma pack()
  69
  70 struct _IPSEC_SPD_DATA {
  71   CHAR16                    Name[100];
  72   UINT32                    PackageFlag;
  73   EFI_IPSEC_TRAFFIC_DIR     TrafficDirection;
  74   EFI_IPSEC_ACTION          Action;
  75   EFI_IPSEC_PROCESS_POLICY  *ProcessingPolicy;
  76   LIST_ENTRY                Sas;
  77 };
  78
  79 struct _IPSEC_SPD_ENTRY {
  80   EFI_IPSEC_SPD_SELECTOR  *Selector;
  81   IPSEC_SPD_DATA          *Data;
  82   LIST_ENTRY              List;
  83 };
  84
  85 typedef struct _IPSEC_SAD_DATA {
  86   EFI_IPSEC_MODE         Mode;
  87   UINT64                 SequenceNumber;
  88   UINT8                  AntiReplayWindowSize;
  89   UINT64                 AntiReplayBitmap[4];  // bitmap for received packet
  90   EFI_IPSEC_ALGO_INFO    AlgoInfo;
  91   EFI_IPSEC_SA_LIFETIME  SaLifetime;
  92   UINT32                 PathMTU;
  93   IPSEC_SPD_ENTRY        *SpdEntry;
  94   EFI_IPSEC_SPD_SELECTOR *SpdSelector;
  95   BOOLEAN                ESNEnabled;           // Extended (64-bit) SN enabled
  96   BOOLEAN                ManualSet;
  97   EFI_IP_ADDRESS         TunnelDestAddress;
  98   EFI_IP_ADDRESS         TunnelSourceAddress;
  99 } IPSEC_SAD_DATA;
 100
 101 typedef struct _IPSEC_SAD_ENTRY {
 102   EFI_IPSEC_SA_ID  *Id;
 103   IPSEC_SAD_DATA  *Data;
 104   LIST_ENTRY      List;
 105   LIST_ENTRY      BySpd;                      // Linked on IPSEC_SPD_DATA.Sas
 106 } IPSEC_SAD_ENTRY;
 107
 108 struct _IPSEC_PAD_ENTRY {
 109   EFI_IPSEC_PAD_ID    *Id;
 110   EFI_IPSEC_PAD_DATA  *Data;
 111   LIST_ENTRY          List;
 112 };
 113
 114 typedef struct _IPSEC_RECYCLE_CONTEXT {
 115   EFI_IPSEC_FRAGMENT_DATA *FragmentTable;
 116   UINT8                   *PayloadBuffer;
 117 } IPSEC_RECYCLE_CONTEXT;
 118
 119 //
 120 // Struct used to store the Hash and its data.
 121 //
 122 typedef struct {
 123   UINTN DataSize;
 124   UINT8 *Data;
 125 } HASH_DATA_FRAGMENT;
 126
 127 struct _IPSEC_PRIVATE_DATA {
 128   UINT32                    Signature;
 129   EFI_HANDLE                Handle;           // Virtual handle to install private prtocol
 130   EFI_HANDLE                ImageHandle;
 131   EFI_IPSEC2_PROTOCOL       IpSec;
 132   EFI_IPSEC_CONFIG_PROTOCOL IpSecConfig;
 133   BOOLEAN                   SetBySelf;
 134   LIST_ENTRY                Udp4List;
 135   UINTN                     Udp4Num;
 136   LIST_ENTRY                Udp6List;
 137   UINTN                     Udp6Num;
 138   LIST_ENTRY                Ikev1SessionList;
 139   LIST_ENTRY                Ikev1EstablishedList;
 140   LIST_ENTRY                Ikev2SessionList;
 141   LIST_ENTRY                Ikev2EstablishedList;
 142   BOOLEAN                   IsIPsecDisabling;
 143 };
 144
 145 /**
 146   This function processes the inbound traffic with IPsec.
 147
 148   It checks the received packet security property, trims the ESP/AH header, and then
 149   returns without an IPsec protected IP Header and FragmentTable.
 150
 151   @param[in]      IpVersion          The version of IP.
 152   @param[in, out] IpHead             Points to IP header containing the ESP/AH header
 153                                      to be trimed on input, and without ESP/AH header
 154                                      on return.
 155   @param[in, out] LastHead           The Last Header in IP header on return.
 156   @param[in, out] OptionsBuffer      Pointer to the options buffer.
 157   @param[in, out] OptionsLength      Length of the options buffer.
 158   @param[in, out] FragmentTable      Pointer to a list of fragments in form of IPsec
 159                                      protected on input, and without IPsec protected
 160                                      on return.
 161   @param[in, out] FragmentCount      The number of fragments.
 162   @param[out]     SpdEntry           Pointer to contain the address of SPD entry on return.
 163   @param[out]     RecycleEvent       The event for recycling of resources.
 164
 165   @retval EFI_SUCCESS              The operation was successful.
 166   @retval EFI_UNSUPPORTED          The IPSEC protocol is not supported.
 167
 168 **/
 169 EFI_STATUS
 170 IpSecProtectInboundPacket (
 171   IN     UINT8                       IpVersion,
 172   IN OUT VOID                        *IpHead,
 173   IN OUT UINT8                       *LastHead,
 174   IN OUT VOID                        **OptionsBuffer,
 175   IN OUT UINT32                      *OptionsLength,
 176   IN OUT EFI_IPSEC_FRAGMENT_DATA     **FragmentTable,
 177   IN OUT UINT32                      *FragmentCount,
 178      OUT EFI_IPSEC_SPD_SELECTOR      **SpdEntry,
 179      OUT EFI_EVENT                   *RecycleEvent
 180   );
 181
 182
 183 /**
 184   This fucntion processes the output traffic with IPsec.
 185
 186   It protected the sending packet by encrypting it payload and inserting ESP/AH header
 187   in the orginal IP header, then return the IpHeader and IPsec protected Fragmentable.
 188
 189   @param[in]      IpVersion          The version of IP.
 190   @param[in, out] IpHead             Point to IP header containing the orginal IP header
 191                                      to be processed on input, and inserted ESP/AH header
 192                                      on return.
 193   @param[in, out] LastHead           The Last Header in IP header.
 194   @param[in, out] OptionsBuffer      Pointer to the options buffer.
 195   @param[in, out] OptionsLength      Length of the options buffer.
 196   @param[in, out] FragmentTable      Pointer to a list of fragments to be protected by
 197                                      IPsec on input, and with IPsec protected
 198                                      on return.
 199   @param[in, out] FragmentCount      Number of fragments.
 200   @param[in]      SadEntry           Related SAD entry.
 201   @param[out]     RecycleEvent       Event for recycling of resources.
 202
 203   @retval EFI_SUCCESS              The operation is successful.
 204   @retval EFI_UNSUPPORTED          If the IPSEC protocol is not supported.
 205
 206 **/
 207 EFI_STATUS
 208 IpSecProtectOutboundPacket (
 209   IN     UINT8                       IpVersion,
 210   IN OUT VOID                        *IpHead,
 211   IN OUT UINT8                       *LastHead,
 212   IN OUT VOID                        **OptionsBuffer,
 213   IN OUT UINT32                      *OptionsLength,
 214   IN OUT EFI_IPSEC_FRAGMENT_DATA     **FragmentTable,
 215   IN OUT UINT32                      *FragmentCount,
 216   IN     IPSEC_SAD_ENTRY             *SadEntry,
 217      OUT EFI_EVENT                   *RecycleEvent
 218   );
 219
 220 /**
 221   Check if the IP Address in the address range of AddressInfos specified.
 222
 223   @param[in]  IpVersion         The IP version.
 224   @param[in]  IpAddr            Points to EFI_IP_ADDRESS to be check.
 225   @param[in]  AddressInfo       A list of EFI_IP_ADDRESS_INFO that is used to check
 226                                 the IP Address is matched.
 227   @param[in]  AddressCount      The total numbers of the AddressInfo.
 228
 229   @retval   TRUE    If the Specified IP Address is in the range of the AddressInfos specified.
 230   @retval   FALSE   If the Specified IP Address is not in the range of the AddressInfos specified.
 231
 232 **/
 233 BOOLEAN
 234 IpSecMatchIpAddress (
 235   IN UINT8                                  IpVersion,
 236   IN EFI_IP_ADDRESS                         *IpAddr,
 237   IN EFI_IP_ADDRESS_INFO                    *AddressInfo,
 238   IN UINT32                                 AddressCount
 239   );
 240
 241 /**
 242   Find a PAD entry according to remote IP address.
 243
 244   @param[in]  IpVersion         The version of IP.
 245   @param[in]  IpAddr            Point to remote IP address.
 246
 247   @return The pointer of related PAD entry.
 248
 249 **/
 250 IPSEC_PAD_ENTRY *
 251 IpSecLookupPadEntry (
 252   IN UINT8                                  IpVersion,
 253   IN EFI_IP_ADDRESS                         *IpAddr
 254   );
 255
 256 /**
 257   Check if the specified IP packet can be serviced by this SPD entry.
 258
 259   @param[in]  SpdEntry          Point to SPD entry.
 260   @param[in]  IpVersion         Version of IP.
 261   @param[in]  IpHead            Point to IP header.
 262   @param[in]  IpPayload         Point to IP payload.
 263   @param[in]  Protocol          The Last protocol of IP packet.
 264   @param[in]  IsOutbound        Traffic direction.
 265   @param[out] Action            The support action of SPD entry.
 266
 267   @retval EFI_SUCCESS       Find the related SPD.
 268   @retval EFI_NOT_FOUND     Not find the related SPD entry;
 269
 270 **/
 271 EFI_STATUS
 272 IpSecLookupSpdEntry (
 273   IN     IPSEC_SPD_ENTRY         *SpdEntry,
 274   IN     UINT8                   IpVersion,
 275   IN     VOID                    *IpHead,
 276   IN     UINT8                   *IpPayload,
 277   IN     UINT8                   Protocol,
 278   IN     BOOLEAN                 IsOutbound,
 279      OUT EFI_IPSEC_ACTION        *Action
 280   );
 281
 282 /**
 283   Look up if there is existing SAD entry for specified IP packet sending.
 284
 285   This function is called by the IPsecProcess when there is some IP packet needed to
 286   send out. This function checks if there is an existing SAD entry that can be serviced
 287   to this IP packet sending. If no existing SAD entry could be used, this
 288   function will invoke an IPsec Key Exchange Negotiation.
 289
 290   @param[in]  Private           Points to private data.
 291   @param[in]  NicHandle         Points to a NIC handle.
 292   @param[in]  IpVersion         The version of IP.
 293   @param[in]  IpHead            The IP Header of packet to be sent out.
 294   @param[in]  IpPayload         The IP Payload to be sent out.
 295   @param[in]  OldLastHead       The Last protocol of the IP packet.
 296   @param[in]  SpdEntry          Points to a related SPD entry.
 297   @param[out] SadEntry          Contains the Point of a related SAD entry.
 298
 299   @retval EFI_DEVICE_ERROR  One of following conditions is TRUE:
 300                             - If don't find related UDP service.
 301                             - Sequence Number is used up.
 302                             - Extension Sequence Number is used up.
 303   @retval EFI_NOT_READY     No existing SAD entry could be used.
 304   @retval EFI_SUCCESS       Find the related SAD entry.
 305
 306 **/
 307 EFI_STATUS
 308 IpSecLookupSadEntry (
 309   IN IPSEC_PRIVATE_DATA      *Private,
 310   IN EFI_HANDLE              NicHandle,
 311   IN UINT8                   IpVersion,
 312   IN VOID                    *IpHead,
 313   IN UINT8                   *IpPayload,
 314   IN UINT8                   OldLastHead,
 315   IN IPSEC_SPD_ENTRY         *SpdEntry,
 316   OUT IPSEC_SAD_ENTRY        **SadEntry
 317   );
 318
 319 /**
 320   Find the SAD through whole SAD list.
 321
 322   @param[in]  Spi               The SPI used to search the SAD entry.
 323   @param[in]  DestAddress       The destination used to search the SAD entry.
 324   @param[in]  IpVersion         The IP version. Ip4 or Ip6.
 325
 326   @return  The pointer to a certain SAD entry.
 327
 328 **/
 329 IPSEC_SAD_ENTRY *
 330 IpSecLookupSadBySpi (
 331   IN UINT32                                 Spi,
 332   IN EFI_IP_ADDRESS                         *DestAddress,
 333   IN UINT8                                  IpVersion
 334   )
 335 ;
 336
 337 /**
 338   Handles IPsec packet processing for inbound and outbound IP packets.
 339
 340   The EFI_IPSEC_PROCESS process routine handles each inbound or outbound packet.
 341   The behavior is that it can perform one of the following actions:
 342   bypass the packet, discard the packet, or protect the packet.
 343
 344   @param[in]      This             Pointer to the EFI_IPSEC2_PROTOCOL instance.
 345   @param[in]      NicHandle        Instance of the network interface.
 346   @param[in]      IpVersion        IPV4 or IPV6.
 347   @param[in, out] IpHead           Pointer to the IP Header.
 348   @param[in, out] LastHead         The protocol of the next layer to be processed by IPsec.
 349   @param[in, out] OptionsBuffer    Pointer to the options buffer.
 350   @param[in, out] OptionsLength    Length of the options buffer.
 351   @param[in, out] FragmentTable    Pointer to a list of fragments.
 352   @param[in, out] FragmentCount    Number of fragments.
 353   @param[in]      TrafficDirection Traffic direction.
 354   @param[out]     RecycleSignal    Event for recycling of resources.
 355
 356   @retval EFI_SUCCESS              The packet was bypassed and all buffers remain the same.
 357   @retval EFI_SUCCESS              The packet was protected.
 358   @retval EFI_ACCESS_DENIED        The packet was discarded.
 359
 360 **/
 361 EFI_STATUS
 362 EFIAPI
 363 IpSecProcess (
 364   IN     EFI_IPSEC2_PROTOCOL              *This,
 365   IN     EFI_HANDLE                      NicHandle,
 366   IN     UINT8                           IpVersion,
 367   IN OUT VOID                            *IpHead,
 368   IN OUT UINT8                           *LastHead,
 369   IN OUT VOID                            **OptionsBuffer,
 370   IN OUT UINT32                          *OptionsLength,
 371   IN OUT EFI_IPSEC_FRAGMENT_DATA         **FragmentTable,
 372   IN OUT UINT32                          *FragmentCount,
 373   IN     EFI_IPSEC_TRAFFIC_DIR           TrafficDirection,
 374      OUT EFI_EVENT                       *RecycleSignal
 375   );
 376
 377 extern EFI_DPC_PROTOCOL    *mDpc;
 378 extern EFI_IPSEC2_PROTOCOL  mIpSecInstance;
 379
 380 extern EFI_COMPONENT_NAME2_PROTOCOL gIpSecComponentName2;
 381 extern EFI_COMPONENT_NAME_PROTOCOL  gIpSecComponentName;
 382
 383
 384 #endif