freebsd-dev/lib/libc/rpc/rpc_secure.3

280 lines
5.9 KiB
Groff
Raw Normal View History

.\" @(#)rpc_secure.3n 2.1 88/08/08 4.0 RPCSRC; from 1.19 88/06/24 SMI
1999-08-28 00:22:10 +00:00
.\" $FreeBSD$
.\"
1998-01-05 07:12:16 +00:00
.Dd February 16, 1988
.Dt RPC 3
.Os
1998-01-05 07:12:16 +00:00
.Sh NAME
.Nm rpc_secure
.Nd library routines for secure remote procedure calls
.Sh SYNOPSIS
.In rpc/rpc.h
1998-01-05 07:12:16 +00:00
.Ft AUTH *
.Fo authdes_create
.Fa "char *name"
.Fa "unsigned window"
.Fa "struct sockaddr *addr"
1998-01-05 07:12:16 +00:00
.Fa "des_block *ckey"
.Fc
.Ft int
.Fn authdes_getucred "struct authdes_cred *adc" "uid_t *uid" "gid_t *gid" "int *grouplen" "gid_t *groups"
.Ft int
.Fn getnetname "char *name"
.Ft int
.Fn host2netname "char *name" "const char *host" "const char *domain"
.Ft int
.Fn key_decryptsession "const char *remotename" "des_block *deskey"
.Ft int
.Fn key_encryptsession "const char *remotename" "des_block *deskey"
.Ft int
1998-01-05 07:12:16 +00:00
.Fn key_gendes "des_block *deskey"
.Ft int
.Fn key_setsecret "const char *key"
.Ft int
1998-01-05 07:12:16 +00:00
.Fn netname2host "char *name" "char *host" "int hostlen"
.Ft int
.Fn netname2user "char *name" "uid_t *uidp" "gid_t *gidp" "int *gidlenp" "gid_t *gidlist"
.Ft int
.Fn user2netname "char *name" "const uid_t uid" "const char *domain"
1998-01-05 07:12:16 +00:00
.Sh DESCRIPTION
These routines are part of the
.Tn RPC
library. They implement
.Tn DES
Authentication. See
1998-01-05 07:12:16 +00:00
.Xr rpc 3
for further details about
.Tn RPC .
.Pp
The
.Fn authdes_create
is the first of two routines which interface to the
1998-01-05 07:12:16 +00:00
.Tn RPC
secure authentication system, known as
1998-01-05 07:12:16 +00:00
.Tn DES
authentication.
The second is
1998-01-05 07:12:16 +00:00
.Fn authdes_getucred ,
below.
.Pp
Note: the keyserver daemon
.Xr keyserv 8
must be running for the
1998-01-05 07:12:16 +00:00
.Tn DES
authentication system to work.
1998-01-05 07:12:16 +00:00
.Pp
2002-12-18 12:45:11 +00:00
The
.Fn authdes_create
function,
used on the client side, returns an authentication handle that
will enable the use of the secure authentication system.
2002-12-19 09:40:28 +00:00
The first argument
1998-01-05 07:12:16 +00:00
.Fa name
is the network name, or
1998-01-05 07:12:16 +00:00
.Fa netname ,
of the owner of the server process.
This field usually
represents a
1998-01-05 07:12:16 +00:00
.Fa hostname
derived from the utility routine
1998-01-05 07:12:16 +00:00
.Fn host2netname ,
but could also represent a user name using
1998-01-05 07:12:16 +00:00
.Fn 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
2002-12-19 09:40:28 +00:00
argument
1998-01-05 07:12:16 +00:00
.Fa addr
is optional. If it is
1998-01-05 07:12:16 +00:00
.Dv NULL ,
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.
2002-12-19 09:40:28 +00:00
This argument is usually the
address of the
1998-01-05 07:12:16 +00:00
.Tn RPC
server itself.
2002-12-19 09:40:28 +00:00
The final argument
1998-01-05 07:12:16 +00:00
.Fa ckey
is also optional. If it is
1998-01-05 07:12:16 +00:00
.Dv NULL ,
then the authentication system will
generate a random
1998-01-05 07:12:16 +00:00
.Tn DES
key to be used for the encryption of credentials.
If it is supplied, however, then it will be used instead.
1998-01-05 07:12:16 +00:00
.Pp
2002-12-18 12:45:11 +00:00
The
.Fn authdes_getucred
function,
the second of the two
1998-01-05 07:12:16 +00:00
.Tn DES
authentication routines,
is used on the server side for converting a
1998-01-05 07:12:16 +00:00
.Tn DES
credential, which is
operating system independent, into a
1998-01-05 07:12:16 +00:00
.Ux
credential.
This routine differs from utility routine
1998-01-05 07:12:16 +00:00
.Fn netname2user
in that
1998-01-05 07:12:16 +00:00
.Fn 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.
1998-01-05 07:12:16 +00:00
.Pp
2002-12-18 12:45:11 +00:00
The
.Fn getnetname
function
1998-01-05 07:12:16 +00:00
installs the unique, operating-system independent netname of
the
caller in the fixed-length array
.Fa name .
Returns
.Dv TRUE
if it succeeds and
.Dv FALSE
if it fails.
.Pp
2002-12-18 12:45:11 +00:00
The
.Fn host2netname
function
1998-01-05 07:12:16 +00:00
converts from a domain-specific hostname to an
operating-system independent netname.
Returns
1998-01-05 07:12:16 +00:00
.Dv TRUE
if it succeeds and
1998-01-05 07:12:16 +00:00
.Dv FALSE
if it fails.
Inverse of
1998-01-05 07:12:16 +00:00
.Fn netname2host .
.Pp
2002-12-18 12:45:11 +00:00
The
.Fn key_decryptsession
function
is an interface to the keyserver daemon, which is associated
with
1998-01-05 07:12:16 +00:00
.Tn RPC Ns 's
secure authentication system
.Tn ( DES
authentication).
User programs rarely need to call it, or its associated routines
1998-01-05 07:12:16 +00:00
.Fn key_encryptsession ,
.Fn key_gendes
and
1998-01-05 07:12:16 +00:00
.Fn key_setsecret .
System commands such as
1998-01-05 07:12:16 +00:00
.Xr login 1
and the
1998-01-05 07:12:16 +00:00
.Tn RPC
library are the main clients of these four routines.
1998-01-05 07:12:16 +00:00
.Pp
2002-12-18 12:45:11 +00:00
The
.Fn key_decryptsession
function
1998-01-05 07:12:16 +00:00
takes a server netname and a
.Tn DES
key, and decrypts the key by
2001-06-24 01:34:38 +00:00
using the public key of the server and the secret key
associated with the effective uid of the calling process. It
is the inverse of
1998-01-05 07:12:16 +00:00
.Fn key_encryptsession .
.Pp
2002-12-18 12:45:11 +00:00
The
.Fn key_encryptsession
function
is a keyserver interface routine.
It
takes a server netname and a des key, and encrypts
it using the public key of the server and the secret key
associated with the effective uid of the calling process. It
is the inverse of
1998-01-05 07:12:16 +00:00
.Fn key_decryptsession .
.Pp
2002-12-18 12:45:11 +00:00
The
.Fn key_gendes
function
is a keyserver interface routine.
It
is used to ask the keyserver for a secure conversation key.
1998-01-05 07:12:16 +00:00
Choosing one
.Qq random
is usually not good enough,
because
the common ways of choosing random numbers, such as using the
current time, are very easy to guess.
1998-01-05 07:12:16 +00:00
.Pp
2002-12-18 12:45:11 +00:00
The
.Fn key_setsecret
function
is a keyserver interface routine.
It is used to set the key for
the effective
1998-01-05 07:12:16 +00:00
.Fa uid
of the calling process.
1998-01-05 07:12:16 +00:00
.Pp
2002-12-18 12:45:11 +00:00
The
.Fn netname2host
function
1998-01-05 07:12:16 +00:00
converts from an operating-system independent netname to a
domain-specific hostname.
Returns
1998-01-05 07:12:16 +00:00
.Dv TRUE
if it succeeds and
1998-01-05 07:12:16 +00:00
.Dv FALSE
if it fails. Inverse of
1998-01-05 07:12:16 +00:00
.Fn host2netname .
.Pp
2002-12-18 12:45:11 +00:00
The
.Fn netname2user
function
1998-01-05 07:12:16 +00:00
converts from an operating-system independent netname to a
domain-specific user ID.
Returns
1998-01-05 07:12:16 +00:00
.Dv TRUE
if it succeeds and
1998-01-05 07:12:16 +00:00
.Dv FALSE
if it fails.
Inverse of
1998-01-05 07:12:16 +00:00
.Fn user2netname .
.Pp
2002-12-18 12:45:11 +00:00
The
.Fn user2netname
function
1998-01-05 07:12:16 +00:00
converts from a domain-specific username to an operating-system
independent netname.
Returns
1998-01-05 07:12:16 +00:00
.Dv TRUE
if it succeeds and
1998-01-05 07:12:16 +00:00
.Dv FALSE
if it fails.
Inverse of
1998-01-05 07:12:16 +00:00
.Fn netname2user .
.Sh SEE ALSO
.Xr rpc 3 ,
.Xr xdr 3 ,
.Xr keyserv 8
.Pp
The following manuals:
1998-01-05 07:12:16 +00:00
.Rs
.%B Remote Procedure Calls: Protocol Specification
.Re
.Rs
.%B Remote Procedure Call Programming Guide
.Re
.Rs
.%B Rpcgen Programming Guide
.Re
.Rs
.%B RPC: Remote Procedure Call Protocol Specification
.%O RFC1050, Sun Microsystems Inc., USC-ISI
.Re