ASP.NET Core のコア暗号化機能拡張

警告

次のいずれかのインターフェイスを実装する型は、複数の呼び出し元に対してスレッドセーフである必要があります。

IAuthenticatedEncryptor

IAuthenticatedEncryptorインターフェイスは、暗号化サブシステムの基本的な構成要素です。 一般に、キーごとに 1 つの IAuthenticatedEncryptor があります。IAuthenticatedEncryptor インスタンスにより、暗号化操作を実行するために必要なすべての暗号化キー マテリアルとアルゴリズム情報がラップされます。

その名前が示すように、型は認証された暗号化および暗号化解除サービスを提供するものです。 次の 2 つの API が公開されます。

• Decrypt(ArraySegment<byte> ciphertext, ArraySegment<byte> additionalAuthenticatedData) : byte[]

• Encrypt(ArraySegment<byte> plaintext, ArraySegment<byte> additionalAuthenticatedData) : byte[]

Encrypt メソッドからは、暗号化されたプレーンテキストと認証タグを含む BLOB が返されます。 認証タグには追加の認証済みデータ (AAD) が含まれている必要がありますが、AAD 自体を最終的なペイロードから回復できる必要はありません。 Decrypt メソッドでは、認証タグが検証され、解読されたペイロードが返されます。 すべてのエラー (ArgumentNullException や同様のものを除く) は CryptographicException に均質化する必要があります。

注意

IAuthenticatedEncryptor インスタンス自体には、実際にキー マテリアルが含まれている必要はありません。 たとえば、実装では、すべての操作について HSM に委任できます。

IAuthenticatedEncryptor を作成する方法

ASP.NET Core 2.x

IAuthenticatedEncryptorFactoryインターフェイスは、IAuthenticatedEncryptor インスタンスを作成する方法を認識する型を表します。 その API は次のとおりです。

• CreateEncryptorInstance(IKey key) : IAuthenticatedEncryptor

特定の IKey インスタンスでは、次のコード サンプルのように、CreateEncryptorInstance メソッドによって作成された認証済みの暗号化機能が同等と見なされる必要があります。

// we have an IAuthenticatedEncryptorFactory instance and an IKey instance
IAuthenticatedEncryptorFactory factory = ...;
IKey key = ...;

// get an encryptor instance and perform an authenticated encryption operation
ArraySegment<byte> plaintext = new ArraySegment<byte>(Encoding.UTF8.GetBytes("plaintext"));
ArraySegment<byte> aad = new ArraySegment<byte>(Encoding.UTF8.GetBytes("AAD"));
var encryptor1 = factory.CreateEncryptorInstance(key);
byte[] ciphertext = encryptor1.Encrypt(plaintext, aad);

// get another encryptor instance and perform an authenticated decryption operation
var encryptor2 = factory.CreateEncryptorInstance(key);
byte[] roundTripped = encryptor2.Decrypt(new ArraySegment<byte>(ciphertext), aad);


// the 'roundTripped' and 'plaintext' buffers should be equivalent

ASP.NET Core 1.x

IAuthenticatedEncryptorDescriptor インターフェイスは、IAuthenticatedEncryptor インスタンスを作成する方法を認識する型を表します。 その API は次のとおりです。

• CreateEncryptorInstance() : IAuthenticatedEncryptor

• ExportToXml() : XmlSerializedDescriptorInfo

IAuthenticatedEncryptor と同様に、IAuthenticatedEncryptorDescriptor のインスタンスは、1 つの特定のキーをラップすると見なされます。 つまり、特定の IAuthenticatedEncryptorDescriptor インスタンスでは、次のコード サンプルのように、CreateEncryptorInstance メソッドによって作成された認証済みの暗号化機能が同等と見なされる必要があります。

// we have an IAuthenticatedEncryptorDescriptor instance
IAuthenticatedEncryptorDescriptor descriptor = ...;

// get an encryptor instance and perform an authenticated encryption operation
ArraySegment<byte> plaintext = new ArraySegment<byte>(Encoding.UTF8.GetBytes("plaintext"));
ArraySegment<byte> aad = new ArraySegment<byte>(Encoding.UTF8.GetBytes("AAD"));
var encryptor1 = descriptor.CreateEncryptorInstance();
byte[] ciphertext = encryptor1.Encrypt(plaintext, aad);

// get another encryptor instance and perform an authenticated decryption operation
var encryptor2 = descriptor.CreateEncryptorInstance();
byte[] roundTripped = encryptor2.Decrypt(new ArraySegment<byte>(ciphertext), aad);


// the 'roundTripped' and 'plaintext' buffers should be equivalent

IAuthenticatedEncryptorDescriptor (ASP.NET Core 2.x のみ)

ASP.NET Core 2.x

IAuthenticatedEncryptorDescriptor インターフェイスは、それ自体を XML にエクスポートする方法を認識する型を表します。 その API は次のとおりです。

• ExportToXml() : XmlSerializedDescriptorInfo

ASP.NET Core 1.x

XML シリアル化

IAuthenticatedEncryptor と IAuthenticatedEncryptorDescriptor の主な違いは、記述子が暗号化機能を作成して有効な引数を指定する方法を認識している点です。 実装が SymmetricAlgorithm と KeyedHashAlgorithm に依存する IAuthenticatedEncryptor について考えてみます。 暗号化機能のジョブではこれらの型を使用しますが、これらの型がどこから来たのかは必ずしもわからないため、アプリケーションが再起動された場合に、それ自体を再作成する方法に関する適切な説明を完全に記述することはできません。 記述子は、この上の上位レベルとして機能します。 記述子は暗号化機能インスタンスの作成方法を認識している (たとえば、必要なアルゴリズムの作成方法を認識している) ので、その知識を XML 形式でシリアル化して、アプリケーションのリセット後に暗号化機能インスタンスを再作成できます。

記述子は、ExportToXml ルーチンを使用してシリアル化できます。 このルーチンにより、2 つのプロパティ (記述子の XElement 表現と、対応する XElement を指定してこの記述子を復活させるために使用できる IAuthenticatedEncryptorDescriptorDeserializer を表す Type) を含む XmlSerializedDescriptorInfo が返されます。

シリアル化された記述子には、暗号化キー マテリアルなどの機密情報が含まれている場合があります。 データ保護システムには、ストレージに保持される前に情報を暗号化するためのサポートが組み込まれています。 これを利用するために、記述子では、機密情報を含む要素を属性名 "requiresEncryption" (xmlns "<http://schemas.asp.net/2015/03/dataProtection>")、値 "true" でマークする必要があります。

ヒント

この属性を設定するヘルパー API があります。 名前空間 Microsoft.AspNetCore.DataProtection.AuthenticatedEncryption.ConfigurationModel にある拡張メソッド XElement.MarkAsRequiresEncryption() を呼び出します。

シリアル化された記述子に機密情報が含まれていない場合もあります。 もう一度、HSM に格納されている暗号化キーの場合を考えます。 HSM はマテリアルをプレーンテキスト形式で公開しないので、記述子では自身をシリアル化するときにキー マテリアルを書き出すことはできません。 代わりに、記述子では、キーがラップされたバージョンのキー (この方法でのエクスポートが HSM によって許可されている場合) またはキーに対する HSM の独自の一意識別子を書き出すことができます。

IAuthenticatedEncryptorDescriptorDeserializer

IAuthenticatedEncryptorDescriptorDeserializer インターフェイスは、XElement から IAuthenticatedEncryptorDescriptor インスタンスを逆シリアル化する方法を認識している型を表します。 これにより、1 つのメソッドが公開されます。

• ImportFromXml(XElement element) : IAuthenticatedEncryptorDescriptor

ImportFromXml メソッドは IAuthenticatedEncryptorDescriptor.ExportToXml によって返された XElement を受け取り、元の IAuthenticatedEncryptorDescriptor と同等のものを作成します。

IAuthenticatedEncryptorDescriptorDeserializer を実装する型には、次の 2 つのパブリック コンストラクターのいずれかが必要です。

• .ctor(IServiceProvider)

• .ctor()

注意

コンストラクターに渡される IServiceProvider は null になる場合があります。

最上位レベル ファクトリ

ASP.NET Core 2.x

AlgorithmConfiguration クラスは、IAuthenticatedEncryptorDescriptor インスタンスを作成する方法を認識する型を表します。 これにより、1 つの API が公開されます。

• CreateNewDescriptor() : IAuthenticatedEncryptorDescriptor

AlgorithmConfiguration は、最上位レベル ファクトリとして考えます。 構成はテンプレートとして機能します。 アルゴリズム情報がラップされますが (たとえば、この構成では、AES-128-GCM マスター キーを使用して記述子が生成されます)、特定のキーにはまだ関連付けられていません。

CreateNewDescriptor が呼び出されると、この呼び出し専用の新しいキー マテリアルが作成され、このキー マテリアルとマテリアルの使用に必要なアルゴリズム情報をラップする新しい IAuthenticatedEncryptorDescriptor が生成されます。 キー マテリアルは、ソフトウェアで作成 (およびメモリ内に保持) したり、HSM 内に作成して保持したりすることなどができます。 重要なのは、CreateNewDescriptor への 2 回の呼び出しで、等価な IAuthenticatedEncryptorDescriptor インスタンスが作成されることはない点です。

AlgorithmConfiguration 型は、自動キー ローリングなどのキー作成ルーチンのエントリ ポイントとして機能します。 今後のすべてのキーの実装を変更するには、KeyManagementOptions 内で AuthenticatedEncryptorConfiguration プロパティを設定します。

ASP.NET Core 1.x

IAuthenticatedEncryptorConfiguration インターフェイスは、IAuthenticatedEncryptorDescriptor インスタンスを作成する方法を認識する型を表します。 これにより、1 つの API が公開されます。

• CreateNewDescriptor() : IAuthenticatedEncryptorDescriptor

IAuthenticatedEncryptorConfiguration は、最上位レベル ファクトリと考えます。 構成はテンプレートとして機能します。 アルゴリズム情報がラップされますが (たとえば、この構成では、AES-128-GCM マスター キーを使用して記述子が生成されます)、特定のキーにはまだ関連付けられていません。

CreateNewDescriptor が呼び出されると、この呼び出し専用の新しいキー マテリアルが作成され、このキー マテリアルとマテリアルの使用に必要なアルゴリズム情報をラップする新しい IAuthenticatedEncryptorDescriptor が生成されます。 キー マテリアルは、ソフトウェアで作成 (およびメモリ内に保持) したり、HSM 内に作成して保持したりすることなどができます。 重要なのは、CreateNewDescriptor への 2 回の呼び出しで、等価な IAuthenticatedEncryptorDescriptor インスタンスが作成されることはない点です。

IAuthenticatedEncryptorConfiguration 型は、自動キー ローリングなどのキー作成ルーチンのエントリ ポイントとして機能します。 今後のすべてのキーの実装を変更するには、サービス コンテナーにシングルトン IAuthenticatedEncryptorConfiguration を登録します。