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.
| 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 |