{"id":16370218,"url":"https://github.com/mrdcvlsc/aes","last_synced_at":"2025-10-15T22:05:06.901Z","repository":{"id":181180830,"uuid":"666357896","full_name":"mrdcvlsc/AES","owner":"mrdcvlsc","description":"A Lightweight Single Header file C++ AES Library that also supports AES Hardware Acceleration Technology","archived":false,"fork":false,"pushed_at":"2025-03-14T16:56:34.000Z","size":57,"stargazers_count":14,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-14T17:27:58.950Z","etag":null,"topics":["aes","aes-128","aes-decryption","aes-encryption","aes192","aes256","aesni","armv8","block-cipher","blockcipher","cipher","confidentiality","cplusplus","cpp","decryption","encryption","hardwareaccelerated","key","library","security"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mrdcvlsc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-07-14T10:09:27.000Z","updated_at":"2025-03-14T16:54:13.000Z","dependencies_parsed_at":"2023-10-10T15:28:43.324Z","dependency_job_id":null,"html_url":"https://github.com/mrdcvlsc/AES","commit_stats":{"total_commits":14,"total_committers":2,"mean_commits":7.0,"dds":0.0714285714285714,"last_synced_commit":"9c1cb56e99c3f9766679d91f4858f48e90ee79be"},"previous_names":["mrdcvlsc/aes"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrdcvlsc%2FAES","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrdcvlsc%2FAES/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrdcvlsc%2FAES/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrdcvlsc%2FAES/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mrdcvlsc","download_url":"https://codeload.github.com/mrdcvlsc/AES/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245048012,"owners_count":20552431,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aes","aes-128","aes-decryption","aes-encryption","aes192","aes256","aesni","armv8","block-cipher","blockcipher","cipher","confidentiality","cplusplus","cpp","decryption","encryption","hardwareaccelerated","key","library","security"],"created_at":"2024-10-11T03:04:22.752Z","updated_at":"2025-10-15T22:05:06.896Z","avatar_url":"https://github.com/mrdcvlsc.png","language":"C++","readme":"# AES - Lightweight Single Header AES C++ Library\n\n![tests](https://github.com/mrdcvlsc/AES/actions/workflows/tests.yml/badge.svg)\n\nThis repository contains a **single header file C++** that provides AES encryption and decryption function that _**supports**_ both a **pure C++** implementation and optimized implementations that leverage **hardware acceleration technologies** such as; **AES-NI** for `x86-64`, `amd64` architectures and **ARM NEON** for arm `aarch64`or 64-bit arm architectures.\n\n\u003e [!IMPORTANT]  \n\u003e This library **focuses solely** on the **encryption** and **decryption** of **AES blocks** and _**does not include padding functions or block cipher encryption modes**_.\n\u003e \n\u003e You need to code additional functions or incorporate libraries to handle padding and encryption modes such as CBC or CTR.\n\u003e \n\u003e Here is a [CLI program for File Encryption](https://github.com/mrdcvlsc/bethela/blob/main/main.cpp) that uses some of the modules that I wrote ([AES](https://github.com/mrdcvlsc/AES), [BytePadding](https://github.com/mrdcvlsc/BytePadding), [BlockCipherModes](https://github.com/mrdcvlsc/BlockCipherModes)) which can be used as an example.\n\n-----------\n\n## What You’ll Need\n\nRequires a C++ compiler that supports **C++17**, you need to compile it with the compilation flag `-std=c++17` or set the C++ version to 17 when using CMake.\n\n## How to Use the Library\n\nFirst download the headerfile and add `#include \"AES.hpp\"` or `#include \"path/to/the/file/AES.hpp\"` to your code.\n\nThen you can choose how the library runs AES based on your device. Here are your **options**:\n\n### 1. **Portable C++ Version**\n- **What it is:** This is a version written entirely in C++ that should work on *any* computer.\n- **How to use it:**  Add `-D USE_CXX_AES` and `-O3` when you compile.\n- **Speed:** It’s slower than the other options but ensures the best compatibility.\n\n### 2. **AES-NI for Intel/AMD Processors**\n- **What it is:** A faster version that uses special instructions built into Intel or AMD processors (found in most PCs and laptops).\n- **How to use it:** Add `-D USE_INTEL_AESNI -maes -O3` when you compile.\n- **Speed:** Much faster than the portable C++ version if your computer supports it.\n\n### 3. **NEON for ARM Processors**\n- **What it is:** A faster version for devices with 64 bit ARM processors, like smartphones or tablets.\n- **How to use it:** Add `-D USE_NEON_AES -march=armv8-a+crypto -O3` when you compile.\n- **Speed:** Boosts performance on ARM devices, much faster that portable C++ version.\n\n### **Automatic Detection and Manual Choice**\n\nBy default, the library will try to figure out the best option for your device after including the header file:\n- For Intel/AMD processors, it picks AES-NI if supported.\n- For ARM processors, it picks NEON if supported.\n- If neither works, it uses the portable C++ version.\n\nAlthough sometimes, the automatic detection might not work correctly. If that happens, you can force the library to use a specific version by adding the flags listed [above](#how-to-use-the-library) to your compile command. Just make sure your device and compiler support the option you picked.\n\n-----------\n\n# Sample Code to Get Started\n\n**sample.cpp**\n\n```c++\n/*    sample.cpp    */\n#include \u003ciostream\u003e\n#include \"AES.hpp\"\n\nint main()\n{\n    unsigned char data[16] = {\n      0x00, 0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77,\n      0x88, 0x99, 0xaa, 0xbb, 0xcc, 0xdd, 0xee, 0xff,\n    };\n\n    unsigned char key[] = {\n      0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,\n      0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f,\n    };\n\n    Cipher::Aes\u003c128\u003e aes(key);\n    aes.encrypt_block(data); // data is now encrypted in-place.\n    aes.decrypt_block(data); // data is now decrypted in-place.\n}\n```\n\n**Resulting Encrypted Value:**\n\n```shell\n0x69, 0xc4, 0xe0, 0xd8, 0x6a, 0x7b, 0x04, 0x30,\n0xd8, 0xcd, 0xb7, 0x80, 0x70, 0xb4, 0xc5, 0x5a,\n```\n-----\n\n## How to Compile Your Code\n\nThe example below will use the [program `sample.cpp` given above](#sample-code-to-get-started)\n\n### Option 1: Using the Command Line\nRun one of these commands in your terminal or command prompt. Replace `sample.cpp` with your file’s name.\n\n- **Portable C++ Version:**\n  ```\n  g++ -o sample.exe sample.cpp -D USE_CXX_AES -O3 -std=c++17\n  ```\n\n- **AES-NI for Intel/AMD:**\n  ```\n  g++ -o sample.exe sample.cpp -D USE_INTEL_AESNI -maes -O3 -std=c++17\n  ```\n\n- **NEON for ARM:**\n  ```\n  g++ -o sample.exe sample.cpp -D USE_NEON_AES -march=armv8-a+crypto -O3 -std=c++17\n  ```\n\n### Option 2: Using CMake\n\n1. On your `CMakeLists.txt` add this block:\n    ```cmake\n    cmake_minimum_required(VERSION 3.16)\n    \n    project(YourProjectName VERSION 1.0.0)\n    \n    # ...\n    \n    # add this block BEFORE `add_executable`\n    set(CMAKE_CXX_STANDARD 17)\n    set(CMAKE_CXX_STANDARD_REQUIRED True)\n    \n    set(AES_IMPL \"aesni\" CACHE STRING \"Choose an AES Implementation\")\n    set_property(CACHE AES_IMPL PROPERTY STRINGS auto portable aesni neon)\n    # add this block BEFORE `add_executable`\n    \n    # ...\n    \n    add_executable(main Source.cpp)\n    \n    # ...\n    \n    # add this block to AFTER `add_executable(...)`\n    if(\"${AES_IMPL}\" STREQUAL \"aesni\")\n      target_compile_definitions(main PUBLIC USE_INTEL_AESNI)\n      if(MSVC)\n        target_compile_options(main PRIVATE /arch:SSE2)\n      else()\n        target_compile_options(main PRIVATE -maes)\n      endif()\n    elseif(\"${AES_IMPL}\" STREQUAL \"neon\")\n      target_compile_definitions(main PUBLIC USE_NEON_AES)\n      target_compile_options(main PRIVATE -march=armv8-a+crypto)\n    elseif(\"${AES_IMPL}\" STREQUAL \"portable\")\n      target_compile_definitions(main PUBLIC USE_CXX_AES)\n    endif()\n    # add this block to AFTER `add_executable(...)`\n    ```\n\n2. Run these commands in your terminal:\n    ```\n    cmake -S . -B . -D AES_IMPL=portable\n    cmake --build . --config Release\n    ```\n    Replace `portable` with `aesni` or `neon` depending on what you want.\n\n---\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmrdcvlsc%2Faes","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmrdcvlsc%2Faes","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmrdcvlsc%2Faes/lists"}