3.1.4.1.8 ICertAdminD::RevokeCertificate (Opnum 10)

  • Article

The RevokeCertificate method revokes a certificate either immediately or on a specified date. It instructs the CA to revoke a certificate based on the certificate's serial number and reason code.

 HRESULT RevokeCertificate(
   [in, string, unique] wchar_t const* pwszAuthority,
   [in, string, unique] wchar_t const* pwszSerialNumber,
   [in] DWORD Reason,
   [in] FILETIME FileTime
 );

pwszAuthority: See the pwszAuthority definition in ICertAdminD::SetExtension (section 3.1.4.1.1).

pwszSerialNumber: A null-terminated Unicode string that specifies a serial number that identifies the certificate to be revoked. The string MUST specify the serial number as plain hexadecimal digits (no leading 0x) as specified in [RFC3280] section 4.1.2.2.<36>

Reason: An unsigned integer value that specifies the revocation reason code. The revocation reason code MUST be either one of the values listed in the following table (and specified in [RFC3280] section 5.3.1), or one of the following values: 0xfffffffd, 0xfffffffe, or 0xffffffff.

Value

Meaning

0

unspecified

1

keyCompromise

2

cACompromise

3

affiliationChanged

4

superseded

5

cessationOfOperation

6

certificateHold

8

removeFromCRL

0xfffffffd

See processing rules, beginning with rule 2.

0xfffffffe

See processing rules, beginning with rule 3.

0xffffffff

Released from hold. (See processing rules, beginning with rule 4.)

FileTime: Contains a 64-bit value that represents the number of 100-nanosecond intervals since January 1, 1601 (UTC). This value specifies the date, according to Greenwich Mean Time, when the certificate became invalid. The FileTime corresponds to the Request_Revocation_Date that is defined in section 3.1.1.1.

The following processing rules apply:

  1. The CA MUST find a row in the request table that contains the certificate that needs to be revoked in this method invocation. The CA finds the row by comparing the value of the pwszSerialNumber parameter to the values of the Serial_Number column in the request table. This is a case-sensitive string comparison. If none of the rows in the Request table have a Serial_Number value that is identical to the value that is passed in the pwszSerialNumber parameter, the CA MUST fail the request. The error returned SHOULD be 0x80070057. When a row that has an identical serial number, as previously specified, is found, the CA SHOULD continue with the following processing rules.

    Note These processing rules refer to this row as the identified row.

  2. If the Reason parameter is 0xfffffffd, the CA MUST set the Publish_Expired_Cert_In_CRL column of the identified row to 0 and return successfully.<37>

  3. If the Reason parameter is 0xfffffffe, the CA MUST set the Publish_Expired_Cert_In_CRL column of the identified row to 1 and return successfully.<38>

  4. If the value for the Reason parameter is 0xffffffff and the value of the Request_Revoked_Reason column in the identified row is not "certificateHold", the CA MUST fail the request, and the error code SHOULD be ERROR_INVALID_DATA.

  5. If the Reason parameter is not 0, 1, 2, 3, 4, 5, 6, 8, 0xfffffffd, 0xfffffffe, or 0xffffffff, the CA MUST fail the request. The error code SHOULD be E_INVALIDARG (0x80070057), as specified in [MS-ERREF] section 2.1. Otherwise, the CA MUST continue with the following processing rules. The Windows mnemonic for reason code 6 is CRL_REASON_CERTIFICATE_HOLD.

  6. If the Request_Disposition column of the identified row equals "certificate issued", the CA MUST set the Request_Disposition column of the identified row to "certificate revoked", and the CA SHOULD set the value of the Request_Disposition_Message column in the identified row to any value that the implementer considers informative for presentation to a human. In this case, the Microsoft CA sets Request_Disposition_Message to "Revoked by {username}" where "{username}" is replaced with the user name of the caller.

  7. If the Request_Disposition column of the identified row equals "certificate revoked":

    1. If the Request_Revoked_Reason column of the identified row equals "certificateHold":

      • If the Reason parameter is 0xffffffff, the CA MUST set the Request_Disposition column to "certificate issued", and the CA SHOULD set the value of the Request_Disposition_Message column in the identified row to any value the implementer considers informative for presentation to a human. In this case, the Microsoft CA sets Request_Disposition_Message to "Revoked by {username}" where "{username}" is replaced with the user name of the caller.

      • The CA MUST continue with processing, following rules 9 and 10.

    2. If the Request_Revoked_Reason column of the identified row does not equal "certificateHold":

      • If the Reason parameter is 0xffffffff, the CA MUST fail the request, as specified in the preceding rule 4.

      • If the Reason parameter is "certificateHold", the CA MUST fail the request. The error code SHOULD be ERROR_INVALID_DATA (0x8007000D), as specified in [MS-ERREF] section 2.1.

      • If the Reason parameter does not equal 0xffffffff and does not equal "certificateHold", the CA MUST continue with processing, following rules 9 and 10.

        One implication of this rule is that the Windows CA allows updating of the Request_Revoked_Reason and Request_Revocation_Date values of a certificate that has already been revoked. Although [RFC3280] section 5.3.3 describes revocationDate as the "date at which the CA processed the revocation", the Windows CA allows a different date to be used.

  8. If the Request_Disposition column of the identified row does not equal "certificate issued" and the Request_Disposition column of the identified row does not equal "certificate revoked", the CA MUST fail the request. The error code SHOULD be ERROR_INVALID_DATA, as specified in [MS-ERREF] section 2.1.

  9. The CA MUST set the Request_Revoked_Reason column of the identified row to the value passed in the Reason parameter.

  10. The CA MUST set the Request_Revocation_Date column of the identified row to the value passed in the FileTime parameter.

  11. The CA MUST set the Request_Revoked_When column of the identified row to the current time.