CryptDecodeObjectEx 함수(wincrypt.h)
CryptDecodeObjectEx 함수는 lpszStructType 매개 변수로 표시된 형식의 구조를 디코딩합니다. CryptDecodeObjectEx 는 CRYPT_DECODE_ALLOC_FLAG 값으로 메모리 할당을 지원하여 CryptDecodeObject 보다 성능이 크게 향상되었습니다.
구문
BOOL CryptDecodeObjectEx(
[in] DWORD dwCertEncodingType,
[in] LPCSTR lpszStructType,
[in] const BYTE *pbEncoded,
[in] DWORD cbEncoded,
[in] DWORD dwFlags,
[in] PCRYPT_DECODE_PARA pDecodePara,
[out] void *pvStructInfo,
[in, out] DWORD *pcbStructInfo
);
매개 변수
[in] dwCertEncodingType
사용되는 인코딩 유형입니다. 다음 예제와 같이 비트 OR 작업과 결합하여 인증서 및 메시지 인코딩 형식을 모두 지정할 수 있습니다.
X509_ASN_ENCODING | PKCS_7_ASN_ENCODING
현재 정의된 인코딩 형식은 다음과 같습니다.
- X509_ASN_ENCODING
- PKCS_7_ASN_ENCODING
[in] lpszStructType
구조체 형식을 정의하는 OID( 개체 식별자 )에 대한 포인터입니다. lpszStructType 매개 변수의 상위 단어가 0이면 하위 단어는 지정된 구조체의 형식에 대한 정수 식별자를 지정합니다. 그렇지 않으면 이 매개 변수는 null로 끝나는 문자열에 대한 긴 포인터입니다.
개체 식별자 문자열, 미리 정의된 상수 및 해당 구조체에 대한 자세한 내용은 CryptEncodeObject 및 CryptDecodeObject에 대한 상수를 참조하세요.
[in] pbEncoded
디코딩할 데이터에 대한 포인터입니다. 구조체는 lpszStructType에 지정된 형식이어야 합니다.
[in] cbEncoded
pbEncoded에서 가리키는 바이트 수입니다. 디코딩할 바이트 수입니다.
[in] dwFlags
이 매개 변수는 다음 플래그 중 하나 이상일 수 있습니다. 비트 OR 연산을 사용하여 플래그를 결합할 수 있습니다.
| 값 | 의미 |
|---|---|
|
호출된 디코딩 함수는 디코딩된 구조체에 대한 메모리를 할당합니다. 할당된 구조체에 대한 포인터가 pvStructInfo에 반환됩니다.
pDecodePara 또는 pDecodePara의 pfnAlloc 멤버가 NULL인 경우 할당에 대해 LocalAlloc가 호출되고, 메모리를 해제하려면 LocalFree를 호출해야 합니다. pDecodePara 및 pDecodePara의 pfnAlloc 멤버가 NULL이 아닌 경우 pfnAlloc에서 가리키는 함수가 할당에 대해 호출되고 pDecodePara의 pfnFree 멤버가 가리키는 함수를 호출하여 메모리를 해제해야 합니다. |
|
이 플래그는 유니코드 문자열 값의 Punycode 디코딩을 사용하도록 설정하는 데 적용됩니다. 자세한 내용은 설명 부분을 참조하세요.
Windows Server 2008, Windows Vista, Windows Server 2003 및 Windows XP: 이 플래그는 지원되지 않습니다. |
|
이 플래그는 "복사 없음" 최적화를 사용하도록 설정할 수 있습니다. 이 최적화는 콘텐츠의 복사본을 만들고 pvStructInfo 에 추가하는 대신 pbEncoded 내에 있는 콘텐츠를 가리키도록 pvStructInfo 멤버를 업데이트합니다. 호출 애플리케이션은 더 적은 메모리를 할당해야 하며 복사가 수행되지 않으므로 실행 속도가 빨라집니다. "복사 없음" 디코딩을 수행할 때 pvStructInfo가 해제될 때까지 pbEncoded를 해제할 수 없습니다. |
|
이 플래그는 X509_UNICODE_NAME, X509_UNICODE_NAME_VALUE 또는 X509_UNICODE_ANY_STRING 디코딩할 때 적용됩니다. 기본적으로 CERT_RDN_T61_STRING 인코딩된 값은 처음에 UTF8로 디코딩됩니다. UTF8 디코딩에 실패하면 값이 8비트 문자로 디코딩됩니다. 이 플래그가 설정되면 값을 UTF8로 디코딩하려는 초기 시도를 건너뛰고 값을 8비트 문자로 디코딩합니다. |
|
기본적으로 pbEncoded 가 가리키는 버퍼의 내용에는 서명된 콘텐츠와 서명이 포함됩니다. 이 플래그가 설정되면 버퍼에는 "서명할" 콘텐츠만 포함됩니다. 이 플래그는 X509_CERT_TO_BE_SIGNED, X509_CERT_CRL_TO_BE_SIGNED, X509_CRT_REQUEST_TO_BE_SIGNED 및 X509_KEYGEN_REQUEST_TO_BE_SIGNED 개체에 적용할 수 있습니다. |
|
이 플래그가 설정되면 OID 문자열은 반환된 데이터 구조로 복사되는 대신 Crypt32.dll 할당되고 공유됩니다. 호출자가 언로드되기 전에 Crypt32.dll 언로드되지 않은 경우 이 플래그를 설정할 수 있습니다. |
|
기본적으로 서명 바이트는 반대로 바뀝니다. 이 플래그를 설정하면 이 바이트 반전이 억제됩니다. |
[in] pDecodePara
디코딩 단락 정보를 포함하는 CRYPT_DECODE_PARA 구조체에 대한 포인터입니다. pDecodePara가 NULL로 설정된 경우 LocalAlloc 및 LocalFree를 사용하여 메모리를 할당하고 해제합니다. pDecodePara가 CRYPT_DECODE_PARA 구조를 가리키는 경우 해당 구조체는 콜백 함수를 전달하여 메모리를 할당하고 해제합니다. 이러한 콜백 함수는 LocalAlloc 및 LocalFree의 기본 메모리 할당을 재정의합니다.
[out] pvStructInfo
dwFlags CRYPT_ENCODE_ALLOC_FLAG 설정된 경우 pvStructInfo는 버퍼에 대한 포인터가 아니라 버퍼에 대한 포인터의 주소입니다. 메모리가 함수 내에 할당되고 포인터가 *pvStructInfo에 저장되기 때문에 pvStructInfo 는 NULL이 되어서는 안 됩니다.
CRYPT_ENCODE_ALLOC_FLAG 설정되지 않은 경우 pvStructInfo 는 디코딩된 구조를 수신하는 버퍼에 대한 포인터입니다. 지정된 버퍼가 디코딩된 구조를 받을 만큼 충분히 크지 않은 경우 함수는 ERROR_MORE_DATA 코드를 설정하고 필요한 버퍼 크기를 pcbStructInfo가 가리키는 변수에 바이트 단위로 저장합니다.
이 매개 변수는 메모리 할당을 위해 이 정보의 크기를 검색하는 NULL 일 수 있습니다. 자세한 내용은 알 수 없는 길이의 데이터 검색을 참조하세요.
[in, out] pcbStructInfo
pvStructInfo 매개 변수가 가리키는 버퍼의 크기(바이트)를 포함하는 DWORD 변수에 대한 포인터입니다. 함수가 반환되면 DWORD 값에는 버퍼에 저장된 바이트 수가 포함됩니다. pcbStructInfo가 가리키는 변수에 포함된 크기는 디코딩된 구조체에 보조 데이터에 대한 포인터를 포함할 수 있으므로 디코딩된 구조체보다 큰 크기를 나타낼 수 있습니다. 이 크기는 디코딩된 구조체 및 보조 데이터에 필요한 크기의 합계입니다.
CRYPT_DECODE_ALLOC_FLAG 설정되면 함수에서 *pcbStructInfo 의 초기 값을 사용하지 않으며, 반환 시 *pcbStructInfo에는 pvStructInfo 에 할당된 바이 트 수가 포함됩니다.
반환 값
함수가 성공하면 함수는 0이 아닌 값(TRUE)을 반환합니다.
함수가 실패하면 0(FALSE)을 반환합니다. 확장된 오류 정보는 GetLastError를 호출합니다. 다음 표에는 몇 가지 가능한 오류 코드가 나와 있습니다.
| 반환 코드 | 설명 |
|---|---|
|
디코딩하는 동안 오류가 발생했습니다. |
|
지정된 dwCertEncodingType 및 lpszStructType에 대한 디코딩 함수를 찾을 수 없습니다. |
|
pvStructInfo 매개 변수로 지정된 버퍼가 반환된 데이터를 저장할 만큼 크지 않은 경우 함수는 ERROR_MORE_DATA 코드를 설정하고 pcbStructInfo가 가리키는 변수에 필요한 버퍼 크기를 바이트 단위로 저장합니다. |
함수가 실패하면 GetLastError 는 ASN.1( 추상 구문 표기법 1) 인코딩/디코딩 오류를 반환할 수 있습니다. 이러한 오류에 대한 자세한 내용은 ASN.1 반환 값 인코딩/디코딩을 참조하세요.
설명
기본 설정 CryptEncodeObjectEx 함수를 사용하여 암호화 개체를 인코딩할 때 종료 되는 NULL 문자가 포함됩니다. 디코딩할 때 기본 설정 CryptDecodeObjectEx 함수를 사용하여 종료되는 NULL 문자는 유지되지 않습니다.
아래 목록의 각 상수에는 pvStructInfo 매개 변수가 가리키는 연결된 구조체 형식이 있습니다. 직간접적으로 가리키는 구조체에는 CERT_ALT_NAME_ENTRY 구조체에 대한 참조가 있습니다.
- X509_ALTERNATE_NAME
- szOID_AUTHORITY_INFO_ACCESS
- X509_AUTHORITY_INFO_ACCESS
- X509_AUTHORITY_KEY_ID2
- szOID_AUTHORITY_KEY_IDENTIFIER2
- szOID_CRL_DIST_POINTS
- X509_CRL_DIST_POINTS
- szOID_CROSS_CERT_DIST_POINTS
- X509_CROSS_CERT_DIST_POINTS
- szOID_ISSUER_ALT_NAME
- szOID_ISSUER_ALT_NAME2
- szOID_ISSUING_DIST_POINT
- X509_ISSUING_DIST_POINT
- X509_NAME_CONSTRAINTS
- szOID_NAME_CONSTRAINTS
- szOID_NEXT_UPDATE_LOCATION
- OCSP_REQUEST
- zOID_SUBJECT_ALT_NAME
- szOID_SUBJECT_ALT_NAME2
| dwAltNameChoice | 영향 |
|---|---|
| CERT_ALT_NAME_DNS_NAME | 호스트 이름에 Punycode로 인코딩된 IA5String 문자열이 포함되어 있으면 유니코드에 해당하는 문자열로 변환됩니다. |
| CERT_ALT_NAME_RFC822_NAME | 이메일 주소의 호스트 이름 부분에 Punycode로 인코딩된 IA5String 문자열이 포함된 경우 해당 유니코드로 변환됩니다. |
| CERT_ALT_NAME_URL | URI가 디코딩됩니다. URI의 서버 호스트 이름에 Punycode로 인코딩된 IA5String 문자열이 포함된 경우 호스트 이름 문자열은 동일한 유니코드로 디코딩됩니다. |
아래 목록의 각 상수에는 pvStructInfo 매개 변수가 가리키는 연결된 구조체 형식이 있습니다. 직접 또는 간접적으로 가리키는 구조체에는 CERT_HASHED_URL 구조체에 대한 참조가 있습니다.
- szOID_LOGOTYPE_EXT
- X509_LOGOTYPE_EXT
- szOID_BIOMETRIC_EXT
- X509_BIOMETRIC_EXT
아래 목록의 각 X509_UNICODE_NAME 상수에는 pvStructInfo 매개 변수가 가리키는 연결된 구조 형식이 있습니다.
- X509_UNICODE_NAME
예제
이 함수를 사용하는 예제는 예제 C 프로그램: ASN.1 인코딩 및 디코딩을 참조하세요.
요구 사항
| 지원되는 최소 클라이언트 | Windows XP [데스크톱 앱 | UWP 앱] |
| 지원되는 최소 서버 | Windows Server 2003 [데스크톱 앱 | UWP 앱] |
| 대상 플랫폼 | Windows |
| 헤더 | wincrypt.h |
| 라이브러리 | Crypt32.lib |
| DLL | Crypt32.dll |