다음을 통해 공유


CryptEncrypt 함수(wincrypt.h)

중요 이 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

암호화되는 계열의 마지막 섹션인지 여부를 지정하는 부울 값입니다. 최종 마지막 또는 유일한 블록에 대해 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 값에 대한 포인터입니다. 종료 시 이 DWORDpbData 버퍼에 기록된 암호 텍스트의 길이(바이트)를 포함합니다.

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

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

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

[in] dwBufLen

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

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

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

반환 값

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

발언

많은 양의 데이터를 암호화해야 하는 경우 CryptEncrypt 반복적으로 호출하여 섹션에서 수행할 수 있습니다. Final 매개 변수는 암호화 엔진이 암호화 프로세스를 제대로 완료할 수 있도록 CryptEncrypt대한 마지막 호출에서 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

참고 항목

CryptCreateHash

CryptDecrypt

CryptGenKey

CryptGetHashParam

CryptGetKeyParam

CryptImportKey

CryptMsgOpenToEncode

CryptSignHash

데이터 암호화 및 암호 해독 함수