2 This document references, accompanies and extends the password changing
3 protocol document, "A Proposal for a Standardized Kerberos Password
4 Changing Protocol" by Theodore Ts'o.
6 Administrative Command Extensions to the Password Changing Protocol
7 ===================================================================
8 The following commands and their accompanying definitions are an
9 extension to the password changing protocol which allow remote
10 administrative clients to perform functions analogous to those which
11 are performed using the local database editing utility. These
12 commands are encoded in the "command request" PDU described in the
13 password changing protocol, and the server's responses to these
14 commands are encoded in the "command reply" PDU.
16 These commands are (optional commands are marked with an asterisk, new
17 or changed commands are marked with a plus sign):
29 In order to support these additional commands, the following additional
30 status codes are also defined:
32 Number Symbolic Name Meaning
33 64 P_ALREADY_EXISTS The specified principal already exists.
34 65 P_DOES_NOT_EXIST The specified principal does not exist.
35 66 NOT_AUTHORIZED The access control list on the server prevents
37 67 BAD_OPTION Either: 1) A bad option was specified; 2) A
38 conflicting set of options would result from
39 this operation; or 3) Existing options prevent
40 this type of operation.
41 68 VALUE_REQUIRED The specified option requires a value.
42 69 SYSTEM_ERROR A system error occurred while processing a
44 70(+) KEY_ALREADY_EXISTS The specified key already exists.
45 71(+) KEY_DOES_NOT_EXIST The specified key does not exist.
47 The add principal operation
48 ---------------------------
49 o Command String "ADD-PRINCIPAL"
51 <new-principal-string> - name of new principal
52 <keyword-value-pair> - either "KEYWORD=value" or "KEYWORD".
57 SUCCESS - operation successful
58 SYSTEM_ERROR - system error
59 NOT_AUTHORIZED - not allowed to perform this
60 P_ALREADY_EXISTS - new principal already exists
61 BAD_OPTION - bad option supplied
62 VALUE_REQUIRED - value required with keyword
63 o Supplemental Returns
65 error message text - if failure
67 If the specified principal does not exist, the arguments parse
68 correctly, and the arguments when combined with defaulted values
69 do not produce a conflicting set of options then add the specified
70 principal with the specified attributes. See below for the list of
73 Client principal must have ADD_PRINCIPAL permission.
75 The delete principal operation
76 ------------------------------
77 o Command String "DELETE-PRINCIPAL"
79 <principal-string> - principal to delete
81 SUCCESS - operation successful
82 SYSTEM_ERROR - system error
83 NOT_AUTHORIZED - not allowed to perform this
84 P_DOES_NOT_EXIST - old principal does not exist
85 o Supplemental returns
87 error message text - if failure
89 If the specified principal exists, then delete it from the database.
91 Client principal must have DELETE_PRINCIPAL permission.
93 The rename principal operation
94 ------------------------------
95 o Command String "RENAME-PRINCIPAL"
97 <orig-principal-string> - original name
98 <new-principal-string> - new name
100 SUCCESS - operation successful
101 SYSTEM_ERROR - system error
102 NOT_AUTHORIZED - not allowed to perform this
103 P_DOES_NOT_EXIST - old principal does not exist
104 P_ALREADY_EXISTS - new principal already exists
105 o Supplemental Returns
107 error message text - if failure
109 If the original principal exists and the new principal name does not
110 exist, rename the original principal to the specified name.
112 Client principal must have ADD_PRINCIPAL and DELETE_PRINCIPAL
115 The modify principal operation
116 ------------------------------
117 o Command String "MODIFY-PRINCIPAL"
119 <principal-string> - name of principal
120 <keyword-value-pair> - either KEYWORD=value or KEYWORD.
125 SUCCESS - operation successful
126 SYSTEM_ERROR - system error
127 NOT_AUTHORIZED - not allowed to perform this
128 P_DOES_NOT_EXIST - principal doesn't exist
129 BAD_OPTION - bad option supplied
130 VALUE_REQUIRED - value required with keyword
131 o Supplemental returns
133 error message text - if failure
135 If the specified principal exists, the arguments parse correctly, and
136 the arguments when combined with existing values do not produce a
137 conflicting set of options, then modify the specified principal with
138 the specified attributes. See below for the list of settable
141 Client principal must have MODIFY_PRINCIPAL permission.
143 The change password operation
144 -----------------------------
145 o Command String "OTHER-CHANGEPW"
147 <principal-string> - principal to change password for
148 <new-password> - new password
150 SUCCESS - operation successful
151 PW_UNACCEPT - specified password is bad
152 SYSTEM_ERROR - system error
153 NOT_AUTHORIZED - not allowed to perform this
154 P_DOES_NOT_EXIST - old principal does not exist
155 BAD_OPTION - principal has a random key
156 o Supplemental returns
158 error message text - if failure
160 If the specified principal exists, and does not have a random key,
161 then change the password to the specified password. The original
162 password is NOT required.
164 Client principal must have CHANGEPW permission.
166 The change random password command
167 ----------------------------------
168 o Command String "OTHER-RANDOM-CHANGEPW"
170 <principal-string> - principal to change password for
172 SUCCESS - operation successful
173 SYSTEM_ERROR - system error
174 NOT_AUTHORIZED - not allowed to perform this
175 P_DOES_NOT_EXIST - old principal does not exist
176 BAD_OPTION - principal does not have a random key
177 o Supplemental Returns
179 error message text - if failure
181 If the specified principal exists, and has a random key, then
182 generate a new random password. The original password is NOT
185 Client principal must have CHANGEPW permission.
187 The inquire principal command
188 -----------------------------
189 o Command String "INQUIRE-PRINCIPAL"
191 <principal-string> - name of principal or null argument
193 SUCCESS - operation successful
194 SYSTEM_ERROR - system error
195 NOT_AUTHORIZED - not allowed to perform this
196 P_DOES_NOT_EXIST - principal doesn't exist
197 o Supplemental Returns
198 If the return is SUCCESS
199 <next-principal-string> - name of next principal in database
200 <keyword-value-pair> - KEYWORD=value list
205 error message text - if failure
207 If a principal is specified, then the database is searched for that
208 particular principal and its attributes are returned as keyword-value
209 pairs. If no principal is specified, then the first database entry
210 is returned. The name of the next principal in the database is always
211 returned to allow for scanning. See below for the list of attributes
212 that can be returned.
214 Client principal must have INQUIRE_PRINCIPAL permission.
216 The OPTIONAL extract service key table entry command
217 ----------------------------------------------------
218 o Command String "EXTRACT-KEY"
220 <instance-string> - instance to extract for
221 <name-string> - name to extract for
223 SUCCESS - operation successful
224 CMD_UNKNOWN - operation not supported by server
225 SYSTEM_ERROR - system error
226 NOT_AUTHORIZED - not allowed to perform this
227 P_DOES_NOT_EXIST - principal does not exist
228 o Supplemental Returns
229 <keytab-entry> - if successful
230 error message text - if failure
232 If the specified name/instance exists in the database, then
233 extract the service key entry and return it in <keytab-entry>.
234 The description of <keytab-entry> follows below.
236 Client principal must have EXTRACT permission.
238 The add key operation
239 ---------------------
240 o Command String "ADD-KEY"
242 <principal-string> - name of the principal
243 <password> - current password value
244 <keyname> - name of the key in the form
245 <keytype>:<salttype>.
250 SUCCESS - operation successful
251 SYSTEM_ERROR - system error
252 NOT_AUTHORIZED - not authorized to perform this
253 KEY_ALREADY_EXISTS - one or more of the specified
254 keytypes already exist.
255 BAD_OPTION - bad keytype:saltype specified
256 BAD_PW - supplied password is incorrect
257 o Supplemental Returns
259 error message text - if failure
261 If the specified principal exists, the keyname(s) parse
262 correctly the specified password is successfully verified
263 against the existing key(s), and the specified keyname(s) do
264 not exist, then these keytype(s) are added to the principal.
266 Client principal must have MODIFY_PRINCIPAL permission.
268 The delete key operation
269 ------------------------
270 o Command String "DELETE-KEY"
272 <principal-string> - name of the principal
273 <password> - current password value
274 <keyname> - name of the key in the form
275 <keytype>:<salttype>, or name of the
276 key in the form <keytype>:<salttype>:
282 SUCCESS - operation successful
283 SYSTEM_ERROR - system error
284 NOT_AUTHORIZED - not authorized to perform this
285 KEY_DOES_NOT_EXIST - one or more of the specified
286 keytypes do not exist.
287 BAD_OPTION - bad keytype:saltype specified
288 BAD_PW - supplied password is incorrect
289 o Supplemental Returns
291 error message text - if failure
293 If the specified principal exists, the keyname(s) parse
294 correctly the specified password is successfully verified
295 against the existing key(s), and the specified keyname(s)
296 exist, then they are deleted from the principal.
298 Client principal must have MODIFY_PRINCIPAL permission.
302 The following list of keywords are used for the ADD-PRINCIPAL and
303 MODIFY-PRINCIPAL commands and are returned from the
304 INQUIRE-PRINCIPAL command.
306 Valid Keyword Value Type Value
307 ------- --------------- --------------- --------------------------------------
308 (S) PASSWORD <string> New password.
309 (SR) MAXLIFE <integer> The maximum lifetime of tickets for
310 this principal in seconds.
311 (SR) MAXRENEWLIFE <integer> The maximum renewable lifetime of
312 tickets for this principal in seconds.
313 (SR) EXPIRATION <general-time> When the new principal expires.
314 (SR) PWEXPIRATION <general-time> When the password expires for this
316 (SR) RANDOMKEY <integer> Specifies that this is to have a
317 random key generated for it.
318 (SR) FLAGS <integer> Specifies flag value for this
319 principal's attributes field in the
321 (R) LASTSUCCESS <general-time> Last successful password entry.
322 (R) LASTFAILED <general-time> Last failed password attempt.
323 (R) FAILCOUNT <integer> Number of failed password attempts.
324 (SR) AUXDATA <tagged-value> Tagged auxiliary value (see below)
325 (R) KEYDATA <key-value> Key value (see below)
326 (SR) EXTRADATA <unspecified> Extra data (see below)
328 The valid field indicates whether an attribute is Settable (e.g. appropriate
329 for use with ADD-PRINCIPAL, et. al.; Returnable (e.g. returned by
330 INQUIRE-PRINCIPAL); or both Settable and Returnable.
333 The <tagged-value> type denotes data which is stored in the database as a
334 tagged value. The protocol representation consists of a 4-byte network order
335 integer to denote the tag with the remaining data providing the value. If
336 encoded data is to be encapsulated, it must be in network order. In summary:
338 For example, to encode the value for tag 1 with a 4-byte value of 32 71 1e 30
339 in network order, the encoding would be:
340 AUXDATA=00 00 00 01 32 71 1e 30
343 The <key-value> type denotes data which is stored in the database on a per-key
344 basis. The protocol representation is consists of a 4-byte network order
345 integer to denote a particular key. This integer is implementation dependent
346 and is only used to correlate different <key-value> entries. This integer
347 is followed by a 4-byte network order integer which denotes the attribute type.
348 Currently, only three are supported: -1 denotes the key version; 1 denotes the
349 key type and 2 denotes the salt type. This attribute type integer is followed
350 by the attribute value and an optional per-attribute value. In summary:
351 KEYDATA=<key-tag><attribute><attribute-value>[<per-attribute-value>]
352 For example, to encode the value of a key with keytype 3, salttype 5, with key
353 version number 32, key data of 12 34 56 78 90 ab cd ef and salt data of f0 e1
354 d2 c3 b4 a5 96 87, the encoding would be (using key-tag de ad be ef):
355 (key version number 32)
356 KEYDATA=de ad be ef ff ff ff ff 00 00 00 20
357 (key keytype 3, value 1234567890abcdef)
358 KEYDATA=de ad be ef 00 00 00 01 00 00 00 03 12 34 56 78 90 ab cd ef
359 (key salttype 5, value f0e1d2c3b4a59687)
360 KEYDATA=de ad be ef 00 00 00 02 00 00 00 05 f0 e1 d2 c3 b4 a5 96 87
363 The <unspecified> type is exactly that. Unspecified. Any data may be encoded
364 here without restriction.
368 If the EXTRACT SERVICE KEY function is supported, then the successful
369 response to this command is the key entry. This is a series of 6
370 reply components as follows:
373 --------- --------------- -----------------------------------------
374 1 <string> Principal name
375 2 <integer> Key entry timestamp
376 3 <integer> Key's version number.
377 4 <integer> Key's keytype.
378 5 <integer> Key's encryption type.
379 6 <octet-string> Key's key value.
381 All of these components are mandatory.