348 lines
7.3 KiB
Groff
348 lines
7.3 KiB
Groff
.\" $Id: krb_sendauth.3,v 1.1.1.1 2000/06/16 18:45:35 thorpej Exp $
|
|
.\" Copyright 1988 by the Massachusetts Institute of Technology.
|
|
.\"
|
|
.\" For copying and distribution information,
|
|
.\" please see the file <mit-copyright.h>.
|
|
.\"
|
|
.TH KRB_SENDAUTH 3 "Kerberos Version 4.0" "MIT Project Athena"
|
|
.SH NAME
|
|
krb_sendauth, krb_recvauth, krb_net_write, krb_net_read \-
|
|
Kerberos routines for sending authentication via network stream sockets
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.nj
|
|
.ft B
|
|
#include <krb.h>
|
|
#include <des.h>
|
|
#include <netinet/in.h>
|
|
.PP
|
|
.fi
|
|
.HP 1i
|
|
.ft B
|
|
int krb_sendauth(options, fd, ktext, service, inst, realm, checksum,
|
|
msg_data, cred, schedule, laddr, faddr, version)
|
|
.nf
|
|
.RS 0
|
|
.ft B
|
|
long options;
|
|
int fd;
|
|
KTEXT ktext;
|
|
char *service, *inst, *realm;
|
|
u_long checksum;
|
|
MSG_DAT *msg_data;
|
|
CREDENTIALS *cred;
|
|
Key_schedule schedule;
|
|
struct sockaddr_in *laddr, *faddr;
|
|
char *version;
|
|
.PP
|
|
.fi
|
|
.HP 1i
|
|
.ft B
|
|
int krb_recvauth(options, fd, ktext, service, inst, faddr, laddr,
|
|
auth_data, filename, schedule, version)
|
|
.nf
|
|
.RS 0
|
|
.ft B
|
|
long options;
|
|
int fd;
|
|
KTEXT ktext;
|
|
char *service, *inst;
|
|
struct sockaddr_in *faddr, *laddr;
|
|
AUTH_DAT *auth_data;
|
|
char *filename;
|
|
Key_schedule schedule;
|
|
char *version;
|
|
.PP
|
|
.ft B
|
|
int krb_net_write(fd, buf, len)
|
|
int fd;
|
|
char *buf;
|
|
int len;
|
|
.PP
|
|
.ft B
|
|
int krb_net_read(fd, buf, len)
|
|
int fd;
|
|
char *buf;
|
|
int len;
|
|
.fi
|
|
.SH DESCRIPTION
|
|
.PP
|
|
These functions,
|
|
which are built on top of the core Kerberos library,
|
|
provide a convenient means for client and server
|
|
programs to send authentication messages
|
|
to one another through network connections.
|
|
The
|
|
.I krb_sendauth
|
|
function sends an authenticated ticket from the client program to
|
|
the server program by writing the ticket to a network socket.
|
|
The
|
|
.I krb_recvauth
|
|
function receives the ticket from the client by
|
|
reading from a network socket.
|
|
|
|
.SH KRB_SENDAUTH
|
|
.PP
|
|
This function writes the ticket to
|
|
the network socket specified by the
|
|
file descriptor
|
|
.IR fd,
|
|
returning KSUCCESS if the write proceeds successfully,
|
|
and an error code if it does not.
|
|
|
|
The
|
|
.I ktext
|
|
argument should point to an allocated KTEXT_ST structure.
|
|
The
|
|
.IR service,
|
|
.IR inst,
|
|
and
|
|
.IR realm
|
|
arguments specify the server program's Kerberos principal name,
|
|
instance, and realm.
|
|
If you are writing a client that uses the local realm exclusively,
|
|
you can set the
|
|
.I realm
|
|
argument to NULL.
|
|
|
|
The
|
|
.I version
|
|
argument allows the client program to pass an application-specific
|
|
version string that the server program can then match against
|
|
its own version string.
|
|
The
|
|
.I version
|
|
string can be up to KSEND_VNO_LEN (see
|
|
.IR <krb.h> )
|
|
characters in length.
|
|
|
|
The
|
|
.I checksum
|
|
argument can be used to pass checksum information to the
|
|
server program.
|
|
The client program is responsible for specifying this information.
|
|
This checksum information is difficult to corrupt because
|
|
.I krb_sendauth
|
|
passes it over the network in encrypted form.
|
|
The
|
|
.I checksum
|
|
argument is passed as the checksum argument to
|
|
.IR krb_mk_req .
|
|
|
|
You can set
|
|
.IR krb_sendauth's
|
|
other arguments to NULL unless you want the
|
|
client and server programs to mutually authenticate
|
|
themselves.
|
|
In the case of mutual authentication,
|
|
the client authenticates itself to the server program,
|
|
and demands that the server in turn authenticate itself to
|
|
the client.
|
|
|
|
.SH KRB_SENDAUTH AND MUTUAL AUTHENTICATION
|
|
.PP
|
|
If you want mutual authentication,
|
|
make sure that you read all pending data from the local socket
|
|
before calling
|
|
.IR krb_sendauth.
|
|
Set
|
|
.IR krb_sendauth's
|
|
.I options
|
|
argument to
|
|
.BR KOPT_DO_MUTUAL
|
|
(this macro is defined in the
|
|
.IR krb.h
|
|
file);
|
|
make sure that the
|
|
.I laddr
|
|
argument points to
|
|
the address of the local socket,
|
|
and that
|
|
.I faddr
|
|
points to the foreign socket's network address.
|
|
|
|
.I Krb_sendauth
|
|
fills in the other arguments--
|
|
.IR msg_data ,
|
|
.IR cred ,
|
|
and
|
|
.IR schedule --before
|
|
sending the ticket to the server program.
|
|
You must, however, allocate space for these arguments
|
|
before calling the function.
|
|
|
|
.I Krb_sendauth
|
|
supports two other options:
|
|
.BR KOPT_DONT_MK_REQ,
|
|
and
|
|
.BR KOPT_DONT_CANON.
|
|
If called with
|
|
.I options
|
|
set as KOPT_DONT_MK_REQ,
|
|
.I krb_sendauth
|
|
will not use the
|
|
.I krb_mk_req
|
|
function to retrieve the ticket from the Kerberos server.
|
|
The
|
|
.I ktext
|
|
argument must point to an existing ticket and authenticator (such as
|
|
would be created by
|
|
.IR krb_mk_req ),
|
|
and the
|
|
.IR service,
|
|
.IR inst,
|
|
and
|
|
.IR realm
|
|
arguments can be set to NULL.
|
|
|
|
If called with
|
|
.I options
|
|
set as KOPT_DONT_CANON,
|
|
.I krb_sendauth
|
|
will not convert the service's instance to canonical form using
|
|
.IR krb_get_phost (3).
|
|
|
|
If you want to call
|
|
.I krb_sendauth
|
|
with a multiple
|
|
.I options
|
|
specification,
|
|
construct
|
|
.I options
|
|
as a bitwise-OR of the options you want to specify.
|
|
|
|
.SH KRB_RECVAUTH
|
|
.PP
|
|
The
|
|
.I krb_recvauth
|
|
function
|
|
reads a ticket/authenticator pair from the socket pointed to by the
|
|
.I fd
|
|
argument.
|
|
Set the
|
|
.I options
|
|
argument
|
|
as a bitwise-OR of the options desired.
|
|
Currently only KOPT_DO_MUTUAL is useful to the receiver.
|
|
|
|
The
|
|
.I ktext
|
|
argument
|
|
should point to an allocated KTEXT_ST structure.
|
|
.I Krb_recvauth
|
|
fills
|
|
.I ktext
|
|
with the
|
|
ticket/authenticator pair read from
|
|
.IR fd ,
|
|
then passes it to
|
|
.IR krb_rd_req .
|
|
|
|
The
|
|
.I service
|
|
and
|
|
.I inst
|
|
arguments
|
|
specify the expected service and instance for which the ticket was
|
|
generated. They are also passed to
|
|
.IR krb_rd_req.
|
|
The
|
|
.I inst
|
|
argument may be set to "*" if the caller wishes
|
|
.I krb_mk_req
|
|
to fill in the instance used (note that there must be space in the
|
|
.I inst
|
|
argument to hold a full instance name, see
|
|
.IR krb_mk_req (3)).
|
|
|
|
The
|
|
.I faddr
|
|
argument
|
|
should point to the address of the peer which is presenting the ticket.
|
|
It is also passed to
|
|
.IR krb_rd_req .
|
|
|
|
If the client and server plan to mutually authenticate
|
|
one another,
|
|
the
|
|
.I laddr
|
|
argument
|
|
should point to the local address of the file descriptor.
|
|
Otherwise you can set this argument to NULL.
|
|
|
|
The
|
|
.I auth_data
|
|
argument
|
|
should point to an allocated AUTH_DAT area.
|
|
It is passed to and filled in by
|
|
.IR krb_rd_req .
|
|
The checksum passed to the corresponding
|
|
.I krb_sendauth
|
|
is available as part of the filled-in AUTH_DAT area.
|
|
|
|
The
|
|
.I filename
|
|
argument
|
|
specifies the filename
|
|
which the service program should use to obtain its service key.
|
|
.I Krb_recvauth
|
|
passes
|
|
.I filename
|
|
to the
|
|
.I krb_rd_req
|
|
function.
|
|
If you set this argument to "",
|
|
.I krb_rd_req
|
|
looks for the service key in the file
|
|
.IR /etc/srvtab.
|
|
|
|
If the client and server are performing mutual authenication,
|
|
the
|
|
.I schedule
|
|
argument
|
|
should point to an allocated Key_schedule.
|
|
Otherwise it is ignored and may be NULL.
|
|
|
|
The
|
|
.I version
|
|
argument should point to a character array of at least KSEND_VNO_LEN
|
|
characters. It is filled in with the version string passed by the client to
|
|
.IR krb_sendauth.
|
|
.PP
|
|
.SH KRB_NET_WRITE AND KRB_NET_READ
|
|
.PP
|
|
The
|
|
.I krb_net_write
|
|
function
|
|
emulates the write(2) system call, but guarantees that all data
|
|
specified is written to
|
|
.I fd
|
|
before returning, unless an error condition occurs.
|
|
.PP
|
|
The
|
|
.I krb_net_read
|
|
function
|
|
emulates the read(2) system call, but guarantees that the requested
|
|
amount of data is read from
|
|
.I fd
|
|
before returning, unless an error condition occurs.
|
|
.PP
|
|
.SH BUGS
|
|
.IR krb_sendauth,
|
|
.IR krb_recvauth,
|
|
.IR krb_net_write,
|
|
and
|
|
.IR krb_net_read
|
|
will not work properly on sockets set to non-blocking I/O mode.
|
|
|
|
.SH SEE ALSO
|
|
|
|
krb_mk_req(3), krb_rd_req(3), krb_get_phost(3)
|
|
|
|
.SH AUTHOR
|
|
John T. Kohl, MIT Project Athena
|
|
.SH RESTRICTIONS
|
|
Copyright 1988, Massachusetts Instititute of Technology.
|
|
For copying and distribution information,
|
|
please see the file <mit-copyright.h>.
|