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