0
# Cryptographic and Security Features
1
2
Cryptographic functions and security features for multimedia data protection, including AES encryption, hash functions, and media content encryption support.
3
4
## Capabilities
5
6
### AES Encryption/Decryption
7
8
#### AES Context Management
9
10
```java { .api }
11
/**
12
* Get size of AVAES context structure
13
* @return Size in bytes required for AES context
14
*/
15
int av_aes_size();
16
17
/**
18
* Allocate AES context
19
* @return New AES context or null on failure
20
*/
21
AVAES av_aes_alloc();
22
23
/**
24
* Initialize AES context with key
25
* @param a AES context to initialize
26
* @param key Encryption key (16, 24, or 32 bytes)
27
* @param key_bits Key size in bits (128, 192, or 256)
28
* @param decrypt 0 for encryption, 1 for decryption
29
* @return 0 on success, negative AVERROR on failure
30
*/
31
int av_aes_init(AVAES a, byte[] key, int key_bits, int decrypt);
32
```
33
34
**Usage Example:**
35
36
```java
37
import org.bytedeco.ffmpeg.avutil.*;
38
import static org.bytedeco.ffmpeg.global.avutil.*;
39
40
// Create AES-256 encryption context
41
AVAES aesCtx = av_aes_alloc();
42
byte[] key = new byte[32]; // 256-bit key
43
// ... fill key with random data ...
44
45
int result = av_aes_init(aesCtx, key, 256, 0); // 0 = encrypt mode
46
if (result < 0) {
47
throw new RuntimeException("Failed to initialize AES context");
48
}
49
50
// Use context for encryption operations
51
// ... cleanup when done
52
```
53
54
#### AES Encryption Operations
55
56
```java { .api }
57
/**
58
* Encrypt or decrypt data using AES
59
* @param a Initialized AES context
60
* @param dst Destination buffer for processed data
61
* @param src Source data to process
62
* @param count Number of 16-byte blocks to process
63
* @param iv Initialization vector (16 bytes, modified during operation)
64
* @param decrypt 0 for encryption, 1 for decryption
65
*/
66
void av_aes_crypt(AVAES a, byte[] dst, byte[] src, int count, byte[] iv, int decrypt);
67
```
68
69
**Usage Example:**
70
71
```java
72
// Encrypt data using AES-256-CBC
73
byte[] plaintext = "This is secret data that needs encryption.".getBytes();
74
byte[] ciphertext = new byte[plaintext.length];
75
byte[] iv = new byte[16]; // Initialization vector
76
// ... fill IV with random data ...
77
78
// Pad plaintext to 16-byte boundary
79
int blockCount = (plaintext.length + 15) / 16;
80
byte[] paddedPlaintext = new byte[blockCount * 16];
81
System.arraycopy(plaintext, 0, paddedPlaintext, 0, plaintext.length);
82
83
// Encrypt
84
av_aes_crypt(aesCtx, ciphertext, paddedPlaintext, blockCount, iv, 0);
85
System.out.println("Data encrypted successfully");
86
```
87
88
### AES-CTR Mode Encryption
89
90
#### AES-CTR Context Management
91
92
```java { .api }
93
/**
94
* Allocate AES-CTR context for counter mode encryption
95
* @return New AES-CTR context or null on failure
96
*/
97
AVAESCTR av_aes_ctr_alloc();
98
99
/**
100
* Initialize AES-CTR context
101
* @param a AES-CTR context to initialize
102
* @param key Encryption key (16 bytes for AES-128)
103
* @return 0 on success, negative AVERROR on failure
104
*/
105
int av_aes_ctr_init(AVAESCTR a, byte[] key);
106
107
/**
108
* Encrypt/decrypt data using AES-CTR mode
109
* @param a Initialized AES-CTR context
110
* @param dst Destination buffer
111
* @param src Source data
112
* @param size Number of bytes to process
113
*/
114
void av_aes_ctr_crypt(AVAESCTR a, byte[] dst, byte[] src, int size);
115
```
116
117
**Usage Example:**
118
119
```java
120
// AES-CTR encryption (stream cipher mode)
121
AVAESCTR aesCtrCtx = av_aes_ctr_alloc();
122
byte[] ctrKey = new byte[16]; // 128-bit key for CTR mode
123
// ... fill key ...
124
125
int result = av_aes_ctr_init(aesCtrCtx, ctrKey);
126
if (result >= 0) {
127
byte[] data = "Stream data for CTR encryption".getBytes();
128
byte[] encrypted = new byte[data.length];
129
130
// Encrypt (no padding needed in CTR mode)
131
av_aes_ctr_crypt(aesCtrCtx, encrypted, data, data.length);
132
133
// Decrypt (same operation in CTR mode)
134
byte[] decrypted = new byte[data.length];
135
av_aes_ctr_crypt(aesCtrCtx, decrypted, encrypted, encrypted.length);
136
137
System.out.println("CTR mode encryption/decryption completed");
138
}
139
```
140
141
### Hash Functions
142
143
#### Generic Hash API
144
145
```java { .api }
146
/**
147
* Allocate hash context for specified algorithm
148
* @param ctx Pointer to store allocated context
149
* @param name Hash algorithm name (e.g., "md5", "sha1", "sha256")
150
* @return 0 on success, negative AVERROR on failure
151
*/
152
int av_hash_alloc(@ByPtrPtr AVHashContext ctx, String name);
153
154
/**
155
* Get available hash algorithm names
156
* @param i Index of hash algorithm (0-based)
157
* @return Hash algorithm name or null if index out of range
158
*/
159
BytePointer av_hash_names(int i);
160
161
/**
162
* Get hash algorithm name for context
163
* @param ctx Hash context
164
* @return Algorithm name
165
*/
166
BytePointer av_hash_get_name(AVHashContext ctx);
167
168
/**
169
* Get hash output size for context
170
* @param ctx Hash context
171
* @return Hash size in bytes
172
*/
173
int av_hash_get_size(AVHashContext ctx);
174
```
175
176
#### Hash Operations
177
178
```java { .api }
179
/**
180
* Initialize hash context for new computation
181
* @param ctx Hash context to initialize
182
*/
183
void av_hash_init(AVHashContext ctx);
184
185
/**
186
* Update hash with input data
187
* @param ctx Hash context
188
* @param src Input data to hash
189
* @param len Length of input data in bytes
190
*/
191
void av_hash_update(AVHashContext ctx, BytePointer src, int len);
192
193
/**
194
* Finalize hash computation and get result
195
* @param ctx Hash context
196
* @param dst Buffer to store hash result
197
*/
198
void av_hash_final(AVHashContext ctx, BytePointer dst);
199
200
/**
201
* Free hash context
202
* @param ctx Hash context to free
203
*/
204
void av_hash_freep(@ByPtrPtr AVHashContext ctx);
205
```
206
207
**Usage Example:**
208
209
```java
210
// Compute SHA-256 hash of data
211
AVHashContext hashCtx = new AVHashContext(null);
212
int result = av_hash_alloc(hashCtx, "sha256");
213
214
if (result >= 0) {
215
try {
216
// Initialize hash computation
217
av_hash_init(hashCtx);
218
219
// Hash input data
220
byte[] data = "Data to be hashed".getBytes();
221
BytePointer dataPtr = new BytePointer(data);
222
av_hash_update(hashCtx, dataPtr, data.length);
223
224
// Get hash result
225
int hashSize = av_hash_get_size(hashCtx);
226
BytePointer hashResult = new BytePointer(hashSize);
227
av_hash_final(hashCtx, hashResult);
228
229
// Convert to hex string
230
StringBuilder hexHash = new StringBuilder();
231
for (int i = 0; i < hashSize; i++) {
232
hexHash.append(String.format("%02x", hashResult.get(i) & 0xFF));
233
}
234
System.out.println("SHA-256: " + hexHash.toString());
235
236
} finally {
237
av_hash_freep(hashCtx);
238
}
239
}
240
```
241
242
### SHA Hash Functions
243
244
#### Specialized SHA Operations
245
246
```java { .api }
247
/**
248
* Get size of AVSHA context structure
249
* @return Size in bytes for SHA context
250
*/
251
int av_sha_size();
252
253
/**
254
* Allocate SHA context
255
* @return New SHA context or null on failure
256
*/
257
AVSHA av_sha_alloc();
258
259
/**
260
* Initialize SHA context for specified bit length
261
* @param context SHA context to initialize
262
* @param bits Hash bit length (160, 224, 256, 384, or 512)
263
* @return 0 on success, negative AVERROR on failure
264
*/
265
int av_sha_init(AVSHA context, int bits);
266
267
/**
268
* Update SHA hash with input data
269
* @param ctx SHA context
270
* @param data Input data
271
* @param len Data length in bytes
272
*/
273
void av_sha_update(AVSHA ctx, BytePointer data, int len);
274
275
/**
276
* Finalize SHA computation
277
* @param ctx SHA context
278
* @param digest Output buffer for hash result
279
*/
280
void av_sha_final(AVSHA ctx, BytePointer digest);
281
```
282
283
### MD5 Hash Functions
284
285
```java { .api }
286
/**
287
* Get size of AVMD5 context structure
288
* @return Size in bytes for MD5 context
289
*/
290
int av_md5_size();
291
292
/**
293
* Allocate MD5 context
294
* @return New MD5 context or null on failure
295
*/
296
AVMD5 av_md5_alloc();
297
298
/**
299
* Initialize MD5 context
300
* @param ctx MD5 context to initialize
301
*/
302
void av_md5_init(AVMD5 ctx);
303
304
/**
305
* Update MD5 hash with input data
306
* @param ctx MD5 context
307
* @param src Input data
308
* @param len Data length in bytes
309
*/
310
void av_md5_update(AVMD5 ctx, BytePointer src, int len);
311
312
/**
313
* Finalize MD5 computation
314
* @param ctx MD5 context
315
* @param dst Output buffer for 16-byte MD5 hash
316
*/
317
void av_md5_final(AVMD5 ctx, BytePointer dst);
318
```
319
320
## Media Content Encryption
321
322
### Encryption Metadata Structures
323
324
```java { .api }
325
/**
326
* Encryption information for media content
327
*/
328
class AVEncryptionInfo extends Pointer {
329
// Encryption scheme identifier
330
int scheme();
331
332
// Encryption pattern for partial encryption
333
int crypt_byte_block();
334
int skip_byte_block();
335
336
// Key identifier
337
BytePointer key_id();
338
int key_id_size();
339
340
// Initialization vector
341
BytePointer iv();
342
int iv_size();
343
344
// Subsample encryption information
345
AVSubsampleEncryptionInfo subsample_encryption_info();
346
int subsample_count();
347
}
348
349
/**
350
* Initialization information for encrypted content
351
*/
352
class AVEncryptionInitInfo extends Pointer {
353
// System identifier (16 bytes)
354
BytePointer system_id();
355
356
// Key ID information
357
PointerPointer key_ids();
358
int num_key_ids();
359
360
// Initialization data
361
BytePointer data();
362
int data_size();
363
}
364
```
365
366
**Usage Example:**
367
368
```java
369
// Access encryption metadata from encrypted media
370
AVEncryptionInfo encInfo = /* from media stream */;
371
372
if (encInfo != null) {
373
System.out.println("Content is encrypted");
374
System.out.println("Scheme: " + encInfo.scheme());
375
System.out.println("Key ID size: " + encInfo.key_id_size());
376
377
// Handle encrypted content appropriately
378
if (encInfo.subsample_count() > 0) {
379
System.out.println("Uses subsample encryption");
380
}
381
}
382
```
383
384
## Security Best Practices
385
386
### Key Management
387
388
```java
389
// Always use cryptographically secure random keys
390
SecureRandom random = new SecureRandom();
391
byte[] aesKey = new byte[32]; // 256-bit key
392
random.nextBytes(aesKey);
393
394
// Clear sensitive data after use
395
Arrays.fill(aesKey, (byte) 0);
396
```
397
398
### Initialization Vectors
399
400
```java
401
// Use unique, random IVs for each encryption operation
402
byte[] iv = new byte[16];
403
random.nextBytes(iv);
404
405
// IV can be stored/transmitted in plaintext with ciphertext
406
```
407
408
### Hash Verification
409
410
```java
411
// Verify data integrity using hash comparison
412
AVHashContext verifyCtx = new AVHashContext(null);
413
av_hash_alloc(verifyCtx, "sha256");
414
415
av_hash_init(verifyCtx);
416
av_hash_update(verifyCtx, dataPtr, dataLength);
417
418
BytePointer computedHash = new BytePointer(32);
419
av_hash_final(verifyCtx, computedHash);
420
421
// Compare with expected hash
422
boolean isValid = Arrays.equals(computedHash.getStringBytes(), expectedHash);
423
```
424
425
## Algorithm Support
426
427
### Available Hash Algorithms
428
429
- **MD5** - 128-bit hash (legacy, not recommended for security)
430
- **SHA-1** - 160-bit hash (legacy, not recommended for security)
431
- **SHA-224** - 224-bit SHA-2 hash
432
- **SHA-256** - 256-bit SHA-2 hash (recommended)
433
- **SHA-384** - 384-bit SHA-2 hash
434
- **SHA-512** - 512-bit SHA-2 hash
435
- **CRC32** - 32-bit cyclic redundancy check
436
437
### Encryption Algorithms
438
439
- **AES-128/192/256** - Advanced Encryption Standard
440
- **AES-CTR** - Counter mode for stream encryption
441
- Integration with media encryption standards (Common Encryption, etc.)
442
443
## Memory Management
444
445
Cryptographic contexts require explicit cleanup:
446
447
```java
448
// Always free cryptographic contexts
449
AVAES aesCtx = av_aes_alloc();
450
try {
451
// Use context
452
} finally {
453
// Context is freed automatically by JavaCPP
454
// but clear sensitive data explicitly
455
}
456
457
// For hash contexts, use av_hash_freep()
458
AVHashContext hashCtx = new AVHashContext(null);
459
try {
460
av_hash_alloc(hashCtx, "sha256");
461
// Use context
462
} finally {
463
av_hash_freep(hashCtx);
464
}
465
```