Connect to the Purdue Home Page

Purdue University

Identity and Access Management

Protocol Fields

Protocol fields contain data supplied to the net daemon, the DBM, or to the client host. Definitions about fields may be found in puidnetd.h. The symbol names begin with PUIDNETD. The protocol fields described here are common to all three DBMs. Fields and field records unique to the authentication DBM are described here.

Field Format

A field has three parts:

  • A field identifier - A single ASCII character (PUIDNETD_DATA_symbols)
  • Field data -- ASCII printable characters (base 64 encoding required for non-printable characters. Leading and trailing spaces are usually discarded, but see Leading and Trailing Space Removal.)
  • A field terminator -- a TAB, ASCII Vertical TAB, decimal value 11, C representation "\t", and symbol PUIDNETD_MSGTERM.

Leading and Trailing Space Removal

With the exception of message fields ('M' -- PUIDNETD_DATA_MSG), leading and trailing spaces are removed from field data.

Caution: removal of leading and trailing spaces can reduce a field that has only spaces to an empty field. I2A2 protocol handlers ignore empty fields. When the field is a lookup key -- an alias or a PUID, for example -- the removal of leading and trailing spaces from a key that contains only spaces means the key will be ignored. If it's the only key and a key is required, the net daemon or the DBM will complain about a missing key.

Examples

Here's an example of a field that contains the alias "foo". 'a' is the field identifier. It is followed immediately by the field data. The field data ends at the terminating TAB, represented here in the "\t" C language convention.

afoo

a -- the alias field identifier (PUIDNETD_DATA_AKA).

foo -- the field data, an alias.

-- the field terminator (PUIDNETD_MSGTERM),

What Fields Go Where?

Fields accompany commands and replies. Check the individual command descriptions for information on the fields that accompany their command and reply messages.

The Sequence Field

There is a private field reserved for client applications.  It is a sequence field that the client may supply in any request and the field will be returned in whatever reply is appropriate, ACK or NAK.

The client may use the value in the sequence field to connect its commands to the replies it receives from the net daemon. That allows client applications to send a block of commands with distinct sequence field values and connect the replies received to the commands by their sequence field values.

The only restriction on the sequence field is that its value must not contain control characters, including a TAB (' '). Hint: if it must contain control characters, consider encoding the value in base 64 notation.

Here's an example:

qMy-sequence 0001

Field Identifier List: Here are lists of all field identifiers used in the I2A2 external protocol, sorted by field identifier character, field description, and the symbol name from puidnetd.h

Continuation Field Identifier: When a message is too full to contain another field, the last field may be followed by the continuation field identifier, '+' (PUIDNETD_DATA_CONT). The continuation field must not be followed by a field terminating PUIDNETD_MSGTERM.

The next message must begin with a continuation command, '+' (PUIDNETD_CMD_CONT).

The last message ends without the continuation field identifier.

Here's an example of a continued authorizer DBM lookup command:

First Message:

l p18 +

Second Message (redundant and containing no useful information):

+p18 +

Last message, containing a PUIDNETD_DATA_EXP characteristics Boolean expression:

+p18 X0

Note how the PUID field is repeated in the messages. That's optional, but is a useful way to identify message parts.

In rare cases the sender of a continued message may encounter an error before sending its last part. To identify the error a last message is sent that begins with a PUIDNETD_REPL_NAK reply character instead of a PUIDNETD_CMD_CONT command character. The sender includes an error code field in the PUIDNETD_REPL_NAK message. If the sender of the previous example were to signal error number 123 after sending the first two messages, it would send this last message:

np18 e123

Field Records

Field records are used to allow field identifiers to be repeated inside a message without causing conflicts in their meaning. For example, the alias field identifier, PUIDNETD_DATA_AKA, might be used at the beginning of the message as a key, and subsequently might be used to identify a change to the alias. Here's an example, using a modify field, PUIDNETD_DATA_MDFY, in a modify command, PUIDNETD_CMD_MODIFY.

m afoobar q9876 Ya nfoobar1 Y

Where:

'm' -- is the modify command, PUIDNETD_CMD_MODIFY.

'a' -- is the alias lookup key in a PUIDNETD_DATA_AKA field

'q' -- is a private sequence number, 9876, in a PUIDNETD_DATA_SEQ field.

'Y' -- is the modify field identifier, PUIDNETD_DATA_MDFY, starting the modification field record.

'a' -- is a repeat of the alias field identifier, PUIDNETD_DATA_AKA, this time indicating what is to be modified by the modification field record.

'n' -- is the new value field identifier, PUIDNETD_BATA_NEW; "foobar1", the new alias.

'Y' -- is a repeat of PUIDNETD_DATA_MDFY to end the modification record.

Feedback | Contact Purdue
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.