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