EXTERNAL_HEADERS/corecrypto/ccchacha20poly1305.h

   1 /*
   2         ccchacha20poly1305.h
   3         corecrypto
   4
   5         Copyright 2014 Apple Inc. All rights reserved.
   6 */
   7
   8 #ifndef _CORECRYPTO_CCCHACHA20POLY1305_H_
   9 #define _CORECRYPTO_CCCHACHA20POLY1305_H_
  10
  11 #include <stdbool.h>
  12 #include <stddef.h>
  13 #include <stdint.h>
  14
  15 #define CCCHACHA20_KEY_NBYTES 32
  16 #define CCCHACHA20_BLOCK_NBYTES 64
  17 #define CCCHACHA20_BLOCK_NBITS (CCCHACHA20_BLOCK_NBYTES * 8)
  18 #define CCCHACHA20_NONCE_NBYTES 12
  19
  20 typedef struct {
  21         uint32_t state[16];
  22         uint8_t buffer[CCCHACHA20_BLOCK_NBYTES];
  23         size_t leftover;
  24 } ccchacha20_ctx;
  25
  26 #define CCPOLY1305_TAG_NBYTES 16
  27
  28 typedef struct {
  29         uint32_t r0, r1, r2, r3, r4;
  30         uint32_t s1, s2, s3, s4;
  31         uint32_t h0, h1, h2, h3, h4;
  32         uint8_t buf[16];
  33         size_t buf_used;
  34         uint8_t key[16];
  35 } ccpoly1305_ctx;
  36
  37
  38 /*!
  39  @group         ccchacha20poly1305
  40  @abstract      Encrypts and authenticates or decrypts and verifies data.
  41  @discussion    See RFC 7539 for details.
  42
  43  @warning The key-nonce pair must be unique per encryption.
  44
  45  @warning A single message can be at most (2^38 - 64) bytes in length.
  46
  47  The correct sequence of calls to encrypt is:
  48
  49  @code ccchacha20poly1305_init(...)
  50  ccchacha20poly1305_setnonce(...)
  51  ccchacha20poly1305_aad(...)       (may be called zero or more times)
  52  ccchacha20poly1305_encrypt(...)   (may be called zero or more times)
  53  ccchacha20poly1305_finalize(...)
  54
  55  To reuse the context for additional encryptions, follow this sequence:
  56
  57  @code ccchacha20poly1305_reset(...)
  58  ccchacha20poly1305_setnonce(...)
  59  ccchacha20poly1305_aad(...)       (may be called zero or more times)
  60  ccchacha20poly1305_encrypt(...)   (may be called zero or more times)
  61  ccchacha20poly1305_finalize(...)
  62
  63  To decrypt, follow this call sequence:
  64
  65  @code ccchacha20poly1305_init(...)
  66  ccchacha20poly1305_setnonce(...)
  67  ccchacha20poly1305_aad(...)       (may be called zero or more times)
  68  ccchacha20poly1305_decrypt(...)   (may be called zero or more times)
  69  ccchacha20poly1305_verify(...)    (returns zero on successful decryption)
  70
  71  To reuse the context for additional encryptions, follow this sequence:
  72
  73  @code ccchacha20poly1305_reset(...)
  74  ccchacha20poly1305_setnonce(...)
  75  ccchacha20poly1305_aad(...)       (may be called zero or more times)
  76  ccchacha20poly1305_decrypt(...)   (may be called zero or more times)
  77  ccchacha20poly1305_verify(...)    (returns zero on successful decryption)
  78 */
  79
  80 #define CCCHACHA20POLY1305_KEY_NBYTES (CCCHACHA20_KEY_NBYTES)
  81 #define CCCHACHA20POLY1305_NONCE_NBYTES (CCCHACHA20_NONCE_NBYTES)
  82 #define CCCHACHA20POLY1305_TAG_NBYTES (CCPOLY1305_TAG_NBYTES)
  83
  84 /* (2^32 - 1) blocks */
  85 /* (2^38 - 64) bytes */
  86 /* (2^41 - 512) bits */
  87 /* Exceeding this figure breaks confidentiality and authenticity. */
  88 #define CCCHACHA20POLY1305_TEXT_MAX_NBYTES ((1ULL << 38) - 64ULL)
  89
  90 #define CCCHACHA20POLY1305_STATE_SETNONCE 1
  91 #define CCCHACHA20POLY1305_STATE_AAD 2
  92 #define CCCHACHA20POLY1305_STATE_ENCRYPT 3
  93 #define CCCHACHA20POLY1305_STATE_DECRYPT 4
  94 #define CCCHACHA20POLY1305_STATE_FINAL 5
  95
  96 typedef struct {
  97         ccchacha20_ctx chacha20_ctx;
  98         ccpoly1305_ctx poly1305_ctx;
  99         uint64_t aad_nbytes;
 100         uint64_t text_nbytes;
 101     uint8_t state;
 102 } ccchacha20poly1305_ctx;
 103
 104 // This is just a stub right now.
 105 // Eventually we will optimize by platform.
 106 struct ccchacha20poly1305_info {
 107
 108 };
 109
 110 extern const struct ccchacha20poly1305_info ccchacha20poly1305_info_default;
 111
 112 const struct ccchacha20poly1305_info *ccchacha20poly1305_info(void);
 113
 114 /*!
 115  @function   ccchacha20poly1305_init
 116  @abstract   Initialize a chacha20poly1305 context.
 117
 118  @param      info       Implementation descriptor
 119  @param      ctx        Context for this instance
 120  @param      key        Secret chacha20 key
 121
 122  @result     0 iff successful.
 123
 124  @discussion The key is 32 bytes in length.
 125
 126  @warning The key-nonce pair must be unique per encryption.
 127  */
 128 int     ccchacha20poly1305_init(const struct ccchacha20poly1305_info *info, ccchacha20poly1305_ctx *ctx, const uint8_t *key);
 129
 130 /*!
 131  @function   ccchacha20poly1305_reset
 132  @abstract   Reset a chacha20poly1305 context for reuse.
 133
 134  @param      info       Implementation descriptor
 135  @param      ctx        Context for this instance
 136
 137  @result     0 iff successful.
 138  */
 139 int ccchacha20poly1305_reset(const struct ccchacha20poly1305_info *info, ccchacha20poly1305_ctx *ctx);
 140
 141 /*!
 142  @function   ccchacha20poly1305_setnonce
 143  @abstract   Set the nonce for encryption or decryption.
 144
 145  @param      info       Implementation descriptor
 146  @param      ctx        Context for this instance
 147  @param      nonce      Unique nonce per encryption
 148
 149  @result     0 iff successful.
 150
 151  @discussion The nonce is 12 bytes in length.
 152
 153  @warning The key-nonce pair must be unique per encryption.
 154  */
 155 int ccchacha20poly1305_setnonce(const struct ccchacha20poly1305_info *info, ccchacha20poly1305_ctx *ctx, const uint8_t *nonce);
 156 int ccchacha20poly1305_incnonce(const struct ccchacha20poly1305_info *info, ccchacha20poly1305_ctx *ctx, uint8_t *nonce);
 157
 158 /*!
 159  @function   ccchacha20poly1305_aad
 160  @abstract   Authenticate additional data.
 161
 162  @param      info       Descriptor for the mode
 163  @param      ctx        Context for this instance
 164  @param      nbytes     Length of the additional data in bytes
 165  @param      aad        Additional data to authenticate
 166
 167  @result     0 iff successful.
 168
 169  @discussion This is typically used to authenticate data that cannot be encrypted (e.g. packet headers).
 170
 171  This function may be called zero or more times.
 172  */
 173 int     ccchacha20poly1305_aad(const struct ccchacha20poly1305_info *info, ccchacha20poly1305_ctx *ctx, size_t nbytes, const void *aad);
 174
 175 /*!
 176  @function   ccchacha20poly1305_encrypt
 177  @abstract   Encrypt data.
 178
 179  @param      info       Descriptor for the mode
 180  @param      ctx        Context for this instance
 181  @param      nbytes     Length of the plaintext in bytes
 182  @param      ptext      Input plaintext
 183  @param      ctext      Output ciphertext
 184
 185  @result     0 iff successful.
 186
 187  @discussion In-place processing is supported.
 188
 189  This function may be called zero or more times.
 190  */
 191 int     ccchacha20poly1305_encrypt(const struct ccchacha20poly1305_info *info, ccchacha20poly1305_ctx *ctx, size_t nbytes, const void *ptext, void *ctext);
 192
 193 /*!
 194  @function   ccchacha20poly1305_finalize
 195  @abstract   Finalize encryption.
 196
 197  @param      info       Descriptor for the mode
 198  @param      ctx        Context for this instance
 199  @param      tag        Generated authentication tag
 200
 201  @result     0 iff successful.
 202
 203  @discussion The generated tag is 16 bytes in length.
 204  */
 205 int     ccchacha20poly1305_finalize(const struct ccchacha20poly1305_info *info, ccchacha20poly1305_ctx *ctx, uint8_t *tag);
 206
 207 /*!
 208  @function   ccchacha20poly1305_decrypt
 209  @abstract   Decrypt data.
 210
 211  @param      info       Descriptor for the mode
 212  @param      ctx        Context for this instance
 213  @param      nbytes     Length of the ciphertext in bytes
 214  @param      ctext      Input ciphertext
 215  @param      ptext      Output plaintext
 216
 217  @result     0 iff successful.
 218
 219  @discussion In-place processing is supported.
 220
 221  This function may be called zero or more times.
 222  */
 223 int     ccchacha20poly1305_decrypt(const struct ccchacha20poly1305_info *info, ccchacha20poly1305_ctx *ctx, size_t nbytes, const void *ctext, void *ptext);
 224
 225 /*!
 226  @function   ccchacha20poly1305_verify
 227  @abstract   Verify authenticity.
 228
 229  @param      info       Descriptor for the mode
 230  @param      ctx        Context for this instance
 231  @param      tag        Expected authentication tag
 232
 233  @result     0 iff authentic and otherwise successful.
 234
 235  @discussion The expected tag is 16 bytes in length.
 236  */
 237 int     ccchacha20poly1305_verify(const struct ccchacha20poly1305_info *info, ccchacha20poly1305_ctx *ctx, const uint8_t *tag);
 238
 239 /*!
 240  @function      ccchacha20poly1305_encrypt_oneshot
 241  @abstract      Encrypt with chacha20poly1305.
 242
 243  @param      info           Descriptor for the mode
 244  @param      key            Secret chacha20 key
 245  @param      nonce          Unique nonce per encryption
 246  @param      aad_nbytes     Length of the additional data in bytes
 247  @param      aad            Additional data to authenticate
 248  @param      ptext_nbytes   Length of the plaintext in bytes
 249  @param      ptext          Input plaintext
 250  @param      ctext          Output ciphertext
 251  @param      tag            Generated authentication tag
 252
 253  @discussion See RFC 7539 for details.
 254
 255  The key is 32 bytes in length.
 256
 257  The nonce is 12 bytes in length.
 258
 259  The generated tag is 16 bytes in length.
 260
 261  In-place processing is supported.
 262
 263  @warning The key-nonce pair must be unique per encryption.
 264
 265  @warning A single message can be at most (2^38 - 64) bytes in length.
 266  */
 267 int ccchacha20poly1305_encrypt_oneshot(const struct ccchacha20poly1305_info *info, const uint8_t *key, const uint8_t *nonce, size_t aad_nbytes, const void *aad, size_t ptext_nbytes, const void *ptext, void *ctext, uint8_t *tag);
 268
 269 /*!
 270  @function      ccchacha20poly1305_decrypt_oneshot
 271  @abstract      Decrypt with chacha20poly1305.
 272
 273  @param      info           Descriptor for the mode
 274  @param      key            Secret chacha20 key
 275  @param      nonce          Unique nonce per encryption
 276  @param      aad_nbytes     Length of the additional data in bytes
 277  @param      aad            Additional data to authenticate
 278  @param      ctext_nbytes   Length of the ciphertext in bytes
 279  @param      ctext          Input ciphertext
 280  @param      ptext          Output plaintext
 281  @param      tag            Expected authentication tag
 282
 283  @discussion See RFC 7539 for details.
 284
 285  The key is 32 bytes in length.
 286
 287  The nonce is 12 bytes in length.
 288
 289  The generated tag is 16 bytes in length.
 290
 291  In-place processing is supported.
 292  */
 293 int ccchacha20poly1305_decrypt_oneshot(const struct ccchacha20poly1305_info *info, const uint8_t *key, const uint8_t *nonce, size_t aad_nbytes, const void *aad, size_t ctext_nbytes, const void *ctext, void *ptext, const uint8_t *tag);
 294
 295 #endif