This document references, accompanies and extends the password changing protocol document, "A Proposal for a Standardized Kerberos Password Changing Protocol" by Theodore Ts'o. Administrative Command Extensions to the Password Changing Protocol =================================================================== The following commands and their accompanying definitions are an extension to the password changing protocol which allow remote administrative clients to perform functions analogous to those which are performed using the local database editing utility. These commands are encoded in the "command request" PDU described in the password changing protocol, and the server's responses to these commands are encoded in the "command reply" PDU. These commands are (optional commands are marked with an asterisk): ADD-PRINCIPAL DELETE-PRINCIPAL RENAME-PRINCIPAL MODIFY-PRINCIPAL OTHER-CHANGEPW OTHER-RANDOM-CHANGEPW INQUIRE-PRINCIPAL EXTRACT-KEY (*) In order to support these additional commands, the following additional status codes are also defined: Number Symbolic Name Meaning 64 P_ALREADY_EXISTS The specified principal already exists. 65 P_DOES_NOT_EXIST The specified principal does not exist. 66 NOT_AUTHORIZED The access control list on the server prevents this operation. 67 BAD_OPTION Either: 1) A bad option was specified; 2) A conflicting set of options would result from this operation; or 3) Existing options prevent this type of operation. 68 VALUE_REQUIRED The specified option requires a value. 69 SYSTEM_ERROR A system error occurred while processing a request. The add principal operation --------------------------- o Command String "ADD-PRINCIPAL" o Arguments - name of new principal - either "KEYWORD=value" or "KEYWORD". . . . o Returns SUCCESS - operation successful SYSTEM_ERROR - system error NOT_AUTHORIZED - not allowed to perform this P_ALREADY_EXISTS - new principal already exists BAD_OPTION - bad option supplied VALUE_REQUIRED - value required with keyword o Supplemental Returns NONE - if successful error message text - if failure o Description If the specified principal does not exist, the arguments parse correctly, and the arguments when combined with defaulted values do not produce a conflicting set of options then add the specified principal with the specified attributes. See below for the list of settable attributes. o Access Required Client principal must have ADD_PRINCIPAL permission. The delete principal operation ------------------------------ o Command String "DELETE-PRINCIPAL" o Argument - principal to delete o Returns SUCCESS - operation successful SYSTEM_ERROR - system error NOT_AUTHORIZED - not allowed to perform this P_DOES_NOT_EXIST - old principal does not exist o Supplemental returns NONE - if successful error message text - if failure o Description If the specified principal exists, then delete it from the database. o Access Required Client principal must have DELETE_PRINCIPAL permission. The rename principal operation ------------------------------ o Command String "RENAME-PRINCIPAL" o Arguments - original name - new name o Returns SUCCESS - operation successful SYSTEM_ERROR - system error NOT_AUTHORIZED - not allowed to perform this P_DOES_NOT_EXIST - old principal does not exist P_ALREADY_EXISTS - new principal already exists o Supplemental Returns NONE - if successful error message text - if failure o Description If the original principal exists and the new principal name does not exist, rename the original principal to the specified name. o Access Required Client principal must have ADD_PRINCIPAL and DELETE_PRINCIPAL permission. The modify principal operation ------------------------------ o Command String "MODIFY-PRINCIPAL" o Arguments - name of principal - either KEYWORD=value or KEYWORD. . . . o Returns SUCCESS - operation successful SYSTEM_ERROR - system error NOT_AUTHORIZED - not allowed to perform this P_DOES_NOT_EXIST - principal doesn't exist BAD_OPTION - bad option supplied VALUE_REQUIRED - value required with keyword o Supplemental returns NONE - if successful error message text - if failure o Description If the specified principal exists, the arguments parse correctly, and the arguments when combined with existing values do not produce a conflicting set of options, then modify the specified principal with the specified attributes. See below for the list of settable attributes. o Access Required Client principal must have MODIFY_PRINCIPAL permission. The change password operation ----------------------------- o Command String "OTHER-CHANGEPW" o Arguments - principal to change password for - new password o Returns SUCCESS - operation successful PW_UNACCEPT - specified password is bad SYSTEM_ERROR - system error NOT_AUTHORIZED - not allowed to perform this P_DOES_NOT_EXIST - old principal does not exist BAD_OPTION - principal has a random key o Supplemental returns NONE - if successful error message text - if failure o Description If the specified principal exists, and does not have a random key, then change the password to the specified password. The original password is NOT required. o Access Required Client principal must have CHANGEPW permission. The change random password command ---------------------------------- o Command String "OTHER-RANDOM-CHANGEPW" o Argument - principal to change password for o Returns SUCCESS - operation successful SYSTEM_ERROR - system error NOT_AUTHORIZED - not allowed to perform this P_DOES_NOT_EXIST - old principal does not exist BAD_OPTION - principal does not have a random key o Supplemental Returns NONE - if successful error message text - if failure o Description If the specified principal exists, and has a random key, then generate a new random password. The original password is NOT required. o Access Required Client principal must have CHANGEPW permission. The inquire principal command ----------------------------- o Command String "INQUIRE-PRINCIPAL" o Argument - name of principal or null argument o Returns SUCCESS - operation successful SYSTEM_ERROR - system error NOT_AUTHORIZED - not allowed to perform this P_DOES_NOT_EXIST - principal doesn't exist o Supplemental Returns If the return is SUCCESS - name of next principal in database - KEYWORD=value list . . . Otherwise error message text - if failure o Description If a principal is specified, then the database is searched for that particular principal and its attributes are returned as keyword-value pairs. If no principal is specified, then the first database entry is returned. The name of the next principal in the database is always returned to allow for scanning. See below for the list of attributes that can be returned. o Access Required Client principal must have INQUIRE_PRINCIPAL permission. The OPTIONAL extract service key table entry command ---------------------------------------------------- o Command String "EXTRACT-KEY" o Arguments - instance to extract for - name to extract for o Returns SUCCESS - operation successful CMD_UNKNOWN - operation not supported by server SYSTEM_ERROR - system error NOT_AUTHORIZED - not allowed to perform this P_DOES_NOT_EXIST - principal does not exist o Supplemental Returns - if successful error message text - if failure o Description If the specified name/instance exists in the database, then extract the service key entry and return it in . The description of follows below. o Access Required Client principal must have EXTRACT permission. Keywords -------- The following list of keywords are used for the ADD-PRINCIPAL and MODIFY-PRINCIPAL commands and are returned from the INQUIRE-PRINCIPAL command. Valid Keyword Value Type Value ------- --------------- --------------- -------------------------------------- (S) PASSWORD New password. (SR) KVNO Key version number. (SR) MAXLIFE The maximum lifetime of tickets for this principal in seconds. (SR) MAXRENEWLIFE The maximum renewable lifetime of tickets for this principal in seconds. (SR) EXPIRATION When the new principal expires. (SR) PWEXPIRATION When the password expires for this principal. (SR) RANDOMKEY Specifies that this is to have a random key generated for it. (SR) FLAGS Specifies flag value for this principal's attributes field in the database. (SR) SALTTYPE Comma-separated list of salt types supported for this principal. See note below. (R) MKVNO Master key version number. (R) LASTPWCHANGE Last time of password change. (R) LASTSUCCESS Last successful password entry. (R) LASTFAILED Last failed password attempt. (R) FAILCOUNT Number of failed password attempts. (R) MODNAME Principal name who performed last modification. (R) MODDATE Last modification date. The valid field indicates whether an attribute is Settable (e.g. appropriate for use with ADD-PRINCIPAL, et. al.; Returnable (e.g. returned by INQUIRE-PRINCIPAL); or both Settable and Returnable. Note: The value for SALTTYPE is a comma-separated list of strings. The individual values for these may be either "KRB5" or "KRB4" or a site-specific value. Keytab Entry ------------ If the EXTRACT SERVICE KEY function is supported, then the successful response to this command is the key entry. This is a series of 6 reply components as follows: component type value --------- --------------- ----------------------------------------- 1 Principal name 2 Key entry timestamp 3 Key's version number. 4 Key's keytype. 5 Key's encryption type. 6 Key's key value. All of these components are mandatory.