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 36 #ifndef _TABLE_MARSHAL_H_ 37 #define _TABLE_MARSHAL_H_ 38 39 // These are the basic unmarshaling types. This is in the first byte of 40 // each structure descriptor that is passed to Marshal()/Unmarshal() for processing. 41 #define UINT_MTYPE 0 42 #define VALUES_MTYPE (UINT_MTYPE + 1) 43 #define TABLE_MTYPE (VALUES_MTYPE + 1) 44 #define MIN_MAX_MTYPE (TABLE_MTYPE + 1) 45 #define ATTRIBUTES_MTYPE (MIN_MAX_MTYPE + 1) 46 #define STRUCTURE_MTYPE (ATTRIBUTES_MTYPE + 1) 47 #define TPM2B_MTYPE (STRUCTURE_MTYPE + 1) 48 #define TPM2BS_MTYPE (TPM2B_MTYPE + 1) 49 #define LIST_MTYPE (TPM2BS_MTYPE + 1) // TPML 50 #define ERROR_MTYPE (LIST_MTYPE + 1) 51 #define NULL_MTYPE (ERROR_MTYPE + 1) 52 #define COMPOSITE_MTYPE (NULL_MTYPE + 1) 53 54 //*** The Marshal Index 55 // A structure is used to hold the values that guide the marshaling/unmarshaling of 56 // each of the types. Each structure has a name and an address. For a structure to 57 // define a TPMS_name, the structure is a TPMS_name_MARSHAL_STRUCT and its 58 // index is TPMS_name_MARSHAL_INDEX. So, to get the proper structure, use the 59 // associated marshal index. The marshal index is passed to Marshal() or Unmarshal() 60 // and those functions look up the proper structure. 61 // 62 // To handle structures that allow a null value, the upper bit of each marshal 63 // index indicates if the null value is allowed. This is the NULL_FLAG. It is defined 64 // in TableMarshalIndex.h because it is needed by code outside of the marshaling 65 // code. 66 67 // A structure will have a list of marshal indexes to indicate what to unmarshal. When 68 // that index appears in a structure/union, the value will contain a flag to indicate 69 // that the NULL_FLAG should be SET on the call to Unmarshal() to unmarshal the type. 70 // The caller simply takes the entry and passes it to Unmarshal() to indicate that the 71 // NULL_FLAG is SET. There is also the opportunity to SET the NULL_FLAG in the called 72 // structure if the NULL_FLAG was set in the call to the calling structure. This is 73 // indicated by: 74 #define NULL_MASK ~(NULL_FLAG) 75 76 // When looking up the value to marshal, the upper bit of the marshal index is 77 // masked to yield the actual index. The MSb is the flag bit that indicates if a 78 // null flag is set. Code does not verify that the bit is clear when the called object 79 // does not take a flag as this is a benign error. 80 81 // the modifier byte as used by each MTYPE shown as a structure. They are expressed 82 // as a bit maps below. However, the code uses masking and not bit fields. The types 83 // show below are just to help in understanding. 84 // NOTE: LSb0 bit numbering is assumed in these typedefs. 85 // 86 // When used in an UINT_MTYPE 87 typedef struct integerModifier { 88 unsigned size : 2; 89 unsigned sign : 1; 90 unsigned unused : 7; 91 } integerModifier; 92 93 // When used in a VALUES_MTYPE 94 typedef struct valuesModifier { 95 unsigned size : 2; 96 unsigned sign : 1; 97 unsigned unused : 5; 98 unsigned takesNull : 1; 99 } valuesModifier; 100 101 // When used in a TABLE_MTYPE 102 typedef struct tableModifier { 103 unsigned size : 2; 104 unsigned sign : 1; 105 unsigned unused : 3; 106 unsigned hasBits : 1; 107 unsigned takesNull : 1; 108 } tableModifier; 109 110 // the modifier byte for MIN_MAX_MTYPE 111 typedef struct minMaxModifier { 112 unsigned size : 2; 113 unsigned sign : 1; 114 unsigned unused : 3; 115 unsigned hasBits : 1; 116 unsigned takesNull : 1; 117 } minMaxModifier; 118 119 // the modifier byte for ATTRIBUTES_MTYPE 120 typedef struct attributesModifier { 121 unsigned size : 2; 122 unsigned sign : 1; 123 unsigned unused : 5; 124 } attributesModifier; 125 126 // the modifier byte is not present in a STRUCTURE_MTYPE or an TPM2B_MTYPE 127 128 // the modifier byte for a TPM2BS_MTYPE 129 typedef struct tpm2bsModifier { 130 unsigned offset : 4; 131 unsigned unused : 2; 132 unsigned sizeEqual : 1; 133 unsigned propigateNull : 1; 134 } tpm2bsModifier; 135 136 // the modifier byte for a LIST_MTYPE 137 typedef struct listModifier { 138 unsigned offset : 4; 139 unsigned unused : 2; 140 unsigned sizeEqual : 1; 141 unsigned propigateNull : 1; 142 } listModifier; 143 144 145 //*** Modifier Octet Values 146 // These are in used in anything that is an integer value. Theses would not be in 147 // structure modifier bytes (they would be used in values in structures but not the 148 // STRUCTURE_MTYPE header. 149 #define ONE_BYTES (0) 150 #define TWO_BYTES (1) 151 #define FOUR_BYTES (2) 152 #define EIGHT_BYTES (3) 153 #define SIZE_MASK (0x3) 154 #define IS_SIGNED (1 << 2) // when the unmarshaled type is a signed value 155 #define SIGNED_MASK (SIZE_MASK | IS_SIGNED) 156 157 // This may be used for any type except a UINT_MTYPE 158 #define TAKES_NULL (1 << 7) // when the type takes a null 159 160 // When referencing a structure, this flag indicates if a null is to be propagated 161 // to the referenced structure or type. 162 #define PROPAGATE_NULL (TAKES_NULL) 163 164 // Can be used in min-max or table structures. 165 #define HAS_BITS (1 << 6) // when bit mask is present 166 167 // In a union, we need to know if this is a union of constant arrays. 168 #define IS_ARRAY_UNION (1 << 6) 169 170 // In a TPM2BS_MTYPE 171 #define SIZE_EQUAL (1 << 6) 172 #define OFFSET_MASK (0xF) 173 174 // Right now, there are three spare bits in the modifiers field. 175 176 // Within the descriptor word of each entry in a StructMarsh_mst, there is a selector 177 // field to determine which of the sub-types the entry represents and a field that is 178 // used to reference another structure entry. This is a 6-bit field allowing a 179 // structure to have 64 entries. This should be more than enough as the structures are 180 // not that long. As of now, only 10-bits of the descriptor word leaving room for 181 // expansion. 182 183 // These are the values used in a STRUCTURE_MTYPE to identify the sub-type of the 184 // thing being processed 185 #define SIMPLE_STYPE 0 186 #define UNION_STYPE 1 187 #define ARRAY_STYPE 2 188 189 // The code used GET_ to get the element type and the compiler uses SET_ to initialize 190 // the value. The element type is the three bits (2:0). 191 #define GET_ELEMENT_TYPE(val) (val & 7) 192 #define SET_ELEMENT_TYPE(val) (val & 7) 193 194 // When an entry is an array or union, this references the structure entry that 195 // contains the dimension or selector value. The code then uses this number to look up 196 // the structure entry for that element to find out what it and where is it in memory. 197 // When this is not a reference, it is a simple type and it could be used as an array 198 // value or a union selector. When a simple value, this field contains the size 199 // of the associated value (ONE_BYTES, TWO_BYTES ...) 200 // 201 // The entry size/number is 6 bits (13:8). 202 #define GET_ELEMENT_NUMBER(val) (((val) >> 8) & 0x3F) 203 #define SET_ELEMENT_NUMBER(val) (((val) & 0x3F) << 8) 204 #define GET_ELEMENT_SIZE(val) GET_ELEMENT_NUMBER(val) 205 #define SET_ELEMENT_SIZE(val) SET_ELEMENT_NUMBER(val) 206 // This determines if the null flag is propagated to this type. If generate, the 207 // NULL_FLAG is SET in the index value. This flag is one bit (7) 208 #define ELEMENT_PROPAGATE (PROPAGATE_NULL) 209 210 #define INDEX_MASK ((UINT16)NULL_MASK) 211 212 // This is used in all bit-field checks. These are used when a value that is checked 213 // is conditional (dependent on the compilation). For example, if AES_128 is (NO), 214 // then the bit associated with AES_128 will be 0. In some cases, the bit value is 215 // found by checking that the input is within the range of the table, and then using 216 // the (val - min) value to index the bit. This would be used when verifying that 217 // a particular algorithm is implemented. In other cases, there is a bit for each 218 // value in a table. For example, if checking the key sizes, there is a list of 219 // possible key sizes allowed by the algorithm registry and a bit field to indicate 220 // if that key size is allowed in the implementation. The smallest bit field has 221 // 32-bits because it is implemented as part of the 'values' array in structures 222 // that allow bit fields. 223 #define IS_BIT_SET32(bit, bits) \ 224 ((((UINT32 *)bits)[bit >> 5] & (1 << (bit & 0x1F))) != 0) 225 226 // For a COMPOSITE_MTYPE, the qualifiers byte has an element size and count. 227 #define SET_ELEMENT_COUNT(count) ((count & 0x1F) << 3) 228 #define GET_ELEMENT_COUNT(val) ((val >> 3) & 0x1F) 229 230 #endif // _TABLE_MARSHAL_H_ 231