Folders and files

Name		Name	Last commit message	Last commit date
Latest commit History 307 Commits
.github		.github
ecies		ecies
scripts		scripts
tests		tests
.cspell.jsonc		.cspell.jsonc
.gitignore		.gitignore
.ruff.toml		.ruff.toml
CHANGELOG.md		CHANGELOG.md
DETAILS.md		DETAILS.md
LICENSE		LICENSE
README.md		README.md
_config.yml		_config.yml
poetry.lock		poetry.lock
pyproject.toml		pyproject.toml

Repository files navigation

eciespy

Elliptic Curve Integrated Encryption Scheme for secp256k1/curve25519 in Python.

Other language versions (curve25519 is not supported in some versions):

You can also check aweb backend demo.

Install

pip install eciespy

Orpip install 'eciespy[eth]' to installeth-keys as well.

Quick Start

Secp256k1

>>>fromecies.keysimportPrivateKey>>>fromeciesimportencrypt,decrypt>>>data='hello world🌍'.encode()>>>sk=PrivateKey('secp256k1')>>>sk_bytes=sk.secret# bytes>>>pk_bytes=sk.public_key.to_bytes(True)# bytes>>>decrypt(sk_bytes,encrypt(pk_bytes,data)).decode()'hello world🌍'>>>sk_hex=sk.to_hex()# hex str>>>pk_hex=sk.public_key.to_hex(True)# hex str>>>decrypt(sk_hex,encrypt(pk_hex,data)).decode()'hello world🌍'

X25519/Ed25519

>>>fromecies.keysimportPrivateKey>>>fromeciesimportencrypt,decrypt>>>fromecies.configimportECIES_CONFIG>>>ECIES_CONFIG.elliptic_curve='x25519'# or 'ed25519'>>>data='hello world🌍'.encode()>>>sk=PrivateKey('x25519')# or 'ed25519'>>>decrypt(sk.secret,encrypt(sk.public_key.to_bytes(),data)).decode()'hello world🌍'

Or just use a builtin commandeciespy in your favoritecommand line.

API

`ecies.encrypt(receiver_pk: Union[str, bytes], data: bytes, config: Config = ECIES_CONFIG) -> bytes`

Parameters:

receiver_pk - Receiver's public key (hexstr orbytes)
data - Data to encrypt
config - Optional configuration object

Returns:bytes

`ecies.decrypt(receiver_sk: Union[str, bytes], data: bytes, config: Config = ECIES_CONFIG) -> bytes`

Parameters:

receiver_sk - Receiver's private key (hexstr orbytes)
data - Data to decrypt
config - Optional configuration object

Returns:bytes

Command Line Interface

Show help

$eciespy -husage: eciespy [-h] [-e] [-d] [-g] [-k KEY] [-c {secp256k1,x25519,ed25519}] [-D [DATA]] [-O [OUT]]Elliptic Curve Integrated Encryption Scheme for secp256k1/curve25519 in Pythonoptions:  -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 key pair, for secp256k1, ethereum public key and address will be printed  -k, --key KEY         public or private key file  -c, --curve {secp256k1,x25519,ed25519}                        elliptic curve, default: secp256k1  -D, --data [DATA]     file to encrypt or decrypt, if not specified, it will read from stdin  -O, --out [OUT]       encrypted or decrypted file, if not specified, it will write to stdout

Generate eth key

$eciespy -gPrivate: 0x95d3c5e483e9b1d4f5fc8e79b2deaf51362980de62dbb082a9a4257eef653d7dPublic: 0x98afe4f150642cd05cc9d2fa36458ce0a58567daeaf5fde7333ba9b403011140a4e28911fcf83ab1f457a30b4959efc4b9306f514a4c3711a16a80e3b47eb58bAddress: 0x47e801184B3a8ea8E6A4A7A4CFEfEcC76809Da72

Encrypt with public key and decrypt with private key

$echo'0x95d3c5e483e9b1d4f5fc8e79b2deaf51362980de62dbb082a9a4257eef653d7d'> sk$echo'0x98afe4f150642cd05cc9d2fa36458ce0a58567daeaf5fde7333ba9b403011140a4e28911fcf83ab1f457a30b4959efc4b9306f514a4c3711a16a80e3b47eb58b'> pk$echo'hello ecies'| eciespy -e -k pk| eciespy -d -k skhello ecies$echo'data to encrypt'> data$eciespy -e -k pk -D data -O enc_data$eciespy -d -k sk -D enc_datadata to encrypt$rm sk pk data enc_data

Configuration

Following configurations are available.

Elliptic curve: secp256k1 or curve25519 (x25519/ed25519)
Ephemeral key format in the payload: compressed or uncompressed (only for secp256k1)
Shared elliptic curve key format in the key derivation: compressed or uncompressed (only for secp256k1)
Symmetric cipher algorithm: AES-256-GCM or XChaCha20-Poly1305
Symmetric nonce length: 12 or 16 bytes (only for AES-256-GCM)

For compatibility, make sure different applications share the same configuration.

EllipticCurve=Literal["secp256k1","x25519","ed25519"]SymmetricAlgorithm=Literal["aes-256-gcm","xchacha20"]NonceLength=Literal[12,16]# only for aes-256-gcm, xchacha20 will always be 24@dataclass()classConfig:elliptic_curve:EllipticCurve="secp256k1"is_ephemeral_key_compressed:bool=Falseis_hkdf_key_compressed:bool=Falsesymmetric_algorithm:SymmetricAlgorithm="aes-256-gcm"symmetric_nonce_length:NonceLength=16@propertydefephemeral_key_size(self):ifself.elliptic_curve=="secp256k1":return (COMPRESSED_PUBLIC_KEY_SIZEifself.is_ephemeral_key_compressedelseUNCOMPRESSED_PUBLIC_KEY_SIZE            )elifself.elliptic_curvein ("x25519","ed25519"):returnCURVE25519_PUBLIC_KEY_SIZEelse:raiseNotImplementedErrorECIES_CONFIG=Config()

OnECIES_CONFIG.elliptic_curve = "x25519" or"ed25519", x25519 (key exchange function on curve25519) or ed25519 (signature algorithm on curve25519) will be used for key exchange instead of secp256k1.

In this case, the payload would always be:32 Bytes + Ciphered.

If you don't know how to choose between x25519 and ed25519, just use the dedicated key exchange function x25519 for efficiency.
Because any 32-byte data is a valid curve25519 public key, the payload would seem random. This property is excellent for circumventing censorship by adversaries.

Secp256k1-specific configuration

Onis_ephemeral_key_compressed = True, the payload would be like:33 Bytes + Ciphered instead of65 Bytes + Ciphered.

Onis_hkdf_key_compressed = True, the hkdf key would be derived fromephemeral public key (compressed) + shared public key (compressed) instead ofephemeral public key (uncompressed) + shared public key (uncompressed).