NetworkPkg/HttpDxe: HTTPS support over IPv4 and IPv6
[mirror_edk2.git] / NetworkPkg / HttpDxe / HttpDriver.h
1 /** @file
2 The header files of the driver binding and service binding protocol for HttpDxe driver.
3
4 Copyright (c) 2015 - 2016, Intel Corporation. All rights reserved.<BR>
5 (C) Copyright 2016 Hewlett Packard Enterprise Development LP<BR>
6
7 This program and the accompanying materials
8 are licensed and made available under the terms and conditions of the BSD License
9 which accompanies this distribution. The full text of the license may be found at
10 http://opensource.org/licenses/bsd-license.php.
11
12 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
13 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
14
15 **/
16
17 #ifndef __EFI_HTTP_DRIVER_H__
18 #define __EFI_HTTP_DRIVER_H__
19
20 #include <Uefi.h>
21 #include <IndustryStandard/Http11.h>
22
23 //
24 // Libraries
25 //
26 #include <Library/UefiBootServicesTableLib.h>
27 #include <Library/UefiRuntimeServicesTableLib.h>
28 #include <Library/MemoryAllocationLib.h>
29 #include <Library/BaseLib.h>
30 #include <Library/UefiLib.h>
31 #include <Library/DebugLib.h>
32 #include <Library/NetLib.h>
33 #include <Library/HttpLib.h>
34 #include <Library/DpcLib.h>
35
36 //
37 // UEFI Driver Model Protocols
38 //
39 #include <Protocol/DriverBinding.h>
40 #include <Protocol/ServiceBinding.h>
41 #include <Protocol/ComponentName2.h>
42 #include <Protocol/ComponentName.h>
43
44 //
45 // Consumed Protocols
46 //
47 #include <Protocol/HttpUtilities.h>
48 #include <Protocol/Tcp4.h>
49 #include <Protocol/Tcp6.h>
50 #include <Protocol/Dns4.h>
51 #include <Protocol/Dns6.h>
52 #include <Protocol/Ip4Config2.h>
53 #include <Protocol/Ip6Config.h>
54 #include <Protocol/Tls.h>
55 #include <Protocol/TlsConfig.h>
56
57 #include <Guid/ImageAuthentication.h>
58 //
59 // Produced Protocols
60 //
61 #include <Protocol/Http.h>
62
63 #include <Guid/TlsAuthentication.h>
64
65 #include <IndustryStandard/Tls1.h>
66
67 //
68 // Driver Version
69 //
70 #define HTTP_DRIVER_VERSION 0xa
71
72 //
73 // Protocol instances
74 //
75 extern EFI_DRIVER_BINDING_PROTOCOL gHttpDxeIp4DriverBinding;
76 extern EFI_DRIVER_BINDING_PROTOCOL gHttpDxeIp6DriverBinding;
77
78 extern EFI_COMPONENT_NAME2_PROTOCOL gHttpDxeComponentName2;
79 extern EFI_COMPONENT_NAME_PROTOCOL gHttpDxeComponentName;
80
81 extern EFI_HTTP_UTILITIES_PROTOCOL *mHttpUtilities;
82
83 //
84 // Include files with function prototypes
85 //
86 #include "ComponentName.h"
87 #include "HttpImpl.h"
88 #include "HttpProto.h"
89 #include "HttpsSupport.h"
90 #include "HttpDns.h"
91
92 typedef struct {
93 EFI_SERVICE_BINDING_PROTOCOL *ServiceBinding;
94 UINTN NumberOfChildren;
95 EFI_HANDLE *ChildHandleBuffer;
96 } HTTP_DESTROY_CHILD_IN_HANDLE_BUF_CONTEXT;
97
98 /**
99 Tests to see if this driver supports a given controller. If a child device is provided,
100 it further tests to see if this driver supports creating a handle for the specified child device.
101
102 This function checks to see if the driver specified by This supports the device specified by
103 ControllerHandle. Drivers will typically use the device path attached to
104 ControllerHandle and/or the services from the bus I/O abstraction attached to
105 ControllerHandle to determine if the driver supports ControllerHandle. This function
106 may be called many times during platform initialization. In order to reduce boot times, the tests
107 performed by this function must be very small, and take as little time as possible to execute. This
108 function must not change the state of any hardware devices, and this function must be aware that the
109 device specified by ControllerHandle may already be managed by the same driver or a
110 different driver. This function must match its calls to AllocatePages() with FreePages(),
111 AllocatePool() with FreePool(), and OpenProtocol() with CloseProtocol().
112 Because ControllerHandle may have been previously started by the same driver, if a protocol is
113 already in the opened state, then it must not be closed with CloseProtocol(). This is required
114 to guarantee the state of ControllerHandle is not modified by this function.
115
116 @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
117 @param[in] ControllerHandle The handle of the controller to test. This handle
118 must support a protocol interface that supplies
119 an I/O abstraction to the driver.
120 @param[in] RemainingDevicePath A pointer to the remaining portion of a device path. This
121 parameter is ignored by device drivers, and is optional for bus
122 drivers. For bus drivers, if this parameter is not NULL, then
123 the bus driver must determine if the bus controller specified
124 by ControllerHandle and the child controller specified
125 by RemainingDevicePath are both supported by this
126 bus driver.
127
128 @retval EFI_SUCCESS The device specified by ControllerHandle and
129 RemainingDevicePath is supported by the driver specified by This.
130 @retval EFI_ALREADY_STARTED The device specified by ControllerHandle and
131 RemainingDevicePath is already being managed by the driver
132 specified by This.
133 @retval EFI_ACCESS_DENIED The device specified by ControllerHandle and
134 RemainingDevicePath is already being managed by a different
135 driver or an application that requires exclusive access.
136 Currently not implemented.
137 @retval EFI_UNSUPPORTED The device specified by ControllerHandle and
138 RemainingDevicePath is not supported by the driver specified by This.
139 **/
140 EFI_STATUS
141 EFIAPI
142 HttpDxeIp4DriverBindingSupported (
143 IN EFI_DRIVER_BINDING_PROTOCOL *This,
144 IN EFI_HANDLE ControllerHandle,
145 IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath OPTIONAL
146 );
147
148 /**
149 Starts a device controller or a bus controller.
150
151 The Start() function is designed to be invoked from the EFI boot service ConnectController().
152 As a result, much of the error checking on the parameters to Start() has been moved into this
153 common boot service. It is legal to call Start() from other locations,
154 but the following calling restrictions must be followed, or the system behavior will not be deterministic.
155 1. ControllerHandle must be a valid EFI_HANDLE.
156 2. If RemainingDevicePath is not NULL, then it must be a pointer to a naturally aligned
157 EFI_DEVICE_PATH_PROTOCOL.
158 3. Prior to calling Start(), the Supported() function for the driver specified by This must
159 have been called with the same calling parameters, and Supported() must have returned EFI_SUCCESS.
160
161 @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
162 @param[in] ControllerHandle The handle of the controller to start. This handle
163 must support a protocol interface that supplies
164 an I/O abstraction to the driver.
165 @param[in] RemainingDevicePath A pointer to the remaining portion of a device path. This
166 parameter is ignored by device drivers, and is optional for bus
167 drivers. For a bus driver, if this parameter is NULL, then handles
168 for all the children of Controller are created by this driver.
169 If this parameter is not NULL and the first Device Path Node is
170 not the End of Device Path Node, then only the handle for the
171 child device specified by the first Device Path Node of
172 RemainingDevicePath is created by this driver.
173 If the first Device Path Node of RemainingDevicePath is
174 the End of Device Path Node, no child handle is created by this
175 driver.
176
177 @retval EFI_SUCCESS The device was started.
178 @retval EFI_DEVICE_ERROR The device could not be started due to a device error.Currently not implemented.
179 @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.
180 @retval Others The driver failded to start the device.
181
182 **/
183 EFI_STATUS
184 EFIAPI
185 HttpDxeIp4DriverBindingStart (
186 IN EFI_DRIVER_BINDING_PROTOCOL *This,
187 IN EFI_HANDLE ControllerHandle,
188 IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath OPTIONAL
189 );
190
191 /**
192 Stops a device controller or a bus controller.
193
194 The Stop() function is designed to be invoked from the EFI boot service DisconnectController().
195 As a result, much of the error checking on the parameters to Stop() has been moved
196 into this common boot service. It is legal to call Stop() from other locations,
197 but the following calling restrictions must be followed, or the system behavior will not be deterministic.
198 1. ControllerHandle must be a valid EFI_HANDLE that was used on a previous call to this
199 same driver's Start() function.
200 2. The first NumberOfChildren handles of ChildHandleBuffer must all be a valid
201 EFI_HANDLE. In addition, all of these handles must have been created in this driver's
202 Start() function, and the Start() function must have called OpenProtocol() on
203 ControllerHandle with an Attribute of EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER.
204
205 @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
206 @param[in] ControllerHandle A handle to the device being stopped. The handle must
207 support a bus specific I/O protocol for the driver
208 to use to stop the device.
209 @param[in] NumberOfChildren The number of child device handles in ChildHandleBuffer.
210 @param[in] ChildHandleBuffer An array of child handles to be freed. May be NULL
211 if NumberOfChildren is 0.
212
213 @retval EFI_SUCCESS The device was stopped.
214 @retval EFI_DEVICE_ERROR The device could not be stopped due to a device error.
215
216 **/
217 EFI_STATUS
218 EFIAPI
219 HttpDxeIp4DriverBindingStop (
220 IN EFI_DRIVER_BINDING_PROTOCOL *This,
221 IN EFI_HANDLE ControllerHandle,
222 IN UINTN NumberOfChildren,
223 IN EFI_HANDLE *ChildHandleBuffer OPTIONAL
224 );
225
226 /**
227 Tests to see if this driver supports a given controller. If a child device is provided,
228 it further tests to see if this driver supports creating a handle for the specified child device.
229
230 This function checks to see if the driver specified by This supports the device specified by
231 ControllerHandle. Drivers will typically use the device path attached to
232 ControllerHandle and/or the services from the bus I/O abstraction attached to
233 ControllerHandle to determine if the driver supports ControllerHandle. This function
234 may be called many times during platform initialization. In order to reduce boot times, the tests
235 performed by this function must be very small, and take as little time as possible to execute. This
236 function must not change the state of any hardware devices, and this function must be aware that the
237 device specified by ControllerHandle may already be managed by the same driver or a
238 different driver. This function must match its calls to AllocatePages() with FreePages(),
239 AllocatePool() with FreePool(), and OpenProtocol() with CloseProtocol().
240 Because ControllerHandle may have been previously started by the same driver, if a protocol is
241 already in the opened state, then it must not be closed with CloseProtocol(). This is required
242 to guarantee the state of ControllerHandle is not modified by this function.
243
244 @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
245 @param[in] ControllerHandle The handle of the controller to test. This handle
246 must support a protocol interface that supplies
247 an I/O abstraction to the driver.
248 @param[in] RemainingDevicePath A pointer to the remaining portion of a device path. This
249 parameter is ignored by device drivers, and is optional for bus
250 drivers. For bus drivers, if this parameter is not NULL, then
251 the bus driver must determine if the bus controller specified
252 by ControllerHandle and the child controller specified
253 by RemainingDevicePath are both supported by this
254 bus driver.
255
256 @retval EFI_SUCCESS The device specified by ControllerHandle and
257 RemainingDevicePath is supported by the driver specified by This.
258 @retval EFI_ALREADY_STARTED The device specified by ControllerHandle and
259 RemainingDevicePath is already being managed by the driver
260 specified by This.
261 @retval EFI_ACCESS_DENIED The device specified by ControllerHandle and
262 RemainingDevicePath is already being managed by a different
263 driver or an application that requires exclusive access.
264 Currently not implemented.
265 @retval EFI_UNSUPPORTED The device specified by ControllerHandle and
266 RemainingDevicePath is not supported by the driver specified by This.
267 **/
268 EFI_STATUS
269 EFIAPI
270 HttpDxeIp6DriverBindingSupported (
271 IN EFI_DRIVER_BINDING_PROTOCOL *This,
272 IN EFI_HANDLE ControllerHandle,
273 IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath OPTIONAL
274 );
275
276 /**
277 Starts a device controller or a bus controller.
278
279 The Start() function is designed to be invoked from the EFI boot service ConnectController().
280 As a result, much of the error checking on the parameters to Start() has been moved into this
281 common boot service. It is legal to call Start() from other locations,
282 but the following calling restrictions must be followed, or the system behavior will not be deterministic.
283 1. ControllerHandle must be a valid EFI_HANDLE.
284 2. If RemainingDevicePath is not NULL, then it must be a pointer to a naturally aligned
285 EFI_DEVICE_PATH_PROTOCOL.
286 3. Prior to calling Start(), the Supported() function for the driver specified by This must
287 have been called with the same calling parameters, and Supported() must have returned EFI_SUCCESS.
288
289 @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
290 @param[in] ControllerHandle The handle of the controller to start. This handle
291 must support a protocol interface that supplies
292 an I/O abstraction to the driver.
293 @param[in] RemainingDevicePath A pointer to the remaining portion of a device path. This
294 parameter is ignored by device drivers, and is optional for bus
295 drivers. For a bus driver, if this parameter is NULL, then handles
296 for all the children of Controller are created by this driver.
297 If this parameter is not NULL and the first Device Path Node is
298 not the End of Device Path Node, then only the handle for the
299 child device specified by the first Device Path Node of
300 RemainingDevicePath is created by this driver.
301 If the first Device Path Node of RemainingDevicePath is
302 the End of Device Path Node, no child handle is created by this
303 driver.
304
305 @retval EFI_SUCCESS The device was started.
306 @retval EFI_ALREADY_STARTED This device is already running on ControllerHandle.
307 @retval EFI_DEVICE_ERROR The device could not be started due to a device error.Currently not implemented.
308 @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.
309 @retval Others The driver failded to start the device.
310
311 **/
312 EFI_STATUS
313 EFIAPI
314 HttpDxeIp6DriverBindingStart (
315 IN EFI_DRIVER_BINDING_PROTOCOL *This,
316 IN EFI_HANDLE ControllerHandle,
317 IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath OPTIONAL
318 );
319
320 /**
321 Stops a device controller or a bus controller.
322
323 The Stop() function is designed to be invoked from the EFI boot service DisconnectController().
324 As a result, much of the error checking on the parameters to Stop() has been moved
325 into this common boot service. It is legal to call Stop() from other locations,
326 but the following calling restrictions must be followed, or the system behavior will not be deterministic.
327 1. ControllerHandle must be a valid EFI_HANDLE that was used on a previous call to this
328 same driver's Start() function.
329 2. The first NumberOfChildren handles of ChildHandleBuffer must all be a valid
330 EFI_HANDLE. In addition, all of these handles must have been created in this driver's
331 Start() function, and the Start() function must have called OpenProtocol() on
332 ControllerHandle with an Attribute of EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER.
333
334 @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
335 @param[in] ControllerHandle A handle to the device being stopped. The handle must
336 support a bus specific I/O protocol for the driver
337 to use to stop the device.
338 @param[in] NumberOfChildren The number of child device handles in ChildHandleBuffer.
339 @param[in] ChildHandleBuffer An array of child handles to be freed. May be NULL
340 if NumberOfChildren is 0.
341
342 @retval EFI_SUCCESS The device was stopped.
343 @retval EFI_DEVICE_ERROR The device could not be stopped due to a device error.
344
345 **/
346 EFI_STATUS
347 EFIAPI
348 HttpDxeIp6DriverBindingStop (
349 IN EFI_DRIVER_BINDING_PROTOCOL *This,
350 IN EFI_HANDLE ControllerHandle,
351 IN UINTN NumberOfChildren,
352 IN EFI_HANDLE *ChildHandleBuffer OPTIONAL
353 );
354
355 /**
356 Creates a child handle and installs a protocol.
357
358 The CreateChild() function installs a protocol on ChildHandle.
359 If ChildHandle is a pointer to NULL, then a new handle is created and returned in ChildHandle.
360 If ChildHandle is not a pointer to NULL, then the protocol installs on the existing ChildHandle.
361
362 @param This Pointer to the EFI_SERVICE_BINDING_PROTOCOL instance.
363 @param ChildHandle Pointer to the handle of the child to create. If it is NULL,
364 then a new handle is created. If it is a pointer to an existing UEFI handle,
365 then the protocol is added to the existing UEFI handle.
366
367 @retval EFI_SUCCES The protocol was added to ChildHandle.
368 @retval EFI_INVALID_PARAMETER This is NULL, or ChildHandle is NULL.
369 @retval EFI_OUT_OF_RESOURCES There are not enough resources available to create
370 the child.
371 @retval other The child handle was not created.
372
373 **/
374 EFI_STATUS
375 EFIAPI
376 HttpServiceBindingCreateChild (
377 IN EFI_SERVICE_BINDING_PROTOCOL *This,
378 IN OUT EFI_HANDLE *ChildHandle
379 );
380
381 /**
382 Destroys a child handle with a protocol installed on it.
383
384 The DestroyChild() function does the opposite of CreateChild(). It removes a protocol
385 that was installed by CreateChild() from ChildHandle. If the removed protocol is the
386 last protocol on ChildHandle, then ChildHandle is destroyed.
387
388 @param This Pointer to the EFI_SERVICE_BINDING_PROTOCOL instance.
389 @param ChildHandle Handle of the child to destroy
390
391 @retval EFI_SUCCES The protocol was removed from ChildHandle.
392 @retval EFI_UNSUPPORTED ChildHandle does not support the protocol that is being removed.
393 @retval EFI_INVALID_PARAMETER Child handle is NULL.
394 @retval other The child handle was not destroyed
395
396 **/
397 EFI_STATUS
398 EFIAPI
399 HttpServiceBindingDestroyChild (
400 IN EFI_SERVICE_BINDING_PROTOCOL *This,
401 IN EFI_HANDLE ChildHandle
402 );
403
404 #endif