CertRes

NAME: CertRes - SET CertRes message data structures and routines

SYNOPSIS

#include <set_msg.h>

typedef struct CertRes_ {
    asn1set__MessageWrapper         messageWrapper;
    asn1set__CertResData            certResData;
    cert_identity                   caSignatureCID;
    asn__octet_string               panSecret;

    asn__any                        signatureCertificate;
    asn__any                        keyExchangeCertificate;

    asn1set__BackKeyData            caBackKeyData;

#define                             CertRes__signatureCertificate        0
#define                             CertRes__keyExchangeCertificate      1
#define                             CertRes__caBackKeyData               2
    UCHAR                           _present[1];
} *CertRes;

CertRes safe_cast_CertRes(msg)
    set_msg            msg;             /* IN */

DESCRIPTION: CertRes contains the data from a SET CertRes message in native C form. See 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.
CertRes message objects of type set_msg may be cast to type CertRes using the safe_cast_CertRes() 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
 *    certResData.rrpid
 *    certResData.lid_EE
 *    certResData.chall_EE3
 *    certResData.lid_CA (optional)
 *    certResData.nonceCCA (optional)
 *    caBackKeyData (optional)
 *    panSecret (for cardholder requests)
 *    caSignatureCID

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

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

 *    certResData.certStatus
 *    signatureCertificate (optional)
 *    keyExchangeCertificate (optional)

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

 *    certResData.certThumbs

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

CACHING

Cardholder, Merchant, Payment Gateway

      STATE_CARDEXPIRY               get
      STATE_CARDSECRET               get
      STATE_CERTINQREQ_RRPID         get
      STATE_CERTREQ_RRPID            get
      STATE_CHALL_EE                 get
      STATE_EE_SIGNATURE_DN          get
      STATE_LOCALID_CA               put
      STATE_PAN                      get
      STATE_PUBLICKEYE               get
      STATE_PUBLICKEYS               get
      STATE_REQUESTTYPE              get

Certification Authority

      STATE_BACKKEYDATA              get
      STATE_CARDSECRET               get
      STATE_CA_SIGID                 get
      STATE_CERTINQREQ_RRPID         get
      STATE_CERTREQ_RRPID            get
      STATE_CHALL_EE                 get
      STATE_LOCALID_CA               get
      STATE_LOCALID_EE               get
      STATE_REQUESTTYPE              get

RETURN VALUES: On success, safe_cast_CertRes() returns a pointer to an CertRes data structure. Objects of type set_msg that were not created with message type asn1set__Message__certRes will cause safe_cast_CertRes() to fail. On failure, safe_cast_CertRes() 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__certRes;
    status = make_set_msg(response, app_ctx, &msg_cache[0], msg_type);
    assert(status == NO_ERROR);

    certRes = safe_cast_CertRes(response);
    assert(certRes != 0);

    /* signatureCertificate is optional */
    certRes->signatureCertificate.length = new_sig_cert.length;
    certRes->signatureCertificate.object = new_sig_cert.object;
    SET_PRESENT(*certRes, CertRes__signatureCertificate);

    certRes->certResData.certStatus.certStatusCode = asn1set__CertStatusCode__requestComplete;

    /* eeMessage is optional */
    certRes->certResData.certStatus.eeMessage._choice =
                                asn1set__EEMessage__visibleString;
    certRes->certResData.certStatus.eeMessage.visibleString = "Thank you.";
    SET_PRESENT(certRes->certResData, asn1set__CertStatus__eeMessage);

    /* ... */

    status = send_set_msg(response, 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.