**DRAFT** **DRAFT** **DRAFT**
by Theodore Ts'o
- Februrary 15, 1994
+ March 10, 1995
Rationale
=========
Currently, the Kerberos administration server which is being shipped
-with the Beta Kerberos V5 distributions from MIT has not been
-functional and 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.
+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
is sent first, and the least signifcant byte is sent last. (i.e.,
standard Internet network byte order.)
-Protocol data units are sent across using the following encoding.
-First, the size is sent as a 4 byte integer, followed by the PDU. The
-PDU is either a Kerberos V5 KRB_AP_REQ, KRB_AP_REP, or KRB_PRIV
-message. The initial exchange use the KRB_AP_REQ and KRB_AP_REP
-message; all successive PDU's will be KRB_PRIV messages.
-
-The KRB_PRIV messages 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.
-
+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
-------------------------
-A common PDU used in the protocol is the "command request" PDU. A
-command request 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 "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", and it must be a NETASCII string
-which may not contain an ASCII null. Command names are case
-insentive. The other arguments (if any) are dependent on the command
-specified by the first 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:
Arg size N (integer)
Arg data N (octet string)
-This structure is then encrypted inside the Kerberos V5 KRB_PRIV
-message.
+This structure is then encrypted using the Kerberos V5 KRB_PRIV message.
The "command reply" PDU
-----------------------
-Another common PDU used in the protocol is the "command reply" PDU.
-It is sent in reply to a "command request" PDU. The first portion of
-the "command reply" PDU is common to all commands, and is required.
-The rest of it is command specific.
-
-It uses the following structure:
+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:
- Error code (integer)
+ 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 inside the Kerberos V5 KRB_PRIV
-message.
+This structure is then encrypted using the Kerberos V5 KRB_PRIV message.
-The error code may be one of the following values:
+The status code may be one of the following values:
# Symbolic name Meaning
-0 NO_ERROR No error
-1 PW_UNACCEPT The password chosen by the user is unnacceptable.
-2 BAD_PW The old password furnished by the user is not correct.
+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
<------- KRB_AP_REP
- <------- MOTD
-
-KRB_AP_REQ and KRB_AP_REP are the respective Kerberos V5 messages.
-
-MOTD is an KRB_PRIV message which is sent by the server to the client.
-It contains NETASCII text which is intended to be displayed to the
-user. The message may be zero length (in which case nothing should be
-displayed); the message may be user specific, or a general message, at
-the descretion of the server.
-
+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
==================
sent, the client should wait for a "command reply" PDU from the
server.
-There are three commands defined in this standard: "QUIT", "CHECKPW",
-and "CHANGEPW".
+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
----------------
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
---------------------------
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.
+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. It will typically explain why
-the password was unacceptable.
+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.
+
projects / krb5.git / commitdiff