ICEnroll3

証明書登録(エンロール)コントロールを表す複数のインターフェイスのうちの1つです。

証明書または証明書チェーンを処理し、適切な証明書ストアに格納します。このメソッドは、要求証明書を受け取らない点で acceptPKCS7 メソッドと異なります。

VB

メソッドが成功した場合、S_OK を返します。

メソッドが失敗した場合、エラーを示す HRESULT 値を返します。一般的なエラーコードの一覧については、Common HRESULT Values を参照してください。

このメソッドがスクリプトから呼び出されると、証明書のインストールを許可するかどうかをユーザーに尋ねるユーザーインターフェイスが表示されます。

証明書登録コントロールオブジェクトを初期状態に戻し、コントロールを再利用できるようにします。このメソッドは ICEnroll3 インターフェイスで初めて定義されました。

VB

メソッドが成功した場合、S_OK を返します。

メソッドが失敗した場合、エラーを示す HRESULT 値を返します。一般的なエラーコードの一覧については、Common HRESULT Values を参照してください。

署名操作および交換操作に対する現在の暗号化サービスプロバイダー(CSP)のサポート状況に関する情報を取得します。このメソッドは ICEnroll3 インターフェイスで初めて定義されました。

C++

メソッドが成功した場合、S_OK を返します。

メソッドが失敗した場合、エラーを示す HRESULT 値を返します。一般的なエラーコードの一覧については、Common HRESULT Values を参照してください。

VB

現在の CSP が交換キーおよび署名キーをサポートしているかどうかを示す値を返します。CSP がこのメソッドをサポートしていない場合は、エラーが返されます。

現在の CSP が交換キー、署名キー、またはその両方をサポートしているかどうかを判断するには、このメソッドを呼び出します。pdwKeySpec パラメーターには、次の定数(Wincrypt.h で定義)のうち1つ以上が格納されます。

• AT_KEYEXCHANGE
• AT_SIGNATURE

例

DWORD dwKeySpec;

// Determine the supported key specifications.
// hr is HRESULT variable.
hr = pEnroll->GetSupportedKeySpec( &dwKeySpec );
if ( FAILED( hr ) )    
    printf("Failed GetSupportedKeySpec [%x]\n", hr);
else
{
    printf("Exchange keys are %s. Signature keys are %s.\n",
           dwKeySpec & AT_KEYEXCHANGE ? "supported" : "not supported",
           dwKeySpec & AT_SIGNATURE ? "supported" : "not supported" );
}

署名キーおよび交換キーの最小キー長と最大キー長を取得します。

C++

メソッドが成功した場合、S_OK を返し、*pdwKeySize にはキーの最小長または最大長を表す値(ビット単位)が格納されます。

メソッドが失敗した場合、エラーを示す HRESULT 値を返します。一般的なエラーコードの一覧については、Common HRESULT Values を参照してください。

VB

キーの最小長または最大長を表す値(ビット単位)。

最小キー長と最大キー長を判断するには、このメソッドを呼び出します。CSP がこのメソッドをサポートしていない場合は、エラーが返されます。

例

DWORD dwExchMin, dwExchMax, dwSignMin, dwSignMax;

// Determine the minimum and maximum key length values.
// hr is HRESULT variable.
hr = pEnroll->GetKeyLen( TRUE, TRUE, &dwExchMin );
if ( FAILED( hr ) )    
    printf("Failed GetKeyLen for Exchange Minimum [%x]\n", hr);
else
    printf("Exchange key Min: %d\n", dwExchMin);

hr = pEnroll->GetKeyLen( FALSE, TRUE, &dwExchMax );
if ( FAILED( hr ) )
    printf("Failed GetKeyLen for Exchange Maximum [%x]\n", hr);
else
    printf("Exchange key Max: %d\n", dwExchMax );

hr = pEnroll->GetKeyLen( TRUE, FALSE, &dwSignMin );
if ( FAILED( hr ) )
    printf("Failed GetKeyLen for Signature Minimum [%x]\n", hr);
else
    printf("Signature key Min: %d\n", dwSignMin );

hr = pEnroll->GetKeyLen( FALSE, FALSE, &dwSignMax );
if ( FAILED( hr ) )    
    printf("Failed GetKeyLen for Signature Maximum [%x]\n", hr);
else
    printf("Signature key Max: %d\n", dwSignMax );

ICEnroll4::EnumAlgs メソッドは、指定されたアルゴリズムクラスに属し、現在の暗号化サービスプロバイダー(CSP)でサポートされている暗号化アルゴリズムの ID を取得します。

C++

戻り値は HRESULT です。S_OK は成功を示します。列挙するアルゴリズムがこれ以上ない場合は、値 ERROR_NO_MORE_ITEMS が返されます。

VB

現在の CSP でサポートされている暗号化アルゴリズム ID。列挙するアルゴリズムがこれ以上ない場合は、値 ERROR_NO_MORE_ITEMS が返されます。

このメソッドで使用されるアルゴリズム ID およびクラスの定数については、Wincrypt.h を参照してください。

例

#include <windows.h>
#include <stdio.h>
#include <Xenroll.h>

DWORD     dwAlgID;
DWORD     dwIndex;

BSTR      bstrAlgName = NULL;

HRESULT   hr, hr2;

// Loop through the AlgIDs.
dwIndex = 0;
while ( TRUE )
{
    // Enumerate the alg IDs for a specific class.
    hr = pEnroll->EnumAlgs(dwIndex, ALG_CLASS_SIGNATURE, &dwAlgID);
    if ( S_OK != hr )
    {
       break;
    }

    // Do something with the AlgID.
    // For example, retrieve the corresponding name.
    hr2 = pEnroll->GetAlgName( dwAlgID, &bstrAlgName);
    if ( FAILED( hr2 ) )    
        printf("Failed GetAlgName [%x]\n", hr);
    else
        printf("AlgID: %d Name: %S\n", dwAlgID, bstrAlgName );

    // Reuse the BSTR variable in next iteration.
    if ( NULL != bstrAlgName )
    {
        SysFreeString( bstrAlgName );
        bstrAlgName = NULL;
    }

    // Increment the index.
    dwIndex++;
}

指定された ID から暗号化アルゴリズムの名前を取得します。このメソッドで取得される値は、現在の暗号化サービスプロバイダー(CSP)に依存します。このメソッドは ICEnroll3 インターフェイスで初めて定義されました。

C++

戻り値は HRESULT です。S_OK は成功を示します。CSP がこのメソッドをサポートしていない場合、または algID の暗号化アルゴリズムをサポートしていない場合は、エラーが返されます。

VB

戻り値は、algID で指定されたアルゴリズムの名前を表す文字列です。CSP がこのメソッドをサポートしていない場合は、エラーが返されます。

このメソッドは、 EnumAlgs を呼び出して取得した ID を持つアルゴリズムの名前を表示するために使用できます。

暗号化アルゴリズムの定数は Wincrypt.h で定義されています。

例

BSTR      bstrAlgName = NULL;

HRESULT   hr;

// Retrieve the algorithm name.
// dwAlgID is a DWORD variable for an algorithm ID.
hr = pEnroll->GetAlgName( dwAlgID, &bstrAlgName);
if (FAILED(hr))
    printf("Failed GetAlgName [%x]\n", hr);
else
    printf("AlgID: %d Name: %S\n", dwAlgID, bstrAlgName );

// Free BSTR resource.
if ( NULL != bstrAlgName )
{
    SysFreeString( bstrAlgName );
    bstrAlgName = NULL;
}

新しいキーの生成時にエラーが発生した場合に証明書登録コントロールオブジェクトが実行する動作を決定するブール値を設定または取得します。(Put)

このプロパティはブール値です。このプロパティは、NTE_TOKEN_KEYSET_STORAGE_FULL を返す 暗号化サービスプロバイダーにのみ影響します。これらの CSP は通常ハードウェアベースであり、スマートカードなどが例として挙げられます。このプロパティが true で、新しいキーの生成中にエラーが発生した場合、証明書登録コントロールオブジェクトは既存のハードウェアキーを再利用します。このプロパティが false で、新しいキーの生成中にエラーが発生した場合、証明書登録コントロールオブジェクトは既存のハードウェアキーを再利用せず、代わりに呼び出し元にエラーを渡します。

例

// Code to set the reuse H/W key status.
// hr is HRESULT variable.
hr = pEnroll->put_ReuseHardwareKeyIfUnableToGenNew( FALSE );
if ( FAILED( hr ) )    
    printf("Failed put_ReuseHardwareKeyIfUnableToGenNew [%x]\n", hr);


// Code to retrieve the reuse H/W key status.
BOOL bReuse;

hr = pEnroll->get_ReuseHardwareKeyIfUnableToGenNew( &bReuse );
if ( FAILED( hr ) )
    printf("Failed get_ReuseHardwareKeyIfUnableToGenNew [%x]\n", hr);
else
    printf("Hardware key %s be reused if unable"
        " to generate a new key.\n", bReuse ? "will" : "will not");

新しいキーの生成時にエラーが発生した場合に証明書登録コントロールオブジェクトが実行する動作を決定するブール値を設定または取得します。(Get)

このプロパティはブール値です。このプロパティは、NTE_TOKEN_KEYSET_STORAGE_FULL を返す 暗号化サービスプロバイダーにのみ影響します。これらの CSP は通常ハードウェアベースであり、スマートカードなどが例として挙げられます。このプロパティが true で、新しいキーの生成中にエラーが発生した場合、証明書登録コントロールオブジェクトは既存のハードウェアキーを再利用します。このプロパティが false で、新しいキーの生成中にエラーが発生した場合、証明書登録コントロールオブジェクトは既存のハードウェアキーを再利用せず、代わりに呼び出し元にエラーを渡します。

例

// Code to set the reuse H/W key status.
// hr is HRESULT variable.
hr = pEnroll->put_ReuseHardwareKeyIfUnableToGenNew( FALSE );
if ( FAILED( hr ) )    
    printf("Failed put_ReuseHardwareKeyIfUnableToGenNew [%x]\n", hr);


// Code to retrieve the reuse H/W key status.
BOOL bReuse;

hr = pEnroll->get_ReuseHardwareKeyIfUnableToGenNew( &bReuse );
if ( FAILED( hr ) )
    printf("Failed get_ReuseHardwareKeyIfUnableToGenNew [%x]\n", hr);
else
    printf("Hardware key %s be reused if unable"
        " to generate a new key.\n", bReuse ? "will" : "will not");

PKCS の署名時に使用するハッシュアルゴリズムを設定または取得します。(Put)

このプロパティの値は、 EnumAlgs メソッドが返すような ハッシュアルゴリズム ID です。HashAlgID プロパティと HashAlgorithm プロパティの両方が設定されている場合は、最後に更新された方が PKCS #10 要求の署名に使用されるハッシュアルゴリズムを決定します。

例

// Code to set the hash algorithm ID.
// hr is HRESULT variable.
hr = pEnroll->put_HashAlgID( CALG_MD4 );
if ( FAILED( hr ) )    
    printf("Failed put_HashAlgID [%x]\n", hr);


// Code to retrieve the hash algorithm ID.
DWORD dwHashID;

hr = pEnroll->get_HashAlgID( &dwHashID );
if ( FAILED( hr ) )    
    printf("Failed get_HashAlgID [%x]\n", hr);
else
    printf("HashAlgID: %d\n", dwHashID);

PKCS の署名時に使用するハッシュアルゴリズムを設定または取得します。(Get)

このプロパティの値は、 EnumAlgs メソッドが返すような ハッシュアルゴリズム ID です。HashAlgID プロパティと HashAlgorithm プロパティの両方が設定されている場合は、最後に更新された方が PKCS #10 要求の署名に使用されるハッシュアルゴリズムを決定します。

例

// Code to set the hash algorithm ID.
// hr is HRESULT variable.
hr = pEnroll->put_HashAlgID( CALG_MD4 );
if ( FAILED( hr ) )    
    printf("Failed put_HashAlgID [%x]\n", hr);


// Code to retrieve the hash algorithm ID.
DWORD dwHashID;

hr = pEnroll->get_HashAlgID( &dwHashID );
if ( FAILED( hr ) )    
    printf("Failed get_HashAlgID [%x]\n", hr);
else
    printf("HashAlgID: %d\n", dwHashID);

AT_KEYEXCHANGE 要求にデジタル署名および否認防止のキー使用法が含まれるかどうかを決定するブール値を設定または取得します。(Put)

このプロパティはブール値であり、AT_KEYEXCHANGE 要求にのみ影響します。AT_SIGNATURE 要求には影響しません。

このプロパティの値が false の場合、AT_KEYEXCHANGE 要求には次のキー使用法が含まれます。

• CERT_DATA_ENCIPHERMENT_KEY_USAGE
• CERT_KEY_ENCIPHERMENT_KEY_USAGE
• CERT_DIGITAL_SIGNATURE_KEY_USAGE
• CERT_NON_REPUDIATION_KEY_USAGE

このプロパティの値が true の場合、AT_KEYEXCHANGE 要求には次のキー使用法が含まれます。

• CERT_DATA_ENCIPHERMENT_KEY_USAGE
• CERT_KEY_ENCIPHERMENT_KEY_USAGE

例

// Get the LimitExchangeKeyToEncipherment value.
BOOL       bLimitKey;
HRESULT    hr;
// pEnroll is previously instantiated ICEnroll interface pointer.
hr = pEnroll->get_LimitExchangeKeyToEncipherment(&bLimitKey);
if (FAILED(hr))
    printf("Failed get_LimitExchangeKeyToEncipherment - %x\n", hr );
else
    printf("LimitExchangeKeyToEncipherment: %s\n",
          ( bLimitKey ? "TRUE" : "FALSE"));

// Set the LimitExchangeKeyToEncipherment value.
hr = pEnroll->put_LimitExchangeKeyToEncipherment( TRUE );
if ( FAILED ( hr ) )
    printf("Failed put_LimitExchangeKeyToEncipherment - %x\n", hr );
else
    printf( "LimitExchangeKeyToEncipherment was set to TRUE\n" );

AT_KEYEXCHANGE 要求にデジタル署名および否認防止のキー使用法が含まれるかどうかを決定するブール値を設定または取得します。(Get)

このプロパティはブール値であり、AT_KEYEXCHANGE 要求にのみ影響します。AT_SIGNATURE 要求には影響しません。

このプロパティの値が false の場合、AT_KEYEXCHANGE 要求には次のキー使用法が含まれます。

• CERT_DATA_ENCIPHERMENT_KEY_USAGE
• CERT_KEY_ENCIPHERMENT_KEY_USAGE
• CERT_DIGITAL_SIGNATURE_KEY_USAGE
• CERT_NON_REPUDIATION_KEY_USAGE

このプロパティの値が true の場合、AT_KEYEXCHANGE 要求には次のキー使用法が含まれます。

• CERT_DATA_ENCIPHERMENT_KEY_USAGE
• CERT_KEY_ENCIPHERMENT_KEY_USAGE

例

// Get the LimitExchangeKeyToEncipherment value.
BOOL       bLimitKey;
HRESULT    hr;
// pEnroll is previously instantiated ICEnroll interface pointer.
hr = pEnroll->get_LimitExchangeKeyToEncipherment(&bLimitKey);
if (FAILED(hr))
    printf("Failed get_LimitExchangeKeyToEncipherment - %x\n", hr );
else
    printf("LimitExchangeKeyToEncipherment: %s\n",
          ( bLimitKey ? "TRUE" : "FALSE"));

// Set the LimitExchangeKeyToEncipherment value.
hr = pEnroll->put_LimitExchangeKeyToEncipherment( TRUE );
if ( FAILED ( hr ) )
    printf("Failed put_LimitExchangeKeyToEncipherment - %x\n", hr );
else
    printf( "LimitExchangeKeyToEncipherment was set to TRUE\n" );

ICEnroll4::EnableSMIMECapabilities プロパティは、PKCS を有効にするかどうかを制御します。(Put)

ICEnroll4::EnableSMIMECapabilities プロパティは、PKCS を有効にするかどうかを制御します。(Get)

#define global IID_ICEnroll3 "{C28C2D95-B7DE-11D2-A421-00C04F79FE8E}"
#usecom global ICEnroll3 IID_ICEnroll3 "{43F8F289-7A20-11D0-8F06-00C04FC295E1}"
#comfunc global ICEnroll3_InstallPKCS7                          69 wstr
#comfunc global ICEnroll3_Reset                                 70
#comfunc global ICEnroll3_GetSupportedKeySpec                   71 var
#comfunc global ICEnroll3_GetKeyLen                             72 int,int,var
#comfunc global ICEnroll3_EnumAlgs                              73 int,int,var
#comfunc global ICEnroll3_GetAlgName                            74 int,var
#comfunc global ICEnroll3_put_ReuseHardwareKeyIfUnableToGenNew  75 int
#comfunc global ICEnroll3_get_ReuseHardwareKeyIfUnableToGenNew  76 var
#comfunc global ICEnroll3_put_HashAlgID                         77 int
#comfunc global ICEnroll3_get_HashAlgID                         78 var
#comfunc global ICEnroll3_put_LimitExchangeKeyToEncipherment    79 int
#comfunc global ICEnroll3_get_LimitExchangeKeyToEncipherment    80 var
#comfunc global ICEnroll3_put_EnableSMIMECapabilities           81 int
#comfunc global ICEnroll3_get_EnableSMIMECapabilities           82 var
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※#usecom 末尾は CoCreateInstance 用のクラスID(コクラスCLSID, SDKから自動取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※IDispatch 実装。HSP では comobj 経由でメソッド名による呼び出しも可能(vtbl 不要)。