| blob | 0319f8bf347ce9b8002442d040b363c58a7c7302 |
2 INTERNET-DRAFT Mike Swift
3 draft-ietf-cat-kerberos-set-passwd-03.txt Microsoft
4 April 2000 Jonathan Trostle
5 Cisco Systems
6 John Brezak
7 Microsoft
8 Bill Gossman
9 Cybersafe
11 Kerberos Set/Change Password: Version 2
14 0. Status Of This Memo
16 This document is an Internet-Draft and is in full conformance with
17 all provisions of Section 10 of RFC2026 [1].
19 Internet-Drafts are working documents of the Internet Engineering
20 Task Force (IETF), its areas, and its working groups. Note that
21 other groups may also distribute working documents as
22 Internet-Drafts.
24 Internet-Drafts are draft documents valid for a maximum of six
25 months and may be updated, replaced, or obsoleted by other
26 documents at any time. It is inappropriate to use Internet-
27 Drafts as reference material or to cite them other than as
28 "work in progress."
30 The list of current Internet-Drafts can be accessed at
31 http://www.ietf.org/ietf/1id-abstracts.txt
33 The list of Internet-Draft Shadow Directories can be accessed at
34 http://www.ietf.org/shadow.html.
36 Comments and suggestions on this document are encouraged. Comments
37 on this document should be sent to the CAT working group discussion
38 list:
39 ietf-cat-wg@stanford.edu
41 1. Abstract
43 The Kerberos (RFC 1510 [3]) change password protocol (Horowitz [4]),
44 does not allow for an administrator to set a password for a new user.
45 This functionality is useful in some environments, and this proposal
46 extends [4] to allow password setting. The changes are: adding new
47 fields to the request message to indicate the principal which is
48 having its password set, not requiring the initial flag in the service
49 ticket, using a new protocol version number, and adding three new
50 result codes. We also extend the set/change protocol to allow a
51 client to send a sequence of keys to the KDC instead of a cleartext
52 password. If in the cleartext password case, the cleartext password
53 fails to satisfy password policy, the server should use the result
54 code KRB5_KPASSWD_POLICY_REJECT.
56 2. Conventions used in this document
58 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
59 \f
60 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in
61 this document are to be interpreted as described in RFC-2119 [2].
63 3. The Protocol
65 The service must accept requests on UDP port 464 and TCP port 464 as
66 well. The protocol consists of a single request message followed by
67 a single reply message. For UDP transport, each message must be fully
68 contained in a single UDP packet.
70 For TCP transport, there is a 4 octet header in network byte order
71 precedes the message and specifies the length of the message. This
72 requirement is consistent with the TCP transport header in 1510bis.
74 Request Message
76 0 1 2 3
77 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
78 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
79 | message length | protocol version number |
80 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
81 | AP_REQ length | AP-REQ data /
82 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
83 / KRB-PRIV message /
84 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
86 All 16 bit fields are in network byte order.
88 message length field: contains the number of bytes in the message
89 including this field.
91 protocol version number: contains the hex constant 0x0002 (network
92 byte order).
94 AP-REQ length: length of AP-REQ data, in bytes. If the length is zero,
95 then the last field contains a KRB-ERROR message instead of a KRB-PRIV
96 message.
98 AP-REQ data: (see [3]) For a change password/key request, the AP-REQ
99 message service ticket sname, srealm principal identifier is
100 kadmin/changepw@REALM where REALM is the realm of the change password
101 service. The same applies to a set password/key request except the
102 principal identifier is kadmin/setpw@REALM. The ticket in the AP-REQ
103 must include a subkey in the Authenticator. To enable setting of
104 passwords/keys, it is not required that the initial flag be set in the
105 Kerberos service ticket. The initial flag is required for change requests,
106 but not for set requests. We have the following definitions:
108 old passwd initial flag target principal can be
109 in request? required? distinct from
110 authenticating principal?
112 change password: yes yes no
114 set password: no policy (*) yes
116 set key: no policy (*) yes
118 change key: no yes no
119 \f
120 policy (*): implementations SHOULD allow administrators to set the
121 initial flag required for set requests policy to either yes or no.
122 Clients MUST be able to retry set requests that fail due to error 7
123 (initial flag required) with an initial ticket. Clients SHOULD NOT
124 cache service tickets targetted at kadmin/changepw.
126 KRB-PRIV message (see [3]) This KRB-PRIV message must be generated
127 using the subkey from the authenticator in the AP-REQ data.
129 The user-data component of the message consists of the following ASN.1
130 structure encoded as an OCTET STRING:
132 ChangePasswdData :: = SEQUENCE {
133 newpasswdorkeys[0] NewPasswdOrKeys,
134 targname[1] PrincipalName OPTIONAL,
135 -- only present in set password/key: the principal
136 -- which will have its password or keys set. Not
137 -- present in a set request if the client principal
138 -- from the ticket is the principal having its
139 -- passwords or keys set.
140 targrealm[2] Realm OPTIONAL,
141 -- only present in set password/key: the realm for
142 -- the principal which will have its password or
143 -- keys set. Not present in a set request if the
144 -- client principal from the ticket is the principal
145 -- having its passwords or keys set.
146 }
148 NewPasswdOrKeys :: = CHOICE {
149 passwords[0] PasswordSequence, -- change/set passwd
150 keyseq[1] KeySequences -- change/set key
151 }
153 KeySequences :: = SEQUENCE OF KeySequence
155 KeySequence :: = SEQUENCE {
156 key[0] EncryptionKey,
157 salt[1] OCTET STRING OPTIONAL,
158 salt-type[2] INTEGER OPTIONAL
159 }
161 PasswordSequence :: = SEQUENCE {
162 newpasswd[0] OCTET STRING,
163 oldpasswd[1] OCTET STRING OPTIONAL
164 -- oldpasswd always present for change password
165 -- but not present for set password, set key, or
166 -- change key
167 }
169 The server must verify the AP-REQ message, check whether the client
170 principal in the ticket is authorized to set or change the password
171 (either for that principal, or for the principal in the targname
172 field if present), and decrypt the new password/keys. The server
173 also checks whether the initial flag is required for this request,
174 replying with status 0x0007 if it is not set and should be. An
175 authorization failure is cause to respond with status 0x0005. For
176 forward compatibility, the server should be prepared to ignore fields
177 after targrealm in the structure that it does not understand.
178 \f
179 The newpasswdorkeys field contains either the new cleartext password
180 (with the old cleartext password for a change password operation),
181 or a sequence of encryption keys with their respective salts.
183 In the cleartext password case, if the old password is sent in the
184 request, the request MUST be a change password request. If the old
185 password is not present in the request, the request MUST be a set
186 password request. The server should apply policy checks to the old
187 and new password after verifying that the old password is valid.
188 The server can check validity by obtaining a key from the old
189 password with a keytype that is present in the KDC database for the
190 user and comparing the keys for equality. The server then generates
191 the appropriate keytypes from the password and stores them in the KDC
192 database. If all goes well, status 0x0000 is returned to the client
193 in the reply message (see below). For a change password operation,
194 the initial flag in the service ticket MUST be set.
196 In the key sequence case, the sequence of keys is sent to the change
197 or set password service (kadmin/changepw or kadmin/setpw respectively).
198 For a principal that can act as a server, its preferred keytype should
199 be sent as the first key in the sequence, but the KDC is not required
200 to honor this preference. Application servers should use the key
201 sequence option for changing/setting their keys. The change/set password
202 services should check that all keys are in the proper format, returning
203 the KRB5_KPASSWD_MALFORMED error otherwise.
205 Reply Message
207 0 1 2 3
208 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
209 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
210 | message length | protocol version number |
211 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
212 | AP_REP length | AP-REP data /
213 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
214 / KRB-PRIV message /
215 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
218 All 16 bit fields are in network byte order.
220 message length field: contains the number of bytes in the message
221 including this field.
223 protocol version number: contains the hex constant 0x0002 (network
224 byte order). (The reply message has the same format as in [4]).
226 AP-REP length: length of AP-REP data, in bytes. If the length is zero,
227 then the last field contains a KRB-ERROR message instead of a KRB-PRIV
228 message.
230 AP-REP data: the AP-REP is the response to the AP-REQ in the request
231 packet.
233 KRB-PRIV from [4]: This KRB-PRIV message must be generated using the
234 subkey in the authenticator in the AP-REQ data.
235 \f
236 The server will respond with a KRB-PRIV message unless it cannot
237 validate the client AP-REQ or KRB-PRIV message, in which case it will
238 respond with a KRB-ERROR message. NOTE: Unlike change password version
239 1, the KRB-ERROR message will be sent back without any encapsulation.
241 The user-data component of the KRB-PRIV message, or e-data component
242 of the KRB-ERROR message, must consist of the following data.
244 0 1 2 3
245 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
246 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
247 | result code | result string /
248 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
249 | edata /
250 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
252 result code (16 bits) (result codes 0-4 are from [4]):
253 The result code must have one of the following values (network
254 byte order):
255 KRB5_KPASSWD_SUCCESS 0 request succeeds (This value is not
256 allowed in a KRB-ERROR message)
257 KRB5_KPASSWD_MALFORMED 1 request fails due to being malformed
258 KRB5_KPASSWD_HARDERROR 2 request fails due to "hard" error in
259 processing the request (for example,
260 there is a resource or other problem
261 causing the request to fail)
262 KRB5_KPASSWD_AUTHERROR 3 request fails due to an error in
263 authentication processing
264 KRB5_KPASSWD_SOFTERROR 4 request fails due to a soft error
265 in processing the request
266 KRB5_KPASSWD_ACCESSDENIED 5 requestor not authorized
267 KRB5_KPASSWD_BAD_VERSION 6 protocol version unsupported
268 KRB5_KPASSWD_INITIAL_FLAG_NEEDED 7 initial flag required
269 KRB5_KPASSWD_POLICY_REJECT 8 new cleartext password fails policy;
270 the result string should include a text message to be presented
271 to the user.
272 KRB5_KPASSWD_BAD_PRINCIPAL 9 target principal does not exist
273 (only in response to a set password request).
274 KRB5_KPASSWD_ETYPE_NOSUPP 10 the request contains a key sequence
275 containing at least one etype that is not supported by the KDC.
276 The response edata contains an ASN.1 encoded PKERB-ETYPE-INFO
277 type that specifies the etypes that the KDC supports:
279 KERB-ETYPE-INFO-ENTRY :: = SEQUENCE {
280 encryption-type[0] INTEGER,
281 salt[1] OCTET STRING OPTIONAL -- not sent
282 }
284 PKERB-ETYPE-INFO ::= SEQUENCE OF KERB-ETYPE-INFO-ENTRY
286 The client should retry the request using only etypes (keytypes)
287 that are contained within the PKERB-ETYPE-INFO structure in the
288 previous response.
289 0xFFFF if the request fails for some other reason.
290 The client must interpret any non-zero result code as a failure.
291 result string - from [4]:
292 This field is a UTF-8 encoded string which should be displayed
293 to the user by the client. Specific reasons for a password
294 \f
295 set/change policy failure is one use for this string.
296 edata: used to convey additional information as defined by the
297 result code.
299 4. Acknowledgements
301 The authors thank Tony Andrea for his input to the document.
303 5. References
305 [1] Bradner, S., "The Internet Standards Process -- Revision 3", BCP
306 9, RFC 2026, October 1996.
308 [2] Bradner, S., "Key words for use in RFCs to Indicate Requirement
309 Levels", BCP 14, RFC 2119, March 1997
311 [3] J. Kohl, C. Neuman. The Kerberos Network Authentication
312 Service (V5), Request for Comments 1510.
314 [4] M. Horowitz. Kerberos Change Password Protocol,
315 ftp://ds.internic.net/internet-drafts/
316 draft-ietf-cat-kerb-chg-password-02.txt
318 6. Expiration Date
320 This draft expires in October 2000.
322 7. Authors' Addresses
324 Jonathan Trostle
325 Cisco Systems
326 170 W. Tasman Dr.
327 San Jose, CA 95134
328 Email: jtrostle@cisco.com
330 Mike Swift
331 1 Microsoft Way
332 Redmond, WA 98052
333 Email: mikesw@microsoft.com
335 John Brezak
336 1 Microsoft Way
337 Redmond, WA 98052
338 Email: jbrezak@microsoft.com
340 Bill Gossman
341 Cybersafe Corporation
342 1605 NW Sammamish Rd.
343 Issaquah, WA 98027-5378
344 Email: bill.gossman@cybersafe.com