1 /* ctr_mode.h - TinyCrypt interface to CTR mode */
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 CTR mode.
36  *
37  *  Overview:  CTR (pronounced "counter") mode is a NIST approved mode of
38  *             operation defined in SP 800-38a. It can be used with any
39  *             block cipher to provide confidentiality of strings of any
40  *             length. TinyCrypt hard codes AES128 as the block cipher.
41  *
42  *  Security:  CTR mode achieves confidentiality only if the counter value is
43  *             never reused with a same encryption key. If the counter is
44  *             repeated, than an adversary might be able to defeat the scheme.
45  *
46  *             A usual method to ensure different counter values refers to
47  *             initialize the counter in a given value (0, for example) and
48  *             increases it every time a new block is enciphered. This naturally
49  *             leaves to a limitation on the number q of blocks that can be
50  *             enciphered using a same key: q < 2^(counter size).
51  *
52  *             TinyCrypt uses a counter of 32 bits. This means that after 2^32
53  *             block encryptions, the counter will be reused (thus losing CBC
54  *             security). 2^32 block encryptions should be enough for most of
55  *             applications targeting constrained devices. Applications intended
56  *             to encrypt a larger number of blocks must replace the key after
57  *             2^32 block encryptions.
58  *
59  *             CTR mode provides NO data integrity.
60  *
61  *  Requires: AES-128
62  *
63  *  Usage:     1) call tc_ctr_mode to process the data to encrypt/decrypt.
64  *
65  */
66 
67 #ifndef __TC_CTR_MODE_H__
68 #define __TC_CTR_MODE_H__
69 
70 #include <tinycrypt/aes.h>
71 #include <tinycrypt/constants.h>
72 
73 #ifdef __cplusplus
74 extern "C" {
75 #endif
76 
77 /**
78  *  @brief CTR mode encryption/decryption procedure.
79  *  CTR mode encrypts (or decrypts) inlen bytes from in buffer into out buffer
80  *  @return returns TC_CRYPTO_SUCCESS (1)
81  *          returns TC_CRYPTO_FAIL (0) if:
82  *                out == NULL or
83  *                in == NULL or
84  *                ctr == NULL or
85  *                sched == NULL or
86  *                inlen == 0 or
87  *                outlen == 0 or
88  *                inlen != outlen
89  *  @note Assumes:- The current value in ctr has NOT been used with sched
90  *              - out points to inlen bytes
91  *              - in points to inlen bytes
92  *              - ctr is an integer counter in littleEndian format
93  *              - sched was initialized by aes_set_encrypt_key
94  * @param out OUT -- produced ciphertext (plaintext)
95  * @param outlen IN -- length of ciphertext buffer in bytes
96  * @param in IN -- data to encrypt (or decrypt)
97  * @param inlen IN -- length of input data in bytes
98  * @param ctr IN/OUT -- the current counter value
99  * @param blk_off IN/OUT -- the offset in the block
100  * @param sched IN -- an initialized AES key schedule
101  */
102 int tc_ctr_mode(uint8_t *out, unsigned int outlen, const uint8_t *in,
103 		unsigned int inlen, uint8_t *ctr, uint32_t *blk_off,
104 		const TCAesKeySched_t sched);
105 
106 #ifdef __cplusplus
107 }
108 #endif
109 
110 #endif /* __TC_CTR_MODE_H__ */
111