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
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
IAuthenticatedEncryptorDescriptor (somente ASP.NET Core 2.x)
A interface IAuthenticatedEncryptorDescriptor representa um tipo que sabe como se exportar para XML. Sua API é a seguinte.
- ExportToXml() : XmlSerializedDescriptorInfo
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
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.
