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