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