CryptographyClient Class

Performs cryptographic operations using Azure Key Vault keys.

This client will perform operations locally when it's intialized with the necessary key material or is able to get that material from Key Vault. When the required key material is unavailable, cryptographic operations are performed by the Key Vault service.

Create a CryptographyClient

   # create a CryptographyClient using a KeyVaultKey instance
   key = await key_client.get_key(key_name)
   crypto_client = CryptographyClient(key, credential)

   # or a key's id, which must include a version
   key_id = "https://<your vault>.vault.azure.net/keys/<key name>/fe4fdcab688c479a9aa80f01ffeac26"
   crypto_client = CryptographyClient(key_id, credential)

   # the client and credential should be closed when no longer needed
   # (both are also async context managers)
   await crypto_client.close()
   await credential.close()

Inheritance

azure.keyvault.keys._shared.async_client_base.AsyncKeyVaultClientBase

CryptographyClient

Constructor

CryptographyClient(key: Union[KeyVaultKey, str], credential: AsyncTokenCredential, **kwargs: Any)

Parameters

key

str or KeyVaultKey

Required

Either a KeyVaultKey instance as returned by get_key, or a string. If a string, the value must be the identifier of an Azure Key Vault key. Including a version is recommended.

credential

Required

An object which can provide an access token for the vault, such as a credential from aio

api_version

ApiVersion

version of the Key Vault API to use. Defaults to the most recent.

transport

AsyncHttpTransport

transport to use. Defaults to AioHttpTransport.

Methods

decrypt	Decrypt a single block of encrypted data using the client's key. Requires the keys/decrypt permission. This method decrypts only a single block of data, whose size depends on the key and encryption algorithm. Decrypt bytes from azure.keyvault.keys.crypto import EncryptionAlgorithm result = await client.decrypt(EncryptionAlgorithm.rsa_oaep, ciphertext) print(result.plaintext)
encrypt	Encrypt bytes using the client's key. Requires the keys/encrypt permission. This method encrypts only a single block of data, whose size depends on the key and encryption algorithm. Encrypt bytes from azure.keyvault.keys.crypto import EncryptionAlgorithm # the result holds the ciphertext and identifies the encryption key and algorithm used result = await client.encrypt(EncryptionAlgorithm.rsa_oaep, b"plaintext") print(result.key_id) print(result.algorithm) ciphertext = result.ciphertext
from_jwk	Creates a client that can only perform cryptographic operations locally.
sign	Create a signature from a digest using the client's key. Requires the keys/sign permission. Sign bytes import hashlib from azure.keyvault.keys.crypto import SignatureAlgorithm digest = hashlib.sha256(b"plaintext").digest() # sign returns the signature and the metadata required to verify it result = await client.sign(SignatureAlgorithm.rs256, digest) print(result.key_id) print(result.algorithm) signature = result.signature
unwrap_key	Unwrap a key previously wrapped with the client's key. Requires the keys/unwrapKey permission. Unwrap a key from azure.keyvault.keys.crypto import KeyWrapAlgorithm result = await client.unwrap_key(KeyWrapAlgorithm.rsa_oaep, encrypted_key)
verify	Verify a signature using the client's key. Requires the keys/verify permission. Verify a signature from azure.keyvault.keys.crypto import SignatureAlgorithm verified = await client.verify(SignatureAlgorithm.rs256, digest, signature) assert verified.is_valid
wrap_key	Wrap a key with the client's key. Requires the keys/wrapKey permission. Wrap a key from azure.keyvault.keys.crypto import KeyWrapAlgorithm # wrap returns a tuple with the wrapped bytes and the metadata required to unwrap the key result = await client.wrap_key(KeyWrapAlgorithm.rsa_oaep, key_bytes) print(result.key_id) print(result.algorithm) encrypted_key = result.encrypted_key

decrypt

Decrypt a single block of encrypted data using the client's key.

Requires the keys/decrypt permission. This method decrypts only a single block of data, whose size depends on the key and encryption algorithm.

Decrypt bytes

   from azure.keyvault.keys.crypto import EncryptionAlgorithm

   result = await client.decrypt(EncryptionAlgorithm.rsa_oaep, ciphertext)
   print(result.plaintext)

async decrypt(algorithm: EncryptionAlgorithm, ciphertext: bytes, **kwargs: Any) -> azure.keyvault.keys.crypto._models.DecryptResult

Parameters

algorithm

EncryptionAlgorithm

Required

encryption algorithm to use

ciphertext

bytes

Required

encrypted bytes to decrypt

iv

bytes

the initialization vector used during encryption. Required for AES decryption.

authentication_tag

bytes

the authentication tag generated during encryption. Required for only AES-GCM decryption.

additional_authenticated_data

bytes

optional data that is authenticated but not encrypted. For use with AES-GCM decryption.

Return type

DecryptResult

Exceptions

ValueError

if parameters that are incompatible with the specified algorithm are provided.

encrypt

Encrypt bytes using the client's key.

Requires the keys/encrypt permission. This method encrypts only a single block of data, whose size depends on the key and encryption algorithm.

Encrypt bytes

   from azure.keyvault.keys.crypto import EncryptionAlgorithm

   # the result holds the ciphertext and identifies the encryption key and algorithm used
   result = await client.encrypt(EncryptionAlgorithm.rsa_oaep, b"plaintext")
   print(result.key_id)
   print(result.algorithm)
   ciphertext = result.ciphertext

async encrypt(algorithm: EncryptionAlgorithm, plaintext: bytes, **kwargs: Any) -> azure.keyvault.keys.crypto._models.EncryptResult

Parameters

algorithm

EncryptionAlgorithm

Required

encryption algorithm to use

plaintext

bytes

Required

bytes to encrypt

iv

bytes

initialization vector. Required for only AES-CBC(PAD) encryption.

additional_authenticated_data

bytes

optional data that is authenticated but not encrypted. For use with AES-GCM encryption.

Return type

EncryptResult

Exceptions

ValueError

if parameters that are incompatible with the specified algorithm are provided.

from_jwk

Creates a client that can only perform cryptographic operations locally.

from_jwk(jwk: Union[JsonWebKey, dict]) -> CryptographyClient

Parameters

jwk

JsonWebKey or dict

Required

the key's cryptographic material, as a JsonWebKey or dictionary.

jwk

Required

Return type

CryptographyClient

Exceptions

ValueError

if parameters that are incompatible with the specified algorithm are provided.

sign

Create a signature from a digest using the client's key.

Requires the keys/sign permission.

Sign bytes

   import hashlib
   from azure.keyvault.keys.crypto import SignatureAlgorithm

   digest = hashlib.sha256(b"plaintext").digest()

   # sign returns the signature and the metadata required to verify it
   result = await client.sign(SignatureAlgorithm.rs256, digest)
   print(result.key_id)
   print(result.algorithm)
   signature = result.signature

async sign(algorithm: SignatureAlgorithm, digest: bytes, **kwargs: Any) -> azure.keyvault.keys.crypto._models.SignResult

Parameters

algorithm

SignatureAlgorithm

Required

signing algorithm

digest

bytes

Required

hashed bytes to sign

Return type

SignResult

Exceptions

ValueError

if parameters that are incompatible with the specified algorithm are provided.

unwrap_key

Unwrap a key previously wrapped with the client's key.

Requires the keys/unwrapKey permission.

Unwrap a key

   from azure.keyvault.keys.crypto import KeyWrapAlgorithm

   result = await client.unwrap_key(KeyWrapAlgorithm.rsa_oaep, encrypted_key)

async unwrap_key(algorithm: KeyWrapAlgorithm, encrypted_key: bytes, **kwargs: Any) -> azure.keyvault.keys.crypto._models.UnwrapResult

Parameters

algorithm

KeyWrapAlgorithm

Required

wrapping algorithm to use

encrypted_key

bytes

Required

the wrapped key

Return type

UnwrapResult

Exceptions

ValueError

if parameters that are incompatible with the specified algorithm are provided.

verify

Verify a signature using the client's key.

Requires the keys/verify permission.

Verify a signature

   from azure.keyvault.keys.crypto import SignatureAlgorithm

   verified = await client.verify(SignatureAlgorithm.rs256, digest, signature)
   assert verified.is_valid

async verify(algorithm: SignatureAlgorithm, digest: bytes, signature: bytes, **kwargs: Any) -> azure.keyvault.keys.crypto._models.VerifyResult

Parameters

algorithm

SignatureAlgorithm

Required

verification algorithm

digest

bytes

Required

Pre-hashed digest corresponding to signature. The hash algorithm used must be compatible with algorithm.

signature

bytes

Required

signature to verify

Return type

VerifyResult

Exceptions

ValueError

if parameters that are incompatible with the specified algorithm are provided.

wrap_key

Wrap a key with the client's key.

Requires the keys/wrapKey permission.

Wrap a key

   from azure.keyvault.keys.crypto import KeyWrapAlgorithm

   # wrap returns a tuple with the wrapped bytes and the metadata required to unwrap the key
   result = await client.wrap_key(KeyWrapAlgorithm.rsa_oaep, key_bytes)
   print(result.key_id)
   print(result.algorithm)
   encrypted_key = result.encrypted_key

async wrap_key(algorithm: KeyWrapAlgorithm, key: bytes, **kwargs: Any) -> azure.keyvault.keys.crypto._models.WrapResult

Parameters

algorithm

KeyWrapAlgorithm

Required

wrapping algorithm to use

key

bytes

Required

key to wrap

Return type

WrapResult

Exceptions

ValueError

if parameters that are incompatible with the specified algorithm are provided.

Attributes

key_id

The full identifier of the client's key.

This property may be None when a client is constructed with from_jwk.

Return type

str,

None

vault_url

The base vault URL of the client's key.

This property may be None when a client is constructed with from_jwk.

Return type

str,

None