Edit File: kadmin.protocol
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, new or changed commands are marked with a plus sign): ADD-PRINCIPAL DELETE-PRINCIPAL RENAME-PRINCIPAL MODIFY-PRINCIPAL OTHER-CHANGEPW OTHER-RANDOM-CHANGEPW INQUIRE-PRINCIPAL EXTRACT-KEY (*+) ADD-KEY (+) DELETE-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. 70(+) KEY_ALREADY_EXISTS The specified key already exists. 71(+) KEY_DOES_NOT_EXIST The specified key does not exist. The add principal operation --------------------------- o Command String "ADD-PRINCIPAL" o Arguments <new-principal-string> - name of new principal <keyword-value-pair> - 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-string> - 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 <orig-principal-string> - original name <new-principal-string> - 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 <principal-string> - name of principal <keyword-value-pair> - 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-string> - principal to change password for <new-password> - 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-string> - 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 <principal-string> - 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 <next-principal-string> - name of next principal in database <keyword-value-pair> - 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-string> - instance to extract for <name-string> - 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 <keytab-entry> - 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 <keytab-entry>. The description of <keytab-entry> follows below. o Access Required Client principal must have EXTRACT permission. The add key operation --------------------- o Command String "ADD-KEY" o Arguments <principal-string> - name of the principal <password> - current password value <keyname> - name of the key in the form <keytype>:<salttype>. . . . o Returns SUCCESS - operation successful SYSTEM_ERROR - system error NOT_AUTHORIZED - not authorized to perform this KEY_ALREADY_EXISTS - one or more of the specified keytypes already exist. BAD_OPTION - bad keytype:saltype specified BAD_PW - supplied password is incorrect o Supplemental Returns NONE - if successful error message text - if failure o Description If the specified principal exists, the keyname(s) parse correctly the specified password is successfully verified against the existing key(s), and the specified keyname(s) do not exist, then these keytype(s) are added to the principal. o Access Required Client principal must have MODIFY_PRINCIPAL permission. The delete key operation ------------------------ o Command String "DELETE-KEY" o Arguments <principal-string> - name of the principal <password> - current password value <keyname> - name of the key in the form <keytype>:<salttype>, or name of the key in the form <keytype>:<salttype>: <key-version> . . . o Returns SUCCESS - operation successful SYSTEM_ERROR - system error NOT_AUTHORIZED - not authorized to perform this KEY_DOES_NOT_EXIST - one or more of the specified keytypes do not exist. BAD_OPTION - bad keytype:saltype specified BAD_PW - supplied password is incorrect o Supplemental Returns NONE - if successful error message text - if failure o Description If the specified principal exists, the keyname(s) parse correctly the specified password is successfully verified against the existing key(s), and the specified keyname(s) exist, then they are deleted from the principal. o Access Required Client principal must have MODIFY_PRINCIPAL 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 <string> New password. (SR) MAXLIFE <integer> The maximum lifetime of tickets for this principal in seconds. (SR) MAXRENEWLIFE <integer> The maximum renewable lifetime of tickets for this principal in seconds. (SR) EXPIRATION <general-time> When the new principal expires. (SR) PWEXPIRATION <general-time> When the password expires for this principal. (SR) RANDOMKEY <integer> Specifies that this is to have a random key generated for it. (SR) FLAGS <integer> Specifies flag value for this principal's attributes field in the database. (R) LASTSUCCESS <general-time> Last successful password entry. (R) LASTFAILED <general-time> Last failed password attempt. (R) FAILCOUNT <integer> Number of failed password attempts. (SR) AUXDATA <tagged-value> Tagged auxiliary value (see below) (R) KEYDATA <key-value> Key value (see below) (SR) EXTRADATA <unspecified> Extra data (see below) 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. o <tagged-value> The <tagged-value> type denotes data which is stored in the database as a tagged value. The protocol representation consists of a 4-byte network order integer to denote the tag with the remaining data providing the value. If encoded data is to be encapsulated, it must be in network order. In summary: AUXDATA=<tag><value> For example, to encode the value for tag 1 with a 4-byte value of 32 71 1e 30 in network order, the encoding would be: AUXDATA=00 00 00 01 32 71 1e 30 o <key-value> The <key-value> type denotes data which is stored in the database on a per-key basis. The protocol representation is consists of a 4-byte network order integer to denote a particular key. This integer is implementation dependent and is only used to correlate different <key-value> entries. This integer is followed by a 4-byte network order integer which denotes the attribute type. Currently, only three are supported: -1 denotes the key version; 1 denotes the key type and 2 denotes the salt type. This attribute type integer is followed by the attribute value and an optional per-attribute value. In summary: KEYDATA=<key-tag><attribute><attribute-value>[<per-attribute-value>] For example, to encode the value of a key with keytype 3, salttype 5, with key version number 32, key data of 12 34 56 78 90 ab cd ef and salt data of f0 e1 d2 c3 b4 a5 96 87, the encoding would be (using key-tag de ad be ef): (key version number 32) KEYDATA=de ad be ef ff ff ff ff 00 00 00 20 (key keytype 3, value 1234567890abcdef) KEYDATA=de ad be ef 00 00 00 01 00 00 00 03 12 34 56 78 90 ab cd ef (key salttype 5, value f0e1d2c3b4a59687) KEYDATA=de ad be ef 00 00 00 02 00 00 00 05 f0 e1 d2 c3 b4 a5 96 87 o <unspecified> The <unspecified> type is exactly that. Unspecified. Any data may be encoded here without restriction. 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 <string> Principal name 2 <integer> Key entry timestamp 3 <integer> Key's version number. 4 <integer> Key's keytype. 5 <integer> Key's encryption type. 6 <octet-string> Key's key value. All of these components are mandatory.
Back to File Manager