Tribblix: manual page: secure

SECURE_RPC(3NSL) 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 calls

SYNOPSIS

cc [ flag... ] file... -lnsl [ library...]
#include <rpc/rpc.h>
#include <sys/types.h>
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);

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(8)
must be running for the AUTH_DES authentication 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 secure authentication
system AUTH_DES. The second is the
authdes_seccreate() function. The
authdes_getucred() function is used on the
server side to convert an AUTH_DES
credential, which is operating system
independent, to an 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 the
user's group. The *gidlist parameter
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.

The authdes_getucred() function fails if
the authdes_cred structure was created with
the netname of a host. In such a case,
netname2host() should be used to get the
host name from the host netname in the
authdes_cred structure.

authdes_seccreate()
The second of two AUTH_DES authentication
functions, the authdes_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, specifies 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 window increases the
frequency of resynchronization due to clock
drift.

The third parameter, timehost, is the
host's name and is optional. If timehost is
NULL, the authentication system assumes
that the local clock is always in sync with
the timehost clock and does not attempt
resynchronization. If a 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 netname 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 an operating system
independent netname. 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 secure authentication system
(AUTH_DES authentication). User programs
rarely need to call key_decryptsession() or
the associated functions
key_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
public key of the server and the secret key
associated with the effective UID of the
calling process. The key_decryptsession()
function is the inverse of
key_encryptsession() function.

key_encryptsession()
This function is a keyserver interface that
takes a server netname remotename and a DES
key deskey, and encrypts the key using the
public key of 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(8). The
key_encryptsession() function is the
inverse of key_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 random is generally not secure
because the common ways of choosing random
numbers are too easy to guess. The
key_gendes() function returns 0 if it
succeeds, -1 if it fails.

key_setsecret()
This is a keyserver interface function used
to set the key for the effective UID of the
calling process. This function returns 0 if
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 the
effective UID of the calling process, the
key_secretkey_is_set() function returns 1.
Otherwise it returns 0.

netname2host()
This function converts an operating system
independent netname name 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 operating system
independent netname to a 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 the user's group. The gidlist parameter
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 operating 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

NAME

SYNOPSIS

DESCRIPTION

ATTRIBUTES

SEE ALSO