ICertAdmin

適切に承認されたクライアントに管理機能を提供します。

証明機関(CA)のキーに対して証明書を検証し、その証明書が失効していないことを確認します。このメソッドは ICertAdmin インターフェイスで最初に定義されました。

C++

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

VB

このメソッドは、証明書が発行済みで現在失効していないかどうかのみを判断します。現在の日時が証明書の有効期間(証明書の NotBefore プロパティおよび NotAfter プロパティ)内にあるかどうかは確認しません。このメソッドを使用するアプリケーションは、証明書の有効期限の確認も行う必要があります。

管理タスクは DCOM を使用します。以前のバージョンの Certadm.h で定義されているこのインターフェイスのメソッドを呼び出すコードは、クライアントとサーバーが両方とも同じ Windows オペレーティングシステムを実行している限り、Windows ベースのサーバーで動作します。

例

    BSTR       bstrCA = NULL;      // Machine\CAName
    BSTR       bstrSerial = NULL;  // Contains the certificate 
                             // serial number
    long       nDisp;              // Contains the certificate
                             // disposition
    HRESULT    hr;

    bstrCA = SysAllocString(L"<COMPUTERNAMEHERE>\\<CANAMEHERE>");
    bstrSerial = SysAllocString(L"<SERIALNUMBERHERE>");

    if (NULL == bstrCA || NULL == bstrSerial)
    {
        printf("Memory allocation failed\n");
        goto error;
    }

    //  Determine whether the certificate is valid.
    //  pCertAdmin is a previously instantiated ICertAdmin 
    //  object pointer.
    hr = pCertAdmin->IsValidCertificate(bstrCA, bstrSerial, &nDisp);
    if (FAILED(hr))
    {
        printf("Failed IsValidCertificate [%x]\n", hr);
        goto error;
    }
    //  Use nDisp as needed.

    //  Done processing.

error:

    //  Free BSTR values.
    if (NULL != bstrCA)
        SysFreeString(bstrCA);

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

証明書が失効した理由を返します。このメソッドは ICertAdmin インターフェイスで最初に定義されました。

C++

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

VB

GetRevocationReason を呼び出す前に、 IsValidCertificate メソッドを呼び出して証明書の処理状況を取得します。GetRevocationReason を呼び出すには、この事前の呼び出しから証明書の処理状況 CA_DISP_REVOKED を受け取り、証明書が失効していることが示されている必要があります。IsValidCertificate の呼び出しによって、失効理由を取得する対象の証明書が特定されます。

管理タスクは DCOM を使用します。以前のバージョンの Certadm.h で定義されているこのインターフェイスのメソッドを呼び出すコードは、クライアントとサーバーが両方とも同じ Windows オペレーティングシステムを実行している限り、Windows ベースのサーバーで動作します。

例

// The value for nDisp was set by 
// a call to ICertAdmin2::IsValidCertificate.
if (CA_DISP_REVOKED == nDisp)
{
    // Variable to contain revocation reason.
    long       nReason;

    // Retrieve the revocation reason.
    hr = pCertAdmin->GetRevocationReason(&nReason);
    if (FAILED(hr))
    {
        printf("Failed GetRevocationReason [%x]\n", hr);
        goto error;
    }
    else
        printf("Revocation reason = %d\n", nReason );
}

指定した日付または即時に証明書を失効させます。このメソッドは ICertAdmin インターフェイスで最初に定義されました。

VB

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

このメソッドは同じ証明書に対して複数回呼び出すことができ、これにより有効な失効日と失効理由を変更できます。

現在失効している証明書の理由コードが CRL_REASON_CERTIFICATE_HOLD である場合、理由コード(Reason パラメーター)の値として MAXDWORD(Winnt.h で定義)を指定して RevokeCertificate を呼び出すことで、その証明書を復元できます。復元後、その証明書は今後の CRL には表示されません。

管理タスクは DCOM を使用します。以前のバージョンの Certadm.h で定義されているこのインターフェイスのメソッドを呼び出すコードは、クライアントとサーバーが両方とも同じ Windows オペレーティングシステムを実行している限り、Windows ベースのサーバーで動作します。

例

    BSTR bstrCA = NULL;
    BSTR bstrSerial = NULL;  // certificate serial number
    long nReason;
    DATE RevokeDate;         // revocation date
    SYSTEMTIME st;

    bstrSerial = SysAllocString(L"<SERIALNUMBERHERE>");
    bstrCA = SysAllocString(L"<COMPUTERNAMEHERE>\\<CANAMEHERE>");
    if (NULL == bstrCA || NULL == bstrSerial)
    {
        printf("Memory allocation failed\n");
        goto error;
    }
    
    nReason = CRL_REASON_AFFILIATION_CHANGED;  // Defined
                                          // in Wincrypt.h

    //  Specify when the cert should be revoked.
    //  Note: To revoke immediately, set RevokeDate to zero.
    //  This example sets the revoke date to noon on 1/1/2001.
    //  Zero out values first (avoids setting minutes, seconds,
    //  and so on).
    memset(&st, 0, sizeof(SYSTEMTIME));
    st.wYear = 2001;
    st.wMonth = 1;     // Jan
    st.wDay = 1;       // 1st day of month
    st.wHour = 12;     // Noon

    //  Place the date in the required format.
    if (!SystemTimeToVariantTime(&st, &RevokeDate))
    {
        printf("Unable to convert time.\n");
        goto error;
    }

    //  Revoke the certificate.
    //  pCertAdmin is a previously instantiated ICertAdmin object.
    hr = pCertAdmin->RevokeCertificate( bstrCA,
                                        bstrSerial,
                                        nReason,
                                        RevokeDate );
    if (FAILED(hr))
    {
        printf("Failed RevokeCertificate. [%x]\n", hr);
        goto error;
    }
    else
        printf("Certificate %ws revoked.\n", bstrSerial );

    //  Done processing.

error:

    //  Free resources.
    if (bstrSerial)
        SysFreeString( bstrSerial );
    if (bstrCA)
        SysFreeString( bstrCA );

指定した保留中の証明書要求に属性を設定します。このメソッドは ICertAdmin インターフェイスで最初に定義されました。

VB

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

SetRequestAttributes を呼び出して追加または更新した属性は、証明書要求に関連付けられた初期の未解析の属性文字列を変更しません。証明書要求の未解析の属性文字列は、証明書が要求された後は変更できません( ICertRequest::Submit メソッドを使用すると、証明書の要求時に属性を指定できます)。

初期の未解析の要求属性文字列を表示するには、証明機関 MMC スナップインを使用できます。

解析済みの属性を表示すると、SetRequestAttributes の呼び出しによる変更も確認できます。

解析済みの属性を表示するには

1. 証明機関 MMC スナップインを開きます。
2. [保留中の要求] フォルダーを開きます。
3. 要求を右クリックし、[すべてのタスク] をポイントして、[属性/拡張の表示] をクリックします。

管理タスクは DCOM を使用します。以前のバージョンの Certadm.h で定義されているこのインターフェイスのメソッドを呼び出すコードは、クライアントとサーバーが両方とも同じ Windows オペレーティングシステムを実行している限り、Windows ベースのサーバーで動作します。

例

    BSTR bstrAttribs = NULL;
    BSTR bstrCA = NULL;
    long nReqID;  // request ID

    //  Specify the attributes.
    //  For example, "AttName1:AttValue1\nAttName2:AttValue2". 
    bstrAttribs = SysAllocString(L"<ATTRIBUTESHERE>");
    if (NULL == bstrAttribs)
    {
        printf("Memory allocation failed for bstrAttribs.\n");
        goto error;
    }
    
    bstrCA = SysAllocString(L"<COMPUTERNAMEHERE>\\<CANAMEHERE>");
    if (NULL == bstrCA)
    {
        printf("Memory allocation failed for bstrCA.\n");
        goto error;
    }

    //  Request ID to receive the attributes.
    nReqID = <REQUESTIDHERE>;

    //  Add these attributes to the certificate.
    //  pCertAdmin is a previously instantiated
    //  ICertAdmin object pointer. 
    hr = pCertAdmin->SetRequestAttributes( bstrCA,
                                           nReqID,
                                           bstrAttribs );
    if (FAILED(hr))
        printf("Failed SetRequestAttributes [%x]\n", hr);
    else
        printf("SetRequestAttributes succeeded\n");

    //  Done processing.

error:

    if (bstrAttribs)
        SysFreeString(bstrAttribs);
    if (bstrCA)
        SysFreeString(bstrCA);
    //  Free other resources.

証明書要求に応じて発行される証明書に新しい拡張を追加します。このメソッドは ICertAdmin インターフェイスで最初に定義されました。

VB

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

管理タスクは DCOM を使用します。以前のバージョンの Certadm.h で定義されているこのインターフェイスのメソッドを呼び出すコードは、クライアントとサーバーが両方とも同じ Windows オペレーティングシステムを実行している限り、Windows ベースのサーバーで動作します。

保留中の指定した証明書要求を拒否します。

管理タスクは DCOM を使用します。以前のバージョンの Certadm.h で定義されているこのインターフェイスのメソッドを呼び出すコードは、クライアントとサーバーが両方とも同じ Windows オペレーティングシステムを実行している限り、Windows ベースのサーバーで動作します。

例

次の例では、必要な変数を宣言し、COM を初期化して、CertAdmin クラスのインスタンスを作成します。次に DenyRequest を呼び出し、成功または失敗を画面に出力します。最後にリソースを解放します。

//  Pointer to an interface object.
ICertAdmin * pCertAdmin = NULL;

    BSTR       bstrCA = NULL;  // variable for machine\CAName
    long       nReqID;         // variable for Request ID
    HRESULT    hr;

    //  Initialize COM.
    hr = CoInitializeEx(NULL, COINIT_APARTMENTTHREADED);
    if (FAILED(hr))
    {
        printf("Failed CoInitializeEx [%x]\n", hr);
        goto error;
    }

    //  Create the CertAdmin object
    //  and get a pointer to its ICertAdmin interface.
    hr = CoCreateInstance( CLSID_CCertAdmin,
                           NULL,
                           CLSCTX_INPROC_SERVER,
                           IID_ICertAdmin,
                           (void **)&pCertAdmin);
    if (FAILED(hr))
    {
        printf("Failed CoCreateInstance pCertAdmin [%x]\n", hr);
        goto error;
    }

    //  Note the use of two '\' in C++ to produce one '\'.
    bstrCA = SysAllocString(L"<COMPUTERNAMEHERE>\\<CANAMEHERE>");
    if (NULL == bstrCA)
    {
        printf("Failed to allocate memory for bstrCA\n");
        goto error;
    }

    //  nReqID is RequestID to be denied.
    nReqID = <REQUESTIDHERE>;

    //  Deny the request.
    hr = pCertAdmin->DenyRequest( bstrCA, nReqID );
    if (FAILED(hr))
    {
        printf("Failed DenyRequest %ws %d [%x]\n",
               bstrCA, nReqID, hr);
        goto error;
    }
    else
        printf("Denied request %ws %d\n",
                bstrCA, nReqID );

    //  Done processing.

    
error:

    //  Free BSTR values.
    if (NULL != bstrCA)
        SysFreeString(bstrCA);

    //  Clean up object resources.
    if (NULL != pCertAdmin)
        pCertAdmin->Release();

    //  Free COM resources.
    CoUninitialize(); 

指定した証明書要求を、指定した証明機関のポリシーモジュールに送信します。このメソッドは ICertAdmin インターフェイスで最初に導入されました。

C++

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

VB

管理タスクは DCOM を使用します。以前のバージョンの Certadm.h で定義されているこのインターフェイスのメソッドを呼び出すコードは、クライアントとサーバーが両方とも同じ Windows オペレーティングシステムを実行している限り、Windows ベースのサーバーで動作します。

例

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


    long nDisp;  // disposition value
    long nReqID = <REQUESTIDHERE>;
    BSTR bstrCA = NULL;

    bstrCA = SysAllocString(L"<COMPUTERNAMEHERE>\\<CANAMEHERE>");
    if (NULL == bstrCA)
    {
        printf("Memory allocation failed\n");
        goto error;
    }

    //  pCertAdmin is a previously instantiated ICertAdmin object.
    hr = pCertAdmin->ResubmitRequest(bstrCA, nReqID, &nDisp);
    if (FAILED(hr))
    {
        printf("Failed ResubmitRequest [%x]\n", hr);
        goto error;
    }
    else
        printf("ResubmitRequest disposition is %d\n", nDisp);

error:
    //  Free resources.
    if (bstrCA)
        SysFreeString(bstrCA);

Certificate Services の証明機関(CA)に対して、新しい証明書失効リスト(CRL)を発行する要求を送信します。このメソッドは ICertAdmin インターフェイスで最初に導入されました。

VB

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

管理タスクは DCOM を使用します。以前のバージョンの Certadm.h で定義されているこのインターフェイスのメソッドを呼び出すコードは、クライアントとサーバーが両方とも同じ Windows オペレーティングシステムを実行している限り、Windows ベースのサーバーで動作します。

例

次の例は、CRL の発行を示しています。

    DATE ExpDate;  // CRL expiration date
    SYSTEMTIME st;
    BSTR bstrCA = NULL;

    //  Set the CRL Expiration Date to Noon on Jan. 1, 2005 GMT.
    //  Zero out values first 
    //  (avoids setting minutes, seconds, and so on).
    memset(&st, 0, sizeof(SYSTEMTIME));
    st.wYear = 2005;
    st.wMonth = 1;     // Jan
    st.wDay = 1;       // 1st day of month
    st.wHour = 12;     // Noon

    //  Place the date in required format.
    if (!SystemTimeToVariantTime(&st, &ExpDate))
    {
        printf("Unable to convert time\n");
        goto error;
    }

    bstrCA = SysAllocString(L"<COMPUTERNAMEHERE>\\<CANAMEHERE>");
    if (NULL == bstrCA)
    {
        printf("Memory allocation failed\n");
        goto error;
    }

    //  Publish the CRL.
    //  pCertAdmin is a previously instantiated ICertAdmin object.
    hr = pCertAdmin->PublishCRL(bstrCA, ExpDate);
    if (FAILED(hr))
    {
        printf("Failed PublishCRL [%x]\n", hr);
        goto error;
    }
    else
        printf("PublishCRL succeeded\n");

Certificate Services の証明機関(CA)の現在の証明書失効リスト(CRL)を取得します。

関数が成功すると、関数は S_OK を返します。

関数が失敗した場合は、エラーを示す HRESULT 値を返します。取り得る値には、次の表に示すものが含まれますが、これらに限定されません。一般的なエラーコードの一覧については、Common HRESULT Values を参照してください。

管理タスクは DCOM を使用します。以前のバージョンの Certadm.h で定義されているこのインターフェイスのメソッドを呼び出すコードは、クライアントとサーバーが両方とも同じ Windows オペレーティングシステムを実行している限り、Windows ベースのサーバーで動作します。

例

次の例では、必要な変数を宣言し、COM を初期化して、CertAdmin クラスのインスタンスを作成します。次に GetCRL を呼び出し、成功または失敗を画面に出力します。最後にリソースを解放します。

    ICertAdmin * pCertAdmin = NULL;  // pointer to interface object
    BSTR bstrCA = NULL;              // variable for machine\CAName
    BSTR bstrCRL = NULL;             // variable to contain
                                     // the retrieved CRL

    HRESULT hr;

    //  Initialize COM.
    hr = CoInitializeEx(NULL, COINIT_APARTMENTTHREADED);
    if (FAILED(hr))
    {
        printf("Failed CoInitializeEx [%x]\n", hr);
        goto error;
    }

    //  Create the CertAdmin object
    //  and get a pointer to its ICertAdmin interface.
    hr = CoCreateInstance( CLSID_CCertAdmin,
                           NULL,
                           CLSCTX_INPROC_SERVER,
                           IID_ICertAdmin,
                           (void **)&pCertAdmin);
    if (FAILED(hr))
    {
        printf("Failed CoCreateInstance pCertAdmin [%x]\n", hr);
        goto error;
    }

    //  Note the use of two backslashes (\\) 
   //  in C++ to produce one backslash (\).
    bstrCA = SysAllocString(L"<COMPUTERNAMEHERE>\\<CANAMEHERE>");
    if (FAILED(hr))
    {
        printf("Failed to allocate memory for bstrCA\n");
        goto error;
    }

    //  Retrieve the CRL.
    hr = pCertAdmin->GetCRL( bstrCA, CR_OUT_BINARY, &bstrCRL );
    if (FAILED(hr))
    {
        printf("Failed GetCRL [%x]\n", hr);
        goto error;
    }
    else
        printf("CRL retrieved successfully\n");
        //  Use the CRL as needed.

    //  Done processing.

error:

    //  Free BSTR values.
    if (NULL != bstrCA)
        SysFreeString(bstrCA);

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

    //  Clean up object resources.
    if (NULL != pCertAdmin)
        pCertAdmin->Release();

    //  Free COM resources.
    CoUninitialize();

以前に発行された証明書を取得し、証明機関(CA)のデータベースにインポートします。このメソッドは ICertAdmin インターフェイスで最初に定義されました。

C++

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

VB

ImportCertificate メソッドは、バックアップから部分的に復元された証明機関の場合に役立ちます。証明機関の復元に使用したバックアップテープに証明書が含まれていないが、ファイルとして存在する場合、このメソッドを使用してその証明書をインポートできます。

このメソッドを成功させるには、インポートする証明書が、strConfig で指定した証明機関によって以前に発行されたものである必要があります。復元された証明機関は証明書の署名を検証し、署名が無効な場合、メソッドの呼び出しは失敗します。

さらに、証明書がデータベースに既に存在する場合はインポートできません。データベース内の各証明書は一意である必要があります。データベースは、証明書のシリアル番号を確認することで一意性を保証します。

例

// This code imports a binary certificate file.
BSTR   bstrCert = NULL;  // Variable for certificate.
HANDLE hFile;  
DWORD  cchFile, cbRead;
LONG   nID;  // Variable for request ID.

// Open the file that contains the certificate.
hFile = CreateFile((LPCSTR) "d:\\cert1.cer",
                  GENERIC_READ,
                  FILE_SHARE_READ,
                  NULL,
                  OPEN_EXISTING,
                  0,
                  NULL);
if (INVALID_HANDLE_VALUE == hFile)
{
    printf("Unable to open file\n");
    // Take error action as needed.
}
// Determine the file size.
cchFile = GetFileSize(hFile, NULL);
if ( (DWORD)-1 == cchFile )
{
    printf("Failed GetFileSize\n");
    CloseHandle(hFile);
    // Take error action as needed.
}
// Allocate the memory for the certificate.
bstrCert = SysAllocStringByteLen(NULL, cchFile);
if (NULL == bstrCert)
{
    printf("Failed SysAllocStringByteLen\n");
    CloseHandle(hFile);
    // Take error action as needed.
}
// Read in the certificate.
if (!ReadFile(hFile,
             (char *)bstrCert,
             cchFile,
             &cbRead,
             NULL) || (cbRead != cchFile))
{
    printf("Failed to successfully read file\n");
    CloseHandle(hFile);
    SysFreeString(bstrCert);
    // Take error action as needed.
}
// Close the file.
CloseHandle(hFile);

// Import the certificate.
bstrCA = SysAllocString(L"<COMPUTERNAMEHERE>\\<CANAMEHERE>");
if (FAILED(hr))
{
    printf("Failed to allocate memory for bstrCA\n");
    SysFreeString(bstrCert);
    // Take error action as needed.
}

hr = pCertAdmin->ImportCertificate(bstrCA,
                                   bstrCert,
                                   CR_IN_BINARY,
                                   &nID);
if (FAILED(hr))
    printf("Failed ImportCertificate [%x]\n", hr);
else
    printf("Imported certificated has Request ID: %d\n", nID);

SysFreeString(bstrCert);
SysFreeString(bstrCA);