0
# Symmetric Encryption
1

2
Comprehensive symmetric encryption capabilities including block ciphers and stream ciphers with support for multiple modes of operation. PyCryptodome provides modern algorithms like AES and ChaCha20 alongside legacy algorithms for compatibility.
3

4
## Capabilities
5

6
### AES (Advanced Encryption Standard)
7

8
The most widely used symmetric encryption algorithm, supporting 128, 192, and 256-bit keys with multiple modes of operation including authenticated encryption modes.
9

10
```python { .api }
11
def new(key, mode, *args, **kwargs):
12
    """
13
    Create a new AES cipher object.
14
    
15
    Parameters:
16
    - key (bytes): The secret key (16, 24, or 32 bytes for AES-128/192/256)
17
    - mode (int): Cipher mode (MODE_ECB, MODE_CBC, MODE_CFB, MODE_OFB, MODE_CTR, 
18
                  MODE_GCM, MODE_CCM, MODE_EAX, MODE_SIV, MODE_OCB, MODE_KW, MODE_KWP)
19
    - iv (bytes): Initialization vector for modes that require it
20
    - nonce (bytes): Number used once for authenticated modes
21
    
22
    Returns:
23
    AES cipher object with encrypt/decrypt methods
24
    """
25

26
# Mode constants
27
MODE_ECB: int  # Electronic Codebook
28
MODE_CBC: int  # Cipher Block Chaining  
29
MODE_CFB: int  # Cipher Feedback
30
MODE_OFB: int  # Output Feedback
31
MODE_CTR: int  # Counter Mode
32
MODE_GCM: int  # Galois/Counter Mode (authenticated)
33
MODE_CCM: int  # Counter with CBC-MAC (authenticated)  
34
MODE_EAX: int  # EAX mode (authenticated)
35
MODE_SIV: int  # Synthetic IV (authenticated)
36
MODE_OCB: int  # Offset Codebook (authenticated)
37
MODE_KW: int   # Key Wrap
38
MODE_KWP: int  # Key Wrap with Padding
39

40
block_size: int  # AES block size (16 bytes)
41
key_size: tuple  # Valid key sizes (16, 24, 32)
42
```
43

44
Usage example:
45
```python
46
from Crypto.Cipher import AES
47
from Crypto.Random import get_random_bytes
48
from Crypto.Util.Padding import pad, unpad
49

50
# Generate a random 256-bit key
51
key = get_random_bytes(32)
52

53
# Encrypt with CBC mode
54
cipher = AES.new(key, AES.MODE_CBC)
55
plaintext = b"This is a secret message"
56
padded = pad(plaintext, AES.block_size)
57
ciphertext = cipher.encrypt(padded)
58

59
# Decrypt
60
decipher = AES.new(key, AES.MODE_CBC, cipher.iv)
61
decrypted_padded = decipher.decrypt(ciphertext)
62
decrypted = unpad(decrypted_padded, AES.block_size)
63

64
# Authenticated encryption with GCM
65
cipher = AES.new(key, AES.MODE_GCM)
66
ciphertext, tag = cipher.encrypt_and_digest(plaintext)
67
```
68

69
### ChaCha20
70

71
Modern stream cipher providing high performance and security, designed as an alternative to AES for applications requiring fast software implementation.
72

73
```python { .api }
74
def new(**kwargs):
75
    """
76
    Create a new ChaCha20 cipher object.
77
    
78
    Parameters:
79
    - key (bytes): 32-byte secret key
80
    - nonce (bytes): 8 or 12-byte nonce (default: random)
81
    
82
    Returns:
83
    ChaCha20 cipher object
84
    """
85

86
class ChaCha20Cipher:
87
    def encrypt(self, plaintext: bytes) -> bytes: ...
88
    def decrypt(self, ciphertext: bytes) -> bytes: ...
89
    
90
    nonce: bytes  # The nonce used
91
    key_size: int  # Key size (32 bytes)
92
```
93

94
### ChaCha20-Poly1305
95

96
Authenticated encryption combining ChaCha20 stream cipher with Poly1305 message authentication code, providing both confidentiality and authenticity.
97

98
```python { .api }
99
def new(**kwargs):
100
    """
101
    Create a new ChaCha20-Poly1305 AEAD cipher.
102
    
103
    Parameters:
104
    - key (bytes): 32-byte secret key
105
    - nonce (bytes): 8 or 12-byte nonce
106
    
107
    Returns:
108
    ChaCha20-Poly1305 cipher object with encrypt_and_digest/decrypt_and_verify
109
    """
110
```
111

112
### Salsa20
113

114
High-speed stream cipher designed for software implementations, predecessor to ChaCha20 with similar performance characteristics.
115

116
```python { .api }
117
def new(key, nonce=None):
118
    """
119
    Create a new Salsa20 cipher object.
120
    
121
    Parameters:
122
    - key (bytes): 16 or 32-byte secret key
123
    - nonce (bytes): 8-byte nonce (default: random)
124
    
125
    Returns:
126
    Salsa20 cipher object
127
    """
128
```
129

130
### Block Ciphers
131

132
Additional block cipher algorithms for legacy compatibility and specialized use cases.
133

134
```python { .api }
135
# DES3 (Triple DES)
136
def DES3.new(key, mode, *args, **kwargs):
137
    """
138
    Create Triple DES cipher.
139
    
140
    Parameters:
141
    - key (bytes): 16 or 24-byte key (2DES or 3DES)
142
    - mode (int): Cipher mode
143
    """
144

145
def DES3.adjust_key_parity(key_in):
146
    """Adjust DES key parity bits."""
147

148
# Blowfish  
149
def Blowfish.new(key, mode, *args, **kwargs):
150
    """
151
    Create Blowfish cipher.
152
    
153
    Parameters:
154
    - key (bytes): Variable length key (4-56 bytes)
155
    - mode (int): Cipher mode
156
    """
157

158
# CAST-128
159
def CAST.new(key, mode, *args, **kwargs):
160
    """Create CAST cipher with variable key length."""
161

162
# ARC2 (RC2)
163
def ARC2.new(key, mode, *args, **kwargs):
164
    """Create ARC2 cipher with effective key length control."""
165

166
# DES (legacy)
167
def DES.new(key, mode, *args, **kwargs):
168
    """Create DES cipher (64-bit key, 56-bit effective)."""
169
```
170

171
### Stream Ciphers
172

173
```python { .api }
174
# ARC4 (RC4) - legacy stream cipher
175
def ARC4.new(key, *args, **kwargs):
176
    """
177
    Create ARC4 stream cipher.
178
    
179
    Parameters:
180
    - key (bytes): Variable length key
181
    
182
    Returns:
183
    ARC4 cipher object
184
    """
185
```
186

187
### RSA Encryption
188

189
Public key encryption using RSA with OAEP or PKCS#1 v1.5 padding schemes.
190

191
```python { .api }
192
# RSA-OAEP (recommended)
193
def PKCS1_OAEP.new(key, hashAlgo=None, mgfunc=None, label=b'', randfunc=None):
194
    """
195
    Create RSA-OAEP cipher for public key encryption.
196
    
197
    Parameters:
198
    - key: RSA key object (public or private)
199
    - hashAlgo: Hash algorithm for OAEP (default: SHA-1)
200
    - mgfunc: Mask generation function
201
    - label (bytes): Optional label
202
    
203
    Returns: 
204
    PKCS1OAEP_Cipher with encrypt/decrypt methods
205
    """
206

207
# RSA PKCS#1 v1.5 (legacy)
208
def PKCS1_v1_5.new(key, randfunc=None):
209
    """Create RSA PKCS#1 v1.5 cipher."""
210
```
211

212
## Cipher Mode Patterns
213

214
All block ciphers follow consistent patterns for mode usage:
215

216
**Basic Modes (ECB, CBC, CFB, OFB):**
217
```python
218
cipher = Algorithm.new(key, mode, iv)  # IV required except ECB
219
ciphertext = cipher.encrypt(plaintext)
220
```
221

222
**Counter Mode (CTR):**
223
```python  
224
cipher = Algorithm.new(key, Algorithm.MODE_CTR, nonce=nonce)
225
ciphertext = cipher.encrypt(plaintext)
226
```
227

228
**Authenticated Modes (GCM, CCM, EAX, OCB, SIV):**
229
```python
230
cipher = Algorithm.new(key, mode)
231
cipher.update(associated_data)  # Optional additional authenticated data
232
ciphertext, tag = cipher.encrypt_and_digest(plaintext)
233

234
# Decryption with verification
235
cipher = Algorithm.new(key, mode, nonce=nonce)
236
cipher.update(associated_data)
237
plaintext = cipher.decrypt_and_verify(ciphertext, tag)
238
```
239

240
## Error Handling
241

242
Common exceptions that may be raised:
243

244
- `ValueError`: Invalid key size, mode, or parameters
245
- `TypeError`: Incorrect parameter types  
246
- `Crypto.Cipher.ValueError`: Authentication failure in AEAD modes