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 Alsokerberos(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)