CryptEncrypt 함수(wincrypt.h)
S/MIME(Secure/Multipurpose Internet Mail Extensions) 전자 메일 상호 운용성을 지원하기 위한 중요한 변경 사항은 봉투 메시지 처리에 영향을 주는 CryptoAPI에 적용되었습니다. 자세한 내용은 CryptMsgOpenToEncode설명 섹션을 참조하세요.
통사론
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
암호화되는 계열의 마지막 섹션인지 여부를 지정하는 부울 값입니다.
[in] dwFlags
다음 dwFlags 값은 정의되지만 나중에 사용하도록 예약되어 있습니다.
| 값 | 의미 |
|---|---|
|
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 값에 바이트 단위로 저장합니다.
[in] dwBufLen
입력 pbData 버퍼의 총 크기(바이트)를 지정합니다.
사용된 알고리즘에 따라 암호화된 텍스트는 원래 일반 텍스트보다 클 수 있습니다. 이 경우 pbData 버퍼는 암호화된 텍스트와 패딩을 포함할 수 있을 만큼 커야 합니다.
일반적으로 스트림 암호화 사용하는 경우 암호 텍스트는 일반 텍스트와 같은 크기입니다. 블록 암호 사용하는 경우 암호 텍스트는 일반 텍스트보다 큰 블록 길이까지입니다.
반환 값
함수가 성공하면 함수는 0이 아닌 값(TRUE)을 반환합니다.
함수가 실패하면 0(FALSE)을 반환합니다. 확장 오류 정보는 GetLastError호출합니다.
NTE에 의해 앞에 있는 오류 코드는 사용 중인 특정 CSP에 의해 생성됩니다. 몇 가지 가능한 오류 코드는 다음과 같습니다.
| 값 | 묘사 |
|---|---|
|
매개 변수 중 하나는 유효하지 않은 핸들을 지정합니다. |
|
매개 변수 중 하나에 유효하지 않은 값이 포함되어 있습니다. 이는 가장 자주 유효하지 않은 포인터입니다. |
|
hKey세션 키 이 CSP가 지원하지 않는 알고리즘을 지정합니다. |
|
암호화할 데이터가 잘못되었습니다. 예를 들어 블록 암호가 사용되고 |
|
dwFlags 매개 변수가 0이 아닌 경우 |
|
hHash 매개 변수에는 유효하지 않은 핸들이 포함되어 있습니다. |
|
이미 "완료됨"으로 표시된 해시 개체에 데이터를 추가하려고 했습니다. |
|
hKey 매개 변수에는 키에 대한 유효한 핸들이 포함되어 있지 않습니다. |
|
출력 버퍼의 크기가 너무 작아서 생성된 암호 텍스트를 보관할 수 없습니다. |
|
키를 만들 때 지정한 CSP 컨텍스트를 찾을 수 없습니다. |
|
애플리케이션에서 동일한 데이터를 두 번 암호화하려고 했습니다. |
|
함수가 예기치 않은 방식으로 실패했습니다. |
|
작업 중에 CSP 메모리가 부족합니다. |
발언
많은 양의 데이터를 암호화해야 하는 경우 CryptEncrypt 반복적으로 호출하여 섹션에서 수행할 수 있습니다.
- 키가 블록 암호 키인 경우 데이터는 암호 블록 크기의 배수로 채워집니다. 데이터 길이가 암호의 블록 크기와 같으면 한 개의 추가 패딩 블록이 데이터에 추가됩니다. 암호의 블록 크기를 찾으려면 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)
}
예제
이 함수를 사용하는 예제는 예제 C 프로그램: 파일 암호화 및 예제 C 프로그램: 파일암호 해독을 참조하세요.
요구 사항
| 요구 | 값 |
|---|---|
| 지원되는 최소 클라이언트 | Windows XP [데스크톱 앱만 해당] |
| 지원되는 최소 서버 | Windows Server 2003 [데스크톱 앱만 해당] |
| 대상 플랫폼 | Windows |
| 헤더 | wincrypt.h |
| 라이브러리 | Advapi32.lib |
| DLL | Advapi32.dll |