crypto/heimdal-0.6.3/lib/kafs/kafs.3

   1 .\" Copyright (c) 1998 - 1999, 2001 - 2003 Kungliga Tekniska Högskolan
   2 .\" (Royal Institute of Technology, Stockholm, Sweden).
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\"
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\"
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\"
  16 .\" 3. Neither the name of the Institute nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     $Id: kafs.3,v 1.16 2003/04/16 13:58:27 lha Exp $
  33 .\"
  34 .Dd Mar 17, 2003
  35 .Os HEIMDAL
  36 .Dt KAFS 3
  37 .Sh NAME
  38 .Nm k_hasafs ,
  39 .Nm k_pioctl ,
  40 .Nm k_unlog ,
  41 .Nm k_setpag ,
  42 .Nm k_afs_cell_of_file ,
  43 .Nm kafs_set_verbose ,
  44 .Nm kafs_settoken_rxkad ,
  45 .Nm kafs_settoken ,
  46 .Nm krb_afslog ,
  47 .Nm krb_afslog_uid
  48 .Nm kafs_settoken5 ,
  49 .Nm krb5_afslog ,
  50 .Nm krb5_afslog_uid
  51 .Nd AFS library
  52 .Sh LIBRARY
  53 AFS cache manager access library (libkafs, -lkafs)
  54 .Sh SYNOPSIS
  55 .In kafs.h
  56 .Ft int
  57 .Fn k_afs_cell_of_file "const char *path" "char *cell" "int len"
  58 .Ft int
  59 .Fn k_hasafs "void"
  60 .Ft int
  61 .Fn k_pioctl "char *a_path" "int o_opcode" "struct ViceIoctl *a_paramsP" "int a_followSymlinks"
  62 .Ft int
  63 .Fn k_setpag "void"
  64 .Ft int
  65 .Fn k_unlog "void"
  66 .Ft void
  67 .Fn kafs_set_verbose "void (*func)(void *, const char *, int)" "void *"
  68 .Ft int
  69 .Fn kafs_settoken_rxkad "const char *cell" "struct ClearToken *token" "void *ticket" "size_t ticket_len"
  70 .Ft int
  71 .Fn kafs_settoken "const char *cell" "uid_t uid" "CREDENTIALS *c"
  72 .Fn krb_afslog "char *cell" "char *realm"
  73 .Ft int
  74 .Fn krb_afslog_uid "char *cell" "char *realm" "uid_t uid"
  75 .Ft krb5_error_code
  76 .Fn krb5_afslog_uid "krb5_context context" "krb5_ccache id" "const char *cell" "krb5_const_realm realm" "uid_t uid"
  77 .Ft int
  78 .Fn kafs_settoken5 "const char *cell" "uid_t uid" "krb5_creds *c"
  79 .Ft krb5_error_code
  80 .Fn krb5_afslog "krb5_context context" "krb5_ccache id" "const char *cell" "krb5_const_realm realm"
  81 .Sh DESCRIPTION
  82 .Fn k_hasafs
  83 initializes some library internal structures, and tests for the
  84 presence of AFS in the kernel, none of the other functions should be
  85 called before
  86 .Fn k_hasafs
  87 is called, or if it fails.
  88 .Pp
  89 .Fn kafs_set_verbose
  90 set a log function that will be called each time the kafs library does
  91 something important so that the application using libkafs can output
  92 verbose logging.
  93 Calling the function
  94 .Fa kafs_set_verbose
  95 with the function argument set to
  96 .Dv NULL
  97 will stop libkafs from calling the logging function (if set).
  98 .Pp
  99 .Fn kafs_settoken_rxkad
 100 set
 101 .Li rxkad
 102 with the
 103 .Fa token
 104 and
 105 .Fa ticket
 106 (that have the length
 107 .Fa ticket_len )
 108 for a given
 109 .Fa cell .
 110 .Pp
 111 .Fn kafs_settoken
 112 and
 113 .Fn kafs_settoken5
 114 work the same way as
 115 .Fn kafs_settoken_rxkad
 116 but internally converts the Kerberos 4 or 5 credential to a afs
 117 cleartoken and ticket.
 118 .Pp
 119 .Fn krb_afslog ,
 120 and
 121 .Fn krb_afslog_uid
 122 obtains new tokens (and possibly tickets) for the specified
 123 .Fa cell
 124 and
 125 .Fa realm .
 126 If
 127 .Fa cell
 128 is
 129 .Dv NULL ,
 130 the local cell is used. If
 131 .Fa realm
 132 is
 133 .Dv NULL ,
 134 the function tries to guess what realm to use. Unless you  have some good knowledge of what cell or realm to use, you should pass
 135 .Dv NULL .
 136 .Fn krb_afslog
 137 will use the real user-id for the
 138 .Dv ViceId
 139 field in the token,
 140 .Fn krb_afslog_uid
 141 will use
 142 .Fa uid .
 143 .Pp
 144 .Fn krb5_afslog ,
 145 and
 146 .Fn krb5_afslog_uid
 147 are the Kerberos 5 equivalents of
 148 .Fn krb_afslog ,
 149 and
 150 .Fn krb_afslog_uid .
 151 .Pp
 152 .Fn krb5_afslog ,
 153 .Fn kafs_settoken5
 154 can be configured to behave diffrently via a
 155 .Nm krb5_appdefault
 156 option
 157 .Li afs-use-524
 158 in
 159 .Pa krb5.conf .
 160 Possible values for
 161 .Li afs-use-524
 162 are:
 163 .Bl -tag -width local
 164 .It yes
 165 use the 524 server in the realm to convert the ticket
 166 .It no
 167 use the Kerberos 5 ticket directly, can be used with if the afs cell
 168 support 2b token.
 169 .It local, 2b
 170 convert the Kerberos 5 credential to a 2b token locally (the same work
 171 as a 2b 524 server should have done).
 172 .El
 173 .Pp
 174 Example:
 175 .Pp
 176 .Bd -literal
 177 [appdefaults]
 178         SU.SE = { afs-use-524 = local }
 179         PDC.KTH.SE = { afs-use-524 = yes }
 180         afs-use-524 = yes
 181 .Ed
 182 .Pp
 183 libkafs will use the
 184 .Li libkafs
 185 as application name when running the
 186 .Nm krb5_appdefault
 187 function call.
 188 .Pp
 189 The (uppercased) cellname is used as the realm to the
 190 .Nm krb5_appdefault function.
 191 .Pp
 192 .\" The extra arguments are the ubiquitous context, and the cache id where
 193 .\" to store any obtained tickets. Since AFS servers normally can't handle
 194 .\" Kerberos 5 tickets directly, these functions will first obtain version
 195 .\" 5 tickets for the requested cells, and then convert them to version 4
 196 .\" tickets, that can be stashed in the kernel. To convert tickets the
 197 .\" .Fn krb524_convert_creds_kdc
 198 .\" function will be used.
 199 .\" .Pp
 200 .Fn k_afs_cell_of_file
 201 will in
 202 .Fa cell
 203 return the cell of a specified file, no more than
 204 .Fa len
 205 characters is put in
 206 .Fa cell .
 207 .Pp
 208 .Fn k_pioctl
 209 does a
 210 .Fn pioctl
 211 syscall with the specified arguments. This function is equivalent to
 212 .Fn lpioctl .
 213 .Pp
 214 .Fn k_setpag
 215 initializes a new PAG.
 216 .Pp
 217 .Fn k_unlog
 218 removes destroys all tokens in the current PAG.
 219 .Sh RETURN VALUES
 220 .Fn k_hasafs
 221 returns 1 if AFS is present in the kernel, 0 otherwise.
 222 .Fn krb_afslog
 223 and
 224 .Fn krb_afslog_uid
 225 returns 0 on success, or a Kerberos error number on failure.
 226 .Fn k_afs_cell_of_file ,
 227 .Fn k_pioctl ,
 228 .Fn k_setpag ,
 229 and
 230 .Fn k_unlog
 231 all return the value of the underlaying system call, 0 on success.
 232 .Sh ENVIRONMENT
 233 The following environment variable affect the mode of operation of
 234 .Nm kafs :
 235 .Bl -tag -width AFS_SYSCALL
 236 .It Ev AFS_SYSCALL
 237 Normally,
 238 .Nm kafs
 239 will try to figure out the correct system call(s) that are used by AFS
 240 by itself.  If it does not manage to do that, or does it incorrectly,
 241 you can set this variable to the system call number or list of system
 242 call numbers that should be used.
 243 .El
 244 .Sh EXAMPLES
 245 The following code from
 246 .Nm login
 247 will obtain a new PAG and tokens for the local cell and the cell of
 248 the users home directory.
 249 .Bd -literal
 250 if (k_hasafs()) {
 251         char cell[64];
 252         k_setpag();
 253         if(k_afs_cell_of_file(pwd->pw_dir, cell, sizeof(cell)) == 0)
 254                 krb_afslog(cell, NULL);
 255         krb_afslog(NULL, NULL);
 256 }
 257 .Ed
 258 .Sh ERRORS
 259 If any of these functions (apart from
 260 .Fn k_hasafs )
 261 is called without AFS being present in the kernel, the process will
 262 usually (depending on the operating system) receive a SIGSYS signal.
 263 .Sh SEE ALSO
 264 .Rs
 265 .%A Transarc Corporation
 266 .%J AFS-3 Programmer's Reference
 267 .%T File Server/Cache Manager Interface
 268 .%D 1991
 269 .Re
 270 .Pp
 271 .Xr krb5_appdefaults 3 ,
 272 .Xr krb5.conf 5
 273 .Sh BUGS
 274 .Ev AFS_SYSCALL
 275 has no effect under AIX.