3.1.4.1.1 ICertAdminD::SetExtension (Opnum 3)

  • Article

The SetExtension method allows adding, modifying, or disabling of extensions, as specified in [RFC3280]. A CA can include an extension in an issued certificate for a particular pending request.

 HRESULT SetExtension(
   [in, string, unique] wchar_t const* pwszAuthority,
   [in] DWORD dwRequestId,
   [in, string, unique] wchar_t const* pwszExtensionName,
   [in] DWORD dwType,
   [in] DWORD dwFlags,
   [in, ref] CERTTRANSBLOB* pctbValue
 );

pwszAuthority: A null-terminated Unicode string that contains the name of the certificate server. The pwszAuthority is a Unicode string in the form of a distinguished name (DN) value, such as "CAName", where CAName MUST be the full common name (CN) or sanitized name of the CA, as specified in [MS-WCCE] section 3.1.1.4.1.1.

dwRequestId: A 32-bit nonzero unsigned integer value that specifies the ID of the certificate request.

pwszExtensionName: A null-terminated Unicode string that specifies the OID (1) for the extension to set, as specified in [X680]. The string MUST be 31 or fewer characters in length and the characters MUST NOT be NULL.

dwType: An unsigned integer value that specifies the type of extension being set. The dwType parameter MUST agree with the data type of the pb member of the pctbValue parameter. This parameter can be one of the following values.

Value

Meaning

0x00000001

Unsigned long data

0x00000002

Date/time

0x00000003

Binary data

0x00000004

Unicode

dwFlags: An unsigned integer value that specifies the flags for the extension being set. This parameter can be one of the following values.

Value

Meaning

1

This is a critical extension.

2

The extension MUST NOT be used on issued certificates.

pctbValue: A pointer to a CERTTRANSBLOB structure. The pb member MUST point to the binary data for the extension and the cb member MUST contain the length, in bytes, of the value. Depending on the value of the dwType parameter, the format of the binary data that is pointed to by the pb member is shown in the following table.

Value of dwType

Meaning

0x00000001

The CERTTRANSBLOB structure pb member MUST point to an unsigned long data value in little-endian format.

0x00000002

The CERTTRANSBLOB structure pb member MUST point to data using little-endian encoding format.

0x00000003

The CERTTRANSBLOB structure pb member MUST point to an array of bytes that are not in need of endian forcing.

0x00000004

The CERTTRANSBLOB structure pb member MUST point to a null-terminated Unicode string in little-endian format.

This method instructs the CA to add, modify, or disable an extension that is associated with a previously submitted certificate request that is in a pending state, as specified in [MS-WCCE] section 3.2.1.4.2.1.3. If the certificate request does not contain an extension with the name specified in pwszExtensionName, then the extension is added to the certificate request. If the request already contains an extension of that name, then the extension specified in the SetExtension call will replace the old one, hence modifying the contents. To disable an extension, a value of 2 can be specified in dwFlags parameter, described above, when calling SetExtension.

The following processing rules apply:

  1. The CA MUST look up the request based on the provided dwRequestId parameter in the request table. If the request is not found, the CA MUST fail the request.

  2. If the request is found in the CA database, the CA MUST verify that the value of the Request_Disposition column is "request pending". If the value of the Request_Disposition column is not "request pending", the CA MUST fail the request.

  3. The CA MUST verify if the pwszExtensionName parameter contains a valid OID (1), as specified in [X680]. If the OID (1) is not valid, the CA MUST fail the request.

  4. The CA MUST associate the specified extension and flags with the pending request, for possible inclusion later in the issued certificate, by adding the entry to the Extension table:

    • If dwType is 1 (PROPTYPE_LONG), the CA MUST encode the LONG value into an ASN.1 integer, as specified in [X660], and save the encoded value as the extension value.

    • If dwType is 2 (PROPTYPE_DATE), the CA MUST encode the FILETIME value into an ASN.1 Choice-of-Time, as specified in [X660], and save the encoded value as the extension value.

    • If dwType is 3 (PROPTYPE_BINARY), the CA MUST save the specified value as the extension value.

    • If dwType is 4 (PROPTYPE_STRING), the CA MUST encode the Unicode string value into an IA5String, as specified in [X660], and save the encoded value as the extension value.

    • If dwType is any other value, the CA MUST fail the request. The error code SHOULD be ERROR_INVALID_PARAMETER (0x80070057).