FoxCryptoHelper

NeoDEEX는 AES 256비트 대칭형(symmetric) 암호화 기능을 제공합니다. FoxCryptoHelper 정적(static) 클래스는 Encrypt/Decrypt 메서드 등을 제공하여 손쉽게 암호화 및 복호화를 수행할 수 있습니다.

Basic encryption and decryption

FoxCryptoHelpr 클래스의 Encrypt 메서드는 바이너리 데이터(바이트 배열)를 암호화 하여 그 결과를 바이트 배열로 반환합니다. 한편 Decrypt 메서드는 암호화된 바이너리 데이터를 복호화 하여 그 결과를 바이트 배열로 반환합니다. Encrypt 및 Decrypt 메서드는 동일하게 256비트 AES 알고리즘을 사용합니다.

다음 코드는 문자열을 암호화하는 전형적인 예제 코드입니다. 문자열을 암호화화기 위해 먼저 바이너리 데이터(바이트 배열)로 전환이 필요함에 주목하십시요. 이 예제에서는 UTF8 인코딩을 사용하여 문자열을 바이트 배열로 변환하였습니다.

Information

이 문서에서 사용된 전체 예제 코드는 암호화 복호화 예제를 참고 하십시요.

string plainText = "Basic Crypto Sample";
byte[] plainData = Encoding.UTF8.GetBytes(plainText);
byte[] cipherData = FoxCryptoHelper.Encrypt(plainData);

byte[] decryptedData = FoxCryptoHelper.Decrypt(cipherData);
string decryptedText = Encoding.UTF8.GetString(decryptedData);
Console.WriteLine($"Decrypted text: {decryptedText}\n");
// 출력: Decrypted text: Basic Crypto Sample

바이트 배열에 대한 암/복호화 외에도 FoxCryptoHelper 클래스는 임의의 Stream 에 대한 암/복호화 메서드 역시 제공합니다. 다음 예제 코드는 TargetFile.txt 파일을 암호화하여 EncryptedFile.bin 파일을 생성합니다.

Stream inputStream = File.OpenRead("TargetFile.txt");
Stream outputStream = File.Create("EncryptedFile.bin");
FoxCryptoHelper.Encrypt(inputStream, outputStream);

다음 예제 코드는 위 코드에서 암호화된 파일을 복호화 하는 예제 입니다. 복호화된 파일 DecryptedFile.txt 의 내용은 원본 파일인 TargetFile.txt 과 동일합니다.

Stream inputStream = File.OpenRead("EncryptedFile.bin");
Stream outputStream = File.Create("DecryptedFile.txt");
FoxCryptoHelper.Decrypt(inputStream, outputStream);

String encryption and decryption

많은 경우, 암호화 대상은 문자열인 상황입니다. 보호 대상인 개인 정보나 액세스 토큰 등이 문자열인 경우가 많기 때문입니다. 앞서 살펴본 기본 암/복호화 예제에서 처럼 문자열을 암호화하기 위해서는 먼저 문자열을 바이트 배열로 전환해야만 하며, 복호화 후에는 다시 바이트 배열을 문자열로 전환해야 합니다.

FoxCryptoHelper 클래스는 문자열에 대한 암/복호화를 보다 편리하게 지원하기 위한 메서드들을 제공합니다. 문자열을 매개변수로 사용하는 Encrypt 메서드는 암호화 전에 문자열을 UTF8 인코딩을 사용하여 바이트 배열로 전환하며, DecryptToString 메서드는 복호화 후 바이트 배열을 UTF8 디코딩을 사용하여 문자열로 전환합니다. 다음 코드는 이들 메서드를 사용하여 문자열을 암/복호화 하는 방법을 보여 줍니다.

string plainText = "Basic Crypto Sample";
byte[] cipherData = FoxCryptoHelper.Encrypt(plainText);
string decryptedText = FoxCryptoHelper.DecryptToString(cipherData);
Console.WriteLine($"Decrypted text: {decryptedText}\n");
// 출력: Decrypted text: Basic Crypto Sample

암호화와 관련된 또 하나의 일반적인 상황은 암호화된 내용을 네트워크를 통해 서버 혹은 클라이언트로 전송해야 상황입니다. 이 때 HTTP와 같이 텍스트 기반의 프로토콜을 사용하면 암호화된 결과인 바이트 배열을 곧바로 전송하기 곤란한 경우가 많습니다. 대개 이러한 상황에서 바이트 배열을 Base64 로 인코딩을 하게 됩니다.

static string GetEncryptedString(string plainText)
{
    byte[] plainData = Encoding.UTF8.GetBytes(plainText);
    byte[] cipherData = FoxCryptoHelper.Encrypt(plainData);
    string encodedCipherText = Convert.ToBase64String(cipherData);
    return encodedCipherText;
}

이러한 작업을 보다 편리하게 수행할 수 있도록 FoxCyrptoHelper 클래스는 EncryptToBase64 메서드를 제공합니다.

string encodedChiperText = FoxCryptoHelper.EncryptToBase64(plainText);

문자열을 매개변수로 사용하는 Decrypt 메서드와 DecryptToString 메서드는 매개변수 문자열이 Base64 로 인코딩된 문자열로 간주하여 Base64 디코딩을 먼저 수행한 후에 복호화를 수행합니다(DecryptToString 메서드는 복호화 후 UTF8 디코딩까지 수행하여 문자열을 반환).

byte[] plainData = FoxCryptoHelper.Decrypt(encodedChiperText);
string plainText = FoxCryptoHelper.DecryptToString(encodedChiperText);

Object encryption and decryption

FoxCryptoHelper 클래스는 객체를 암호화 하고 복호화 하는 메서드도 제공합니다. 보호해야 할 객체를 저장하거나 네트워크로 전송해야 하는 경우 EncryptObject 메서드와 DecrpytObject 메서드를 사용할 수 있습니다. EncryptObject 메서드는 먼저 객체를 JSON 직렬화하고 암호화를 수행하여 바이트 배열을 반환합니다. DecryptObject 메서드는 바이트 배열을 복호화 한 후 JSON 역 직렬화를 수행합니다.

SimplePoco obj = new SimplePoco() { Id = 1, Name = "Nobody", Password = "!23$" };
byte[] cipherData = FoxCryptoHelper.EncryptObject(obj);
SimplePoco? obj2 = FoxCryptoHelper.DecryptObject<SimplePoco>(cipherData);

Warning

EncryptObject/DecryptObject 메서드는 System.Text.Json 네임스페이스의 JSON 직렬화/역직렬화 기능을 사용합니다. 개발자는 암호화 대상인 객체가 JSON 직렬화에 문제가 없는지 확인을 해야 합니다.

Encryption key provider

FoxCryptoHelper 클래스는 기본적으로 256비트 AES 알고리즘을 암호화와 복호화에 사용합니다. 기본으로 제공되는 암호화 키와 다른 키를 사용하고자 하거나 다른 암호화 알고리즘을 사용하고자 한다면 커스텀 암호화 키 프로바이더를 작성해야 합니다.

FoxCryptoHelper 클래스가 사용하는 암호화 키 프로바이더는 FoxCryptoKeyProvider 추상(abstract) 클래스에서 파생된 클래스를 정의하고 3개의 메서드를 오버라이드 해야 합니다. 다음 코드는 TripleDES 알고리즘을 사용하고 패스워드에 기반한 키를 사용하는 커스텀 암호화 키 프로바이더의 예를 보여 줍니다.

Warning

TripleDES 알고리즘은 최신 .net 환경에서 더 이상 사용하지 않는 것이 좋습니다(Obsoluted).

namespace KeyProviderLib;

public class MyKeyProvider : FoxCryptoKeyProvider
{
    private readonly byte[] _key;
    private readonly byte[] _iv;
    private readonly TripleDES _algorithm;

    public MyKeyProvider()
    {
        byte[] salt = new byte[] { 0, 1, 2, 3, 4, 5, 6, 7 };
        Rfc2898DeriveBytes derivedBytes = new("password", salt);
        _key = derivedBytes.GetBytes(24);
        _iv = derivedBytes.GetBytes(8);
        _algorithm = TripleDES.Create();
    }

    public override SymmetricAlgorithm GetSymmetricAlgorithm() => _algorithm;
    public override byte[] GetSymmetricKey() => _key;
    public override byte[] GetSymmetricIV() => _iv;
}

Warning

MyKeyProvider 클래스는 간단한 예제 이므로 하드 코드된 패스워드를 사용하여 암호화 키를 적용하였지만 실무 커스텀 암호화 키 프로바이더는 안전한 장소에서 키를 읽어 오거나 서버를 호출하여 암호화 키를 획득하는 로직을 구현할 수도 있습니다.

작성된 암호화 키 프로바이더는 구성 설정을 사용하거나 FoxCryptoHelper.KeyProvider 속성을 사용하여 설정이 가능합니다.

{
  "security": {
    "keyProviderType": "KeyProviderLib.MyKeyProvider, KeyProviderLib"
  }
}

var provider = new MyKeyProvider();
FoxCryptoHelper.KeyProvider = provider;

Warning

암호화 키 프로바이더를 재지정할 때의 주의 사항은 이 설정이 FoxCryptoHelper 클래스를 사용하는 모든 코드에 전역적으로 즉시 적용된다는 점입니다. 예를 들어 NeoDEEX의 Fox DB Access 기능은 암호화된 DB 연결 문자열을 복호화 하는데 FoxCryptoHelper 클래스를 사용하며, FoxUserInfoContext 를 암/복호화 하는데에도 FoxCryptoHelper 클래스를 사용합니다.

따라서 커스텀 암호화 키 프로바이더 설정은 Startup 메서드와 같이 어플리케이션의 엔트리 포인트에서 수행하거나 구성 설정("security:keyProviderType" 속성)만을 사용하고 이후에는 설정값을 변경하지 않는 것이 좋습니다.

Note

암호화 키 프로바이더 구성 설정은 어플리케이션 구동 도중 값을 변경하더라도 변경된 값을 다시 읽지 않습니다.

---