다음을 통해 공유


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_ASN_ENCODING
65536 (0x10000)
PKCS 7 메시지 인코딩을 지정합니다.
X509_ASN_ENCODING
1(0x1)
X.509 인증서 인코딩을 지정합니다.

[in] lpszStructType

구조체 형식을 정의하는 OID( 개체 식별자 )에 대한 포인터입니다. lpszStructType 매개 변수의 상위 단어가 0이면 하위 단어는 지정된 구조체의 형식에 대한 정수 식별자를 지정합니다. 그렇지 않으면 이 매개 변수는 OID의 문자열 표현을 포함하는 null로 끝나는 문자열에 대한 포인터입니다.

개체 식별자 문자열, 미리 정의된 상수 및 해당 구조에 대한 자세한 내용은 CryptEncodeObject 및 CryptDecodeObject 상수를 참조하세요.

[in] pvStructInfo

인코딩할 구조체에 대한 포인터입니다. 구조체는 lpszStructType에 지정된 형식이어야 합니다.

[in] dwFlags

인코딩 옵션을 지정합니다. 이 매개 변수는 0이거나 다음 값 중 하나 이상의 조합일 수 있습니다.

의미
CRYPT_ENCODE_ALLOC_FLAG
32768 (0x8000)
호출된 인코딩 함수는 인코딩된 바이트에 대한 메모리를 할당합니다. 할당된 바이트에 대한 포인터가 pvEncoded로 반환됩니다.
CRYPT_ENCODE_ENABLE_PUNYCODE_FLAG
131072 (0x20000)
이 플래그는 유니코드 문자열 값의 Punycode 인코딩을 사용하도록 설정하는 데 적용됩니다. 자세한 내용은 설명 부분을 참조하세요.

Windows Server 2008, Windows Vista, Windows Server 2003 및 Windows XP: 이 플래그는 지원되지 않습니다.

CRYPT_UNICODE_NAME_ENCODE_DISABLE_CHECK_TYPE_FLAG
1073741824(0x40000000)
이 플래그는 X509_UNICODE_NAME, X509_UNICODE_NAME_VALUE 또는 X509_UNICODE_ANY_STRING 인코딩할 때 적용됩니다. 이 플래그를 설정하면 문자가 지정된 값 형식에 대해 유효한지 여부를 확인하지 않습니다.
CRYPT_UNICODE_NAME_ENCODE_ENABLE_T61_UNICODE_FLAG
2147483648(0x80000000)
이 플래그는 X509_UNICODE_NAME 인코딩할 때 적용됩니다. 이 플래그가 설정되고 모든 유니코드 문자가 <= 0xFF 경우 CERT_RDN_UNICODE_STRING 대신 CERT_RDN_T61_STRING 선택됩니다.
CRYPT_UNICODE_NAME_ENCODE_ENABLE_UTF8_UNICODE_FLAG
536870912(0x20000000)
이 플래그는 X509_UNICODE_NAME 인코딩할 때 적용됩니다. 설정하면 CERT_RDN_UNICODE_STRING 대신 CERT_RDN_UTF8_STRING 선택됩니다.
CRYPT_UNICODE_NAME_ENCODE_FORCE_UTF8_UNICODE_FLAG
268435456(0x10000000)
이 플래그는 X509_UNICODE_NAME 인코딩할 때 적용됩니다. 설정하면 디렉터리 문자열 형식에 대해 CERT_RDN_PRINTABLE_STRING 대신 CERT_RDN_UTF8_STRING 선택됩니다. 또한 이 플래그를 사용하면 CRYPT_UNICODE_NAME_ENCODE_ENABLE_UTF8_UNICODE_FLAG 수 있습니다.

[in] pEncodePara

인코딩 정보를 포함하는 CRYPT_ENCODE_PARA 구조체에 대한 포인터입니다. 이 매개 변수는 NULL일 수 있습니다.

pEncodePara 또는 pEncodeParapfnAlloc 멤버가 NULL인 경우 할당에 LocalAlloc가 사용되고 메모리를 해제하려면 LocalFree를 호출해야 합니다.

pEncodePara와 pEncodeParapfnAlloc 멤버가 모두 NULL이 아닌 경우 pEncodePara가 가리키는 CRYPT_ENCODE_PARA 구조체의 pfnAlloc 멤버가 가리키는 함수가 할당을 위해 호출됩니다. pEncodeParapfnFree 멤버가 가리키는 함수를 호출하여 메모리를 해제해야 합니다.

[out] pvEncoded

인코딩된 구조를 수신할 버퍼에 대한 포인터입니다. 이 버퍼의 크기는 pcbEncoded 매개 변수에 지정됩니다. 지정된 버퍼가 디코딩된 구조를 받을 만큼 크지 않은 경우 함수는 ERROR_MORE_DATA 코드를 설정하고 필요한 버퍼 크기를 pcbEncoded가 가리키는 변수에 바이트 단위로 저장합니다.

이 매개 변수는 메모리 할당을 위해 버퍼의 크기를 검색하는 NULL 일 수 있습니다. 자세한 내용은 알 수 없는 길이의 데이터 검색을 참조하세요.

dwFlagsCRYPT_ENCODE_ALLOC_FLAG 플래그가 포함된 경우 pvEncoded는 버퍼에 대한 포인터가 아니라 버퍼에 대한 포인터의 주소입니다. 메모리가 함수 내에 할당되고 포인터가 pvEncoded에 저장되므로 pvEncodedNULL일 수 없습니다.

[in, out] pcbEncoded

pvEncoded 매개 변수가 가리키는 버퍼의 크기(바이트)를 포함하는 DWORD 변수에 대한 포인터입니다. 함수가 반환되면 pcbEncoded 매개 변수가 가리키는 변수에는 버퍼에 저장된 할당된 인코딩된 바이트 수가 포함됩니다.

dwFlagsCRYPT_ENCODE_ALLOC_FLAG 플래그가 포함된 경우 pcbEncoded는 업데이트되는 DWORD 값에 대한 포인터의 주소입니다.

참고 버퍼에서 반환된 데이터를 처리할 때 애플리케이션은 반환된 데이터의 실제 크기를 사용해야 합니다. 실제 크기는 입력에 지정된 버퍼의 크기보다 약간 작을 수 있습니다. (입력에서 버퍼 크기는 일반적으로 가능한 가장 큰 출력 데이터가 버퍼에 맞도록 충분히 크게 지정됩니다.) 출력에서 이 매개 변수가 가리키는 변수는 버퍼에 복사된 데이터의 실제 크기를 반영하도록 업데이트됩니다.
 

반환 값

성공하면 0이 아닌 값을 반환하고 그렇지 않으면 0을 반환합니다.

확장 오류 정보는 GetLastError를 호출합니다. 다음 표에서는 CryptEncodeObjectEx가 실패할 때 GetLastError에서 반환할 수 있는 몇 가지 가능한 오류 코드를 보여 줍니다.

반환 코드 설명
CRYPT_E_BAD_ENCODE
인코딩하는 동안 오류가 발생했습니다.
ERROR_FILE_NOT_FOUND
지정된 dwCertEncodingTypelpszStructType에 대한 인코딩 함수를 찾을 수 없습니다.
ERROR_MORE_DATA
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
CRYPT_ENCODE_ENABLE_PUNYCODE_FLAG 플래그는 CERT_ALT_NAME_ENTRY 구조체의 dwAltNameChoice 멤버 값과 함께 문자열이 인코딩되는 방식을 결정합니다.
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
CERT_HASHED_URL 구조체 값을 인코딩할 때 URI의 서버 호스트 이름에 ASCII 문자 집합 외부의 유니코드 문자가 포함되어 있고 CRYPT_ENCODE_ENABLE_PUNYCODE_FLAG 설정된 경우 URI의 호스트 이름 부분은 Punycode로 인코딩됩니다. 그런 다음 결과 URI가 이스케이프되고 URL이 IA5String 문자열로 인코딩됩니다.

아래 목록의 각 X509_UNICODE_NAME 상수에는 pvStructInfo 매개 변수가 가리키는 연결된 구조체 형식이 있습니다.

  • X509_UNICODE_NAME
CERT_RDN_ATTR 구조체의 pszObjId 멤버가 szOID_RSA_emailAddr 설정되고 Value 멤버의 이메일 주소에 ASCII 문자 집합 외부의 유니코드 문자가 포함된 경우 전자 메일 주소의 호스트 이름 부분은 Punycode로 인코딩됩니다. 그런 다음 결과 전자 메일 주소는 IA5String 문자열로 인코딩됩니다.

모든 경우에 호스트 이름의 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

추가 정보

CryptDecodeObject

CryptDecodeObjectEx

CryptEncodeObject

개체 인코딩 및 디코딩 함수