Theory of Operation

The Secure Electronic Transaction Draft Reference Implementation (SETREF) is a reference implementation of the SET protocol.

The SET Specification

The SET specification describes two related transaction security protocols, one for transmitting payment card transactions and the other for transmitting requests for public key certificates. In SET, this later protocol is referred to as registration. The SET specification is prerequisite reading material for the SETREF documentation.

From the perspective of the SET application programmer, SET applications can be thought to consist of three layers: the SET protocol layer, the solution layer, and an intermediary layer that integrates these two.

         ____________________
         |                  |
         |     solution     |
         |__________________|
         |                  |
         |   intermediary   |
         |__________________|
         |                  |
         |     protocol     |
         |__________________|

In many cases, the solution layer will be a legacy system that is oblivious to SET. The SET protocol layer, on the other hand, is the layer described in detail by the SET specification and implemented by SETREF. The intermediary layer consists of the SETREF API as well as the logic that connects this API to the solution layer. In theory, it should be possible to substitute another, similar protocol for SET by changing the intermediary layer.

The documentation included with SETREF focuses on the intermediary layer. The protocol layer, as was mentioned, is documented in the SET specification and implemented by SETREF.

SETREF Documentation

This Theory of Operation provides an introductory overview of SETREF. The Implementor's Guide describes each of the protocol-layer services, as well as other aspects of SETREF. For API details, please see the API Reference Guide.

Entities

Conceptually, there are four entities which participate in SET: the cardholder, the merchant, the payment gateway, and the certification authority (CA). The certification authority is unique in that this entity does not participate in the payment protocol. The series of messages that make up a transaction in one of the protocols is referred to as a flow.

The registration flow for the cardholder, merchant, and payment gateway consists of obtaining public key certificates from a certification authority. The purpose of these certificates is to state, on the authority of the CA, that the entity identified in the certificate is the possessor of the public/private keypair associated with the certificate. SET security is based on entities knowing the identity of the entities they are communicating with.

The cardholder participates in the payment protocol by asking to buy and by receiving the status of this request. The merchant is concerned not only with selling to the cardholder, but also with obtaining payment from the payment gateway. The payment gateway deals directly only with the merchant, either in authorizing potential payments or in processing actual payments. All gateway communication with the cardholder is tunneled through the merchant.

Applications

Conceptually, the SET protocol involves seven applications: a payment application for each the cardholder, merchant, and payment gateway, and a registration application for these three entities in addition to the certification authority.

Architecture

SETREF has the following modular architecture, which is organized into a number of layers:


         .....................................................
         :                                                   :
         :                [application/user]                 :  
         :___________________________________________________:
         |                                                   |
         |      set_msg                                      |
         |                           ________________________|
         |                           |         |             |
         |                           |   ops   | setref_util |
         |                           |_________|_____________|
         |                           |                       |
         |                           |        setcert        |
         |                           |_______________________|
         |                           |                       |
         |                           |         pkcs7         |
         |                           |_______________________|
         |                           |         |  |          |
         |                           |  certs  |  |   glue   |
         |___________________________|_________|  |__________|
         |             |             |         |  :          :
         |  cache_ctx  |   log_ctx   |   kdb   |  :  crypto  :
         |_____________|_____________|_________|  :..........:
         |                  |                  | 
         |       asn1       |      store       |
         |__________________|__________________|
         |                  |                  |
         |       util       |       a2c        |
         |__________________|__________________|
         |                  |                  | 
         |    alloc_ctx     |      io_ctx      |
         |__________________|__________________|
         |                                     |
         |              error_ctx              |
         |_____________________________________|

Higher layers rely on the services provided by lower layers, while lower layers are oblivious to the higher layers.

From bottom to top, a short description of each module is provided below.

crypto: The crypto module, which is not part of SETREF, implements the fundamental cryptographic algorithms employed by SET--for instance DES and SHA-1.
error_ctx: SETREF uses specially-formatted error return values which provide a per-module error numbering scheme. In certain cases, an error_ctx passed in as a parameter permits error information, beyond the numeric return value, to be obtained by the application programmer. The error_ctx module also provides functions useful to the programmer for logging errors and for obtaining textual descriptions of error return values.
alloc_ctx: An alloc_ctx is a memory allocation abstraction based on the standard malloc allocator package. SETREF uses application programmer-supplied heaps to allocate any memory that is passed back to the application programmer.
io_ctx: Most I/O in SETREF is performed using the io_ctx I/O abstraction. The interface for this module uses a subset of the interface defined by the standard stdio I/O package. Two sample io_ctx implementations are provided with SETREF: io_ctx_stdio, which is implemented using the stdio package, and io_ctx_memio, which keeps data in-core.
util: The util module provides generic utility functions to SETREF and to the application programmer. Many applications will already have some or all of these functions.
a2c: SET messages are described using ASN.1 and encoded using DER. SETREF includes a2c, an ASN.1/DER processing runtime that is used by most of SETREF. This runtime may at times be used by the application programmer, for instance for decoding X.509 Distinguished Names.
asn1: The asn1 module supplies the SET data definitions (x509.h, x509_useful.h, setpkcs7.h, setpkcs7_useful.h, pkcs8.h, pkcs9.h, and asn1set.h) used by SETREF, and the DER encoding information used by the ASN.1/DER runtime. This information is generated through automatic means from the ASN.1 supplied in the SET specification.
The application programmer uses the data definitions as the fundamental SET datatypes. The DER encoding information (which is contained in x509.c, x509_useful.c, pkcs7.c, pkcs7_useful.c, pkcs8.c, pkcs9.c, and asn1set.c ) should be ignored by the application programmer as it is only meaningful to the ASN.1/DER runtime.
store: A simple caching database is provided, although the application programmer is unlikely to ever use it directly. Sample implementations of a log_ctx and cache_ctx are built on top of this database.
cache_ctx: A cache abstraction is used to carry transaction-specific data between messages and to hold persistent state for the life of a transaction. The application programmer will be expected at times to put information into a cache. Documentation for each type of SET message enumerates what information, if any, the application programmer is expected to put into the transaction-specific cache. Although SETREF provides an example cache_ctx which uses a simple file-based database, it is expected that application programmers will supply cache_ctx implementations that support local implementation requirements rather than using the example implementation provided with SETREF.
log_ctx: The log abstraction is used to retain per-message information, for the most part the RRPID and/or XID of messages that have been processed. This information is used primarily to detect repeated/replayed messages.
SETREF expects there to be a single, global log file which the user manages. Although SETREF provides an example log_ctx which uses a simple file-based database, it is expected that application programmers will supply implementations for log_ctx that support local implementation requirements rather than using the example implementation provided with SETREF.
kdb: The kdb module implements a keying material database. The application programmer will never access this module directly.
certs: The certs module also implements generic X.509 certificate processing. The application programmer will never access this module directly.
glue: The glue module provides a primitive, SET-specific crypto abstraction. The application programmer will never access this module directly.
pkcs7: The pkcs7 module provides an implementation of the PKCS-7 datatypes DigestedData, EnvelopedData, and SignedData. The application programmer will never access this module directly.
setcert: The setcert module implements SET-specific X.509 certificate processing. The application programmer will never access this module directly.
ops: The SET protocol defines a number of primitive cryptographic operators, for instance S() for the signature operation and E() for the public-key encryption operation. Nearly all cryptographic functionality in SET is accessed using these primitive operators. The application programmer will never access this module directly.
setref_util: The setref_util module implements generic SETREF utility functions. The application programmer will never access this module directly.
set_msg: set_msg is the module that the application programmer will most commonly use. This module organizes and performs all SET-specific protocol processing and provides the interface for sending and receiving SET messages.