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.

Inheritance

azure.keyvault.keys._shared.client_base.KeyVaultClientBase

CryptographyClient

Constructor

CryptographyClient(key: KeyVaultKey | str, credential: TokenCredential, **kwargs: Any)

Parameters

Name	Description
key Required	str or KeyVaultKey Either a azure.keyvault.keys.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	TokenCredential An object which can provide an access token for the vault, such as a credential from identity

Keyword-Only Parameters

Name	Description
api_version	ApiVersion or str Version of the service API to use. Defaults to the most recent.
verify_challenge_resource	bool Whether to verify the authentication challenge resource matches the Key Vault or Managed HSM domain. Defaults to True.

Methods

close	Close sockets opened by the client. Calling this method is unnecessary when using the client as a context manager.
create_rsa_private_key	Create an RSAPrivateKey implementation backed by this CryptographyClient, as a KeyVaultRSAPrivateKey. The CryptographyClient will attempt to download the key, if it hasn't been already, as part of this operation.
create_rsa_public_key	Create an RSAPublicKey implementation backed by this CryptographyClient, as a KeyVaultRSAPublicKey. The CryptographyClient will attempt to download the key, if it hasn't been already, as part of this operation.
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.
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.
from_jwk	Creates a client that can only perform cryptographic operations locally.
send_request	Runs a network request using the client's existing pipeline. The request URL can be relative to the vault URL. The service API version used for the request is the same as the client's unless otherwise specified. This method does not raise if the response is an error; to raise an exception, call raise_for_status() on the returned response object. For more information about how to send custom requests with this method, see https://aka.ms/azsdk/dpcodegen/python/send_request.
sign	Create a signature from a digest using the client's key. Requires the keys/sign permission.
unwrap_key	Unwrap a key previously wrapped with the client's key. Requires the keys/unwrapKey permission.
verify	Verify a signature using the client's key. Requires the keys/verify permission.
wrap_key	Wrap a key with the client's key. Requires the keys/wrapKey permission.

close

Close sockets opened by the client.

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

close() -> None

create_rsa_private_key

Create an RSAPrivateKey implementation backed by this CryptographyClient, as a KeyVaultRSAPrivateKey.

The CryptographyClient will attempt to download the key, if it hasn't been already, as part of this operation.

create_rsa_private_key() -> KeyVaultRSAPrivateKey

Returns

Type	Description
KeyVaultRSAPrivateKey	A KeyVaultRSAPrivateKey, which implements cryptography's RSAPrivateKey interface.

create_rsa_public_key

Create an RSAPublicKey implementation backed by this CryptographyClient, as a KeyVaultRSAPublicKey.

The CryptographyClient will attempt to download the key, if it hasn't been already, as part of this operation.

create_rsa_public_key() -> KeyVaultRSAPublicKey

Returns

Type	Description
KeyVaultRSAPublicKey	A KeyVaultRSAPublicKey, which implements cryptography's RSAPublicKey interface.

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(algorithm: EncryptionAlgorithm, ciphertext: bytes, *, iv: bytes | None = None, authentication_tag: bytes | None = None, additional_authenticated_data: bytes | None = None, **kwargs: Any) -> DecryptResult

Parameters

Name	Description
algorithm Required	EncryptionAlgorithm Encryption algorithm to use
ciphertext Required	bytes Encrypted bytes to decrypt. Microsoft recommends you not use CBC without first ensuring the integrity of the ciphertext using, for example, an HMAC. See https://docs.microsoft.com/dotnet/standard/security/vulnerabilities-cbc-mode for more information.

Keyword-Only Parameters

Name	Description
iv	bytes or None The initialization vector used during encryption. Required for AES decryption.
authentication_tag	bytes or None The authentication tag generated during encryption. Required for only AES-GCM decryption.
additional_authenticated_data	bytes or None Optional data that is authenticated but not encrypted. For use with AES-GCM decryption.

Returns

Type	Description
DecryptResult	The result of the decryption operation.

Exceptions

Type	Description
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(algorithm: EncryptionAlgorithm, plaintext: bytes, *, iv: bytes | None = None, additional_authenticated_data: bytes | None = None, **kwargs: Any) -> EncryptResult

Parameters

Name	Description
algorithm Required	EncryptionAlgorithm Encryption algorithm to use
plaintext Required	bytes Bytes to encrypt

Keyword-Only Parameters

Name	Description
iv	bytes or None Initialization vector. Required for only AES-CBC(PAD) encryption. If you pass your own IV, make sure you use a cryptographically random, non-repeating IV. If omitted, an attempt will be made to generate an IV via os.urandom for local cryptography; for remote cryptography, Key Vault will generate an IV.
additional_authenticated_data	bytes or None Optional data that is authenticated but not encrypted. For use with AES-GCM encryption.

Returns

Type	Description
EncryptResult	The result of the encryption operation.

Exceptions

Type	Description
ValueError	if parameters that are incompatible with the specified algorithm are provided, or if generating an IV fails on the current platform.

from_jwk

Creates a client that can only perform cryptographic operations locally.

from_jwk(jwk: JsonWebKey | Dict[str, Any]) -> CryptographyClient

Parameters

Name	Description
jwk Required	JsonWebKey or Dict[str, Any] the key's cryptographic material, as a JsonWebKey or dictionary.

Returns

Type	Description
CryptographyClient	A client that can only perform local cryptographic operations.

send_request

Runs a network request using the client's existing pipeline.

The request URL can be relative to the vault URL. The service API version used for the request is the same as the client's unless otherwise specified. This method does not raise if the response is an error; to raise an exception, call raise_for_status() on the returned response object. For more information about how to send custom requests with this method, see https://aka.ms/azsdk/dpcodegen/python/send_request.

send_request(request: HttpRequest, *, stream: bool = False, **kwargs: Any) -> HttpResponse

Parameters

Name	Description
request Required	HttpRequest The network request you want to make.

Keyword-Only Parameters

Name	Description
stream	bool Whether the response payload will be streamed. Defaults to False.

Returns

Type	Description
HttpResponse	The response of your network call. Does not do error handling on your response.

sign

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

Requires the keys/sign permission.

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

Parameters

Name	Description
algorithm Required	SignatureAlgorithm signing algorithm
digest Required	bytes hashed bytes to sign

Returns

Type	Description
SignResult	The result of the signing operation.

unwrap_key

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

Requires the keys/unwrapKey permission.

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

Parameters

Name	Description
algorithm Required	KeyWrapAlgorithm wrapping algorithm to use
encrypted_key Required	bytes the wrapped key

Returns

Type	Description
UnwrapResult	The result of the unwrapping operation.

verify

Verify a signature using the client's key.

Requires the keys/verify permission.

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

Parameters

Name	Description
algorithm Required	SignatureAlgorithm verification algorithm
digest Required	bytes Pre-hashed digest corresponding to signature. The hash algorithm used must be compatible with algorithm.
signature Required	bytes signature to verify

Returns

Type	Description
VerifyResult	The result of the verifying operation.

wrap_key

Wrap a key with the client's key.

Requires the keys/wrapKey permission.

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

Parameters

Name	Description
algorithm Required	KeyWrapAlgorithm wrapping algorithm to use
key Required	bytes key to wrap

Returns

Type	Description
WrapResult	The result of the wrapping operation.

Attributes

key_id

The full identifier of the client's key.

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

Returns

Type	Description
str, None	The full identifier of the client's key.

vault_url

The base vault URL of the client's key.

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

Returns

Type	Description
str, None	The base vault URL of the client's key.