CryptMsgOpenToDecode 함수(wincrypt.h)

  • 아티클

CryptMsgOpenToDecode 함수는 디코딩을 위한 암호화 메시지를 열고 열린 메시지의 핸들을 반환합니다. CryptMsgClose 함수가 호출될 때까지 메시지는 열린 상태로 유지됩니다.

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

구문

HCRYPTMSG CryptMsgOpenToDecode(
  [in]           DWORD             dwMsgEncodingType,
  [in]           DWORD             dwFlags,
  [in]           DWORD             dwMsgType,
  [in]           HCRYPTPROV_LEGACY hCryptProv,
  [in]           PCERT_INFO        pRecipientInfo,
  [in, optional] PCMSG_STREAM_INFO pStreamInfo
);

매개 변수

[in] dwMsgEncodingType

사용되는 인코딩 형식을 지정합니다. 다음 예제와 같이 비트 OR 작업과 결합하여 인증서 및 메시지 인코딩 형식을 모두 지정할 수 있습니다.

X509_ASN_ENCODING | PKCS_7_ASN_ENCODING

현재 정의된 인코딩 형식은 다음과 같습니다.

  • X509_ASN_ENCODING
  • PKCS_7_ASN_ENCODING

[in] dwFlags

이 매개 변수는 다음 플래그 중 하나일 수 있습니다.

값 의미
CMSG_DETACHED_FLAG
 디코딩할 메시지가 분리되었음을 나타냅니다. 이 플래그를 설정하지 않으면 메시지가 분리되지 않습니다.
CMSG_CRYPT_RELEASE_CONTEXT_FLAG
 설정되면 이 함수에 전달된 hCryptProv 가 최종 CryptMsgUpdate에서 해제됩니다. 함수가 실패하면 핸들이 해제되지 않습니다.

[in] dwMsgType

디코딩할 메시지의 유형을 지정합니다. 대부분의 경우 메시지 형식은 메시지 헤더에서 결정되고 이 매개 변수에 대해 0이 전달됩니다. 특히 인터넷 Explorer 3.0의 경우 메시지에 헤더가 없으며 디코딩할 메시지 형식을 이 함수 호출에서 제공해야 합니다. 헤더가 누락되고 이 매개 변수에 대해 0이 전달되면 함수가 실패합니다.

이 매개 변수는 다음과 같은 미리 정의된 메시지 유형 중 하나일 수 있습니다.

값 의미
CMSG_DATA
 메시지는 인코딩된 데이터입니다.
CMSG_ENVELOPED
 메시지는 봉투형 메시지입니다.
CMSG_HASHED
 메시지는 해시된 메시지입니다.
CMSG_SIGNED
 메시지는 서명된 메시지입니다.
CMSG_SIGNED_AND_ENVELOPED
 메시지는 서명되고 봉투로 둘러싸인 메시지입니다.

[in] hCryptProv

이 매개 변수는 사용되지 않으며 NULL로 설정해야 합니다.

Windows Server 2003 및 Windows XP: 메시지를 해시하는 데 사용할 암호화 공급자의 핸들 을 지정합니다. 서명된 메시지의 경우 서명 확인에 hCryptProv 가 사용됩니다. 이 매개 변수의 데이터 형식은 HCRYPTPROV입니다.

hCryptProv에서 특정 암호화 공급자를 전달하는 강력한 이유가 없는 한 이 매개 변수를 NULL로 설정합니다. NULL을 전달하면 해시, 서명 확인 또는 받는 사람 암호화 작업을 수행하기 전에 기본 RSA 또는 DSS 공급자를 가져옵니다.

[in] pRecipientInfo

이 매개 변수는 나중에 사용하도록 예약되어 있으며 NULL이어야 합니다.

[in, optional] pStreamInfo

스트리밍을 사용하지 않는 경우 이 매개 변수를 NULL로 설정해야 합니다.

참고 스트리밍은 CMSG_HASHED 메시지와 함께 사용되지 않습니다. 해시된 데이터를 처리할 때 이 매개 변수는 NULL로 설정해야 합니다.
 

스트리밍을 사용할 때 pStreamInfo 매개 변수는 CryptMsgUpdate가 실행되거나 스트리밍된 봉투 메시지를 디코딩할 때 CryptMsgControl이 실행될 때 호출할 콜백에 대한 포인터가 포함된 CMSG_STREAM_INFO 구조에 대한 포인터입니다.

서명된 메시지의 경우 콜백은 메시지의 내부 콘텐츠 에서 디코딩된 바이트의 블록을 전달합니다.

봉투 메시지의 경우 CryptMsgUpdate를 호출할 때마다 검사 cryptMsgGetParam 함수를 호출하여 CMSG_ENVELOPE_ALGORITHM_PARAM 속성을 사용할 수 있는지 여부를 확인해야 합니다. CryptMsgGetParam 은 실패하고 GetLastError 는 CryptMsgUpdate 가 CMSG_ENVELOPE_ALGORITHM_PARAM 속성을 사용할 수 있도록 메시지를 충분히 처리할 때까지 CRYPT_E_STREAM_MSG_NOT_READY 반환합니다. CMSG_ENVELOPE_ALGORITHM_PARAM 속성을 사용할 수 있는 경우 CryptMsgGetParam 함수를 사용하여 각 받는 사람에 대한 CERT_INFO 구조를 검색하여 받는 사람을 반복하여 CMSG_RECIPIENT_INFO_PARAM 속성을 검색할 수 있습니다. 인위적으로 큰 헤더 블록이 있는 봉투 메시지의 서비스 거부 공격을 방지하려면 이 프로세스 중에 CryptMsgUpdate 함수에 전달된 메모리 양을 추적해야 합니다. CMSG_ENVELOPE_ALGORITHM_PARAM 속성을 사용할 수 있기 전에 데이터 양이 애플리케이션 정의 제한을 초과하는 경우 메시지 처리를 중지하고 CryptMsgClose 함수를 호출하여 운영 체제가 메시지에 할당된 메모리를 해제하도록 해야 합니다. 제안된 제한은 메시지의 최대 허용 크기입니다. 예를 들어 최대 메시지 크기가 10MB인 경우 이 테스트의 제한은 10MB여야 합니다.

CERT_INFO 구조는 CertGetSubjectCertificateFromStore 함수를 사용하여 이전에 연 인증서 저장소에서 일치하는 인증서를 찾는 데 사용됩니다. 올바른 인증서가 발견되면 CERT_KEY_PROV_INFO_PROP_ID 매개 변수가 있는 CertGetCertificateContextProperty 함수가 호출되어 CRYPT_KEY_PROV_INFO 구조를 검색합니다. 구조체에는 CRYPT_KEY_PROV_INFO 구조체의 pwszContainerName, pwszProvName, dwProvType 및 dwFlags 멤버를 사용하여 CryptAcquireContext를 호출하여 받는 사람의 프라이빗 키를 획득하는 데 필요한 정보가 포함됩니다. 획득된 hCryptProv 및 CRYPT_KEY_PROV_INFO 구조체의 dwKeySpec 멤버는 내부 콘텐츠의 암호 해독 시작을 허용하기 위해 CMSG_CTRL_DECRYPT_PARA 구조체의 멤버로 CryptMsgControl 구조체에 전달됩니다. 그러면 스트리밍 코드는 데이터가 입력될 때 암호 해독을 수행합니다. 일반 텍스트의 결과 블록은 암호 해독된 메시지의 출력을 처리하기 위해 CMSG_STREAM_INFO 구조체의 pfnStreamOutput 멤버에 의해 지정된 콜백 함수에 전달됩니다.

참고 봉투형 메시지의 스트리밍된 디코딩은 암호 해독을 시작하기 위해 CryptMsgControl이 호출될 때까지 메모리의 암호 텍스트를 큐에 넣습니다. 누적된 암호 텍스트 가 너무 커지고 시스템이 메모리가 부족해지기 전에 데이터를 디스크에 저장하거나 다른 곳으로 라우팅할 수 있도록 애플리케이션에서 적시에 암호 해독을 시작해야 합니다.
 

봉투형 메시지로 묶인 서명된 메시지의 경우 봉투형 메시지의 스트리밍 디코딩에서 일반 텍스트 출력을 다른 스트리밍 디코딩으로 공급하여 서명된 메시지를 처리할 수 있습니다.

반환 값

함수가 성공하면 함수는 열린 메시지의 핸들을 반환합니다.

이 함수가 실패하면 NULL을 반환합니다. 확장 오류 정보는 GetLastError를 호출합니다.

다음 표에서는 GetLastError 함수에서 가장 일반적으로 반환되는 오류 코드를 나열합니다.

값 Description
E_INVALIDARG
 하나 이상의 인수가 잘못되었습니다.
E_OUTOFMEMORY
 메모리 할당 오류가 발생했습니다.

요구 사항

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

추가 정보

CryptMsgClose

CryptMsgGetParam

CryptMsgOpenToEncode

CryptMsgUpdate

하위 수준 메시지 함수

간소화된 메시지 함수