--- /dev/null
+
+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
+ <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
+ <octet-string> - 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 <octet-string>.
+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 <string> New password.
+ (SR) KVNO <integer> Key version number.
+ (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.
+ (SR) SALTTYPE <string> Comma-separated list of salt types
+ supported for this principal. See
+ note below.
+ (R) MKVNO <integer> Master key version number.
+ (R) LASTPWCHANGE <general-time> Last time of password change.
+ (R) LASTSUCCESS <general-time> Last successful password entry.
+ (R) LASTFAILED <general-time> Last failed password attempt.
+ (R) FAILCOUNT <integer> Number of failed password attempts.
+ (R) MODNAME <string> Principal name who performed last
+ modification.
+ (R) MODDATE <general-time> 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.
+
projects / krb5.git / commitdiff