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