.\"	$OpenBSD: rpcauth.3,v 1.12 2006/11/10 17:29:31 grunk Exp $
.\" Mostly converted to mandoc by Theo de Raadt, Tue Feb 24 04:04:46 MST 1998
.\"
.\" Sun RPC is a product of Sun Microsystems, Inc. and is provided for
.\" unrestricted use provided that this legend is included on all tape
.\" media and as a part of the software program in whole or part.  Users
.\" may copy or modify Sun RPC without charge, but are not authorized
.\" to license or distribute it to anyone else except as part of a product or
.\" program developed by the user.
.\"
.\" SUN RPC IS PROVIDED AS IS WITH NO WARRANTIES OF ANY KIND INCLUDING THE
.\" WARRANTIES OF DESIGN, MERCHANTIBILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE, OR ARISING FROM A COURSE OF DEALING, USAGE OR TRADE PRACTICE.
.\"
.\" Sun RPC is provided with no support and without any obligation on the
.\" part of Sun Microsystems, Inc. to assist in its use, correction,
.\" modification or enhancement.
.\"
.\" SUN MICROSYSTEMS, INC. SHALL HAVE NO LIABILITY WITH RESPECT TO THE
.\" INFRINGEMENT OF COPYRIGHTS, TRADE SECRETS OR ANY PATENTS BY SUN RPC
.\" OR ANY PART THEREOF.
.\"
.\" In no event will Sun Microsystems, Inc. be liable for any lost revenue
.\" or profits or other special, indirect and consequential damages, even if
.\" Sun has been advised of the possibility of such damages.
.\"
.\" Sun Microsystems, Inc.
.\" 2550 Garcia Avenue
.\" Mountain View, California  94043
.\"
.Dd February 16, 1988
.Dt RPC 3
.Os
.Sh NAME
.Nm auth_destroy ,
.Nm authnone_create ,
.Nm authunix_create ,
.Nm authunix_create_default
.Nd library routines for remote procedure calls
.Sh SYNOPSIS
.Fd #include <rpc/rpc.h>
.Ft void
.Fn auth_destroy "AUTH *auth"
.Ft AUTH *
.Fn authnone_create "void"
.Ft AUTH *
.Fn authunix_create "char *host" "int uid" "int gid" "int len" "int *aup.gids"
.Ft AUTH *
.Fn authunix_create_default "void"
.Ft void
.Fn set_rpc_maxgrouplist "int num"
.Sh DESCRIPTION
These routines establish authentication information for use by the
RPC functions described in
.Xr rpc 3 .
.Pp
.Fn auth_destroy
is a macro that destroys the authentication information associated with
.Fa auth .
Destruction usually involves deallocation of private data structures.
The use of
.Fa auth
is undefined after calling
.Fn auth_destroy .
.Pp
.Fn authnone_create
creates and returns an
.Tn RPC
authentication handle that passes nonusable authentication
information with each remote procedure call.
This is the default authentication used by
.Tn RPC .
.Pp
.Fn authunix_create
creates and returns an
.Tn RPC
authentication handle that contains
.Ux
authentication information.
The parameter
.Fa host
is the name of the machine on which the information was
created;
.Fa uid
is the user's user ID;
.Fa gid
is the user's current group ID;
.Fa len
and
.Fa aup_gids
refer to a counted array of groups to which the user belongs.
It is easy to impersonate a user.
.Pp
.Fn authunix_create_default
calls
.Fn authunix_create
with the appropriate parameters.
.Pp
.Fn set_rpc_maxgrouplist
allows the application to set the maximum size of the group list that
will be used in
.Fn authunix_create_default
to
.Fa num .
Some servers will refuse mounts if the group list is larger than it
expects (like 8).
.Sh SEE ALSO
.\"Xr rpc_secure 3 ,
.Xr rpcgen 1 ,
.Xr select 2 ,
.Xr getrpcport 3 ,
.Xr rpc 3 ,
.Xr xdr 3 ,
.Xr rpc 5 ,
.Xr portmap 8
.Rs
.%T "Remote Procedure Calls: Protocol Specification"
.Re
.Rs
.%T "Remote Procedure Call Programming Guide"
.Re
.Rs
.%T "rpcgen Programming Guide"
.Re
.Rs
.%A "Sun Microsystems, Inc."
.%T "RPC: Remote Procedure Call Protocol Specification"
.%R "RFC 1057, USC-ISI"
.Re