# AES Cipher
| |
|---|
| [](https://pypi.org/project/aes_cipher/) [](https://pypi.org/project/aes_cipher/) [](https://github.com/ebellocchia/aes_cipher?tab=MIT-1-ov-file) |
| [](https://github.com/ebellocchia/aes_cipher/actions/workflows/codecov.yml) [](https://github.com/ebellocchia/aes_cipher/actions/workflows/code-analysis.yml) [](https://github.com/ebellocchia/aes_cipher/actions/workflows/test.yml) |
| [](https://codecov.io/gh/ebellocchia/aes_cipher) [](https://app.codacy.com/gh/ebellocchia/aes_cipher/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade) [](https://www.codefactor.io/repository/github/ebellocchia/aes_cipher) |
| |
## Introduction
AES cipher is a library to encrypt/decrypt using AES256-CBC. It is possible to encrypt/decrypt both files and raw data (string or bytes).
# How it works
1. A master key and IV are derived from the given password and (optionally) salt using a key derivation function. The key derivation function can be chosen among the provided ones:
- PBKDF2-SHA512
- Scrypt
Alternatively, it can also be customized by the user by simply implementing the `IKeyDerivator` interface.\
Salt is randomly generated (16-byte long) if not specified.
2. A random key and IV are generated and used to encrypt the actual data. In this way, if the same file is encrypted with the same password multiple times, the encrypted file will always be different.
3. The random key and IV are encrypted with the master key and IV
4. HMAC-SHA256 of the encrypted key/IV and file data is computed to ensure integrity, using the master key as key
It is possible to specify either a single password or a list of passwords.
In the last case, the file will be encrypted multiple times with a different password and salt each time.
## Installation
The package requires Python >= 3.7.
To install it:
- Using *setuptools*:
python setup.py install
- Using *pip*:
pip install aes_cipher
## Test and Coverage
Install develop dependencies:
pip install -r requirements-dev.txt
To run tests:
python -m unittest discover
To run tests with coverage:
coverage run -m unittest discover
coverage report
## APIs
### Key derivation
`Pbkdf2Sha512` class: derive keys using PBKDF2-SHA512 algorithm
- `Pbkdf2Sha512(itr_num)`: construct the class
- `itr_num`: iterations number
For default values, the `Pbkdf2Sha512Default` class instance can be used:
Pbkdf2Sha512Default = Pbkdf2Sha512(512 * 1024)
`Scrypt` class: derive keys using Scrypt algorithm
- `Scrypt(n, p, r)`: construct the class
- `n`: CPU/Memory cost parameter
- `p`: block size parameter
- `r`: parallelization parameter
For default values, the `ScryptDefault` class instance can be used:
ScryptDefault = Scrypt(16384, 8, 8)
To add a custom key derivation function, the `IKeyDerivator` interface shall be implemented:
class IKeyDerivator(ABC):
@abstractmethod
def DeriveKey(self,
password: Union[str, bytes],
salt: Union[str, bytes]) -> bytes:
pass
The only requirement is that the output of the `DeriveKey` method is at least 48-byte long.\
A constructor can be added to customize the algorithm.
### Encryption
`DataEncrypter` class: encrypt bytes or string data
- `DataEncrypter(key_derivator)`: construct the class
- `key_derivator`: key derivator to be used for master key and IV generation, it shall be an instance of the `IKeyDerivator` interface. Default value: `Pbkdf2Sha512Default`.
- `DataEncrypter.Encrypt(data, passwords [, salts])`: encrypt data with the specified passwords and salts
- `data`: input data (string or bytes)
- `passwords`: list of passwords (list of strings)
- `salts` (optional): list of salts (list of strings). The number of salts shall be the same of the passwords. If not specified, salts will be randomly generated (16-byte long).
- `DataEncrypter.GetEncryptedData()`: get encrypted data (bytes)
`FileEncrypter` class: encrypt a file
- `FileEncrypter(key_derivator)`: construct the class
- `key_derivator`: see `DataEncrypter` constructor
- `FileEncrypter.Encrypt(file_in, passwords [, salts])`: encrypt file with the specified passwords and salts
- `file_in`: input file
- `passwords`: see `DataEncrypter.Encrypt`
- `salts`: see `DataEncrypter.Encrypt`
- `FileEncrypter.GetEncryptedData()`: get encrypted data (bytes)
- `FileEncrypter.SaveTo(file_out)`: save to file
- `file_out`: output file to be saved
### Decryption
`DataDecrypter` class: decrypt bytes or string data
- `DataDecrypter(key_derivator)`: construct the class
- `key_derivator`: key derivator to be used for master key and IV generation, it shall be an instance of the `IKeyDerivator` interface. Default value: `Pbkdf2Sha512Default`.
- `DataDecrypter.Decrypt(data, passwords)`: decrypt data with the specified passwords
- `data`: input data (string or bytes)
- `passwords`: see `DataEncrypter.Encrypt`
- `DataDecrypter.GetDecryptedData()`: get decrypted data (bytes)
`FileDecrypter` class: decrypt a file
- `FileDecrypter(key_derivator)`: construct the class
- `key_derivator`: see `DataDecrypter` constructor
- `FileDecrypter.Decrypt(file_in, passwords)`
- `file_in`: input file
- `passwords`: see `DataDecrypter.Decrypt`
- `FileDecrypter.GetDecryptedData()`: get decrypted data (bytes)
- `FileDecrypter.SaveTo(file_out)`: save to file
- `file_out`: output file to be saved
## Examples
Data encryption with single password and random salt, using PBKDF2-SHA512 algorithm with default values:
data_encrypter = DataEncrypter(Pbkdf2Sha512Default)
data_encrypter.Encrypt(data, "test_pwd")
enc_data = data_encrypter.GetEncryptedData()
Data encryption with single password and custom salt, using PBKDF2-SHA512 algorithm with custom values:
data_encrypter = DataEncrypter(
Pbkdf2Sha512(1024 * 1024)
)
data_encrypter.Encrypt(data, ["test_pwd"], ["test_salt"])
enc_data = data_encrypter.GetEncryptedData()
Data encryption with multiple passwords and custom salts, using Scrypt algorithm with default values:
data_encrypter = DataEncrypter(ScryptDefault)
data_encrypter.Encrypt(data, ["test_pwd_1", "test_pwd_2"], ["test_salt_1", "test_salt_2"])
enc_data = data_encrypter.GetEncryptedData()
Data decryption with single password and random salt:
data_decrypter = DataDecrypter()
data_decrypter.Decrypt(data, ["test_pwd"])
dec_data = data_decrypter.GetDecryptedData()
Data decryption with multiple passwords and custom salts:
data_decrypter = DataDecrypter()
data_decrypter.Decrypt(data, ["test_pwd_1", "test_pwd_2"], ["test_salt_1", "test_salt_2"])
dec_data = data_decrypter.GetDecryptedData()
File encryption with single password and random salt:
file_encrypter = FileEncrypter()
file_encrypter.Encrypt(file_in, "test_pwd")
file_encrypter.SaveTo(file_out)
Enable logging:
data_encrypter = DataEncrypter()
data_encrypter.Logger().SetLevel(logging.INFO)
data_decrypter = DataDecrypter()
data_decrypter.Logger().SetLevel(logging.INFO)
## Sample Application
A sample application based on the library using the PBKDF2-SHA512 algorithm can be found in the *app* folder.
Basic usage:
python aes_cipher_app.py -m <enc:dec> -p <password1,password2,...> -i <input_files_or_folder> -o <output_folder> [-s <salt1,salt2,...>] [-t <itr_num>] [-v] [-h]
Parameters description:
|Short name|Long name| Description |
|---|---|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|`-m`|`--mode`| Operational mode: `enc` for encrypting, `dec` for decrypting |
|`-p`|`--password`| Password used for encrypting/decrypting. It can be a single password or a list of passwords separated by a comma |
|`-i`|`--input`| Input to be encrypted/decrypted. It can be a single file, a list of files separated by a comma or a folder (in this case all files in the folder will be encrypted/decrypted) |
|`-o`|`--output`| Output folder where the encrypted/decrypted files will be saved |
|`-s`|`--salt`| Optional: custom salts for master key and IV derivation, random if not specified` |
|`-t`|`--iteration`| Optional: number of iteration for the PBKDF2-SHA512 algorithm, default value: 524288 |
|`-v`|`--verbose`| Optional: enable verbose mode |
|`-h`|`--help`| Optional: print usage and exit |
**NOTE:** the password shall not contain spaces or commas (in this case it will be interpreted as multiple passwords)
Examples:
- Encrypt a file one time with the given password and salt. If *input_file* is a folder, all the files inside the folder will be encrypted:
python aes_cipher_app.py -m enc -p test_pwd -i input_file -o encrypted -s test_salt
- Decrypt the previous file:
python aes_cipher_app.py -m dec -p test_pwd -i encrypted -o decrypted -s test_salt
- Encrypt multiple files one time with the given password and salt. If one of the input files is a directory, it will be discarded:
python aes_cipher_app.py -m enc -p test_pwd -i input_file1,input_file2,input_file3 -o encrypted -s test_salt
- Encrypt a file 3 times using 3 passwords with random salts and custom number of iteration:
python aes_cipher_app.py -m enc -p test_pwd_1,test_pwd_2,test_pwd_3 -t 131072 -i input_file -o encrypted
- Decrypt the previous file:
python aes_cipher_app.py -m dec -p test_pwd_1,test_pwd_2,test_pwd_3 -t 131072 -i encrypted -o decrypted
Raw data
{
"_id": null,
"home_page": "https://github.com/ebellocchia/aes_cipher",
"name": "aes-cipher",
"maintainer": "Emanuele Bellocchia",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "ebellocchia@gmail.com",
"keywords": "cipher,aes,aes256,sha,sha256,sha512,pbkdf2,pbkdf2-sha512,hmac,hmac-sha256",
"author": "Emanuele Bellocchia",
"author_email": "ebellocchia@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/e5/14/23dacb8baa394b796d6954e607a591a22b4f94f276bc61fd1a6b22bc79b5/aes_cipher-2.0.1.tar.gz",
"platform": "any",
"description": "# AES Cipher\r\n\r\n| |\r\n|---|\r\n| [](https://pypi.org/project/aes_cipher/) [](https://pypi.org/project/aes_cipher/) [](https://github.com/ebellocchia/aes_cipher?tab=MIT-1-ov-file) |\r\n| [](https://github.com/ebellocchia/aes_cipher/actions/workflows/codecov.yml) [](https://github.com/ebellocchia/aes_cipher/actions/workflows/code-analysis.yml) [](https://github.com/ebellocchia/aes_cipher/actions/workflows/test.yml) |\r\n| [](https://codecov.io/gh/ebellocchia/aes_cipher) [](https://app.codacy.com/gh/ebellocchia/aes_cipher/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade) [](https://www.codefactor.io/repository/github/ebellocchia/aes_cipher) |\r\n| |\r\n\r\n## Introduction\r\n\r\nAES cipher is a library to encrypt/decrypt using AES256-CBC. It is possible to encrypt/decrypt both files and raw data (string or bytes).\r\n\r\n# How it works\r\n\r\n1. A master key and IV are derived from the given password and (optionally) salt using a key derivation function. The key derivation function can be chosen among the provided ones:\r\n - PBKDF2-SHA512\r\n - Scrypt\r\n\r\n Alternatively, it can also be customized by the user by simply implementing the `IKeyDerivator` interface.\\\r\n Salt is randomly generated (16-byte long) if not specified.\r\n2. A random key and IV are generated and used to encrypt the actual data. In this way, if the same file is encrypted with the same password multiple times, the encrypted file will always be different.\r\n3. The random key and IV are encrypted with the master key and IV\r\n4. HMAC-SHA256 of the encrypted key/IV and file data is computed to ensure integrity, using the master key as key\r\n\r\nIt is possible to specify either a single password or a list of passwords.\r\nIn the last case, the file will be encrypted multiple times with a different password and salt each time.\r\n\r\n## Installation\r\n\r\nThe package requires Python >= 3.7.\r\n\r\nTo install it:\r\n- Using *setuptools*:\r\n\r\n python setup.py install\r\n\r\n- Using *pip*:\r\n\r\n pip install aes_cipher\r\n\r\n## Test and Coverage\r\n\r\nInstall develop dependencies:\r\n\r\n pip install -r requirements-dev.txt\r\n\r\nTo run tests:\r\n\r\n python -m unittest discover\r\n\r\nTo run tests with coverage:\r\n\r\n coverage run -m unittest discover\r\n coverage report\r\n\r\n## APIs\r\n\r\n### Key derivation\r\n\r\n`Pbkdf2Sha512` class: derive keys using PBKDF2-SHA512 algorithm\r\n - `Pbkdf2Sha512(itr_num)`: construct the class\r\n - `itr_num`: iterations number\r\n\r\nFor default values, the `Pbkdf2Sha512Default` class instance can be used:\r\n\r\n Pbkdf2Sha512Default = Pbkdf2Sha512(512 * 1024)\r\n\r\n`Scrypt` class: derive keys using Scrypt algorithm\r\n - `Scrypt(n, p, r)`: construct the class\r\n - `n`: CPU/Memory cost parameter\r\n - `p`: block size parameter\r\n - `r`: parallelization parameter\r\n\r\nFor default values, the `ScryptDefault` class instance can be used:\r\n\r\n ScryptDefault = Scrypt(16384, 8, 8)\r\n\r\nTo add a custom key derivation function, the `IKeyDerivator` interface shall be implemented:\r\n\r\n class IKeyDerivator(ABC):\r\n @abstractmethod\r\n def DeriveKey(self,\r\n password: Union[str, bytes],\r\n salt: Union[str, bytes]) -> bytes:\r\n pass\r\n\r\nThe only requirement is that the output of the `DeriveKey` method is at least 48-byte long.\\\r\nA constructor can be added to customize the algorithm.\r\n\r\n### Encryption\r\n\r\n`DataEncrypter` class: encrypt bytes or string data\r\n\r\n- `DataEncrypter(key_derivator)`: construct the class\r\n - `key_derivator`: key derivator to be used for master key and IV generation, it shall be an instance of the `IKeyDerivator` interface. Default value: `Pbkdf2Sha512Default`.\r\n- `DataEncrypter.Encrypt(data, passwords [, salts])`: encrypt data with the specified passwords and salts\r\n - `data`: input data (string or bytes)\r\n - `passwords`: list of passwords (list of strings)\r\n - `salts` (optional): list of salts (list of strings). The number of salts shall be the same of the passwords. If not specified, salts will be randomly generated (16-byte long).\r\n- `DataEncrypter.GetEncryptedData()`: get encrypted data (bytes)\r\n\r\n`FileEncrypter` class: encrypt a file\r\n\r\n- `FileEncrypter(key_derivator)`: construct the class\r\n - `key_derivator`: see `DataEncrypter` constructor\r\n- `FileEncrypter.Encrypt(file_in, passwords [, salts])`: encrypt file with the specified passwords and salts\r\n - `file_in`: input file\r\n - `passwords`: see `DataEncrypter.Encrypt`\r\n - `salts`: see `DataEncrypter.Encrypt`\r\n- `FileEncrypter.GetEncryptedData()`: get encrypted data (bytes)\r\n- `FileEncrypter.SaveTo(file_out)`: save to file\r\n - `file_out`: output file to be saved\r\n\r\n### Decryption\r\n\r\n`DataDecrypter` class: decrypt bytes or string data\r\n\r\n- `DataDecrypter(key_derivator)`: construct the class\r\n - `key_derivator`: key derivator to be used for master key and IV generation, it shall be an instance of the `IKeyDerivator` interface. Default value: `Pbkdf2Sha512Default`.\r\n- `DataDecrypter.Decrypt(data, passwords)`: decrypt data with the specified passwords\r\n - `data`: input data (string or bytes)\r\n - `passwords`: see `DataEncrypter.Encrypt`\r\n- `DataDecrypter.GetDecryptedData()`: get decrypted data (bytes)\r\n\r\n`FileDecrypter` class: decrypt a file\r\n\r\n- `FileDecrypter(key_derivator)`: construct the class\r\n - `key_derivator`: see `DataDecrypter` constructor\r\n- `FileDecrypter.Decrypt(file_in, passwords)`\r\n - `file_in`: input file\r\n - `passwords`: see `DataDecrypter.Decrypt`\r\n- `FileDecrypter.GetDecryptedData()`: get decrypted data (bytes)\r\n- `FileDecrypter.SaveTo(file_out)`: save to file\r\n - `file_out`: output file to be saved\r\n\r\n## Examples\r\n\r\nData encryption with single password and random salt, using PBKDF2-SHA512 algorithm with default values:\r\n\r\n data_encrypter = DataEncrypter(Pbkdf2Sha512Default)\r\n data_encrypter.Encrypt(data, \"test_pwd\")\r\n enc_data = data_encrypter.GetEncryptedData()\r\n\r\nData encryption with single password and custom salt, using PBKDF2-SHA512 algorithm with custom values:\r\n\r\n data_encrypter = DataEncrypter(\r\n Pbkdf2Sha512(1024 * 1024)\r\n )\r\n data_encrypter.Encrypt(data, [\"test_pwd\"], [\"test_salt\"])\r\n enc_data = data_encrypter.GetEncryptedData()\r\n\r\nData encryption with multiple passwords and custom salts, using Scrypt algorithm with default values:\r\n\r\n data_encrypter = DataEncrypter(ScryptDefault)\r\n data_encrypter.Encrypt(data, [\"test_pwd_1\", \"test_pwd_2\"], [\"test_salt_1\", \"test_salt_2\"])\r\n enc_data = data_encrypter.GetEncryptedData()\r\n\r\nData decryption with single password and random salt:\r\n\r\n data_decrypter = DataDecrypter()\r\n data_decrypter.Decrypt(data, [\"test_pwd\"])\r\n dec_data = data_decrypter.GetDecryptedData()\r\n\r\nData decryption with multiple passwords and custom salts:\r\n\r\n data_decrypter = DataDecrypter()\r\n data_decrypter.Decrypt(data, [\"test_pwd_1\", \"test_pwd_2\"], [\"test_salt_1\", \"test_salt_2\"])\r\n dec_data = data_decrypter.GetDecryptedData()\r\n\r\nFile encryption with single password and random salt:\r\n\r\n file_encrypter = FileEncrypter()\r\n file_encrypter.Encrypt(file_in, \"test_pwd\")\r\n file_encrypter.SaveTo(file_out)\r\n\r\nEnable logging:\r\n\r\n data_encrypter = DataEncrypter()\r\n data_encrypter.Logger().SetLevel(logging.INFO)\r\n\r\n data_decrypter = DataDecrypter()\r\n data_decrypter.Logger().SetLevel(logging.INFO)\r\n\r\n## Sample Application\r\n\r\nA sample application based on the library using the PBKDF2-SHA512 algorithm can be found in the *app* folder.\r\n\r\nBasic usage:\r\n\r\n python aes_cipher_app.py -m <enc:dec> -p <password1,password2,...> -i <input_files_or_folder> -o <output_folder> [-s <salt1,salt2,...>] [-t <itr_num>] [-v] [-h]\r\n\r\nParameters description:\r\n\r\n|Short name|Long name| Description |\r\n|---|---|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\r\n|`-m`|`--mode`| Operational mode: `enc` for encrypting, `dec` for decrypting |\r\n|`-p`|`--password`| Password used for encrypting/decrypting. It can be a single password or a list of passwords separated by a comma |\r\n|`-i`|`--input`| Input to be encrypted/decrypted. It can be a single file, a list of files separated by a comma or a folder (in this case all files in the folder will be encrypted/decrypted) |\r\n|`-o`|`--output`| Output folder where the encrypted/decrypted files will be saved |\r\n|`-s`|`--salt`| Optional: custom salts for master key and IV derivation, random if not specified` |\r\n|`-t`|`--iteration`| Optional: number of iteration for the PBKDF2-SHA512 algorithm, default value: 524288 |\r\n|`-v`|`--verbose`| Optional: enable verbose mode |\r\n|`-h`|`--help`| Optional: print usage and exit |\r\n\r\n**NOTE:** the password shall not contain spaces or commas (in this case it will be interpreted as multiple passwords)\r\n\r\nExamples:\r\n\r\n- Encrypt a file one time with the given password and salt. If *input_file* is a folder, all the files inside the folder will be encrypted:\r\n\r\n python aes_cipher_app.py -m enc -p test_pwd -i input_file -o encrypted -s test_salt\r\n\r\n- Decrypt the previous file:\r\n\r\n python aes_cipher_app.py -m dec -p test_pwd -i encrypted -o decrypted -s test_salt\r\n\r\n- Encrypt multiple files one time with the given password and salt. If one of the input files is a directory, it will be discarded:\r\n\r\n python aes_cipher_app.py -m enc -p test_pwd -i input_file1,input_file2,input_file3 -o encrypted -s test_salt\r\n\r\n- Encrypt a file 3 times using 3 passwords with random salts and custom number of iteration:\r\n\r\n python aes_cipher_app.py -m enc -p test_pwd_1,test_pwd_2,test_pwd_3 -t 131072 -i input_file -o encrypted\r\n\r\n- Decrypt the previous file:\r\n\r\n python aes_cipher_app.py -m dec -p test_pwd_1,test_pwd_2,test_pwd_3 -t 131072 -i encrypted -o decrypted\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Cipher based on AES256-CBC",
"version": "2.0.1",
"project_urls": {
"Download": "https://github.com/ebellocchia/aes_cipher/archive/v2.0.1.tar.gz",
"Homepage": "https://github.com/ebellocchia/aes_cipher"
},
"split_keywords": [
"cipher",
"aes",
"aes256",
"sha",
"sha256",
"sha512",
"pbkdf2",
"pbkdf2-sha512",
"hmac",
"hmac-sha256"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "70b153ab84471c3f365be0e5bcfebc988dbfbaa742fe92d1cfaa26631cb8297e",
"md5": "7a67a47b8c57d42dc424cb94f079b28c",
"sha256": "4d99733ece21c08204ecea75f72e1139491e69ec1dd60de2be1afe0973bd177e"
},
"downloads": -1,
"filename": "aes_cipher-2.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7a67a47b8c57d42dc424cb94f079b28c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 29102,
"upload_time": "2024-02-09T18:47:37",
"upload_time_iso_8601": "2024-02-09T18:47:37.298837Z",
"url": "https://files.pythonhosted.org/packages/70/b1/53ab84471c3f365be0e5bcfebc988dbfbaa742fe92d1cfaa26631cb8297e/aes_cipher-2.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e51423dacb8baa394b796d6954e607a591a22b4f94f276bc61fd1a6b22bc79b5",
"md5": "fc897dd1f9c5a8097b183eebdcbd2b84",
"sha256": "38058da98e4fb7c6ac12334cf85c28a1db3e8c072f67f8cd9e8d852b1e679e3a"
},
"downloads": -1,
"filename": "aes_cipher-2.0.1.tar.gz",
"has_sig": false,
"md5_digest": "fc897dd1f9c5a8097b183eebdcbd2b84",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 18247,
"upload_time": "2024-02-09T18:47:39",
"upload_time_iso_8601": "2024-02-09T18:47:39.198312Z",
"url": "https://files.pythonhosted.org/packages/e5/14/23dacb8baa394b796d6954e607a591a22b4f94f276bc61fd1a6b22bc79b5/aes_cipher-2.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-09 18:47:39",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ebellocchia",
"github_project": "aes_cipher",
"travis_ci": true,
"coveralls": false,
"github_actions": true,
"requirements": [],
"tox": true,
"lcname": "aes-cipher"
}
JSON
