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 connection server
70 .B cs
71 (see
72 .IR ndb (8))
73 is queried for an entry which contains
74 .B authdom=\fIad\fP
75 or
76 .BR dom=\fIad\fP ,
77 the former having precedence,
78 and which also contains an
79 .B auth
80 attribute.
81 The string dialed is then
82 .I netroot\fP!\fIserver\fP!ticket
83 where
84 .I server
85 is the value of the
86 .B auth
87 attribute.
88 If no entry is found, the error string is
89 set to ``no authentication server found''
90 and -1 is returned.
91 If
92 .I authdom
93 is nil, the string
94 .IB netroot !$auth! ticket
95 is used to make the call.
96 .PP
97 .I Passtokey
98 converts
99 .I password
100 into a DES key and stores the result in
101 .IR key .
102 It returns 0 if
103 .I password
104 could not be converted,
105 and 1 otherwise.
106 .PP
107 .I Readnvram
108 reads authentication information into the structure:
109 .EX
110 .ta 4n +4n +8n +4n +4n +4n +4n
111 	struct Nvrsafe
112 	{
113 		char	machkey[DESKEYLEN];
114 		uchar	machsum;
115 		char	authkey[DESKEYLEN];
116 		uchar	authsum;
117 		char	config[CONFIGLEN];
118 		uchar	configsum;
119 		char	authid[ANAMELEN];
120 		uchar	authidsum;
121 		char	authdom[DOMLEN];
122 		uchar	authdomsum;
123 	};
124 .EE
125 .PP
126 On Sparc, MIPS, and SGI machines this information is
127 in non-volatile ram, accessible in the file
128 .BR #r/nvram .
129 On x86s and Alphas
130 .I readnvram
131 successively opens the following areas stopping with the
132 first to succeed:
133 .PP
134 \- the partition named by the
135 .B $nvram
136 environment variable
137 (commonly set via
138 .IR plan9.ini (8))
139 .br
140 \- the partition
141 .B #S/sdC0/nvram
142 .br
143 \- a file called
144 .B plan9.nvr
145 in the partition
146 .B #S/sdC0/9fat
147 .br
148 \- the partition
149 .B #S/sd00/nvram
150 .br
151 \- a file called
152 .B plan9.nvr
153 in the partition
154 .B #S/sd00/9fat
155 .br
156 \- a file called
157 .B plan9.nvr
158 on a DOS floppy in drive 0
159 .br
160 \- a file called
161 .B plan9.nvr
162 on a DOS floppy in drive 1
163 .PP
164 The
165 .IR nvcsum s
166 of the fields
167 .BR machkey ,
168 .BR authid ,
169 and
170 .B authdom
171 must match their respective checksum or that field is zeroed.
172 If
173 .I flag
174 is
175 .B NVwrite
176 or at least one checksum fails and
177 .I flag
178 is
179 .BR NVwriteonerr ,
180 .I readnvram
181 will prompt for new values on
182 .B #c/cons
183 and then write them back to the storage area.
184 .PP
185 .IR ConvT2M ,
186 .IR convA2M ,
187 .IR convTR2M ,
188 and
189 .I convPR2M
190 convert tickets, authenticators, ticket requests, and password change request
191 structures into transmittable messages.
192 .IR ConvM2T ,
193 .IR convM2A ,
194 .IR convM2TR ,
195 and
196 .I convM2PR
197 are used to convert them back.
198 .I Key
199 is used for encrypting the message before transmission and decrypting
200 after reception.
201 .PP
202 The routine
203 .I _asgetresp
204 receives either a character array or an error string.
205 On error, it sets errstr and returns -1.  If successful,
206 it returns the number of bytes received.
207 .PP
208 The routine
209 .I _asgetticket
210 sends a ticket request message and then uses
211 .I _asgetresp
212 to recieve an answer.
213 .SH SOURCE
214 .B /sys/src/libauthsrv
215 .SH SEE ALSO
216 .IR passwd (1),
217 .IR cons (3),
218 .IR dial (3),
219 .IR authsrv (6),
220 .SH DIAGNOSTICS
221 These routines set
222 .IR errstr .
223 Integer-valued functions return -1 on error.