Client-Side Encryption for Microsoft Azure Storage – Preview

Welcome to the preview of the new Azure Storage Client Library for .NET.  This preview contains new functionality to help developers encrypt their data inside client applications before uploading to Azure Storage, and also to decrypt it while downloading. We also support integration with Azure Key Vault in order to let you store and manage your keys. Client-side encryption has been a common request from the Azure Storage developer community, and so we are happy to put it in your hands for feedback.

Why use client-side encryption?

Client-side encryption offers one significant advantage that server side encryption cannot guarantee: you (the user) completely control the keys.  In fact, the storage service never sees the keys and is incapable of decrypting the data.  This gives you the most control you can have.  It’s also fully transparent – our library is open source and on GitHub, and so you can inspect exactly how the library is encrypting your data to ensure that it meets your standards.

Why are we delivering a library with client-side encryption support?

While any developer can encrypt their data client side prior to uploading it, each developer would have to become an encryption expert.  Not only that, but they would need to design for performance and security.  In the end, a lot of developers would have to do the same work repeatedly.  Not only that, but in the end, since each solution would be different, none of them would work together.

We wanted to provide a library that would accomplish the following:

  • Implement Security Best Practices.  This library has been thoroughly reviewed for its security, so that you can use it with confidence.
  • Design for Performance.  We’ve designed to keep your application running quick.
  • Ease of use for common scenarios: We’ve tried to cover the most common scenarios in a way that would be easy for developers to pick up.  While we may support more scenarios in the future, we won’t do it at the expense of usability of the library.
  • Interoperability across languages.  Many users use more than one of our client libraries, and our goal is to use the same technical design across implementations, so that data encrypted using the .NET library can be decrypted using the Java library.  This first preview is focused on .NET, but we will add this support to more languages as we move forward.

What’s available now?

In our first release, we support encryption for blobs, tables, and queues.  All of them use the envelope technique. Encryption and decryption with asymmetric keys is computationally expensive. Therefore, in the envelope technique, the data itself is not encrypted directly with such keys but instead encrypted using a random symmetric content encryption key. This content encryption key is then encrypted using a public key. We also have support for integrating with Azure Key Vault so you can manage your keys efficiently.

Using client-side encryption is easy. All you need to do is hook up request options with the appropriate encryption policy (Blob, Queue, and Table) and pass it to data upload/download APIs. The client library will internally take care of encrypting data on the client when uploading to Azure Storage, and automatically decrypts it when data is retrieved. You can find more details and code samples in the Getting Started with Client-Side Encryption for Microsoft Azure Storage article.

Goodness –

  • Security – Encrypted data is not readable even if the customers storage account keys are compromised
  • Fixed overhead encryption – We have used a technique where there is a fixed overhead so that your encrypted data will have a predictable size based on the original size.
  • Self-contained encryption – Every blob, table entity, or queue message has all encryption metadata stored in either the object or its metadata.  There is no need to get any additional data from anywhere else, except for the key you used.
  • Interoperability – Data encrypted using .NET client can be decrypted by clients using other languages like Java, Node.js, C++.  We will be providing support in languages beyond .NET in the future.
  • Blobs
    • Full blob upload – Files like documents, photos, and videos that are going to be uploaded in entirety are supported.
    • Full or Range blob download – Of course, you can also download the blob in its entirety, but sometimes, files like mp3 are downloaded in ranges depending on the part that is to be played. Therefore, range downloads are allowed and are entirely taken care of by the SDK internally.
    • Key Rotation – We’ve made it simple and straightforward for users to rotate keys themselves. i.e. multiple keys will be supported during the key rotation timeframe.
    • Clean upgrade path – Additional encryption algorithms and protocol versions can be supported in the future without needing significant changes – the design expects these to happen.

Points to be aware of –

  • This is a preview!  It should not be used for production data.  You should expect that changes will be made that will affect the schemas to be used and therefore not be able to read data written with the first preview.
  • It is easy to corrupt data on the blob service or make it un-readable – If you do blob update operations WritePages/ClearPages, PutBlock etc once you have written an encrypted blob, you may end up corrupting the encrypted blob making it unreadable.  For encryption, you should only use full blob upload commands and range/full blob download commands.
  • For tables, a similar constraint exists – be careful to not update encrypted properties without updating the encryption metadata.
  • Also, if you do a SetMetadata on the encrypted blob (since set metadata is not additive), it can wipe out all encryption related metadata required for decryption. Same with snapshots – specifying metadata while creating a snapshot of an encrypted blob.

Why a preview?

We want to get your feedback on design, ease of use and any additional scenarios you would like to tell us about.  This will enable us to actually use that feedback in shaping the final library.  We are open to your feedback and want to know where we can improve this functionality before releasing it.  Requests for additional functionality may not be reflected in the first release, but we want those too!


Getting Started with Client-Side Encryption for Microsoft Azure Storage
Download the Azure Storage Client Library for .NET NuGet package
Download the Azure Storage Client Library for .NET Source Code from GitHub


The Azure Storage Team

Comments (3)

  1. Rohit says:

    Is there any plan to enable encryption decryption functionality from JS?

  2. Jason Hogg says:

    Hi Rohit. Not write now. Can you provide more information on your scenario please or email me at JAHOGG at

  3. Maarten says:

    This is great! I'm actually missing one thing though. We have a scenario where users don't use the client SDK, but just use their browser and other tools to download blobs. It would be great to use this library to encrypt blobs "at rest". However for users to consume these blobs, we'd have to decrypt them on our webserver and then stream them to the clients that have no SDK. Will there be support for some sort of shared access token so downloads can be handled by the blob storage service directly? (ping me on corpnet if needed, maballia)

Skip to main content