Skip to main content

Elliptic Curve Integrated Encryption Scheme for secp256k1 in Python

Project description

eciespy

Codacy Badge License PyPI PyPI - Downloads PyPI - Python Version CI Codecov

Elliptic Curve Integrated Encryption Scheme for secp256k1 in Python.

Other language versions:

You can also check a web backend demo.

Install

pip install eciespy

Or pip install 'eciespy[eth]' to install eth-keys as well.

Quick Start

Secp256k1

>>> from ecies.keys import PrivateKey
>>> from ecies import encrypt, 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

>>> from ecies.keys import PrivateKey
>>> from ecies import encrypt, decrypt
>>> from ecies.config import ECIES_CONFIG
>>> ECIES_CONFIG.elliptic_curve = 'x25519'
>>> data = 'hello world🌍'.encode()
>>> sk = PrivateKey('x25519')
>>> decrypt(sk.secret, encrypt(sk.public_key.to_bytes(), data)).decode()
'hello world🌍'

Or just use a builtin command eciespy in your favorite command line.

API

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

Parameters:

  • receiver_pk - Receiver's public key (hex str or bytes)
  • 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 (hex str or bytes)
  • data - Data to decrypt
  • config - Optional configuration object

Returns: bytes

Command Line Interface

Show help

$ 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

$ eciespy -g
Private: 0x95d3c5e483e9b1d4f5fc8e79b2deaf51362980de62dbb082a9a4257eef653d7d
Public: 0x98afe4f150642cd05cc9d2fa36458ce0a58567daeaf5fde7333ba9b403011140a4e28911fcf83ab1f457a30b4959efc4b9306f514a4c3711a16a80e3b47eb58b
Address: 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 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.

EllipticCurve = Literal["secp256k1", "x25519"]
SymmetricAlgorithm = Literal["aes-256-gcm", "xchacha20"]
NonceLength = Literal[12, 16]  # only for aes-256-gcm, xchacha20 will always be 24


@dataclass()
class Config:
    elliptic_curve: EllipticCurve = "secp256k1"
    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):
        if self.elliptic_curve == "secp256k1":
            return (
                COMPRESSED_PUBLIC_KEY_SIZE
                if self.is_ephemeral_key_compressed
                else UNCOMPRESSED_PUBLIC_KEY_SIZE
            )
        elif self.elliptic_curve == "x25519":
            return CURVE25519_PUBLIC_KEY_SIZE
        else:
            raise NotImplementedError


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.

Changelog

See CHANGELOG.md.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

eciespy-0.4.5.tar.gz (11.3 kB view details)

Uploaded Source

Built Distribution

eciespy-0.4.5-py3-none-any.whl (14.4 kB view details)

Uploaded Python 3

File details

Details for the file eciespy-0.4.5.tar.gz.

File metadata

  • Download URL: eciespy-0.4.5.tar.gz
  • Upload date:
  • Size: 11.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/2.1.3 CPython/3.12.3 Linux/6.11.0-1015-azure

File hashes

Hashes for eciespy-0.4.5.tar.gz
Algorithm Hash digest
SHA256 546da36fb2fe48a03966b888e2b64f786be67c9c4e6408d3af6dd68c413b8e2b
MD5 77155fb176407dc150a99925119036c1
BLAKE2b-256 273a59813dba790f6d79eaa2c6dc7367813946a0a76ba4b9f89165422ecef77f

See more details on using hashes here.

File details

Details for the file eciespy-0.4.5-py3-none-any.whl.

File metadata

  • Download URL: eciespy-0.4.5-py3-none-any.whl
  • Upload date:
  • Size: 14.4 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/2.1.3 CPython/3.12.3 Linux/6.11.0-1015-azure

File hashes

Hashes for eciespy-0.4.5-py3-none-any.whl
Algorithm Hash digest
SHA256 091a5b7a4b269e251fc352356570e1a63423fcbbd31fb9c96adc195b8fa0ae2a
MD5 aca2496d2843ff18a10cd26f4122bab6
BLAKE2b-256 5fac09bfc159dfd644b5bf4040b0245cfdaa7e0c59d7147a1c530f731e47e635

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page