Connect to the Purdue Home Page

Purdue University

Identity and Access Management

File Formats                                          PUIDNETD(4)

     PUIDNETD - the PUID net daemon (NETD) protocol

     The PUIDNETD protocol defines an external method for
     exchanging information between protocol translators of the
     Purdue University IDentification (PUID) system (also known
     as I2A2 for Infrastructure for Identification, Authentica-
     tion, and Authorization.)

     The I2A2 system has three fast-access data base managers
     (DBMs):  a reflector DBM for looking up PUID information by
     various keys; an authentication DBM for accessing and test-
     ing authentication information; and an authorization DBM for
     testing authorization characteristics.

     This manual page describes the protocol that clients exter-
     nal to the DBM systems may use to communicate with net dae-
     mons that can communicate with the DBMs.  Thus the net dae-
     mons are fundamentally protocol converters, translating
     between external client commands and replies ("external"
     protocol) and DBM replies and commands ("internal proto-

     The protocol uses a simple message and reply method.  With
     one exception (the "welcome" reply from a net daemon) each
     message transmitted requires an immediate reply from the
     recipient, and there are no unsolicited replies.  Responses
     include positive (ACK) and negative (NAK) acknowledgements.

     The net daemon's welcome reply is a message solicited by
     connecting to it.  The act of connecting can be considered
     the command, and the welcome reply a response to it.

     Single character commands lead transmitted messages.  The
     same position is occupied by reply characters in response.
     Commands are defined with PUIDNETD_CMD_* names and replies
     with PUIDNETD_REPL_* names in puidnetd.h.

     All message and reply characters - with three exceptions -
     must be ASCII printable characters, conforming to a success-
     ful isprint(3) function test.

     Individual messages are limited to PUIDNETD_MAXMSGL charac-
     ters, including any required termination characters.
     (PUIDNETD_MAXMSGL is defined in puidnetd.h.)

     The three exceptions to ASCII printable characters in mes-
     sages are for the field terminator character (defined as
     PUIDNETD_MSGTERM in puidnetd.h), carriage return ('\r'), and

SunOS 5.8                 Last change:                          1

File Formats                                          PUIDNETD(4)

     new line ('\n').

     Every message and response body must be followed by at least
     the '\n' character.  A preceding '\r' character is optional,
     but since it is commonly supplied by Windows telnet pro-
     grams, it may be used as well, and the PUID net daemons
     always supply it.  The '\n' character is commonly used by
     UNIX message string handlers like fgets(3).

     An application that sends command or reply messages must
     follow their bodies with '\n'.  When an application receives
     command or reply messages ending in '\r\n' or '\n', it must
     strip them from the end of the message string body and
     insure the message body string is terminated with a NUL
     ('\0') character before sending the message body string to a
     function such as puidnetd_unpfld(3) for processing.

     CAUTION: the bytes of a command or reply message need not
     arrive in one response from low-level system read commands
     like read(2) or SSL_read().  Applications using these
     methods must acquire an input stream of characters until the
     terminating '\n' appears.  When read(2) or SSL_read() is
     used, the application may also have to hold received charac-
     ters that follow the '\n' and supply them as the beginning
     of the next command or reply message.  (That good input pro-
     gramming practice is sometimes overlooked.)

     FURTHER CAUTION: the sending of two '\n' characters is the
     same as sending 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, too.  If the sender
     is unaware it has sent two messages - e.g., it has acciden-
     tally ended a message with two '\n' characters - and sends a
     third, the sender may find itself erroneously processing the
     net daemon's second reply as the reply to the third message.
     Be careful when sending '\n' characters to match the mes-
     sages they terminate to their corresponding replies.

     Within message bodies the command character, the reply char-
     acter, and data fields must be followed by a
     PUIDNETD_MSGTERM character.  (See puidnetd.h for its current
     definition.)  The command and reply characters always occupy
     the first position of a message.

     Field identification characters, however, always are found
     after the command or reply character, and almost always also
     after a PUIDNETD_MSGTERM character.  (Strictly speaking, the
     PUIDNETD_MSGTERM character is optional after a command or
     reply character when a field identification character fol-
     lows it.)  Field data - ASCII printable characters only -
     follows the field identification character.  It is limited

SunOS 5.8                 Last change:                          2

File Formats                                          PUIDNETD(4)

     defined in puidnetd.h.)

     With one exception, the body of the message string (before
     the '\r\n' or '\n') always ends with a PUIDNETD_MSGTERM
     character.  The exception is when space in the message body
     is too short to contain the next field.  Then the message
     body may be continued by ending it with a PUIDNETD_DATA_CONT
     character instead.  (PUIDNETD_DATA_CONT is defined in

     When a message body ends with PUIDNETD_DATA_CONT, the next
     message must begin with a PUIDNETD_CMD_CONT in its command
     character position.  (PUIDNETD_CMD_CONT is defined in
     puidnetd.h.)  The application handling continued messages
     must remember the command character of the first message.
     (The puidnetd_unpk family of functions does this for the
     application; see puidnetd_unpk(3).)

     For all fields except the message field - PUIDNETD_DATA_MSG
     ('M') - leading and trailing spaces (' ') are removed.

     When leading and trailing spaces are removed from a field
     that contains only blanks, the field becomes empty.  Empty
     fields are generally ignored by PUIDNETD protocol functions.

     An empty field may produce unexpected results when it is a
     key to a command - e.g., a PUID in a PUIDNETD_DATA_PUID
     ('p') field - since the PUID key will be ignored.

     The command descriptions in COMMANDS and the examples in
     EXAMPLES use the following definitions from the current
     puidnetd.h.  Definitions in that header file are definitive
     and supercede those given here. The current command and
     field characters are shown below, but programmers should use
     the PUIDNETD_* definitions instead.

          the message field terminator character (currently TAB)

          the positive acknowledgement (ACK) reply character

          the negative acknowledgement (NAK) reply character

          the net daemon's welcome reply to a successful connec-

SunOS 5.8                 Last change:                          3

File Formats                                          PUIDNETD(4)

          the alias (Also-Known-As)


          common name

          the continuation data field character

          the creator PUID

          the record creation time

          the effectiVe PUID

          the error code

          the modification record

          the message

          the PUID (Purdue University IDentifier)

          updater's (modifier's) PUID

          record update time

          Human Resources ID

          common name search regular expression

          Student ID Number


SunOS 5.8                 Last change:                          4

File Formats                                          PUIDNETD(4)

          Realm-person access control list (ACL).

          the X.509 certificate (base-64 format)

          Password hash (unused).

          Clear-text password in base-64 format.

          Start or end of realm record.

          Realm ID (numeric)

          Realm name (e.g., "purdue")

          ACL permission mask

          "bad" (unsuccessful) authentication attempts since last
          successful authentication.

          Cumulative bad (unsuccessful) authentication attempts
          since counter was last reset.

          Cumulative good authentications since counter was last

          Time account was "frozen" (reply only)

          Time of last successful authentication (reply only)

          authorization characteristics

          authorization characteristic number list

          authorization characteristic name


SunOS 5.8                 Last change:                          5

File Formats                                          PUIDNETD(4)

          authorization characteristic number

          authorization expression

          authorization expression value (reply only)

     These command and reply descriptions include examples.  See
     the EXAMPLES section for more.  In the examples, lines
     beginning with "Client" come from an external client to the
     net daemon, and lines marked "Netd" go from the net daemon
     to the client.

         The continue command (and PUIDNETD_REPL_CONT ('+')
         reply) begin the second and subsequent parts of commands
         and replies lines whose first part was continued.

         The first part must end with a PUIDNETD_DATA_CONT field
         that has no PUIDNETD_MSGTERM character.  Subsequent com-
         mands are continued by the same convention.

         Here's a lookup command with a negative reply, whose
         PUID key (112233) is in a continuation command message.
         Note that the first part is acknowledged positively,
         while the entire command receives a continued negative
         reply with an error code of 333:

             Client: l\t+\n
             Netd: a\t\r\n
             Client: +\tp112233\t\n
             Netd: n\t+\r\n
             Client: a\t\n
             Netd: +\te333\t\r\n

     PUIDNETD_CMD_GETINFO ('i', lower case "eye")
         This command's sub-commands obtain information from
         DBMs.  Sub-commands are supplied in the first character
         of a message field - PUIDNETD_DATA_MSG ('M').  These
         sub-commands are recognized.

         PUIDNETD_GIFO_ALL ('A')
             This sub-command fetches all statistical information
             from an I2A2 DBM.  Statistics are delivered in mes-
             sage fields and their content varies by DBM.  Both
             basic statistics - DBM Process ID (PID), memory
             allocated (malloc arena), and PUID range - and
             DBM-specific statistics are delivered.  An example:

                 Client: i\tMA\t\n

SunOS 5.8                 Last change:                          6

File Formats                                          PUIDNETD(4)

                 Netd: a\tMPID: ...\tMAKA: ...\t\r\n

         PUIDNETD_GIFO_AKA ('a')
             This sub-command fetches both basic and alias
             management statistics.

         PUIDNETD_GIFO_CN ('n')
             This sub-command fetches both basic and common name
             management statistics.

             This sub-command fetches the value of the global
             Access Control List (ACL) bits for the PUID speci-
             fied in a PUIDNETD_DATA_PUID ('p') field. -- e.g.,

                 Client: i\tMb\tp1234\t\n
                 Netd: a\tp1234\tMACL=0x9abc\t\r\n

             The ACL bits value is in hexadecimal with the stan-
             dard "0x" prefix.

             Use of the PUIDNETD_GIFO_GETACL sub-command is res-
             tricted.  Contact the I2A2 system administrator for
             more information.

         PUIDNETD_GIFO_ID ('s')
             This sub-command fetches basic, Human Resources
             (HRID), and Student IDentification number management

         PUIDNETD_GIFO_PUID ('p')
             This sub-command fetches both basic and PUID statis-

             This sub-command fetches both basic and authentica-
             tion realm management statistics.

         PUIDNETD_GIFO_Q ('q')
             This sub-command fetches both basic and message
             queuing statistics.

     PUIDNETD_CMD_LOOKUP ('l', lower case "ell"))
         This command asks any I2A2 DBM to look up the person
         named with the supplied key.

         Two keys may be supplied to all DBMs, alias and PUID.
         The reflector DBM will also accept a name; a UNIX regu-
         lar expression to apply to all names in the data base;
         and for authorized users, it will accept a Human
         Resources IDentification number (HRID, also commonly
         know as a staff ID) or a Student IDentification number

SunOS 5.8                 Last change:                          7

File Formats                                          PUIDNETD(4)


         The authorization DBM will accept an additional field, a
         boolean expression made of characteristics numbers,
         parentheses, the OR operator ('|'), the AND operator
         ('&') and the negation operator ('~').

         Here is a reflector lookup request for the "foobar"
         alias, followed by a positive (ACK) reply, returning the
         common name for the alias, (Foo Bar), its PUID
         (7654321), and echoing the alias:

             Client: l\tafoobar\t\n
             Netd: a\tNFoo Bar\tp7654321\tafoobar\t\r\n

         Here is an authorizer request that asks an additional
         question, "Are characteristics 1234 and 5678 associated
         with the foobar alias?", followed by a DBM "no" reply:

             Client: l\tafoobar\tX(1234 & 5678)\t\n
             Netd: a\tNFoo Bar\tp7654321\tafoobar\t\v0\t\r\n

         This example asks the authorizer a more complicated
         characteristics question, "Does the person's record have
         characteristic 1234, but not characteristic 5678, and
         characteristic 9012, or just characteristic 3456; the
         reply is "yes":

             Client: l\tafoobar\tX(1234&~4567&9012)|3456\t\n
             Netd: a\tNFoo Bar\tp7654321\tafoobar\t\v1\t\r\n

         This lookup example makes a regular expression request
         of the reflector DBM for a name ending in "abell," and
         gets a negative repl (NAK), accompanied by some possible
         matches (the long reply has been broken into shorter
         lines by adding an artificial trailing " \" line break

             Client: l\tr,,abell$\t
             Netd: n\te17\tMPerson not found\t \
             Netd: MThere are 5 possible matches:\t \
             Netd: ... \
             Netd: M  9876543210(abellv09) VINCENT Z ABELL\t\r\n

     PUIDNETD_CMD_MINE ('I', upper case "eye")
         The mIne command allows authorized PUIDs to dump all
         information for a PUID.  PUIDs are authorized by ACLs
         managed by the I2A2 system administrator.

         In order for a client to use the mIne command, it must
         present an authorized PUID in an X.509 certificate,
         issued by the Purdue Certificate Authority (CA).

SunOS 5.8                 Last change:                          8

File Formats                                          PUIDNETD(4)

         Contact the I2A2 administrator for information on
         authorization and certificates.

         What the mIne command returns is DBM-specific.  It's
         beyond the scope of this manual page to describe every
         possible field returned by all DBMs.  An example will
         have to suffice.

         This is an example of mIning PUID 1234567 in the reflec-
         tor DBM.  The response is a positive acknowledgement
         with each reply field shown on a separate lines with the
         artificial "\" line break notation.  After the line
         break, a comment, started with '#', explains the field.

             Client: I\tp1234567\t\n
             Netd: a\t  \              # ACK
             Netd: NFoo Bar\t \        # Common name
             Netd: afoobar\t           # alias
             Netd: i0\t                # attributes
             Netd: c0\t                # creator's PUID
             Netd: >951419104.5744     # creation time
             Netd: h000112222          # HRID
             Netd: p1234567\t\r\n \    # PUID

         The creation time is a two part value, the parts
         separated by a period ('.').  The first part is UNIX
         seconds-since-the-epoch and can be fed to the ctime(3)
         function for conversion to a formatted date.  The second
         part is an internal serial number, used to distinguish
         times within the same second; it can effectively be

         The quit command directs the net daemon to close the
         connection.  The net daemon will send an acknowledgement
         before closing the connection.


     The authentication DBM (authcdbm) provides a way for users
     to submit authentication credentials to prove their identi-
     ties.  Logically, authcdbm is an authentication database
     partitioned into an arbitrary number of realms (an unfor-
     tunate choice of word that has nothing to do with Kerberos
     realms).  Realms correspond to departmental boundaries.
     Each realm specifies its preferred password encryption
     scheme from a list of supported ones, and may install its
     own X.509 certificates.  Realm administrators may join users
     to their realm, create authentication credentials for them,

SunOS 5.8                 Last change:                          9

File Formats                                          PUIDNETD(4)

     unjoin them, install X.509 certificates on their behalf, and
     perform other administrative actions.  Realm members may
     authenticate to the realm by supplying a PUID or alias, a
     password, and the realm name.

     Realm configuration is flexible.  In some realms, adminis-
     trators may not allow realm members to change their own
     passwords.  In others, members may be allowed not only to
     change their own passwords, but to delegate password chang-
     ing permission to a third party (e.g., a departmental

     Realms do not automatically trust authentication credentials
     from other realms.  Trust is established explicitly in the
     realm configuration file.  If a realm "a" trusts another
     realm "b", a member of both realms may authenticate to
     either realm to establish his identity in realm "a".  If
     realm "b" also trusts realm "a", the user may authenticate
     to either realm to establish his identity in both realms.
     However, these two-way trust relationships are not

     See authcdbm(8) and authcdbm_realms(5) for more information
     about realms and how to administer them.

     All authcdbm commands having to do with realms require a
     realm record. A realm record consists of a
     PUIDNETD_DATA_AUTHC_REC character, followed by realm data
     fields, a closing PUIDNETD_DATA_AUTHC_REC character, and a
     PUID_MSGTERM character.  The realm name is a required data
     field, so the minimal realm record would be just:


     A minimal realm record is used to join and unjoin users to
     and from a realm, and to list a user in a realm.  Typical
     realm records may also include fields such as the password
     or X.509 certificate.

         The authentication command allows people to prove their
         identities.  The user supplies a PUID or alias, a pass-
         word, and a realm name.  The netd replies ACK or NAK and
         keeps track of the authentication state of the netd ses-
         sion until the user disconnects.  The current authenti-
         cation state, which the user cannot modify except
         through the authenticate command, is passed to the DBM
         with modify and other commands.

         Passwords are supplied as base-64 encoded, clear text
         strings.  To avoid passing clear-text passwords over the
         net, authentication is only allowed over an SSL (Secure

SunOS 5.8                 Last change:                         10

File Formats                                          PUIDNETD(4)

         Sockets Layer) connection.  Users who attempt to authen-
         ticate without establishing an SSL connection receive an
         error message.  The netd asks authcdbm which encryption
         method to use for the realm to which the user wishes to
         authenticate, encrypts the password, and passes it to
         authcdbm.  This removes the burden of encoding encryp-
         tion methods into each netd client.  Supported encryp-
         tion methods are defined in the include file
         "puid_etypes.h".  Realms that wish to use their own
         encryption methods may specify "PUID_ETYPE_NULL" as the
         method, and support encryption in their clients.

         The syntax for an authentication command is:



         (Subsequent syntax examples will show only the
         "a<alias>" version. In all cases, "p<puid>" may also be

         The join command allows a realm administrator to add a
         person to the realm.  It requires a PUID or alias, and a
         minimal realm record:


         The realm administrator may also specify an initial
         password when joining a person to a realm:


         The unjoin command removes a user from a realm. WARNING:
         unjoining a user irrevocably destroys the user's authen-
         tication credentials (password and X.509 certificate) in
         that realm!  The unjoin command requires a PUID or
         alias, and a minimal realm record:


         Authcdbm modify commands can either modify the person
         record, as with the other DBMs, or one of the user's
         realm records.  The syntax of person-record modifica-
         tions is exactly like the other DBMs:  a
         PUIDNETD_CMD_MODIFY, an alias or PUID, and a
         PUIDNETD_DATA_MDFY field giving the new value. For
         instance, to modify a common name:

SunOS 5.8                 Last change:                         11

File Formats                                          PUIDNETD(4)

             m\ta<alias>\tYN\tn<New Common Name>\tY\t\n

         Realm record modifications do not require a
         PUIDNETD_DATA_MDFY field.  They require an alias or
         PUID, and a realm record that contains the new values
         for the fields to modify.  For instance, the syntax to
         modify a password is:


         The syntax to modify a certificate is the same except
         for the field type and field data:


         Modifying access control lists (ACLs) is more compli-
         cated.  Modify commands are used to add, delete and
         modify ACLs in a user's realm record. These ACLs control
         users' ability to change their own passwords and install
         certificates.  They also allow users to delegate permis-
         sion for password changes to another realm member.

         An ACL record contains a subcommand (add, delete, or
         modify), the PUID to which permissions are granted, and
         a numeric permission mask.  (Note: inside an ACL record
         the PUID is required and the alias may not be used. This
         restriction may be removed in future versions.)  The
         syntax of an ACL record is:


         The subcommand field is one of PUIDC_DATA_ACLR_ADD
         ("a"), PUIDC_DATA_ACLR_DEL ("d"), or
         PUIDC_DATA_ACLR_MDFY ("m").  (These definitions are
         found in the header file "puidc_acl.h".)  The syntax to
         add a new ACL entry is:


         The syntax to delete an existing ACL entry is:


         (Note that only the subcommand and PUID are required for
         a delete. The permission mask may be included but is

         The syntax to modify an existing ACL entry is:


         The mask is the only modifiable field.  Changing the

SunOS 5.8                 Last change:                         12

File Formats                                          PUIDNETD(4)

         PUID is not allowed, but would be equivalent to deleting
         an existing ACL and adding a new one. This restriction
         may be removed in future versions.

     The authorization DBM (authzdbm) supports two commands for
     managing authorization characteristics.

     PUIDNETD_CMD_CHLKUP ('C', lower case "cee")
         The characteristic lookup command allows an application
         to obtain a characteristic number for a name, or a name
         for a number.

         If the client application supplies a characteristic name
         field, PUIDNETD_DATA_AUTHZ_CHNM ('z', lower case "zee"),
         authzdbm will return the characteristic number via the
         authorizer net daemon in a PUIDNETD_DATA_AUTHZ_CHNR
         ('Z', upper case "zee") field.  An error code will be
         returned if the name can't be mapped to a number.

             Client: C\tzEmployee\t\n
             Netd: a\tZ0\t\r\n

         If the client application supplies a characteristic
         number field, PUIDNED_DATA_AUTHZ_CHNR, authzdbm will
         return the characteristic name via the authorizer net
         daemon in a PUIDNETD_DATA_AUTHZ_CHNM field.  An error
         code will be returned if the number can't be mapped to a

             Client: C\tZ0\t\n
             Netd: a\tzEmployee\t\r\n

         A request for a name to number lookup takes precedence
         over a number to name lookup.  If both name and number
         fields are specified in the same request, only the name
         to number lookup will be processed.

     PUIDNETD_CMD_LSTCH ('L', upper case "ell")
         The get characteristic list command allows an applica-
         tion to obtain a list of the characteristic numbers for
         an authenticated PUID.

         The application must first authenticate the PUID with
         the PUIDNETD_CMD_AUTHC command, sending it to the
         authorizer net daemon instead of its usual receptor, the
         authenticator net daemon.  (See the description of

         For an authenticated PUID (or its alias), the
         PUIDNETD_CMD_LSTCH command will return a list of the
         characteristic numbers assigned the PUID in a

SunOS 5.8                 Last change:                         13

File Formats                                          PUIDNETD(4)

         PUIDNETD_DATA_AUTHZ_CHL ('L', upper case "ell") field.

         The characteristic list field, PUIDNETD_DATA_AUTHZ_CHL
         ('L', upper case "ell") will contain a list of charac-
         teristic numbers, separated by commas.

         Either an alias or a PUID key must be used with the
         PUIDNETD_CMD_LSTCH command.

             Client: L\ta<alias>\t\n

             Client: L\ta<puid>\t\n

             NetD: a\tp<puid>\ta<alias>\tN<name>>\tL0,1\t\n

     This "welcome" string is sent by the net daemon after a con-
     nection has been established successfully - the remote peer
     sends no specific command message that solicits this reply.
     The remote peer's making of the connection can be considered
     the command that elicits this reply.


     The examples below all assume a realm named purdue that uses
     LDES encryption, and a user jdoe.  The clear-text password
     for jdoe is secret, and the base-64 encoding of the password
     is c2VjcmV0.  The new password is newsecret and the base-64
     encoded version is bmV3c2VjcmV0.


             Client: a\tajdoe\t@Rpurdue\tPc2VjcmV0\t@\t\n
             Netd: a\r\n


             Client: j\tajdoe\t@Rpurdue\t@\t\n
             Netd: a\r\n

     Join with an initial password:

             Client: j\tajdoe\t@Rpurdue\tPc2VjcmV0\t@\t\n
             Netd: a\r\n


             Client: u\tajdoe\t@Rpurdue\t@\t\n
             Netd: a\r\n

SunOS 5.8                 Last change:                         14

File Formats                                          PUIDNETD(4)

     Modify common name:

             Client: m\tajdoe\tYN\tnJohn D Doe\tY\t\n
             Netd: a\r\n

     Modify password:
             Client: m\tajdoe\t@Rpurdue\tPbmV3c2VjcmV0\t@\t\n
             Netd: a\r\n

     Modify, ACL, add:
             Netd: a\r\n

     Modify, ACL, modify:
             Netd: a\r\n

     Modify, ACL, delete:
             Client: m\tajdoe\t@Rpurdue\t!d\tp10254533\t!\t@\t\n
             Netd: a\r\n

     puidnetd.h          is the header file for the PUIDNETD pro-
                         tocol.  It defines command characters,
                         reply characters, field identification
                         characters, the field terminator charac-
                         ter, limits, error codes, and related

     The PUIDNETD protocol was designed by Victor A. Abell

     puidnetd_unpk(3), puidnetd_strerror(3).

SunOS 5.8                 Last change:                         15


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 or (765) 494-4000.