RSA BSAFE Cert-C API Reference

Cert-C CMP PKI Service Provider

The Cert-C CMP (Certificate Management Protocol) PKI service provider supports certificate requests and certificate responses using a CA that implements the CMP protocol. This service provider implements the following message types according to the profiles outlined in RFC 2510 and draft-ietf-pkix-rfc2510bis-06.

Message Type	Description
ir	Initialization Request
ip	Initialization Response
cr	Certification Request
cp	Certification Response
kur	Key Update Request
kup	Key Update Response
rr	Revocation Request
rp	Revocation Response
pkiconf	Confirmation
error	Error Message
certConf	Certificate Confirm

New PKI messaging objects and new APIs that manipulate the individual fields of these objects are introduced in Cert-C 2.7. There are two methods to use the Cert-C CMP PKI Service Provider with the new APIs, namely:

1. The request/confirm procedure
   
   This is the recommended way of using the Cert-C CMP PKI Service Provider. Use C_RequestPKIMsg to make a particular request. Optionally, call C_RequestPKIMsg again for a confirmation request, if the first call was successful.
   
   
2. The write/send/read procedure
   
   This procedure is used primarily for debugging or batch processing. Use C_GetPKIMsgDER to write a serialized request. Then, call C_SendPKIRequest to send the serialized request and to receive a serialized response from the server. The final step is to call C_SetPKIMsgBER to read the serialized response in a PKI_MSG_OBJ. It may be necessary to repeat the same sequence with a different message type, depending on the request and response. When using this procedure, popType PKI_POP_ENCRYPTION and PKI_POP_GEN_INFO.method cannot be PKI_POP_METHOD_ENCRYPT_CERT and PKI_POP_GEN_INFO.method cannot be PKI_POP_METHOD_ENCRYPT_CERT. These assignments are not supported.

The following APIs are deprecated for all Cert-C PKI Service Providers:

• C_SetPKIMsgFields
• C_GetPKIMsgFields
• C_SetPKICertRequestFields
• C_GetPKICertRequestFields
• C_SetPKICertResponseFields
• C_GetPKICertResponseFields
• C_RequestPKICert
• C_WritePKICertRequestMsg
• C_SendPKIMsg
• C_ReadPKICertResponseMsg
• C_GeneratePKIProofOfPossession
• C_ValidatePKIProofOfPossession

The only reason to use the C_Write*, C_Send*, and C_Read* functions are for application debugging. The use of C_RequestPKIMsg is highly recommended. Both of these methods require input parameters to be set in the same way; these input parameters are discussed in the following section. For additional guidance on the use of these API functions, see the examples provided in the samples subdirectory of the Cert-C installation directory.

Almost all forms of certificate requests must contain a call to C_GeneratePKIMsgProofOfPossession before C_GetPKIMsgDER or C_RequestPKIMsg is called; otherwise, an error will occur. The C_GeneratePKIMsgProofOfPossession function call is not required when the key pair is generated by the CA and given to the end entity.

Some types of certificate requests cause certificates to be issued immediately if a pre-approval mechanism is supported by the CA. In other cases, the CA must manually examine and approve (or reject) the request; afterwards, the issued certificate may be retrieved by the client.

The Cert-C CMP PKI service provider has no provision for verifying that the signer of a CMP response is the expected sender. This is because the CA addressed by a single service-provider instance may cause responses to be signed by different entities, depending on the particulars of the request. The application can, and should, verify that the signer (returned from C_GetPKIMsgSender) of the response object is the one that is supposed to have signed the response.

General information to help construct a complete CMP certificate request is located in the CMP and CRMF specifications. The CMP specification describes several ways to transport the request from the client to the CA.

This service provider supports only CMP-over-TCP as the transport method for communicating with a CA.

Because the options for creating certificate requests are numerous and vary significantly from one CA implementation and configuration to another, contact the CA vendor for information that is specific to their CA's implementation of CMP.

Data structures and functions specific to this service provider are defined in cmp.h. There is one API specific to this service provider: S_InitializeCMP. There are also three deprecated APIs: S_CMPCertConfirm, S_CMPSetMessageType, and S_CMPGetMessageType. All generic PKI API functionality is defined in header file pkimsg.h.

To use the Cert-C CMP PKI service provider in an application, be sure to link in the certcsp library and include the cmp.h header file. Cert-C includes a sample for the Cert-C CMP PKI service provider in the sample/cmp directory. For more information on PKI service providers, see the chapter about PKI transaction samples in the Cert-C Developer's Guide.

Setting Up Data Structures

CMP messages can be one of many sub-message types, each with a different purpose and with a different encoding. The Cert-C CMP PKI service provider can encode the following types of CMP PKI messages: ir, cr, kur, and rr. It can also decode the following types of CMP PKI messages: ip, cp, kup, rp,and error.

Use an ir request message to request an end entity's first certificate from a CA. The CA uses an ip message to return the certificate to the end entity, after the end entity submits an ir message to the CA. Use an cr message to request additional certificates for an end entity after the end entity receives its first certificate. Currently, Cert-C supports the sender name as directoryName only. The sender name is taken from the end entity's certificate in the ip message. The CA uses a cp message to deliver the certificate to the end entity after the end entity submits a cr request message. Use a kur request message to request updates to existing certificates from a CA. The CA uses a kup message to return the updated certificate to the end-entity. Use an rr request message to request revocation of certificates from a CA. The CA uses an rp message to send the response back to the requestor of the revocation. The CA uses an error message to deliver any error to the end entity.

The certConf and pkiConf message types are handled by calling S_CMPCertConfirm, now deprecated.

To form a valid CMP request using this service provider, certain request and response fields must be correctly set.(Many of these fields are not used by this service provider.)

In previous versions of Cert-C, these fields were set with the following deprecated structures:

PKI_MSG_FIELDS
PKI_CERTREQ_FIELDS
PKI_PROTECT_INFO
PKI_POP_GEN_INFO
PKI_POP_GEN_SIGNATURE_INFO
PKI_CERTRESP_FIELDS

• The deprecated data structure PKI_MSG_FIELDS and two APIs, C_SetPKIMsgFields and C_GetPKIMsgFields have been replaced by the following functions:

  C_SetPKIMsgSender	C_GetPKIMsgSender
  C_SetPKIMsgRecipient	C_GetPKIMsgRecipient
  C_SetPKIMsgProtectionType	C_GetPKIMsgProtectionType
  C_SetPKIMsgType	C_GetPKIMsgType
  C_SetPKIMsgVersion	C_GetPKIMsgVersion
  C_SetPKIMsgTime	C_GetPKIMsgTime
  C_SetPKIMsgTransID	C_GetPKIMsgTransID
  C_SetPKIMsgSenderNonce	C_GetPKIMsgSenderNonce
  C_SetPKIMsgRecipientNonce	C_GetPKIMsgRecipientNonce
  C_SetPKIMsgFreeText	C_GetPKIMsgFreeText
  C_SetPKIMsgGeneralInfo	C_GetPKIMsgGeneralInfo
  C_SetPKIMsgExtraCerts	C_GetPKIMsgExtraCerts
  C_SetPKIMsgExtraCRLs	C_GetPKIMsgExtraCRLs

• The data structure PKI_CERTREQ_FIELDS has been replaced by PKI_CERT_REQ_OBJ. The two APIs, C_SetPKICertRequestFields and GetPKICertRequestFields have been replaced by the following functions:

  C_SetPKICertReqID	C_GetPKICertReqID
  C_SetPKICertReqControls	C_GetPKICertReqControls
  C_SetPKICertReqPOPType	C_GetPKICertReqPOPType
  C_SetPKICertRegInfo	C_GetPKICertReqRegInfo
  C_SetPKICertReqTemplate	C_GetPKICertReqTemplate

• The data structure PKI_CERTREQ_FIELDS has been replaced by PKI_CERT_REQ_OBJ. The two APIs, C_SetPKICertResponseFields and C_GetPKICertResponseFields have been replaced by the following functions:

  C_SetPKICertRespStatus	C_GetPKICertRespStatus
  C_SetPKICertCertRespReqId	C_GetPKICertCertRespReqId
  C_SetPKICertRespRequestedCert	C_GetPKICertRespRequestedCert
  C_SetPKICertRespRequestedPrivateKey	C_GetPKICertRespRequestedPrivateKey
  C_SetPKICertRespRegInfo	C_GetPKICertRespRegInfo
  C_SetPKICertRespCACerts	C_GetPKICertRespCACerts

• C_RequestPKIMsg replaces the deprecated API C_RequestPKICert.

• C_GetPKIMsgDER replaces the deprecated API C_WritePKICertRequestMsg.

• C_SendPKIRequest replaces the deprecated API C_SendPKIMsg.

• C_SetPKIMsgBER replaces the deprecated API C_ReadPKICertResponseMsg.

• C_GeneratePKIMsgProofOfPossession replaces the deprecated API C_GeneratePKIProofOfPossession.

• C_ValidatePKIMsgProofOfPossession replaces the deprecated API C_ValidatePKIProofOfPossession.

The following deprecated SPIs are replaced by a combination of new APIs and specific flags. They are replaced by new procedures.

• S_CMPCertConfirm generated a certificate confirmation message, sentthe confirmation DER and decoded the response. Replace it by using the API C_RequestPKIMsg with the message type set to PKI_MSGTYPE_CERT_CONF_REQ.
  
  
• S_CMPSetMessageType and S_CMPGetMessageType are replaced by using the two APIs C_SetPKIMsgType and C_GetPKIMsgType specifying one of the following message types:

     PKI_MSGTYPE_UNKNOWN
     PKI_MSGTYPE_CERT_REQ
     PKI_MSGTYPE_CERT_RESP
     PKI_MSGTYPE_REVOKE_REQ
     PKI_MSGTYPE_REVOKE_RESP
     PKI_MSGTYPE_KEYUPDATE_REQ
     PKI_MSGTYPE_KEYUPDATE_RESP
     PKI_MSGTYPE_ERROR_MSG
     PKI_MSGTYPE_CERT_CONF_REQ
     PKI_MSGTYPE_CERT_CONF_RESP

Service Provider Configuration Information on the Web

To download a current version of the Service Provider regInfo Configuration Options document that describes the correct settings for these fields, go to RSA Security's Support Web Site ( http://www.rsasecurity.com/support). This document describes each of the fields, how to set each one, and the required combinations. For the encode or input fields structures, the site describes what is required to make the different types of CMP requests. For the decode or output fields structures the site describes what fields to expect in the different types of CMP responses. The values of the output fields are determined by the CA.

Notes on Deprecated Structures

All of the deprecated structures are defined to contain a flags field and a series of data items. For each data item, a flags field states whether or not the data item should be considered when performing a SetFields or GetFields function call. When it is stated that an data item is not used, this means that the field should have its corresponding IGNORE-bit set in the flags field. When a data item is set with the intent of being transferred into the object's fields during a SetFields function call, its IGNORE-bit should be cleared before the call. Similarly, if a data item in the fields structure is made relevant as a side-effect of the call, its corresponding IGNORE-bit will be cleared to show that this is the case. The flags field is intended to always reflect the state of the pertinence of its related data item.

The use of PKI_MSG_FIELDS.sender and PKI_MSG_FIELDS.recipient and their corresponding IGNORE bits were deprecated in Cert-C 2.0. Do not use these deprecated data structure fields with the Cert-C CMP PKI service provider. The new data structures PKI_ENTITY_ID and PKI_RECIPIENT_INFO along with the API calls C_GetPKIMsgSender and C_SetPKIMsgRecipient, respectively, must be used instead.