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.
