# eciespy
[](https://app.codacy.com/gh/ecies/py/dashboard)
[](https://github.com/ecies/py/actions)
[](https://codecov.io/gh/ecies/py)
[](https://pypi.org/project/eciespy/)
[](https://pypi.org/project/eciespy/)
[](https://github.com/ecies/py)
Elliptic Curve Integrated Encryption Scheme for secp256k1 in Python.
Other language versions:
- [Rust](https://github.com/ecies/rs)
- [TypeScript](https://github.com/ecies/js)
- [Golang](https://github.com/ecies/go)
- [WASM](https://github.com/ecies/rs-wasm)
You can also check a FastAPI web backend demo [here](https://github.com/ecies/py-demo).
## Install
`pip install eciespy`
## Quick Start
```python
>>> from ecies.utils import generate_eth_key, generate_key
>>> from ecies import encrypt, decrypt
>>> eth_k = generate_eth_key()
>>> sk_hex = eth_k.to_hex() # hex string
>>> pk_hex = eth_k.public_key.to_hex() # hex string
>>> data = b'this is a test'
>>> decrypt(sk_hex, encrypt(pk_hex, data))
b'this is a test'
>>> secp_k = generate_key()
>>> sk_bytes = secp_k.secret # bytes
>>> pk_bytes = secp_k.public_key.format(True) # bytes
>>> decrypt(sk_bytes, encrypt(pk_bytes, data))
b'this is a test'
```
Or just use a builtin command `eciespy` in your favorite [command line](#command-line-interface).
## API
### `ecies.encrypt(receiver_pk: Union[str, bytes], msg: bytes) -> bytes`
Parameters:
- **receiver_pk** - Receiver's public key (hex str or bytes)
- **msg** - Data to encrypt
Returns: **bytes**
### `ecies.decrypt(receiver_sk: Union[str, bytes], msg: bytes) -> bytes`
Parameters:
- **receiver_sk** - Receiver's private key (hex str or bytes)
- **msg** - Data to decrypt
Returns: **bytes**
## Command Line Interface
### Show help
```console
$ eciespy -h
usage: eciespy [-h] [-e] [-d] [-g] [-k KEY] [-D [DATA]] [-O [OUT]]
Elliptic Curve Integrated Encryption Scheme for secp256k1 in Python
optional arguments:
-h, --help show this help message and exit
-e, --encrypt encrypt with public key, exclusive with -d
-d, --decrypt decrypt with private key, exclusive with -e
-g, --generate generate ethereum key pair
-k KEY, --key KEY public or private key file
-D [DATA], --data [DATA]
file to encrypt or decrypt, if not specified, it will
read from stdin
-O [OUT], --out [OUT]
encrypted or decrypted file, if not specified, it will
write to stdout
```
### Generate eth key
```console
$ eciespy -g
Private: 0x95d3c5e483e9b1d4f5fc8e79b2deaf51362980de62dbb082a9a4257eef653d7d
Public: 0x98afe4f150642cd05cc9d2fa36458ce0a58567daeaf5fde7333ba9b403011140a4e28911fcf83ab1f457a30b4959efc4b9306f514a4c3711a16a80e3b47eb58b
Address: 0x47e801184B3a8ea8E6A4A7A4CFEfEcC76809Da72
```
### Encrypt with public key and decrypt with private key
```console
$ echo '0x95d3c5e483e9b1d4f5fc8e79b2deaf51362980de62dbb082a9a4257eef653d7d' > sk
$ echo '0x98afe4f150642cd05cc9d2fa36458ce0a58567daeaf5fde7333ba9b403011140a4e28911fcf83ab1f457a30b4959efc4b9306f514a4c3711a16a80e3b47eb58b' > pk
$ echo 'hello ecies' | eciespy -e -k pk | eciespy -d -k sk
hello ecies
$ echo 'data to encrypt' > data
$ eciespy -e -k pk -D data -O enc_data
$ eciespy -d -k sk -D enc_data
data to encrypt
$ rm sk pk data enc_data
```
## Configuration
Ephemeral key format in the payload and shared key in the key derivation can be configured as compressed or uncompressed format.
```py
SymmetricAlgorithm = Literal["aes-256-gcm", "xchacha20"]
NonceLength = Literal[12, 16] # only for aes-256-gcm, xchacha20 will always be 24
COMPRESSED_PUBLIC_KEY_SIZE = 33
UNCOMPRESSED_PUBLIC_KEY_SIZE = 65
@dataclass()
class Config:
is_ephemeral_key_compressed: bool = False
is_hkdf_key_compressed: bool = False
symmetric_algorithm: SymmetricAlgorithm = "aes-256-gcm"
symmetric_nonce_length: NonceLength = 16
@property
def ephemeral_key_size(self):
return (
COMPRESSED_PUBLIC_KEY_SIZE
if self.is_ephemeral_key_compressed
else UNCOMPRESSED_PUBLIC_KEY_SIZE
)
ECIES_CONFIG = Config()
```
On `is_ephemeral_key_compressed = True`, the payload would be like: `33 Bytes + AES` instead of `65 Bytes + AES`.
On `is_hkdf_key_compressed = True`, the hkdf key would be derived from `ephemeral public key (compressed) + shared public key (compressed)` instead of `ephemeral public key (uncompressed) + shared public key (uncompressed)`.
On `symmetric_algorithm = "xchacha20"`, plaintext data would be encrypted with XChaCha20-Poly1305.
On `symmetric_nonce_length = 12`, then the nonce of AES-256-GCM would be 12 bytes. XChaCha20-Poly1305's nonce is always 24 bytes.
For compatibility, make sure different applications share the same configuration.
## Technical details
They are moved to [DETAILS.md](./DETAILS.md).
## Changelog
See [CHANGELOG.md](./CHANGELOG.md).
Raw data
{
"_id": null,
"home_page": "https://github.com/ecies/py",
"name": "eciespy",
"maintainer": "Weiliang Li",
"docs_url": null,
"requires_python": "<4.0,>=3.8",
"maintainer_email": "to.be.impressive@gmail.com",
"keywords": "secp256k1, crypto, elliptic curves, ecies, bitcoin, ethereum, cryptocurrency",
"author": "Weiliang Li",
"author_email": "to.be.impressive@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/8f/3f/a2f2d32ef66ece5e7d0a705384ff5ae8cc6f5b18bdded6848aa57891587b/eciespy-0.4.3.tar.gz",
"platform": null,
"description": "# eciespy\n\n[](https://app.codacy.com/gh/ecies/py/dashboard)\n[](https://github.com/ecies/py/actions)\n[](https://codecov.io/gh/ecies/py)\n[](https://pypi.org/project/eciespy/)\n[](https://pypi.org/project/eciespy/)\n[](https://github.com/ecies/py)\n\nElliptic Curve Integrated Encryption Scheme for secp256k1 in Python.\n\nOther language versions:\n\n- [Rust](https://github.com/ecies/rs)\n- [TypeScript](https://github.com/ecies/js)\n- [Golang](https://github.com/ecies/go)\n- [WASM](https://github.com/ecies/rs-wasm)\n\nYou can also check a FastAPI web backend demo [here](https://github.com/ecies/py-demo).\n\n## Install\n\n`pip install eciespy`\n\n## Quick Start\n\n```python\n>>> from ecies.utils import generate_eth_key, generate_key\n>>> from ecies import encrypt, decrypt\n>>> eth_k = generate_eth_key()\n>>> sk_hex = eth_k.to_hex() # hex string\n>>> pk_hex = eth_k.public_key.to_hex() # hex string\n>>> data = b'this is a test'\n>>> decrypt(sk_hex, encrypt(pk_hex, data))\nb'this is a test'\n>>> secp_k = generate_key()\n>>> sk_bytes = secp_k.secret # bytes\n>>> pk_bytes = secp_k.public_key.format(True) # bytes\n>>> decrypt(sk_bytes, encrypt(pk_bytes, data))\nb'this is a test'\n```\n\nOr just use a builtin command `eciespy` in your favorite [command line](#command-line-interface).\n\n## API\n\n### `ecies.encrypt(receiver_pk: Union[str, bytes], msg: bytes) -> bytes`\n\nParameters:\n\n- **receiver_pk** - Receiver's public key (hex str or bytes)\n- **msg** - Data to encrypt\n\nReturns: **bytes**\n\n### `ecies.decrypt(receiver_sk: Union[str, bytes], msg: bytes) -> bytes`\n\nParameters:\n\n- **receiver_sk** - Receiver's private key (hex str or bytes)\n- **msg** - Data to decrypt\n\nReturns: **bytes**\n\n## Command Line Interface\n\n### Show help\n\n```console\n$ eciespy -h\nusage: eciespy [-h] [-e] [-d] [-g] [-k KEY] [-D [DATA]] [-O [OUT]]\n\nElliptic Curve Integrated Encryption Scheme for secp256k1 in Python\n\noptional arguments:\n -h, --help show this help message and exit\n -e, --encrypt encrypt with public key, exclusive with -d\n -d, --decrypt decrypt with private key, exclusive with -e\n -g, --generate generate ethereum key pair\n -k KEY, --key KEY public or private key file\n -D [DATA], --data [DATA]\n file to encrypt or decrypt, if not specified, it will\n read from stdin\n -O [OUT], --out [OUT]\n encrypted or decrypted file, if not specified, it will\n write to stdout\n```\n\n### Generate eth key\n\n```console\n$ eciespy -g\nPrivate: 0x95d3c5e483e9b1d4f5fc8e79b2deaf51362980de62dbb082a9a4257eef653d7d\nPublic: 0x98afe4f150642cd05cc9d2fa36458ce0a58567daeaf5fde7333ba9b403011140a4e28911fcf83ab1f457a30b4959efc4b9306f514a4c3711a16a80e3b47eb58b\nAddress: 0x47e801184B3a8ea8E6A4A7A4CFEfEcC76809Da72\n```\n\n### Encrypt with public key and decrypt with private key\n\n```console\n$ echo '0x95d3c5e483e9b1d4f5fc8e79b2deaf51362980de62dbb082a9a4257eef653d7d' > sk\n$ echo '0x98afe4f150642cd05cc9d2fa36458ce0a58567daeaf5fde7333ba9b403011140a4e28911fcf83ab1f457a30b4959efc4b9306f514a4c3711a16a80e3b47eb58b' > pk\n$ echo 'hello ecies' | eciespy -e -k pk | eciespy -d -k sk\nhello ecies\n$ echo 'data to encrypt' > data\n$ eciespy -e -k pk -D data -O enc_data\n$ eciespy -d -k sk -D enc_data\ndata to encrypt\n$ rm sk pk data enc_data\n```\n\n## Configuration\n\nEphemeral key format in the payload and shared key in the key derivation can be configured as compressed or uncompressed format.\n\n```py\nSymmetricAlgorithm = Literal[\"aes-256-gcm\", \"xchacha20\"]\nNonceLength = Literal[12, 16] # only for aes-256-gcm, xchacha20 will always be 24\n\nCOMPRESSED_PUBLIC_KEY_SIZE = 33\nUNCOMPRESSED_PUBLIC_KEY_SIZE = 65\n\n\n@dataclass()\nclass Config:\n is_ephemeral_key_compressed: bool = False\n is_hkdf_key_compressed: bool = False\n symmetric_algorithm: SymmetricAlgorithm = \"aes-256-gcm\"\n symmetric_nonce_length: NonceLength = 16\n\n @property\n def ephemeral_key_size(self):\n return (\n COMPRESSED_PUBLIC_KEY_SIZE\n if self.is_ephemeral_key_compressed\n else UNCOMPRESSED_PUBLIC_KEY_SIZE\n )\n\n\nECIES_CONFIG = Config()\n```\n\nOn `is_ephemeral_key_compressed = True`, the payload would be like: `33 Bytes + AES` instead of `65 Bytes + AES`.\n\nOn `is_hkdf_key_compressed = True`, the hkdf key would be derived from `ephemeral public key (compressed) + shared public key (compressed)` instead of `ephemeral public key (uncompressed) + shared public key (uncompressed)`.\n\nOn `symmetric_algorithm = \"xchacha20\"`, plaintext data would be encrypted with XChaCha20-Poly1305.\n\nOn `symmetric_nonce_length = 12`, then the nonce of AES-256-GCM would be 12 bytes. XChaCha20-Poly1305's nonce is always 24 bytes.\n\nFor compatibility, make sure different applications share the same configuration.\n\n## Technical details\n\nThey are moved to [DETAILS.md](./DETAILS.md).\n\n## Changelog\n\nSee [CHANGELOG.md](./CHANGELOG.md).\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Elliptic Curve Integrated Encryption Scheme for secp256k1 in Python",
"version": "0.4.3",
"project_urls": {
"Homepage": "https://github.com/ecies/py",
"Repository": "https://github.com/ecies/py"
},
"split_keywords": [
"secp256k1",
" crypto",
" elliptic curves",
" ecies",
" bitcoin",
" ethereum",
" cryptocurrency"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b4e559ae5012049af381f80a30a81410a3316e57a3d52a874da7d3e2e78f9747",
"md5": "a20a510c1aff8c2c1ab3a01de040bf2b",
"sha256": "3cc24b2f4aa99792bc638c6ee6ac0e2bbe268c8f0ac30fb810bbcd49ef5ba2cc"
},
"downloads": -1,
"filename": "eciespy-0.4.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a20a510c1aff8c2c1ab3a01de040bf2b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8",
"size": 10029,
"upload_time": "2024-11-13T23:49:06",
"upload_time_iso_8601": "2024-11-13T23:49:06.915513Z",
"url": "https://files.pythonhosted.org/packages/b4/e5/59ae5012049af381f80a30a81410a3316e57a3d52a874da7d3e2e78f9747/eciespy-0.4.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8f3fa2f2d32ef66ece5e7d0a705384ff5ae8cc6f5b18bdded6848aa57891587b",
"md5": "895fbe57acd03eebe415579aaf025c8d",
"sha256": "d0ce98ee47122d669ccd8311a331e6806e2707fe629f1c3d7c1bb6f394b652fc"
},
"downloads": -1,
"filename": "eciespy-0.4.3.tar.gz",
"has_sig": false,
"md5_digest": "895fbe57acd03eebe415579aaf025c8d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8",
"size": 8877,
"upload_time": "2024-11-13T23:49:08",
"upload_time_iso_8601": "2024-11-13T23:49:08.582538Z",
"url": "https://files.pythonhosted.org/packages/8f/3f/a2f2d32ef66ece5e7d0a705384ff5ae8cc6f5b18bdded6848aa57891587b/eciespy-0.4.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-13 23:49:08",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ecies",
"github_project": "py",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "eciespy"
}
JSON
