Subversion Repositories openrisc_2011-10-31

.\" @(#)rpc_secure.3n   2.1 88/08/08 4.0 RPCSRC; from 1.19 88/06/24 SMI

.\" $FreeBSD: src/lib/libc/rpc/rpc_secure.3,v 1.6 2000/03/02 09:13:48 sheldonh Exp $

.\"

.Dd February 16, 1988

.Dt RPC 3

.Sh NAME

.Nm rpc_secure

.Nd library routines for secure remote procedure calls

.Sh SYNOPSIS

.Fd #include 

.Ft AUTH *

.Fo authdes_create

.Fa "char *name"

.Fa "unsigned window"

.Fa "struct sockaddr *addr"

.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" "char *host" "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

.Fn key_gendes "des_block *deskey"

.Ft int

.Fn key_setsecret "const char *key"

.Ft int

.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" "uid_t uid" "char *domain"

.Sh DESCRIPTION

These routines are part of the

.Tn RPC

library.  They implement

.Tn DES

Authentication.  See

.Xr rpc 3

for further details about

.Tn RPC .

.Pp

The

.Fn authdes_create

is the first of two routines which interface to the

.Tn RPC

secure authentication system, known as

.Tn DES

authentication.

The second is

.Fn authdes_getucred ,

below.

.Pp

Note: the keyserver daemon

.Xr keyserv 8

must be running for the

.Tn DES

authentication system to work.

.Pp

.Fn Authdes_create ,

used on the client side, returns an authentication handle that

will enable the use of the secure authentication system.

The first parameter

.Fa name

is the network name, or

.Fa netname ,

of the owner of the server process.

This field usually

represents a

.Fa hostname

derived from the utility routine

.Fn host2netname ,

but could also represent a user name using

.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

parameter

.Fa addr

is optional.  If it is

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

This parameter is usually the

address of the

.Tn RPC

server itself.

The final parameter

.Fa ckey

is also optional.  If it is

.Dv NULL ,

then the authentication system will

generate a random

.Tn DES

key to be used for the encryption of credentials.

If it is supplied, however, then it will be used instead.

.Pp

.Fn Authdes_getucred ,

the second of the two

.Tn DES

authentication routines,

is used on the server side for converting a

.Tn DES

credential, which is

operating system independent, into a

.Ux

credential.

This routine differs from utility routine

.Fn netname2user

in that

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

.Pp

.Fn Getnetname

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

.Fn Host2netname

converts from a domain-specific hostname to an

operating-system independent netname.

Returns

.Dv TRUE

if it succeeds and

.Dv FALSE

if it fails.

Inverse of

.Fn netname2host .

.Pp

.Fn Key_decryptsession

is an interface to the keyserver daemon, which is associated

with

.Tn RPC Ns 's

secure authentication system (

.Tn DES

authentication).

User programs rarely need to call it, or its associated routines

.Fn key_encryptsession ,

.Fn key_gendes

and

.Fn key_setsecret .

System commands such as

.Xr login 1

and the

.Tn RPC

library are the main clients of these four routines.

.Pp

.Fn Key_decryptsession

takes a server netname and a

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

.Fn key_encryptsession .

.Pp

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

.Fn key_decryptsession .

.Pp

.Fn Key_gendes

is a keyserver interface routine.

It

is used to ask the keyserver for a secure conversation key.

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.

.Pp

.Fn Key_setsecret

is a keyserver interface routine.

It is used to set the key for

the effective

.Fa uid

of the calling process.

.Pp

.Fn Netname2host

converts from an operating-system independent netname to a

domain-specific hostname.

Returns

.Dv TRUE

if it succeeds and

.Dv FALSE

if it fails.  Inverse of

.Fn host2netname .

.Pp

.Fn Netname2user

converts from an operating-system independent netname to a

domain-specific user ID.

Returns

.Dv TRUE

if it succeeds and

.Dv FALSE

if it fails.

Inverse of

.Fn user2netname .

.Pp

.Fn User2netname

converts from a domain-specific username to an operating-system

independent netname.

Returns

.Dv TRUE

if it succeeds and

.Dv FALSE

if it fails.

Inverse of

.Fn netname2user .

.Sh SEE ALSO

.Xr rpc 3 ,

.Xr xdr 3 ,

.Xr keyserv 8

.Pp

The following manuals:

.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