🚀 Big News: Socket Acquires Coana to Bring Reachability Analysis to Every Appsec Team.Learn more
Socket
DemoInstallSign in
Socket

Microsoft.Data.Encryption.Cryptography

Package Overview
Dependencies
Maintainers
2
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

Microsoft.Data.Encryption.Cryptography

The Microsoft Data Encryption SDK 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. Commonly Used Types: Microsoft.Data.Encryption.Cryptography.DataProtector Microsoft.Data.Encryption.Cryptography.DataEncryptionKey Microsoft.Data.Encryption.Cryptography.KeyEncryptionKey Microsoft.Data.Encryption.Cryptography.EncryptionSettings Microsoft.Data.Encryption.Cryptography.EncryptionKeyStoreProvider Microsoft.Data.Encryption.Cryptography.MicrosoftDataEncryptionException Microsoft.Data.Encryption.Cryptography.PlaintextDataEncryptionKey Microsoft.Data.Encryption.Cryptography.ProtectedDataEncryptionKey When using NuGet 3.x this package requires at least version 3.4.

2.0.0-pre007
NuGet
Version published
Maintainers
2
Created
Source

GitHub license Nuget

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.

TypePropertiesThrown when
ArgumentEmptyExceptionArgumentNameCollection in the argument is empty
ArgumentNotHexStringExceptionArgumentNameArgument is not valid hexadecimal string
ArgumentNotPositiveExceptionArgumentNameArgument is <=0
ArgumentNullExceptionArgumentNameArgument is null
ArgumentNullOrWhiteSpaceExceptionArgumentNameString argument is either null, empty or white space
ArgumentOutOfRangeExceptionArgumentName, ArgumentValueArgument value is out of valid range
ArgumentSizeIncorrectExceptionArgumentName, ExpectedSizeCollection size is different than expected
ArgumentTooSmallExceptionArgumentName, ExpectedSizeCollection is smaller than necessary
DefaultAESerializerNotFoundExceptionSerializerType, SerializerNameSqlSerializer for given type could not be found
DefaultStandardSerializerNotFoundExceptionSerializerType, SerializerNameStandardSerializer for given type could not be found
InvalidAlgorithmVersionExceptionCipherTextStart, EncryptionKeyEnd, SpecifiedVersion, SupportedVersionCipher text specifies unsupported algorithm version
InvalidAuthenticationTagExceptionCipherTextStart, EncryptionKeyEndCipher text contains invalid authentication tag, data could have been tampered
InvalidCipherTextSizeExceptionCipherTextStart, EncryptionKeyEnd, ActualLength, ExpectedLengthCipher text length is not of expected length
InvalidDataEncryptionKeySizeExceptionKeySizeSize of Encryption key is different than expected
PlaintextEncryptionSettingsExceptionArgumentNameEncryption 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

MethodParametersReturn valueBehavior
Identifier-stringProperty returning string identifier of the serializer
SerializeT valuebyte[]Serialize to byte[]
SerializeT value, Span outputBufferintSerialize to provided Span, return number of bytes written
SerializeT value, IBufferWriter outputBufferintSerialize to provided IBufferWriter, return number of bytes written
Deserializebyte[] bytesTDeserialize byte[] to T
DeserializeReadOnlySpan bytesTDeserialize Span to T

All IFixedSizeSerializer<T> serializers have additional methods

MethodParametersReturn valueBehavior
GetSerializedMaxByteCount-intReturns required size of output buffer

All IVariableSizeSerializer<TSuper,TBase> ie. <string, char> or <byte[], byte> have these additional methods

MethodParametersReturn valueBehavior
GetSerializedMaxByteCountint inputLengthintReturns required size of serialization buffer for input of given size - this is upper bound
GetDeserializedMaxLengthint serializedLengthintReturns required length of deserialization buffer for input of given size - this is upper bound
DeserializeReadOnlySpan bytes, Span outputintDeserialize 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
  • 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
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.

Keywords

microsoft.data.encryption

FAQs

Package last updated on 01 Oct 2024

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts