Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
KERBEROS(3)		   Library Functions Manual		   KERBEROS(3)

NAME
       krb_mk_req,    krb_rd_req,   krb_kntoln,	  krb_set_key,	 krb_get_cred,
       krb_mk_priv,   krb_rd_priv,   krb_mk_safe,   krb_rd_safe,   krb_mk_err,
       krb_rd_err, krb_ck_repl - Kerberos authentication library

SYNOPSIS
       #include	<openssl/des.h>
       #include	<krb.h>

       extern char *krb_err_txt[];

       int krb_mk_req(authent,service,instance,realm,checksum)
       KTEXT authent;
       char *service;
       char *instance;
       char *realm;
       u_long checksum;

       int krb_rd_req(authent,service,instance,from_addr,ad,fn)
       KTEXT authent;
       char *service;
       char *instance;
       u_long from_addr;
       AUTH_DAT	*ad;
       char *fn;

       int krb_kntoln(ad,lname)
       AUTH_DAT	*ad;
       char *lname;

       int krb_set_key(key,cvt)
       char *key;
       int cvt;

       int krb_get_cred(service,instance,realm,c)
       char *service;
       char *instance;
       char *realm;
       CREDENTIALS *c;

       long krb_mk_priv(in,out,in_length,schedule,key,sender,receiver)
       u_char *in;
       u_char *out;
       u_long in_length;
       des_cblock key;
       des_key_schedule	schedule;
       struct sockaddr_in *sender;
       struct sockaddr_in *receiver;

       long krb_rd_priv(in,in_length,schedule,key,sender,receiver,msg_data)
       u_char *in;
       u_long in_length;
       Key_schedule schedule;
       des_cblock key;
       struct sockaddr_in *sender;
       struct sockaddr_in *receiver;
       MSG_DAT *msg_data;

       long krb_mk_safe(in,out,in_length,key,sender,receiver)
       u_char *in;
       u_char *out;
       u_long in_length;
       des_cblock key;
       struct sockaddr_in *sender;
       struct sockaddr_in *receiver;

       long krb_rd_safe(in,length,key,sender,receiver,msg_data)
       u_char *in;
       u_long length;
       des_cblock key;
       struct sockaddr_in *sender;
       struct sockaddr_in *receiver;
       MSG_DAT *msg_data;

       long krb_mk_err(out,code,string)
       u_char *out;
       long code;
       char *string;

       long krb_rd_err(in,length,code,msg_data)
       u_char *in;
       u_long length;
       long code;
       MSG_DAT *msg_data;

DESCRIPTION
       This library supports network authentication and	various	related	opera-
       tions.  The library contains many routines beyond  those	 described  in
       this man	page, but they are not intended	to be used directly.  Instead,
       they are	called by the routines that are	described, the	authentication
       server and the login program.

       krb_err_txt[] contains text string descriptions of various Kerberos er-
       ror codes returned by some of the routines below.

       krb_mk_req takes	a pointer to a text structure in which an  authentica-
       tor is to be built.  It also takes the name, instance, and realm	of the
       service to be used and an optional checksum.  It	is up to the  applica-
       tion to decide how to generate the checksum.  krb_mk_req	then retrieves
       a ticket	for the	desired	service	and creates an authenticator.  The au-
       thenticator is built in authent and is accessible to the	calling	proce-
       dure.

       It is up	to the application to get the  authenticator  to  the  service
       where  it  will be read by krb_rd_req.  Unless an attacker posesses the
       session key contained in	the ticket, it will be unable  to  modify  the
       authenticator.  Thus, the checksum can be used to verify	the authentic-
       ity of the other	data that will pass through a connection.

       krb_rd_req takes	an authenticator of type KTEXT,	a service name,	an in-
       stance,	the address of the host	originating the	request, and a pointer
       to a structure of type AUTH_DAT which is	filled in with information ob-
       tained  from  the  authenticator.  It also optionally takes the name of
       the file	in which it will find the secret key(s)	for the	 service.   If
       the supplied instance contains "*", then	the first service key with the
       same service name found in the service key file will be used,  and  the
       instance	 argument  will	 be  filled in with the	chosen instance.  This
       means that the caller must provide space	for such an instance name.

       It is used to find out information about	the principal when  a  request
       has  been  made	to a service.  It is up	to the application protocol to
       get the authenticator from the client to	the service.  The  authentica-
       tor is then passed to krb_rd_req	to extract the desired information.

       krb_rd_req  returns zero	(RD_AP_OK) upon	successful authentication.  If
       a packet	was forged, modified, or replayed, authentication  will	 fail.
       If  the	authentication	fails, a non-zero value	is returned indicating
       the particular problem encountered.  See	krb.h for the  list  of	 error
       codes.

       If  the	last argument is the null string (""), krb_rd_req will use the
       file /etc/srvtab	to find	its keys.  If the last argument	 is  NULL,  it
       will  assume  that  the	key  has  been set by krb_set_key and will not
       bother looking further.

       krb_kntoln converts a Kerberos name to a	local name.  It	takes a	struc-
       ture  of	 type  AUTH_DAT	 and uses the name and instance	to look	in the
       database	/etc/aname to find the corresponding local  name.   The	 local
       name  is	returned and can be used by an application to change uids, di-
       rectories, or other parameters.	It is not an  integral	part  of  Ker-
       beros, but is instead provided to support the use of Kerberos in	exist-
       ing utilities.

       krb_set_key takes as an argument	a des key.   It	 then  creates	a  key
       schedule	 from  it and saves the	original key to	be used	as an initial-
       ization vector.	It is used to set the server's key which must be  used
       to decrypt tickets.

       If  called with a non-zero second argument, krb_set_key will first con-
       vert the	input from a string of arbitrary length	to a DES  key  by  en-
       crypting	it with	a one-way function.

       In most cases it	should not be necessary	to call	krb_set_key.  The nec-
       essary keys  will  usually  be  obtained	 and  set  inside  krb_rd_req.
       krb_set_key  is	provided  for  those  applications that	do not wish to
       place the application keys on disk.

       krb_get_cred searches the caller's ticket file for  a  ticket  for  the
       given service, instance,	and realm; and,	if a ticket is found, fills in
       the given CREDENTIALS structure with the	ticket information.

       If the ticket was found,	krb_get_cred returns  GC_OK.   If  the	ticket
       file  can't  be found, can't be read, doesn't belong to the user	(other
       than root), isn't a regular file, or is in the wrong  mode,  the	 error
       GC_TKFIL	is returned.

       krb_mk_priv  creates an encrypted, authenticated	message	from any arbi-
       trary application data, pointed to by in	and in_length bytes long.  The
       private	session	key, pointed to	by key and the key schedule, schedule,
       are used	to encrypt the data and	some header information	using pcbc_en-
       crypt.	sender	and  receiver point to the Internet address of the two
       parties.	 In addition to	providing privacy, this	protocol message  pro-
       tects  against  modifications, insertions or replays.  The encapsulated
       message and header are placed in	the area pointed to  by	 out  and  the
       routine returns the length of the output, or -1 indicating an error.

       krb_rd_priv  decrypts and authenticates a received krb_mk_priv message.
       in points to the	beginning of the received  message,  whose  length  is
       specified  in  in_length.   The private session key, pointed to by key,
       and the key schedule, schedule, are used	to decrypt and verify the  re-
       ceived  message.	 msg_data is a pointer to a MSG_DAT struct, defined in
       krb.h.  The routine fills in the	app_data field with a pointer  to  the
       decrypted  application data, app_length with the	length of the app_data
       field, time_sec and time_5ms with the timestamps	in  the	 message,  and
       swap  with a 1 if the byte order	of the receiver	is different than that
       of the sender.  (The application	must still determine if	it  is	appro-
       priate  to byte-swap application	data; the Kerberos protocol fields are
       already taken care of).	The hash field returns a value useful as input
       to the krb_ck_repl routine.

       The routine returns zero	if ok, or a Kerberos error code. Modified mes-
       sages and old messages cause errors, but	it is  up  to  the  caller  to
       check  the time sequence	of messages, and to check against recently re-
       played messages using krb_ck_repl if so desired.

       krb_mk_safe creates an authenticated, but unencrypted message from  any
       arbitrary  application data, pointed to by in and in_length bytes long.
       The private session key,	pointed	 to  by	 key,  is  used	 to  seed  the
       quad_cksum()  checksum  algorithm  used	as part	of the authentication.
       sender and receiver point to the	Internet address of the	 two  parties.
       This message does not provide privacy, but does protect (via detection)
       against modifications, insertions or replays.  The encapsulated message
       and header are placed in	the area pointed to by out and the routine re-
       turns the length	of the output, or -1 indicating	an error.  The authen-
       tication	 provided by this routine is not as strong as that provided by
       krb_mk_priv or by computing the checksum	using cbc_cksum	instead,  both
       of which	authenticate via DES.

       krb_rd_safe authenticates a received krb_mk_safe	message.  in points to
       the beginning of	the received message, whose  length  is	 specified  in
       in_length.  The private session key, pointed to by key, is used to seed
       the quad_cksum()	routine	as part	of the authentication.	msg_data is  a
       pointer	to  a MSG_DAT struct, defined in krb.h .  The routine fills in
       these MSG_DAT fields: the app_data field	with a pointer to the applica-
       tion  data,  app_length with the	length of the app_data field, time_sec
       and time_5ms with the timestamps	in the message,	and swap with a	 1  if
       the  byte  order	 of the	receiver is different than that	of the sender.
       (The application	must still determine if	it is appropriate to byte-swap
       application  data;  the Kerberos	protocol fields	are already taken care
       of).  The hash field returns a value useful as input to the krb_ck_repl
       routine.

       The routine returns zero	if ok, or a Kerberos error code. Modified mes-
       sages and old messages cause errors, but	it is  up  to  the  caller  to
       check  the time sequence	of messages, and to check against recently re-
       played messages using krb_ck_repl if so desired.

       krb_mk_err constructs an	application level error	message	 that  may  be
       used  along  with  krb_mk_priv or krb_mk_safe.  out is a	pointer	to the
       output buffer, code is an application specific error code,  and	string
       is an application specific error	string.

       krb_rd_err unpacks a received krb_mk_err	message.  in points to the be-
       ginning	of  the	 received  message,  whose  length  is	specified   in
       in_length.  code	is a pointer to	a value	to be filled in	with the error
       value provided by the application.  msg_data is a pointer to a  MSG_DAT
       struct,	defined	in krb.h .  The	routine	fills in these MSG_DAT fields:
       the app_data field with	a  pointer  to	the  application  error	 text,
       app_length  with	the length of the app_data field, and swap with	a 1 if
       the byte	order of the receiver is different than	that  of  the  sender.
       (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 zero	if the error message has been successfully re-
       ceived, or a Kerberos error code.

       The KTEXT structure is used to pass around text of varying lengths.  It
       consists	 of  a buffer for the data, and	a length.  krb_rd_req takes an
       argument	of this	type containing	the authenticator, and krb_mk_req  re-
       turns  the  authenticator in a structure	of this	type.  KTEXT itself is
       really a	pointer	to the structure.   The	actual structure  is  of  type
       KTEXT_ST.

       The  AUTH_DAT  structure	 is filled in by krb_rd_req.  It must be allo-
       cated before calling krb_rd_req,	and a pointer to it  is	 passed.   The
       structure  is  filled  in  with	data  obtained from Kerberos.  MSG_DAT
       structure  is  filled  in  by  either  krb_rd_priv,   krb_rd_safe,   or
       krb_rd_err.   It	 must be allocated before the call and a pointer to it
       is passed.  The structure is filled in with  data  obtained  from  Ker-
       beros.

FILES
       /usr/include/krb.h
       /usr/lib/libkrb.a
       /usr/include/des.h
       /usr/lib/libdes.a
       /etc/aname
       /etc/srvtab
       /tmp/tkt[uid]

SEE ALSO
       kerberos(1), des_crypt(3)

DIAGNOSTICS
BUGS
       The  caller of krb_rd_req, krb_rd_priv, and krb_rd_safe must check time
       order and for replay attempts.  krb_ck_repl is not implemented yet.

AUTHORS
       Clifford	Neuman,	MIT Project Athena
       Steve Miller, MIT Project Athena/Digital	Equipment Corporation

RESTRICTIONS
       COPYRIGHT 1985,1986,1989	Massachusetts Institute	of Technology

MIT Project Athena	     Kerberos Version 4.0		   KERBEROS(3)

NAME | SYNOPSIS | DESCRIPTION | FILES | SEE ALSO | DIAGNOSTICS | BUGS | AUTHORS | RESTRICTIONS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=kerberos&sektion=3&manpath=FreeBSD+4.11-RELEASE>

home | help