CertReq

NAME: CertReq - SET CertReq message data structures and routines

SYNOPSIS

#include <set_msg.h>

typedef struct CertReq_ {
    asn1set__MessageWrapper    messageWrapper;
    asn1set__CertReqData       certReqData;
    cert_identity              caKeyExchangeCID;
    pkcs8__PrivateKeyInfo      eeSignatureKey;
    cert_identity              eeSignatureCID;

    /* not required */
    asn1set__AcctInfo          acctInfo;

#define                        CertReq__eeSignatureCID       0
#define                        CertReq__eeSignatureKey      1
#define                        CertReq__acctInfo            2
    UCHAR                      _present[1];
} *CertReq;

CertReq safe_cast_CertReq(msg)
    set_msg            msg;             /* IN */

DESCRIPTION: CertReq contains the data from a SET CertReq message in native C form. ee the asn_types.h and asn1set.h header files for the declarations of the various types. See the SET specification for a description of individual fields.
CertReq message objects of type set_msg may be cast to type CertReq using the safe_cast_CertReq() routine.

FIELDS

A call to make_set_msg() results in the protocol layer filling in the following fields:

 *    messageWrapper.messageHeader.version
 *    messageWrapper.messageHeader.date
 *    messageWrapper.messageHeader.rrPID
 *    messageWrapper.messageHeader.swIdent
 *    messageWrapper.message._choice
 *    certReqData.rrpid
 *    certReqData.requestType
 *    certReqData.lid_EE
 *    certReqData.chall_EE3
 *    certReqData.lid_CA
 *    certReqData.chall_CA
 *    certReqData.caBackKeyData (optional)
 *    acctInfo.u.panData0.cardNonce (optional)
 *    acctInfo.u.panData0.exNonce or acctInfo.u.acctData.exNonce (optional)
 *    caKeyExchangeCID

It is unwise for users to change the contents of the fields filled in by the protocol layer.

After calling make_set_msg(), software must fill in the following required fields:

 *    certReqData.regFormID
 *    certReqData.regForm
 *    publicKeySorE

If the request type requires a certificate-backed signature, then software must fill in the following required fields:

 *    eeSignatureCID

If the request is for a signature cert, then software must fill in the following required fields:

 *    eeSignatureKey

Cardholder software must also complete the following required fields:

 *    acctInfo.u.panData0.pan
 *    acctInfo.u.panData0.cardExpiry

Non-required fields may be left empty at the discretion of the application, subject to any business constraints placed on the application.

OPTIONAL FIELDS

The _present element is used for specifying the presence or absence of optional elements. The macros SET_PRESENT(), IS_PRESENT(), SET_ABSENT(), and IS_ABSENT() are used to specify or query the status of optional elements. See documentation on ASN.1/DER runtime types for additional information.

When sending a message, the presence or absence must be set (using SET_PRESENT() or SET_ABSENT()) prior to calling send_set_msg(). It is usually unnecessary to invoke the SET_ABSENT() macro because absent is the default setting for blank messages.

When receiving a message, presence or absence can be determined (using the IS_PRESENT() or IS_ABSENT() macro) after calling decode_set_msg().

CertReq__eeSignatureCID: Software indicates to SETREF that the CertReq message is to be signed using a key pair backed by an existed cert by setting CertReq__eeSignatureCID to present.
SETREF indicates to CA software that the CertReq message was signed using a key pair backed by an existing cert by setting CertReq__eeSignatureCID to present.
CertReq__eeSignatureKey: Software indicates to SETREF that the CertReq message is to be signed using a key pair for which a cert is being requested by setting CertReq__eeSignatureKey to present.
SETREF indicates to CA software that the CertReq message was signed using a key pair for which a cert is being requested by setting CertReq__eeSignatureKey to present.

CACHING

Cardholder, Merchant, Payment Gateway

      STATE_CAETHUMB                 get
      STATE_CARDEXPIRY               put
      STATE_CARDSECRET               put
      STATE_CERTREQ_RRPID            put
      STATE_CHALL_CA                 get
      STATE_CHALL_EE                 put
      STATE_EE_SIGNATURE_DN          put
      STATE_LOCALID_CA               get
      STATE_LOCALID_EE               get
      STATE_PAN                      put
      STATE_PUBLICKEYE               put
      STATE_PUBLICKEYS               put
      STATE_REQUESTTYPE              get

Certification Authority

      STATE_BACKKEYDATA              put
      STATE_CARDSECRET               put
      STATE_CA_SIGID                 put
      STATE_CERTREQ_RRPID            put
      STATE_CHALL_CA                 get
      STATE_CHALL_EE                 put
      STATE_LOCALID_EE               put
      STATE_PUBLICKEYS               put
      STATE_REQUESTTYPE              put

RETURN VALUES: On success, safe_cast_CertReq() returns a pointer to an CertReq data structure. Objects of type set_msg that were not created with message type asn1set__Message__certReq will cause safe_cast_CertReq() to fail. On failure, safe_cast_CertReq() returns a null pointer.

SEE ALSO: set_msg

NOTES: There is a difference between non-required and optional. Non-required fields may be omitted according to the SET protocol. Optional fields may be omitted according to ASN.1 encoding rules. In some messages, a field may be optional according to ASN.1, but still required by the SET protocol. In these cases, the application must fill in these fields.
Optional fields that are filled in require an application of the SET_PRESENT() macro. See documentation on ASN.1/DER runtime types for additional information.

EXAMPLE

A more complete, explicated example is provided in the Implementor's Guide.

    msg_type = asn1set__Message__certReq;
    status = make_set_msg(request, app_ctx, &msg_cache[0], msg_type);
    assert(status == NO_ERROR);

    certReq = safe_cast_CertReq(request);
    assert(certReq != 0);
   
    /* ... */

    status = send_set_msg(request, app_ctx, &msg_cache[0], outstream);
    assert(status == NO_ERROR);

BUGS: This document describes a beta implementation. The information contained in this document may be incomplete and is subject to change.