'\"macro stdmacro
.if n .pH g3n.secure_rpc @(#)secure_rpc	40.9 of 10/10/89
.\" Copyright 1989 AT&T
.nr X
.if \nX=0 .ds x} secure_rpc 3N "" "\&"
.if \nX=1 .ds x} secure_rpc 3N ""
.if \nX=2 .ds x} secure_rpc 3N "" "\&"
.if \nX=3 .ds x} secure_rpc "" "" "\&"
.TH \*(x}
.SH NAME
.na
\f4secure_rpc\fP: \f4 authdes_seccreate\f1, \f4authdes_getucred\f1, \f4getnetname\f1, \f4host2netname\f1, \f4key_decryptsession\f1, \f4key_encryptsession\f1, \f4key_gendes\f1, \f4key_setsecret\f1, \f4netname2host\f1, \f4netname2user\f1, \f4user2netname\f1 \- library routines for secure remote procedure calls
.ad
.SH DESCRIPTION
RPC library routines allow C programs to make procedure
calls on other machines across the network.
First, the client calls a procedure to send a
data packet to the server.
Upon receipt of the packet,
the server calls a dispatch routine
to perform the requested service,
and then sends back a reply.
.P
RPC supports various authentication flavors.
Among them are:
.RS
.TP 15
.PD 0
\f4AUTH_NONE\fP
(none)  no authentication.
.TP
\f4AUTH_SYS\fP
Traditional
UNIX\(rg-style
authentication.
.TP
.PD
\f4AUTH_DES\fP
DES encryption-based authentication.
.RE
.P
The
\f4authdes_getucred\f1
and
\f4authdes_seccreate\f1
routines implement the \f4AUTH_DES\fP authentication flavor.
The keyserver daemon \f4keyserv\f1
[see \f4keyserv\fP(1M)]
must be running for the
\f4AUTH_DES\fP
authentication system to work.
.SS Routines
See \f4rpc\fP(3N) for the definition of the \f4AUTH\fP data structure.
.P
.ft 4
.nf
.sp .5
#include <rpc/rpc.h>
.br
.if t .ne 13
.P
.ft 4
.nf
.sp .5
int
authdes_getucred(const struct authdes_cred *adc, uid_t *uidp,
	gid_t *gidp, short *gidlenp, gid_t *gidlist);
.fi
.ft 1
.IP
\f4authdes_getucred\f1
is the first of the two routines which interface to the
RPC secure authentication system known as \f4AUTH_DES\fP.
The second is
\f4authdes_seccreate\f1,
below.
\f4authdes_getucred\f1
is used on the server side for converting an
\f4AUTH_DES\fP
credential,
which is operating system independent,
into an \f4AUTH_SYS\fP credential.
This routine returns \f41\f1 if it succeeds, \f40\f1 if it fails.
.IP
\f4*\f2uidp\f1
is set to the user's numerical ID associated with
\f2adc\f1.
\f4*\f2gidp\f1
is set to the numerical ID of the group to which the user
belongs.
\f4*\f2gidlist\f1
contains the numerical IDs of the other groups
to which the user belongs.
\f4*\f2gidlenp\f1
is set to the number of valid group ID entries in
\f4*\f2gidlist\f1
[see
\f4netname2user\f1, below].
.br
.if t .ne 22
.P
.ft 4
.nf
.sp .5
AUTH *
authdes_seccreate(const char *name, const unsigned int window,
	const char *timehost, const des_block *ckey);
.fi
.ft 1
.IP
\f4authdes_seccreate\f1,
the second of two 
\f4AUTH_DES\fP authentication routines,
is used on the client side to 
return an authentication handle that
will enable the use of the secure authentication system.
The first parameter
\f2name\f1
is the network name, or
\f2netname\f1,
of the owner of the server process. 
This field usually represents a hostname
derived from the utility routine
\f4host2netname\f1,
but could also represent a user name using
\f4user2netname\f1, described below.
The second field is window on the validity of
the client credential, 
given in seconds.  
A small window is more secure than a large one, 
but choosing too small of a window will increase the frequency of
resynchronizations because of clock drift. 
The third parameter,
\f2timehost\f1, the host's name,
is optional.  
If it is
\f4NULL\fP,
then the authentication system will assume
that the local clock is always in sync with the \f2timehost\f1 clock,
and will not attempt resynchronizations.
If a timehost is supplied,
however,
then the system will
consult with the remote time service whenever
resynchronization is required. 
This parameter is usually the name of the
RPC
server itself.
The final parameter
\f2ckey\f1
is also optional.
If it is
\f4NULL\fP,
then the authentication system will
generate a random
DES
key to be used for the encryption of credentials.
If 
\f2ckey\f1
is supplied,
then it will be used instead.
.if t .ne 7
.P
.ft 4
.nf
.sp .5
int
getnetname(char name[MAXNETNAMELEN+1]);
.fi
.ft 1
.IP
\f4getnetname\f1
installs the unique, 
operating-system independent netname of the
caller in the fixed-length array
\f2name\f1.
Returns \f41\f1 if it succeeds, and
\f40\f1 if it fails.
.br
.if t .ne 8
.P
.ft 4
.nf
.sp .5
int
host2netname(char name[MAXNETNAMELEN+1], const char *host,
	const char *domain);
.fi
.ft 1
.IP
Convert from a domain-specific hostname 
\f2host\f1
to an operating-system independent netname.
Return \f41\f1 if it succeeds, and \f40\f1 if it fails.
Inverse of
\f4netname2host\f1.
If
\f2domain\f1
is \f4NULL\fP,
\f4host2netname\f1
uses the default domain name of the machine.  
If
\f2host\f1
is \f4NULL\fP,
it defaults to that machine itself.
.br
.if t .ne 9
.P
.ft 4
.nf
.sp .5
int
key_decryptsession(const char *remotename, des_block *deskey);
.fi
.ft 1
.IP
\f4key_decryptsession\f1
is an interface to the keyserver daemon, 
which is associated with
RPC's
secure authentication system (\f4AUTH_DES\fP
authentication).
User programs rarely need to call it, 
or its associated routines
\f4key_encryptsession\f1,
\f4key_gendes\f1
and
\f4key_setsecret\f1.
.IP
\f4key_decryptsession\f1
takes a server netname
\f2remotename\f1
and a DES key
\f2deskey\f1, 
and decrypts the key by
using the the public key of the the server and the secret key
associated with the effective UID of the calling process.  
It is the inverse of
\f4key_encryptsession\f1.
.br
.if t .ne 8
.P
.ft 4
.nf
.sp .5
int
key_encryptsession(const char *remotename, des_block *deskey);
.fi
.ft 1
.IP
\f4key_encryptsession\f1
is a keyserver interface routine. 
It takes a server netname 
\f2remotename\f1
and a DES key
\f2deskey\f1, 
and encrypts it using the public key of the the server and the secret key
associated with the effective UID of the calling process.  
It is the inverse of
\f4key_decryptsession\f1.
This routine returns \f40\f1 if it succeeds, \f4\-1\f1 if it fails.
.br
.if t .ne 7
.P
.ft 4
.nf
.sp .5
int
key_gendes(des_block *deskey);
.fi
.ft 1
.IP
\f4key_gendes\f1
is a keyserver interface routine. 
It is used to ask the keyserver for a secure conversation key.
Choosing one at \(lqrandom\(rq is usually not good enough,
because the common ways of choosing random numbers, 
such as using the current time, 
are very easy to guess.
.br
.if t .ne 6
.P
.ft 4
.nf
.sp .5
int
key_setsecret(const char *key);
.fi
.ft 1
.IP
\f4key_setsecret\f1
is a keyserver interface routine. 
It is used to set the key for the effective
UID
of the calling process.
this routine returns \f40\f1 if it succeeds,
\f4\-1\f1 if it fails.
.br
.if t .ne 6
.P
.ft 4
.nf
.sp .5
int
netname2host(const char *name, char *host, const int hostlen);
.fi
.ft 1
.IP
Convert from an operating-system independent netname
\f2name\f1
to a domain-specific hostname
\f2host\f1.
\f2hostlen\f1
is the maximum size of
\f2host\f1.
Returns \f41\f1 if it succeeds, and \f40\f1 if it fails.
Inverse of
\f4host2netname\f1.
.br
.if t .ne 9
.P
.ft 4
.nf
.sp .5
int
netname2user(const char *name, uid_t *uidp, gid_t *gidp,
	int *gidlenp, gid_t gidlist[NGROUPS]);
.fi
.ft 1
.IP
Convert from an operating-system independent netname to a
domain-specific user
ID.
Returns \f41\f1 if it succeeds, and \f40\f1 if it fails.
Inverse of
\f4user2netname\f1.
.IP
\f4*\f2uidp\f1
is set to the user's numerical ID associated with
\f2name\f1.
\f4*\f2gidp\f1
is set to the numerical ID of the group to which the user
belongs.
\f2gidlist\f1
contains the numerical IDs of the other groups
to which the user belongs.
\f4*\f2gidlenp\f1
is set to the number of valid group ID entries in
\f2gidlist\f1.
.if t .ne 8
.P
.ft 4
.nf
.sp .5
int
user2netname(char name[MAXNETNAMELEN+1], const uid_t uid,
	const char *domain);
.fi
.ft 1
.IP
Convert from a domain-specific username to an operating-system
independent netname.
Returns \f41\f1 if it succeeds, and \f40\f1 if it fails.
Inverse of
\f4netname2user\f1.
.SH SEE ALSO
.na
\f4chkey\fP(1),
\f4keyserv\fP(1M),
\f4newkey\fP(1M),
\f4rpc\fP(3N),
\f4rpc_clnt_auth\fP(3N).
.ad
