I2A2 uses a simple character-based protocol for exchanging information. The client host application
to a DBM's net daemon, serving the particular I2A2 data base manager (DBM) -- reflector, authenticator, or
authorizer -- at one of two dedicated
ports. Then the
client host application sends a command to the net daemon. The net daemon passes the command to the DBM and
returns the DBM's reply to the client application.
This a general description of the protocol, complete with examples.
The protocol described above is called the external protocol, since it is used by net daemons and client host applications external to the DBMs. The DBMs and net daemons use a separate protocol, called the internal protocol. It has more options than the external protocol. On occasion a description of a external protocol reply will indicate that it also contains the net daemon's interpretation of an internal protocol error, complete with number and message.
While the I2A2 external protocol is a simple one and libraries are provided for using it, sometimes a remote client host application can't be modified to use the I2A2 external protocol. For some applications I2A2 offers protocol converters that allow the application to speak to I2A2 in its own language and hear replies in that language. A protocol converter acts as a gateway between the application and I2A2 servers.
These protocol converters are available:
- LDAP -- I2A2 provides a server that understands a limited subset of the Lightweight Directory Access Protocol, described in RFC 2251. Some LDAP bind, filter, search, and unbind operations are supported.
- RADIUS -- provides a service that enables authentication via the Remote Authentication Dial In User Service (RADIUS), described in RFC 2865.
A client host application makes a request -- issues a
command -- to an
I2A2 net daemon as a single character. The command character is the first character of the message and it is usually
followed by data associated with the command in the form of
For example, a lookup command must be accompanied by a field that contains some key to be used to look up a PUID for a person.
Fields accompany commands and replies and give additional information about the command or the reply. A field's leading character identifies the data contained in the field, and a field terminator character (a TAB) ends the field.
Replies from the net daemon to the client host application are encoded in a single character, which may be accompanied by fields which explain or expand the reply. There are three main reply codes, ACK (positive acknowledgment), continue, and NAK (negative acknowledgment), and a welcome reply code that is used once when a successful connection begins.
Sample Protocol Access Methods
To assist I2A2 developers a number of samples for using the I2A2 external potocol and protocol converters are available. They include the following ones.
The sslclnt program in the libpuidX
external library is a complete implementation in C of a client program that will communicate with the I2A2 DBMs, using
server-side or server- and client-side SSL|TLS.
This is the UNIX man page for sslclnt.
- The Apache Web Server Package is a complete package for installing a UNIX Apache web server that will do I2A2 authentication and authorization.
- I2A2 Examples in Perl contains sample Perl scripts.
- The PUIDCL external library provides I2A2 access functions for use by C programs, Visual Basic scripts, and Active Server Pages (ASP).