EXTERNAL_HEADERS/corecrypto/ccmode_impl.h

   1 /* Copyright (c) (2010,2011,2012,2015,2016,2017,2018,2019) Apple Inc. All rights reserved.
   2  *
   3  * corecrypto is licensed under Apple Inc.’s Internal Use License Agreement (which
   4  * is contained in the License.txt file distributed with corecrypto) and only to
   5  * people who accept that license. IMPORTANT:  Any license rights granted to you by
   6  * Apple Inc. (if any) are limited to internal use within your organization only on
   7  * devices and computers you own or control, for the sole purpose of verifying the
   8  * security characteristics and correct functioning of the Apple Software.  You may
   9  * not, directly or indirectly, redistribute the Apple Software or any portions thereof.
  10  */
  11
  12 #ifndef _CORECRYPTO_CCMODE_IMPL_H_
  13 #define _CORECRYPTO_CCMODE_IMPL_H_
  14
  15 #include <corecrypto/cc.h>
  16
  17 /* ECB mode. */
  18 cc_aligned_struct(16) ccecb_ctx;
  19
  20
  21 /* Actual symmetric algorithm implementation should provide you one of these. */
  22 struct ccmode_ecb {
  23     size_t size;        /* first argument to ccecb_ctx_decl(). */
  24     size_t block_size;
  25     int (*init)(const struct ccmode_ecb *ecb, ccecb_ctx *ctx,
  26                 size_t key_nbytes, const void *key);
  27     int (*ecb)(const ccecb_ctx *ctx, size_t nblocks, const void *in,
  28                void *out);
  29     void (*roundkey)(const ccecb_ctx *ctx, unsigned r, void *key);
  30 };
  31
  32 /*!
  33  * @brief corecrypto symmetrical encryption and decryption modes
  34  *
  35  * corecrypto supports 6 stateless en(de)cryption modes and 2 stateful authenticated en(de)cryption modes
  36  * stateless modes CBC, CFB, CFB8, CTR, OFB, XTS: They provide 3 interface functions that do not return errors codes
  37  *   1- ccmod_xxx_init()
  38  *   2- ccmod_xxx_decrypt()
  39  *   3- ccmod_xxx_encrypt()
  40  *
  41  * stateful modes CCM and GCM: They provide 7 interface functions that return error codes if a function is called out of state
  42  *   1- ccmod_xxx_init()
  43  *   2- ccmod_xxx_setiv()
  44  *   3- ccmod_xxx_aad()
  45  *   4- ccmod_xxx_decrypt()
  46  *   5- ccmod_xxx_encrypt()
  47  *   6- ccmod_xxx_finalize()
  48  *   7- ccmod_xxx_reset()
  49  *
  50  *  the correct call sequences are:
  51  *
  52  *  calls to 1, 2 and 6 arerequired
  53  *  2 and 3 can be called as mant times as needed
  54  *  calls to 3, 4, 5 can be skipped
  55  *
  56  *  1, 2*n, 3*n, 4|5, 6
  57  *  1, 2*n,    , 4|5, 6
  58  *  1, 2*n,    ,    , 6
  59  *  1, 2*n, 3*n,    , 6
  60  */
  61
  62 // 1- CBC mode, stateless
  63 cc_aligned_struct(16) cccbc_ctx;
  64 cc_aligned_struct(16) cccbc_iv;
  65
  66 struct ccmode_cbc {
  67     size_t size;        /* first argument to cccbc_ctx_decl(). */
  68     size_t block_size;
  69     int (*init)(const struct ccmode_cbc *cbc, cccbc_ctx *ctx,
  70                 size_t key_len, const void *key);
  71     /* cbc encrypt or decrypt nblocks from in to out, iv will be used and updated. */
  72     int (*cbc)(const cccbc_ctx *ctx, cccbc_iv *iv,
  73                size_t nblocks, const void *in, void *out);
  74     const void *custom;
  75 };
  76
  77 // 2- CFB mode, stateless
  78 cc_aligned_struct(16) cccfb_ctx;
  79
  80 struct ccmode_cfb {
  81     size_t size;        /* first argument to cccfb_ctx_decl(). */
  82     size_t block_size;
  83     int (*init)(const struct ccmode_cfb *cfb, cccfb_ctx *ctx,
  84                 size_t key_len, const void *key, const void *iv);
  85     int (*cfb)(cccfb_ctx *ctx, size_t nbytes, const void *in, void *out);
  86     const void *custom;
  87 };
  88
  89 // 3- CFB8 mode, stateless
  90 cc_aligned_struct(16) cccfb8_ctx;
  91
  92 struct ccmode_cfb8 {
  93     size_t size;        /* first argument to cccfb8_ctx_decl(). */
  94     size_t block_size;
  95     int (*init)(const struct ccmode_cfb8 *cfb8, cccfb8_ctx *ctx,
  96                 size_t key_len, const void *key, const void *iv);
  97     int (*cfb8)(cccfb8_ctx *ctx, size_t nbytes, const void *in, void *out);
  98     const void *custom;
  99 };
 100
 101 // 4- CTR mode, stateless
 102 cc_aligned_struct(16) ccctr_ctx;
 103
 104 struct ccmode_ctr {
 105     size_t size;        /* first argument to ccctr_ctx_decl(). */
 106     size_t block_size;  /* for historical reasons, this is set to 1 */
 107     size_t ecb_block_size;  /* the actual block size of the underlying cipher */
 108     int (*init)(const struct ccmode_ctr *mode, ccctr_ctx *ctx,
 109                 size_t key_len, const void *key, const void *iv);
 110     int (*setctr)(const struct ccmode_ctr *mode, ccctr_ctx *ctx, const void *ctr);
 111     int (*ctr)(ccctr_ctx *ctx, size_t nbytes, const void *in, void *out);
 112     const void *custom;
 113 };
 114
 115 // 5- OFB mode, stateless
 116 cc_aligned_struct(16) ccofb_ctx;
 117
 118 struct ccmode_ofb {
 119     size_t size;        /* first argument to ccofb_ctx_decl(). */
 120     size_t block_size;
 121     int (*init)(const struct ccmode_ofb *ofb, ccofb_ctx *ctx,
 122                 size_t key_len, const void *key, const void *iv);
 123     int (*ofb)(ccofb_ctx *ctx, size_t nbytes, const void *in, void *out);
 124     const void *custom;
 125 };
 126
 127 // 6- XTS mode, stateless
 128 cc_aligned_struct(16) ccxts_ctx;
 129 cc_aligned_struct(16) ccxts_tweak;
 130
 131 struct ccmode_xts {
 132     size_t size;        /* first argument to ccxts_ctx_decl(). Size of the ctx data structure */
 133     size_t tweak_size;  /* first argument to ccxts_tweak_decl(). Size of the tweak structure, not the expected tweak size */
 134     size_t block_size;
 135
 136     /* Create a xts key from a xts mode object.
 137      key must point to at least 'size' bytes of free storage.
 138      tweak_key must point to at least 'tweak_size' bytes of free storage.
 139      key and tweak_key must differ.
 140      Returns nonzero on failure.
 141      */
 142     int (*init)(const struct ccmode_xts *xts, ccxts_ctx *ctx,
 143                 size_t key_nbytes, const void *data_key, const void *tweak_key);
 144
 145     void (*key_sched)(const struct ccmode_xts *xts, ccxts_ctx *ctx,
 146                       size_t key_nbytes, const void *data_key, const void *tweak_key);
 147
 148     /* Set the tweak (sector number), the block within the sector zero. */
 149     int (*set_tweak)(const ccxts_ctx *ctx, ccxts_tweak *tweak, const void *iv);
 150
 151     /* Encrypt blocks for a sector, clients must call set_tweak before calling
 152        this function. Return a pointer to the tweak buffer */
 153     void *(*xts)(const ccxts_ctx *ctx, ccxts_tweak *tweak,
 154                  size_t nblocks, const void *in, void *out);
 155
 156     const void *custom;
 157     const void *custom1;
 158 };
 159
 160 //7- GCM mode, statful
 161 cc_aligned_struct(16) ccgcm_ctx;
 162 #define  CCMODE_GCM_DECRYPTOR 78647
 163 #define  CCMODE_GCM_ENCRYPTOR 4073947
 164
 165 struct ccmode_gcm {
 166     size_t size;        /* first argument to ccgcm_ctx_decl(). */
 167     int encdec;        //is it encrypt or decrypt object
 168     size_t block_size;
 169     int (*init)(const struct ccmode_gcm *gcm, ccgcm_ctx *ctx,
 170                  size_t key_nbytes, const void *key);
 171     int (*set_iv)(ccgcm_ctx *ctx, size_t iv_nbytes, const void *iv);
 172     int (*gmac)(ccgcm_ctx *ctx, size_t nbytes, const void *in);  // could just be gcm with NULL out
 173     int (*gcm)(ccgcm_ctx *ctx, size_t nbytes, const void *in, void *out);
 174     int (*finalize)(ccgcm_ctx *key, size_t tag_nbytes, void *tag);
 175     int (*reset)(ccgcm_ctx *ctx);
 176     const void *custom;
 177 };
 178
 179 //8- CCM mode, stateful
 180 cc_aligned_struct(16) ccccm_ctx;
 181 cc_aligned_struct(16) ccccm_nonce;
 182
 183 struct ccmode_ccm {
 184     size_t size;        /* first argument to ccccm_ctx_decl(). */
 185     size_t nonce_size;  /* first argument to ccccm_nonce_decl(). */
 186     size_t block_size;
 187     int (*init)(const struct ccmode_ccm *ccm, ccccm_ctx *ctx,
 188                  size_t key_len, const void *key);
 189     int (*set_iv)(ccccm_ctx *ctx, ccccm_nonce *nonce_ctx, size_t nonce_len, const void *nonce,
 190                    size_t mac_size, size_t auth_len, size_t data_len);
 191     int (*cbcmac)(ccccm_ctx *ctx, ccccm_nonce *nonce_ctx, size_t nbytes, const void *in);  // could just be ccm with NULL out
 192     int (*ccm)(ccccm_ctx *ctx, ccccm_nonce *nonce_ctx, size_t nbytes, const void *in, void *out);
 193     int (*finalize)(ccccm_ctx *key, ccccm_nonce *nonce_ctx, void *mac);
 194     int (*reset)(ccccm_ctx *key, ccccm_nonce *nonce_ctx);
 195     const void *custom;
 196 };
 197
 198 /* We need to expose this (currently)to keep CommonCrypto happy. */
 199 struct _ccmode_ccm_nonce {
 200     unsigned char A_i[16];      /* crypto block iv */
 201     unsigned char B_i[16];      /* mac block iv */
 202     unsigned char MAC[16];      /* crypted mac */
 203     unsigned char buf[16];      /* crypt buffer */
 204
 205     uint32_t mode;         /* mode: IV -> AD -> DATA */
 206     uint32_t buflen;       /* length of data in buf */
 207     uint32_t b_i_len;      /* length of cbcmac data in B_i */
 208
 209     size_t nonce_size;
 210     size_t mac_size;
 211 };
 212
 213 /* OMAC mode. */
 214 cc_aligned_struct(16) ccomac_ctx;
 215
 216 struct ccmode_omac {
 217     size_t size;        /* first argument to ccomac_ctx_decl(). */
 218     size_t block_size;
 219     int (*init)(const struct ccmode_omac *omac, ccomac_ctx *ctx,
 220                 size_t tweak_len, size_t key_len, const void *key);
 221     int (*omac)(ccomac_ctx *ctx, size_t nblocks,
 222                 const void *tweak, const void *in, void *out);
 223     const void *custom;
 224 };
 225
 226 #endif /* _CORECRYPTO_CCMODE_IMPL_H_ */