Refactor utils

Author: kigawas

.cspell.jsonc

@@ -1,6 +1,7 @@
 {
   "words": [
     "bitcointalk",
+    "chacha",
     "Cipolla",
     "Codacy",
     "Codecov",
@@ -14,12 +15,17 @@
     "helloworld",
     "hexdigest",
     "hkdf",
+    "keccak",
     "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
+- Revamp documentation
+
 ## 0.4.1 ~ 0.4.3
 
 - Bump dependencies
 - Support Python 3.12, 3.13
+- Drop Python 3.8
 
 ## 0.4.0
 

DETAILS.md

@@ -136,6 +136,6 @@ Now we have the shared key, and we can use the `nonce` and `tag` to decrypt. Thi
 b'helloworld'
 ```
 
-> Strictly speaking, `nonce` != `iv`, but this is a little bit off topic, if you are curious, you can check [the comment in `utils/symmetric.py`](./ecies/utils/symmetric.py#L79).
+> Strictly speaking, `nonce` != `iv`, but this is a little bit off topic, if you are curious, you can check [the comment in `utils/symmetric.py`](./ecies/utils/symmetric.py#L86).
 >
 > Warning: it's dangerous to reuse nonce, if you don't know what you are doing, just follow the default setting.

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,64 +1,66 @@
 # 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`
 
+Or `pip install 'eciespy[eth]'` to use `ecies.utils.generate_eth_key`.
+
 ## Quick Start
 
 ```python
->>> from ecies.utils import generate_eth_key, generate_key
+>>> from ecies.utils import 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'
+>>> data = 'hello world🌍'.encode()
+>>> sk = generate_key()
+>>> sk_bytes = sk.secret  # bytes
+>>> pk_bytes = sk.public_key.format(True)  # bytes
+>>> decrypt(sk_bytes, encrypt(pk_bytes, data)).decode()
+'hello world🌍'
 ```
 
 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`
+### `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

@@ -4,7 +4,7 @@
 
 from .config import ECIES_CONFIG, Config
 from .utils import (
-    compat_eth_public_key,
+    bytes2pk,
     decapsulate,
     encapsulate,
     generate_key,
@@ -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
     -------
@@ -38,20 +40,22 @@ def encrypt(
     if isinstance(receiver_pk, str):
         pk = hex2pk(receiver_pk)
     elif isinstance(receiver_pk, bytes):
-        pk = PublicKey(compat_eth_public_key(receiver_pk))
+        pk = bytes2pk(receiver_pk)
     else:
         raise TypeError("Invalid public key type")
 
     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/__main__.py

@@ -14,7 +14,7 @@
 import sys
 
 from ecies import decrypt, encrypt
-from ecies.utils import generate_eth_key
+from ecies.utils import generate_key, get_eth_address, get_eth_public_key
 
 __description__ = "Elliptic Curve Integrated Encryption Scheme for secp256k1 in Python"
 
@@ -68,11 +68,11 @@ def main():
 
     args = parser.parse_args()
     if args.generate:
-        k = generate_eth_key()
+        k = generate_key()
         sk, pk, addr = (
             k.to_hex(),
-            k.public_key.to_hex(),
-            k.public_key.to_checksum_address(),
+            f"0x{get_eth_public_key(k.public_key).hex()}",
+            get_eth_address(k.public_key),
         )
         print("Private: {}\nPublic: {}\nAddress: {}".format(sk, pk, addr))
         return

ecies/utils/__init__.py

@@ -1,25 +1,25 @@
-from .elliptic import (
-    compat_eth_public_key,
-    decapsulate,
-    encapsulate,
-    generate_eth_key,
-    generate_key,
-    hex2pk,
-    hex2sk,
-)
-from .hex import decode_hex, sha256
+from .elliptic import bytes2pk, decapsulate, encapsulate, generate_key, hex2pk, hex2sk
+from .eth import generate_eth_key, get_eth_address, get_eth_public_key
+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",
-    "generate_eth_key",
     "hex2sk",
     "hex2pk",
+    "bytes2pk",
     "decapsulate",
     "encapsulate",
-    "compat_eth_public_key",
+    # eth
+    "generate_eth_key",
+    "get_eth_address",
+    "get_eth_public_key",
+    # hex
+    "decode_hex",
+    # hash
+    "sha256",
+    "derive_key",
 ]

ecies/utils/elliptic.py

@@ -1,9 +1,9 @@
 from coincurve import PrivateKey, PublicKey
 from coincurve.utils import get_valid_secret
 
-from ..config import ECIES_CONFIG, Config
+from .eth import compat_eth_public_key
+from .hash import derive_key
 from .hex import decode_hex
-from .symmetric import derive_key
 
 
 def generate_key() -> PrivateKey:
@@ -20,24 +20,9 @@ def generate_key() -> PrivateKey:
     return PrivateKey(get_valid_secret())
 
 
-def generate_eth_key():
-    """
-    Generate a random `eth_keys.keys.PrivateKey`
-
-    Returns
-    -------
-    eth_keys.keys.PrivateKey
-        An ethereum key
-
-    """
-    from eth_keys import keys
-
-    return keys.PrivateKey(get_valid_secret())
-
-
 def hex2pk(pk_hex: str) -> PublicKey:
     """
-    Convert ethereum hex to `coincurve.PublicKey`
+    Convert public key hex to `coincurve.PublicKey`
     The hex should be 65 bytes (uncompressed) or 33 bytes (compressed), but ethereum public key has 64 bytes.
     `0x04` will be appended if it's an ethereum public key.
 
@@ -55,10 +40,22 @@ 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 bytes2pk(pk_bytes: bytes) -> PublicKey:
+    """
+    Convert public key bytes to `coincurve.PublicKey`
+
+    Parameters
+    ----------
+    pk_bytes: bytes
+        Public key bytes
+
+    Returns
+    -------
+    coincurve.PublicKey
+        A secp256k1 public key
+
+    """
+    return PublicKey(compat_eth_public_key(pk_bytes))
 
 
 def hex2sk(sk_hex: str) -> PrivateKey:
@@ -81,9 +78,8 @@ def hex2sk(sk_hex: str) -> PrivateKey:
 
 # 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 +88,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)