Client provided keys with Azure Storage server-side encryption

Microsoft Azure Storage offers several options to encrypt data at rest. With client-side encryption you can encrypt data prior to uploading it to Azure Storage. You can also choose to have Azure Storage manage encryption operations with server-side encryption using Microsoft managed keys or using customer managed keys in Microsoft Azure Key vault. Today, we present enhancement to server-side encryption to support granular encryption settings on storage account with keys hosted in any key store. Client provided key (CPK) enables you to store and manage keys in on-premises or key stores other than Azure Key Vault to meet corporate, contractual and regulatory compliance requirements for data security.

Client provided keys allows you to pass an encryption key as part of read or write operation to storage service using blob APIs. When you create a blob with a client provided key, the storage service persists the SHA-256 hash of the encryption key with the blob to validate future requests. When you retrieve an object, you must provide the same encryption key as part of the request. For example, if a blob is created with Put Blob, all subsequent write operations must provide the same encryption key. If a different key is provided, or if no key is provided in the request, the operation will fail with 400 Bad Request. As the encryption key itself is provided in the request, a secure connection must be established to transfer the key. Here’s the process:


Figure 1: Client provided keys

Getting started

Client provided keys may be used with supported blob operations by adding the x-ms-encryption-* headers to the request.

Request Header



Required. A Base64-encoded AES-256 encryption key value.


Required. The Base64-encoded SHA256 of the encryption key.


Required. Specifies the algorithm to use when encrypting data using the given key. Must be AES256.


PUT mycontainer/myblob.txt
x-ms-version: 2019-02-02
x-ms-encryption-key: MDEyMzQ1NjcwMTIzNDU2NzAxMjM0NTY3MDEyMzQ1Njc=
x-ms-encryption-key-sha256: 3QFFFpRA5+XANHqwwbT4yXDmrT/2JaLt/FKHjzhOdoE=
x-ms-encryption-algorithm: AES256
Content-Length: <length>

Key Management

Azure Storage does not store or manage client provided encryption keys. Keys are securely discarded as soon as possible after they’ve been used to encrypt or decrypt the blob data. If client provided keys are used on blobs with snapshots enabled, each snapshot can be provisioned with different encryption key. You must keep track of snapshot and associated encryption key to pass the correct key with blob operations. If you need to rotate the key associated with an object, you can use copy blob operation to pass old and new keys as headers as shown below.


PUT mycontainer/myblob.txt
x-ms-source-encryption-key: MDEyMzQ1NjcwMTIzNDU2NzAxMjM0NTY3MDEyMzQ1Njc=
x-ms-source-encryption-key-sha256: 3QFFFpRA5+XANHqwwbT4yXDmrT/2JaLt/FKHjzhOdoE=
x-ms-source-encryption-algorithm: AES256
x-ms-encryption-key: NzY1NDMyMTA3NjU0MzIxMDc2NTQzMjEwNzY1NDMyMTA=
x-ms-encryption-key-sha256: uYo4dwqNEIFWjJ5tWAlTJWSrfdY2QIH5UF9IHYNRqyo=
x-ms-encryption-algorithm: AES256

Next Steps

This feature is available now on your storage account with recent release of Storage Services REST API (version 2019-02-02). You may also use .NET client library and Java client library.

For more information on client provided keys please visit our documentation page. For any further questions, or to discuss your specific scenario, send us an email at or post your ideas and suggestions about Azure Storage on our feedback forum.

Source: Azure Blog Feed

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.