ASP.NET Core의 핵심 암호화 확장성

Warning

다음 인터페이스 중 하나를 구현하는 형식은 여러 호출자에 대해 스레드로부터 안전해야 합니다.

IAuthenticatedEncryptor

IAuthenticatedEncryptor 인터페이스는 암호화 하위 시스템의 기본 구성 블록입니다. 일반적으로 키당 하나의 IAuthenticatedEncryptor가 있으며 IAuthenticatedEncryptor 인스턴스는 암호화 작업을 수행하는 데 필요한 모든 암호화 키 자료 및 알고리즘 정보를 래핑합니다.

이름에서 확인할 수 있듯이 형식은 인증된 암호화 및 암호 해독 서비스를 제공합니다. 다음 두 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 키) : 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의 인스턴스는 하나의 특정 키를 래핑하는 것으로 가정됩니다. 즉, 지정된 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 Serialization

IAuthenticatedEncryptor와 IAuthenticatedEncryptorDescriptor의 주요 차이점은 설명자가 암호화기를 만들고 유효한 인수를 제공하는 방법을 알고 있다는 것입니다. 구현이 SymmetricAlgorithm 및 KeyedHashAlgorithm을 사용하는 IAuthenticatedEncryptor를 고려합니다. 암호화기의 작업은 이러한 형식을 사용하는 것이지만 이러한 형식이 어디에서 오는지 반드시 알 필요는 없으므로 애플리케이션이 다시 시작될 경우 자신을 다시 작성하는 방법에 대한 적절한 설명을 작성할 수 없습니다. 설명자는 이 위에 더 높은 수준으로 작동합니다. 설명자는 암호화기 인스턴스를 만드는 방법(예: 필요한 알고리즘을 만드는 방법을 알고 있음)을 알고 있으므로 애플리케이션 재설정 후에 암호화기 인스턴스를 다시 만들 수 있도록 XML 형식으로 해당 지식을 직렬화할 수 있습니다.

설명자는 ExportToXml 루틴을 통해 직렬화할 수 있습니다. 이 루틴은 두 가지 속성이 포함된 XmlSerializedDescriptorInfo를 반환합니다. 즉, 설명자의 XElement 표현과 해당 XElement가 지정된 경우 이 설명자를 표시하는 데 사용할 수 있는 IAuthenticatedEncryptorDescriptorDeserializer를 나타내는 Type입니다.

직렬화된 설명자는 암호화 키 자료와 같은 중요한 정보를 포함할 수 있습니다. 데이터 보호 시스템은 스토리지에 유지되기 전에 정보 암호화를 기본으로 지원합니다. 이를 활용하려면 설명자는 중요한 정보가 포함된 요소를 특성 이름 ‘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 인스턴스를 역직렬화하는 방법을 알고 있는 형식을 나타냅니다. 단일 메서드를 노출합니다.

• ImportFromXml(XElement 요소) : IAuthenticatedEncryptorDescriptor

ImportFromXml 메서드는 IAuthenticatedEncryptorDescriptor.ExportToXml에서 반환된 XElement를 사용하고 원래 IAuthenticatedEncryptorDescriptor에 해당하는 것을 만듭니다.

IAuthenticatedEncryptorDescriptorDeserializer를 구현하는 형식에는 다음 두 공용 생성자 중 하나가 있어야 합니다.

• .ctor(IServiceProvider)

• .ctor()

참고 항목

생성자에 전달된 IServiceProvider는 Null일 수 있습니다.

최상위 팩터리

ASP.NET Core 2.x

AlgorithmConfiguration 클래스는 IAuthenticatedEncryptorDescriptor 인스턴스를 만드는 방법을 알고 있는 형식을 나타냅니다. 단일 API를 노출합니다.

• CreateNewDescriptor() : IAuthenticatedEncryptorDescriptor

AlgorithmConfiguration을 최상위 팩터리로 간주합니다. 구성은 템플릿으로 사용됩니다. 알고리즘 정보(예: 이 구성은 AES-128-GCM 마스터 키를 가진 설명자를 생성함)를 래핑하지만 아직 특정 키와 연결되지 않았습니다.

CreateNewDescriptor가 호출되면 이 호출에 대해서만 새 키 자료가 생성되고, 이 키 자료 및 자료를 사용하는 데 필요한 알고리즘 정보를 래핑하는 새 IAuthenticatedEncryptorDescriptor가 생성됩니다. 키 자료는 소프트웨어에서 만들어지고 메모리에 보관될 수 있으며, HSM 내에서 만들어지고 보관될 수 있습니다. 중요한 점은 CreateNewDescriptor에 대한 두 호출이 동일한 IAuthenticatedEncryptorDescriptor 인스턴스를 만들지 않아야 한다는 것입니다.

AlgorithmConfiguration 형식은 자동 키 롤링과 같은 키 생성 루틴의 진입점으로 사용됩니다. 이후의 모든 키에 대한 구현을 변경하려면 KeyManagementOptions에서 AuthenticatedEncryptorConfiguration 속성을 설정합니다.

ASP.NET Core 1.x

IAuthenticatedEncryptorConfiguration 인터페이스는 IAuthenticatedEncryptorDescriptor 인스턴스를 만드는 방법을 알고 있는 형식을 나타냅니다. 단일 API를 노출합니다.

• CreateNewDescriptor() : IAuthenticatedEncryptorDescriptor

IAuthenticatedEncryptorConfiguration을 최상위 팩터리로 간주합니다. 구성은 템플릿으로 사용됩니다. 알고리즘 정보(예: 이 구성은 AES-128-GCM 마스터 키를 가진 설명자를 생성함)를 래핑하지만 아직 특정 키와 연결되지 않았습니다.

CreateNewDescriptor가 호출되면 이 호출에 대해서만 새 키 자료가 생성되고, 이 키 자료 및 자료를 사용하는 데 필요한 알고리즘 정보를 래핑하는 새 IAuthenticatedEncryptorDescriptor가 생성됩니다. 키 자료는 소프트웨어에서 만들어지고 메모리에 보관될 수 있으며, HSM 내에서 만들어지고 보관될 수 있습니다. 중요한 점은 CreateNewDescriptor에 대한 두 호출이 동일한 IAuthenticatedEncryptorDescriptor 인스턴스를 만들지 않아야 한다는 것입니다.

IAuthenticatedEncryptorConfiguration 형식은 자동 키 롤링과 같은 키 생성 루틴의 진입점으로 사용됩니다. 이후의 모든 키에 대한 구현을 변경하려면 서비스 컨테이너에 싱글톤 IAuthenticatedEncryptorConfiguration을 등록합니다.