games/mix: document -g option, rename tests to examples as it is in the man page

[plan9front.git] / sys / man / 6 / authsrv

.TH AUTHSRV 6
.SH NAME
authsrv, p9any, p9sk1, dp9ik \- authentication protocols
.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 four values important to authentication; a 56-bit DES
key, a 128-bit AES 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,
.IR factotum (4)
prompts for user name and password.
The user name becomes the terminal's authentication ID. 
The password is converted using
.I passtokey
(see
.IR authsrv (2))
into a 56-bit DES and 128-bit AES keys and saved in memory.
The authentication domain is set to the null string.
If possible,
.I factotum
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, 
.I factotum
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 Ks
server's host ID's key
.TP
.I Kc
client's host ID's key
.TP
.I Kn
a nonce key created for a ticket
.RB ( key )
.TP
.I K{m}
message
.I m
encrypted with key
.I K
.TP
.I CHc
an 8-byte random challenge from a client
.RB ( chal )
.TP
.I CHs
an 8-byte random challenge from a server
.RB ( chal )
.TP
.I IDs
server's ID
.RB ( authid )
.TP
.I DN
server's authentication domain name
.RB ( authdom )
.TP
.I IDc
client's ID
.RB ( hostid ,
.BR cuid )
.TP
.I IDr
client's desired ID on server
.RB ( uid ,
.BR suid )
.TP
.I YAc
client → AS DH public key
.TP
.I YBc
AS → client DH public key
.TP
.I YAs
server → AS DH public key
.TP
.I YBs
AS → server DH public key
.TP
.I RNc
client's 32-byte random string
.TP
.I RNs
server's 32-byte random string
.PD
.PP
The parenthesized names are the ones used in the
.B Ticketreq
and
.B Ticket
structures in
.BR <authsrv.h> .
.PP
The message type constants
.IR AuthTreq ,
.IR AuthChal ,
.IR AuthPass ,
.IR AuthOK ,
.IR AuthErr ,
.IR AuthMod ,
.IR AuthApop ,
.IR AuthOKvar ,
.IR AuthChap ,
.IR AuthMSchap ,
.IR AuthCram ,
.IR AuthVNC ,
and
.IR AuthPAK
.RB ( type )
are defined in
.BR <authsrv.h> ,
as are the encrypted message types
.IR AuthTs ,
.IR AuthAs ,
.IR AuthAc ,
.IR AuthTp ,
and
.IR AuthHr
.RB ( num ).
.SS "Ticket Service
When a client and server wish to authenticate to each other,
they do so using
.I tickets
issued by the AS.
Obtaining tickets from the AS
is the client's responsibility.
.PP
The protocol to obtain a ticket pair is:
.TP
.I C→A:
.IR AuthTreq ,
.IR IDs ,
.IR DN ,
.IR CHs ,
.IR IDc ,
.IR IDr
.TP
.I A→C:
.IR AuthOK ,
.IR Kc { AuthTc ,
.IR CHs ,
.IR IDc ,
.IR IDr ,
.IR Kn },
.IR Ks { AuthTs ,
.IR CHs ,
.IR IDc ,
.IR IDr ,
.IR Kn }
.PP
The two tickets are identical except for their type fields
and the keys with which they are encrypted.
The client and server can each decrypt one of the tickets,
establishing a shared secret
.IR Kn .
.PP
The
tickets can be viewed as a statement by the
AS that
``a client possessing the
.I Kn
key is allowed to authenticate as
.IR IDr .''
.PP
The presence of the server challenge
.I CHs
in the ticket allows the server to verify the freshness
of the ticket pair.
.PP
The AS sets the
.I IDr
in the tickets to the requested
.I IDr
only if
.I IDc
is allowed to
.I "speak for
.RI ( q.v. )
.IR IDr .
If not,
the AS sets
.I IDr
to the empty string.
.PP
If the users
.I IDc
or
.I IDs
do not exist,
the AS silently generates one-time
random keys to use in place of
.I Kc
or
.IR Ks ,
so that clients cannot probe the AS
to learn whether a user name is valid.
.SS "P9sk1
The Plan 9 shared key protocol
.I p9sk1
allows a client and server to authenticate each other.
The protocol is:
.TP
.I C→S:
.I CHc
.br
The client starts by sending a random challenge to the server.
.TP
.I S→C:
.IR AuthTreq ,
.IR IDs ,
.IR DN ,
.IR CHs ,
.IR \- ,
.IR \-
.br
The server replies with a ticket request giving its
id and authentication domain along with its own 
random challenge.
.TP
.I C→S:
.IR Ks { AuthTs ,
.IR CHs ,
.IR IDc ,
.IR IDr ,
.IR Kn },
.IR Kn { AuthAc ,
.IR CHs }
.br
The client adds 
.I IDc
and
.I IDr
to the ticket request and obtains a ticket pair
from the AS as described above.
The client relays the server's ticket along with
an 
.IR authenticator ,
the
.I AuthAc
message.
The authenticator proves to the server that the
client knows
.I Kn
and is therefore allowed to authenticate as
.IR IDr .
(The inclusion of
.IR CHs
in the authenticator avoids replay attacks.)
.TP
.I S→C:
.IR Kn { AuthAs ,
.IR CHc }
.br
The server replies with its own authenticator,
proving to the client that it also knows
.I Kn
and therefore 
.I Ks .
.PP
The 64-bit shared secret
.I Kn
is used as the session secret.
.SS "Password authenticated key exchange"
Initially, the server and client keys
.I Ks
and
.I Kc
where equivalent to the password derived 56-bit DES keys, which
made the encrypted tickets subject to offline dictionary attacks
and provided too small a key space against brute force attacks
on current hardware.
.PP
The
.I AuthPAK
protocol is used to establish new 256-bit random keys with the
AS for
.I Ks
and
.I Kc
before each ticket request on the connection.
.PP
The protocol is based on SPAKE2EE, where a hash of the user's secret
is used to encypt the public keys of a Elliptic-Curve Diffie-Hellman
key exchange. The user's
.I ID
and 128-bit AES key is hashed and mapped (using Elligator2)
into two curve points
.I PM
and
.IR PN ,
called the
.IR pakhash .
Both sides generate a random number
.IR xa / xb
and make the public keys
.IR YA / YB
as:
.IR YA = xa*G+PM ,
.IR YB = xb*G+PN .
After the public keys have been exchanged, each side calculates the
shared secret as:
.IR Z = xa*(YB-PN) = xb*(YA-PM) .
The shared secret
.I Z
is then hashed with the transmitted public keys
.IR YA | YB
producing the 256-bit
.IR pakkey .
.PP
The
.I pakkey
is then used in place of
.I Ks
and
.I Kc
to authenticate and encrypt tickets from the AS using
Chacha20/Poly1305 AEAD for the next following
request made on the connection.
.PP
The protocol (for
.IR AuthTreq )
to establish keys
.I Ks
and
.I Kc
with the AS for
.I IDs
and
.I IDc
is:
.TP
.I C→A:
.IR AuthPAK ,
.IR IDs ,
.IR DN ,
.IR CHs ,
.IR IDc ,
.IR IDr ,
.IR YAs ,
.I YAc
.TP
.I A→C:
.IR AuthOK ,
.IR YBs ,
.I YBc
.PP
The protocol (for
.IR AuthApop ,
.IR AuthChap ...)
to establish a single server key
.I Ks
for
.IR IDs :
.TP
.I C→A:
.IR AuthPAK ,
.IR \- ,
.IR DN ,
.IR CHs ,
.IR IDs ,
.IR IDc ,
.I YAs
.TP
.I A→C:
.IR AuthOK ,
.I YBs
.PP
The protocol (for
.IR AuthPass )
to establish a single client key
.I Kc
for
.IR IDc :
.TP
.I C→A:
.IR AuthPAK ,
.IR \- ,
.IR \- ,
.IR CHc ,
.IR \- ,
.IR IDc ,
.I YAc
.TP
.I A→C:
.IR AuthOK ,
.I YBc
.SS "Dp9ik"
The
.I dp9ik
protocol is an extended version of
.I p9sk1
that adds the random strings
.I RNc
and
.I RNs
in the
.I authenticator
messages for the session key derivation and uses the
password authenticated key exchange as described above
to derive the ticket encryption keys
.I Ks
and
.IR Kc :
.TP
.I C→S:
.I CHc
.br
The client starts by sending a random challenge to the server.
.TP
.I S→C:
.IR AuthPAK ,
.IR IDs ,
.IR DN ,
.IR CHs ,
.IR \- ,
.IR \- ,
.IR YAs
.br
The server generates a new public key
.I YAs
and replies with a
.I AuthPAK
request giving its
.I IDs
and authentication domain
.I DNs
along with its own random challenge
.I CHs
and its public key
.IR YAs .
.TP
.I C→S:
.IR YBs ,
.IR Ks { AuthTs ,
.IR CHs ,
.IR IDc ,
.IR IDr ,
.IR Kn },
.IR Kn { AuthAc ,
.IR CHs ,
.IR RNc }
.br
The client generates its own public key
.I YAc
and adds it along with 
.I IDc
and
.I IDr
to the
.I AuthPAK
request and obtains the public keys
.I YBs
and
.I YBc
from the AS response. At this point, client and AS
have completed ther authenticated key exchange and
derive
.I Kc
as described above.
Then the client requests a ticket pair using the same
message but with
.I AuthPAK
type changed to
.IR AuthTreq .
It decrypts his ticket with
.I Kc
extracting the shared secret
.IR Kn .
The client relays the server's
.I YBs
and ticket along with an
.IR authenticator ,
the
.I AuthAc
message.
The server finishes his authenticated key exchange
using
.I YBs
and derives
.I Ks
to decrypt his ticket to extract the shared secret
.IR Kn .
When the decryption of the clients authenticator using
.I Kn
is successfull then this proves to the server that the
client knows
.I Kn
and is therefore allowed to authenticate as
.IR IDr .
The random string
.I RNc
is used in the derivation of the session secret.
.TP
.I S→C:
.IR Kn { AuthAs ,
.IR CHc ,
.IR RNs }
.br
The server replies with its own authenticator,
proving to the client that it also knows
.I Kn
and contributes its random string
.IR RNs
for the session secret.
.PP
The 2048-bit session secret is derived with HKDF-SHA256 hashing the
concatenated random strings
.IR RNc | RNs
with the the shared secret key
.IR Kn .
.SS "P9any
.I P9any
is the standard Plan 9 authentication protocol.
It consists of a negotiation to determine a common
protocol, followed by the agreed-upon protocol.
.PP
The negotiation protocol is:
.TP
.I S→C:
.B v.2
.IB proto@authdom
.IB proto@authdom
.I ...
.TP
.I C→S:
.I proto
.I dom
.TP
.I S→C:
.B OK
.PP
Each message is a NUL-terminated UTF string.
The server begins by sending a list of
.IR proto ,
.I authdom
pairs it is willing to use.
The client
responds with its choice.
Requiring the client to wait for the final
.B OK
ensures that the client will not start
the chosen protocol until the server is ready.
.PP
The above is version 2 of the protocol.
Version 1,
no longer used,
omitted the first message's
.B v.2
prefix
and the 
.B OK
message.
.PP
The
.I p9any
protocol is the protocol used by all
Plan 9 services.
The file server runs it over special
authentication files
(see
.IR fauth (2)
and
.IR attach (5)).
Other services, such as
.IR cpu (1),
.IR exportfs (4)
and
.IR tlssrv (8)
run
.I p9any
over the network and then use the session secret to derive an
.IR ssl (3)
or
.IR tls (3)
key to encrypt the rest of their communications.
.SS "Password Change
Users connect directly to the AS
to change their passwords.
The protocol is:
.TP
.I C→A:
.IR AuthPass ,
.IR \- ,
.IR \- ,
.IR CHc ,
.IR \- ,
.IR IDc
.br
The client sends a password change ticket request.
.TP
.I A→C:
.IR Kc { AuthTp ,
.IR CHc ,
.IR IDc ,
.IR IDc ,
.IR Kn }
.br
The server responds with a ticket containing the key
.I Kn
encrypted with the client's key
.IR Kc
.TP
.I C→A:
.IR Kn { AuthPass ,
.IR old ,
.IR new ,
.IR changesecret ,
.IR secret }
.br
The client decrypts the ticket using the old password
and then sends back an encrypted password request
.RB ( Passwordreq
structure)
containing the old password and the new password.
If
.I changesecret
is set, the AS also changes
the user's 
.IR secret ,
the password used for non-Plan 9 authentications.
.TP
.I A→C:
.I AuthOK
or
.IR AuthErr ,
64-byte error message
.br
The AS responds with simply
.I AuthOK
or with
.I AuthErr
followed by a 64-byte error message.
.SS "Authentication Database
An
.IR ndb (2)
database file 
.B /lib/ndb/auth
exists for the AS.
This database maintains ``speaks for'' relationships, i.e.,
it lists which users may speak for other users when
authenticating.
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
may 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:
.PP
.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 .
This property is used heavily on CPU servers.
.SS "Foreign Protocols
The AS accepts ticket request
messages of types other than
.I AuthTreq
to allow users to
authenticate using non-Plan 9 protocols.
In these situations, the server communicates
directly with the AS.
Some protocols must begin without knowing the
client's name.  They ignore the client name in the
ticket request.
All the protocols end
with the AS sending
an
.I AuthOK
message containing a server ticket and authenticator.
.PP
.I AuthOK
messages
always have a fixed but context-dependent size.
The occasional variable-length OK message starts with a
.I AuthOKvar
byte and a five-byte space-padded decimal length of the
data that follows.
.PP
Anywhere an
.I AuthOK
message is expected, a
.I AuthErr
message may be substituted.
.de Ok
.TP
.I A→S:
.IR AuthOK ,
.IR Ks { AuthTs ,
.IR CHs ,
.IR IDc ,
.IR IDc ,
.IR Kn },
.IR Kn { AuthAc ,
.IR CHs }
..
.PP
.TP
.I S→A:
.IR AuthChal ,
.IR \- ,
.IR DN ,
.IR CHs ,
.IR IDs ,
.IR IDc
.TP
.I A→S:
.IR AuthOK ,
.IR challenge
.TP
.I S→A:
.IR response
.Ok
.IP
This protocol allows the use of 
handheld authenticators such as SecureNet
keys and SecureID tokens
in programs such as
.I telnetd
and
.I ftpd
(see
.IR ipserv (8)).
.IP
.I Challenge
and
.I response 
are text strings,
.SM NUL -padded
to 16 bytes
.RB ( NETCHLEN ).
The
.I challenge
is a random five-digit decimal number.
When using a SecureNet key or
.I netkey
(see
.IR passwd (1)),
the 
.I response
is an eight-digit decimal or hexadecimal number
that is an encryption of the challenge
using the user's DES key.
.IP
When using a SecureID token,
the challenge is ignored.
The response is the user's PIN followed by
the six-digit number currently displayed
on the token.
In this case, the AS
queries an external RADIUS server
to check the response.
Use of a RADIUS server requires an entry in
the authentication database.  For example:
.IP
.EX
    radius=server-name secret=xyzzy
        uid=howard rid=trickey
        uid=sape   rid=smullender
.EE
.IP
In this example, the secret
.B xyzzy
is the hash key used in talking to the RADIUS server.
The
.BR uid / rid
lines map from Plan 9 user ids to RADIUS ids.
Users not listed are assumed to have the
same id in both places.
.TP
.I S→A:
.IR AuthApop ,
.IR \- ,
.IR DN ,
.IR CHs ,
.IR IDs ,
.IR \-
.TP
.I A→S:
.IR AuthOKvar ,
.IR challenge
.TP
.I S→A:
.IR AuthApop ,
.IR \- ,
.IR DN ,
.IR CHs ,
.IR IDs ,
.IR IDc ;
hexadecimal MD5 checksum
.Ok
.IP
This protocol implements APOP authentication
(see
.IR pop3 (8)).
After receiving a ticket request of type
.IR AuthApop ,
the AS generates a random challenge
of the form
.BI < random @ domain >\fR.
The client then replies with a new ticket request
giving the user name
followed by the MD5 checksum of
the challenge concatenated with the user's secret.
If the response is correct, the authentication
server sends back a ticket
and authenticator.
If the response is incorrect, the client may repeat the
ticket request/MD5 checksum message to try again.
.IP
The 
.I AuthCram
protocol runs identically to the
.I AuthApop
protocol, except that the expected MD5 checksum
is the keyed MD5 hash using the user's secret as the key
(see
.I hmac_md5
in
.IR sechash (2)).
.TP
.I S→A:
.IR AuthChap ,
.IR \- ,
.IR DN ,
.IR CHs ,
.IR IDs ,
.IR \-
.TP
.I A→S:
.I challenge
.TP
.I S→A:
.IR pktid ,
.IR IDc ,
.IR response
.Ok
.IP
This protocol implements CHAP authentication
(see
.IR ppp (8)).
The
.I challenge
is eight random bytes.
The response is a 16-byte MD5 checksum
over the packet id, user's secret, and challenge.
The reply packet is defined as 
.B OChapreply
in
.BR <authsrv.h> .
.TP
.I S→A:
.IR AuthMSchap ,
.IR \- ,
.IR DN ,
.IR CHs ,
.IR IDs ,
.IR \-
.TP
.I A→S:
.I challenge
.TP
.I S→A:
.IR IDc ,
.IR lm-response ,
.IR nt-response
.Ok
.IP
This protocol implements Microsoft's MS-CHAP
authentication
(see
.IR ppp (8)).
The
.I challenge
is eight random bytes.
The two responses are Microsoft's LM and NT hashes.
Only the NT hash may be used to authenticate,
as the LM hash is considered too weak.
The reply packet is defined as
.B OMSchapreply
in
.BR <authsrv.h> .
.TP
.I S→A:
.IR AuthVNC ,
.IR \- ,
.IR DN ,
.IR CHs ,
.IR IDs ,
.IR IDc
.TP
.I A→S:
.IR AuthOKvar ,
.I challenge
.TP
.I S→A:
.I response
.Ok
.IP
This protocol implements VNC authentication
(see
.I vncs
in
.IR vnc (1)).
The challenge is 16 random bytes, and the response
is a DES ECB encryption of the challenge.
The method by which VNC converts the user's
secret into a DES key is weak, 
considering only the first eight bytes of the secret.
.PD
.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)