I2A2 uses a simple character-based protocol for exchanging information. The client host application
connects
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.
Protocol Conversion
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.
Commands
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
fields.
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
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
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.
User Commands sslclnt(1)
NAME
sslclnt - sample I2A2 client-side SSL client
SYNOPSIS
sslclnt [ -c cpath ] [ -C cser ] [ -d dir ] [ -e ] [ -h ] [
-H host ] [ -n nm ] [ -N ] [ -p port ] [ -P priv ] [ -t ] [
-s PUID ] [ -U pub ]
DESCRIPTION
Sslclnt is a sample client that makes client-side SSL con-
nections to I2A2 net daemons. It will also make server-side
only SSL connections when its -N option is specified.
I2A2 stands for Infrastructure for Identification, Authenti-
cation and Authorization. It is a Purdue infrastructure
designed to provide general support to Purdue data systems
for identifying accesses, authenticating their claimed iden-
tities, and determining what services the identities are
authorized to use.
Sslclnt operates in I2A2 external protocol mode. See puid-
netd(4) for more information on the protocol.
OPTIONS
Sslclnt accepts the following options.
-c cpath
optionally provides a path to the Purdue Certificate
Authority (CA) certificate in PEM format.
The Purdue CA certificate must be available, either
through this -c option, through the -d dir option, or
in the default OpenSSL certificate directory,
/opt/openssl/certs.
-C cser
provides an optional certificate serial number associ-
ated with the net daemon's Purdue University ID (PUID).
Normally the certificate serial number is taken from
the header file puidnetd.h, based on the net daemon's
name. (See the -n nm option.)
-N suppresses the client-side SSL functions, reducing the
connection to server-side only SSL.
When -N is specified, the -P priv and -U pub options
SunOS 5.8 Last change: 1
User Commands sslclnt(1)
must not be specified.
-d dir
optionally specifies the directory where the Purdue CA
may be found. That directory must also contain a sym-
bolic link to the Purdue CA certificate, named with the
certificate's hash.
See the -hash option of the openssl application's x509
function for information on obtaining a certificate's
hash.
-e suppresses all echoing of input commands to standard
output. Normally input echoing is suppressed when the
input device is the terminal and enabled when the input
device is a file or a pipe.
This option makes sure input is never echoed, enabling
sslclnt to be used in child processes with an alternat-
ing command-reply protocol.
-h optionally requests the display of a help output panel.
When this option is used, no further processing takes
place.
-H host
optionally specifies the name of the host where the
I2A2 net daemon is running. See the specification of
the default host names under the description of the -n
nm option. See the -t option for information on how it
changes the default host names.
Sslclnt normally determines the host name from the net
daemon's name - e.g., provided with the -n nm option.
-n nm
optionally specifies the name of the I2A2 net daemon.
Three names may be specified:
authc - the I2A2 authentication net daemon
at authenticate.i2a2.purdue.edu
authz - the I2A2 authorization net daemon
at authorize.i2a2.purdue.edu
refl - the I2A2 reflector (identification)
net daemon at lookup.i2a2.purdue.edu
The default is refl.
When the net daemon is specified with this option,
sslclnt supplies defaults for the net daemon's host
name, port, PUID, and certificate serial number from
SunOS 5.8 Last change: 2
User Commands sslclnt(1)
the puidnetd.h header file.
-p port
optionally specifies the port number at which the net
daemon should be contacted.
Sslclnt normally supplies a default port number for the
indicated net daemon:
1562 (authcs) - for the authentication net daemon
1564 (authzs) - for the authorization net daemon
1566 (refls) - for the reflector (identification)
net daemon
The names - "authcs", "authzs", and "refls" - given in
parentheses are the service sometimes found in the UNIX
system's /etc/services file. The port numbers may also
be found in puidnetd.h.
-P priv
is an option that must be supplied when doing
client-side SSL (i.e., the -N option has not been
specified.) Priv specifies the path to the client-side
certificate's private key in PEM format.
The key may be locked or unlocked. If it is locked,
sslclnt will ask for entry of the pass phrase that
unlocks it.
The key supplied by this option must match the public
certificate, supplied by the -U pub option.
-s PUID
optionally provides the PUID that will be found in the
net daemon's certificate. Normally the PUID is taken
from the header file puidnetd.h, based on the net
daemon's name. (See the -n nm option.)
-t optionally switches sslclnt to test mode. In test mode
the default net daemon host names become
dbm-dev.i2a2.purdue.edu.
-U pub
is an option that must be supplied when doing
client-side SSL (i.e., the -N option has not been
specified.) Pub specifies the path to the client-side
public certificate in PEM format.
The certificate supplied by this option must match the
private key, supplied by the -P priv option.
SunOS 5.8 Last change: 3
User Commands sslclnt(1)
INPUT AND OUTPUT
Once sslclnt has established a connection to the requested
net daemon, it communicates in I2A2 external protocol. (See
puidnetd(4) for details.)
Commands destined for the I2A2 net daemon must be supplied
to sslclnt via its standard input file in external protocol.
When the standard input isn't a terminal device, sslclnt
echoes input commands to standard output.
Sslclnt reports net daemon replies to its standard output
file in external protocol, exactly as received.
DIAGNOSTICS
Sslclnt reports errors to the standard error file and
returns a non-zero exit code.
EXAMPLES
Here's an example which effects a connection to the I2A2
reflector (the default net daemon). The example assumes the
Purdue CA certificate is in /opt/openssl/certs.
sslclnt -P private.pem -U public.pem
This example initiates a server-side SSL connection to the
I2A2 authenticator.
sslclnt -N -n authc
This example fragment selects a connection to the I2A2
authorizer.
sslclnt -n authz ...
This example shows how to specify an alternate directory
where the Purdue CA may be found.
sslclnt -d /foo/bar/certificates ...
PERMISSION
A Purdue certificate is required to use client-side SSL.
PREREQUISITES
The Purdue CA certificate must be available.
The presence of an OpenSSL is desirable. It's required for
compiling sslclnt from its sources.
FILES
All certificate files must contain X.509 certificates in PEM
format - i.e., have the ".pem" extension.
SunOS 5.8 Last change: 4
User Commands sslclnt(1)
AUTHORS
Vic Abell
SEE ALSO
openssl(1), puidnetd(4), puidnetd.h,
SunOS 5.8 Last change: 5
-
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).
