RSA BSAFE Cert-C
API Reference

pkimsg.h File Reference

This file defines PKI messaging (for example, certificate request) objects, including PKI_MSG_OBJ.

#include "basetype.h"
#include "bsafe.h"
#include "certext.h"
#include "certapi.h"
#include "certalg.h"
#include "cms.h"
#include "altname.h"
#include "pkistinf.h"

Go to the source code of this file.

Data Structures

struct PKI_CERT_IDENTIFIER

Identifies a certificate by using information related to the certificate. More...

struct PKI_ISSUER_SERIAL_NUMBER

Identifies issuer and serial number of a certificate. More...

struct PKI_POP_VAL_INFO

Contains information needed to validate a Proof-of-Possession that is included with a message. More...

union PKI_POP_GEN_INFO

Contains information for generating a Proof-of-Possession (POP) for a signature, key-agreement, or encryption private key. More...

struct PBM_INFO

Contains the information needed to protect or validate the protection of a PKI message using a password-based message authentication code (Password-Based MAC). More...

struct PKI_POP_GEN_SIGNATURE_INFO

Contains the information needed to generate a Proof-of-Possession for a signature private-key corresponding to the public key in a certification request, using either a digital signature or a password-based MAC. More...

struct PKI_PROTECT_INFO

Contains the information needed to generate and/or validate cryptographic protection of the message. More...

struct GENERAL_NAME_KEYID

Specifies PKI identity information. More...

struct PKI_CERTREQ_FIELDS

Contains the PKI message information that is specific to PKI certification request messages. More...

struct PKI_CERTRESP_FIELDS

Contains the PKI message information that is specific to PKI certification response messages. More...

struct PKI_ENTITY_ID

Identifies a PKI entity by its certificate issuer name and serial number (ISSUER_SERIAL_NUMBER) or by its general name and key identifier (GENERAL_NAME_KEYID). More...

struct PKI_KEY_TRANSPORT_INFO

Represents information associated with the recipient of a PKI message that transports a message-protection key from one entity to another. More...

struct PKI_MSG_FIELDS

Contains the PKI message information that is common to all PKI message types. More...

struct PKI_RECIPIENT

Holds information associated with a PKI message recipient. More...

struct PKI_RECIPIENT_INFO

Holds information associated with the recipient of a PKI message. More...

struct PKI_SENDER_INFO

The PKI_SENDER_INFO structure holds information associated with the sender of a PKI message. More...

Typedefs

typedef POINTER PKI_MSG_OBJ

Cert-C uses a PKI_MSG_OBJ object to store and pass PKI message requests and responses that pass between a certificate-requesting application and a CA or RA. More...

typedef LIST_OBJ_ENTRY_HANDLER PKI_SP_DATA_HANDLER

A LIST_OBJ_ENTRY_HANDLER that Cert-C uses to allocate and copy service-provider- specific data and associate it with a PKI message object. More...

Functions

int C_CreatePKIMsgObject (CERTC_CTX ctx, PKI_MSG_OBJ *pPkiMsgObj)

Creates a new PKI message object and stores the result in pPkiMsgObj. More...

void C_DestroyPKIMsgObject (PKI_MSG_OBJ *pPkiMsgObj)

Destroys a PKI message object, and frees its associated memory. More...

int C_SetPKIMsgSender (PKI_MSG_OBJ pkiMsgObj, PKI_SENDER_INFO *pSenderInfo)

Sets sender-related information in pkiMsgObj, using the information in pSenderInfo. More...

int C_GetPKIMsgSender (PKI_MSG_OBJ pkiMsgObj, PKI_SENDER_INFO *pSenderInfo)

Returns sender-specific information stored in the PKI message object. More...

int C_SetPKIMsgRecipient (PKI_MSG_OBJ pkiMsgObj, PKI_RECIPIENT_INFO *pRecipientInfo)

Sets recipient-related information in pkiMsgObj using the information in pRecipientInfo. More...

int C_GetPKIMsgRecipient (PKI_MSG_OBJ pkiMsgObj, PKI_RECIPIENT_INFO *pRecipientInfo)

Returns recipient-specific information stored in the PKI message object. More...

int C_SetPKIMsgProtectionType (PKI_MSG_OBJ pkiMsgObj, unsigned int protectionType)

Sets the message protection type. More...

int C_GetPKIMsgProtectionType (PKI_MSG_OBJ pkiMsgObj, unsigned int *pProtectionType)

Gets the protection type of an initialized message object. More...

int C_SetPKIMsgType (PKI_MSG_OBJ pkiMsgObj, unsigned int msgType)

Sets the message type of a PKI message object. More...

int C_GetPKIMsgType (PKI_MSG_OBJ pkiMsgObj, unsigned int *pMsgType)

Gets the message type of a PKI message object. More...

int C_SetPKIMsgVersion (PKI_MSG_OBJ pkiMsgObj, unsigned int version)

Sets the value of the protocol version. More...

int C_GetPKIMsgVersion (PKI_MSG_OBJ pkiMsgObj, unsigned int *pVersion)

Gets the value of the protocol version. More...

int C_SetPKIMsgTime (PKI_MSG_OBJ pkiMsgObj, GENERALIZED_TIME *pMsgTime)

Sets the time of production to the message. More...

int C_GetPKIMsgTime (PKI_MSG_OBJ pkiMsgObj, GENERALIZED_TIME *pMsgTime)

Gets the value of the message time when it was sent. More...

int C_SetPKIMsgTransID (PKI_MSG_OBJ pkiMsgObj, ITEM *pTransID)

Sets the value of the transaction ID used to associate request messages with corresponding response messages. More...

int C_GetPKIMsgTransID (PKI_MSG_OBJ pkiMsgObj, ITEM *pTransID)

Gets the value of the transaction ID used to associate request messages with corresponding response messages. More...

int C_SetPKIMsgSenderNonce (PKI_MSG_OBJ pkiMsgObj, ITEM *pSenderNonce)

Sets the nonce for the sender of the message. More...

int C_GetPKIMsgSenderNonce (PKI_MSG_OBJ pkiMsgObj, ITEM *pSenderNonce)

Gets the nonce for the sender of the message. More...

int C_SetPKIMsgRecipientNonce (PKI_MSG_OBJ pkiMsgObj, ITEM *pRecipientNonce)

Sets the nonce for recipient of the message. More...

int C_GetPKIMsgRecipientNonce (PKI_MSG_OBJ pkiMsgObj, ITEM *pRecipientNonce)

Gets the nonce for the recipient of the message. More...

int C_SetPKIMsgFreeText (PKI_MSG_OBJ pkiMsgObj, LIST_OBJ freeText)

Sets the value of the free text that contains a list of text strings that contain context-specific information to accompany the message. More...

int C_GetPKIMsgFreeText (PKI_MSG_OBJ pkiMsgObj, LIST_OBJ *pFreeText)

Gets the value of the free text that contains a list of text strings that contain context-specific information to accompany the message. More...

int C_SetPKIMsgGeneralInfo (PKI_MSG_OBJ pkiMsgObj, ATTRIBUTES_OBJ genInfo)

Sets the value of the general information that contains a set of messaging attributes used to convey context-specific information. More...

int C_GetPKIMsgGeneralInfo (PKI_MSG_OBJ pkiMsgObj, ATTRIBUTES_OBJ *pGenInfo)

Gets the value of the general information that contains a set of messaging attributes used to convey context-specific information. More...

int C_SetPKIMsgExtraCerts (PKI_MSG_OBJ pkiMsgObj, LIST_OBJ extraCerts)

Sets the value of extra certificates that may be useful for the recipient. More...

int C_GetPKIMsgExtraCerts (PKI_MSG_OBJ pkiMsgObj, LIST_OBJ *pExtraCerts)

Gets the value of extra certificates that may be useful for the recipient. More...

int C_SetPKIMsgExtraCRLs (PKI_MSG_OBJ pkiMsgObj, LIST_OBJ extraCRLs)

Sets the value of extra CRLs that may be useful for the recipient. More...

int C_GetPKIMsgExtraCRLs (PKI_MSG_OBJ pkiMsgObj, LIST_OBJ *pExtraCRLs)

Gets the value of extra CRLs that may be useful for the recipient. More...

int C_ResetPKIMsgObject (PKI_MSG_OBJ pkiMsgObj)

Resets the PKI message object to the state it was in after it was created. More...

int C_GetPKIMsgCount (PKI_MSG_OBJ pkiMsgObj, unsigned int *pCount)

Returns the count of PKI objects in a single PKI message object. More...

int C_AddPKIMsg (PKI_MSG_OBJ pkiMsgObj, POINTER pkiMsg, unsigned int *pIndex)

Adds a PKI message to a PKI message object. More...

int C_DeletePKIMsg (PKI_MSG_OBJ pkiMsgObj, unsigned int index)

Deletes a PKI message in a PKI message object. More...

int C_GetPKIMsg (PKI_MSG_OBJ pkiMsgObj, POINTER *pPkiMsg, unsigned int index)

Gets a PKI message from a PKI message object. More...

int C_RequestPKIMsg (CERTC_CTX ctx, char *pki, PKI_MSG_OBJ pkiRequest, PKI_PROTECT_INFO *pProtectInfo, SERVICE db, PKI_MSG_OBJ response)

Sends a certification request message to the specified PKI service. More...

int C_GetPKIMsgDER (CERTC_CTX ctx, char *pki, PKI_MSG_OBJ request, PKI_PROTECT_INFO *pProtectInfo, ITEM *pEncodedMsg)

Creates a serialized certification request message according to the protocol implemented by the specified PKI service provider. More...

int C_SendPKIRequest (CERTC_CTX ctx, char *pki, ITEM *pEncodedRequest, ITEM *pEncodedResponse, PKI_STATUS_INFO_OBJ statusInfo)

The C_SendPKIRequest() function sends a PKI request message to the server, and returns an encoded response message and the status of the send request operation. More...

int C_SetPKIMsgBER (CERTC_CTX ctx, char *pki, ITEM *pEncodedMsg, PKI_PROTECT_INFO *pProtectInfo, PKI_MSG_OBJ response)

Processes a certification response message. More...

int C_GeneratePKIMsgProofOfPossession (CERTC_CTX ctx, char *pki, PKI_MSG_OBJ pkiMsgObj, unsigned int index, B_KEY_OBJ privateKey, PKI_POP_GEN_INFO *pPopGenInfo)

Generates a POP for a particular certificate request message in the PKI message object. More...

int C_ValidatePKIMsgProofOfPossession (CERTC_CTX ctx, char *pki, PKI_MSG_OBJ msg, unsigned int index, PKI_POP_VAL_INFO *pPopValInfo, B_KEY_OBJ privateKey)

Validates a POP for a particular certificate request message in the PKI message object. More...

int C_SetPKIProviderData (PKI_MSG_OBJ message, POINTER data, PKI_SP_DATA_HANDLER *pHandler)

Typically used by a PKI service provider to associate service-provider-specific data with the message object. More...

int C_GetPKIProviderData (PKI_MSG_OBJ message, POINTER *data)

Typically used by a PKI service provider to retrieve service-provider-specific data previously associated with a PKI_MSG_OBJ, message, by a call to C_SetPKIProviderData(). More...

void C_DestroyPKIProviderData (PKI_MSG_OBJ message)

Destroys the provider-specific data stored in a PKI message object by calling the Destroy function specified in the handler provided to the C_SetPKIProviderData() function. More...

int C_SetPKIMsgFields (PKI_MSG_OBJ pkiMsgObj, PKI_MSG_FIELDS *pMsgFields)

Initializes or updates the general fields of a PKI message object. More...

int C_GetPKIMsgFields (PKI_MSG_OBJ pkiMsgObj, PKI_MSG_FIELDS *pMsgFields)

Returns the general, message type-independent fields of the PKI message object. More...

int C_SetPKICertRequestFields (PKI_MSG_OBJ certRequest, PKI_CERTREQ_FIELDS *pRequestFields)

Updates or initializes the message-type-specific fields of a certification request message object. More...

int C_GetPKICertRequestFields (PKI_MSG_OBJ certRequest, PKI_CERTREQ_FIELDS *pRequestFields)

Returns the message-type-specific fields of a certification request object. More...

int C_SetPKICertResponseFields (PKI_MSG_OBJ certResponse, PKI_CERTRESP_FIELDS *pResponseFields)

Updates or initializes the message-type-specific fields of a certification response message object. More...

int C_GetPKICertResponseFields (PKI_MSG_OBJ certResponse, PKI_CERTRESP_FIELDS *pResponseFields)

Returns the message-type-specific fields of a certification response object. More...

int C_RequestPKICert (CERTC_CTX ctx, char *pki, PKI_MSG_OBJ certRequest, PKI_PROTECT_INFO *pProtectInfo, SERVICE db, PKI_MSG_OBJ response)

Sends a certification request message to the specified PKI service. More...

int C_WritePKICertRequestMsg (CERTC_CTX ctx, char *pki, PKI_MSG_OBJ request, PKI_PROTECT_INFO *pProtectInfo, ITEM *pEncodedMsg)

Creates a serialized certification request message according to the protocol implemented by the specified PKI service provider. More...

int C_SendPKIMsg (CERTC_CTX ctx, char *pki, ITEM *pEncodedRequest, ITEM *pEncodedResponse, PKI_STATUS_INFO *pStatusInfo)

Sends a serialized PKI_MSG_OBJ (for example, as returned by C_WritePKICertRequestMsg()) to the specified PKI service. More...

int C_ReadPKICertResponseMsg (CERTC_CTX ctx, char *pki, ITEM *pEncodedMsg, PKI_PROTECT_INFO *pProtectInfo, PKI_MSG_OBJ certResponse)

Processes a certification response message. More...

int C_GeneratePKIProofOfPossession (CERTC_CTX ctx, char *pki, PKI_MSG_OBJ certRequest, B_KEY_OBJ privateKey, PKI_POP_GEN_INFO *pPopGenInfo)

Generates a POP for the indicated private key and attaches it to the message object. More...

int C_ValidatePKIProofOfPossession (CERTC_CTX ctx, char *pki, PKI_MSG_OBJ msg, PKI_POP_VAL_INFO *pPopValInfo, B_KEY_OBJ privateKey)

Validates the POP for a private key contained in a certification request message, and may also return the caller’s private key in a response. More...

Typedef Documentation

typedef POINTER PKI_MSG_OBJ

Cert-C uses a PKI_MSG_OBJ object to store and pass PKI message requests and responses that pass between a certificate-requesting application and a CA or RA. Cert-C 2.5 supports certificate requests and responses, certificate confirmation requests and responses, key update requests and responses, and certificate revocation requests and responses.
Cert-C supports the CRS, CMP, and SCEP PKI messaging transport mechanisms. The CRMF message format is also supported for use with the Cert-C CMP PKI service provider. These transport mechanisms are supported through the use of the Cert-C PKI messaging API and the various Cert-C PKI service providers. To create a PKI message request and transport it to a CA using CRS, SCEP, or CMP, use the relevant Cert-C PKI service provider and the PKI messaging APIs To set a PKI_MSG_OBJ with a PKI message type, call C_SetPKIMsgType and pass one of the following message types: PKI_MSGTYPE_CERT_REQ, PKI_MSGTYPE_KEY_UPDATE_REQ, or PKI_MSGTYPE_REVOKE_REQ.
Similarly, C_GetPKIMsgType can be called to determine the type of message in a PKI_MSG_OBJ. Cert-C 2.5 also supports key archival requests, at the time of the certificate request. A PKI message object can encapsulate any of the following PKI objects.

PKI Objects

PKI_CERT_REQ_OBJ

PKI_CERT_RESP_OBJ

PKI_CERT_CONF_REQ_OBJ

PKI_CERT_CONF_RESP_OBJ

PKI_KEY_UPDATE_REQ_OBJ

PKI_KEY_UPDATE_RESP_OBJ

PKI_REVOKE_REQ_OBJ

PKI_REVOKE_RESP_OBJ

PKI_ERROR_MSG_OBJ

PKI Related Objects
There are two more PKI objects: PKI_CERT_TEMPLATE_OBJ and PKI_STATUS_INFO_OBJ. However, the PKI_MSG_OBJ does not directly encapsulate these objects. Both PKI_CERT_REQ_OBJ and PKI_KEY_UPDATE_REQ_OBJ encapsulate the PKI_CERT_TEMPLATE_OBJ object. The PKI_CERT_RESP_OBJ, PKI_KEY_UPDATE_RESP_OBJ, PKI_REVOKE_RESP_OBJ, and PKI_CERT_CONF_REQ_OBJ objects encapsulate the PKI_STATUS_INFO_OBJ object.
Deprecated PKI Messaging APIs and Structures in Cert-C 2.5
In Cert-C 2.0 the C_GetPKIMsgFields and C_SetPKIMsgFields APIs were used to modify the PKI_MSG_FIELDS structure. This structure represented the fields of a PKI message object. The C_GetPKIMsgFields and C_SetPKIMsgFields API and the PKI_MSG_FIELDS structure are deprecated in Cert-C 2.5. Many other PKI message APIs and structures are deprecated in Cert-C 2.5. The following is a list of those deprecated functions and structures:

Deprecated Functions and Structures

C_GeneratePKIProofOfPossession()

C_GetPKICertRequestFields()

C_GetPKICertResponseFields()

C_GetPKIMsgFields()

C_ReadPKICertResponseMsg()

C_RequestPKICert()

C_SendPKIMsg()

C_SetPKICertResponseFields()

C_SetPKICertRequestFields()

C_SetPKIMsgFields()

C_ValidatePKIProofOfPossession()

C_WritePKICertRequestMsg()

PKI_MSG_FIELDS

PKI_CERTREQ_FIELDS

PKI_CERTRESP_FIELDS

PKI_RECIPIENT

Instead of these deprecated APIs, Cert-C 2.5 provides new C_Set* and C_Get* APIs that you must call directly on the PKI message object. These APIs modify the internal fields of a PKI message object. Cert-C 2.5 also provides new C_Set* and C_Get* APIs to modify the internal fields of the new PKI objects, which are encapsulated in the PKI_MSG_OBJ.
PKI Message Object Functions
Use a Cert-C function to view or modify information in a PKI_MSG_OBJ object. Do not assume that the PKI_MSG_OBJ object points to any specific information. Some examples of the functions that Cert-C provides to work with a PKI message object are listed in the following table.

Function Description

C_AddPKIMsg() Adds a specific type of PKI message to a PKI message object.

C_CreatePKIMsgObject() Creates a new PKI message object and stores the result.

C_DeletePKIMsg() Deletes a PKI message in a PKI message object.

C_DestroyPKIMsgObject() Destroys a PKI message object and frees its associated memory.

C_DestroyPKIProviderData() Destroys the provider-specific data stored in a PKI_MSG_OBJ object by calling the Destroy function specified in the handler provided to the C_SetPKIProviderData() function.

C_GetPKIMsg() Gets a PKI message from a PKI message object.

C_GetPKIMsgCount() Gets the number of PKI message objects in a single PKI message object.

C_GetPKIProviderData() Retrieves provider-specific data previously associated with a PKI_MSG_OBJ message, by a call to C_SetPKIProviderData(). It is typically used by a service provider.

C_ResetPKIMsgObject() Resets a PKI message object to the initial state produced by calling the C_CreatePKIMsgObject() function.

C_SetPKIProviderData() Associates service-provider-specific data with the PKI_MSG_OBJ object. It is typically used by a service provider.

C_GetPKIMsgExtraCerts() Gets any extra certificates that are stored in a PKI message object.

C_GetPKIMsgExtraCRLs() Gets any extra CRLs that are stored in a PKI message object.

C_GetPKIMsgFreeText() Gets a list of text strings stored in a PKI message object, which contain context-specific information to accompany the message.

C_GetPKIMsgGeneralInfo() Gets a set of messaging attributes stored in a PKI message object, which are used to convey context-specific information.

C_GetPKIMsgProtectionType() Gets the protection type of an initialized PKI message object.

C_GetPKIMsgRecipient() Gets the recipient information stored in a PKI message object and populates a PKI_RECIPIENT_INFO structure.

C_GetPKIMsgRecipientNonce() Gets the message-recipient nonce stored in a PKI message object.

C_GetPKIMsgSender() Gets the sender information stored in a PKI message object and populates a PKI_SENDER_INFO structure.

C_GetPKIMsgSenderNonce() Gets the message-sender nonce stored in a PKI message object.

C_GetPKIMsgTime() Gets the time when the PKI message was generated, which is stored in a PKI message object.

C_GetPKIMsgTransID() Gets the transaction ID used to associate a request message with its corresponding response message, which is stored in a PKI message object.

C_GetPKIMsgType() Gets the message type of a PKI message object.

C_GetPKIMsgVersion() Gets the value of the protocol version, stored in a PKI message object.

C_SetPKIMsgExtraCerts() Sets extra certificates in the PKI message object. The recipient can use these certificates to build a certificate chain.

C_SetPKIMsgExtraCRLs() Sets extra CRLs in the PKI message object. The recipient can use these certificates to build a certificate chain.

C_SetPKIMsgFreeText() Sets the PKI message object with a list of text strings that contain context-specific information to accompany the PKI message.

C_SetPKIMsgGeneralInfo() Sets the PKI message object with a set of messaging attributes used to convey context-specific information in the PKI message.

C_SetPKIMsgProtectionType() Sets the message protection type of the PKI message.

C_SetPKIMsgRecipient() Sets or initializes the recipient-specific information in a PKI message object.

C_SetPKIMsgRecipientNonce() Sets the message-recipient nonce in a PKI message object.

C_SetPKIMsgSender() Sets or initializes the sender-specific information in a PKI message object.

C_SetPKIMsgSenderNonce() Sets the message-sender nonce in a PKI message object.

C_SetPKIMsgTime() Sets the PKI message generation time in a PKI message object.

C_SetPKIMsgTransID() Sets the transaction ID, used to associate a request message with its corresponding response message, in a PKI message object.

C_SetPKIMsgType() Sets the PKI message type that this PKI message object represents. If the type is changed, the type-specific information is updated.

C_SetPKIMsgVersion() Sets the value of the protocol version in a PKI message object.

For more information on Cert-C objects, see Cert-C Objects.

typedef LIST_OBJ_ENTRY_HANDLER PKI_SP_DATA_HANDLER

A LIST_OBJ_ENTRY_HANDLER that Cert-C uses to allocate and copy service-provider- specific data and associate it with a PKI message object. Typically, it is called by the service provider. Use the destructor to clean up the memory associated with the data when the message object is destroyed.

Function Documentation

int C_AddPKIMsg ( PKI_MSG_OBJ pkiMsgObj,

POINTER pkiMsg,

unsigned int * pIndex

) ;

Adds a PKI message to a PKI message object.
Parameters:

pkiMsgObj This input/output parameter specifies the PKI message object.

pkiMsg This input parameter specifies a PKI message object.

pIndex This output parameter specifies the index of the request.

Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_CreatePKIMsgObject ( CERTC_CTX ctx,

PKI_MSG_OBJ * pPkiMsgObj

) ;

Creates a new PKI message object and stores the result in pPkiMsgObj. If unsuccessful, no memory is allocated, pPkiMsgObj is set to (PKI_MSG_OBJ)NULL_PTR, and E_ALLOC is returned.
Parameters:

ctx This input parameter is the Cert-C context.

pPkiMsgObj This output parameter points to the newly created PKI message object. It keeps an internal reference to the current Cert-C context.

Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_DeletePKIMsg ( PKI_MSG_OBJ pkiMsgObj,

unsigned int index

) ;

Deletes a PKI message in a PKI message object.
Parameters:

pkiMsgObj This input/output parameter specifies the PKI message object.

index This input parameter specifies the index of the request.

Returns:
If successful, returns 0. If not, returns a Cert-C error code.

void C_DestroyPKIMsgObject ( PKI_MSG_OBJ * pPkiMsgObj ) ;

Destroys a PKI message object, and frees its associated memory. It sets pPkiMsgObj to (PKI_MSG_OBJ)NULL_PTR. If pPkiMsgObj is already (PKI_MSG_OBJ)NULL_PTR, then no action is taken.
Parameters:

pPkiMsgObj This is both an input and an output parameter. As an input parameter, it is the PKI message object that Cert-C should destroy. As an output parameter, it is (PKI_MSG_OBJ)NULL_PTR.

Returns:
None.

void C_DestroyPKIProviderData ( PKI_MSG_OBJ message ) ;

Destroys the provider-specific data stored in a PKI message object by calling the Destroy function specified in the handler provided to the C_SetPKIProviderData() function.

The C_DestroyPKIProviderData() function is closely associated with the C_SetPKIProviderData() function, which is typically called by the service provider. If you call the C_SetPKIProviderData() function, for example, to clone the PKI_MSG_OBJ, use this C_DestroyPKIProviderData() function to destroy the provider-specific data.

Subsequent calls to C_GetPKIProviderData() return NULL_PTR for the provider-specific data value.
Parameters:

message This is both an input and an output parameter. As an input parameter, it is the PKI message object that Cert-C should destroy. As an output parameter, it is the updated PKI message object.

Returns:
None.

int C_GeneratePKIMsgProofOfPossession ( CERTC_CTX ctx,

char * pki,

PKI_MSG_OBJ pkiMsgObj,

unsigned int index,

B_KEY_OBJ privateKey,

PKI_POP_GEN_INFO * pPopGenInfo

) ;

Generates a POP for a particular certificate request message in the PKI message object.
Parameters:

ctx This input parameter is the Cert-C context.

pki This input parameter specifies the PKI protocol handler name.

pkiMsgObj This input/output parameter specifies the PKI message object.

index This input parameter specifies the index of the request in the message object.

privateKey This input parameter specifies the private key.

pPopGenInfo This input parameter is determined by POP type.

Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_GeneratePKIProofOfPossession ( CERTC_CTX ctx,

char * pki,

PKI_MSG_OBJ certRequest,

B_KEY_OBJ privateKey,

PKI_POP_GEN_INFO * pPopGenInfo

) ;

Generates a POP for the indicated private key and attaches it to the message object.
Deprecated:
This API is deprecated in Cert-C 2.5. For information of the replacements for deprecated PKI APIs, see the Cert-C CMP PKI Service Provider

int C_GetPKICertRequestFields ( PKI_MSG_OBJ certRequest,

PKI_CERTREQ_FIELDS * pRequestFields

) ;

Returns the message-type-specific fields of a certification request object.
Deprecated:
This API is deprecated in Cert-C 2.5. For information of the replacements for deprecated PKI APIs, see the Cert-C CMP PKI Service Provider

int C_GetPKICertResponseFields ( PKI_MSG_OBJ certResponse,

PKI_CERTRESP_FIELDS * pResponseFields

) ;

Returns the message-type-specific fields of a certification response object.
Deprecated:
This API is deprecated in Cert-C 2.5. For information of the replacements for deprecated PKI APIs, see the Cert-C CMP PKI Service Provider

int C_GetPKIMsg ( PKI_MSG_OBJ pkiMsgObj,

POINTER * pPkiMsg,

unsigned int index

) ;

Gets a PKI message from a PKI message object.
Parameters:

pkiMsgObj This input parameter specifies the certification request object.

pPkiMsg This input parameter specifies a PKI message object.

index This input parameter specifies the index of the request.

Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_GetPKIMsgCount ( PKI_MSG_OBJ pkiMsgObj,

unsigned int * pCount

) ;

Returns the count of PKI objects in a single PKI message object.
Parameters:

pkiMsgObj This input parameter specifies the PKI message object.

pCount This input/output parameter returns the count of messages in an object.

Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_GetPKIMsgDER ( CERTC_CTX ctx,

char * pki,

PKI_MSG_OBJ request,

PKI_PROTECT_INFO * pProtectInfo,

ITEM * pEncodedMsg

) ;

Creates a serialized certification request message according to the protocol implemented by the specified PKI service provider. The message is not actually transmitted to a PKI server. This function also applies relevant cryptographic protections, such as digital signatures or envelopes, to the message as a part of the serialization process.

Note: The application is responsible for calling T_Free() to free pEncodedMsg->data.
Parameters:

ctx This input parameter is the Cert-C context.

pki This input parameter specifies the PKI protocol handler name.

request This input parameter specifies the certification request object.

pProtectInfo This input parameter specifies the protection/integrity information.

pEncodedMsg This output parameter specifies the serialized request. The application is responsible for calling T_Free() to free pEncodedMsg->data.

ctx This input parameter is the Cert-C context.

Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_GetPKIMsgExtraCerts ( PKI_MSG_OBJ pkiMsgObj,

LIST_OBJ * pExtraCerts

) ;

Gets the value of extra certificates that may be useful for the recipient.
Parameters:

pkiMsgObj This input parameter specifies the message object.

pExtraCerts This output parameter specifies the list of CERT_OBJ to retrieve.

Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_GetPKIMsgExtraCRLs ( PKI_MSG_OBJ pkiMsgObj,

LIST_OBJ * pExtraCRLs

) ;

Gets the value of extra CRLs that may be useful for the recipient.
Parameters:

pkiMsgObj This input parameter specifies the message object.

pExtraCRLs This output parameter specifies the CRL_OBJ list to retrieve.

Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_GetPKIMsgFields ( PKI_MSG_OBJ pkiMsgObj,

PKI_MSG_FIELDS * pMsgFields

) ;

Returns the general, message type-independent fields of the PKI message object.
Deprecated:
This API is deprecated in Cert-C 2.5. For information of the replacements for deprecated PKI APIs, see the Cert-C CMP PKI Service Provider

int C_GetPKIMsgFreeText ( PKI_MSG_OBJ pkiMsgObj,

LIST_OBJ * pFreeText

) ;

Gets the value of the free text that contains a list of text strings that contain context-specific information to accompany the message.
Parameters:

pkiMsgObj This input parameter specifies the message object.

pFreeText This output parameter specifies the list of UTF-8 strings to retrieve.

Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_GetPKIMsgGeneralInfo ( PKI_MSG_OBJ pkiMsgObj,

ATTRIBUTES_OBJ * pGenInfo

) ;

Gets the value of the general information that contains a set of messaging attributes used to convey context-specific information.
Parameters:

pkiMsgObj This input parameter specifies the message object.

pGenInfo This output parameter specifies the context-specific information to retrieve.

Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_GetPKIMsgProtectionType ( PKI_MSG_OBJ pkiMsgObj,

unsigned int * pProtectionType

) ;

Gets the protection type of an initialized message object.
Parameters:

pkiMsgObj This input parameter specifies the message object.

pProtectionType This output parameter specifies the object's message protection type.

Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_GetPKIMsgRecipient ( PKI_MSG_OBJ pkiMsgObj,

PKI_RECIPIENT_INFO * pRecipientInfo

) ;

Returns recipient-specific information stored in the PKI message object. It fills in pRecipientInfo with the recipient information found in pkiMsgObj.

Internal objects in pRecipientInfo (such as NAME_OBJ objects) do not need to be created, and internal pointers (such as the data pointer in an ITEM) do not need to be allocated, before you pass pRecipientInfo to this function. Cert-C uses internal objects and structures to fill in pRecipientInfo.

After calling this function, you share the returned fields with the pkiMsgObj. To avoid memory leaks and crashes, you must use the C_SetPKIMsgRecipient() function if you need to modify any of these fields. This ensures that the internal state of the PKI message object remains consistent with your modifications.

C_GetPKIMsgRecipient() allows you to retrieve an individual field from a PKI message, whereas the C_GetPKIMsgFields() function obtains all of the fields from a PKI message. Begin using the C_GetPKIMsgRecipient() function in all new applications; the use of C_GetPKIMsgFields() to get msgFields.recipient is deprecated in Cert-C 2.0.

If you are using a CMP PKI service provider, you must call C_GetPKIMsgRecipient() instead of C_GetPKIMsgFields() to retrieve PKI recipient information.
Currently, if you are using another type of PKI service provider, you can call either C_GetPKIMsgRecipient() (recommended) or C_GetPKIMsgFields() (deprecated).

Note: Do not create any objects or items in pRecipientInfo before calling this function. Also, if you need to modify any of these fields, you must use the C_SetPKIMsgRecipient() function. If you do not, memory leaks and crashes are likely to occur.
Parameters:

pkiMsgObj This input parameter is a PKI message object.

pRecipientInfo This output parameter points to a structure that holds the recipient-related contents of pkiMsgObj.

Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_GetPKIMsgRecipientNonce ( PKI_MSG_OBJ pkiMsgObj,

ITEM * pRecipientNonce

) ;

Gets the nonce for the recipient of the message.
Parameters:

pkiMsgObj This input parameter contains the message object.

pRecipientNonce This output parameter provides the recipient nonce to retrieve.

Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_GetPKIMsgSender ( PKI_MSG_OBJ pkiMsgObj,

PKI_SENDER_INFO * pSenderInfo

) ;

Returns sender-specific information stored in the PKI message object. It fills in pSenderInfo with the sender information found in pkiMsgObj. Internal objects in pSenderInfo (such as NAME_OBJ objects) do not need to be created, and internal pointers (such as the data pointer in an ITEM) do not need to be allocated, before you pass pSenderInfo to this function. Cert-C uses internal objects and structures to fill in pSenderInfo.

After calling this function, you share the returned fields with the pkiMsgObj. This means that you must use the C_SetPKIMsgSender() function if you need to modify any of these fields. This ensures that the internal state of the PKI message object remains consistent with your modifications.

C_GetPKIMsgSender() allows you to retrieve an individual field from a PKI message, whereas the C_GetPKIMsgFields() function obtains all of the fields from a PKI message. Begin using the C_GetPKIMsgSender() function in all new applications; the use of C_GetPKIMsgFields() to get msgFields.sender is deprecated in Cert-C 2.0.

If you are using a CMP PKI service provider, you must call C_GetPKIMsgSender() instead of C_GetPKIMsgFields() to retrieve PKI sender information.
Currently, if you are using another type of PKI service provider, you can call either C_GetPKIMsgSender() (recommended) or C_GetPKIMsgFields() (deprecated).

Note: Do not create any objects or items in pSenderInfo before calling this function. Also, you must use the C_SetPKIMsgSender() function if you need to modify any of these fields. If you do not use the C_SetPKIMsgSender() function, memory leaks and crashes are likely to occur.
Parameters:

pkiMsgObj This input parameter is a PKI message object.

pSenderInfo This output parameter points to a structure that holds the sender-related contents of pkiMsgObj.

Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_GetPKIMsgSenderNonce ( PKI_MSG_OBJ pkiMsgObj,

ITEM * pSenderNonce

) ;

Gets the nonce for the sender of the message.
Parameters:

pkiMsgObj This input parameter contains the message object.

pSenderNonce This output parameter provides the sender nonce to retrieve.

Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_GetPKIMsgTime ( PKI_MSG_OBJ pkiMsgObj,

GENERALIZED_TIME * pMsgTime

) ;

Gets the value of the message time when it was sent.
Parameters:

pkiMsgObj This input parameter specifies the message object.

pMsgTime This output parameter specifies the time of message production to retrieve.

Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_GetPKIMsgTransID ( PKI_MSG_OBJ pkiMsgObj,

ITEM * pTransID

) ;

Gets the value of the transaction ID used to associate request messages with corresponding response messages.
Parameters:

pkiMsgObj This input parameter specifies the message object.

pTransID This output parameter specifies the transaction identifier to retrieve.

Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_GetPKIMsgType ( PKI_MSG_OBJ pkiMsgObj,

unsigned int * pMsgType

) ;

Gets the message type of a PKI message object.
Parameters:

pkiMsgObj This input parameter specifies the message object.

pMsgType This output parameter specifies the message type to retrieve.

Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_GetPKIMsgVersion ( PKI_MSG_OBJ pkiMsgObj,

unsigned int * pVersion

) ;

Gets the value of the protocol version.
Parameters:

pkiMsgObj This input parameter specifies the message object.

pVersion This output parameter specifies the protocol version identifier to retrieve.

Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_GetPKIProviderData ( PKI_MSG_OBJ message,

POINTER * data

) ;

Typically used by a PKI service provider to retrieve service-provider-specific data previously associated with a PKI_MSG_OBJ, message, by a call to C_SetPKIProviderData().

Note: The function returns a pointer to the message object's copy of the data. If the service provider modifies the data, it should call C_SetPKIProviderData() to ensure that the internal state of the message object is synchronized with the changes. The service provider should not directly destroy the data buffer, but rather should call C_DestroyPKIProviderData().
Parameters:

message This input parameter specifies the certification response.

data This output parameter specifies the serialization of provider-specific data.

Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_ReadPKICertResponseMsg ( CERTC_CTX ctx,

char * pki,

ITEM * pEncodedMsg,

PKI_PROTECT_INFO * pProtectInfo,

PKI_MSG_OBJ certResponse

) ;

Processes a certification response message.
Deprecated:
This API is deprecated in Cert-C 2.5. For information of the replacements for deprecated PKI APIs, see the Cert-C CMP PKI Service Provider

int C_RequestPKICert ( CERTC_CTX ctx,

char * pki,

PKI_MSG_OBJ certRequest,

PKI_PROTECT_INFO * pProtectInfo,

SERVICE db,

PKI_MSG_OBJ response

) ;

Sends a certification request message to the specified PKI service.
Deprecated:
This API is deprecated in Cert-C 2.5. For information of the replacements for deprecated PKI APIs, see the Cert-C CMP PKI Service Provider

int C_RequestPKIMsg ( CERTC_CTX ctx,

char * pki,

PKI_MSG_OBJ pkiRequest,

PKI_PROTECT_INFO * pProtectInfo,

SERVICE db,

PKI_MSG_OBJ response

) ;

Sends a certification request message to the specified PKI service. It receives and processes the response. If any certificates, CRLs, or keys are received in the response, these are stored in the database(s) bound to db. The application can examine the response message for status information. In addition, some services may require the application to examine the response to determine whether the identity of the responder is the one the application expected.
Parameters:

ctx This input parameter is the Cert-C context.

pki This input parameter specifies the PKI protocol handler name.

pkiRequest This input parameter specifies the certification request object.

pProtectInfo This input parameter specifies the protection/integrity information.

db This output parameter specifies the location of keys, certificates, and CRLs.

response This output parameter specifies the response message object.

Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_ResetPKIMsgObject ( PKI_MSG_OBJ pkiMsgObj ) ;

Resets the PKI message object to the state it was in after it was created.
Parameters:

pkiMsgObj This is both an input and an output parameter. As an input parameter, it is the PKI message object that Cert-C should reset. As an output parameter, it is the reset PKI message object.

Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_SendPKIMsg ( CERTC_CTX ctx,

char * pki,

ITEM * pEncodedRequest,

ITEM * pEncodedResponse,

PKI_STATUS_INFO * pStatusInfo

) ;

Sends a serialized PKI_MSG_OBJ (for example, as returned by C_WritePKICertRequestMsg()) to the specified PKI service.

Note: If the PKI_STATUS_INFO pStatusInfo->statusString is (LIST_OBJ)NULL_PTR, this API creates a list object in that field. Otherwise, it assumes that the user has placed a LIST_OBJ in that field. It is the user's responsibility to destroy that LIST_OBJ. If the pStatusInfo->statusString field is not initialized, C_AddItemToList() causes an access violation.

The application is also responsible for calling T_Free() to free pEncodedResponse->data.

Deprecated:
This API is deprecated in Cert-C 2.5. It is replaced by C_SendPKIRequest(). For information of the replacements for deprecated PKI APIs, see the Cert-C CMP PKI Service Provider
Parameters:

ctx This input parameter is the Cert-C context.

pki This input parameter is the PKI protocol handler name.

pEncodedRequest This input parameter is the encoded request message.

pEncodedResponse This output parameter is the encoded response message. The application is responsible for calling T_Free() to free pEncodedResponse->data.

pStatusInfo This output parameter is the out-of-band status information. Be sure the contents of pStatusInfo are zeroed out.

int C_SendPKIRequest ( CERTC_CTX ctx,

char * pki,

ITEM * pEncodedRequest,

ITEM * pEncodedResponse,

PKI_STATUS_INFO_OBJ statusInfo

) ;

The C_SendPKIRequest() function sends a PKI request message to the server, and returns an encoded response message and the status of the send request operation.

Note: The application is responsible for calling T_Free() to free pEncodedResponse->data.
Parameters:

ctx This input parameter is the Cert-C context.

pki This input parameter specifies the PKI protocol handler name.

pEncodedRequest This input parameter specifies the encoded request message.

pEncodedResponse This output parameter specifies the encoded response message. The application is responsible for calling T_Free() to free pEncodedMsg->data.

statusInfo This output parameter specifies the out-of-band status information.

Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_SetPKICertRequestFields ( PKI_MSG_OBJ certRequest,

PKI_CERTREQ_FIELDS * pRequestFields

) ;

Updates or initializes the message-type-specific fields of a certification request message object.
Deprecated:
This API is deprecated in Cert-C 2.5. For information of the replacements for deprecated PKI APIs, see the Cert-C CMP PKI Service Provider

int C_SetPKICertResponseFields ( PKI_MSG_OBJ certResponse,

PKI_CERTRESP_FIELDS * pResponseFields

) ;

Updates or initializes the message-type-specific fields of a certification response message object.
Deprecated:
This API is deprecated in Cert-C 2.5. For information of the replacements for deprecated PKI APIs, see the Cert-C CMP PKI Service Provider

int C_SetPKIMsgBER ( CERTC_CTX ctx,

char * pki,

ITEM * pEncodedMsg,

PKI_PROTECT_INFO * pProtectInfo,

PKI_MSG_OBJ response

) ;

Processes a certification response message. Relevant cryptographic protections are validated (such as digital signatures) or inverted (such as digital envelopes), or both validated and inverted. Information extracted from the message is stored in the supplied PKI_MSG_OBJ. The application is responsible for the long-term disposition of the information in the response object. The function does not store any elements of the certification response in the persistent data stores.
Parameters:

ctx This input parameter is the Cert-C context.

pki This input parameter specifies the PKI protocol handler name.

pEncodedMsg This input parameter specifies the serialized response.

pProtectInfo This input parameter specifies the protection/integrity information.

response This output parameter specifies the response message object.

Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_SetPKIMsgExtraCerts ( PKI_MSG_OBJ pkiMsgObj,

LIST_OBJ extraCerts

) ;

Sets the value of extra certificates that may be useful for the recipient.
Parameters:

pkiMsgObj This input/output parameter specifies the message object.

extraCerts This input parameter specifies the CERT_OBJ list to set.

Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_SetPKIMsgExtraCRLs ( PKI_MSG_OBJ pkiMsgObj,

LIST_OBJ extraCRLs

) ;

Sets the value of extra CRLs that may be useful for the recipient.
Parameters:

pkiMsgObj This input/output parameter specifies the message object.

extraCRLs This input parameter specifies the list of CRL_OBJ to set.

Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_SetPKIMsgFields ( PKI_MSG_OBJ pkiMsgObj,

PKI_MSG_FIELDS * pMsgFields

) ;

Initializes or updates the general fields of a PKI message object.
Deprecated:
This API is deprecated in Cert-C 2.5. For information of the replacements for deprecated PKI APIs, see the Cert-C CMP PKI Service Provider

int C_SetPKIMsgFreeText ( PKI_MSG_OBJ pkiMsgObj,

LIST_OBJ freeText

) ;

Sets the value of the free text that contains a list of text strings that contain context-specific information to accompany the message.
Parameters:

pkiMsgObj This input/output parameter specifies the message object.

freeText This input parameter specifies the list of UTF-8 strings to set.

Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_SetPKIMsgGeneralInfo ( PKI_MSG_OBJ pkiMsgObj,

ATTRIBUTES_OBJ genInfo

) ;

Sets the value of the general information that contains a set of messaging attributes used to convey context-specific information.
Parameters:

pkiMsgObj This input/output parameter specifies the message object.

genInfo This input parameter specifies the context-specific information to set.

Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_SetPKIMsgProtectionType ( PKI_MSG_OBJ pkiMsgObj,

unsigned int protectionType

) ;

Sets the message protection type.
Parameters:

pkiMsgObj This input/output parameter specifies the message object.

protectionType This input parameter specifies the message protection type to set.

Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_SetPKIMsgRecipient ( PKI_MSG_OBJ pkiMsgObj,

PKI_RECIPIENT_INFO * pRecipientInfo

) ;

Sets recipient-related information in pkiMsgObj using the information in pRecipientInfo. Subsequent calls to C_SetPKIMsgRecipient() replace existing recipient information. You can use this function to set the recipient information in one of two ways (see the PKI message recipient initialization options below).

C_SetPKIMsgRecipient() is a recipient-specific function that uses a separate structure to set recipient information in a PKI message. In contrast, C_SetPKIMsgFields() is a generic function that uses a shared structure to set all the fields of a PKI message. Begin using the C_SetPKIMsgRecipient() function in all new applications; the use of C_SetPKIMsgFields() to set msgFields.recipient is deprecated in Cert-C 2.0.

If you are using a CMP PKI service provider, you must call C_SetPKIMsgRecipient() instead of C_SetPKIMsgFields() to update PKI recipient information.
Currently, if you are using another type of PKI service provider, you can call either C_SetPKIMsgRecipient() (recommended) or C_SetPKIMsgFields() (deprecated).

PKI Message Recipient Initialization - Option 1

The application can create a new PKI_RECIPIENT_INFO structure, and initialize the structure. Then it can call C_SetPKIMsgRecipient() to update the recipient information in pkiMsgObj.

Because of the large number of fields and subfields in the PKI_RECIPIENT_INFO structure, it is likely that a number of them will be optional for any given PKI service provider. Before calling this function, call T_memset to ensure that all unused fields and subfields are initialized to 0 (zero). (For more information about T_memset in Cert-C, see Cert-C Service Provider Overview.)

Any internal objects or data structures referenced by pRecipientInfo must be allocated or created by the application. These objects or data structures are copied into the internal pkiMsgObj by C_PKISetMsgRecipient(), so the application must subsequently free or destroy them.

You should also call C_SetPKIMsgFields() to set the PKI_MSGFLAGS_IGNORE_RECIPIENT flag in msgFields.flags. This flag indicates that the msgFields.recipient field in pkiMsgObj is to be ignored.

PKI Message Recipient Initialization - Option 2

The application can allocate a new PKI_MSG_OBJ, and call C_GetPKIMsgRecipient() on that object. Then the application can initialize the returned pRecipientInfo structure, and call C_SetPKIMsgRecipient() to update the sender information in pkiMsgObj.

In this case, the application need not create any internal objects or data structures, but can instead update the objects or data structures returned by C_GetPKIMsgRecipient(). If the application chooses to allocate its own objects and assign them to pRecipientInfo structure members, they are copied into the pkiMsgObj, so the application is responsible for destroying or freeing those objects or data structures.

You should also call C_SetPKIMsgFields() to set the PKI_MSGFLAGS_IGNORE_RECIPIENT flag in msgFields.flags. This flag indicates that the msgFields.recipient field in pkiMsgObj is to be ignored.
Parameters:

pkiMsgObj This input/output parameter is a PKI message object to initialize or modify.

pRecipientInfo This input parameter is the recipient information to set in the PKI message object.

Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_SetPKIMsgRecipientNonce ( PKI_MSG_OBJ pkiMsgObj,

ITEM * pRecipientNonce

) ;

Sets the nonce for recipient of the message.
Parameters:

pkiMsgObj This input/output parameter contains the message object.

pRecipientNonce This input parameter provides the recipient nonce to set.

Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_SetPKIMsgSender ( PKI_MSG_OBJ pkiMsgObj,

PKI_SENDER_INFO * pSenderInfo

) ;

Sets sender-related information in pkiMsgObj, using the information in pSenderInfo. Subsequent calls to C_SetPKIMsgSender() replace existing sender information. Use this function to set the sender information in one of two ways (see the PKI message sender initialization options below).

C_SetPKIMsgSender() is a sender-specific function that uses a separate structure to set sender information in a PKI message. In contrast, C_SetPKIMsgFields() is a generic function that uses a shared structure to set all the fields of a PKI message. You should begin using the C_SetPKIMsgSender() function in all new applications; the use of C_SetPKIMsgFields() to set msgFields.sender is deprecated in Cert-C 2.0.

If you are using a CMP PKI service provider, you must call C_SetPKIMsgSender() instead of C_SetPKIMsgFields() to update PKI sender information.
Currently, if you are using another type of PKI service provider, you can call either C_SetPKIMsgSender() (recommended) or C_SetPKIMsgFields() (deprecated).

PKI Message Sender Initialization - Option 1

The application can create a new PKI_SENDER_INFO structure, and initialize the structure. Then it can call C_SetPKIMsgSender() to update the sender information in pkiMsgObj.

Because of the large number of fields and subfields in the PKI_SENDER_INFO structure, it is likely that a number of them will be optional for any given PKI service provider. Before calling this function, call T_memset to ensure that all unused fields and subfields are initialized to 0 (zero). (For more information about T_memset in Cert-C, see Cert-C Service Provider Overview.)

Any internal objects or data structures referenced by pSenderInfo must be allocated or created by the application. These objects or data structures are copied into the internal pkiMsgObj by C_PKISetMsgSender(), so the application must subsequently free or destroy them.

You should also call C_SetPKIMsgFields() to set the PKI_MSGFLAGS_IGNORE_SENDER flag in msgFields.flags. This flag indicates that the msgFields.sender field in pkiMsgObj is to be ignored.

PKI Message Sender Initialization - Option 2

The application can allocate a new PKI_MSG_OBJ, and call C_GetPKIMsgSender() on that object. Then the application can initialize the returned pSenderInfo structure, and call C_SetPKIMsgSender() to update the sender information in pkiMsgObj.

In this case, the application need not create any internal objects or data structures, but can instead update the objects or data structures returned by C_GetPKIMsgSender(). If the application chooses to allocate its own objects and assign them to pSenderInfo structure members, they are copied into the pkiMsgObj, so the application is responsible for destroying or freeing those objects or data structures.

You should also call C_SetPKIMsgFields() to set the PKI_MSGFLAGS_IGNORE_SENDER flag in msgFields.flags. This flag indicates that the msgFields.sender field in pkiMsgObj is to be ignored.
Parameters:

pkiMsgObj This input/output parameter is a PKI message object to initialize or modify.

pSenderInfo This input parameter contains the sender information to set in the PKI message object.

Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_SetPKIMsgSenderNonce ( PKI_MSG_OBJ pkiMsgObj,

ITEM * pSenderNonce

) ;

Sets the nonce for the sender of the message. Nonce is used to provide replay protection. senderNonce is inserted by the creator of this message. recipNonce is a nonce previously inserted in a related message by the intended recipient of this message.
Parameters:

pkiMsgObj This input/output parameter contains the message object.

pSenderNonce This input parameter provides the sender nonce to set.

Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_SetPKIMsgTime ( PKI_MSG_OBJ pkiMsgObj,

GENERALIZED_TIME * pMsgTime

) ;

Sets the time of production to the message.
Parameters:

pkiMsgObj This input/output parameter specifies the message object.

pMsgTime This input parameter specifies the time of message production to set.

Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_SetPKIMsgTransID ( PKI_MSG_OBJ pkiMsgObj,

ITEM * pTransID

) ;

Sets the value of the transaction ID used to associate request messages with corresponding response messages.
Parameters:

pkiMsgObj This input/output parameter specifies the message object.

pTransID This input parameter specifies the transaction identifier to set.

Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_SetPKIMsgType ( PKI_MSG_OBJ pkiMsgObj,

unsigned int msgType

) ;

Sets the message type of a PKI message object.
Parameters:

pkiMsgObj This input/output parameter specifies the message object.

msgType This input parameter specifies the message type to set.

Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_SetPKIMsgVersion ( PKI_MSG_OBJ pkiMsgObj,

unsigned int version

) ;

Sets the value of the protocol version.
Parameters:

pkiMsgObj This input/output parameter specifies the message object.

version This input parameter specifies the protocol version identifier to set.

Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_SetPKIProviderData ( PKI_MSG_OBJ message,

POINTER data,

PKI_SP_DATA_HANDLER * pHandler

) ;

Typically used by a PKI service provider to associate service-provider-specific data with the message object. If the new data pointer differs from one previously associated with the message, the previous data is destroyed. By calling C_GetPKIProviderData() and modifying the contents of the returned data, the PKI service provider can update the data without destroying and recopying it. If the data pointer is new, the AllocAndCopy function of the handler is called to create a new copy of the data to store with the message object. The Destroy function of the handler is called if the message object is destroyed, if the message type of the message object is modified, if C_SetPKIProviderData() is called with new data pointer, or if C_DestroyPKIProviderData() is called.
Parameters:

message This input/output parameter is the PKI message object to be updated.

data This input parameter is the PKI service provider data to associate with the message.

pHandler This parameter is a pointer to the data handler.

Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_ValidatePKIMsgProofOfPossession ( CERTC_CTX ctx,

char * pki,

PKI_MSG_OBJ msg,

unsigned int index,

PKI_POP_VAL_INFO * pPopValInfo,

B_KEY_OBJ privateKey

) ;

Validates a POP for a particular certificate request message in the PKI message object.
Parameters:

ctx This input parameter is the Cert-C context.

pki This input parameter specifies the PKI protocol handler name.

msg This input parameter specifies the PKI message object.

index This input parameter specifies the index of the request or response in the message object.

pPopValInfo This input parameter specifies private information to open response.

privateKey This output parameter specifies the subject's private key.

Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_ValidatePKIProofOfPossession ( CERTC_CTX ctx,

char * pki,

PKI_MSG_OBJ msg,

PKI_POP_VAL_INFO * pPopValInfo,

B_KEY_OBJ privateKey

) ;

Validates the POP for a private key contained in a certification request message, and may also return the caller’s private key in a response.
Deprecated:
This API is deprecated in Cert-C 2.5. For information of the replacements for deprecated PKI APIs, see the Cert-C CMP PKI Service Provider

int C_WritePKICertRequestMsg ( CERTC_CTX ctx,

char * pki,

PKI_MSG_OBJ request,

PKI_PROTECT_INFO * pProtectInfo,

ITEM * pEncodedMsg

) ;

Creates a serialized certification request message according to the protocol implemented by the specified PKI service provider.

Note: The application is responsible for calling T_Free() to free pEncodedMsg->data.

Deprecated:
This API is deprecated in Cert-C 2.5. For information of the replacements for deprecated PKI APIs, see the Cert-C CMP PKI Service Provider
Parameters:

ctx This input parameter is the Cert-C context.

pki This input parameter is the PKI protocol handler name.

request This input parameter is the certification request object.

pProtectInfo This input parameter is the PKI protection and integrity information.

pEncodedMsg This output parameter is the serialized request. The application is responsible for calling T_Free() to free pEncodedMsg->data.

RSA BSAFE^® Cert-C 2.7 API Reference

Data Structures
struct	PKI_CERT_IDENTIFIER
	Identifies a certificate by using information related to the certificate. More...
struct	PKI_ISSUER_SERIAL_NUMBER
	Identifies issuer and serial number of a certificate. More...
struct	PKI_POP_VAL_INFO
	Contains information needed to validate a Proof-of-Possession that is included with a message. More...
union	PKI_POP_GEN_INFO
	Contains information for generating a Proof-of-Possession (POP) for a signature, key-agreement, or encryption private key. More...
struct	PBM_INFO
	Contains the information needed to protect or validate the protection of a PKI message using a password-based message authentication code (Password-Based MAC). More...
struct	PKI_POP_GEN_SIGNATURE_INFO
	Contains the information needed to generate a Proof-of-Possession for a signature private-key corresponding to the public key in a certification request, using either a digital signature or a password-based MAC. More...
struct	PKI_PROTECT_INFO
	Contains the information needed to generate and/or validate cryptographic protection of the message. More...
struct	GENERAL_NAME_KEYID
	Specifies PKI identity information. More...
struct	PKI_CERTREQ_FIELDS
	Contains the PKI message information that is specific to PKI certification request messages. More...
struct	PKI_CERTRESP_FIELDS
	Contains the PKI message information that is specific to PKI certification response messages. More...
struct	PKI_ENTITY_ID
	Identifies a PKI entity by its certificate issuer name and serial number (`ISSUER_SERIAL_NUMBER`) or by its general name and key identifier (`GENERAL_NAME_KEYID`). More...
struct	PKI_KEY_TRANSPORT_INFO
	Represents information associated with the recipient of a PKI message that transports a message-protection key from one entity to another. More...
struct	PKI_MSG_FIELDS
	Contains the PKI message information that is common to all PKI message types. More...
struct	PKI_RECIPIENT
	Holds information associated with a PKI message recipient. More...
struct	PKI_RECIPIENT_INFO
	Holds information associated with the recipient of a PKI message. More...
struct	PKI_SENDER_INFO
	The `PKI_SENDER_INFO` structure holds information associated with the sender of a PKI message. More...
Typedefs
typedef POINTER	PKI_MSG_OBJ
	Cert-C uses a PKI_MSG_OBJ object to store and pass PKI message requests and responses that pass between a certificate-requesting application and a CA or RA. More...
typedef LIST_OBJ_ENTRY_HANDLER	PKI_SP_DATA_HANDLER
	A `LIST_OBJ_ENTRY_HANDLER` that Cert-C uses to allocate and copy service-provider- specific data and associate it with a PKI message object. More...
Functions
int	C_CreatePKIMsgObject (CERTC_CTX ctx, PKI_MSG_OBJ *pPkiMsgObj)
	Creates a new PKI message object and stores the result in pPkiMsgObj. More...
void	C_DestroyPKIMsgObject (PKI_MSG_OBJ *pPkiMsgObj)
	Destroys a PKI message object, and frees its associated memory. More...
int	C_SetPKIMsgSender (PKI_MSG_OBJ pkiMsgObj, PKI_SENDER_INFO *pSenderInfo)
	Sets sender-related information in pkiMsgObj, using the information in pSenderInfo. More...
int	C_GetPKIMsgSender (PKI_MSG_OBJ pkiMsgObj, PKI_SENDER_INFO *pSenderInfo)
	Returns sender-specific information stored in the PKI message object. More...
int	C_SetPKIMsgRecipient (PKI_MSG_OBJ pkiMsgObj, PKI_RECIPIENT_INFO *pRecipientInfo)
	Sets recipient-related information in pkiMsgObj using the information in pRecipientInfo. More...
int	C_GetPKIMsgRecipient (PKI_MSG_OBJ pkiMsgObj, PKI_RECIPIENT_INFO *pRecipientInfo)
	Returns recipient-specific information stored in the PKI message object. More...
int	C_SetPKIMsgProtectionType (PKI_MSG_OBJ pkiMsgObj, unsigned int protectionType)
	Sets the message protection type. More...
int	C_GetPKIMsgProtectionType (PKI_MSG_OBJ pkiMsgObj, unsigned int *pProtectionType)
	Gets the protection type of an initialized message object. More...
int	C_SetPKIMsgType (PKI_MSG_OBJ pkiMsgObj, unsigned int msgType)
	Sets the message type of a PKI message object. More...
int	C_GetPKIMsgType (PKI_MSG_OBJ pkiMsgObj, unsigned int *pMsgType)
	Gets the message type of a PKI message object. More...
int	C_SetPKIMsgVersion (PKI_MSG_OBJ pkiMsgObj, unsigned int version)
	Sets the value of the protocol version. More...
int	C_GetPKIMsgVersion (PKI_MSG_OBJ pkiMsgObj, unsigned int *pVersion)
	Gets the value of the protocol version. More...
int	C_SetPKIMsgTime (PKI_MSG_OBJ pkiMsgObj, GENERALIZED_TIME *pMsgTime)
	Sets the time of production to the message. More...
int	C_GetPKIMsgTime (PKI_MSG_OBJ pkiMsgObj, GENERALIZED_TIME *pMsgTime)
	Gets the value of the message time when it was sent. More...
int	C_SetPKIMsgTransID (PKI_MSG_OBJ pkiMsgObj, ITEM *pTransID)
	Sets the value of the transaction ID used to associate request messages with corresponding response messages. More...
int	C_GetPKIMsgTransID (PKI_MSG_OBJ pkiMsgObj, ITEM *pTransID)
	Gets the value of the transaction ID used to associate request messages with corresponding response messages. More...
int	C_SetPKIMsgSenderNonce (PKI_MSG_OBJ pkiMsgObj, ITEM *pSenderNonce)
	Sets the nonce for the sender of the message. More...
int	C_GetPKIMsgSenderNonce (PKI_MSG_OBJ pkiMsgObj, ITEM *pSenderNonce)
	Gets the nonce for the sender of the message. More...
int	C_SetPKIMsgRecipientNonce (PKI_MSG_OBJ pkiMsgObj, ITEM *pRecipientNonce)
	Sets the nonce for recipient of the message. More...
int	C_GetPKIMsgRecipientNonce (PKI_MSG_OBJ pkiMsgObj, ITEM *pRecipientNonce)
	Gets the nonce for the recipient of the message. More...
int	C_SetPKIMsgFreeText (PKI_MSG_OBJ pkiMsgObj, LIST_OBJ freeText)
	Sets the value of the free text that contains a list of text strings that contain context-specific information to accompany the message. More...
int	C_GetPKIMsgFreeText (PKI_MSG_OBJ pkiMsgObj, LIST_OBJ *pFreeText)
	Gets the value of the free text that contains a list of text strings that contain context-specific information to accompany the message. More...
int	C_SetPKIMsgGeneralInfo (PKI_MSG_OBJ pkiMsgObj, ATTRIBUTES_OBJ genInfo)
	Sets the value of the general information that contains a set of messaging attributes used to convey context-specific information. More...
int	C_GetPKIMsgGeneralInfo (PKI_MSG_OBJ pkiMsgObj, ATTRIBUTES_OBJ *pGenInfo)
	Gets the value of the general information that contains a set of messaging attributes used to convey context-specific information. More...
int	C_SetPKIMsgExtraCerts (PKI_MSG_OBJ pkiMsgObj, LIST_OBJ extraCerts)
	Sets the value of extra certificates that may be useful for the recipient. More...
int	C_GetPKIMsgExtraCerts (PKI_MSG_OBJ pkiMsgObj, LIST_OBJ *pExtraCerts)
	Gets the value of extra certificates that may be useful for the recipient. More...
int	C_SetPKIMsgExtraCRLs (PKI_MSG_OBJ pkiMsgObj, LIST_OBJ extraCRLs)
	Sets the value of extra CRLs that may be useful for the recipient. More...
int	C_GetPKIMsgExtraCRLs (PKI_MSG_OBJ pkiMsgObj, LIST_OBJ *pExtraCRLs)
	Gets the value of extra CRLs that may be useful for the recipient. More...
int	C_ResetPKIMsgObject (PKI_MSG_OBJ pkiMsgObj)
	Resets the PKI message object to the state it was in after it was created. More...
int	C_GetPKIMsgCount (PKI_MSG_OBJ pkiMsgObj, unsigned int *pCount)
	Returns the count of PKI objects in a single PKI message object. More...
int	C_AddPKIMsg (PKI_MSG_OBJ pkiMsgObj, POINTER pkiMsg, unsigned int *pIndex)
	Adds a PKI message to a PKI message object. More...
int	C_DeletePKIMsg (PKI_MSG_OBJ pkiMsgObj, unsigned int index)
	Deletes a PKI message in a PKI message object. More...
int	C_GetPKIMsg (PKI_MSG_OBJ pkiMsgObj, POINTER *pPkiMsg, unsigned int index)
	Gets a PKI message from a PKI message object. More...
int	C_RequestPKIMsg (CERTC_CTX ctx, char pki, PKI_MSG_OBJ pkiRequest, PKI_PROTECT_INFO pProtectInfo, SERVICE db, PKI_MSG_OBJ response)
	Sends a certification request message to the specified PKI service. More...
int	C_GetPKIMsgDER (CERTC_CTX ctx, char pki, PKI_MSG_OBJ request, PKI_PROTECT_INFO pProtectInfo, ITEM *pEncodedMsg)
	Creates a serialized certification request message according to the protocol implemented by the specified PKI service provider. More...
int	C_SendPKIRequest (CERTC_CTX ctx, char pki, ITEM pEncodedRequest, ITEM *pEncodedResponse, PKI_STATUS_INFO_OBJ statusInfo)
	The C_SendPKIRequest() function sends a PKI request message to the server, and returns an encoded response message and the status of the send request operation. More...
int	C_SetPKIMsgBER (CERTC_CTX ctx, char pki, ITEM pEncodedMsg, PKI_PROTECT_INFO *pProtectInfo, PKI_MSG_OBJ response)
	Processes a certification response message. More...
int	C_GeneratePKIMsgProofOfPossession (CERTC_CTX ctx, char pki, PKI_MSG_OBJ pkiMsgObj, unsigned int index, B_KEY_OBJ privateKey, PKI_POP_GEN_INFO pPopGenInfo)
	Generates a POP for a particular certificate request message in the PKI message object. More...
int	C_ValidatePKIMsgProofOfPossession (CERTC_CTX ctx, char pki, PKI_MSG_OBJ msg, unsigned int index, PKI_POP_VAL_INFO pPopValInfo, B_KEY_OBJ privateKey)
	Validates a POP for a particular certificate request message in the PKI message object. More...
int	C_SetPKIProviderData (PKI_MSG_OBJ message, POINTER data, PKI_SP_DATA_HANDLER *pHandler)
	Typically used by a PKI service provider to associate service-provider-specific data with the message object. More...
int	C_GetPKIProviderData (PKI_MSG_OBJ message, POINTER *data)
	Typically used by a PKI service provider to retrieve service-provider-specific data previously associated with a `PKI_MSG_OBJ`, message, by a call to C_SetPKIProviderData(). More...
void	C_DestroyPKIProviderData (PKI_MSG_OBJ message)
	Destroys the provider-specific data stored in a PKI message object by calling the `Destroy` function specified in the handler provided to the C_SetPKIProviderData() function. More...
int	C_SetPKIMsgFields (PKI_MSG_OBJ pkiMsgObj, PKI_MSG_FIELDS *pMsgFields)
	Initializes or updates the general fields of a PKI message object. More...
int	C_GetPKIMsgFields (PKI_MSG_OBJ pkiMsgObj, PKI_MSG_FIELDS *pMsgFields)
	Returns the general, message type-independent fields of the PKI message object. More...
int	C_SetPKICertRequestFields (PKI_MSG_OBJ certRequest, PKI_CERTREQ_FIELDS *pRequestFields)
	Updates or initializes the message-type-specific fields of a certification request message object. More...
int	C_GetPKICertRequestFields (PKI_MSG_OBJ certRequest, PKI_CERTREQ_FIELDS *pRequestFields)
	Returns the message-type-specific fields of a certification request object. More...
int	C_SetPKICertResponseFields (PKI_MSG_OBJ certResponse, PKI_CERTRESP_FIELDS *pResponseFields)
	Updates or initializes the message-type-specific fields of a certification response message object. More...
int	C_GetPKICertResponseFields (PKI_MSG_OBJ certResponse, PKI_CERTRESP_FIELDS *pResponseFields)
	Returns the message-type-specific fields of a certification response object. More...
int	C_RequestPKICert (CERTC_CTX ctx, char pki, PKI_MSG_OBJ certRequest, PKI_PROTECT_INFO pProtectInfo, SERVICE db, PKI_MSG_OBJ response)
	Sends a certification request message to the specified PKI service. More...
int	C_WritePKICertRequestMsg (CERTC_CTX ctx, char pki, PKI_MSG_OBJ request, PKI_PROTECT_INFO pProtectInfo, ITEM *pEncodedMsg)
	Creates a serialized certification request message according to the protocol implemented by the specified PKI service provider. More...
int	C_SendPKIMsg (CERTC_CTX ctx, char pki, ITEM pEncodedRequest, ITEM pEncodedResponse, PKI_STATUS_INFO pStatusInfo)
	Sends a serialized `PKI_MSG_OBJ` (for example, as returned by C_WritePKICertRequestMsg()) to the specified PKI service. More...
int	C_ReadPKICertResponseMsg (CERTC_CTX ctx, char pki, ITEM pEncodedMsg, PKI_PROTECT_INFO *pProtectInfo, PKI_MSG_OBJ certResponse)
	Processes a certification response message. More...
int	C_GeneratePKIProofOfPossession (CERTC_CTX ctx, char pki, PKI_MSG_OBJ certRequest, B_KEY_OBJ privateKey, PKI_POP_GEN_INFO pPopGenInfo)
	Generates a POP for the indicated private key and attaches it to the message object. More...
int	C_ValidatePKIProofOfPossession (CERTC_CTX ctx, char pki, PKI_MSG_OBJ msg, PKI_POP_VAL_INFO pPopValInfo, B_KEY_OBJ privateKey)
	Validates the POP for a private key contained in a certification request message, and may also return the caller’s private key in a response. More...