summaryrefslogtreecommitdiff
path: root/doc/specs/std-agent-id.raw
diff options
context:
space:
mode:
Diffstat (limited to 'doc/specs/std-agent-id.raw')
-rw-r--r--doc/specs/std-agent-id.raw95
1 files changed, 95 insertions, 0 deletions
diff --git a/doc/specs/std-agent-id.raw b/doc/specs/std-agent-id.raw
new file mode 100644
index 00000000..d5fbdd56
--- /dev/null
+++ b/doc/specs/std-agent-id.raw
@@ -0,0 +1,95 @@
+PAM working group ## A.G. Morgan
+
+## $Id$ ##
+
+## Pluggable Authentication Modules ##
+
+## REGISTERED AGENTS AND THEIR AGENT-ID'S ##
+
+#$ Purpose of this document
+
+#$$#{definition} Definition of an agent-id
+
+The most complete version of a "PAM agent-id" is contained in this
+reference [#$R#{PAM_RFC2}]. A copy of a recent definition is
+reproduced here for convenience. The reader is recommended to consult
+reference [#{PAM_RFC2}] for definitions of other terms that are
+used in this document.
+
+## -------------- ##
+
+The agent_id is a sequence of characters satisfying the following
+regexp:
+
+ /^[a-z0-9\_]+(@[a-z0-9\_.]+)?$/
+
+and has a specific form for each independent agent.
+
+o Agent_ids that do not contain an at-sign (@) are to be considered as
+ representing some authentication mode that is a "public
+ standard". Registered names MUST NOT contain an at-sign (@).
+
+o Anyone can define additional agents by using names in the format
+ name@domainname, e.g. "ouragent@example.com". The part following
+ the at-sign MUST be a valid fully qualified internet domain name
+ [RFC-1034] controlled by the person or organization defining the
+ name. (Said another way, if you control the email address that
+ your agent has as an identifier, they you are entitled to use
+ this identifier.) It is up to each domain how it manages its local
+ namespace.
+
+## -------------- ##
+
+#$ Registered agent-id's
+
+The structure of this section is a single subsection for each
+registered agent-id. This section includes a full definition of binary
+prompts accepted by the agent and example responses of said
+agent. Using the defining section alone, it should be possible for a
+third party to create a conforming agent and modules that can
+interoperate with other implementations of these objects.
+
+*$ "userpass" - the user+password agent
+
+Many legacy authentication systems are hardcoded to support one and
+only one authentication method. Namely,
+
+ username: joe
+ password: <secret>
+
+Indeed, this authentication method is often embedded into parts of the
+transport protocol. The "user+password" agent with PAM agent-id:
+
+ "userpass"
+
+Is intended to support this legacy authentication scheme. The protocol
+for binary prompt exchange with this 'standard agent' is as follows:
+
+Case 1: module does not know the username, but expects the agent to
+ obtain this information and also the user's password:
+
+ module: {LENGTH;PAM_BP_SELECT;userpass;'/'}
+ agent: {}
+
+Case 2: module has suggested username, but would like agent to confirm
+ it and gather password:
+
+ module: {}
+ agent: {}
+
+Case 3: module knows username and will not permit the agent to change it:
+
+ module: {}
+ agent: {}
+
+#$ References
+
+[#{PAM_RFC2}] Internet draft, "Pluggable Authentication Modules
+ (PAM)", available here:
+
+# http://linux.kernel.org/pub/linux/libs/pam/pre/doc/current-draft.txt #
+
+#$ Author's Address
+
+Andrew G. Morgan
+Email: morgan@kernel.org