1 /* Microsoft Reference Implementation for TPM 2.0 2 * 3 * The copyright in this software is being made available under the BSD License, 4 * included below. This software may be subject to other third party and 5 * contributor rights, including patent rights, and no such rights are granted 6 * under this license. 7 * 8 * Copyright (c) Microsoft Corporation 9 * 10 * All rights reserved. 11 * 12 * BSD License 13 * 14 * Redistribution and use in source and binary forms, with or without modification, 15 * are permitted provided that the following conditions are met: 16 * 17 * Redistributions of source code must retain the above copyright notice, this list 18 * of conditions and the following disclaimer. 19 * 20 * Redistributions in binary form must reproduce the above copyright notice, this 21 * list of conditions and the following disclaimer in the documentation and/or 22 * other materials provided with the distribution. 23 * 24 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ""AS IS"" 25 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 26 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 27 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR 28 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 29 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 30 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON 31 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 32 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 33 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 34 */ 35 /*(Auto-generated) 36 * Created by TpmPrototypes; Version 3.0 July 18, 2017 37 * Date: Mar 4, 2020 Time: 02:36:44PM 38 */ 39 40 #ifndef _PCR_FP_H_ 41 #define _PCR_FP_H_ 42 43 //*** PCRBelongsAuthGroup() 44 // This function indicates if a PCR belongs to a group that requires an authValue 45 // in order to modify the PCR. If it does, 'groupIndex' is set to value of 46 // the group index. This feature of PCR is decided by the platform specification. 47 // 48 // Return Type: BOOL 49 // TRUE(1) PCR belongs an authorization group 50 // FALSE(0) PCR does not belong an authorization group 51 BOOL 52 PCRBelongsAuthGroup( 53 TPMI_DH_PCR handle, // IN: handle of PCR 54 UINT32 *groupIndex // OUT: group index if PCR belongs a 55 // group that allows authValue. If PCR 56 // does not belong to an authorization 57 // group, the value in this parameter is 58 // invalid 59 ); 60 61 //*** PCRBelongsPolicyGroup() 62 // This function indicates if a PCR belongs to a group that requires a policy 63 // authorization in order to modify the PCR. If it does, 'groupIndex' is set 64 // to value of the group index. This feature of PCR is decided by the platform 65 // specification. 66 // 67 // Return Type: BOOL 68 // TRUE(1) PCR belongs to a policy group 69 // FALSE(0) PCR does not belong to a policy group 70 BOOL 71 PCRBelongsPolicyGroup( 72 TPMI_DH_PCR handle, // IN: handle of PCR 73 UINT32 *groupIndex // OUT: group index if PCR belongs a group that 74 // allows policy. If PCR does not belong to 75 // a policy group, the value in this 76 // parameter is invalid 77 ); 78 79 //*** PCRPolicyIsAvailable() 80 // This function indicates if a policy is available for a PCR. 81 // 82 // Return Type: BOOL 83 // TRUE(1) the PCR may be authorized by policy 84 // FALSE(0) the PCR does not allow policy 85 BOOL 86 PCRPolicyIsAvailable( 87 TPMI_DH_PCR handle // IN: PCR handle 88 ); 89 90 //*** PCRGetAuthValue() 91 // This function is used to access the authValue of a PCR. If PCR does not 92 // belong to an authValue group, an EmptyAuth will be returned. 93 TPM2B_AUTH * 94 PCRGetAuthValue( 95 TPMI_DH_PCR handle // IN: PCR handle 96 ); 97 98 //*** PCRGetAuthPolicy() 99 // This function is used to access the authorization policy of a PCR. It sets 100 // 'policy' to the authorization policy and returns the hash algorithm for policy 101 // If the PCR does not allow a policy, TPM_ALG_NULL is returned. 102 TPMI_ALG_HASH 103 PCRGetAuthPolicy( 104 TPMI_DH_PCR handle, // IN: PCR handle 105 TPM2B_DIGEST *policy // OUT: policy of PCR 106 ); 107 108 //*** PCRSimStart() 109 // This function is used to initialize the policies when a TPM is manufactured. 110 // This function would only be called in a manufacturing environment or in 111 // a TPM simulator. 112 void 113 PCRSimStart( 114 void 115 ); 116 117 //*** PcrIsAllocated() 118 // This function indicates if a PCR number for the particular hash algorithm 119 // is allocated. 120 // Return Type: BOOL 121 // TRUE(1) PCR is allocated 122 // FALSE(0) PCR is not allocated 123 BOOL 124 PcrIsAllocated( 125 UINT32 pcr, // IN: The number of the PCR 126 TPMI_ALG_HASH hashAlg // IN: The PCR algorithm 127 ); 128 129 //*** PcrDrtm() 130 // This function does the DRTM and H-CRTM processing it is called from 131 // _TPM_Hash_End. 132 void 133 PcrDrtm( 134 const TPMI_DH_PCR pcrHandle, // IN: the index of the PCR to be 135 // modified 136 const TPMI_ALG_HASH hash, // IN: the bank identifier 137 const TPM2B_DIGEST *digest // IN: the digest to modify the PCR 138 ); 139 140 //*** PCR_ClearAuth() 141 // This function is used to reset the PCR authorization values. It is called 142 // on TPM2_Startup(CLEAR) and TPM2_Clear(). 143 void 144 PCR_ClearAuth( 145 void 146 ); 147 148 //*** PCRStartup() 149 // This function initializes the PCR subsystem at TPM2_Startup(). 150 BOOL 151 PCRStartup( 152 STARTUP_TYPE type, // IN: startup type 153 BYTE locality // IN: startup locality 154 ); 155 156 //*** PCRStateSave() 157 // This function is used to save the PCR values that will be restored on TPM Resume. 158 void 159 PCRStateSave( 160 TPM_SU type // IN: startup type 161 ); 162 163 //*** PCRIsStateSaved() 164 // This function indicates if the selected PCR is a PCR that is state saved 165 // on TPM2_Shutdown(STATE). The return value is based on PCR attributes. 166 // Return Type: BOOL 167 // TRUE(1) PCR is state saved 168 // FALSE(0) PCR is not state saved 169 BOOL 170 PCRIsStateSaved( 171 TPMI_DH_PCR handle // IN: PCR handle to be extended 172 ); 173 174 //*** PCRIsResetAllowed() 175 // This function indicates if a PCR may be reset by the current command locality. 176 // The return value is based on PCR attributes, and not the PCR allocation. 177 // Return Type: BOOL 178 // TRUE(1) TPM2_PCR_Reset is allowed 179 // FALSE(0) TPM2_PCR_Reset is not allowed 180 BOOL 181 PCRIsResetAllowed( 182 TPMI_DH_PCR handle // IN: PCR handle to be extended 183 ); 184 185 //*** PCRChanged() 186 // This function checks a PCR handle to see if the attributes for the PCR are set 187 // so that any change to the PCR causes an increment of the pcrCounter. If it does, 188 // then the function increments the counter. Will also bump the counter if the 189 // handle is zero which means that PCR 0 can not be in the TCB group. Bump on zero 190 // is used by TPM2_Clear(). 191 void 192 PCRChanged( 193 TPM_HANDLE pcrHandle // IN: the handle of the PCR that changed. 194 ); 195 196 //*** PCRIsExtendAllowed() 197 // This function indicates a PCR may be extended at the current command locality. 198 // The return value is based on PCR attributes, and not the PCR allocation. 199 // Return Type: BOOL 200 // TRUE(1) extend is allowed 201 // FALSE(0) extend is not allowed 202 BOOL 203 PCRIsExtendAllowed( 204 TPMI_DH_PCR handle // IN: PCR handle to be extended 205 ); 206 207 //*** PCRExtend() 208 // This function is used to extend a PCR in a specific bank. 209 void 210 PCRExtend( 211 TPMI_DH_PCR handle, // IN: PCR handle to be extended 212 TPMI_ALG_HASH hash, // IN: hash algorithm of PCR 213 UINT32 size, // IN: size of data to be extended 214 BYTE *data // IN: data to be extended 215 ); 216 217 //*** PCRComputeCurrentDigest() 218 // This function computes the digest of the selected PCR. 219 // 220 // As a side-effect, 'selection' is modified so that only the implemented PCR 221 // will have their bits still set. 222 void 223 PCRComputeCurrentDigest( 224 TPMI_ALG_HASH hashAlg, // IN: hash algorithm to compute digest 225 TPML_PCR_SELECTION *selection, // IN/OUT: PCR selection (filtered on 226 // output) 227 TPM2B_DIGEST *digest // OUT: digest 228 ); 229 230 //*** PCRRead() 231 // This function is used to read a list of selected PCR. If the requested PCR 232 // number exceeds the maximum number that can be output, the 'selection' is 233 // adjusted to reflect the actual output PCR. 234 void 235 PCRRead( 236 TPML_PCR_SELECTION *selection, // IN/OUT: PCR selection (filtered on 237 // output) 238 TPML_DIGEST *digest, // OUT: digest 239 UINT32 *pcrCounter // OUT: the current value of PCR generation 240 // number 241 ); 242 243 //*** PCRAllocate() 244 // This function is used to change the PCR allocation. 245 // Return Type: TPM_RC 246 // TPM_RC_NO_RESULT allocate failed 247 // TPM_RC_PCR improper allocation 248 TPM_RC 249 PCRAllocate( 250 TPML_PCR_SELECTION *allocate, // IN: required allocation 251 UINT32 *maxPCR, // OUT: Maximum number of PCR 252 UINT32 *sizeNeeded, // OUT: required space 253 UINT32 *sizeAvailable // OUT: available space 254 ); 255 256 //*** PCRSetValue() 257 // This function is used to set the designated PCR in all banks to an initial value. 258 // The initial value is signed and will be sign extended into the entire PCR. 259 // 260 void 261 PCRSetValue( 262 TPM_HANDLE handle, // IN: the handle of the PCR to set 263 INT8 initialValue // IN: the value to set 264 ); 265 266 //*** PCRResetDynamics 267 // This function is used to reset a dynamic PCR to 0. This function is used in 268 // DRTM sequence. 269 void 270 PCRResetDynamics( 271 void 272 ); 273 274 //*** PCRCapGetAllocation() 275 // This function is used to get the current allocation of PCR banks. 276 // Return Type: TPMI_YES_NO 277 // YES if the return count is 0 278 // NO if the return count is not 0 279 TPMI_YES_NO 280 PCRCapGetAllocation( 281 UINT32 count, // IN: count of return 282 TPML_PCR_SELECTION *pcrSelection // OUT: PCR allocation list 283 ); 284 285 //*** PCRCapGetProperties() 286 // This function returns a list of PCR properties starting at 'property'. 287 // Return Type: TPMI_YES_NO 288 // YES if no more property is available 289 // NO if there are more properties not reported 290 TPMI_YES_NO 291 PCRCapGetProperties( 292 TPM_PT_PCR property, // IN: the starting PCR property 293 UINT32 count, // IN: count of returned properties 294 TPML_TAGGED_PCR_PROPERTY *select // OUT: PCR select 295 ); 296 297 //*** PCRCapGetHandles() 298 // This function is used to get a list of handles of PCR, started from 'handle'. 299 // If 'handle' exceeds the maximum PCR handle range, an empty list will be 300 // returned and the return value will be NO. 301 // Return Type: TPMI_YES_NO 302 // YES if there are more handles available 303 // NO all the available handles has been returned 304 TPMI_YES_NO 305 PCRCapGetHandles( 306 TPMI_DH_PCR handle, // IN: start handle 307 UINT32 count, // IN: count of returned handles 308 TPML_HANDLE *handleList // OUT: list of handle 309 ); 310 311 #endif // _PCR_FP_H_ 312