A Proposal for a Standardized Kerberos Password Changing Protocol **DRAFT** **DRAFT** **DRAFT** by Theodore Ts'o September 7, 1995 Rationale ========= Currently, the Kerberos administration server which is being shipped with the Beta Kerberos V5 distributions from MIT has not been of sufficient quality for vendors to ship it in their products. Hence, many vendors are creating and deploying proprietary administration servers. In general, this is not a big problem --- relatively few users are Kerberos administrators and thus the Kerberos administration clients are used by relatively few users. There is a big exception to this, however, which is the functionality of a user being able to change his or her own password. Application programs may want to include this functionality in their programs; it would be desireable for there to be a standardized protocol for doing this. Standardized Kerberos desktop management programs (such as Cornell's Authman) would also benefit from a standardized protocol; this way, they will do not need to implement many vendor-specific Kerberos administration protocols. Similarily, at least one terminal server vendor has come to expressing their concern that there was not a standardized password changing protocol, since they wanted their product to offer this functionality. This protocol is designed to address these concerns. Protocol Description ==================== The protocol used by the password changing protocol is intentionally very simple. This is to encourage its widespread implementation, even in cases where there are size constraints (i.e., in a terminal server). The protocol will use a TCP stream connection using port 464. The symbolic name of this port is kpasswd: kpasswd 464/tcp The following encoding standards are used throughout. Integers are sent as 4 byte objects, where the most significant byte is sent first, and the least signifcant byte is sent last. (i.e., standard Internet network byte order.) Protocol data units (PDU's) are sent across using the following encoding. First, the size of the PDU is sent as a 4 byte integer, followed by the PDU itself. PDU's used by the protocol will be either a KRB_AP_REQ message, a KRB_AP_REP message, a "command request" PDU, or a "command response" PDU. (The last two PDU's are encoded using a KRB_PRIV message. For definitions of the KRB_AP_REQ, KRB_AP_REP, and KRB_PRIV message, see the Kerberos V5 protocol specification found in RFC 1510.) The PDU's which are encoded using the KRB_PRIV message must include the sequence number field --- the client and server must fill in each successive PDU that it sends with a monotonically increasing sequence number. The initial sequence number in each direction are negotiated in the KRB_AP_REQ and KRB_AP_REP messages. The size of a Protoocl Data Unit SHOULD not exceed 16,384 bytes. If an implementation receives a PDU which is larger that 16,384 bytes, the implementation MAY consider this a fatal error and terminate the TCP connection. An implementation MUST be able to receive PDU's of at least 16,384 bytes. The "command request" PDU ------------------------- The "command request" PDU is sent from the client to server. This PDU uses the following structure: First, the number of arguments, sent across as an integer. The number of arguments MUST be greater than zero. It is then followed by the arguments themselves, which are encoded as an integer length followed by the value of the argument. The first argument is "command name". The command name is a NETASCII string, and it may not contain an ASCII null. Command names are case insentive. Valid command names are defined below; any site-, or vendor- specific extensions to this protocol should use command names which begin with the letter 'X'. The other arguments (if any) are dependent on the command specified by the first argument. In other words: Number of Arguments (integer, must be greater than zero) Arg size 1 (integer) Arg data 1 (octet string, command name) ... Arg size N (integer) Arg data N (octet string) This structure is then encrypted using the Kerberos V5 KRB_PRIV message. The "command reply" PDU ----------------------- In response to a "command request" PDU, the server will send to the client a "command reply" PDU. The structure of a "command reply" PDU is as follows: status code (integer) Number of reply components (integer, may be zero) Arg size 1 (integer) Arg data 1 (octet string) ... Arg size N (integer) Arg data N (octet string) This structure is then encrypted using the Kerberos V5 KRB_PRIV message. The status code may be one of the following values: # Symbolic name Meaning 0 SUCCESS The command was executed without any errors 1 CMD_UNKNOWN Command not recognized 2 PW_UNACCEPT The password chosen by the user is unnacceptable. 3 BAD_PW The old password furnished by the user is not correct. 4 NOT_IN_TKT The ticket used to authenticate to the server did not have the TKT_FLAG_INITIAL flag set. 5 CANT_CHANGE The server is not able to change the password due to no fault of the user. (For example, the database may be in read-only mode for maintance reasons.) 6 LANG_NOT_SUPPORTED The requested language is not supported. The error codes below 127, and above 256 are reserved for future expansion. Local extensions of this protocol should use error codes between 128 and 255. The user text in the reply message is generally some sort of explanatory text, which should be displayed to the user. Connection Establishment ======================== When a connection is made the password changing client exchanges the following PDU's: Client Server ------ ------ KRB_AP_REQ -------> <------- KRB_AP_REP KRB_AP_REQ and KRB_AP_REP are the respective Kerberos V5 messages. The client will autenticate to the server using the service name changepw/<REALMNAME>@<REALMNAME>, where <REALMNAME> should be substituted with the name of the Kerberos realm of the password changing server. The client MUST set the MUTUAL-REQUIRED flag in the KRB_AP_REQ message, which indicates that server shall send a KRB_AP_REP message for the purposes of establishing mutual authentication between the client and the server. Protocol Commands ================== After the connection is established, the client may then send any number of "command request" PDUs; after each command request PDU is sent, the client should wait for a "command reply" PDU from the server. If after 30 seconds inactivity, the client does not send a "command request" PDU, the server MAY elect to terminate the TCP connection. The following commands defined in this standard: QUIT CHECKPW CHANGEPW MOTD (*) MIME (*) LANGUAGE (*) The commands marked with a (*) are optional; servers may or may not elect to support these commands. If the commands are not supported, the server shall return a status code of CMD_UNKNOWN. The quit command ---------------- The name of this command is "QUIT", and it takes no arguments. The response to this command must be the error code "NO_ERROR". There may be an optional reply component, which will consist of user text which should be displayed to the user. After processing this command, the server will terminate the connection. Kerberos password changing servers MUST implement this command. The check password command --------------------------- The name of this command is "CHECKPW", and it takes one argument, which is a proposed password. The server will evaluate this password according to its criteria and return either an NO_ERROR or PW_UNACCEPT error code. There may be an optional reply component which consists of user text which should be displayed to the user. It will typically explain why the password was unacceptable. Kerberos password changing servers MUST implement this command. The change password command --------------------------- The name of this command is "CHANGEPW", and it takes two arguments. The first argument is the old password, and the second password is the new password. The response from this command will generally be one of the following error codes: NO_ERROR, PW_UNACCEPT, BAD_PW, NOT_IN_TKT, CANT_CHANGE. This command changes the password of the Kerberos principal which the client used to authenticate to the server. For security reasons, the server should check to make sure that the ticket used to authenticate to the server had the TKT_FLG_INITIAL flag set; if this flag is not set in the ticket, then when the client attempts to use the "CHANGEPW" command, the server should return the NOT_IN_TKT error. There may be an optional reply component which consists of user text which should be displayed to the user, explaining why the password was unacceptable or why the user's password could not be changed. Kerberos password changing servers MUST implement this command. The Message of the Day command ------------------------------ The name of this command is "MOTD", and it takes zero or one additional arguments. The optional argument is a magic token passed back from a previous MOTD command. If this magic token is sent, the server MAY use it to determine use it to determine what (if any) messages should be displayed to the user. This command returns one or two reply components. The first reply component is a magic token; the magic token shall be a NETASCII string which may not contain an ASCII null character, and its length shall be less than 64 characters. A client MAY store this magic token between invocations of the client, and send it to the server the next time the MOTD command is requested. The second (optional) reply component contains text which should be displayed to the user. Kerberos password changing servers MAY optionally implement this command. The MIME command ---------------- The name of this command is "MIME", and it takes zero additional arguments. This command indicates that the client is willing to accept MIME-enhanced textual messages in place of the standard NETASCII textual messages. If this command is not sent, the server MUST send all textual messages using NETASCII, with <CR><LF> used as a line breaks, and line lengths no more than 80 characters. If this command is sent, and the server returns a status code of SUCCESS, the server MUST send textual messages as MIME-enhanced textual messages. The server may refuse to send MIME messages by sending a status code of CMD_UNKNOWN. Kerberos password changing servers MAY optionally implement this command. The Language Command --------------------- The name of this command is "LANGUAGE", and it takes one additional argument, which indicates the language that the textual messages should be sent back in. This additional argument must be consist of NETASCII characters, with ASCII nulls not allowed. The argument shall be case insensitive. What constitute valid arguments to this command are a local matter. [Since ISO apparently doesn't have a standard way of referring to different languages or dialects.] This command indicates that the client would prefer that textual messages be sent back using the requested language. If the server does not support the requested language, the server may refuse the request by sending the error code LANG_NOT_SUPPORTED. Kerberos password changing servers MAY optionally implement this command.
