SETREF supports both sending and receiving SET messages. Each of those operations involves several distinct steps, as described below. Before a SET message can be sent or received however, the SETREF runtime environment must be initialized.
Initializing SETREF runtime environment involves:
log_ctx)set_app_ctx)alloc_ctx)io_ctx)Note, in SETREF, a context is analagous to an object in object-oriented programming.
Whenever contexts must be created in a specific order, SETREF enforces that ordering by making the
first context to be created a parameter to the second. For example, since create_set_app_ctx() takes the
log_ctx as an input parameter, the log_ctx must be created first. Other than that, contexts can be created
in any order.
Conversely, the ordering for deleting contexts is implied, rather than enforced by the SETREF API. The rule
is straightforward, absolute, and probably familiar: if context A must be created before context B can be
created, then context B must be deleted before context A can be deleted. Given this rule, for example, the
set_app_ctx must be deleted before the log_ctx can be deleted.
Note, responsibility for deleting the context is placed on whoever created
the context.
When the application is receiving a message, data is first read from the input stream and parsed to determine the message type and possibly to obtain preliminary message identifiers. Next, the message is decoded and verified.
Whether a SET message is being sent or received, the first step is to create an empty SET message object
(set_msg) by calling create_set_msg() . When this message object is created, a memory-allocation heap
is associated with it. Whenever SETREF allocates memory for data in this object, it uses the associated
heap. The benefit of using a supplied heap for memory allocation is that the programmer is freed from having
to keep track of pointers and all of the memory allocated by SETREF can be deallocated with a single call
to delete the heap (AC_delete()).
After the empty message object has been created, the application is ready to receive a SET message from the
input stream by calling receive_set_msg(). This function does little more than read and parse the SET message wrapper.
As a result of calling this function, the application is given the message's type.
The next step is to decode and decrypt the message by calling decode_set_msg(). This function performs
cryptographic verification of the message, but it does not verify the SET protocol.
There is a subtle difference between these two types of verification.
Cryptographic verification consists only of transforming the message using the cryptographic operators that
are spelled out in the SET specification (such as Enc(), S(), and DD()). Protocol verification operates on
the contents of SET messages rather than their cryptographic wrappers. For example, validating digital
signatures occurs during cryptographic verification. Checking that XID is used consistently is a
protocol-verification step.
After a message has been decoded, the contents of the message are available and at least partially
authenticated,
which means that the application programmer should only partially trust
these contents (they should be considered hints).
Using the transaction identification information that is contained in each SET message, the
application locates the transaction-specific message cache (cache_ctx). The message cache allows SETREF
to maintain transaction state through the course of a SET transaction.
If the cache_ctx implementation provided with SETREF
is being used, the message cache is opened
with a call to create_cache_ctx_db().
Using the transaction state provided by the application-supplied cache_ctx, verify_set_msg() is called
to perform SET protocol verification. After the final verification checks have been performed and have all been passed,
verify_set_msg() may cache additional state in the cache_ctx.
When the application no longer needs the information contained in the message, it is deleted using
delete_set_msg(). The application can choose to postpone deletion in situations where the message
information may be used later, perhaps as part of the response message.
To send a message, SETREF constructs the message by inserting protocol-layer data. Next, the message is encrypted, encoded, and written to the output stream.
As when a message is being received, the first step is to create an empty SET message object (set_msg) by
calling create_set_msg(). An empty message object has no message type, nor does it contain data.
The second step in sending a message is to locate the relevant transaction-specific message cache
(cache_ctx). If the message being sent is the first in a sequence of messages, such as a PInitReq message,
a new cache is created. If the message is later in the sequence, you must reuse the cache that was used for
receiving the preceding message in the sequence.
SETREF uses this cache to accumulate protocol-layer data derived partly from application inputs and
partly from messages sent by other parties to the transaction. The function make_set_msg() is invoked to
insert the relevant protocol-layer data into the message. SETREF
avoids caching some of the information that it obtains from the application,
so the application may have to provide some pieces of information repeatedly.
After SETREF has inserted protocol-layer data into the message, the application is given an opportunity to insert application-layer data. The API Reference documents the required data items for each type of message, and the SET specification provides additional information describing the format and use of each of these data items.
A call to send_set_msg() completes the process by first encoding and encrypting the message and then
sending the result to the output stream. As a final step, SETREF may cache state in the
application-supplied cache_ctx.
As when a message is sent, the application deletes the message after it is finished with the message contents.
Copyright © 1996, 1997 Visa International Service Association and MasterCard International Incorporated
All Rights Reserved.