NAME

     rpc_secure — library routines for secure remote procedure calls

SYNOPSIS

     #include <rpc/rpc.h>

     AUTH *
     authdes_create(char *name, unsigned window, struct sockaddr *addr, des_block *ckey);

     int
     authdes_getucred(struct authdes_cred *adc, uid_t *uid, gid_t *gid, int *grouplen,
         gid_t *groups);

     int
     getnetname(char *name);

     int
     host2netname(char *name, const char *host, const char *domain);

     int
     key_decryptsession(const char *remotename, des_block *deskey);

     int
     key_encryptsession(const char *remotename, des_block *deskey);

     int
     key_gendes(des_block *deskey);

     int
     key_setsecret(const char *key);

     int
     netname2host(char *name, char *host, int hostlen);

     int
     netname2user(char *name, uid_t *uidp, gid_t *gidp, int *gidlenp, gid_t *gidlist);

     int
     user2netname(char *name, const uid_t uid, const char *domain);

DESCRIPTION

     These routines are part of the RPC library.  They implement DES Authentication.  See rpc(3)
     for further details about RPC.

     The authdes_create() is the first of two routines which interface to the RPC secure
     authentication system, known as DES authentication.  The second is authdes_getucred(),
     below.

     Note: the keyserver daemon keyserv(8) must be running for the DES authentication system to
     work.

     The authdes_create() function, used on the client side, returns an authentication handle
     that will enable the use of the secure authentication system.  The first argument 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().  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 argument addr is optional.  If it is NULL, then the
     authentication system will assume that the local clock is always in sync with the server's
     clock, and will not attempt resynchronizations.  If an address is supplied, however, then
     the system will use the address for consulting the remote time service whenever
     resynchronization is required.  This argument is usually the address of the RPC server
     itself.  The final argument 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 it
     is supplied, however, then it will be used instead.

     The authdes_getucred() function, the second of the two DES authentication routines, is used
     on the server side for converting a DES credential, which is operating system independent,
     into a UNIX credential.  This routine differs from utility routine netname2user() in that
     authdes_getucred() pulls its information from a cache, and does not have to do a Yellow
     Pages lookup every time it is called to get its information.

     The getnetname() function installs the unique, operating-system independent netname of the
     caller in the fixed-length array name.  Returns TRUE if it succeeds and FALSE if it fails.

     The host2netname() function converts from a domain-specific hostname to an operating-system
     independent netname.  Returns TRUE if it succeeds and FALSE if it fails.  Inverse of
     netname2host().

     The key_decryptsession() function is an interface to the keyserver daemon, which is
     associated with RPC's secure authentication system (DES authentication).  User programs
     rarely need to call it, or its associated routines key_encryptsession(), key_gendes() and
     key_setsecret().  System commands such as login(1) and the RPC library are the main clients
     of these four routines.

     The key_decryptsession() function takes a server netname and a DES key, and decrypts the key
     by using the public key of the server and the secret key associated with the effective uid
     of the calling process.  It is the inverse of key_encryptsession().

     The key_encryptsession() function is a keyserver interface routine.  It takes a server
     netname and a des key, and encrypts it using the public key of the server and the secret key
     associated with the effective uid of the calling process.  It is the inverse of
     key_decryptsession().

     The key_gendes() function is a keyserver interface routine.  It is used to ask the keyserver
     for a secure conversation key.  Choosing one "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.

     The key_setsecret() function is a keyserver interface routine.  It is used to set the key
     for the effective uid of the calling process.

     The netname2host() function converts from an operating-system independent netname to a
     domain-specific hostname.  Returns TRUE if it succeeds and FALSE if it fails.  Inverse of
     host2netname().

     The netname2user() function converts from an operating-system independent netname to a
     domain-specific user ID.  Returns TRUE if it succeeds and FALSE if it fails.  Inverse of
     user2netname().

     The user2netname() function converts from a domain-specific username to an operating-system
     independent netname.  Returns TRUE if it succeeds and FALSE if it fails.  Inverse of
     netname2user().

AVAILABILITY

     These functions are part of libtirpc.

SEE ALSO

     rpc(3), xdr(3)

     The following manuals:

     Remote Procedure Calls: Protocol Specification.

     Remote Procedure Call Programming Guide.

     Rpcgen Programming Guide.

     RPC: Remote Procedure Call Protocol Specification, RFC1050, Sun Microsystems Inc., USC-ISI.