lib/libc/rpc/rpc_secure.3

   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 .In 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" "const char *host" "const 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" "const uid_t uid" "const char *domain"
  39 .Sh DESCRIPTION
  40 These routines are part of the
  41 .Tn RPC
  42 library.
  43 They implement
  44 .Tn DES
  45 Authentication.
  46 See
  47 .Xr rpc 3
  48 for further details about
  49 .Tn RPC .
  50 .Pp
  51 The
  52 .Fn authdes_create
  53 is the first of two routines which interface to the
  54 .Tn RPC
  55 secure authentication system, known as
  56 .Tn DES
  57 authentication.
  58 The second is
  59 .Fn authdes_getucred ,
  60 below.
  61 .Pp
  62 Note: the keyserver daemon
  63 .Xr keyserv 8
  64 must be running for the
  65 .Tn DES
  66 authentication system to work.
  67 .Pp
  68 The
  69 .Fn authdes_create
  70 function,
  71 used on the client side, returns an authentication handle that
  72 will enable the use of the secure authentication system.
  73 The first argument
  74 .Fa name
  75 is the network name, or
  76 .Fa netname ,
  77 of the owner of the server process.
  78 This field usually
  79 represents a
  80 .Fa hostname
  81 derived from the utility routine
  82 .Fn host2netname ,
  83 but could also represent a user name using
  84 .Fn user2netname .
  85 The second field is window on the validity of
  86 the client credential, given in seconds.
  87 A small
  88 window is more secure than a large one, but choosing
  89 too small of a window will increase the frequency of
  90 resynchronizations because of clock drift.
  91 The third
  92 argument
  93 .Fa addr
  94 is optional.
  95 If it is
  96 .Dv NULL ,
  97 then the authentication system will assume
  98 that the local clock is always in sync with the server's
  99 clock, and will not attempt resynchronizations.
 100 If an address
 101 is supplied, however, then the system will use the address
 102 for consulting the remote time service whenever
 103 resynchronization
 104 is required.
 105 This argument is usually the
 106 address of the
 107 .Tn RPC
 108 server itself.
 109 The final argument
 110 .Fa ckey
 111 is also optional.
 112 If it is
 113 .Dv NULL ,
 114 then the authentication system will
 115 generate a random
 116 .Tn DES
 117 key to be used for the encryption of credentials.
 118 If it is supplied, however, then it will be used instead.
 119 .Pp
 120 The
 121 .Fn authdes_getucred
 122 function,
 123 the second of the two
 124 .Tn DES
 125 authentication routines,
 126 is used on the server side for converting a
 127 .Tn DES
 128 credential, which is
 129 operating system independent, into a
 130 .Ux
 131 credential.
 132 This routine differs from utility routine
 133 .Fn netname2user
 134 in that
 135 .Fn authdes_getucred
 136 pulls its information from a cache, and does not have to do a
 137 Yellow Pages lookup every time it is called to get its information.
 138 .Pp
 139 The
 140 .Fn getnetname
 141 function
 142 installs the unique, operating-system independent netname of
 143 the
 144 caller in the fixed-length array
 145 .Fa name .
 146 Returns
 147 .Dv TRUE
 148 if it succeeds and
 149 .Dv FALSE
 150 if it fails.
 151 .Pp
 152 The
 153 .Fn host2netname
 154 function
 155 converts from a domain-specific hostname to an
 156 operating-system independent netname.
 157 Returns
 158 .Dv TRUE
 159 if it succeeds and
 160 .Dv FALSE
 161 if it fails.
 162 Inverse of
 163 .Fn netname2host .
 164 .Pp
 165 The
 166 .Fn key_decryptsession
 167 function
 168 is an interface to the keyserver daemon, which is associated
 169 with
 170 .Tn RPC Ns 's
 171 secure authentication system
 172 .Tn ( DES
 173 authentication).
 174 User programs rarely need to call it, or its associated routines
 175 .Fn key_encryptsession ,
 176 .Fn key_gendes
 177 and
 178 .Fn key_setsecret .
 179 System commands such as
 180 .Xr login 1
 181 and the
 182 .Tn RPC
 183 library are the main clients of these four routines.
 184 .Pp
 185 The
 186 .Fn key_decryptsession
 187 function
 188 takes a server netname and a
 189 .Tn DES
 190 key, and decrypts the key by
 191 using the public key of the server and the secret key
 192 associated with the effective uid of the calling process.
 193 It
 194 is the inverse of
 195 .Fn key_encryptsession .
 196 .Pp
 197 The
 198 .Fn key_encryptsession
 199 function
 200 is a keyserver interface routine.
 201 It
 202 takes a server netname and a des key, and encrypts
 203 it using the public key of the server and the secret key
 204 associated with the effective uid of the calling process.
 205 It
 206 is the inverse of
 207 .Fn key_decryptsession .
 208 .Pp
 209 The
 210 .Fn key_gendes
 211 function
 212 is a keyserver interface routine.
 213 It
 214 is used to ask the keyserver for a secure conversation key.
 215 Choosing one
 216 .Qq random
 217 is usually not good enough,
 218 because
 219 the common ways of choosing random numbers, such as using the
 220 current time, are very easy to guess.
 221 .Pp
 222 The
 223 .Fn key_setsecret
 224 function
 225 is a keyserver interface routine.
 226 It is used to set the key for
 227 the effective
 228 .Fa uid
 229 of the calling process.
 230 .Pp
 231 The
 232 .Fn netname2host
 233 function
 234 converts from an operating-system independent netname to a
 235 domain-specific hostname.
 236 Returns
 237 .Dv TRUE
 238 if it succeeds and
 239 .Dv FALSE
 240 if it fails.
 241 Inverse of
 242 .Fn host2netname .
 243 .Pp
 244 The
 245 .Fn netname2user
 246 function
 247 converts from an operating-system independent netname to a
 248 domain-specific user ID.
 249 Returns
 250 .Dv TRUE
 251 if it succeeds and
 252 .Dv FALSE
 253 if it fails.
 254 Inverse of
 255 .Fn user2netname .
 256 .Pp
 257 The
 258 .Fn user2netname
 259 function
 260 converts from a domain-specific username to an operating-system
 261 independent netname.
 262 Returns
 263 .Dv TRUE
 264 if it succeeds and
 265 .Dv FALSE
 266 if it fails.
 267 Inverse of
 268 .Fn netname2user .
 269 .Sh SEE ALSO
 270 .Xr rpc 3 ,
 271 .Xr xdr 3 ,
 272 .Xr keyserv 8
 273 .Pp
 274 The following manuals:
 275 .Rs
 276 .%B Remote Procedure Calls: Protocol Specification
 277 .Re
 278 .Rs
 279 .%B Remote Procedure Call Programming Guide
 280 .Re
 281 .Rs
 282 .%B Rpcgen Programming Guide
 283 .Re
 284 .Rs
 285 .%B RPC: Remote Procedure Call Protocol Specification
 286 .%O RFC1050, Sun Microsystems Inc., USC-ISI
 287 .Re