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