10564b1175
groff 1.23.0 added .MR to its -man macro package. The NEWS file states
that the inclusion of the macro "was prompted by its introduction to
Plan 9 from User Space's troff in August 2020." From d32deab it seems
that the name for Plan 9 from User Space's implementation was suggested
by groff maintainer G. Brandon Robinson.
Not sure if the intention was to make these definitions compatible, but
it would be nice if they were.
Currently, Plan 9 from User Space's .MR expects its second argument to
be parenthesized. groff's .MR does not. This results in extra
parentheses appearing in manual references when viewing Plan 9 from User
Space's manual pages on a system using groff.
444 lines
8.5 KiB
Groff
444 lines
8.5 KiB
Groff
.TH AUTH 3
|
|
.SH NAME
|
|
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, fsauth_proxy, fsfauth_proxy, fsamount, nsamount\- 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(void);
|
|
.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(AuthRpc *rpc);
|
|
.PP
|
|
.B
|
|
#include <9pclient.h>
|
|
.PP
|
|
.B
|
|
AuthInfo* fsauth_proxy(CFid *fid, AuthGetkey *getkey, char *fmt, ...);
|
|
.PP
|
|
.B
|
|
AuthInfo* fsfauth_proxy(CFid *fid, AuthRpc *rpc, AuthGetkey *getkey,
|
|
.br
|
|
.B char *params);
|
|
.PP
|
|
.B
|
|
CFsys* fsamount(int fd, char *aname);
|
|
.PP
|
|
.B
|
|
CFsys* nsamount(char *name, char *aname);
|
|
.SH DESCRIPTION
|
|
.PP
|
|
This library, in concert with
|
|
.MR 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
|
|
.MR 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 is meaningful only on Plan 9.
|
|
.\" 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, as opened by
|
|
.IR auth_allocrpc.
|
|
An
|
|
.B sprint
|
|
(see
|
|
.MR print 3 )
|
|
of
|
|
.I fmt
|
|
and the variable arg list yields a key template (see
|
|
.MR 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
|
|
.IR auth_allocrpc .
|
|
.I Auth_allocrpc
|
|
arranges a connection to
|
|
.IR factotum ,
|
|
either by opening
|
|
.B /mnt/factotum/rpc
|
|
or by using
|
|
.MR 9pclient 3
|
|
to connect to a
|
|
.B factotum
|
|
service posted in the current name space.
|
|
The returned connection
|
|
is freed using
|
|
.IR auth_freerpc .
|
|
Individual commands can be sent to
|
|
.MR 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 factotum
|
|
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.
|
|
.PP
|
|
.I Fsauth_proxy
|
|
and
|
|
.I fsfauth_proxy
|
|
are like
|
|
.I auth_proxy
|
|
and
|
|
.I fauth_proxy
|
|
but execute the protocol on a
|
|
.B CFid*
|
|
(see
|
|
.MR 9pclient 3 )
|
|
instead of a file descriptor.
|
|
.PP
|
|
.I Fsamount
|
|
and
|
|
.I nsamount
|
|
are like
|
|
.I fsmount
|
|
and
|
|
.I nsmount
|
|
(see
|
|
.MR 9pclient 3 )
|
|
but use
|
|
.I factotum
|
|
to authenticate to the file servers.
|
|
.SH SOURCE
|
|
.B \*9/src/libauth
|
|
.SH SEE ALSO
|
|
.MR factotum 4 ,
|
|
.MR authsrv 3
|
|
.SH DIAGNOSTICS
|
|
These routines set
|
|
.IR errstr .
|