Azure Security Keyvault Keys Java

1---
2name: azure-security-keyvault-keys-java
3description: Azure Key Vault Keys Java SDK for cryptographic key management. Use when creating, managing, or using RSA/EC keys, performing encrypt/decrypt/sign/verify operations, or working with HSM-backed keys.
4package: com.azure:azure-security-keyvault-keys
5---
6 
7# Azure Key Vault Keys (Java)
8 
9Manage cryptographic keys and perform cryptographic operations in Azure Key Vault and Managed HSM.
10 
11## Installation
12 
13```xml
14<dependency>
15    <groupId>com.azure</groupId>
16    <artifactId>azure-security-keyvault-keys</artifactId>
17    <version>4.9.0</version>
18</dependency>
19```
20 
21## Client Creation
22 
23```java
24import com.azure.security.keyvault.keys.KeyClient;
25import com.azure.security.keyvault.keys.KeyClientBuilder;
26import com.azure.security.keyvault.keys.cryptography.CryptographyClient;
27import com.azure.security.keyvault.keys.cryptography.CryptographyClientBuilder;
28import com.azure.identity.DefaultAzureCredentialBuilder;
29 
30// Key management client
31KeyClient keyClient = new KeyClientBuilder()
32    .vaultUrl("https://<vault-name>.vault.azure.net")
33    .credential(new DefaultAzureCredentialBuilder().build())
34    .buildClient();
35 
36// Async client
37KeyAsyncClient keyAsyncClient = new KeyClientBuilder()
38    .vaultUrl("https://<vault-name>.vault.azure.net")
39    .credential(new DefaultAzureCredentialBuilder().build())
40    .buildAsyncClient();
41 
42// Cryptography client (for encrypt/decrypt/sign/verify)
43CryptographyClient cryptoClient = new CryptographyClientBuilder()
44    .keyIdentifier("https://<vault-name>.vault.azure.net/keys/<key-name>/<key-version>")
45    .credential(new DefaultAzureCredentialBuilder().build())
46    .buildClient();
47```
48 
49## Key Types
50 
51| Type | Description |
52|------|-------------|
53| `RSA` | RSA key (2048, 3072, 4096 bits) |
54| `RSA_HSM` | RSA key in HSM |
55| `EC` | Elliptic Curve key |
56| `EC_HSM` | Elliptic Curve key in HSM |
57| `OCT` | Symmetric key (Managed HSM only) |
58| `OCT_HSM` | Symmetric key in HSM |
59 
60## Create Keys
61 
62### Create RSA Key
63 
64```java
65import com.azure.security.keyvault.keys.models.*;
66 
67// Simple RSA key
68KeyVaultKey rsaKey = keyClient.createRsaKey(new CreateRsaKeyOptions("my-rsa-key")
69    .setKeySize(2048));
70 
71System.out.println("Key name: " + rsaKey.getName());
72System.out.println("Key ID: " + rsaKey.getId());
73System.out.println("Key type: " + rsaKey.getKeyType());
74 
75// RSA key with options
76KeyVaultKey rsaKeyWithOptions = keyClient.createRsaKey(new CreateRsaKeyOptions("my-rsa-key-2")
77    .setKeySize(4096)
78    .setExpiresOn(OffsetDateTime.now().plusYears(1))
79    .setNotBefore(OffsetDateTime.now())
80    .setEnabled(true)
81    .setKeyOperations(KeyOperation.ENCRYPT, KeyOperation.DECRYPT, 
82                       KeyOperation.WRAP_KEY, KeyOperation.UNWRAP_KEY)
83    .setTags(Map.of("environment", "production")));
84 
85// HSM-backed RSA key
86KeyVaultKey hsmKey = keyClient.createRsaKey(new CreateRsaKeyOptions("my-hsm-key")
87    .setKeySize(2048)
88    .setHardwareProtected(true));
89```
90 
91### Create EC Key
92 
93```java
94// EC key with P-256 curve
95KeyVaultKey ecKey = keyClient.createEcKey(new CreateEcKeyOptions("my-ec-key")
96    .setCurveName(KeyCurveName.P_256));
97 
98// EC key with other curves
99KeyVaultKey ecKey384 = keyClient.createEcKey(new CreateEcKeyOptions("my-ec-key-384")
100    .setCurveName(KeyCurveName.P_384));
101 
102KeyVaultKey ecKey521 = keyClient.createEcKey(new CreateEcKeyOptions("my-ec-key-521")
103    .setCurveName(KeyCurveName.P_521));
104 
105// HSM-backed EC key
106KeyVaultKey ecHsmKey = keyClient.createEcKey(new CreateEcKeyOptions("my-ec-hsm-key")
107    .setCurveName(KeyCurveName.P_256)
108    .setHardwareProtected(true));
109```
110 
111### Create Symmetric Key (Managed HSM only)
112 
113```java
114KeyVaultKey octKey = keyClient.createOctKey(new CreateOctKeyOptions("my-symmetric-key")
115    .setKeySize(256)
116    .setHardwareProtected(true));
117```
118 
119## Get Key
120 
121```java
122// Get latest version
123KeyVaultKey key = keyClient.getKey("my-key");
124 
125// Get specific version
126KeyVaultKey keyVersion = keyClient.getKey("my-key", "<version-id>");
127 
128// Get only key properties (no key material)
129KeyProperties keyProps = keyClient.getKey("my-key").getProperties();
130```
131 
132## Update Key Properties
133 
134```java
135KeyVaultKey key = keyClient.getKey("my-key");
136 
137// Update properties
138key.getProperties()
139    .setEnabled(false)
140    .setExpiresOn(OffsetDateTime.now().plusMonths(6))
141    .setTags(Map.of("status", "archived"));
142 
143KeyVaultKey updatedKey = keyClient.updateKeyProperties(key.getProperties(),
144    KeyOperation.ENCRYPT, KeyOperation.DECRYPT);
145```
146 
147## List Keys
148 
149```java
150import com.azure.core.util.paging.PagedIterable;
151 
152// List all keys
153for (KeyProperties keyProps : keyClient.listPropertiesOfKeys()) {
154    System.out.println("Key: " + keyProps.getName());
155    System.out.println("  Enabled: " + keyProps.isEnabled());
156    System.out.println("  Created: " + keyProps.getCreatedOn());
157}
158 
159// List key versions
160for (KeyProperties version : keyClient.listPropertiesOfKeyVersions("my-key")) {
161    System.out.println("Version: " + version.getVersion());
162    System.out.println("Created: " + version.getCreatedOn());
163}
164```
165 
166## Delete Key
167 
168```java
169import com.azure.core.util.polling.SyncPoller;
170 
171// Begin delete (soft-delete enabled vaults)
172SyncPoller<DeletedKey, Void> deletePoller = keyClient.beginDeleteKey("my-key");
173 
174// Wait for deletion
175DeletedKey deletedKey = deletePoller.poll().getValue();
176System.out.println("Deleted: " + deletedKey.getDeletedOn());
177 
178deletePoller.waitForCompletion();
179 
180// Purge deleted key (permanent deletion)
181keyClient.purgeDeletedKey("my-key");
182 
183// Recover deleted key
184SyncPoller<KeyVaultKey, Void> recoverPoller = keyClient.beginRecoverDeletedKey("my-key");
185recoverPoller.waitForCompletion();
186```
187 
188## Cryptographic Operations
189 
190### Encrypt/Decrypt
191 
192```java
193import com.azure.security.keyvault.keys.cryptography.models.*;
194 
195CryptographyClient cryptoClient = new CryptographyClientBuilder()
196    .keyIdentifier("https://<vault>.vault.azure.net/keys/<key-name>")
197    .credential(new DefaultAzureCredentialBuilder().build())
198    .buildClient();
199 
200byte[] plaintext = "Hello, World!".getBytes(StandardCharsets.UTF_8);
201 
202// Encrypt
203EncryptResult encryptResult = cryptoClient.encrypt(EncryptionAlgorithm.RSA_OAEP, plaintext);
204byte[] ciphertext = encryptResult.getCipherText();
205System.out.println("Ciphertext length: " + ciphertext.length);
206 
207// Decrypt
208DecryptResult decryptResult = cryptoClient.decrypt(EncryptionAlgorithm.RSA_OAEP, ciphertext);
209String decrypted = new String(decryptResult.getPlainText(), StandardCharsets.UTF_8);
210System.out.println("Decrypted: " + decrypted);
211```
212 
213### Sign/Verify
214 
215```java
216import java.security.MessageDigest;
217 
218// Create digest of data
219byte[] data = "Data to sign".getBytes(StandardCharsets.UTF_8);
220MessageDigest md = MessageDigest.getInstance("SHA-256");
221byte[] digest = md.digest(data);
222 
223// Sign
224SignResult signResult = cryptoClient.sign(SignatureAlgorithm.RS256, digest);
225byte[] signature = signResult.getSignature();
226 
227// Verify
228VerifyResult verifyResult = cryptoClient.verify(SignatureAlgorithm.RS256, digest, signature);
229System.out.println("Valid signature: " + verifyResult.isValid());
230```
231 
232### Wrap/Unwrap Key
233 
234```java
235// Key to wrap (e.g., AES key)
236byte[] keyToWrap = new byte[32];  // 256-bit key
237new SecureRandom().nextBytes(keyToWrap);
238 
239// Wrap
240WrapResult wrapResult = cryptoClient.wrapKey(KeyWrapAlgorithm.RSA_OAEP, keyToWrap);
241byte[] wrappedKey = wrapResult.getEncryptedKey();
242 
243// Unwrap
244UnwrapResult unwrapResult = cryptoClient.unwrapKey(KeyWrapAlgorithm.RSA_OAEP, wrappedKey);
245byte[] unwrappedKey = unwrapResult.getKey();
246```
247 
248## Backup and Restore
249 
250```java
251// Backup
252byte[] backup = keyClient.backupKey("my-key");
253 
254// Save backup to file
255Files.write(Paths.get("key-backup.blob"), backup);
256 
257// Restore
258byte[] backupData = Files.readAllBytes(Paths.get("key-backup.blob"));
259KeyVaultKey restoredKey = keyClient.restoreKeyBackup(backupData);
260```
261 
262## Key Rotation
263 
264```java
265// Rotate to new version
266KeyVaultKey rotatedKey = keyClient.rotateKey("my-key");
267System.out.println("New version: " + rotatedKey.getProperties().getVersion());
268 
269// Set rotation policy
270KeyRotationPolicy policy = new KeyRotationPolicy()
271    .setExpiresIn("P90D")  // Expire after 90 days
272    .setLifetimeActions(Arrays.asList(
273        new KeyRotationLifetimeAction(KeyRotationPolicyAction.ROTATE)
274            .setTimeBeforeExpiry("P30D")));  // Rotate 30 days before expiry
275 
276keyClient.updateKeyRotationPolicy("my-key", policy);
277 
278// Get rotation policy
279KeyRotationPolicy currentPolicy = keyClient.getKeyRotationPolicy("my-key");
280```
281 
282## Import Key
283 
284```java
285import com.azure.security.keyvault.keys.models.ImportKeyOptions;
286import com.azure.security.keyvault.keys.models.JsonWebKey;
287 
288// Import existing key material
289JsonWebKey jsonWebKey = new JsonWebKey()
290    .setKeyType(KeyType.RSA)
291    .setN(modulus)
292    .setE(exponent)
293    .setD(privateExponent)
294    // ... other RSA components
295    ;
296 
297ImportKeyOptions importOptions = new ImportKeyOptions("imported-key", jsonWebKey)
298    .setHardwareProtected(false);
299 
300KeyVaultKey importedKey = keyClient.importKey(importOptions);
301```
302 
303## Encryption Algorithms
304 
305| Algorithm | Key Type | Description |
306|-----------|----------|-------------|
307| `RSA1_5` | RSA | RSAES-PKCS1-v1_5 |
308| `RSA_OAEP` | RSA | RSAES with OAEP (recommended) |
309| `RSA_OAEP_256` | RSA | RSAES with OAEP using SHA-256 |
310| `A128GCM` | OCT | AES-GCM 128-bit |
311| `A256GCM` | OCT | AES-GCM 256-bit |
312| `A128CBC` | OCT | AES-CBC 128-bit |
313| `A256CBC` | OCT | AES-CBC 256-bit |
314 
315## Signature Algorithms
316 
317| Algorithm | Key Type | Hash |
318|-----------|----------|------|
319| `RS256` | RSA | SHA-256 |
320| `RS384` | RSA | SHA-384 |
321| `RS512` | RSA | SHA-512 |
322| `PS256` | RSA | SHA-256 (PSS) |
323| `ES256` | EC P-256 | SHA-256 |
324| `ES384` | EC P-384 | SHA-384 |
325| `ES512` | EC P-521 | SHA-512 |
326 
327## Error Handling
328 
329```java
330import com.azure.core.exception.HttpResponseException;
331import com.azure.core.exception.ResourceNotFoundException;
332 
333try {
334    KeyVaultKey key = keyClient.getKey("non-existent-key");
335} catch (ResourceNotFoundException e) {
336    System.out.println("Key not found: " + e.getMessage());
337} catch (HttpResponseException e) {
338    System.out.println("HTTP error " + e.getResponse().getStatusCode());
339    System.out.println("Message: " + e.getMessage());
340}
341```
342 
343## Environment Variables
344 
345```bash
346AZURE_KEYVAULT_URL=https://<vault-name>.vault.azure.net
347```
348 
349## Best Practices
350 
3511. **Use HSM Keys for Production** - Set `setHardwareProtected(true)` for sensitive keys
3522. **Enable Soft Delete** - Protects against accidental deletion
3533. **Key Rotation** - Set up automatic rotation policies
3544. **Least Privilege** - Use separate keys for different operations
3555. **Local Crypto When Possible** - Use `CryptographyClient` with local key material to reduce round-trips
356 
357## Trigger Phrases
358 
359- "Key Vault keys Java", "cryptographic keys Java"
360- "encrypt decrypt Java", "sign verify Java"
361- "RSA key", "EC key", "HSM key"
362- "key rotation", "wrap unwrap key"
363