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