MdePkg/Include/Protocol/IpSec.h

   1 /** @file
   2   EFI IPSEC Protocol Definition
   3   The EFI_IPSEC_PROTOCOL is used to abstract the ability to deal with the individual
   4   packets sent and received by the host and provide packet-level security for IP
   5   datagram.
   6   The EFI_IPSEC2_PROTOCOL is used to abstract the ability to deal with the individual
   7   packets sent and received by the host and provide packet-level security for IP
   8   datagram. In addition, it supports the Option (extension header) processing in
   9   IPsec which doesn't support in EFI_IPSEC_PROTOCOL. It is also recommended to
  10   use EFI_IPSEC2_PROTOCOL instead of EFI_IPSEC_PROTOCOL especially for IPsec Tunnel
  11   Mode.
  12
  13   Copyright (c) 2009 - 2010, Intel Corporation. All rights reserved.<BR>
  14   This program and the accompanying materials
  15   are licensed and made available under the terms and conditions of the BSD License
  16   which accompanies this distribution.  The full text of the license may be found at
  17   http://opensource.org/licenses/bsd-license.php
  18
  19   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  20   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  21
  22   @par Revision Reference:
  23   The EFI_IPSEC2_PROTOCOL is introduced in UEFI Specification 2.3D.
  24
  25 **/
  26
  27 #ifndef __EFI_IPSEC_PROTOCOL_H__
  28 #define __EFI_IPSEC_PROTOCOL_H__
  29
  30 #include <Protocol/IpSecConfig.h>
  31
  32 #define EFI_IPSEC_PROTOCOL_GUID \
  33   { \
  34     0xdfb386f7, 0xe100, 0x43ad, {0x9c, 0x9a, 0xed, 0x90, 0xd0, 0x8a, 0x5e, 0x12 } \
  35   }
  36
  37 #define EFI_IPSEC2_PROTOCOL_GUID \
  38   { \
  39     0xa3979e64, 0xace8, 0x4ddc, {0xbc, 0x7, 0x4d, 0x66, 0xb8, 0xfd, 0x9, 0x77 } \
  40   }
  41
  42 typedef struct _EFI_IPSEC_PROTOCOL  EFI_IPSEC_PROTOCOL;
  43 typedef struct _EFI_IPSEC2_PROTOCOL EFI_IPSEC2_PROTOCOL;
  44
  45 ///
  46 /// EFI_IPSEC_FRAGMENT_DATA
  47 /// defines the instances of packet fragments.
  48 ///
  49 typedef struct _EFI_IPSEC_FRAGMENT_DATA {
  50   UINT32  FragmentLength;
  51   VOID    *FragmentBuffer;
  52 } EFI_IPSEC_FRAGMENT_DATA;
  53
  54
  55 /**
  56   Handles IPsec packet processing for inbound and outbound IP packets.
  57
  58   The EFI_IPSEC_PROCESS process routine handles each inbound or outbound packet.
  59   The behavior is that it can perform one of the following actions:
  60   bypass the packet, discard the packet, or protect the packet.
  61
  62   @param[in]      This             Pointer to the EFI_IPSEC_PROTOCOL instance.
  63   @param[in]      NicHandle        Instance of the network interface.
  64   @param[in]      IpVer            IPV4 or IPV6.
  65   @param[in, out] IpHead           Pointer to the IP Header.
  66   @param[in]      LastHead         The protocol of the next layer to be processed by IPsec.
  67   @param[in]      OptionsBuffer    Pointer to the options buffer.
  68   @param[in]      OptionsLength    Length of the options buffer.
  69   @param[in, out] FragmentTable    Pointer to a list of fragments.
  70   @param[in]      FragmentCount    Number of fragments.
  71   @param[in]      TrafficDirection Traffic direction.
  72   @param[out]     RecycleSignal    Event for recycling of resources.
  73
  74   @retval EFI_SUCCESS              The packet was bypassed and all buffers remain the same.
  75   @retval EFI_SUCCESS              The packet was protected.
  76   @retval EFI_ACCESS_DENIED        The packet was discarded.
  77
  78 **/
  79 typedef
  80 EFI_STATUS
  81 (EFIAPI  *EFI_IPSEC_PROCESS)(
  82   IN     EFI_IPSEC_PROTOCOL      *This,
  83   IN     EFI_HANDLE              NicHandle,
  84   IN     UINT8                   IpVer,
  85   IN OUT VOID                    *IpHead,
  86   IN     UINT8                   *LastHead,
  87   IN     VOID                    *OptionsBuffer,
  88   IN     UINT32                  OptionsLength,
  89   IN OUT EFI_IPSEC_FRAGMENT_DATA **FragmentTable,
  90   IN     UINT32                  *FragmentCount,
  91   IN     EFI_IPSEC_TRAFFIC_DIR   TrafficDirection,
  92      OUT EFI_EVENT               *RecycleSignal
  93   );
  94
  95 ///
  96 /// EFI_IPSEC_PROTOCOL
  97 /// provides the ability for  securing IP communications by authenticating
  98 /// and/or encrypting each IP packet in a data stream.
  99 //  EFI_IPSEC_PROTOCOL can be consumed by both the IPv4 and IPv6 stack.
 100 //  A user can employ this protocol for IPsec package handling in both IPv4
 101 //  and IPv6 environment.
 102 ///
 103 struct _EFI_IPSEC_PROTOCOL {
 104   EFI_IPSEC_PROCESS      Process;           ///< Handle the IPsec message.
 105   EFI_EVENT              DisabledEvent;     ///< Event signaled when the interface is disabled.
 106   BOOLEAN                DisabledFlag;      ///< State of the interface.
 107 };
 108
 109 /**
 110   Handles IPsec processing for both inbound and outbound IP packets. Compare with
 111   Process() in EFI_IPSEC_PROTOCOL, this interface has the capability to process
 112   Option(Extension Header).
 113
 114   The EFI_IPSEC2_PROCESS process routine handles each inbound or outbound packet.
 115   The behavior is that it can perform one of the following actions:
 116   bypass the packet, discard the packet, or protect the packet.
 117
 118   @param[in]       This               Pointer to the EFI_IPSEC2_PROTOCOL instance.
 119   @param[in]       NicHandle          Instance of the network interface.
 120   @param[in]       IpVer              IP version.IPv4 or IPv6.
 121   @param[in, out]  IpHead             Pointer to the IP Header it is either
 122                                       the EFI_IP4_HEADER or EFI_IP6_HEADER.
 123                                       On input, it contains the IP header.
 124                                       On output, 1) in tunnel mode and the
 125                                       traffic direction is inbound, the buffer
 126                                       will be reset to zero by IPsec; 2) in
 127                                       tunnel mode and the traffic direction
 128                                       is outbound, the buffer will reset to
 129                                       be the tunnel IP header.3) in transport
 130                                       mode, the related fielders (like payload
 131                                       length, Next header) in IP header will
 132                                       be modified according to the condition.
 133   @param[in, out]  LastHead           For IP4, it is the next protocol in IP
 134                                       header. For IP6 it is the Next Header
 135                                       of the last extension header.
 136   @param[in, out]  OptionsBuffer      On input, it contains the options
 137                                       (extensions header) to be processed by
 138                                       IPsec. On output, 1) in tunnel mode and
 139                                       the traffic direction is outbound, it
 140                                       will be set to NULL, and that means this
 141                                       contents was wrapped after inner header
 142                                       and should not be concatenated after
 143                                       tunnel header again; 2) in transport
 144                                       mode and the traffic direction is inbound,
 145                                       if there are IP options (extension headers)
 146                                       protected by IPsec, IPsec will concatenate
 147                                       the those options after the input options
 148                                       (extension headers); 3) on other situations,
 149                                       the output of contents of OptionsBuffer
 150                                       might be same with input's. The caller
 151                                       should take the responsibility to free
 152                                       the buffer both on input and on output.
 153   @param[in, out]  OptionsLength      On input, the input length of the options
 154                                       buffer. On output, the output length of
 155                                       the options buffer.
 156   @param[in, out]  FragmentTable      Pointer to a list of fragments. On input,
 157                                       these fragments contain the IP payload.
 158                                       On output, 1) in tunnel mode and the traffic
 159                                       direction is inbound, the fragments contain
 160                                       the whole IP payload which is from the
 161                                       IP inner header to the last byte of the
 162                                       packet; 2) in tunnel mode and the traffic
 163                                       direction is the outbound, the fragments
 164                                       contains the whole encapsulated payload
 165                                       which encapsulates the whole IP payload
 166                                       between the encapsulated header and
 167                                       encapsulated trailer fields. 3) in transport
 168                                       mode and the traffic direction is inbound,
 169                                       the fragments contains the IP payload
 170                                       which is from the next layer protocol to
 171                                       the last byte of the packet; 4) in transport
 172                                       mode and the traffic direction is outbound,
 173                                       the fragments contains the whole encapsulated
 174                                       payload which encapsulates the next layer
 175                                       protocol information between the encapsulated
 176                                       header and encapsulated trailer fields.
 177   @param[in, out]  FragmentCount      Number of fragments.
 178   @param[in]       TrafficDirection   Traffic direction.
 179   @param[out]      RecycleSignal      Event for recycling of resources.
 180
 181   @retval      EFI_SUCCESS           The packet was processed by IPsec successfully.
 182   @retval      EFI_ACCESS_DENIED     The packet was discarded.
 183   @retval      EFI_NOT_READY         The IKE negotiation is invoked and the packet
 184                                      was discarded.
 185   @retval      EFI_INVALID_PARAMETER One or more of following are TRUE:
 186                                      If OptionsBuffer is NULL;
 187                                      If OptionsLength is NULL;
 188                                      If FragmentTable is NULL;
 189                                      If FragmentCount is NULL.
 190
 191 **/
 192 typedef
 193 EFI_STATUS
 194 (EFIAPI *EFI_IPSEC_PROCESSEXT) (
 195   IN EFI_IPSEC2_PROTOCOL         *This,
 196   IN EFI_HANDLE                  NicHandle,
 197   IN UINT8                       IpVer,
 198   IN OUT VOID                    *IpHead,
 199   IN OUT UINT8                   *LastHead,
 200   IN OUT VOID                    **OptionsBuffer,
 201   IN OUT UINT32                  *OptionsLength,
 202   IN OUT EFI_IPSEC_FRAGMENT_DATA **FragmentTable,
 203   IN OUT UINT32                  *FragmentCount,
 204   IN EFI_IPSEC_TRAFFIC_DIR       TrafficDirection,
 205      OUT EFI_EVENT               *RecycleSignal
 206   );
 207
 208 ///
 209 /// EFI_IPSEC2_PROTOCOL
 210 /// supports the Option (extension header) processing in IPsec which doesn't support
 211 /// in EFI_IPSEC_PROTOCOL. It is also recommended to use EFI_IPSEC2_PROTOCOL instead
 212 /// of EFI_IPSEC_PROTOCOL especially for IPsec Tunnel Mode.
 213 /// provides the ability for securing IP communications by authenticating and/or
 214 /// encrypting each IP packet in a data stream.
 215 ///
 216 struct _EFI_IPSEC2_PROTOCOL {
 217 EFI_IPSEC_PROCESSEXT ProcessExt;
 218 EFI_EVENT            DisabledEvent;
 219 BOOLEAN              DisabledFlag;
 220 };
 221
 222 extern EFI_GUID gEfiIpSecProtocolGuid;
 223 extern EFI_GUID gEfiIpSec2ProtocolGuid;
 224 #endif