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