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 int     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 It returns 0 if
 113 .I password
 114 could not be converted,
 115 and 1 otherwise.
 116 .PP
 117 .I Readnvram
 118 reads authentication information into the structure:
 119 .PP
 120 .EX
 121 .ta 4n +4n +8n +4n +4n +4n +4n
 122 struct Nvrsafe
 123 {
 124         char    machkey[DESKEYLEN];     /* was file server's authid's des key */
 125         uchar   machsum;
 126         char    authkey[DESKEYLEN];     /* authid's des key from password */
 127         uchar   authsum;
 128         /*
 129          * file server config string of device holding full configuration;
 130          * secstore key on non-file-servers.
 131          */
 132         char    config[CONFIGLEN];
 133         uchar   configsum;
 134         char    authid[ANAMELEN];       /* auth userid, e.g., bootes */
 135         uchar   authidsum;
 136         char    authdom[DOMLEN]; /* auth domain, e.g., cs.bell-labs.com */
 137         uchar   authdomsum;
 138 };
 139 .EE
 140 .PP
 141 On Sparc, MIPS, and SGI machines this information is
 142 in non-volatile ram, accessible in the file
 143 .BR #r/nvram .
 144 On x86s and Alphas
 145 .I readnvram
 146 successively opens the following areas stopping with the
 147 first to succeed:
 148 .PP
 149 \- the partition named by the
 150 .B $nvram
 151 environment variable
 152 (commonly set via
 153 .IR plan9.ini (8))
 154 .br
 155 \- the partition
 156 .B #S/sdC0/nvram
 157 .br
 158 \- a file called
 159 .B plan9.nvr
 160 in the partition
 161 .B #S/sdC0/9fat
 162 .br
 163 \- the partition
 164 .B #S/sd00/nvram
 165 .br
 166 \- a file called
 167 .B plan9.nvr
 168 in the partition
 169 .B #S/sd00/9fat
 170 .br
 171 \- a file called
 172 .B plan9.nvr
 173 on a DOS floppy in drive 0
 174 .br
 175 \- a file called
 176 .B plan9.nvr
 177 on a DOS floppy in drive 1
 178 .PP
 179 The
 180 .IR nvcsum s
 181 of the fields
 182 .BR machkey ,
 183 .BR authid ,
 184 and
 185 .B authdom
 186 must match their respective checksum or that field is zeroed.
 187 If
 188 .I flag
 189 is
 190 .B NVwrite
 191 or at least one checksum fails and
 192 .I flag
 193 is
 194 .BR NVwriteonerr ,
 195 .I readnvram
 196 will prompt for new values on
 197 .B #c/cons
 198 and then write them back to the storage area.
 199 If
 200 .I flag
 201 is
 202 .BR NVwritemem ,
 203 .I readnvram
 204 will write the values in
 205 .I *nv
 206 back to the storage area.
 207 .PP
 208 .IR ConvT2M ,
 209 .IR convA2M ,
 210 .IR convTR2M ,
 211 and
 212 .I convPR2M
 213 convert tickets, authenticators, ticket requests, and password change request
 214 structures into transmittable messages.
 215 .IR ConvM2T ,
 216 .IR convM2A ,
 217 .IR convM2TR ,
 218 and
 219 .I convM2PR
 220 are used to convert them back.
 221 .I Key
 222 is used for encrypting the message before transmission and decrypting
 223 after reception.
 224 .IR ConvA2M ,
 225 .IR convM2A ,
 226 .I convPR2M
 227 and
 228 .I convM2PR
 229 encrypt/decrypt the message with the random ticket key.
 230 .PP
 231 The routine
 232 .I _asgetticket
 233 sends a ticket request
 234 .I tr
 235 returning the two encrypted tickets in
 236 .IR buf .
 237 The routine
 238 .I _asrequest
 239 encodes the ticket request
 240 .I tr
 241 and sends it not waiting for a response.
 242 After sending a request,
 243 .I _asgetresp
 244 can be used to receive the response containing a ticket and an optional
 245 authenticator and decrypts the ticket and authenticator using
 246 .IR key .
 247 The routine
 248 .I _asrdresp
 249 receives either a character array or an error string.
 250 On error, it sets errstr and returns -1.  If successful,
 251 it returns the number of bytes received.
 252 .SH SOURCE
 253 .B /sys/src/libauthsrv
 254 .SH SEE ALSO
 255 .IR passwd (1),
 256 .IR cons (3),
 257 .IR dial (2),
 258 .IR authsrv (6),
 259 .SH DIAGNOSTICS
 260 These routines set
 261 .IR errstr .
 262 Integer-valued functions return -1 on error.