Networking Services Library Functions secure_rpc(3NSL)
NAME
secure_rpc, authdes_getucred, authdes_seccreate, getnetname,
host2netname, key_decryptsession, key_encryptsession,
key_gendes, key_setsecret, key_secretkey_is_set,
netname2host, netname2user, user2netname - library routines
for secure remote procedure callsSYNOPSIS
cc [ flag... ] file... -lnsl [ library...]
#include
#include
int authdes_getucred(const struct authdes_cred *adc, uid_t *uidp,
gid_t *gidp, short *gidlenp, gid_t *gidlist);
AUTH *authdes_seccreate(const char *name, const uint_t window,
const char *timehost, ckey);int getnetname(char name [MAXNETNAMELEN+1]);
int host2netname(char name [MAXNETNAMELEN+1], 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 key_secretkey_is_set(void)
int netname2host(const char *name, char *host, const int hostlen);int netname2user(const char *name, uid_t *uidp, gid_t *gidp, int *gidlenp,
gid_t *gidlist [NGRPS]);
int user2netname(char name [MAXNETNAMELEN+1], const uid_t uid,
const char *domain);SunOS 5.11 Last change: 19 Feb 2004 1
Networking Services Library Functions secure_rpc(3NSL)
DESCRIPTION
The RPC library functions allow C programs to make procedure calls on other machines across the network. RPC supports various authentication flavors. Among them are:AUTH_NONE No authentication (none).
AUTH_SYS Traditional UNIX-style authentication.
AUTH_DES DES encryption-based authentication.
The authdes_getucred() and authdes_seccreate() functions
implement the AUTH_DES authentication style. The keyserver
daemon keyserv(1M) must be running for the AUTH_DES authen-
tication system to work and keylogin(1) must have been run.The AUTH_DES style of authentication is discussed here. For
information about the AUTH_NONE and AUTH_SYS flavors of
authentication, refer to rpc_clnt_auth(3NSL). See rpc(3NSL)
for the definition of the AUTH data structure.The following functions documented on this page are MT-Safe.
For the MT-levels of other authentication styles, see
relevant man pages.authdes_getucred() This is the first of two functions
that interface to the RPC secureauthentication system AUTH_DES.
The second is theauthdes_seccreate() function. The
authdes_getucred() function is
used on the server side to convertan AUTH_DES credential, which is
operating system independent, toan AUTH_SYS credential. The
authdes_getucred() function
returns 1 if it succeeds, 0 if it fails. The *uidp parameter is set to the user's numerical ID associated with adc. The *gidp parameter is set to the numerical ID of theuser's group. The *gidlist parame-
ter contains the numerical IDs of the other groups to which the userSunOS 5.11 Last change: 19 Feb 2004 2
Networking Services Library Functions secure_rpc(3NSL)
belongs. The *gidlenp parameter is set to the number of valid group ID entries specified by the *gidlist parameter.The authdes_getucred() function
fails if the authdes_cred struc-
ture was created with the netname of a host. In such a case, netname2host() should be used to get the host name from the hostnetname in the authdes_cred struc-
ture.authdes_seccreate() The second of two AUTH_DES authen-
tication functions, theauthdes_seccreate() function is
used on the client side to return an authentication handle that enables the use of the secure authentication system. The first field, name, specifies the network name netname of the owner of the server process. The field usually represents a hostname derived from the host2netname() utility, but the field might also represent a user name converted with the user2netname() utility.The second field, window, speci-
fies the validity of the client credential in seconds. If the difference in time between the client's clock and the server's clock exceeds window, the server rejects the client's credentials and the clock will have to be resynchronized. A small window is more secure than a large one, but choosing too small a windowincreases the frequency of resyn-
chronization due to clock drift. The third parameter, timehost, is the host's name and is optional.If timehost is NULL, the authenti-
cation system assumes that the local clock is always in sync with the timehost clock and does not attempt resynchronization. If aSunOS 5.11 Last change: 19 Feb 2004 3
Networking Services Library Functions secure_rpc(3NSL)
timehost is supplied, the system consults the remote time service whenever resynchronization is required. The timehost parameter is usually the name of the host on which the server is running. The final parameter, ckey, is also optional. If ckey is NULL, the authentication system generates a random DES key to be used for the encryption of credentials. If ckey is supplied, it is used for encryption.If authdes_seccreate() fails, it
returns NULL. getnetname() This function returns the unique,operating system independent net-
name of the caller in the fixed-
length array name. The function returns 1 if it succeeds and 0 if it fails.host2netname() This function converts a domain-
specific hostname host to anoperating system independent net-
name. The function returns 1 if it succeeds and 0 if it fails. The host2netname() function is the inverse of the netname2host() function. If the domain is NULL, host2netname() uses the default domain name of the machine. If host is NULL, it defaults to that machine itself. If domain is NULL and host is an NIS name such as myhost.sun.example.com, the host2netname() function uses the domain sun.example.com rather than the default domain name of the machine.key_decryptsession() This function is an interface to
the keyserver daemon, which is associated with RPC's secureauthentication system (AUTH_DES
authentication). User programsSunOS 5.11 Last change: 19 Feb 2004 4
Networking Services Library Functions secure_rpc(3NSL)
rarely need to callkey_decryptsession() or the asso-
ciated functionskey_encryptsession(),
key_gendes(), and key_setsecret().
The key_decryptsession() function
takes a server netname remotename and a DES key deskey, and decrypts the key by using the the public key of the server and the secret key associated with the effective UID of the calling process. Thekey_decryptsession() function is
the inverse ofkey_encryptsession() function.
key_encryptsession() This function is a keyserver
interface that takes a server net-
name remotename and a DES key des-
key, and encrypts the key using the public key of the the server and the secret key associated with the effective UID of the calling process. If the keyserver does not have a key registered for the UID, it falls back to using the secret key for the netname nobody unless this feature has been disabled. See keyserv(1M). Thekey_encryptsession() function is
the inverse ofkey_decryptsession() function. The
key_encryptsession() function
returns 0 if it succeeds, -1 if it
fails.key_gendes() This is a keyserver interface
function used to ask the keyserver for a secure conversation key.Selecting a conversion key at ran-
dom is generally not securebecause the common ways of choos-
ing random numbers are too easy toguess. The key_gendes() function
returns 0 if it succeeds, -1 if it
fails.SunOS 5.11 Last change: 19 Feb 2004 5
Networking Services Library Functions secure_rpc(3NSL)
key_setsecret() This is a keyserver interface
function used to set the key for the effective UID of the calling process. This function returns 0if it succeeds, -1 if it fails.
key_secretkey_is_set() This is a keyserver interface
function used to determine if a key has been set for the effective UID of the calling process. If the keyserver has a key stored for theeffective UID of the calling pro-
cess, the key_secretkey_is_set()
function returns 1. Otherwise it returns 0.netname2host() This function converts an operat-
ing system independent netnamename to a domain-specific hostname
host. The hostlen parameter is the maximum size of host. The netname2host() function returns 1 if it succeeds and 0 if it fails. The function is the inverse of the host2netname() function.netname2user() This function converts an operat-
ing system independent netname toa domain-specific user ID. The
netname2user() function returns 1 if it succeeds and 0 if it fails.The function is the inverse of the user2netname() function. The *uidp parameter is set to the user's numerical ID associated with name. The *gidp parameter is set to the numerical ID of theuser's group. The gidlist parame-
ter contains the numerical IDs of the other groups to which the user belongs. The *gidlenp parameter is set to the number of valid group ID entries specified by the gidlist parameter.user2netname() This function converts a domain-
specific username to an operatingSunOS 5.11 Last change: 19 Feb 2004 6
Networking Services Library Functions secure_rpc(3NSL)
system independent netname. The user2netname() function returns 1 if it succeeds and 0 if it fails. The function is the inverse of netname2user() function.ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| MT-Level | MT-Safe |
|_____________________________|_____________________________|
SEE ALSO
chkey(1), keylogin(1), keyserv(1M), newkey(1M), rpc(3NSL),rpc_clnt_auth(3NSL), attributes(5)
SunOS 5.11 Last change: 19 Feb 2004 7