crypto/heimdal/lib/kafs/kafs.3

   1 .\" Copyright (c) 1998 - 2006 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$
  33 .\"
  34 .Dd May  1, 2006
  35 .Os HEIMDAL
  36 .Dt KAFS 3
  37 .Sh NAME
  38 .Nm k_hasafs ,
  39 .Nm k_hasafs_recheck ,
  40 .Nm k_pioctl ,
  41 .Nm k_unlog ,
  42 .Nm k_setpag ,
  43 .Nm k_afs_cell_of_file ,
  44 .Nm kafs_set_verbose ,
  45 .Nm kafs_settoken_rxkad ,
  46 .Nm kafs_settoken ,
  47 .Nm krb_afslog ,
  48 .Nm krb_afslog_uid ,
  49 .Nm kafs_settoken5 ,
  50 .Nm krb5_afslog ,
  51 .Nm krb5_afslog_uid
  52 .Nd AFS library
  53 .Sh LIBRARY
  54 AFS cache manager access library (libkafs, -lkafs)
  55 .Sh SYNOPSIS
  56 .In kafs.h
  57 .Ft int
  58 .Fn k_afs_cell_of_file "const char *path" "char *cell" "int len"
  59 .Ft int
  60 .Fn k_hasafs "void"
  61 .Ft int
  62 .Fn k_hasafs_recheck "void"
  63 .Ft int
  64 .Fn k_pioctl "char *a_path" "int o_opcode" "struct ViceIoctl *a_paramsP" "int a_followSymlinks"
  65 .Ft int
  66 .Fn k_setpag "void"
  67 .Ft int
  68 .Fn k_unlog "void"
  69 .Ft void
  70 .Fn kafs_set_verbose "void (*func)(void *, const char *, int)" "void *"
  71 .Ft int
  72 .Fn kafs_settoken_rxkad "const char *cell" "struct ClearToken *token" "void *ticket" "size_t ticket_len"
  73 .Ft int
  74 .Fn kafs_settoken "const char *cell" "uid_t uid" "CREDENTIALS *c"
  75 .Fn krb_afslog "char *cell" "char *realm"
  76 .Ft int
  77 .Fn krb_afslog_uid "char *cell" "char *realm" "uid_t uid"
  78 .Ft krb5_error_code
  79 .Fn krb5_afslog_uid "krb5_context context" "krb5_ccache id" "const char *cell" "krb5_const_realm realm" "uid_t uid"
  80 .Ft int
  81 .Fn kafs_settoken5 "const char *cell" "uid_t uid" "krb5_creds *c"
  82 .Ft krb5_error_code
  83 .Fn krb5_afslog "krb5_context context" "krb5_ccache id" "const char *cell" "krb5_const_realm realm"
  84 .Sh DESCRIPTION
  85 .Fn k_hasafs
  86 initializes some library internal structures, and tests for the
  87 presence of AFS in the kernel, none of the other functions should be
  88 called before
  89 .Fn k_hasafs
  90 is called, or if it fails.
  91 .Pp
  92 .Fn k_hasafs_recheck
  93 forces a recheck if a AFS client has started since last time
  94 .Fn k_hasafs
  95 or
  96 .Fn k_hasafs_recheck
  97 was called.
  98 .Pp
  99 .Fn kafs_set_verbose
 100 set a log function that will be called each time the kafs library does
 101 something important so that the application using libkafs can output
 102 verbose logging.
 103 Calling the function
 104 .Fa kafs_set_verbose
 105 with the function argument set to
 106 .Dv NULL
 107 will stop libkafs from calling the logging function (if set).
 108 .Pp
 109 .Fn kafs_settoken_rxkad
 110 set
 111 .Li rxkad
 112 with the
 113 .Fa token
 114 and
 115 .Fa ticket
 116 (that have the length
 117 .Fa ticket_len )
 118 for a given
 119 .Fa cell .
 120 .Pp
 121 .Fn kafs_settoken
 122 and
 123 .Fn kafs_settoken5
 124 work the same way as
 125 .Fn kafs_settoken_rxkad
 126 but internally converts the Kerberos 4 or 5 credential to a afs
 127 cleartoken and ticket.
 128 .Pp
 129 .Fn krb_afslog ,
 130 and
 131 .Fn krb_afslog_uid
 132 obtains new tokens (and possibly tickets) for the specified
 133 .Fa cell
 134 and
 135 .Fa realm .
 136 If
 137 .Fa cell
 138 is
 139 .Dv NULL ,
 140 the local cell is used. If
 141 .Fa realm
 142 is
 143 .Dv NULL ,
 144 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
 145 .Dv NULL .
 146 .Fn krb_afslog
 147 will use the real user-id for the
 148 .Dv ViceId
 149 field in the token,
 150 .Fn krb_afslog_uid
 151 will use
 152 .Fa uid .
 153 .Pp
 154 .Fn krb5_afslog ,
 155 and
 156 .Fn krb5_afslog_uid
 157 are the Kerberos 5 equivalents of
 158 .Fn krb_afslog ,
 159 and
 160 .Fn krb_afslog_uid .
 161 .Pp
 162 .Fn krb5_afslog ,
 163 .Fn kafs_settoken5
 164 can be configured to behave differently via a
 165 .Nm krb5_appdefault
 166 option
 167 .Li afs-use-524
 168 in
 169 .Pa krb5.conf .
 170 Possible values for
 171 .Li afs-use-524
 172 are:
 173 .Bl -tag -width local
 174 .It yes
 175 use the 524 server in the realm to convert the ticket
 176 .It no
 177 use the Kerberos 5 ticket directly, can be used with if the afs cell
 178 support 2b token.
 179 .It local, 2b
 180 convert the Kerberos 5 credential to a 2b token locally (the same work
 181 as a 2b 524 server should have done).
 182 .El
 183 .Pp
 184 Example:
 185 .Pp
 186 .Bd -literal
 187 [appdefaults]
 188         SU.SE = { afs-use-524 = local }
 189         PDC.KTH.SE = { afs-use-524 = yes }
 190         afs-use-524 = yes
 191 .Ed
 192 .Pp
 193 libkafs will use the
 194 .Li libkafs
 195 as application name when running the
 196 .Nm krb5_appdefault
 197 function call.
 198 .Pp
 199 The (uppercased) cell name is used as the realm to the
 200 .Nm krb5_appdefault function.
 201 .Pp
 202 .\" The extra arguments are the ubiquitous context, and the cache id where
 203 .\" to store any obtained tickets. Since AFS servers normally can't handle
 204 .\" Kerberos 5 tickets directly, these functions will first obtain version
 205 .\" 5 tickets for the requested cells, and then convert them to version 4
 206 .\" tickets, that can be stashed in the kernel. To convert tickets the
 207 .\" .Fn krb524_convert_creds_kdc
 208 .\" function will be used.
 209 .\" .Pp
 210 .Fn k_afs_cell_of_file
 211 will in
 212 .Fa cell
 213 return the cell of a specified file, no more than
 214 .Fa len
 215 characters is put in
 216 .Fa cell .
 217 .Pp
 218 .Fn k_pioctl
 219 does a
 220 .Fn pioctl
 221 system call with the specified arguments. This function is equivalent to
 222 .Fn lpioctl .
 223 .Pp
 224 .Fn k_setpag
 225 initializes a new PAG.
 226 .Pp
 227 .Fn k_unlog
 228 removes destroys all tokens in the current PAG.
 229 .Sh RETURN VALUES
 230 .Fn k_hasafs
 231 returns 1 if AFS is present in the kernel, 0 otherwise.
 232 .Fn krb_afslog
 233 and
 234 .Fn krb_afslog_uid
 235 returns 0 on success, or a Kerberos error number on failure.
 236 .Fn k_afs_cell_of_file ,
 237 .Fn k_pioctl ,
 238 .Fn k_setpag ,
 239 and
 240 .Fn k_unlog
 241 all return the value of the underlaying system call, 0 on success.
 242 .Sh ENVIRONMENT
 243 The following environment variable affect the mode of operation of
 244 .Nm kafs :
 245 .Bl -tag -width AFS_SYSCALL
 246 .It Ev AFS_SYSCALL
 247 Normally,
 248 .Nm kafs
 249 will try to figure out the correct system call(s) that are used by AFS
 250 by itself.  If it does not manage to do that, or does it incorrectly,
 251 you can set this variable to the system call number or list of system
 252 call numbers that should be used.
 253 .El
 254 .Sh EXAMPLES
 255 The following code from
 256 .Nm login
 257 will obtain a new PAG and tokens for the local cell and the cell of
 258 the users home directory.
 259 .Bd -literal
 260 if (k_hasafs()) {
 261         char cell[64];
 262         k_setpag();
 263         if(k_afs_cell_of_file(pwd->pw_dir, cell, sizeof(cell)) == 0)
 264                 krb_afslog(cell, NULL);
 265         krb_afslog(NULL, NULL);
 266 }
 267 .Ed
 268 .Sh ERRORS
 269 If any of these functions (apart from
 270 .Fn k_hasafs )
 271 is called without AFS being present in the kernel, the process will
 272 usually (depending on the operating system) receive a SIGSYS signal.
 273 .Sh SEE ALSO
 274 .Xr krb5_appdefault 3 ,
 275 .Xr krb5.conf 5
 276 .Rs
 277 .%A Transarc Corporation
 278 .%J AFS-3 Programmer's Reference
 279 .%T File Server/Cache Manager Interface
 280 .%D 1991
 281 .Re
 282 .Sh FILES
 283 libkafs will search for
 284 .Pa ThisCell and
 285 .Pa TheseCells
 286 in the following locations:
 287 .Pa /usr/vice/etc ,
 288 .Pa /etc/openafs ,
 289 .Pa /var/db/openafs/etc ,
 290 .Pa /usr/arla/etc ,
 291 .Pa /etc/arla ,
 292 and
 293 .Pa /etc/afs
 294 .Sh BUGS
 295 .Ev AFS_SYSCALL
 296 has no effect under AIX.