azure-security-keyvault-keys-java

# Azure Key Vault Keys (Java) Manage cryptographic keys and perform cryptographic operations in Azure Key Vault and Managed HSM. ## Installation ```xml <dependency> <groupId>com.azure</groupId> <artifactId>azure-security-keyvault-keys</artifactId> <version>4.9.0</version> </dependency> ``` ## Client Creation ```java import com.azure.security.keyvault.keys.KeyClient; import com.azure.security.keyvault.keys.KeyClientBuilder; import com.azure.security.keyvault.keys.cryptography.CryptographyClient; import com.azure.security.keyvault.keys.cryptography.CryptographyClientBuilder; import com.azure.identity.DefaultAzureCredentialBuilder; // Key management client KeyClient keyClient = new KeyClientBuilder() .vaultUrl("https://<vault-name>.vault.azure.net") .credential(new DefaultAzureCredentialBuilder().build()) .buildClient(); // Async client KeyAsyncClient keyAsyncClient = new KeyClientBuilder() .vaultUrl("https://<vault-name>.vault.azure.net") .credential(new DefaultAzureCredentialBuilder().build()) .buildAsyncClient(); // Cryptography client (for encrypt/decrypt/sign/verify) CryptographyClient cryptoClient = new CryptographyClientBuilder() .keyIdentifier("https://<vault-name>.vault.azure.net/keys/<key-name>/<key-version>") .credential(new DefaultAzureCredentialBuilder().build()) .buildClient(); ``` ## Key Types | Type | Description | |------|-------------| | `RSA` | RSA key (2048, 3072, 4096 bits) | | `RSA_HSM` | RSA key in HSM | | `EC` | Elliptic Curve key | | `EC_HSM` | Elliptic Curve key in HSM | | `OCT` | Symmetric key (Managed HSM only) | | `OCT_HSM` | Symmetric key in HSM | ## Create Keys ### Create RSA Key ```java import com.azure.security.keyvault.keys.models.*; // Simple RSA key KeyVaultKey rsaKey = keyClient.createRsaKey(new CreateRsaKeyOptions("my-rsa-key") .setKeySize(2048)); System.out.println("Key name: " + rsaKey.getName()); System.out.println("Key ID: " + rsaKey.getId()); System.out.println("Key type: " + rsaKey.getKeyType()); // RSA key with options KeyVaultKey rsaKeyWithOptions = keyClient.createRsaKey(new CreateRsaKeyOptions("my-rsa-key-2") .setKeySize(4096) .setExpiresOn(OffsetDateTime.now().plusYears(1)) .setNotBefore(OffsetDateTime.now()) .setEnabled(true) .setKeyOperations(KeyOperation.ENCRYPT, KeyOperation.DECRYPT, KeyOperation.WRAP_KEY, KeyOperation.UNWRAP_KEY) .setTags(Map.of("environment", "production"))); // HSM-backed RSA key KeyVaultKey hsmKey = keyClient.createRsaKey(new CreateRsaKeyOptions("my-hsm-key") .setKeySize(2048) .setHardwareProtected(true)); ``` ### Create EC Key ```java // EC key with P-256 curve KeyVaultKey ecKey = keyClient.createEcKey(new CreateEcKeyOptions("my-ec-key") .setCurveName(KeyCurveName.P_256)); // EC key with other curves KeyVaultKey ecKey384 = keyClient.createEcKey(new CreateEcKeyOptions("my-ec-key-384") .setCurveName(KeyCurveName.P_384)); KeyVaultKey ecKey521 = keyClient.createEcKey(new CreateEcKeyOptions("my-ec-key-521") .setCurveName(KeyCurveName.P_521)); // HSM-backed EC key KeyVaultKey ecHsmKey = keyClient.createEcKey(new CreateEcKeyOptions("my-ec-hsm-key") .setCurveName(KeyCurveName.P_256) .setHardwareProtected(true)); ``` ### Create Symmetric Key (Managed HSM only) ```java KeyVaultKey octKey = keyClient.createOctKey(new CreateOctKeyOptions("my-symmetric-key") .setKeySize(256) .setHardwareProtected(true)); ``` ## Get Key ```java // Get latest version KeyVaultKey key = keyClient.getKey("my-key"); // Get specific version KeyVaultKey keyVersion = keyClient.getKey("my-key", "<version-id>"); // Get only key properties (no key material) KeyProperties keyProps = keyClient.getKey("my-key").getProperties(); ``` ## Update Key Properties ```java KeyVaultKey key = keyClient.getKey("my-key"); // Update properties key.getProperties() .setEnabled(false) .setExpiresOn(OffsetDateTime.now().plusMonths(6)) .setTags(Map.of("status", "archived")); KeyVaultKey updatedKey = keyClient.updateKeyProperties(key.getProperties(), KeyOperation.ENCRYPT, KeyOperation.DECRYPT); ``` ## List Keys ```java import com.azure.core.util.paging.PagedIterable; // List all keys for (KeyProperties keyProps : keyClient.listPropertiesOfKeys()) { System.out.println("Key: " + keyProps.getName()); System.out.println(" Enabled: " + keyProps.isEnabled()); System.out.println(" Created: " + keyProps.getCreatedOn()); } // List key versions for (KeyProperties version : keyClient.listPropertiesOfKeyVersions("my-key")) { System.out.println("Version: " + version.getVersion()); System.out.println("Created: " + version.getCreatedOn()); } ``` ## Delete Key ```java import com.azure.core.util.polling.SyncPoller; // Begin delete (soft-delete enabled vaults) SyncPoller<DeletedKey, Void> deletePoller = keyClient.beginDeleteKey("my-key"); // Wait for deletion DeletedKey deletedKey = deletePoller.poll().getValue(); System.out.println("Deleted: " + deletedKey.getDeletedOn()); deletePoller.waitForCompletion(); // Purge deleted key (permanent deletion) keyClient.purgeDeletedKey("my-key"); // Recover deleted key SyncPoller<KeyVaultKey, Void> recoverPoller = keyClient.beginRecoverDeletedKey("my-key"); recoverPoller.waitForCompletion(); ``` ## Cryptographic Operations ### Encrypt/Decrypt ```java import com.azure.security.keyvault.keys.cryptography.models.*; CryptographyClient cryptoClient = new CryptographyClientBuilder() .keyIdentifier("https://<vault>.vault.azure.net/keys/<key-name>") .credential(new DefaultAzureCredentialBuilder().build()) .buildClient(); byte[] plaintext = "Hello, World!".getBytes(StandardCharsets.UTF_8); // Encrypt EncryptResult encryptResult = cryptoClient.encrypt(EncryptionAlgorithm.RSA_OAEP, plaintext); byte[] ciphertext = encryptResult.getCipherText(); System.out.println("Ciphertext length: " + ciphertext.length); // Decrypt DecryptResult decryptResult = cryptoClient.decrypt(EncryptionAlgorithm.RSA_OAEP, ciphertext); String decrypted = new String(decryptResult.getPlainText(), StandardCharsets.UTF_8); System.out.println("Decrypted: " + decrypted); ``` ### Sign/Verify ```java import java.security.MessageDigest; // Create digest of data byte[] data = "Data to sign".getBytes(StandardCharsets.UTF_8); MessageDigest md = MessageDigest.getInstance("SHA-256"); byte[] digest = md.digest(data); // Sign SignResult signResult = cryptoClient.sign(SignatureAlgorithm.RS256, digest); byte[] signature = signResult.getSignature(); // Verify VerifyResult verifyResult = cryptoClient.verify(SignatureAlgorithm.RS256, digest, signature); System.out.println("Valid signature: " + verifyResult.isValid()); ``` ### Wrap/Unwrap Key ```java // Key to wrap (e.g., AES key) byte[] keyToWrap = new byte[32]; // 256-bit key new SecureRandom().nextBytes(keyToWrap); // Wrap WrapResult wrapResult = cryptoClient.wrapKey(KeyWrapAlgorithm.RSA_OAEP, keyToWrap); byte[] wrappedKey = wrapResult.getEncryptedKey(); // Unwrap UnwrapResult unwrapResult = cryptoClient.unwrapKey(KeyWrapAlgorithm.RSA_OAEP, wrappedKey); byte[] unwrappedKey = unwrapResult.getKey(); ``` ## Backup and Restore ```java // Backup byte[] backup = keyClient.backupKey("my-key"); // Save backup to file Files.write(Paths.get("key-backup.blob"), backup); // Restore byte[] backupData = Files.readAllBytes(Paths.get("key-backup.blob")); KeyVaultKey restoredKey = keyClient.restoreKeyBackup(backupData); ``` ## Key Rotation ```java // Rotate to new version KeyVaultKey rotatedKey = keyClient.rotateKey("my-key"); System.out.println("New version: " + rotatedKey.getProperties().getVersion()); // Set rotation policy KeyRotationPolicy policy = new KeyRotationPolicy() .setExpiresIn("P90D") // Expire after 90 days .setLifetimeActions(Arrays.asList( new KeyRotationLifetimeAction(KeyRotationPolicyAction.ROTATE) .setTimeBeforeExpiry("P30D"))); // Rotate 30 days before expiry keyClient.updateKeyRotationPolicy("my-key", policy); // Get rotation policy KeyRotationPolicy currentPolicy = keyClient.getKeyRotationPolicy("my-key"); ``` ## Import Key ```java import com.azure.security.keyvault.keys.models.ImportKeyOptions; import com.azure.security.keyvault.keys.models.JsonWebKey; // Import existing key material JsonWebKey jsonWebKey = new JsonWebKey() .setKeyType(KeyType.RSA) .setN(modulus) .setE(exponent) .setD(privateExponent) // ... other RSA components ; ImportKeyOptions importOptions = new ImportKeyOptions("imported-key", jsonWebKey) .setHardwareProtected(false); KeyVaultKey importedKey = keyClient.importKey(importOptions); ``` ## Encryption Algorithms | Algorithm | Key Type | Description | |-----------|----------|-------------| | `RSA1_5` | RSA | RSAES-PKCS1-v1_5 | | `RSA_OAEP` | RSA | RSAES with OAEP (recommended) | | `RSA_OAEP_256` | RSA | RSAES with OAEP using SHA-256 | | `A128GCM` | OCT | AES-GCM 128-bit | | `A256GCM` | OCT | AES-GCM 256-bit | | `A128CBC` | OCT | AES-CBC 128-bit | | `A256CBC` | OCT | AES-CBC 256-bit | ## Signature Algorithms | Algorithm | Key Type | Hash | |-----------|----------|------| | `RS256` | RSA | SHA-256 | | `RS384` | RSA | SHA-384 | | `RS512` | RSA | SHA-512 | | `PS256` | RSA | SHA-256 (PSS) | | `ES256` | EC P-256 | SHA-256 | | `ES384` | EC P-384 | SHA-384 | | `ES512` | EC P-521 | SHA-512 | ## Error Handling ```java import com.azure.core.exception.HttpResponseException; import com.azure.core.exception.ResourceNotFoundException; try { KeyVaultKey key = keyClient.getKey("non-existent-key"); } catch (ResourceNotFoundException e) { System.out.println("Key not found: " + e.getMessage()); } catch (HttpResponseException e) { System.out.println("HTTP error " + e.getResponse().getStatusCode()); System.out.println("Message: " + e.getMessage()); } ``` ## Environment Variables ```bash AZURE_KEYVAULT_URL=https://<vault-name>.vault.azure.net ``` ## Best Practices 1. **Use HSM Keys for Production** - Set `setHardwareProtected(true)` for sensitive keys 2. **Enable Soft Delete** - Protects against accidental deletion 3. **Key Rotation** - Set up automatic rotation policies 4. **Least Privilege** - Use separate keys for different operations 5. **Local Crypto When Possible** - Use `CryptographyClient` with local key material to reduce round-trips ## Trigger Phrases - "Key Vault keys Java", "cryptographic keys Java" - "encrypt decrypt Java", "sign verify Java" - "RSA key", "EC key", "HSM key" - "key rotation", "wrap unwrap key"