crypto/external/bsd/heimdal/dist/lib/kafs/kafs.3

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