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 225