SECURE_RPC(3N)

NAME
authdes_create, authdes_getucred, get_myaddress, getnetname, host2netname, key_decryptsession, key_encryptsession, key_gendes, key_setsecret, 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 <rpc/rpc.h>

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 authentication system, known as DES authentication.

    Used on the client side, authdes_create() returns an authentication 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 resynchronization 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 system 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 succeeds 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 authentication 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 netname2host().

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

    An interface routine 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 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 usually 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-specific 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-specific 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 user2netname().

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

    Convert a domain-specific username to an operating-system independent 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), keyserv(8C), newkey(8)