secure_rpc(3N) secure_rpc(3N)
NAME
securerpc: authdesseccreate, authdesgetucred, getnetname,
host2netname, keydecryptsession, keyencryptsession, keygendes,
keysetsecret, netname2host, netname2user, user2netname - library
routines for secure remote procedure calls
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.
RPC supports various authentication flavors. Among them are:
AUTHNONE (none) no authentication.
AUTHSYS Traditional UNIX®-style authentication.
AUTHDES DES encryption-based authentication.
The authdesgetucred and authdesseccreate routines implement the
AUTHDES authentication flavor. The keyserver daemon keyserv [see
keyserv(1M)] must be running for the AUTHDES authentication system
to work.
Routines
See rpc(3N) for the definition of the AUTH data structure.
#include <rpc/rpc.h>
int
authdesgetucred(const struct authdescred *adc, uidt *uidp,
gidt *gidp, short *gidlenp, gidt *gidlist);
authdesgetucred is the first of the two routines which
interface to the RPC secure authentication system known as
AUTHDES. The second is authdesseccreate, below.
authdesgetucred is used on the server side for converting an
AUTHDES credential, which is operating system independent,
into an AUTHSYS credential. This routine returns 1 if it
succeeds, 0 if it fails.
*uidp is set to the user's numerical ID associated with adc.
*gidp is set to the numerical ID of the group to which the user
belongs. *gidlist contains the numerical IDs of the other
groups to which the user belongs. *gidlenp is set to the
number of valid group ID entries in *gidlist [see netname2user,
below].
AUTH *
authdesseccreate(const char *name, const unsigned int window,
const char *timehost, const desblock *ckey);
8/91 Page 1
secure_rpc(3N) secure_rpc(3N)
authdesseccreate, the second of two AUTHDES 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 name is the network
name, or netname, of the owner of the server process. This
field usually represents a hostname derived from the utility
routine host2netname, but could also represent a user name
using user2netname, 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,
timehost, the host's name, is optional. If it is NULL, then the
authentication system will assume that the local clock is
always in sync with the timehost 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 ckey is
also optional. If it is NULL, then the authentication system
will generate a random DES key to be used for the encryption of
credentials. If ckey is supplied, then it will be used
instead.
int
getnetname(char name[MAXNETNAMELEN+1]);
getnetname installs the unique, operating-system independent
netname of the caller in the fixed-length array name. Returns
1 if it succeeds, and 0 if it fails.
int
host2netname(char name[MAXNETNAMELEN+1], const char *host,
const char *domain);
Convert from a domain-specific hostname host to an operating-
system independent netname. Return 1 if it succeeds, and 0 if
it fails. Inverse of netname2host. If domain is NULL,
host2netname uses the default domain name of the machine. If
host is NULL, it defaults to that machine itself.
int
keydecryptsession(const char *remotename, desblock *deskey);
keydecryptsession is an interface to the keyserver daemon,
which is associated with RPC's secure authentication system
(AUTHDES authentication). User programs rarely need to call
it, or its associated routines keyencryptsession, keygendes
and keysetsecret.
Page 2 8/91
secure_rpc(3N) secure_rpc(3N)
keydecryptsession takes a server netname remotename and a DES
key deskey, 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
keyencryptsession.
int
keyencryptsession(const char *remotename, desblock *deskey);
keyencryptsession is a keyserver interface routine. It takes a
server netname remotename and a DES key deskey, 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 keydecryptsession. This routine returns 0 if
it succeeds, -1 if it fails.
int
keygendes(desblock *deskey);
keygendes is a keyserver interface routine. It is used to ask
the keyserver for a secure conversation key. Choosing one at
random is usually not good enough, because the common ways of
choosing random numbers, such as using the current time, are
very easy to guess.
int
keysetsecret(const char *key);
keysetsecret is a keyserver interface routine. It is used to
set the key for the effective UID of the calling process. this
routine returns 0 if it succeeds, -1 if it fails.
int
netname2host(const char *name, char *host, const int hostlen);
Convert from an operating-system independent netname name to a
domain-specific hostname host. hostlen is the maximum size of
host. Returns 1 if it succeeds, and 0 if it fails. Inverse of
host2netname.
int
netname2user(const char *name, uidt *uidp, gidt *gidp,
int *gidlenp, gidt gidlist[NGROUPS]);
Convert from an operating-system independent netname to a
domain-specific user ID. Returns 1 if it succeeds, and 0 if it
fails. Inverse of user2netname.
*uidp is set to the user's numerical ID associated with name.
*gidp is set to the numerical ID of the group to which the user
belongs. gidlist contains the numerical IDs of the other
8/91 Page 3
secure_rpc(3N) secure_rpc(3N)
groups to which the user belongs. *gidlenp is set to the
number of valid group ID entries in gidlist.
int
user2netname(char name[MAXNETNAMELEN+1], const uidt uid,
const char *domain);
Convert from a domain-specific username to an operating-system
independent netname. Returns 1 if it succeeds, and 0 if it
fails. Inverse of netname2user.
SEE ALSO
chkey(1), keyserv(1M), newkey(1M), rpc(3N), rpcclntauth(3N).
Page 4 8/91