CryptMsgControl 함수(wincrypt.h)
CryptMsgControl 함수는 CryptMsgUpdate 함수에 대한 최종 호출로 메시지가 디코딩된 후 제어 작업을 수행합니다. 이 함수에서 제공하는 제어 작업은 암호 해독, 서명 및 해시 확인, 인증서 추가 및 삭제, CRL( 인증서 해지 목록 ), 서명자 및 인증되지 않은 특성에 사용됩니다.
S/MIME( Secure/Multipurpose Internet Mail Extensions ) 전자 메일 상호 운용성을 지원하기 위해 암호화된 메시지 처리에 영향을 주는 중요한 변경 사항이 CryptoAPI에 적용되었습니다. 자세한 내용은 CryptMsgOpenToEncode 함수에 대한 설명을 참조하세요.
구문
BOOL CryptMsgControl(
[in] HCRYPTMSG hCryptMsg,
[in] DWORD dwFlags,
[in] DWORD dwCtrlType,
[in] void const *pvCtrlPara
);
매개 변수
[in] hCryptMsg
컨트롤을 적용할 암호화 메시지의 핸들입니다.
[in] dwFlags
다음 값은 dwCtrlType 매개 변수가 다음 중 하나일 때 정의됩니다.
- CMSG_CTRL_DECRYPT
- CMSG_CTRL_KEY_TRANS_DECRYPT
- CMSG_CTRL_KEY_AGREE_DECRYPT
- CMSG_CTRL_MAIL_LIST_DECRYPT
| 값 | 의미 |
|---|---|
|
암호화 공급자에 대한 핸들은 CryptMsgClose 함수에 대한 최종 호출에서 해제됩니다. CryptMsgControl 함수가 실패하면 이 핸들이 해제되지 않습니다. |
dwCtrlType 매개 변수가 암호 해독 작업을 지정하지 않으면 이 값을 0으로 설정합니다.
[in] dwCtrlType
수행할 작업의 유형입니다. 현재 정의된 메시지 컨트롤 형식 및 pvCtrlPara 매개 변수에 전달되어야 하는 구조체의 형식은 다음 표에 나와 있습니다.
| 값 | 의미 |
|---|---|
|
특성 인증서의 인코딩된 바이트를 포함하는 BLOB 입니다. |
|
메시지에 추가할 인증서의 인코딩된 바이트를 포함하는 CRYPT_INTEGER_BLOB 구조체입니다. |
|
서명자 정보를 포함하는 CMSG_CMS_SIGNER_INFO 구조체입니다. 서명자 정보에 서명자가 포함되어 있으므로 이 작업은 CMSG_CTRL_ADD_SIGNER 다릅니다. |
|
메시지에 추가할 CRL의 인코딩된 바이트를 포함하는 BLOB입니다. |
|
메시지에 추가할 서명자 정보가 포함된 CMSG_SIGNER_ENCODE_INFO 구조체입니다. |
|
서명자의 인덱스와 메시지에 추가할 인증되지 않은 특성 정보가 포함된 BLOB이 포함된 CMSG_CTRL_ADD_SIGNER_UNAUTH_ATTR_PARA 구조체입니다. |
|
지정된 키 전송 수신자에 대한 메시지의 암호를 해독하는 데 사용되는 CMSG_CTRL_DECRYPT_PARA 구조체입니다. 이 값은 RSA 받는 사람에게 적용됩니다. 이 작업은 CryptMsgControl 함수가 받는 사람 인덱스를 검색하여 키 전송 받는 사람 정보를 가져오도록 지정합니다. 함수가 실패하면 키 전송 받는 사람이 없으면 GetLastError 가 CRYPT_E_INVALID_INDEX 반환합니다. |
|
제거할 특성 인증서의 인덱스입니다. |
|
메시지에서 삭제할 인증서의 인덱스입니다. |
|
메시지에서 삭제할 CRL의 인덱스입니다. |
|
삭제할 서명자의 인덱스입니다. |
|
서명자를 지정하는 인덱스와 삭제할 서명자의 인증되지 않은 특성을 지정하는 인덱스가 포함된 CMSG_CTRL_DEL_SIGNER_UNAUTH_ATTR_PARA 구조체입니다. |
|
강력한 서명 검사를 수행하는 데 사용되는 CERT_STRONG_SIGN_PARA 구조체입니다.
강력한 서명을 검사 위해 CryptMsgGetAndVerifySigner를 호출하기 전에 또는 다음 컨트롤 형식이 설정된 CryptMsgControl을 호출하기 전에 이 컨트롤 형식을 지정합니다.
|
|
지정된 키 계약 세션 키에 대한 메시지의 암호를 해독하는 데 사용되는 CMSG_CTRL_KEY_AGREE_DECRYPT_PARA 구조체입니다. 키 계약은 Diffie-Hellman 암호화/암호 해독과 함께 사용됩니다. |
|
지정된 키 전송 수신자에 대한 메시지의 암호를 해독하는 데 사용되는 CMSG_CTRL_KEY_TRANS_DECRYPT_PARA 구조체입니다. 키 전송은 RSA 암호화/암호 해독과 함께 사용됩니다. |
|
이전에 KEK(분산 키 암호화 키)를 사용하여 지정된 받는 사람의 메시지를 해독하는 데 사용되는 CMSG_CTRL_MAIL_LIST_DECRYPT_PARA 구조입니다. |
|
이 값은 사용되지 않습니다. |
|
서명을 확인할 메시지의 서명자를 식별하는 CERT_INFO 구조체입니다. |
|
서명자 인덱스와 메시지 서명을 확인하는 공개 키를 지정하는 CMSG_CTRL_VERIFY_SIGNATURE_EX_PARA 구조체입니다. 서명자 공개 키는 CERT_PUBLIC_KEY_INFO 구조, 인증서 컨텍스트 또는 인증서 체인 컨텍스트일 수 있습니다. |
[in] pvCtrlPara
dwCtrlType 값으로 결정되는 구조체에 대한 포인터입니다.
| dwCtrlType 값 | 의미 |
|---|---|
|
디코딩은 스트리밍된 콘텐츠가 암호 해독되는 것처럼 수행됩니다. 이 호출 전에 암호화된 스트리밍 콘텐츠가 누적된 경우 암호화 텍스트의 암호 해독으로 인해 발생하는 일반 텍스트 의 일부 또는 전부는 CryptMsgOpenToDecode 함수 호출에 지정된 콜백 함수를 통해 애플리케이션에 다시 전달됩니다.
참고 봉투 메시지를 스트리밍할 때 cryptMsgControl 함수는 CMSG_ENVELOPE_ALGORITHM_PARAM 가용성에 대한 폴링이 성공할 때까지 호출되지 않습니다. 폴링이 성공하지 못하면 오류가 발생합니다. 해당 폴링에 대한 설명은 CryptMsgOpenToDecode 함수를 참조하세요.
|
|
메시지 내용에서 계산된 해시 는 메시지에 포함된 해시와 비교됩니다. |
|
pvCtrlPara 는 메시지에 추가할 서명자 정보가 포함된 CMSG_SIGNER_ENCODE_INFO 구조를 가리킵니다. |
|
삭제가 완료되면 이 메시지에 사용하는 다른 서명자 인덱스는 더 이상 유효하지 않으며 CryptMsgGetParam 함수를 호출하여 다시 입력해야 합니다. |
|
삭제가 완료되면 이 서명자에 사용하는 다른 인증되지 않은 특성 인덱스는 더 이상 유효하지 않으며 CryptMsgGetParam 함수를 호출하여 다시 입력해야 합니다. |
|
삭제가 완료되면 이 메시지에 사용 중인 다른 인증서 인덱스는 더 이상 유효하지 않으며 CryptMsgGetParam 함수를 호출하여 다시 입력해야 합니다. |
|
삭제가 완료되면 이 메시지에 사용되는 다른 CRL 인덱스는 더 이상 유효하지 않으며 CryptMsgGetParam 함수를 호출하여 다시 입력해야 합니다. |
반환 값
함수가 성공하면 반환 값이 0이 아닙니다.
함수가 실패하면 반환 값이 0이고 GetLastError 함수는 ASN.1( 추상 구문 표기법 1) 인코딩/디코딩 오류를 반환합니다. 이러한 오류에 대한 자세한 내용은 ASN.1 반환 값 인코딩/디코딩을 참조하세요.
스트리밍된 봉투 메시지를 디코딩할 때 의 pStreamInfo 매개 변수로 지정된 애플리케이션 정의 콜백 함수에서 오류가 발생합니다.
CryptMsgOpenToDecode 함수는 CryptMsgControl 함수로 전파될 수 있습니다. 이 경우 콜백 함수가 반환된 후 CryptMsgControl 함수에서 SetLastError 함수를 호출하지 않습니다. 이렇게 하면 애플리케이션의 제어 하에서 발생한 모든 오류가 유지됩니다. 애플리케이션이 스트리밍된 데이터를 처리하는 동안 오류가 발생하는 경우 SetLastError 함수를 호출하는 것은 콜백 함수(또는 호출하는 API 중 하나)의 책임입니다.
전파된 오류는 다음 함수에서 발생할 수 있습니다.
- CryptCreateHash
- CryptDecrypt
- CryptGetHashParam
- CryptGetUserKey
- CryptHashData
- CryptImportKey
- CryptSignHash
- CryptVerifySignature
다음 오류 코드가 가장 일반적으로 반환됩니다.
| 반환 코드 | 설명 |
|---|---|
|
메시지 콘텐츠가 이미 암호 해독되었습니다. dwCtrlType 매개 변수를 CMSG_CTRL_DECRYPT 설정하면 이 오류가 반환될 수 있습니다. |
|
메시지에는 예상되는 인증된 특성이 포함되어 있지 않습니다. dwCtrlType 매개 변수를 CMSG_CTRL_VERIFY_SIGNATURE 설정하면 이 오류가 반환될 수 있습니다. |
|
인코딩 또는 디코딩하는 동안 오류가 발생했습니다. dwCtrlType 매개 변수를 CMSG_CTRL_VERIFY_SIGNATURE 설정하면 이 오류가 반환될 수 있습니다. |
|
컨트롤 형식이 잘못되었습니다. |
|
해시 값이 잘못되었습니다. |
|
인덱스 값이 잘못되었습니다. |
|
메시지 유형이 잘못되었습니다. |
|
개체 식별자의 형식이 잘못되었습니다. dwCtrlType 매개 변수를 CMSG_CTRL_ADD_SIGNER 설정하면 이 오류가 반환될 수 있습니다. |
|
봉투형 데이터 메시지에 지정된 받는 사람이 포함되어 있지 않습니다. dwCtrlType 매개 변수를 CMSG_CTRL_DECRYPT 설정하면 이 오류가 반환될 수 있습니다. |
|
메시지에 지정된 서명자를 찾을 수 없습니다. dwCtrlType 매개 변수를 CMSG_CTRL_VERIFY_SIGNATURE 설정하면 이 오류가 반환될 수 있습니다. |
|
암호화 알고리즘을 알 수 없습니다. |
|
메시지는 예상대로 인코딩되지 않습니다. dwCtrlType 매개 변수를 CMSG_CTRL_VERIFY_SIGNATURE 설정하면 이 오류가 반환될 수 있습니다. |
|
하나 이상의 인수가 잘못되었습니다. dwCtrlType 매개 변수를 CMSG_CTRL_DECRYPT 설정하면 이 오류가 반환될 수 있습니다. |
|
메모리가 부족하여 작업을 완료할 수 없었습니다. |
요구 사항
| 요구 사항 | 값 |
|---|---|
| 지원되는 최소 클라이언트 | Windows XP [데스크톱 앱 | UWP 앱] |
| 지원되는 최소 서버 | Windows Server 2003 [데스크톱 앱 | UWP 앱] |
| 대상 플랫폼 | Windows |
| 헤더 | wincrypt.h |
| 라이브러리 | Crypt32.lib |
| DLL | Crypt32.dll |