[mirror_edk2.git] / MdePkg / Include / Protocol / IpSec.h

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