CryptEncrypt 함수(wincrypt.h)

아티클
03/15/2023

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

CryptEncrypt 함수는 데이터를 암호화합니다. 데이터를 암호화하는 데 사용되는 알고리즘은 CSP 모듈에서 보유한 키로 지정되며 hKey 매개 변수에서 참조됩니다.

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

중요CryptEncrypt 함수는 스레드로부터 안전한 것으로 보장되지 않으며 여러 호출자가 동시에 호출하는 경우 잘못된 결과를 반환할 수 있습니다.

구문

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

매개 변수

[in] hKey

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

키는 사용되는 암호화 알고리즘을 지정합니다.

[in] hHash

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

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

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

[in] Final

이 섹션이 암호화되는 계열의 마지막 섹션인지 여부를 지정하는 부울 값입니다. 마지막 또는 유일한 블록의 경우 Final이 TRUE 로 설정되고 암호화할 블록이 더 있는 경우 FALSE 로 설정됩니다. 자세한 내용은 설명 부분을 참조하세요.

[in] dwFlags

다음 dwFlags 값은 정의되지만 나중에 사용하도록 예약됩니다.

값	의미
CRYPT_OAEP	OAEP(최적 비대칭 암호화 패딩)(PKCS #1 버전 2)를 사용합니다. 이 플래그는 RSA 암호화/암호 해독 을 사용하는 Microsoft 고급 암호화 공급자 에서만 지원됩니다.

[in, out] pbData

암호화할 일반 텍스트가 포함된 버퍼에 대한 포인터입니다. 이 버퍼의 일반 텍스트는 이 함수에서 만든 암호 텍스트 로 덮어씁니다.

pdwDataLen 매개 변수는 일반 텍스트의 길이(바이트)를 포함하는 변수를 가리킵니다. dwBufLen 매개 변수에는 이 버퍼의 총 크기(바이트)가 포함됩니다.

이 매개 변수에 NULL이 포함된 경우 이 함수는 암호 텍스트에 필요한 크기를 계산하고 pdwDataLen 매개 변수가 가리키는 값에 배치합니다.

[in, out] pdwDataLen

항목에서 pbData 버퍼에 있는 일반 텍스트의 길이(바이트)를 포함하는 DWORD 값에 대한 포인터입니다. 종료 시 이 DWORD 에는 pbData 버퍼에 기록된 암호 텍스트의 길이(바이트)가 포함됩니다.

pbData에 할당된 버퍼가 암호화된 데이터를 저장할 만큼 크지 않은 경우 GetLastError는 ERROR_MORE_DATA 반환하고 pdwDataLen이 가리키는 DWORD 값에 필요한 버퍼 크기를 바이트 단위로 저장합니다.

pbData가 NULL이면 오류가 반환되지 않으며 함수는 pdwDataLen이 가리키는 DWORD 값에 암호화된 데이터의 크기를 바이트 단위로 저장합니다. 이렇게 하면 애플리케이션에서 올바른 버퍼 크기를 확인할 수 있습니다.

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

[in] dwBufLen

입력 pbData 버퍼의 총 크기(바이트)를 지정합니다.

사용된 알고리즘에 따라 암호화된 텍스트는 원래 일반 텍스트보다 클 수 있습니다. 이 경우 pbData 버퍼는 암호화된 텍스트와 패딩을 포함할 수 있을 만큼 커야 합니다.

일반적으로 스트림 암호화 를 사용하는 경우 암호 텍스트는 일반 텍스트와 동일한 크기입니다. 블록 암호화를 사용하는 경우 암호 텍스트는 일반 텍스트보다 큰 블록 길이까지입니다.

반환 값

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

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

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

값	Description
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_HASH_STATE	이미 "완료됨"으로 표시된 해시 개체에 데이터를 추가하려고 했습니다.
NTE_BAD_KEY	hKey 매개 변수에는 키에 대한 유효한 핸들이 포함되어 있지 않습니다.
NTE_BAD_LEN	출력 버퍼의 크기가 너무 작아서 생성된 암호 텍스트를 저장할 수 없습니다.
NTE_BAD_UID	키를 만들 때 지정한 CSP 컨텍스트를 찾을 수 없습니다.
NTE_DOUBLE_ENCRYPT	애플리케이션은 동일한 데이터를 두 번 암호화하려고 했습니다.
NTE_FAIL	함수가 예기치 않은 방식으로 실패했습니다.
NTE_NO_MEMORY	작업 중에 CSP 메모리가 부족했습니다.

설명

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

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

Final 매개 변수를 TRUE로 설정하지 않고는 암호의 피드백 레지스터를 키의 KP_IV 값으로 설정할 수 없습니다. 추가 패딩 블록을 추가하거나 각 블록의 크기를 변경하지 않으려는 경우와 같이 필요한 경우 CryptDuplicateKey 함수를 사용하여 원래 키의 중복을 만들고 중복 키를 CryptEncrypt 함수에 전달하여 이를 시뮬레이션할 수 있습니다. 이렇게 하면 원래 키의 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)

    // Encrypt the block with the duplicate key.
    CryptEncrypt(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 키를 사용하여 CryptEncrypt 를 호출하여 암호화할 수 있는 일반 텍스트 데이터의 길이는 키 모듈러스에서 11바이트를 뺀 길이입니다. 11바이트는 PKCS #1 패딩에 대해 선택한 최소값입니다. 암호 텍스트는 little-endian 형식으로 반환됩니다.

예제

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

요구 사항

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