Connect to the Purdue Home Page

Purdue University

Identity and Access Management

The I2A2 External Protocol

Client host applications communicate with net daemon servants of the I2A2 data base managers (DBMs) via an external protocol after a connection has been established. The protocol uses ASCII text messages in a simple command-reply sequence -- i.e., the client sends a command ASCII message to the net daemon and it responds with a reply ASCII message.

That is always the sequence in which messages are exchanged with one exception. When a client host makes a connection to the net daemon, the connection itself is considered a command message, so the net daemon replies with a welcome reply message.

Definitions for the external protocol appear in the puidnetd.h header file. Typically they begin with PUIDNETD. Where possible the PUIDNETD symbol definition will be given in this documentation.

Message Format

The command and reply messages have the same format.

A command or reply begins with a single character. For a command it is the command character. For a reply it is the reply character. Command characters have symbol names in puidnetd.h beginning with PUID_NETD_CMD_; reply characters. with PUIDNETD_REPL_.

The command or reply may be followed by an optional field terminator character, an ASCII Vertical Tab (TAB, or VT, decimal 11). The field terminator will be represented in this documentation by its C language escape, "\t".  It's puidnetd.h symbol name is PUIDNETD_MSGTERM

The command or reply may be accompanied by data fields. Each field must begin with a field identifier character, be optionally followed by ASCII data characters, and be ended with a field terminator. puidnetd.h data field identifier symbol names begin with PUIDNETD_DATA. When binary information must be sent as field data, it must be encoded in base 64.

The command or reply line must end with at least an ASCII New Line character (NL, decimal 10). NL will be represented in this documentation by its C language escape, "\n".

The NL character may be optionally preceded by an ASCII Carriage Return character (CR, decimal 13). CR will be represented in this documentation by its C language escape, "\r". Since \r is commonly used in Windows messages, the I2A2 net daemons always include it in reply messages, right before the ending \n.

Sample Command-Reply Exchange

Here's a sample exchange of a command from a client host application to a net daemon and the net daemon's reply. In this example the client host application is looking up information about an alias and the net daemon returns the DBM's positive acknowledgement that includes information about the PUID.

Command:

l afoobar

l -- is the lookup command (PUIDNETD_CMD_LOOKUP).

-- terminates the command field (PUIDNETD_MSGTERM). (This is optional.)

a -- is the alias field identifier (PUIDNETD_DATA_AKA).

foobar -- is the alias of interest.

-- terminates the alias field (PUIDNETD_MSGTERM).

-- ends the message

Reply:

a NFoo Bar p123123457 afoobar

a -- is the positive acknowledgement (ACK) reply code (PUIDNETD_REPL_ACK).

-- terminates the reply field (PUIDNETD_MSGTERM). (This is optional.)

N -- is the common name field identifier (PUIDNETD_DATA_CNM).

Foo Bar -- is the common name.

-- terminates the canonical name field (PUIDNETD_MSGTERM).

p -- is the PUID field identifier (PUIDNETD_DATA_PUID).

123123457 -- is the PUID value.

-- terminates the PUID field (PUIDNETD_MSGTERM).

a -- is the alias field identifier (PUIDNETD_DATA_AKA).

foobar -- is the alias field value

-- terminates the alias field (PUIDNETD_MSGTERM).

-- ends the reply message.

Message Length

Individual messages are limited to 4,095 characters PUIDNETD_MAXMSGL in puidnetd.h).

Cautions

Here are some cautions the client host application developer should keep in mind about command and reply messages.

The bytes of a command or reply message need not arrive in one return from low-level system read calls like the UNIX read(2) or SSL_read(). Applications using these calls must acquire an input stream of characters until the message's terminating \n appears. When read(2) or SSL_read() is used, the application may also have to hold received characters that follow the \n and supply them as the beginning of the next message.

The sending of two \n characters is the same as the sending of two messages. The net daemon will read the first message, send a reply to it, then immediately read the second message, and send a reply to it. If the client host application doesn't realize it has sent two messages -- e.g., it has accidentally ended a message with two \n characters -- and sends a third message, it may find itself erroneously processing the net daemon's second reply as the reply to the third message. Thus it is very important when sending \n characters to match the messages they terminate to the corresponding reply messages.

Continuations

With one exception, the body of the message string before the ending \r\n or \n must always end with a \t. The one exception is when space in the message body is too short to contain the next field.

The message must have room for the continuation character (PUIDNETD_DATA_CONT in puidnetd.h) after the last field (instead of \t) and the ending \n or \r\n characters.

When a message ends with PUIDNETD_DATA_CONT, the next message is part of it and must begin with the PUIDNETD_CMD_CONT command character (defined in puidnetd.h) or a PUIDNETD_REPL_NAK reply character (see Exception below). The fields of the next message become part of the preceding one, continuing until a message ends with \t\r\n. The application must remember the "real" reply character that appeared in the first message of a continued sequence.

Exception In rare circumstances the sender of a continued message may not be able to complete it. In that case the sender will indicate the continuation failed and use the PUIDNETD_REPL_NAK reply character instead of PUIDNETD_CMD_CONT. The receiving application must be prepared to recognize the failure signal and replace the "real" reply character it previously remembered with PUID_REPL_NAK. The last reply message containing PUID_REPL_NAK will also contain an error explanation code in the PUIDNETD_DATA_ERRC field.

The I2A2 PUID external C library contains a function, puidnetd_unpk(3), that will do all the book work required to remember the real reply character and combine the fields of all parts of the message into one structure. Reading and recognizing the parts of the message is still the responsibility of the application; puidnetd_unpk(3) merely combines them in a usable form.

Libraries and Examples

The following libraries and examples are provided to assist the client host application developer in managing use of the I2A2 external protocol.

The PUID external C library contains functions for handling parts of the external protocol.

A C client access library, PUIDCL, written by Curtis Smith of the PACE Technical Group, is available for some UNIX and Windows systems.

Instructions for using I2A2 from an Apache Web Server may be found here.

Examples of accessing the I2A2 net daemons from Perl may be found here.

Feedback | Contact Purdue | Style Standards
Maintained by: IAMO Team

Purdue University, West Lafayette, IN 47907, (765) 494-4600
© 2010 - 2013 Purdue University | An equal access/equal opportunity university | Copyright Complaints
If you have trouble accessing this page because of a disability, please contact the CSC at itap@purdue.edu or (765) 494-4000.