CryptMsgOpenToEncode 함수(wincrypt.h)

아티클
08/27/2023

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

구문

HCRYPTMSG CryptMsgOpenToEncode(
  [in]           DWORD             dwMsgEncodingType,
  [in]           DWORD             dwFlags,
  [in]           DWORD             dwMsgType,
  [in]           void const        *pvMsgEncodeInfo,
  [in, optional] LPSTR             pszInnerContentObjID,
  [in]           PCMSG_STREAM_INFO pStreamInfo
);

매개 변수

[in] dwMsgEncodingType

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

X509_ASN_ENCODING | PKCS_7_ASN_ENCODING

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

X509_ASN_ENCODING
PKCS_7_ASN_ENCODING

[in] dwFlags

현재 정의된 dwFlag는 다음 표에 나와 있습니다.

값	의미
CMSG_BARE_CONTENT_FLAG	스트리밍된 출력에는 외부 ContentInfo 래퍼가 없습니다(PKCS #7에 정의된 대로). 이렇게 하면 묶은 메시지로 스트리밍하는 것이 적합합니다.
CMSG_DETACHED_FLAG	CryptMsgUpdate에 대한 후속 호출에 대해 분리된 데이터가 제공됩니다.
CMSG_AUTHENTICATED_ATTRIBUTES_FLAG	인증된 특성은 PKCS #7에서 정의한 대로 SignerInfo에 포함되어야 합니다(그렇지 않으면 필요하지 않은 경우).
CMSG_CONTENTS_OCTETS_FLAG	DER(Distinguished Encoding Rules)을 사용하여 인코딩된 메시지의 크기를 계산할 때 사용되며 봉투형 메시지 내에 중첩됩니다. 이는 스트리밍을 수행할 때 특히 유용합니다.
CMSG_CMS_ENCAPSULATED_CONTENT_FLAG	설정하면 데이터 형식이 아닌 내부 콘텐츠 가 OCTET STRING 내에 캡슐화됩니다. 서명된 메시지와 봉투 메시지 모두에 적용할 수 있습니다.
CMSG_CRYPT_RELEASE_CONTEXT_FLAG	설정되면 이 함수에 전달되는 hCryptProv 가 최종 CryptMsgUpdate에서 해제됩니다. 함수가 실패하면 핸들이 해제되지 않습니다. 참고 봉투 받는 사람의 hCryptProv는 해제되지 않습니다.

[in] dwMsgType

메시지 형식을 나타냅니다. 다음 값 중 하나여야 합니다.

값	의미
CMSG_DATA	이 값은 사용되지 않습니다.
CMSG_SIGNED	pvMsgEncodeInfo 매개 변수는 인코딩 정보를 포함하는 CMSG_SIGNED_ENCODE_INFO 구조체의 주소입니다.
CMSG_ENVELOPED	pvMsgEncodeInfo 매개 변수는 인코딩 정보를 포함하는 CMSG_ENVELOPED_ENCODE_INFO 구조체의 주소입니다.
CMSG_SIGNED_AND_ENVELOPED	이 값은 현재 구현되지 않습니다.
CMSG_HASHED	pvMsgEncodeInfo 매개 변수는 인코딩 정보를 포함하는 CMSG_HASHED_ENCODE_INFO 구조체의 주소입니다.

[in] pvMsgEncodeInfo

인코딩 정보를 포함하는 구조체의 주소입니다. 데이터 형식은 dwMsgType 매개 변수의 값에 따라 달라집니다. 자세한 내용은 dwMsgType을 참조하세요.

[in, optional] pszInnerContentObjID

CryptMsgCalculateEncodedLength가 호출되고 CryptMsgUpdate에 대한 데이터가 이미 메시지 인코딩된 경우 적절한 개체 식별자(OID)가 pszInnerContentObjID로 전달됩니다. pszInnerContentObjID가 NULL인 경우 내부 콘텐츠 형식은 이전에 인코딩되지 않은 것으로 간주되므로 8진수 문자열로 인코딩되고 CMSG_DATA 형식이 지정됩니다.

참고 스트리밍을 사용하는 경우 pszInnerContentObjID 는 NULL 또는 szOID_RSA_data.

일반적으로 사용되는 알고리즘 OID는 다음과 같습니다. 사용자는 메시지의 보낸 사람과 수신자가 OID와 연결된 의미 체계에 동의하도록 하여 새 내부 콘텐츠 사용을 정의할 수 있습니다.

szOID_RSA_data
szOID_RSA_signedData
szOID_RSA_envelopedData
szOID_RSA_signEnvData
szOID_RSA_digestedData
szOID_RSA_encryptedData
SPC_INDIRECT_DATA_OBJID

[in] pStreamInfo

스트리밍을 사용하는 경우 이 매개 변수는 CMSG_STREAM_INFO 구조체의 주소입니다. CMSG_STREAM_INFO 구조체의 pfnStreamOutput 멤버가 지정한 콜백 함수는 CryptMsgUpdate가 실행될 때 호출됩니다. 콜백은 인코딩에서 생성된 인코딩된 바이트를 전달합니다. 콜백을 사용하는 방법에 대한 자세한 내용은 CMSG_STREAM_INFO.

참고 스트리밍을 사용하는 경우 애플리케이션은 이 함수에서 반환된 메시지 핸들이 CryptMsgClose 함수를 사용하여 닫히기 전까지는 pvMsgEncodeInfo 매개 변수에 전달되는 데이터 핸들(예: CMSG_SIGNER_ENCODE_INFO 구조체의 hCryptProv 멤버에 있는 공급자 핸들)을 해제해서는 안 됩니다.

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

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

봉투형 메시지로 묶인 서명된 메시지의 경우를 고려합니다. 서명된 메시지 피드의 스트리밍 인코딩에서 인코딩된 출력은 봉투된 메시지의 다른 스트리밍 인코딩으로 전달됩니다. 스트리밍 인코딩에 대한 콜백은 CryptMsgUpdate 를 호출하여 봉투 메시지를 인코딩합니다. 봉투형 메시지에 대한 콜백은 중첩된 서명된 메시지의 인코딩된 바이트를 받습니다.

반환 값

함수가 성공하면 열린 메시지에 대한 핸들을 반환합니다. 이 핸들은 CryptMsgClose 함수에 전달하여 더 이상 필요하지 않은 경우 닫아야 합니다.

이 함수가 실패하면 NULL 이 반환됩니다.

확장된 오류 정보를 검색하려면 GetLastError 함수를 사용합니다.

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

반환 코드	설명
CRYPT_E_INVALID_MSG_TYPE	메시지 유형이 잘못되었습니다.
CRYPT_E_OID_FORMAT	OID의 형식이 잘못되었습니다.
CRYPT_E_UNKNOWN_ALGO	암호화 알고리즘을 알 수 없습니다.
E_INVALIDARG	하나 이상의 인수가 잘못되었습니다.
E_OUTOFMEMORY	메모리가 부족합니다.

또한 dwMsgType 이 CMSG_SIGNED 경우 CryptCreateHash에서 오류가 전파될 수 있습니다.

dwMsgType이 CMSG_ENVELOPED 경우 CryptGenKey, CryptImportKey 및 CryptExportKey에서 오류가 전파될 수 있습니다.

dwMsgType이 CMSG_HASHED 경우 CryptCreateHash에서 오류를 전파할 수 있습니다.

설명

암호화를 수행하는 함수의 경우 암호화된 대칭 키는 CryptExportKey가 내부적으로 호출된 후 little-endian 형식에서 big-endian 형식으로 반전됩니다. 암호 해독을 수행하는 함수의 경우 암호화된 대칭 키는 CryptImportKey 가 호출되기 전에 big-endian 형식에서 little-endian 형식으로 반전됩니다.

CRYPT_NO_SALT CryptGenKey 및 CryptImportKey를 사용하여 대칭 키를 생성하고 가져올 때 지정됩니다.

RC2 암호화 알고리즘으로 암호화된 메시지는 CryptGetKeyParam 과 함께 KP_EFFECTIVE_KEYLEN 사용하여 RC2 키 가져오기 또는 내보내기의 유효 키 길이 를 결정합니다.

RC2 암호화 알고리즘으로 암호화된 메시지의 경우 CMSG_ENVELOPED_ENCODE_INFO 구조체의 ContentEncryptionAlgorithm 멤버에 대한 ASN RC2 매개 변수를 처리하도록 인코딩 및 디코딩 작업이 업데이트되었습니다.

RC4, DES 및 3DES 암호화 알고리즘으로 암호화된 메시지의 경우 인코딩 및 디코딩 작업은 이제 CMSG_ENVELOPED_ENCODE_INFO 구조체의 ContentEncryptionAlgorithm 멤버에 대한 ASN IV 옥릿 문자열 매개 변수를 처리합니다.

예제

이 함수를 사용하는 예제는 예제 C 프로그램: 서명, 인코딩, 디코딩 및 메시지 확인, 봉투 메시지 인코딩을 위한 대체 코드, 예제 C 프로그램: 봉투형, 서명된 메시지 인코딩 및 예제 C 프로그램: 해시된 메시지 인코딩 및 디코딩을 참조하세요.

요구 사항

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