221463c2b3
v3: * Correct the commits grammar v2: * Rename the PCD to PcdAllowHttpConnections. * Refine the PCD descriptions. If the value of PcdAllowHttpConnections is TRUE, HTTP connections are allowed. Both the "https://" and "http://" URI schemes are permitted. Otherwise, HTTP connections are denied. Only the "https://" URI scheme is permitted. Cc: Ye Ting <ting.ye@intel.com> Cc: Fu Siyuan <siyuan.fu@intel.com> Cc: Laszlo Ersek <lersek@redhat.com> Cc: Kinney Michael D <michael.d.kinney@intel.com> Contributed-under: TianoCore Contribution Agreement 1.0 Signed-off-by: Wu Jiaxin <jiaxin.wu@intel.com> Reviewed-by: Ye Ting <ting.ye@intel.com> Reviewed-by: Fu Siyuan <siyuan.fu@intel.com> Reviewed-by: Gary Lin <glin@suse.com> Tested-by: Gary Lin <glin@suse.com>
415 lines
13 KiB
C
415 lines
13 KiB
C
/** @file
|
|
Support functions declaration for UEFI HTTP boot driver.
|
|
|
|
Copyright (c) 2015 - 2017, Intel Corporation. All rights reserved.<BR>
|
|
This program and the accompanying materials are licensed and made available under
|
|
the terms and conditions of the BSD License that accompanies this distribution.
|
|
The full text of the license may be found at
|
|
http://opensource.org/licenses/bsd-license.php.
|
|
|
|
THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
|
|
WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
|
|
|
|
**/
|
|
|
|
#ifndef __EFI_HTTP_BOOT_SUPPORT_H__
|
|
#define __EFI_HTTP_BOOT_SUPPORT_H__
|
|
|
|
/**
|
|
Get the Nic handle using any child handle in the IPv4 stack.
|
|
|
|
@param[in] ControllerHandle Pointer to child handle over IPv4.
|
|
|
|
@return NicHandle The pointer to the Nic handle.
|
|
@return NULL Can't find the Nic handle.
|
|
|
|
**/
|
|
EFI_HANDLE
|
|
HttpBootGetNicByIp4Children (
|
|
IN EFI_HANDLE ControllerHandle
|
|
);
|
|
|
|
/**
|
|
Get the Nic handle using any child handle in the IPv6 stack.
|
|
|
|
@param[in] ControllerHandle Pointer to child handle over IPv6.
|
|
|
|
@return NicHandle The pointer to the Nic handle.
|
|
@return NULL Can't find the Nic handle.
|
|
|
|
**/
|
|
EFI_HANDLE
|
|
HttpBootGetNicByIp6Children (
|
|
IN EFI_HANDLE ControllerHandle
|
|
);
|
|
|
|
/**
|
|
This function is to convert UINTN to ASCII string with the required formatting.
|
|
|
|
@param[in] Number Numeric value to be converted.
|
|
@param[in] Buffer The pointer to the buffer for ASCII string.
|
|
@param[in] Length The length of the required format.
|
|
|
|
**/
|
|
VOID
|
|
HttpBootUintnToAscDecWithFormat (
|
|
IN UINTN Number,
|
|
IN UINT8 *Buffer,
|
|
IN INTN Length
|
|
);
|
|
|
|
|
|
/**
|
|
This function is to display the IPv4 address.
|
|
|
|
@param[in] Ip The pointer to the IPv4 address.
|
|
|
|
**/
|
|
VOID
|
|
HttpBootShowIp4Addr (
|
|
IN EFI_IPv4_ADDRESS *Ip
|
|
);
|
|
|
|
/**
|
|
This function is to display the IPv6 address.
|
|
|
|
@param[in] Ip The pointer to the IPv6 address.
|
|
|
|
**/
|
|
VOID
|
|
HttpBootShowIp6Addr (
|
|
IN EFI_IPv6_ADDRESS *Ip
|
|
);
|
|
|
|
/**
|
|
This function is to display the HTTP error status.
|
|
|
|
@param[in] StatusCode The status code value in HTTP message.
|
|
|
|
**/
|
|
VOID
|
|
HttpBootPrintErrorMessage (
|
|
EFI_HTTP_STATUS_CODE StatusCode
|
|
);
|
|
|
|
//
|
|
// A wrapper structure to hold the HTTP headers.
|
|
//
|
|
typedef struct {
|
|
UINTN MaxHeaderCount;
|
|
UINTN HeaderCount;
|
|
EFI_HTTP_HEADER *Headers;
|
|
} HTTP_IO_HEADER;
|
|
|
|
/**
|
|
Create a HTTP_IO_HEADER to hold the HTTP header items.
|
|
|
|
@param[in] MaxHeaderCount The maximun number of HTTP header in this holder.
|
|
|
|
@return A pointer of the HTTP header holder or NULL if failed.
|
|
|
|
**/
|
|
HTTP_IO_HEADER *
|
|
HttpBootCreateHeader (
|
|
IN UINTN MaxHeaderCount
|
|
);
|
|
|
|
/**
|
|
Destroy the HTTP_IO_HEADER and release the resouces.
|
|
|
|
@param[in] HttpIoHeader Point to the HTTP header holder to be destroyed.
|
|
|
|
**/
|
|
VOID
|
|
HttpBootFreeHeader (
|
|
IN HTTP_IO_HEADER *HttpIoHeader
|
|
);
|
|
|
|
/**
|
|
Set or update a HTTP header with the field name and corresponding value.
|
|
|
|
@param[in] HttpIoHeader Point to the HTTP header holder.
|
|
@param[in] FieldName Null terminated string which describes a field name.
|
|
@param[in] FieldValue Null terminated string which describes the corresponding field value.
|
|
|
|
@retval EFI_SUCCESS The HTTP header has been set or updated.
|
|
@retval EFI_INVALID_PARAMETER Any input parameter is invalid.
|
|
@retval EFI_OUT_OF_RESOURCES Insufficient resource to complete the operation.
|
|
@retval Other Unexpected error happened.
|
|
|
|
**/
|
|
EFI_STATUS
|
|
HttpBootSetHeader (
|
|
IN HTTP_IO_HEADER *HttpIoHeader,
|
|
IN CHAR8 *FieldName,
|
|
IN CHAR8 *FieldValue
|
|
);
|
|
|
|
//
|
|
// HTTP_IO configuration data for IPv4
|
|
//
|
|
typedef struct {
|
|
EFI_HTTP_VERSION HttpVersion;
|
|
UINT32 RequestTimeOut; // In milliseconds.
|
|
UINT32 ResponseTimeOut; // In milliseconds.
|
|
BOOLEAN UseDefaultAddress;
|
|
EFI_IPv4_ADDRESS LocalIp;
|
|
EFI_IPv4_ADDRESS SubnetMask;
|
|
UINT16 LocalPort;
|
|
} HTTP4_IO_CONFIG_DATA;
|
|
|
|
//
|
|
// HTTP_IO configuration data for IPv6
|
|
//
|
|
typedef struct {
|
|
EFI_HTTP_VERSION HttpVersion;
|
|
UINT32 RequestTimeOut; // In milliseconds.
|
|
BOOLEAN UseDefaultAddress;
|
|
EFI_IPv6_ADDRESS LocalIp;
|
|
UINT16 LocalPort;
|
|
} HTTP6_IO_CONFIG_DATA;
|
|
|
|
|
|
//
|
|
// HTTP_IO configuration
|
|
//
|
|
typedef union {
|
|
HTTP4_IO_CONFIG_DATA Config4;
|
|
HTTP6_IO_CONFIG_DATA Config6;
|
|
} HTTP_IO_CONFIG_DATA;
|
|
|
|
//
|
|
// HTTP_IO wrapper of the EFI HTTP service.
|
|
//
|
|
typedef struct {
|
|
UINT8 IpVersion;
|
|
EFI_HANDLE Image;
|
|
EFI_HANDLE Controller;
|
|
EFI_HANDLE Handle;
|
|
|
|
EFI_HTTP_PROTOCOL *Http;
|
|
|
|
EFI_HTTP_TOKEN ReqToken;
|
|
EFI_HTTP_MESSAGE ReqMessage;
|
|
EFI_HTTP_TOKEN RspToken;
|
|
EFI_HTTP_MESSAGE RspMessage;
|
|
|
|
BOOLEAN IsTxDone;
|
|
BOOLEAN IsRxDone;
|
|
|
|
EFI_EVENT TimeoutEvent;
|
|
} HTTP_IO;
|
|
|
|
//
|
|
// A wrapper structure to hold the received HTTP response data.
|
|
//
|
|
typedef struct {
|
|
EFI_HTTP_RESPONSE_DATA Response;
|
|
UINTN HeaderCount;
|
|
EFI_HTTP_HEADER *Headers;
|
|
UINTN BodyLength;
|
|
CHAR8 *Body;
|
|
EFI_STATUS Status;
|
|
} HTTP_IO_RESPONSE_DATA;
|
|
|
|
/**
|
|
Retrieve the host address using the EFI_DNS6_PROTOCOL.
|
|
|
|
@param[in] Private The pointer to the driver's private data.
|
|
@param[in] HostName Pointer to buffer containing hostname.
|
|
@param[out] IpAddress On output, pointer to buffer containing IPv6 address.
|
|
|
|
@retval EFI_SUCCESS Operation succeeded.
|
|
@retval EFI_DEVICE_ERROR An unexpected network error occurred.
|
|
@retval Others Other errors as indicated.
|
|
**/
|
|
EFI_STATUS
|
|
HttpBootDns (
|
|
IN HTTP_BOOT_PRIVATE_DATA *Private,
|
|
IN CHAR16 *HostName,
|
|
OUT EFI_IPv6_ADDRESS *IpAddress
|
|
);
|
|
|
|
/**
|
|
Notify the callback function when an event is triggered.
|
|
|
|
@param[in] Event The triggered event.
|
|
@param[in] Context The opaque parameter to the function.
|
|
|
|
**/
|
|
VOID
|
|
EFIAPI
|
|
HttpBootCommonNotify (
|
|
IN EFI_EVENT Event,
|
|
IN VOID *Context
|
|
);
|
|
|
|
/**
|
|
Create a HTTP_IO to access the HTTP service. It will create and configure
|
|
a HTTP child handle.
|
|
|
|
@param[in] Image The handle of the driver image.
|
|
@param[in] Controller The handle of the controller.
|
|
@param[in] IpVersion IP_VERSION_4 or IP_VERSION_6.
|
|
@param[in] ConfigData The HTTP_IO configuration data.
|
|
@param[out] HttpIo The HTTP_IO.
|
|
|
|
@retval EFI_SUCCESS The HTTP_IO is created and configured.
|
|
@retval EFI_INVALID_PARAMETER One or more parameters are invalid.
|
|
@retval EFI_UNSUPPORTED One or more of the control options are not
|
|
supported in the implementation.
|
|
@retval EFI_OUT_OF_RESOURCES Failed to allocate memory.
|
|
@retval Others Failed to create the HTTP_IO or configure it.
|
|
|
|
**/
|
|
EFI_STATUS
|
|
HttpIoCreateIo (
|
|
IN EFI_HANDLE Image,
|
|
IN EFI_HANDLE Controller,
|
|
IN UINT8 IpVersion,
|
|
IN HTTP_IO_CONFIG_DATA *ConfigData,
|
|
OUT HTTP_IO *HttpIo
|
|
);
|
|
|
|
/**
|
|
Destroy the HTTP_IO and release the resouces.
|
|
|
|
@param[in] HttpIo The HTTP_IO which wraps the HTTP service to be destroyed.
|
|
|
|
**/
|
|
VOID
|
|
HttpIoDestroyIo (
|
|
IN HTTP_IO *HttpIo
|
|
);
|
|
|
|
/**
|
|
Synchronously send a HTTP REQUEST message to the server.
|
|
|
|
@param[in] HttpIo The HttpIo wrapping the HTTP service.
|
|
@param[in] Request A pointer to storage such data as URL and HTTP method.
|
|
@param[in] HeaderCount Number of HTTP header structures in Headers list.
|
|
@param[in] Headers Array containing list of HTTP headers.
|
|
@param[in] BodyLength Length in bytes of the HTTP body.
|
|
@param[in] Body Body associated with the HTTP request.
|
|
|
|
@retval EFI_SUCCESS The HTTP request is trasmitted.
|
|
@retval EFI_INVALID_PARAMETER One or more parameters are invalid.
|
|
@retval EFI_OUT_OF_RESOURCES Failed to allocate memory.
|
|
@retval EFI_DEVICE_ERROR An unexpected network or system error occurred.
|
|
@retval Others Other errors as indicated.
|
|
|
|
**/
|
|
EFI_STATUS
|
|
HttpIoSendRequest (
|
|
IN HTTP_IO *HttpIo,
|
|
IN EFI_HTTP_REQUEST_DATA *Request, OPTIONAL
|
|
IN UINTN HeaderCount,
|
|
IN EFI_HTTP_HEADER *Headers, OPTIONAL
|
|
IN UINTN BodyLength,
|
|
IN VOID *Body OPTIONAL
|
|
);
|
|
|
|
/**
|
|
Synchronously receive a HTTP RESPONSE message from the server.
|
|
|
|
@param[in] HttpIo The HttpIo wrapping the HTTP service.
|
|
@param[in] RecvMsgHeader TRUE to receive a new HTTP response (from message header).
|
|
FALSE to continue receive the previous response message.
|
|
@param[out] ResponseData Point to a wrapper of the received response data.
|
|
|
|
@retval EFI_SUCCESS The HTTP response is received.
|
|
@retval EFI_INVALID_PARAMETER One or more parameters are invalid.
|
|
@retval EFI_OUT_OF_RESOURCES Failed to allocate memory.
|
|
@retval EFI_DEVICE_ERROR An unexpected network or system error occurred.
|
|
@retval Others Other errors as indicated.
|
|
|
|
**/
|
|
EFI_STATUS
|
|
HttpIoRecvResponse (
|
|
IN HTTP_IO *HttpIo,
|
|
IN BOOLEAN RecvMsgHeader,
|
|
OUT HTTP_IO_RESPONSE_DATA *ResponseData
|
|
);
|
|
|
|
/**
|
|
This function checks the HTTP(S) URI scheme.
|
|
|
|
@param[in] Uri The pointer to the URI string.
|
|
|
|
@retval EFI_SUCCESS The URI scheme is valid.
|
|
@retval EFI_INVALID_PARAMETER The URI scheme is not HTTP or HTTPS.
|
|
@retval EFI_ACCESS_DENIED HTTP is disabled and the URI is HTTP.
|
|
|
|
**/
|
|
EFI_STATUS
|
|
HttpBootCheckUriScheme (
|
|
IN CHAR8 *Uri
|
|
);
|
|
|
|
/**
|
|
Get the URI address string from the input device path.
|
|
|
|
Caller need to free the buffer in the UriAddress pointer.
|
|
|
|
@param[in] FilePath Pointer to the device path which contains a URI device path node.
|
|
@param[out] UriAddress The URI address string extract from the device path.
|
|
|
|
@retval EFI_SUCCESS The URI string is returned.
|
|
@retval EFI_OUT_OF_RESOURCES Failed to allocate memory.
|
|
|
|
**/
|
|
EFI_STATUS
|
|
HttpBootParseFilePath (
|
|
IN EFI_DEVICE_PATH_PROTOCOL *FilePath,
|
|
OUT CHAR8 **UriAddress
|
|
);
|
|
|
|
/**
|
|
This function returns the image type according to server replied HTTP message
|
|
and also the image's URI info.
|
|
|
|
@param[in] Uri The pointer to the image's URI string.
|
|
@param[in] UriParser URI Parse result returned by NetHttpParseUrl().
|
|
@param[in] HeaderCount Number of HTTP header structures in Headers list.
|
|
@param[in] Headers Array containing list of HTTP headers.
|
|
@param[out] ImageType The image type of the downloaded file.
|
|
|
|
@retval EFI_SUCCESS The image type is returned in ImageType.
|
|
@retval EFI_INVALID_PARAMETER ImageType, Uri or UriParser is NULL.
|
|
@retval EFI_INVALID_PARAMETER HeaderCount is not zero, and Headers is NULL.
|
|
@retval EFI_NOT_FOUND Failed to identify the image type.
|
|
@retval Others Unexpect error happened.
|
|
|
|
**/
|
|
EFI_STATUS
|
|
HttpBootCheckImageType (
|
|
IN CHAR8 *Uri,
|
|
IN VOID *UriParser,
|
|
IN UINTN HeaderCount,
|
|
IN EFI_HTTP_HEADER *Headers,
|
|
OUT HTTP_BOOT_IMAGE_TYPE *ImageType
|
|
);
|
|
|
|
/**
|
|
This function register the RAM disk info to the system.
|
|
|
|
@param[in] Private The pointer to the driver's private data.
|
|
@param[in] BufferSize The size of Buffer in bytes.
|
|
@param[in] Buffer The base address of the RAM disk.
|
|
@param[in] ImageType The image type of the file in Buffer.
|
|
|
|
@retval EFI_SUCCESS The RAM disk has been registered.
|
|
@retval EFI_NOT_FOUND No RAM disk protocol instances were found.
|
|
@retval EFI_UNSUPPORTED The ImageType is not supported.
|
|
@retval Others Unexpected error happened.
|
|
|
|
**/
|
|
EFI_STATUS
|
|
HttpBootRegisterRamDisk (
|
|
IN HTTP_BOOT_PRIVATE_DATA *Private,
|
|
IN UINTN BufferSize,
|
|
IN VOID *Buffer,
|
|
IN HTTP_BOOT_IMAGE_TYPE ImageType
|
|
);
|
|
#endif
|