1secure_rpc(3NSL)     Networking Services Library Functions    secure_rpc(3NSL)
2
3
4

NAME

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

SYNOPSIS

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
18
19       AUTH *authdes_seccreate(const char *name, const uint_t window,
20            const char *timehost, ckey);
21
22
23       int getnetname(char name [MAXNETNAMELEN+1]);
24
25
26       int host2netname(char name [MAXNETNAMELEN+1], const char *host,
27            const char *domain);
28
29
30       int key_decryptsession(const char *remotename, des_block *deskey);
31
32
33       int key_encryptsession(const char *remotename, des_block *deskey);
34
35
36       int key_gendes(des_block *deskey);
37
38
39       int key_setsecret(const char *key);
40
41
42       int key_secretkey_is_set(void)
43
44
45       int netname2host(const char *name, char *host, const int hostlen);
46
47
48       int netname2user(const char *name, uid_t *uidp, gid_t *gidp, int *gidlenp,
49            gid_t *gidlist [NGRPS]);
50
51
52       int user2netname(char name [MAXNETNAMELEN+1], const uid_t uid,
53            const char *domain);
54
55

DESCRIPTION

57       The RPC library functions allow C programs to make procedure  calls  on
58       other machines across the network.
59
60
61       RPC supports various authentication flavors. Among them are:
62
63       AUTH_NONE    No authentication (none).
64
65
66       AUTH_SYS     Traditional UNIX-style authentication.
67
68
69       AUTH_DES     DES encryption-based authentication.
70
71
72
73       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
81
82       The  following  functions  documented on this page are MT-Safe. For the
83       MT-levels of other authentication styles, see relevant man pages.
84
85       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
96                                 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
105                                 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
112
113       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
125                                 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
136                                 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
147                                 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
153                                 If   authdes_seccreate()  fails,  it  returns
154                                 NULL.
155
156
157       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
162
163       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
177
178       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
186                                 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
195
196       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
211
212       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
220
221       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
226
227       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
235
236       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
244
245       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
251                                 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
260
261       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
268

ATTRIBUTES

270       See attributes(5) for descriptions of the following attributes:
271
272
273
274
275       ┌─────────────────────────────┬─────────────────────────────┐
276       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
277       ├─────────────────────────────┼─────────────────────────────┤
278       │MT-Level                     │MT-Safe                      │
279       └─────────────────────────────┴─────────────────────────────┘
280

SEE ALSO

282       chkey(1),    keylogin(1),    keyserv(1M),    newkey(1M),     rpc(3NSL),
283       rpc_clnt_auth(3NSL), attributes(5)
284
285
286
287SunOS 5.11                        19 Feb 2004                 secure_rpc(3NSL)
Impressum