kerberos(3krb)kerberos(3krb)Namekerberos - 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 princi‐
pal. The local principal is the principal that calls the
routines listed above. The local principal tries to communi‐
cate with the foreign principal.
f_instance
Character pointer to the instance name of the foreign princi‐
pal.
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 princi‐
pal.
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 authenti‐
cate 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 by the foreign principal and transmit‐
ted 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 princi‐
pal. The checksum serves as a secret piece of data that can
be known only to the foreign principal if the foreign princi‐
pal is authenticated as the foreign principal. It is used to
facilitate mutual authentication with and See 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 authen‐
tication association between the local and foreign princi‐
pals. 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 prin‐
cipal 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 parameter 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 session 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 authen‐
ticate the foreign principal. It also includes other authen‐
tication 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 param‐
eter 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 princi‐
pals that have authenticated once, but wish to authenticate all data
passed between them.
The and routines are designed to be used by applications that communi‐
cate 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-authentica‐
tor pair.
The and routines are used by applications that require that every mes‐
sage passed between them be authenticated and free from unauthorized
modifications, and whose "on-the-wire" protocol has no room for authen‐
tication 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 informa‐
tion 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-authentica‐
tor 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 can‐
not 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 prin‐
cipal "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 authen‐
tication. 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 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 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 princi‐
pal.
RD_AP_NYV The time at which the ticket of the ticket-authentica‐
tor 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 cre‐
dentials 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 can‐
not 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 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 out‐
put 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 dif‐
ferent 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 follow‐
ing 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 mes‐
sage, 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 mes‐
sage, in, was generated, or
The message was modified when it was sent from the for‐
eign to the local principal, or
The message, in, is too small to be the message pro‐
duced 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_sendmu‐
tual(3krb), krb_sendauth(3krb),
krb_svc_init(3krb),
krb_set_tkt_string(3krb),
krb.conf(5krb)kerberos(3krb)
