mobicore/ClientLib/include/mcSo.h

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