ICertAdmin2::RevokeCertificate Method (Windows)

ICertAdmin2::RevokeCertificate Method

The RevokeCertificate method revokes a certificate either on a specified date or immediately. This method was first defined in the ICertAdmin interface.

A revoked certificate will appear in a subsequent certificate revocation lists (CRLs), provided the revocation date is effective at the time the CRL was published.

Syntax

C++

HRESULT RevokeCertificate(
  [in]  const BSTR strConfig,
  [in]  const BSTR strSerialNumber,
  [in]  LONG Reason,
  [in]  DATE Date
);

Parameters

strConfig [in]

Represents a valid configuration string for the certification authority server in the form COMPUTERNAME\CANAME, where COMPUTERNAME is the network name of the Certificate Services server and CANAME is the common name of the certification authority, as entered during Certificate Services setup. For information about the configuration string name, see ICertConfig.

strSerialNumber [in]

Specifies a serial number that identifies the certificate to be revoked. The string must specify the serial number as an even number of hexadecimal digits. If necessary, a zero can be prefixed to the number to produce an even number of digits. However, no more than one leading zero may be used.

Reason [in]

Specifies the reason for the revocation. The following values (defined in Wincrypt.h) are supported reason codes.

Name	Value
CRL_REASON_UNSPECIFIED	0
CRL_REASON_KEY_COMPROMISE	1
CRL_REASON_CA_COMPROMISE	2
CRL_REASON_AFFILIATION_CHANGED	3
CRL_REASON_SUPERSEDED	4
CRL_REASON_CESSATION_OF_OPERATION	5
CRL_REASON_CERTIFICATE_HOLD	6

You can reinstate a certificate revoked with the CRL_REASON_CERTIFICATE_HOLD revocation reason code by calling RevokeCertificate with MAXDWORD as the Reason value. Note that if a certificate has been revoked with any reason code other than CRL_REASON_CERTIFICATE_HOLD, it cannot be reinstated.

Date [in]

Specifies the date, in Coordinated Universal Time (Greenwich Mean Time), on which the revocation will become effective. The value zero indicates the current Coordinated Universal Time, causing a certificate to be revoked immediately. The value of Date appears in the Effective Revocation Date column of the revoked certificate (in the Certification Authority MMC snap-in).

Return Value

If the method succeeds, the method returns S_OK.

If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see Common HRESULT Values.

VBScript


Sub RevokeCertificate( _
  ByVal strConfig, _
  ByVal strSerialNumber, _
  ByVal Reason, _
  ByVal Date _
)

Parameters

strConfig [in]

strSerialNumber [in]

Reason [in]

Specifies the reason for the revocation. The following values (defined in Wincrypt.h) are supported reason codes.

Name	Value
CRL_REASON_UNSPECIFIED	0
CRL_REASON_KEY_COMPROMISE	1
CRL_REASON_CA_COMPROMISE	2
CRL_REASON_AFFILIATION_CHANGED	3
CRL_REASON_SUPERSEDED	4
CRL_REASON_CESSATION_OF_OPERATION	5
CRL_REASON_CERTIFICATE_HOLD	6

Date [in]

Return Value

This method does not return a value.

Remarks

This method can be called more than once on the same certificate, which allows you to change the effective revocation date and revocation reason.

If a currently revoked certificate has CRL_REASON_CERTIFICATE_HOLD as its reason code, you can reinstate the certificate by calling RevokeCertificate with MAXDWORD (defined in Winnt.h) as the value for its reason code (the Reason parameter). After it is reinstated, the certificate will not appear in future CRLs.

Administration tasks use DCOM. Code that calls this interface method as defined in an earlier version of Certadm.h will run on Windows-based servers as long as the client and the server are both running the same Windows operating system.

Examples


    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 );

Requirements

Minimum supported client	None supported
Minimum supported server	Windows Server 2003
Header	Certadm.h (include Certsrv.h)
Library	Certidl.lib
DLL	Certadm.dll
IID	IID_ICertAdmin2 is defined as f7c3ac41-b8ce-4fb4-aa58-3d1dc0e36b39

Syntax

Parameters

Return Value

Parameters

Return Value

Remarks

Examples

Requirements

See Also