Azure Encryption Extensions is a simple library designed to streamline the work required to encrypt data stored in Azure Blob Storage. Data is encrypted on-the-fly as it is uploaded to Azure, and decrypted as it is downloaded. Unencrypted data never leaves your machine and you can manage your keys however you'd like.
For the nuget package: https://www.nuget.org/packages/AzureEncryptionExtensions/
PM> Install-Package AzureEncryptionExtensions
Azure Encryption Extensions currently contains two providers, an AsymmetricBlobCryptoProvider and a SymmetricBlobCryptoProvider. These provide the choice between symmetric AES encryption or asymmetric RSA encryption. To ensure performance for large files the asymmetric provider internally encrypts data with AES256 based on a randomly generated key which is encrypted with RSA and prepended on the blob stream. This provides the benefits of public/private key management with the speed of symmetric encryption.
In both cases the .NET framework Cryptographic Service Providers provide the underlying implementation.
The library provides extensions for ICloudBlob which are identical to the existing methods, but with the addition of an encryption provider parameter. This makes it trivial to modify existing Azure Storage code to add encryption without refactoring.
Make sure you add the appropriate using statements.
using AzureEncryptionExtensions;
using AzureEncryptionExtensions.Providers;Typical use is simple - create a provider and leverage one of the extension methods for uploading or download blobs instead of the standard ICloudBlob methods.
Here we encrypt a blob using an X509Certificate2 as our key:
CloudBlockBlob blob = container.GetBlockBlobReference("TestBlob");
// Create an Asymmetric provider from an X509Certificate2
var provider = new AsymmetricBlobCryptoProvider(certificate);
// Encrypt and upload the file to Azure, passing in our provider
blob.UploadFromFileEncrypted(provider, path, FileMode.Open);
// Download and decrypt the file
blob.DownloadToFileEncrypted(provider, destinationPath, FileMode.Create);Additional samples are available in the AzureEncryptionSample project in the repository.
The library attempts to make usage simple by mimicking existing commonly used BlockBlob methods. Currently four methods are implemented for working with files and streams. Files and streams are encrypted and decrypted on-the-fly without creating temporary files.
Method signatures match the existing Microsoft.WindowsAzure.Storage ICloudBlob with the addition of a IBlobCrytoProvider parameter.
To use the extension methods, add the appropriate using to your code:
using AzureEncryptionExtensions;| Method |
|---|
| UploadFromFileEncrypted(...) |
| UploadFromStreamEncrypted(...) |
| DownloadToFileEncrypted(...) |
| DownloadToStreamEncrypted(...) |
All extension methods provided by Azure Encryption Extensions require an IBlobCryptoProvider instance to do the underlying encryption, decryption and key management.
Providers are very easy to instantiate from existing key material and in all cases are capable of generating cryptographically random key material for you if instantiated with an empty constructor.
To provide additional options for key management all providers also implement WriteKeyFile(string path) and ToKeyFileString() methods which will serialize the key material to a JSON blob for easy storage and future use. You do not need to use these, and can instead use convenience constructors to create providers from x509certificates or byte arrays if you prefer.
Using the data generated by these methods you can recreate a provider at any time using the provider factory:
var provider = ProviderFactory.CreateProviderFromKeyFile("exported_key_data.txt");or
var provider = ProviderFactory.CreateProviderFromKeyFileString(jsonString);###AsymmetricBlobCryptoProvider
The AsymmetricBlobCryptoProvider provides encryption when you prefer to use a Public-Private Key pair, such as an X509 certificate. This provider allows you to encrypt data with the public key, and decrypt data with the private key. It is useful in scenarios where you want to let systems encrypt data but not give them access to decrypt it. You can share the public (encryption) key broadly while maintaining the security of your data by protecting the private (decryption) key.
The provider can be instantiated with X509Certificate2, a byte array, a previously exported JSON keyfile, or can generate a key pair for you.
This provider provides fast encryption by first encrypting your data with a crytographically random 256 bit key using AES. This random key is then encrypted using RSA and your key-pair. The RSA encrypted key is prepended to the AES encrypted stream so that it can be recovered as part of the decryption process. This all happens directly on the stream as it is read/written with no seperate buffering or disk access.
A crytographically random IV is prepended to the data for every blob written, and neither the IV or the AES key are reused for any other blobs.
| Constructor | Description |
|---|---|
| AsymmetricBlobCryptoProvider() | Will generate a crytographically random 4096bit RSA key-pair for you. You must save the key material for future decryption using WriteKeyFile(...) or similar. |
| AsymmetricBlobCryptoProvider(byte[] cspBlob) | Loads a key from another source, such as X509Certificate2.ExportCspBlob(). Will load private key if provided. If only public key is provided decryption methods will throw an exception but encryption methods will succeed. |
| AsymmetricBlobCryptoProvider(X509Certificate2 certificate, [bool loadPrivateKeyIfAvailable]) | Load key from certificate. Optionally specify if private key should be loaded (if available). By default both public and private key are loaded if provided. |
Regardless of how the provider was instantiated, any of the following methods may be used to export a simple JSON representation of the key material for easy storage and future creation of compatible providers.
| Method | Description |
|---|---|
| WriteKeyFile(string path) | Write public and private (if available) to file specific by path |
| WriteKeyFile(string path, bool publicOnly) | Write public and optionally private (if available) to file specified by path. |
| ToKeyFileString() | Retrieve JSON blob as string instead of writing to file. |
| ToKeyFileString(bool publicOnly) | Retrieve JSON blob as string instead of writing to file, and optionally limit inclusion of private key |
###SymmetricBlobCryptoProvider
The SymmetricBlobCryptoProvider is designed for scenarios where you prefer to use the same key for encryption and decryption. This is often more simple to manage, and performs better than the asymmetric option. The provider performs industry standard AES encryption. Default key size is 256bit/32 byte and the Initialization Vector is 16 random bytes unique to each blob. You may also provide keys of length 16 bytes or 24 bytes.
The provider can be instantiated with a byte array or a previously exported JSON keyfile, or can generate a secure random key for you.
| Constructor | Description |
|---|---|
| SymmetricBlobCryptoProvider() | Will generate a crytographically random 256bit key for you. You must save the key material for future decryption using WriteKeyFile(...) or similar. |
| SymmetricBlobCryptoProvider(byte[] key) | Loads a key from a byte array. 16, 24, or 32 bytes. |
Regardless of how the provider was instantiated, any of the following methods may be used to export a simple JSON representation of the key material for easy storage and future creation of compatible providers.
| Method | Description |
|---|---|
| WriteKeyFile(string path) | Write public and private (if available) to file specific by path |
| ToKeyFileString() | Retrieve JSON blob as string instead of writing to file. |
###ProviderFactory
The ProviderFactory simply offers utility methods to trivially recreate a provider from a previously exported JSON keyfile or string. It will detect the provider type and create an instance for you to pass to any of the extension methods.
| Method | Description |
|---|---|
| IBlobCryptoProvider CreateProviderFromKeyFileString(string keyFileData) | Create provider from JSON string. |
| IBlobCryptoProvider CreateProviderFromKeyFile(string keyFilePath) | Create provider from JSON file. |
// Create an Azure Encryption Extensions symmetric encryption provider
// We are not passing any key material so a 256-bit AES key will be generated for us.
var provider = new SymmetricBlobCryptoProvider();
// Since we let the library generate a new key for us, we need to persist it somewhere
// so we can decrypt our blob later.
provider.WriteKeyFile("symmetricKey.dat");
.... later
// Since we have our AES key exported we can use the provider factory to quickly
// insantiate a provider for working with the key again
var provider = ProviderFactory.CreateProviderFromKeyFile("symmetricKey.dat");