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