Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/polfosol/micro-aes
A minimalist implementation of AES algorithms in C
https://github.com/polfosol/micro-aes
aes aes-128 aes-256 aes-cbc aes-gcm aes-gcm-siv aes-ocb ansi-c c89 cplusplus cryptography embedded-systems poly1305
Last synced: about 1 month ago
JSON representation
A minimalist implementation of AES algorithms in C
- Host: GitHub
- URL: https://github.com/polfosol/micro-aes
- Owner: polfosol
- License: apache-2.0
- Created: 2022-08-20T18:21:19.000Z (about 2 years ago)
- Default Branch: master
- Last Pushed: 2024-05-05T15:28:04.000Z (6 months ago)
- Last Synced: 2024-10-12T17:21:40.722Z (about 1 month ago)
- Topics: aes, aes-128, aes-256, aes-cbc, aes-gcm, aes-gcm-siv, aes-ocb, ansi-c, c89, cplusplus, cryptography, embedded-systems, poly1305
- Language: C
- Homepage:
- Size: 2.95 MB
- Stars: 33
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# **µAES**
**A minimalist ANSI-C compatible API for the AES encryption and block cipher modes**.
[](../../ "µAES")  [](../../files/15161967/micro_aes-v1.9.1.zip "micro_aes-v1.9.1.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
* Comprehensive — 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 "It is theoretically broken and shouldn't be used. The ANSI C12.22 has not withdrawn it yet, so here we go."), [**_SIV_**](../../files/10318348/siv.pdf "You may also refer to 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 "From D. J. Bernstein's website: cr.yp.to/mac.html").
* All in one — the whole implementation code is in a single C file with no external dependencies.
* Clear and readable code — 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.
* Flexible — most features are controllable by macros, so that you can just pick up what you need and disable the unnecessary parts. These macros are defined in [the header file](micro_aes.h) and comments are added for each of them to explain what they represent. *Please read those comments carefully before using the code*.
* Lightweight — 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_. You can verify this 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
2088 0 176 2264 8d8 arm.o
$ avr-size avr.o
text data bss dec hex filename
2196 0 176 2372 944 avr.o
```
* Portable — µ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 with [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
```
* Fast — 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.
---
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
_In sorrowful memory of_ [**_Mahsa Amini_**](https://en.wikipedia.org/wiki/Death_of_Mahsa_Amini "MAY ALL THE DICTATORS ROT IN HELL") :black_heart: