1 @c acl_blockcipher.texi
4 A block cipher is a algorithm which turns an input of fixed length into an
5 output of the same length (enciphering or encrypting). The transformation is
6 specified by a key which has to be of a fixed length, or a length of a given
8 Generally there is also an algorithm which turns the output back to the
9 previous input (deciphering or decrypting) when supplied with the same key.
11 @subsection List of available block ciphers
12 This is a list of the currently supported block ciphers:
14 @item AES (Advanced Encryption Standard)
19 @item DES (Data Encryption Standard)
26 @item Serpent (AES finalist)
30 @item TDES (Tripple DES)
35 @subsection high frequent parameters:
40 64 bits, 80 bits, 128 bits, 192 bits, 256 bits
41 (note that some block ciphers use different sizes)
44 @subsection Parts of a block cipher
46 @item encryption algorithm
47 @item decryption algorithm
48 @item mostly a set of subkeys
49 @item mostly a keyschedule which generates the subkeys from the supplied key.
51 As we can see here a block cipher normally has an algorithm besides the
52 encryption and decryption algorithm, which we call keyschedule.
53 Mostly the encryption and decryption algorithm consist of multiple rounds,
54 where each round (and sometimes between rounds) subkeys are needed to modify
55 the data. This subkeys are generated by the keyschedule and stored in a state
57 Note that not all algorithms need a pregenerated context, sometimes it is easy
58 to generate the subkeys "on the fly" so there is not always the need of a
59 context variable. In this case instead of a context the actual key is passed
60 to the encryption and decryption function.
62 @subsection API of block ciphers
63 The API is not always consistent due to the fact that we tried to optimize the
64 code for size (flash, heap and stack) and speed (runtime of the different
66 Generally the API of the implemented block ciphers consists of:
69 function, which implements the keyschedule
71 function, which implements the encryption algorithm
73 function, which implements the decryption algorithm
75 function, which frees memory allocated for the keyschedule
77 context type, which can contain a keyschedule and other information
79 @subsubsection @code{*_init} function
80 The @code{*_init} function generally takes a pointer to the key as first parameter.
81 For ciphers where the keysize is not fixed the second parameter gives the
82 keysize (in bits regularly) and the last parameter points to the context
84 For some ciphers there are additional parameters like the number of rounds,
85 these parameters generally occur before the context pointer.
87 @subsubsection @code{*_enc} and @code{*_dec} functions
88 The encryption and decryption function of a specific algorithm normally do not
89 differ in their parameters. Generally these functions take a pointer to the
90 block to operate on. Some ciphers allow to specify two blocks, where the first
91 one will be written to and the second will contain the source block. The two
92 blocks may overlap or be the same. Most ciphers have only one block pointer.
93 The block specified by the pointer is encrypted (if the @code{*_enc} function is
94 called) or decrypted (if the @code{*_dec} function is called).
95 The last parameter specifies either the key direct (with a pointer to it) or
96 is a pointer to a context created with the @code{*_init} function.
97 It is guaranteed that the context is in the same state as before the *_enc or
98 @code{*_dec} function call. Most @code{*_enc} and @code{*_dec} functions do not modify the context
99 at all, but some do for reducing dynamic memory requirements. So here are some
100 limitations to the reentrant property.
102 @subsubsection @code{*_free} function
103 A @code{*_free} function is only provided where needed (so most ciphers do not have
104 it). It is used to free memory dynamically allocated by the @code{*_init} function.
106 @subsubsection *_ctx_t type
107 A variable of the @code{*_ctx_t} type may hold information needed by the @code{*_enc} or
108 @code{*_dec} function. It is initialized by the @code{*_init} function. If dynamic memory is
109 allocated by the @code{*_init} function also a @code{*_free} function is provided which frees
110 the allocated memory. An initialized @code{*_ctx_t} variable may not be copied as it
111 may contains pointers to itself.
113 @section Block cipher abstraction layer (BCAL)
114 The BlockCipeherAbstractionLayer (BCAL) is an abstraction layer which allows
115 usage of all implemented block ciphers in a simple way. It abstracts specific
116 function details and is suitable for implementations which want to be flexible
117 in the choosing of specific block ciphers. Another important aspect is that this
118 abstraction layer enables the implementation of block cipher operating modes
119 independently from concrete ciphers. It is very simple to use and reassembles
120 the API used to implement individual ciphers.
122 The main component is a block cipher descriptor which contains the details of
123 the individual ciphers.
125 Care should be taken when choosing a specific keysize. It may be the case that
126 the chosen keysize is not compatible with the chosen block cipher.
129 @subsection Parts of BCAL
130 The BCAL is split up in different parts:
132 @item BCAL declaration for BCAL decriptors
133 @item algorithm specific definitions of BCAL decriptors
134 @item BCAL basic context type
135 @item BCAL basic functions
138 @subsection BCAL declaration for BCAL decriptors
139 The BCAL descriptor is a structure which is usually placed in FLASH or ROM since
140 modification is unnecessary. It contains all information required to use the
141 according block cipher.
145 uint8_t type; /* 1==block cipher */
149 uint16_t blocksize_b;
154 PGM_VOID_P valid_keysize_desc;
155 } bcdesc_t; /* block cipher descriptor type */
160 should be set to @samp{1} to indicate that this descriptor is for a
164 defines what kind of init function is provided and what kind of decrypt
165 and encrypt functions are provided.
169 if clear (@samp{0}) designates an init function with fixed key length, so
170 the length parameter is omitted (@code{init(void* ctx, void* key)}).
172 if set (@samp{1}) designates an init function which requires an explicit
173 keysize argument (@code{init(void*ctx, uint16_t length_b, void* key)}).
176 if clear (@samp{0}) designates that the encryption function transforms the
177 plaintext block in place to the ciphertext (@code{enc(void* block, void* ctx)}).
179 if set (@samp{1}) designates that the encryption function offers a dedicated
180 pointers for input and output. The two regions may be the same
181 (@code{enc(void* out, void* in, void*ctx)}).
184 if clear (@samp{0}) designates that the decryption function transforms the
185 ciphertext block in place to the plaintext (@code{dec(void* block, void* ctx)}).
187 if set (@samp{1}) designates that the decryption function offers a dedicated
188 pointers for input and output. The two regions may be the same
189 (@code{dec(void* out, void* in, void*ctx)}).
193 is a pointer to a zero terminated ASCII string giving the name of the
194 implemented primitive. On targets with Harvard-architecture the string resides
195 in code memory (FLASH, ROM, ...).
198 is the number of bytes which should be allocated for the context variable.
201 is the number of bits on which the encrypt and decrypt function work on.
204 is a pointer to the init function (see @samp{flags} how the init function
205 should be called). If there is no init function this field is NULL.
208 is a pointer to the encryption function (see @samp{flags} how the encryption
209 function should be called).
212 is a pointer to the decryption function (see @samp{flags} how the decryption
213 function should be called).
216 is a pointer to the free function or NULL if there is no free function.
218 @item valid_keysize_desc
219 is a pointer to a keysize descriptor structure which is used to validate
220 that the chosen keysize is valid
223 @subsection BCAL-Basic context
224 Besides the context types for individual ciphers there is a generic context
225 type for BCAL. This is the context to use when using BCAL based functions.
226 The BCAL context has the following structure:
236 a pointer to the BCAL descriptor
240 pointer to the cipher specific context
245 @subsection BCAL-Basic
246 BCAL-Basic provides the basic features of an block cipher on top of the
247 BCAL. To use it you simply have to include the algorithms you want to use,
248 the BCAL descriptor file and of course the BCAL-Basic implementation.
250 The following functions are provided:
251 @subsubsection @code{bcal_cipher_init}
252 @code{uint8_t bcal_cipher_init(const bcdesc_t* cipher_descriptor, const void* key, uint16_t keysize_b, bcgen_ctx_t* ctx)}
253 this function initializes a BCAL context based on the given BCAL descriptor
254 pointer (first parameter) with a given key (second parameter) of a given length
255 (third parameter). The context to initialize is designated by the pointer
256 passed as fourth parameter.
258 If everything works fine @samp{0} is returned. In the case something fails
259 the following codes are returned:
262 The specified keysize is not available with this cipher
264 It was not possible to allocate enough memory to hold the key.
265 (This is returned when there is no actual init function and you ran out
268 It was not possible to allocate enough memory to hold the context variable
269 for the selected cipher.
272 @subsubsection @code{bcal_cipher_free}
273 @code{void bcal_cipher_free(bcgen_ctx_t* ctx)} this function frees the memory
274 allocated by the init function and should be called whenever you are finished
275 with BCAL context. It automatically also calls the @code{free} function if
278 @subsubsection @code{bcal_cipher_enc}
279 @code{void bcal_cipher_enc(void* block, const bcgen_ctx_t* ctx)}
280 this function encrypts a block in-place using a given BCAL contex.
282 @subsubsection @code{bcal_cipher_dec}
283 @code{void bcal_cipher_dec(void* block, const bcgen_ctx_t* ctx)}
284 this function decrypts a block in-place using a given BCAL contex.
286 @subsubsection @code{bcal_cipher_getBlocksize_b}
287 @code{uint16_t bcal_cipher_getBlocksize_b(const bcdesc_t* desc)}
288 this function returns the block size of a given cipher by using the BCAL
289 descriptor (to which a pointer must be passed).
291 @subsubsection @code{bcal_cipher_getKeysizeDesc}
292 @code{PGM_VOID_P bcal_cipher_getKeysizeDesc(const bcdesc_t* desc)}
293 this function returns a pointer to the keysize descriptor of a given cipher by
294 using the BCAL descriptor (to which a pointer must be passed).