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