1 /* 2 * cifra - embedded cryptography library 3 * Written in 2014 by Joseph Birr-Pixton <jpixton@gmail.com> 4 * 5 * To the extent possible under law, the author(s) have dedicated all 6 * copyright and related and neighboring rights to this software to the 7 * public domain worldwide. This software is distributed without any 8 * warranty. 9 * 10 * You should have received a copy of the CC0 Public Domain Dedication 11 * along with this software. If not, see 12 * <http://creativecommons.org/publicdomain/zero/1.0/>. 13 */ 14 15 #ifndef MODES_H 16 #define MODES_H 17 18 #include <stddef.h> 19 #include <stdint.h> 20 21 #include "gf128.h" 22 #include "prp.h" 23 24 /** 25 * Block cipher modes 26 * ================== 27 */ 28 29 /** 30 * CBC mode 31 * -------- 32 * This implementation allows encryption or decryption of whole 33 * blocks in CBC mode. It does not offer a byte-wise incremental 34 * interface, or do any padding. 35 * 36 * This mode provides no useful integrity and should not be used 37 * directly. 38 */ 39 40 /* .. c:type:: cf_cbc 41 * This structure binds together the things needed to encrypt/decrypt whole 42 * blocks in CBC mode. 43 * 44 * .. c:member:: cf_cbc.prp 45 * How to encrypt or decrypt blocks. This could be, for example, :c:data:`cf_aes`. 46 * 47 * .. c:member:: cf_cbc.prpctx 48 * Private data for prp functions. For a `prp` of `cf_aes`, this would be a 49 * pointer to a :c:type:`cf_aes_context` instance. 50 * 51 * .. c:member:: cf_cbc.block 52 * The IV or last ciphertext block. 53 */ 54 typedef struct 55 { 56 const cf_prp *prp; 57 void *prpctx; 58 uint8_t block[CF_MAXBLOCK]; 59 } cf_cbc; 60 61 /* .. c:function:: $DECL 62 * Initialise CBC encryption/decryption context using selected prp, prp context and IV. */ 63 void cf_cbc_init(cf_cbc *ctx, const cf_prp *prp, void *prpctx, const uint8_t iv[CF_MAXBLOCK]); 64 65 /* .. c:function:: $DECL 66 * Encrypt blocks in CBC mode. input and output 67 * must point to blocks * ctx->prp->blocksz bytes of storage (and may alias). */ 68 void cf_cbc_encrypt(cf_cbc *ctx, const uint8_t *input, uint8_t *output, size_t blocks); 69 70 /* .. c:function:: $DECL 71 * Decrypt blocks in CBC mode. input and output 72 * must point to blocks * ctx->prp->blocksz bytes of storage (and may alias). */ 73 void cf_cbc_decrypt(cf_cbc *ctx, const uint8_t *input, uint8_t *output, size_t blocks); 74 75 /** 76 * Counter mode 77 * ------------ 78 * This implementation allows incremental encryption/decryption of 79 * messages. Encryption and decryption are the same operation. 80 * 81 * The counter is always big-endian, but has configurable location 82 * and size within the nonce block. The counter wraps, so you 83 * should make sure the length of a message with a given nonce 84 * doesn't cause nonce reuse. 85 * 86 * This mode provides no integrity and should not be used directly. 87 */ 88 89 /* .. c:type:: cf_ctr 90 * 91 * .. c:member:: cf_ctr.prp 92 * How to encrypt or decrypt blocks. This could be, for example, :c:data:`cf_aes`. 93 * 94 * .. c:member:: cf_ctr.prpctx 95 * Private data for prp functions. For a `prp` of `cf_aes`, this would be a 96 * pointer to a :c:type:`cf_aes_context` instance. 97 * 98 * .. c:member:: cf_ctr.nonce 99 * The next block to encrypt to get another block of key stream. 100 * 101 * .. c:member:: cf_ctr.keymat 102 * The current block of key stream. 103 * 104 * .. c:member:: cf_ctr.nkeymat 105 * The number of bytes at the end of :c:member:`keymat` that are so-far unused. 106 * If this is zero, all the bytes are used up and/or of undefined value. 107 * 108 * .. c:member:: cf_ctr.counter_offset 109 * The offset (in bytes) of the counter block within the nonce. 110 * 111 * .. c:member:: cf_ctr.counter_width 112 * The width (in bytes) of the counter block in the nonce. 113 */ 114 typedef struct 115 { 116 const cf_prp *prp; 117 void *prpctx; 118 uint8_t nonce[CF_MAXBLOCK]; 119 uint8_t keymat[CF_MAXBLOCK]; 120 size_t nkeymat; 121 size_t counter_offset; 122 size_t counter_width; 123 } cf_ctr; 124 125 /* .. c:function:: $DECL 126 * Initialise CTR encryption/decryption context using selected prp and nonce. 127 * (nb, this only increments the whole nonce as a big endian block) */ 128 void cf_ctr_init(cf_ctr *ctx, const cf_prp *prp, void *prpctx, const uint8_t nonce[CF_MAXBLOCK]); 129 130 /* .. c:function:: $DECL 131 * Set the location and width of the nonce counter. 132 * 133 * eg. offset = 12, width = 4 means the counter is mod 2^32 and placed 134 * at the end of the nonce. */ 135 void cf_ctr_custom_counter(cf_ctr *ctx, size_t offset, size_t width); 136 137 /* .. c:function:: $DECL 138 * Encrypt or decrypt bytes in CTR mode. 139 * input and output may alias and must point to specified number of bytes. */ 140 void cf_ctr_cipher(cf_ctr *ctx, const uint8_t *input, uint8_t *output, size_t bytes); 141 142 /* .. c:function:: $DECL 143 * Discards the rest of this block of key stream. */ 144 void cf_ctr_discard_block(cf_ctr *ctx); 145 146 /** 147 * CBC-MAC 148 * ------- 149 * This is a incremental interface to computing a CBC-MAC tag over a message. 150 * 151 * It optionally pads the message with PKCS#5/PKCS#7 padding -- if you don't 152 * do this, messages must be an exact number of blocks long. 153 * 154 * You shouldn't use this directly because it isn't secure for variable-length 155 * messages. Use CMAC instead. 156 */ 157 158 /* .. c:type:: cf_cbcmac_stream 159 * Stream interface to CBC-MAC signing. 160 * 161 * .. c:member:: cf_cbcmac.prp 162 * How to encrypt or decrypt blocks. This could be, for example, :c:data:`cf_aes`. 163 * 164 * .. c:member:: cf_cbcmac.prpctx 165 * Private data for prp functions. For a `prp` of `cf_aes`, this would be a 166 * pointer to a :c:type:`cf_aes_context` instance. 167 * 168 * .. c:member:: cf_cbcmac.cbc 169 * CBC data. 170 * 171 * .. c:member:: cf_cbcmac.buffer 172 * Buffer for data which can't be processed until we have a full block. 173 * 174 * .. c:member:: cf_cbcmac.used 175 * How many bytes at the front of :c:member:`buffer` are valid. 176 */ 177 typedef struct 178 { 179 const cf_prp *prp; 180 void *prpctx; 181 cf_cbc cbc; 182 uint8_t buffer[CF_MAXBLOCK]; 183 size_t used; 184 } cf_cbcmac_stream; 185 186 /* .. c:function:: $DECL 187 * Initialise CBC-MAC signing context using selected prp. */ 188 void cf_cbcmac_stream_init(cf_cbcmac_stream *ctx, const cf_prp *prp, void *prpctx); 189 190 /* .. c:function:: $DECL 191 * Reset the streaming signing context, to sign a new message. */ 192 void cf_cbcmac_stream_reset(cf_cbcmac_stream *ctx); 193 194 /* .. c:function:: $DECL 195 * Process ndata bytes at data. */ 196 void cf_cbcmac_stream_update(cf_cbcmac_stream *ctx, const uint8_t *data, size_t ndata); 197 198 /* .. c:function:: $DECL 199 * Finish the current block of data by adding zeroes. Does nothing if there 200 * are no bytes awaiting processing. */ 201 void cf_cbcmac_stream_finish_block_zero(cf_cbcmac_stream *ctx); 202 203 /* .. c:function:: $DECL 204 * Output the MAC to ctx->prp->blocksz bytes at out. 205 * ctx->used must be zero: the inputed message must be an exact number of 206 * blocks. */ 207 void cf_cbcmac_stream_nopad_final(cf_cbcmac_stream *ctx, uint8_t out[CF_MAXBLOCK]); 208 209 /* .. c:function:: $DECL 210 * Output the MAC to ctx->prp->blocksz bytes at out. 211 * 212 * The message is padded with PKCS#5 padding. */ 213 void cf_cbcmac_stream_pad_final(cf_cbcmac_stream *ctx, uint8_t out[CF_MAXBLOCK]); 214 215 /** 216 * CMAC 217 * ---- 218 * This is both a one-shot and incremental interface to 219 * computing a CMAC tag over a message. 220 * 221 * The one-shot interface separates out the per-key computation, 222 * so if you need to compute lots of MACs with one key you don't 223 * pay that cost more than once. 224 * 225 * CMAC is a good choice for a symmetric MAC. 226 */ 227 228 /* .. c:type:: cf_cmac 229 * One-shot interface to CMAC signing. 230 * 231 * .. c:member:: cf_cmac.prp 232 * How to encrypt or decrypt blocks. This could be, for example, :c:data:`cf_aes`. 233 * 234 * .. c:member:: cf_cmac.prpctx 235 * Private data for prp functions. For a `prp` of `cf_aes`, this would be a 236 * pointer to a :c:type:`cf_aes_context` instance. 237 * 238 * .. c:member:: cf_cmac.B 239 * The XOR offset for the last message block if it is a complete block 240 * (also known as K\ :sub:`1`). 241 * 242 * .. c:member:: cf_cmac.P 243 * The XOR offset for the last message block if it is a partial block 244 * (also known as K\ :sub:`2`). 245 */ 246 typedef struct 247 { 248 const cf_prp *prp; 249 void *prpctx; 250 uint8_t B[CF_MAXBLOCK]; 251 uint8_t P[CF_MAXBLOCK]; 252 } cf_cmac; 253 254 /* .. c:function:: $DECL 255 * Initialise CMAC signing context using selected prp. */ 256 void cf_cmac_init(cf_cmac *ctx, const cf_prp *prp, void *prpctx); 257 258 /* .. c:function:: $DECL 259 * CMAC sign the given data. The MAC is written to ctx->prp->blocksz 260 * bytes at out. This is a one-shot function. */ 261 void cf_cmac_sign(cf_cmac *ctx, const uint8_t *data, size_t bytes, 262 uint8_t out[CF_MAXBLOCK]); 263 264 /* .. c:type:: cf_cmac_stream 265 * Stream interface to CMAC signing. 266 * 267 * Input data in arbitrary chunks using :c:func:`cf_cmac_stream_update`. 268 * The last bit of data must be signalled with the `isfinal` flag to 269 * that function, and the data cannot be zero length unless the whole 270 * message is empty. 271 * 272 * .. c:member:: cf_cmac_stream.cmac 273 * CMAC one-shot data. 274 * 275 * .. c:member:: cf_cmac_stream.cbc 276 * CBC block encryption data. 277 * 278 * .. c:member:: cf_cmac_stream.buffer 279 * Buffer for data which can't be processed until we have a full block. 280 * 281 * .. c:member:: cf_cmac_stream.used 282 * How many bytes at the front of :c:member:`buffer` are valid. 283 * 284 * .. c:member:: cf_cmac_stream.processed 285 * How many bytes in total we've processed. This is used to correctly 286 * process empty messages. 287 * 288 * .. c:member:: cf_cmac_stream.finalised 289 * A flag set when the final chunk of the message has been processed. 290 * Only when this flag is set can you get the MAC out. 291 */ 292 typedef struct 293 { 294 cf_cmac cmac; 295 cf_cbc cbc; 296 uint8_t buffer[CF_MAXBLOCK]; 297 size_t used; 298 size_t processed; 299 int finalised; 300 } cf_cmac_stream; 301 302 /* .. c:function:: $DECL 303 * Initialise CMAC streaming signing context using selected prp. */ 304 void cf_cmac_stream_init(cf_cmac_stream *ctx, const cf_prp *prp, void *prpctx); 305 306 /* .. c:function:: $DECL 307 * Reset the streaming signing context, to sign a new message. */ 308 void cf_cmac_stream_reset(cf_cmac_stream *ctx); 309 310 /* .. c:function:: $DECL 311 * Process ndata bytes at data. isfinal is non-zero if this is the last piece 312 * of data. */ 313 void cf_cmac_stream_update(cf_cmac_stream *ctx, const uint8_t *data, size_t ndata, 314 int isfinal); 315 316 /* .. c:function:: $DECL 317 * Output the MAC to ctx->cmac->prp->blocksz bytes at out. 318 * cf_cmac_stream_update with isfinal non-zero must have been called 319 * since the last _init/_reset. */ 320 void cf_cmac_stream_final(cf_cmac_stream *ctx, uint8_t out[CF_MAXBLOCK]); 321 322 /** 323 * EAX 324 * --- 325 * 326 * The EAX authenticated encryption mode. This is a one-shot 327 * interface. 328 * 329 * EAX is a pretty respectable and fast AEAD mode. 330 */ 331 332 /* .. c:function:: $DECL 333 * EAX authenticated encryption. 334 * 335 * This function does not fail. 336 * 337 * :param prp/prpctx: describe the block cipher to use. 338 * :param plain: message plaintext. 339 * :param nplain: length of message. May be zero. 340 * :param header: additionally authenticated data (AAD). 341 * :param nheader: length of AAD. May be zero. 342 * :param nonce: nonce. This must not repeat for a given key. 343 * :param nnonce: length of nonce. The nonce can be any length. 344 * :param cipher: ciphertext output. `nplain` bytes are written here. 345 * :param tag: authentication tag. `ntag` bytes are written here. 346 * :param ntag: authentication tag length. This must be non-zero and no greater than `prp->blocksz`. 347 */ 348 void cf_eax_encrypt(const cf_prp *prp, void *prpctx, 349 const uint8_t *plain, size_t nplain, 350 const uint8_t *header, size_t nheader, 351 const uint8_t *nonce, size_t nnonce, 352 uint8_t *cipher, 353 uint8_t *tag, size_t ntag); 354 355 /* .. c:function:: $DECL 356 * EAX authenticated decryption. 357 * 358 * :return: 0 on success, non-zero on error. Nothing is written to plain on error. 359 * 360 * :param prp/prpctx: describe the block cipher to use. 361 * :param cipher: message ciphertext. 362 * :param ncipher: message length. 363 * :param header: additionally authenticated data (AAD). 364 * :param nheader: length of AAD. 365 * :param nonce: nonce. 366 * :param nnonce: length of nonce. 367 * :param tag: authentication tag. `ntag` bytes are read from here. 368 * :param ntag: authentication tag length. 369 * :param plain: plaintext output. `ncipher` bytes are written here. 370 */ 371 int cf_eax_decrypt(const cf_prp *prp, void *prpctx, 372 const uint8_t *cipher, size_t ncipher, 373 const uint8_t *header, size_t nheader, 374 const uint8_t *nonce, size_t nnonce, 375 const uint8_t *tag, size_t ntag, 376 uint8_t *plain); 377 378 /** 379 * GCM 380 * --- 381 * The GCM ('Galois counter mode') authenticated encryption mode. 382 * This is a one-shot interface. 383 * 384 * GCM is a reasonably respectable AEAD mode. It's somewhat more 385 * complex than EAX, and side channel-free implementations can 386 * be quite slow. 387 */ 388 389 /* .. c:function:: $DECL 390 * GCM authenticated encryption. 391 * 392 * This function does not fail. 393 * 394 * :param prp/prpctx: describe the block cipher to use. 395 * :param plain: message plaintext. 396 * :param nplain: length of message. May be zero. 397 * :param header: additionally authenticated data (AAD). 398 * :param nheader: length of AAD. May be zero. 399 * :param nonce: nonce. This must not repeat for a given key. 400 * :param nnonce: length of nonce. The nonce can be any length, but 12 bytes is strongly recommended. 401 * :param cipher: ciphertext output. `nplain` bytes are written here. 402 * :param tag: authentication tag. `ntag` bytes are written here. 403 * :param ntag: authentication tag length. This must be non-zero and no greater than `prp->blocksz`. 404 * 405 * This function does not fail. 406 */ 407 void cf_gcm_encrypt(const cf_prp *prp, void *prpctx, 408 const uint8_t *plain, size_t nplain, 409 const uint8_t *header, size_t nheader, 410 const uint8_t *nonce, size_t nnonce, 411 uint8_t *cipher, 412 uint8_t *tag, size_t ntag); 413 414 /* Incremental GHASH computation. */ 415 typedef struct 416 { 417 cf_gf128 H; 418 cf_gf128 Y; 419 uint8_t buffer[16]; 420 size_t buffer_used; 421 uint64_t len_aad; 422 uint64_t len_cipher; 423 unsigned state; 424 } ghash_ctx; 425 426 typedef struct 427 { 428 cf_ctr ctr; 429 ghash_ctx gh; 430 uint8_t Y0[16]; 431 uint8_t e_Y0[16]; 432 } cf_gcm_ctx; 433 434 void cf_gcm_encrypt_init(const cf_prp *prp, void *prpctx, cf_gcm_ctx *gcmctx, 435 const uint8_t *header, size_t nheader, 436 const uint8_t *nonce, size_t nnonce); 437 void cf_gcm_encrypt_update(cf_gcm_ctx *gcmctx, const uint8_t *plain, size_t nplain, uint8_t *cipher); 438 void cf_gcm_encrypt_final(cf_gcm_ctx *gcmctx, uint8_t *tag, size_t ntag); 439 440 /* .. c:function:: $DECL 441 * GCM authenticated decryption. 442 * 443 * :return: 0 on success, non-zero on error. Nothing is written to plain on error. 444 * 445 * :param prp: describe the block cipher to use. 446 * :param prpctx: describe the block cipher to use. 447 * :param cipher: message ciphertext. 448 * :param ncipher: message length. 449 * :param header: additionally authenticated data (AAD). 450 * :param nheader: length of AAD. 451 * :param nonce: nonce. 452 * :param nnonce: length of nonce. 453 * :param tag: authentication tag. `ntag` bytes are read from here. 454 * :param ntag: authentication tag length. 455 * :param plain: plaintext output. `ncipher` bytes are written here. 456 */ 457 int cf_gcm_decrypt(const cf_prp *prp, void *prpctx, 458 const uint8_t *cipher, size_t ncipher, 459 const uint8_t *header, size_t nheader, 460 const uint8_t *nonce, size_t nnonce, 461 const uint8_t *tag, size_t ntag, 462 uint8_t *plain); 463 464 /** 465 * CCM 466 * --- 467 * 468 * The CCM ('Counter with CBC-MAC') authenticated encryption mode. 469 * CCM is a widely used AEAD mode (in IPSec, WPA2, Bluetooth, etc.) 470 * 471 * It works (at a high level) by just gluing together CTR and CBC-MAC 472 * modes (in MAC-then-encrypt mode) and then fixing the problems inherent 473 * with CBC-MAC in over-complicated ways. 474 * 475 * This is a one-shot interface, which is good because the underlying 476 * mechanism isn't actually online: you need to know the message length 477 * before you start, or do everything in two passes. 478 */ 479 480 /* .. c:function:: $DECL 481 * CCM authenticated encryption. 482 * 483 * This function does not fail. 484 * 485 * :param prp/prpctx: describe the block cipher to use. 486 * :param plain: message plaintext. 487 * :param nplain: length of message. May be zero. Must meet the constraints placed on it by `L`. 488 * :param L: length of the message length encoding. This must be in the interval `[2,8]` and gives a maximum message size of 2\ :sup:`8L` bytes. 489 * :param header: additionally authenticated data (AAD). 490 * :param nheader: length of AAD. May be zero. 491 * :param nonce: nonce. This must not repeat for a given key. 492 * :param nnonce: length of nonce. Must be exactly `15 - L` bytes for a 128-bit block cipher. 493 * :param cipher: ciphertext output. `nplain` bytes are written here. 494 * :param tag: authentication tag. `ntag` bytes are written here. 495 * :param ntag: authentication tag length. This must be 4, 6, 8, 10, 12, 14 or 16. 496 */ 497 void cf_ccm_encrypt(const cf_prp *prp, void *prpctx, 498 const uint8_t *plain, size_t nplain, size_t L, 499 const uint8_t *header, size_t nheader, 500 const uint8_t *nonce, size_t nnonce, 501 uint8_t *cipher, 502 uint8_t *tag, size_t ntag); 503 504 /* .. c:function:: $DECL 505 * CCM authenticated decryption. 506 * 507 * :return: 0 on success, non-zero on error. Plain is cleared on error. 508 * 509 * :param prp: describe the block cipher to use. 510 * :param prpctx: describe the block cipher to use. 511 * :param cipher: message ciphertext. 512 * :param ncipher: length of message. 513 * :param L: length of the message length encoding. See :c:func:`cf_ccm_encrypt`. 514 * :param header: additionally authenticated data (AAD). 515 * :param nheader: length of AAD. 516 * :param nonce: nonce. 517 * :param nnonce: length of nonce. 518 * :param tag: authentication tag. `ntag` bytes are read from here. 519 * :param ntag: authentication tag length. This must be 4, 6, 8, 10, 12, 14 or 16. 520 * :param plain: plaintext output. `ncipher` bytes are written here. 521 */ 522 int cf_ccm_decrypt(const cf_prp *prp, void *prpctx, 523 const uint8_t *cipher, size_t ncipher, size_t L, 524 const uint8_t *header, size_t nheader, 525 const uint8_t *nonce, size_t nnonce, 526 const uint8_t *tag, size_t ntag, 527 uint8_t *plain); 528 529 /** 530 * OCB 531 * --- 532 * 533 * OCB is an authenticated encryption mode by Phil Rogaway. 534 * 535 * This is version 3, as standardised in RFC7253. It's defined 536 * only for block ciphers with a 128-bit block size. 537 * 538 * This is a one-shot interface. 539 */ 540 541 /* .. c:function:: $DECL 542 * OCB authenticated encryption. 543 * 544 * This function does not fail. 545 * 546 * :param prp/prpctx: describe the block cipher to use. 547 * :param plain: message plaintext. 548 * :param nplain: length of message. May be zero. 549 * :param header: additionally authenticated data (AAD). 550 * :param nheader: length of AAD. May be zero. 551 * :param nonce: nonce. This must not repeat for a given key. 552 * :param nnonce: length of nonce. Must be 15 or fewer bytes. 553 * :param cipher: ciphertext output. `nplain` bytes are written here. 554 * :param tag: authentication tag. `ntag` bytes are written here. 555 * :param ntag: authentication tag length. Must be 16 or fewer bytes. 556 */ 557 void cf_ocb_encrypt(const cf_prp *prp, void *prpctx, 558 const uint8_t *plain, size_t nplain, 559 const uint8_t *header, size_t nheader, 560 const uint8_t *nonce, size_t nnonce, 561 uint8_t *cipher, 562 uint8_t *tag, size_t ntag); 563 564 /* .. c:function:: $DECL 565 * OCB authenticated decryption. 566 * 567 * :return: 0 on success, non-zero on error. `plain` is cleared on error. 568 * 569 * :param prp: describe the block cipher to use. 570 * :param prpctx: describe the block cipher to use. 571 * :param cipher: message ciphertext. 572 * :param ncipher: length of message. 573 * :param header: additionally authenticated data (AAD). 574 * :param nheader: length of AAD. 575 * :param nonce: nonce. 576 * :param nnonce: length of nonce. 577 * :param tag: authentication tag. `ntag` bytes are read from here. 578 * :param ntag: authentication tag length. 579 * :param plain: plaintext output. `ncipher` bytes are written here. 580 */ 581 int cf_ocb_decrypt(const cf_prp *prp, void *prpctx, 582 const uint8_t *cipher, size_t ncipher, 583 const uint8_t *header, size_t nheader, 584 const uint8_t *nonce, size_t nnonce, 585 const uint8_t *tag, size_t ntag, 586 uint8_t *plain); 587 #endif 588