次の方法で共有


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

オブジェクトのエンコードに使用する証明書エンコードの種類とメッセージ エンコードの種類。 このパラメーターには、次の値の 1 つ以上の組み合わせを指定できます。

意味
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 または次の値の 1 つ以上の組み合わせを指定できます。

意味
CRYPT_ENCODE_ALLOC_FLAG
32768 (0x8000)
呼び出されたエンコード関数は、エンコードされたバイトにメモリを割り当てます。 割り当てられたバイトへのポインターが pvEncoded で返されます。
CRYPT_ENCODE_ENABLE_PUNYCODE_FLAG
131072 (0x20000)
このフラグは、Unicode 文字列値の 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エンコードする場合に適用されます。 このフラグが設定され、すべての Unicode 文字が <= 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 を呼び出す必要があります。

pEncodeParapEncodeParapfnAlloc メンバーの両方が 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
指定した dwCertEncodingType および lpszStructType に対してエンコード関数が見つかりませんでした。
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 文字セット以外の Unicode 文字が含まれている場合、ホスト名は最初に Punycode でエンコードされ、 IA5String 文字列としてエンコードされます。
CERT_ALT_NAME_RFC822_NAME 電子メール アドレスのホスト名部分に ASCII 文字セット以外の Unicode 文字が含まれている場合、電子メール アドレスのホスト名部分は Punycode でエンコードされます。 結果の電子メール アドレスは、 IA5String 文字列としてエンコードされます。
CERT_ALT_NAME_URL URI のサーバー ホスト名に ASCII 文字セット以外の Unicode 文字が含まれている場合、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 文字セットの外部に Unicode 文字が含まれており、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 文字セットの外部の Unicode 文字が含まれている場合、電子メール アドレスのホスト名部分は Punycode でエンコードされます。 その後、結果の電子メール アドレスは IA5String 文字列としてエンコードされます。

いずれの場合も、ホスト名の Punycode エンコードはラベルごとに実行されます。

次の例は、 CryptEncodeObjectEx を使用したX509_NAME構造体の初期化とエンコードを示しています。 この例の完全なコンテキストを含む例については、「 サンプル C Program: ASN.1 Encoding and Decodeing」を参照してください。

#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
Library Crypt32.lib
[DLL] Crypt32.dll

こちらもご覧ください

CryptDecodeObject

CryptDecodeObjectEx

CryptEncodeObject

オブジェクトエンコードおよびデコード関数