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