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

   1
   2 INTERNET-DRAFT                                        Mike Swift
   3 draft-ietf-cat-kerberos-set-passwd-02.txt             Microsoft
   4 March 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]) The AP-REQ message must be for the service
  99    principal kadmin/changepw@REALM, where REALM is the REALM of the user
 100    who wishes to change/set his password.  The ticket in the AP-REQ must
 101    must include a subkey in the Authenticator. To enable setting of
 102    passwords/keys, it is not required that the initial flag be set in the
 103    Kerberos service ticket. The initial flag is required for change requests,
 104    but not for set password requests. We have the following definitions:
 105
 106                     old passwd   initial flag  target principal can be
 107                     in request?  required?     distinct from
 108                                                authenticating principal?
 109
 110    change password:  yes         yes           no
 111
 112    set password:     no          no            yes
 113
 114    set key:          no          policy        yes
 115                                  determined
 116 \f
 117    KRB-PRIV message (see [3]) This KRB-PRIV message must be generated
 118    using the subkey from the authenticator in the AP-REQ data.
 119
 120    The user-data component of the message consists of the following ASN.1
 121    structure encoded as an OCTET STRING:
 122
 123    ChangePasswdData :: =  SEQUENCE {
 124                        newpasswdorkeys[0]   NewPasswdOrKeys,
 125                        targname[1]          PrincipalName OPTIONAL,
 126                          -- only present in set password: the principal
 127                          -- which will have its password set
 128                        targrealm[2]         Realm OPTIONAL,
 129                          -- only present in set password: the realm for
 130                          -- the principal which will have its password set
 131
 132                        }
 133
 134    NewPasswdOrKeys :: = CHOICE {
 135                        passwords[0]  PasswordSequence,
 136                        keyseq[1]     KeySequences
 137    }
 138
 139    KeySequences :: = SEQUENCE OF KeySequence
 140
 141    KeySequence :: = SEQUENCE {
 142                        key[0]        EncryptionKey,
 143                        salt[1]       OCTET STRING OPTIONAL,
 144                        salt-type[2]  INTEGER OPTIONAL
 145    }
 146
 147    PasswordSequence :: = SEQUENCE {
 148                        newpasswd[0]  OCTET STRING,
 149                        oldpasswd[1]  OCTET STRING OPTIONAL
 150                          -- oldpasswd always present for change password
 151                          -- but not present for set password
 152    }
 153
 154    The server must verify the AP-REQ message, check whether the client
 155    principal in the ticket is authorized to set or change the password
 156    (either for that principal, or for the principal in the targname
 157    field if present), and decrypt the new password/keys. The server
 158    also checks whether the initial flag is required for this request,
 159    replying with status 0x0007 if it is not set and should be. An
 160    authorization failure is cause to respond with status 0x0005. For
 161    forward compatibility, the server should be prepared to ignore fields
 162    after targrealm in the structure that it does not understand.
 163
 164    The newpasswdorkeys field contains either the new cleartext password
 165    (with the old cleartext password for a change password operation),
 166    or a sequence of encryption keys with their respective salts.
 167
 168    In the cleartext password case, if the old password is sent in the
 169    request, the request is defined to be a change password request. If
 170    the old password is not present in the request, the request is a set
 171    password request. The server should apply policy checks to the old
 172    and new password after verifying that the old password is valid.
 173    The server can check validity by obtaining a key from the old
 174    password with a keytype that is present in the KDC database for the
 175    user and comparing the keys for equality. The server then generates
 176    the appropriate keytypes from the password and stores them in the KDC
 177 \f
 178    database. If all goes well, status 0x0000 is returned to the client
 179    in the reply message (see below). For a change password operation,
 180    the initial flag in the service ticket MUST be set.
 181
 182    In the key sequence case, the sequence of keys is sent to the set
 183    password service. For a principal that can act as a server, its
 184    preferred keytype should be sent as the first key in the sequence,
 185    but the KDC is not required to honor this preference. Application
 186    servers should use the key sequence option for changing/setting their
 187    keys. The set password service should check that all keys are in the
 188    proper format, returning the KRB5_KPASSWD_MALFORMED error otherwise.
 189
 190 Reply Message
 191
 192        0                   1                   2                   3
 193        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
 194       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 195       |         message length        |    protocol version number    |
 196       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 197       |          AP_REP length        |         AP-REP data           /
 198       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 199       /                          KRB-PRIV message                     /
 200       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 201
 202
 203    All 16 bit fields are in network byte order.
 204
 205    message length field: contains the number of bytes in the message
 206    including this field.
 207
 208    protocol version number: contains the hex constant 0x0002 (network
 209    byte order). (The reply message has the same format as in [4]).
 210
 211    AP-REP length: length of AP-REP data, in bytes. If the length is zero,
 212    then the last field contains a KRB-ERROR message instead of a KRB-PRIV
 213    message.
 214
 215    AP-REP data: the AP-REP is the response to the AP-REQ in the request
 216    packet.
 217
 218    KRB-PRIV from [4]: This KRB-PRIV message must be generated using the
 219    subkey in the authenticator in the AP-REQ data.
 220
 221    The server will respond with a KRB-PRIV message unless it cannot
 222    validate the client AP-REQ or KRB-PRIV message, in which case it will
 223    respond with a KRB-ERROR message. NOTE: Unlike change password version
 224    1, the KRB-ERROR message will be sent back without any encapsulation.
 225
 226    The user-data component of the KRB-PRIV message, or e-data component
 227    of the KRB-ERROR message, must consist of the following data.
 228
 229        0                   1                   2                   3
 230        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
 231       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 232       |          result code          |        result string          /
 233       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 234       |                             edata                             /
 235       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 236 \f
 237       result code (16 bits) (result codes 0-4 are from [4]):
 238          The result code must have one of the following values (network
 239          byte order):
 240          KRB5_KPASSWD_SUCCESS      0 request succeeds (This value is not
 241                                      allowed in a KRB-ERROR message)
 242          KRB5_KPASSWD_MALFORMED    1 request fails due to being malformed
 243          KRB5_KPASSWD_HARDERROR    2 request fails due to "hard" error in
 244                                      processing the request (for example,
 245                                      there is a resource or other problem
 246                                      causing the request to fail)
 247          KRB5_KPASSWD_AUTHERROR    3 request fails due to an error in
 248                                      authentication processing
 249          KRB5_KPASSWD_SOFTERROR    4 request fails due to a soft error
 250                                      in processing the request
 251          KRB5_KPASSWD_ACCESSDENIED 5 requestor not authorized
 252          KRB5_KPASSWD_BAD_VERSION  6 protocol version unsupported
 253          KRB5_KPASSWD_INITIAL_FLAG_NEEDED 7 initial flag required
 254          KRB5_KPASSWD_POLICY_REJECT 8 new cleartext password fails policy;
 255          the result string should include a text message to be presented
 256          to the user.
 257          KRB5_KPASSWD_BAD_PRINCIPAL 9 target principal does not exist
 258          (only in response to a set password request).
 259          KRB5_KPASSWD_ETYPE_NOSUPP 10 the request contains a key sequence
 260          containing at least one etype that is not supported by the KDC.
 261          The response edata contains an ASN.1 encoded PKERB-ETYPE-INFO
 262          type that specifies the etypes that the KDC supports:
 263
 264          KERB-ETYPE-INFO-ENTRY :: = SEQUENCE {
 265                 encryption-type[0]  INTEGER,
 266                 salt[1]             OCTET STRING OPTIONAL -- not sent
 267          }
 268
 269          PKERB-ETYPE-INFO ::= SEQUENCE OF KERB-ETYPE-INFO-ENTRY
 270
 271          The client should retry the request using only etypes (keytypes)
 272          that are contained within the PKERB-ETYPE-INFO structure in the
 273          previous response.
 274          0xFFFF if the request fails for some other reason.
 275          The client must interpret any non-zero result code as a failure.
 276       result string - from [4]:
 277          This field is a UTF-8 encoded string which should be displayed
 278          to the user by the client. Specific reasons for a password
 279          set/change policy failure is one use for this string.
 280       edata: used to convey additional information as defined by the
 281          result code.
 282
 283 4. References
 284
 285    [1] Bradner, S., "The Internet Standards Process -- Revision 3", BCP
 286        9, RFC 2026, October 1996.
 287
 288    [2] Bradner, S., "Key words for use in RFCs to Indicate Requirement
 289        Levels", BCP 14, RFC 2119, March 1997
 290
 291    [3] J. Kohl, C. Neuman. The Kerberos Network Authentication
 292        Service (V5), Request for Comments 1510.
 293 \f
 294    [4] M. Horowitz. Kerberos Change Password Protocol,
 295        ftp://ds.internic.net/internet-drafts/
 296        draft-ietf-cat-kerb-chg-password-02.txt
 297
 298 5. Expiration Date
 299
 300    This draft expires in September 2000.
 301
 302 6. Authors' Addresses
 303
 304    Jonathan Trostle
 305    Cisco Systems
 306    170 W. Tasman Dr.
 307    San Jose, CA 95134
 308    Email: jtrostle@cisco.com
 309
 310    Mike Swift
 311    1 Microsoft Way
 312    Redmond, WA 98052
 313    Email: mikesw@microsoft.com
 314
 315    John Brezak
 316    1 Microsoft Way
 317    Redmond, WA 98052
 318    Email: jbrezak@microsoft.com
 319
 320    Bill Gossman
 321    Cybersafe Corporation
 322    1605 NW Sammamish Rd.
 323    Issaquah, WA 98027-5378
 324    Email: bill.gossman@cybersafe.com
 325