azure.keyvault.keys.crypto package

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

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

Keyword Arguments

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

• transport (HttpTransport) – transport to use. Defaults to RequestsTransport.

Create a CryptographyClient

# create a CryptographyClient using a KeyVaultKey instance
key = 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)

close() → None

Close sockets opened by the client.

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

decrypt(algorithm: EncryptionAlgorithm, ciphertext: bytes, **kwargs: Any) → DecryptResult

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 = client.decrypt(EncryptionAlgorithm.rsa_oaep, ciphertext)
print(result.plaintext)

encrypt(algorithm: EncryptionAlgorithm, plaintext: bytes, **kwargs: Any) → EncryptResult

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 = client.encrypt(EncryptionAlgorithm.rsa_oaep, b"plaintext")
ciphertext = result.ciphertext
print(result.key_id)
print(result.algorithm)

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

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

sign(algorithm: SignatureAlgorithm, digest: bytes, **kwargs: Any) → SignResult

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 = client.sign(SignatureAlgorithm.rs256, digest)
print(result.key_id)
print(result.algorithm)
signature = result.signature

unwrap_key(algorithm: KeyWrapAlgorithm, encrypted_key: bytes, **kwargs: Any) → UnwrapResult

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 = client.unwrap_key(KeyWrapAlgorithm.rsa_oaep, encrypted_key)
key = result.key

verify(algorithm: SignatureAlgorithm, digest: bytes, signature: bytes, **kwargs: Any) → VerifyResult

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

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

wrap_key(algorithm: KeyWrapAlgorithm, key: bytes, **kwargs: Any) → WrapResult

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

# the result holds the encrypted key and identifies the encryption key and algorithm used
result = client.wrap_key(KeyWrapAlgorithm.rsa_oaep, key_bytes)
encrypted_key = result.encrypted_key
print(result.key_id)
print(result.algorithm)

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.DecryptResult(key_id: Optional[str], algorithm: EncryptionAlgorithm, plaintext: bytes)

The result of a decrypt operation.

Parameters

• key_id (str) – The encryption key’s Key Vault identifier

• algorithm (EncryptionAlgorithm) – The encryption algorithm used

• plaintext (bytes) – The decrypted bytes

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

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.EncryptionAlgorithm(value)

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.KeyWrapAlgorithm(value)

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.SignResult(key_id: Optional[str], algorithm: SignatureAlgorithm, signature: bytes)

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.SignatureAlgorithm(value)

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.UnwrapResult(key_id: Optional[str], algorithm: KeyWrapAlgorithm, key: bytes)

The result of an unwrap key operation.

Parameters

• key_id (str) – Key encryption key’s Key Vault identifier

• algorithm (KeyWrapAlgorithm) – The key wrap algorithm used

• key (bytes) – The unwrapped key

class azure.keyvault.keys.crypto.VerifyResult(key_id: Optional[str], is_valid: bool, algorithm: SignatureAlgorithm)

The result of a verify operation.

Parameters

• key_id (str) – The signing key’s Key Vault identifier

• is_valid (bool) – Whether the signature is valid

• algorithm (SignatureAlgorithm) – The signature algorithm used

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

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

Subpackages

• azure.keyvault.keys.crypto.aio package