1 /** 2 * @defgroup MC_DATA_TYPES MobiCore generic data types 3 * 4 * @addtogroup MC_SO mcSo - Secure objects definitions. 5 * <!-- Copyright Giesecke & Devrient GmbH 2011-2012 --> 6 * 7 * Redistribution and use in source and binary forms, with or without 8 * modification, are permitted provided that the following conditions 9 * are met: 10 * 1. Redistributions of source code must retain the above copyright 11 * notice, this list of conditions and the following disclaimer. 12 * 2. Redistributions in binary form must reproduce the above copyright 13 * notice, this list of conditions and the following disclaimer in the 14 * documentation and/or other materials provided with the distribution. 15 * 3. The name of the author may not be used to endorse or promote 16 * products derived from this software without specific prior 17 * written permission. 18 * 19 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS 20 * OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 21 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22 * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY 23 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE 25 * GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 26 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 27 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 28 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 29 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 30 * 31 * @ingroup MC_DATA_TYPES 32 * @{ 33 * 34 */ 35 36 #ifndef MC_SO_H_ 37 #define MC_SO_H_ 38 39 #include "mcUuid.h" 40 #include "mcSpid.h" 41 42 #define SO_USE_VERSION_22 TRUE 43 44 #if SO_USE_VERSION_22 45 #define SO_VERSION_MAJOR 2 46 #define SO_VERSION_MINOR 2 47 #else 48 #define SO_VERSION_MAJOR 2 49 #define SO_VERSION_MINOR 1 50 #endif 51 52 #define MC_ENUM_32BIT_SPACER ((int32_t)-1) 53 54 /** Secure object type. */ 55 typedef enum { 56 /** Regular secure object. */ 57 MC_SO_TYPE_REGULAR = 0x00000001, 58 /** Dummy to ensure that enum is 32 bit wide. */ 59 MC_SO_TYPE_DUMMY = MC_ENUM_32BIT_SPACER, 60 } mcSoType_t; 61 62 63 /** Secure object context. 64 * A context defines which key to use to encrypt/decrypt a secure object. 65 */ 66 typedef enum { 67 /** Trustlet context. */ 68 MC_SO_CONTEXT_TLT = 0x00000001, 69 /** Service provider context. */ 70 MC_SO_CONTEXT_SP = 0x00000002, 71 /** Device context. */ 72 MC_SO_CONTEXT_DEVICE = 0x00000003, 73 /** Dummy to ensure that enum is 32 bit wide. */ 74 MC_SO_CONTEXT_DUMMY = MC_ENUM_32BIT_SPACER, 75 } mcSoContext_t; 76 77 /** Secure object lifetime. 78 * A lifetime defines how long a secure object is valid. 79 */ 80 typedef enum { 81 /** SO does not expire. */ 82 MC_SO_LIFETIME_PERMANENT = 0x00000000, 83 /** SO expires on reboot (coldboot). */ 84 MC_SO_LIFETIME_POWERCYCLE = 0x00000001, 85 /** SO expires when Trustlet is closed. */ 86 MC_SO_LIFETIME_SESSION = 0x00000002, 87 /** Dummy to ensure that enum is 32 bit wide. */ 88 MC_SO_LIFETIME_DUMMY = MC_ENUM_32BIT_SPACER, 89 } mcSoLifeTime_t; 90 91 /** Service provider Trustlet id. 92 * The combination of service provider id and Trustlet UUID forms a unique 93 * Trustlet identifier. 94 */ 95 typedef struct { 96 /** Service provider id. */ 97 mcSpid_t spid; 98 /** Trustlet UUID. */ 99 mcUuid_t uuid; 100 } tlApiSpTrustletId_t; 101 102 /** Secure object header v2.2. 103 * A secure object header introduces a secure object. 104 * Layout of a secure object: 105 * <pre> 106 * <code> 107 * 108 * +--------+------------------+------------------+--------+--------+ 109 * | Header | plain-data | encrypted-data | hash | random | 110 * +--------+------------------+------------------+--------+--------+ 111 * 112 * /--------/---- plainLen ----/-- encryptedLen --/-- 32 --/-- 16 --/ 113 * 114 * /----------------- toBeHashedLen --------------/ 115 * 116 * /-- toBeEncryptedLen --/ 117 * 118 * /--------------------------- totalSoSize ------------------------/ 119 * 120 * </code> 121 * </pre> 122 */ 123 124 /** Secure object header v2.1. 125 * A secure object header introduces a secure object. 126 * Layout of a secure object: 127 * <pre> 128 * <code> 129 * 130 * +--------+------------------+------------------+--------+--------+---------+ 131 * | Header | plain-data | encrypted-data | hash | random | padding | 132 * +--------+------------------+------------------+--------+--------+---------+ 133 * 134 * /--------/---- plainLen ----/-- encryptedLen --/-- 24 --/--- 9 --/- 0..15 -/ 135 * 136 * /----------------- toBeHashedLen --------------/ 137 * 138 * /-- toBeEncryptedLen --/ 139 * 140 * /--------------------------- totalSoSize ----------------------------------/ 141 * 142 * </code> 143 * </pre> 144 */ 145 146 /** Secure object header v2.0. 147 * A secure object header introduces a secure object. 148 * Layout of a secure object: 149 * <pre> 150 * <code> 151 * 152 * +--------+------------------+------------------+--------+---------+ 153 * | Header | plain-data | encrypted-data | hash | padding | 154 * +--------+------------------+------------------+--------+---------+ 155 * 156 * /--------/---- plainLen ----/-- encryptedLen --/-- 32 --/- 1..16 -/ 157 * 158 * /----------------- toBeHashedLen --------------/ 159 * 160 * /---------- toBeEncryptedLen ---------/ 161 * 162 * /--------------------------- totalSoSize -------------------------/ 163 * 164 * </code> 165 * </pre> 166 */ 167 typedef struct { 168 /** Type of secure object. */ 169 uint32_t type; 170 /** Secure object version. */ 171 uint32_t version; 172 /** Secure object context. */ 173 mcSoContext_t context; 174 /** Secure object lifetime. */ 175 mcSoLifeTime_t lifetime; 176 /** Producer Trustlet id. */ 177 tlApiSpTrustletId_t producer; 178 /** Length of unencrypted user data (after the header). */ 179 uint32_t plainLen; 180 /** Length of encrypted user data (after unencrypted data, excl. checksum 181 * and excl. padding bytes). */ 182 uint32_t encryptedLen; 183 } mcSoHeader_t; 184 185 /** Maximum size of the payload (plain length + encrypted length) of a secure object. */ 186 #define MC_SO_PAYLOAD_MAX_SIZE 1000000 187 188 /** Block size of encryption algorithm used for secure objects. */ 189 #define MC_SO_ENCRYPT_BLOCK_SIZE 16 190 191 /** Maximum number of ISO padding bytes. */ 192 #define MC_SO_MAX_PADDING_SIZE (MC_SO_ENCRYPT_BLOCK_SIZE) 193 194 /** Size of hash used for secure objects v2. */ 195 #define MC_SO_HASH_SIZE 32 196 197 /** Size of hash used for secure object v2.1. */ 198 #define MC_SO21_HASH_SIZE 24 199 /** Size of random used for secure objects v2.1. */ 200 #define MC_SO21_RND_SIZE 9 201 202 /** Size of hash used for secure object v2.2. */ 203 #define MC_SO22_HASH_SIZE 32 204 /** Size of random used for secure objects v2.2. */ 205 #define MC_SO22_RND_SIZE 16 206 207 /** Hash size for current generated wrapping */ 208 #define MC_SO2X_HASH_SIZE (SO_USE_VERSION_22 ? MC_SO22_HASH_SIZE : MC_SO21_HASH_SIZE) 209 /** Random size for current generated wrapping */ 210 #define MC_SO2X_RND_SIZE (SO_USE_VERSION_22 ? MC_SO22_RND_SIZE : MC_SO21_RND_SIZE) 211 212 #define MC_SO_ENCRYPT_PADDED_SIZE_F21(netsize) ( (netsize) + \ 213 MC_SO_MAX_PADDING_SIZE - (netsize) % MC_SO_MAX_PADDING_SIZE ) 214 215 #if SO_USE_VERSION_22 216 // No encryption padding at all. 217 #else 218 /** Calculates gross size of cryptogram within secure object including ISO padding bytes. */ 219 #define MC_SO_ENCRYPT_PADDED_SIZE(netsize) MC_SO_ENCRYPT_PADDED_SIZE_F21(netsize) 220 #endif 221 222 223 /** Calculates the total size of a secure object. 224 * @param plainLen Length of plain text part within secure object. 225 * @param encryptedLen Length of encrypted part within secure object (excl. 226 * hash, padding). 227 * @return Total (gross) size of the secure object or 0 if given parameters are 228 * illegal or would lead to a secure object of invalid size. 229 */ 230 #define MC_SO_SIZE_F22(plainLen, encryptedLen) ( \ 231 ((plainLen) + (encryptedLen) < (encryptedLen) || (plainLen) + (encryptedLen) > MC_SO_PAYLOAD_MAX_SIZE) ? 0 : \ 232 sizeof(mcSoHeader_t) + (plainLen) + (encryptedLen) +MC_SO22_HASH_SIZE +MC_SO22_RND_SIZE \ 233 ) 234 #define MC_SO_SIZE_F21(plainLen, encryptedLen) ( \ 235 ((plainLen) + (encryptedLen) < (encryptedLen) || (plainLen) + (encryptedLen) > MC_SO_PAYLOAD_MAX_SIZE) ? 0 : \ 236 sizeof(mcSoHeader_t) + (plainLen) + MC_SO_ENCRYPT_PADDED_SIZE_F21((encryptedLen) + MC_SO_HASH_SIZE) \ 237 ) 238 239 #if SO_USE_VERSION_22 240 #define MC_SO_SIZE(plainLen, encryptedLen) MC_SO_SIZE_F22(plainLen, encryptedLen) 241 #else 242 #define MC_SO_SIZE(plainLen, encryptedLen) MC_SO_SIZE_F21(plainLen, encryptedLen) 243 #endif 244 245 #endif // MC_SO_H_ 246 247 /** @} */ 248