IX509Extension interface (certenroll.h)

The IX509Extension interface can be used to define an extension for a certificate request. Certificate extensions provide information about key usage, certificate policies and constraints, alternative name forms, and more. An extension consists of an object identifier (OID), a Boolean value that identifies whether the extension is critical, and a byte array that contains the extension value as shown by the following Abstract Syntax Notation One (ASN.1) syntax.


Extension ::= SEQUENCE 
{
   extnId              OBJECT IDENTIFIER,
   critical            BOOLEAN DEFAULT FALSE,
   extnValue           OCTETSTRING
}

The Certificate Enrollment API contains the following interfaces, derived from IX509Extension, that you can use to create the various extensions used most commonly in a public key infrastructure (PKI) that relies on a Windows certificate server.

Note  Do not use the IX509Extension base interface to represent any extension that can be represented by one of the following interfaces. Enrollment behavior is undefined if the appropriate interface is not used.

 
Interface Description
IX509ExtensionAlternativeNames Defines an AlternativeNames extension that contains one or more alternative name forms for the subject of the certificate request.
IX509ExtensionAuthorityKeyIdentifier Defines an AuthorityKeyIdentifier extension that enables identification of the certification authority public key that corresponds to the certification authority private key that signed an issued certificate. It is used by certificate path building software on a Windows server to find the certification authority certificate.
IX509ExtensionBasicConstraints Defines a BasicConstraints extension that identifies whether the entity can be used as a certification authority and, if so, the number of subordinate certification authorities that can exist beneath it in the certificate chain.
IX509ExtensionCertificatePolicies Defines a CertificatePolicies extension that identifies the policies under which the certificate has been issued and the purposes for which it can be used.
IX509ExtensionEnhancedKeyUsage Defines an EnhancedKeyUsage extension that identifies one or more uses of the public key contained in the certificate.
IX509ExtensionKeyUsage Defines a KeyUsage extension that restricts the operations that can be performed by the public key contained in the certificate.
IX509ExtensionMSApplicationPolicies Defines an MSApplicationPolicies extension that can be used by an application to filter certificates on the basis of permitted use. Permitted uses are identified by object identifiers (OIDs).
IX509ExtensionSmimeCapabilities Defines an SmimeCapabilities extension that identifies the decryption capabilities of an email recipient so that the sender of the email can choose the most secure encryption algorithm supported by both parties.
IX509ExtensionSubjectKeyIdentifier Defines a SubjectKeyIdentifier extension that differentiates between multiple public keys held by the certificate owner. The extension value is typically a SHA-1 hash of the key.
IX509ExtensionTemplate Defines a Template extension that identifies the version 2 template to use when issuing or renewing a certificate.
IX509ExtensionTemplateName Defines a TemplateName extension that identifies the version 1 template to use when issuing or renewing a certificate.
 

Most of the extensions that can be created by using the preceding interfaces are defined by the version 3 X.509 syntax standard. To create the version 3 extensions for which Microsoft does not provide a custom object, you can use the IX509Extension interface. These extensions are identified in the following table.

Extension/OID Description
AuthorityInformationAccess(XCN_OID_AUTHORITY_INFO_ACCESS) Identifies how to access certification authority information and services. The extension value contains a sequence of URIs.
CrlDistributionPoints(XCN_OID_CRL_DIST_POINTS) Contains the URI of the base certificate revocation list (CRL).
FreshestCRL(XCN_OID_FRESHEST_CRL) Contains the URI of the delta CRL. The same ASN.1 syntax is used for this extension and the CrlDistributionPoints extension.
NameConstraints(XCN_OID_NAME_CONSTRAINTS) Identifies the namespace within which all subject names of certificates in a certificate hierarchy must be located. The extension is used only in a certification authority certificate.
PolicyConstraints(XCN_OID_POLICY_CONSTRAINTS) Constrains path validation by prohibiting policy mapping or by requiring that each certificate in the hierarchy contain an acceptable policy identifier.
PolicyMappings(XCN_OID_POLICY_MAPPINGS) Identifies the policies in a subordinate certification authority that correspond to policies in the issuing certification authority. The extension value contains a sequence of issuing certification authority and subordinate certification authority policy mappings represented by object identifiers.
PrivateKeyUsagePeriod(XCN_OID_PRIVATEKEY_USAGE_PERIOD) Specifies a different validity period for the private key than for the certificate with which the key is associated.
SubjectDirectoryAttributes(XCN_OID_SUBJECT_DIR_ATTRS) Conveys identification attributes such as nationality about the certificate subject. The extension value is a sequence of OID-value pairs.
 

Finally, you can use the IX509Extension interface to define private extensions that contain information that is unique to a specific community.

Extensions are added to the Attributes structure of a PKCS #10 request and to the TaggedAttributes structure of a CMC request. To add extensions to either request format, you must first add them to an IX509Extensions collection and use the collection to initialize an IX509AttributeExtensions object. For more information, see the PKCS #10 Extensions and the CMC Extensions topics.

Inheritance

The IX509Extension interface inherits from the IDispatch interface. IX509Extension also has these types of members:

Methods

The IX509Extension interface has these methods.

 
IX509Extension::get_Critical

Specifies and retrieves a Boolean value that identifies whether the certificate extension is critical. (Get)
IX509Extension::get_ObjectId

Retrieves the object identifier (OID) for the extension.
IX509Extension::get_RawData

Retrieves a byte array that contains the extension value. (IX509Extension.get_RawData)
IX509Extension::Initialize

Initializes an IX509Extension object by using an object identifier (OID) and a byte array that contains the Distinguished Encoding Rules (DER) encoded extension.
IX509Extension::put_Critical

Specifies and retrieves a Boolean value that identifies whether the certificate extension is critical. (Put)

Requirements

Requirement Value
Minimum supported client Windows Vista [desktop apps only]
Minimum supported server Windows Server 2008 [desktop apps only]
Target Platform Windows
Header certenroll.h

See also

Certificate Enrollment API

ICryptAttribute

IDispatch

IX509AttributeExtensions

IX509Extensions