My Project
Chapter 3 – Rxkad

Section 3.1: Introduction

The rxkad security module is offered as one of the built-in Rx authentication models. It is based on the Kerberos system developed by MIT's Project Athena. Readers wishing detailed information regarding Kerberos design and implementation are directed to [2]. This chapter is devoted to defining how Kerberos authentication services are made available as Rx components, and assumes the reader has some familiarity with Kerberos. Included are descriptions of how client-side and server-side Rx security objects (struct rx securityClass; see Section 5.3.1.1) implementing this protocol may be generated by an Rx application. Also, a description appears of the set of routines available in the associated struct rx securityOps structures, as covered in Section 5.3.1.2. It is strongly recommended that the reader become familiar with this section on struct rx securityOps before reading on.

Section 3.2: Definitions

An important set of definitions related to the rxkad security package is provided by the rxkad.h include file. Determined here are various values for ticket lifetimes, along with structures for encryption keys and Kerberos principals. Declarations for the two routines required to generate the different rxkad security objects also appear here. The two functions are named rxkad NewServerSecurityObject() and rxkad NewClientSecurityObject(). In addition, type field values, encryption levels, security index operations, and statistics structures may be found in this file.

Section 3.3: Exported Objects

To be usable as an Rx security module, the rxkad facility exports routines to create server-side and client-side security objects. The server authentication object is incorporated into the server code when calling rx NewService(). The client authentication object is incorporated into the client code every time a connection is established via rx NewConnection(). Also, in order to implement these security objects, the rxkad module must provide definitions for some subset of the generic security operations as defined in the appropriate struct rx securityOps variable.

Section 3.3.1: Server-Side Mechanisms

Section 3.3.1.1: Security Operations

The server side of the rxkad module fills in all but two of the possible routines associated with an Rx security object, as described in Section 5.3.1.2.
static struct rx_securityOps rxkad_server_ops = {
rxkad_Close,
rxkad_NewConnection,
rxkad_PreparePacket, /* Once per packet creation */
0, /* Send packet (once per retrans) */
rxkad_CheckAuthentication,
rxkad_CreateChallenge,
rxkad_GetChallenge,
0,
rxkad_CheckResponse, /* Check data packet */
rxkad_DestroyConnection,
rxkad_GetStats,
};
The rxkad service does not need to take any special action each time a packet belonging to a call in an rxkad Rx connection is physically transmitted. Thus, a routine is not supplied for the op SendPacket() function slot. Similarly, no preparatory work needs to be done previous to the reception of a response packet from a security challenge, so the op GetResponse() function slot is also empty.

Section 3.3.1.2: Security Object

The exported routine used to generate an rxkad-specific server-side security class object is named rxdad NewServerSecurityObject(). It is declared with four parameters, as follows:
struct rx_securityClass *
rxkad_NewServerSecurityObject(a_level, a_getKeyRockP, a_getKeyP, a_userOKP)
rxkad_level a_level; /* Minimum level */
char *a_getKeyRockP; /* Rock for get_key implementor */
int (*a_getKeyP)(); /* Passed kvno & addr(key) to fill */
int (*a_userOKP)(); /* Passed name, inst, cell => bool */
The first argument specifies the desired level of encryption, and may take on the following values (as defined in rxkad.h):
  • rxkad clear: Specifies that packets are to be sent entirely in the clear, without any encryption whatsoever.
  • rxkad auth: Specifies that packet sequence numbers are to be encrypted.
  • rxkad crypt: Specifies that the entire data packet is to be encrypted.
The second and third parameters represent, respectively, a pointer to a private data area, sometimes called a "rock", and a procedure reference that is called with the key version number accompanying the Kerberos ticket and returns a pointer to the server's decryption key. The fourth argument, if not null, is a pointer to a function that will be called for every new connection with the client's name, instance, and cell. This routine should return zero if the user is not acceptable to the server.

Section 3.3.2: Client-Side Mechanisms

Section 3.3.2.1: Security Operations

The client side of the rxkad module fills in relatively few of the routines associated with an Rx security object, as demonstrated below. The general Rx security object, of which this is an instance, is described in detail in Section 5.3.1.2.
static struct rx_securityOps rxkad_client_ops = {
rxkad_Close,
rxkad_NewConnection, /* Every new connection */
rxkad_PreparePacket, /* Once per packet creation */
0, /* Send packet (once per retrans) */
0,
0,
0,
rxkad_GetResponse, /* Respond to challenge packet */
0,
rxkad_CheckPacket, /* Check data packet */
rxkad_DestroyConnection,
rxkad_GetStats,
0,
0,
0,
};
As expected, routines are defined for use when someone destroys a security object (rxkad Close()) and when an Rx connection using the rxkad model creates a new connection (rxkad NewConnection()) or deletes an existing one (rxkad DestroyConnection()). Security-specific operations must also be performed in behalf of rxkad when packets are created (rxkad PreparePacket()) and received (rxkad CheckPacket()). finally, the client side of an rxkad security object must also be capable of constructing responses to security challenges from the server (rxkad GetResponse()) and be willing to reveal statistics on its own operation (rxkad GetStats()).

Section 3.3.2.2: Security Object

The exported routine used to generate an rxkad-specific client-side security class object is named rxkad NewClientSecurityObject(). It is declared with five parameters, specified below:
struct rx_securityClass * rxkad_NewClientSecurityObject(
a_level,
a_sessionKeyP,
a_kvno,
a_ticketLen,
a_ticketP
)
rxkad_level a_level;
struct ktc_encryptionKey *a_sessionKeyP;
long a_kvno;
int a_ticketLen;
char *a_ticketP;
The first parameter, a level, specifies the level of encryption desired for this security object, with legal choices being identical to those defined for the server-side security object described in Section 3.3.1.2. The second parameter, a sessionKeyP, provides the session key to use. The ktc encryptionKey structure is defined in the rxkad.h include file, and consists of an array of 8 characters. The third parameter, a kvno, provides the key version number associated with a sessionKeyP. The fourth argument, a ticketLen, communicates the length in bytes of the data stored in the fifth parameter, a ticketP, which points to the Kerberos ticket to use for the principal for which the security object will operate.