CryptEncodeObjectEx 함수(wincrypt.h)
CryptEncodeObjectEx 함수는 lpszStructType 매개 변수의 값으로 표시된 형식의 구조를 인코딩합니다. 이 함수는 CRYPT_ENCODE_ALLOC_FLAG 값으로 메모리 할당을 지원하여 CryptEncodeObject보다 성능이 크게 향상되었습니다.
구문
BOOL CryptEncodeObjectEx(
[in] DWORD dwCertEncodingType,
[in] LPCSTR lpszStructType,
[in] const void *pvStructInfo,
[in] DWORD dwFlags,
[in] PCRYPT_ENCODE_PARA pEncodePara,
[out] void *pvEncoded,
[in, out] DWORD *pcbEncoded
);
매개 변수
[in] dwCertEncodingType
개체 를 인코딩하는 데 사용할 인증서 인코딩 형식 및 메시지 인코딩 형식 입니다. 이 매개 변수는 다음 값 중 하나 이상의 조합일 수 있습니다.
| 값 | 의미 |
|---|---|
|
PKCS 7 메시지 인코딩을 지정합니다. |
|
X.509 인증서 인코딩을 지정합니다. |
[in] lpszStructType
구조체 형식을 정의하는 OID( 개체 식별자 )에 대한 포인터입니다. lpszStructType 매개 변수의 상위 단어가 0이면 하위 단어는 지정된 구조체의 형식에 대한 정수 식별자를 지정합니다. 그렇지 않으면 이 매개 변수는 OID의 문자열 표현을 포함하는 null로 끝나는 문자열에 대한 포인터입니다.
개체 식별자 문자열, 미리 정의된 상수 및 해당 구조에 대한 자세한 내용은 CryptEncodeObject 및 CryptDecodeObject 상수를 참조하세요.
[in] pvStructInfo
인코딩할 구조체에 대한 포인터입니다. 구조체는 lpszStructType에 지정된 형식이어야 합니다.
[in] dwFlags
인코딩 옵션을 지정합니다. 이 매개 변수는 0이거나 다음 값 중 하나 이상의 조합일 수 있습니다.
[in] pEncodePara
인코딩 정보를 포함하는 CRYPT_ENCODE_PARA 구조체에 대한 포인터입니다. 이 매개 변수는 NULL일 수 있습니다.
pEncodePara 또는 pEncodePara의 pfnAlloc 멤버가 NULL인 경우 할당에 LocalAlloc가 사용되고 메모리를 해제하려면 LocalFree를 호출해야 합니다.
pEncodePara와 pEncodePara의 pfnAlloc 멤버가 모두 NULL이 아닌 경우 pEncodePara가 가리키는 CRYPT_ENCODE_PARA 구조체의 pfnAlloc 멤버가 가리키는 함수가 할당을 위해 호출됩니다. pEncodePara의 pfnFree 멤버가 가리키는 함수를 호출하여 메모리를 해제해야 합니다.
[out] pvEncoded
인코딩된 구조를 수신할 버퍼에 대한 포인터입니다. 이 버퍼의 크기는 pcbEncoded 매개 변수에 지정됩니다. 지정된 버퍼가 디코딩된 구조를 받을 만큼 크지 않은 경우 함수는 ERROR_MORE_DATA 코드를 설정하고 필요한 버퍼 크기를 pcbEncoded가 가리키는 변수에 바이트 단위로 저장합니다.
이 매개 변수는 메모리 할당을 위해 버퍼의 크기를 검색하는 NULL 일 수 있습니다. 자세한 내용은 알 수 없는 길이의 데이터 검색을 참조하세요.
dwFlags에 CRYPT_ENCODE_ALLOC_FLAG 플래그가 포함된 경우 pvEncoded는 버퍼에 대한 포인터가 아니라 버퍼에 대한 포인터의 주소입니다. 메모리가 함수 내에 할당되고 포인터가 pvEncoded에 저장되므로 pvEncoded 는 NULL일 수 없습니다.
[in, out] pcbEncoded
pvEncoded 매개 변수가 가리키는 버퍼의 크기(바이트)를 포함하는 DWORD 변수에 대한 포인터입니다. 함수가 반환되면 pcbEncoded 매개 변수가 가리키는 변수에는 버퍼에 저장된 할당된 인코딩된 바이트 수가 포함됩니다.
dwFlags에 CRYPT_ENCODE_ALLOC_FLAG 플래그가 포함된 경우 pcbEncoded는 업데이트되는 DWORD 값에 대한 포인터의 주소입니다.
반환 값
성공하면 0이 아닌 값을 반환하고 그렇지 않으면 0을 반환합니다.
확장 오류 정보는 GetLastError를 호출합니다. 다음 표에서는 CryptEncodeObjectEx가 실패할 때 GetLastError에서 반환할 수 있는 몇 가지 가능한 오류 코드를 보여 줍니다.
| 반환 코드 | 설명 |
|---|---|
|
인코딩하는 동안 오류가 발생했습니다. |
|
지정된 dwCertEncodingType 및 lpszStructType에 대한 인코딩 함수를 찾을 수 없습니다. |
|
pvEncoded 매개 변수로 지정된 버퍼가 반환된 데이터를 저장할 만큼 크지 않은 경우 함수는 ERROR_MORE_DATA 코드를 설정하고 pcbEncoded가 가리키는 변수에 필요한 버퍼 크기를 바이트 단위로 저장합니다. |
함수가 실패하면 GetLastError 는 추상 구문 표기법 1(ASN.1) 인코딩/디코딩 오류를 반환할 수 있습니다. 이러한 오류에 대한 자세한 내용은 ASN.1 반환 값 인코딩/디코딩을 참조하세요.
설명
기본 설정 CryptEncodeObjectEx 함수를 사용하여 암호화 개체를 인코딩할 때 종료 되는 NULL 문자가 포함됩니다. 디코딩할 때 기본 설정 CryptDecodeObjectEx 함수를 사용하여 종료되는 NULL 문자는 유지되지 않습니다.
CryptEncodeObjectEx 는 먼저 설치 가능한 확장 인코딩 함수를 찾습니다. 확장 인코딩 함수를 찾을 수 없는 경우 이전의 비동기식 설치 가능 함수가 있습니다.
개체의 직접 IA5String 인코딩을 수행할 수 없는 경우 dwFlag 매개 변수를 CRYPT_ENCODE_ENABLE_PUNYCODE_FLAG 값으로 설정하여 Punycode 인코딩을 지정할 수 있습니다. CRYPT_ENCODE_ENABLE_PUNYCODE_FLAG 플래그를 설정하면 lpszStructType 매개 변수의 값으로 지정된 대로 인코딩되는 구조체 형식에 따라 다른 효과가 있습니다.
아래 목록의 각 상수에는 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
- szOID_NAME_CONSTRAINTS
- X509_NAME_CONSTRAINTS
- szOID_NEXT_UPDATE_LOCATION
- OCSP_REQUEST
- zOID_SUBJECT_ALT_NAME
- szOID_SUBJECT_ALT_NAME2
| dwAltNameChoice | 효과 |
|---|---|
| CERT_ALT_NAME_DNS_NAME | 호스트 이름에 ASCII 문자 집합 외부의 유니코드 문자가 포함된 경우 호스트 이름은 먼저 Punycode로 인코딩된 다음 IA5String 문자열로 인코딩됩니다. |
| CERT_ALT_NAME_RFC822_NAME | 이메일 주소의 호스트 이름 부분에 ASCII 문자 집합 외부의 유니코드 문자가 포함된 경우 전자 메일 주소의 호스트 이름 부분은 Punycode로 인코딩됩니다. 그러면 결과 전자 메일 주소가 IA5String 문자열로 인코딩됩니다. |
| CERT_ALT_NAME_URL | URI의 서버 호스트 이름에 ASCII 문자 집합 외부의 유니코드 문자가 포함된 경우 URI의 호스트 이름 부분은 Punycode로 인코딩됩니다. 그런 다음 결과 URI가 이스케이프되고 URL이 IA5String 문자열로 인코딩됩니다. |
아래 목록의 각 상수에는 pvStructInfo 매개 변수가 가리키는 연결된 구조체 형식이 있습니다. 직간접적으로 가리키는 구조체에는 CERT_HASHED_URL 구조체에 대한 참조가 있습니다.
- szOID_BIOMETRIC_EXT
- X509_BIOMETRIC_EXT
- szOID_LOGOTYPE_EXT
- X509_LOGOTYPE_EXT
아래 목록의 각 X509_UNICODE_NAME 상수에는 pvStructInfo 매개 변수가 가리키는 연결된 구조체 형식이 있습니다.
- X509_UNICODE_NAME
모든 경우에 호스트 이름의 Punycode 인코딩은 레이블별로 수행됩니다.
예제
다음 예제에서는 CryptEncodeObjectEx를 사용하여 X509_NAME 구조를 초기화하고 인코딩하는 방법을 보여줍니다. 이 예제의 전체 컨텍스트를 포함하는 예제는 예제 C 프로그램: ASN.1 인코딩 및 디코딩을 참조하세요.
#include <windows.h>
#include <stdio.h>
#include <Wincrypt.h>
#pragma comment(lib, "crypt32.lib")
#define MY_TYPE (X509_ASN_ENCODING)
void main()
{
//#define moved
//--------------------------------------------------------------------
// Declare and initialize local variables.
char *Cert_Sub_Name ="Test User Name";
//--------------------------------------------------------------------
// Initialize a single RDN structure.
CERT_RDN_ATTR rgNameAttr =
{
"2.5.4.3", // The OID
CERT_RDN_PRINTABLE_STRING, // Type of string
(DWORD)strlen(Cert_Sub_Name)+1, // String length including
// the terminating null character
(BYTE *)Cert_Sub_Name // Pointer to the string
};
//--------------------------------------------------------------------
// Declare and initialize a structure to include
// the array of RDN structures.
CERT_RDN rgRDN[] =
{
1, // The number of elements in the array
&rgNameAttr // Pointer to the array
};
//--------------------------------------------------------------------
// Declare and initialize a CERT_NAME_INFO
// structure that includes a CERT_RND.
CERT_NAME_INFO CertName =
{
1, // The number of elements in the CERT_RND's array
rgRDN
};
//--------------------------------------------------------------------
// Declare additional variables.
DWORD cbEncoded; // Variable to hold the
// length of the encoded string
BYTE *pbEncoded; // Variable to hold a pointer to the
// encoded buffer
//--------------------------------------------------------------------
// Call CrypteEncodeObjectEx to get
// length to allocate for pbEncoded.
if( CryptEncodeObjectEx(
MY_TYPE, // The encoding/decoding type
X509_NAME,
&CertName,
0,
NULL,
NULL,
&cbEncoded)) // Fill in the length needed for
// the encoded buffer.
{
printf("The number of bytes needed is %d \n",cbEncoded);
}
else
{
printf("The first call to the function failed.\n");
exit(1);
}
if( pbEncoded = (BYTE*)malloc(cbEncoded))
{
printf("Memory for pvEncoded has been allocated.\n");
}
else
{
printf("Memory allocation failed.\n");
exit(1);
}
if(CryptEncodeObjectEx(
MY_TYPE,
X509_NAME,
&CertName,
0,
NULL,
pbEncoded,
&cbEncoded))
{
printf("The structure has been encoded.\n");
}
else
{
printf("Encoding failed.");
exit(1);
}
// Free allocated memory when done.
// ...
if(pbEncoded)
{
free(pbEncoded);
}
요구 사항
| 요구 사항 | 값 |
|---|---|
| 지원되는 최소 클라이언트 | Windows XP [데스크톱 앱 | UWP 앱] |
| 지원되는 최소 서버 | Windows Server 2003 [데스크톱 앱 | UWP 앱] |
| 대상 플랫폼 | Windows |
| 헤더 | wincrypt.h |
| 라이브러리 | Crypt32.lib |
| DLL | Crypt32.dll |