CryptDecrypt 함수(wincrypt.h)

아티클
08/27/2023

중요 이 API는 더 이상 사용되지 않습니다. 신규 및 기존 소프트웨어는 암호화 차세대 API 사용을 시작해야 합니다. Microsoft는 이후 릴리스에서 이 API를 제거할 수 있습니다.

CryptDecrypt 함수는 CryptEncrypt 함수를 사용하여 이전에 암호화된 데이터를 해독합니다.

S/MIME( Secure/Multipurpose Internet Mail Extensions ) 이메일 상호 운용성을 지원하기 위한 중요한 변경 사항은 봉투 메시지 처리에 영향을 주는 CryptoAPI에 적용되었습니다. 자세한 내용은 CryptMsgOpenToEncode의 설명 섹션을 참조하세요.

구문

BOOL CryptDecrypt(
  [in]      HCRYPTKEY  hKey,
  [in]      HCRYPTHASH hHash,
  [in]      BOOL       Final,
  [in]      DWORD      dwFlags,
  [in, out] BYTE       *pbData,
  [in, out] DWORD      *pdwDataLen
);

매개 변수

[in] hKey

암호 해독에 사용할 키에 대한 핸들입니다. 애플리케이션은 CryptGenKey 또는 CryptImportKey 함수를 사용하여 이 핸들 을 가져옵니다.

이 키는 사용할 암호 해독 알고리즘을 지정합니다.

[in] hHash

해시 개체에 대한 핸들입니다. 데이터를 암호 해독하고 동시에 해시하는 경우 해시 개체에 대한 핸들이 이 매개 변수에 전달됩니다. 해시 값은 암호 해독된 일반 텍스트로 업데이트됩니다. 이 옵션은 서명을 동시에 암호 해독하고 확인할 때 유용합니다.

CryptDecrypt를 호출하기 전에 애플리케이션은 CryptCreateHash 함수를 호출하여 해시 개체에 대한 핸들을 가져와야 합니다. 암호 해독이 완료되면 CryptGetHashParam 함수를 사용하여 해시 값을 가져오거나 CryptSignHash 함수를 사용하여 서명하거나 CryptVerifySignature 함수를 사용하여 디지털 서명을 확인하는 데 사용할 수 있습니다.

해시가 없는 경우 이 매개 변수는 0이어야 합니다.

[in] Final

이 섹션이 암호 해독되는 계열의 마지막 섹션인지 여부를 지정하는 부울 값입니다. 마지막 또는 유일한 블록인 경우 이 값은 TRUE 입니다. 마지막 블록이 아닌 경우 이 값은 FALSE입니다. 자세한 내용은 설명 부분을 참조하세요.

[in] dwFlags

다음 플래그 값이 정의됩니다.

값	의미
CRYPT_OAEP 0x00000040	OAEP(최적 비대칭 암호화 패딩)(PKCS #1 버전 2)를 사용합니다. 이 플래그는 RSA 암호화/암호 해독 을 사용하는 Microsoft 고급 암호화 공급자 에서만 지원됩니다. 이 플래그는 CRYPT_DECRYPT_RSA_NO_PADDING_CHECK 플래그와 결합할 수 없습니다.
CRYPT_DECRYPT_RSA_NO_PADDING_CHECK 0x00000020	패딩을 확인하지 않고 BLOB 에서 암호 해독을 수행합니다. 이 플래그는 RSA 암호화/암호 해독 을 사용하는 Microsoft 고급 암호화 공급자 에서만 지원됩니다. 이 플래그는 CRYPT_OAEP 플래그와 결합할 수 없습니다.

[in, out] pbData

암호 해독할 데이터가 포함된 버퍼에 대한 포인터입니다. 암호 해독이 수행되면 일반 텍스트가 동일한 버퍼에 다시 배치됩니다.

이 버퍼의 암호화된 바이트 수는 pdwDataLen으로 지정됩니다.

[in, out] pdwDataLen

pbData 버퍼의 길이를 나타내는 DWORD 값에 대한 포인터입니다. 이 함수를 호출하기 전에 호출 애플리케이션은 DWORD 값을 암호 해독할 바이트 수로 설정합니다. 반환 시 DWORD 값에는 암호 해독된 일반 텍스트의 바이트 수가 포함됩니다.

블록 암호화를 사용하는 경우 암호 해독할 데이터의 마지막 섹션이고 Final 매개 변수가 TRUE인 경우가 아니면 이 데이터 길이는 블록 크기의 배수여야 합니다.

반환 값

함수가 성공하면 함수는 0이 아닌 값(TRUE)을 반환합니다.

함수가 실패하면 0(FALSE)을 반환합니다. 확장된 오류 정보는 GetLastError를 호출합니다.

NTE에서 앞에 있는 오류 코드는 사용 중인 특정 CSP에 의해 생성됩니다. 몇 가지 가능한 오류 코드는 다음과 같습니다.

값	설명
ERROR_INVALID_HANDLE	매개 변수 중 하나는 유효하지 않은 핸들을 지정합니다.
ERROR_INVALID_PARAMETER	매개 변수 중 하나에는 유효하지 않은 값이 포함되어 있습니다. 이는 가장 자주 유효하지 않은 포인터입니다.
NTE_BAD_ALGID	hKey세션 키는 이 CSP가 지원하지 않는 알고리즘을 지정합니다.
NTE_BAD_DATA	암호 해독할 데이터가 잘못되었습니다. 예를 들어 블록 암호가 사용되고 Final 플래그가 FALSE인 경우 pdwDataLen 으로 지정된 값은 블록 크기의 배수여야 합니다. 안쪽 여백이 잘못된 것으로 확인되면 이 오류가 반환될 수도 있습니다.
NTE_BAD_FLAGS	dwFlags 매개 변수가 0이 아닌 경우
NTE_BAD_HASH	hHash 매개 변수에는 유효하지 않은 핸들이 포함되어 있습니다.
NTE_BAD_KEY	hKey 매개 변수에는 키에 대한 유효한 핸들이 포함되어 있지 않습니다.
NTE_BAD_LEN	출력 버퍼의 크기가 너무 작아서 생성된 일반 텍스트를 저장할 수 없습니다.
NTE_BAD_UID	키를 만들 때 지정한 CSP 컨텍스트를 찾을 수 없습니다.
NTE_DOUBLE_ENCRYPT	애플리케이션은 동일한 데이터의 암호를 두 번 해독하려고 했습니다.
NTE_FAIL	함수가 예기치 않은 방식으로 실패했습니다.

설명

많은 양의 데이터를 해독하려면 CryptDecrypt 를 반복적으로 호출하여 섹션에서 수행할 수 있습니다. 암호 해독 엔진이 암호 해독 프로세스를 제대로 완료할 수 있도록 Final 매개 변수는 CryptDecrypt에 대한 마지막 호출에서만 TRUE로 설정해야 합니다. Final이 TRUE이면 다음 추가 작업이 수행됩니다.

키가 블록 암호화 키인 경우 데이터는 암호화의 블록 크기의 배수로 패딩됩니다. 암호화의 블록 크기를 찾으려면 CryptGetKeyParam 을 사용하여 키의 KP_BLOCKLEN 값을 가져옵니다.
암호화가 체인 모드에서 작동하는 경우 다음 CryptDecrypt 작업은 암호의 피드백 레지스터를 키의 KP_IV 값으로 다시 설정합니다.
암호화가 스트림 암호인 경우 다음 CryptDecrypt 호출은 암호화를 초기 상태로 다시 설정합니다.

Final 매개 변수를 TRUE로 설정하지 않고는 암호의 피드백 레지스터를 키의 KP_IV 값으로 설정할 수 없습니다. 추가 패딩 블록을 추가하거나 각 블록의 크기를 변경하지 않으려는 경우와 같이 필요한 경우 CryptDuplicateKey 함수를 사용하여 원래 키의 중복을 만들고 중복 키를 CryptDecrypt 함수에 전달하여 이를 시뮬레이션할 수 있습니다. 이렇게 하면 원래 키의 KP_IV 중복 키에 배치됩니다. 원래 키를 만들거나 가져온 후에는 키의 피드백 레지스터가 변경되므로 원래 키를 암호화에 사용할 수 없습니다. 다음 의사 코드는 이 작업을 수행하는 방법을 보여 줍니다.

// Set the IV for the original key. Do not use the original key for 
// encryption or decryption after doing this because the key's 
// feedback register will get modified and you cannot change it.
CryptSetKeyParam(hOriginalKey, KP_IV, newIV)

while(block = NextBlock())
{
    // Create a duplicate of the original key. This causes the 
    // original key's IV to be copied into the duplicate key's 
    // feedback register.
    hDuplicateKey = CryptDuplicateKey(hOriginalKey)

    // Decrypt the block with the duplicate key.
    CryptDecrypt(hDuplicateKey, block)

    // Destroy the duplicate key. Its feedback register has been 
    // modified by the CryptEncrypt function, so it cannot be used
    // again. It will be re-duplicated in the next iteration of the 
    // loop.
    CryptDestroyKey(hDuplicateKey)
}

Microsoft 고급 암호화 공급자는 RSA 퍼블릭 키로 직접 암호화하고 RSA 프라이빗 키를 사용하여 암호 해독을 지원합니다. 암호화는 PKCS #1 패딩을 사용합니다. 암호 해독에서 이 패딩이 확인됩니다. 암호 해독할 암호 텍스트 데이터의 길이는 데이터 암호 해독에 사용되는 RSA 키의 모듈러스 길이와 같아야 합니다. 암호 텍스트에 가장 중요한 바이트에서 0이 있는 경우 이러한 바이트는 입력 데이터 버퍼 및 입력 버퍼 길이에 포함되어야 합니다. 암호 텍스트는 little-endian 형식이어야 합니다.

예제

이 함수를 사용하는 예제는 예제 C 프로그램: 파일 암호 해독을 참조하세요.

요구 사항


지원되는 최소 클라이언트	Windows XP [데스크톱 앱만 해당]
지원되는 최소 서버	Windows Server 2003 [데스크톱 앱만 해당]
대상 플랫폼	Windows
헤더	wincrypt.h
라이브러리	Advapi32.lib
DLL	Advapi32.dll