0
# Digital Signatures
1

2
Comprehensive digital signature schemes providing authentication, integrity, and non-repudiation. Supports RSA-based signatures (PKCS#1 v1.5, PSS), DSA variants, and modern EdDSA with deterministic and probabilistic options.
3

4
## Capabilities
5

6
### RSA Signatures - PKCS#1 v1.5
7

8
Traditional RSA signature scheme with PKCS#1 v1.5 padding, widely supported but less secure than PSS for new applications.
9

10
```python { .api }
11
# Legacy interface
12
def PKCS1_v1_5.new(rsa_key):
13
    """
14
    Create PKCS#1 v1.5 signature scheme.
15
    
16
    Parameters:
17
    - rsa_key: RSA key object (private for signing, public for verification)
18
    
19
    Returns:
20
    Signature scheme object with can_sign/sign/verify methods
21
    """
22

23
# Modern interface  
24
def pkcs1_15.new(rsa_key):
25
    """
26
    Create PKCS#1 v1.5 signature scheme with modern interface.
27
    
28
    Parameters:
29
    - rsa_key: RSA key object
30
    
31
    Returns:
32
    PKCS115_SigScheme object
33
    """
34

35
class PKCS115_SigScheme:
36
    """PKCS#1 v1.5 signature scheme."""
37
    
38
    def can_sign(self) -> bool:
39
        """Check if private key is available for signing."""
40
    
41
    def sign(self, msg_hash) -> bytes:
42
        """
43
        Sign a message hash.
44
        
45
        Parameters:
46
        - msg_hash: Hash object with digest() method
47
        
48
        Returns:
49
        Signature bytes
50
        """
51
    
52
    def verify(self, msg_hash, signature: bytes) -> None:
53
        """
54
        Verify a signature.
55
        
56
        Parameters:
57
        - msg_hash: Hash object with digest() method  
58
        - signature (bytes): Signature to verify
59
        
60
        Raises:
61
        ValueError if signature is invalid
62
        """
63
```
64

65
### RSA Signatures - PSS
66

67
Probabilistic Signature Scheme providing provable security properties, recommended for new RSA signature applications.
68

69
```python { .api }
70
# Legacy interface
71
def PKCS1_PSS.new(rsa_key, mgfunc=None, saltLen=None, randfunc=None):
72
    """
73
    Create RSA-PSS signature scheme.
74
    
75
    Parameters:
76
    - rsa_key: RSA key object
77
    - mgfunc: Mask generation function (default: MGF1 with same hash as message)
78
    - saltLen (int): Salt length in bytes (default: hash length)
79
    - randfunc (callable): Random function for salt generation
80
    
81
    Returns:
82
    PSS signature scheme object
83
    """
84

85
# Modern interface
86
def pss.new(rsa_key, **kwargs):
87
    """
88
    Create RSA-PSS signature scheme with modern interface.
89
    
90
    Parameters:
91
    - rsa_key: RSA key object
92
    - mgfunc: Mask generation function
93
    - salt_bytes (int): Salt length in bytes
94
    - rand_func (callable): Random function
95
    
96
    Returns:
97
    PSS_SigScheme object
98
    """
99

100
class PSS_SigScheme:
101
    """RSA-PSS signature scheme."""
102
    
103
    def can_sign(self) -> bool:
104
        """Check if private key is available for signing."""
105
    
106
    def sign(self, msg_hash) -> bytes:
107
        """Sign message hash with PSS padding."""
108
    
109
    def verify(self, msg_hash, signature: bytes) -> None:
110
        """Verify PSS signature (raises ValueError if invalid)."""
111
```
112

113
### DSA Signatures
114

115
Digital Signature Standard providing FIPS-approved signatures with support for deterministic and probabilistic variants.
116

117
```python { .api }
118
def new(key, mode, encoding='binary', randfunc=None):
119
    """
120
    Create DSA signature scheme.
121
    
122
    Parameters:
123
    - key: DSA or ECC key object
124
    - mode (str): 'fips-186-3' (probabilistic) or 'deterministic-rfc6979' (deterministic)
125
    - encoding (str): 'binary' for bytes, 'der' for ASN.1 DER encoding
126
    - randfunc (callable): Random function for probabilistic mode
127
    
128
    Returns:
129
    DSA signature scheme object
130
    """
131

132
class DssSigScheme:
133
    """Base DSA signature scheme."""
134
    
135
    def can_sign(self) -> bool:
136
        """Check if private key is available."""
137
    
138
    def sign(self, msg_hash) -> bytes:
139
        """
140
        Sign message hash.
141
        
142
        Parameters:
143
        - msg_hash: Hash object with digest() method
144
        
145
        Returns:
146
        Signature in specified encoding format
147
        """
148
    
149
    def verify(self, msg_hash, signature: bytes) -> None:
150
        """
151
        Verify signature.
152
        
153
        Parameters:
154
        - msg_hash: Hash object
155
        - signature (bytes): Signature to verify
156
        
157
        Raises:
158
        ValueError if signature is invalid
159
        """
160

161
class DeterministicDsaSigScheme(DssSigScheme):
162
    """Deterministic DSA following RFC 6979."""
163

164
class FipsDsaSigScheme(DssSigScheme):
165
    """FIPS 186-3 compliant probabilistic DSA."""
166
```
167

168
### EdDSA (Edwards-curve Digital Signature Algorithm)
169

170
Modern signature algorithm using Edwards curves (Ed25519, Ed448) providing high security and performance with deterministic signatures.
171

172
```python { .api }
173
def new(priv_key, context):
174
    """
175
    Create EdDSA signature scheme.
176
    
177
    Parameters:
178
    - priv_key: Ed25519 or Ed448 private key
179
    - context (bytes): Context string (Ed448 only, must be empty for Ed25519)
180
    
181
    Returns:
182
    EdDSA signature scheme object
183
    """
184

185
def import_public_key(encoded):
186
    """
187
    Import Ed25519/Ed448 public key.
188
    
189
    Parameters:
190
    - encoded (bytes): Key in binary, PEM, or OpenSSH format
191
    
192
    Returns:
193
    ECC key object for EdDSA curves
194
    """
195

196
def import_private_key(encoded, passphrase=None):
197
    """
198
    Import Ed25519/Ed448 private key.
199
    
200
    Parameters:
201
    - encoded (bytes): Key in binary, PEM, or PKCS#8 format
202
    - passphrase (bytes): Password for encrypted keys
203
    
204
    Returns:
205
    ECC key object for EdDSA curves
206
    """
207

208
class EdDSASigScheme:
209
    """EdDSA signature scheme for Ed25519/Ed448."""
210
    
211
    def can_sign(self) -> bool:
212
        """Check if private key is available."""
213
    
214
    def sign(self, msg_or_hash) -> bytes:
215
        """
216
        Sign message or hash.
217
        
218
        Parameters:
219
        - msg_or_hash: Raw message bytes or hash object
220
        
221
        Returns:
222
        EdDSA signature bytes (64 bytes for Ed25519, 114 bytes for Ed448)
223
        """
224
    
225
    def verify(self, msg_or_hash, signature: bytes) -> None:
226
        """
227
        Verify EdDSA signature.
228
        
229
        Parameters:
230
        - msg_or_hash: Raw message bytes or hash object
231
        - signature (bytes): Signature to verify
232
        
233
        Raises:
234
        ValueError if signature is invalid
235
        """
236
```
237

238
## Usage Examples
239

240
### RSA-PSS Signatures (Recommended)
241
```python
242
from Crypto.PublicKey import RSA
243
from Crypto.Signature import pss
244
from Crypto.Hash import SHA256
245

246
# Generate RSA key
247
key = RSA.generate(2048)
248

249
# Create message hash
250
message = b"Message to be signed"
251
hash_obj = SHA256.new(message)
252

253
# Create PSS signature scheme
254
signature_scheme = pss.new(key)
255

256
# Sign the hash
257
signature = signature_scheme.sign(hash_obj)
258

259
# Verify with public key
260
public_key = key.publickey()
261
verifier = pss.new(public_key)
262
try:
263
    verifier.verify(hash_obj, signature)
264
    print("Signature is valid")
265
except ValueError:
266
    print("Signature is invalid")
267
```
268

269
### DSA Deterministic Signatures
270
```python
271
from Crypto.PublicKey import DSA
272
from Crypto.Signature import DSS
273
from Crypto.Hash import SHA256
274

275
# Generate DSA key
276
key = DSA.generate(2048)
277

278
# Create deterministic signature scheme
279
signer = DSS.new(key, 'deterministic-rfc6979', 'der')
280

281
# Sign message hash
282
message = b"Message for DSA signature"
283
hash_obj = SHA256.new(message)
284
signature = signer.sign(hash_obj)
285

286
# Verify signature
287
verifier = DSS.new(key.publickey(), 'deterministic-rfc6979', 'der')
288
try:
289
    verifier.verify(hash_obj, signature)
290
    print("DSA signature verified")
291
except ValueError:
292
    print("DSA signature invalid")
293
```
294

295
### EdDSA with Ed25519
296
```python
297
from Crypto.PublicKey import ECC
298
from Crypto.Signature import eddsa
299

300
# Generate Ed25519 key pair
301
key = ECC.generate(curve='Ed25519')
302

303
# Create EdDSA signature scheme  
304
signer = eddsa.new(key, b'')  # Empty context for Ed25519
305

306
# Sign raw message (EdDSA handles hashing internally)
307
message = b"Message for Ed25519 signature"
308
signature = signer.sign(message)
309

310
# Verify with public key
311
public_key = key.public_key()
312
verifier = eddsa.new(public_key, b'')
313
try:
314
    verifier.verify(message, signature)
315
    print("Ed25519 signature verified")
316
except ValueError:
317
    print("Ed25519 signature invalid")
318
```
319

320
### ECC with DSS (ECDSA)
321
```python
322
from Crypto.PublicKey import ECC
323
from Crypto.Signature import DSS
324
from Crypto.Hash import SHA256
325

326
# Generate P-256 ECC key
327
key = ECC.generate(curve='P-256')
328

329
# Create ECDSA signature scheme
330
signer = DSS.new(key, 'fips-186-3')
331

332
# Sign hash
333
message = b"Message for ECDSA"
334
hash_obj = SHA256.new(message)
335
signature = signer.sign(hash_obj)
336

337
# Verify signature
338
verifier = DSS.new(key.publickey(), 'fips-186-3')
339
verifier.verify(hash_obj, signature)
340
```
341

342
## Signature Scheme Comparison
343

344
### RSA PKCS#1 v1.5
345
- **Security**: Adequate for most applications, but PSS preferred for new designs
346
- **Deterministic**: Yes (same message+key = same signature)
347
- **Hash Independence**: Requires specific hash algorithm encoding
348
- **Standards**: Widely supported, PKCS#1, RFC 3447
349

350
### RSA-PSS  
351
- **Security**: Provably secure with tight security reduction
352
- **Deterministic**: No (randomized salt provides probabilistic signatures)
353
- **Hash Independence**: More flexible hash algorithm support
354
- **Standards**: PKCS#1, RFC 3447, preferred for new applications
355

356
### DSS/ECDSA
357
- **Security**: Based on discrete logarithm problem hardness
358
- **Deterministic**: Optional (RFC 6979 deterministic variant available)
359
- **Hash Independence**: Works with any hash algorithm
360
- **Standards**: FIPS 186-4, RFC 6979
361

362
### EdDSA
363
- **Security**: Based on elliptic curve discrete logarithm problem
364
- **Deterministic**: Yes (deterministic by design)
365
- **Hash Independence**: Built-in hash function (SHA-512 for Ed25519)
366
- **Standards**: RFC 8032, modern and efficient
367

368
## Common Signature Interface
369

370
```python { .api }
371
class SignatureSchemeInterface:
372
    """Common interface for all signature schemes."""
373
    
374
    def can_sign(self) -> bool:
375
        """Check if private key is available for signing."""
376
    
377
    def sign(self, msg_hash) -> bytes:
378
        """Sign message hash and return signature."""
379
    
380
    def verify(self, msg_hash, signature: bytes) -> None:
381
        """Verify signature, raise ValueError if invalid."""
382
```
383

384
## Error Handling
385

386
- `ValueError`: Invalid signature, key mismatch, or parameter errors
387
- `TypeError`: Incorrect parameter types (hash object vs bytes)
388
- `AttributeError`: Missing required methods on hash objects
389
- Algorithm-specific exceptions for unsupported operations or parameters
390

391
## Security Best Practices
392

393
1. **Use PSS for new RSA applications** instead of PKCS#1 v1.5
394
2. **Prefer EdDSA (Ed25519)** for new applications requiring high performance
395
3. **Use deterministic signatures** when signature reproducibility is needed
396
4. **Hash messages before signing** (except EdDSA which handles this internally)
397
5. **Verify signatures in constant time** to prevent timing attacks
398
6. **Use appropriate key sizes** (2048+ bit RSA, P-256+ ECC curves)