ultrix man page for kerberos

kerberos(3krb)															    kerberos(3krb)

Name
       kerberos - Kerberos authentication library routines

Syntax
	#include <des.h>
	#include <krb.h>

	int krb_mk_req(tkt_authen_out, f_service, f_instance,
				f_realm, checksum)
	KTEXT	 tkt_authen_out;
	char	      *f_service;
	char	      *f_instance;
	char	      *f_realm;
	u_long	      checksum;

	int krb_rd_req(tkt_authen_in, l_service, l_instance,
				f_hostaddr, ad, srvtab_file)
	KTEXT	 tkt_authen_in;
	char	      *l_service;
	char	      *l_instance;
	u_long	      f_hostaddr;
	AUTH_DAT *ad;
	char	      *srvtab_file;

	int krb_get_cred(f_service, f_instance,
				 f_realm, cred)
	char	      *f_service;
	char	      *f_instance;
	char	      *f_realm;
	CREDENTIALS   *cred;

	long	 krb_mk_safe(in, out, in_length, key,
				      l_addr, f_addr)
	u_char	      *in;
	u_char	      *out;
	u_long		   in_length;
	C_Block       *key;
	struct	 sockaddr_in	*l_addr;
	struct	 sockaddr_in	*f_addr;

	long	 krb_rd_safe(in, in_length, key, f_addr,
				      l_addr, msg_data)
	u_char	      *in;
	u_long		   in_length;
	C_Block       *key;
	struct	 sockaddr_in	*f_addr;
	struct	 sockaddr_in	*l_addr;
	MSG_DAT       *msg_data;

Arguments
       f_service Character  pointer  to  the  primary name of the foreign principal.  The local principal is the principal that calls the routines
		 listed above.	The local principal tries to communicate with the foreign principal.

       f_instance
		 Character pointer to the instance name of the foreign principal.

       f_realm	 Character pointer to the realm name of the foreign principal.

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

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

       tkt_authen_out
		 Pointer to the text structure in which the Kerberos library routines build the  ticket-authenticator  pair.   This  structure	is
		 designed  to  be  sent to the foreign principal to authenticate the local principal's identity to the foreign principal.  Storage
		 must be allocated for tkt_authen_out.

       tkt_authen_in
		 Pointer to the ticket-authenticator pair that the Kerberos library uses to authenticate the foreign principal to the local  prin-
		 cipal.   The data in this structure must have been generated by a call to by the foreign principal and transmitted by the foreign
		 principal to the local principal.

       checksum  The checksum parameter is input to It is packaged with the ticket-authenticator pair that is sent to the foreign principal.   The
		 checksum  serves  as a secret piece of data that can be known only to the foreign principal if the foreign principal is authenti-
		 cated as the foreign principal.  It is used to facilitate mutual authentication with and See for information about these two rou-
		 tines.

       f_hostaddr
		 Address of the machine from which the foreign principal sent the tkt_authen_in data.

       f_addr	 Address of the socket that the foreign principal is using to communicate with the local principal.

       l_addr	 Address of the socket that the local principal is using to communicate with the foreign principal.

       ad	 Pointer to the AUTH_DAT structure that describes the authentication association between the local and foreign principals.  The ad
		 structure is output from You must allocate space for the ad structure.

       srvtab_file
		 The 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 (srvtab) file 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  parame-
		 ter  cannot  be set equal 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 the reference page).

       key	 Pointer to the C_Block input to and It contains a Data Encryption Standard (DES) key.	The key that is usually used is  the  ses-
		 sion key between the local and foreign principal.

       cred	 A  pointer  to  a  credentials  structure  that  is  allocated by the caller of and filled with data by The credentials structure
		 includes the ticket that the local principal uses to authenticate the foreign principal.  It also includes  other  authentication
		 information associated with the foreign principal.

       in	 Character pointer to the user data that must be included in a safe message.

       out	 Character pointer to the safe message output by The in parameter may not overlap with out.

       in_length Length of the user data, in.

       msg_data  The  msg_data	parameter is a pointer to a MSG_DAT structure which must be allocated by the caller of and which is filled by with
		 information about the safe message.  A pointer to the user data sent within the safe message is also included in msg_data.

Description
       The calls are designed to be used by two principals that are attempting to authenticate themselves for the first time as  well  as  by  two
       principals that have authenticated once, but wish to authenticate all data passed between them.

       The and routines are designed to be used by applications that communicate over a network, require the authentication of both parties across
       the communication path, and support "on-the-wire" protocols in which authentication data can be placed.	These routines	perform  only  the
       authentication  of  the first message sent between such applications.  creates a ticket-authenticator pair that can be included in the "on-
       the-wire" protocol of an application, and reads the ticket-authenticator pair.

       The and routines are used by applications that require that every message passed between them be authenticated and free	from  unauthorized
       modifications,  and  whose  "on-the-wire" protocol has no room for authentication data.	These routines only provide for the authentication
       and integrity protection of a message if the first authenticated message has already been sent by the pair  or  the  pair.   See  for  more
       information about the latter pair.

       The routine encapsulates user data inside the "on-the-wire" message authentication protocol.  can interpret the message authentication pro-
       tocol and the message, and return the data encapsulated by Since any application which is modified to use or must encapsulate its  "on-the-
       wire"  protocol	within	the "on-the-wire" protocol of the application must develop a method of distinguishing between the old and new "on-
       the-wire" protocols.

       The routine (see can be used to provide some of the guarantees of the and routines without encapsulating the protocol of the application.

       The routines of this library make extensive use of the following locally defined data types: KTEXT,  AUTH_DAT,  CREDENTIALS,  C_Block,  and
       MSG_DAT.  For specific information on the definitions of these data types, see the and files.

Routines and Structures
       krb_mk_req

       Used  to produce the data necessary to authenticate a principal "A" to a principal "B".	It takes as input a checksum and the primary name,
       instance name, and realm name of the service to which the principal "A" is attempting to authenticate itself.  outputs a text structure	in
       which the ticket to communicate with principal "B" and an authenticator have been combined to form a ticket-authenticator pair.

       The application "A" must pass the ticket-authenticator pair to the principal "B" where it can be read by Once the ticket-authenticator pair
       has been read and verified, "A" has been authenticated to "B".  Unless an attacker possesses the session key contained in the  ticket,  the
       attacker will be unable to modify or replay the ticket-authenticator pair.

       The  checksum  can  be used with and to provide for the authentication of "B" to "A" after authenticates "A" to "B".  Although the checksum
       value can be any value known only to "A", it is recommended that the checksum value used differ every time is called.  The following  is  a
       list of the return values from and, if they are error codes, their possible cause:

       KFAILURE       file (see cannot be opened, or it is not properly formed.

       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 so that can perform its function, but the attempt cannot be made because a socket cannot
		      be opened or bound, or because there is no Kerberos server listed in

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

       INTK_PROT      Kerberos protocol error.

       KSUCCESS       All went well.

       krb_rd_req

       This  routine  is  used to read the authentication data produced by principal "A" with and sent by "A" to principal "B".  It takes as input
       the primary name and instance name of the local principal "B", as well as the authentication data sent to "B", the address of  the  machine
       from  which  "A"  sent  the  ticket-authenticator  pair,  and the name of the file in which to find the key of the local principal.  If the
       authentication attempt is successful, will fill the ad structure with data about the authenticated association between "A" and "B".

       The krb_rd_req routine returns zero (RD_AP_OK) upon successful authentication.  If a packet was forged, modified, or replayed, then authen-
       tication fails.

       The following is a list of the error values returned from and their possible causes:

       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 actually a ticket-authenticator pair.

       RD_AP_UNDEC     The ticket was indecipherable.  This error can be caused by a forged or a 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 from the address, f_hostaddr.

       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.

       krb_get_cred

       Searches  the caller's ticket file for the authentication information associated with the principal specified by the f_service, f_instance,
       and f_realm.  If finds information in the ticket file, it fills a credentials structure with the information and returns the status, GC_OK.

       The following is a list of the error values returned from and their possible causes:

       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.

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

       krb_mk_safe

       Creates an authenticated but unencrypted message from text pointed to by in, of a length indicated by in_length. The routine uses the  pri-
       vate  session  key  (*key)  to  seed  the checksum algorithm, des_quad_cksum, that it uses as part of the authentication process. (For more
       information about see the reference page.)  The routine also uses the arguments l_addr and f_addr for authentication purposes.

       A safe message does not provide privacy, but does provide protection against modifications in addition to  providing  authentication.   The
       encapsulated  message  and  header  produced by krb_mk_safe are placed in the area pointed to by out. The routine returns the length of the
       output or a negative one (-1), indicating an error.

       krb_rd_safe

       Authenticates a received message and writes the appropriate fields in the message data structure MSG_DAT. The argument  in  points  to  the
       beginning  of  the  received  message. The argument in_length specifies the length of the message. The krb_rd_safe routine uses the private
       session key (*key) to seed the routine (see the reference page) as part of its authentication process. The routine fills in  the  following
       MSG_DAT fields:

       MSG_DAT Field			  Description
       app_data        Pointer to the application data
       app_length      Length of the app_data
       time_sec        Timestamp of the message in seconds
       time_5ms        Timestamp of the message in 5-millisecond units
       swap	       A  1 if the byte order of the receiver is differ-
		       ent from that of the sender

       Note that the application must still determine if it is appropriate to byte-swap application data; the Kerberos protocol fields are already
       taken care of.

       The  routine  returns  RD_AP_OK if the message, in, is authenticated and has not been modified when it was sent between the foreign and the
       local principal.  It is up to the caller to check the time sequence of messages and to check against recently replayed messages.  The  fol-
       lowing is a list of the error values returned by and their possible causes:

       -1	       A system call used by returned an error.

       RD_AP_VERSION   The Kerberos version of the code that generated message, in, is not supported by the version used.

       RD_AP_MSG_TYPE  The message, in, is not really a message produced by

       RD_AP_MODIFIED  The  address  of the machine from which in was sent does not match the address of the machine on which the message, in, was
		       generated, or
		       The message was modified when it was sent from the foreign to the local principal, or
		       The message, in, is too small to be the message produced by

       RD_AP_TIME      The difference between the time at which the message, in, was produced by and the time at which	it  was  read  by  is  too
		       large.  The time difference must be within five minutes.

Restrictions
       The caller of the functions, and must check the time order of messages and protect against replay attempts.

Files
       See Also
	      des_crypt(3krb), krb_sendmutual(3krb), krb_sendauth(3krb), krb_svc_init(3krb), krb_set_tkt_string(3krb), krb.conf(5krb)

																    kerberos(3krb)