0
# Symmetric Cryptography
1

2
Symmetric encryption and decryption operations using AES, DES, 3DES, RC2, and RC4 algorithms. All operations use OS-native crypto libraries for optimal performance and security updates through the operating system.
3

4
```python
5
from typing import Tuple
6
```
7

8
## Capabilities
9

10
### AES Encryption
11

12
Advanced Encryption Standard (AES) operations with CBC mode and various padding schemes.
13

14
```python { .api }
15
def aes_cbc_pkcs7_encrypt(key: bytes, data: bytes, iv: bytes = None) -> Tuple[bytes, bytes]:
16
    """
17
    Encrypt data using AES-CBC with PKCS#7 padding.
18

19
    Parameters:
20
    - key: bytes - AES key (16, 24, or 32 bytes for AES-128/192/256)
21
    - data: bytes - Data to encrypt
22
    - iv: bytes - 16-byte initialization vector (None to generate random)
23

24
    Returns:
25
    Tuple of (iv, ciphertext) bytes
26
    """
27

28
def aes_cbc_pkcs7_decrypt(key: bytes, data: bytes, iv: bytes) -> bytes:
29
    """
30
    Decrypt AES-CBC data with PKCS#7 padding.
31

32
    Parameters:
33
    - key: bytes - AES key (16, 24, or 32 bytes)
34
    - data: bytes - Encrypted ciphertext
35
    - iv: bytes - 16-byte initialization vector
36

37
    Returns:
38
    Decrypted plaintext data
39
    """
40

41
def aes_cbc_no_padding_encrypt(key: bytes, data: bytes, iv: bytes = None) -> Tuple[bytes, bytes]:
42
    """
43
    Encrypt data using AES-CBC without padding.
44

45
    Parameters:
46
    - key: bytes - AES key (16, 24, or 32 bytes)
47
    - data: bytes - Data to encrypt (must be multiple of 16 bytes)
48
    - iv: bytes - 16-byte initialization vector (None to generate random)
49

50
    Returns:
51
    Tuple of (iv, ciphertext) bytes
52
    """
53

54
def aes_cbc_no_padding_decrypt(key: bytes, data: bytes, iv: bytes) -> bytes:
55
    """
56
    Decrypt AES-CBC data without padding.
57

58
    Parameters:
59
    - key: bytes - AES key (16, 24, or 32 bytes)
60
    - data: bytes - Ciphertext to decrypt
61
    - iv: bytes - 16-byte initialization vector
62

63
    Returns:
64
    Decrypted plaintext data
65
    """
66
```
67

68
### DES Encryption
69

70
Data Encryption Standard (DES) operations with CBC mode and PKCS#5 padding.
71

72
```python { .api }
73
def des_cbc_pkcs5_encrypt(key: bytes, data: bytes, iv: bytes = None) -> Tuple[bytes, bytes]:
74
    """
75
    Encrypt data using DES-CBC with PKCS#5 padding.
76

77
    Parameters:
78
    - key: bytes - DES key (8 bytes)
79
    - data: bytes - Data to encrypt
80
    - iv: bytes - 8-byte initialization vector (None to generate random)
81

82
    Returns:
83
    Tuple of (iv, ciphertext) bytes
84
    """
85

86
def des_cbc_pkcs5_decrypt(key: bytes, data: bytes, iv: bytes) -> bytes:
87
    """
88
    Decrypt DES-CBC data with PKCS#5 padding.
89

90
    Parameters:
91
    - key: bytes - DES key (8 bytes)
92
    - data: bytes - Ciphertext to decrypt
93
    - iv: bytes - 8-byte initialization vector
94

95
    Returns:
96
    Decrypted plaintext data
97
    """
98
```
99

100
### Triple DES Encryption
101

102
Triple DES (3DES) operations with CBC mode and PKCS#5 padding.
103

104
```python { .api }
105
def tripledes_cbc_pkcs5_encrypt(key: bytes, data: bytes, iv: bytes = None) -> Tuple[bytes, bytes]:
106
    """
107
    Encrypt data using 3DES-CBC with PKCS#5 padding.
108

109
    Parameters:
110
    - key: bytes - 3DES key (16 or 24 bytes)
111
    - data: bytes - Data to encrypt
112
    - iv: bytes - 8-byte initialization vector (None to generate random)
113

114
    Returns:
115
    Tuple of (iv, ciphertext) bytes
116
    """
117

118
def tripledes_cbc_pkcs5_decrypt(key: bytes, data: bytes, iv: bytes) -> bytes:
119
    """
120
    Decrypt 3DES-CBC data with PKCS#5 padding.
121

122
    Parameters:
123
    - key: bytes - 3DES key (16 or 24 bytes)
124
    - data: bytes - Ciphertext to decrypt
125
    - iv: bytes - 8-byte initialization vector
126

127
    Returns:
128
    Decrypted plaintext data
129
    """
130
```
131

132
### RC2 Encryption
133

134
RC2 cipher operations with CBC mode and PKCS#5 padding.
135

136
```python { .api }
137
def rc2_cbc_pkcs5_encrypt(key: bytes, data: bytes, iv: bytes = None) -> Tuple[bytes, bytes]:
138
    """
139
    Encrypt data using RC2-CBC with PKCS#5 padding.
140

141
    Parameters:
142
    - key: bytes - RC2 key (5-16 bytes for 40-128 bit keys)
143
    - data: bytes - Data to encrypt
144
    - iv: bytes - 8-byte initialization vector (None to generate random)
145

146
    Returns:
147
    Tuple of (iv, ciphertext) bytes
148
    """
149

150
def rc2_cbc_pkcs5_decrypt(key: bytes, data: bytes, iv: bytes) -> bytes:
151
    """
152
    Decrypt RC2-CBC data with PKCS#5 padding.
153

154
    Parameters:
155
    - key: bytes - RC2 key (5-16 bytes for 40-128 bit keys)
156
    - data: bytes - Ciphertext to decrypt
157
    - iv: bytes - 8-byte initialization vector
158

159
    Returns:
160
    Decrypted plaintext data
161
    """
162
```
163

164
### RC4 Encryption
165

166
RC4 stream cipher operations (encryption and decryption use the same function).
167

168
```python { .api }
169
def rc4_encrypt(key: bytes, data: bytes) -> bytes:
170
    """
171
    Encrypt data using RC4 stream cipher.
172

173
    Parameters:
174
    - key: bytes - RC4 key (5-16 bytes for 40-128 bit keys)
175
    - data: bytes - Data to encrypt
176

177
    Returns:
178
    Encrypted ciphertext
179
    """
180

181
def rc4_decrypt(key: bytes, data: bytes) -> bytes:
182
    """
183
    Decrypt RC4 data (same operation as encryption).
184

185
    Parameters:
186
    - key: bytes - RC4 key (5-16 bytes for 40-128 bit keys)
187
    - data: bytes - Ciphertext to decrypt
188

189
    Returns:
190
    Decrypted plaintext data
191
    """
192
```
193

194
## Usage Examples
195

196
### AES Encryption Example
197

198
```python
199
from oscrypto.symmetric import aes_cbc_pkcs7_encrypt, aes_cbc_pkcs7_decrypt
200
from oscrypto.util import rand_bytes
201

202
# Generate a 256-bit (32-byte) AES key
203
key = rand_bytes(32)
204

205
# Encrypt data
206
plaintext = b"This is a secret message that needs to be encrypted"
207
iv, ciphertext = aes_cbc_pkcs7_encrypt(key, plaintext, None)
208

209
# Decrypt data
210
decrypted = aes_cbc_pkcs7_decrypt(key, ciphertext, iv)
211
assert decrypted == plaintext
212

213
print(f"Original: {plaintext}")
214
print(f"Encrypted length: {len(ciphertext)} bytes")
215
print(f"Decrypted: {decrypted}")
216
```
217

218
### Multiple Algorithm Example
219

220
```python
221
from oscrypto.symmetric import (
222
    aes_cbc_pkcs7_encrypt, aes_cbc_pkcs7_decrypt,
223
    des_cbc_pkcs5_encrypt, des_cbc_pkcs5_decrypt,
224
    rc4_encrypt, rc4_decrypt
225
)
226
from oscrypto.util import rand_bytes
227

228
message = b"Secret data"
229

230
# AES-256 encryption
231
aes_key = rand_bytes(32)
232
aes_iv, aes_ciphertext = aes_cbc_pkcs7_encrypt(aes_key, message, None)
233
aes_decrypted = aes_cbc_pkcs7_decrypt(aes_key, aes_ciphertext, aes_iv)
234

235
# DES encryption
236
des_key = rand_bytes(8)
237
des_iv, des_ciphertext = des_cbc_pkcs5_encrypt(des_key, message, None)
238
des_decrypted = des_cbc_pkcs5_decrypt(des_key, des_ciphertext, des_iv)
239

240
# RC4 encryption
241
rc4_key = rand_bytes(16)
242
rc4_encrypted = rc4_encrypt(rc4_key, message)
243
rc4_decrypted = rc4_decrypt(rc4_key, rc4_encrypted)
244

245
# All should decrypt to original message
246
assert aes_decrypted == des_decrypted == rc4_decrypted == message
247
```
248

249
### Custom IV Example
250

251
```python
252
from oscrypto.symmetric import aes_cbc_pkcs7_encrypt, aes_cbc_pkcs7_decrypt
253
from oscrypto.util import rand_bytes
254

255
key = rand_bytes(16)  # AES-128 key
256
iv = rand_bytes(16)   # AES block size IV
257
plaintext = b"Message with custom IV"
258

259
# Encrypt with custom IV
260
returned_iv, ciphertext = aes_cbc_pkcs7_encrypt(key, plaintext, iv)
261

262
# Decrypt with same IV
263
decrypted = aes_cbc_pkcs7_decrypt(key, ciphertext, iv)
264
assert decrypted == plaintext
265
```