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 //** Introduction 36 // This header contains the hash structure definitions used in the TPM code 37 // to define the amount of space to be reserved for the hash state. This allows 38 // the TPM code to not have to import all of the symbols used by the hash 39 // computations. This lets the build environment of the TPM code not to have 40 // include the header files associated with the CryptoEngine code. 41 42 #ifndef _CRYPT_HASH_H 43 #define _CRYPT_HASH_H 44 45 //** Hash-related Structures 46 47 union SMAC_STATES; 48 49 // These definitions add the high-level methods for processing state that may be 50 // an SMAC 51 typedef void(* SMAC_DATA_METHOD)( 52 union SMAC_STATES *state, 53 UINT32 size, 54 const BYTE *buffer 55 ); 56 57 typedef UINT16(* SMAC_END_METHOD)( 58 union SMAC_STATES *state, 59 UINT32 size, 60 BYTE *buffer 61 ); 62 63 typedef struct sequenceMethods { 64 SMAC_DATA_METHOD data; 65 SMAC_END_METHOD end; 66 } SMAC_METHODS; 67 68 #define SMAC_IMPLEMENTED (CC_MAC || CC_MAC_Start) 69 70 // These definitions are here because the SMAC state is in the union of hash states. 71 typedef struct tpmCmacState { 72 TPM_ALG_ID symAlg; 73 UINT16 keySizeBits; 74 INT16 bcount; // current count of bytes accumulated in IV 75 TPM2B_IV iv; // IV buffer 76 TPM2B_SYM_KEY symKey; 77 } tpmCmacState_t; 78 79 typedef union SMAC_STATES { 80 #if ALG_CMAC 81 tpmCmacState_t cmac; 82 #endif 83 UINT64 pad; 84 } SMAC_STATES; 85 86 typedef struct SMAC_STATE { 87 SMAC_METHODS smacMethods; 88 SMAC_STATES state; 89 } SMAC_STATE; 90 91 #if ALG_SHA1 92 # define IF_IMPLEMENTED_SHA1(op) op(SHA1, Sha1) 93 #else 94 # define IF_IMPLEMENTED_SHA1(op) 95 #endif 96 #if ALG_SHA256 97 # define IF_IMPLEMENTED_SHA256(op) op(SHA256, Sha256) 98 #else 99 # define IF_IMPLEMENTED_SHA256(op) 100 #endif 101 #if ALG_SHA384 102 # define IF_IMPLEMENTED_SHA384(op) op(SHA384, Sha384) 103 #else 104 # define IF_IMPLEMENTED_SHA384(op) 105 #endif 106 #if ALG_SHA512 107 # define IF_IMPLEMENTED_SHA512(op) op(SHA512, Sha512) 108 #else 109 # define IF_IMPLEMENTED_SHA512(op) 110 #endif 111 #if ALG_SM3_256 112 # define IF_IMPLEMENTED_SM3_256(op) op(SM3_256, Sm3_256) 113 #else 114 # define IF_IMPLEMENTED_SM3_256(op) 115 #endif 116 #if ALG_SHA3_256 117 # define IF_IMPLEMENTED_SHA3_256(op) op(SHA3_256, Sha3_256) 118 #else 119 # define IF_IMPLEMENTED_SHA3_256(op) 120 #endif 121 #if ALG_SHA3_384 122 # define IF_IMPLEMENTED_SHA3_384(op) op(SHA3_384, Sha3_384) 123 #else 124 # define IF_IMPLEMENTED_SHA3_384(op) 125 #endif 126 #if ALG_SHA3_512 127 # define IF_IMPLEMENTED_SHA3_512(op) op(SHA3_512, Sha3_512) 128 #else 129 # define IF_IMPLEMENTED_SHA3_512(op) 130 #endif 131 132 #define FOR_EACH_HASH(op) \ 133 IF_IMPLEMENTED_SHA1(op) \ 134 IF_IMPLEMENTED_SHA256(op) \ 135 IF_IMPLEMENTED_SHA384(op) \ 136 IF_IMPLEMENTED_SM3_256(op) \ 137 IF_IMPLEMENTED_SHA3_256(op) \ 138 IF_IMPLEMENTED_SHA3_384(op) \ 139 IF_IMPLEMENTED_SHA3_512(op) 140 141 142 #define HASH_TYPE(HASH, Hash) tpmHashState##HASH##_t Hash; 143 typedef union 144 { 145 FOR_EACH_HASH(HASH_TYPE) 146 // Additions for symmetric block cipher MAC 147 #if SMAC_IMPLEMENTED 148 SMAC_STATE smac; 149 #endif 150 // to force structure alignment to be no worse than HASH_ALIGNMENT 151 #if HASH_ALIGNMENT == 8 152 uint64_t align; 153 #else 154 uint32_t align; 155 #endif 156 } ANY_HASH_STATE; 157 158 typedef ANY_HASH_STATE *PANY_HASH_STATE; 159 typedef const ANY_HASH_STATE *PCANY_HASH_STATE; 160 161 #define ALIGNED_SIZE(x, b) ((((x) + (b) - 1) / (b)) * (b)) 162 // MAX_HASH_STATE_SIZE will change with each implementation. It is assumed that 163 // a hash state will not be larger than twice the block size plus some 164 // overhead (in this case, 16 bytes). The overall size needs to be as 165 // large as any of the hash contexts. The structure needs to start on an 166 // alignment boundary and be an even multiple of the alignment 167 #define MAX_HASH_STATE_SIZE ((2 * MAX_HASH_BLOCK_SIZE) + 16) 168 #define MAX_HASH_STATE_SIZE_ALIGNED \ 169 ALIGNED_SIZE(MAX_HASH_STATE_SIZE, HASH_ALIGNMENT) 170 171 // This is an aligned byte array that will hold any of the hash contexts. 172 typedef ANY_HASH_STATE ALIGNED_HASH_STATE; 173 174 // The header associated with the hash library is expected to define the methods 175 // which include the calling sequence. When not compiling CryptHash.c, the methods 176 // are not defined so we need placeholder functions for the structures 177 178 #ifndef HASH_START_METHOD_DEF 179 # define HASH_START_METHOD_DEF void (HASH_START_METHOD)(void) 180 #endif 181 #ifndef HASH_DATA_METHOD_DEF 182 # define HASH_DATA_METHOD_DEF void (HASH_DATA_METHOD)(void) 183 #endif 184 #ifndef HASH_END_METHOD_DEF 185 # define HASH_END_METHOD_DEF void (HASH_END_METHOD)(void) 186 #endif 187 #ifndef HASH_STATE_COPY_METHOD_DEF 188 # define HASH_STATE_COPY_METHOD_DEF void (HASH_STATE_COPY_METHOD)(void) 189 #endif 190 #ifndef HASH_STATE_EXPORT_METHOD_DEF 191 # define HASH_STATE_EXPORT_METHOD_DEF void (HASH_STATE_EXPORT_METHOD)(void) 192 #endif 193 #ifndef HASH_STATE_IMPORT_METHOD_DEF 194 # define HASH_STATE_IMPORT_METHOD_DEF void (HASH_STATE_IMPORT_METHOD)(void) 195 #endif 196 197 // Define the prototypical function call for each of the methods. This defines the 198 // order in which the parameters are passed to the underlying function. 199 typedef HASH_START_METHOD_DEF; 200 typedef HASH_DATA_METHOD_DEF; 201 typedef HASH_END_METHOD_DEF; 202 typedef HASH_STATE_COPY_METHOD_DEF; 203 typedef HASH_STATE_EXPORT_METHOD_DEF; 204 typedef HASH_STATE_IMPORT_METHOD_DEF; 205 206 207 typedef struct _HASH_METHODS 208 { 209 HASH_START_METHOD *start; 210 HASH_DATA_METHOD *data; 211 HASH_END_METHOD *end; 212 HASH_STATE_COPY_METHOD *copy; // Copy a hash block 213 HASH_STATE_EXPORT_METHOD *copyOut; // Copy a hash block from a hash 214 // context 215 HASH_STATE_IMPORT_METHOD *copyIn; // Copy a hash block to a proper hash 216 // context 217 } HASH_METHODS, *PHASH_METHODS; 218 219 #define HASH_TPM2B(HASH, Hash) TPM2B_TYPE(HASH##_DIGEST, HASH##_DIGEST_SIZE); 220 221 FOR_EACH_HASH(HASH_TPM2B) 222 223 // When the TPM implements RSA, the hash-dependent OID pointers are part of the 224 // HASH_DEF. These macros conditionally add the OID reference to the HASH_DEF and the 225 // HASH_DEF_TEMPLATE. 226 #if ALG_RSA 227 #define PKCS1_HASH_REF const BYTE *PKCS1; 228 #define PKCS1_OID(NAME) , OID_PKCS1_##NAME 229 #else 230 #define PKCS1_HASH_REF 231 #define PKCS1_OID(NAME) 232 #endif 233 234 // When the TPM implements ECC, the hash-dependent OID pointers are part of the 235 // HASH_DEF. These macros conditionally add the OID reference to the HASH_DEF and the 236 // HASH_DEF_TEMPLATE. 237 #if ALG_ECDSA 238 #define ECDSA_HASH_REF const BYTE *ECDSA; 239 #define ECDSA_OID(NAME) , OID_ECDSA_##NAME 240 #else 241 #define ECDSA_HASH_REF 242 #define ECDSA_OID(NAME) 243 #endif 244 245 typedef const struct HASH_DEF 246 { 247 HASH_METHODS method; 248 uint16_t blockSize; 249 uint16_t digestSize; 250 uint16_t contextSize; 251 uint16_t hashAlg; 252 const BYTE *OID; 253 PKCS1_HASH_REF // PKCS1 OID 254 ECDSA_HASH_REF // ECDSA OID 255 } HASH_DEF, *PHASH_DEF; 256 257 // Macro to fill in the HASH_DEF for an algorithm. For SHA1, the instance would be: 258 // HASH_DEF_TEMPLATE(Sha1, SHA1) 259 // This handles the difference in capitalization for the various pieces. 260 #define HASH_DEF_TEMPLATE(HASH, Hash) \ 261 HASH_DEF Hash##_Def= { \ 262 {(HASH_START_METHOD *)&tpmHashStart_##HASH, \ 263 (HASH_DATA_METHOD *)&tpmHashData_##HASH, \ 264 (HASH_END_METHOD *)&tpmHashEnd_##HASH, \ 265 (HASH_STATE_COPY_METHOD *)&tpmHashStateCopy_##HASH, \ 266 (HASH_STATE_EXPORT_METHOD *)&tpmHashStateExport_##HASH, \ 267 (HASH_STATE_IMPORT_METHOD *)&tpmHashStateImport_##HASH, \ 268 }, \ 269 HASH##_BLOCK_SIZE, /*block size */ \ 270 HASH##_DIGEST_SIZE, /*data size */ \ 271 sizeof(tpmHashState##HASH##_t), \ 272 TPM_ALG_##HASH, OID_##HASH \ 273 PKCS1_OID(HASH) ECDSA_OID(HASH)}; 274 275 // These definitions are for the types that can be in a hash state structure. 276 // These types are used in the cryptographic utilities. This is a define rather than 277 // an enum so that the size of this field can be explicit. 278 typedef BYTE HASH_STATE_TYPE; 279 #define HASH_STATE_EMPTY ((HASH_STATE_TYPE) 0) 280 #define HASH_STATE_HASH ((HASH_STATE_TYPE) 1) 281 #define HASH_STATE_HMAC ((HASH_STATE_TYPE) 2) 282 #if CC_MAC || CC_MAC_Start 283 #define HASH_STATE_SMAC ((HASH_STATE_TYPE) 3) 284 #endif 285 286 287 // This is the structure that is used for passing a context into the hashing 288 // functions. It should be the same size as the function context used within 289 // the hashing functions. This is checked when the hash function is initialized. 290 // This version uses a new layout for the contexts and a different definition. The 291 // state buffer is an array of HASH_UNIT values so that a decent compiler will put 292 // the structure on a HASH_UNIT boundary. If the structure is not properly aligned, 293 // the code that manipulates the structure will copy to a properly aligned 294 // structure before it is used and copy the result back. This just makes things 295 // slower. 296 // NOTE: This version of the state had the pointer to the update method in the 297 // state. This is to allow the SMAC functions to use the same structure without 298 // having to replicate the entire HASH_DEF structure. 299 typedef struct _HASH_STATE 300 { 301 HASH_STATE_TYPE type; // type of the context 302 TPM_ALG_ID hashAlg; 303 PHASH_DEF def; 304 ANY_HASH_STATE state; 305 } HASH_STATE, *PHASH_STATE; 306 typedef const HASH_STATE *PCHASH_STATE; 307 308 309 //** HMAC State Structures 310 311 // An HMAC_STATE structure contains an opaque HMAC stack state. A caller would 312 // use this structure when performing incremental HMAC operations. This structure 313 // contains a hash state and an HMAC key and allows slightly better stack 314 // optimization than adding an HMAC key to each hash state. 315 typedef struct hmacState 316 { 317 HASH_STATE hashState; // the hash state 318 TPM2B_HASH_BLOCK hmacKey; // the HMAC key 319 } HMAC_STATE, *PHMAC_STATE; 320 321 // This is for the external hash state. This implementation assumes that the size 322 // of the exported hash state is no larger than the internal hash state. 323 typedef struct 324 { 325 BYTE buffer[sizeof(HASH_STATE)]; 326 } EXPORT_HASH_STATE, *PEXPORT_HASH_STATE; 327 328 typedef const EXPORT_HASH_STATE *PCEXPORT_HASH_STATE; 329 330 #endif // _CRYPT_HASH_H 331