RSA Security logo

RSA BSAFE Cert-C
API Reference

pkistinf.h File Reference

This file defines PKI status information objects.

PKI_STATUS_INFO_OBJ is used to represent the status information from the response.

#include "basetype.h"

Go to the source code of this file.

Data Structures

struct  PKI_STATUS_INFO
 Contains information about the status of a PKI transaction. More...


Typedefs

typedef POINTER PKI_STATUS_INFO_OBJ
 Represents encapsulated provider-specific status and failure information. More...


Functions

int C_CreatePKIStatusInfoObject (CERTC_CTX ctx, PKI_STATUS_INFO_OBJ *pPkiStatusInfoObj)
 Creates and initializes a PKI status info Object. More...

void C_DestroyPKIStatusInfoObject (PKI_STATUS_INFO_OBJ *pPkiStatusInfoObj)
 Destroys a PKI_STATUS_INFO_OBJ and frees all memory used by it. More...

int C_SetPKIStatus (POINTER pkiObj, unsigned int pkiStatus)
 Sets the overall PKI status in a PKI_STATUS_INFO_OBJ or a PKI_ERROR_MSG_OBJ. More...

int C_GetPKIStatus (POINTER pkiObj, unsigned int *pPkiStatus)
 Gets the overall PKI status from a PKI_STATUS_INFO_OBJ or a PKI_ERROR_MSG_OBJ. More...

int C_SetPKIFailInfo (POINTER pkiObj, unsigned int pkiFailInfo)
 Sets the additional information about failure cases in a PKI_STATUS_INFO_OBJ or a PKI_ERROR_MSG_OBJ. More...

int C_GetPKIFailInfo (POINTER pkiObj, unsigned int *pPkiFailInfo)
 Gets additional information about failure cases from a PKI_STATUS_INFO_OBJ or a PKI_ERROR_MSG_OBJ. More...

int C_SetPKIStatusString (POINTER pkiObj, LIST_OBJ statusStringList)
 Sets the PKI status string in a PKI_STATUS_INFO_OBJ or a PKI_ERROR_MSG_OBJ. More...

int C_GetPKIStatusString (POINTER pkiObj, LIST_OBJ *pStatusStringList)
 Gets a list of NUL-terminated text strings, which represent the status value, from a PKI_STATUS_INFO_OBJ or a PKI_ERROR_MSG_OBJ. More...

int C_SetPKIFailInfoAux (POINTER pkiObj, unsigned int failInfoAux)
 Sets the PKI service-provider-specific failure code in a PKI_STATUS_INFO_OBJ or a PKI_ERROR_MSG_OBJ. More...

int C_GetPKIFailInfoAux (POINTER pkiObj, unsigned int *pFailInfoAux)
 Gets the PKI service-provider-specific failure code from a PKI_STATUS_INFO_OBJ or a PKI_ERROR_MSG_OBJ. More...

Typedef Documentation

typedef POINTER PKI_STATUS_INFO_OBJ
 

Represents encapsulated provider-specific status and failure information. The PKI_MSG_OBJ does not directly encapsulate the PKI_STATUS_INFO_OBJ object. PKI_STATUS_INFO_OBJ can be encapsulated by the PKI_CERT_RESP_OBJ, PKI_KEY_UPDATE_RESP_OBJ, PKI_REVOKE_RESP_OBJ, or PKI_CERT_CONF_REQ_OBJ objects, which in turn is encapsulated by the PKI_MSG_OBJ object.

Use a Cert-C function to view or modify information in this object. Do not assume that the PKI_STATUS_INFO_OBJ object points to any specific information. Some examples of the functions that Cert-C provides to work with a PKI status-information object are listed in the following table.

Function Description
C_CreatePKIStatusInfoObject() Creates and initializes a PKI status-information object.
C_DestroyPKIStatusInfoObject() Destroys the PKI status-information object and frees any memory associated with it.
C_SetPKIFailInfo() Sets additional information about failure cases in a PKI_STATUS_INFO_OBJ or a PKI_ERROR_MSG_OBJ.
C_SetPKIFailInfoAux() Sets the PKI service-provider-specific failure code in a PKI_STATUS_INFO_OBJ or a PKI_ERROR_MSG_OBJ.
C_SetPKIStatus() Sets the overall PKI status in a PKI_STATUS_INFO_OBJ or a PKI_ERROR_MSG_OBJ.
C_SetPKIStatusString() Sets a list of NUL-terminated text strings, which represent the status value, in a PKI_STATUS_INFO_OBJ or a PKI_ERROR_MSG_OBJ. This text is displayed to a user.
C_GetPKIFailInfo() Gets additional information about failure cases from a PKI_STATUS_INFO_OBJ or a PKI_ERROR_MSG_OBJ.
C_GetPKIFailInfoAux() Gets the PKI service-provider-specific failure code from a PKI_STATUS_INFO_OBJ or a PKI_ERROR_MSG_OBJ.
C_GetPKIStatus() Gets the overall PKI status from a PKI_STATUS_INFO_OBJ or a PKI_ERROR_MSG_OBJ.
C_GetPKIStatusString() Gets a list of NUL-terminated text strings, which represent the status value, from a PKI_STATUS_INFO_OBJ or a PKI_ERROR_MSG_OBJ. This text is displayed to a user.

Function Documentation

int C_CreatePKIStatusInfoObject (  CERTC_CTX    ctx,
PKI_STATUS_INFO_OBJ *    pPkiStatusInfoObj
)  ;
 

Creates and initializes a PKI status info Object.

Parameters:
ctx This input parameter is the Cert-C context.
pPkiStatusInfoObj This input/output parameter is the PKI status info object.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

void C_DestroyPKIStatusInfoObject (  PKI_STATUS_INFO_OBJ *    pPkiStatusInfoObj )  ;
 

Destroys a PKI_STATUS_INFO_OBJ and frees all memory used by it.

Parameters:
pPkiStatusInfoObj This input/output parameter is the PKI status info object.
Returns:
None.

int C_GetPKIFailInfo (  POINTER    pkiObj,
unsigned int *    pPkiFailInfo
)  ;
 

Gets additional information about failure cases from a PKI_STATUS_INFO_OBJ or a PKI_ERROR_MSG_OBJ.

Parameters:
pkiObj This input/output parameter is a PKI_STATUS_INFO_OBJ or a PKI_ERROR_MSG_OBJ.
pPkiFailInfo This output parameter is the PKI Status, one of the PKI_STATUS_* values defined in the table below:

PKI Failure Info Flag Description
PKI_FAIL_BAD_ALG The algorithm identifier is unrecognized or unsupported.
PKI_FAIL_BAD_MESSAGE_CHECK The integrity check failed (for example, the signature did not verify).
PKI_FAIL_BAD_REQUEST The transaction is not permitted or supported.
PKI_FAIL_BAD_TIME The message time was not sufficiently close to the system time as defined by local policy.
PKI_FAIL_BAD_CERT_ID No certificate could be found matching the provided criteria.
PKI_FAIL_BAD_DATA_FORMAT The data submitted has the wrong format.
PKI_FAIL_WRONG_AUTHORITY The authority indicated in the request is different from the one creating the response message.
PKI_FAIL_INCORRECT_DATA The requester's data is incorrect.
PKI_FAIL_MISSING_TIMESTAMP When the timestamp is missing but should be there (by policy).
PKI_FAIL_BAD_POP The proof-of-possession failed.
PKI_FAIL_SERVER_ERROR The requester was unable to contact the transaction end-point.
PKI_FAIL_REMOTE_SERVER_ERROR A back-end server or process behind the transaction end-point failed.
PKI_FAIL_CERT_REVOKED The certificate has already been revoked.
PKI_FAIL_CERT_CONFIRMED The certificate has already been confirmed.
PKI_FAIL_WRONG_INTEGRITY Invalid integrity, password based instead of signature or vice versa.
PKI_FAIL_BAD_RECIPIENT_NONCE Invalid recipient nonce, either missing or wrong value.
PKI_FAIL_TIME_NOT_AVALIABLE The TSA's time source is not available.
PKI_FAIL_UNACCEPTED_POLICY The requested TSA policy is not supported by the TSA.
PKI_FAIL_UNACCEPTED_EXTENSION The requested extension is not supported by the TSA.
PKI_FAIL_ADD_INFO_NOT_AVAILABLE The additional information requested could not be understood or is not available.
PKI_FAIL_BAD_SENDER_NONCE Invalid sender nonce, either missing or wrong size.
PKI_FAIL_BAD_CERT_TEMPLATE Invalid certificate template or missing mandatory information.
PKI_FAIL_SIGNER_NOT_TRUSTED The signer of the message is unknown or not trusted.
PKI_FAIL_TRANSACTION_ID_IN_USE The transaction identifier is already in use.
PKI_FAIL_UNSUPPORTED_VERSION The version of the message is not supported.
PKI_FAIL_NOT_AUTHORIZED The sender was not authorized to make the preceding request or perform the preceding action.
PKI_FAIL_SYSTEM_UNAVAIL The request cannot be handled due to system unavailability.
PKI_FAIL_SYSTEM_FAILURE The request cannot be handled due to system failure.
PKI_FAIL_DUPLICATE_CERTREQ The certificate cannot be issued because a duplicate certificate already exists.

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

int C_GetPKIFailInfoAux (  POINTER    pkiObj,
unsigned int *    pFailInfoAux
)  ;
 

Gets the PKI service-provider-specific failure code from a PKI_STATUS_INFO_OBJ or a PKI_ERROR_MSG_OBJ.

Parameters:
pkiObj This input/output parameter is a PKI_STATUS_INFO_OBJ or a PKI_ERROR_MSG_OBJ.
pFailInfoAux This output parameter is a detailed provider-specific failure code.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_GetPKIStatus (  POINTER    pkiObj,
unsigned int *    pPkiStatus
)  ;
 

Gets the overall PKI status from a PKI_STATUS_INFO_OBJ or a PKI_ERROR_MSG_OBJ.

Parameters:
pkiObj This input/output parameter is a PKI_STATUS_INFO_OBJ or a PKI_ERROR_MSG_OBJ.
pPkiStatus This output parameter is the PKI status and is one of the PKI_STATUS_* values defined in the table below:

PKI Status Value Description
PKI_STATUS_GRANTED The application was approved, exactly as requested.
PKI_STATUS_GRANTED_MODS The application was approved; however, the requester is responsible for ascertaining the differences.
PKI_STATUS_REJECTED The application was rejected; more information is usually found elsewhere in the message.
PKI_STATUS_WAITING The request has not yet been processed; expect further processing (in some cases, you must poll the recipient for updated status).
PKI_STATUS_WARNING_REVOCATION Warning that a revocation is imminent.
PKI_STATUS_REVOCATION Notification that a revocation has occurred.
PKI_STATUS_WARNING_KEY_UPDATE The requested key update was previously performed.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_GetPKIStatusString (  POINTER    pkiObj,
LIST_OBJ *    pStatusStringList
)  ;
 

Gets a list of NUL-terminated text strings, which represent the status value, from a PKI_STATUS_INFO_OBJ or a PKI_ERROR_MSG_OBJ. This text is displayed to a user.

Parameters:
pkiObj This input/output parameter is a PKI_STATUS_INFO_OBJ or a PKI_ERROR_MSG_OBJ.
pStatusStringList This output parameter is a list of UTF8 strings.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_SetPKIFailInfo (  POINTER    pkiObj,
unsigned int    pkiFailInfo
)  ;
 

Sets the additional information about failure cases in a PKI_STATUS_INFO_OBJ or a PKI_ERROR_MSG_OBJ.

Parameters:
pkiObj This input/output parameter is a PKI_STATUS_INFO_OBJ or a PKI_ERROR_MSG_OBJ.
pkiFailInfo This input parameter is the PKI Status and is one of the PKI_STATUS_* values defined in the table below:

PKI Failure Info Flag Description
PKI_FAIL_BAD_ALG The algorithm identifier is unrecognized or unsupported.
PKI_FAIL_BAD_MESSAGE_CHECK The integrity check failed (for example, the signature did not verify).
PKI_FAIL_BAD_REQUEST The transaction is not permitted or supported.
PKI_FAIL_BAD_TIME The message time was not sufficiently close to the system time as defined by local policy.
PKI_FAIL_BAD_CERT_ID No certificate could be found matching the provided criteria.
PKI_FAIL_BAD_DATA_FORMAT The data submitted has the wrong format.
PKI_FAIL_WRONG_AUTHORITY The authority indicated in the request is different from the one creating the response message.
PKI_FAIL_INCORRECT_DATA The requester's data is incorrect.
PKI_FAIL_MISSING_TIMESTAMP When the timestamp is missing but should be there (by policy).
PKI_FAIL_BAD_POP The proof-of-possession failed.
PKI_FAIL_SERVER_ERROR The requester was unable to contact the transaction end-point.
PKI_FAIL_REMOTE_SERVER_ERROR A back-end server or process behind the transaction end-point failed.
PKI_FAIL_CERT_REVOKED The certificate has already been revoked.
PKI_FAIL_CERT_CONFIRMED The certificate has already been confirmed.
PKI_FAIL_WRONG_INTEGRITY Invalid integrity, password based instead of signature or vice versa.
PKI_FAIL_BAD_RECIPIENT_NONCE Invalid recipient nonce, either missing or wrong value.
PKI_FAIL_TIME_NOT_AVALIABLE The TSA's time source is not available.
PKI_FAIL_UNACCEPTED_POLICY The requested TSA policy is not supported by the TSA.
PKI_FAIL_UNACCEPTED_EXTENSION The requested extension is not supported by the TSA.
PKI_FAIL_ADD_INFO_NOT_AVAILABLE The additional information requested could not be understood or is not available.
PKI_FAIL_BAD_SENDER_NONCE Invalid sender nonce, either missing or wrong size.
PKI_FAIL_BAD_CERT_TEMPLATE Invalid certificate template or missing mandatory information.
PKI_FAIL_SIGNER_NOT_TRUSTED The signer of the message is unknown or not trusted.
PKI_FAIL_TRANSACTION_ID_IN_USE The transaction identifier is already in use.
PKI_FAIL_UNSUPPORTED_VERSION The version of the message is not supported.
PKI_FAIL_NOT_AUTHORIZED The sender was not authorized to make the preceding request or perform the preceding action.
PKI_FAIL_SYSTEM_UNAVAIL The request cannot be handled due to system unavailability.
PKI_FAIL_SYSTEM_FAILURE The request cannot be handled due to system failure.
PKI_FAIL_DUPLICATE_CERTREQ The certificate cannot be issued because a duplicate certificate already exists.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_SetPKIFailInfoAux (  POINTER    pkiObj,
unsigned int    failInfoAux
)  ;
 

Sets the PKI service-provider-specific failure code in a PKI_STATUS_INFO_OBJ or a PKI_ERROR_MSG_OBJ.

Parameters:
pkiObj This input/output parameter is a PKI_STATUS_INFO_OBJ or a PKI_ERROR_MSG_OBJ.
failInfoAux This input parameter is a detailed provider-specific failure code.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_SetPKIStatus (  POINTER    pkiObj,
unsigned int    pkiStatus
)  ;
 

Sets the overall PKI status in a PKI_STATUS_INFO_OBJ or a PKI_ERROR_MSG_OBJ.

Parameters:
pkiObj This input/output parameter is a PKI_STATUS_INFO_OBJ or a PKI_ERROR_MSG_OBJ.
pkiStatus This input parameter is the PKI status, one of the PKI_STATUS_* values defined in the table below:

PKI Status Value Description
PKI_STATUS_GRANTED The application was approved, exactly as requested.
PKI_STATUS_GRANTED_MODS The application was approved; however, the requester is responsible for ascertaining the differences.
PKI_STATUS_REJECTED The application was rejected; more information is usually found elsewhere in the message.
PKI_STATUS_WAITING The request has not yet been processed; expect further processing (in some cases, you must poll the recipient for updated status).
PKI_STATUS_WARNING_REVOCATION Warning that a revocation is imminent.
PKI_STATUS_REVOCATION Notification that a revocation has occurred.
PKI_STATUS_WARNING_KEY_UPDATE The requested key update was previously performed.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_SetPKIStatusString (  POINTER    pkiObj,
LIST_OBJ    statusStringList
)  ;
 

Sets the PKI status string in a PKI_STATUS_INFO_OBJ or a PKI_ERROR_MSG_OBJ.

Parameters:
pkiObj This input/output parameter is a PKI_STATUS_INFO_OBJ or a PKI_ERROR_MSG_OBJ.
statusStringList This input parameter is a list of UTF8 strings.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.


RSA BSAFE® Cert-C 2.7 API Reference