unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-4.1.3)
Page:
Section:
Apropos / Subsearch:
optional field

SECURE_RPC(3N)                                                  SECURE_RPC(3N)



NAME
       authdes_create,  authdes_getucred, get_myaddress, getnetname, host2net-
       name, key_decryptsession,  key_encryptsession,  key_gendes,  key_setse-
       cret,  netname2host,  netname2user, user2netname - library routines for
       secure remote procedure calls

DESCRIPTION
       RPC routines allow C programs to make procedure calls on other machines
       across  the  network.   First,  the  client calls a procedure to send a
       request to the server.  Upon receipt of the request, the server calls a
       dispatch  routine to perform the requested service, and then sends back
       a reply.  Finally, the procedure call returns to the client.

       RPC allows various authentication flavors  The  authdes_getucred()  and
       authdes_create() routines implement the DES authentication flavor.  See
       rpc_clnt_auth(3N) for routines relating to the AUTH_NONE and  AUTH_UNIX
       authentication types.

              Note:  Both  the client and server should have their keys in the
              publickey(5) database.  Also, the keyserver  daemon  keyserv(8C)
              must  be running on both the client and server hosts for the DES
              authentication system to work.

   Routines
       #include <&lt;rpc/rpc.h>&gt;

       AUTH * authdes_create(netname, window, syncaddr, deskeyp)
       char *netname;
       unsigned window;
       struct sockaddr_in *syncaddr;
       des_block *deskeyp;

              authdes_create() is an interface to the RPC  secure  authentica-
              tion system, known as DES authentication.

              Used on the client side, authdes_create() returns an authentica-
              tion handle that enables the use of  the  secure  authentication
              system.   The first parameter netname is the network name of the
              owner of the server process.  This field  usually  represents  a
              host  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  parameter
              syncaddr  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 to synchronize with the
              server. If an address is supplied then the system  will  use  it
              for  consulting  the remote time service whenever resynchroniza-
              tion is required. This parameter is usually the address  of  the
              RPC server itself. The final parameter deskeyp 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
              deskeyp is supplied then it is used instead.

       int authdes_getucred(adc, uidp, gidp, gidlenp, gidlistp)
       struct authdes_cred *adc;
       short *uidp;
       short *gidp;
       short *gidlenp;
       int *gidlistp;

              authdes_getucred(), is a DES authentication routine used by  the
              server  for converting a DES credential, which is operating sys-
              tem independent, into a UNIX credential.   uidp  points  to  the
              user  ID  of  the  user  associated with adc; gidp refers to the
              user's current group ID; gidlistp refers to an array  of  groups
              to  which  the  user  belongs  and  gidlenp has the count of the
              entries in this array.

              This routine differs from the utility routine netname2user()  in
              that  authdes_getucred() pulls its information from a cache, and
              does not have to do a NIS name service lookup every time  it  is
              called  to  get its information.  Returns 1 if it succeeds and 0
              if it fails.

       void get_myaddress(addr)
       struct sockaddr_in *addr;

              Return  the machine's IP address in addr.  The  port  number  is
              always set to htons(PMAPPORT).

       int getnetname(netname)
       char netname[MAXNETNAMELEN];

              Return  the  unique, operating-system independent netname of the
              caller in the fixed-length array netname.  Returns 1 if it  suc-
              ceeds and 0 if it fails.

       int host2netname(netname, host, domain)
       char netname[MAXNETNAMELEN];
       char *host;
       char *domain;

              Convert  from  a domain-specific hostname to an operating-system
              independent netname.  This routine is normally used to  get  the
              netname  of the server, which is then used to get an authentica-
              tion handle by calling authdes_create().  This routine should be
              used  if the owner of the server process is the machine that is,
              the user with effective user ID zero.  Returns 1 if it  succeeds
              and  0  if  it  fails.  This  routine  is  the  inverse  of net-
              name2host().

       int key_decryptsession(netname, deskeyp)
       char *netname;
       des_block *deskeyp;

              An interface routine to the keyserver daemon, which  is  associ-
              ated  with  RPC's  secure authentication system (DES authentica-
              tion).  User programs rarely need to call it, or its  associated
              routines key_encryptsession(), key_gendes() and key_setsecret().
              System commands such as login and the RPC library are  the  main
              clients of these four routines.

              key_decryptsession()  takes  the  netname  of a server and a DES
              key, and decrypts the key by using the public key of the  server
              and  the secret key associated with the effective user ID of the
              calling process.  Returns 0 if it succeeds and -1 if  it  fails.
              This routine is the inverse of key_encryptsession().

       int key_encryptsession(netname, deskeyp)
       char *netname;
       des_block *deskeyp;

              A  keyserver  interface  routine.  It  takes  the netname of the
              server and a des key, and encrypts it using the  public  key  of
              the server and the secret key associated with the effective user
              ID of the calling process.  Returns 0 if it succeeds and  -1  if
              it fails. This routine is the inverse of key_decryptsession().

       int key_gendes(deskeyp)
       des_block *deskeyp;

              A  keyserver  interface routine. It is used to ask the keyserver
              for a secure conversation key.  Choosing one at "random" is usu-
              ally not good enough, because the common ways of choosing random
              numbers, such as using the current time, are very easy to guess.
              Returns 0 if it succeeds and -1 if it fails.

       int key_setsecret(keyp)
       char *keyp;

              A  keyserver interface routine. It is used to set the secret key
              for the effective user ID of the calling process.  Returns 0  if
              it succeeds and -1 if it fails.

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

              Convert an operating-system independent netname to a domain-spe-
              cific hostname.  hostlen specifies the size of the array pointed
              to  by  host.   It  returns  1 if it succeeds and 0 if it fails.
              This routine is the inverse of host2netname().

       int netname2user(netname, uidp, gidp, gidlenp, gidlistp)
       char *name;
       int *uidp;
       int *gidp;
       int *gidlenp;
       int *gidlistp;

              Convert an operating-system independent netname to a domain-spe-
              cific  user  ID.   uidp  points to the user ID of the user; gidp
              refers to the user's current group ID;  gidlistp  refers  to  an
              array  of  groups  to which the user belongs and gidlenp has the
              count of the entries in this array.  It returns 1 if it succeeds
              and  0  if  it  fails.  This routine is the inverse of user2net-
              name().

       int user2netname(netname, uid, domain)
       char name[MAXNETNAMELEN];
       int uid;
       char *domain;

              Convert  a domain-specific username to an operating-system inde-
              pendent  netname.  uid is the user ID of the owner of the server
              process.  This routine is normally used to get  the  netname  of
              the  server,  which is then used to get an authentication handle
              by calling authdes_create().  Returns 1 if it succeeds and 0  if
              it fails.  This routine is the inverse of netname2user().

SEE ALSO
       login(1),  chkey(1),  rpc(3N),  rpc_clnt_auth(3N),  publickey(5),  key-
       serv(8C), newkey(8)



                                20 January 1990                 SECURE_RPC(3N)