Edit

Attribute Functions

  • Article

Attributes can be added to a certificate request to provide a certification authority (CA) with additional information that it can use when creating and issuing a certificate.

CertEnroll.dll implements the following interfaces to define attributes and attribute collections:

The following sections identify functions exported by Xenroll.dll to associate cryptographic attributes with certificate requests and discuss how to use CertEnroll.dll to replace the function or indicate that no mapping between the two libraries exists:

addAttributeToRequestWStr

The addAttributeToRequestWStr function in Xenroll.dll adds an attribute to a certificate request.

In general, to add an attribute to a request by using the objects implemented in CertEnroll.dll, you can perform the following actions:

  1. Create an IX509Attributes collection object.
  2. Create an IX509Attribute object and call the Initialize method to create an attribute from an object identifier and attribute value or use any of the interfaces listed earlier to define one of the more common attributes.
  3. Add each new attribute created in the preceding step to the IX509Attributes collection by using the Add method.
  4. Create an ICryptAttribute object and initialize it by calling the InitializeFromValues method and specifying the IX509Attributes collection on input.
  5. Retrieve an ICryptAttributes collection object by calling the CryptAttributes property on an existing IX509CertificateRequestPkcs10 or IX509CertificateRequestCmc request object.
  6. Add the ICryptAttribute object to the ICryptAttributes collection.

AddAuthenticatedAttributesToPKCS7Request

Authenticated attributes are name-value pairs that are signed by and added to a signature. The AddAuthenticatedAttributesToPKCS7Request function in Xenroll.dll adds an array of authenticated attributes to a PKCS #7 request.

As discussed above for the addAttributeToRequestWStr function, you can use CertEnroll.dll to easily define and add a collection of attributes to a certificate request. You cannot, however, choose whether the attribute is authenticated. The enrollment process automatically makes this decision.

addNameValuePairToRequestWStr

The addNameValuePairToRequestWStr function in Xenroll.dll adds an unauthenticated name-value pair to a request.

You can use the IX509NameValuePair interface in CertEnroll.dll to define a name-value pair, and you can add a collection of name-value pairs to a CMC request object by performing the following actions:

  1. Create and initialize an IX509CertificateRequestCmc object. The initialization process creates an empty IX509NameValuePairs collection.
  2. Call the NameValuePairs property on an existing CMC request object to retrieve the collection.
  3. Create and initialize an IX509NameValuePair object.
  4. Add each new name-value pair to the IX509NameValuePairs collection by calling the Add method.

The enrollment process places the collection of name-value pairs in the TaggedAttribute structure of the CMC request.

AddNameValuePairToSignatureWStr

The AddNameValuePairToSignatureWStr function in Xenroll.dll adds an authenticated name-value pair to a request. This is typically used to specify the requester name in an enroll-on-behalf-of (EOBO) request.

In CertEnroll.dll, use the RequesterName property to specify the name in an EOBO request.

ClientId

The ClientId function in Xenroll.dll specifies or retrieves a ClientId attribute.

Use the ClientId property in CertEnroll.dll to add this attribute to a CMC or PKCS #10 request.

RenewalCertificate

The RenewalCertificate function in Xenroll.dll specifies or retrieves a RenewalCertificate attribute.

In CertEnroll.dll, when you call InitializeFromCertificate on a PKCS #7 or PKCS ) object is automatically created.

resetAttributes

The resetAttributes function in Xenroll.dll removes the attribute collection from a request.

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

Mapping Xenroll.dll to CertEnroll.dll

ICryptAttribute

ICryptAttributes

IX509Attribute

IX509Attributes

IX509NameValuePair

IX509NameValuePairs