krb_recvauth man page on Ultrix

Man page or keyword search:  
man Server   3690 pages
apropos Keyword Search (all sections)
Output format
Ultrix logo
[printable version]

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	 argu‐
			ment 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	 caller	 of but the caller of is not authenti‐
			cated 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_ser‐
	       vice should be set equal to the NULL pointer.

       f_instance
	       Character pointer to the instance name of the  foreign  princi‐
	       pal.   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 princi‐
	       pal 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 for‐
	       eign principal to authenticate the local	 principal's  identity
	       to  the	foreign 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   facilitate	mutual	 authentication,   so  if  the
	       KOPT_DO_MUTUAL is not set, the value of this argument is incon‐
	       sequential.   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 creation of the ticket-authenticator pair,
	       authen_tkt.

       msg_data
	       Pointer to a structure which is filled with the mutual  authen‐
	       tication	 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.	Other‐
	       wise, since no message will be sent from to the msg_data param‐
	       eter 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	 prin‐
	       cipal  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 equiva‐
	       lent to the NULL pointer.

       ad      a pointer to the AUTH_DAT structure that describes the  authen‐
	       tication	 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  cannot 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 addi‐
	       tion, it can be set equal to the NULL string.

       version_out
	       An application-specific version string output from  This	 argu‐
	       ment  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 characters 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 unauthenticated
       initial message exchange.

       The routines make extensive use	of  the	 locally  defined  data	 types
       KTEXT,  MSG_DAT,	 CREDENTIALS, and Key_schedule.	 For specific informa‐
       tion 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  parame‐
       ters, "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  mes‐
       sage.

       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 authen‐
       tication,  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.	Other‐
       wise, will not function correctly.

       If  "A"	has been correctly authenticated to "B" and mutual authentica‐
       tion 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 foreign 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 descrip‐
			 tor 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	 modi‐
			 fied  between	the  "B" and "A" or it was in some way
			 incorrectly produced, 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 for‐
       eign 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 appli‐
       cation 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 authenti‐
       cation, 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  authentica‐
       tion  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  inconsis‐
			 tency.	 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 prin‐
			 cipal.

       RD_AP_NYV	 The time at which the ticket of the  ticket-authenti‐
			 cator	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 ses‐
			 sion 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 authenti‐
			 cation message itself, SENDMUT_MAKMSG is returned.

       SENDMUT_WR	 If the mutual authentication message cannot be	 writ‐
			 ten   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)
[top]

List of man pages available for Ultrix

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net