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 54AFS 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 86initializes some library internal structures, and tests for the 87presence of AFS in the kernel, none of the other functions should be 88called before 89.Fn k_hasafs 90is called, or if it fails. 91.Pp 92.Fn k_hasafs_recheck 93forces a recheck if a AFS client has started since last time 94.Fn k_hasafs 95or 96.Fn k_hasafs_recheck 97was called. 98.Pp 99.Fn kafs_set_verbose 100set a log function that will be called each time the kafs library does 101something important so that the application using libkafs can output 102verbose logging. 103Calling the function 104.Fa kafs_set_verbose 105with the function argument set to 106.Dv NULL 107will stop libkafs from calling the logging function (if set). 108.Pp 109.Fn kafs_settoken_rxkad 110set 111.Li rxkad 112with the 113.Fa token 114and 115.Fa ticket 116(that have the length 117.Fa ticket_len ) 118for a given 119.Fa cell . 120.Pp 121.Fn kafs_settoken 122and 123.Fn kafs_settoken5 124work the same way as 125.Fn kafs_settoken_rxkad 126but internally converts the Kerberos 4 or 5 credential to a afs 127cleartoken and ticket. 128.Pp 129.Fn krb_afslog , 130and 131.Fn krb_afslog_uid 132obtains new tokens (and possibly tickets) for the specified 133.Fa cell 134and 135.Fa realm . 136If 137.Fa cell 138is 139.Dv NULL , 140the local cell is used. If 141.Fa realm 142is 143.Dv NULL , 144the 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 147will use the real user-id for the 148.Dv ViceId 149field in the token, 150.Fn krb_afslog_uid 151will use 152.Fa uid . 153.Pp 154.Fn krb5_afslog , 155and 156.Fn krb5_afslog_uid 157are the Kerberos 5 equivalents of 158.Fn krb_afslog , 159and 160.Fn krb_afslog_uid . 161.Pp 162.Fn krb5_afslog , 163.Fn kafs_settoken5 164can be configured to behave differently via a 165.Nm krb5_appdefault 166option 167.Li afs-use-524 168in 169.Pa krb5.conf . 170Possible values for 171.Li afs-use-524 172are: 173.Bl -tag -width local 174.It yes 175use the 524 server in the realm to convert the ticket 176.It no 177use the Kerberos 5 ticket directly, can be used with if the afs cell 178support 2b token. 179.It local, 2b 180convert the Kerberos 5 credential to a 2b token locally (the same work 181as a 2b 524 server should have done). 182.El 183.Pp 184Example: 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 193libkafs will use the 194.Li libkafs 195as application name when running the 196.Nm krb5_appdefault 197function call. 198.Pp 199The (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 211will in 212.Fa cell 213return the cell of a specified file, no more than 214.Fa len 215characters is put in 216.Fa cell . 217.Pp 218.Fn k_pioctl 219does a 220.Fn pioctl 221system call with the specified arguments. This function is equivalent to 222.Fn lpioctl . 223.Pp 224.Fn k_setpag 225initializes a new PAG. 226.Pp 227.Fn k_unlog 228removes destroys all tokens in the current PAG. 229.Sh RETURN VALUES 230.Fn k_hasafs 231returns 1 if AFS is present in the kernel, 0 otherwise. 232.Fn krb_afslog 233and 234.Fn krb_afslog_uid 235returns 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 , 239and 240.Fn k_unlog 241all return the value of the underlaying system call, 0 on success. 242.Sh ENVIRONMENT 243The following environment variable affect the mode of operation of 244.Nm kafs : 245.Bl -tag -width AFS_SYSCALL 246.It Ev AFS_SYSCALL 247Normally, 248.Nm kafs 249will try to figure out the correct system call(s) that are used by AFS 250by itself. If it does not manage to do that, or does it incorrectly, 251you can set this variable to the system call number or list of system 252call numbers that should be used. 253.El 254.Sh EXAMPLES 255The following code from 256.Nm login 257will obtain a new PAG and tokens for the local cell and the cell of 258the users home directory. 259.Bd -literal 260if (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 269If any of these functions (apart from 270.Fn k_hasafs ) 271is called without AFS being present in the kernel, the process will 272usually (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 283libkafs will search for 284.Pa ThisCell and 285.Pa TheseCells 286in 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 , 292and 293.Pa /etc/afs 294.Sh BUGS 295.Ev AFS_SYSCALL 296has no effect under AIX. 297