Cyclic0007/micro-AES
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

added FPE (FF1)

Browse Source
This commit is contained in:
polfosol
2022-12-04 20:51:19 +03:30
parent 2bb470f669
commit 0c9ca7ebec
5 changed files with 617 additions and 314 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
README.md
View File

@@ -2,7 +2,7 @@
**A minimalist ANSI-C compatible code for most of the AES-related algorithms**.
[![GitHub release](https://img.shields.io/static/v1?message=%C2%B5AES&logo=github&labelColor=gray&color=blue&logoColor=white&label=%20)](https://github.com/polfosol/micro-AES) ![C](https://img.shields.io/badge/langauge-C-blue.svg) [![Build Status](https://img.shields.io/badge/v1.0.1-blue)](https://github.com/polfosol/micro-AES/files/9952994/micro_aes-v1.0.1.zip) [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![GitHub release](https://img.shields.io/static/v1?message=%C2%B5AES&logo=github&labelColor=gray&color=blue&logoColor=white&label=%20)](https://github.com/polfosol/micro-AES) ![C](https://img.shields.io/badge/langauge-C-blue.svg) [![Build Status](https://img.shields.io/badge/v1.2.0-blue)](https://github.com/polfosol/micro-AES/files/10149095/micro_aes-v1.2.0.zip) [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
This library is a highly flexible and portable implementation of different AES encryption schemes and block cipher modes.
@@ -20,7 +20,7 @@ This library is a highly flexible and portable implementation of different AES e
* $\textrm{\textbf{Lightweight}}$ — the API has very little memory footprint and compiled code size. In my own tests, the amount of RAM used by the functions didn'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 will be around **3KB** with `gcc -Os` on x86 machine for either AES-128-GCM or AES-256-GCM.
* $\textrm{\textbf{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. But it is worth noting that faster methods are hardly portable or easy to understand. So it's not a surprise that paralellization or advanced CPU optimizations are not a feature of µAES —which will affect its overall speed.
* $\textrm{\textbf{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. But it is worth noting that faster methods are hardly portable or easy to understand. So it's no surprise that paralellization or advanced CPU optimizations are not a feature of µAES —which will affect its overall speed.
As a side note, 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).
@@ -34,13 +34,13 @@ This library is a highly flexible and portable implementation of different AES e
tcc -o micro_aes.exe main.o micro_aes.o
```
## Examples
See the `main.c` file which contains test vectors and example codes illustrating how to use the API functions.
See the `main.c` file which has some example codes illustrating how to use the API functions, along with test vectors.
## Remarks
* First and foremost, 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!
* 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) so-called "Foot Shooting Prevention Agreement". To save you some clicks, I have put a copy of it below.
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) so-called "Foot Shooting Prevention Agreement". To save you a click and scroll, I have put a copy of it below (but it is recommended to follow the link and read that article if you haven't).
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 I hope that somebody, some day, would gain a bit of knowledge from it.

31
main.c
View File

@@ -2,7 +2,7 @@
==============================================================================
Name : main.c
Author : polfosol
Version : 9.6.0.0
Version : 9.8.1.0
Copyright : copyright © 2022 - polfosol
Description : test vectors for µAES ™ library, mostly generated by Crypto++ ®
==============================================================================
@@ -67,6 +67,7 @@ static const char
25111d34bb2bfcc2 25", /* 16 bytes i.v. PREPENDED */
*cmac_hash = "b887df1fd8c239c3 e8a64d9822e21128",
*p1305_mac = "3175bed9bd01821a 62d4c7bef26722be",
*fpe_plain = "0123456789abcdefghi",
*wrapped = "1FA68B0A8112B447 AEF34BD8FB5A7B82 9D3E862371D2CFE5";
#elif AES_KEY_LENGTH == 24 /* ↓↓↓↓ PKCS#7 is enabled */
*ecbcipher = "af1893f0fbb09a43 7f6b0fd4f4977890 7bb85cccf1e9d2e3 ebe5bae935107868\
@@ -91,8 +92,8 @@ static void check(const char* method, uint8_t* result, uint8_t* expected, size_t
static void str2bytes(const char* str, uint8_t* bytes)
#define char2num(c) (c > '9' ? (c & 7) + 9 : c & 0xF)
{
size_t i, j;
for (i = 0, j = ~0; str[i]; ++i)
unsigned i, j;
for (i = 0, j = ~0U; str[i]; ++i)
{
if (str[i] < '0' || str[i] > 'f') continue;
if (j++ & 1) bytes[j / 2] = char2num(str[i]) << 4;
@@ -231,6 +232,30 @@ int main()
AES_KEY_unwrap(mainKey, test, AES_KEY_LENGTH + 8, output);
check("key unwrapping", output, key + 32, AES_KEY_LENGTH);
#endif
#if FF_X == 3 && AES_KEY_LENGTH == 16
str2bytes("EF 43 59 D8 D5 80 AA 4F 7F 03 6D 6F 04 FC 6A 94", key);
str2bytes("D8 E7 92 0A FA 33 0A 73", a);
#elif FPE && AES_KEY_LENGTH == 16
str2bytes("2B 7E 15 16 28 AE D2 A6 AB F7 15 88 09 CF 4F 3C", key);
#if CUSTOM_ALPHABET == 2
st = 19; sa = 11;
str2bytes("37 37 37 37 70 71 72 73 37 37 37", a);
memcpy(test, "a9tv40mll9kdu509eum", st);
#elif !CUSTOM_ALPHABET
sa = 10; st = 10;
str2bytes("39 38 37 36 35 34 33 32 31 30", a);
memcpy(test, "6124200773", st);
AES_FPE_encrypt(key, a, sa, fpe_plain, st, output);
check("FF1 encryption", output, test, st);
AES_FPE_decrypt(key, a, sa, test, st, output);
check("FF1 decryption", output, (void*) fpe_plain, st);
memcpy(test, "2433477484", st); sa = 0;
#endif
AES_FPE_encrypt(key, a, sa, fpe_plain, st, output);
check("FF1 encryption", output, test, st);
AES_FPE_decrypt(key, a, sa, test, st, output);
check("FF1 decryption", output, (void*) fpe_plain, st);
#endif
/** a template for "OFFICIAL TEST VECTORS": */
#if OCB && EAX && SIV && GCM_SIV && POLY1305 && AES_KEY_LENGTH == 16

759
micro_aes.c
View File

File diff suppressed because it is too large Load Diff

129
micro_aes.h
View File

@@ -2,14 +2,14 @@
==============================================================================
Name : micro_aes.h
Author : polfosol
Version : 9.6.0.0
Version : 9.8.1.0
Copyright : copyright © 2022 - polfosol
Description : μAES ™ is a minimalist all-in-one library for AES encryption
==============================================================================
*/
#ifndef _MICRO__AES_
#define _MICRO__AES_
#ifndef MICRO_AES_H_
#define MICRO_AES_H_
/**----------------------------------------------------------------------------
You can use different AES algorithms by changing this macro. Default is AES-128
@@ -83,6 +83,11 @@ Refer to the BOTTOM OF THIS DOCUMENT for some explanations about these macros:
#define AES_PADDING 0 /* other valid values: (1) PKCS#7 (2) IEC7816-4 */
#endif
#if FPE
#define CUSTOM_ALPHABET 0 /* if disabled, use default alphabet (digits 0..9) */
#define FF_X 1 /* algorithm type: (1) for FF1, or (3) for FF3-1 */
#endif
#if CTR_NA
#define CTR_IV_LENGTH 12 /* for using the last 32 bits as counter */
#define CTR_STARTVALUE 1 /* recommended value according to the RFC-3686. */
@@ -90,7 +95,7 @@ Refer to the BOTTOM OF THIS DOCUMENT for some explanations about these macros:
#if CCM
#define CCM_NONCE_LEN 11 /* for 32-bit count (since one byte is reserved). */
#define CCM_TAG_LEN 16 /* an even number in the range of 4..16 */
#define CCM_TAG_LEN 16 /* must be an even number in the range of 4..16 */
#endif
#if GCM
@@ -110,11 +115,16 @@ Refer to the BOTTOM OF THIS DOCUMENT for some explanations about these macros:
Since stdint.h is not a part of ANSI-C, we may need a 'trick' to use uint8_t
-----------------------------------------------------------------------------*/
#include <string.h>
#if __STDC_VERSION__ > 199900L
#if __STDC_VERSION__ > 199900L || __cplusplus > 201100L || defined(_MSC_VER)
#include <stdint.h>
#else
typedef unsigned char uint8_T;
#define uint8_t uint8_T
#include <limits.h>
typedef unsigned char uint8_t;
#if INT_MAX > 100000L
typedef int int32_t;
#else
typedef long int32_t;
#endif
#endif
#ifdef __cplusplus
@@ -136,14 +146,14 @@ Main functions for ECB-AES block ciphering
-----------------------------------------------------------------------------*/
#if ECB
void AES_ECB_encrypt( const uint8_t* key, /* encryption key */
const uint8_t* pntxt, /* plain text buffer */
const uint8_t* pntxt, /* plaintext buffer */
const size_t ptextLen, /* length of input plain text */
uint8_t* crtxt ); /* cipher-text result */
char AES_ECB_decrypt( const uint8_t* key, /* decryption key */
const uint8_t* crtxt, /* cipher text buffer */
const size_t crtxtLen, /* length of input cipher-text */
uint8_t* pntxt ); /* plain-text result */
const uint8_t* crtxt, /* cipher-text buffer */
const size_t crtxtLen, /* length of input cipher text */
uint8_t* pntxt ); /* plaintext result */
#endif /* ECB */
/**----------------------------------------------------------------------------
@@ -152,15 +162,15 @@ Main functions for CBC-AES block ciphering
#if CBC
char AES_CBC_encrypt( const uint8_t* key, /* encryption key */
const uint8_t* iVec, /* initialization vector */
const uint8_t* pntxt, /* plain text buffer */
const uint8_t* pntxt, /* plaintext buffer */
const size_t ptextLen, /* length of input plain text */
uint8_t* crtxt ); /* cipher-text result */
char AES_CBC_decrypt( const uint8_t* key, /* decryption key */
const uint8_t* iVec, /* initialization vector */
const uint8_t* crtxt, /* cipher text buffer */
const size_t crtxtLen, /* length of input cipher-text */
uint8_t* pntxt ); /* plain-text result */
const uint8_t* crtxt, /* cipher-text buffer */
const size_t crtxtLen, /* length of input cipher text */
uint8_t* pntxt ); /* plaintext result */
#endif /* CBC */
/**----------------------------------------------------------------------------
@@ -169,15 +179,15 @@ Main functions for CFB-AES block ciphering
#if CFB
void AES_CFB_encrypt( const uint8_t* key, /* encryption key */
const uint8_t* iVec, /* initialization vector */
const uint8_t* pntxt, /* plain text buffer */
const uint8_t* pntxt, /* plaintext buffer */
const size_t ptextLen, /* length of input plain text */
uint8_t* crtxt ); /* cipher-text result */
void AES_CFB_decrypt( const uint8_t* key, /* decryption key */
const uint8_t* iVec, /* initialization vector */
const uint8_t* crtxt, /* cipher text buffer */
const size_t crtxtLen, /* length of input cipher-text */
uint8_t* pntxt ); /* plain-text result */
const uint8_t* crtxt, /* cipher-text buffer */
const size_t crtxtLen, /* length of input cipher text */
uint8_t* pntxt ); /* plaintext result */
#endif /* CFB */
/**----------------------------------------------------------------------------
@@ -186,15 +196,15 @@ Main functions for OFB-AES block ciphering
#if OFB
void AES_OFB_encrypt( const uint8_t* key, /* encryption key */
const uint8_t* iVec, /* initialization vector */
const uint8_t* pntxt, /* plain text buffer */
const uint8_t* pntxt, /* plaintext buffer */
const size_t ptextLen, /* length of input plain text */
uint8_t* crtxt ); /* cipher-text result */
void AES_OFB_decrypt( const uint8_t* key, /* decryption key */
const uint8_t* iVec, /* initialization vector */
const uint8_t* crtxt, /* cipher text buffer */
const size_t crtxtLen, /* length of input cipher-text */
uint8_t* pntxt ); /* plain-text result */
const uint8_t* crtxt, /* cipher-text buffer */
const size_t crtxtLen, /* length of input cipher text */
uint8_t* pntxt ); /* plaintext result */
#endif /* OFB */
/**----------------------------------------------------------------------------
@@ -203,15 +213,15 @@ Main functions for XTS-AES block ciphering
#if XTS
char AES_XTS_encrypt( const uint8_t* keys, /* encryption key pair */
const uint8_t* unitId, /* tweak value (sector ID) */
const uint8_t* pntxt, /* plain text buffer */
const uint8_t* pntxt, /* plaintext buffer */
const size_t ptextLen, /* length of input plain text */
uint8_t* crtxt ); /* cipher-text result */
char AES_XTS_decrypt( const uint8_t* keys, /* decryption key pair */
const uint8_t* unitId, /* tweak value (sector ID) */
const uint8_t* crtxt, /* cipher text buffer */
const size_t crtxtLen, /* length of input cipher-text */
uint8_t* pntxt ); /* plain-text result */
const uint8_t* crtxt, /* cipher-text buffer */
const size_t crtxtLen, /* length of input cipher text */
uint8_t* pntxt ); /* plaintext result */
#endif /* XTS */
/**----------------------------------------------------------------------------
@@ -220,15 +230,15 @@ Main functions for CTR-AES block ciphering
#if CTR_NA
void AES_CTR_encrypt( const uint8_t* key, /* encryption key */
const uint8_t* iv, /* initialization vector/ nonce */
const uint8_t* pntxt, /* plain text buffer */
const uint8_t* pntxt, /* plaintext buffer */
const size_t ptextLen, /* length of input plain text */
uint8_t* crtxt ); /* cipher-text result */
void AES_CTR_decrypt( const uint8_t* key, /* decryption key */
const uint8_t* iv, /* initialization vector/ nonce */
const uint8_t* crtxt, /* cipher text buffer */
const size_t crtxtLen, /* length of input cipher-text */
uint8_t* pntxt ); /* plain-text result */
const uint8_t* crtxt, /* cipher-text buffer */
const size_t crtxtLen, /* length of input cipher text */
uint8_t* pntxt ); /* plaintext result */
#endif /* CTR */
/**----------------------------------------------------------------------------
@@ -303,7 +313,7 @@ Main functions for OCB-AES block ciphering
-----------------------------------------------------------------------------*/
#if OCB
void AES_OCB_encrypt( const uint8_t* key, /* encryption key */
const uint8_t* nonce, /* 96-bit initialization vector */
const uint8_t* nonce, /* a.k.a initialization vector */
const uint8_t* pntxt, /* plain text */
const size_t ptextLen, /* length of input plain text */
const uint8_t* aData, /* added authentication data */
@@ -312,7 +322,7 @@ void AES_OCB_encrypt( const uint8_t* key, /* encryption key */
uint8_t* auTag ); /* message authentication tag */
char AES_OCB_decrypt( const uint8_t* key, /* decryption key */
const uint8_t* nonce, /* 96-bit initialization vector */
const uint8_t* nonce, /* a.k.a initialization vector */
const uint8_t* crtxt, /* cipher text + appended tag */
const size_t crtxtLen, /* length of input cipher-text */
const uint8_t* aData, /* added authentication data */
@@ -377,7 +387,7 @@ char GCM_SIV_decrypt( const uint8_t* key, /* decryption key */
#endif /* GCM-SIV */
/**----------------------------------------------------------------------------
Main functions for AES key-wrapping; more info at the bottom of this page.
Main functions for AES key-wrapping
-----------------------------------------------------------------------------*/
#if KWA
char AES_KEY_wrap( const uint8_t* kek, /* key encryption key */
@@ -392,10 +402,26 @@ char AES_KEY_unwrap( const uint8_t* kek, /* key encryption key */
#endif /* KWA */
/**----------------------------------------------------------------------------
Main functions for FPE-AES (to be added soon)
Main functions for FPE-AES; more info at the bottom of this page.
-----------------------------------------------------------------------------*/
#if FPE
char AES_FPE_encrypt( const uint8_t* key, /* encryption key */
const uint8_t* tweak, /* tweak bytes */
#if FF_X != 3
const size_t tweakLen, /* size of tweak array */
#endif
const void* pntxt, /* input plaintext string */
const size_t ptextLen, /* length of plaintext string */
void* crtxt ); /* cipher-text result */
char AES_FPE_decrypt( const uint8_t* key, /* decryption key */
const uint8_t* tweak, /* tweak bytes */
#if FF_X != 3
const size_t tweakLen, /* size of tweak array */
#endif
const void* crtxt, /* input ciphertext string */
const size_t crtxtLen, /* length of ciphertext string */
void* pntxt ); /* plain-text result */
#endif /* FPE */
/**----------------------------------------------------------------------------
@@ -406,7 +432,7 @@ void AES_Poly1305( const uint8_t* keys, /* encryption/mixing key pair */
const uint8_t* nonce, /* the 128-bit nonce */
const void* data, /* input data buffer */
const size_t dataSize, /* size of data in bytes */
uint8_t* mac ); /* calculated poly1305 hash */
uint8_t* mac ); /* calculated poly1305-AES mac */
#endif
/**----------------------------------------------------------------------------
@@ -439,27 +465,27 @@ The error codes and key length should be defined here for external references:
#endif /* header guard */
/**--------------------------------------------------------------------------**\
| Notes and remarks about the above-defined macros |
+------------------------------------------------------------------------------+
/**¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯**\
¦ Notes and remarks about the above-defined macros ¦
--------------------------------------------------------------------------------
> Some AES modes just use the 'encryption' part of the Rijndael algorithm. So if
* Some AES modes just use the 'encryption' part of the Rijndael algorithm. So if
you are NOT using the decryption functions of ECB/CBC/KWA/XEX modes, you can
safely disable DECRYPTION macro and save a few kilobytes in compiled code.
> In EBC/CBC/XEX modes, the size of input must be a multiple of block-size.
* In EBC/CBC/XEX modes, the size of input must be a multiple of block-size.
Otherwise it needs to be padded. The simplest (default) padding mode is to
fill the rest of block by zeros. Supported standard padding methods are
PKCS#7 and ISO/IEC 7816-4, which can be enabled by AES_PADDING macro.
> In many texts, you may see that the words 'nonce' and 'initialization vector'
* In many texts, you may see that the words 'nonce' and 'initialization vector'
are used interchangeably. But they have a subtle difference. Sometimes nonce
is a part of the I.V, which itself can either be a full block or a partial
one. In CBC/CFB/OFB modes, the provided I.V must be a full block. In pure
CTR mode (CTR_NA) you can either provide a 96-bit I.V and let the count
start at CTR_STARTVALUE, or use a full block IV.
> In AEAD modes, the size of nonce and tag might be a parameter of the algorithm
* In AEAD modes, the size of nonce and tag might be a parameter of the algorithm
such that changing them affect the results. The GCM/EAX modes support
arbitrary sizes for nonce. In CCM, the nonce length may vary from 8 to 13
bytes. Also the tag size is an EVEN number between 4..16. In OCB, the nonce
@@ -467,23 +493,32 @@ The error codes and key length should be defined here for external references:
size is always 16 bytes which can later be truncated to desired values. So
in encryption functions, the provided authTag buffer must be 16 bytes long.
> For the EAX mode of operation, the IEEE-1703 standard defines EAX' which is a
* For the EAX mode of operation, the IEEE-1703 standard defines EAX' which is a
modified version that combines AAD and nonce. Also the tag size is fixed to
4 bytes. So EAX-prime functions don't need to take additional authentication
data and tag-size as separate parameters.
> In SIV mode, multiple separate units of authentication headers can be provided
* In SIV mode, multiple separate units of authentication headers can be provided
for the nonce synthesis. Here we assume that only one unit of AAD (aData) is
sufficient, which is practically true.
> The key wrapping mode is also denoted by KW. In this mode, the input secret is
* The FPE mode has two distinct NIST-approved algorithms, namely FF1 and FF3-1.
Use the FF_X macro to change the encryption method, which is FF1 by default.
The input and output strings must be consisted of a fixed set of characters
called 'the alphabet'. The default alphabet is the set of digits {'0'..'9'}.
If you want to use a different alphabet, set the CUSTOM_ALPHABET macro and
refer to the "micro_fpe.h" header. This file is needed only when a custom
alphabet has to be defined, and contains some illustrative examples and
clear guidelines on how to do so.
* The key wrapping mode is also denoted by KW. In this mode, the input secret is
divided into 64bit blocks. Number of blocks is at least 2, and it is assumed
that no padding is required. For padding, the KWP mode is used which is
easily implementable, but left as an exercise! In the NIST document you may
find some mentions of TKW which is for 3DES and irrelevant here. Anyway, the
wrapped output has an additional block, i.e. wrappedSize = secretSize + 8.
> Let me explain three extra options that are defined in the source file. If the
* Let me explain three extra options that are defined in the source file. If the
length of the input cipher/plain text is 'always' less than 4KB, you can
enable the SMALL_CIPHER macro to save a few bytes in the compiled code. Note
that for key-wrapping, this limit is 42 blocks (336 bytes) of secret key.

2
testvectors/Poly1305test.c
View File

@@ -102,8 +102,6 @@ int main()
str2bytes(value, m);
++n;
break;
default:
continue;
}
if (n == 2)
{