다음을 통해 공유


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
의미
CMSG_CRYPT_RELEASE_CONTEXT_FLAG
암호화 공급자에 대한 핸들은 CryptMsgClose 함수에 대한 최종 호출에서 해제됩니다. CryptMsgControl 함수가 실패하면 이 핸들이 해제되지 않습니다.
 

dwCtrlType 매개 변수가 암호 해독 작업을 지정하지 않으면 이 값을 0으로 설정합니다.

[in] dwCtrlType

수행할 작업의 유형입니다. 현재 정의된 메시지 컨트롤 형식 및 pvCtrlPara 매개 변수에 전달되어야 하는 구조체의 형식은 다음 표에 나와 있습니다.

의미
CMSG_CTRL_ADD_ATTR_CERT
14(0xE)
특성 인증서의 인코딩된 바이트를 포함하는 BLOB 입니다.
CMSG_CTRL_ADD_CERT
10(0xA)
메시지에 추가할 인증서의 인코딩된 바이트를 포함하는 CRYPT_INTEGER_BLOB 구조체입니다.
CMSG_CTRL_ADD_CMS_SIGNER_INFO
20(0x14)
서명자 정보를 포함하는 CMSG_CMS_SIGNER_INFO 구조체입니다. 서명자 정보에 서명자가 포함되어 있으므로 이 작업은 CMSG_CTRL_ADD_SIGNER 다릅니다.
CMSG_CTRL_ADD_CRL
12(0xC)
메시지에 추가할 CRL의 인코딩된 바이트를 포함하는 BLOB입니다.
CMSG_CTRL_ADD_SIGNER
6(0x6)
메시지에 추가할 서명자 정보가 포함된 CMSG_SIGNER_ENCODE_INFO 구조체입니다.
CMSG_CTRL_ADD_SIGNER_UNAUTH_ATTR
8(0x8)
서명자의 인덱스와 메시지에 추가할 인증되지 않은 특성 정보가 포함된 BLOB이 포함된 CMSG_CTRL_ADD_SIGNER_UNAUTH_ATTR_PARA 구조체입니다.
CMSG_CTRL_DECRYPT
2(0x2)
지정된 키 전송 수신자에 대한 메시지의 암호를 해독하는 데 사용되는 CMSG_CTRL_DECRYPT_PARA 구조체입니다. 이 값은 RSA 받는 사람에게 적용됩니다. 이 작업은 CryptMsgControl 함수가 받는 사람 인덱스를 검색하여 키 전송 받는 사람 정보를 가져오도록 지정합니다. 함수가 실패하면 키 전송 받는 사람이 없으면 GetLastErrorCRYPT_E_INVALID_INDEX 반환합니다.
CMSG_CTRL_DEL_ATTR_CERT
15(0xF)
제거할 특성 인증서의 인덱스입니다.
CMSG_CTRL_DEL_CERT
11(0xB)
메시지에서 삭제할 인증서의 인덱스입니다.
CMSG_CTRL_DEL_CRL
13(0xD)
메시지에서 삭제할 CRL의 인덱스입니다.
CMSG_CTRL_DEL_SIGNER
7(0x7)
삭제할 서명자의 인덱스입니다.
CMSG_CTRL_DEL_SIGNER_UNAUTH_ATTR
9(0x9)
서명자를 지정하는 인덱스와 삭제할 서명자의 인증되지 않은 특성을 지정하는 인덱스가 포함된 CMSG_CTRL_DEL_SIGNER_UNAUTH_ATTR_PARA 구조체입니다.
CMSG_CTRL_ENABLE_STRONG_SIGNATURE
21(0x15)
강력한 서명 검사를 수행하는 데 사용되는 CERT_STRONG_SIGN_PARA 구조체입니다.

강력한 서명을 검사 위해 CryptMsgGetAndVerifySigner를 호출하기 전에 또는 다음 컨트롤 형식이 설정된 CryptMsgControl을 호출하기 전에 이 컨트롤 형식을 지정합니다.

  • CMSG_CTRL_VERIFY_SIGNATURE
  • CMSG_CTRL_VERIFY_SIGNATURE_EX
서명이 성공적으로 확인되면 이 함수는 강력한 서명을 확인합니다. 서명이 강력하지 않으면 작업이 실패하고 GetLastError 값이 NTE_BAD_ALGID 설정됩니다.
CMSG_CTRL_KEY_AGREE_DECRYPT
17(0x11)
지정된 키 계약 세션 키에 대한 메시지의 암호를 해독하는 데 사용되는 CMSG_CTRL_KEY_AGREE_DECRYPT_PARA 구조체입니다. 키 계약은 Diffie-Hellman 암호화/암호 해독과 함께 사용됩니다.
CMSG_CTRL_KEY_TRANS_DECRYPT
16(0x10)
지정된 키 전송 수신자에 대한 메시지의 암호를 해독하는 데 사용되는 CMSG_CTRL_KEY_TRANS_DECRYPT_PARA 구조체입니다. 키 전송은 RSA 암호화/암호 해독과 함께 사용됩니다.
CMSG_CTRL_MAIL_LIST_DECRYPT
18(0x12)
이전에 KEK(분산 키 암호화 키)를 사용하여 지정된 받는 사람의 메시지를 해독하는 데 사용되는 CMSG_CTRL_MAIL_LIST_DECRYPT_PARA 구조입니다.
CMSG_CTRL_VERIFY_HASH
5(0x5)
이 값은 사용되지 않습니다.
CMSG_CTRL_VERIFY_SIGNATURE
1(0x1)
서명을 확인할 메시지의 서명자를 식별하는 CERT_INFO 구조체입니다.
CMSG_CTRL_VERIFY_SIGNATURE_EX
19(0x13)
서명자 인덱스와 메시지 서명을 확인하는 공개 키를 지정하는 CMSG_CTRL_VERIFY_SIGNATURE_EX_PARA 구조체입니다. 서명자 공개 키는 CERT_PUBLIC_KEY_INFO 구조, 인증서 컨텍스트 또는 인증서 체인 컨텍스트일 수 있습니다.

[in] pvCtrlPara

dwCtrlType 값으로 결정되는 구조체에 대한 포인터입니다.

dwCtrlType 의미
CMSG_CTRL_DECRYPT, CMSG_CTRL_KEY_TRANS_DECRYPT, CMSG_CTRL_KEY_AGREE_DECRYPT 또는 CMSG_CTRL_MAIL_LIST_DECRYPT 스트리밍된 봉투 메시지가 디코딩되고 있습니다.
디코딩은 스트리밍된 콘텐츠가 암호 해독되는 것처럼 수행됩니다. 이 호출 전에 암호화된 스트리밍 콘텐츠가 누적된 경우 암호화 텍스트의 암호 해독으로 인해 발생하는 일반 텍스트 의 일부 또는 전부는 CryptMsgOpenToDecode 함수 호출에 지정된 콜백 함수를 통해 애플리케이션에 다시 전달됩니다.
참고 봉투 메시지를 스트리밍할 때 cryptMsgControl 함수는 CMSG_ENVELOPE_ALGORITHM_PARAM 가용성에 대한 폴링이 성공할 때까지 호출되지 않습니다. 폴링이 성공하지 못하면 오류가 발생합니다. 해당 폴링에 대한 설명은 CryptMsgOpenToDecode 함수를 참조하세요.
 
CMSG_CTRL_VERIFY_HASH
메시지 내용에서 계산된 해시 는 메시지에 포함된 해시와 비교됩니다.
CMSG_CTRL_ADD_SIGNER
pvCtrlPara 는 메시지에 추가할 서명자 정보가 포함된 CMSG_SIGNER_ENCODE_INFO 구조를 가리킵니다.
CMSG_CTRL_DEL_SIGNER
삭제가 완료되면 이 메시지에 사용하는 다른 서명자 인덱스는 더 이상 유효하지 않으며 CryptMsgGetParam 함수를 호출하여 다시 입력해야 합니다.
CMSG_CTRL_DEL_SIGNER_UNAUTH_ATTR
삭제가 완료되면 이 서명자에 사용하는 다른 인증되지 않은 특성 인덱스는 더 이상 유효하지 않으며 CryptMsgGetParam 함수를 호출하여 다시 입력해야 합니다.
CMSG_CTRL_DEL_CERT
삭제가 완료되면 이 메시지에 사용 중인 다른 인증서 인덱스는 더 이상 유효하지 않으며 CryptMsgGetParam 함수를 호출하여 다시 입력해야 합니다.
CMSG_CTRL_DEL_CRL
삭제가 완료되면 이 메시지에 사용되는 다른 CRL 인덱스는 더 이상 유효하지 않으며 CryptMsgGetParam 함수를 호출하여 다시 입력해야 합니다.

반환 값

함수가 성공하면 반환 값이 0이 아닙니다.

함수가 실패하면 반환 값이 0이고 GetLastError 함수는 ASN.1( 추상 구문 표기법 1) 인코딩/디코딩 오류를 반환합니다. 이러한 오류에 대한 자세한 내용은 ASN.1 반환 값 인코딩/디코딩을 참조하세요.

스트리밍된 봉투 메시지를 디코딩할 때 의 pStreamInfo 매개 변수로 지정된 애플리케이션 정의 콜백 함수에서 오류가 발생합니다.
CryptMsgOpenToDecode 함수는 CryptMsgControl 함수로 전파될 수 있습니다. 이 경우 콜백 함수가 반환된 후 CryptMsgControl 함수에서 SetLastError 함수를 호출하지 않습니다. 이렇게 하면 애플리케이션의 제어 하에서 발생한 모든 오류가 유지됩니다. 애플리케이션이 스트리밍된 데이터를 처리하는 동안 오류가 발생하는 경우 SetLastError 함수를 호출하는 것은 콜백 함수(또는 호출하는 API 중 하나)의 책임입니다.

전파된 오류는 다음 함수에서 발생할 수 있습니다.

다음 오류 코드가 가장 일반적으로 반환됩니다.

반환 코드 설명
CRYPT_E_ALREADY_DECRYPTED
메시지 콘텐츠가 이미 암호 해독되었습니다. dwCtrlType 매개 변수를 CMSG_CTRL_DECRYPT 설정하면 이 오류가 반환될 수 있습니다.
CRYPT_E_AUTH_ATTR_MISSING
메시지에는 예상되는 인증된 특성이 포함되어 있지 않습니다. dwCtrlType 매개 변수를 CMSG_CTRL_VERIFY_SIGNATURE 설정하면 이 오류가 반환될 수 있습니다.
CRYPT_E_BAD_ENCODE
인코딩 또는 디코딩하는 동안 오류가 발생했습니다. dwCtrlType 매개 변수를 CMSG_CTRL_VERIFY_SIGNATURE 설정하면 이 오류가 반환될 수 있습니다.
CRYPT_E_CONTROL_TYPE
컨트롤 형식이 잘못되었습니다.
CRYPT_E_HASH_VALUE
해시 값이 잘못되었습니다.
CRYPT_E_INVALID_INDEX
인덱스 값이 잘못되었습니다.
CRYPT_E_INVALID_MSG_TYPE
메시지 유형이 잘못되었습니다.
CRYPT_E_OID_FORMAT
개체 식별자의 형식이 잘못되었습니다. dwCtrlType 매개 변수를 CMSG_CTRL_ADD_SIGNER 설정하면 이 오류가 반환될 수 있습니다.
CRYPT_E_RECIPIENT_NOT_FOUND
봉투형 데이터 메시지에 지정된 받는 사람이 포함되어 있지 않습니다. dwCtrlType 매개 변수를 CMSG_CTRL_DECRYPT 설정하면 이 오류가 반환될 수 있습니다.
CRYPT_E_SIGNER_NOT_FOUND
메시지에 지정된 서명자를 찾을 수 없습니다. dwCtrlType 매개 변수를 CMSG_CTRL_VERIFY_SIGNATURE 설정하면 이 오류가 반환될 수 있습니다.
CRYPT_E_UNKNOWN_ALGO
암호화 알고리즘을 알 수 없습니다.
CRYPT_E_UNEXPECTED_ENCODING
메시지는 예상대로 인코딩되지 않습니다. dwCtrlType 매개 변수를 CMSG_CTRL_VERIFY_SIGNATURE 설정하면 이 오류가 반환될 수 있습니다.
E_INVALIDARG
하나 이상의 인수가 잘못되었습니다. dwCtrlType 매개 변수를 CMSG_CTRL_DECRYPT 설정하면 이 오류가 반환될 수 있습니다.
E_OUTOFMEMORY
메모리가 부족하여 작업을 완료할 수 없었습니다.

요구 사항

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

추가 정보

하위 수준 메시지 함수

간소화된 메시지 함수