 |
» |
|
|
|
NAMEsecure_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); DESCRIPTIONRPC 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. RoutinesSee
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
