Edit

Extension Functions

  • Article

The X.509 version 3 certificate format identifies multiple extensions that can be added to a certificate to provide enhanced information about key usage, certificate policies and constraints, alternative name forms, and more.

CertEnroll.dll implements the following interfaces to manage certificate extensions:

Each of the following sections discusses a function exported by Xenroll.dll to manage certificate extensions. Each section also discusses how to use CertEnroll.dll to replace the function or indicates that no mapping between the two libraries exists:

AddCertTypeToRequestWStr

The AddCertTypeToRequestWStr function in Xenroll.dll adds a certificate template, by name, to a request.

Using CertEnroll.dll, the preferred method to incorporate a template into a certificate request is to use the InitializeFromTemplateName method on a PKCS#10 or [*PKCS ) request object or the InitializeFromInnerRequestTemplateName method on a CMC request.

If a specific template is not available on the client but is expected to be understood by the certification authority (CA), you can use the IX509ExtensionTemplateName interface to add a version 1 template or you can use the IX509ExtensionTemplate interface to add a version 2 template to a certificate request. For example, to add a version 1 template, perform the following actions:

  1. Create an IX509Extensions object.
  2. Create an IX509ExtensionTemplateName object and call the InitializeEncode method, specifying the template name.
  3. Add the extension created to the IX509Extensions collection by calling the Add method.
  4. Create an IX509AttributeExtensions object and call the InitializeEncode method, specifying the IX509Extensions collection on input.
  5. Retrieve an ICryptAttributes collection object by calling the CryptAttributes property on an existing IX509CertificateRequestPkcs10 or IX509CertificateRequestCmc request object.

AddCertTypeToRequestWStrEx

The AddCertTypeToRequestWStrEx function in Xenroll.dll adds a certificate template to a request by name, object identifier, and version.

For information about how to use CertEnroll.dll to incorporate template information in a request, see AddCertTypeToRequestWStr.

AddExtensionsToRequest

The AddExtensionsToRequest function in Xenroll.dll adds a collection of extensions to a request.

In CertEnroll.dll, extensions are added to the attributes collection of a CMC or a PKCS #10 request. To add extensions, perform the following actions:

  1. Create an IX509Extensions object.
  2. Create an IX509Extension object and call the Initialize method to create an extension from an object identifier and extension value or use any of the interfaces listed earlier to define one of the more common extensions.
  3. Add each new extension created in the preceding step to the IX509Extensions collection by calling the Add method.

addExtensionToRequestWStr

The addExtensionToRequestWStr function in Xenroll.dll adds a specific extension to the request.

In CertEnroll.dll, a specific extension must be defined and added to an extensions collection before the extension collection is added to the attributes collection of a CMC or a PKCS #10 request. For more information see the AddExtensionsToRequest discussion above.

EnableSMIMECapabilities

The EnableSMIMECapabilities function in Xenroll.dll specifies or retrieves a Boolean value that indicates whether to add the SMIMECapabilities extension to the request.

You can call the SmimeCapabilities property on the IX509CertificateRequestPkcs10 object to automatically add an IX509ExtensionSmimeCapabilities object to the request before encoding.

IncludeSubjectKeyID

The IncludeSubjectKeyID function in Xenroll.dll specifies or retrieves a Boolean value that indicates whether to add the SubjectKeyIdentifier extension to the request.

By default, the SubjectKeyIdentifier extension is created when the IX509CertificateRequestPkcs10 request object is initialized. You can override this behavior by calling the SuppressOids property.

If you have a public/private key pair, you can also use the IX509ExtensionSubjectKeyIdentifier interface in CertEnroll.dll to add a SubjectKeyIdentifier extension to a certificate request by performing the following actions:

  1. Create an IX509Extensions object.
  2. Create an IX509ExtensionSubjectKeyIdentifier object and call the InitializeEncode method, specifying a string that contains the identifier. Typically, this is a 20-byte SHA-1 hash of the public key contained in the CA signing certificate.
  3. Add the extension created to the IX509Extensions collection by calling the Add method.
  4. Create an IX509AttributeExtensions object and call the InitializeEncode method, specifying the IX509Extensions collection on input.
  5. Retrieve an ICryptAttributes collection object by calling the CryptAttributes property on an existing IX509CertificateRequestPkcs10 or IX509CertificateRequestCmc request object.

resetExtensions

The resetExtensions function in Xenroll.dll removes the extension collection from the request.

To remove an extension from a request by index number using CertEnroll.dll, call the Remove method on the IX509Extensions collection. To remove all attributes from a request, call the Clear method.

Mapping Xenroll.dll to CertEnroll.dll

ICryptAttributes

IX509Extension

IX509Extensions