Add new document describing kadmin extensions to admin protocol

git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@5639 dc483132-0cff-0310-8789-dd5450dbe970
author: Paul Park <pjpark@mit.edu> 1995-04-28 21:00:51 +0000
committer: Paul Park <pjpark@mit.edu> 1995-04-28 21:00:51 +0000
commit: e471d4a28c3fe78af4de414265657f5502495387 (patch)
tree: 594dafb16bf8b9a10807386f54f7a7f659b36b22
parent: 3af80e14f21e908adacd47e31e29d68d7a45e17d (diff)
download: krb5-e471d4a28c3fe78af4de414265657f5502495387.tar.gz
krb5-e471d4a28c3fe78af4de414265657f5502495387.tar.xz
krb5-e471d4a28c3fe78af4de414265657f5502495387.zip
3 files changed, 278 insertions, 0 deletions
diff --git a/doc/.Sanitize b/doc/.Sanitize
index e2fcb3f51c..a39bce2a73 100644
--- a/doc/.Sanitize
+++ b/doc/.Sanitize
@@ -33,6 +33,7 @@ api
 implement
 install.texi
 kadmin
+kadmin.protocol
 kpasswd.protocol
 krb5-protocol
 old-V4-docs
diff --git a/doc/ChangeLog b/doc/ChangeLog
index 1a38ba0117..b525eec868 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,7 @@
+
+Fri Apr 28 16:59:41 EDT 1995	Paul Park	(pjpark@mit.edu)
+	Add new kadmin.protocol.
+
 Wed Feb 22 18:56:06 1995  John Gilmore  (gnu at toad.com)
 
 	* install.texi:  Minor corrections.  Add info about bare source
diff --git a/doc/kadmin.protocol b/doc/kadmin.protocol
new file mode 100644
index 0000000000..e534d39555
--- /dev/null
+++ b/doc/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
+	<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.
+
author	Paul Park <pjpark@mit.edu>	1995-04-28 21:00:51 +0000
committer	Paul Park <pjpark@mit.edu>	1995-04-28 21:00:51 +0000
commit	e471d4a28c3fe78af4de414265657f5502495387 (patch)
tree	594dafb16bf8b9a10807386f54f7a7f659b36b22
parent	3af80e14f21e908adacd47e31e29d68d7a45e17d (diff)
download	krb5-e471d4a28c3fe78af4de414265657f5502495387.tar.gz krb5-e471d4a28c3fe78af4de414265657f5502495387.tar.xz krb5-e471d4a28c3fe78af4de414265657f5502495387.zip