RSA BSAFE Cert-C
API Reference

PKI_MSG_FIELDS Struct Reference

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

Note that not all of the fields of the structure are used by every PKI service provider or every PKI message type. The application can indicate that specific fields are to be ignored when it sets the value of a PKI_MSG_OBJ, and the PKI service provider can indicate that specific fields are to be uninitialized when the application gets the value of a PKI_MSG_OBJ.

Use PKI_MSG_FIELDS with functions such as C_SetPKIMsgFields() or C_GetPKIMsgFields().

Using Individual Data Structures

Cert-C 2.0 provided individual data structures and functions for sender-specific information and recipient-specific information:

The PKI_SENDER_INFO structure is used with the C_SetPKIMsgSender() and C_GetPKIMsgSender() functions to set and get sender-specific information.
The PKI_RECIPIENT_INFO structure is used with the C_SetPKIMsgRecipient() and C_GetPKIMsgRecipient() functions to set and get recipient-specific information.

In contrast, the PKI_MSG_FIELDS structure contains multiple PKI message fields, and is manipulated with generic functions, C_SetPKIMsgFields() and C_GetPKIMsgFields(). Begin using the sender-specific and recipient-specific structures and functions in all new applications. The use of the sender and recipient fields of the PKI_MSG_FIELDS structure was deprecated in Cert-C 2.0.

When using a Certificate Management Protocol (CMP) PKI service provider, use the sender-specific and recipient-specific structures and functions.
Currently, for existing applications, use either the specific or the generic structures and functions.

In Cert-C 2.5, new set and get APIs are introduced to retrieve and update the new PKI objects directly. These are the recommended method for working with fields in this structure. PKI_MSG_FIELDS, C_SetPKIMsgFields() and C_GetPKIMsgFields() are deprecated in this release, and will be removed from its successor.

Backward-Compatibility

The following convention allows applications that use Cert-C 2.5 API functions to operate compatibly with applications that use the Cert-C 1.0 API functions, to the extent that this is possible.

When setting and getting sender or recipient information that is compatible with the Cert-C 1.0 data structures, even when setting and getting it with the new sender- specific or recipient-specific functions, do not set the PKI_MSGFLAGS_IGNORE_SENDER or PKI_MSGFLAGS_IGNORE_RECIPIENT flags.
However, if any portion of the sender or recipient data that has been set with the new sender-specific and recipient-specific functions is not compatible with the Cert-C 1.0 data structures, set the applicable *_IGNORE_* flags to indicate that the sender or recipient field is to be ignored by Cert-C.



Data Fields 


flags 
An unsigned int value that specifies the type of message protection to be performed and the fields in the PKI_MSG_FIELDS structure that are to be ignored by Cert-C. Individual flags can be combined by 'OR'ing them together. Note that you can set only one of the PKI_MSGFLAGS_WRAP_* flags. 



 PKI Message Flag Description 
PKI_MSGFLAGS_WRAP_NONE This flag value indicates that the message is not cryptographically protected. 
PKI_MSGFLAGS_WRAP_SIGN This flag value indicates that the message is signed by the sender. 
PKI_MSGFLAGS_WRAP_ENVELOPE  This flag value indicates that the message is encrypted for the recipient. 
PKI_MSGFLAGS_WRAP_ SIGN_THEN_ENVELOPE This flag indicates that the message is first signed by the sender and then encrypted for the recipient. (The signature is included in the encrypted content.) 
PKI_MSGFLAGS_WRAP_ ENVELOPE_THEN_SIGN This flag indicates that the message is first encrypted for the recipient and then the encrypted message is signed by the sender. 
PKI_MSGFLAGS_WRAP_MASK This constant can be used to separate the WRAP flag value from the rest of the flags (such as for use in a C switch statement). The mask should be applied to the flags using the bitwise-and operator. 
PKI_MSGFLAGS_IGNORE_SENDER The sender field value is undefined. 
PKI_MSGFLAGS_IGNORE_RECIPIENT  The recipient field value is undefined. 
PKI_MSGFLAGS_IGNORE_MSGTYPE  The msgType field value is undefined. 
PKI_MSGFLAGS_IGNORE_PROTOCOLVERSION< /code> The version field value is undefined. 
PKI_MSGFLAGS_IGNORE_MSGTIME  The messageTime field value is undefined. 
PKI_MSGFLAGS_IGNORE_TRANSACTIONID</c ode> The transactionID field value is undefined. 
PKI_MSGFLAGS_IGNORE_FREETEXT  The freeText field value is undefined. 
PKI_MSGFLAGS_IGNORE_GENERALINFO  The generalInfo field value is undefined. 
PKI_MSGFLAGS_IGNORE_EXTRACERTS  The extraCerts field value is undefined. 
PKI_MSGFLAGS_IGNORE_EXTRACRLS  The extraCRLs field value is undefined. 
 



 
sender 
A SIGNER_INFO structure that identifies the message sender. If the message was signed, it may also contain information about the message signature algorithms and attributes accompanying the signature.
recipient 
A PKI_RECIPIENT structure that identifies the intended message recipient. It may also contain information about message encryption algorithms and keys.
msgType 
An unsigned int value that specifies the type of PKI message contained in the corresponding PKI_MSG_OBJ. The msgType field in a PKI_MSG_FIELDS structure can have any one of the following values: 



 PKI Message Type Description 
PKI_MSGTYPE_UNKNOWN The type of PKI message contained in the PKI_MSG_OBJ is unknown. This is the state of the PKI message object when it is first created. 
PKI_MSGTYPE_CERTREQ The PKI_MSG_OBJ contains a certification request. 
PKI_MSGTYPE_CERTRESP The PKI_MSG_OBJ contains a certification response. 
PKI_REVOKE_REQ The PKI_MSG_OBJ contains a revocation request. 
PKI_REVOKE_RESP The PKI_MSG_OBJ contains a revocation response. 
PKI_KEYUPDATE_REQ The PKI_MSG_OBJ contains a key update request. 
PKI_KEYUPDATE_RESP The PKI_MSG_OBJ contains a key update response. 
PKI_ERROR_MSG The PKI_MSG_OBJ contains an error. 
PKI_MSGTYPE_CERT_CONF_REQ The PKI_MSG_OBJ contains a confirmation request. 
PKI_MSGTYPE_CERT_CONF_RESP The PKI_MSG_OBJ contains a confirmation response. 
 



 
version 
An unsigned int value that specifies the PKI protocol-specific version number associated with the encoded message format. Generally the application is not required to set this field. It is usually set by the PKI service provider when it encodes or decodes the message.
messageTime 
A GENERALIZED_TIME structure that contains the time when the message was sent. Generally the application is not required to set this field. It is usually set by the PKI service provider when it encodes or decodes the message.
transactionID 
An ITEM structure that points to the transaction identifier used to associate request messages with the corresponding response messages. When formulating a request message, the application is not required to set this field. It is usually set by the PKI service provider when it encodes the message. When formulating a response message, the application generally copies this field from the corresponding request message.
freeText 
A LIST_OBJ object that contains a list of text strings that contain context-specific information to accompany the message. Each entry in the list is a pointer to an ITEM, where the ITEM specifies the string. The text is displayed to a user and can contain instructions or other information for that person. Usually multiple text strings are present only when the same text has been provided in multiple (human) languages, with each individual string containing the text in a single language. Each string should consist of UTF8 characters, with the language tag, if any, specified at the beginning of the string. (In the absence of a language tag, the sender and receiver should have some out-of- band agreement on the language of the string.)
generalInfo 
An ATTRIBUTES_OBJ object that contains a set of messaging attributes used to convey context-specific information.
extraCerts 
A LIST_OBJ object that contains a list of CERT_OBJ  objects that may be useful for the recipient. For example, this can be used by a CA or RA to present an end entity with certificates that it needs to verify its own new certificate (if, for example, the CA that issued the end entity's certificate is not a root CA for the end entity). Note that this field does not necessarily contain a certification path. If this is the case, the recipient may have to sort, select from, or otherwise process the extra certificates in order to use them.
extraCRLs 
A LIST_OBJ object that contains a list of CRL_OBJ objects that may be useful for the recipient. For example, this can be used by a CA or RA to present an end entity with the current CRLs that it needs to verify its own new certificate.

Deprecated:: This structure is deprecated in Cert-C 2.5. New set and get APIs are introduced to retrieve and update individual fields. PKI_MSG_FIELDS, C_SetPKIMsgFields() and C_GetPKIMsgFields() are deprecated in this release, and will be removed from its successor.

#include <pkimsg.h>

00603 typedef struct {
00604   unsigned int     flags;         /* wrap & PKI_MSGFLAGS_IGNORE_* flags      */
00605   SIGNER_INFO      sender;        /* identifies request initiator (EE/RA)    */
00606   PKI_RECIPIENT    recipient;     /* identifies request target    (RA/CA)    */
00607   unsigned int     msgType;       /* PKI message type (one of PKI_MSGTYPE_*) */
00608   unsigned int     version;       /* protocol version identifier             */
00609   GENERALIZED_TIME messageTime;   /* time of message production              */
00610   ITEM             transactionID; /* transaction identifier                  */
00611   LIST_OBJ         freeText;      /* list of UTF8 strings                    */
00612   ATTRIBUTES_OBJ   generalInfo;   /* context-specific info                   */
00613   LIST_OBJ         extraCerts;    /* list of CERT_OBJ                        */
00614   LIST_OBJ         extraCRLs;     /* list of CRL_OBJ                         */
00615 } PKI_MSG_FIELDS;

The documentation for this struct was generated from the following file:

pkimsg.h

RSA BSAFE^® Cert-C 2.7 API Reference