Edit

Certificate Response Functions

  • Article

CertEnroll.dll implements the IX509Enrollment interface to submit a client certificate request and install the response from a certification authority (CA).

The enrollment process can accommodate the following three scenarios:

Out-of-band enrollment
  1. Call any initialization method implemented by the IX509Enrollment object.
  2. Call the CreateRequest method to retrieve the request.
  3. Submit the request out of band (manually or by using some other process).
  4. Receive the response from a CA.
  5. Call the InstallResponse method.

Automatic enrollment

  1. Call any initialization method implemented by the IX509Enrollment object.
  2. Call the Enroll method.

Delayed enrollment

  1. Call any initialization method implemented by the IX509Enrollment object.
  2. Call the CreateRequest method to retrieve the request.
  3. Store the request until you are ready to submit it.
  4. When you are ready to enroll, call the Initialize method to reinitialize the enrollment object.
  5. Call the InstallResponse method when the CA returns a certificate.

During the enrollment process, you can call the Status property on the IX509Enrollment object to retrieve an EnrollmentEnrollStatus enumeration value that identifies whether enrollment succeeded, is pending, was skipped, generated an error, or was denied.

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

acceptFilePKCS7WStr

The acceptFilePKCS7WStr function in Xenroll.dll installs a PKCS #7 response from a file.

The CertEnroll.dll library does not directly implement functionality to install a PKCS #7 certificate response from a file. You can, however, create a custom function to read the file data into a byte array and call InstallResponse to install the response.

If you specify the AllowNoOutstandingRequest value of the InstallResponseRestrictionFlags enumeration for the first parameter of InstallResponse, a dummy certificate need not exist, thereby enabling you to install a certificate without first calling Enroll or CreateRequest. However, if you are installing a certificate by using a web script, a dummy certificate must exist in the request store. You must therefore specify AllowNone for the first parameter.

acceptFileResponseWStr

The acceptFileResponseWStr function in Xenroll.dll installs a PKCS #7 or CMC certificate response from a file.

The CertEnroll.dll library does not directly implement functionality to install a certificate response from a file. You can, however, create a custom function to read the file data into a byte array and call InstallResponse to install the PKCS #7 or CMC response.

If you specify the AllowNoOutstandingRequest value of the InstallResponseRestrictionFlags enumeration for the first parameter of InstallResponse, a dummy certificate need not exist, thereby enabling you to install a certificate without first calling Enroll or CreateRequest. However, if you are installing a certificate by using a web script, a dummy certificate must exist in the request store. You must therefore specify AllowNone for the first parameter.

acceptPKCS7Blob

The acceptPKCS7Blob function in Xenroll.dll installs a PKCS #7 response contained in a byte array.

You can call InstallResponse to install a PKCS #7 message. If you specify the AllowNoOutstandingRequest value of the InstallResponseRestrictionFlags enumeration for the first parameter of InstallResponse, a dummy certificate need not exist, thereby enabling you to install the PKCS #7 response without first calling Enroll or CreateRequest. However, if you are installing a certificate by using a web script, a dummy certificate must exist in the request store. You must therefore specify AllowNone for the first parameter.

acceptResponseBlob

The acceptResponseBlob function in Xenroll.dll installs a PKCS #7 or CMC certificate response contained in a byte array.

You can call InstallResponse to install a PKCS #7 or CMC response. If you specify the AllowNoOutstandingRequest value of the InstallResponseRestrictionFlags enumeration for the first parameter of InstallResponse, a dummy certificate need not exist, thereby enabling you to install the response without first calling Enroll or CreateRequest. However, if you are installing a certificate by using a web script, a dummy certificate must exist in the request store. You must therefore specify AllowNone for the first parameter.

getCertContextFromFileResponseWStr

The getCertContextFromFileResponseWStr function in Xenroll.dll retrieves the client certificate from a file.

The CertEnroll.dll library does not directly implement functionality to retrieve a certificate from a CA response saved in a file. You can, however, create a custom function to read the file data into a byte array and call InstallResponse to install the PKCS #7 or CMC response, and call the Certificate property to retrieve the certificate.

If you specify the AllowNoOutstandingRequest value of the InstallResponseRestrictionFlags enumeration for the first parameter of InstallResponse, a dummy certificate need not exist, thereby enabling you to install a certificate without first calling Enroll or CreateRequest. However, if you are installing a certificate by using a web script, a dummy certificate must exist in the request store. You must therefore specify AllowNone for the first parameter.

getCertContextFromPKCS7

The getCertContextFromPKCS7 function in Xenroll.dll retrieves the client certificate from a PKCS #7 response.

You can call the Certificate property on the IX509Enrollment object to retrieve a certificate after calling the Enroll or InstallResponse method.

getCertContextFromResponseBlob

The getCertContextFromResponseBlob function in Xenroll.dll retrieves a client certificate from a PKCS #7 or CMC response.

You can call the Certificate property on the IX509Enrollment object to retrieve a certificate after calling the Enroll or InstallResponse method.

InstallPKCS7Blob

The InstallPKCS7Blob function in Xenroll.dll installs a PKCS #7 response.

You can call InstallResponse to install a PKCS #7 or CMC response. If you specify the AllowNoOutstandingRequest value of the InstallResponseRestrictionFlags enumeration for the first parameter of InstallResponse, a dummy certificate need not exist, thereby enabling you to install the response without first calling Enroll or CreateRequest. However, if you are installing a certificate by using a web script, a dummy certificate must exist in the request store. You must therefore specify AllowNone for the first parameter.

InstallPKCS7BlobEx

The InstallPKCS7BlobEx function in Xenroll.dll installs a PKCS #7 response and returns the number of certificates installed.

You can call InstallResponse to install a PKCS #7 or CMC response. If you specify the AllowNoOutstandingRequest value of the InstallResponseRestrictionFlags enumeration for the first parameter of InstallResponse, a dummy certificate need not exist, thereby enabling you to install the response without first calling Enroll or CreateRequest. However, if you are installing a certificate by using a web script, a dummy certificate must exist in the request store. You must therefore specify AllowNone for the first parameter.

SPCFileNameWStr

The SPCFileNameWStr function in Xenroll.dll specifies or retrieves the name of the file in which to save the certificate response. The CertEnroll.dll library does not implement functionality that enables you to copy a certificate to a specific file. The enrollment process automatically installs the certificate chain into files in the appropriate stores.

WriteCertToCSP

The WriteCertToCSP function in Xenroll.dll specifies or retrieves a Boolean value that indicates whether a certificate should be written to a cryptographic service provider (CSP). Typically, if this function is called, the provider is a smart card.

In CertEnroll.dll, when a client calls the Enroll method to submit a request for a smart card certificate and a certificate is issued, Enroll automatically installs the certificate on the smart card, assuming that the card is installed in the reader. The InstallResponse method also automatically writes the certificate to the smart card.

WriteCertToUserDS

The WriteCertToUserDS function in Xenroll.dll specifies or retrieves a Boolean value that indicates whether a certificate should be saved in the Active Directory store. The CertEnroll.dll library does not implement functionality that enables you to specify a store to copy a certificate to.

Mapping Xenroll.dll to CertEnroll.dll

IX509Enrollment