1 /* cbc_mode.h - TinyCrypt interface to a CBC mode implementation */ 2 3 /* 4 * Copyright (C) 2017 by Intel Corporation, All Rights Reserved. 5 * 6 * Redistribution and use in source and binary forms, with or without 7 * modification, are permitted provided that the following conditions are met: 8 * 9 * - Redistributions of source code must retain the above copyright notice, 10 * this list of conditions and the following disclaimer. 11 * 12 * - Redistributions in binary form must reproduce the above copyright 13 * notice, this list of conditions and the following disclaimer in the 14 * documentation and/or other materials provided with the distribution. 15 * 16 * - Neither the name of Intel Corporation nor the names of its contributors 17 * may be used to endorse or promote products derived from this software 18 * without specific prior written permission. 19 * 20 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 21 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE 24 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 25 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 26 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 27 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 28 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 29 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 30 * POSSIBILITY OF SUCH DAMAGE. 31 */ 32 33 /** 34 * @file 35 * @brief Interface to a CBC mode implementation. 36 * 37 * Overview: CBC (for "cipher block chaining") mode is a NIST approved mode of 38 * operation defined in SP 800-38a. It can be used with any block 39 * cipher to provide confidentiality of strings whose lengths are 40 * multiples of the block_size of the underlying block cipher. 41 * TinyCrypt hard codes AES as the block cipher. 42 * 43 * Security: CBC mode provides data confidentiality given that the maximum 44 * number q of blocks encrypted under a single key satisfies 45 * q < 2^63, which is not a practical constraint (it is considered a 46 * good practice to replace the encryption when q == 2^56). CBC mode 47 * provides NO data integrity. 48 * 49 * CBC mode assumes that the IV value input into the 50 * tc_cbc_mode_encrypt is randomly generated. The TinyCrypt library 51 * provides HMAC-PRNG module, which generates suitable IVs. Other 52 * methods for generating IVs are acceptable, provided that the 53 * values of the IVs generated appear random to any adversary, 54 * including someone with complete knowledge of the system design. 55 * 56 * The randomness property on which CBC mode's security depends is 57 * the unpredictability of the IV. Since it is unpredictable, this 58 * means in practice that CBC mode requires that the IV is stored 59 * somehow with the ciphertext in order to recover the plaintext. 60 * 61 * TinyCrypt CBC encryption prepends the IV to the ciphertext, 62 * because this affords a more efficient (few buffers) decryption. 63 * Hence tc_cbc_mode_encrypt assumes the ciphertext buffer is always 64 * 16 bytes larger than the plaintext buffer. 65 * 66 * Requires: AES-128 67 * 68 * Usage: 1) call tc_cbc_mode_encrypt to encrypt data. 69 * 70 * 2) call tc_cbc_mode_decrypt to decrypt data. 71 * 72 */ 73 74 #ifndef __TC_CBC_MODE_H__ 75 #define __TC_CBC_MODE_H__ 76 77 #include <tinycrypt/aes.h> 78 79 #ifdef __cplusplus 80 extern "C" { 81 #endif 82 83 /** 84 * @brief CBC encryption procedure 85 * CBC encrypts inlen bytes of the in buffer into the out buffer 86 * using the encryption key schedule provided, prepends iv to out 87 * @return returns TC_CRYPTO_SUCCESS (1) 88 * returns TC_CRYPTO_FAIL (0) if: 89 * out == NULL or 90 * in == NULL or 91 * ctr == NULL or 92 * sched == NULL or 93 * inlen == 0 or 94 * (inlen % TC_AES_BLOCK_SIZE) != 0 or 95 * (outlen % TC_AES_BLOCK_SIZE) != 0 or 96 * outlen != inlen + TC_AES_BLOCK_SIZE 97 * @note Assumes: - sched has been configured by aes_set_encrypt_key 98 * - iv contains a 16 byte random string 99 * - out buffer is large enough to hold the ciphertext + iv 100 * - out buffer is a contiguous buffer 101 * - in holds the plaintext and is a contiguous buffer 102 * - inlen gives the number of bytes in the in buffer 103 * @param out IN/OUT -- buffer to receive the ciphertext 104 * @param outlen IN -- length of ciphertext buffer in bytes 105 * @param in IN -- plaintext to encrypt 106 * @param inlen IN -- length of plaintext buffer in bytes 107 * @param iv IN -- the IV for the this encrypt/decrypt 108 * @param sched IN -- AES key schedule for this encrypt 109 */ 110 int utils_tc_cbc_mode_encrypt(uint8_t *out, unsigned int outlen, const uint8_t *in, 111 unsigned int inlen, const uint8_t *iv, 112 const TCAesKeySched_t sched); 113 114 /** 115 * @brief CBC decryption procedure 116 * CBC decrypts inlen bytes of the in buffer into the out buffer 117 * using the provided encryption key schedule 118 * @return returns TC_CRYPTO_SUCCESS (1) 119 * returns TC_CRYPTO_FAIL (0) if: 120 * out == NULL or 121 * in == NULL or 122 * sched == NULL or 123 * inlen == 0 or 124 * outlen == 0 or 125 * (inlen % TC_AES_BLOCK_SIZE) != 0 or 126 * (outlen % TC_AES_BLOCK_SIZE) != 0 or 127 * outlen != inlen + TC_AES_BLOCK_SIZE 128 * @note Assumes:- in == iv + ciphertext, i.e. the iv and the ciphertext are 129 * contiguous. This allows for a very efficient decryption 130 * algorithm that would not otherwise be possible 131 * - sched was configured by aes_set_decrypt_key 132 * - out buffer is large enough to hold the decrypted plaintext 133 * and is a contiguous buffer 134 * - inlen gives the number of bytes in the in buffer 135 * @param out IN/OUT -- buffer to receive decrypted data 136 * @param outlen IN -- length of plaintext buffer in bytes 137 * @param in IN -- ciphertext to decrypt, including IV 138 * @param inlen IN -- length of ciphertext buffer in bytes 139 * @param iv IN -- the IV for the this encrypt/decrypt 140 * @param sched IN -- AES key schedule for this decrypt 141 * 142 */ 143 int utils_tc_cbc_mode_decrypt(uint8_t *out, unsigned int outlen, const uint8_t *in, 144 unsigned int inlen, const uint8_t *iv, 145 const TCAesKeySched_t sched); 146 147 #ifdef __cplusplus 148 } 149 #endif 150 151 #endif /* __TC_CBC_MODE_H__ */ 152