+++ /dev/null
-
-This document references, accompanies and extends the password changing
-protocol document, "A Proposal for a Standardized Kerberos Password
-Changing Protocol" by Theodore Ts'o.
-
-Administrative Command Extensions to the Password Changing Protocol
-===================================================================
-The following commands and their accompanying definitions are an
-extension to the password changing protocol which allow remote
-administrative clients to perform functions analogous to those which
-are performed using the local database editing utility. These
-commands are encoded in the "command request" PDU described in the
-password changing protocol, and the server's responses to these
-commands are encoded in the "command reply" PDU.
-
-These commands are (optional commands are marked with an asterisk):
- ADD-PRINCIPAL
- DELETE-PRINCIPAL
- RENAME-PRINCIPAL
- MODIFY-PRINCIPAL
- OTHER-CHANGEPW
- OTHER-RANDOM-CHANGEPW
- INQUIRE-PRINCIPAL
- EXTRACT-KEY (*)
-
-In order to support these additional commands, the following additional
-status codes are also defined:
-
-Number Symbolic Name Meaning
-64 P_ALREADY_EXISTS The specified principal already exists.
-65 P_DOES_NOT_EXIST The specified principal does not exist.
-66 NOT_AUTHORIZED The access control list on the server prevents
- this operation.
-67 BAD_OPTION Either: 1) A bad option was specified; 2) A
- conflicting set of options would result from
- this operation; or 3) Existing options prevent
- this type of operation.
-68 VALUE_REQUIRED The specified option requires a value.
-69 SYSTEM_ERROR A system error occurred while processing a
- request.
-
-The add principal operation
----------------------------
-o Command String "ADD-PRINCIPAL"
-o Arguments
- <new-principal-string> - name of new principal
- <keyword-value-pair> - either "KEYWORD=value" or "KEYWORD".
- .
- .
- .
-o Returns
- SUCCESS - operation successful
- SYSTEM_ERROR - system error
- NOT_AUTHORIZED - not allowed to perform this
- P_ALREADY_EXISTS - new principal already exists
- BAD_OPTION - bad option supplied
- VALUE_REQUIRED - value required with keyword
-o Supplemental Returns
- NONE - if successful
- error message text - if failure
-o Description
- If the specified principal does not exist, the arguments parse
- correctly, and the arguments when combined with defaulted values
- do not produce a conflicting set of options then add the specified
- principal with the specified attributes. See below for the list of
- settable attributes.
-o Access Required
- Client principal must have ADD_PRINCIPAL permission.
-
-The delete principal operation
-------------------------------
-o Command String "DELETE-PRINCIPAL"
-o Argument
- <principal-string> - principal to delete
-o Returns
- SUCCESS - operation successful
- SYSTEM_ERROR - system error
- NOT_AUTHORIZED - not allowed to perform this
- P_DOES_NOT_EXIST - old principal does not exist
-o Supplemental returns
- NONE - if successful
- error message text - if failure
-o Description
- If the specified principal exists, then delete it from the database.
-o Access Required
- Client principal must have DELETE_PRINCIPAL permission.
-
-The rename principal operation
-------------------------------
-o Command String "RENAME-PRINCIPAL"
-o Arguments
- <orig-principal-string> - original name
- <new-principal-string> - new name
-o Returns
- SUCCESS - operation successful
- SYSTEM_ERROR - system error
- NOT_AUTHORIZED - not allowed to perform this
- P_DOES_NOT_EXIST - old principal does not exist
- P_ALREADY_EXISTS - new principal already exists
-o Supplemental Returns
- NONE - if successful
- error message text - if failure
-o Description
- If the original principal exists and the new principal name does not
- exist, rename the original principal to the specified name.
-o Access Required
- Client principal must have ADD_PRINCIPAL and DELETE_PRINCIPAL
- permission.
-
-The modify principal operation
-------------------------------
-o Command String "MODIFY-PRINCIPAL"
-o Arguments
- <principal-string> - name of principal
- <keyword-value-pair> - either KEYWORD=value or KEYWORD.
- .
- .
- .
-o Returns
- SUCCESS - operation successful
- SYSTEM_ERROR - system error
- NOT_AUTHORIZED - not allowed to perform this
- P_DOES_NOT_EXIST - principal doesn't exist
- BAD_OPTION - bad option supplied
- VALUE_REQUIRED - value required with keyword
-o Supplemental returns
- NONE - if successful
- error message text - if failure
-o Description
- If the specified principal exists, the arguments parse correctly, and
- the arguments when combined with existing values do not produce a
- conflicting set of options, then modify the specified principal with
- the specified attributes. See below for the list of settable
- attributes.
-o Access Required
- Client principal must have MODIFY_PRINCIPAL permission.
-
-The change password operation
------------------------------
-o Command String "OTHER-CHANGEPW"
-o Arguments
- <principal-string> - principal to change password for
- <new-password> - new password
-o Returns
- SUCCESS - operation successful
- PW_UNACCEPT - specified password is bad
- SYSTEM_ERROR - system error
- NOT_AUTHORIZED - not allowed to perform this
- P_DOES_NOT_EXIST - old principal does not exist
- BAD_OPTION - principal has a random key
-o Supplemental returns
- NONE - if successful
- error message text - if failure
-o Description
- If the specified principal exists, and does not have a random key,
- then change the password to the specified password. The original
- password is NOT required.
-o Access Required
- Client principal must have CHANGEPW permission.
-
-The change random password command
-----------------------------------
-o Command String "OTHER-RANDOM-CHANGEPW"
-o Argument
- <principal-string> - principal to change password for
-o Returns
- SUCCESS - operation successful
- SYSTEM_ERROR - system error
- NOT_AUTHORIZED - not allowed to perform this
- P_DOES_NOT_EXIST - old principal does not exist
- BAD_OPTION - principal does not have a random key
-o Supplemental Returns
- NONE - if successful
- error message text - if failure
-o Description
- If the specified principal exists, and has a random key, then
- generate a new random password. The original password is NOT
- required.
-o Access Required
- Client principal must have CHANGEPW permission.
-
-The inquire principal command
------------------------------
-o Command String "INQUIRE-PRINCIPAL"
-o Argument
- <principal-string> - name of principal or null argument
-o Returns
- SUCCESS - operation successful
- SYSTEM_ERROR - system error
- NOT_AUTHORIZED - not allowed to perform this
- P_DOES_NOT_EXIST - principal doesn't exist
-o Supplemental Returns
- If the return is SUCCESS
- <next-principal-string> - name of next principal in database
- <keyword-value-pair> - KEYWORD=value list
- .
- .
- .
- Otherwise
- error message text - if failure
-o Description
- If a principal is specified, then the database is searched for that
- particular principal and its attributes are returned as keyword-value
- pairs. If no principal is specified, then the first database entry
- is returned. The name of the next principal in the database is always
- returned to allow for scanning. See below for the list of attributes
- that can be returned.
-o Access Required
- Client principal must have INQUIRE_PRINCIPAL permission.
-
-The OPTIONAL extract service key table entry command
-----------------------------------------------------
-o Command String "EXTRACT-KEY"
-o Arguments
- <instance-string> - instance to extract for
- <name-string> - name to extract for
-o Returns
- SUCCESS - operation successful
- CMD_UNKNOWN - operation not supported by server
- SYSTEM_ERROR - system error
- NOT_AUTHORIZED - not allowed to perform this
- P_DOES_NOT_EXIST - principal does not exist
-o Supplemental Returns
- <octet-string> - if successful
- error message text - if failure
-o Description
- If the specified name/instance exists in the database, then
- extract the service key entry and return it in <octet-string>.
-o Access Required
- Client principal must have EXTRACT permission.
-
-Keywords
---------
-The following list of keywords are used for the ADD-PRINCIPAL and
-MODIFY-PRINCIPAL commands and are returned from the
-INQUIRE-PRINCIPAL command.
-
-Valid Keyword Value Type Value
-------- --------------- --------------- --------------------------------------
- (S) PASSWORD <string> New password.
- (SR) KVNO <integer> Key version number.
- (SR) MAXLIFE <integer> The maximum lifetime of tickets for
- this principal in seconds.
- (SR) MAXRENEWLIFE <integer> The maximum renewable lifetime of
- tickets for this principal in seconds.
- (SR) EXPIRATION <general-time> When the new principal expires.
- (SR) PWEXPIRATION <general-time> When the password expires for this
- principal.
- (SR) RANDOMKEY <integer> Specifies that this is to have a
- random key generated for it.
- (SR) FLAGS <integer> Specifies flag value for this
- principal's attributes field in the
- database.
- (SR) SALTTYPE <string> Comma-separated list of salt types
- supported for this principal. See
- note below.
- (R) MKVNO <integer> Master key version number.
- (R) LASTPWCHANGE <general-time> Last time of password change.
- (R) LASTSUCCESS <general-time> Last successful password entry.
- (R) LASTFAILED <general-time> Last failed password attempt.
- (R) FAILCOUNT <integer> Number of failed password attempts.
- (R) MODNAME <string> Principal name who performed last
- modification.
- (R) MODDATE <general-time> Last modification date.
-
-The valid field indicates whether an attribute is Settable (e.g. appropriate
-for use with ADD-PRINCIPAL, et. al.; Returnable (e.g. returned by
-INQUIRE-PRINCIPAL); or both Settable and Returnable.
-
-Note: The value for SALTTYPE is a comma-separated list of strings. The
-individual values for these may be either "KRB5" or "KRB4" or a site-specific
-value.
-
+++ /dev/null
-
-
-
- A Proposal for a Standardized
- Kerberos Password Changing Protocol
-
- **DRAFT** **DRAFT** **DRAFT**
-
- by Theodore Ts'o
- March 10, 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 XXX.
-
-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.
-
projects / krb5.git / commitdiff