include/nettle/ccm.h

0001 /* ccm.h
0002
0003    Counter with CBC-MAC mode, specified by NIST,
0004    http://csrc.nist.gov/publications/nistpubs/800-38C/SP800-38C_updated-July20_2007.pdf
0005
0006    Copyright (C) 2014 Exegin Technologies Limited
0007    Copyright (C) 2014 Owen Kirby
0008
0009    Contributed to GNU Nettle by Owen Kirby
0010
0011    This file is part of GNU Nettle.
0012
0013    GNU Nettle is free software: you can redistribute it and/or
0014    modify it under the terms of either:
0015
0016      * the GNU Lesser General Public License as published by the Free
0017        Software Foundation; either version 3 of the License, or (at your
0018        option) any later version.
0019
0020    or
0021
0022      * the GNU General Public License as published by the Free
0023        Software Foundation; either version 2 of the License, or (at your
0024        option) any later version.
0025
0026    or both in parallel, as here.
0027
0028    GNU Nettle is distributed in the hope that it will be useful,
0029    but WITHOUT ANY WARRANTY; without even the implied warranty of
0030    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
0031    General Public License for more details.
0032
0033    You should have received copies of the GNU General Public License and
0034    the GNU Lesser General Public License along with this program.  If
0035    not, see http://www.gnu.org/licenses/.
0036 */
0037
0038 /* NIST SP800-38C doesn't specify the particular formatting and
0039  * counter generation algorithm for CCM, but it does include an
0040  * example algorithm. This example has become the de-factor standard,
0041  * and has been adopted by both the IETF and IEEE across a wide
0042  * variety of protocols.
0043  */
0044
0045 #ifndef NETTLE_CCM_H_INCLUDED
0046 #define NETTLE_CCM_H_INCLUDED
0047
0048 #include "aes.h"
0049
0050 #ifdef __cplusplus
0051 extern "C" {
0052 #endif
0053
0054 /* Name mangling */
0055 #define ccm_set_nonce nettle_ccm_set_nonce
0056 #define ccm_update nettle_ccm_update
0057 #define ccm_encrypt nettle_ccm_encrypt
0058 #define ccm_decrypt nettle_ccm_decrypt
0059 #define ccm_digest nettle_ccm_digest
0060 #define ccm_encrypt_message nettle_ccm_encrypt_message
0061 #define ccm_decrypt_message nettle_ccm_decrypt_message
0062
0063 #define ccm_aes128_set_key nettle_ccm_aes128_set_key
0064 #define ccm_aes128_set_nonce nettle_ccm_aes128_set_nonce
0065 #define ccm_aes128_update nettle_ccm_aes128_update
0066 #define ccm_aes128_encrypt nettle_ccm_aes128_encrypt
0067 #define ccm_aes128_decrypt nettle_ccm_aes128_decrypt
0068 #define ccm_aes128_digest nettle_ccm_aes128_digest
0069 #define ccm_aes128_encrypt_message nettle_ccm_aes128_encrypt_message
0070 #define ccm_aes128_decrypt_message nettle_ccm_aes128_decrypt_message
0071
0072 #define ccm_aes192_set_key nettle_ccm_aes192_set_key
0073 #define ccm_aes192_set_nonce nettle_ccm_aes192_set_nonce
0074 #define ccm_aes192_update nettle_ccm_aes192_update
0075 #define ccm_aes192_encrypt nettle_ccm_aes192_encrypt
0076 #define ccm_aes192_decrypt nettle_ccm_aes192_decrypt
0077 #define ccm_aes192_digest nettle_ccm_aes192_digest
0078 #define ccm_aes192_encrypt_message nettle_ccm_aes192_encrypt_message
0079 #define ccm_aes192_decrypt_message nettle_ccm_aes192_decrypt_message
0080
0081 #define ccm_aes256_set_key nettle_ccm_aes256_set_key
0082 #define ccm_aes256_set_nonce nettle_ccm_aes256_set_nonce
0083 #define ccm_aes256_update nettle_ccm_aes256_update
0084 #define ccm_aes256_encrypt nettle_ccm_aes256_encrypt
0085 #define ccm_aes256_decrypt nettle_ccm_aes256_decrypt
0086 #define ccm_aes256_digest nettle_ccm_aes256_digest
0087 #define ccm_aes256_encrypt_message nettle_ccm_aes256_encrypt_message
0088 #define ccm_aes256_decrypt_message nettle_ccm_aes256_decrypt_message
0089
0090 /* For CCM, the block size of the block cipher shall be 128 bits. */
0091 #define CCM_BLOCK_SIZE  16
0092 #define CCM_DIGEST_SIZE 16
0093 #define CCM_MIN_NONCE_SIZE 7
0094 #define CCM_MAX_NONCE_SIZE 14
0095
0096 /* Maximum cleartext message size, as a function of the nonce size N.
0097    The length field is L octets, with L = 15 - N, and then the maximum
0098    size M = 2^{8L} - 1. */
0099 #define CCM_MAX_MSG_SIZE(N)         \
0100   ((sizeof(size_t) + (N) <= 15)         \
0101    ? ~(size_t) 0                \
0102    : ((size_t) 1 << (8*(15 - N))) - 1)
0103
0104 /* Per-message state */
0105 struct ccm_ctx {
0106   union nettle_block16 ctr;     /* Counter for CTR encryption. */
0107   union nettle_block16 tag;     /* CBC-MAC message tag. */
0108   /* Length of data processed by the CBC-MAC modulus the block size */
0109   unsigned int blength;
0110 };
0111
0112 /*
0113  * CCM mode requires the adata and message lengths when building the IV, which
0114  * prevents streaming processing and it incompatible with the AEAD API.
0115  */
0116 void
0117 ccm_set_nonce(struct ccm_ctx *ctx, const void *cipher, nettle_cipher_func *f,
0118           size_t noncelen, const uint8_t *nonce,
0119           size_t authlen, size_t msglen, size_t taglen);
0120
0121 void
0122 ccm_update(struct ccm_ctx *ctx, const void *cipher, nettle_cipher_func *f,
0123         size_t length, const uint8_t *data);
0124
0125 void
0126 ccm_encrypt(struct ccm_ctx *ctx, const void *cipher, nettle_cipher_func *f,
0127         size_t length, uint8_t *dst, const uint8_t *src);
0128
0129 void
0130 ccm_decrypt(struct ccm_ctx *ctx, const void *cipher, nettle_cipher_func *f,
0131         size_t length, uint8_t *dst, const uint8_t *src);
0132
0133 void
0134 ccm_digest(struct ccm_ctx *ctx, const void *cipher, nettle_cipher_func *f,
0135        size_t length, uint8_t *digest);
0136
0137 /*
0138  * All-in-one encryption and decryption API:
0139  *  tlength = sizeof(digest)
0140  *  mlength = sizeof(cleartext)
0141  *  clength = sizeof(ciphertext) = mlength + tlength
0142  *
0143  * The ciphertext will contain the encrypted payload with the message digest
0144  * appended to the end.
0145  */
0146 void
0147 ccm_encrypt_message(const void *cipher, nettle_cipher_func *f,
0148             size_t nlength, const uint8_t *nonce,
0149             size_t alength, const uint8_t *adata,
0150             size_t tlength,
0151             size_t clength, uint8_t *dst, const uint8_t *src);
0152
0153 /*
0154  * The decryption function will write the plaintext to dst and parse the digest
0155  * from the final tlength bytes of the ciphertext. If the digest matched the
0156  * value computed during decryption then this will return 1, or it will return
0157  * 0 if the digest was invalid.
0158  */
0159 int
0160 ccm_decrypt_message(const void *cipher, nettle_cipher_func *f,
0161             size_t nlength, const uint8_t *nonce,
0162             size_t alength, const uint8_t *adata,
0163             size_t tlength,
0164             size_t mlength, uint8_t *dst, const uint8_t *src);
0165
0166 /* CCM Mode with AES-128 */
0167 struct ccm_aes128_ctx {
0168     struct ccm_ctx      ccm;
0169     struct aes128_ctx   cipher;
0170 };
0171
0172 void
0173 ccm_aes128_set_key(struct ccm_aes128_ctx *ctx, const uint8_t *key);
0174
0175 void
0176 ccm_aes128_set_nonce(struct ccm_aes128_ctx *ctx,
0177              size_t length, const uint8_t *nonce,
0178              size_t authlen, size_t msglen, size_t taglen);
0179
0180 void
0181 ccm_aes128_update (struct ccm_aes128_ctx *ctx,
0182            size_t length, const uint8_t *data);
0183
0184 void
0185 ccm_aes128_encrypt(struct ccm_aes128_ctx *ctx,
0186            size_t length, uint8_t *dst, const uint8_t *src);
0187
0188 void
0189 ccm_aes128_decrypt(struct ccm_aes128_ctx *ctx,
0190            size_t length, uint8_t *dst, const uint8_t *src);
0191
0192 void
0193 ccm_aes128_digest(struct ccm_aes128_ctx *ctx,
0194           size_t length, uint8_t *digest);
0195
0196 /* FIXME: For next API/ABI break: first argument should be const
0197    struct aes128_ctx *, and similarly for other ccm_*_message
0198    functions below. */
0199 void
0200 ccm_aes128_encrypt_message(struct ccm_aes128_ctx *ctx,
0201                size_t nlength, const uint8_t *nonce,
0202                size_t alength, const uint8_t *adata,
0203                size_t tlength,
0204                size_t clength, uint8_t *dst, const uint8_t *src);
0205
0206 int
0207 ccm_aes128_decrypt_message(struct ccm_aes128_ctx *ctx,
0208                size_t nlength, const uint8_t *nonce,
0209                size_t alength, const uint8_t *adata,
0210                size_t tlength,
0211                size_t mlength, uint8_t *dst, const uint8_t *src);
0212
0213 struct ccm_aes192_ctx {
0214     struct ccm_ctx      ccm;
0215     struct aes192_ctx   cipher;
0216 };
0217
0218 /* CCM Mode with AES-192 */
0219 void
0220 ccm_aes192_set_key(struct ccm_aes192_ctx *ctx, const uint8_t *key);
0221
0222 void
0223 ccm_aes192_set_nonce(struct ccm_aes192_ctx *ctx,
0224              size_t length, const uint8_t *nonce,
0225              size_t authlen, size_t msglen, size_t taglen);
0226
0227 void
0228 ccm_aes192_update(struct ccm_aes192_ctx *ctx,
0229           size_t length, const uint8_t *data);
0230
0231 void
0232 ccm_aes192_encrypt(struct ccm_aes192_ctx *ctx,
0233            size_t length, uint8_t *dst, const uint8_t *src);
0234
0235 void
0236 ccm_aes192_decrypt(struct ccm_aes192_ctx *ctx,
0237            size_t length, uint8_t *dst, const uint8_t *src);
0238
0239 void
0240 ccm_aes192_digest(struct ccm_aes192_ctx *ctx,
0241           size_t length, uint8_t *digest);
0242
0243 void
0244 ccm_aes192_encrypt_message(struct ccm_aes192_ctx *ctx,
0245                size_t nlength, const uint8_t *nonce,
0246                size_t alength, const uint8_t *adata,
0247                size_t tlength,
0248                size_t clength, uint8_t *dst, const uint8_t *src);
0249
0250 int
0251 ccm_aes192_decrypt_message(struct ccm_aes192_ctx *ctx,
0252                size_t nlength, const uint8_t *nonce,
0253                size_t alength, const uint8_t *adata,
0254                size_t tlength,
0255                size_t mlength, uint8_t *dst, const uint8_t *src);
0256
0257 /* CCM Mode with AES-256 */
0258 struct ccm_aes256_ctx {
0259     struct ccm_ctx      ccm;
0260     struct aes256_ctx   cipher;
0261 };
0262
0263 void
0264 ccm_aes256_set_key(struct ccm_aes256_ctx *ctx, const uint8_t *key);
0265
0266 void
0267 ccm_aes256_set_nonce(struct ccm_aes256_ctx *ctx,
0268              size_t length, const uint8_t *nonce,
0269              size_t authlen, size_t msglen, size_t taglen);
0270
0271 void
0272 ccm_aes256_update(struct ccm_aes256_ctx *ctx,
0273           size_t length, const uint8_t *data);
0274
0275 void
0276 ccm_aes256_encrypt(struct ccm_aes256_ctx *ctx,
0277            size_t length, uint8_t *dst, const uint8_t *src);
0278
0279 void
0280 ccm_aes256_decrypt(struct ccm_aes256_ctx *ctx,
0281            size_t length, uint8_t *dst, const uint8_t *src);
0282
0283 void
0284 ccm_aes256_digest(struct ccm_aes256_ctx *ctx,
0285           size_t length, uint8_t *digest);
0286
0287 void
0288 ccm_aes256_encrypt_message(struct ccm_aes256_ctx *ctx,
0289                size_t nlength, const uint8_t *nonce,
0290                size_t alength, const uint8_t *adata,
0291                size_t tlength,
0292                size_t clength, uint8_t *dst, const uint8_t *src);
0293
0294 int
0295 ccm_aes256_decrypt_message(struct ccm_aes256_ctx *ctx,
0296                size_t nlength, const uint8_t *nonce,
0297                size_t alength, const uint8_t *adata,
0298                size_t tlength,
0299                size_t mlength, uint8_t *dst, const uint8_t *src);
0300
0301 #ifdef __cplusplus
0302 }
0303 #endif
0304
0305 #endif /* NETTLE_CCM_H_INCLUDED */