Things-to-keep:
-cli.func-spec
+kpasswd.protocol
+kadmin.protocol
Things-to-lose:
+++ /dev/null
-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"
--- /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