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

/** @file\r
  This file defines the BIS protocol.\r
\r
  Copyright (c) 2006, Intel Corporation                                                         \r
  All rights reserved. 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
  Module Name:  Bis.h\r
\r
**/\r
\r
#ifndef __BIS_H__\r
#define __BIS_H__\r
\r
#define EFI_BIS_PROTOCOL_GUID \\r
  { \\r
    0x0b64aab0, 0x5429, 0x11d4, {0x98, 0x16, 0x00, 0xa0, 0xc9, 0x1f, 0xad, 0xcf } \\r
  }\r
\r
typedef struct _EFI_BIS_PROTOCOL  EFI_BIS_PROTOCOL;\r
\r
\r
//\r
// Basic types\r
//\r
typedef VOID    *BIS_APPLICATION_HANDLE;\r
typedef UINT16  BIS_ALG_ID;\r
typedef UINT32  BIS_CERT_ID;\r
\r
//\r
// EFI_BIS_DATA type.\r
//\r
// EFI_BIS_DATA instances obtained from BIS must be freed by calling Free( ).\r
//\r
typedef struct {\r
  UINT32  Length; // Length of Data in 8 bit bytes.\r
  UINT8   *Data;  // 32 Bit Flat Address of data.\r
} EFI_BIS_DATA;\r
\r
//\r
// EFI_BIS_VERSION type.\r
//\r
typedef struct {\r
  UINT32  Major;  // BIS Interface version number.\r
  UINT32  Minor;  // Build number.\r
} EFI_BIS_VERSION;\r
\r
//\r
// ----------------------------------------------------//\r
// Use these values to initialize EFI_BIS_VERSION.Major\r
// and to interpret results of Initialize.\r
// ----------------------------------------------------//\r
//\r
#define BIS_CURRENT_VERSION_MAJOR BIS_VERSION_1\r
#define BIS_VERSION_1             1\r
\r
//\r
// EFI_BIS_SIGNATURE_INFO type.\r
//\r
typedef struct {\r
  BIS_CERT_ID CertificateID;  // Truncated hash of platform Boot Object\r
  //  authorization certificate.\r
  //\r
  BIS_ALG_ID  AlgorithmID;  // A signature algorithm number.\r
  UINT16      KeyLength;    // Length of alg. keys in bits.\r
} EFI_BIS_SIGNATURE_INFO;\r
\r
//\r
// Currently defined values for EFI_BIS_SIGNATURE_INFO.AlgorithmID.\r
// The exact numeric values come from\r
//    "Common Data Security Architecture (CDSA) Specification".\r
//\r
#define BIS_ALG_DSA     (41)  // CSSM_ALGID_DSA\r
#define BIS_ALG_RSA_MD5 (42)  // CSSM_ALGID_MD5_WITH_RSA\r
// Currently defined values for EFI_BIS_SIGNATURE_INFO.CertificateId.\r
//\r
#define BIS_CERT_ID_DSA     BIS_ALG_DSA     // CSSM_ALGID_DSA\r
#define BIS_CERT_ID_RSA_MD5 BIS_ALG_RSA_MD5 // CSSM_ALGID_MD5_WITH_RSA\r
// The  following  is a mask value that gets applied to the truncated hash of a\r
// platform  Boot Object Authorization Certificate to create the certificateID.\r
// A certificateID must not have any bits set to the value 1 other than bits in\r
// this mask.\r
//\r
#define BIS_CERT_ID_MASK  (0xFF7F7FFF)\r
\r
//\r
// Macros for dealing with the EFI_BIS_DATA object obtained\r
// from BIS_GetSignatureInfo()\r
// BIS_GET_SIGINFO_COUNT - tells how many EFI_BIS_SIGNATURE_INFO\r
//  elements are contained in a EFI_BIS_DATA struct pointed to\r
//  by the provided EFI_BIS_DATA*.\r
//\r
#define BIS_GET_SIGINFO_COUNT(BisDataPtr) ((BisDataPtr)->Length / sizeof (EFI_BIS_SIGNATURE_INFO))\r
\r
//\r
// BIS_GET_SIGINFO_ARRAY - produces a EFI_BIS_SIGNATURE_INFO*\r
//  from a given EFI_BIS_DATA*.\r
//\r
#define BIS_GET_SIGINFO_ARRAY(BisDataPtr) ((EFI_BIS_SIGNATURE_INFO *) (BisDataPtr)->Data)\r
\r
//\r
// Binary Value of "X-Intel-BIS-ParameterSet" Attribute.\r
// (Value is Base64 encoded in actual signed manifest).\r
// {EDD35E31-07B9-11d2-83A3-00A0C91FADCF}\r
//\r
#define BOOT_OBJECT_AUTHORIZATION_PARMSET_GUID \\r
  { \\r
    0xedd35e31, 0x7b9, 0x11d2, \\r
    { \\r
      0x83, 0xa3, 0x0, 0xa0, 0xc9, 0x1f, 0xad, 0xcf \\r
    } \\r
  }\r
\r
//\r
// Support old name for backward compatible\r
//\r
#define BOOT_OBJECT_AUTHORIZATION_PARMSET_GUIDVALUE \\r
        BOOT_OBJECT_AUTHORIZATION_PARMSET_GUID\r
\r
/**                                                                 \r
  Initializes the BIS service, checking that it is compatible with the version requested by the caller.\r
  After this call, other BIS functions may be invoked.                                                 \r
    \r
  @param  This                     A pointer to the EFI_BIS_PROTOCOL object.\r
  @param  AppHandle                The function writes the new BIS_APPLICATION_HANDLE if           \r
                                   successful, otherwise it writes NULL. The caller must eventually\r
                                   destroy this handle by calling Shutdown().                      \r
  @param  InterfaceVersion         On input, the caller supplies the major version number of the\r
                                   interface version desired.                                   \r
                                   On output, both the major and minor                         \r
                                   version numbers are updated with the major and minor version\r
                                   numbers of the interface                                    \r
  @param  TargetAddress            Indicates a network or device address of the BIS platform to connect to.                                                                 \r
  \r
  @retval EFI_SUCCESS              The function completed successfully.\r
  @retval EFI_INCOMPATIBLE_VERSION The InterfaceVersion.Major requested by the                \r
                                   caller was not compatible with the interface version of the\r
  @retval EFI_UNSUPPORTED          This is a local-platform implementation and        \r
                                   TargetAddress.Data was not NULL, or                \r
                                   TargetAddress.Data was any other value that was not\r
                                   supported by the implementation.                   \r
  @retval EFI_OUT_OF_RESOURCES     The function failed due to lack of memory or other resources.                              \r
  @retval EFI_DEVICE_ERROR         The function encountered an unexpected internal failure.\r
  @retval EFI_INVALID_PARAMETER    One or more parameters are invalid.\r
                                          \r
**/                                       \r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_BIS_INITIALIZE) (\r
  IN     EFI_BIS_PROTOCOL        *This,              \r
  OUT    BIS_APPLICATION_HANDLE  *AppHandle,         \r
  IN OUT EFI_BIS_VERSION         *InterfaceVersion,  \r
  IN     EFI_BIS_DATA            *TargetAddress      \r
  );\r
\r
/**                                                                 \r
  Frees memory structures allocated and returned by other functions in the EFI_BIS protocol.  \r
      \r
Commit	Line	Data
878ddf1f	1	/** @file\r
	2	This file defines the BIS protocol.\r
	3	\r
	4	Copyright (c) 2006, Intel Corporation \r
	5	All rights reserved. This program and the accompanying materials \r
	6	are licensed and made available under the terms and conditions of the BSD License \r
	7	which accompanies this distribution. The full text of the license may be found at \r
	8	http://opensource.org/licenses/bsd-license.php \r
	9	\r
	10	THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, \r
	11	WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. \r
	12	\r
	13	Module Name: Bis.h\r
	14	\r
	15	**/\r
	16	\r
	17	#ifndef __BIS_H__\r
	18	#define __BIS_H__\r
	19	\r
	20	#define EFI_BIS_PROTOCOL_GUID \\r
	21	{ \\r
	22	0x0b64aab0, 0x5429, 0x11d4, {0x98, 0x16, 0x00, 0xa0, 0xc9, 0x1f, 0xad, 0xcf } \\r
	23	}\r
	24	\r
	25	typedef struct _EFI_BIS_PROTOCOL EFI_BIS_PROTOCOL;\r
	26	\r
	27	\r
	28	//\r
	29	// Basic types\r
	30	//\r
	31	typedef VOID *BIS_APPLICATION_HANDLE;\r
	32	typedef UINT16 BIS_ALG_ID;\r
	33	typedef UINT32 BIS_CERT_ID;\r
	34	\r
	35	//\r
	36	// EFI_BIS_DATA type.\r
	37	//\r
	38	// EFI_BIS_DATA instances obtained from BIS must be freed by calling Free( ).\r
	39	//\r
	40	typedef struct {\r
	41	UINT32 Length; // Length of Data in 8 bit bytes.\r
	42	UINT8 *Data; // 32 Bit Flat Address of data.\r
	43	} EFI_BIS_DATA;\r
	44	\r
	45	//\r
	46	// EFI_BIS_VERSION type.\r
	47	//\r
	48	typedef struct {\r
	49	UINT32 Major; // BIS Interface version number.\r
	50	UINT32 Minor; // Build number.\r
	51	} EFI_BIS_VERSION;\r
	52	\r
	53	//\r
	54	// ----------------------------------------------------//\r
	55	// Use these values to initialize EFI_BIS_VERSION.Major\r
	56	// and to interpret results of Initialize.\r
	57	// ----------------------------------------------------//\r
	58	//\r
	59	#define BIS_CURRENT_VERSION_MAJOR BIS_VERSION_1\r
	60	#define BIS_VERSION_1 1\r
	61	\r
	62	//\r
	63	// EFI_BIS_SIGNATURE_INFO type.\r
	64	//\r
65	typedef struct {\r
66	BIS_CERT_ID CertificateID; // Truncated hash of platform Boot Object\r
67	// authorization certificate.\r
68	//\r
69	BIS_ALG_ID AlgorithmID; // A signature algorithm number.\r
70	UINT16 KeyLength; // Length of alg. keys in bits.\r
71	} EFI_BIS_SIGNATURE_INFO;\r
72	\r
73	//\r
74	// Currently defined values for EFI_BIS_SIGNATURE_INFO.AlgorithmID.\r
75	// The exact numeric values come from\r
76	// "Common Data Security Architecture (CDSA) Specification".\r
77	//\r
78	#define BIS_ALG_DSA (41) // CSSM_ALGID_DSA\r
79	#define BIS_ALG_RSA_MD5 (42) // CSSM_ALGID_MD5_WITH_RSA\r
80	// Currently defined values for EFI_BIS_SIGNATURE_INFO.CertificateId.\r
81	//\r
82	#define BIS_CERT_ID_DSA BIS_ALG_DSA // CSSM_ALGID_DSA\r
83	#define BIS_CERT_ID_RSA_MD5 BIS_ALG_RSA_MD5 // CSSM_ALGID_MD5_WITH_RSA\r
84	// The following is a mask value that gets applied to the truncated hash of a\r
85	// platform Boot Object Authorization Certificate to create the certificateID.\r
86	// A certificateID must not have any bits set to the value 1 other than bits in\r
87	// this mask.\r
88	//\r
89	#define BIS_CERT_ID_MASK (0xFF7F7FFF)\r
90	\r
91	//\r
92	// Macros for dealing with the EFI_BIS_DATA object obtained\r
93	// from BIS_GetSignatureInfo()\r
94	// BIS_GET_SIGINFO_COUNT - tells how many EFI_BIS_SIGNATURE_INFO\r
95	// elements are contained in a EFI_BIS_DATA struct pointed to\r
96	// by the provided EFI_BIS_DATA*.\r
97	//\r
98	#define BIS_GET_SIGINFO_COUNT(BisDataPtr) ((BisDataPtr)->Length / sizeof (EFI_BIS_SIGNATURE_INFO))\r
99	\r
100	//\r
101	// BIS_GET_SIGINFO_ARRAY - produces a EFI_BIS_SIGNATURE_INFO*\r
102	// from a given EFI_BIS_DATA*.\r
103	//\r
104	#define BIS_GET_SIGINFO_ARRAY(BisDataPtr) ((EFI_BIS_SIGNATURE_INFO *) (BisDataPtr)->Data)\r
105	\r
106	//\r
107	// Binary Value of "X-Intel-BIS-ParameterSet" Attribute.\r
108	// (Value is Base64 encoded in actual signed manifest).\r
109	// {EDD35E31-07B9-11d2-83A3-00A0C91FADCF}\r
110	//\r
111	#define BOOT_OBJECT_AUTHORIZATION_PARMSET_GUID \\r
112	{ \\r
113	0xedd35e31, 0x7b9, 0x11d2, \\r
114	{ \\r
115	0x83, 0xa3, 0x0, 0xa0, 0xc9, 0x1f, 0xad, 0xcf \\r
116	} \\r
117	}\r
118	\r
119	//\r
120	// Support old name for backward compatible\r
121	//\r
122	#define BOOT_OBJECT_AUTHORIZATION_PARMSET_GUIDVALUE \\r
123	BOOT_OBJECT_AUTHORIZATION_PARMSET_GUID\r
124	\r
125	/** \r
126	Initializes the BIS service, checking that it is compatible with the version requested by the caller.\r
127	After this call, other BIS functions may be invoked. \r
128	\r
129	@param This A pointer to the EFI_BIS_PROTOCOL object.\r
130	@param AppHandle The function writes the new BIS_APPLICATION_HANDLE if \r
131	successful, otherwise it writes NULL. The caller must eventually\r
132	destroy this handle by calling Shutdown(). \r
133	@param InterfaceVersion On input, the caller supplies the major version number of the\r
134	interface version desired. \r
135	On output, both the major and minor \r
136	version numbers are updated with the major and minor version\r
137	numbers of the interface \r
138	@param TargetAddress Indicates a network or device address of the BIS platform to connect to. \r
139	\r
140	@retval EFI_SUCCESS The function completed successfully.\r
141	@retval EFI_INCOMPATIBLE_VERSION The InterfaceVersion.Major requested by the \r
142	caller was not compatible with the interface version of the\r
143	@retval EFI_UNSUPPORTED This is a local-platform implementation and \r
144	TargetAddress.Data was not NULL, or \r
145	TargetAddress.Data was any other value that was not\r
146	supported by the implementation. \r
147	@retval EFI_OUT_OF_RESOURCES The function failed due to lack of memory or other resources. \r
148	@retval EFI_DEVICE_ERROR The function encountered an unexpected internal failure.\r
149	@retval EFI_INVALID_PARAMETER One or more parameters are invalid.\r
150	\r
151	**/ \r
152	typedef\r
153	EFI_STATUS\r
154	(EFIAPI *EFI_BIS_INITIALIZE) (\r
155	IN EFI_BIS_PROTOCOL *This, \r
156	OUT BIS_APPLICATION_HANDLE *AppHandle, \r
157	IN OUT EFI_BIS_VERSION *InterfaceVersion, \r
158	IN EFI_BIS_DATA *TargetAddress \r
159	);\r
160	\r
161	/** \r
162	Frees memory structures allocated and returned by other functions in the EFI_BIS protocol. \r
163	\r
164