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, _asgetpakkey, authpak_hash, authpak_new, authpak_finish \- 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 .PP
  62 .B
  63 int     _asgetpakkey(int fd, Ticketreq *tr, Authkey *a)
  64 .PP
  65 .B
  66 void    authpak_hash(Authkey *k, char *u)
  67 .PP
  68 .B
  69 void    authpak_new(PAKpriv *p, Authkey *k, uchar y[PAKYLEN], int isclient)
  70 .PP
  71 .B
  72 int     authpak_finish(PAKpriv *p, Authkey *k, uchar y[PAKYLEN])
  73 .SH DESCRIPTION
  74 .I Authdial
  75 dials an authentication server over the
  76 network rooted at
  77 .IR net ,
  78 default
  79 .BR /net  .
  80 The authentication domain,
  81 .IR ad ,
  82 specifies which server to call.
  83 If
  84 .I ad
  85 is non-nil,
  86 the connection server
  87 .B cs
  88 (see
  89 .IR ndb (8))
  90 is queried for an entry which contains
  91 .B authdom=\fIad\fP
  92 or
  93 .BR dom=\fIad\fP ,
  94 the former having precedence,
  95 and which also contains an
  96 .B auth
  97 attribute.
  98 If it finds neither, it tries
  99 .BI p9auth. ad
 100 in DNS as the authentication server.
 101 The string dialed is then
 102 .I netroot\fP!\fIserver\fP!ticket
 103 where
 104 .I server
 105 is the value of the
 106 .B auth
 107 attribute.
 108 If no entry is found, the error string is
 109 set to ``no authentication server found''
 110 and -1 is returned.
 111 If
 112 .I authdom
 113 is nil, the string
 114 .IB netroot !$auth! ticket
 115 is used to make the call.
 116 .PP
 117 .I Passtokey
 118 converts
 119 .I password
 120 into a set of cryptographic keys and stores them in the
 121 .I Authkey
 122 structure
 123 .IR key .
 124 .PP
 125 .I Readnvram
 126 reads authentication information into the structure:
 127 .PP
 128 .EX
 129 .ta 4n +4n +8n +4n +4n +4n +4n
 130 struct Nvrsafe
 131 {
 132         char    machkey[DESKEYLEN];     /* was file server's authid's des key */
 133         uchar   machsum;
 134         char    authkey[DESKEYLEN];     /* authid's des key from password */
 135         uchar   authsum;
 136         /*
 137          * file server config string of device holding full configuration;
 138          * secstore key on non-file-servers.
 139          */
 140         char    config[CONFIGLEN];
 141         uchar   configsum;
 142         char    authid[ANAMELEN];       /* auth userid, e.g., bootes */
 143         uchar   authidsum;
 144         char    authdom[DOMLEN]; /* auth domain, e.g., cs.bell-labs.com */
 145         uchar   authdomsum;
 146
 147         uchar   aesmachkey[AESKEYLEN];
 148         uchar   aesmachsum;
 149 };
 150 .EE
 151 .PP
 152 On Sparc, MIPS, and SGI machines this information is
 153 in non-volatile ram, accessible in the file
 154 .BR #r/nvram .
 155 On x86s and Alphas
 156 .I readnvram
 157 successively opens the following areas stopping with the
 158 first to succeed:
 159 .PP
 160 \- the partition named by the
 161 .B $nvram
 162 environment variable
 163 (commonly set via
 164 .IR plan9.ini (8))
 165 .br
 166 \- the partition
 167 .B #S/sdC0/nvram
 168 .br
 169 \- a file called
 170 .B plan9.nvr
 171 in the partition
 172 .B #S/sdC0/9fat
 173 .br
 174 \- the partition
 175 .B #S/sd00/nvram
 176 .br
 177 \- a file called
 178 .B plan9.nvr
 179 in the partition
 180 .B #S/sd00/9fat
 181 .br
 182 \- a file called
 183 .B plan9.nvr
 184 on a DOS floppy in drive 0
 185 .br
 186 \- a file called
 187 .B plan9.nvr
 188 on a DOS floppy in drive 1
 189 .PP
 190 The
 191 .IR nvcsum s
 192 of the fields
 193 .BR machkey ,
 194 .BR authid ,
 195 and
 196 .B authdom
 197 must match their respective checksum or that field is zeroed.
 198 If
 199 .I flag
 200 is
 201 .B NVwrite
 202 or at least one checksum fails and
 203 .I flag
 204 is
 205 .BR NVwriteonerr ,
 206 .I readnvram
 207 will prompt for new values on
 208 .B #c/cons
 209 and then write them back to the storage area.
 210 If
 211 .I flag
 212 is
 213 .BR NVwritemem ,
 214 .I readnvram
 215 will write the values in
 216 .I *nv
 217 back to the storage area.
 218 .PP
 219 .IR ConvT2M ,
 220 .IR convA2M ,
 221 .IR convTR2M ,
 222 and
 223 .I convPR2M
 224 convert tickets, authenticators, ticket requests, and password change request
 225 structures into transmittable messages.
 226 .IR ConvM2T ,
 227 .IR convM2A ,
 228 .IR convM2TR ,
 229 and
 230 .I convM2PR
 231 are used to convert them back.
 232 .I Key
 233 is used for encrypting the message before transmission and decrypting
 234 after reception.
 235 .IR ConvA2M ,
 236 .IR convM2A ,
 237 .I convPR2M
 238 and
 239 .I convM2PR
 240 encrypt/decrypt the message with the random ticket key.
 241 .PP
 242 The routine
 243 .I _asgetticket
 244 sends a ticket request
 245 .I tr
 246 returning the two encrypted tickets in
 247 .IR buf .
 248 The routine
 249 .I _asrequest
 250 encodes the ticket request
 251 .I tr
 252 and sends it not waiting for a response.
 253 After sending a request,
 254 .I _asgetresp
 255 can be used to receive the response containing a ticket and an optional
 256 authenticator and decrypts the ticket and authenticator using
 257 .IR key .
 258 The routine
 259 .I _asrdresp
 260 receives either a character array or an error string.
 261 On error, it sets errstr and returns -1.  If successful,
 262 it returns the number of bytes received.
 263 .PP
 264 .I Authpak_hash
 265 prepares a
 266 .I Authkey
 267 structure for a password authenticated key exchange (see
 268 .IR authsrv (6))
 269 by calculating the pakhash from a user's aeskey and id
 270 .IR u .
 271 The fuction hashes the password derived aeskey and user id together
 272 using hmac_sha256 and maps the result into two elliptic curve points
 273 PN/PM on the Ed448-goldielocks curve using elligator2.
 274 .PP
 275 .I Authpak_new
 276 generates a new elliptic curve diffie-hellman key pair for a password
 277 authenticated key exchange from a previously hashed
 278 .I Authkey
 279 structure
 280 .IR k .
 281 The randomly generated private key is returned in the
 282 .I PAKpriv
 283 structure passed in
 284 .IR p ,
 285 while the pakhash encrytped public key is returned in
 286 .IR y .
 287 .PP
 288 .I Authpak_finish
 289 completes a password authenticated key exchange, taking the other
 290 sides pakhash encrypted public key
 291 .I y
 292 and our private key
 293 .I p
 294 returning the shared secret pakkey in the
 295 .I Authkey
 296 structure
 297 .IR k .
 298 The function returns zero on success or non-zero on failure (malformed
 299 public key).
 300 .PP
 301 The function
 302 .I _asgetpakkey
 303 establishes a new shared pakkey between the us and the authentication server
 304 for ticket encryption; using the functions above; taking a previously hashed
 305 .I Authkey
 306 .I a
 307 and
 308 .I Ticketreq
 309 .I tr
 310 and returns the shared pakkey in the
 311 .I Authkey
 312 structure. It is usually called before
 313 .I _asrequest
 314 right after
 315 .IR authdial
 316 to negotiate bruteforce resistant ticket encryption for the
 317 ticket request that follows (see
 318 .IR authsrv (6)).
 319 Returns zero on success, or non-zero on error (authenticatoin
 320 server does not support the AuthPAK request or when we got a malformed public key).
 321 .SH SOURCE
 322 .B /sys/src/libauthsrv
 323 .SH SEE ALSO
 324 .IR passwd (1),
 325 .IR cons (3),
 326 .IR dial (2),
 327 .IR authsrv (6),
 328 .SH DIAGNOSTICS
 329 These routines set
 330 .IR errstr .
 331 Integer-valued functions return -1 on error.