Lots of man pages.
This commit is contained in:
rsc
parent
08df2a433e
commit
cfa37a7b11
152 changed files with 25407 additions and 148 deletions
395
man/man3/auth.3
Normal file
395
man/man3/auth.3
Normal file
|
|
@ -0,0 +1,395 @@
|
|||
.TH AUTH 3
|
||||
.SH NAME
|
||||
amount, newns, addns, login, noworld, auth_proxy, fauth_proxy, auth_allocrpc, auth_freerpc, auth_rpc, auth_getkey, amount_getkey, auth_freeAI, auth_chuid, auth_challenge, auth_response, auth_freechal, auth_respond, auth_userpasswd, auth_getuserpasswd, auth_getinfo\- routines for authenticating users
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
.PP
|
||||
.ft L
|
||||
#include <u.h>
|
||||
#include <libc.h>
|
||||
#include <auth.h>
|
||||
.fi
|
||||
.ta 11n +4n +4n +4n +4n +4n +4n
|
||||
.PP
|
||||
.B
|
||||
int newns(char *user, char *nsfile);
|
||||
.PP
|
||||
.B
|
||||
int addns(char *user, char *nsfile);
|
||||
.PP
|
||||
.B
|
||||
int amount(int fd, char *old, int flag, char *aname);
|
||||
.PP
|
||||
.B
|
||||
int login(char *user, char *password, char *namespace);
|
||||
.PP
|
||||
.B
|
||||
int noworld(char *user);
|
||||
.PP
|
||||
.B
|
||||
AuthInfo* auth_proxy(int fd, AuthGetkey *getkey, char *fmt, ...);
|
||||
.PP
|
||||
.B
|
||||
AuthInfo* fauth_proxy(int fd, AuthRpc *rpc, AuthGetkey *getkey,
|
||||
.br
|
||||
.B char *params);
|
||||
.PP
|
||||
.B
|
||||
AuthRpc* auth_allocrpc(int afd);
|
||||
.PP
|
||||
.B
|
||||
void auth_freerpc(AuthRpc *rpc);
|
||||
.PP
|
||||
.B
|
||||
uint auth_rpc(AuthRpc *rpc, char *verb, void *a, int n);
|
||||
.PP
|
||||
.B
|
||||
int auth_getkey(char *proto, char *dom);
|
||||
.PP
|
||||
.B
|
||||
int (*amount_getkey)(char*, char*);
|
||||
.PP
|
||||
.B
|
||||
void auth_freeAI(AuthInfo *ai);
|
||||
.PP
|
||||
.B
|
||||
int auth_chuid(AuthInfo *ai, char *ns);
|
||||
.PP
|
||||
.B
|
||||
Chalstate* auth_challenge(char *fmt, ...);
|
||||
.PP
|
||||
.B
|
||||
AuthInfo* auth_response(Chalstate*);
|
||||
.PP
|
||||
.B
|
||||
void auth_freechal(Chalstate*);
|
||||
.PP
|
||||
.B
|
||||
int auth_respond(void *chal, uint nchal, char *user, uint nuser, void *resp, uint nresp, AuthGetkey *getkey, char *fmt, ...);
|
||||
.PP
|
||||
.B
|
||||
AuthInfo* auth_userpasswd(char*user, char*password);
|
||||
.PP
|
||||
.B
|
||||
UserPasswd* auth_getuserpasswd(AuthGetkey *getkey, char*fmt, ...);
|
||||
.PP
|
||||
.B
|
||||
AuthInfo* auth_getinfo(int fd);
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
This library, in concert with
|
||||
.IR factotum (4),
|
||||
is used to authenticate users.
|
||||
It provides the primary interface to
|
||||
.IR factotum .
|
||||
.PP
|
||||
.I Newns
|
||||
builds a name space for
|
||||
.IR user .
|
||||
It opens the file
|
||||
.I nsfile
|
||||
.RB ( /lib/namespace
|
||||
is used if
|
||||
.I nsfile
|
||||
is null),
|
||||
copies the old environment, erases the current name space,
|
||||
sets the environment variables
|
||||
.B user
|
||||
and
|
||||
.BR home ,
|
||||
and interprets the commands in
|
||||
.IR nsfile .
|
||||
The format of
|
||||
.I nsfile
|
||||
is described in
|
||||
.IR namespace (6).
|
||||
.PP
|
||||
.I Addns
|
||||
also interprets and executes the commands in
|
||||
.IR nsfile .
|
||||
Unlike
|
||||
.I newns
|
||||
it applies the command to the current name space
|
||||
rather than starting from scratch.
|
||||
.PP
|
||||
.I Amount
|
||||
is like
|
||||
.I mount
|
||||
but performs any authentication required.
|
||||
It should be used instead of
|
||||
.I mount
|
||||
whenever the file server being mounted requires authentication.
|
||||
See
|
||||
.IR bind (2)
|
||||
for a definition of the arguments to
|
||||
.I mount
|
||||
and
|
||||
.IR amount .
|
||||
.PP
|
||||
.I Login
|
||||
changes the user id of the process
|
||||
.I user
|
||||
and recreates the namespace using the file
|
||||
.I namespace
|
||||
(default
|
||||
.BR /lib/nnamespace ).
|
||||
It uses
|
||||
.I auth_userpassword
|
||||
and
|
||||
.IR auth_chuid .
|
||||
.PP
|
||||
.I Noworld
|
||||
returns 1 if the user is in the group
|
||||
.B noworld
|
||||
in
|
||||
.BR /adm/users .
|
||||
Otherwise, it returns 0.
|
||||
.I Noworld
|
||||
is used by telnetd and ftpd to provide sandboxed
|
||||
access for some users.
|
||||
.PP
|
||||
The following routines use the
|
||||
.B AuthInfo
|
||||
structure returned after a successful authentication by
|
||||
.IR factotum (4).
|
||||
.PP
|
||||
.ne 8
|
||||
.EX
|
||||
.ta 4n +4n +4n +4n +4n +4n +4n +4n +4n
|
||||
typedef struct
|
||||
{
|
||||
char *cuid; /* caller id */
|
||||
char *suid; /* server id */
|
||||
char *cap; /* capability */
|
||||
int nsecret; /* length of secret */
|
||||
uchar *secret; /* secret */
|
||||
} AuthInfo;
|
||||
.EE
|
||||
.sp
|
||||
The fields
|
||||
.B cuid
|
||||
and
|
||||
.B suid
|
||||
point to the authenticated ids of the client and server.
|
||||
.B Cap
|
||||
is a capability returned only to the server.
|
||||
It can be passed to the
|
||||
.IR cap (3)
|
||||
device to change the user id of the process.
|
||||
.B Secret
|
||||
is an
|
||||
.BR nsecret -byte
|
||||
shared secret that can be used by the client and server to
|
||||
create encryption and hashing keys for the rest of the
|
||||
conversation.
|
||||
.PP
|
||||
.I Auth_proxy
|
||||
proxies an authentication conversation between a remote
|
||||
server reading and writing
|
||||
.I fd
|
||||
and a
|
||||
.I factotum
|
||||
file. The
|
||||
.I factotum
|
||||
file used is
|
||||
.BR /mnt/factotum/rpc .
|
||||
An
|
||||
.B sprint
|
||||
(see
|
||||
.IR print (2))
|
||||
of
|
||||
.I fmt
|
||||
and the variable arg list yields a key template (see
|
||||
.IR factotum (4))
|
||||
specifying the key to use.
|
||||
The template must specify at least the protocol (
|
||||
.BI proto= xxx )
|
||||
and the role (either
|
||||
.B role=client
|
||||
or
|
||||
.BR role=server ).
|
||||
.I Auth_proxy
|
||||
either returns an allocated
|
||||
.B AuthInfo
|
||||
structure, or sets the error string and
|
||||
returns nil.
|
||||
.PP
|
||||
.I Fauth_proxy
|
||||
can be used instead of
|
||||
.I auth_proxy
|
||||
if a single connection to
|
||||
.I factotum
|
||||
will be used for multiple authentications.
|
||||
This is necessary, for example, for
|
||||
.I newns
|
||||
which must open the
|
||||
.I factotum
|
||||
file before wiping out the namespace.
|
||||
.I Fauth_proxy
|
||||
takes as an argument a pointer to an
|
||||
.B AuthRPC
|
||||
structure which contains an fd for an open connection to
|
||||
.I factotum
|
||||
in addition to storage and state information for
|
||||
the protocol.
|
||||
An
|
||||
.B AuthRPC
|
||||
structure is obtained by calling
|
||||
.I auth_allocrpc
|
||||
with the fd of an open
|
||||
.I factotum
|
||||
connection.
|
||||
It is freed using
|
||||
.IR auth_freerpc .
|
||||
Individual commands can be sent to
|
||||
.IR factotum (4)
|
||||
by invoking
|
||||
.IR auth_rpc .
|
||||
.PP
|
||||
Both
|
||||
.I auth_proxy
|
||||
and
|
||||
.I fauth_proxy
|
||||
take a pointer to a routine,
|
||||
.IR getkey ,
|
||||
to invoke should
|
||||
.I factotum
|
||||
not posess a key for the authentication. If
|
||||
.I getkey
|
||||
is nil, the authentication fails.
|
||||
.I Getkey
|
||||
is called with a key template for the desired
|
||||
key.
|
||||
We have provided a generic routine,
|
||||
.IR auth_getkey ,
|
||||
which queries the user for
|
||||
the key information and passes it to
|
||||
.IR factotum .
|
||||
This is the default for the global variable,
|
||||
.IR amount_getkey ,
|
||||
which holds a pointer to the key prompting routine used by
|
||||
.IR amount .
|
||||
.PP
|
||||
.I Auth_chuid
|
||||
uses the
|
||||
.B cuid
|
||||
and
|
||||
.B cap
|
||||
fields of an
|
||||
.B AuthInfo
|
||||
structure to change the user id of the current
|
||||
process and uses
|
||||
.IR ns ,
|
||||
default
|
||||
.BR /lib/namespace ,
|
||||
to build it a new name space.
|
||||
.PP
|
||||
.I Auth_challenge
|
||||
and
|
||||
.I auth_response
|
||||
perform challenge/response protocols with
|
||||
.IR factotum .
|
||||
State between the challenge and response phase are
|
||||
kept in the
|
||||
.B Chalstate
|
||||
structure:
|
||||
.sp
|
||||
.EX
|
||||
struct Chalstate
|
||||
{
|
||||
char *user;
|
||||
char chal[MAXCHLEN];
|
||||
int nchal;
|
||||
void *resp;
|
||||
int nresp;
|
||||
|
||||
/* for implementation only */
|
||||
int afd;
|
||||
AuthRpc *rpc;
|
||||
char userbuf[MAXNAMELEN];
|
||||
int userinchal;
|
||||
};
|
||||
.EE
|
||||
.sp
|
||||
.I Auth_challenge
|
||||
requires a key template generated by an
|
||||
.B sprint
|
||||
of
|
||||
.I fmt
|
||||
and the variable arguments. It must contain the protocol
|
||||
(\fBproto=\fIxxx\fR)
|
||||
and depending on the protocol, the user name (
|
||||
.BI user= xxx \fR).\fP
|
||||
.B P9cr
|
||||
and
|
||||
.B vnc
|
||||
expect the user specified as an attribute in
|
||||
the key template and
|
||||
.BR apop ,
|
||||
.BR cram ,
|
||||
and
|
||||
.BR chap
|
||||
expect it in the
|
||||
.B user
|
||||
field of the arg to
|
||||
.IR auth_response .
|
||||
For all protocols, the response is returned
|
||||
to
|
||||
.I auth_response
|
||||
in the
|
||||
.I resp
|
||||
field of the
|
||||
.BR Chalstate .
|
||||
.I Chalstate.nresp
|
||||
must be the length of the response.
|
||||
.PP
|
||||
Supply to
|
||||
.I auth_respond
|
||||
a challenge string and the fmt and args specifying a key,
|
||||
and it will use
|
||||
.I factotum
|
||||
to return the proper user and response.
|
||||
.PP
|
||||
.I Auth_userpasswd
|
||||
verifies a simple user/password pair.
|
||||
.I Auth_getuserpasswd
|
||||
retrieves a user/password pair from
|
||||
.I factotum
|
||||
if permitted.
|
||||
.PP
|
||||
.I Auth_getinfo
|
||||
reads an
|
||||
.B AuthInfo
|
||||
message from
|
||||
.I fd
|
||||
and converts it into a structure. It is only
|
||||
used by the other routines in this library when
|
||||
communicating with
|
||||
.IR factotum .
|
||||
.PP
|
||||
.ne 8
|
||||
.EX
|
||||
.ta 4n +4n +4n +4n +4n +4n +4n +4n +4n
|
||||
typedef struct UserPasswd {
|
||||
char *user;
|
||||
char *passwd;
|
||||
} UserPasswd;
|
||||
.EE
|
||||
.sp
|
||||
.PP
|
||||
.I Auth_freeAI
|
||||
is used to free an
|
||||
.B AuthInfo
|
||||
structure returned by one of these routines.
|
||||
Similary
|
||||
.I auth_freechal
|
||||
frees a challenge/response state.
|
||||
.SH SOURCE
|
||||
.B /sys/src/libauth
|
||||
.SH SEE ALSO
|
||||
.IR factotum (4),
|
||||
.IR authsrv (2),
|
||||
.IR bind (2)
|
||||
.SH DIAGNOSTICS
|
||||
These routines set
|
||||
.IR errstr .
|
||||
Loading…
Add table
Add a link
Reference in a new issue