From: Theodore Tso Date: Fri, 5 May 1995 17:00:10 +0000 (+0000) Subject: Moved kadmin.protocol and kpasswd.protocol files to the doc/kadmin directory X-Git-Tag: krb5-1.0-beta5~12 X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=5dfee43bb2db36b8ec921b2490b01d40c36e7c01;p=krb5.git Moved kadmin.protocol and kpasswd.protocol files to the doc/kadmin directory Removed old OV cli functional specification git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@5741 dc483132-0cff-0310-8789-dd5450dbe970 --- diff --git a/doc/kadmin/.Sanitize b/doc/kadmin/.Sanitize index 5136af5fc..148fae1be 100644 --- a/doc/kadmin/.Sanitize +++ b/doc/kadmin/.Sanitize @@ -23,7 +23,8 @@ Do-first: Things-to-keep: -cli.func-spec +kpasswd.protocol +kadmin.protocol Things-to-lose: diff --git a/doc/kadmin/cli.func-spec b/doc/kadmin/cli.func-spec deleted file mode 100644 index 1f336cbfd..000000000 --- a/doc/kadmin/cli.func-spec +++ /dev/null @@ -1,388 +0,0 @@ -kadmin [-r _realm_] [[-p _principal_] [-k _keytab_]] [-q _query_] - - If given the -p option, kadmin will use the specified - principal to authenticate. If the -p option is not given, - kadmin will default appending "/admin" to the first component - of the default principal of the default credentials cache. If - the default credentials cache does not exist, then kadmin will - default to $USER/admin (if the environment variable USER is - set). If $USER is not set, then the first component of the - principal will be the username as obtained from - getpwnam(getuid()). If given -k, kadmin will not prompt for a - password, but rather use the specified keytab. Also, if the - -k option is given, the default principal will be the - host/hostname. If -r is present, then kadmin will use the - specified realm as the default database realm rather than the - default realm for the local machine. Upon starting up, kadmin - will prompt for a password (unless the -k option has been - given). The program will then obtain tickets for - ovsec_admin/admin in the default realm (unless -r has been - specified, in which case it will use the specified realm). - The ticket is stored in a separate ccache. The lifetime for - these tickets is 5 minutes. - - The -q option allows the passing of a request directly to - kadmin, which will then exit. This can be useful for writing - scripts. The query provided must be quoted as a single - argument to the program if there is more than one word in it. - -DATE FORMAT - Various commands in kadmin can take a variety of date formats, - specifying durations or absolute times. Examples of valid - formats are: - - 1 month ago - 2 hours ago - 400000 seconds ago - last year - last Monday - yesterday - a fortnight ago - 3/31/92 10:00:07 PST - January 23, 1987 10:05pm - 22:00 GMT - - Dates which do not have the "ago" specifier default to being - absolute dates, unless they appear in a field where a duration - is expected. In that case the time specifier will be - interpreted as relative. Specifying "ago" on a duration may - result in unexpected behaviour. The format follows that of - the public-domain "getdate" package. All date parameters must - be provided as a single word, which means that they must be - double-quoted if there are any spaces. - -COMMAND DESCRIPTIONS - -add_principal [options] _newprinc_ - creates the principal _newprinc_, prompting twice for a - password. This command requires the "add" privilege. This - command has the aliases "addprinc", "ank". - - OPTIONS - -expire _expdate_ - expiration date of the principal - - -pwexpire _pwexpdate_ - password expiration date - - -maxlife _maxlife_ - maximum ticket life of the principal - - -kvno _kvno_ - explicity set the key version number. This is not - recommended. - - -policy _policy_ - policy used by this principal. If no policy is - supplied, the principal will default to having no - policy, and a warning message will be printed. - - {-|+}allow_tgs_req - "-allow_tgs_req" specifies that a TGS request for a - ticket for a service ticket for this principal is not - permitted. This option is useless for most things. - "+allow_tgs_req" clears this flag. The default is - "+allow_tgs_req". In effect, "-allow_tgs_req" sets - the KRB5_KDB_DISALLOW_TGT_BASED flag on the principal - in the database. - - {-|+}allow_tix - "-allow_tix" forbids the issuance of any tickets for - this principal. "+allow_tix" clears this flag. The - default is "+allow_tix". In effect, "-allow_tix" sets - the KRB5_KDB_DISALLOW_ALL_TIX flag on the principal in - the database. - - {-|+}needchange - "+needchange" sets a flag in attributes field to force - a password change; "-needchange" clears it. The - default is "-needchange". In effect, "+needchange" - sets the KRB5_KDB_REQUIRES_PWCHANGE flag on the - principal in the database. - - {-|+}password_changing_service - "+password_changing_service" sets a flag in the - attributes field marking this as a password change - service principal (useless for most things). - "-password_changing_service" clears the flag. This - flag intentionally has a long name. The default is - "-password_changing_service". In effect, - "+password_changing_service" sets the - KRB5_KDB_PWCHANGE_SERVICE flag on the principal in the - database. - - -randkey - sets the key of the principal to a random value - - -pw _password_ - sets the key of the principal to the specified string - and does not prompt for a password. This is not - recommended. - - EXAMPLE - kadmin: addprinc tlyu/deity - WARNING: no policy specified for "tlyu/deity@ATHENA.MIT.EDU"; - defaulting to no policy. - Enter password for principal tlyu/deity@ATHENA.MIT.EDU: - Re-enter password for principal tlyu/deity@ATHENA.MIT.EDU: - Principal "tlyu/deity@ATHENA.MIT.EDU" created. - kadmin: - - ERRORS - OVSEC_KADM_AUTH_ADD (requires "add" privilege) - OVSEC_KADM_DUP (principal exists already) - OVSEC_KADM_UNK_POLICY (policy does not exist) - OVSEC_KADM_PASS_Q_* (password quality violations) - -delete_principal [-force] _principal_ - deletes the specified principal from the database. This - command prompts for deletion, unless the "-force" option is - given. This command requires the "delete" privilege. Aliased - to "delprinc". - - EXAMPLE - kadmin: delprinc testuser - Are you sure you want to delete the principal - "testuser@ATHENA.MIT.EDU"? (yes/no): yes - Principal "testuser@ATHENA.MIT.EDU" deleted. - Make sure that you have removed this principal from - all ACLs before reusing. - kadmin: - - ERRORS - OVSEC_KADM_AUTH_DELETE (reequires "delete" privilege) - OVSEC_KADM_UNK_PRINC (principal does not exist) - -modify_principal [options] _principal_ - modifies the specified principal, changing the fields as - specified. The options are as above for "add_principal", - except that password changing is forbidden by this command. - In addition, the option "-clearpolicy" will remove clear the - current policy of a principal. This command requires the - "modify" privilege. Aliased to "modprinc". - - ERRORS - OVSEC_KADM_AUTH_MODIFY (requires "modify" privilege) - OVSEC_KADM_UNK_PRINC (principal does not exist) - OVSEC_KADM_UNK_POLICY (policy does not exist) - OVSEC_KADM_BAD_MASK (shouldn't happen) - -rename_principal [-force] _old_ _new_ - rename the principal _old_ to _new_. Prompts for - confirmation, unless the "-force" option is given. Requires - both the "add" and "delete" privileges. Aliased to - "renprinc". - - EXAMPLE - kadmin: renprinc tlyutest test0 - Are you sure you want to rename the principal - "tlyutest@ATHENA.MIT.EDU" to - "test0@ATHENA.MIT.EDU"? (yes/no): yes - Principal "tlyutest@ATHENA.MIT.EDU" renamed to - "test0@ATHENA.MIT.EDU". - Make sure that you have removed "tlyutest@ATHENA.MIT.EDU" from - all ACLs before reusing. - kadmin: - - ERRORS - OVSEC_KADM_AUTH_ADD (requires "add" privilege) - OVSEC_KADM_AUTH_DELETE (requires "delete" privilege) - OVSEC_KADM_UNK_PRINC (source principal does not exist) - OVSEC_KADM_DUP (target principal already exists) - -change_password [options] _principal_ - changes the password of _principal_. Prompts for a new - password if neither -randpass or -pw is specified. Requires - the "modify" privilege, or that the principal that is running - the program to be the same as the one changed. Aliased to - "cpw". - - OPTIONS - -randkey - sets the key of the principal to a random value - - -pw _password_ - set the password to the specified string. Not - recommended. - - EXAMPLE - kadmin: cpw systest - Enter password for principal systest@ATHENA.MIT.EDU: - Re-enter password for principal systest@ATHENA.MIT.EDU: - Password for systest@ATHENA.MIT.EDU changed. - kadmin: - - ERRORS - OVSEC_KADM_AUTH_MODIFY (requires the modify privilege) - OVSEC_KADM_UNK_PRINC (principal does not exist) - OVSEC_KADM_PASS_Q_* (password policy violation errors) - OVSEC_KADM_PADD_REUSE (password is in principal's password - history) - OVSEC_KADM_PASS_TOOSOON (current password minimum life not - expired) - -get_principal [-terse] _principal_ - gets the attributes of _principal_. Requires the "get" - privilege, or that the principal that is running the the - program to be the same as the one being listed. With the - "-terse" option, outputs fields as tab-separated strings. Any - string fields get double-quoted. Alias "getprinc". - - EXAMPLES - kadmin: getprinc tlyu/deity - Principal: tlyu/deity@ATHENA.MIT.EDU - Key version: 3 - Maximum life: 1 day 00:00:00 - Maximum renewable life: 7 days 00:00:00 - Master key version: 1 - Expires: Mon Jan 18 22:14:07 EDT 2038 - Password expires: Mon Sep 19 14:40:00 EDT 1994 - Password last changed: Mon Jan 31 02:06:40 EDT 1994 - Last modified: by tlyu/admin@ATHENA.MIT.EDU - on Wed Jul 13 18:27:08 EDT 1994 - Attributes: DISALLOW_FORWARDABLE, DISALLOW_PROXIABLE, - REQUIRES_HW_AUTH - Salt type: DEFAULT - kadmin: getprinc -terse systest - "systest@ATHENA.MIT.EDU" 3 86400 604800 - 1 785926535 753241234 785900000 - "tlyu/admin@ATHENA.MIT.EDU" 786100034 0 0 - kadmin: - - ERRORS - OVSEC_KADM_AUTH_GET (requires the get privilege) - OVSEC_KADM_UNK_PRINC (principal does not exist) - -add_policy [options] _policy_ - adds the named policy to the policy database. Requires the - "add" privilege. Aliased to "addpol". - - OPTIONS - -maxlife _time_ - sets the maximum lifetime of a password - - -minlife _time_ - sets the minimum lifetime of a password - - -minlength _length_ - sets the minimum length of a password - - -minclasses _number_ - sets the minimum number of character classes allowed - in a password - - -history _number_ - sets the number of past keys kept for a principal - - ERRORS - OVSEC_KADM_AUTH_ADD (requires the add privilege) - OVSEC_KADM_DUP (policy already exists) - -delete_policy _policy_ - deletes the named policy. Prompts for confirmation before - deletion. The command will fail if the policy is in use by - any principals. Requires the "delete" privilege. Alias - "delpol". - - EXAMPLE - kadmin: del_policy guests - Are you sure you want to delete the policy "guests"? - (yes/no): yes - Policy "guests" deleted. - kadmin: - - ERRORS - OVSEC_KADM_AUTH_DELETE (requires the delete privilege) - OVSEC_KADM_UNK_POLICY (policy does not exist) - OVSEC_KADM_POLICY_REF (reference count on policy is not zero) - -modify_policy [options] _policy_ - modifies the named policy. Options are as above for - "add_policy". Requires the "modify" privilege". Alias - "modpol". - - ERRORS - OVSEC_KADM_AUTH_MODIFY (requires the modify privilege) - OVSEC_KADM_UNK_POLICY (policy does not exist) - -get_policy [-terse] _policy_ - displays the values of the named policy. Requires the "get" - privilege. With the "-terse" flag, outputs the fields as - strings separated by tabs. All string fields get - double-quoted. Alias "getpol". - - EXAMPLES - kadmin: get_policy admin - Policy: admin - Maximum password life: 180 days 00:00:00 - Minimum password life: 00:00:00 - Minimum password length: 6 - Minimum number of password character classes: 2 - Number of old keys kept: 5 - Reference count: 17 - kadmin: get_policy -terse admin - "admin" 15552000 0 6 2 5 17 - kadmin: - - ERRORS - OVSEC_KADM_AUTH_GET (requires the get privilege) - OVSEC_KADM_UNK_POLICY (policy does not exist) - -get_privs - returns the administrative privileges of the current user. - Alias "getprivs". - - EXAMPLE - kadmin: get_privs - Principal tlyu/admin@ATHENA.MIT.EDU - has privileges: GET, ADD, MODIFY, DELETE, CHSTAB - kadmin: - -OPEN POINTS - Implementation will most likely be in tcl, which implies that - scripts can be written to be run directly by kadmin. This - will require some more spec'ing out. - - get_srvtab is being pulled out into a separate program, to be - spec'ed out and documented at a later time. ----------------------------------------------------------------------------- -get_srvtab [-v4] [-file _name_] {_principal..._}|{-host _host_ _service..._} - Creates a srvtab (a krb4 srvtab if -v4 is specified). If - given a list of principals, randomizes the keys for the - principals named, creating them if necessary, and stores the - keys in the new srvtab. If -host is given, then the named service - principals are randomized/created for the named host and - placed in the new srvtab. The naming convention for the files - is hostname-new-srvtab if -host is given, overwriting anything - previously in such a file. If -host is not given, then the - filename defaults to the principal-new-srvtab, using only the - first component of the principal name. - - If the principals need to be created, the command will prompt - for confirmation. This command requires the "chstab" - privilege, and only certain service names can be obtained this - way. (The services are specified in a configuration file on - the server.) In addition, certain hosts may be excluded from - this command. The "modify" privilege is necessary in order to - use this command on arbitrary principals. - - This command is aliased to "gst" - - EXAMPLE - kadmin: get_srvtab -host dragons-lair host rvdsrv discuss - WARNING: hostname canonicalized to "dragons-lair.mit.edu" - Principal "host/dragons-lair.mit.edu@ATHENA.MIT.EDU" - updated to kvno 3. - WARNING: principal - "rvdsrv/dragons-lair.mit.edu@ATHENA.MIT.EDU" - does not exist. Create? (y/n): y - Created principal - "rvdsrv/dragons-lair.mit.edu@ATHENA.MIT.EDU". - Principal "discuss/dragons-lair.mit.edu@ATHENA.MIT.EDU" - updated to kvno 3. - Wrote keytab "WRFILE:dragons-lair-new-srvtab". - kadmin: - - ERRORS - "Operation requires the chstab privilege" - "Operation requires the modify privilege" diff --git a/doc/kadmin/kadmin.protocol b/doc/kadmin/kadmin.protocol new file mode 100644 index 000000000..e534d3955 --- /dev/null +++ b/doc/kadmin/kadmin.protocol @@ -0,0 +1,273 @@ + +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/kadmin/kpasswd.protocol b/doc/kadmin/kpasswd.protocol new file mode 100644 index 000000000..9fef56572 --- /dev/null +++ b/doc/kadmin/kpasswd.protocol @@ -0,0 +1,299 @@ + + + + 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. +