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