doc/kadmin/kpasswd.protocol

   1
   2
   3
   4                     A Proposal for a Standardized
   5                  Kerberos Password Changing Protocol
   6
   7                    **DRAFT**  **DRAFT**  **DRAFT**
   8
   9                            by Theodore Ts'o
  10                           September 7, 1995
  11
  12 Rationale
  13 =========
  14
  15 Currently, the Kerberos administration server which is being shipped
  16 with the Beta Kerberos V5 distributions from MIT has not been of
  17 sufficient quality for vendors to ship it in their products.  Hence,
  18 many vendors are creating and deploying proprietary administration
  19 servers.  In general, this is not a big problem --- relatively few
  20 users are Kerberos administrators and thus the Kerberos administration
  21 clients are used by relatively few users.
  22
  23 There is a big exception to this, however, which is the functionality of
  24 a user being able to change his or her own password.  Application
  25 programs may want to include this functionality in their programs; it
  26 would be desireable for there to be a standardized protocol for doing
  27 this.  Standardized Kerberos desktop management programs (such as
  28 Cornell's Authman) would also benefit from a standardized protocol; this
  29 way, they will do not need to implement many vendor-specific Kerberos
  30 administration protocols.  Similarily, at least one terminal server
  31 vendor has come to expressing their concern that there was not a
  32 standardized password changing protocol, since they wanted their product
  33 to offer this functionality.
  34
  35 This protocol is designed to address these concerns.
  36
  37
  38 Protocol Description
  39 ====================
  40
  41 The protocol used by the password changing protocol is intentionally
  42 very simple.  This is to encourage its widespread implementation, even
  43 in cases where there are size constraints (i.e., in a terminal server).
  44
  45 The protocol will use a TCP stream connection using port 464.  The
  46 symbolic name of this port is kpasswd:
  47
  48                 kpasswd         464/tcp
  49
  50
  51 The following encoding standards are used throughout.
  52
  53 Integers are sent as 4 byte objects, where the most significant byte
  54 is sent first, and the least signifcant byte is sent last.  (i.e.,
  55 standard Internet network byte order.)
  56
  57 Protocol data units (PDU's) are sent across using the following
  58 encoding.  First, the size of the PDU is sent as a 4 byte integer,
  59 followed by the PDU itself.  PDU's used by the protocol will be either a
  60 KRB_AP_REQ message, a KRB_AP_REP message, a "command request" PDU, or a
  61 "command response" PDU.  (The last two PDU's are encoded using a
  62 KRB_PRIV message.  For definitions of the KRB_AP_REQ, KRB_AP_REP, and
  63 KRB_PRIV message, see the Kerberos V5 protocol specification found in
  64 RFC 1510.)
  65
  66 The PDU's which are encoded using the KRB_PRIV message must include the
  67 sequence number field --- the client and server must fill in each
  68 successive PDU that it sends with a monotonically increasing sequence
  69 number.  The initial sequence number in each direction are negotiated in
  70 the KRB_AP_REQ and KRB_AP_REP messages.
  71
  72 The size of a Protoocl Data Unit SHOULD not exceed 16,384 bytes.  If an
  73 implementation receives a PDU which is larger that 16,384 bytes, the
  74 implementation MAY consider this a fatal error and terminate the TCP
  75 connection.  An implementation MUST be able to receive PDU's of at least
  76 16,384 bytes.
  77
  78 The "command request" PDU
  79 -------------------------
  80
  81 The "command request" PDU is sent from the client to server.  This PDU
  82 uses the following structure: First, the number of arguments, sent
  83 across as an integer.  The number of arguments MUST be greater than
  84 zero.  It is then followed by the arguments themselves, which are
  85 encoded as an integer length followed by the value of the argument.
  86
  87 The first argument is "command name".  The command name is a NETASCII
  88 string, and it may not contain an ASCII null.  Command names are case
  89 insentive.  Valid command names are defined below; any site-, or vendor-
  90 specific extensions to this protocol should use command names which
  91 begin with the letter 'X'.
  92
  93 The other arguments (if any) are dependent on the command specified by
  94 the first argument.
  95
  96 In other words:
  97
  98         Number of Arguments (integer, must be greater than zero)
  99                 Arg size 1 (integer)
 100                 Arg data 1 (octet string, command name)
 101                 ...
 102                 Arg size N (integer)
 103                 Arg data N (octet string)
 104
 105 This structure is then encrypted using the Kerberos V5 KRB_PRIV message.
 106
 107 The "command reply" PDU
 108 -----------------------
 109
 110 In response to a "command request" PDU, the server will send to the
 111 client a "command reply" PDU.  The structure of a "command reply" PDU is
 112 as follows:
 113
 114         status code (integer)
 115         Number of reply components (integer, may be zero)
 116                 Arg size 1 (integer)
 117                 Arg data 1 (octet string)
 118                 ...
 119                 Arg size N (integer)
 120                 Arg data N (octet string)
 121
 122 This structure is then encrypted using the Kerberos V5 KRB_PRIV message.
 123
 124 The status code may be one of the following values:
 125
 126 # Symbolic name                 Meaning
 127
 128 0 SUCCESS               The command was executed without any errors
 129 1 CMD_UNKNOWN           Command not recognized
 130 2 PW_UNACCEPT           The password chosen by the user is unnacceptable.
 131 3 BAD_PW                The old password furnished by the user is not correct.
 132 4 NOT_IN_TKT            The ticket used to authenticate to the server
 133                                 did not have the TKT_FLAG_INITIAL flag set.
 134 5 CANT_CHANGE           The server is not able to change the password
 135                                 due to no fault of the user.  (For
 136                                 example, the database may be in
 137                                 read-only mode for maintance reasons.)
 138 6 LANG_NOT_SUPPORTED    The requested language is not supported.
 139
 140 The error codes below 127, and above 256 are reserved for future
 141 expansion.  Local extensions of this protocol should use error codes
 142 between 128 and 255.
 143
 144 The user text in the reply message is generally some sort of
 145 explanatory text, which should be displayed to the user.
 146
 147
 148 Connection Establishment
 149 ========================
 150
 151 When a connection is made the password changing client exchanges the
 152 following PDU's:
 153
 154 Client                          Server
 155 ------                          ------
 156
 157 KRB_AP_REQ      ------->
 158
 159                 <-------        KRB_AP_REP
 160
 161 KRB_AP_REQ and KRB_AP_REP are the respective Kerberos V5 messages.  The
 162 client will autenticate to the server using the service name
 163 changepw/<REALMNAME>@<REALMNAME>, where <REALMNAME> should be
 164 substituted with the name of the Kerberos realm of the password changing
 165 server.  The client MUST set the MUTUAL-REQUIRED flag in the KRB_AP_REQ
 166 message, which indicates that server shall send a KRB_AP_REP message for
 167 the purposes of establishing mutual authentication between the client
 168 and the server.
 169
 170 Protocol Commands
 171 ==================
 172
 173 After the connection is established, the client may then send any
 174 number of "command request" PDUs; after each command request PDU is
 175 sent, the client should wait for a "command reply" PDU from the
 176 server.
 177
 178 If after 30 seconds inactivity, the client does not send a "command
 179 request" PDU, the server MAY elect to terminate the TCP connection.
 180
 181 The following commands defined in this standard:
 182
 183         QUIT
 184         CHECKPW
 185         CHANGEPW
 186         MOTD (*)
 187         MIME (*)
 188         LANGUAGE (*)
 189
 190 The commands marked with a (*) are optional; servers may or may not
 191 elect to support these commands.  If the commands are not supported, the
 192 server shall return a status code of CMD_UNKNOWN.
 193
 194 The quit command
 195 ----------------
 196
 197 The name of this command is "QUIT", and it takes no arguments.  The
 198 response to this command must be the error code "NO_ERROR".  There may
 199 be an optional reply component, which will consist of user text which
 200 should be displayed to the user.  After processing this command, the
 201 server will terminate the connection.
 202
 203 Kerberos password changing servers MUST implement this command.
 204
 205
 206 The check password command
 207 ---------------------------
 208
 209 The name of this command is "CHECKPW", and it takes one argument,
 210 which is a proposed password.  The server will evaluate this password
 211 according to its criteria and return either an NO_ERROR or PW_UNACCEPT
 212 error code.
 213
 214 There may be an optional reply component which consists of user text
 215 which should be displayed to the user.  It will typically explain why
 216 the password was unacceptable.
 217
 218 Kerberos password changing servers MUST implement this command.
 219
 220
 221 The change password command
 222 ---------------------------
 223
 224 The name of this command is "CHANGEPW", and it takes two arguments.  The
 225 first argument is the old password, and the second password is the new
 226 password.  The response from this command will generally be one of the
 227 following error codes: NO_ERROR, PW_UNACCEPT, BAD_PW, NOT_IN_TKT,
 228 CANT_CHANGE.
 229
 230 This command changes the password of the Kerberos principal which the
 231 client used to authenticate to the server.  For security reasons, the
 232 server should check to make sure that the ticket used to authenticate to
 233 the server had the TKT_FLG_INITIAL flag set; if this flag is not set in
 234 the ticket, then when the client attempts to use the "CHANGEPW" command,
 235 the server should return the NOT_IN_TKT error.
 236
 237 There may be an optional reply component which consists of user text
 238 which should be displayed to the user, explaining why the password was
 239 unacceptable or why the user's password could not be changed.
 240
 241 Kerberos password changing servers MUST implement this command.
 242
 243
 244 The Message of the Day command
 245 ------------------------------
 246
 247 The name of this command is "MOTD", and it takes zero or one additional
 248 arguments.  The optional argument is a magic token passed back from a
 249 previous MOTD command.  If this magic token is sent, the server MAY use
 250 it to determine use it to determine what (if any) messages should be
 251 displayed to the user.
 252
 253 This command returns one or two reply components.  The first reply
 254 component is a magic token; the magic token shall be a NETASCII string
 255 which may not contain an ASCII null character, and its length shall be
 256 less than 64 characters.  A client MAY store this magic token between
 257 invocations of the client, and send it to the server the next time the
 258 MOTD command is requested.
 259
 260 The second (optional) reply component contains text which should be
 261 displayed to the user.
 262
 263 Kerberos password changing servers MAY optionally implement this command.
 264
 265
 266 The MIME command
 267 ----------------
 268
 269 The name of this command is "MIME", and it takes zero additional
 270 arguments.
 271
 272 This command indicates that the client is willing to accept
 273 MIME-enhanced textual messages in place of the standard NETASCII textual
 274 messages.
 275
 276 If this command is not sent, the server MUST send all textual messages
 277 using NETASCII, with <CR><LF> used as a line breaks, and line lengths no
 278 more than 80 characters.  If this command is sent, and the server
 279 returns a status code of SUCCESS, the server MUST send textual messages
 280 as MIME-enhanced textual messages.  The server may refuse to send MIME
 281 messages by sending a status code of CMD_UNKNOWN.
 282
 283 Kerberos password changing servers MAY optionally implement this command.
 284
 285
 286 The Language Command
 287 ---------------------
 288
 289 The name of this command is "LANGUAGE", and it takes one additional
 290 argument, which indicates the language that the textual messages should
 291 be sent back in.  This additional argument must be consist of NETASCII
 292 characters, with ASCII nulls not allowed.  The argument shall be case
 293 insensitive.  What constitute valid arguments to this command are a
 294 local matter.  [Since ISO apparently doesn't have a standard way of
 295 referring to different languages or dialects.]
 296
 297 This command indicates that the client would prefer that textual
 298 messages be sent back using the requested language.  If the server does
 299 not support the requested language, the server may refuse the request by
 300 sending the error code LANG_NOT_SUPPORTED.
 301
 302 Kerberos password changing servers MAY optionally implement this command.
 303