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, _asrequest, _asgetresp, _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 void    passtokey(Authkey *key, 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, int len, Authkey *key)
  28 .PP
  29 .B
  30 int     convM2T(char *msg, int len, Ticket *t, Authkey *key)
  31 .PP
  32 .B
  33 int     convA2M(Authenticator *a, char *msg, int len, Ticket *t)
  34 .PP
  35 .B
  36 int     convM2A(char *msg, int len, Authenticator *a, Ticket *t)
  37 .PP
  38 .B
  39 int     convTR2M(Ticketreq *tr, char *msg, int len)
  40 .PP
  41 .B
  42 int     convM2TR(char *msg, int len, Ticketreq *tr)
  43 .PP
  44 .B
  45 int     convPR2M(Passwordreq *pr, char *msg, int len, Ticket *t)
  46 .PP
  47 .B
  48 int     convM2PR(char *msg, int len, Passwordreq *pr, Ticket *t)
  49 .PP
  50 .B
  51 int     _asgetticket(int fd, Ticketreq *tr, char *buf, int len)
  52 .PP
  53 .B
  54 int     _asrequest(int fd, Ticketreq *tr)
  55 .PP
  56 .B
  57 int     _asgetresp(int fd, Ticket *t, Authenticator *a, Authkey *key)
  58 .PP
  59 .B
  60 int     _asrdresp(int fd, char *buf, int len)
  61 .SH DESCRIPTION
  62 .I Authdial
  63 dials an authentication server over the
  64 network rooted at
  65 .IR net ,
  66 default
  67 .BR /net  .
  68 The authentication domain,
  69 .IR ad ,
  70 specifies which server to call.
  71 If
  72 .I ad
  73 is non-nil,
  74 the connection server
  75 .B cs
  76 (see
  77 .IR ndb (8))
  78 is queried for an entry which contains
  79 .B authdom=\fIad\fP
  80 or
  81 .BR dom=\fIad\fP ,
  82 the former having precedence,
  83 and which also contains an
  84 .B auth
  85 attribute.
  86 If it finds neither, it tries
  87 .BI p9auth. ad
  88 in DNS as the authentication server.
  89 The string dialed is then
  90 .I netroot\fP!\fIserver\fP!ticket
  91 where
  92 .I server
  93 is the value of the
  94 .B auth
  95 attribute.
  96 If no entry is found, the error string is
  97 set to ``no authentication server found''
  98 and -1 is returned.
  99 If
 100 .I authdom
 101 is nil, the string
 102 .IB netroot !$auth! ticket
 103 is used to make the call.
 104 .PP
 105 .I Passtokey
 106 converts
 107 .I password
 108 into a set of cryptographic keys and stores them in the
 109 .I Authkey
 110 structure
 111 .IR key .
 112 .PP
 113 .I Readnvram
 114 reads authentication information into the structure:
 115 .PP
 116 .EX
 117 .ta 4n +4n +8n +4n +4n +4n +4n
 118 struct Nvrsafe
 119 {
 120         char    machkey[DESKEYLEN];     /* was file server's authid's des key */
 121         uchar   machsum;
 122         char    authkey[DESKEYLEN];     /* authid's des key from password */
 123         uchar   authsum;
 124         /*
 125          * file server config string of device holding full configuration;
 126          * secstore key on non-file-servers.
 127          */
 128         char    config[CONFIGLEN];
 129         uchar   configsum;
 130         char    authid[ANAMELEN];       /* auth userid, e.g., bootes */
 131         uchar   authidsum;
 132         char    authdom[DOMLEN]; /* auth domain, e.g., cs.bell-labs.com */
 133         uchar   authdomsum;
 134 };
 135 .EE
 136 .PP
 137 On Sparc, MIPS, and SGI machines this information is
 138 in non-volatile ram, accessible in the file
 139 .BR #r/nvram .
 140 On x86s and Alphas
 141 .I readnvram
 142 successively opens the following areas stopping with the
 143 first to succeed:
 144 .PP
 145 \- the partition named by the
 146 .B $nvram
 147 environment variable
 148 (commonly set via
 149 .IR plan9.ini (8))
 150 .br
 151 \- the partition
 152 .B #S/sdC0/nvram
 153 .br
 154 \- a file called
 155 .B plan9.nvr
 156 in the partition
 157 .B #S/sdC0/9fat
 158 .br
 159 \- the partition
 160 .B #S/sd00/nvram
 161 .br
 162 \- a file called
 163 .B plan9.nvr
 164 in the partition
 165 .B #S/sd00/9fat
 166 .br
 167 \- a file called
 168 .B plan9.nvr
 169 on a DOS floppy in drive 0
 170 .br
 171 \- a file called
 172 .B plan9.nvr
 173 on a DOS floppy in drive 1
 174 .PP
 175 The
 176 .IR nvcsum s
 177 of the fields
 178 .BR machkey ,
 179 .BR authid ,
 180 and
 181 .B authdom
 182 must match their respective checksum or that field is zeroed.
 183 If
 184 .I flag
 185 is
 186 .B NVwrite
 187 or at least one checksum fails and
 188 .I flag
 189 is
 190 .BR NVwriteonerr ,
 191 .I readnvram
 192 will prompt for new values on
 193 .B #c/cons
 194 and then write them back to the storage area.
 195 If
 196 .I flag
 197 is
 198 .BR NVwritemem ,
 199 .I readnvram
 200 will write the values in
 201 .I *nv
 202 back to the storage area.
 203 .PP
 204 .IR ConvT2M ,
 205 .IR convA2M ,
 206 .IR convTR2M ,
 207 and
 208 .I convPR2M
 209 convert tickets, authenticators, ticket requests, and password change request
 210 structures into transmittable messages.
 211 .IR ConvM2T ,
 212 .IR convM2A ,
 213 .IR convM2TR ,
 214 and
 215 .I convM2PR
 216 are used to convert them back.
 217 .I Key
 218 is used for encrypting the message before transmission and decrypting
 219 after reception.
 220 .IR ConvA2M ,
 221 .IR convM2A ,
 222 .I convPR2M
 223 and
 224 .I convM2PR
 225 encrypt/decrypt the message with the random ticket key.
 226 .PP
 227 The routine
 228 .I _asgetticket
 229 sends a ticket request
 230 .I tr
 231 returning the two encrypted tickets in
 232 .IR buf .
 233 The routine
 234 .I _asrequest
 235 encodes the ticket request
 236 .I tr
 237 and sends it not waiting for a response.
 238 After sending a request,
 239 .I _asgetresp
 240 can be used to receive the response containing a ticket and an optional
 241 authenticator and decrypts the ticket and authenticator using
 242 .IR key .
 243 The routine
 244 .I _asrdresp
 245 receives either a character array or an error string.
 246 On error, it sets errstr and returns -1.  If successful,
 247 it returns the number of bytes received.
 248 .SH SOURCE
 249 .B /sys/src/libauthsrv
 250 .SH SEE ALSO
 251 .IR passwd (1),
 252 .IR cons (3),
 253 .IR dial (2),
 254 .IR authsrv (6),
 255 .SH DIAGNOSTICS
 256 These routines set
 257 .IR errstr .
 258 Integer-valued functions return -1 on error.