[mirror_edk2.git] / NetworkPkg / HttpDxe / HttpsSupport.h

/** @file\r
  The header files of miscellaneous routines specific to Https for HttpDxe driver.\r
\r
Copyright (c) 2016 - 2018, Intel Corporation. All rights reserved.<BR>\r
SPDX-License-Identifier: BSD-2-Clause-Patent\r
\r
**/\r
\r
#ifndef __EFI_HTTPS_SUPPORT_H__\r
#define __EFI_HTTPS_SUPPORT_H__\r
\r
#define HTTPS_DEFAULT_PORT  443\r
\r
#define HTTPS_FLAG  "https://"\r
\r
/**\r
  Check whether the Url is from Https.\r
\r
  @param[in]    Url             The pointer to a HTTP or HTTPS URL string.\r
\r
  @retval TRUE                  The Url is from HTTPS.\r
  @retval FALSE                 The Url is from HTTP.\r
\r
**/\r
BOOLEAN\r
IsHttpsUrl (\r
  IN CHAR8  *Url\r
  );\r
\r
/**\r
  Creates a Tls child handle, open EFI_TLS_PROTOCOL and EFI_TLS_CONFIGURATION_PROTOCOL.\r
\r
  @param[in]  ImageHandle           The firmware allocated handle for the UEFI image.\r
  @param[out] TlsSb                 Pointer to the TLS SERVICE_BINDING_PROTOCOL.\r
  @param[out] TlsProto              Pointer to the EFI_TLS_PROTOCOL instance.\r
  @param[out] TlsConfiguration      Pointer to the EFI_TLS_CONFIGURATION_PROTOCOL instance.\r
\r
  @return  The child handle with opened EFI_TLS_PROTOCOL and EFI_TLS_CONFIGURATION_PROTOCOL.\r
\r
**/\r
EFI_HANDLE\r
EFIAPI\r
TlsCreateChild (\r
  IN  EFI_HANDLE                      ImageHandle,\r
  OUT EFI_SERVICE_BINDING_PROTOCOL    **TlsSb,\r
  OUT EFI_TLS_PROTOCOL                **TlsProto,\r
  OUT EFI_TLS_CONFIGURATION_PROTOCOL  **TlsConfiguration\r
  );\r
\r
/**\r
  Create event for the TLS receive and transmit tokens which are used to receive and\r
  transmit TLS related messages.\r
\r
  @param[in, out]  HttpInstance       Pointer to HTTP_PROTOCOL structure.\r
\r
  @retval EFI_SUCCESS            The events are created successfully.\r
  @retval others                 Other error as indicated.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
TlsCreateTxRxEvent (\r
  IN OUT HTTP_PROTOCOL  *HttpInstance\r
  );\r
\r
/**\r
  Close events in the TlsTxToken and TlsRxToken.\r
\r
  @param[in]  HttpInstance   Pointer to HTTP_PROTOCOL structure.\r
\r
**/\r
VOID\r
EFIAPI\r
TlsCloseTxRxEvent (\r
  IN  HTTP_PROTOCOL  *HttpInstance\r
  );\r
\r
/**\r
  Read the TlsCaCertificate variable and configure it.\r
\r
  @param[in, out]  HttpInstance       The HTTP instance private data.\r
\r
  @retval EFI_SUCCESS            TlsCaCertificate is configured.\r
  @retval EFI_OUT_OF_RESOURCES   Can't allocate memory resources.\r
  @retval EFI_NOT_FOUND          Fail to get "TlsCaCertificate" variable.\r
  @retval Others                 Other error as indicated.\r
\r
**/\r
EFI_STATUS\r
TlsConfigCertificate (\r
  IN OUT HTTP_PROTOCOL  *HttpInstance\r
  );\r
\r
/**\r
  Configure TLS session data.\r
\r
  @param[in, out]  HttpInstance       The HTTP instance private data.\r
\r
  @retval EFI_SUCCESS            TLS session data is configured.\r
  @retval Others                 Other error as indicated.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
TlsConfigureSession (\r
  IN OUT HTTP_PROTOCOL  *HttpInstance\r
  );\r
\r
/**\r
  Transmit the Packet by processing the associated HTTPS token.\r
\r
  @param[in, out]   HttpInstance    Pointer to HTTP_PROTOCOL structure.\r
  @param[in]        Packet          The packet to transmit.\r
\r
  @retval EFI_SUCCESS            The packet is transmitted.\r
  @retval EFI_INVALID_PARAMETER  HttpInstance is NULL or Packet is NULL.\r
  @retval EFI_OUT_OF_RESOURCES   Can't allocate memory resources.\r
  @retval EFI_DEVICE_ERROR       An unexpected system or network error occurred.\r
  @retval Others                 Other errors as indicated.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
TlsCommonTransmit (\r
  IN OUT HTTP_PROTOCOL  *HttpInstance,\r
  IN     NET_BUF        *Packet\r
  );\r
\r
/**\r
  Receive the Packet by processing the associated HTTPS token.\r
\r
  @param[in, out]   HttpInstance    Pointer to HTTP_PROTOCOL structure.\r
  @param[in]        Packet          The packet to transmit.\r
  @param[in]        Timeout         The time to wait for connection done.\r
\r
  @retval EFI_SUCCESS            The Packet is received.\r
  @retval EFI_INVALID_PARAMETER  HttpInstance is NULL or Packet is NULL.\r
  @retval EFI_OUT_OF_RESOURCES   Can't allocate memory resources.\r
  @retval EFI_TIMEOUT            The operation is time out.\r
  @retval Others                 Other error as indicated.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
TlsCommonReceive (\r
  IN OUT HTTP_PROTOCOL  *HttpInstance,\r
  IN     NET_BUF        *Packet,\r
  IN     EFI_EVENT      Timeout\r
  );\r
\r
/**\r
  Receive one TLS PDU. An TLS PDU contains an TLS record header and its\r
  corresponding record data. These two parts will be put into two blocks of buffers in the\r
  net buffer.\r
\r
  @param[in, out]      HttpInstance    Pointer to HTTP_PROTOCOL structure.\r
  @param[out]          Pdu             The received TLS PDU.\r
  @param[in]           Timeout         The time to wait for connection done.\r
\r
  @retval EFI_SUCCESS          An TLS PDU is received.\r
  @retval EFI_OUT_OF_RESOURCES Can't allocate memory resources.\r
  @retval EFI_PROTOCOL_ERROR   An unexpected TLS packet was received.\r
  @retval Others               Other errors as indicated.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
TlsReceiveOnePdu (\r
  IN OUT HTTP_PROTOCOL  *HttpInstance,\r
  OUT NET_BUF           **Pdu,\r
  IN     EFI_EVENT      Timeout\r
  );\r
\r
/**\r
  Connect one TLS session by finishing the TLS handshake process.\r
\r
  @param[in]  HttpInstance       The HTTP instance private data.\r
  @param[in]  Timeout            The time to wait for connection done.\r
\r
  @retval EFI_SUCCESS            The TLS session is established.\r
  @retval EFI_OUT_OF_RESOURCES   Can't allocate memory resources.\r
  @retval EFI_ABORTED            TLS session state is incorrect.\r
  @retval Others                 Other error as indicated.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
TlsConnectSession (\r
  IN  HTTP_PROTOCOL  *HttpInstance,\r
  IN  EFI_EVENT      Timeout\r
  );\r
\r
/**\r
  Close the TLS session and send out the close notification message.\r
\r
  @param[in]  HttpInstance       The HTTP instance private data.\r
\r
  @retval EFI_SUCCESS            The TLS session is closed.\r
  @retval EFI_INVALID_PARAMETER  HttpInstance is NULL or Packet is NULL.\r
  @retval EFI_OUT_OF_RESOURCES   Can't allocate memory resources.\r
  @retval Others                 Other error as indicated.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
TlsCloseSession (\r
  IN  HTTP_PROTOCOL  *HttpInstance\r
  );\r
\r
/**\r
  Process one message according to the CryptMode.\r
\r
  @param[in]           HttpInstance    Pointer to HTTP_PROTOCOL structure.\r
  @param[in]           Message         Pointer to the message buffer needed to processed.\r
                                       If ProcessMode is EfiTlsEncrypt, the message contain the TLS\r
                                       header and plain text TLS APP payload.\r
                                       If ProcessMode is EfiTlsDecrypt, the message contain the TLS\r
                                       header and cipher text TLS APP payload.\r
  @param[in]           MessageSize     Pointer to the message buffer size.\r
  @param[in]           ProcessMode     Process mode.\r
  @param[in, out]      Fragment        Only one Fragment returned after the Message is\r
                                       processed successfully.\r
                                       If ProcessMode is EfiTlsEncrypt, the fragment contain the TLS\r
                                       header and cipher text TLS APP payload.\r
                                       If ProcessMode is EfiTlsDecrypt, the fragment contain the TLS\r
                                       header and plain text TLS APP payload.\r
\r
  @retval EFI_SUCCESS          Message is processed successfully.\r
  @retval EFI_OUT_OF_RESOURCES   Can't allocate memory resources.\r
  @retval Others               Other errors as indicated.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
TlsProcessMessage (\r
  IN     HTTP_PROTOCOL       *HttpInstance,\r
  IN     UINT8               *Message,\r
  IN     UINTN               MessageSize,\r
  IN     EFI_TLS_CRYPT_MODE  ProcessMode,\r
  IN OUT NET_FRAGMENT        *Fragment\r
  );\r
\r
/**\r
  Receive one fragment decrypted from one TLS record.\r
\r
  @param[in]           HttpInstance    Pointer to HTTP_PROTOCOL structure.\r
  @param[in, out]      Fragment        The received Fragment.\r
  @param[in]           Timeout         The time to wait for connection done.\r
\r
  @retval EFI_SUCCESS          One fragment is received.\r
  @retval EFI_OUT_OF_RESOURCES Can't allocate memory resources.\r
  @retval EFI_ABORTED          Something wrong decryption the message.\r
  @retval Others               Other errors as indicated.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
HttpsReceive (\r
  IN     HTTP_PROTOCOL  *HttpInstance,\r
  IN OUT NET_FRAGMENT   *Fragment,\r
  IN     EFI_EVENT      Timeout\r
  );\r
\r
#endif\r
Commit	Line	Data
7618784b HW	1	/** @file\r
	2	The header files of miscellaneous routines specific to Https for HttpDxe driver.\r
	3	\r
07bd82d4	4	Copyright (c) 2016 - 2018, Intel Corporation. All rights reserved.<BR>\r
ecf98fbc	5	SPDX-License-Identifier: BSD-2-Clause-Patent\r
7618784b HW	6	\r
	7	**/\r
	8	\r
	9	#ifndef __EFI_HTTPS_SUPPORT_H__\r
	10	#define __EFI_HTTPS_SUPPORT_H__\r
	11	\r
d1050b9d	12	#define HTTPS_DEFAULT_PORT 443\r
7618784b	13	\r
d1050b9d	14	#define HTTPS_FLAG "https://"\r
7618784b HW	15	\r
	16	/**\r
	17	Check whether the Url is from Https.\r
	18	\r
	19	@param[in] Url The pointer to a HTTP or HTTPS URL string.\r
	20	\r
	21	@retval TRUE The Url is from HTTPS.\r
	22	@retval FALSE The Url is from HTTP.\r
	23	\r
	24	**/\r
	25	BOOLEAN\r
	26	IsHttpsUrl (\r
d1050b9d	27	IN CHAR8 *Url\r
7618784b HW	28	);\r
	29	\r
	30	/**\r
	31	Creates a Tls child handle, open EFI_TLS_PROTOCOL and EFI_TLS_CONFIGURATION_PROTOCOL.\r
	32	\r
	33	@param[in] ImageHandle The firmware allocated handle for the UEFI image.\r
45ea8a0c	34	@param[out] TlsSb Pointer to the TLS SERVICE_BINDING_PROTOCOL.\r
7618784b HW	35	@param[out] TlsProto Pointer to the EFI_TLS_PROTOCOL instance.\r
	36	@param[out] TlsConfiguration Pointer to the EFI_TLS_CONFIGURATION_PROTOCOL instance.\r
	37	\r
	38	@return The child handle with opened EFI_TLS_PROTOCOL and EFI_TLS_CONFIGURATION_PROTOCOL.\r
	39	\r
	40	**/\r
	41	EFI_HANDLE\r
	42	EFIAPI\r
	43	TlsCreateChild (\r
d1050b9d MK	44	IN EFI_HANDLE ImageHandle,\r
	45	OUT EFI_SERVICE_BINDING_PROTOCOL **TlsSb,\r
	46	OUT EFI_TLS_PROTOCOL **TlsProto,\r
	47	OUT EFI_TLS_CONFIGURATION_PROTOCOL **TlsConfiguration\r
7618784b HW	48	);\r
	49	\r
	50	/**\r
	51	Create event for the TLS receive and transmit tokens which are used to receive and\r
	52	transmit TLS related messages.\r
	53	\r
	54	@param[in, out] HttpInstance Pointer to HTTP_PROTOCOL structure.\r
	55	\r
	56	@retval EFI_SUCCESS The events are created successfully.\r
	57	@retval others Other error as indicated.\r
	58	\r
	59	**/\r
	60	EFI_STATUS\r
	61	EFIAPI\r
	62	TlsCreateTxRxEvent (\r
d1050b9d	63	IN OUT HTTP_PROTOCOL *HttpInstance\r
7618784b HW	64	);\r
	65	\r
	66	/**\r
	67	Close events in the TlsTxToken and TlsRxToken.\r
	68	\r
	69	@param[in] HttpInstance Pointer to HTTP_PROTOCOL structure.\r
	70	\r
	71	**/\r
	72	VOID\r
	73	EFIAPI\r
	74	TlsCloseTxRxEvent (\r
d1050b9d	75	IN HTTP_PROTOCOL *HttpInstance\r
7618784b HW	76	);\r
	77	\r
	78	/**\r
	79	Read the TlsCaCertificate variable and configure it.\r
	80	\r
	81	@param[in, out] HttpInstance The HTTP instance private data.\r
	82	\r
	83	@retval EFI_SUCCESS TlsCaCertificate is configured.\r
	84	@retval EFI_OUT_OF_RESOURCES Can't allocate memory resources.\r
	85	@retval EFI_NOT_FOUND Fail to get "TlsCaCertificate" variable.\r
	86	@retval Others Other error as indicated.\r
	87	\r
	88	**/\r
	89	EFI_STATUS\r
	90	TlsConfigCertificate (\r
d1050b9d	91	IN OUT HTTP_PROTOCOL *HttpInstance\r
7618784b HW	92	);\r
	93	\r
	94	/**\r
	95	Configure TLS session data.\r
	96	\r
	97	@param[in, out] HttpInstance The HTTP instance private data.\r
	98	\r
	99	@retval EFI_SUCCESS TLS session data is configured.\r
	100	@retval Others Other error as indicated.\r
	101	\r
	102	**/\r
	103	EFI_STATUS\r
	104	EFIAPI\r
	105	TlsConfigureSession (\r
d1050b9d	106	IN OUT HTTP_PROTOCOL *HttpInstance\r
7618784b HW	107	);\r
	108	\r
	109	/**\r
	110	Transmit the Packet by processing the associated HTTPS token.\r
	111	\r
	112	@param[in, out] HttpInstance Pointer to HTTP_PROTOCOL structure.\r
	113	@param[in] Packet The packet to transmit.\r
	114	\r
	115	@retval EFI_SUCCESS The packet is transmitted.\r
	116	@retval EFI_INVALID_PARAMETER HttpInstance is NULL or Packet is NULL.\r
	117	@retval EFI_OUT_OF_RESOURCES Can't allocate memory resources.\r
	118	@retval EFI_DEVICE_ERROR An unexpected system or network error occurred.\r
	119	@retval Others Other errors as indicated.\r
	120	\r
	121	**/\r
	122	EFI_STATUS\r
	123	EFIAPI\r
	124	TlsCommonTransmit (\r
d1050b9d MK	125	IN OUT HTTP_PROTOCOL *HttpInstance,\r
d1050b9d MK	126	IN NET_BUF *Packet\r
7618784b HW	127	);\r
	128	\r
	129	/**\r
	130	Receive the Packet by processing the associated HTTPS token.\r
	131	\r
	132	@param[in, out] HttpInstance Pointer to HTTP_PROTOCOL structure.\r
	133	@param[in] Packet The packet to transmit.\r
	134	@param[in] Timeout The time to wait for connection done.\r
	135	\r
	136	@retval EFI_SUCCESS The Packet is received.\r
	137	@retval EFI_INVALID_PARAMETER HttpInstance is NULL or Packet is NULL.\r
	138	@retval EFI_OUT_OF_RESOURCES Can't allocate memory resources.\r
	139	@retval EFI_TIMEOUT The operation is time out.\r
	140	@retval Others Other error as indicated.\r
	141	\r
	142	**/\r
	143	EFI_STATUS\r
	144	EFIAPI\r
	145	TlsCommonReceive (\r
d1050b9d MK	146	IN OUT HTTP_PROTOCOL *HttpInstance,\r
	147	IN NET_BUF *Packet,\r
	148	IN EFI_EVENT Timeout\r
7618784b HW	149	);\r
	150	\r
	151	/**\r
ba3b642d	152	Receive one TLS PDU. An TLS PDU contains an TLS record header and its\r
7618784b HW	153	corresponding record data. These two parts will be put into two blocks of buffers in the\r
	154	net buffer.\r
	155	\r
	156	@param[in, out] HttpInstance Pointer to HTTP_PROTOCOL structure.\r
	157	@param[out] Pdu The received TLS PDU.\r
	158	@param[in] Timeout The time to wait for connection done.\r
	159	\r
	160	@retval EFI_SUCCESS An TLS PDU is received.\r
	161	@retval EFI_OUT_OF_RESOURCES Can't allocate memory resources.\r
	162	@retval EFI_PROTOCOL_ERROR An unexpected TLS packet was received.\r
	163	@retval Others Other errors as indicated.\r
	164	\r
	165	**/\r
	166	EFI_STATUS\r
	167	EFIAPI\r
	168	TlsReceiveOnePdu (\r
d1050b9d MK	169	IN OUT HTTP_PROTOCOL *HttpInstance,\r
	170	OUT NET_BUF **Pdu,\r
	171	IN EFI_EVENT Timeout\r
7618784b HW	172	);\r
	173	\r
	174	/**\r
	175	Connect one TLS session by finishing the TLS handshake process.\r
	176	\r
	177	@param[in] HttpInstance The HTTP instance private data.\r
	178	@param[in] Timeout The time to wait for connection done.\r
	179	\r
	180	@retval EFI_SUCCESS The TLS session is established.\r
	181	@retval EFI_OUT_OF_RESOURCES Can't allocate memory resources.\r
	182	@retval EFI_ABORTED TLS session state is incorrect.\r
	183	@retval Others Other error as indicated.\r
	184	\r
	185	**/\r
	186	EFI_STATUS\r
	187	EFIAPI\r
	188	TlsConnectSession (\r
d1050b9d MK	189	IN HTTP_PROTOCOL *HttpInstance,\r
d1050b9d MK	190	IN EFI_EVENT Timeout\r
7618784b HW	191	);\r
	192	\r
	193	/**\r
	194	Close the TLS session and send out the close notification message.\r
	195	\r
	196	@param[in] HttpInstance The HTTP instance private data.\r
	197	\r
	198	@retval EFI_SUCCESS The TLS session is closed.\r
	199	@retval EFI_INVALID_PARAMETER HttpInstance is NULL or Packet is NULL.\r
	200	@retval EFI_OUT_OF_RESOURCES Can't allocate memory resources.\r
	201	@retval Others Other error as indicated.\r
	202	\r
	203	**/\r
	204	EFI_STATUS\r
	205	EFIAPI\r
	206	TlsCloseSession (\r
d1050b9d	207	IN HTTP_PROTOCOL *HttpInstance\r
7618784b HW	208	);\r
	209	\r
	210	/**\r
	211	Process one message according to the CryptMode.\r
	212	\r
	213	@param[in] HttpInstance Pointer to HTTP_PROTOCOL structure.\r
f75a7f56	214	@param[in] Message Pointer to the message buffer needed to processed.\r
07bd82d4 JW	215	If ProcessMode is EfiTlsEncrypt, the message contain the TLS\r
07bd82d4 JW	216	header and plain text TLS APP payload.\r
f75a7f56	217	If ProcessMode is EfiTlsDecrypt, the message contain the TLS\r
07bd82d4	218	header and cipher text TLS APP payload.\r
7618784b HW	219	@param[in] MessageSize Pointer to the message buffer size.\r
	220	@param[in] ProcessMode Process mode.\r
	221	@param[in, out] Fragment Only one Fragment returned after the Message is\r
	222	processed successfully.\r
f75a7f56	223	If ProcessMode is EfiTlsEncrypt, the fragment contain the TLS\r
07bd82d4	224	header and cipher text TLS APP payload.\r
f75a7f56	225	If ProcessMode is EfiTlsDecrypt, the fragment contain the TLS\r
07bd82d4	226	header and plain text TLS APP payload.\r
7618784b HW	227	\r
	228	@retval EFI_SUCCESS Message is processed successfully.\r
	229	@retval EFI_OUT_OF_RESOURCES Can't allocate memory resources.\r
	230	@retval Others Other errors as indicated.\r
	231	\r
	232	**/\r
	233	EFI_STATUS\r
	234	EFIAPI\r
	235	TlsProcessMessage (\r
d1050b9d MK	236	IN HTTP_PROTOCOL *HttpInstance,\r
	237	IN UINT8 *Message,\r
	238	IN UINTN MessageSize,\r
	239	IN EFI_TLS_CRYPT_MODE ProcessMode,\r
	240	IN OUT NET_FRAGMENT *Fragment\r
7618784b HW	241	);\r
	242	\r
	243	/**\r
	244	Receive one fragment decrypted from one TLS record.\r
	245	\r
	246	@param[in] HttpInstance Pointer to HTTP_PROTOCOL structure.\r
	247	@param[in, out] Fragment The received Fragment.\r
	248	@param[in] Timeout The time to wait for connection done.\r
	249	\r
	250	@retval EFI_SUCCESS One fragment is received.\r
	251	@retval EFI_OUT_OF_RESOURCES Can't allocate memory resources.\r
	252	@retval EFI_ABORTED Something wrong decryption the message.\r
	253	@retval Others Other errors as indicated.\r
	254	\r
	255	**/\r
	256	EFI_STATUS\r
	257	EFIAPI\r
	258	HttpsReceive (\r
d1050b9d MK	259	IN HTTP_PROTOCOL *HttpInstance,\r
	260	IN OUT NET_FRAGMENT *Fragment,\r
	261	IN EFI_EVENT Timeout\r
7618784b HW	262	);\r
	263	\r
	264	#endif\r