0
# Asymmetric Cryptography
1

2
Comprehensive asymmetric cryptographic operations including key generation, loading, signing, verification, encryption, and decryption using RSA, DSA, and ECDSA algorithms. All operations use OS-native crypto libraries for security and performance.
3

4
```python
5
from oscrypto import asymmetric
6
from oscrypto.errors import SignatureError, AsymmetricKeyError
7
```
8

9
## Capabilities
10

11
### Key Generation
12

13
Generate new asymmetric key pairs for RSA, DSA, and ECDSA algorithms with configurable parameters.
14

15
```python { .api }
16
def generate_pair(algorithm: str, bit_size: int = None, curve: str = None) -> Tuple[PublicKey, PrivateKey]:
17
    """
18
    Generate an asymmetric key pair.
19

20
    Parameters:
21
    - algorithm: str - 'rsa', 'dsa', or 'ec'
22
    - bit_size: int - Key size in bits (RSA: 1024-4096, DSA: 1024-3072)
23
    - curve: str - Curve name for EC keys ('secp256r1', 'secp384r1', 'secp521r1')
24

25
    Returns:
26
    Tuple of (PublicKey, PrivateKey) objects
27
    """
28

29
def generate_dh_parameters(bit_size: int) -> bytes:
30
    """
31
    Generate Diffie-Hellman parameters.
32

33
    Parameters:
34
    - bit_size: int - Parameter size in bits (1024-4096)
35

36
    Returns:
37
    DER-encoded DH parameters
38
    """
39
```
40

41
### Key and Certificate Loading
42

43
Load keys and certificates from various sources and formats including DER, PEM, PKCS#8, and PKCS#12.
44

45
```python { .api }
46
def load_private_key(source: Union[str, bytes], password: bytes = None) -> PrivateKey:
47
    """
48
    Load a private key from various sources.
49

50
    Parameters:
51
    - source: Union[str, bytes] - File path, DER bytes, or PEM string
52
    - password: bytes - Password for encrypted keys
53

54
    Returns:
55
    PrivateKey object
56
    """
57

58
def load_public_key(source: Union[str, bytes]) -> PublicKey:
59
    """
60
    Load a public key from various sources.
61

62
    Parameters:
63
    - source: Union[str, bytes] - File path, DER bytes, or PEM string
64

65
    Returns:
66
    PublicKey object
67
    """
68

69
def load_certificate(source: Union[str, bytes]) -> Certificate:
70
    """
71
    Load an X.509 certificate from various sources.
72

73
    Parameters:
74
    - source: Union[str, bytes] - File path, DER bytes, or PEM string
75

76
    Returns:
77
    Certificate object
78
    """
79

80
def load_pkcs12(source: Union[str, bytes], password: bytes = None) -> Tuple[Certificate, PrivateKey, List[Certificate]]:
81
    """
82
    Load a PKCS#12 bundle containing certificate and private key.
83

84
    Parameters:
85
    - source: Union[str, bytes] - File path or PKCS#12 bytes
86
    - password: bytes - Password for the PKCS#12 bundle
87

88
    Returns:
89
    Tuple of (Certificate, PrivateKey, [intermediate_certificates])
90
    """
91
```
92

93
### Key and Certificate Export
94

95
Export keys and certificates to various formats for storage or transmission.
96

97
```python { .api }
98
def dump_private_key(private_key: PrivateKey, passphrase: bytes = None, target_ms: int = 200) -> bytes:
99
    """
100
    Export a private key to PKCS#8 DER format.
101

102
    Parameters:
103
    - private_key: PrivateKey - Key to export
104
    - passphrase: bytes - Optional passphrase for encryption
105
    - target_ms: int - Target milliseconds for PBKDF2 (if encrypting)
106

107
    Returns:
108
    DER-encoded PKCS#8 private key
109
    """
110

111
def dump_public_key(public_key: PublicKey) -> bytes:
112
    """
113
    Export a public key to DER format.
114

115
    Parameters:
116
    - public_key: PublicKey - Key to export
117

118
    Returns:
119
    DER-encoded public key
120
    """
121

122
def dump_certificate(certificate: Certificate) -> bytes:
123
    """
124
    Export a certificate to DER format.
125

126
    Parameters:
127
    - certificate: Certificate - Certificate to export
128

129
    Returns:
130
    DER-encoded X.509 certificate
131
    """
132

133
def dump_openssl_private_key(private_key: PrivateKey, passphrase: bytes = None) -> bytes:
134
    """
135
    Export a private key in OpenSSL format.
136

137
    Parameters:
138
    - private_key: PrivateKey - Key to export
139
    - passphrase: bytes - Optional passphrase for encryption
140

141
    Returns:
142
    OpenSSL-format private key bytes
143
    """
144

145
def dump_dh_parameters(dh_parameters: bytes) -> bytes:
146
    """
147
    Export DH parameters to DER format.
148

149
    Parameters:
150
    - dh_parameters: bytes - DH parameters to export
151

152
    Returns:
153
    DER-encoded DH parameters
154
    """
155
```
156

157
### RSA Operations
158

159
RSA encryption, decryption, signing, and verification with PKCS#1 v1.5 and PSS padding.
160

161
```python { .api }
162
def rsa_pkcs1v15_encrypt(certificate_or_public_key: Union[Certificate, PublicKey], data: bytes) -> bytes:
163
    """
164
    Encrypt data using RSA PKCS#1 v1.5 padding.
165

166
    Parameters:
167
    - certificate_or_public_key: Union[Certificate, PublicKey] - RSA key for encryption
168
    - data: bytes - Data to encrypt (max length depends on key size)
169

170
    Returns:
171
    Encrypted data bytes
172
    """
173

174
def rsa_pkcs1v15_decrypt(private_key: PrivateKey, ciphertext: bytes) -> bytes:
175
    """
176
    Decrypt data using RSA PKCS#1 v1.5 padding.
177

178
    Parameters:
179
    - private_key: PrivateKey - RSA private key for decryption
180
    - ciphertext: bytes - Encrypted data to decrypt
181

182
    Returns:
183
    Decrypted plaintext bytes
184
    """
185

186
def rsa_oaep_encrypt(certificate_or_public_key: Union[Certificate, PublicKey], data: bytes, 
187
                    hash_algorithm: str = 'sha1', mgf_hash_algorithm: str = 'sha1', label: bytes = b'') -> bytes:
188
    """
189
    Encrypt data using RSA OAEP padding.
190

191
    Parameters:
192
    - certificate_or_public_key: Union[Certificate, PublicKey] - RSA key for encryption
193
    - data: bytes - Data to encrypt
194
    - hash_algorithm: str - Hash algorithm ('sha1', 'sha224', 'sha256', 'sha384', 'sha512')
195
    - mgf_hash_algorithm: str - MGF hash algorithm
196
    - label: bytes - Optional label
197

198
    Returns:
199
    Encrypted data bytes
200
    """
201

202
def rsa_oaep_decrypt(private_key: PrivateKey, ciphertext: bytes,
203
                    hash_algorithm: str = 'sha1', mgf_hash_algorithm: str = 'sha1', label: bytes = b'') -> bytes:
204
    """
205
    Decrypt data using RSA OAEP padding.
206

207
    Parameters:
208
    - private_key: PrivateKey - RSA private key for decryption
209
    - ciphertext: bytes - Encrypted data to decrypt
210
    - hash_algorithm: str - Hash algorithm used during encryption
211
    - mgf_hash_algorithm: str - MGF hash algorithm used during encryption
212
    - label: bytes - Label used during encryption
213

214
    Returns:
215
    Decrypted plaintext bytes
216
    """
217

218
def rsa_pkcs1v15_sign(private_key: PrivateKey, data: bytes, hash_algorithm: str) -> bytes:
219
    """
220
    Sign data using RSA PKCS#1 v1.5 padding.
221

222
    Parameters:
223
    - private_key: PrivateKey - RSA private key for signing
224
    - data: bytes - Data to sign
225
    - hash_algorithm: str - Hash algorithm ('sha1', 'sha224', 'sha256', 'sha384', 'sha512')
226

227
    Returns:
228
    Signature bytes
229
    """
230

231
def rsa_pkcs1v15_verify(certificate_or_public_key: Union[Certificate, PublicKey], signature: bytes, 
232
                       data: bytes, hash_algorithm: str) -> None:
233
    """
234
    Verify RSA PKCS#1 v1.5 signature.
235

236
    Parameters:
237
    - certificate_or_public_key: Union[Certificate, PublicKey] - RSA key for verification
238
    - signature: bytes - Signature to verify
239
    - data: bytes - Original data that was signed
240
    - hash_algorithm: str - Hash algorithm used during signing
241

242
    Raises:
243
    SignatureError if verification fails
244
    """
245

246
def rsa_pss_sign(private_key: PrivateKey, data: bytes, hash_algorithm: str) -> bytes:
247
    """
248
    Sign data using RSA PSS padding.
249

250
    Parameters:
251
    - private_key: PrivateKey - RSA private key for signing
252
    - data: bytes - Data to sign
253
    - hash_algorithm: str - Hash algorithm ('sha1', 'sha224', 'sha256', 'sha384', 'sha512')
254

255
    Returns:
256
    Signature bytes
257
    """
258

259
def rsa_pss_verify(certificate_or_public_key: Union[Certificate, PublicKey], signature: bytes,
260
                  data: bytes, hash_algorithm: str) -> None:
261
    """
262
    Verify RSA PSS signature.
263

264
    Parameters:
265
    - certificate_or_public_key: Union[Certificate, PublicKey] - RSA key for verification
266
    - signature: bytes - Signature to verify
267
    - data: bytes - Original data that was signed
268
    - hash_algorithm: str - Hash algorithm used during signing
269

270
    Raises:
271
    SignatureError if verification fails
272
    """
273
```
274

275
### DSA Operations
276

277
DSA signing and verification operations.
278

279
```python { .api }
280
def dsa_sign(private_key: PrivateKey, data: bytes, hash_algorithm: str) -> bytes:
281
    """
282
    Sign data using DSA.
283

284
    Parameters:
285
    - private_key: PrivateKey - DSA private key for signing
286
    - data: bytes - Data to sign
287
    - hash_algorithm: str - Hash algorithm ('sha1', 'sha224', 'sha256')
288

289
    Returns:
290
    Signature bytes
291
    """
292

293
def dsa_verify(certificate_or_public_key: Union[Certificate, PublicKey], signature: bytes,
294
              data: bytes, hash_algorithm: str) -> None:
295
    """
296
    Verify DSA signature.
297

298
    Parameters:
299
    - certificate_or_public_key: Union[Certificate, PublicKey] - DSA key for verification
300
    - signature: bytes - Signature to verify
301
    - data: bytes - Original data that was signed
302
    - hash_algorithm: str - Hash algorithm used during signing
303

304
    Raises:
305
    SignatureError if verification fails
306
    """
307
```
308

309
### ECDSA Operations
310

311
ECDSA signing and verification operations for elliptic curve cryptography.
312

313
```python { .api }
314
def ecdsa_sign(private_key: PrivateKey, data: bytes, hash_algorithm: str) -> bytes:
315
    """
316
    Sign data using ECDSA.
317

318
    Parameters:
319
    - private_key: PrivateKey - ECDSA private key for signing
320
    - data: bytes - Data to sign
321
    - hash_algorithm: str - Hash algorithm ('sha1', 'sha224', 'sha256', 'sha384', 'sha512')
322

323
    Returns:
324
    Signature bytes
325
    """
326

327
def ecdsa_verify(certificate_or_public_key: Union[Certificate, PublicKey], signature: bytes,
328
                data: bytes, hash_algorithm: str) -> None:
329
    """
330
    Verify ECDSA signature.
331

332
    Parameters:
333
    - certificate_or_public_key: Union[Certificate, PublicKey] - ECDSA key for verification
334
    - signature: bytes - Signature to verify
335
    - data: bytes - Original data that was signed
336
    - hash_algorithm: str - Hash algorithm used during signing
337

338
    Raises:
339
    SignatureError if verification fails
340
    """
341
```
342

343
## Usage Examples
344

345
### Generating and Using RSA Keys
346

347
```python
348
from oscrypto import asymmetric
349

350
# Generate RSA key pair
351
public_key, private_key = asymmetric.generate_pair('rsa', bit_size=2048)
352

353
# Encrypt data
354
plaintext = b"Secret message"
355
ciphertext = asymmetric.rsa_pkcs1v15_encrypt(public_key, plaintext)
356

357
# Decrypt data
358
decrypted = asymmetric.rsa_pkcs1v15_decrypt(private_key, ciphertext)
359

360
# Sign data
361
signature = asymmetric.rsa_pkcs1v15_sign(private_key, plaintext, 'sha256')
362

363
# Verify signature
364
try:
365
    asymmetric.rsa_pkcs1v15_verify(public_key, signature, plaintext, 'sha256')
366
    print("Signature valid")
367
except asymmetric.SignatureError:
368
    print("Signature invalid")
369
```
370

371
### Loading Keys from Files
372

373
```python
374
from oscrypto import asymmetric
375

376
# Load private key from PEM file
377
with open('private_key.pem', 'rb') as f:
378
    private_key = asymmetric.load_private_key(f.read())
379

380
# Load certificate from PEM file  
381
with open('certificate.pem', 'rb') as f:
382
    certificate = asymmetric.load_certificate(f.read())
383

384
# Load PKCS#12 bundle
385
with open('bundle.p12', 'rb') as f:
386
    cert, key, intermediates = asymmetric.load_pkcs12(f.read(), b'password')
387
```