Refactor utils

Author: kigawas

.cspell.jsonc

@@ -1,6 +1,7 @@
 {
   "words": [
     "bitcointalk",
+    "chacha",
     "Cipolla",
     "Codacy",
     "Codecov",
@@ -15,11 +16,15 @@
     "hexdigest",
     "hkdf",
     "pycryptodome",
+    "pytest",
     "readablize",
     "secp",
     "urandom",
     "xcfl",
     "xchacha"
   ],
-  "ignorePaths": [".cspell.jsonc", "LICENSE"]
+  "ignorePaths": [
+    ".cspell.jsonc",
+    "LICENSE"
+  ]
 }

CHANGELOG.md

@@ -1,9 +1,17 @@
 # Release Notes
 
+## 0.4.4
+
+- Refactor `utils`
+- Bump dependencies
+- Make `eth-keys` optional. Install with `pip install ecies[eth]` for the first time
+- Revamp doc
+
 ## 0.4.1 ~ 0.4.3
 
 - Bump dependencies
 - Support Python 3.12, 3.13
+- Drop Python 3.8
 
 ## 0.4.0
 

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2018-2024 Weiliang Li
+Copyright (c) 2018-2025 Weiliang Li
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,26 +1,29 @@
 # eciespy
 
 [![Codacy Badge](https://api.codacy.com/project/badge/Grade/2a11aeb9939244019d2c64bce3ff3c4e)](https://app.codacy.com/gh/ecies/py/dashboard)
+[![License](https://img.shields.io/github/license/ecies/py.svg)](https://github.com/ecies/py)
+[![PyPI](https://img.shields.io/pypi/v/eciespy.svg)](https://pypi.org/project/eciespy/)
+[![PyPI - Downloads](https://img.shields.io/pypi/dm/eciespy)](https://pypistats.org/packages/eciespy)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/eciespy.svg)](https://pypi.org/project/eciespy/)
 [![CI](https://img.shields.io/github/actions/workflow/status/ecies/py/ci.yml?branch=master)](https://github.com/ecies/py/actions)
 [![Codecov](https://img.shields.io/codecov/c/github/ecies/py.svg)](https://codecov.io/gh/ecies/py)
-[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/eciespy.svg)](https://pypi.org/project/eciespy/)
-[![PyPI](https://img.shields.io/pypi/v/eciespy.svg)](https://pypi.org/project/eciespy/)
-[![License](https://img.shields.io/github/license/ecies/py.svg)](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)
+- [Rust](https://github.com/ecies/rs)
 - [Golang](https://github.com/ecies/go)
 - [WASM](https://github.com/ecies/rs-wasm)
+- [Java](https://github.com/ecies/java)
+- [Dart](https://github.com/ecies/dart)
 
-You can also check a FastAPI web backend demo [here](https://github.com/ecies/py-demo).
+You can also check a web backend demo [here](https://github.com/ecies/py-demo).
 
 ## Install
 
-`pip install eciespy`
+`pip install eciespy[eth]`
 
 ## Quick Start
 
@@ -44,21 +47,23 @@ Or just use a builtin command `eciespy` in your favorite [command line](#command
 
 ## API
 
-### `ecies.encrypt(receiver_pk: Union[str, bytes], msg: bytes) -> bytes`
+### `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)
-- **msg** - Data to encrypt
+- **data** - Data to encrypt
+- **config** - Optional configuration object
 
 Returns: **bytes**
 
-### `ecies.decrypt(receiver_sk: Union[str, bytes], msg: bytes) -> 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)
-- **msg** - Data to decrypt
+- **data** - Data to decrypt
+- **config** - Optional configuration object
 
 Returns: **bytes**
 

ecies/__init__.py

@@ -18,7 +18,7 @@
 
 
 def encrypt(
-    receiver_pk: Union[str, bytes], msg: bytes, config: Config = ECIES_CONFIG
+    receiver_pk: Union[str, bytes], data: bytes, config: Config = ECIES_CONFIG
 ) -> bytes:
     """
     Encrypt with receiver's secp256k1 public key
@@ -27,8 +27,10 @@ def encrypt(
     ----------
     receiver_pk: Union[str, bytes]
         Receiver's public key (hex str or bytes)
-    msg: bytes
+    data: bytes
         Data to encrypt
+    config: Config
+        Optional configuration object
 
     Returns
     -------
@@ -45,13 +47,15 @@ def encrypt(
     ephemeral_sk = generate_key()
     ephemeral_pk = ephemeral_sk.public_key.format(config.is_ephemeral_key_compressed)
 
-    sym_key = encapsulate(ephemeral_sk, pk, config)
-    encrypted = sym_encrypt(sym_key, msg, config)
+    sym_key = encapsulate(ephemeral_sk, pk, config.is_hkdf_key_compressed)
+    encrypted = sym_encrypt(
+        sym_key, data, config.symmetric_algorithm, config.symmetric_nonce_length
+    )
     return ephemeral_pk + encrypted
 
 
 def decrypt(
-    receiver_sk: Union[str, bytes], msg: bytes, config: Config = ECIES_CONFIG
+    receiver_sk: Union[str, bytes], data: bytes, config: Config = ECIES_CONFIG
 ) -> bytes:
     """
     Decrypt with receiver's secp256k1 private key
@@ -60,8 +64,10 @@ def decrypt(
     ----------
     receiver_sk: Union[str, bytes]
         Receiver's private key (hex str or bytes)
-    msg: bytes
+    data: bytes
         Data to decrypt
+    config: Config
+        Optional configuration object
 
     Returns
     -------
@@ -76,7 +82,9 @@ def decrypt(
         raise TypeError("Invalid secret key type")
 
     key_size = config.ephemeral_key_size
-    ephemeral_pk, encrypted = PublicKey(msg[0:key_size]), msg[key_size:]
+    ephemeral_pk, encrypted = PublicKey(data[0:key_size]), data[key_size:]
 
-    sym_key = decapsulate(ephemeral_pk, sk, config)
-    return sym_decrypt(sym_key, encrypted, config)
+    sym_key = decapsulate(ephemeral_pk, sk, config.is_hkdf_key_compressed)
+    return sym_decrypt(
+        sym_key, encrypted, config.symmetric_algorithm, config.symmetric_nonce_length
+    )

ecies/utils/__init__.py

@@ -7,12 +7,11 @@
     hex2pk,
     hex2sk,
 )
-from .hex import decode_hex, sha256
+from .hash import derive_key, sha256
+from .hex import decode_hex
 from .symmetric import sym_decrypt, sym_encrypt
 
 __all__ = [
-    "sha256",
-    "decode_hex",
     "sym_encrypt",
     "sym_decrypt",
     "generate_key",
@@ -22,4 +21,9 @@
     "decapsulate",
     "encapsulate",
     "compat_eth_public_key",
+    # hex
+    "decode_hex",
+    # hash
+    "sha256",
+    "derive_key",
 ]

ecies/utils/elliptic.py

@@ -1,9 +1,8 @@
 from coincurve import PrivateKey, PublicKey
 from coincurve.utils import get_valid_secret
 
-from ..config import ECIES_CONFIG, Config
+from .hash import derive_key
 from .hex import decode_hex
-from .symmetric import derive_key
 
 
 def generate_key() -> PrivateKey:
@@ -22,12 +21,14 @@ def generate_key() -> PrivateKey:
 
 def generate_eth_key():
     """
+    Note: `eth-keys` needs to be installed in advance.
+
     Generate a random `eth_keys.keys.PrivateKey`
 
     Returns
     -------
     eth_keys.keys.PrivateKey
-        An ethereum key
+        An ethereum flavored secp256k1 key
 
     """
     from eth_keys import keys
@@ -55,12 +56,6 @@ def hex2pk(pk_hex: str) -> PublicKey:
     return PublicKey(compat_eth_public_key(decode_hex(pk_hex)))
 
 
-def compat_eth_public_key(data: bytes):
-    if len(data) == 64:  # eth public key format
-        data = b"\x04" + data
-    return data
-
-
 def hex2sk(sk_hex: str) -> PrivateKey:
     """
     Convert ethereum hex to `coincurve.PrivateKey`
@@ -79,11 +74,30 @@ def hex2sk(sk_hex: str) -> PrivateKey:
     return PrivateKey(decode_hex(sk_hex))
 
 
+def compat_eth_public_key(data: bytes):
+    """
+    Convert ethereum public key format to uncompressed format
+
+    Parameters
+    ----------
+    data: bytes
+        Ethereum public key (64 bytes)
+
+    Returns
+    -------
+    bytes
+        Uncompressed public key (65 bytes)
+
+    """
+    if len(data) == 64:
+        data = b"\x04" + data
+    return data
+
+
 # private below
 def encapsulate(
-    private_key: PrivateKey, peer_public_key: PublicKey, config: Config = ECIES_CONFIG
+    private_key: PrivateKey, peer_public_key: PublicKey, is_compressed: bool = False
 ) -> bytes:
-    is_compressed = config.is_hkdf_key_compressed
     shared_point = peer_public_key.multiply(private_key.secret)
     master = private_key.public_key.format(is_compressed) + shared_point.format(
         is_compressed
@@ -92,9 +106,8 @@ def encapsulate(
 
 
 def decapsulate(
-    public_key: PublicKey, peer_private_key: PrivateKey, config: Config = ECIES_CONFIG
+    public_key: PublicKey, peer_private_key: PrivateKey, is_compressed: bool = False
 ) -> bytes:
-    is_compressed = config.is_hkdf_key_compressed
     shared_point = public_key.multiply(peer_private_key.secret)
     master = public_key.format(is_compressed) + shared_point.format(is_compressed)
     return derive_key(master)

ecies/utils/hash.py

@@ -0,0 +1,29 @@
+import hashlib
+
+from Crypto.Hash import SHA256
+from Crypto.Protocol.KDF import HKDF
+
+
+def sha256(data: bytes) -> bytes:
+    """
+    Calculate sha256 hash.
+
+    Parameters
+    ----------
+    data: bytes
+        data to hash
+
+    Returns
+    -------
+    bytes
+        sha256 hash in bytes
+
+    >>> sha256(b'0'*16).hex()[:8] == 'fcdb4b42'
+    True
+    """
+    return hashlib.sha256(data).digest()
+
+
+def derive_key(master: bytes) -> bytes:
+    derived = HKDF(master, 32, b"", SHA256)
+    return derived  # type: ignore

ecies/utils/hex.py

@@ -1,25 +1,4 @@
 import codecs
-import hashlib
-
-
-def sha256(msg: bytes) -> bytes:
-    """
-    Calculate sha256 hash.
-
-    Parameters
-    ----------
-    msg: bytes
-        message to hash
-
-    Returns
-    -------
-    bytes
-        sha256 hash in bytes
-
-    >>> sha256(b'0'*16).hex()[:8] == 'fcdb4b42'
-    True
-    """
-    return hashlib.sha256(msg).digest()
 
 
 def decode_hex(s: str) -> bytes: