document the kafs_settoken functions

write about the krb5_appdefault option for kerberos 5 afs tokens
fix prototypes


git-svn-id: svn://svn.h5l.se/heimdal/trunk/heimdal@11877 ec53bebd-3082-4978-b11e-865c3cabbd6b

lib/kafs/kafs.3

@@ -40,8 +40,11 @@
 .Nm k_unlog ,
 .Nm k_setpag ,
 .Nm k_afs_cell_of_file ,
+.Nm kafs_settoken_rxkad ,
+.Nm kafs_settoken ,
 .Nm krb_afslog ,
 .Nm krb_afslog_uid
+.Nm kafs_settoken5 ,
 .Nm krb5_afslog ,
 .Nm krb5_afslog_uid
 .Nd AFS library
@@ -52,19 +55,24 @@ AFS cache manager access library (libkafs, -lkafs)
 .Ft int
 .Fn k_afs_cell_of_file "const char *path" "char *cell" "int len"
 .Ft int
-.Fn k_hasafs
+.Fn k_hasafs "void"
 .Ft int
 .Fn k_pioctl "char *a_path" "int o_opcode" "struct ViceIoctl *a_paramsP" "int a_followSymlinks"
 .Ft int
-.Fn k_setpag
+.Fn k_setpag "void"
 .Ft int
-.Fn k_unlog
+.Fn k_unlog "void"
 .Ft int
+.Fn kafs_settoken_rxkad "const char *cell" "struct ClearToken *token" "void *ticket" "size_t ticket_len"
+.Ft int
+.Fn kafs_settoken "const char *cell" "uid_t uid" "CREDENTIALS *c"
 .Fn krb_afslog "char *cell" "char *realm"
 .Ft int
 .Fn krb_afslog_uid "char *cell" "char *realm" "uid_t uid"
 .Ft krb5_error_code
 .Fn krb5_afslog_uid "krb5_context context" "krb5_ccache id" "const char *cell" "krb5_const_realm realm" "uid_t uid"
+.Ft int
+.Fn kafs_settoken5 "const char *cell" "uid_t uid" "krb5_creds *c"
 .Ft krb5_error_code
 .Fn krb5_afslog "krb5_context context" "krb5_ccache id" "const char *cell" "krb5_const_realm realm"
 .Sh DESCRIPTION
@@ -75,6 +83,26 @@ called before
 .Fn k_hasafs
 is called, or if it fails.
 .Pp
+.Fn kafs_settoken_rxkad
+set
+.Li rxkad
+with the
+.Fa token
+and
+.Fa ticket
+(that have the length
+.Fa ticket_len )
+for a given
+.Fa cell .
+.Pp
+.Fn kafs_settoken
+and
+.Fn kafs_settoken5
+work the same way as
+.Fn kafs_settoken_rxkad
+but internally converts the Kerberos 4 or 5 credential to a afs
+cleartoken and ticket.
+.Pp
 .Fn krb_afslog ,
 and
 .Fn krb_afslog_uid
@@ -106,7 +134,44 @@ and
 are the Kerberos 5 equivalents of
 .Fn krb_afslog ,
 and
- .Fn krb_afslog_uid .
+.Fn krb_afslog_uid .
+.Pp
+.Fn krb5_afslog ,
+.Fn kafs_settoken5
+can be configured to behave diffrently via a 
+.Nm krb5_appdefault
+option
+.Li afs-use-524
+in
+.Pa krb5.conf .
+Possible values for
+.Li afs-use-524
+are:
+.Bl -tag -width local
+.It yes
+use the 524 server in the realm to convert the ticket
+.It no
+use the kerberos 5 ticket directly, can be used with if the afs cell
+support 2b token.
+.It local, 2b
+convert the kerberos 5 credential to a 2b token locally (the same work
+as a 2b 524 server should have done).
+.El
+.Pp
+Example:
+.Pp
+.Bd -literal
+[appdefaults]
+	SU.SE = { afs-use-524 = local }
+	afs-use-524 = yes
+.Ed
+.Pp
+libkafs will use the
+.Li libkafs
+as application name when running the
+.Nm krb5_appdefault
+function call.
+.Pp
 .\" The extra arguments are the ubiquitous context, and the cache id where
 .\" to store any obtained tickets. Since AFS servers normally can't handle
 .\" Kerberos 5 tickets directly, these functions will first obtain version
@@ -185,6 +250,9 @@ usually (depending on the operating system) receive a SIGSYS signal.
 .%T File Server/Cache Manager Interface
 .%D 1991
 .Re
+.Pp
+.Xr krb5_appdefaults 3 ,
+.Xr krb5.conf 5
 .Sh BUGS
 .Ev AFS_SYSCALL
 has no effect under AIX.