Skip to content

Commit adec074

Browse files
isakruasisakruas
authored
Merge pull request #25 from isakruas/docs/improve-readme-api-examples
docs: added usage examples, api details, and multi-language library references
2 parents 081eeb2 + 58a230e commit adec074

File tree

5 files changed

+220
-16
lines changed

5 files changed

+220
-16
lines changed

‎CHANGELOG.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,11 @@ All notable changes to this project will be documented in this file.
44

55
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).
66

7+
## [v1.1.3] - 2024-10-26
8+
9+
### Changed
10+
- Expand README and API documentation with usage examples and multi-language support
11+
712
## [v1.1.2] - 2024-10-03
813

914
### Changed

‎README.md‎

Lines changed: 208 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,7 @@
1-
# Elliptic Curve Utils (ecutils)
1+
# ecutils
2+
3+
**Python Library for Elliptic Curve Cryptography**
4+
25
[![Documentation Status](https://readthedocs.org/projects/ecutils/badge/?version=latest)](https://ecutils.readthedocs.io/en/stable/?badge=latest)
36
[![Latest Version](https://img.shields.io/pypi/v/ecutils.svg?style=flat)](https://pypi.python.org/pypi/ecutils/)
47
[![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
1619
- Includes an implementation of the Elliptic Curve Digital Signature Algorithm (ECDSA) for signing messages and verifying signatures.
1720
- Features key exchange protocols like Diffie-Hellman and Massey-Omura over elliptic curves.
1821

22+
## Table of Contents
23+
24+
- [Installation](#installation)
25+
- [Usage](#usage)
26+
- [API Documentation](#api-documentation)
27+
- [Examples](#examples)
28+
- [Encoding and Decoding Messages with Koblitz](#encoding-and-decoding-messages-with-koblitz)
29+
- [Digital Signatures with ECDSA](#digital-signatures-with-ecdsa)
30+
- [Diffie-Hellman Key Exchange](#diffie-hellman-key-exchange)
31+
- [Massey-Omura Key Exchange](#massey-omura-key-exchange)
32+
- [Support](#support)
33+
- [License](#license)
34+
- [Language-Specific Libraries for Elliptic Curve Cryptography](#language-specific-libraries-for-elliptic-curve-cryptography)
35+
36+
1937
## Installation
2038

2139
You can install the `ecutils` package using `pip`:
@@ -26,6 +44,190 @@ pip install ecutils
2644

2745
## Usage
2846

47+
After installing the `ecutils` library, you can import it into your Python project. Below are the steps for using the library:
48+
49+
```python
50+
# Importing core classes and functions
51+
from ecutils.core import EllipticCurve, Point
52+
from ecutils.curves import get as get_curve
53+
from ecutils.settings import LRU_CACHE_MAXSIZE
54+
55+
# Importing protocols
56+
from ecutils.protocols import DiffieHellman, MasseyOmura
57+
58+
# Importing algorithms
59+
from ecutils.algorithms import Koblitz, DigitalSignature
60+
```
61+
62+
## API Documentation
63+
64+
### Classes and Methods
65+
66+
#### Class: **`DigitalSignature`**
67+
68+
##### Constructor
69+
- **`__init__(self, private_key, curve_name='secp192k1')`**
70+
- Creates a new instance of the `DigitalSignature` class for performing ECDSA (Elliptic Curve Digital Signature Algorithm) operations.
71+
- **Parameters**:
72+
- `private_key`: The private key used for generating a signature.
73+
- `curve_name`: (Optional) The name of the elliptic curve to use. Defaults to `'secp192k1'`.
74+
75+
##### Properties
76+
- **`public_key`**
77+
- Retrieves the public key associated with the given private key, derived by multiplying the elliptic curve's generator point by the private key.
78+
- **Returns**: `Point` representing the public key of the signer.
79+
80+
##### Methods
81+
- **`generate_signature(self, message_hash)`**
82+
- Generates an ECDSA signature for a given message hash using the private key.
83+
- **Parameters**:
84+
- `message_hash`: The hash of the message to be signed (string or bytes).
85+
- **Returns**: A tuple `(r: int, s: int)` representing the ECDSA signature components.
86+
87+
- **`verify_signature(self, public_key, message_hash, r, s)`**
88+
- Verifies the authenticity of an ECDSA signature `(r, s)` against a public key and a message hash.
89+
- **Parameters**:
90+
- `public_key`: The public key associated with the signature.
91+
- `message_hash`: The hash of the message that was signed (string or bytes).
92+
- `r`: The `r` component of the signature (int).
93+
- `s`: The `s` component of the signature (int).
94+
- **Returns**: `True` if the signature is valid; `False` otherwise.
95+
96+
---
97+
98+
#### Class: **`Koblitz`**
99+
100+
##### Constructor
101+
- **`__init__(self, curve_name='secp521r1')`**
102+
- Creates a new instance of the `Koblitz` class for encoding and decoding messages on elliptic curves using the Koblitz method.
103+
- **Parameters**:
104+
- `curve_name`: (Optional) The name of the elliptic curve to use. Defaults to `'secp521r1'`.
105+
106+
##### Methods
107+
- **`encode(self, message, alphabet_size=256, chunked=False)`**
108+
- Encodes a textual message into a point on the elliptic curve using the Koblitz method.
109+
- **Parameters**:
110+
- `message`: The string message to be encoded.
111+
- `alphabet_size`: (Optional) The size of the character set used in the message. Defaults to 256 (for ASCII).
112+
- `chunked`: (Optional) Set to `True` for encoding large messages in chunks. Defaults to `False`.
113+
- **Returns**: A tuple `(Point, int)` representing the encoded message as a point on the curve.
114+
115+
- **`decode(self, encoded, j=0, alphabet_size=256, chunked=False)`**
116+
- Decodes a point from the elliptic curve back into its corresponding textual message using the Koblitz method.
117+
- **Parameters**:
118+
- `encoded`: The point on the elliptic curve or tuple of points representing the encoded message.
119+
- `j`: (Optional) An auxiliary value used during encoding. Defaults to `0`.
120+
- `alphabet_size`: (Optional) The size of the character set used during encoding. Defaults to 256 (for ASCII).
121+
- `chunked`: (Optional) Set to `True` if the message was encoded in chunks. Defaults to `False`.
122+
- **Returns**: The decoded message as a string.
123+
124+
---
125+
126+
#### Class: **`DiffieHellman`**
127+
128+
##### Constructor
129+
- **`__init__(self, private_key, curve_name='secp192k1')`**
130+
- Creates a new instance of the `DiffieHellman` class for performing Diffie-Hellman key exchange using elliptic curves.
131+
- **Parameters**:
132+
- `private_key`: The private key of the user.
133+
- `curve_name`: (Optional) The name of the elliptic curve to use. Defaults to `'secp192k1'`.
134+
135+
##### Properties
136+
- **`public_key`**
137+
- Retrieves the public key associated with the given private key, derived by multiplying the elliptic curve's generator point by the private key.
138+
- **Returns**: `Point` representing the user's public key.
139+
140+
##### Methods
141+
- **`compute_shared_secret(self, other_public_key)`**
142+
- Computes the shared secret using the private key and the other party’s public key.
143+
- **Parameters**:
144+
- `other_public_key`: The other party's public key.
145+
- **Returns**: The shared secret as a `Point`.
146+
147+
---
148+
149+
#### Class: **`MasseyOmura`**
150+
151+
##### Constructor
152+
- **`__init__(self, private_key, curve_name='secp192k1')`**
153+
- Creates a new instance of the `MasseyOmura` class for performing the Massey-Omura key exchange using elliptic curves.
154+
- **Parameters**:
155+
- `private_key`: The private key of the user.
156+
- `curve_name`: (Optional) The name of the elliptic curve to use. Defaults to `'secp192k1'`.
157+
158+
##### Properties
159+
- **`public_key`**
160+
- Retrieves the public key associated with the given private key, derived by multiplying the elliptic curve's generator point by the private key.
161+
- **Returns**: `Point` representing the user's public key.
162+
163+
##### Methods
164+
- **`first_encryption_step(self, message)`**
165+
- Applies the first encryption step by encrypting the provided message using the user's private key.
166+
- **Parameters**:
167+
- `message`: The original message as a `Point`.
168+
- **Returns**: The encrypted message as a `Point`.
169+
170+
- **`second_encryption_step(self, received_encrypted_message)`**
171+
- Applies the second encryption step by encrypting the received later message using the user's private key.
172+
- **Parameters**:
173+
- `received_encrypted_message`: The encrypted message received from the other party.
174+
- **Returns**: The resulting encrypted message as a `Point`.
175+
176+
- **`partial_decryption_step(self, encrypted_message)`**
177+
- Applies a partial decryption using the inverse of the private key.
178+
- **Parameters**:
179+
- `encrypted_message`: The encrypted message as a `Point`.
180+
- **Returns**: A partially decrypted `Point`.
181+
182+
---
183+
184+
#### Class: **`EllipticCurve`**
185+
186+
##### Constructor
187+
- **`__init__(self, p, a, b, G, n, h, use_projective_coordinates=True)`**
188+
- Creates a new instance of the `EllipticCurve` class to define the elliptic curve parameters and available mathematical operations.
189+
- **Parameters**:
190+
- `p`: The prime order of the finite field.
191+
- `a`: The coefficient `a` in the elliptic curve equation.
192+
- `b`: The coefficient `b` in the elliptic curve equation.
193+
- `G`: The base point/origin of the curve (point generator).
194+
- `n`: The order of the base point.
195+
- `h`: The cofactor of the elliptic curve.
196+
- `use_projective_coordinates`: (Optional) Whether to use Jacobian/projective coordinate systems for efficient point operations. Defaults to `True`.
197+
198+
##### Methods
199+
- **`add_points(self, p1, p2)`**
200+
- Adds two points `p1` and `p2` on the elliptic curve.
201+
- **Parameters**:
202+
- `p1`: Point on the elliptic curve.
203+
- `p2`: Another point to be added.
204+
- **Returns**: `Point` representing the sum of the two points.
205+
206+
- **`double_point(self, p)`**
207+
- Doubles a point on the elliptic curve.
208+
- **Parameters**:
209+
- `p`: The point on the elliptic curve to be doubled.
210+
- **Returns**: The resulting `Point`.
211+
212+
- **`multiply_point(self, k, p)`**
213+
- Multiplies a point by an integer scalar `k` on the elliptic curve.
214+
- **Parameters**:
215+
- `k`: The integer scalar to multiply by.
216+
- `p`: The point to be multiplied.
217+
- **Returns**: The resulting `Point`.
218+
219+
- **`is_point_on_curve(self, p)`**
220+
- Checks whether a point lies on the elliptic curve.
221+
- **Parameters**:
222+
- `p`: The point to check.
223+
- **Returns**: `True` if the point is on the curve; `False` otherwise.
224+
225+
For more in-depth use and examples, check out the [official documentation](https://ecutils.readthedocs.io/en/stable/).
226+
227+
## Examples
228+
229+
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.
230+
29231
### Encoding and Decoding Messages with Koblitz
30232

31233
```python
@@ -139,11 +341,6 @@ decoded_message = koblitz.decode(original_message, j)
139341
print(decoded_message)
140342
```
141343

142-
143-
## Documentation
144-
145-
For more in-depth use and examples, check out the [official documentation](https://ecutils.readthedocs.io/en/stable/).
146-
147344
## Support
148345

149346
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
154351

155352
Don't forget to give this project a star if you find it useful! 🌟
156353

157-
## Cross-Platform Compiled Library
354+
## Language-Specific Libraries for Elliptic Curve Cryptography
158355

159-
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:
356+
In addition to the Python module, there are other language-specific libraries available for elliptic curve cryptography:
160357

161-
[ecutils - software distribution](https://d3llw48k0uhrwl.cloudfront.net/)
358+
- **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).
162359

163-
If you need an implementation outside of the Python environment or seek integration with other programming languages, this library might be an excellent alternative.
360+
- **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).
164361

362+
These libraries enable developers to utilize elliptic curve cryptography in their preferred programming environments, ensuring flexibility and ease of integration.

‎SECURITY.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ Use this section to tell people about which versions of your project are current
66

77
| Version | Supported |
88
| ------- | ------------------ |
9+
| 1.1.3 | :white_check_mark: |
910
| 1.1.2 | :white_check_mark: |
1011
| 1.1.1 | :white_check_mark: |
1112
| 1.1.0 | :white_check_mark: |
@@ -17,7 +18,6 @@ Use this section to tell people about which versions of your project are current
1718
| 0.0.1.dev2 | :x: |
1819
| 0.0.1.dev1 | :x: |
1920
| 0.0.1.dev0 | :x: |
20-
2121

2222
## Reporting a Vulnerability
2323

‎docs/index.md‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -49,11 +49,12 @@ However, please be aware that the software comes "as is," with no warranty of an
4949

5050
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.
5151

52-
## Cross-Platform Compiled Library
52+
## Language-Specific Libraries for Elliptic Curve Cryptography
5353

54-
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:
54+
In addition to the Python module, there are other language-specific libraries available for elliptic curve cryptography:
5555

56-
[ecutils - software distribution](https://d3llw48k0uhrwl.cloudfront.net/)
56+
- **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).
5757

58-
If you need an implementation outside of the Python environment or seek integration with other programming languages, this library might be an excellent alternative.
58+
- **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).
5959

60+
These libraries enable developers to utilize elliptic curve cryptography in their preferred programming environments, ensuring flexibility and ease of integration.

‎src/ecutils/__init__.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
__version__ = "1.1.2"
1+
__version__ = "1.1.3"

0 commit comments

Comments
 (0)