Extensibilidade de criptografia principal no ASP.NET Core

Aviso

Os tipos que implementam qualquer uma das interfaces a seguir devem ser thread-safe para vários chamadores.

IAuthenticatedEncryptor

A interface IAuthenticatedEncryptor é o bloco de construção básico do subsistema criptográfico. Geralmente, há um IAuthenticatedEncryptor por chave e a instância IAuthenticatedEncryptor encapsula todo o material de chave criptográfica e as informações algorítmicas necessárias para executar operações criptográficas.

Como o nome sugere, o tipo é responsável por fornecer serviços de criptografia e descriptografia autenticados. Ele expõe as duas APIs a seguir.

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

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

O método Encrypt retorna um blob que inclui o texto sem formatação cifrada e uma marca de autenticação. A marca de autenticação deve abranger os dados autenticados adicionais (AAD), embora o próprio AAD não precise ser recuperável da carga final. O método Decrypt valida a marca de autenticação e retorna a carga decifrada. Todas as falhas (exceto ArgumentNullException e similares) devem ser homogeneizadas para CryptographicException.

Observação

A própria instância IAuthenticatedEncryptor não precisa conter o material de chave. Por exemplo, a implementação pode delegar a um HSM para todas as operações.

Como criar um IAuthenticatedEncryptor

ASP.NET Core 2.x

A interface IAuthenticatedEncryptorFactory representa um tipo que sabe como criar uma instância IAuthenticatedEncryptor . Sua API é a seguinte.

• CreateEncryptorInstance(IKey key) : IAuthenticatedEncryptor

Para qualquer instância IKey, todos os criptografadores autenticados criados pelo método CreateEncryptorInstance devem ser considerados equivalentes, como no exemplo de código abaixo.

// 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

A interface IAuthenticatedEncryptorFactory representa um tipo que sabe como criar uma instância IAuthenticatedEncryptor . Sua API é a seguinte.

• CreateEncryptorInstance() : IAuthenticatedEncryptor

• ExportToXml() : XmlSerializedDescriptorInfo

Como IAuthenticatedEncryptor, uma instância de IAuthenticatedEncryptorDescriptor é presumida para encapsular uma chave específica. Isso significa que, para qualquer instância IAuthenticatedEncryptorDescriptor, todos os criptografadores autenticados criados pelo método CreateEncryptorInstance devem ser considerados equivalentes, como no exemplo de código abaixo.

// 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 (somente ASP.NET Core 2.x)

ASP.NET Core 2.x

A interface IAuthenticatedEncryptorDescriptor representa um tipo que sabe como se exportar para XML. Sua API é a seguinte.

• ExportToXml() : XmlSerializedDescriptorInfo

ASP.NET Core 1.x

Serialização XML

A principal diferença entre IAuthenticatedEncryptor e IAuthenticatedEncryptorDescriptor é que o descritor sabe como criar o criptografador e fornecê-lo com argumentos válidos. Considere um IAuthenticatedEncryptor cuja implementação depende de SymmetricAlgorithm e KeyedHashAlgorithm. O trabalho do criptografador é consumir esses tipos, mas ele não sabe necessariamente de onde esses tipos vieram, portanto, ele não pode realmente escrever uma descrição adequada de como se recriar se o aplicativo for reiniciado. O descritor atua como um nível mais alto sobre isso. Como o descritor sabe como criar a instância do criptografador (por exemplo, ele sabe como criar os algoritmos necessários), ele pode serializar esse conhecimento no formulário XML para que a instância do criptografador possa ser recriada após uma redefinição de aplicativo.

O descritor pode ser serializado por meio de sua rotina ExportToXml. Essa rotina retorna um XmlSerializedDescriptorInfo que contém duas propriedades: a representação XElement do descritor e o Type que representa um IAuthenticatedEncryptorDescriptorDeserializer que pode ser usado para ressuscitar esse descritor dado o XElement correspondente.

O descritor serializado pode conter informações confidenciais, como material de chave criptográfica. O sistema de proteção de dados tem suporte interno para criptografar informações antes de persistir no armazenamento. Para aproveitar isso, o descritor deve marcar o elemento que contém informações confidenciais com o nome do atributo "requiresEncryption" (xmlns "<http://schemas.asp.net/2015/03/dataProtection>"), valor "true".

Dica

Há uma API auxiliar para definir esse atributo. Chame o método de extensão XElement.MarkAsRequiresEncryption() localizado no namespace Microsoft.AspNetCore.DataProtection.AuthenticatedEncryption.ConfigurationModel.

Também pode haver casos em que o descritor serializado não contém informações confidenciais. Considere novamente o caso de uma chave criptográfica armazenada em um HSM. O descritor não pode gravar o material de chave ao se serializar, pois o HSM não exporá o material em forma de texto sem formatação. Em vez disso, o descritor pode gravar a versão encapsulada por chave da chave (se o HSM permitir a exportação dessa forma) ou o próprio identificador exclusivo do HSM para a chave.

IAuthenticatedEncryptorDescriptorDeserializer

A interface IAuthenticatedEncryptorDescriptorDeserializer representa um tipo que sabe como desserializar uma instância IAuthenticatedEncryptorDescriptor de um XElement. Ele expõe um único método:

• ImportFromXml(elemento XElement) : IAuthenticatedEncryptorDescriptor

O método ImportFromXml usa o XElement que foi retornado por IAuthenticatedEncryptorDescriptor.ExportToXml e cria um equivalente do IAuthenticatedEncryptorDescriptor original.

Os tipos que implementam IAuthenticatedEncryptorDescriptorDeserializer devem ter um dos dois construtores públicos a seguir:

• .ctor(IServiceProvider)

• .ctor()

Observação

O IServiceProvider passado para o construtor pode ser nulo.

A fábrica de nível superior

ASP.NET Core 2.x

A classe AlgorithmConfiguration representa um tipo que sabe como criar instâncias IAuthenticatedEncryptorDescriptor . Ele expõe uma única API.

• CreateNewDescriptor() : IAuthenticatedEncryptorDescriptor

Pense em AlgorithmConfiguration como a fábrica de nível superior. A configuração serve como um modelo. Ele encapsula informações algorítmicas (por exemplo, essa configuração produz descritores com uma chave mestra AES-128-GCM), mas ainda não está associada a uma chave específica.

Quando CreateNewDescriptor é chamado, o material de chave novo é criado exclusivamente para essa chamada e um novo IAuthenticatedEncryptorDescriptor é produzido, que encapsula esse material de chave e as informações algorítmicas necessárias para consumir o material. O material de chave pode ser criado em software (e mantido na memória), ele pode ser criado e mantido dentro de um HSM e assim por diante. O ponto crucial é que as duas chamadas para CreateNewDescriptor nunca devem criar instâncias IAuthenticatedEncryptorDescriptor equivalentes.

O tipo AlgorithmConfiguration serve como o ponto de entrada para rotinas de criação de chave, como rolagem automática de chave. Para alterar a implementação de todas as chaves futuras, defina a propriedade AuthenticatedEncryptorConfiguration em KeyManagementOptions.

ASP.NET Core 1.x

A interface IAuthenticatedEncryptorConfiguration representa um tipo que sabe como criar instâncias IAuthenticatedEncryptorDescriptor . Ele expõe uma única API.

• CreateNewDescriptor() : IAuthenticatedEncryptorDescriptor

Pense em IAuthenticatedEncryptorConfiguration como a fábrica de nível superior. A configuração serve como um modelo. Ele encapsula informações algorítmicas (por exemplo, essa configuração produz descritores com uma chave mestra AES-128-GCM), mas ainda não está associada a uma chave específica.

Quando CreateNewDescriptor é chamado, o material de chave novo é criado exclusivamente para essa chamada e um novo IAuthenticatedEncryptorDescriptor é produzido, que encapsula esse material de chave e as informações algorítmicas necessárias para consumir o material. O material de chave pode ser criado em software (e mantido na memória), ele pode ser criado e mantido dentro de um HSM e assim por diante. O ponto crucial é que as duas chamadas para CreateNewDescriptor nunca devem criar instâncias IAuthenticatedEncryptorDescriptor equivalentes.

O tipo AlgorithmConfiguration serve como o ponto de entrada para rotinas de criação de chave, como a rolagem automática de chave. Para alterar a implementação de todas as chaves futuras, registre um singleton IAuthenticatedEncryptorConfiguration no contêiner de serviço.