332 lines
7 KiB
Plaintext
332 lines
7 KiB
Plaintext
.TH AUTHSRV 2
|
|
.SH NAME
|
|
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
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.PP
|
|
.ft L
|
|
#include <u.h>
|
|
#include <libc.h>
|
|
#include <authsrv.h>
|
|
.fi
|
|
.ta 8n +4n +4n +4n +4n +4n +4n
|
|
.PP
|
|
.B
|
|
int authdial(char *netroot, char *ad);
|
|
.PP
|
|
.B
|
|
void passtokey(Authkey *key, char *password)
|
|
.PP
|
|
.B
|
|
uchar nvcsum(void *mem, int len)
|
|
.PP
|
|
.B
|
|
int readnvram(Nvrsafe *nv, int flag);
|
|
.PPP
|
|
.B
|
|
int convT2M(Ticket *t, char *msg, int len, Authkey *key)
|
|
.PP
|
|
.B
|
|
int convM2T(char *msg, int len, Ticket *t, Authkey *key)
|
|
.PP
|
|
.B
|
|
int convA2M(Authenticator *a, char *msg, int len, Ticket *t)
|
|
.PP
|
|
.B
|
|
int convM2A(char *msg, int len, Authenticator *a, Ticket *t)
|
|
.PP
|
|
.B
|
|
int convTR2M(Ticketreq *tr, char *msg, int len)
|
|
.PP
|
|
.B
|
|
int convM2TR(char *msg, int len, Ticketreq *tr)
|
|
.PP
|
|
.B
|
|
int convPR2M(Passwordreq *pr, char *msg, int len, Ticket *t)
|
|
.PP
|
|
.B
|
|
int convM2PR(char *msg, int len, Passwordreq *pr, Ticket *t)
|
|
.PP
|
|
.B
|
|
int _asgetticket(int fd, Ticketreq *tr, char *buf, int len)
|
|
.PP
|
|
.B
|
|
int _asrequest(int fd, Ticketreq *tr)
|
|
.PP
|
|
.B
|
|
int _asgetresp(int fd, Ticket *t, Authenticator *a, Authkey *key)
|
|
.PP
|
|
.B
|
|
int _asrdresp(int fd, char *buf, int len)
|
|
.PP
|
|
.B
|
|
int _asgetpakkey(int fd, Ticketreq *tr, Authkey *a)
|
|
.PP
|
|
.B
|
|
void authpak_hash(Authkey *k, char *u)
|
|
.PP
|
|
.B
|
|
void authpak_new(PAKpriv *p, Authkey *k, uchar y[PAKYLEN], int isclient)
|
|
.PP
|
|
.B
|
|
int authpak_finish(PAKpriv *p, Authkey *k, uchar y[PAKYLEN])
|
|
.SH DESCRIPTION
|
|
.I Authdial
|
|
dials an authentication server over the
|
|
network rooted at
|
|
.IR net ,
|
|
default
|
|
.BR /net .
|
|
The authentication domain,
|
|
.IR ad ,
|
|
specifies which server to call.
|
|
If
|
|
.I ad
|
|
is non-nil,
|
|
the connection server
|
|
.B cs
|
|
(see
|
|
.IR ndb (8))
|
|
is queried for an entry which contains
|
|
.B authdom=\fIad\fP
|
|
or
|
|
.BR dom=\fIad\fP ,
|
|
the former having precedence,
|
|
and which also contains an
|
|
.B auth
|
|
attribute.
|
|
If it finds neither, it tries
|
|
.BI p9auth. ad
|
|
in DNS as the authentication server.
|
|
The string dialed is then
|
|
.I netroot\fP!\fIserver\fP!ticket
|
|
where
|
|
.I server
|
|
is the value of the
|
|
.B auth
|
|
attribute.
|
|
If no entry is found, the error string is
|
|
set to ``no authentication server found''
|
|
and -1 is returned.
|
|
If
|
|
.I authdom
|
|
is nil, the string
|
|
.IB netroot !$auth! ticket
|
|
is used to make the call.
|
|
.PP
|
|
.I Passtokey
|
|
converts
|
|
.I password
|
|
into a set of cryptographic keys and stores them in the
|
|
.I Authkey
|
|
structure
|
|
.IR key .
|
|
.PP
|
|
.I Readnvram
|
|
reads authentication information into the structure:
|
|
.PP
|
|
.EX
|
|
.ta 4n +4n +8n +4n +4n +4n +4n
|
|
struct Nvrsafe
|
|
{
|
|
char machkey[DESKEYLEN]; /* was file server's authid's des key */
|
|
uchar machsum;
|
|
char authkey[DESKEYLEN]; /* authid's des key from password */
|
|
uchar authsum;
|
|
/*
|
|
* file server config string of device holding full configuration;
|
|
* secstore key on non-file-servers.
|
|
*/
|
|
char config[CONFIGLEN];
|
|
uchar configsum;
|
|
char authid[ANAMELEN]; /* auth userid, e.g., bootes */
|
|
uchar authidsum;
|
|
char authdom[DOMLEN]; /* auth domain, e.g., cs.bell-labs.com */
|
|
uchar authdomsum;
|
|
|
|
uchar aesmachkey[AESKEYLEN];
|
|
uchar aesmachsum;
|
|
};
|
|
.EE
|
|
.PP
|
|
On Sparc, MIPS, and SGI machines this information is
|
|
in non-volatile ram, accessible in the file
|
|
.BR #r/nvram .
|
|
On x86s and Alphas
|
|
.I readnvram
|
|
successively opens the following areas stopping with the
|
|
first to succeed:
|
|
.PP
|
|
\- the partition named by the
|
|
.B $nvram
|
|
environment variable
|
|
(commonly set via
|
|
.IR plan9.ini (8))
|
|
.br
|
|
\- the partition
|
|
.B #S/sdC0/nvram
|
|
.br
|
|
\- a file called
|
|
.B plan9.nvr
|
|
in the partition
|
|
.B #S/sdC0/9fat
|
|
.br
|
|
\- the partition
|
|
.B #S/sd00/nvram
|
|
.br
|
|
\- a file called
|
|
.B plan9.nvr
|
|
in the partition
|
|
.B #S/sd00/9fat
|
|
.br
|
|
\- a file called
|
|
.B plan9.nvr
|
|
on a DOS floppy in drive 0
|
|
.br
|
|
\- a file called
|
|
.B plan9.nvr
|
|
on a DOS floppy in drive 1
|
|
.PP
|
|
The
|
|
.IR nvcsum s
|
|
of the fields
|
|
.BR machkey ,
|
|
.BR authid ,
|
|
and
|
|
.B authdom
|
|
must match their respective checksum or that field is zeroed.
|
|
If
|
|
.I flag
|
|
is
|
|
.B NVwrite
|
|
or at least one checksum fails and
|
|
.I flag
|
|
is
|
|
.BR NVwriteonerr ,
|
|
.I readnvram
|
|
will prompt for new values on
|
|
.B #c/cons
|
|
and then write them back to the storage area.
|
|
If
|
|
.I flag
|
|
is
|
|
.BR NVwritemem ,
|
|
.I readnvram
|
|
will write the values in
|
|
.I *nv
|
|
back to the storage area.
|
|
.PP
|
|
.IR ConvT2M ,
|
|
.IR convA2M ,
|
|
.IR convTR2M ,
|
|
and
|
|
.I convPR2M
|
|
convert tickets, authenticators, ticket requests, and password change request
|
|
structures into transmittable messages.
|
|
.IR ConvM2T ,
|
|
.IR convM2A ,
|
|
.IR convM2TR ,
|
|
and
|
|
.I convM2PR
|
|
are used to convert them back.
|
|
.I Key
|
|
is used for encrypting the message before transmission and decrypting
|
|
after reception.
|
|
.IR ConvA2M ,
|
|
.IR convM2A ,
|
|
.I convPR2M
|
|
and
|
|
.I convM2PR
|
|
encrypt/decrypt the message with the random ticket key.
|
|
.PP
|
|
The routine
|
|
.I _asgetticket
|
|
sends a ticket request
|
|
.I tr
|
|
returning the two encrypted tickets in
|
|
.IR buf .
|
|
The routine
|
|
.I _asrequest
|
|
encodes the ticket request
|
|
.I tr
|
|
and sends it not waiting for a response.
|
|
After sending a request,
|
|
.I _asgetresp
|
|
can be used to receive the response containing a ticket and an optional
|
|
authenticator and decrypts the ticket and authenticator using
|
|
.IR key .
|
|
The routine
|
|
.I _asrdresp
|
|
receives either a character array or an error string.
|
|
On error, it sets errstr and returns -1. If successful,
|
|
it returns the number of bytes received.
|
|
.PP
|
|
.I Authpak_hash
|
|
prepares a
|
|
.I Authkey
|
|
structure for a password authenticated key exchange (see
|
|
.IR authsrv (6))
|
|
by calculating the pakhash from a user's aeskey and id
|
|
.IR u .
|
|
The fuction hashes the password derived aeskey and user id together
|
|
using hmac_sha256 and maps the result into two elliptic curve points
|
|
PN/PM on the Ed448-goldielocks curve using elligator2.
|
|
.PP
|
|
.I Authpak_new
|
|
generates a new elliptic curve diffie-hellman key pair for a password
|
|
authenticated key exchange from a previously hashed
|
|
.I Authkey
|
|
structure
|
|
.IR k .
|
|
The randomly generated private key is returned in the
|
|
.I PAKpriv
|
|
structure passed in
|
|
.IR p ,
|
|
while the pakhash encrytped public key is returned in
|
|
.IR y .
|
|
.PP
|
|
.I Authpak_finish
|
|
completes a password authenticated key exchange, taking the other
|
|
sides pakhash encrypted public key
|
|
.I y
|
|
and our private key
|
|
.I p
|
|
returning the shared secret pakkey in the
|
|
.I Authkey
|
|
structure
|
|
.IR k .
|
|
The function returns zero on success or non-zero on failure (malformed
|
|
public key).
|
|
.PP
|
|
The function
|
|
.I _asgetpakkey
|
|
establishes a new shared pakkey between the us and the authentication server
|
|
for ticket encryption; using the functions above; taking a previously hashed
|
|
.I Authkey
|
|
.I a
|
|
and
|
|
.I Ticketreq
|
|
.I tr
|
|
and returns the shared pakkey in the
|
|
.I Authkey
|
|
structure. It is usually called before
|
|
.I _asrequest
|
|
right after
|
|
.IR authdial
|
|
to negotiate bruteforce resistant ticket encryption for the
|
|
ticket request that follows (see
|
|
.IR authsrv (6)).
|
|
Returns zero on success, or non-zero on error (authenticatoin
|
|
server does not support the AuthPAK request or when we got a malformed public key).
|
|
.SH SOURCE
|
|
.B /sys/src/libauthsrv
|
|
.SH SEE ALSO
|
|
.IR passwd (1),
|
|
.IR cons (3),
|
|
.IR dial (2),
|
|
.IR authsrv (6),
|
|
.SH DIAGNOSTICS
|
|
These routines set
|
|
.IR errstr .
|
|
Integer-valued functions return -1 on error.
|