ICertPolicy

Certificate Services サーバーエンジンとポリシーモジュール間の通信を提供します。

スタンドアロンの証明機関 (CA)のみが、カスタムのポリシーモジュールまたは終了 (Exit) モジュールを使用すべきです。エンタープライズ証明機関を実行する場合は、Microsoft が提供するポリシーモジュールおよび終了モジュールの使用を強く推奨します。

ICertPolicy の実装者は ICertManageModule も実装する必要があります。さらに、ICertPolicy を実装するクラスの ProgID は命名規則に従う必要があります。具体的には、ProgID は次の形式でなければなりません。

"MyApp.Policy"

ここで MyApp はアプリケーションを識別する指定子です。たとえば C++ では、ICertPolicy を実装するクラス (CMyCertPolicyModule) の DECLARE_REGISTRY マクロで次のコードを使用できます。

DECLARE_REGISTRY(
    CMyCertPolicyModule,
    L"MyCode.Policy.1",
    L"MyCode.Policy",
    IDS_CERTPOLICYMODULE_DESC,
    THREADFLAGS_BOTH);

前述の例では、IDS_CERTPOLICYMODULE_DESC 値は、クラスを説明する文字列に対する、リソースファイル (.rc) 内のアプリケーション固有の識別子です。

Certmod.h で定義されている文字列定数を使用すると、命名規則への準拠を簡素化できます。

Certificate Services サーバーには、同時に複数の Visual Basic Scripting Edition ポリシーモジュールを登録することはできません。そのようなポリシーモジュールが Certificate Services サーバーに複数登録されていると、証明機関 MMC スナップイン、Certificate Services アプリケーション、または certutil コマンドラインプログラムでエラーが発生する場合があります。Visual Basic Scripting Edition の開発環境は、ビルドが成功すると DLL を自動的に登録することに注意してください。そのため、ある Visual Basic Scripting Edition ポリシーモジュールが既に登録されている状態で別の Visual Basic Scripting Edition ポリシーモジュールを作成すると、この状況に遭遇することがあります。この状況を回避するには、コマンドライン命令 regsvr32 /u FileName.dll (FileName.dll はアクティブにしたくない Visual Basic Scripting Edition ポリシーモジュールの名前) を使用して、いずれかの Visual Basic Scripting Edition ポリシーモジュールの登録を解除する必要があります。

Visual Basic Scripting Edition で ICertPolicy を実装する場合は、プロジェクトを次の形式で命名する必要があります。

"MyApp"

ここで MyApp はアプリケーションを識別する指定子です。さらに、ICertPolicy を実装するクラスは "Policy" という名前にする必要があります。

ポリシーモジュールが初期化タスクを実行できるように、サーバーエンジンによって呼び出されます。

VB

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

カスタムポリシーモジュールを作成する場合は、このメソッドを実装してください。

例

#include <windows.h>
#include <Certpol.h>

STDMETHODIMP CCertPolicy::Initialize(
    /* [in] */ BSTR const strConfig)
{
    // strConfig can be used by the Policy module.
    // Here, it is stored in a BSTR member variable.
    // m_strConfig is an application-defined variable.
    // Call SysFreeString to free m_strConfig when done.
    m_strConfig = SysAllocString( strConfig );
    // Check to determine whether there was enough memory.
    if (NULL == m_strConfig)
        return ( E_OUTOFMEMORY );  // Not enough memory

    return( S_OK );
}

新しい要求がシステムに入ったことをポリシーモジュールに通知します。

C++

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

VB

VerifyRequest は、要求の検証を行うために他のプロセスを起動したり、外部データベースにアクセスしたりできます。検証に帯域外 (out-of-band) の処理や人間の介入が必要な場合、VerifyRequest は別のプロセスに通知したり、着信した要求に必要な通知を残したりできます。帯域外の処理が完了した後、 ResubmitRequest を呼び出すか、提供されている管理ツールを使用して、要求をポリシーモジュールに再送信できます。ポリシーモジュールは要求を再度検査し、必要な外部データにアクセスして、証明書を発行すべきか拒否すべきかを示す値を返すことができます。

カスタムポリシーモジュールを作成する場合は、モジュール内で VerifyRequest の機能を実装する必要があります。

例

次の例は、VerifyRequest メソッドの実装例を示しています。

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

STDMETHODIMP CCertPolicy::VerifyRequest(
             BSTR const strConfig,
             LONG Context,
             LONG bNewRequest,
             LONG Flags,
             LONG __RPC_FAR *pDisposition)
{
    HRESULT            hr;
    long               nDisp = VR_INSTANT_BAD;
    ICertServerPolicy *pServer = NULL;
    BSTR               bstrPropName = NULL;
    VARIANT            varProp;

    // Verify that pointer is not NULL.
    if ( NULL == pDisposition )
    {
        hr = E_POINTER;  // E_POINTER is #defined in Winerror.h
        goto error;
    }
    
    // Set disposition to pending.
    *pDisposition = VR_PENDING; 

    // Obtain a pointer to the CertServerPolicy interface.
    hr = CoCreateInstance( CLSID_CCertServerPolicy,
                           NULL,
                           CLSCTX_INPROC_SERVER,
                           IID_ICertServerPolicy,
                           (void **) &pServer);
    if (FAILED( hr ))
    {
        printf("Failed CoCreateInstance for pServer - %x\n", hr );
        goto error;
    }

    // Set the context to refer to this request.
    hr = pServer->SetContext(Context);
    if (FAILED( hr ))
    {
        printf("Failed SetContext(%u) - %x\n", Context, hr );
        goto error;
    }

    // This policy will perform a database check on the CN.
    // Set the property name to Subject.Commonname.
    bstrPropName = SysAllocString(L"Subject.Commonname");
    if ( NULL == bstrPropName )
    {
        hr = E_OUTOFMEMORY;  // #defined in Winerror.h
        printf("Failed SysAllocString (no memory)\n" );
        goto error;
    }

    // Retrieve the certificate property for the CN.
    // Actual implementations may want to examine other properties.
    VariantInit( &varProp );
    hr = pServer->GetCertificateProperty( bstrPropName,
                                          PROPTYPE_STRING,
                                          &varProp );
    if (FAILED(hr))
    {
        printf("Failed GetCertificateProperty - %x\n", hr);
        goto error;
    }

    // For this simple sample, merely check CN in a database.
    // (Implementation not shown, as it is application-specific).
    hr = MyDatabaseCheck( varProp.bstrVal );
    if ( S_OK == hr )
        *pDisposition = VR_INSTANT_OK;   // Accepted.
    else 
        *pDisposition = VR_INSTANT_BAD;  // Denied.

error:

    // Free resources.
    if (NULL != pServer)
        pServer->Release();

    VariantClear( &varProp );

    if ( NULL != bstrPropName )
        SysFreeString( bstrPropName );

    return(hr);
}

ポリシーモジュールとその機能について、人間が読める形式の説明を返します。

C++

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

VB

カスタムポリシーモジュールを作成する場合は、このメソッドを実装してください。

例

#include <windows.h>
#include <Certpol.h>

STDMETHODIMP CCertPolicy::GetDescription(
    /* [out, retval] */ BSTR __RPC_FAR *pstrDescription)
{
    if (NULL == pstrDescription)
    {
        // Bad pointer address
        return ( E_POINTER );
    }
    if (NULL != *pstrDescription)
    {
        SysFreeString(*pstrDescription);
        *pstrDescription=NULL;
    }
    // wszMyModuleDesc defined elsewhere, for example:
    // #define wszMyModuleDesc L"My Policy Module"
    *pstrDescription = SysAllocString(wszMyModuleDesc);
    if (NULL == *pstrDescription)
    {
        // Not enough memory
        return ( E_OUTOFMEMORY );
    }
    // Success
    return( S_OK );
}

サーバーが終了する前に、サーバーエンジンによって呼び出されます。

VB

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

カスタムポリシーモジュールを作成する場合は、このメソッドを実装してください。

例

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

STDMETHODIMP CCertPolicy::ShutDown()
{
    // Clean up resources used by this process.

    // Display message that this method has been called.
    if ( fDebug )
    {
        printf("Policy module Shutdown was called\n");
    }
    return( S_OK );
}