The Authenticator Lookup Command
The lookup command is most often used with the authenticator DBM to list public information about a person. The primary lookup key may be an alias or PUID; an authentication realm record may be given as a secondary lookup key.
Symbol
The puidnetd.h symbol for the lookup command is PUIDNETD_CMD_LOOKUP.
Keys
These keys may be used to locate a person. The field identifier symbols come from puidnetd.h
- a -- alias (PUIDNETD_DATA_AKA); do an exact match on the alias field value.
- p -- PUID (PUIDNETD_DATA_PUID); do an exact match on the PUID field value.
Sub-Key
This realm record sub-key may be included with the PUID or alias to cause the authentication DBM to return information about realm membership. The primary reasons for using this lookup key are: (1) to determine whether a person is a member of a realm; and (2) to list a realm member's public X.509 certificate, if any.
- @ -- realm record start/end symbol (PUIDNETD_DATA_AUTHC_REC); do an exact match on the alias or PUID field value, and return information about realm membership.
Reply
A positive acknowledgment (ACK) authenticator reply message may contain these fields. The field identifier symbols come from puidnetd.h
- @ -- realm record start/end (PUIDNETD_DATA_AUTHC_REC)
- R -- realm name (PUIDNETD_DATA_AUTHC_RNAME); the mnemonic realm name, e.g., "purdue"
- B -- certificate (PUIDNETD_DATA_AUTHC_CERT); an X.509 certificate, almost-base-64 encoded
A negative acknowledgment (NAK) reply will contain these fields.
- e -- an error code (PUIDNETD_DATA_ERRC); it accompanies a NAK reply.
- M -- a message (PUIDNETD_DATA_MSG); it accompanies a NAK reply.
Examples
Here are some examples using the simple keys alias and PUID.
This example asks the authenticator to report the identity of a person whose alias is "foobar":
External protocol lookup command message:
l afoobar
Positive acknowledgment (ACK) reply:
- a NFOO BAR p18 afoobar
Negative acknowledgment (NAK) reply:
-
n e17 MPerson not found (75)
17 is the external protocol PUIDNETD_EDBME error code. 75 is the internal protocol error number from the DBM, expanded in the first part of the message (PUIDNETD_DATA_MSG) field.
Example with a Secondary Key
Here's an example showing the use of the realm record as a
secondary key to see whether user "jdoe" has an account in the "purdue" realm, and list his certificate if he has one.
External protocol lookup command message:
l ajdoe @Rpurdue @
Positive acknowledgment (ACK) reply:
-
a NJohn Doe p18 ajdoe @ Rpurdue BNONE @
This reply shows that while "jdoe" is a member of the "purdue" realm, he does not have a certificate installed.
A negative acknowledgment (NAK) reply may be sent for several reasons. Either the person may not exist in the database, or may exist in the database but not be a member of the realm used as a secondary key. Here are both types of NAKs:
- n e17 MPerson not found (75)
- n e17 MPerson not a member of this realm (199)