azure.keyvault.keys.crypto.aio package¶

class azure.keyvault.keys.crypto.aio.CryptographyClient(key: Union[KeyVaultKey, str], credential: AsyncTokenCredential, **kwargs: Any)[source]¶

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.

Parameters

key (str or KeyVaultKey) – 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 – An object which can provide an access token for the vault, such as a credential from azure.identity.aio

Keyword Arguments

api_version (ApiVersion) – version of the Key Vault API to use. Defaults to the most recent.
transport (AsyncHttpTransport) – transport to use. Defaults to AioHttpTransport.

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()

async close() → None ¶

Close sockets opened by the client.

Calling this method is unnecessary when using the client as a context manager.

async decrypt(algorithm: EncryptionAlgorithm, ciphertext: bytes, **kwargs: Any) → azure.keyvault.keys.crypto._models.DecryptResult[source]¶

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.

Parameters

algorithm (EncryptionAlgorithm) – encryption algorithm to use
ciphertext (bytes) – encrypted bytes to decrypt

Keyword Arguments

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

Raises

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

Decrypt bytes¶

from azure.keyvault.keys.crypto import EncryptionAlgorithm

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

async encrypt(algorithm: EncryptionAlgorithm, plaintext: bytes, **kwargs: Any) → azure.keyvault.keys.crypto._models.EncryptResult[source]¶

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.

Parameters

algorithm (EncryptionAlgorithm) – encryption algorithm to use
plaintext (bytes) – bytes to encrypt

Keyword Arguments

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

Raises

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

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

classmethod from_jwk(jwk: Union[JsonWebKey, dict]) → CryptographyClient [source]¶

Creates a client that can only perform cryptographic operations locally.

Parameters: jwk (JsonWebKey or dict) – the key’s cryptographic material, as a JsonWebKey or dictionary.
Return type: CryptographyClient

async sign(algorithm: SignatureAlgorithm, digest: bytes, **kwargs: Any) → azure.keyvault.keys.crypto._models.SignResult[source]¶

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

Requires the keys/sign permission.

Parameters

algorithm (SignatureAlgorithm) – signing algorithm
digest (bytes) – hashed bytes to sign

Return type

SignResult

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 unwrap_key(algorithm: KeyWrapAlgorithm, encrypted_key: bytes, **kwargs: Any) → azure.keyvault.keys.crypto._models.UnwrapResult[source]¶

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

Requires the keys/unwrapKey permission.

Parameters

algorithm (KeyWrapAlgorithm) – wrapping algorithm to use
encrypted_key (bytes) – the wrapped key

Return type

UnwrapResult

Unwrap a key¶

from azure.keyvault.keys.crypto import KeyWrapAlgorithm

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

async verify(algorithm: SignatureAlgorithm, digest: bytes, signature: bytes, **kwargs: Any) → azure.keyvault.keys.crypto._models.VerifyResult[source]¶

Verify a signature using the client’s key.

Requires the keys/verify permission.

Parameters

algorithm (SignatureAlgorithm) – verification algorithm
digest (bytes) – Pre-hashed digest corresponding to signature. The hash algorithm used must be compatible with algorithm.
signature (bytes) – signature to verify

Return type

VerifyResult

Verify a signature¶

from azure.keyvault.keys.crypto import SignatureAlgorithm

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

async wrap_key(algorithm: KeyWrapAlgorithm, key: bytes, **kwargs: Any) → azure.keyvault.keys.crypto._models.WrapResult[source]¶

Wrap a key with the client’s key.

Requires the keys/wrapKey permission.

Parameters

algorithm (KeyWrapAlgorithm) – wrapping algorithm to use
key (bytes) – key to wrap

Return type

WrapResult

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

property 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 or None

property 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 or None

class azure.keyvault.keys.crypto.aio.EncryptResult(key_id: Optional[str], algorithm: EncryptionAlgorithm, ciphertext: bytes, **kwargs: Any)[source]¶

The result of an encrypt operation.

Parameters

key_id (str) – The encryption key’s Key Vault identifier
algorithm (EncryptionAlgorithm) – The encryption algorithm used
ciphertext (bytes) – The encrypted bytes

Keyword Arguments

iv (bytes) – Initialization vector for symmetric algorithms
authentication_tag (bytes) – The tag to authenticate when performing decryption with an authenticated algorithm
additional_authenticated_data (bytes) – Additional data to authenticate but not encrypt/decrypt when using an authenticated algorithm

class azure.keyvault.keys.crypto.aio.EncryptionAlgorithm(value)[source]¶

Encryption algorithms

a128_cbc = 'A128CBC'¶

a128_cbcpad = 'A128CBCPAD'¶

a128_gcm = 'A128GCM'¶

a192_cbc = 'A192CBC'¶

a192_cbcpad = 'A192CBCPAD'¶

a192_gcm = 'A192GCM'¶

a256_cbc = 'A256CBC'¶

a256_cbcpad = 'A256CBCPAD'¶

a256_gcm = 'A256GCM'¶

rsa1_5 = 'RSA1_5'¶

rsa_oaep = 'RSA-OAEP'¶

rsa_oaep_256 = 'RSA-OAEP-256'¶

class azure.keyvault.keys.crypto.aio.KeyWrapAlgorithm(value)[source]¶

Key wrapping algorithms

aes_128 = 'A128KW'¶

aes_192 = 'A192KW'¶

aes_256 = 'A256KW'¶

rsa1_5 = 'RSA1_5'¶

rsa_oaep = 'RSA-OAEP'¶

rsa_oaep_256 = 'RSA-OAEP-256'¶

class azure.keyvault.keys.crypto.aio.SignResult(key_id: Optional[str], algorithm: SignatureAlgorithm, signature: bytes)[source]¶

The result of a sign operation.

Parameters

key_id (str) – The signing key’s Key Vault identifier
algorithm (SignatureAlgorithm) – The signature algorithm used
signature (bytes) –

class azure.keyvault.keys.crypto.aio.SignatureAlgorithm(value)[source]¶

Signature algorithms, described in https://tools.ietf.org/html/rfc7518

es256 = 'ES256'¶: ECDSA using P-256 and SHA-256

es256_k = 'ES256K'¶: ECDSA using P-256K and SHA-256

es384 = 'ES384'¶: ECDSA using P-384 and SHA-384

es512 = 'ES512'¶: ECDSA using P-521 and SHA-512

ps256 = 'PS256'¶: RSASSA-PSS using SHA-256 and MGF1 with SHA-256

ps384 = 'PS384'¶: RSASSA-PSS using SHA-384 and MGF1 with SHA-384

ps512 = 'PS512'¶: RSASSA-PSS using SHA-512 and MGF1 with SHA-512

rs256 = 'RS256'¶: RSASSA-PKCS1-v1_5 using SHA-256

rs384 = 'RS384'¶: RSASSA-PKCS1-v1_5 using SHA-384

rs512 = 'RS512'¶: RSASSA-PKCS1-v1_5 using SHA-512

class azure.keyvault.keys.crypto.aio.WrapResult(key_id: Optional[str], algorithm: KeyWrapAlgorithm, encrypted_key: bytes)[source]¶

The result of a wrap key operation.

Parameters

key_id (str) – The wrapping key’s Key Vault identifier
algorithm (KeyWrapAlgorithm) – The key wrap algorithm used
encrypted_key (bytes) – The encrypted key bytes