third_party/heimdal/doc/standardisation/rfc3244.txt

   1
   2
   3
   4
   5
   6
   7 Network Working Group                                           M. Swift
   8 Request for Comments: 3244                      University of Washington
   9 Category: Informational                                       J. Trostle
  10                                                            Cisco Systems
  11                                                                J. Brezak
  12                                                                Microsoft
  13                                                            February 2002
  14
  15
  16             Microsoft Windows 2000 Kerberos Change Password
  17                        and Set Password Protocols
  18
  19 Status of this Memo
  20
  21    This memo provides information for the Internet community.  It does
  22    not specify an Internet standard of any kind.  Distribution of this
  23    memo is unlimited.
  24
  25 Copyright Notice
  26
  27    Copyright (C) The Internet Society (2002).  All Rights Reserved.
  28
  29 Abstract
  30
  31    This memo specifies Microsoft's Windows 2000 Kerberos change password
  32    and set password protocols.  The Windows 2000 Kerberos change
  33    password protocol interoperates with the original Kerberos change
  34    password protocol.  Change password is a request reply protocol that
  35    includes a KRB_PRIV message that contains the new password for the
  36    user.
  37
  38 1. Introduction
  39
  40    Microsoft's Windows 2000 Kerberos change password protocol
  41    interoperates with the original Kerberos change password protocol.
  42    Change password is a request reply protocol that includes a KRB_PRIV
  43    message that contains the new password for the user.  The original
  44    change password protocol does not allow an administrator to set a
  45    password for a new user.  This functionality is useful in some
  46    environments, and this proposal extends the change password protocol
  47    to allow password setting.  The changes are: adding new fields to the
  48    request message to indicate the principal which is having its
  49    password set, not requiring the initial flag in the service ticket,
  50    using a new protocol version number, and adding three new result
  51    codes.
  52
  53
  54
  55
  56
  57
  58 Swift, et al.                Informational                      [Page 1]
  59 \f
  60 RFC 3244      Microsoft Windows 2000 Kerberos Change & Set February 2002
  61
  62
  63 2.  The Protocol
  64
  65    The service accepts 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
  68    fully contained in a single UDP packet.
  69
  70    For TCP transport, there is a 4 octet header in network byte order
  71    that precedes the message and specifies the length of the message.
  72
  73    Request Message
  74
  75      0                   1                   2                   3
  76      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
  77     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  78     |         message length        |    protocol version number    |
  79     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  80     |          AP_REQ length        |         AP_REQ data           /
  81     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  82     /                        KRB-PRIV message                       /
  83     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  84
  85    All 16 bit fields are in big-endian order.
  86
  87    message length field: contains the number of bytes in the message
  88    including this field.
  89
  90    protocol version number: contains the hex constant 0xff80 (big-endian
  91    integer).
  92
  93    AP-REQ length: length of AP-REQ data, in bytes.  If the length is
  94    zero, then the last field contains a KRB-ERROR message instead of a
  95    KRB-PRIV message.
  96
  97    AP-REQ data: (see [1]) The AP-REQ message must be for the service
  98    principal kadmin/changepw@REALM, where REALM is the REALM of the user
  99    who wishes to change/set his password.  The authenticator in the AP-
 100    REQ must include a subsession key.  (NOTE: The subsession key must be
 101    pseudo-randomly generated and must never be reused for multiple
 102    authenticators.)  To enable setting of passwords, it is not required
 103    that the initial flag be set in the Kerberos service ticket.
 104
 105    KRB-PRIV message (see [1]) This user-data field in the KRB-PRIV
 106    message is encrypted using the subkey from the authenticator in the
 107    AP-REQ data.  The usec and seq-number fields of the KRB_PRIV message
 108    are present and have the same value as the seq-number field in the
 109
 110
 111
 112
 113
 114 Swift, et al.                Informational                      [Page 2]
 115 \f
 116 RFC 3244      Microsoft Windows 2000 Kerberos Change & Set February 2002
 117
 118
 119    authenticator from the AP_REQ message (the seq-number in the
 120    authenticator will be present).  The server ignores the optional
 121    r-address field in the KRB_PRIV message, if it is present.
 122
 123    The user-data component of the message consists of the following
 124    ASN.1 structure encoded as an OCTET STRING:
 125
 126       ChangePasswdData ::=  SEQUENCE {
 127                           newpasswd[0]   OCTET STRING,
 128                           targname[1]    PrincipalName OPTIONAL,
 129                           targrealm[2]   Realm OPTIONAL
 130                           }
 131
 132    The server must verify the AP-REQ message, check whether the client
 133    principal in the ticket is authorized to set/change the password
 134    (either for that principal, or for the principal in the targname
 135    field if present), and decrypt the new password.  The server also
 136    checks whether the initial flag is required for this request,
 137    replying with status 0x0007 if it is not set and should be.  An
 138    authorization failure is cause to respond with status 0x0005.  For
 139    forward compatibility, the server should be prepared to ignore fields
 140    after targrealm in the structure that it does not understand.
 141
 142    The newpasswd field contains the cleartext password, and the server
 143    will apply any local policy checks including password policy checks.
 144    The server then generates the appropriate keytypes from the password
 145    and stores them in the KDC database.  If all goes well, status 0x0000
 146    is returned to the client in the reply message (see below).
 147
 148    Reply Message
 149
 150      0                   1                   2                   3
 151      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
 152     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 153     |         message length        |    protocol version number    |
 154     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 155     |          AP_REP length        |         AP-REP data           /
 156     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 157     /                         KRB-PRIV message                      /
 158     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 159
 160    All 16 bit fields are in big-endian order.
 161
 162    message length field: contains the number of bytes in the message
 163    including this field.
 164
 165
 166
 167
 168
 169
 170 Swift, et al.                Informational                      [Page 3]
 171 \f
 172 RFC 3244      Microsoft Windows 2000 Kerberos Change & Set February 2002
 173
 174
 175    protocol version number: contains the hex constant 0x0001 (big-endian
 176    integer). (The reply message has the same format as the original
 177    change password protocol.)
 178
 179    AP-REP length: length of AP-REP data, in bytes.  If the length is
 180    zero, then the last field contains a KRB-ERROR message instead of a
 181    KRB-PRIV message.
 182
 183    AP-REP data: the AP-REP is the response to the AP-REQ in the request
 184    packet.
 185
 186    KRB-PRIV message: This KRB-PRIV message must be encrypted with the
 187    subsession key from the authenticator in the AP-REQ data.
 188
 189    The server will respond with a KRB-PRIV message unless it cannot
 190    decode the client AP-REQ or KRB-PRIV message, in which case it will
 191    respond with a KRB-ERROR message.  NOTE: Unlike change password
 192    version 1, the KRB-ERROR message will be sent back without any
 193    encapsulation.
 194
 195    The user-data component of the KRB-PRIV message, or e-data component
 196    of the KRB-ERROR message, consists of the following data.
 197
 198      0                   1                   2                   3
 199      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
 200     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 201     |          result code          |        result string          /
 202     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 203
 204    result code (16 bits) (result codes 0-4 are from the original change
 205    password protocol):
 206
 207       The result code must have one of the following values
 208       (big-endian integer):
 209
 210       KRB5_KPASSWD_SUCCESS             0 request succeeds (This value
 211                                          is not allowed in a KRB-ERROR
 212                                          message)
 213
 214       KRB5_KPASSWD_MALFORMED           1 request fails due to being
 215                                          malformed
 216
 217       KRB5_KPASSWD_HARDERROR           2 request fails due to "hard"
 218                                          error in processing the
 219                                          request (for example, there
 220                                          is a resource or other
 221                                          problem causing the request
 222                                          to fail)
 223
 224
 225
 226 Swift, et al.                Informational                      [Page 4]
 227 \f
 228 RFC 3244      Microsoft Windows 2000 Kerberos Change & Set February 2002
 229
 230
 231       KRB5_KPASSWD_AUTHERROR           3 request fails due to an error
 232                                          in authentication processing
 233
 234       KRB5_KPASSWD_SOFTERROR           4 request fails due to a
 235                                          "soft" error in processing
 236                                          the request
 237
 238       KRB5_KPASSWD_ACCESSDENIED        5 requestor not authorized
 239
 240       KRB5_KPASSWD_BAD_VERSION         6 protocol version unsupported
 241
 242       KRB5_KPASSWD_INITIAL_FLAG_NEEDED 7 initial flag required
 243
 244       0xFFFF is returned if the request fails for some other reason.
 245       Although only a few non-zero result codes are specified here, the
 246       client should accept any non-zero result code as indicating
 247       failure.
 248
 249    result string:
 250
 251       This field contains information which might be useful to the user,
 252       such as feedback about policy failures.  The string is encoded in
 253       UTF-8.  It may be omitted if the server does not wish to include
 254       it.  If it is present, the client will display the string to the
 255       user.
 256
 257 3. Security Considerations
 258
 259    Password policies should be enforced to make sure that users do not
 260    pick passwords (for change password) that are vulnerable to brute
 261    force password guessing attacks.  An administrator who is authorized
 262    to set other principal's passwords is highly trusted and must also
 263    carefully protect his/her own credentials.
 264
 265 4.  References
 266
 267    [1]   Kohl, J. and C. Neuman, "The Kerberos Network Authentication
 268          Service (V5)", RFC 1510, September 1993.
 269
 270
 271
 272
 273
 274
 275
 276
 277
 278
 279
 280
 281
 282 Swift, et al.                Informational                      [Page 5]
 283 \f
 284 RFC 3244      Microsoft Windows 2000 Kerberos Change & Set February 2002
 285
 286
 287 5. Authors' Addresses
 288
 289    Mike Swift
 290    University of Washington
 291    Seattle, WA
 292
 293    EMail: mikesw@cs.washington.edu
 294
 295
 296    Jonathan Trostle
 297    Cisco Systems
 298    170 W. Tasman Dr.
 299    San Jose, CA 95134
 300
 301    EMail: john3725@world.std.com
 302
 303
 304    John Brezak
 305    Microsoft
 306    1 Microsoft Way
 307    Redmond, WA 98052
 308
 309    EMail: jbrezak@microsoft.com
 310
 311
 312
 313
 314
 315
 316
 317
 318
 319
 320
 321
 322
 323
 324
 325
 326
 327
 328
 329
 330
 331
 332
 333
 334
 335
 336
 337
 338 Swift, et al.                Informational                      [Page 6]
 339 \f
 340 RFC 3244      Microsoft Windows 2000 Kerberos Change & Set February 2002
 341
 342
 343 6.  Full Copyright Statement
 344
 345    Copyright (C) The Internet Society (2002).  All Rights Reserved.
 346
 347    This document and translations of it may be copied and furnished to
 348    others, and derivative works that comment on or otherwise explain it
 349    or assist in its implementation may be prepared, copied, published
 350    and distributed, in whole or in part, without restriction of any
 351    kind, provided that the above copyright notice and this paragraph are
 352    included on all such copies and derivative works.  However, this
 353    document itself may not be modified in any way, such as by removing
 354    the copyright notice or references to the Internet Society or other
 355    Internet organizations, except as needed for the purpose of
 356    developing Internet standards in which case the procedures for
 357    copyrights defined in the Internet Standards process must be
 358    followed, or as required to translate it into languages other than
 359    English.
 360
 361    The limited permissions granted above are perpetual and will not be
 362    revoked by the Internet Society or its successors or assigns.
 363
 364    This document and the information contained herein is provided on an
 365    "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
 366    TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
 367    BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
 368    HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
 369    MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
 370
 371 Acknowledgement
 372
 373    Funding for the RFC Editor function is currently provided by the
 374    Internet Society.
 375
 376
 377
 378
 379
 380
 381
 382
 383
 384
 385
 386
 387
 388
 389
 390
 391
 392
 393
 394 Swift, et al.                Informational                      [Page 7]
 395 \f