Microsoft.Data.Encryption.Cryptography
2.0.0-pre007
Prefix Reserved
dotnet add package Microsoft.Data.Encryption.Cryptography --version 2.0.0-pre007
NuGet\Install-Package Microsoft.Data.Encryption.Cryptography -Version 2.0.0-pre007
<PackageReference Include="Microsoft.Data.Encryption.Cryptography" Version="2.0.0-pre007" />
paket add Microsoft.Data.Encryption.Cryptography --version 2.0.0-pre007
#r "nuget: Microsoft.Data.Encryption.Cryptography, 2.0.0-pre007"
// Install Microsoft.Data.Encryption.Cryptography as a Cake Addin #addin nuget:?package=Microsoft.Data.Encryption.Cryptography&version=2.0.0-pre007&prerelease // Install Microsoft.Data.Encryption.Cryptography as a Cake Tool #tool nuget:?package=Microsoft.Data.Encryption.Cryptography&version=2.0.0-pre007&prerelease
Overview
Microsoft.Data.Encryption.Cryptography
provides encryption support to applications. It allows developers to implement column- or field-level encryption for data stored in various data stores, including Azure data services.
Features
The library provides APIs for objects like encryption keys, serializers, key store provider interfaces, and associated caches.
The module implements cryptographic operations using a two-level key hierarchy composed of:
- Data Encryption Keys (DEKs) - symmetric keys that encrypt data.
- Key Encryption Keys (KEKs) - asymmetric keys that encrypt DEKs.
The Cryptography module uses cryptographic algorithms that are fully compatible with Always Encrypted in Azure SQL. The data encryption algorithm is AEAD_AES_256_CBC_HMAC_SHA_256 that is derived from the IETF specification draft at https://tools.ietf.org/html/draft-mcgrew-aead-aes-cbc-hmac-sha2-05. The key encryption algorithm is RSA with OEAP padding. For more information, see Always Encrypted cryptography.
Using the SDK for data protection in Azure
The SDK helps ensure:
- Interoperability with Always Encrypted in Azure SQL
- You can load the data, encrypted using the SDK, to databases columns configured with Always Encrypted in Azure SQL.
- If you ensure the database columns are encrypted in the same way as the data you are inserting, your Azure Data Factory and Spark jobs as well as your applications can transparently decrypt the data stored in the database and run confidential queries using Azure SQL client drivers. This is because the SDK is compatible with Always Encrypted.
- Similarly, you can move the data from a database in Azure SQL to another service or application without decrypting it. Then, you can use the SDK to decrypt the data where it needs to be decrypted, rather than in an application that directly talks to the database.
Supported Platforms
The SDK currently supports the following platforms:
- .NET Standard 2.0 or higher
Installation
To install the latest version of Microsoft.Data.Encryption.Cryptography
via NuGet, use the following command:
dotnet add package Microsoft.Data.Encryption.Cryptography --version 2.0.0
Changelog
[2.0.0]
Changed
Exception handling
MicrosoftDataEncryptionException is now abstract. It's handling is fully backward compatible. New exceptions were introduced for better handling of each individual exception case with specific properties to avoid need to parse exception message. All new exceptions are within Microsoft.Data.Encryption.Cryptography.Exceptions
namespace.
Type | Properties | Thrown when |
---|---|---|
ArgumentEmptyException | ArgumentName | Collection in the argument is empty |
ArgumentNotHexStringException | ArgumentName | Argument is not valid hexadecimal string |
ArgumentNotPositiveException | ArgumentName | Argument is ⇐0 |
ArgumentNullException | ArgumentName | Argument is null |
ArgumentNullOrWhiteSpaceException | ArgumentName | String argument is either null, empty or white space |
ArgumentOutOfRangeException | ArgumentName, ArgumentValue | Argument value is out of valid range |
ArgumentSizeIncorrectException | ArgumentName, ExpectedSize | Collection size is different than expected |
ArgumentTooSmallException | ArgumentName, ExpectedSize | Collection is smaller than necessary |
DefaultAESerializerNotFoundException | SerializerType, SerializerName | SqlSerializer for given type could not be found |
DefaultStandardSerializerNotFoundException | SerializerType, SerializerName | StandardSerializer for given type could not be found |
InvalidAlgorithmVersionException | CipherTextStart, EncryptionKeyEnd, SpecifiedVersion, SupportedVersion | Cipher text specifies unsupported algorithm version |
InvalidAuthenticationTagException | CipherTextStart, EncryptionKeyEnd | Cipher text contains invalid authentication tag, data could have been tampered |
InvalidCipherTextSizeException | CipherTextStart, EncryptionKeyEnd, ActualLength, ExpectedLength | Cipher text length is not of expected length |
InvalidDataEncryptionKeySizeException | KeySize | Size of Encryption key is different than expected |
PlaintextEncryptionSettingsException | ArgumentName | Encryption setting was set to plain text |
New serialization API
All serializers are now immutable, it is no longer possible to change serialization properties like size, codepage, precision
or scale
on already created serializers. New methods were added to allow for allocation-less serialization and deserialization.
All ISerializer<T>
serializers now have following methods
Method | Parameters | Return value | Behavior |
---|---|---|---|
Identifier | - | string | Property returning string identifier of the serializer |
Serialize | T value | byte[] | Serialize to byte[] |
Serialize | T value, Span<byte> outputBuffer | int | Serialize to provided Span<byte>, return number of bytes written |
Serialize | T value, IBufferWriter<byte> outputBuffer | int | Serialize to provided IBufferWriter<byte>, return number of bytes written |
Deserialize | byte[] bytes | T | Deserialize byte[] to T |
Deserialize | ReadOnlySpan<byte> bytes | T | Deserialize Span<byte> to T |
All IFixedSizeSerializer<T>
serializers have additional methods
Method | Parameters | Return value | Behavior |
---|---|---|---|
GetSerializedMaxByteCount | - | int | Returns required size of output buffer |
All IVariableSizeSerializer<TSuper,TBase>
ie. <string, char>
or <byte[], byte>
have these additional methods
Method | Parameters | Return value | Behavior |
---|---|---|---|
GetSerializedMaxByteCount | int inputLength | int | Returns required size of serialization buffer for input of given size - this is upper bound |
GetDeserializedMaxLength | int serializedLength | int | Returns required length of deserialization buffer for input of given size - this is upper bound |
Deserialize | ReadOnlySpan<byte> bytes, Span<TBase> output | int | Deserialize input bytes to provided output buffer, return number of TBase written in output buffer |
Edge cases
- Nullable struct types default behavior
- serialization of
null
to Span/IBufferWriter returns size-1
with no writes in the buffer - Deserialization of empty return
null
- serialization of
- Array types (string, byte[]) default behavior
- serialization of
null
to Span/IBufferWriter returns size-1
with no writes in the buffer - serialization of empty string/byte[] returns size
0
with no writes in the buffer - deserialization of empty span returns empty string/byte[], resp. reports size[0] with no writes in the output buffer
- serialization of
Further changes
- Method
AeadAes256CbcHmac256EncryptionAlgorithm.GetOrCreate(DataEncryptionKey dataEncryptionKey, EncryptionType encryptionType)
was removed, please use overload with explicit algorithm version (1
) - Constructor
AeadAes256CbcHmac256EncryptionAlgorithm(DataEncryptionKey encryptionKey, EncryptionType encryptionType)
was removed, please use overload with explicit algorithm version (1
)
[1.2.0]
Changed
- Further improved Encryption and Decryption performance and memory allocations
[1.1.0]
Added
- Added Methods in
Microsoft.Data.Encryption.Cryptography.DataProtector
Decrypt(byte[] input, int inputOffset, int inputLength, byte[] output, int outputOffset) -> int
- This method implements decryption functionality that processes a portion of the input byte array and writes the decrypted data into the output byte array. The return value indicates the number of bytes written. By defining output buffer this can significantly reduce allocations.
Encrypt(byte[] input, int inputOffset, int inputLength, byte[] output, int outputOffset) -> int
- This methos implement encryption functionality that processes a portion of the input byte array and writes the encrypted data into the output byte array. The return value indicates the number of bytes written. By defining output buffer this can significantly reduce allocations.
GetDecryptByteCount(int inputSize) -> int
- Returns upper bound of bytes required for decryption output based on the given input size.
GetEncryptByteCount(int inputSize) -> int
- Returns the number of bytes required for encryption output based on the given input size.
Changed
AeadAes256CbcHmac256EncryptionAlgorithm
is now sealed.CryptographyExtensions.FromHexString
implementation is 2-3x faster while allocating 90-97% less memory (applicable only to .NET6.0+)
[1.0.0]
Changed
- Significant performance and memory optimizations while sustaining current API.
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net5.0 was computed. net5.0-windows was computed. net6.0 is compatible. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 was computed. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. |
.NET Core | netcoreapp2.0 was computed. netcoreapp2.1 was computed. netcoreapp2.2 was computed. netcoreapp3.0 was computed. netcoreapp3.1 was computed. |
.NET Standard | netstandard2.0 is compatible. netstandard2.1 was computed. |
.NET Framework | net461 was computed. net462 was computed. net463 was computed. net47 was computed. net471 was computed. net472 was computed. net48 was computed. net481 was computed. |
MonoAndroid | monoandroid was computed. |
MonoMac | monomac was computed. |
MonoTouch | monotouch was computed. |
Tizen | tizen40 was computed. tizen60 was computed. |
Xamarin.iOS | xamarinios was computed. |
Xamarin.Mac | xamarinmac was computed. |
Xamarin.TVOS | xamarintvos was computed. |
Xamarin.WatchOS | xamarinwatchos was computed. |
-
.NETStandard 2.0
- Microsoft.Extensions.Caching.Memory (>= 3.1.7)
- System.Text.Encoding.CodePages (>= 5.0.0)
-
net6.0
- Microsoft.Extensions.Caching.Memory (>= 3.1.7)
- System.Text.Encoding.CodePages (>= 5.0.0)
-
net8.0
- Microsoft.Extensions.Caching.Memory (>= 3.1.7)
- System.Text.Encoding.CodePages (>= 5.0.0)
NuGet packages (4)
Showing the top 4 NuGet packages that depend on Microsoft.Data.Encryption.Cryptography:
Package | Downloads |
---|---|
Microsoft.Data.Encryption.AzureKeyVaultProvider
The Microsoft Data Encryption SDK provides encryption support to applications. The Microsoft.Data.Encryption.AzureKeyVaultProvider enables .NET applications to use Microsoft Azure Key Vault to perform encryption/decryption. Commonly Used Types: Microsoft.Data.Encryption.AzureKeyVaultProvider.AzureKeyVaultKeyStoreProvider When using NuGet 3.x this package requires at least version 3.4. |
|
Microsoft.Azure.Cosmos.Encryption.Custom
This is an internal library that provides an implementation for client-side encryption for Azure Cosmos DB for NoSQL for multi-tenant use case. For more information, refer to https://aka.ms/CosmosCustomClientEncryption |
|
Microsoft.Data.Encryption.FileEncryption
The Microsoft Data Encryption SDK provides encryption support to applications. The Microsoft.Data.Encryption.FileEncryption package provides parquet file encryption support. Commonly Used Types: Microsoft.Data.Encryption.FileEncryption.IColumn Microsoft.Data.Encryption.FileEncryption.IColumnarDataReader Microsoft.Data.Encryption.FileEncryption.IColumnarDataWriter Microsoft.Data.Encryption.FileEncryption.Column Microsoft.Data.Encryption.FileEncryption.ColumnarCryptographer Microsoft.Data.Encryption.FileEncryption.CryptoMetadata Microsoft.Data.Encryption.FileEncryption.ParquetFileReader Microsoft.Data.Encryption.FileEncryption.ParquetFileWriter Microsoft.Data.Encryption.FileEncryption.FileEncryptionSettings When using NuGet 3.x this package requires at least version 3.4. |
|
Xtrimmer.KeyStoreProvider.Certificate
The implementation of the Microsoft.Data.Encryption.Cryptography.EncryptionKeyStoreProvider for Windows Certificate Store. This package enables using certificates stored in the Windows Certificate Store as key encryption keys. |
GitHub repositories (1)
Showing the top 1 popular GitHub repositories that depend on Microsoft.Data.Encryption.Cryptography:
Repository | Stars |
---|---|
Azure/azure-cosmos-dotnet-v3
.NET SDK for Azure Cosmos DB for the core SQL API
|