crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-set-passwd-03.txt

   1
   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
  10
  11               Kerberos Set/Change Password: Version 2
  12
  13
  14 0. Status Of This Memo
  15
  16    This document is an Internet-Draft and is in full conformance with
  17    all provisions of Section 10 of RFC2026 [1].
  18
  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.
  23
  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."
  29
  30    The list of current Internet-Drafts can be accessed at
  31    http://www.ietf.org/ietf/1id-abstracts.txt
  32
  33    The list of Internet-Draft Shadow Directories can be accessed at
  34    http://www.ietf.org/shadow.html.
  35
  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
  40
  41 1. Abstract
  42
  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.
  55
  56 2. Conventions used in this document
  57
  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].
  62
  63 3. The Protocol
  64
  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.
  69
  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.
  73
  74 Request Message
  75
  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       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  85
  86    All 16 bit fields are in network byte order.
  87
  88    message length field: contains the number of bytes in the message
  89    including this field.
  90
  91    protocol version number: contains the hex constant 0x0002 (network
  92    byte order).
  93
  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.
  97
  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:
 107
 108                     old passwd   initial flag  target principal can be
 109                     in request?  required?     distinct from
 110                                                authenticating principal?
 111
 112    change password:  yes         yes           no
 113
 114    set password:     no          policy (*)    yes
 115
 116    set key:          no          policy (*)    yes
 117
 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.
 125
 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.
 128
 129    The user-data component of the message consists of the following ASN.1
 130    structure encoded as an OCTET STRING:
 131
 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                        }
 147
 148    NewPasswdOrKeys :: = CHOICE {
 149                        passwords[0]  PasswordSequence,  -- change/set passwd
 150                        keyseq[1]     KeySequences       -- change/set key
 151    }
 152
 153    KeySequences :: = SEQUENCE OF KeySequence
 154
 155    KeySequence :: = SEQUENCE {
 156                        key[0]        EncryptionKey,
 157                        salt[1]       OCTET STRING OPTIONAL,
 158                        salt-type[2]  INTEGER OPTIONAL
 159    }
 160
 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    }
 168
 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.
 182
 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.
 195
 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.
 204
 205 Reply Message
 206
 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       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 216
 217
 218    All 16 bit fields are in network byte order.
 219
 220    message length field: contains the number of bytes in the message
 221    including this field.
 222
 223    protocol version number: contains the hex constant 0x0002 (network
 224    byte order). (The reply message has the same format as in [4]).
 225
 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.
 229
 230    AP-REP data: the AP-REP is the response to the AP-REQ in the request
 231    packet.
 232
 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.
 240
 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.
 243
 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       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 251
 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:
 278
 279          KERB-ETYPE-INFO-ENTRY :: = SEQUENCE {
 280                 encryption-type[0]  INTEGER,
 281                 salt[1]             OCTET STRING OPTIONAL -- not sent
 282          }
 283
 284          PKERB-ETYPE-INFO ::= SEQUENCE OF KERB-ETYPE-INFO-ENTRY
 285
 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.
 298
 299 4. Acknowledgements
 300
 301    The authors thank Tony Andrea for his input to the document.
 302
 303 5. References
 304
 305    [1] Bradner, S., "The Internet Standards Process -- Revision 3", BCP
 306        9, RFC 2026, October 1996.
 307
 308    [2] Bradner, S., "Key words for use in RFCs to Indicate Requirement
 309        Levels", BCP 14, RFC 2119, March 1997
 310
 311    [3] J. Kohl, C. Neuman. The Kerberos Network Authentication
 312        Service (V5), Request for Comments 1510.
 313
 314    [4] M. Horowitz. Kerberos Change Password Protocol,
 315        ftp://ds.internic.net/internet-drafts/
 316        draft-ietf-cat-kerb-chg-password-02.txt
 317
 318 6. Expiration Date
 319
 320    This draft expires in October 2000.
 321
 322 7. Authors' Addresses
 323
 324    Jonathan Trostle
 325    Cisco Systems
 326    170 W. Tasman Dr.
 327    San Jose, CA 95134
 328    Email: jtrostle@cisco.com
 329
 330    Mike Swift
 331    1 Microsoft Way
 332    Redmond, WA 98052
 333    Email: mikesw@microsoft.com
 334
 335    John Brezak
 336    1 Microsoft Way
 337    Redmond, WA 98052
 338    Email: jbrezak@microsoft.com
 339
 340    Bill Gossman
 341    Cybersafe Corporation
 342    1605 NW Sammamish Rd.
 343    Issaquah, WA 98027-5378
 344    Email: bill.gossman@cybersafe.com
 345