Networking Services Library Functions securerpc(3NSL)
NAME
securerpc, authdesgetucred, authdesseccreate, getnetname,
host2netname, keydecryptsession, keyencryptsession,
keygendes, keysetsecret, keysecretkeyisset,
netname2host, netname2user, user2netname - library routines
for secure remote procedure calls
SYNOPSIS
cc [ flag... ] file... -lnsl [ library...]
#include
#include
int authdesgetucred(const struct authdescred *adc, uidt *uidp,
gidt *gidp, short *gidlenp, gidt *gidlist);
AUTH *authdesseccreate(const char *name, const uintt window,
const char *timehost, ckey);
int getnetname(char name [MAXNETNAMELEN]1]);
int host2netname(char name [MAXNETNAMELEN]1], const char *host,
const char *domain);
int keydecryptsession(const char *remotename, desblock *deskey);
int keyencryptsession(const char *remotename, desblock *deskey);
int keygendes(desblock *deskey);
int keysetsecret(const char *key);
int keysecretkeyisset(void)
int netname2host(const char *name, char *host, const int hostlen);
int netname2user(const char *name, uidt *uidp, gidt *gidp, int *gidlenp,
gidt *gidlist [NGRPS]);
int user2netname(char name [MAXNETNAMELEN]1], const uidt uid,
const char *domain);
SunOS 5.11 Last change: 19 Feb 2004 1
Networking Services Library Functions securerpc(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:
AUTHNONE No authentication (none).
AUTHSYS Traditional UNIX-style authentication.
AUTHDES DES encryption-based authentication.
The authdesgetucred() and authdesseccreate() functions
implement the AUTHDES authentication style. The keyserver
daemon keyserv(1M) must be running for the AUTHDES authen-
tication system to work and keylogin(1) must have been run.
The AUTHDES style of authentication is discussed here. For
information about the AUTHNONE and AUTHSYS flavors of
authentication, refer to rpcclntauth(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.
authdesgetucred() This is the first of two functions
that interface to the RPC secure
authentication system AUTHDES.
The second is the
authdesseccreate() function. The
authdesgetucred() function is
used on the server side to convert
an AUTHDES credential, which is
operating system independent, to
an AUTHSYS credential. The
authdesgetucred() 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 parame-
ter contains the numerical IDs of
the other groups to which the user
SunOS 5.11 Last change: 19 Feb 2004 2
Networking Services Library Functions securerpc(3NSL)
belongs. The *gidlenp parameter is
set to the number of valid group
ID entries specified by the
*gidlist parameter.
The authdesgetucred() function
fails if the authdescred 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 host
netname in the authdescred struc-
ture.
authdesseccreate() The second of two AUTHDES authen-
tication functions, the
authdesseccreate() 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 window
increases the frequency of resyn-
chronization due to clock drift.
The third parameter, timehost, is
the host's name and is optional.
If timehost is NUL, the authenti-
cation system assumes that the
local clock is always in sync with
the timehost clock and does not
attempt resynchronization. If a
SunOS 5.11 Last change: 19 Feb 2004 3
Networking Services Library Functions securerpc(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 NUL, 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 authdesseccreate() fails, it
returns NUL.
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 an
operating 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 NUL,
host2netname() uses the default
domain name of the machine. If
host is NUL, it defaults to that
machine itself. If domain is NUL
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.
keydecryptsession() This function is an interface to
the keyserver daemon, which is
associated with RPC's secure
authentication system (AUTHDES
authentication). User programs
SunOS 5.11 Last change: 19 Feb 2004 4
Networking Services Library Functions securerpc(3NSL)
rarely need to call
keydecryptsession() or the asso-
ciated functions
keyencryptsession(),
keygendes(), and keysetsecret().
The keydecryptsession() 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. The
keydecryptsession() function is
the inverse of
keyencryptsession() function.
keyencryptsession() 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). The
keyencryptsession() function is
the inverse of
keydecryptsession() function. The
keyencryptsession() function
returns 0 if it succeeds, -1 if it
fails.
keygendes() 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 secure
because the common ways of choos-
ing random numbers are too easy to
guess. The keygendes() function
returns 0 if it succeeds, -1 if it
fails.
SunOS 5.11 Last change: 19 Feb 2004 5
Networking Services Library Functions securerpc(3NSL)
keysetsecret() 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.
keysecretkeyisset() 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 pro-
cess, the keysecretkeyisset()
function returns 1. Otherwise it
returns 0.
netname2host() This function converts an operat-
ing 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 operat-
ing 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 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 operating
SunOS 5.11 Last change: 19 Feb 2004 6
Networking Services Library Functions securerpc(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.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
MT-Level MT-Safe
SEE ALSO
chkey(1), keylogin(1), keyserv(1M), newkey(1M), rpc(3NSL),
rpcclntauth(3NSL), attributes(5)
SunOS 5.11 Last change: 19 Feb 2004 7
|
