krb_set_srvtab_string(3krb) [ultrix man page]

krb_set_tkt_string(3krb)												  krb_set_tkt_string(3krb)

Name
       krb_set_tkt_string, krb_set_srvtab_string - Environmental setup of the Kerberos libraries

Syntax
	#include <krb.h>

	void krb_set_tkt_string (filename)
	char *filename

	void krb_set_srvtab_string (filename)
	char *filename

Arguments
       filename
	       The filename of the Kerberos ticket cache file or the name of the service table file.

Description
       The  routine  sets  the	default name of the file that holds a cache of service tickets and associated session keys belonging to a Kerberos
       principal.  The routine accepts a filename for the cache and copies this name into the local storage of The default before any calls to	is
       is the user ID of the process that calls

       You  should call krb_set_tkt_string during Kerberos initialization to assure that any routines called later receive the proper name if they
       require the filename of the cache.

       The routine sets the default name of the file that stores the keys of the Kerberos applications running on the  local  host.   The  routine
       accepts a filename for the service table file and copies this name into the local storage of

       You  should call krb_set_srvtab_string during the Kerberos initialization of a service to assure that any subsequently called routines that
       require the filename of the service table receive the proper name.  The default, before any calls to the string, is

Files
       See Also
	      kerberos(3krb), krb_sendauth(3krb), krb_sendmutual(3krb)

															  krb_set_tkt_string(3krb)

krb_sendauth(3krb)														krb_sendauth(3krb)

Name
       krb_sendauth, krb_recvauth - Kerberos authentication library routines.

Syntax
	#include <krb.h>
	#include <des.h>
	#include <netinet/in.h>

	int krb_sendauth (options, fd, tkt_authen, f_service,
				   f_inst, f_realm, checksum, msg_data,
				   cred, schedule, l_addr, f_addr,
				   version_in)
	long		   options;
	int	      fd;
	KTEXT	      tkt_authen;
	char		   *f_service;
	char		   *f_instance;
	char		   *f_realm;
	u_long		   checksum;
	MSG_DAT       *msg_data;
	CREDENTIALS   *cred;
	Key_schedule	   schedule;
	struct sockaddr_in *l_addr;
	struct sockaddr_in *f_addr;
	char		   *version_in;

	int krb_recvauth (options, fd, tkt_authen_out, l_service,
				   l_instance, f_addr, l_addr, ad,
				   srvtab_file, schedule, version_out)
	long		   options;
	int	      fd;
	KTEXT	      tkt_authen_out;
	char		   *l_service;
	char		   *l_instance;
	struct sockaddr_in *f_addr;
	struct sockaddr_in *l_addr;
	AUTH_DAT	   *ad;
	char		   *srvtab_file;
	Key_schedule	   schedule;
	char		   *version_out;

Arguments
       options Defined	in To specify multiple options, construct the options argument as a bitwise-OR of the desired options.	The options are as
	       follows:

	       KOPT_DONT_MK_REQ
			will not use the function (see to produce the ticket-authenticator pair, authen_tkt.   Instead,  the  ticket-authenticator
			pair is read from the argument, tkt_authen.

	       KOPT_DONT_CANON
			will  not convert the instance name, f_instance, to canonical form.  If KOPT_DONT_CANON is not set, the instance name used
			is the output from (see with argument f_instance as input.

	       KOPT_DO_MUTUAL
			and provide authentication on both ends of the network connection.  Otherwise, the caller of is authenticated to the call-
			er  of but the caller of is not authenticated to the caller of For mutual authentication to occur, both and must be called
			with this option set.

       f_service
	       Character pointer to the primary name of the foreign principal.	The local principal is the principal that  calls  the  above  rou-
	       tines.  The foreign principal is the principal with which the local principal is attempting to communicate.  If KOPT_DONT_MK_REQ is
	       set and KOPT_DO_MUTUAL is not, then f_service should be set equal to the NULL pointer.

       f_instance
	       Character pointer to the instance name of the foreign principal.  If KOPT_DONT_MK_REQ  is  set  and  KOPT_DO_MUTUAL  is	not,  then
	       f_instance should be set equal to the NULL pointer.

       f_realm Character  pointer to the realm name of the foreign principal.  If the f_realm parameter is set equal to the NULL pointer, then the
	       local realm is used as the f_realm.  If KOPT_DONT_MK_REQ is set and KOPT_DO_MUTUAL is not, then f_service should be  set  equal	to
	       the NULL pointer.

       l_service
	       Character pointer to the primary name of the local principal.

       l_instance
	       Character pointer to the instance name of the local principal.

       fd      The  file  descriptor used to send data to the foreign principal, or the file descriptor from which data from the foreign principal
	       can be read.  In either case, the file descriptor must be associated with a socket that uses blocking I/O.

       tkt_authen
	       Pointer to the text structure in which the Kerberos library routines  build  the  ticket-authenticator  pair.   This  structure	is
	       designed to be included within the message sent to the foreign principal to authenticate the local principal's identity to the for-
	       eign principal.	This structure can be either input to or output from depending on whether KOPT_DONT_MK_REQ is set or not set.	In
	       either case, storage must be allocated for tkt_authen.

       tkt_authen_out
	       Pointer	to  the  ticket-authenticator  pair  that reads from within the message.  The message is sent by to the local principal to
	       authenticate the foreign principal to the local principal.  Storage must be allocated for tkt_authen_out.

       checksum
	       Input to checksum is packaged in the message that is sent to the foreign principal.  It serves as a secret piece of data  that  can
	       only  be  known to the foreign principal if the foreign principal is authenticated as the foreign principal.  It is used to facili-
	       tate mutual authentication, so if the KOPT_DO_MUTUAL is	not  set,  the	value  of  this  argument  is  inconsequential.   If  both
	       KOPT_DONT_MK_REQ  and  KOPT_DO_MUTUAL  are set, then the checksum parameter must be equal to the checksum value used by in the cre-
	       ation of the ticket-authenticator pair, authen_tkt.

       msg_data
	       Pointer to a structure which is filled with the mutual authentication message sent by and interpreted by The message sent  from	to
	       the  message  that includes the ticket-authenticator pair, authenticates only the caller of to the caller of An additional message,
	       the one returned by inside msg_data, must be sent by and interpreted by in order to authenticate the caller of to the caller of	If
	       the  KOPT_DO_MUTUAL option is set, space must be allocated for the    msg_data structure.  Otherwise, since no message will be sent
	       from to the msg_data parameter should be set equivalent to the NULL pointer.

       cred    a pointer to a credentials structure that is output from The credentials structure includes the ticket  that  the  local  principal
	       uses  to  authenticate  to the foreign principal as well as other authentication information associated with the foreign principal.
	       If the KOPT_DO_MUTUAL option is set, space must be allocated for the cred structure and the cred structure will	be  filled  in	by
	       Otherwise, the cred structure will not be filled in by so the cred parameter should be set equivalent to the NULL pointer.

       schedule
	       a  key  schedule,  derived  from  the  session  key  between  the  local  and  foreign  principals,  that is output from and If the
	       KOPT_DO_MUTUAL option is set, the key schedule will be filled in; otherwise, the key schedule will not be  filled.   In	any  case,
	       space must be allocated for the key schedule.

       f_addr  the  address  of  the  socket  that  the foreign principal is using to communicate with the local principal.  If the KOPT_DO_MUTUAL
	       option is not set on a call to then the f_addr parameter should be set equivalent to the NULL pointer.  f_addr should never be  set
	       to NULL on a call to

       l_addr  the  address  of  the  socket  that  the local principal is using to communicate with the foreign principal.  If the KOPT_DO_MUTUAL
	       option is not set, the l_addr parameter should be set equivalent to the NULL pointer.

       ad      a pointer to the AUTH_DAT structure that describes the authentication association between the local and foreign principals.   Since
	       it is output from space for the ad structure must be allocated.

       srvtab_file
	       path  name  of  the file that contains the key of the principal obtaining a ticket.  If this value is set equal to a string of zero
	       length, the default service table file (srvtab) value is used.  If this value is set equal to the NULL pointer, then the key of the
	       service is not read from the srvtab file, but is read from storage space internal to the libraries.  The srvtab_file parameter can-
	       not be set to the NULL string on the first call to The default srvtab file value is set to although this value can be changed by  a
	       call to the function (see

       version_in
	       An  application-specific version string input to This argument allows the caller of to pass an application-specific version string,
	       within the message format, that the caller of can use to match against its own version string.  The version string  can	be  up	to
	       KRB_SENDAUTH_VLEN characters long and, in addition, it can be set equal to the NULL string.

       version_out
	       An  application-specific  version string output from This argument allows the caller of to receive the application-specific version
	       string included in the message that was sent by the foreign principal.  The version string can be up to	KRB_SENDAUTH_VLEN  charac-
	       ters long.

Description
       The routines are designed to be used by applications that communicate over a network, require the authentication of both parties across the
       communications path, and which support "on-the-wire" protocols that have no room for authentication information.  The routines are designed
       to  perform only the authentication of the first message sent between such applications.  Therefore, the routines should be used before any
       other communication occurs between the authenticating principals.

       After the communications channel between the applications has been established, but before any communication takes place,  and  before  the
       "on-the-wire"  protocol	of the application comes into effect, creates a message which can authenticate the caller of "A", to the caller of
       "B".  then sends the message to "B" where it is read from the communications channel by

       Next, attempts to authenticate "A" by producing a response to "A" which, depending upon the value of KOPT_DO_MUTUAL and the success of  the
       authentication  of  "A"	by  will  contain  either an error code, a code indicating success, or a mutual authentication message.  sends the
       response and returns to "B".  receives the message from "B", tries to authenticate "B" if KOPT_DO_MUTUAL is set, and then returns to "A".

       Since the authentication information is sent between the applications before the "on-the-wire"  protocol  of  the  application  comes  into
       effect,	the application must develop some method of distinguishing between the new authenticated initial message exchange and an old unau-
       thenticated initial message exchange.

       The routines make extensive use of the locally defined data types KTEXT, MSG_DAT, CREDENTIALS, and Key_schedule.  For specific  information
       on the definitions of these data types, see the des.h and krb.h files.

       The routines found in the library are and

       krb_sendauth

       The  function  is  designed  to	authenticate  a local principal, "A", to the principal specified by the f_service, f_instance, and f_realm
       parameters, "B", and to allow the authentication of "B" to "A" as well.	uses file descriptor fd, to send the authentication  message  that
       will authenticate "A" to principal "B".	It returns, in the tkt_authen parameter, the ticket-authenticator pair used to authenticate "A" to
       "B".  The version_in parameter contains an application-specific version string which is transmitted to "B" along  with  the  authentication
       message.

       If  mutual  authentication  is  selected as an option, the file descriptor, fd will be used to receive a mutual authentication message from
       "B".  To allow the mutual authentication to take place, l_addr and f_addr must be set equal to the address of the sockets which	the  local
       and  foreign principals use to communicate.  A value known only to "A" must be input to as the checksum parameter.  As the result of mutual
       authentication, cred will be filled with data describing the authentication information associated with "B", schedule will be set equal	to
       the  key_schedule of the session key between "A" and "B", and msg_data will be set equal to the mutual authentication message sent from "B"
       to "A".

       fd must be a file descriptor associated with a blocking socket.	Otherwise, will not function correctly.

       If "A" has been correctly authenticated to "B" and mutual authentication was not chosen as an option, or if "A" has been correctly  authen-
       ticated to "B", and "B" correctly authenticated to "A" and mutual authentication was chosen as an option, then KSUCCESS is returned by

       The  following  is a list of most of the error values from Since calls other section 3 Kerberos routines ( to perform its function, some of
       the error codes are references to the error codes of other functions:

       SENDAUTH_OPNOTSUP The options bits sent to contain a bit which is set, but does not correspond to an option.

       SENDAUTH_WR	 could not write the authentication message to "B" using fd.

       KFAILURE 	 The file cannot be opened, or
			 The file (see is not formed properly, or
			 An authentication message was sent from "A" to "B", but "B" could not successfully identify "A", or
			 A mutual authentication message was sent from "B" to "A", but "A" could not successfully identify "B".

       -1		 Negative one is returned if each byte of the session key does not have odd parity.

       -2		 Negative two is returned if the session key is a weak key as defined by (see

       NO_TKT_FIL	 The ticket file does not exist.

       TKT_FIL_ACC	 The ticket file cannot be opened or the ticket file cannot be accessed.

       TKT_FIL_LCK	 The ticket file could not be locked for access.

       TKT_FIL_FMT	 The ticket file format is incorrect.

       AD_NOTGT 	 There is no ticket-granting-ticket in the ticket file that can be used to ask for a ticket to communicate with  the  for-
			 eign principal.

       SKDC_CANT	 A Kerberos server must be contacted in order for to perform its function, but the attempt cannot be made because a socket
			 cannot be opened or bound, or there is no Kerberos server listed in

       SKDC_RETRY	 A Kerberos server needs to be contacted, but none responded even after several retries.

       INTK_PROT	 Kerberos protocol error.

       GC_NOTKT 	 Information concerning the foreign principal does not exist in the ticket file.

       RECVMUT_OPNOTSUP  The options bits sent to (see contain a bit which is set, but does not correspond to an option.

       RECVMUT_RD	 If the message cannot be read from the file descriptor fd, SENDMUT_RD is returned.

       RD_AP_VERSION	 If the Kerberos version used to create the mutual authentication message  is  not  supported  by  then  RD_AP_VERSION	is
			 returned.

       RD_AP_MSG_TYPE	 If the message read from the file descriptor, fd, is not a mutual authentication message, RD_AP_MSG_TYPE is returned.

       RD_AP_MODIFIED	 If  the  mutual  authentication  message has been modified between the "B" and "A" or it was in some way incorrectly pro-
			 duced, RD_AP_MODIFIED is returned.

       RD_AP_TIME	 Returned if the mutual authentication message is too old.

       krb_recvauth

       The function is designed to wait for a message from on the file descriptor fd, receive the message and attempt to authenticate the  foreign
       principal, "A", to the local principal determined by the l_service and l_instance parameters.  The srvtab_file must contain the private key
       of principal "B".  The tkt_authen_out parameter is filled with the ticket-authenticator pair sent within the message received by  "B"  from
       "A".   ad  is  filled  with  information that describes the authentication association between "A" and "B".  version_out is filled with the
       application version string included in the message.

       If mutual authentication is selected as an option, the file descriptor fd, will be used to send a mutual authentication message to "A".	To
       allow the mutual authentication to take place, l_addr and f_addr must be set equal to the address of the sockets that the local and foreign
       principals are using to communicate.  As the result of mutual authentication, schedule will be set equal to the key_schedule of the session
       key between "A" and "B".

       fd must be a file descriptor that is associated with a blocking socket.	Otherwise, will not function correctly.

       If  "A"	has  been  correctly authenticated to "B" and mutual authentication was not chosen as an option, or if mutual authentication is an
       option and "A" has been correctly authenticated to "B" and "B" has sent a mutual authentication message to "B", then KSUCCESS  is  returned
       by

       The  following  is  a  list of most of the error values from calls other section 3 Kerberos routines ( to perform its function, some of the
       error codes are references to the error codes of other functions.

       RECVAUTH_OPNOTSUP The options bits sent to contain a bit which is set but does not correspond to an option.

       RECVAUTH_RD	 could not read the authentication message sent to "B" using fd.

       RECVAUTH_TKTLEN	 The length of the ticket-authenticator pair within the message is longer than the maximum or less than or equal to 0.

       RD_AP_VERSION	 The versions of Kerberos used by the caller of is incompatible with the version.

       RD_AP_MSG_TYPE	 The ticket-authenticator pair given to was not really a ticket-authenticator pair.

       RD_AP_UNDEC	 The ticket could not be decyphered.  This error can be caused by a forged or modified message.

       RD_AP_INCON	 The message given to contains an internal inconsistency.  This could occur if the ticket in the ticket-authenticator pair
			 does not match the authenticator.

       RD_AP_BADD	 The ticket-authenticator pair cannot be used to authenticate a principal from the address specified by f_addr.

       RD_AP_TIME	 The authenticator in the ticket-authenticator pair is too old to be used to authenticate the foreign principal.

       RD_AP_NYV	 The  time at which the ticket of the ticket-authenticator pair was created is too far ahead of the time of the local host
			 of the local principal.

       RD_AP_EXP	 The ticket is too old to be used.

       -1		 Negative one is returned if the each byte of the session key does not have odd parity.

       -2		 Negative two is returned if the session key is a weak key as defined by

       SENDMUT_OPNOTSUP  The options bits sent to contains a bit which is set but does not correspond to an option.

       SENDMUT_MAKMSG	 If there is an error in forming the mutual authentication message itself, SENDMUT_MAKMSG is returned.

       SENDMUT_WR	 If the mutual authentication message cannot be written to the file descriptor fd, SENDMUT_WR is returned.

Restrictions
       and will not work properly on sockets set to nonblocking I/O mode.

See Also
       kerberos(3krb), krb_sendmutual(3krb), krb_svc_init(3krb), des_crypt(3krb, krb_get_lrealm(3krb), krb_set_tkt_string(3krb), krb.conf(5krb).

																krb_sendauth(3krb)