authsrv man page on Plan9

Man page or keyword search:  
man Server   549 pages
apropos Keyword Search (all sections)
Output format
Plan9 logo
[printable version]

AUTHSRV(6)							    AUTHSRV(6)

       authsrv, p9any, p9sk1, p9sk2 - authentication protocols

       This manual page describes the protocols used to authorize connections,
       confirm the identities of users and machines, and maintain the  associ‐
       ated databases.	The machine that provides these services is called the
       authentication server (AS).  The AS may be a stand-alone machine	 or  a
       general-use  machine such as a CPU server.  The network database ndb(6)
       holds for each public machine, such as a CPU server or file server, the
       name of the authentication server that machine uses.

       Each  machine  contains	three  values  important  to authentication; a
       56-bit DES key, a 28-byte authentication ID, and a 48-byte  authentica‐
       tion  domain  name.   The  ID is a user name and identifies who is cur‐
       rently 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.

       When a terminal boots, factotum(4) prompts for user name and  password.
       The  user  name becomes the terminal's authentication ID.  The password
       is converted using passtokey (see authsrv(2)) into a 56-bit DES key and
       saved  in memory.  The authentication domain is set to the null string.
       If possible, factotum validates the key with the AS before  saving  it.
       For Internet machines the correct AS to ask is found using dhcpd(8).

       When a CPU or file server boots, factotum reads the key, ID, and domain
       name from non-volatile RAM.  This  allows  servers  to  reboot  without
       operator intervention.

       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:

       Ks     server's host ID's key

       Kc     client's host ID's key

       Kn     a nonce key created for a ticket (key)

       K{m}   message m encrypted with key K

       CHc    an 8-byte random challenge from a client (chal)

       CHs    an 8-byte random challenge from a server (chal)

       IDs    server's ID (authid)

       DN     server's authentication domain name (authdom)

       IDc    client's ID (hostid, cuid)

       IDr    client's desired ID on server (uid, suid)

       The  parenthesized  names are the ones used in the Ticketreq and Ticket
       structures in <authsrv.h>.

       The  message  type  constants  AuthTreq,	 AuthChal,  AuthPass,  AuthOK,
       AuthErr,	 AuthMod, AuthApop, AuthOKvar, AuthChap, AuthMSchap, AuthCram,
       and AuthVNC (type) are defined in <authsrv.h>,  as  are	the  encrypted
       message types AuthTs, AuthAs, AuthAc, AuthTp, and AuthHr (num).

   Ticket Service
       When a client and server wish to authenticate to each other, they do so
       using tickets issued by the AS.	Obtaining tickets from the AS  is  the
       client's responsibility.

       The protocol to obtain a ticket pair is:

       C→A    AuthTreq, IDs, DN, CHs, IDc, IDr
       A→C    AuthOK, Kc{AuthTc, CHs, IDc, IDr, Kn}, Ks{AuthTs, CHs, IDc, IDr,

       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 Kn.

       The tickets can be viewed as a statement by the AS that ``a client pos‐
       sessing the Kn key is allowed to authenticate as IDr.''

       The  presence  of  the  server  challenge  CHs in the ticket allows the
       server to verify the freshness of the ticket pair.

       The AS sets the IDr in the tickets to the requested IDr only if IDc  is
       allowed to speak for (q.v.)  IDr.  If not, the AS sets IDr to the empty

       If the users IDc or IDs do not exist, the AS  silently  generates  one-
       time  random  keys  to use in place of Kc or Ks, so that clients cannot
       probe the AS to learn whether a user name is valid.

       The Plan 9 shared key protocol p9sk1 allows  a  client  and  server  to
       authenticate each other.	 The protocol is:

       C→S    CHc
	      The client starts by sending a random challenge to the server.

       S→C    AuthTreq, IDs, DN, CHs, -, -
	      The  server  replies  with  a  ticket  request giving its id and
	      authentication domain along with its own random challenge.

       C→S    Ks{AuthTs, CHs, IDc, IDr, Kn}, Kn{AuthAc, CHs}
	      The client adds IDc and 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 authenticator, the AuthAc mes‐
	      sage.   The  authenticator  proves to the server that the client
	      knows Kn and is therefore allowed to authenticate as IDr.	  (The
	      inclusion of CHs in the authenticator avoids replay attacks.)

       S→C    Kn{AuthAs, CHc}
	      The  server  replies  with its own authenticator, proving to the
	      client that it also knows Kn and therefore Ks .

       P9sk2 is an older  variant  of  p9sk1  used  only  when	connecting  to
       pre-9P2000  remote  execution services.	It omits the first message and
       last messages and therefore does not authenticate  the  server  to  the

       P9any is the standard Plan 9 authentication protocol.  It consists of a
       negotiation to determine a common protocol, followed by the agreed-upon

       The negotiation protocol is:

       S→C    v.2 proto@authdom proto@authdom ...
       C→S    proto dom
       S→C    OK

       Each  message  is  a  NUL-terminated  UTF string.  The server begins by
       sending a list of proto, authdom pairs  it  is  willing	to  use.   The
       client  responds with its choice.  Requiring the client to wait for the
       final OK ensures that the client will not  start	 the  chosen  protocol
       until the server is ready.

       The  above  is  version	2 of the protocol.  Version 1, no longer used,
       omitted the first message's v.2 prefix and the OK message.

       The p9any protocol is the protocol used by all Plan  9  services.   The
       file server runs it over special authentication files (see fauth(2) and
       attach(5)).  Other services, such as cpu(1) and exportfs(4), run	 p9any
       over the network and then use Kn to derive an ssl(3) key to encrypt the
       rest of their communications.

   Password Change
       Users connect directly to the AS to change their passwords.  The proto‐
       col is:

       C→A    AuthPass, IDc, DN, CHc, IDc, IDc
	      The client sends a password change ticket request.

       A→C    Kc{AuthTp, CHc, IDc, IDc, Kn}
	      The  server  responds  with  a  ticket  containing  the  key  Kn
	      encrypted with the client's key Kc

       C→A    Kn{AuthPass, old, new, changesecret, secret}
	      The client decrypts the ticket using the old password  and  then
	      sends back an encrypted password request (Passwordreq structure)
	      containing the old password and the new password.	 If  changese‐
	      cret is set, the AS also changes the user's secret, the password
	      used for non-Plan 9 authentications.

       A→C    AuthOK or AuthErr, 64-byte error message
	      The AS responds with simply AuthOK or with AuthErr followed by a
	      64-byte error message.

   Authentication Database
       An ndb(2) database file /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 authtenticating.  The attribute types used
       by the AS are hostid and uid.  The value in  the	 hostid	 is  a	client
       host's  ID.   The  values in the uid pairs in the same entry list which
       users that host ID make speak for.  A uid value of * means the host  ID
       may  speak  for	all users.  A uid value of !user means the host ID may
       not speak for user.  For example:

	    uid=!sys uid=!adm uid=*

       is interpreted as bootes may speak for any user	except	sys  and  adm.
       This property is used heavily on CPU servers.

   Foreign Protocols
       The  AS accepts ticket request messages of types other than AuthTreq to
       allow users to authenticate using non-Plan 9 protocols.	In these situ‐
       ations,	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 AuthOK message containing a server ticket and authenticator.

       AuthOK messages always have a fixed but	context-dependent  size.   The
       occasional  variable-length OK message starts with a AuthOKvar byte and
       a five-byte space-padded decimal length of the data that follows.

       Anywhere an AuthOK message is expected, a AuthErr message may  be  sub‐

       S→A    AuthChal, IDs, DN, CHs, IDs, IDc
       A→S    AuthOK, challenge
       S→A    response
       A→S    AuthOK,  Ks{AuthChal,  IDs,  DN,	CHs, IDs, IDc, Kn}, Kn{AuthTs,

	      This protocol allows the use of handheld authenticators such  as
	      SecureNet	 keys  and  SecureID tokens in programs such as ssh(1)
	      and ftpd (see ipserv(8)).

	      Challenge and response are text strings, NUL -padded to 16 bytes
	      (NETCHLEN).   The	 challenge is a random five-digit decimal num‐
	      ber.  When using a SecureNet key or netkey (see passwd(1)),  the
	      response is an eight-digit decimal or hexadecimal number that is
	      an encryption of the challenge using the user's DES key.

	      When using a SecureID token,  the	 challenge  is	ignored.   The
	      response is the user's PIN followed by the six-digit number cur‐
	      rently 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

		  radius=server-name secret=xyzzy
		      uid=howard rid=trickey
		      uid=sape	 rid=smullender

	      In  this example, the secret xyzzy is the hash key used in talk‐
	      ing to the RADIUS server.	 The 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.

       S→A    AuthApop , IDs, DN, CHs, -, -
       A→S    AuthOKvar, challenge
       S→A    AuthApop , IDs, DN, CHs, IDc, IDc; hexadecimal MD5 checksum
       A→S    AuthOK, Ks{AuthApop, IDs, DN, CHs,  IDs,	IDc,  Kn},  Kn{AuthTs,

	      This  protocol  implements  APOP	authentication	(see pop3(8)).
	      After receiving a ticket request of type AuthApop, the AS gener‐
	      ates a random challenge of the form <random@domain>.  The client
	      then replies with a new ticket request giving the user name fol‐
	      lowed 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.

	      The AuthCram protocol runs identically to the AuthApop protocol,
	      except that the expected MD5 checksum  is	 the  keyed  MD5  hash
	      using the user's secret as the key (see hmac_md5 in sechash(2)).

       S→A    AuthChap, IDs, DN, CHs, -, -
       A→S    challenge
       S→A    pktid, IDc, response
       A→S    AuthOK,  Ks{AuthChap,  IDs,  DN,	CHs, IDs, IDc, Kn}, Kn{AuthTs,

	      This protocol implements CHAP authentication (see ppp(8)).   The
	      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 OChapreply in <authsrv.h>.

       S→A    AuthMSchap, IDs, DN, CHs, -, -
       A→S    challenge
       S→A    IDc, lm-response, nt-response
       A→S    AuthOK,  Ks{AuthMschap,  IDs, DN, CHs, IDs, IDc, Kn}, Kn{AuthTs,

	      This protocol implements Microsoft's MS-CHAP authentication (see
	      ppp(8)).	  The  challenge  is  eight  random  bytes.   The  two
	      responses are Microsofts 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 OMSchapreply in <authsrv.h>.

       S→A    AuthVNC, IDs, DN, CHs, IDs, IDc
       A→S    AuthOKvar, challenge
       S→A    response
       A→S    AuthOK, Ks{, IDs, DN, CHs, IDs, IDc, Kn}, Kn{AuthTs, CHs}

	      This  protocol  implements  VNC  authentication  (see  vncs   in
	      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.

	      database file

	      hash files for /lib/ndb/auth

       auth(2), fauth(2), cons(3), attach(5), auth(8)

                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server Plan9

List of man pages available for Plan9

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
Vote for polarhome
Free Shell Accounts :: the biggest list on the net