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 メッセージ エンコーディングを指定します。 |
|
X.509 証明書のエンコードを指定します。 |
[in] lpszStructType
構造体の種類を定義する オブジェクト識別子 (OID) へのポインター。 lpszStructType パラメーターの上位ワードが 0 の場合、下位ワードは指定した構造体の型の整数識別子を指定します。 それ以外の場合、このパラメーターは、OID の文字列表現を含む null で終わる文字列へのポインターです。
オブジェクト識別子の文字列、定義済みの定数、および対応する構造体の詳細については、「 CryptEncodeObject および CryptDecodeObject の定数」を参照してください。
[in] pvStructInfo
エンコードする構造体へのポインター。 構造体は lpszStructType で指定された型である必要があります。
[in] dwFlags
エンコードのオプションを指定します。 このパラメーターには、0 または次の値の 1 つ以上の組み合わせを指定できます。
[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 文字セット以外の 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
次の一覧の 各X509_UNICODE_NAME 定数には、 pvStructInfo パラメーターによって指される構造体型が関連付けられています。
- X509_UNICODE_NAME
いずれの場合も、ホスト名の 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 |