1 \input texinfo @c -*-texinfo-*-
3 @setfilename acl-manual.info
4 @settitle AVR/ARM-Crypto-Lib Manual 1.0
8 This is a short example of a complete Texinfo file.
9 Copyright © 2011 Daniel Otte (@email{daniel.otte@@rub.de})
13 @title AVR/ARM-Crypto-Lib Manual 1.0
15 @vskip 0pt plus 1filll
18 @c Output the table of the contents at the beginning.
27 This documentation is a guide to the AVR-Crypto-Lib and ARM-Crypto-Lib.
28 Instead of documenting the full API and each function we choose the approach
29 of documenting the structure of the API so you know what to do when you want
32 @chapter Generic stuff
33 @section File organisation
34 @section Build process
35 @section Testing system
36 @section Sizes in bits and bytes
37 Working with cryptographic functions involves working with different
38 lengths. Some times you want to know it in bits, sometimes in bytes and another
39 time in words (how long a word is must be defined by the context).
40 To reduce confusion, frustration and to avoid bugs we suffix a length
41 parameter with either _b, _B or _w depending on the meaning.
42 _b means in bits and _B means in bytes (big b big word) and _w meaning words.
44 @chapter Symmetric primitives
46 @section Block ciphers
47 @subsection What a block cipher does
48 A block cipher is a algorithm which turn an input of fixed length into an
49 output of the same length (enciphering or encrypting). The transformation is
50 specified by a key which has to be of a fixed length, or a length of a given
52 Generally there is also an algorithm which turns the output back to the
53 previous input (deciphering or decrypting) when supplied with the same key.
55 @subsection List of available block ciphers
56 This is a list of the currently supported block ciphers:
58 @item AES (Advanced Encryption Standard)
63 @item DES (Data Encryption Standard)
70 @item Serpent (AES finalist)
74 @item TDES (Tripple DES)
79 @subsection high frequent parameters:
80 block size: 64 bits, 128 bits
81 key size: 64 bits, 80 bits, 128 bits, 192 bits, 256 bits
82 (note that some block ciphers use different sizes)
84 @subsection Parts of a block cipher
86 @item encryption algorithm
87 @item decryption algorithm
88 @item mostly a set of subkeys
89 @item mostly a keyschedule which generates the subkeys from the supplied key.
91 As we can see here a block cipher normally has an algorithm besides the
92 encryption and decryption algorithm, which we call keyschedule.
93 Mostly the encryption and decryption algorithm consist of multiple rounds,
94 where each round (and sometimes between rounds) subkeys are needed to modify
95 the data. This subkeys are generated by the keyschedule and stored in a state
97 Note that not all algorithms need a pregenerated context, sometimes it is easy
98 to generate the subkeys "on the fly" so there is not always the need of a
99 context variable. In this case instead of a context the actual key is passed
100 to the encryption and decryption function.
102 @subsection API of block ciphers
103 The API is not always consistent due to the fact that we tried to optimize the
104 code for size (flash, heap and stack) and speed (runtime of the different
106 Generally the API of the implemented block ciphers consists of:
108 @item *_init function, which implements the keyschedule
109 @item *_enc function, which implements the encryption algorithm
110 @item *_dec function, which implements the decryption algorithm
111 @item *_free function, which frees memory allocated for the keyschedule
112 @item *_ctx_t context type, which can contain a keyschedule and other information
114 @subsubsection *_init function
115 The *_init function generally takes a pointer to the key as first parameter.
116 For ciphers where the keysize is not fixed the second parameter gives the
117 keysize (in bits regularly) and the last parameter points to the context
119 For some ciphers there are additional parameters like the number of rounds,
120 these parameters generally occur before the context pointer.
122 @subsubsection *_enc and *_dec functions
123 The encryption and decryption function of a specific algorithm normally do not
124 differ in their parameters. Generally these functions take a pointer to the
125 block to operate on. Some ciphers allow to specify two blocks, where the first
126 one will be written to and the second will contain the source block. The two
127 blocks may overlap or be the same. Most ciphers have only one block pointer.
128 The block specified by the pointer is encrypted (if the *_enc function is
129 called) or decrypted (if the *_dec function is called).
130 The last parameter specifies either the key direct (with a pointer to it) or
131 is a pointer to a context created with the *_init function.
132 It is guaranteed that the context is in the same state as before the *_enc or
133 *_dec function call. Most *_enc and *_dec functions do not modify the context
134 at all, but some do for reducing dynamic memory requirements. So here are some
135 limitations to the reentrant property.
137 @subsubsection *_free function
138 A *_free function is only provided where needed (so most ciphers do not have
139 it). It is used to free memory dynamically allocated by the *_init function.
141 @subsubsection *_ctx_t type
142 A variable of the *_ctx_t type may hold information needed by the *_enc or
143 *_dec function. It is initialized by the *_init function. If dynamic memory is
144 allocated by the *_init function also a *_free function is provided which frees
145 the allocated memory. An initialized *_ctx_t variable may not be copied as it
146 may contains pointers to itself.
148 @section Block cipher abstraction layer (BCAL)
149 The BlockCipeherAbstractionLayer (BCAL) is an abstraction layer which allows
150 usage of all implemented block ciphers in a simple way. It abstracts specific
151 function details and is suitable for implementations which want to be flexible
152 in the choosing of specific block ciphers. Another important aspect is that this
153 abstraction layer enables the implementation of block cipher operating modes
154 independently from concrete ciphers. It is very simple to use and reassembles
155 the API used to implement individual ciphers.
157 The main component is a block cipher descriptor which contains the details of
158 the individual ciphers.
160 Care should be taken when choosing a specific keysize. It may be the case that
161 the chosen keysize is not compatible with the chosen block cipher.
164 @subsection Parts of BCAL
165 The BCAL is split up in different parts:
167 @item BCAL declaration for BCAL decriptors
168 @item algorithm specific definitions of BCAL decriptors
169 @item BCAL basic context type
170 @item BCAL basic functions
173 @subsubsection BCAL declaration for BCAL decriptors
174 The BCAL descriptor is a structure which is usually placed in FLASH or ROM since
175 modification is unnecessary. It contains all information required to use the
176 according block cipher.
180 uint8_t type; /* 1==block cipher */
184 uint16_t blocksize_b;
189 PGM_VOID_P valid_keysize_desc;
190 } bcdesc_t; /* block cipher descriptor type */
195 should be set to @samp{1} to indicate that this descriptor is for a
199 defines what kind of init function is provided and what kind of decrypt
200 and encrypt functions are provided.
204 if clear (@samp{0}) designates an init function with fixed key length, so
205 the length parameter is omitted (@code{init(void* ctx, void* key)}).
207 if set (@samp{1}) designates an init function which requires an explicit
208 keysize argument (@code{init(void*ctx, uint16_t length_b, void* key)}).
211 if clear (@samp{0}) designates that the encryption function transforms the
212 plaintext block in place to the ciphertext (@code{enc(void* block, void* ctx)}).
214 if set (@samp{1}) designates that the encryption function offers a dedicated
215 pointers for input and output. The two regions may be the same
216 (@code{enc(void* out, void* in, void*ctx)}).
219 if clear (@samp{0}) designates that the decryption function transforms the
220 ciphertext block in place to the plaintext (@code{dec(void* block, void* ctx)}).
222 if set (@samp{1}) designates that the decryption function offers a dedicated
223 pointers for input and output. The two regions may be the same
224 (@code{dec(void* out, void* in, void*ctx)}).
228 is a pointer to a zero terminated ASCII string giving the name of the
229 implemented primitive. On targets with Harvard-architecture the string resides
230 in code memory (FLASH, ROM, ...).
233 is the number of bytes which should be allocated for the context variable.
236 is the number of bits on which the encrypt and decrypt function work on.
239 is a pointer to the init function (see @samp{flags} how the init function
240 should be called). If there is no init function this field is NULL.
243 is a pointer to the encryption function (see @samp{flags} how the encryption
244 function should be called).
247 is a pointer to the decryption function (see @samp{flags} how the decryption
248 function should be called).
251 is a pointer to the free function or NULL if there is no free function.
253 @item valid_keysize_desc
254 is a pointer to a keysize descriptor structure which is used to validate
255 that the chosen keysize is valid
258 @subsubsection BCAL-Basic context
259 Besides the context types for individual ciphers there is a generic context
260 type for BCAL. This is the context to use when using BCAL based functions.
261 The BCAL context has the following structure:
271 a pointer to the BCAL descriptor
275 pointer to the cipher specific context
280 @subsubsection BCAL-Basic
281 BCAL-Basic provides the basic features of an block cipher on top of the
282 BCAL. To use it you simply have to include the algorithms you want to use,
283 the BCAL descriptor file and of course the BCAL-Basic implementation.
285 The following functions are provided:
287 @item bcal_cipher_init
288 @code{uint8_t bcal_cipher_init(const bcdesc_t* cipher_descriptor, const void* key, uint16_t keysize_b, bcgen_ctx_t* ctx)}
289 this function initializes a BCAL context based on the given BCAL descriptor
290 pointer (first parameter) with a given key (second parameter) of a given length
291 (third parameter). The context to initialize is designated by the pointer
292 passed as fourth parameter.
294 If everything works fine @samp{0} is returned. In the case something fails
295 the following codes are returned:
298 The specified keysize is not available with this cipher
300 It was not possible to allocate enough memory to hold the key.
301 (This is returned when there is no actual init function and you ran out
304 It was not possible to allocate enough memory to hold the context variable
305 for the selected cipher.
308 @item bcal_cipher_free
309 @code{void bcal_cipher_free(bcgen_ctx_t* ctx)} this function frees the memory
310 allocated by the init function and should be called whenever you are finished
311 with BCAL context. It automatically also calls the @code{free} function if
314 @item bcal_cipher_enc
315 @code{void bcal_cipher_enc(void* block, const bcgen_ctx_t* ctx)}
316 this function encrypts a block in-place using a given BCAL contex.
318 @item bcal_cipher_dec
319 @code{void bcal_cipher_dec(void* block, const bcgen_ctx_t* ctx)}
320 this function decrypts a block in-place using a given BCAL contex.
322 @item bcal_cipher_getBlocksize_b
323 @code{uint16_t bcal_cipher_getBlocksize_b(const bcdesc_t* desc)}
324 this function returns the block size of a given cipher by using the BCAL
325 descriptor (to which a pointer must be passed).
327 @item bcal_cipher_getKeysizeDesc
328 @code{PGM_VOID_P bcal_cipher_getKeysizeDesc(const bcdesc_t* desc)}
329 this function returns a pointer to the keysize descriptor of a given cipher by
330 using the BCAL descriptor (to which a pointer must be passed).
333 @section Modes of operation
335 @section Stream ciphers
336 @subsection List of available stream ciphers
337 @subsection API of stream ciphers
338 @subsection Stream cipher abstraction layer (SCAL)
340 @section Hash functions
341 @subsection List of available hash functions
342 @subsection API of hash functions
343 @subsection Hash function abstraction layer (HFAL)
345 @section MAC functions
346 @section Pseudo random number generators (PRNGs)
352 @chapter Big integer functions
354 @chapter Asymmetric Primitives