secure_rpc(3N)

NAME
     secure_rpc:  authdes_seccreate, authdes_getucred, getnetname,
     host2netname, key_decryptsession, key_encryptsession, key_gendes,
     key_setsecret, netname2host, netname2user, user2netname - library
     routines for secure remote procedure calls

NOTE
     IRIX does not support DES encryption, so the AUTH_DES authentication
     discussed here and the various encryption routines are not functional.
     These routines are not present in libc.  Stubs are provided as part of
     libnsl to allow linking of programs, but they return an error condition,
     DESERR_NONE, if invoked.

     On the other hand, starting from 6.5.24 IRIX has support for RPCSEC_GSS
     authentication - see rpcsec_gss(3N).

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:

          AUTH_NONE      (none)  no authentication.
          AUTH_SYS       Traditional UNIXr-style authentication.
          AUTH_DES       DES encryption-based authentication.

     The authdes_getucred and authdes_seccreate routines implement the
     AUTH_DES authentication flavor.  The keyserver daemon keyserv [see
     keyserv(1M)] must be running for the AUTH_DES authentication system to
     work.

   Routines
     See rpc(3N) for the definition of the AUTH data structure.

     #include <rpc/rpc.h>

     int
     authdes_getucred(const struct authdes_cred *adc, uid_t *uidp,
          gid_t *gidp, short *gidlenp, gid_t *gidlist);

          authdes_getucred is the first of the two routines which interface to
          the RPC secure authentication system known as AUTH_DES.  The second
          is authdes_seccreate, below.  authdes_getucred is used on the server
          side for converting an AUTH_DES credential, which is operating
          system independent, into an AUTH_SYS 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 *
     authdes_seccreate(const char *name, const unsigned int window,
          const char *timehost, const des_block *ckey);

          authdes_seccreate, the second of two AUTH_DES 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
     key_decryptsession(const char *remotename, des_block *deskey);
          key_decryptsession is an interface to the keyserver daemon, which is
          associated with RPC's secure authentication system (AUTH_DES
          authentication).  User programs rarely need to call it, or its
          associated routines key_encryptsession, key_gendes and
          key_setsecret.

          key_decryptsession takes a server netname remotename and a DES key
          deskey, and decrypts the key by 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 key_encryptsession.

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

          key_encryptsession 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 server and the secret key associated
          with the effective UID of the calling process. It is the inverse of
          key_decryptsession.  This routine returns 0 if it succeeds, -1 if it
          fails.

     int
     key_gendes(des_block *deskey);

          key_gendes 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
     key_setsecret(const char *key);

          key_setsecret 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, uid_t *uidp, gid_t *gidp,
          int *gidlenp, gid_t 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 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], uid_t 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
     rpc(3N), rpcsec_gss(3N), rpc_clnt_auth(3N)