0
# ECDSA
1

2
A pure Python implementation of Elliptic Curve Cryptography (ECC) providing comprehensive support for ECDSA (Elliptic Curve Digital Signature Algorithm), EdDSA (Edwards-curve Digital Signature Algorithm), and ECDH (Elliptic Curve Diffie-Hellman) protocols. The library supports multiple cryptographic curves including NIST Suite B curves, Bitcoin's secp256k1, Brainpool curves, and Edwards curves for secure digital signing, signature verification, and key exchange operations.
3

4
## Package Information
5

6
- **Package Name**: ecdsa
7
- **Language**: Python
8
- **Installation**: `pip install ecdsa`
9

10
## Core Imports
11

12
```python
13
import ecdsa
14
```
15

16
Common imports for key operations:
17

18
```python
19
from ecdsa import SigningKey, VerifyingKey, NIST256p, SECP256k1
20
```
21

22
For specific functionality:
23

24
```python
25
from ecdsa import ECDH, BadSignatureError
26
from ecdsa.util import sigencode_der, sigdecode_der, sigencode_string, sigdecode_string
27
from ecdsa.curves import Ed25519, BRAINPOOLP256r1
28
```
29

30
## Basic Usage
31

32
```python
33
from ecdsa import SigningKey, VerifyingKey, NIST256p, BadSignatureError
34
import hashlib
35

36
# Generate a new signing key
37
sk = SigningKey.generate(curve=NIST256p)
38
vk = sk.verifying_key
39

40
# Sign some data
41
message = b"Hello, world!"
42
signature = sk.sign(message, hashfunc=hashlib.sha256)
43

44
# Verify the signature
45
try:
46
    vk.verify(signature, message, hashfunc=hashlib.sha256)
47
    print("Signature is valid")
48
except BadSignatureError:
49
    print("Invalid signature")
50

51
# Export keys
52
private_key_pem = sk.to_pem()
53
public_key_pem = vk.to_pem()
54

55
# Load keys from PEM
56
loaded_sk = SigningKey.from_pem(private_key_pem)
57
loaded_vk = VerifyingKey.from_pem(public_key_pem)
58
```
59

60
## Architecture
61

62
The ecdsa library follows a layered architecture built around elliptic curve mathematics:
63

64
- **Key Classes**: SigningKey and VerifyingKey provide high-level ECDSA/EdDSA operations
65
- **ECDH Class**: Implements elliptic curve Diffie-Hellman key agreement protocol
66
- **Curve Objects**: Pre-defined curve parameters for NIST, SECP, Brainpool, and Edwards curves
67
- **Mathematical Foundation**: Point arithmetic, finite field operations, and number theory functions
68
- **Encoding/Decoding**: DER, PEM, SSH formats and signature encoding schemes
69
- **Utilities**: Random number generation, deterministic signatures (RFC 6979), and format conversions
70

71
This design enables cryptographically secure operations while maintaining compatibility across Python 2.6+ and 3.6+ environments without external C dependencies.
72

73
## Capabilities
74

75
### Core Keys & Signatures
76

77
Primary ECDSA/EdDSA functionality including key generation, digital signing, and signature verification with support for multiple hash functions, signature encodings, and deterministic signatures.
78

79
```python { .api }
80
class SigningKey:
81
    @classmethod
82
    def generate(cls, curve=NIST192p, entropy=None, hashfunc=sha1): ...
83
    @classmethod
84
    def from_secret_exponent(cls, secexp, curve=NIST192p, hashfunc=sha1): ...
85
    @classmethod
86
    def from_string(cls, string, curve=NIST192p, hashfunc=sha1): ...
87
    @classmethod
88
    def from_pem(cls, string, hashfunc=sha1, valid_curve_encodings=None): ...
89
    @classmethod
90
    def from_der(cls, string, hashfunc=sha1, valid_curve_encodings=None): ...
91
    
92
    def sign(self, data, entropy=None, hashfunc=None, sigencode=sigencode_string, k=None, allow_truncate=True): ...
93
    def sign_deterministic(self, data, hashfunc=None, sigencode=sigencode_string, extra_entropy=b""): ...
94
    def sign_digest(self, digest, entropy=None, sigencode=sigencode_string, k=None, allow_truncate=False): ...
95
    def sign_digest_deterministic(self, digest, hashfunc=None, sigencode=sigencode_string, extra_entropy=b"", allow_truncate=False): ...
96
    def sign_number(self, number, entropy=None, k=None): ...
97
    def get_verifying_key(self): ...
98
    def to_string(self): ...
99
    def to_pem(self, point_encoding="uncompressed", format="ssleay", curve_parameters_encoding=None): ...
100
    def to_der(self, point_encoding="uncompressed", format="ssleay", curve_parameters_encoding=None): ...
101
    def to_ssh(self): ...
102

103
class VerifyingKey:
104
    @classmethod
105
    def from_public_point(cls, point, curve=NIST192p, hashfunc=sha1, validate_point=True): ...
106
    @classmethod
107
    def from_string(cls, string, curve=NIST192p, hashfunc=sha1, validate_point=True, valid_encodings=None): ...
108
    @classmethod
109
    def from_pem(cls, string, hashfunc=sha1, valid_encodings=None, valid_curve_encodings=None): ...
110
    @classmethod
111
    def from_der(cls, string, hashfunc=sha1, valid_encodings=None, valid_curve_encodings=None): ...
112
    @classmethod
113
    def from_public_key_recovery(cls, signature, data, curve, hashfunc=sha1, sigdecode=sigdecode_string, allow_truncate=True): ...
114
    @classmethod
115
    def from_public_key_recovery_with_digest(cls, signature, digest, curve, hashfunc=sha1, sigdecode=sigdecode_string, allow_truncate=False): ...
116
    
117
    def verify(self, signature, data, hashfunc=None, sigdecode=sigdecode_string, allow_truncate=True): ...
118
    def verify_digest(self, signature, digest, sigdecode=sigdecode_string, allow_truncate=False): ...
119
    def precompute(self, lazy=False): ...
120
    def to_string(self, encoding="raw"): ...
121
    def to_pem(self, point_encoding="uncompressed", curve_parameters_encoding=None): ...
122
    def to_der(self, point_encoding="uncompressed", curve_parameters_encoding=None): ...
123
    def to_ssh(self): ...
124
```
125

126
[Core Keys & Signatures](./keys-signatures.md)
127

128
### ECDH Key Exchange
129

130
Elliptic Curve Diffie-Hellman key agreement protocol implementation for secure shared secret generation between parties using elliptic curve cryptography.
131

132
```python { .api }
133
class ECDH:
134
    def __init__(self, curve=None, private_key=None, public_key=None): ...
135
    
136
    def set_curve(self, key_curve): ...
137
    def generate_private_key(self): ...
138
    def load_private_key(self, private_key): ...
139
    def load_private_key_bytes(self, private_key): ...
140
    def load_private_key_der(self, private_key_der): ...
141
    def load_private_key_pem(self, private_key_pem): ...
142
    def get_public_key(self): ...
143
    def load_received_public_key(self, public_key): ...
144
    def load_received_public_key_bytes(self, public_key_str, valid_encodings=None): ...
145
    def load_received_public_key_der(self, public_key_der): ...
146
    def load_received_public_key_pem(self, public_key_pem): ...
147
    def generate_sharedsecret(self): ...
148
    def generate_sharedsecret_bytes(self): ...
149
```
150

151
[ECDH Key Exchange](./ecdh.md)
152

153
### Curves & Mathematical Foundation
154

155
Pre-defined elliptic curve parameters and mathematical operations supporting NIST Suite B curves, SECP curves, Brainpool curves, and Edwards curves for various cryptographic applications.
156

157
```python { .api }
158
# NIST Curves
159
NIST192p: Curve
160
NIST224p: Curve
161
NIST256p: Curve
162
NIST384p: Curve
163
NIST521p: Curve
164

165
# SECP Curves
166
SECP256k1: Curve  # Bitcoin curve
167
SECP112r1: Curve
168
SECP112r2: Curve
169
SECP128r1: Curve
170
SECP160r1: Curve
171

172
# Edwards Curves
173
Ed25519: Curve
174
Ed448: Curve
175

176
# Brainpool Curves (r1 series)
177
BRAINPOOLP160r1: Curve
178
BRAINPOOLP192r1: Curve
179
BRAINPOOLP224r1: Curve
180
BRAINPOOLP256r1: Curve
181
BRAINPOOLP320r1: Curve
182
BRAINPOOLP384r1: Curve
183
BRAINPOOLP512r1: Curve
184

185
# Brainpool Curves (t1 series)
186
BRAINPOOLP160t1: Curve
187
BRAINPOOLP192t1: Curve
188
BRAINPOOLP224t1: Curve
189
BRAINPOOLP256t1: Curve
190
BRAINPOOLP320t1: Curve
191
BRAINPOOLP384t1: Curve
192
BRAINPOOLP512t1: Curve
193

194
class Curve:
195
    def to_der(self, encoding=None, point_encoding="uncompressed"): ...
196
    def to_pem(self, encoding=None, point_encoding="uncompressed"): ...
197

198
# Curve utility functions
199
def find_curve(oid_curve): ...
200
def curve_by_name(name): ...
201
curves: list  # List of all supported curve objects
202
```
203

204
[Curves & Mathematical Foundation](./curves.md)
205

206
### Encoding & Decoding Utilities
207

208
Comprehensive encoding and decoding utilities for signature formats (DER, raw), key formats (PEM, DER, SSH), and ASN.1 structures used in elliptic curve cryptography.
209

210
```python { .api }
211
# Signature encoding/decoding
212
def sigencode_der(r, s, order): ...
213
def sigencode_string(r, s, order): ...
214
def sigencode_strings(r, s, order): ...
215
def sigencode_string_canonize(r, s, order): ...
216
def sigencode_strings_canonize(r, s, order): ...
217
def sigencode_der_canonize(r, s, order): ...
218
def sigdecode_der(sig_der, order): ...
219
def sigdecode_string(signature, order): ...
220
def sigdecode_strings(rs_strings, order): ...
221

222
# DER encoding/decoding
223
def encode_sequence(*encoded_pieces): ...
224
def encode_integer(r): ...
225
def encode_octet_string(s): ...
226
def encode_bitstring(s, unused=0): ...
227
def encode_oid(first, second, *pieces): ...
228
def encode_constructed(tag, value): ...
229
def encode_implicit(tag, value, cls="context-specific"): ...
230
def remove_sequence(string): ...
231
def remove_integer(string): ...
232
def remove_octet_string(string): ...
233
def remove_bitstring(string, expect_unused=0): ...
234
def remove_object(string): ...
235
def remove_constructed(string): ...
236

237
# Number/string conversion
238
def number_to_string(num, order): ...
239
def number_to_string_crop(num, order): ...
240
def string_to_number(string): ...
241
def string_to_number_fixedlen(string, order): ...
242
```
243

244
[Encoding & Decoding Utilities](./encoding.md)
245

246
### EdDSA Digital Signatures
247

248
Edwards-curve Digital Signature Algorithm providing deterministic, high-performance signatures using Ed25519 and Ed448 curves with built-in resistance to side-channel attacks.
249

250
```python { .api }
251
class PublicKey:
252
    def __init__(self, generator, public_key, public_point=None): ...
253
    def public_point(self): ...
254
    def public_key(self): ...
255
    def verify(self, data, signature): ...
256

257
class PrivateKey:
258
    def __init__(self, generator, private_key): ...
259
    def private_key(self): ...
260
    def public_key(self): ...
261
    def sign(self, data): ...
262

263
# Edwards curve parameters
264
curve_ed25519: CurveEdTw
265
generator_ed25519: PointEdwards
266
curve_ed448: CurveEdTw
267
generator_ed448: PointEdwards
268
```
269

270
[EdDSA Digital Signatures](./eddsa.md)
271

272
### Mathematical Functions & Low-Level Operations
273

274
Number theory functions, polynomial operations, deterministic signature generation (RFC 6979), and low-level ECDSA mathematical operations for advanced cryptographic applications.
275

276
```python { .api }
277
# Number theory operations
278
def gcd(*a): ...
279
def lcm(*a): ...
280
def jacobi(a, n): ...
281
def square_root_mod_prime(a, p): ...
282
def is_prime(n): ...
283
def next_prime(starting_value): ...
284

285
# RFC 6979 deterministic signatures
286
def generate_k(order, secexp, hash_func, data, retry_gen=0, extra_entropy=b""): ...
287
def bits2int(data, qlen): ...
288
def bits2octets(data, order): ...
289

290
# Low-level ECDSA classes
291
class Signature:
292
    def recover_public_keys(self, hash, generator): ...
293

294
class Public_key:
295
    def verifies(self, hash, signature): ...
296

297
class Private_key:
298
    def sign(self, hash, k): ...
299

300
# Utility functions
301
def point_is_valid(generator, x, y): ...
302
def bit_length(x): ...
303
def orderlen(order): ...
304
```
305

306
[Mathematical Functions & Low-Level Operations](./mathematical-functions.md)
307

308
## Exception Classes
309

310
The library defines specific exception classes for different error conditions:
311

312
```python { .api }
313
# Core signature and key exceptions
314
class BadSignatureError(Exception): ...
315
class BadDigestError(Exception): ...  
316
class MalformedPointError(AssertionError): ...
317

318
# DER encoding/decoding exceptions
319
class UnexpectedDER(Exception): ...
320

321
# ECDH key exchange exceptions
322
class NoKeyError(Exception): ...
323
class NoCurveError(Exception): ...
324
class InvalidCurveError(Exception): ...
325
class InvalidSharedSecretError(Exception): ...
326

327
# Low-level ECDSA exceptions
328
class RSZeroError(RuntimeError): ...
329
class InvalidPointError(RuntimeError): ...
330

331
# Curve and mathematical exceptions
332
class UnknownCurveError(Exception): ...
333

334
# Number theory exceptions
335
class JacobiError(Exception): ...
336
class SquareRootError(Exception): ...
337
class NegativeExponentError(Exception): ...
338

339
# Utility exceptions
340
class MalformedSignature(Exception): ...
341
```
342

343
## Version Information
344

345
```python { .api }
346
__version__: str  # Current package version
347
```