331 lines
6.3 KiB
Groff
331 lines
6.3 KiB
Groff
|
.\" @(#)rpc_secure.3n 2.1 88/08/08 4.0 RPCSRC; from 1.19 88/06/24 SMI
|
||
|
|
.TH RPC 3N "16 February 1988"
|
||
|
|
.SH NAME
|
||
|
|
rpc_secure \- library routines for secure remote procedure calls
|
||
|
|
.SH SYNOPSIS AND DESCRIPTION
|
||
|
|
These routines are part of the RPC library. They implement DES
|
||
|
|
Authentication. See
|
||
|
|
.BR rpc (3N)
|
||
|
|
for further details about RPC.
|
||
|
|
.LP
|
||
|
|
.ft B
|
||
|
|
.nf
|
||
|
|
.sp .5
|
||
|
|
#include <rpc/rpc.h>
|
||
|
|
.fi
|
||
|
|
.ft R
|
||
|
|
.br
|
||
|
|
.if t .ne 22
|
||
|
|
.LP
|
||
|
|
.ft B
|
||
|
|
.nf
|
||
|
|
.sp .5
|
||
|
|
\s-1AUTH\s0 *
|
||
|
|
authdes_create(name, window, syncaddr, ckey)
|
||
|
|
char *name;
|
||
|
|
unsigned window;
|
||
|
|
struct sockaddr_in *addr;
|
||
|
|
des_block *ckey;
|
||
|
|
.fi
|
||
|
|
.ft R
|
||
|
|
.IP
|
||
|
|
.B authdes_create(\|)
|
||
|
|
is the first of two routines which interface to the
|
||
|
|
.SM RPC
|
||
|
|
secure authentication system, known as
|
||
|
|
.SM DES
|
||
|
|
authentication.
|
||
|
|
The second is
|
||
|
|
.BR authdes_getucred(\|) ,
|
||
|
|
below. Note: the keyserver daemon
|
||
|
|
.BR keyserv (8C)
|
||
|
|
must be running for the
|
||
|
|
.SM DES
|
||
|
|
authentication system to work.
|
||
|
|
.IP
|
||
|
|
.BR authdes_create(\|) ,
|
||
|
|
used on the client side, returns an authentication handle that
|
||
|
|
will enable the use of the secure authentication system.
|
||
|
|
The first parameter
|
||
|
|
.I name
|
||
|
|
is the network name, or
|
||
|
|
.IR netname ,
|
||
|
|
of the owner of the server process. This field usually
|
||
|
|
represents a
|
||
|
|
.I hostname
|
||
|
|
derived from the utility routine
|
||
|
|
.BR host2netname ,
|
||
|
|
but could also represent a user name using
|
||
|
|
.BR user2netname .
|
||
|
|
The second field is window on the validity of
|
||
|
|
the client credential, given in seconds. A small
|
||
|
|
window is more secure than a large one, but choosing
|
||
|
|
too small of a window will increase the frequency of
|
||
|
|
resynchronizations because of clock drift. The third
|
||
|
|
parameter
|
||
|
|
.I syncaddr
|
||
|
|
is optional. If it is
|
||
|
|
.SM NULL\s0,
|
||
|
|
then the authentication system will assume
|
||
|
|
that the local clock is always in sync with the server's
|
||
|
|
clock, and will not attempt resynchronizations. If an address
|
||
|
|
is supplied, however, then the system will use the address
|
||
|
|
for consulting the remote time service whenever
|
||
|
|
resynchronization
|
||
|
|
is required. This parameter is usually the
|
||
|
|
address of the
|
||
|
|
.SM RPC
|
||
|
|
server itself. The final parameter
|
||
|
|
.I ckey
|
||
|
|
is also optional. If it is
|
||
|
|
.SM NULL\s0,
|
||
|
|
then the authentication system will
|
||
|
|
generate a random
|
||
|
|
.SM DES
|
||
|
|
key to be used for the encryption of credentials.
|
||
|
|
If it is supplied, however, then it will be used instead.
|
||
|
|
.br
|
||
|
|
.if t .ne 13
|
||
|
|
.LP
|
||
|
|
.ft B
|
||
|
|
.nf
|
||
|
|
.sp .5
|
||
|
|
authdes_getucred(adc, uid, gid, grouplen, groups)
|
||
|
|
struct authdes_cred *adc;
|
||
|
|
short *uid;
|
||
|
|
short *gid;
|
||
|
|
short *grouplen;
|
||
|
|
int *groups;
|
||
|
|
.fi
|
||
|
|
.ft R
|
||
|
|
.IP
|
||
|
|
.BR authdes_getucred(\|) ,
|
||
|
|
the second of the two
|
||
|
|
.SM DES
|
||
|
|
authentication routines,
|
||
|
|
is used on the server side for converting a
|
||
|
|
.SM DES
|
||
|
|
credential, which is
|
||
|
|
operating system independent, into a
|
||
|
|
.UX
|
||
|
|
credential. This routine differs from utility routine
|
||
|
|
.B netname2user
|
||
|
|
in that
|
||
|
|
.B authdes_getucred(\|)
|
||
|
|
pulls its information from a cache, and does not have to do a
|
||
|
|
Yellow Pages lookup every time it is called to get its information.
|
||
|
|
.br
|
||
|
|
.ft .ne 8
|
||
|
|
.LP
|
||
|
|
.ft B
|
||
|
|
.nf
|
||
|
|
.sp .5
|
||
|
|
host2netname(name, host, domain)
|
||
|
|
char *name;
|
||
|
|
char *host;
|
||
|
|
char *domain;
|
||
|
|
.fi
|
||
|
|
.ft R
|
||
|
|
.IP
|
||
|
|
Convert from a domain-specific hostname to an
|
||
|
|
operating-system independent netname. Return
|
||
|
|
.SM TRUE
|
||
|
|
if it succeeds and
|
||
|
|
.SM FALSE
|
||
|
|
if it fails. Inverse of
|
||
|
|
.BR netname2host(\|) .
|
||
|
|
.br
|
||
|
|
.if t .ne 9
|
||
|
|
.LP
|
||
|
|
.ft B
|
||
|
|
.nf
|
||
|
|
.sp .5
|
||
|
|
key_decryptsession(remotename, deskey)
|
||
|
|
char *remotename;
|
||
|
|
des_block *deskey;
|
||
|
|
.fi
|
||
|
|
.ft R
|
||
|
|
.IP
|
||
|
|
.B key_decryptsession(\|)
|
||
|
|
is an interface to the keyserver daemon, which is associated
|
||
|
|
with
|
||
|
|
.SM RPC\s0's
|
||
|
|
secure authentication system (\s-1DES\s0
|
||
|
|
authentication).
|
||
|
|
User programs rarely need to call it, or its associated routines
|
||
|
|
.BR key_encryptsession(\|) ,
|
||
|
|
.B key_gendes(\|)
|
||
|
|
and
|
||
|
|
.BR key_setsecret(\|) .
|
||
|
|
System commands such as
|
||
|
|
.B login
|
||
|
|
and the
|
||
|
|
.SM RPC
|
||
|
|
library are the main clients of these four routines.
|
||
|
|
.IP
|
||
|
|
.B key_decryptsession(\|)
|
||
|
|
takes a server netname and a des key, and decrypts the key by
|
||
|
|
using the the public key of the the server and the secret key
|
||
|
|
associated with the effective uid of the calling process. It
|
||
|
|
is the inverse of
|
||
|
|
.BR key_encryptsession(\|) .
|
||
|
|
.br
|
||
|
|
.if t .ne 8
|
||
|
|
.LP
|
||
|
|
.ft B
|
||
|
|
.nf
|
||
|
|
.sp .5
|
||
|
|
key_encryptsession(remotename, deskey)
|
||
|
|
char *remotename;
|
||
|
|
des_block *deskey;
|
||
|
|
.fi
|
||
|
|
.ft R
|
||
|
|
.IP
|
||
|
|
.B key_encryptsession(\|)
|
||
|
|
is a keyserver interface routine. It
|
||
|
|
takes a server netname and a des key, and encrypts
|
||
|
|
it using the public key of the the server and the secret key
|
||
|
|
associated with the effective uid of the calling process. It
|
||
|
|
is the inverse of
|
||
|
|
.BR key_decryptsession(\|) .
|
||
|
|
.br
|
||
|
|
.if t .ne 7
|
||
|
|
.LP
|
||
|
|
.ft B
|
||
|
|
.nf
|
||
|
|
.sp .5
|
||
|
|
key_gendes(deskey)
|
||
|
|
des_block *deskey;
|
||
|
|
.fi
|
||
|
|
.ft R
|
||
|
|
.IP
|
||
|
|
.B key_gendes(\|)
|
||
|
|
is a keyserver interface routine. It
|
||
|
|
is used to ask the keyserver for a secure conversation key.
|
||
|
|
Choosing one at \(lqrandom\(rq is usually not good enough,
|
||
|
|
because
|
||
|
|
the common ways of choosing random numbers, such as using the
|
||
|
|
current time, are very easy to guess.
|
||
|
|
.br
|
||
|
|
.if t .ne 6
|
||
|
|
.LP
|
||
|
|
.ft B
|
||
|
|
.nf
|
||
|
|
.sp .5
|
||
|
|
key_setsecret(key)
|
||
|
|
char *key;
|
||
|
|
.fi
|
||
|
|
.ft R
|
||
|
|
.IP
|
||
|
|
.B key_setsecret(\|)
|
||
|
|
is a keyserver interface routine. It is used to set the key for
|
||
|
|
the effective
|
||
|
|
.I uid
|
||
|
|
of the calling process.
|
||
|
|
.br
|
||
|
|
.if t .ne 7
|
||
|
|
.LP
|
||
|
|
.ft B
|
||
|
|
.nf
|
||
|
|
.sp .5
|
||
|
|
getnetname(name)
|
||
|
|
char name[\s-1MAXNETNAMELEN\s0];
|
||
|
|
.fi
|
||
|
|
.ft R
|
||
|
|
.IP
|
||
|
|
.B getnetname(\|)
|
||
|
|
installs the unique, operating-system independent netname of
|
||
|
|
the
|
||
|
|
caller in the fixed-length array
|
||
|
|
.IR name .
|
||
|
|
Returns
|
||
|
|
.SM TRUE
|
||
|
|
if it succeeds and
|
||
|
|
.SM FALSE
|
||
|
|
if it fails.
|
||
|
|
.br
|
||
|
|
.if t .ne 6
|
||
|
|
.LP
|
||
|
|
.ft B
|
||
|
|
.nf
|
||
|
|
.sp .5
|
||
|
|
netname2host(name, host, hostlen)
|
||
|
|
char *name;
|
||
|
|
char *host;
|
||
|
|
int hostlen;
|
||
|
|
.fi
|
||
|
|
.ft R
|
||
|
|
.IP
|
||
|
|
Convert from an operating-system independent netname to a
|
||
|
|
domain-specific hostname. Returns
|
||
|
|
.SM TRUE
|
||
|
|
if it succeeds and
|
||
|
|
.SM FALSE
|
||
|
|
if it fails. Inverse of
|
||
|
|
.BR host2netname(\|) .
|
||
|
|
.br
|
||
|
|
.if t .ne 9
|
||
|
|
.LP
|
||
|
|
.ft B
|
||
|
|
.nf
|
||
|
|
.sp .5
|
||
|
|
netname2user(name, uidp, gidp, gidlenp, gidlist)
|
||
|
|
char *name;
|
||
|
|
int *uidp;
|
||
|
|
int *gidp;
|
||
|
|
int *gidlenp;
|
||
|
|
int *gidlist;
|
||
|
|
.fi
|
||
|
|
.ft R
|
||
|
|
.IP
|
||
|
|
Convert from an operating-system independent netname to a
|
||
|
|
domain-specific user
|
||
|
|
.SM ID.
|
||
|
|
Returns
|
||
|
|
.SM TRUE
|
||
|
|
if it succeeds and
|
||
|
|
.SM FALSE
|
||
|
|
if it fails. Inverse of
|
||
|
|
.BR user2netname(\|) .
|
||
|
|
.br
|
||
|
|
.if t .ne 8
|
||
|
|
.LP
|
||
|
|
.ft B
|
||
|
|
.nf
|
||
|
|
.sp .5
|
||
|
|
user2netname(name, uid, domain)
|
||
|
|
char *name;
|
||
|
|
int uid;
|
||
|
|
char *domain;
|
||
|
|
.fi
|
||
|
|
.ft R
|
||
|
|
.IP
|
||
|
|
Convert from a domain-specific username to an operating-system
|
||
|
|
independent netname. Returns
|
||
|
|
.SM TRUE
|
||
|
|
if it succeeds and
|
||
|
|
.SM FALSE
|
||
|
|
if it fails. Inverse of
|
||
|
|
.BR netname2user(\|) .
|
||
|
|
.br
|
||
|
|
.SH SEE ALSO
|
||
|
|
.BR xdr (3N),
|
||
|
|
.BR keyserv (8C),
|
||
|
|
.BR rpc (3N)
|
||
|
|
.br
|
||
|
|
The following manuals:
|
||
|
|
.RS
|
||
|
|
.ft I
|
||
|
|
Remote Procedure Calls: Protocol Specification
|
||
|
|
.br
|
||
|
|
Remote Procedure Call Programming Guide
|
||
|
|
.br
|
||
|
|
rpcgen Programming Guide
|
||
|
|
.br
|
||
|
|
.ft R
|
||
|
|
.RE
|
||
|
|
.IR "\s-1RPC\s0: Remote Procedure Call Protocol Specification" ,
|
||
|
|
.SM RFC1050, Sun Microsystems, Inc.,
|
||
|
|
.SM USC-ISI\s0.
|
||
|
|
|