1 .TH AUTHSRV 3
2 .SH NAME
3 authdial, passtokey, nvcsum, readnvram, convT2M, convM2T, convTR2M, convM2TR, convA2M, convM2A, convPR2M, convM2PR, _asgetticket, _asrdresp \- routines for communicating with authentication servers
4 .SH SYNOPSIS
5 .nf
6 .PP
7 .ft L
8 #include <u.h>
9 #include <libc.h>
10 #include <authsrv.h>
11 .fi
12 .ta 8n +4n +4n +4n +4n +4n +4n
13 .PP
14 .B
15 int	authdial(char *netroot, char *ad);
16 .PP
17 .B
18 int	passtokey(char key[DESKEYLEN], char *password)
19 .PP
20 .B
21 uchar	nvcsum(void *mem, int len)
22 .PP
23 .B
24 int	readnvram(Nvrsafe *nv, int flag);
25 .PPP
26 .B
27 int	convT2M(Ticket *t, char *msg, char *key)
28 .PP
29 .B
30 void	convM2T(char *msg, Ticket *t, char *key)
31 .PP
32 .B
33 int	convA2M(Authenticator *a, char *msg, char *key)
34 .PP
35 .B
36 void	convM2A(char *msg, Authenticator *a, char *key)
37 .PP
38 .B
39 int	convTR2M(Ticketreq *tr, char *msg)
40 .PP
41 .B
42 void	convM2TR(char *msg, Ticketreq *tr)
43 .PP
44 .B
45 int	convPR2M(Passwordreq *pr, char *msg, char *key)
46 .PP
47 .B
48 void	convM2PR(char *msg, Passwordreq *pr, char *key)
49 .PP
50 .B
51 int	_asgetticket(int fd, char *trbuf, char *tbuf);
52 .PP
53 .B
54 int	_asrdresp(int fd, char *buf, int len);
55 .SH DESCRIPTION
56 .PP
57 .I Authdial
58 dials an authentication server over the
59 network rooted at
60 .IR net ,
61 default
62 .BR /net  .
63 The authentication domain,
64 .IR ad ,
65 specifies which server to call.
66 If
67 .I ad
68 is non-nil,
69 the network database
70 (see
71 .MR ndb (1) )
72 is queried for an entry which contains
73 .B authdom=\fIad\fP
74 or
75 .BR dom=\fIad\fP ,
76 the former having precedence,
77 and which also contains an
78 .B auth
79 attribute.
80 The string dialed is then
81 .I netroot\fP!\fIserver\fP!ticket
82 where
83 .I server
84 is the value of the
85 .B auth
86 attribute.
87 If no entry is found, the error string is
88 set to ``no authentication server found''
89 and -1 is returned.
90 If
91 .I authdom
92 is nil, the string
93 .IB netroot !$auth! ticket
94 is used to make the call.
95 .PP
96 .I Passtokey
97 converts
98 .I password
99 into a DES key and stores the result in
100 .IR key .
101 It returns 0 if
102 .I password
103 could not be converted,
104 and 1 otherwise.
105 .PP
106 .I Readnvram
107 reads authentication information into the structure:
108 .EX
109 .ta 4n +4n +8n +4n +4n +4n +4n
110 	struct Nvrsafe
111 	{
112 		char	machkey[DESKEYLEN];
113 		uchar	machsum;
114 		char	authkey[DESKEYLEN];
115 		uchar	authsum;
116 		char	config[CONFIGLEN];
117 		uchar	configsum;
118 		char	authid[ANAMELEN];
119 		uchar	authidsum;
120 		char	authdom[DOMLEN];
121 		uchar	authdomsum;
122 	};
123 .EE
124 .PP
125 On Sparc, MIPS, and SGI machines this information is
126 in non-volatile ram, accessible in the file
127 .BR #r/nvram .
128 On x86s and Alphas
129 .I readnvram
130 successively opens the following areas stopping with the
131 first to succeed:
132 .PP
133 \- the partition named by the
134 .B $nvram
135 environment variable
136 .\" (commonly set via
137 .\" .IR plan9.ini (8))
138 .br
139 \- the partition
140 .B #S/sdC0/nvram
141 .br
142 \- a file called
143 .B plan9.nvr
144 in the partition
145 .B #S/sdC0/9fat
146 .br
147 \- the partition
148 .B #S/sd00/nvram
149 .br
150 \- a file called
151 .B plan9.nvr
152 in the partition
153 .B #S/sd00/9fat
154 .br
155 \- a file called
156 .B plan9.nvr
157 on a DOS floppy in drive 0
158 .br
159 \- a file called
160 .B plan9.nvr
161 on a DOS floppy in drive 1
162 .PP
163 The
164 .IR nvcsum s
165 of the fields
166 .BR machkey ,
167 .BR authid ,
168 and
169 .B authdom
170 must match their respective checksum or that field is zeroed.
171 If
172 .I flag
173 is
174 .B NVwrite
175 or at least one checksum fails and
176 .I flag
177 is
178 .BR NVwriteonerr ,
179 .I readnvram
180 will prompt for new values on
181 .B #c/cons
182 and then write them back to the storage area.
183 .PP
184 .IR ConvT2M ,
185 .IR convA2M ,
186 .IR convTR2M ,
187 and
188 .I convPR2M
189 convert tickets, authenticators, ticket requests, and password change request
190 structures into transmittable messages.
191 .IR ConvM2T ,
192 .IR convM2A ,
193 .IR convM2TR ,
194 and
195 .I convM2PR
196 are used to convert them back.
197 .I Key
198 is used for encrypting the message before transmission and decrypting
199 after reception.
200 .PP
201 The routine
202 .I _asgetresp
203 receives either a character array or an error string.
204 On error, it sets errstr and returns -1.  If successful,
205 it returns the number of bytes received.
206 .PP
207 The routine
208 .I _asgetticket
209 sends a ticket request message and then uses
210 .I _asgetresp
211 to recieve an answer.
212 .SH SOURCE
213 .B \*9/src/libauthsrv
214 .SH SEE ALSO
215 .MR passwd (1) ,
216 .MR dial (3) ,
217 Plan 9's
218 .IR authsrv (6).
219 .SH DIAGNOSTICS
220 These routines set
221 .IR errstr .
222 Integer-valued functions return -1 on error.