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)
 KTEXTtkt_authen_out;
 char*f_service;
 char*f_instance;
 char*f_realm;
 u_longchecksum;

 int krb_rd_req(tkt_authen_in, l_service, l_instance,
                         f_hostaddr, ad, srvtab_file)
 KTEXTtkt_authen_in;
 char*l_service;
 char*l_instance;
 u_longf_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;

 longkrb_mk_safe(in, out, in_length, key,
                               l_addr, f_addr)
 u_char*in;
 u_char*out;
 u_longin_length;
 C_Block*key;
 struct sockaddr_in*l_addr;
 structsockaddr_in*f_addr;

 longkrb_rd_safe(in, in_length, key, f_addr,
                               l_addr, msg_data)
 u_char*in;
 u_longin_length;
 C_Block*key;
 structsockaddr_in*f_addr;
 structsockaddr_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 principal.  The data in this structure must have been generated by a call to krb_mk_req by the foreign principal and transmitted by the foreign principal to the local principal.

checksum The checksum parameter is input to krb_mk_req. 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 authenticated as the foreign principal.  It is used to facilitate mutual authentication with krb_sendmutual and krb_recvmutual. See krb_sendmutual(3krb) for information about these two routines.

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 krb_rd_req. 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, srvtab_file[0]=’\0’, 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 parameter cannot be set equal to the NULL string on the first call to krb_rd_req. The default srvtab file value is set to /etc/srvtab, although this value can be changed by a call to the krb_set_srvtab_string function.  (See the krb_set_tkt_string(3krb) reference page).

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

cred A pointer to a credentials structure that is allocated by the caller of krb_get_cred and filled with data by krb_get_cred. 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 krb_mk_safe. 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 krb_rd_safe and which is filled by krb_rd_safe 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 krb_mk_req 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 krb_mk_req and krb_rd_req 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. krb_mk_req creates a ticket-authenticator pair that can be included in the "on-the-wire" protocol of an application, and krb_rd_req reads the ticket-authenticator pair.

The krb_mk_safe and krb_rd_safe 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 krb_mk_req/krb_rd_req pair or the krb_sendauth/krb_recvauth pair.  See krb_sendauth(3krb) for more information about the latter pair.

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

The des_quad_cksum routine (see des_crypt(3krb)) can be used to provide some of the guarantees of the krb_mk_safe and krb_rd_safe 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 des.h and krb.h 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.  krb_mk_req 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 krb_rd_req. 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 krb_sendmutual and krb_recvmutual to provide for the authentication of "B" to "A" after krb_rd_req 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 krb_mk_req is called. The following is a list of the return values from krb_mk_req and, if they are error codes, their possible cause:

KFAILURE /etc/krb.conf file (see krb.conf(5krb)) 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 krb_mk_req 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 /etc/krb.conf.

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 krb_mk_req 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, krb_rd_req 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 authentication fails. 

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

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

RD_AP_MSG_TYPE
The ticket-authenticator pair given to krb_rd_req 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 krb_rd_req 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 krb_get_cred 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 krb_mk_req 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 private session key (*key) to seed the checksum algorithm, des_quad_cksum, that it uses as part of the authentication process. (For more information about des_quad_cksum, see the des_crypt(3krb) reference page.)  The krb_mk_safe 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 krb_mk_safe 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 des_quad_cksum routine (see the des_crypt(3krb) reference page) as part of its authentication process. The routine fills in the following MSG_DAT fields:

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 krb_rd_safe 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 following is a list of the error values returned by krb_rd_req and their possible causes:

-1 A system call used by krb_rd_safe returned an error.

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

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

RD_AP_MODIFIED
The address of the machine from which in was sent does not match the address of the machine on which the krb_mk_safe 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 krb_mk_req.

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

Restrictions

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

Files

/usr/include/krb.h

/usr/lib/libkrb.a

/usr/include/des.h

/usr/lib/libdes.a

/etc/srvtab

See Also

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