Uniformly refer to RFCs as 'RFC xxxx' and not 'RFCxxxx' or 'RFC-xxxx'.
[dragonfly.git] / lib / libc / rpc / rpc_secure.3
CommitLineData
984263bc
MD
1.\" @(#)rpc_secure.3n 2.1 88/08/08 4.0 RPCSRC; from 1.19 88/06/24 SMI
2.\" $FreeBSD: src/lib/libc/rpc/rpc_secure.3,v 1.6.2.5 2001/12/14 18:33:57 ru Exp $
cabeba47 3.\" $DragonFly: src/lib/libc/rpc/rpc_secure.3,v 1.4 2007/11/23 23:16:36 swildner Exp $
984263bc
MD
4.\"
5.Dd February 16, 1988
6.Dt RPC 3
7.Os
8.Sh NAME
9.Nm rpc_secure
10.Nd library routines for secure remote procedure calls
770899e9
SW
11.Sh LIBRARY
12.Lb libc
984263bc
MD
13.Sh SYNOPSIS
14.In rpc/rpc.h
15.Ft AUTH *
16.Fo authdes_create
17.Fa "char *name"
18.Fa "unsigned window"
19.Fa "struct sockaddr *addr"
20.Fa "des_block *ckey"
21.Fc
22.Ft int
23.Fn authdes_getucred "struct authdes_cred *adc" "uid_t *uid" "gid_t *gid" "int *grouplen" "gid_t *groups"
24.Ft int
25.Fn getnetname "char *name"
26.Ft int
27.Fn host2netname "char *name" "char *host" "char *domain"
28.Ft int
29.Fn key_decryptsession "const char *remotename" "des_block *deskey"
30.Ft int
31.Fn key_encryptsession "const char *remotename" "des_block *deskey"
32.Ft int
33.Fn key_gendes "des_block *deskey"
34.Ft int
35.Fn key_setsecret "const char *key"
36.Ft int
37.Fn netname2host "char *name" "char *host" "int hostlen"
38.Ft int
39.Fn netname2user "char *name" "uid_t *uidp" "gid_t *gidp" "int *gidlenp" "gid_t *gidlist"
40.Ft int
41.Fn user2netname "char *name" "uid_t uid" "char *domain"
42.Sh DESCRIPTION
43These routines are part of the
44.Tn RPC
45library. They implement
46.Tn DES
47Authentication. See
48.Xr rpc 3
49for further details about
50.Tn RPC .
51.Pp
52The
53.Fn authdes_create
54is the first of two routines which interface to the
55.Tn RPC
56secure authentication system, known as
57.Tn DES
58authentication.
59The second is
60.Fn authdes_getucred ,
61below.
62.Pp
63Note: the keyserver daemon
64.Xr keyserv 8
65must be running for the
66.Tn DES
67authentication system to work.
68.Pp
69.Fn Authdes_create ,
70used on the client side, returns an authentication handle that
71will enable the use of the secure authentication system.
72The first parameter
73.Fa name
74is the network name, or
75.Fa netname ,
76of the owner of the server process.
77This field usually
78represents a
79.Fa hostname
80derived from the utility routine
81.Fn host2netname ,
82but could also represent a user name using
83.Fn user2netname .
84The second field is window on the validity of
85the client credential, given in seconds. A small
86window is more secure than a large one, but choosing
87too small of a window will increase the frequency of
88resynchronizations because of clock drift.
89The third
90parameter
91.Fa addr
92is optional. If it is
93.Dv NULL ,
94then the authentication system will assume
95that the local clock is always in sync with the server's
96clock, and will not attempt resynchronizations.
97If an address
98is supplied, however, then the system will use the address
99for consulting the remote time service whenever
100resynchronization
101is required.
102This parameter is usually the
103address of the
104.Tn RPC
105server itself.
106The final parameter
107.Fa ckey
108is also optional. If it is
109.Dv NULL ,
110then the authentication system will
111generate a random
112.Tn DES
113key to be used for the encryption of credentials.
114If it is supplied, however, then it will be used instead.
115.Pp
116.Fn Authdes_getucred ,
117the second of the two
118.Tn DES
119authentication routines,
120is used on the server side for converting a
121.Tn DES
122credential, which is
123operating system independent, into a
124.Ux
125credential.
126This routine differs from utility routine
127.Fn netname2user
128in that
129.Fn authdes_getucred
130pulls its information from a cache, and does not have to do a
131Yellow Pages lookup every time it is called to get its information.
132.Pp
133.Fn Getnetname
134installs the unique, operating-system independent netname of
135the
136caller in the fixed-length array
137.Fa name .
138Returns
139.Dv TRUE
140if it succeeds and
141.Dv FALSE
142if it fails.
143.Pp
144.Fn Host2netname
145converts from a domain-specific hostname to an
146operating-system independent netname.
147Returns
148.Dv TRUE
149if it succeeds and
150.Dv FALSE
151if it fails.
152Inverse of
153.Fn netname2host .
154.Pp
155.Fn Key_decryptsession
156is an interface to the keyserver daemon, which is associated
157with
158.Tn RPC Ns 's
159secure authentication system
160.Tn ( DES
161authentication).
162User programs rarely need to call it, or its associated routines
163.Fn key_encryptsession ,
164.Fn key_gendes
165and
166.Fn key_setsecret .
167System commands such as
168.Xr login 1
169and the
170.Tn RPC
171library are the main clients of these four routines.
172.Pp
173.Fn Key_decryptsession
174takes a server netname and a
175.Tn DES
176key, and decrypts the key by
177using the public key of the server and the secret key
178associated with the effective uid of the calling process. It
179is the inverse of
180.Fn key_encryptsession .
181.Pp
182.Fn Key_encryptsession
183is a keyserver interface routine.
184It
185takes a server netname and a des key, and encrypts
186it using the public key of the server and the secret key
187associated with the effective uid of the calling process. It
188is the inverse of
189.Fn key_decryptsession .
190.Pp
191.Fn Key_gendes
192is a keyserver interface routine.
193It
194is used to ask the keyserver for a secure conversation key.
195Choosing one
196.Qq random
197is usually not good enough,
198because
199the common ways of choosing random numbers, such as using the
200current time, are very easy to guess.
201.Pp
202.Fn Key_setsecret
203is a keyserver interface routine.
204It is used to set the key for
205the effective
206.Fa uid
207of the calling process.
208.Pp
209.Fn Netname2host
210converts from an operating-system independent netname to a
211domain-specific hostname.
212Returns
213.Dv TRUE
214if it succeeds and
215.Dv FALSE
216if it fails. Inverse of
217.Fn host2netname .
218.Pp
219.Fn Netname2user
220converts from an operating-system independent netname to a
221domain-specific user ID.
222Returns
223.Dv TRUE
224if it succeeds and
225.Dv FALSE
226if it fails.
227Inverse of
228.Fn user2netname .
229.Pp
230.Fn User2netname
231converts from a domain-specific username to an operating-system
232independent netname.
233Returns
234.Dv TRUE
235if it succeeds and
236.Dv FALSE
237if it fails.
238Inverse of
239.Fn netname2user .
240.Sh SEE ALSO
241.Xr rpc 3 ,
242.Xr xdr 3 ,
243.Xr keyserv 8
244.Pp
245The following manuals:
246.Rs
247.%B Remote Procedure Calls: Protocol Specification
248.Re
249.Rs
250.%B Remote Procedure Call Programming Guide
251.Re
252.Rs
253.%B Rpcgen Programming Guide
254.Re
255.Rs
256.%B RPC: Remote Procedure Call Protocol Specification
cabeba47 257.%O RFC 1050, Sun Microsystems Inc., USC-ISI
984263bc 258.Re