SymmetricKey Class

Package:

com.microsoft.azure.keyvault.cryptography

• java.lang.Object
• • Closeable
  • • IKey
    • • com.microsoft.azure.keyvault.cryptography.SymmetricKey

public class SymmetricKey implements IKey

A simple symmetric key implementation

Field Summary

Modifier and Type	Field and Description
final int	DefaultKeySize
final int	KeySize128
final int	KeySize192
final int	KeySize256
final int	KeySize384
final int	KeySize512

Constructor Summary

Constructor	Description
SymmetricKey()	Creates a SymmetricKey with a random key identifier and a random key with DefaultKeySize bits.
SymmetricKey(String kid)	Creates a SymmetricKey with the specified key identifier and a random key with DefaultKeySize bits.
SymmetricKey(String kid, byte[] keyBytes)	Creates a SymmetricKey with the specified key identifier and key material.
SymmetricKey(String kid, byte[] keyBytes, Provider provider)	Creates a SymmetricKey with the specified key identifier and key material that uses the specified Provider.
SymmetricKey(String kid, int keySizeInBytes)	Creates a SymmetricKey with the specified key identifier and a random key with the specified size.
SymmetricKey(String kid, int keySizeInBytes, Provider provider)	Creates a SymmetricKey with the specified key identifier and a random key with the specified size that uses the specified provider.

Method Summary

Modifier and Type	Method and Description
void	close()
ListenableFuture<byte[]>	decryptAsync(final byte[] ciphertext, final byte[] iv, final byte[] authenticationData, final byte[] authenticationTag, final String algorithm) Decrypts the specified cipher text. Note that not all algorithms require, or support, all parameters.
ListenableFuture<Triple<byte[], byte[], String>>	encryptAsync(final byte[] plaintext, final byte[] iv, final byte[] authenticationData, final String algorithm) Encrypts the specified plain text. Note that not all algorithms require, or support, all parameters.
String	getDefaultEncryptionAlgorithm() The default encryption algorithm for this key, using the representations from Json Web Key Algorithms, RFC7513.
String	getDefaultKeyWrapAlgorithm() The default key wrap algorithm for this key, using the representations from Json Web Key Algorithms, RFC7513.
String	getDefaultSignatureAlgorithm() The default signature algorithm for this key, using the representations from Json Web Key Algorithms, RFC7513.
String	getKid() The unique key identifier for this key.
ListenableFuture<Pair<byte[], String>>	signAsync(final byte[] digest, final String algorithm) Signs the specified digest using the specified algorithm, or the keys DefaultSignatureAlgorithm if no algorithm is specified.
ListenableFuture<byte[]>	unwrapKeyAsync(final byte[] encryptedKey, final String algorithm) Unwraps (decrypts) the specified encryped key material.
ListenableFuture<Boolean>	verifyAsync(final byte[] digest, final byte[] signature, final String algorithm) Verifies the supplied signature value using the supplied digest and algorithm.
ListenableFuture<Pair<byte[], String>>	wrapKeyAsync(final byte[] key, final String algorithm) Wraps (encrypts) the specified symmetric key material using the specified algorithm, or the keys DefaultKeyWrapAlgorithm if none is specified.

Field Details

DefaultKeySize

public static final int DefaultKeySize= KeySize256

KeySize128

public static final int KeySize128= 128>> 3

KeySize192

public static final int KeySize192= 192>> 3

KeySize256

public static final int KeySize256= 256>> 3

KeySize384

public static final int KeySize384= 384>> 3

KeySize512

public static final int KeySize512= 512>> 3

Constructor Details

SymmetricKey

public SymmetricKey()

Creates a SymmetricKey with a random key identifier and a random key with DefaultKeySize bits.

SymmetricKey

public SymmetricKey(String kid)

Creates a SymmetricKey with the specified key identifier and a random key with DefaultKeySize bits.

Parameters:

kid - The key identifier to use.

SymmetricKey

public SymmetricKey(String kid, byte[] keyBytes)

Creates a SymmetricKey with the specified key identifier and key material.

Parameters:

kid - The key identifier to use.

keyBytes - The key material to use.

SymmetricKey

public SymmetricKey(String kid, byte[] keyBytes, Provider provider)

Creates a SymmetricKey with the specified key identifier and key material that uses the specified Provider.

Parameters:

kid - The key identifier to use.

keyBytes - The key material to use.

provider - The Provider to use (optional, null for default)

SymmetricKey

public SymmetricKey(String kid, int keySizeInBytes)

Creates a SymmetricKey with the specified key identifier and a random key with the specified size.

Parameters:

kid - The key identifier to use.

keySizeInBytes - The key size to use in bytes.

SymmetricKey

public SymmetricKey(String kid, int keySizeInBytes, Provider provider)

Creates a SymmetricKey with the specified key identifier and a random key with the specified size that uses the specified provider.

Parameters:

kid - The key identifier to use.

keySizeInBytes - The key size to use in bytes.

provider - The provider to use (optional, null for default)

Method Details

close

public void close()

decryptAsync

public ListenableFuture decryptAsync(final byte[] ciphertext, final byte[] iv, final byte[] authenticationData, final byte[] authenticationTag, final String algorithm)

Decrypts the specified cipher text. Note that not all algorithms require, or support, all parameters.

Overrides:

SymmetricKey.decryptAsync(final byte[] ciphertext, final byte[] iv, final byte[] authenticationData, final byte[] authenticationTag, final String algorithm)

Parameters:

ciphertext - The cipher text to decrypt

iv - The initialization vector (optional with some algorithms)

authenticationData - Additional authentication data (optional with some algorithms)

authenticationTag - The authentication tag from the encrypt operation (optional with some algorithms)

algorithm - The encryption algorithm to use, must be supplied

Returns:

A ListenableFuture containing the plain text

Throws:

NoSuchAlgorithmException - the algorithm is not valid

encryptAsync

public ListenableFuture> encryptAsync(final byte[] plaintext, final byte[] iv, final byte[] authenticationData, final String algorithm)

Encrypts the specified plain text. Note that not all algorithms require, or support, all parameters.

Overrides:

SymmetricKey.encryptAsync(final byte[] plaintext, final byte[] iv, final byte[] authenticationData, final String algorithm)

Parameters:

plaintext - The plain text to encrypt

iv - The initialization vector (optional with some algorithms)

authenticationData - Additional authentication data (optional with some algorithms)

algorithm - The encryption algorithm to use, defaults to the keys DefaultEncryptionAlgorithm

Returns:

A ListenableFuture containing the cipher text, the authentication tag and the algorithm that was used

Throws:

NoSuchAlgorithmException - the algorithm is not valid

getDefaultEncryptionAlgorithm

public String getDefaultEncryptionAlgorithm()

The default encryption algorithm for this key, using the representations from Json Web Key Algorithms, RFC7513.

Overrides:

SymmetricKey.getDefaultEncryptionAlgorithm()

Returns:

The default encryption algorithm for this key.

getDefaultKeyWrapAlgorithm

public String getDefaultKeyWrapAlgorithm()

The default key wrap algorithm for this key, using the representations from Json Web Key Algorithms, RFC7513.

Overrides:

SymmetricKey.getDefaultKeyWrapAlgorithm()

Returns:

The default key wrap algorithm for this key.

getDefaultSignatureAlgorithm

public String getDefaultSignatureAlgorithm()

The default signature algorithm for this key, using the representations from Json Web Key Algorithms, RFC7513.

Overrides:

SymmetricKey.getDefaultSignatureAlgorithm()

Returns:

The default signature algorithm for this key.

getKid

public String getKid()

The unique key identifier for this key.

Overrides:

SymmetricKey.getKid()

Returns:

The key identifier

signAsync

public ListenableFuture> signAsync(final byte[] digest, final String algorithm)

Signs the specified digest using the specified algorithm, or the keys DefaultSignatureAlgorithm if no algorithm is specified.

Overrides:

SymmetricKey.signAsync(final byte[] digest, final String algorithm)

Parameters:

digest - The digest to sign

algorithm - The signature algorithm to use

Returns:

A ListenableFuture containing the signature and the algorithm used.

Throws:

NoSuchAlgorithmException - the algorithm is not valid

unwrapKeyAsync

public ListenableFuture unwrapKeyAsync(final byte[] encryptedKey, final String algorithm)

Unwraps (decrypts) the specified encryped key material.

Overrides:

SymmetricKey.unwrapKeyAsync(final byte[] encryptedKey, final String algorithm)

Parameters:

encryptedKey - The encrypted key to decrypt

algorithm - The algorithm to use, must be supplied

Returns:

A ListenableFuture containing the unwrapped key

Throws:

NoSuchAlgorithmException - the algorithm is not valid

verifyAsync

public ListenableFuture verifyAsync(final byte[] digest, final byte[] signature, final String algorithm)

Verifies the supplied signature value using the supplied digest and algorithm.

Overrides:

SymmetricKey.verifyAsync(final byte[] digest, final byte[] signature, final String algorithm)

Parameters:

digest - The digest input

signature - The signature to verify

algorithm - The algorithm to use, must be provided

Returns:

A ListenableFuture containing the signature and the algorithm used.

Throws:

NoSuchAlgorithmException - the algorithm is not valid

wrapKeyAsync

public ListenableFuture> wrapKeyAsync(final byte[] key, final String algorithm)

Wraps (encrypts) the specified symmetric key material using the specified algorithm, or the keys DefaultKeyWrapAlgorithm if none is specified.

Overrides:

SymmetricKey.wrapKeyAsync(final byte[] key, final String algorithm)

Parameters:

key - The symmetric key to wrap

algorithm - The wrapping algorithm to use, defaults to the keys DefaultKeyWrapAlgorithm

Returns:

ListenableFuture containing the encrypted key and the algorithm that was used

Throws:

NoSuchAlgorithmException - the algorithm is not valid