build: Better Build System

1 files changed, 373 insertions, 0 deletions

diff --git a/static/plan9-4e/man6/authsrv.6 b/static/plan9-4e/man6/authsrv.6
new file mode 100644
index 00000000..2638f631
--- /dev/null
+++ b/static/plan9-4e/man6/authsrv.6
@@ -0,0 +1,373 @@
+.TH AUTHSRV 6
+.SH NAME
+ticket \- authentication service
+.SH DESCRIPTION
+This manual page describes
+the protocols used to authorize connections, confirm the identities
+of users and machines, and maintain the associated databases.
+The machine that provides these services is called the
+.I authentication server
+(AS).
+The AS may be a stand-alone machine or a general-use machine such as a CPU server.
+The network database
+.IR ndb (6)
+holds for each public machine, such as a CPU server or
+file server, the name of the authentication server that machine uses.
+.PP
+Each machine contains three values important to authentication; a 56-bit DES
+key, a 28-byte authentication ID, and a 48-byte authentication domain name.
+The ID is a user name and identifies who is currently responsible for the
+kernel running on that machine.
+The domain name identifies the machines across which the ID is valid.
+Together, the ID and domain name identify the owner of a key.
+.PP
+When a terminal boots, the user is prompted for user name and password.
+The user name becomes the terminal's authentication ID. 
+The password is converted using
+.I passtokey
+(see
+.IR auth (2))
+into a 56-bit DES key and saved as the machine's key.
+The authentication domain is set to the null string.
+If possible, the terminal validates the key with the AS
+before saving it.
+For Internet machines the correct AS to ask is found using
+.IR dhcpd (8).
+.PP
+When a CPU or file server boots, it reads the key, ID, and domain name from
+non-volatile RAM.
+This allows servers to reboot without operator intervention.
+.PP
+The details of any authentication are mixed with the semantics
+of the particular service they are authenticating so we describe
+them one case at a time. The following definitions will be used
+in the descriptions:
+.TF nullx
+.TP
+.I \fICHc\fP
+an 8-byte random challenge from a client
+.TP
+.I CHs
+an 8-byte random challenge from a server
+.TP
+.I \fIKs\fP
+server's key
+.TP
+.I \fIKc\fP
+client's key
+.TP
+.I \fIKn\fP
+a nonce key created for a ticket
+.TP
+.I K\fP\fIm\fP
+message m
+encrypted with key K
+.TP
+.I \fIIDs\fP
+server's ID
+.TP
+.I \fIDNs\fP
+server's authentication domain name
+.TP
+.I \fIIDc\fP
+client's ID
+.TP
+.I \fIUIDc\fP
+user's name on the client
+.TP
+.I \fIUIDs\fP
+user's name on the server
+.PD
+.PP
+A number of constants defined in
+.B auth.h
+are also used:
+.IR AuthTreq,
+.IR AuthChal,
+.IR AuthOK,
+.IR AuthErr,
+.IR AuthTs,
+.IR AuthTc,
+.IR AuthAs,
+and
+.IR AuthAc .
+.SS "File Service"
+File service sessions are long-lived connections between a client host
+and a file server.
+Processes belonging to different users share the session.
+Whenever a user process on the client
+.I mounts
+a file server
+(see
+.IR bind (2)),
+it must authenticate itself.
+There are four players in an authentication: the server, the client kernel,
+the user process on the client, and the authentication server.
+The goal of the authentication protocol is to convince the server
+that the client may validly speak for the user process.
+.PP
+To reduce the number of messages for each authentication,
+common information is exchanged once at the
+beginning of the session within a
+.I session
+message
+(see
+.IR attach (5)):
+.TF "Client→Server"
+.TP
+.IR Client → Server
+Tsession( \fICHc\fP )
+.TP
+.IR Server → Client
+Rsession( \fICHs\fP, \fIIDs\fP, \fIDNs\fP )
+.PD
+.PP
+Each time a user mounts a file server connection, an attach
+message is sent identifying/authenticating the user:
+.TF "Client→Server"
+.TP
+.IR Client → Server
+Tattach( \fIKs\fP{ \fIAuthTs\fP, \fICHs\fP, \fIUIDc\fP, \fIUIDs\fP, \fIKn\fP }, \fIKn\fP{ \fIAuthAc\fP, \fICHs\fP, \fIcount\fP } )
+.TP
+.IR Server → Client
+Rattach( \fIKn\fP{ AuthAs, \fICHc\fP, \fIcount\fP } )
+.PD
+.PP
+The part of the attach request encrypted with
+.BR \fIKs\fP
+is called a
+.IR ticket .
+Since it is encrypted in the server's secret key, this message is guaranteed
+to have originated on the AS.
+The part encrypted with the
+.B \fIKn\fP
+found in the ticket is called an
+.IR authenticator .
+The authenticator is generated by the client kernel and guarantees that
+the ticket was not stolen.
+The
+.I count
+is incremented with each mount to make every authenticator unique,
+thus foiling replay attacks.
+The server is itself authenticated by the authenticator
+it sends as a reply to the attach.
+.PP
+Tickets are created by the AS at the request of a user process.
+The AS contains a database of which \fIIDc\fP's may speak for which \fIUIDc\fP's.
+If the \fIIDc\fP may speak for the \fIUIDc\fP, two tickets are returned.
+.TF "UserProc→AS"
+.TP
+.IR UserProc → AS
+\fIAuthTreq\fP, \fICHs\fP, \fIIDs\fP, \fIDNs\fP, \fIIDc\fP, \fIUIDc\fP
+.TP
+.IR AS → UserProc
+\fIAuthOK\fP, \fIKc\fP{ \fIAuthTc\fP, \fICHs\fP, \fIUIDc\fP, \fIUIDs\fP, \fIKn\fP }, \fIKs\fP{ \fIAuthTs\fP, \fICHs\fP, \fIUIDc\fP, \fIUIDs\fP, \fIKn\fP }
+.PD
+.PP
+Otherwise an error message is returned.
+.TF "UserProc→AS"
+.TP
+.IR AS → UserProc
+\fIAuthErr\fP, 64-byte error string
+.PD
+.PP
+The user passes both tickets to the client's kernel using
+the
+.I fauth
+system call
+(see
+.IR fauth (2)).
+The kernel decrypts the ticket encrypted with \fIKc\fP.
+If \fIUIDc\fP
+matches the user's login ID, the tickets are remembered for
+any subsequent attaches by that user of that file server session.
+Otherwise, the ticket is assumed stolen and an error is returned.
+.SS "Remote Execution"
+.PP
+A number of applications require a process on one machine to start
+a process with the same user ID on a server machine.
+Examples are
+.IR cpu (1),
+.I rx
+(see
+.IR con (1)),
+and
+.IR exportfs (4).
+The called process replies to the connection with a ticket request.
+.TF "Server→UserProc"
+.TP
+.IR Server → UserProc
+\fIAuthTreq\fP, \fICHs\fP, \fIIDs\fP, \fIDNs\fP, xxx, xxx
+.PD
+.PP
+Here
+.I xxx
+indicates a field whose contents do not matter.
+.PP
+The calling process adds its machine's \fIIDc\fP and its \fIUIDc\fP to the request
+and follows the protocol outlined above to get two tickets from the AS.
+The process passes the
+\fIKs\fP
+encrypted ticket plus an authenticator generated by
+.B /dev/authenticator
+from the 
+\fIKc\fP
+ticket to the remote server, which writes them to the
+kernel to set the user ID (see 
+.IR cons (3)).
+The server replies with its own authenticator which can be written
+to the kernel along with the
+\fIKc\fP
+encrypted ticket to confirm the server's identity (see
+.IR cons (3)).
+.TF "UserProc→Server"
+.TP
+.IR UserProc → Server
+\fIKs\fP{ \fIAuthTs\fP, \fICHs\fP, \fIUIDc\fP, \fIUIDs\fP, \fIKn\fP }, \fIKn\fP{ \fIAuthAc\fP, \fICHs\fP, 0 } 
+.TP
+.IR Server → UserProc
+\fIKn\fP{ \fIAuthAs\fP, \fICHs\fP, 0 }
+.PD
+.SS "Challenge Box"
+A user may also start a process on a CPU server from a non Plan 9
+machine using commands such as
+.IR con,
+.IR telnet,
+or
+.I ftp
+(see
+.IR con (1)
+and
+.IR ftpfs (4)).
+In these situations, the user can authenticate using a hand-held
+DES encryptor.
+The telnet or FTP daemon first sends a ticket request to the
+authentication server.
+If the AS has keys for both the \fIIDc\fP and \fIUIDc\fP in the ticket
+request it returns a challenge as a hexadecimal number.
+.TF "Daemon→AS"
+.TP
+.IR Daemon → AS
+\fIAuthChal\fP, \fICHc\fP, \fIIDc\fP, \fIDNs\fP, \fIIDc\fP, \fIUIDc\fP 
+.TP
+.IR AS → Daemon
+\fIAuthOK\fP, 16-byte
+.SM ASCII
+challenge
+.PD
+.PP
+Otherwise, it returns a null-terminated 64-byte error string.
+.TF "Daemon→AS"
+.TP
+.IR AS → Daemon
+\fIAuthErr\fP, 64-byte error string
+.PD
+.PP
+The daemon relays the challenge to the calling program,
+which displays the challenge on the user's screen.
+The user encrypts it and types in the
+result, which is relayed back to the AS.
+The AS checks it against the expected response and returns
+either a ticket or an error.
+.TF "Daemon→AS"
+.TP
+.IR Daemon → AS
+16-byte
+.SM ASCII
+response
+.TP
+.IR AS → Daemon
+\fIAuthOK\fP, \fIKc\fP{ \fIAuthTs\fP, \fICHc\fP, \fIUIDc\fP, \fIUIDc\fP, \fIKn\fP }
+.PD
+.PP
+or
+.TF "Daemon→AS"
+.TP
+.IR AS → Daemon
+\fIAuthErr\fP, 64-byte error string
+.PD
+.PP
+Finally, the daemon passes the ticket to the kernel
+to set the user ID (see
+.IR cons (3)).
+.SS "Password Change"
+Any user can change the key stored for him or her on the AS.
+Once again we start by passing a ticket request to the AS.
+Only the user ID in the request is meaningful.
+The AS replies with a single ticket (or an error message)
+encrypted in the user's personal key.
+The user encrypts both the old and new keys with the
+\fIKn\fP from the returned ticket and sends that back to the AS.
+The AS checks the reply for validity and replies with an
+\fIAuthOK\fP byte or an error message.
+.TF "UserProc→AS"
+.TP
+.IR UserProc → AS
+\fIAuthPass\fP, xxx, xxx, xxx, xxx, \fIUIDc\fP
+.TP
+.IR AS → UserProc
+\fIAuthOK\fP, \fIKc\fP{ \fIAuthTp\fR, xxx, xxx, xxx, \fIKn\fP }
+.TP
+.IR UserProc → AS
+\fIKn\fP{ \fIAuthPass\fP, "old password", "new password" }
+.TP
+.IR AS → UserProc
+\fIAuthOK\fP
+.PD
+.PP
+or
+.TF "UserProc→AS"
+.TP
+.IR AS → UserProc
+\fIAuthErr\fP, 64-byte error string
+.PD
+.PP
+.SS "Data Base"
+An
+.IR ndb (2)
+database file exists for the authentication server.
+The attribute types used by the AS are
+.B hostid
+and
+.BR uid .
+The value in the
+.B hostid
+is a client host's ID.
+The values in the
+.B uid
+pairs in the same entry list which users that host ID
+make speak for.
+A uid value of
+.B *
+means the host ID may speak for all users.
+A uid value of
+.BI ! user
+means the host ID may not speak for
+.IR user .
+For example:
+.EX
+hostid=bootes
+	uid=!sys uid=!adm uid=*
+.EE
+.PP
+is interpreted as
+.B bootes
+may speak for any user except
+.B sys
+and
+.BR adm .
+.SH FILES
+.TF /lib/ndb/auth.*xxx
+.TP
+.B /lib/ndb/auth
+database file
+.TP
+.B /lib/ndb/auth.*
+hash files for
+.B /lib/ndb/auth
+.SH SEE ALSO
+.IR auth (2),
+.IR fauth (2),
+.IR cons (3),
+.IR attach (5),
+.IR auth (8)