Delen via

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.

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://free.blessedness.top/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.

Default value: None
authentication_tag
bytes or None

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

Default value: None
additional_authenticated_data
bytes or None

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

Default value: None

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.

Default value: None
additional_authenticated_data
bytes or None

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

Default value: None

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.

Default value: 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.