0
# Curves & Mathematical Foundation
1

2
Pre-defined elliptic curve parameters and mathematical operations supporting a comprehensive range of standardized curves. The ecdsa library provides curves from NIST Suite B, SECP standards, Brainpool specifications, and Edwards curves for various cryptographic applications and compliance requirements.
3

4
## Capabilities
5

6
### NIST Curves
7

8
NIST (National Institute of Standards and Technology) Suite B curves, widely adopted for government and commercial cryptographic applications.
9

10
```python { .api }
11
NIST192p: Curve  # NIST P-192 (secp192r1, prime192v1) - 192-bit security
12
NIST224p: Curve  # NIST P-224 (secp224r1) - 224-bit security  
13
NIST256p: Curve  # NIST P-256 (secp256r1, prime256v1) - 256-bit security
14
NIST384p: Curve  # NIST P-384 (secp384r1) - 384-bit security
15
NIST521p: Curve  # NIST P-521 (secp521r1) - 521-bit security (not 512!)
16
```
17

18
**NIST Curve Properties:**
19
- Recommended by US government standards
20
- Widely supported across implementations
21
- Well-studied security properties
22
- Common in TLS/SSL, government applications
23

24
### SECP Curves
25

26
Standards for Efficient Cryptography Project (SECP) curves, including the famous Bitcoin curve.
27

28
```python { .api }
29
SECP112r1: Curve  # secp112r1 - 112-bit security (legacy, weak)
30
SECP112r2: Curve  # secp112r2 - 112-bit security (legacy, weak)
31
SECP128r1: Curve  # secp128r1 - 128-bit security (legacy, weak)
32
SECP160r1: Curve  # secp160r1 - 160-bit security (legacy, weak)
33
SECP256k1: Curve  # secp256k1 - 256-bit security (Bitcoin, Ethereum)
34
```
35

36
**Notable SECP Curves:**
37
- `SECP256k1`: Used by Bitcoin, Ethereum, and other cryptocurrencies
38
- Legacy curves (112, 128, 160-bit) provided for compatibility but not recommended
39
- Different mathematical properties from NIST curves
40

41
### Brainpool Curves
42

43
European Telecommunications Standards Institute (ETSI) Brainpool curves, providing alternative curve parameters with transparent generation.
44

45
#### Brainpool Random Curves (r1 series)
46

47
```python { .api }
48
BRAINPOOLP160r1: Curve  # Brainpool P-160r1 - 160-bit security
49
BRAINPOOLP192r1: Curve  # Brainpool P-192r1 - 192-bit security
50
BRAINPOOLP224r1: Curve  # Brainpool P-224r1 - 224-bit security
51
BRAINPOOLP256r1: Curve  # Brainpool P-256r1 - 256-bit security
52
BRAINPOOLP320r1: Curve  # Brainpool P-320r1 - 320-bit security
53
BRAINPOOLP384r1: Curve  # Brainpool P-384r1 - 384-bit security
54
BRAINPOOLP512r1: Curve  # Brainpool P-512r1 - 512-bit security
55
```
56

57
#### Brainpool Twisted Curves (t1 series)
58

59
```python { .api }
60
BRAINPOOLP160t1: Curve  # Brainpool P-160t1 - 160-bit security
61
BRAINPOOLP192t1: Curve  # Brainpool P-192t1 - 192-bit security
62
BRAINPOOLP224t1: Curve  # Brainpool P-224t1 - 224-bit security
63
BRAINPOOLP256t1: Curve  # Brainpool P-256t1 - 256-bit security
64
BRAINPOOLP320t1: Curve  # Brainpool P-320t1 - 320-bit security
65
BRAINPOOLP384t1: Curve  # Brainpool P-384t1 - 384-bit security
66
BRAINPOOLP512t1: Curve  # Brainpool P-512t1 - 512-bit security
67
```
68

69
**Brainpool Curve Features:**
70
- European standard alternative to NIST curves
71
- Transparent parameter generation process
72
- r1 (random) and t1 (twisted) variants available
73
- Used in European government and industry applications
74

75
### Edwards Curves
76

77
Montgomery and Edwards curves optimized for digital signature algorithms (EdDSA).
78

79
```python { .api }
80
Ed25519: Curve  # Edwards 25519 - ~128-bit security, optimized for EdDSA
81
Ed448: Curve    # Edwards 448 - ~224-bit security, optimized for EdDSA
82
```
83

84
**Edwards Curve Features:**
85
- Designed for EdDSA (Edwards-curve Digital Signature Algorithm)
86
- Faster and more secure than traditional ECDSA on these curves
87
- Resistance to timing attacks and other side-channel vulnerabilities
88
- Ed25519 widely adopted in modern applications (SSH, TLS 1.3, etc.)
89

90
### Curve Class
91

92
The Curve class encapsulates all parameters and operations for a specific elliptic curve.
93

94
```python { .api }
95
class Curve:
96
    def __init__(self, name, curve, generator, oid, openssl_name=None):
97
        """
98
        Initialize curve with parameters.
99

100
        Parameters:
101
        - name: str, human-readable curve name
102
        - curve: mathematical curve object (CurveFp or CurveEdTw)
103
        - generator: Point object, generator point
104
        - oid: tuple, ASN.1 Object Identifier
105
        - openssl_name: str or None, OpenSSL curve name
106
        """
107

108
    def to_der(self, encoding=None, point_encoding="uncompressed"):
109
        """
110
        Export curve parameters in DER format.
111

112
        Parameters:
113
        - encoding: str or None, parameter encoding method
114
        - point_encoding: str, point encoding format
115

116
        Returns:
117
        bytes, DER-encoded curve parameters
118
        """
119

120
    def to_pem(self, encoding=None, point_encoding="uncompressed"):
121
        """
122
        Export curve parameters in PEM format.
123

124
        Parameters:
125
        - encoding: str or None, parameter encoding method
126
        - point_encoding: str, point encoding format
127

128
        Returns:
129
        str, PEM-encoded curve parameters
130
        """
131

132
    @staticmethod
133
    def from_der(data, valid_encodings=None):
134
        """
135
        Load curve from DER-encoded parameters.
136

137
        Parameters:
138
        - data: bytes, DER-encoded curve parameters
139
        - valid_encodings: list or None, acceptable encodings
140

141
        Returns:
142
        Curve object
143
        """
144

145
    @classmethod
146
    def from_pem(cls, string, valid_encodings=None):
147
        """
148
        Load curve from PEM-encoded parameters.
149

150
        Parameters:
151
        - string: str, PEM-encoded curve parameters
152
        - valid_encodings: list or None, acceptable encodings
153

154
        Returns:
155
        Curve object
156
        """
157
```
158

159
#### Curve Attributes
160

161
```python { .api }
162
    name: str                    # Human-readable curve name
163
    curve: object               # Mathematical curve object
164
    generator: Point            # Generator point on the curve
165
    order: int                  # Order of the curve (number of points)
166
    baselen: int               # Base length in bytes for keys
167
    verifying_key_length: int  # Public key length in bytes
168
    signature_length: int      # Signature length in bytes
169
    oid: tuple                 # ASN.1 Object Identifier
170
    openssl_name: str          # OpenSSL curve name (if available)
171
```
172

173
### Curve Utility Functions
174

175
Functions for finding and working with curves by name or identifier.
176

177
```python { .api }
178
def find_curve(oid_curve):
179
    """
180
    Find curve by ASN.1 Object Identifier.
181

182
    Parameters:
183
    - oid_curve: tuple, ASN.1 OID tuple
184

185
    Returns:
186
    Curve object
187

188
    Raises:
189
    UnknownCurveError: if curve not found
190
    """
191

192
def curve_by_name(name):
193
    """
194
    Find curve by name string.
195

196
    Parameters:
197
    - name: str, curve name (e.g., "NIST256p", "secp256k1")
198

199
    Returns:
200
    Curve object
201

202
    Raises:
203
    UnknownCurveError: if curve not found
204
    """
205

206
curves: list  # List of all supported Curve objects
207
```
208

209
### Mathematical Foundation Classes
210

211
Low-level mathematical classes that implement elliptic curve arithmetic (primarily for internal use).
212

213
```python { .api }
214
class CurveFp:
215
    """Elliptic curve over finite field (Weierstrass form: y² = x³ + ax + b)."""
216

217
class CurveEdTw:
218
    """Twisted Edwards curve (ax² + y² = 1 + dx²y²)."""
219

220
class Point:
221
    """Point on elliptic curve in affine coordinates."""
222

223
class PointJacobi:
224
    """Point on elliptic curve in Jacobian coordinates (for efficiency)."""
225

226
class PointEdwards:
227
    """Point on Edwards curve."""
228
```
229

230
## Exception Classes
231

232
```python { .api }
233
class UnknownCurveError(Exception):
234
    """Raised when referencing an unknown or unsupported curve."""
235
```
236

237
## Usage Examples
238

239
### Working with Different Curve Types
240

241
```python
242
from ecdsa import SigningKey, NIST256p, SECP256k1, Ed25519, BRAINPOOLP384r1
243

244
# NIST curve (government standard)
245
nist_key = SigningKey.generate(curve=NIST256p)
246
print(f"NIST P-256 key length: {nist_key.baselen} bytes")
247

248
# Bitcoin curve
249
bitcoin_key = SigningKey.generate(curve=SECP256k1)
250
print(f"Bitcoin secp256k1 key length: {bitcoin_key.baselen} bytes")
251

252
# Edwards curve (for EdDSA)
253
edwards_key = SigningKey.generate(curve=Ed25519)
254
print(f"Ed25519 key length: {edwards_key.baselen} bytes")
255

256
# European Brainpool curve
257
brainpool_key = SigningKey.generate(curve=BRAINPOOLP384r1)
258
print(f"Brainpool P-384r1 key length: {brainpool_key.baselen} bytes")
259
```
260

261
### Curve Information and Properties
262

263
```python
264
from ecdsa import NIST256p, SECP256k1, Ed25519
265
from ecdsa.curves import curves, curve_by_name
266

267
# Examine curve properties
268
for curve in [NIST256p, SECP256k1, Ed25519]:
269
    print(f"Curve: {curve.name}")
270
    print(f"  Key length: {curve.baselen} bytes")
271
    print(f"  Public key length: {curve.verifying_key_length} bytes")
272
    print(f"  Signature length: {curve.signature_length} bytes")
273
    print(f"  Order: {curve.order}")
274
    print(f"  OID: {curve.oid}")
275
    print()
276

277
# Find curve by name
278
try:
279
    secp_curve = curve_by_name("secp256k1")
280
    print(f"Found curve: {secp_curve.name}")
281
except UnknownCurveError:
282
    print("Curve not found")
283

284
# List all available curves
285
print(f"Total supported curves: {len(curves)}")
286
for curve in curves[:5]:  # Show first 5
287
    print(f"  {curve.name}")
288
```
289

290
### Curve Selection Guidelines
291

292
```python
293
from ecdsa import SigningKey, NIST256p, SECP256k1, Ed25519, BRAINPOOLP256r1
294

295
# For general applications - NIST P-256 (widely supported)
296
general_key = SigningKey.generate(curve=NIST256p)
297

298
# For blockchain/cryptocurrency - secp256k1
299
crypto_key = SigningKey.generate(curve=SECP256k1)
300

301
# For modern high-security applications - Ed25519
302
modern_key = SigningKey.generate(curve=Ed25519)
303

304
# For European compliance - Brainpool curves
305
eu_key = SigningKey.generate(curve=BRAINPOOLP256r1)
306

307
print("Generated keys for different use cases:")
308
print(f"General purpose (NIST P-256): {general_key.curve.name}")
309
print(f"Cryptocurrency (secp256k1): {crypto_key.curve.name}")
310
print(f"Modern security (Ed25519): {modern_key.curve.name}")
311
print(f"European standard (Brainpool): {eu_key.curve.name}")
312
```
313

314
### Curve Compatibility and Interoperability
315

316
```python
317
from ecdsa import SigningKey, VerifyingKey, NIST256p
318

319
# Generate key pair
320
sk = SigningKey.generate(curve=NIST256p)
321
vk = sk.verifying_key
322

323
# Export curve parameters
324
curve_der = sk.curve.to_der()
325
curve_pem = sk.curve.to_pem()
326

327
print(f"Curve DER parameters: {len(curve_der)} bytes")
328
print(f"Curve PEM parameters: {len(curve_pem)} characters")
329

330
# Curve metadata
331
print(f"Curve name: {sk.curve.name}")
332
print(f"OpenSSL name: {getattr(sk.curve, 'openssl_name', 'N/A')}")
333
print(f"OID: {sk.curve.oid}")
334
```
335

336
### Security Considerations by Curve Type
337

338
```python
339
from ecdsa import curves
340

341
# Analyze security levels of different curves
342
security_levels = {
343
    # Approximate security levels in bits
344
    112: ["SECP112r1", "SECP112r2"],
345
    128: ["SECP128r1"],
346
    160: ["SECP160r1", "BRAINPOOLP160r1", "BRAINPOOLP160t1"],
347
    192: ["NIST192p", "BRAINPOOLP192r1", "BRAINPOOLP192t1"],
348
    224: ["NIST224p", "BRAINPOOLP224r1", "BRAINPOOLP224t1"],
349
    256: ["NIST256p", "SECP256k1", "BRAINPOOLP256r1", "BRAINPOOLP256t1"],
350
    320: ["BRAINPOOLP320r1", "BRAINPOOLP320t1"],
351
    384: ["NIST384p", "BRAINPOOLP384r1", "BRAINPOOLP384t1"],
352
    512: ["BRAINPOOLP512r1", "BRAINPOOLP512t1"],
353
    521: ["NIST521p"],
354
}
355

356
print("Curve security levels:")
357
for bits, curve_names in security_levels.items():
358
    if bits < 160:
359
        status = "(WEAK - not recommended)"
360
    elif bits < 256:
361
        status = "(legacy)"
362
    else:
363
        status = "(strong)"
364
    print(f"{bits}-bit {status}: {', '.join(curve_names)}")
365

366
# Special cases
367
print("\nSpecial curves:")
368
print("Ed25519: ~128-bit security, optimized for EdDSA")
369
print("Ed448: ~224-bit security, optimized for EdDSA")
370
```