ICertAdmin::SetCertificateExtension method (certadm.h)

Article
10/13/2021

The SetCertificateExtension method adds a new extension to the certificate issued in response to a certificate request. This method was first defined by the ICertAdmin interface.

For this method to succeed, the certificate request must be pending.

Syntax

HRESULT SetCertificateExtension(
  [in] const BSTR    strConfig,
  [in] LONG          RequestId,
  [in] const BSTR    strExtensionName,
  [in] LONG          Type,
  [in] LONG          Flags,
  [in] const VARIANT *pvarValue
);

Parameters

[in] strConfig

Represents a valid configuration string for the certification authority (CA) 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.

Important SetCertificateExtension does not clear the internal cache when the configuration string is changed. When you change the configuration string for the CA, you must instantiate a new ICertAdmin object and call this method again with the new configuration string.

[in] RequestId

Specifies the ID of the certificate request.

[in] strExtensionName

Specifies the object identifier (OID) for the extension to set. The string must be 31 or fewer non-NULL characters in length.

[in] Type

Specifies the type of extension being set. The Type parameter must agree with the data type of the pvarValue parameter. This data type is set in the vt field of the VARIANT structure.

This parameter can be one of the following values.

Value	Meaning
PROPTYPE_LONG	Signed long data
PROPTYPE_DATE	Date/time
PROPTYPE_BINARY	The extension value is set as is and is assumed to be ASN.1 encoded if necessary.
PROPTYPE_STRING	The extension value will be ASN.1 encoded as an IA5 string before it is placed in the new certificate. Note You should use PROPTYPE_STRING for an extension value that consists of a single URL only if you want the URL to be automatically encoded as an IA5 string. Otherwise, encode the URL as an IA5 string yourself and pass the encoded value as PROPTYPE_BINARY.

[in] Flags

Specifies the flags for the extension being set. If no flag is to be set, use a value of zero. You can combine these flags with a bitwise-OR operation and also with policy private extension flags (the high 8 bits of the EXTENSION_POLICY_MASK field).

Note When the Flags parameter is set to EXTENSION_DISABLE_FLAG, the extension will be disabled in the server log and will not be added to the certificate.

Value	Meaning
EXTENSION_CRITICAL_FLAG	This is a critical extension.
EXTENSION_DISABLE_FLAG	The extension will not be used.

[in] pvarValue

Specifies the value associated with the extension.

Return value

VB

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.

Remarks

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.

Requirements

Requirement	Value
Minimum supported client	None supported
Minimum supported server	Windows Server 2003 [desktop apps only]
Target Platform	Windows
Header	certadm.h (include Certsrv.h)
Library	Certidl.lib
DLL	Certadm.dll