1.\" @(#)rpc_secure.3n 2.1 88/08/08 4.0 RPCSRC; from 1.19 88/06/24 SMI 2.\" $FreeBSD$ 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 174using the public key of the server and the secret key 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 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 256