0
# Cryptographic Operations
1

2
High-performance cryptographic operations using keys stored in Azure Key Vault. Provides encryption, decryption, digital signing, verification, and key wrapping capabilities with support for various algorithms. Enables both local and remote cryptographic operations depending on key type and requirements.
3

4
## Capabilities
5

6
### Cryptography Client
7

8
Client for performing cryptographic operations with Azure Key Vault keys.
9

10
```python { .api }
11
class CryptographyClient:
12
    def __init__(self, key, credential, **kwargs):
13
        """
14
        Initialize CryptographyClient for cryptographic operations.
15
        
16
        Parameters:
17
        - key: KeyVaultKey or JsonWebKey, key to use for operations
18
        - credential: Azure credential object for authentication
19
        - **kwargs: Additional configuration options
20
        """
21

22
    @classmethod
23
    def from_jwk(cls, jwk: JsonWebKey) -> "CryptographyClient":
24
        """
25
        Create client from JSON Web Key for local operations.
26
        
27
        Parameters:
28
        - jwk: JsonWebKey, key material for local operations
29
        
30
        Returns:
31
        CryptographyClient configured for local operations
32
        """
33

34
    def close(self) -> None:
35
        """Close the client and release resources."""
36
```
37

38
### Encryption and Decryption
39

40
Encrypt and decrypt data using various symmetric and asymmetric algorithms.
41

42
```python { .api }
43
def encrypt(self, algorithm: EncryptionAlgorithm, plaintext: bytes, **kwargs) -> EncryptResult:
44
    """
45
    Encrypt data using the specified algorithm.
46
    
47
    Parameters:
48
    - algorithm: EncryptionAlgorithm, encryption algorithm to use
49
    - plaintext: bytes, data to encrypt
50
    - iv: bytes, initialization vector for symmetric algorithms
51
    - additional_authenticated_data: bytes, AAD for authenticated encryption
52
    
53
    Returns:
54
    EncryptResult with encrypted data and metadata
55
    """
56

57
def decrypt(self, algorithm: EncryptionAlgorithm, ciphertext: bytes, **kwargs) -> DecryptResult:
58
    """
59
    Decrypt data using the specified algorithm.
60
    
61
    Parameters:
62
    - algorithm: EncryptionAlgorithm, decryption algorithm to use
63
    - ciphertext: bytes, encrypted data to decrypt
64
    - iv: bytes, initialization vector for symmetric algorithms
65
    - additional_authenticated_data: bytes, AAD for authenticated encryption
66
    - authentication_tag: bytes, authentication tag for authenticated encryption
67
    
68
    Returns:
69
    DecryptResult with decrypted data and metadata
70
    """
71
```
72

73
### Digital Signing and Verification
74

75
Sign data and verify signatures using various algorithms.
76

77
```python { .api }
78
def sign(self, algorithm: SignatureAlgorithm, digest: bytes, **kwargs) -> SignResult:
79
    """
80
    Sign a digest using the specified algorithm.
81
    
82
    Parameters:
83
    - algorithm: SignatureAlgorithm, signature algorithm to use
84
    - digest: bytes, pre-computed hash to sign
85
    
86
    Returns:
87
    SignResult with signature and metadata
88
    """
89

90
def verify(self, algorithm: SignatureAlgorithm, digest: bytes, signature: bytes, **kwargs) -> VerifyResult:
91
    """
92
    Verify a signature using the specified algorithm.
93
    
94
    Parameters:
95
    - algorithm: SignatureAlgorithm, signature algorithm used
96
    - digest: bytes, original hash that was signed
97
    - signature: bytes, signature to verify
98
    
99
    Returns:
100
    VerifyResult with verification status and metadata
101
    """
102
```
103

104
### Key Wrapping and Unwrapping
105

106
Wrap and unwrap keys for secure key exchange and storage.
107

108
```python { .api }
109
def wrap_key(self, algorithm: KeyWrapAlgorithm, key: bytes, **kwargs) -> WrapResult:
110
    """
111
    Wrap (encrypt) a key using the specified algorithm.
112
    
113
    Parameters:
114
    - algorithm: KeyWrapAlgorithm, key wrapping algorithm to use
115
    - key: bytes, key material to wrap
116
    
117
    Returns:
118
    WrapResult with wrapped key and metadata
119
    """
120

121
def unwrap_key(self, algorithm: KeyWrapAlgorithm, encrypted_key: bytes, **kwargs) -> UnwrapResult:
122
    """
123
    Unwrap (decrypt) a key using the specified algorithm.
124
    
125
    Parameters:
126
    - algorithm: KeyWrapAlgorithm, key unwrapping algorithm to use
127
    - encrypted_key: bytes, wrapped key to unwrap
128
    
129
    Returns:
130
    UnwrapResult with unwrapped key and metadata
131
    """
132
```
133

134
## Cryptographic Algorithms
135

136
### Encryption Algorithms
137

138
```python { .api }
139
class EncryptionAlgorithm(str, Enum):
140
    """Supported encryption algorithms."""
141
    # RSA algorithms
142
    rsa1_5 = "RSA1_5"                    # RSA with PKCS#1 v1.5 padding
143
    rsa_oaep = "RSA-OAEP"                # RSA with OAEP padding (SHA-1)
144
    rsa_oaep_256 = "RSA-OAEP-256"        # RSA with OAEP padding (SHA-256)
145
    
146
    # AES GCM algorithms
147
    a128gcm = "A128GCM"                  # AES-128 GCM
148
    a192gcm = "A192GCM"                  # AES-192 GCM  
149
    a256gcm = "A256GCM"                  # AES-256 GCM
150
    
151
    # AES Key Wrap algorithms
152
    a128kw = "A128KW"                    # AES-128 Key Wrap
153
    a192kw = "A192KW"                    # AES-192 Key Wrap
154
    a256kw = "A256KW"                    # AES-256 Key Wrap
155
    
156
    # AES CBC algorithms
157
    a128cbc = "A128CBC"                  # AES-128 CBC
158
    a192cbc = "A192CBC"                  # AES-192 CBC
159
    a256cbc = "A256CBC"                  # AES-256 CBC
160
    
161
    # AES CBC with PKCS#7 padding
162
    a128cbcpad = "A128CBCPAD"            # AES-128 CBC with PKCS#7 padding
163
    a192cbcpad = "A192CBCPAD"            # AES-192 CBC with PKCS#7 padding
164
    a256cbcpad = "A256CBCPAD"            # AES-256 CBC with PKCS#7 padding
165
```
166

167
### Key Wrap Algorithms
168

169
```python { .api }
170
class KeyWrapAlgorithm(str, Enum):
171
    """Supported key wrapping algorithms."""
172
    # RSA algorithms
173
    rsa1_5 = "RSA1_5"                    # RSA with PKCS#1 v1.5 padding
174
    rsa_oaep = "RSA-OAEP"                # RSA with OAEP padding (SHA-1)
175
    rsa_oaep_256 = "RSA-OAEP-256"        # RSA with OAEP padding (SHA-256)
176
    
177
    # AES Key Wrap algorithms
178
    a128kw = "A128KW"                    # AES-128 Key Wrap
179
    a192kw = "A192KW"                    # AES-192 Key Wrap
180
    a256kw = "A256KW"                    # AES-256 Key Wrap
181
```
182

183
### Signature Algorithms
184

185
```python { .api }
186
class SignatureAlgorithm(str, Enum):
187
    """Supported signature algorithms."""
188
    # RSA PSS algorithms
189
    ps256 = "PS256"                      # RSA-PSS with SHA-256
190
    ps384 = "PS384"                      # RSA-PSS with SHA-384
191
    ps512 = "PS512"                      # RSA-PSS with SHA-512
192
    
193
    # RSA PKCS#1 v1.5 algorithms
194
    rs256 = "RS256"                      # RSA with SHA-256
195
    rs384 = "RS384"                      # RSA with SHA-384
196
    rs512 = "RS512"                      # RSA with SHA-512
197
    
198
    # ECDSA algorithms
199
    es256 = "ES256"                      # ECDSA with SHA-256 (P-256 curve)
200
    es384 = "ES384"                      # ECDSA with SHA-384 (P-384 curve)
201
    es512 = "ES512"                      # ECDSA with SHA-512 (P-521 curve)
202
    es256k = "ES256K"                    # ECDSA with SHA-256 (secp256k1 curve)
203
```
204

205
## Cryptographic Result Classes
206

207
```python { .api }
208
class EncryptResult:
209
    """Result of encryption operation."""
210
    key_id: str
211
    algorithm: EncryptionAlgorithm  
212
    ciphertext: bytes
213
    iv: bytes                            # Initialization vector (if applicable)
214
    authentication_tag: bytes           # Authentication tag (for authenticated encryption)
215

216
class DecryptResult:
217
    """Result of decryption operation."""
218
    key_id: str
219
    algorithm: EncryptionAlgorithm
220
    plaintext: bytes
221

222
class WrapResult:
223
    """Result of key wrap operation."""
224
    key_id: str
225
    algorithm: KeyWrapAlgorithm
226
    encrypted_key: bytes
227

228
class UnwrapResult:
229
    """Result of key unwrap operation."""
230
    key_id: str
231
    algorithm: KeyWrapAlgorithm
232
    key: bytes
233

234
class SignResult:
235
    """Result of sign operation."""
236
    key_id: str
237
    algorithm: SignatureAlgorithm
238
    signature: bytes
239

240
class VerifyResult:
241
    """Result of verify operation."""
242
    key_id: str
243
    algorithm: SignatureAlgorithm
244
    is_valid: bool
245
```
246

247
## Usage Examples
248

249
### Basic Encryption and Decryption
250

251
```python
252
from azure.keyvault.keys import KeyClient
253
from azure.keyvault.keys.crypto import EncryptionAlgorithm
254
from azure.identity import DefaultAzureCredential
255

256
# Initialize clients
257
credential = DefaultAzureCredential()
258
key_client = KeyClient(vault_url="https://vault-name.vault.azure.net/", credential=credential)
259

260
# Create RSA key for encryption
261
rsa_key = key_client.create_rsa_key("encryption-key", size=2048)
262

263
# Get cryptography client
264
crypto_client = key_client.get_cryptography_client("encryption-key")
265

266
# Encrypt data
267
plaintext = b"This is sensitive data that needs to be encrypted"
268
encrypt_result = crypto_client.encrypt(EncryptionAlgorithm.rsa_oaep, plaintext)
269

270
print(f"Encrypted with key: {encrypt_result.key_id}")
271
print(f"Ciphertext length: {len(encrypt_result.ciphertext)} bytes")
272

273
# Decrypt data
274
decrypt_result = crypto_client.decrypt(EncryptionAlgorithm.rsa_oaep, encrypt_result.ciphertext)
275
print(f"Decrypted: {decrypt_result.plaintext.decode()}")
276
```
277

278
### AES Symmetric Encryption
279

280
```python
281
from azure.keyvault.keys.crypto import EncryptionAlgorithm
282
import os
283

284
# Create AES key
285
aes_key = key_client.create_oct_key("aes-key", size=256)
286
aes_crypto_client = key_client.get_cryptography_client("aes-key")
287

288
# AES-GCM encryption (authenticated encryption)
289
plaintext = b"Symmetric encryption with AES-256-GCM"
290
iv = os.urandom(12)  # 96-bit IV for GCM
291
aad = b"additional authenticated data"
292

293
encrypt_result = aes_crypto_client.encrypt(
294
    EncryptionAlgorithm.a256gcm,
295
    plaintext,
296
    iv=iv,
297
    additional_authenticated_data=aad
298
)
299

300
# Decrypt with authentication
301
decrypt_result = aes_crypto_client.decrypt(
302
    EncryptionAlgorithm.a256gcm,
303
    encrypt_result.ciphertext,
304
    iv=iv,
305
    additional_authenticated_data=aad,
306
    authentication_tag=encrypt_result.authentication_tag
307
)
308

309
print(f"Decrypted: {decrypt_result.plaintext.decode()}")
310
```
311

312
### Digital Signing and Verification
313

314
```python
315
from azure.keyvault.keys.crypto import SignatureAlgorithm
316
import hashlib
317

318
# Create EC key for signing
319
ec_key = key_client.create_ec_key("signing-key", curve="P-256")
320
sign_crypto_client = key_client.get_cryptography_client("signing-key")
321

322
# Create hash of data to sign
323
data = b"This document needs to be digitally signed"
324
digest = hashlib.sha256(data).digest()
325

326
# Sign the hash
327
sign_result = sign_crypto_client.sign(SignatureAlgorithm.es256, digest)
328
print(f"Signature length: {len(sign_result.signature)} bytes")
329

330
# Verify signature
331
verify_result = sign_crypto_client.verify(SignatureAlgorithm.es256, digest, sign_result.signature)
332
print(f"Signature valid: {verify_result.is_valid}")
333

334
# Verify with tampered data (should fail)
335
tampered_data = b"This document has been tampered with"
336
tampered_digest = hashlib.sha256(tampered_data).digest()
337
verify_tampered = sign_crypto_client.verify(SignatureAlgorithm.es256, tampered_digest, sign_result.signature)
338
print(f"Tampered signature valid: {verify_tampered.is_valid}")
339
```
340

341
### Key Wrapping and Unwrapping
342

343
```python
344
from azure.keyvault.keys.crypto import KeyWrapAlgorithm
345
import os
346

347
# Create RSA key for key wrapping
348
wrap_key = key_client.create_rsa_key("key-wrap-key", size=2048)
349
wrap_crypto_client = key_client.get_cryptography_client("key-wrap-key")
350

351
# Generate symmetric key to wrap
352
symmetric_key = os.urandom(32)  # 256-bit key
353

354
# Wrap the symmetric key
355
wrap_result = wrap_crypto_client.wrap_key(KeyWrapAlgorithm.rsa_oaep, symmetric_key)
356
print(f"Wrapped key length: {len(wrap_result.encrypted_key)} bytes")
357

358
# Unwrap the key
359
unwrap_result = wrap_crypto_client.unwrap_key(KeyWrapAlgorithm.rsa_oaep, wrap_result.encrypted_key)
360
print(f"Keys match: {unwrap_result.key == symmetric_key}")
361

362
# Use AES key wrapping
363
aes_wrap_key = key_client.create_oct_key("aes-wrap-key", size=256)
364
aes_wrap_crypto_client = key_client.get_cryptography_client("aes-wrap-key")
365

366
# Wrap with AES-KW
367
aes_wrap_result = aes_wrap_crypto_client.wrap_key(KeyWrapAlgorithm.a256kw, symmetric_key)
368
aes_unwrap_result = aes_wrap_crypto_client.unwrap_key(KeyWrapAlgorithm.a256kw, aes_wrap_result.encrypted_key)
369
print(f"AES wrapped keys match: {aes_unwrap_result.key == symmetric_key}")
370
```
371

372
### Local Cryptographic Operations
373

374
```python
375
from azure.keyvault.keys.crypto import CryptographyClient
376

377
# Get key with private key material (for HSM keys, operations are always remote)
378
key_with_private = key_client.get_key("encryption-key")
379

380
# Create local crypto client
381
local_crypto_client = CryptographyClient.from_jwk(key_with_private.key)
382

383
# Local operations (faster, no network calls)
384
local_encrypt_result = local_crypto_client.encrypt(EncryptionAlgorithm.rsa_oaep, plaintext)
385
local_decrypt_result = local_crypto_client.decrypt(EncryptionAlgorithm.rsa_oaep, local_encrypt_result.ciphertext)
386

387
print(f"Local operation successful: {local_decrypt_result.plaintext == plaintext}")
388
```
389

390
### Advanced Encryption Scenarios
391

392
```python
393
from azure.keyvault.keys.crypto import EncryptionAlgorithm
394
import os
395

396
# Multi-layer encryption example
397
outer_key = key_client.create_rsa_key("outer-key", size=2048)
398
inner_key = key_client.create_oct_key("inner-key", size=256)
399

400
outer_crypto = key_client.get_cryptography_client("outer-key")
401
inner_crypto = key_client.get_cryptography_client("inner-key")
402

403
sensitive_data = b"Top secret information requiring multi-layer encryption"
404

405
# Layer 1: AES-GCM encryption
406
iv = os.urandom(12)
407
inner_result = inner_crypto.encrypt(EncryptionAlgorithm.a256gcm, sensitive_data, iv=iv)
408

409
# Layer 2: RSA encryption of the AES-encrypted data
410
outer_result = outer_crypto.encrypt(EncryptionAlgorithm.rsa_oaep, inner_result.ciphertext)
411

412
print("Multi-layer encryption complete")
413

414
# Decrypt layers in reverse order
415
outer_decrypt = outer_crypto.decrypt(EncryptionAlgorithm.rsa_oaep, outer_result.ciphertext)
416
inner_decrypt = inner_crypto.decrypt(
417
    EncryptionAlgorithm.a256gcm, 
418
    outer_decrypt.plaintext,
419
    iv=iv,
420
    authentication_tag=inner_result.authentication_tag
421
)
422

423
print(f"Multi-layer decryption successful: {inner_decrypt.plaintext == sensitive_data}")
424
```
425

426
### Async Cryptographic Operations
427

428
```python
429
from azure.keyvault.keys.aio import KeyClient
430
from azure.keyvault.keys.crypto.aio import CryptographyClient
431
import asyncio
432

433
async def async_crypto_operations():
434
    credential = DefaultAzureCredential()
435
    key_client = KeyClient(vault_url="https://vault-name.vault.azure.net/", credential=credential)
436
    
437
    try:
438
        # Create key asynchronously
439
        key = await key_client.create_rsa_key("async-key", size=2048)
440
        
441
        # Get async crypto client
442
        crypto_client = await key_client.get_cryptography_client("async-key")
443
        
444
        try:
445
            # Async encryption
446
            plaintext = b"Async encryption test"
447
            encrypt_result = await crypto_client.encrypt(EncryptionAlgorithm.rsa_oaep, plaintext)
448
            
449
            # Async decryption
450
            decrypt_result = await crypto_client.decrypt(EncryptionAlgorithm.rsa_oaep, encrypt_result.ciphertext)
451
            
452
            print(f"Async operation successful: {decrypt_result.plaintext == plaintext}")
453
            
454
        finally:
455
            await crypto_client.close()
456
            
457
    finally:
458
        await key_client.close()
459

460
# Run async operations
461
asyncio.run(async_crypto_operations())
462
```