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