Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/iyassou/mpyaes
MicroPython utility library for AES encryption
https://github.com/iyassou/mpyaes
aes micropython
Last synced: 25 days ago
JSON representation
MicroPython utility library for AES encryption
- Host: GitHub
- URL: https://github.com/iyassou/mpyaes
- Owner: iyassou
- License: mit
- Created: 2020-09-11T19:11:35.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2020-09-15T14:19:11.000Z (about 4 years ago)
- Last Synced: 2024-04-22T12:33:05.332Z (8 months ago)
- Topics: aes, micropython
- Language: Python
- Homepage:
- Size: 18.6 KB
- Stars: 26
- Watchers: 3
- Forks: 4
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-micropython - mpyaes - MicroPython module for AES encryption. (Libraries / Communications)
README
# mpyaes
MicroPython utility library around `ucryptolib.aes`
## What is this?
The `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`.
## Features
- `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.
- `mpyaes.PKCS7`: pads and verifies padding, raises `mpyaes.PaddingError` if the padding is incorrect.
- `mpyaes.AES`: handles AES encryption and decryption.
- `mpyaes.new`: returns an AES cipher object i.e. instantiates the `mpyaes.AES` class.
## Usage
### Key and IV generation
Keys 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`.
The 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.
`seed` is optional, but if supplied will result in `urandom.seed(seed)` being executed.
```python
>>> import mpyaes
>>> key = mpyaes.generate_key(32)
>>> key
bytearray(b'\xe5\x82\xe7\xc1\xcfP9\xab\x9e4-(\\}\xab\xaa\xf3\xe2S\x054d\xdf"\x82\xd0\xd8\'\x9ee\xc6\x1b')
>>> IV = mpyaes.generate_IV(16)
>>> IV
bytearray(b"\xfeYD\x91\xf2\xcd\xf1\xc6\xc9\xd0\x9c#\xf1\xad'\x9a")
```
With a buffer and seed value:
```python
>>> key2 = bytearray(32)
>>> seed = 110011
>>> mpyaes.generate_key(key2, seed)
>>> key2
bytearray(b"\x81IV_i\xcd\xc5\xad9>\xe8'\x00\xf9<\x85")
```
### Cipher object creation
Cipher 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.
```python
>>> aes = mpyaes.new(key, mpyaes.MODE_CBC, IV)
>>> aes
```
### Encryption/Decryption
Padding 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.
- **`bytearray`**
```python
>>> message = bytearray("https://www.youtube.com/watch?v=_HHlclssEP4")
>>> aes.encrypt(message) # in place
>>> message
bytearray(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')
>>> message = aes.decrypt(message) # zero-copy
>>> message
bytearray(b'https://www.youtube.com/watch?v=_HHlclssEP4')
```
- **`bytes`/`str`**
```python
>>> message = "This is an example string." # alternatively b'This is an example bytes.'
>>> message = aes.encrypt(message) # mpyaes.AES.encrypt([bytes, str]) returns a bytearray
>>> message
bytearray(b'^"\x06u\x95\xcb\xb4\xf6\xf0\x90\xd6\xc7T\xd0)\xe1\xf6GMh\xf9\x0b\xd5\xbf\xb3\x12n\x037\xa0K\xfb')
>>> message = aes.decrypt(message) # zero-copy
>>> message
bytearray(b'This is an example string.')
```
- **Files**
```python
>>> aes.encrypt_file('to_encrypt.txt', 'out.enc') # mpyaes.AES.encrypt_file(input_file, output_file)
>>> aes.decrypt_file('out.enc', 'challenger.txt') # mpyaes.AES.decrypt_file(input_file, output_file)
>>> with open('to_encrypt.txt', 'rb') as f, open('challenger.txt', 'rb') as g:
... assert f.read() == g.read()
...
>>>
```
## Notes
- `mpyaes` makes use of generic MicroPython libraries to increase portability.
- AES 128-bit and 256-bit, ECB and CBC modes were tested on an ESP32 running MicroPython 1.13.
- CTR mode isn't supported on the ESP32, so I haven't tested it.