1secure_rpc(3NSL) Networking Services Library Functions secure_rpc(3NSL)
2
6 secure_rpc, authdes_getucred, authdes_seccreate, getnetname, host2net‐
7 name, key_decryptsession, key_encryptsession, key_gendes, key_setse‐
8 cret, key_secretkey_is_set, netname2host, netname2user, user2netname -
9 library routines for secure remote procedure calls
10
12 cc [ flag... ] file... -lnsl [ library...]
13 #include <rpc/rpc.h>
14 #include <sys/types.h>
15 int authdes_getucred(const struct authdes_cred *adc, uid_t *uidp,
16 gid_t *gidp, short *gidlenp, gid_t *gidlist);
17 AUTH *authdes_seccreate(const char *name, const uint_t window,
20 const char *timehost, ckey);
21 int getnetname(char name [MAXNETNAMELEN+1]);
24 int host2netname(char name [MAXNETNAMELEN+1], const char *host,
27 const char *domain);
28 int key_decryptsession(const char *remotename, des_block *deskey);
31 int key_encryptsession(const char *remotename, des_block *deskey);
34 int key_gendes(des_block *deskey);
37 int key_setsecret(const char *key);
40 int key_secretkey_is_set(void)
43 int netname2host(const char *name, char *host, const int hostlen);
46 int netname2user(const char *name, uid_t *uidp, gid_t *gidp, int *gidlenp,
49 gid_t *gidlist [NGRPS]);
50 int user2netname(char name [MAXNETNAMELEN+1], const uid_t uid,
53 const char *domain);
54
57 The RPC library functions allow C programs to make procedure calls on
58 other machines across the network.
59 RPC supports various authentication flavors. Among them are:
62 AUTH_NONE No authentication (none).
64 AUTH_SYS Traditional UNIX-style authentication.
67 AUTH_DES DES encryption-based authentication.
70 The authdes_getucred() and authdes_seccreate() functions implement the
74 AUTH_DES authentication style. The keyserver daemon keyserv(1M) must be
75 running for the AUTH_DES authentication system to work and keylogin(1)
76 must have been run. The AUTH_DES style of authentication is discussed
77 here. For information about the AUTH_NONE and AUTH_SYS flavors of
78 authentication, refer to rpc_clnt_auth(3NSL). See rpc(3NSL) for the
79 definition of the AUTH data structure.
80 The following functions documented on this page are MT-Safe. For the
83 MT-levels of other authentication styles, see relevant man pages.
84 authdes_getucred() This is the first of two functions that
86 interface to the RPC secure authentication
87 system AUTH_DES. The second is the
88 authdes_seccreate() function. The
89 authdes_getucred() function is used on the
90 server side to convert an AUTH_DES creden‐
91 tial, which is operating system independent,
92 to an AUTH_SYS credential. The authdes_getu‐
93 cred() function returns 1 if it succeeds, 0
94 if it fails.
95 The *uidp parameter is set to the user's
97 numerical ID associated with adc. The *gidp
98 parameter is set to the numerical ID of the
99 user's group. The *gidlist parameter contains
100 the numerical IDs of the other groups to
101 which the user belongs. The *gidlenp parame‐
102 ter is set to the number of valid group ID
103 entries specified by the *gidlist parameter.
104 The authdes_getucred() function fails if the
106 authdes_cred structure was created with the
107 netname of a host. In such a case, net‐
108 name2host() should be used to get the host
109 name from the host netname in the
110 authdes_cred structure.
111 authdes_seccreate() The second of two AUTH_DES authentication
114 functions, the authdes_seccreate() function
115 is used on the client side to return an
116 authentication handle that enables the use of
117 the secure authentication system. The first
118 field, name, specifies the network name net‐
119 name of the owner of the server process. The
120 field usually represents a hostname derived
121 from the host2netname() utility, but the
122 field might also represent a user name con‐
123 verted with the user2netname() utility.
124 The second field, window, specifies the
126 validity of the client credential in seconds.
127 If the difference in time between the
128 client's clock and the server's clock exceeds
129 window, the server rejects the client's cre‐
130 dentials and the clock will have to be resyn‐
131 chronized. A small window is more secure than
132 a large one, but choosing too small a window
133 increases the frequency of resynchronization
134 due to clock drift.
135 The third parameter, timehost, is the host's
137 name and is optional. If timehost is NULL,
138 the authentication system assumes that the
139 local clock is always in sync with the time‐
140 host clock and does not attempt resynchro‐
141 nization. If a timehost is supplied, the sys‐
142 tem consults the remote time service whenever
143 resynchronization is required. The timehost
144 parameter is usually the name of the host on
145 which the server is running.
146 The final parameter, ckey, is also optional.
148 If ckey is NULL, the authentication system
149 generates a random DES key to be used for the
150 encryption of credentials. If ckey is sup‐
151 plied, it is used for encryption.
152 If authdes_seccreate() fails, it returns
154 NULL.
155 getnetname() This function returns the unique, operating
158 system independent netname of the caller in
159 the fixed-length array name. The function
160 returns 1 if it succeeds and 0 if it fails.
161 host2netname() This function converts a domain-specific
164 hostname host to an operating system indepen‐
165 dent netname. The function returns 1 if it
166 succeeds and 0 if it fails. The host2net‐
167 name() function is the inverse of the net‐
168 name2host() function. If the domain is NULL,
169 host2netname() uses the default domain name
170 of the machine. If host is NULL, it defaults
171 to that machine itself. If domain is NULL and
172 host is an NIS name such as myhost.sun.exam‐
173 ple.com, the host2netname() function uses the
174 domain sun.example.com rather than the
175 default domain name of the machine.
176 key_decryptsession() This function is an interface to the key‐
179 server daemon, which is associated with RPC's
180 secure authentication system (AUTH_DES
181 authentication). User programs rarely need to
182 call key_decryptsession() or the associated
183 functions key_encryptsession(), key_gendes(),
184 and key_setsecret().
185 The key_decryptsession() function takes a
187 server netname remotename and a DES key
188 deskey, and decrypts the key by using the the
189 public key of the server and the secret key
190 associated with the effective UID of the
191 calling process. The key_decryptsession()
192 function is the inverse of key_encryptses‐
193 sion() function.
194 key_encryptsession() This function is a keyserver interface that
197 takes a server netname remotename and a DES
198 key deskey, and encrypts the key using the
199 public key of the the server and the secret
200 key associated with the effective UID of the
201 calling process. If the keyserver does not
202 have a key registered for the UID, it falls
203 back to using the secret key for the netname
204 nobody unless this feature has been disabled.
205 See keyserv(1M). The key_encryptsession()
206 function is the inverse of key_decryptses‐
207 sion() function. The key_encryptsession()
208 function returns 0 if it succeeds, −1 if it
209 fails.
210 key_gendes() This is a keyserver interface function used
213 to ask the keyserver for a secure conversa‐
214 tion key. Selecting a conversion key at ran‐
215 dom is generally not secure because the com‐
216 mon ways of choosing random numbers are too
217 easy to guess. The key_gendes() function
218 returns 0 if it succeeds, −1 if it fails.
219 key_setsecret() This is a keyserver interface function used
222 to set the key for the effective UID of the
223 calling process. This function returns 0 if
224 it succeeds, −1 if it fails.
225 key_secretkey_is_set() This is a keyserver interface function used
228 to determine if a key has been set for the
229 effective UID of the calling process. If the
230 keyserver has a key stored for the effective
231 UID of the calling process, the
232 key_secretkey_is_set() function returns 1.
233 Otherwise it returns 0.
234 netname2host() This function converts an operating system
237 independent netname name to a domain-specific
238 hostname host. The hostlen parameter is the
239 maximum size of host. The netname2host()
240 function returns 1 if it succeeds and 0 if it
241 fails. The function is the inverse of the
242 host2netname() function.
243 netname2user() This function converts an operating system
246 independent netname to a domain-specific user
247 ID. The netname2user() function returns 1 if
248 it succeeds and 0 if it fails.The function is
249 the inverse of the user2netname() function.
250 The *uidp parameter is set to the user's
252 numerical ID associated with name. The *gidp
253 parameter is set to the numerical ID of the
254 user's group. The gidlist parameter contains
255 the numerical IDs of the other groups to
256 which the user belongs. The *gidlenp parame‐
257 ter is set to the number of valid group ID
258 entries specified by the gidlist parameter.
259 user2netname() This function converts a domain-specific
262 username to an operating system independent
263 netname. The user2netname() function returns
264 1 if it succeeds and 0 if it fails. The func‐
265 tion is the inverse of netname2user() func‐
266 tion.
267
270 See attributes(5) for descriptions of the following attributes:
271 ┌─────────────────────────────┬─────────────────────────────┐
276 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
277 ├─────────────────────────────┼─────────────────────────────┤
278 │MT-Level │MT-Safe │
279 └─────────────────────────────┴─────────────────────────────┘
280
282 chkey(1), keylogin(1), keyserv(1M), newkey(1M), rpc(3NSL),
283 rpc_clnt_auth(3NSL), attributes(5)
284SunOS 5.11 19 Feb 2004 secure_rpc(3NSL)