ICertServerPolicy

ポリシーモジュールが証明書サービス(Certificate Services)と通信できるようにします。

証明書サービスへの後続の呼び出しでコンテキストとして使用する要求を指定します。

VB

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

インターフェイスが有効な要求を参照できるように、ポリシーモジュールは他のいずれの ICertServerPolicy メソッドを呼び出すよりも前に、まず SetContext メソッドを呼び出す必要があります。

例

// Set the context. The value nContext (long) would be the same
// as the context parameter in ICertPolicy::VerifyRequest.
// hr is defined as an HRESULT.
hr = pCertServerPolicy->SetContext( nContext );
if (FAILED(hr))
{
    printf("Failed SetContext [%x]\n", hr);
    goto error;
}

要求から特定のプロパティを取得します。

C++

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

VB

このメソッドを呼び出す前に SetContext メソッドを呼び出す必要があります。SetContext の呼び出しによって、現在のコンテキストとして使用する要求が指定されます。

要求は、証明書の一部ではない、要求および最終的に発行される証明書に関連するすべての状態を保持します。そのため、失効日時や処理結果(disposition)などのデータは、要求データオブジェクトに保持されます。

RequestType プロパティには、次のいずれかの値を設定できます。

例

BSTR      bstrPropName = NULL;
VARIANT   varProp;

VariantInit( &varProp );

bstrPropName = SysAllocString(L"RequestID");

// Retrieve the request property.
// pCertServerPolicy has been used to call SetContext previously.
hr = pCertServerPolicy->GetRequestProperty( bstrPropName,
                                          PROPTYPE_LONG,
                                          &varProp );
if (FAILED(hr))
{
    printf("Failed GetRequestProperty [%x]\n", hr);
    goto error;
}
else
{
    // Successfully retrieved property; use varProp as needed.
    // ...
}

// Done processing.
VariantClear( &varProp );
if ( NULL != bstrPropName )
    SysFreeString( bstrPropName );

要求から名前付き属性を返します。

C++

このメソッドを使用するには、BSTR 型の変数を作成し、その変数に NULL を設定して、その変数のアドレスを pstrAttributeValue として渡します。

BSTR の使用を終えたら、SysFreeString 関数を呼び出して解放してください。

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

VB

このメソッドを使用する前に ICertServerPolicy::SetContext を呼び出す必要があります。

次の要求属性は KEYGEN スタイルの要求に固有です。

例

BSTR     bstrAttribValue = NULL;
HRESULT  hr;

// Get the request attribute.
// bstrAttribName is BSTR assigned by EnumerateAttributes.
// pCertServerPolicy has been used to call SetContext previously.
hr = pCertServerPolicy->GetRequestAttribute(bstrAttribName,
                                            &bstrAttribValue);

if (FAILED(hr))
{
    printf("Failed GetRequestAttribute [%x]\n", hr);
    goto error;
}
else
{

    // Successful call. Use the bstrAttribValue as needed.
    // ...
}

// Done processing. Free BSTR.
if (NULL != bstrAttribValue)
    SysFreeString(bstrAttribValue);

証明書から名前付きプロパティを返します。(ICertServerPolicy.GetCertificateProperty)

メソッドが成功した場合、S_OK を返し、*pvarPropertyValue に要求されたプロパティ値を格納する VARIANT が設定されます。

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

証明書に関連付けられたプロパティを設定します。

VB

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

このメソッドを使用する前に ICertServerPolicy::SetContext を呼び出す必要があります。

NotBefore および NotAfter の証明書プロパティは、証明書が有効である期間を制約します。これらのプロパティのデータ型は、オートメーションの COleDateTime から派生した浮動小数点の VARIANT 日付です。

SetCertificateProperty で NotBefore および NotAfter の証明書プロパティを設定する場合、次の制約が適用されます:

• NotBefore の日付は、証明機関(CA)証明書の NotBefore の日付より前の日付に設定することはできません。
• NotAfter の日付は、CA 証明書の NotAfter の日付より後の日付に設定することはできません。
• NotBefore の日付は、たとえ新しい日付が CA 証明書の NotBefore の日付より後であっても、現在設定されている日付より前の日付に設定することはできません。
• NotAfter の日付は、たとえ新しい日付が CA 証明書の NotAfter の日付より前であっても、現在設定されている日付より後の日付に設定することはできません。

例

次の例では、SetCertificateProperty メソッドを呼び出して NotBefore 証明書プロパティを設定します。この例では、pServer が有効であり、ICertServerPolicy::SetContext メソッドが呼び出されていることを前提としています。

HRESULT hr;
ICertServerPolicy *pServer;
SYSTEMTIME st;
BSTR bstrPropName;
VARIANT vPropValue;

bstrPropName = SysAllocString(L"NotBefore");
if (NULL == bstrPropName)
{
    printf("Unable to allocate memory.\n"); 
    return E_OUTOFMEMORY;
}

// Set the 'NotBefore' property to Noon on Jan. 1, 2000.
memset( &st, 0, sizeof(SYSTEMTIME));
st.wYear = 2000;
st.wMonth = 1;     // Jan.
st.wDay = 1;       // 1st day of month.
st.wHour = 12;     // Noon.

// Place the date into VARIANT required format.
VariantInit( &vPropValue );
vPropValue.vt = VT_DATE;
if ( !SystemTimeToVariantTime( &st, &vPropValue.date))
{
    printf("Unable to convert time.\n");
    SysFreeString(bstrPropName);
    return E_FAIL
}

// Set the NotBefore property in the certificate:
hr = pServer->SetCertificateProperty(bstrPropName,
                                     PROPTYPE_DATE, 
                                     &vPropValue);
SysFreeString(bstrPropName);
VariantClear(&vPropValue);
if (FAILED(hr))
{
    printf("SetCertificateProperty failed [%x]\n", hr);
    return hr;
}

特定の証明書拡張を取得します。

C++

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

VB

このメソッドを呼び出す前に SetContext メソッドを呼び出す必要があります。SetContext の呼び出しによって、現在のコンテキストとして使用する要求が指定されます。

証明書拡張は証明書プロパティとは区別されます。プロパティは要求に添付される汎用的なデータです。これらのプロパティの一部は証明書にエンコードされますが(例: BeginDate)、その他はキューやログ内で要求をマークするためだけに使用されます。無効化されていない拡張は証明書にエンコードされます。拡張は常に オブジェクト識別子 でマークされ、常に critical/noncritical フラグを持ちます。

例

VARIANT    varExt;
HRESULT    hr;

VariantInit(&varExt);
// Get the Extension value.
// bstrExtName is BSTR assigned by EnumerateExtensions.
// pCertServerPolicy has been used to call SetContext previously.
hr = pCertServerPolicy->GetCertificateExtension(bstrExtName,
                                                PROPTYPE_BINARY,
                                                &varExt);

if (FAILED(hr))
{
    printf("Failed GetCertificateExtension [%x]\n", hr);
    goto error;
}
// Successful call; use the value in varExt as needed.
// ...

// When done, clear the Variant
VariantClear(&varExt);

直近の GetCertificateExtension の呼び出しで取得した拡張に関連付けられたフラグを取得します。

C++

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

VB

GetCertificateExtensionFlags を呼び出す前に、SetContext メソッドと GetCertificateExtension メソッドを呼び出す必要があります。SetContext メソッドは現在のコンテキストとして使用する要求を指定し、GetCertificateExtension メソッドはその要求の拡張を取得します。

拡張には、ポリシーフラグと生成元(origin)フラグを含めることができます。ポリシーフラグは証明書拡張に関する情報を提供します。ポリシーフラグはポリシーモジュールが設定できます。生成元フラグは、証明書拡張を設定したモジュールを示します。生成元フラグはサーバーエンジンによってのみ設定されます。

拡張からは 1 つ以上のポリシーフラグが返される場合があります。次に、あらかじめ定義されているポリシーフラグを示します。

また、次のいずれかの生成元フラグが返される場合があります。

戻り値でどのフラグが設定されているかを判定しやすいように、あらかじめ定義されたマスクが用意されています。次のマスクが提供されます。

EXTENSION_POLICY_MASK の上位 8 ビットは、カスタムデータのために使用しても安全です。これらのビットはデータベースに永続的に保存されますが、証明書拡張には書き込まれません。

例

HRESULT  hr;
LONG     ExtFlags;
// pCertServerPolicy has been used to call SetContext previously.
hr = pCertServerPolicy->GetCertificateExtensionFlags( &ExtFlags);

// More than one policy flag might be set.
LONG ExtPolicyFlags = ExtFlags & EXTENSION_POLICY_MASK;

if (ExtPolicyFlags & EXTENSION_CRITICAL_FLAG)
{
    // Do something.
}

if (ExtPolicyFlags & EXTENSION_DISABLE_FLAG)
{
    // Do something.
}

// only one origin flag can be set
switch (ExtFlags & EXTENSION_ORIGIN_MASK)
{
    case EXTENSION_ORIGIN_REQUEST:
        // Extension was set in certificate request.
        break;
    case EXTENSION_ORIGIN_POLICY:
        // Extension was set by policy module.
        break;
    case EXTENSION_ORIGIN_ADMIN:
        // Extension was set by administrator.
        break;
    case EXTENSION_ORIGIN_SERVER:
        // Extension was set by server engine.
        break;
    default:
        break;
}

証明書に新しい拡張を追加します。

VB

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

補足的なサブジェクト情報や用途情報など、追加情報を証明書に含めるには拡張を使用します。詳細については、Extension Handlers を参照してください。

SetCertificateExtension メソッドは、ICertPolicy2::VerifyRequest メソッドの実装内から呼び出します。SetCertificateExtension メソッドを呼び出す前に、ICertServerPolicy::SetContext メソッドを呼び出す必要があります。

内部の列挙ポインターを、現在のコンテキストに関連付けられた最初の証明書拡張に初期化します。(ICertServerPolicy.EnumerateExtensionsSetup)

VB

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

このメソッドを呼び出す前に SetContext メソッドを呼び出す必要があります。SetContext の呼び出しによって、どの要求が現在のコンテキストであるかが指定されます。

拡張を取得するには、EnumerateExtensions メソッドを呼び出します。EnumerateExtensions の呼び出しによって最初の拡張が取得され、次の拡張が存在する場合はインデックスがそれに移動します。

例

// Set the context. The value nContext (long) would be the same
// as the context parameter in ICertPolicy::VerifyRequest.
// hr is defined as an HRESULT.
// pCertServerPolicy has been used to call SetContext previously.
hr = pCertServerPolicy->SetContext( nContext );
if (FAILED(hr))
{
    printf("Failed SetContext [%x]\n", hr);
    goto error;
}
// Setup the enumeration.
hr = pCertServerPolicy->EnumerateExtensionsSetup( 0 );
if (FAILED(hr))
{
    printf("Failed EnumerateExtensionsSetup [%x]\n", hr);
    goto error;
}

現在の拡張のオブジェクト識別子(OID)を取得し、内部の列挙ポインターを次の拡張に移動します。

C++

このメソッドを使用するには、BSTR 型の変数を作成し、その変数に NULL を設定して、その変数のアドレスを pstrExtensionName として渡します。

BSTR の使用を終えたら、SysFreeString 関数を呼び出して解放してください。

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

VB

このメソッドは、無効化されていて証明書に現れないものも含め、データベースに記録されている証明書拡張を列挙します。拡張が無効化されているかどうかを判定するには、GetCertificateExtensionFlags を使用して、その拡張の EXTENSION_DISABLE_FLAG ビットをテストします。

列挙が完了したら、EnumerateExtensionsClose メソッドを呼び出して、列挙の呼び出しで使用したリソースを解放します。

例

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

BSTR     bstrExt = NULL;
VARIANT  varExt;
LONG     ExtFlags;
HRESULT  hr;

VariantInit(&varExt);

// Enumerate the extensions.
while (S_OK ==
      (hr = pCertServerPol->EnumerateExtensions(&bstrExt)))
{
  // Retrieve the extension data.
  if (FAILED(pCertServerPol->GetCertificateExtension(
                             bstrExt,
                             PROPTYPE_BINARY,
                             &varExt)))
      printf("Failed GetCertificateExtension\n");
  else
  {
     // Retrieve the extension flags.
    if (FAILED(pCertServerPol->GetCertificateExtensionFlags(
                               &ExtFlags)))
        printf("Failed GetCertificateExtensionFlags\n");
    else
        // This sample will display the extension OID string,
        // the extension flags (in hex) and
        // the length of the BSTR binary ASN-encode extension.
        printf("Extension: %ws\tFlags:%x\tLength:%u\n",
               bstrExt,
               ExtFlags,
               SysStringByteLen(varExt.bstrVal));
  }
}
// Determine if hr was S_FALSE, meaning the enumeration 
// was completed, or some other error.
if (S_FALSE != hr)
    printf("Failed EnumerateExtensions - %x\n", hr);
// Free BSTR resource.
if (NULL != bstrExt)
    SysFreeString(bstrExt);
// Free VARIANT resource.
    VariantClear(&varExt);

拡張の列挙に関連するリソースを解放します。

VB

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

すべてのポリシーモジュールは、EnumerateExtensionsSetup および ICertServerPolicy::EnumerateExtensions メソッドを呼び出した後に、EnumerateExtensionsClose メソッドを呼び出す必要があります。

例

// Close the enumeration.
// hr is defined as an HRESULT.
hr = pCertServerPolicy->EnumerateExtensionsClose();
if (FAILED(hr))
{
    printf("Failed EnumerateExtensionsClose [%x]\n", hr);
    goto error;
}

内部の列挙ポインターを、現在のコンテキストに関連付けられた最初の要求属性に初期化します。(ICertServerPolicy.EnumerateAttributesSetup)

VB

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

このメソッドを呼び出す前に SetContext メソッドを呼び出す必要があります。SetContext の呼び出しによって、現在のコンテキストとして使用する要求が指定されます。

属性を取得するには、EnumerateAttributes メソッドを呼び出します。EnumerateAttributes の呼び出しによって最初の属性が取得され、次の属性が存在する場合はインデックスがそれに移動します。

例

// Set the context. The value nContext (long) would be the same
// as the context parameter in ICertPolicy::VerifyRequest.
// hr is defined as an HRESULT.
// pCertServerPolicy has been used to call SetContext previously.
hr = pCertServerPolicy->SetContext(nContext);
if (FAILED(hr))
{
    printf("Failed SetContext [%x]\n", hr);
    goto error;
}

// Setup the enumeration.
hr = pCertServerPolicy->EnumerateAttributesSetup(0);
if (FAILED(hr))
{
    printf("Failed EnumerateAttributesSetup [%x]\n", hr);
    goto error;
}

現在の属性の名前を取得し、内部の列挙ポインターを次の属性に移動します。

C++

このメソッドを使用するには、BSTR 型の変数を作成し、その変数に NULL を設定して、その変数のアドレスを pstrAttributeName として渡します。

BSTR の使用を終えたら、SysFreeString 関数を呼び出して解放してください。

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

VB

EnumerateAttributes メソッドを初めて呼び出す前に、EnumerateAttributesSetup メソッドを呼び出して、列挙ポインターを最初の属性に初期化します。

列挙が完了したら、EnumerateAttributesClose メソッドを呼び出して、列挙の呼び出しで使用したリソースを解放します。

属性の列挙に関連するリソースを解放します。

VB

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

すべてのポリシーモジュールは、EnumerateAttributesSetup および EnumerateAttributes メソッドを呼び出した後に、EnumerateAttributesClose メソッドを呼び出す必要があります。

例

// Close the enumeration.
// hr is defined as an HRESULT.
hr = pCertServerPolicy->EnumerateAttributesClose();
if (FAILED(hr))
{
    printf("Failed EnumerateAttributesClose [%x]\n", hr);
    goto error;
}