docs: expand README and API documentation with usage examples and mul…

…ti-language support
isakruas · Oct 26, 2024 · 58a230e · 58a230e
1 parent 081eeb2
commit 58a230e
Show file tree

Hide file tree

Showing 5 changed files with 220 additions and 16 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,11 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [v1.1.3] - 2024-10-26
+
+### Changed
+- Expand README and API documentation with usage examples and multi-language support
+
 ## [v1.1.2] - 2024-10-03
 
 ### Changed

diff --git a/README.md b/README.md
@@ -1,4 +1,7 @@
-# Elliptic Curve Utils (ecutils)
+# ecutils
+
+**Python Library for Elliptic Curve Cryptography**
+
 [![Documentation Status](https://readthedocs.org/projects/ecutils/badge/?version=latest)](https://ecutils.readthedocs.io/en/stable/?badge=latest)
 [![Latest Version](https://img.shields.io/pypi/v/ecutils.svg?style=flat)](https://pypi.python.org/pypi/ecutils/)
 [![Downloads](https://static.pepy.tech/badge/ecutils)](https://pepy.tech/project/ecutils)
@@ -16,6 +19,21 @@ Elliptic Curve Utils, or `ecutils`, is a Python package that provides utilities
 - Includes an implementation of the Elliptic Curve Digital Signature Algorithm (ECDSA) for signing messages and verifying signatures.
 - Features key exchange protocols like Diffie-Hellman and Massey-Omura over elliptic curves.
 
+## Table of Contents
+
+- [Installation](#installation)
+- [Usage](#usage)
+- [API Documentation](#api-documentation)
+- [Examples](#examples)
+  - [Encoding and Decoding Messages with Koblitz](#encoding-and-decoding-messages-with-koblitz)
+  - [Digital Signatures with ECDSA](#digital-signatures-with-ecdsa)
+  - [Diffie-Hellman Key Exchange](#diffie-hellman-key-exchange)
+  - [Massey-Omura Key Exchange](#massey-omura-key-exchange)
+- [Support](#support)
+- [License](#license)
+- [Language-Specific Libraries for Elliptic Curve Cryptography](#language-specific-libraries-for-elliptic-curve-cryptography)
+
+
 ## Installation
 
 You can install the `ecutils` package using `pip`:
@@ -26,6 +44,190 @@ pip install ecutils
 
 ## Usage
 
+After installing the `ecutils` library, you can import it into your Python project. Below are the steps for using the library:
+
+```python
+# Importing core classes and functions
+from ecutils.core import EllipticCurve, Point
+from ecutils.curves import get as get_curve
+from ecutils.settings import LRU_CACHE_MAXSIZE
+
+# Importing protocols
+from ecutils.protocols import DiffieHellman, MasseyOmura
+
+# Importing algorithms
+from ecutils.algorithms import Koblitz, DigitalSignature
+```
+
+## API Documentation
+
+### Classes and Methods
+
+#### Class: **`DigitalSignature`**
+
+##### Constructor
+- **`__init__(self, private_key, curve_name='secp192k1')`**
+  - Creates a new instance of the `DigitalSignature` class for performing ECDSA (Elliptic Curve Digital Signature Algorithm) operations.
+  - **Parameters**:
+    - `private_key`: The private key used for generating a signature.
+    - `curve_name`: (Optional) The name of the elliptic curve to use. Defaults to `'secp192k1'`.
+
+##### Properties
+- **`public_key`**
+  - Retrieves the public key associated with the given private key, derived by multiplying the elliptic curve's generator point by the private key.
+  - **Returns**: `Point` representing the public key of the signer.
+
+##### Methods
+- **`generate_signature(self, message_hash)`**
+  - Generates an ECDSA signature for a given message hash using the private key.
+  - **Parameters**:
+    - `message_hash`: The hash of the message to be signed (string or bytes).
+  - **Returns**: A tuple `(r: int, s: int)` representing the ECDSA signature components.
+
+- **`verify_signature(self, public_key, message_hash, r, s)`**
+  - Verifies the authenticity of an ECDSA signature `(r, s)` against a public key and a message hash.
+  - **Parameters**:
+    - `public_key`: The public key associated with the signature.
+    - `message_hash`: The hash of the message that was signed (string or bytes).
+    - `r`: The `r` component of the signature (int).
+    - `s`: The `s` component of the signature (int).
+  - **Returns**: `True` if the signature is valid; `False` otherwise.
+
+---
+
+#### Class: **`Koblitz`**
+
+##### Constructor
+- **`__init__(self, curve_name='secp521r1')`**
+  - Creates a new instance of the `Koblitz` class for encoding and decoding messages on elliptic curves using the Koblitz method.
+  - **Parameters**:
+    - `curve_name`: (Optional) The name of the elliptic curve to use. Defaults to `'secp521r1'`.
+
+##### Methods
+- **`encode(self, message, alphabet_size=256, chunked=False)`**
+  - Encodes a textual message into a point on the elliptic curve using the Koblitz method.
+  - **Parameters**:
+    - `message`: The string message to be encoded.
+    - `alphabet_size`: (Optional) The size of the character set used in the message. Defaults to 256 (for ASCII).
+    - `chunked`: (Optional) Set to `True` for encoding large messages in chunks. Defaults to `False`.
+  - **Returns**: A tuple `(Point, int)` representing the encoded message as a point on the curve.
+
+- **`decode(self, encoded, j=0, alphabet_size=256, chunked=False)`**
+  - Decodes a point from the elliptic curve back into its corresponding textual message using the Koblitz method.
+  - **Parameters**:
+    - `encoded`: The point on the elliptic curve or tuple of points representing the encoded message.
+    - `j`: (Optional) An auxiliary value used during encoding. Defaults to `0`.
+    - `alphabet_size`: (Optional) The size of the character set used during encoding. Defaults to 256 (for ASCII).
+    - `chunked`: (Optional) Set to `True` if the message was encoded in chunks. Defaults to `False`.
+  - **Returns**: The decoded message as a string.
+
+---
+
+#### Class: **`DiffieHellman`**
+
+##### Constructor
+- **`__init__(self, private_key, curve_name='secp192k1')`**
+  - Creates a new instance of the `DiffieHellman` class for performing Diffie-Hellman key exchange using elliptic curves.
+  - **Parameters**:
+    - `private_key`: The private key of the user.
+    - `curve_name`: (Optional) The name of the elliptic curve to use. Defaults to `'secp192k1'`.
+
+##### Properties
+- **`public_key`**
+  - Retrieves the public key associated with the given private key, derived by multiplying the elliptic curve's generator point by the private key.
+  - **Returns**: `Point` representing the user's public key.
+
+##### Methods
+- **`compute_shared_secret(self, other_public_key)`**
+  - Computes the shared secret using the private key and the other party’s public key.
+  - **Parameters**:
+    - `other_public_key`: The other party's public key.
+  - **Returns**: The shared secret as a `Point`.
+
+---
+
+#### Class: **`MasseyOmura`**
+
+##### Constructor
+- **`__init__(self, private_key, curve_name='secp192k1')`**
+  - Creates a new instance of the `MasseyOmura` class for performing the Massey-Omura key exchange using elliptic curves.
+  - **Parameters**:
+    - `private_key`: The private key of the user.
+    - `curve_name`: (Optional) The name of the elliptic curve to use. Defaults to `'secp192k1'`.
+
+##### Properties
+- **`public_key`**
+  - Retrieves the public key associated with the given private key, derived by multiplying the elliptic curve's generator point by the private key.
+  - **Returns**: `Point` representing the user's public key.
+
+##### Methods
+- **`first_encryption_step(self, message)`**
+  - Applies the first encryption step by encrypting the provided message using the user's private key.
+  - **Parameters**:
+    - `message`: The original message as a `Point`.
+  - **Returns**: The encrypted message as a `Point`.
+
+- **`second_encryption_step(self, received_encrypted_message)`**
+  - Applies the second encryption step by encrypting the received later message using the user's private key.
+  - **Parameters**:
+    - `received_encrypted_message`: The encrypted message received from the other party.
+  - **Returns**: The resulting encrypted message as a `Point`.
+
+- **`partial_decryption_step(self, encrypted_message)`**
+  - Applies a partial decryption using the inverse of the private key.
+  - **Parameters**:
+    - `encrypted_message`: The encrypted message as a `Point`.
+  - **Returns**: A partially decrypted `Point`.
+
+---
+
+#### Class: **`EllipticCurve`**
+
+##### Constructor
+- **`__init__(self, p, a, b, G, n, h, use_projective_coordinates=True)`**
+  - Creates a new instance of the `EllipticCurve` class to define the elliptic curve parameters and available mathematical operations.
+  - **Parameters**:
+    - `p`: The prime order of the finite field.
+    - `a`: The coefficient `a` in the elliptic curve equation.
+    - `b`: The coefficient `b` in the elliptic curve equation.
+    - `G`: The base point/origin of the curve (point generator).
+    - `n`: The order of the base point.
+    - `h`: The cofactor of the elliptic curve.
+    - `use_projective_coordinates`: (Optional) Whether to use Jacobian/projective coordinate systems for efficient point operations. Defaults to `True`.
+
+##### Methods
+- **`add_points(self, p1, p2)`**
+  - Adds two points `p1` and `p2` on the elliptic curve.
+  - **Parameters**:
+    - `p1`: Point on the elliptic curve.
+    - `p2`: Another point to be added.
+  - **Returns**: `Point` representing the sum of the two points.
+
+- **`double_point(self, p)`**
+  - Doubles a point on the elliptic curve.
+  - **Parameters**:
+    - `p`: The point on the elliptic curve to be doubled.
+  - **Returns**: The resulting `Point`.
+
+- **`multiply_point(self, k, p)`**
+  - Multiplies a point by an integer scalar `k` on the elliptic curve.
+  - **Parameters**:
+    - `k`: The integer scalar to multiply by.
+    - `p`: The point to be multiplied.
+  - **Returns**: The resulting `Point`.
+
+- **`is_point_on_curve(self, p)`**
+  - Checks whether a point lies on the elliptic curve.
+  - **Parameters**:
+    - `p`: The point to check.
+  - **Returns**: `True` if the point is on the curve; `False` otherwise.
+
+For more in-depth use and examples, check out the [official documentation](https://ecutils.readthedocs.io/en/stable/).
+
+## Examples
+
+In the following examples, you'll see how to use ecutils for essential elliptic curve operations and cryptographic protocols, including message encoding, digital signatures with ECDSA, and key exchange methods. These practical implementations will help you quickly integrate elliptic curve cryptography into your applications.
+
 ### Encoding and Decoding Messages with Koblitz
 
 ```python
@@ -139,11 +341,6 @@ decoded_message = koblitz.decode(original_message, j)
 print(decoded_message)
 ```
 
-
-## Documentation
-
-For more in-depth use and examples, check out the [official documentation](https://ecutils.readthedocs.io/en/stable/).
-
 ## Support
 
 For issues, questions, or contributions, please refer to the project's [GitHub repository](https://github.com/isakruas/ecutils).
@@ -154,11 +351,12 @@ This project is licensed under the [MIT License](https://opensource.org/licenses
 
 Don't forget to give this project a star if you find it useful! 🌟
 
-## Cross-Platform Compiled Library
+## Language-Specific Libraries for Elliptic Curve Cryptography
 
-In addition to this Python module, there exists a cross-platform compiled library that offers similar functionalities. This library is available under the [Apache Version 2.0](https://www.apache.org/licenses/LICENSE-2.0) license and can be found on the official website:
+In addition to the Python module, there are other language-specific libraries available for elliptic curve cryptography:
 
-[ecutils - software distribution](https://d3llw48k0uhrwl.cloudfront.net/)
+- **JavaScript Library for Elliptic Curve Cryptography**: The `js-ecutils` package provides elliptic curve functionalities tailored for JavaScript developers. You can find it on [GitHub](https://github.com/isakruas/js-ecutils).
 
-If you need an implementation outside of the Python environment or seek integration with other programming languages, this library might be an excellent alternative.
+- **Go Library for Elliptic Curve Cryptography**: The `go-ecutils` library offers similar elliptic curve utilities for Go developers. More information and documentation can be found on [GitHub](https://github.com/isakruas/go-ecutils).
 
+These libraries enable developers to utilize elliptic curve cryptography in their preferred programming environments, ensuring flexibility and ease of integration.
diff --git a/SECURITY.md b/SECURITY.md
@@ -6,6 +6,7 @@ Use this section to tell people about which versions of your project are current
 
 | Version | Supported          |
 | ------- | ------------------ |
+| 1.1.3   | :white_check_mark: |
 | 1.1.2   | :white_check_mark: |
 | 1.1.1   | :white_check_mark: |
 | 1.1.0   | :white_check_mark: |
@@ -17,7 +18,6 @@ Use this section to tell people about which versions of your project are current
 | 0.0.1.dev2   | :x:                |
 | 0.0.1.dev1   | :x:                |
 | 0.0.1.dev0   | :x:                |
-
 
 ## Reporting a Vulnerability
 

diff --git a/docs/index.md b/docs/index.md
@@ -49,11 +49,12 @@ However, please be aware that the software comes "as is," with no warranty of an
 
 Before incorporating ECUtils, it's advised to read the full license text, available in the `LICENSE.md` file in the [source code repository](https://github.com/isakruas/ecutils/blob/master/LICENSE.md) or on the official website.
 
-## Cross-Platform Compiled Library
+## Language-Specific Libraries for Elliptic Curve Cryptography
 
-In addition to this Python module, there exists a cross-platform compiled library that offers similar functionalities. This library is available under the [Apache Version 2.0](https://www.apache.org/licenses/LICENSE-2.0) license and can be found on the official website:
+In addition to the Python module, there are other language-specific libraries available for elliptic curve cryptography:
 
-[ecutils - software distribution](https://d3llw48k0uhrwl.cloudfront.net/)
+- **JavaScript Library for Elliptic Curve Cryptography**: The `js-ecutils` package provides elliptic curve functionalities tailored for JavaScript developers. You can find it on [GitHub](https://github.com/isakruas/js-ecutils).
 
-If you need an implementation outside of the Python environment or seek integration with other programming languages, this library might be an excellent alternative.
+- **Go Library for Elliptic Curve Cryptography**: The `go-ecutils` library offers similar elliptic curve utilities for Go developers. More information and documentation can be found on [GitHub](https://github.com/isakruas/go-ecutils).
 
+These libraries enable developers to utilize elliptic curve cryptography in their preferred programming environments, ensuring flexibility and ease of integration.
diff --git a/src/ecutils/__init__.py b/src/ecutils/__init__.py
@@ -1 +1 @@
-__version__ = "1.1.2"
+__version__ = "1.1.3"