fastecdsa

https://fastecdsa.readthedocs.io/en/latest/
Admin
Python library for fast elliptic curve digital signature algorithm (ECDSA) implementation with...
Tokens:7,856
Snippets:38
Trust Score:9.6
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install fastecdsa with uv, poetry, or pip

Source: https://fastecdsa.readthedocs.io/en/latest/_sources/installation.rst.txt

Adds the fastecdsa package to your project using the specified package manager. Choose the command that matches your preferred tool.

```bash
$ uv add fastecdsa
```

```bash
$ poetry add fastecdsa
```

```bash
$ pip install fastecdsa
```

--------------------------------

### Build fastecdsa from source with maturin

Source: https://fastecdsa.readthedocs.io/en/latest/_sources/installation.rst.txt

Runs maturin develop in the cloned repository to build the package. Requires the Rust toolchain to be installed.

```bash
$ uv run maturin develop
```

--------------------------------

### Arbitrary Elliptic Curve Arithmetic with Point class

Source: https://fastecdsa.readthedocs.io/en/latest/_sources/point-arithmetic.rst.txt

Demonstrates point addition, subtraction, doubling, scalar multiplication, and joint scalar multiplication using the Point class on the P256 curve. Uses standard Python operators + and *. The example is taken from NIST routines document section 4.3.2.

```python
# example taken from the document below (section 4.3.2):
# https://koclab.cs.ucsb.edu/teaching/cren/docs/w02/nist-routines.pdf

from fastecdsa.curve import P256
from fastecdsa.point import Point

xs = 0xde2444bebc8d36e682edd27e0f271508617519b3221a8fa0b77cab3989da97c9
ys = 0xc093ae7ff36e5380fc01a5aad1e66659702de80f53cec576b6350b243042a256
S = Point(xs, ys, curve=P256)

xt = 0x55a8b00f8da1d44e62f6b3b25316212e39540dc861c89575bb8cf92e35e0986b
yt = 0x5421c3209c2d6c704835d82ac4c3dd90f61a8a52598b9e7ab656e9d8c8b24316
T = Point(xt, yt, curve=P256)

# Point Addition
R = S + T

# Point Subtraction: (xs, ys) - (xt, yt) = (xs, ys) + (xt, -yt)
R = S - T

# Point Doubling
R = S + S  # produces the same value as the operation below
R = 2 * S  # S * 2 works fine too i.e. order doesn't matter

d = 0xc51e4753afdec1e6b6c6a5b992f43f8dd0c7a8933072708b6522468b2ffb06fd

# Scalar Multiplication
R = d * S  # S * d works fine too i.e. order doesn't matter

e = 0xd37f628ece72a462f0145cbefe3f0b355ee8332d37acdd83a358016aea029db7

# Joint Scalar Multiplication
R = d * S + e * T
```

--------------------------------

### Projective Point Operations

Source: https://fastecdsa.readthedocs.io/en/latest/point-arithmetic.html

Demonstrates how to create and use projective points for more efficient arithmetic, and how to convert them back to affine points using the normalize method.

```APIDOC
## Projective Point Operations

### Description
Create projective points for cheaper arithmetic operations and convert them to affine points when needed.

### Usage
```python
from fastecdsa.curve import P256
from fastecdsa.point import Point

# Create a projective point
proj_point = Point(P256.G.x, P256.G.y, P256, projective=True)

# Perform scalar multiplication
result = x * proj_point

# Convert to affine point
affine_result = result.normalize()
```

### Parameters
- **projective** (bool): Set to True to create a projective point. Default is False (affine).

### Methods
- **normalize()**: Converts a projective point to an affine point.

### Notes
- Comparisons between projective and affine points are possible but less performant than affine-affine comparisons.
```

--------------------------------

### Projective Point Arithmetic with normalize

Source: https://fastecdsa.readthedocs.io/en/latest/_sources/point-arithmetic.rst.txt

Shows how to create a projective point using the projective=True flag, perform scalar multiplication, and convert back to affine with normalize(). Projective arithmetic is cheaper for intermediate calculations, but comparisons with affine points are less performant. By default all representations are affine.

```python
In [1]: from fastecdsa.curve import P256

In [2]: from fastecdsa.point import Point

In [3]: x = 0xdeadc0de

In [4]: x * P256.G
Out[4]:
X: 0x32079326d26449f8b36bde4410f805eb520c0120da1585c79c369f356c8a298f
Y: 0x249daa2c57c8d6a90575630635aa5448fa56d21f5e363c155fe98c597b1c70ae
(Affine point on curve "P256")

In [5]: g_ = Point(P256.G.x, P256.G.y, P256, projective=True)

In [6]: h = x * g_

In [7]: h
Out[7]:
X: 0x15819ed127c46b11b751a1d575a6e7712fe72c03e693ea0783268e2f0d4bdfac
Y: 0x879367bd0ebcf1b97fdb0841c33333f7c321a41c2ced6ab14a1cd2cc7684f6bf
Z: 0x99682c948ddc2ddd15966aecfe83fe52b1df7d76255d460f90d7bd615bb80cfc
(Projective point on curve "P256")

In [8]: h.normalize()  # gives the same result as x * P256.G
Out[8]:
X: 0x32079326d26449f8b36bde4410f805eb520c0120da1585c79c369f356c8a298f
Y: 0x249daa2c57c8d6a90575630635aa5448fa56d21f5e363c155fe98c597b1c70ae
(Affine point on curve "P256")
```

--------------------------------

### Point Arithmetic Operations

Source: https://fastecdsa.readthedocs.io/en/latest/point-arithmetic.html

Demonstrates the standard arithmetic operations available on Point objects: addition, subtraction, doubling, scalar multiplication, and joint scalar multiplication.

```APIDOC
## Point Arithmetic Operations

### Description
Perform point addition, subtraction, doubling, scalar multiplication, and joint scalar multiplication on elliptic curve points using Python operators.

### Usage
```python
from fastecdsa.curve import P256
from fastecdsa.point import Point

# Create points
S = Point(xs, ys, curve=P256)
T = Point(xt, yt, curve=P256)

# Point Addition
R = S + T

# Point Subtraction
R = S - T

# Point Doubling
R = S + S  # or 2 * S

# Scalar Multiplication
R = d * S  # or S * d

# Joint Scalar Multiplication
R = d * S + e * T
```

### Operations
- **Addition** (`+`): Adds two points on the same curve.
- **Subtraction** (`-`): Subtracts one point from another (equivalent to adding the negation).
- **Doubling** (`+` with same point or `2 * point`): Doubles a point.
- **Scalar Multiplication** (`*`): Multiplies a point by an integer scalar.
- **Joint Scalar Multiplication**: Combines scalar multiplications and addition in one expression.
```

--------------------------------

### Curve Constructor

Source: https://fastecdsa.readthedocs.io/en/latest/_sources/user-defined-curves.rst.txt

Constructs a custom elliptic curve in Weierstrass form y^2 = x^3 + ax + b mod p. The constructor takes the curve name, parameters a, b, p, the order q of the base point, and the base point coordinates (gx, gy).

```APIDOC
## Curve Constructor

### Description
Constructs a custom elliptic curve in Weierstrass form \(y^2 \equiv x^3 + ax + b \pmod{p}\). The constructor validates that \(p\) is a non-even prime, the curve is non-singular, the point \((gx, gy)\) lies on the curve, and \(q\) is prime. Exhaustive validation (e.g., that \(q\) is the actual order of the point) is not performed.

### Method
Constructor

### Endpoint
`fastecdsa.curve.Curve`

### Parameters
- **name** (str) - Required - The name of the curve.
- **p** (int) - Required - The value of \(p\) in the curve equation.
- **a** (int) - Required - The value of \(a\) in the curve equation.
- **b** (int) - Required - The value of \(b\) in the curve equation.
- **q** (int) - Required - The order of the base point of the curve.
- **gx** (int) - Required - The x coordinate of the base point of the curve.
- **gy** (int) - Required - The y coordinate of the base point of the curve.

### Request Example
```python
from fastecdsa.curve import Curve
curve = Curve(
    name,  # (str): The name of the curve
    p,     # (int): The value of p in the curve equation.
    a,     # (int): The value of a in the curve equation.
    b,     # (int): The value of b in the curve equation.
    q,     # (int): The order of the base point of the curve.
    gx,    # (int): The x coordinate of the base point of the curve.
    gy,    # (int): The y coordinate of the base point of the curve.
)
```

### Response
#### Success Response
Returns a `Curve` object representing the custom curve.

#### Response Example
No explicit response example is provided in the source.
```

--------------------------------

### Edwards Curve Point Arithmetic with Ed25519Point

Source: https://fastecdsa.readthedocs.io/en/latest/point-arithmetic.html

Interactive session showing how to use the Ed25519Point class for Edwards curve arithmetic, including point doubling, addition, and scalar multiplication via scale_base. Demonstrates the extended projective representation and normalization.

```python
In [1]: from fastecdsa.eddsa import Ed25519Point as e25519

In [2]: G = e25519.g()

In [3]: G
Out[3]:
X: 0x216936d3cd6e53fec0a4e231fdd6dc5c692cc7609525a7b2c9562d608f25d51a
Y: 0x6666666666666666666666666666666666666666666666666666666666666658
(Affine point on curve Edwards25519)

In [4]: G * 2
Out[4]:
X: 0x36ab384c9f5a046c3d043b7d1833e7ac080d8e4515d7a45f83c5a14e2843ce0e
Y: 0x2260cdf3092329c21da25ee8c9a21f5697390f51643851560e5f46ae6af8a3c9
(Affine point on curve Edwards25519)

In [5]: G + G
Out[5]:
X: 0x36ab384c9f5a046c3d043b7d1833e7ac080d8e4515d7a45f83c5a14e2843ce0e
Y: 0x2260cdf3092329c21da25ee8c9a21f5697390f51643851560e5f46ae6af8a3c9
(Affine point on curve Edwards25519)

In [6]: e25519.scale_base(2)
Out[6]:
X: 0x5881d418cc897a3a0eb49cdb9e6859fe2c55894bcdf7f8095714be2d5cf2e79a
Y: 0x27e006a46c706615d5ef0e2ff33fb48a6fbc113c77c0bd916574e8d0e2c42106
Z: 0x1f7616052c96e0810d7ff513e392dfbad03e66e0a95c8d2796a29516b07725f4
T: 0x5dec8aec83e2c5266dd025b8da706eed6a2729713b3f035372c8624d35caa7b
(Extended projective point on curve Edwards25519)

In [7]: _.normalize()
Out[7]:
X: 0x36ab384c9f5a046c3d043b7d1833e7ac080d8e4515d7a45f83c5a14e2843ce0e
Y: 0x2260cdf3092329c21da25ee8c9a21f5697390f51643851560e5f46ae6af8a3c9
(Affine point on curve Edwards25519

```

--------------------------------

### Curve Constructor

Source: https://fastecdsa.readthedocs.io/en/latest/user-defined-curves.html

Creates a new elliptic curve in Weierstrass form with the given parameters. The constructor applies sanity checks in version 4.0.0+ to ensure the curve is valid.

```APIDOC
## Curve Constructor

### Description
Creates a new elliptic curve in Weierstrass form with the given parameters. The constructor applies sanity checks in version 4.0.0+ to ensure the curve is valid.

### Method
Constructor

### Endpoint
`Curve(name, p, a, b, q, gx, gy)`

### Parameters
- **name** (str) - Required - The name of the curve
- **p** (int) - Required - The value of p in the curve equation
- **a** (int) - Required - The value of a in the curve equation
- **b** (int) - Required - The value of b in the curve equation
- **q** (int) - Required - The order of the base point of the curve
- **gx** (int) - Required - The x coordinate of the base point of the curve
- **gy** (int) - Required - The y coordinate of the base point of the curve

### Request Example
```python
from fastecdsa.curve import Curve
curve = Curve(
    name,  # (str): The name of the curve
    p,     # (int): The value of p in the curve equation.
    a,     # (int): The value of a in the curve equation.
    b,     # (int): The value of b in the curve equation.
    q,     # (int): The order of the base point of the curve.
    gx,    # (int): The x coordinate of the base point of the curve.
    gy,    # (int): The y coordinate of the base point of the curve.
)
```

### Response
#### Success Response
- **curve** (Curve) - The constructed curve object

#### Response Example
```python
curve = Curve(...)
```

### Notes
- In versions before 4.0.0, no checks on the curve parameters are done.
- In 4.0.0+, the following sanity checks are applied:
  - `p` must be a non-even (not 2) prime
  - The curve cannot be singular (discriminant equal to 0)
  - `(gx, gy)` must be a point on the curve
  - `q` must be prime
- Exhaustive validation checks are not performed, e.g., no check that `q` is actually the order of point `(gx, gy)` is performed.
```

--------------------------------

### Edwards Curve Point Operations

Source: https://fastecdsa.readthedocs.io/en/latest/point-arithmetic.html

Demonstrates usage of the dedicated point classes for Edwards curves (Ed25519 and Ed448), including point creation, addition, doubling, scalar multiplication, and normalization.

```APIDOC
## Edwards Curve Point Operations

### Description
Use the Ed25519Point and Ed448Point classes for arithmetic on Edwards curves. These classes provide methods for point generation, addition, scalar multiplication, and normalization.

### Usage
```python
from fastecdsa.eddsa import Ed25519Point as e25519

# Get the generator point
G = e25519.g()

# Point doubling
result = G * 2

# Point addition
result = G + G

# Scalar multiplication with scaling
result = e25519.scale_base(2)

# Normalize a projective point to affine
normalized = result.normalize()
```

### Methods
- **g()**: Returns the generator point of the curve.
- **scale_base(scalar)**: Returns the scalar multiplication of the base point, returning a projective point.
- **normalize()**: Converts a projective point to an affine point.

### Notes
- Ed448Point has the same interface but uses standard projective coordinates that omit the T coordinate.
```

--------------------------------

### Create a custom Curve object with fastecdsa

Source: https://fastecdsa.readthedocs.io/en/latest/_sources/user-defined-curves.rst.txt

Constructs a Curve instance for a user-defined Weierstrass curve. Requires parameters p, a, b, q, gx, gy, and a name. Since version 4.0.0, sanity checks ensure p is a non-even prime, the curve is non-singular, (gx, gy) is on the curve, and q is prime; exhaustive validation is not performed.

```python
from fastecdsa.curve import Curve
curve = Curve(
    name,  # (str): The name of the curve
    p,     # (int): The value of p in the curve equation.
    a,     # (int): The value of a in the curve equation.
    b,     # (int): The value of b in the curve equation.
    q,     # (int): The order of the base point of the curve.
    gx,    # (int): The x coordinate of the base point of the curve.
    gy,    # (int): The y coordinate of the base point of the curve.
)
```

--------------------------------

### Create a custom curve with fastecdsa.curve.Curve

Source: https://fastecdsa.readthedocs.io/en/latest/user-defined-curves.html

Constructs a Curve object for a user-defined Weierstrass curve. Requires parameters: name, p, a, b, q, gx, gy. In versions 4.0.0+, sanity checks are applied: p must be a non-even prime, the curve must be non-singular, (gx, gy) must be on the curve, and q must be prime. Exhaustive validation is not performed, e.g., q is not checked to be the actual order of the base point.

```python
from fastecdsa.curve import Curve
curve = Curve(
    name,  # (str): The name of the curve
    p,     # (int): The value of p in the curve equation.
    a,     # (int): The value of a in the curve equation.
    b,     # (int): The value of b in the curve equation.
    q,     # (int): The order of the base point of the curve.
    gx,    # (int): The x coordinate of the base point of the curve.
    gy,    # (int): The y coordinate of the base point of the curve.
)

```

--------------------------------

### RFC6979.gen_nonce()

Source: https://fastecdsa.readthedocs.io/en/latest/fastecdsa.html

Generates a deterministic nonce per RFC6979 for use in ECDSA signing. This method avoids nonce reuse by deriving the nonce from the message and private key using HMAC.

```APIDOC
## RFC6979.gen_nonce()

### Description
Generates a nonce per RFC6979. This method is used to deterministically generate a nonce for ECDSA signing, avoiding nonce reuse which could leak the private key.

### Method
Function

### Signature
`gen_nonce() -> int`

### Parameters
None

### Returns
- **int**: The generated nonce.

### Reference
http://tools.ietf.org/html/rfc6979#section-3.2
```

--------------------------------

### Edwards Curve Point Arithmetic with Ed25519Point

Source: https://fastecdsa.readthedocs.io/en/latest/_sources/point-arithmetic.rst.txt

Shows usage of the Ed25519Point class for Edwards curve arithmetic, including generator creation, doubling, addition, and scalar multiplication via scale_base. The output shows affine and extended projective point representations. Note that Ed448Point has the same interface but uses standard projective coordinates that omit 'T'.

```python
In [1]: from fastecdsa.eddsa import Ed25519Point as e25519

In [2]: G = e25519.g()

In [3]: G
Out[3]:
X: 0x216936d3cd6e53fec0a4e231fdd6dc5c692cc7609525a7b2c9562d608f25d51a
Y: 0x6666666666666666666666666666666666666666666666666666666666666658
(Affine point on curve Edwards25519)

In [4]: G * 2
Out[4]:
X: 0x36ab384c9f5a046c3d043b7d1833e7ac080d8e4515d7a45f83c5a14e2843ce0e
Y: 0x2260cdf3092329c21da25ee8c9a21f5697390f51643851560e5f46ae6af8a3c9
(Affine point on curve Edwards25519)

In [5]: G + G
Out[5]:
X: 0x36ab384c9f5a046c3d043b7d1833e7ac080d8e4515d7a45f83c5a14e2843ce0e
Y: 0x2260cdf3092329c21da25ee8c9a21f5697390f51643851560e5f46ae6af8a3c9
(Affine point on curve Edwards25519)

In [6]: e25519.scale_base(2)
Out[6]:
X: 0x5881d418cc897a3a0eb49cdb9e6859fe2c55894bcdf7f8095714be2d5cf2e79a
Y: 0x27e006a46c706615d5ef0e2ff33fb48a6fbc113c77c0bd916574e8d0e2c42106
Z: 0x1f7616052c96e0810d7ff513e392dfbad03e66e0a95c8d2796a29516b07725f4
T: 0x5dec8aec83e2c5266dd025b8da706eed6a2729713b3f035372c8624d35caa7b
(Extended projective point on curve Edwards25519)

In [7]: _.normalize()
Out[7]:
X: 0x36ab384c9f5a046c3d043b7d1833e7ac080d8e4515d7a45f83c5a14e2843ce0e
Y: 0x2260cdf3092329c21da25ee8c9a21f5697390f51643851560e5f46ae6af8a3c9
(Affine point on curve Edwards25519
```

--------------------------------

### fastecdsa.util.mod_sqrt()

Source: https://fastecdsa.readthedocs.io/en/latest/fastecdsa.html

Computes the square root of a modulo p in the field of integers modulo p. Returns the two values of x that satisfy x^2 ≡ a (mod p).

```APIDOC
## fastecdsa.util.mod_sqrt(a, p)

### Description
Compute the square root of a (mod p). In other words, find a value x such that x^2 ≡ a (mod p).

### Method
Function

### Signature
`mod_sqrt(a: int, p: int) -> tuple[int, int]`

### Parameters
- **a** (int) - Required - The value whose root to take.
- **p** (int) - Required - The prime whose field to perform the square root in.

### Returns
- **tuple[int, int]**: The two values of x satisfying x^2 ≡ a (mod p).
```
Tokens:
Raw