Protocol Fields Specific to the Authentication DBM
The authentication DBM uses fields and field records not employed by the other DBMs. Definitions of these fields are found in puidnetd.h. All symbol names begin with PUIDNETD.
Realm Records
The realm record contains the data for realm-specific operations (e.g.,
join). It begins with a PUIDNETD_DATA_AUTHC_REC ('@'), contains one or more
realm-specific fields, and ends with a PUIDNETD_DATA_AUTHC_REC and a
PUIDNETD_MSGTERM (TAB, or '\t'). The realm name is the only required field.
Below is an example of a minimal realm record whose only
data field is the realm name.
Realm Record Fields Here are fields that may be included in a realm
record, with their definitions from puidnetd.h:
- PUIDNETD_DATA_AUTHC_ACLR ('!') -- an access control list (ACL) record (see below)
- PUIDNETD_DATA_AUTHC_BA ('`') -- consecutive bad authentication attempts counter.
- PUIDNETD_DATA_AUTHC_CBA ('}') -- cumulative bad authentication attempts counter
- PUIDNETD_DATA_AUTHC_CERT ('B') -- X.509 certificate (base 64)
- PUIDNETD_DATA_AUTHC_CGA ('{') -- cumulative good authentication attempts counter
- PUIDNETD_DATA_AUTHC_PWD ('P') -- clear-text password (base 64)
- PUIDNETD_DATA_AUTHC_RNAME ('R') -- the realm name
Read-Only Realm Record Fields
In addition to the realm record fields described above, the authenticator DBM returns some or all of these internal fields in response to a mine command. These fields may not be set or modified by a client program:
- PUIDNETD_DATA_AUTHC_FRZ ('*') -- time account was frozen
- PUIDNETD_DATA_AUTHC_LGA ('~') -- time of last successful (good) authentication
- PUIDNETD_DATA_AUTHC_PHASH ('H') -- password hash (base 64)
- PUIDNETD_DATA_CRID ('c') -- creator's PUID (the administrator who joined the person to the realm created the realm record)
- PUIDNETD_DATA_CRTM ('>') -- creation time (time person was joined to the realm)
- PUIDNETD_DATA_UPUID ('u') -- last modifier's (updater's) PUID
- PUIDNETD_DATA_UTM ('U') -- last modification (update) time (of realm record)
The symbolic definitions for creator's PUID, creation time, modifier's PUID and modification time are identical to those
used outside of the realm record. Even though the symbols are identical, when they are embedded within a realm record
they apply only to that particular realm record.
ACL Records An ACL record specifies permissions given to a user to alter another user's realm
record. An ACL record consists of a beginning PUIDNETD_DATA_AUTHC_ACLR ('!') followed immediately by an ACL command
character, a PUID, a permission mask, a closing PUIDNETD_DATA_AUTHC_ACLR, and a PUIDNETD_MSGTERM.
ACL Record Fields
The ACL command characters are defined in puidnetd.h as:
- PUIDNETD_AUTHC_ACL_OP_ADD ('a') - add a new ACL entry
- PUIDNETD_AUTHC_ACL_OP_DEL ('d') - delete an existing ACL entry
- PUIDNETD_AUTHC_ACL_OP_MDFY ('m') - modify an existing ACL entry
The PUID field is given as a PUIDNETD_DATA_PUID, the PUID, and a PUIDNETD_MSGTERM. For example, "p12345678".
The permissions mask is a given as a PUIDNETD_DATA_AUTHC_ACLPM ('#'), a hexadecimal mask, and a PUIDNETD_MSGTERM.
The definitions for the ACL mask permissions are given in puidnetd.h as:
- PUIDNETD_AUTHC_ACLP_MP (0x1) - modify password
- PUIDNETD_AUTHC_ACLP_MC (0x2) - modify certificate
- PUIDNETD_AUTHC_ACLP_MAC (0x4 - modify ACL, create
- PUIDNETD_AUTHC_ACLP_MAD (0x8) - modify ACL, delete
- PUIDNETD_AUTHC_ACLP_MAM (0x10) - modify ACL, modify
- PUIDNETD_AUTHC_ACLP_ALL - all permissions
Here is a sample ACL record to add "modify password" and "modify certificate" permission for PUID 01234-56789:
!a p1234567 #0x3 !
Read-Only ACL Record Fields
In addition to the ACL record fields described above, the DBM returns these internal ACL fields in response to a mine command. These fields may not be set or modified by a client program:
- PUIDNETD_DATA_CRID ('c')-- creator's PUID (the administrator who joined the person to the realm created the realm record)
- PUIDNETD_DATA_CRTM ('>') -- creation time (time person was joined to the realm)
- PUIDNETD_DATA_UPUID ('u') -- last modifier's (updater's) PUID
- PUIDNETD_DATA_UTM ('U') -- last modification (update) time (of realm record)
Note that the symbolic definitions for creator's PUID, creation time, modifier's PUID and modification time are identical
to those used elsewhere. Even though the symbols are identical, when they are embedded within an ACL record they apply only
to that particular ACL record.
Examples Here are some sample realm records.
A minimal realm record for the
Purdue realm:
@Rpurdue @
A realm record with a base 64 encoded password ("secret0"):
@Rpurdue Pc2VjcmV0MA== @
A realm record with two ACL entry records adding "change password" permission to PUID 1234567, and "modify certificate" permission to PUID 7654321. The entry is broken into four chunks for readability but would be sent as a single, long line in the protocol:
@Rpurdue
!a p7654321 #0x2 !
!a p1234567 #0x1 !
@