reactos/dll/win32/libtirpc/man/rpc_secure.3t

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