102 lines
10 KiB
Markdown
102 lines
10 KiB
Markdown
# **µAES**
|
|
|
|
**A minimalist ANSI-C compatible API for the AES encryption and block cipher modes**.
|
|
|
|
[](../../ "µAES")
|
|
|
|
[](../../../../user-attachments/files/22698833/micro_aes-v1.11.0.zip "µAES-v1.11.0.zip")
|
|
[](https://opensource.org/licenses/Apache-2.0)
|
|
|
|
This is a highly flexible, small and portable implementation of most of the AES related algorithms.
|
|
|
|
## Features
|
|
|
|
* <font size="4">Comprehensive</font> — supports all standard AES key sizes (128, 192 and 256 bits) along with almost every block-cipher mode.
|
|
|
|
All popular (and some unpopular) block ciphering modes of the AES are implemented in this library, such as
|
|
[**_ECB_**, **_CBC_**, **_CFB_**, **_OFB_**, **_CTR_**](https://csrc.nist.gov/publications/detail/sp/800-38a/final "Described in NIST SP 800-38A"),
|
|
[**_GCM_**](https://csrc.nist.gov/publications/detail/sp/800-38d/final "NIST SP 800-38D"),
|
|
[**_CCM_**](https://csrc.nist.gov/publications/detail/sp/800-38c/final "NIST SP 800-38C"),
|
|
[**_XTS_**](https://csrc.nist.gov/publications/detail/sp/800-38e/final "NIST SP 800-38E"),
|
|
[**_KW_**](https://csrc.nist.gov/publications/detail/sp/800-38f/final "NIST SP 800-38F")
|
|
[(_KWA_)](https://www.rfc-editor.org/rfc/rfc3394 "RFC-3394"),
|
|
[**_OCB_**](https://www.rfc-editor.org/rfc/rfc7253.html "RFC-7253"),
|
|
[**_EAX_**](../../files/10318260/eax.pdf "Bellare-Rogaway-Wagner paper. For more info, see wikipedia.")
|
|
/[**_EAX'_**](../../files/10318265/eax-prime.pdf "Theoretically broken, but ANSI C12.22 has not withdrawn it yet. so here we go..."),
|
|
[**_SIV_**](../../files/10318348/siv.pdf "Also described in the RFC-5297"),
|
|
[**_GCM-SIV_**](https://www.rfc-editor.org/rfc/rfc8452.html "RFC-8452"),
|
|
[**_FPE_** (**_FF1_** /**_FF3-1_**)](https://csrc.nist.gov/publications/detail/sp/800-38g/final "NIST SP 800-38G"),
|
|
and furthermore, authentication APIs for
|
|
[**_CMAC_**](https://csrc.nist.gov/publications/detail/sp/800-38b/final "NIST SP 800-38B") and
|
|
[**_Poly1305-AES_**](../../files/10319003/poly1305.pdf "D. J. Bernstein's website: cr.yp.to/mac.html").
|
|
|
|
* <font size="4">All in one</font> — the whole implementation code is in a single C file with no external dependencies.
|
|
|
|
* <font size="4">Clear and readable code</font> — written in a layman-friendly way with lots of comments to clarify its purpose. Also the code styling is a bit different, and IMHO more eye-catching, than what you might see in other implementations.
|
|
|
|
* <font size="4">Flexible</font> — most features are controllable by macros, so that you can just pick up what you need and disable the unnecessary parts. These [macros](micro_aes.h#L544) are defined in the header file and comments are added for each of them to explain what they represent. *Please read [those comments](micro_aes.h#L481) carefully before using the code*.
|
|
|
|
* <font size="4">Lightweight</font> — the API has very little memory footprint and compiled code size. The amount of RAM used by the functions doesn't exceed a few hundred bytes in most extreme cases. Moreover, the ROM space of µAES is optimized as much as possible.
|
|
|
|
For example if you disable all other macros and just stick with the GCM, the compiled code size with `gcc -Os` will be less than **2.5KB** for either _AES-128-GCM_ or _AES-256-GCM_. This can be verified by running:
|
|
```
|
|
$ arm-none-eabi-gcc -Os -c micro_aes.c -o arm.o
|
|
$ avr-gcc -mmcu=atmega16 -Os -c micro_aes.c -o avr.o
|
|
```
|
|
and checking the results with `size` command. See [this page](https://stackoverflow.com/q/31217181/5358284) for more info.
|
|
```
|
|
$ size arm.o
|
|
text data bss dec hex filename
|
|
2112 0 176 2288 8f0 arm.o
|
|
|
|
$ avr-size avr.o
|
|
text data bss dec hex filename
|
|
2242 0 176 2418 972 avr.o
|
|
```
|
|
|
|
* <font size="4">Portable</font> — µAES is fully compliant with the ANSI-C or C89 standard which, combined with its small size and independence from external libraries, makes it a competent candidate for embedded systems and mini applications.
|
|
|
|
You can even [compile it](../../../../user-attachments/files/21704976/TCPROJ.zip "instructions and prerequisites") with a vintage [Borland Turbo C](https://hackaday.com/2023/04/08/revisiting-borland-turbo-c-and-c/) or a teeny [tiny C compiler](https://bellard.org/tcc/):
|
|
```
|
|
path/to/tcc.exe -c micro_aes.c
|
|
path/to/tcc.exe micro_aes.c -run main.c
|
|
```
|
|
|
|
* <font size="4">Fast</font> — the encryption or decryption speed is fairly high, especially when there is no authentication. Since code simplicity and minimizing memory usage was a top priority, some functions may not look so efficient speed-wise; though faster methods are hardly portable or easy to understand. As a result, paralellization or advanced CPU optimizations are not a feature of µAES —which might affect its overall speed.
|
|
|
|
For 32-bit CPUs a few tweaks are discussed in [x86 improvements](x86-improvements). It's worth noting that speed is not always a blessing in cryptography and sometimes slower codes turn out to be more secure. One must be wary of those speedups that make the code more susceptible to [timing attacks](https://en.wikipedia.org/wiki/Timing_attack).
|
|
|
|
## Examples
|
|
See the [main C](main.c) file which has some example codes demonstrating how to use the API functions, along with test vectors.
|
|
Also check out the [/testvectors](testvectors/README.md) directory.
|
|
|
|
## Remarks
|
|
|
|
* First, please keep in mind that most security experts strongly warn *against* implementing your own version of AES—or other ciphering algorithms; AND THEY ARE ABSOLUTELY RIGHT!
|
|
|
|
Everyone who is becoming familiar with cryptography, should first sign [Jeff Moser's](https://www.moserware.com/2009/09/stick-figure-guide-to-advanced.html "A stick figure guide to AES") so-called "Foot Shooting Prevention Agreement". It's a great article if you haven't read it yet. But to save you a click and scroll, I put a copy of the contract below.
|
|
|
|
With that in mind, I shall say that the main purpose of developing µAES was purely educational. I learned a lot during writing these codes and hope that somebody, some day, would gain a bit of knowledge from it.
|
|
|
|
* The code is optimized for small embedded systems and 8-bit microcontrollers with limited amount of memory. So for stronger CPUs it is plausible to speed-up the code [by applying some simple changes](x86-improvements). If you are working with an 8-bit microcontroller, it is recommended to take a look at Nigel Jones' rather old article "[Efficient C Code for 8-bit Microcontrollers](https://barrgroup.com/embedded-systems/how-to/efficient-c-code)". It contains some highly useful tips to better program such systems.
|
|
|
|
* There are some standard encryption algorithms specifically designed for small embedded systems, that minimize the use of computational resources while maintaining a high level of security. The most prominent one is the ASCON cipher suite which recently got [approved by the NIST](https://csrc.nist.gov/Projects/lightweight-cryptography/finalists). **_I have created [another repository](../../../simple-ASCON "Simple ASCON") to implement those algorithms as well_**.
|
|
|
|
* For the sake of simplicity, it is often assumed that the input parameters of the functions are well defined, and the user knows what they're doing. As a result, a bunch of error checks are just skipped. Obviously, this is a naive and sometimes dangerous assumption. One must be aware that in a serious application, anything can be fed into the functions and they must take all the necessary precautions for erroneous parameters.
|
|
|
|
* µAES was originally influenced by [kokke's tiny-AES](https://github.com/kokke/tiny-AES-c) library, but I have made a handful of modifications to make it smaller and more efficient.
|
|
|
|
<p align="center">
|
|
<img src="https://user-images.githubusercontent.com/1939363/221410529-ea6bc2ab-b44c-4a34-a617-4a2ec3d16d0f.png" alt="The foot-shooting prevention agreement taken from Jeff Moser's blog"/>
|
|
</p>
|
|
|
|
---
|
|
|
|
All the contents of this repository (except the ones that I didn't write!) are subject to the terms of Apache 2.0 license.
|
|
|
|
|
|
|
|
Copyright © 2022 - polfosol
|
|
|
|
<font size="3" face="Georgia">_In sorrowful memory of_ [**_Mahsa Amini_**](https://en.wikipedia.org/wiki/Death_of_Mahsa_Amini "MAY ALL THE DICTATORS ROT IN HELL")</font> :black_heart:
|