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