0
# PyCryptodome
1

2
PyCryptodome is a comprehensive self-contained Python library providing low-level cryptographic primitives. It offers a complete suite of symmetric ciphers, cryptographic hash functions, public key cryptography algorithms, digital signature schemes, key derivation functions, and secure random number generation.
3

4
## Package Information
5

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

10
## Core Imports
11

12
```python
13
import Crypto
14
```
15

16
Common module imports:
17

18
```python
19
from Crypto.Cipher import AES, ChaCha20, DES3
20
from Crypto.Hash import SHA256, HMAC
21
from Crypto.PublicKey import RSA, ECC
22
from Crypto.Signature import pkcs1_15, pss
23
from Crypto.Random import get_random_bytes
24
from Crypto.Util.Padding import pad, unpad
25
```
26

27
## Basic Usage
28

29
```python
30
from Crypto.Cipher import AES
31
from Crypto.Hash import SHA256
32
from Crypto.PublicKey import RSA
33
from Crypto.Random import get_random_bytes
34
from Crypto.Util.Padding import pad, unpad
35

36
# Symmetric encryption with AES
37
key = get_random_bytes(16)  # 128-bit key
38
cipher = AES.new(key, AES.MODE_CBC)
39
plaintext = b"Secret message that needs to be encrypted!"
40
padded_data = pad(plaintext, AES.block_size)
41
ciphertext = cipher.encrypt(padded_data)
42

43
# Decryption
44
decipher = AES.new(key, AES.MODE_CBC, cipher.iv)
45
decrypted_padded = decipher.decrypt(ciphertext)
46
decrypted = unpad(decrypted_padded, AES.block_size)
47

48
# Hash computation
49
hash_obj = SHA256.new()
50
hash_obj.update(b"Data to hash")
51
hash_digest = hash_obj.digest()
52

53
# RSA key generation and usage
54
key = RSA.generate(2048)
55
public_key = key.publickey()
56
```
57

58
## Architecture
59

60
PyCryptodome is organized into functional modules that provide distinct cryptographic capabilities:
61

62
- **Cipher Module**: Symmetric and asymmetric encryption algorithms with multiple modes of operation
63
- **Hash Module**: Cryptographic hash functions, message authentication codes, and extendable output functions
64
- **PublicKey Module**: Public key cryptography including RSA, DSA, ECC, and ElGamal key management
65
- **Signature Module**: Digital signature schemes for RSA, DSA, and elliptic curve algorithms
66
- **Protocol Module**: High-level cryptographic protocols including key derivation and secret sharing
67
- **Util Module**: Utility functions for padding, encoding, number theory, and data manipulation
68
- **IO Module**: Input/output utilities for PEM and PKCS#8 key formats
69
- **Math Module**: Mathematical primitives for big integers and primality testing
70
- **Random Module**: Cryptographically secure random number generation
71

72
This modular design enables developers to import only the required functionality while maintaining compatibility with the broader Python cryptographic ecosystem.
73

74
## Capabilities
75

76
### Symmetric Encryption
77

78
Comprehensive collection of symmetric encryption algorithms including block ciphers (AES, DES, Blowfish) and stream ciphers (ChaCha20, Salsa20, ARC4) with support for multiple cipher modes.
79

80
```python { .api }
81
# AES cipher factory
82
def AES.new(key, mode, *args, **kwargs): ...
83

84
# ChaCha20 cipher factory  
85
def ChaCha20.new(**kwargs): ...
86

87
# Cipher mode constants
88
AES.MODE_ECB, AES.MODE_CBC, AES.MODE_CFB, AES.MODE_OFB, AES.MODE_CTR,
89
AES.MODE_GCM, AES.MODE_CCM, AES.MODE_EAX, AES.MODE_SIV, AES.MODE_OCB
90
```
91

92
[Symmetric Encryption](./symmetric-encryption.md)
93

94
### Cryptographic Hashing
95

96
Complete suite of cryptographic hash functions including SHA family, SHA-3, MD family, BLAKE2, and specialized functions like SHAKE, cSHAKE, KMAC, and TurboSHAKE.
97

98
```python { .api }
99
# Hash function factories
100
def SHA256.new(data=None): ...
101
def SHA3_256.new(data=None, update_after_digest=False): ...
102
def BLAKE2b.new(**kwargs): ...
103

104
# Message authentication codes
105
def HMAC.new(key, msg=b"", digestmod=None): ...
106
def CMAC.new(key, msg=None, ciphermod=None, **kwargs): ...
107
```
108

109
[Cryptographic Hashing](./cryptographic-hashing.md)
110

111
### Public Key Cryptography
112

113
Public key algorithms for key generation, encryption, and key exchange including RSA, DSA, ECC, and ElGamal with comprehensive key management capabilities.
114

115
```python { .api }
116
# Key generation functions
117
def RSA.generate(bits, randfunc=None, e=65537): ...
118
def ECC.generate(**kwargs): ...
119
def DSA.generate(bits, randfunc=None, domain=None): ...
120

121
# Key import/export
122
def RSA.import_key(extern_key, passphrase=None): ...
123
```
124

125
[Public Key Cryptography](./public-key-cryptography.md)
126

127
### Digital Signatures
128

129
Digital signature schemes for RSA (PKCS#1 v1.5, PSS), DSA variants, and EdDSA with support for deterministic and probabilistic signing.
130

131
```python { .api }
132
# RSA signature schemes
133
def pkcs1_15.new(rsa_key): ...
134
def pss.new(rsa_key, **kwargs): ...
135

136
# DSA signature scheme
137
def DSS.new(key, mode, encoding='binary', randfunc=None): ...
138
```
139

140
[Digital Signatures](./digital-signatures.md)
141

142
### Cryptographic Protocols
143

144
High-level cryptographic protocols including key derivation functions (PBKDF2, scrypt, HKDF), secret sharing, and key exchange protocols.
145

146
```python { .api }
147
# Key derivation functions
148
def scrypt(password, salt, key_len, N, r, p, num_keys=1): ...
149
def PBKDF2(password, salt, dkLen=16, count=1000, prf=None, **kwargs): ...
150

151
# Secret sharing
152
class Shamir:
153
    @staticmethod
154
    def split(k, n, secret, ssss=False): ...
155
    @staticmethod
156
    def combine(shares, ssss=False): ...
157
```
158

159
[Cryptographic Protocols](./cryptographic-protocols.md)
160

161
### Utility Functions
162

163
Essential utilities for padding, encoding, number theory operations, and data manipulation that support the core cryptographic functions.
164

165
```python { .api }
166
# Padding operations
167
def pad(data_to_pad, block_size, style='pkcs7'): ...
168
def unpad(padded_data, block_size, style='pkcs7'): ...
169

170
# Random number generation
171
def get_random_bytes(n): ...
172

173
# Number theory
174
def isPrime(N, false_positive_prob=1e-6, randfunc=None): ...
175
def getPrime(N, randfunc=None): ...
176
```
177

178
[Utility Functions](./utility-functions.md)
179

180
### Input/Output Operations
181

182
Utilities for encoding and decoding cryptographic objects in standard formats including PEM and PKCS#8 for key serialization.
183

184
```python { .api }
185
# PEM encoding/decoding
186
def PEM.encode(data, marker, passphrase=None, randfunc=None): ...
187
def PEM.decode(pem_data, passphrase=None): ...
188

189
# PKCS#8 key wrapping
190
def PKCS8.wrap(private_key, key_oid, passphrase=None, **kwargs): ...
191
def PKCS8.unwrap(p8_private_key, passphrase=None): ...
192
```
193

194
[Input/Output Operations](./input-output-operations.md)
195

196
### Mathematical Primitives
197

198
Mathematical operations for cryptographic computations including big integer arithmetic and primality testing.
199

200
```python { .api }
201
# Big integer class
202
class Integer:
203
    def __init__(self, value): ...
204
    # Arithmetic and modular operations available
205

206
# Primality testing
207
def miller_rabin_test(candidate, iterations, randfunc=None): ...
208
def test_probable_prime(candidate, randfunc=None): ...
209
```
210

211
[Mathematical Primitives](./mathematical-primitives.md)
212

213
## Types
214

215
```python { .api }
216
# Common cipher interface
217
class CipherObject:
218
    def encrypt(self, plaintext: bytes) -> bytes: ...
219
    def decrypt(self, ciphertext: bytes) -> bytes: ...
220

221
# Hash object interface  
222
class HashObject:
223
    def update(self, data: bytes) -> None: ...
224
    def digest(self) -> bytes: ...
225
    def hexdigest(self) -> str: ...
226
    def copy(self): ...
227

228
# Key object interface
229
class KeyObject:
230
    def has_private(self) -> bool: ...
231
    def public_key(self): ...
232
    def export_key(self, format: str = 'PEM', **kwargs) -> bytes: ...
233
```