From: Theodore Tso Date: Fri, 5 May 1995 16:59:09 +0000 (+0000) Subject: Moved kadmin.protocol and kpasswd.protocol to the kadmin directory X-Git-Tag: krb5-1.0-beta5~14 X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=ca0263d3b2b9de7a9791be9f24445bc1376649aa;p=krb5.git Moved kadmin.protocol and kpasswd.protocol to the kadmin directory git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@5739 dc483132-0cff-0310-8789-dd5450dbe970 --- diff --git a/doc/.Sanitize b/doc/.Sanitize index a39bce2a7..3c6228b79 100644 --- a/doc/.Sanitize +++ b/doc/.Sanitize @@ -33,8 +33,6 @@ api implement install.texi kadmin -kadmin.protocol -kpasswd.protocol krb5-protocol old-V4-docs texinfo.tex diff --git a/doc/kadmin.protocol b/doc/kadmin.protocol deleted file mode 100644 index e534d3955..000000000 --- a/doc/kadmin.protocol +++ /dev/null @@ -1,273 +0,0 @@ - -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 - - name of new principal - - 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 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 - - original name - - 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 - - name of principal - - 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 to change password for - - 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 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 - - 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 - - name of next principal in database - - 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 to extract for - - 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 - - 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 . -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 New password. - (SR) KVNO Key version number. - (SR) MAXLIFE The maximum lifetime of tickets for - this principal in seconds. - (SR) MAXRENEWLIFE The maximum renewable lifetime of - tickets for this principal in seconds. - (SR) EXPIRATION When the new principal expires. - (SR) PWEXPIRATION When the password expires for this - principal. - (SR) RANDOMKEY Specifies that this is to have a - random key generated for it. - (SR) FLAGS Specifies flag value for this - principal's attributes field in the - database. - (SR) SALTTYPE Comma-separated list of salt types - supported for this principal. See - note below. - (R) MKVNO Master key version number. - (R) LASTPWCHANGE Last time of password change. - (R) LASTSUCCESS Last successful password entry. - (R) LASTFAILED Last failed password attempt. - (R) FAILCOUNT Number of failed password attempts. - (R) MODNAME Principal name who performed last - modification. - (R) MODDATE 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. - diff --git a/doc/kpasswd.protocol b/doc/kpasswd.protocol deleted file mode 100644 index 9fef56572..000000000 --- a/doc/kpasswd.protocol +++ /dev/null @@ -1,299 +0,0 @@ - - - - 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/@, where 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 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. -