Jump to content United States-English
HP.com Home Products and Services Support and Drivers Solutions How to Buy
» Contact HP
More options
HP.com home
HP-UX Reference > S

secure_rpc(3N)

HP-UX 11i Version 3: February 2007
» 

Technical documentation

» Feedback
Content starts here

 » Table of Contents

 » Index

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

#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 unsigned int window, const char *timehost, const des_block *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[NGROUPS]); int user2netname( char name[MAXNETNAMELEN+1], const uid_t uid, const char *domain);

DESCRIPTION

RPC library routines 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() 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, and keylogin(1) must have been run. Only the AUTH_DES style of authentication is discussed here. For information about the AUTH_NONE and AUTH_SYS styles of authentication, refer to rpc_clnt_auth(3N).

The routines documented on this page are Thread Safe. For the other authentication styles, see the MULTITHREAD USAGE section of the routines' respective manual pages.

The HP-UX implementation of RPC only supports the X/Open Transport Interface (XTI). Applications that are written using the Transport Layer Interface (TLI) and wish to use RPC, must convert their application to XTI.

Routines

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

int 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 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.

AUTH *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 will enable the use of the secure authentication system. The first parameter, name, specifies the network name netname of the owner of the server process. This field usually represents a hostname derived from the host2netname() utility, but could also represent a user name converted with the user2netname() utility.

The second parameter, 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 will generate 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.

int 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.

int 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.hp.example.com, the host2netname() function uses the domain hp.example.com rather than the default domain name of the machine.

int 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 the key_encryptsession() function. The key_decryptsession() function returns 0 if it succeeds, -1 if it fails.

int key_encryptsession()

This function is a keyserver interface routine 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(1M). The key_encryptsession() function is the inverse of the key_decryptsession() function. The key_encryptsession() function returns 0 if it succeeds, -1 if it fails.

int key_gendes()

This is a keyserver interface function used to ask the keyserver for a secure conversation key. Selecting a conversation 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.

int 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.

int 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.

int 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.

int 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.

int 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 the netname2user() function.

MULTITHREAD USAGE

Thread Safe:

Yes

Cancel Safe:

Yes

Fork Safe:

No

Async-cancel Safe:

No

Async-signal Safe:

No

These functions can be called safely in a multithreaded environment. They may be cancellation points in that they call functions that are cancel points.

In a multithreaded environment, these functions are not safe to be called by a child process after fork() and before exec(). These functions should not be called by a multithreaded application that supports asynchronous cancellation or asynchronous signals.

Printable version
Privacy statement Using this site means you accept its terms Feedback to webmaster
© 1983-2007 Hewlett-Packard Development Company, L.P.