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