{"id":13801374,"url":"https://github.com/iyassou/mpyaes","last_synced_at":"2025-05-13T11:31:04.873Z","repository":{"id":143580883,"uuid":"294791428","full_name":"iyassou/mpyaes","owner":"iyassou","description":"MicroPython utility library for AES encryption","archived":false,"fork":false,"pushed_at":"2020-09-15T14:19:11.000Z","size":19,"stargazers_count":26,"open_issues_count":0,"forks_count":4,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-04-22T12:33:05.332Z","etag":null,"topics":["aes","micropython"],"latest_commit_sha":null,"homepage":"","language":"Python","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/iyassou.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":"2020-09-11T19:11:35.000Z","updated_at":"2024-08-04T00:06:12.051Z","dependencies_parsed_at":null,"dependency_job_id":"bda9522a-d9e8-4231-81fe-c4f612f38f4e","html_url":"https://github.com/iyassou/mpyaes","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iyassou%2Fmpyaes","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iyassou%2Fmpyaes/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iyassou%2Fmpyaes/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iyassou%2Fmpyaes/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/iyassou","download_url":"https://codeload.github.com/iyassou/mpyaes/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253932808,"owners_count":21986449,"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","micropython"],"created_at":"2024-08-04T00:01:22.158Z","updated_at":"2025-05-13T11:31:03.756Z","avatar_url":"https://github.com/iyassou.png","language":"Python","funding_links":[],"categories":["Libraries"],"sub_categories":["Communications"],"readme":"# mpyaes\nMicroPython utility library around `ucryptolib.aes`\n\n## What is this?\n\nThe `ucryptolib` MicroPython module provides an `aes` class that is capable of doing AES encryption. `mpyaes` provides an implementation of PKCS7 padding and other facilities around `ucryptolib.aes`.\n\n## Features\n\n- `mpyaes.generate_key` (`mpyaes.generate_IV`): generates a specified amount of pseudorandom bytes, making use of `urandom.getrandbits`. It's intended for (but not limited to) key (and IV) generation.\n- `mpyaes.PKCS7`: pads and verifies padding, raises `mpyaes.PaddingError` if the padding is incorrect.\n- `mpyaes.AES`: handles AES encryption and decryption.\n- `mpyaes.new`: returns an AES cipher object i.e. instantiates the `mpyaes.AES` class.\n\n## Usage\n\n### Key and IV generation\n\nKeys and IVs are generated by `mpyaes.generate_key(x[, seed])` and `mpyaes.generate_IV(x[, seed])`. `mpyaes.generate_IV` is an alias of `mpyaes.generate_key`.\nThe only mandatory argument to `mpyaes.generate_key` is either the size in bytes of the key to be generated, or a `bytes`-like object which will be filled with the pseudorandom data.\n`seed` is optional, but if supplied will result in `urandom.seed(seed)` being executed.\n\n```python\n\u003e\u003e\u003e import mpyaes\n\u003e\u003e\u003e key = mpyaes.generate_key(32)\n\u003e\u003e\u003e key\nbytearray(b'\\xe5\\x82\\xe7\\xc1\\xcfP9\\xab\\x9e4-(\\\\}\\xab\\xaa\\xf3\\xe2S\\x054d\\xdf\"\\x82\\xd0\\xd8\\'\\x9ee\\xc6\\x1b')\n\u003e\u003e\u003e IV = mpyaes.generate_IV(16)\n\u003e\u003e\u003e IV\nbytearray(b\"\\xfeYD\\x91\\xf2\\xcd\\xf1\\xc6\\xc9\\xd0\\x9c#\\xf1\\xad'\\x9a\")\n```\n\nWith a buffer and seed value:\n\n```python\n\u003e\u003e\u003e key2 = bytearray(32)\n\u003e\u003e\u003e seed = 110011\n\u003e\u003e\u003e mpyaes.generate_key(key2, seed)\n\u003e\u003e\u003e key2\nbytearray(b\"\\x81IV_i\\xcd\\xc5\\xad9\u003e\\xe8'\\x00\\xf9\u003c\\x85\")\n```\n\n### Cipher object creation\n\nCipher objects are created using `mpyaes.new(key, mode[, IV])`. Note that keys and IVs are consumed once used to instantiate a cipher object, so save them to variables for sharing (as done in the previous section). Alternatively, if communicating with a device that implements the [Yasmarang PRNG](http://www.literatecode.com/yasmarang), you could use and save a seed.\n\n```python\n\u003e\u003e\u003e aes = mpyaes.new(key, mpyaes.MODE_CBC, IV)\n\u003e\u003e\u003e aes\n\u003cAES 256-bit CBC\u003e\n```\n\n### Encryption/Decryption\n\nPadding of plaintexts is carried out by `mpyaes.PKCS7.pad` and similarly verified by `mpyaes.PKCS7.verify` with every call for encryption and decryption. Note that decrypted ciphertexts are stripped of their padding.\n\n- **`bytearray`**\n\n```python\n\u003e\u003e\u003e message = bytearray(\"https://www.youtube.com/watch?v=_HHlclssEP4\")\n\u003e\u003e\u003e aes.encrypt(message)                # in place\n\u003e\u003e\u003e message\nbytearray(b'\\xe4\\xb3\\x90\\xc3\\x0b\\x80%\\xb3\\xc2\\n\\xc3nY\\xdfv\\xc9\\xd3X8\\x82Y\\xd8\\xd7\\xbc\\xd0\\xafP\\xbdJ~\\xe5\\xdf\\x8a\\xbc\\x9cU\\xfd\\xa3\\x9a\\x8d\\x1a\\xed\\xdd\\x99\\x9a\\xa5Ll\\xff\\xaa\\xef\\xf0\\xfbU)o\\xb11\\xacC\\x981\\x0b\\xdf')\n\u003e\u003e\u003e message = aes.decrypt(message)      # zero-copy\n\u003e\u003e\u003e message\nbytearray(b'https://www.youtube.com/watch?v=_HHlclssEP4')\n```\n\n- **`bytes`/`str`**\n\n```python\n\u003e\u003e\u003e message = \"This is an example string.\"          # alternatively b'This is an example bytes.'\n\u003e\u003e\u003e message = aes.encrypt(message)                  # mpyaes.AES.encrypt([bytes, str]) returns a bytearray\n\u003e\u003e\u003e message\nbytearray(b'^\"\\x06u\\x95\\xcb\\xb4\\xf6\\xf0\\x90\\xd6\\xc7T\\xd0)\\xe1\\xf6GMh\\xf9\\x0b\\xd5\\xbf\\xb3\\x12n\\x037\\xa0K\\xfb')\n\u003e\u003e\u003e message = aes.decrypt(message)                  # zero-copy\n\u003e\u003e\u003e message\nbytearray(b'This is an example string.')\n```\n\n- **Files**\n\n```python\n\u003e\u003e\u003e aes.encrypt_file('to_encrypt.txt', 'out.enc')   # mpyaes.AES.encrypt_file(input_file, output_file)\n\u003e\u003e\u003e aes.decrypt_file('out.enc', 'challenger.txt')   # mpyaes.AES.decrypt_file(input_file, output_file)\n\u003e\u003e\u003e with open('to_encrypt.txt', 'rb') as f, open('challenger.txt', 'rb') as g:\n...     assert f.read() == g.read()\n...\n\u003e\u003e\u003e\n```\n\n## Notes\n\n- `mpyaes` makes use of generic MicroPython libraries to increase portability.\n- AES 128-bit and 256-bit, ECB and CBC modes were tested on an ESP32 running MicroPython 1.13.\n- CTR mode isn't supported on the ESP32, so I haven't tested it.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiyassou%2Fmpyaes","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fiyassou%2Fmpyaes","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiyassou%2Fmpyaes/lists"}