sys/man/2/authsrv

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