.TH AUTHSRV 6.SH NAMEauthsrv, p9any, p9sk1, p9sk2 \- authentication protocols.SH DESCRIPTIONThis manual page describesthe protocols used to authorize connections, confirm the identitiesof 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 orfile server, the name of the authentication server that machine uses..PPEach machine contains three values important to authentication; a 56-bit DESkey, 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 thekernel 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..PPWhen 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 key and saved in memory.The authentication domain is set to the null string.If possible,.I factotumvalidates the key with the ASbefore saving it.For Internet machines the correct AS to ask is found using.IR dhcpd (8)..PPWhen a CPU or file server boots, .I factotumreads the key, ID, and domain name fromnon-volatile RAM.This allows servers to reboot without operator intervention..PPThe details of any authentication are mixed with the semanticsof the particular service they are authenticating so we describethem one case at a time. The following definitions will be usedin the descriptions:.TF nullx.TP.I Ksserver's host ID's key.TP.I Kcclient's host ID's key.TP.I Kna nonce key created for a ticket.RB ( key ).TP.IR K { m }message.I mencrypted with key.I K.TP.I CHcan 8-byte random challenge from a client.RB ( chal ).TP.I CHsan 8-byte random challenge from a server.RB ( chal ).TP.I IDsserver's ID.RB ( authid ).TP.I DNserver's authentication domain name.RB ( authdom ).TP.I IDcclient's ID.RB ( hostid ,.BR cuid ).TP.I IDrclient's desired ID on server.RB ( uid ,.BR suid ).PD.PPThe parenthesized names are the ones used in the.B Ticketreqand.B Ticketstructures in.BR <authsrv.h> ..PPThe 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 ,and.IR AuthVNC.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 ServiceWhen a client and server wish to authenticate to each other,they do so using.I ticketsissued by the AS.Obtaining tickets from the ASis the client's responsibility..PPThe protocol to obtain a ticket pair is:.TP.IR C \(-> A.IR AuthTreq ,.IR IDs ,.IR DN ,.IR CHs ,.IR IDc ,.IR IDr.sp -\n(PDu.TP.IR 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 }.PPThe two tickets are identical except for their type fieldsand the keys with which they are encrypted.The client and server can each decrypt one of the tickets,establishing a shared secret.IR Kn ..PPThetickets can be viewed as a statement by theAS that``a client possessing the.I Knkey is allowed to authenticate as.IR IDr .''.PPThe presence of the server challenge.I CHsin the ticket allows the server to verify the freshnessof the ticket pair..PPThe AS sets the.I IDrin the tickets to the requested.I IDronly if.I IDcis allowed to.I "speak for.RI ( q.v. ).IR IDr .If not,the AS sets.I IDrto the empty string..PPIf the users.I IDcor.I IDsdo not exist,the AS silently generates one-timerandom keys to use in place of.I Kcor.IR Ks ,so that clients cannot probe the ASto learn whether a user name is valid..SS "P9sk1The Plan 9 shared key protocol.I p9sk1allows a client and server to authenticate each other.The protocol is:.TP.IR C \(-> S.I CHc.brThe client starts by sending a random challenge to the server..TP.IR S \(-> C.IR AuthTreq ,.IR IDs ,.IR DN ,.IR CHs ,.IR \- ,.IR \-.brThe server replies with a ticket request giving itsid and authentication domain along with its own random challenge..TP.IR C \(-> S.IR Ks { AuthTs ,.IR CHs ,.IR IDc ,.IR IDr ,.IR Kn },.IR Kn { AuthAc ,.IR CHs }.brThe client adds .I IDcand.I IDrto the ticket request and obtains a ticket pairfrom the AS as described above.The client relays the server's ticket along withan .IR authenticator ,the.I AuthAcmessage.The authenticator proves to the server that theclient knows.I Knand is therefore allowed to authenticate as.IR IDr .(The inclusion of.IR CHsin the authenticator avoids replay attacks.).TP.IR S \(-> C.IR Kn { AuthAs ,.IR CHc }.brThe server replies with its own authenticator,proving to the client that it also knows.I Knand therefore .I Ks ..PD.PP.I P9sk2is an older variant of .I p9sk1used only when connecting to pre-9P2000 remoteexecution services.It omits the first message and last messages and therefore does notauthenticate the server to the client..SS "P9any.I P9anyis the standard Plan 9 authentication protocol.It consists of a negotiation to determine a commonprotocol, followed by the agreed-upon protocol..PPThe negotiation protocol is:.TP.IR S \(-> C.B v.2.IB proto@authdom.IB proto@authdom.I ....sp -\n(PDu.TP.IR C \(-> S.I proto.I dom.sp -\n(PDu.TP.IR S \(-> C.B OK.PPEach message is a NUL-terminated UTF string.The server begins by sending a list of.IR proto ,.I authdompairs it is willing to use.The clientresponds with its choice.Requiring the client to wait for the final.B OKensures that the client will not startthe chosen protocol until the server is ready..PPThe above is version 2 of the protocol.Version 1,no longer used,omitted the first message's.B v.2prefixand the .B OKmessage..PPThe.I p9anyprotocol is the protocol used by allPlan 9 services.The file server runs it over specialauthentication files(see.IR fauth (2)and.IR attach (5)).Other services, such as.IR cpu (1)and.IR exportfs (4),run.I p9anyover the network and then use.I Knto derive an.IR ssl (3)key to encrypt the rest of their communications..SS "Password ChangeUsers connect directly to the ASto change their passwords.The protocol is:.TP.IR C \(-> A.IR AuthPass ,.IR IDc ,.IR DN ,.IR CHc ,.IR IDc ,.IR IDc.brThe client sends a password change ticket request..TP.IR A \(-> C.IR Kc { AuthTp ,.IR CHc ,.IR IDc ,.IR IDc ,.IR Kn }.brThe server responds with a ticket containing the key.I Knencrypted with the client's key.IR Kc.TP.IR C \(-> A.IR Kn { AuthPass ,.IR old ,.IR new ,.IR changesecret ,.IR secret }.brThe client decrypts the ticket using the old passwordand then sends back an encrypted password request.RB ( Passwordreqstructure)containing the old password and the new password.If.I changesecretis set, the AS also changesthe user's .IR secret ,the password used for non-Plan 9 authentications..TP.IR A \(-> C.I AuthOKor.IR AuthErr ,64-byte error message.brThe AS responds with simply.I AuthOKor with.I AuthErrfollowed by a 64-byte error message..SS "Authentication DatabaseAn.IR ndb (2)database file .B /lib/ndb/authexists for the AS.This database maintains ``speaks for'' relationships, i.e.,it lists which users may speak for other users whenauthtenticating.The attribute types used by the AS are.B hostidand.BR uid .The value in the.B hostidis a client host's ID.The values in the.B uidpairs in the same entry list which users that host IDmake speak for.A uid value of.B *means the host ID may speak for all users.A uid value of.BI ! usermeans the host ID may not speak for.IR user .For example:.PP.EXhostid=bootes uid=!sys uid=!adm uid=*.EE.PPis interpreted as.B bootesmay speak for any user except.B sysand.BR adm .This property is used heavily on CPU servers..SS "Foreign ProtocolsThe AS accepts ticket requestmessages of types other than.I AuthTreqto allow users toauthenticate using non-Plan 9 protocols.In these situations, the server communicatesdirectly with the AS.Some protocols must begin without knowing theclient's name. They ignore the client name in theticket request.All the protocols endwith the AS sendingan.I AuthOKmessage containing a server ticket and authenticator..PP.I AuthOKmessagesalways have a fixed but context-dependent size.The occasional variable-length OK message starts with a.I AuthOKvarbyte and a five-byte space-padded decimal length of thedata that follows..PPAnywhere an.I AuthOKmessage is expected, a.I AuthErrmessage may be substituted..de Ok.sp -\n(PDu.TP.IR A \(-> S.IR AuthOK ,.IR Ks { \\$1 ,.IR IDs ,.IR DN ,.IR CHs ,.IR IDs ,.IR IDc ,.IR Kn },.IR Kn { AuthTs ,.IR CHs }...PP.TP.IR S \(-> A.IR AuthChal ,.IR IDs ,.IR DN ,.IR CHs ,.IR IDs ,.IR IDc.sp -\n(PDu.TP.IR A \(-> S.IR AuthOK ,Lines 1–500 of 726. Load more
.TH AUTHSRV 6 .SH NAME authsrv, p9any, p9sk1, p9sk2 \- 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 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, .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 key 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 .IR 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 ) .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 , and .IR AuthVNC .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 .IR C \(-> A .IR AuthTreq , .IR IDs , .IR DN , .IR CHs , .IR IDc , .IR IDr .sp -\n(PDu .TP .IR 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 .IR C \(-> S .I CHc .br The client starts by sending a random challenge to the server. .TP .IR 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 .IR 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 .IR 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 . .PD .PP .I P9sk2 is an older variant of .I 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 client. .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 .IR S \(-> C .B v.2 .IB proto@authdom .IB proto@authdom .I ... .sp -\n(PDu .TP .IR C \(-> S .I proto .I dom .sp -\n(PDu .TP .IR 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) and .IR exportfs (4), run .I p9any over the network and then use .I Kn to derive an .IR ssl (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 .IR C \(-> A .IR AuthPass , .IR IDc , .IR DN , .IR CHc , .IR IDc , .IR IDc .br The client sends a password change ticket request. .TP .IR 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 .IR 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 .IR 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 authtenticating. 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: .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 .sp -\n(PDu .TP .IR A \(-> S .IR AuthOK , .IR Ks { \\$1 , .IR IDs , .IR DN , .IR CHs , .IR IDs , .IR IDc , .IR Kn }, .IR Kn { AuthTs , .IR CHs } .. .PP .TP .IR S \(-> A .IR AuthChal , .IR IDs , .IR DN , .IR CHs , .IR IDs , .IR IDc .sp -\n(PDu .TP .IR A \(-> S .IR AuthOK ,