60643d379b
(Including all changes for FreeBSD - importing the original eBones distribution would be too complex at this stage, since I don't have access to Piero's CVS.) (If you want to include eBones in your system, don't forget to include MAKE_EBONES in /etc/make.conf.) (This stuff is now also suppable from braae.ru.ac.za.) Bones originally from MIT SIPB. Original port to FreeBSD 1.x by Piero Serini. Moved to FreeBSD 2.0 by Doug Rabson and Geoff Rehmet. Nice bug fixes from Doug Rabson.
462 lines
12 KiB
Groff
462 lines
12 KiB
Groff
.\" from: kerberos.3,v 4.9 89/01/23 16:28:19 steiner Exp $
|
|
.\" $Id: kerberos.3,v 1.2 1994/07/19 19:27:35 g89r4222 Exp $
|
|
.\" Copyright 1989 by the Massachusetts Institute of Technology.
|
|
.\"
|
|
.\" For copying and distribution information,
|
|
.\" please see the file <Copyright.MIT>.
|
|
.\"
|
|
.TH KERBEROS 3 "Kerberos Version 4.0" "MIT Project Athena"
|
|
.SH 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
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.nj
|
|
.ft B
|
|
#include <des.h>
|
|
#include <krb.h>
|
|
.PP
|
|
.ft B
|
|
extern char *krb_err_txt[];
|
|
.PP
|
|
.ft B
|
|
int krb_mk_req(authent,service,instance,realm,checksum)
|
|
KTEXT authent;
|
|
char *service;
|
|
char *instance;
|
|
char *realm;
|
|
u_long checksum;
|
|
.PP
|
|
.ft B
|
|
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;
|
|
.PP
|
|
.ft B
|
|
int krb_kntoln(ad,lname)
|
|
AUTH_DAT *ad;
|
|
char *lname;
|
|
.PP
|
|
.ft B
|
|
int krb_set_key(key,cvt)
|
|
char *key;
|
|
int cvt;
|
|
.PP
|
|
.ft B
|
|
int krb_get_cred(service,instance,realm,c)
|
|
char *service;
|
|
char *instance;
|
|
char *realm;
|
|
CREDENTIALS *c;
|
|
.PP
|
|
.ft B
|
|
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;
|
|
.PP
|
|
.ft B
|
|
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;
|
|
.PP
|
|
.ft B
|
|
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;
|
|
.PP
|
|
.ft B
|
|
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;
|
|
.PP
|
|
.ft B
|
|
long krb_mk_err(out,code,string)
|
|
u_char *out;
|
|
long code;
|
|
char *string;
|
|
.PP
|
|
.ft B
|
|
long krb_rd_err(in,length,code,msg_data)
|
|
u_char *in;
|
|
u_long length;
|
|
long code;
|
|
MSG_DAT *msg_data;
|
|
.fi
|
|
.ft R
|
|
.SH DESCRIPTION
|
|
This library supports network authentication and various related
|
|
operations. 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.
|
|
.PP
|
|
.I krb_err_txt[]
|
|
contains text string descriptions of various Kerberos error codes returned
|
|
by some of the routines below.
|
|
.PP
|
|
.I krb_mk_req
|
|
takes a pointer to a text structure in which an authenticator 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 application to decide
|
|
how to generate the checksum.
|
|
.I krb_mk_req
|
|
then retrieves a ticket for the desired service and creates an
|
|
authenticator. The authenticator is built in
|
|
.I authent
|
|
and is accessible
|
|
to the calling procedure.
|
|
.PP
|
|
It is up to the application to get the authenticator to the service
|
|
where it will be read by
|
|
.I 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 authenticity of the other data that will pass through
|
|
a connection.
|
|
.PP
|
|
.I krb_rd_req
|
|
takes an authenticator of type
|
|
.B KTEXT,
|
|
a service name, an instance, the address of the
|
|
host originating the request, and a pointer to a structure of type
|
|
.B AUTH_DAT
|
|
which is filled in with information obtained 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
|
|
.I instance
|
|
contains "*", then the first service key with the same service name
|
|
found in the service key file will be used, and the
|
|
.I instance
|
|
argument will be filled in with the chosen instance. This means that
|
|
the caller must provide space for such an instance name.
|
|
.PP
|
|
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 authenticator is
|
|
then passed to
|
|
.I krb_rd_req
|
|
to extract the desired information.
|
|
.PP
|
|
.I 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
|
|
.I krb.h
|
|
for the list of error codes.
|
|
.PP
|
|
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
|
|
.I krb_set_key
|
|
and will not bother looking further.
|
|
.PP
|
|
.I krb_kntoln
|
|
converts a Kerberos name to a local name. It takes a structure
|
|
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, directories,
|
|
or other parameters. It is not an integral part of Kerberos, but is
|
|
instead provided to support the use of Kerberos in existing utilities.
|
|
.PP
|
|
.I 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
|
|
initialization vector.
|
|
It is used to set the server's key which
|
|
must be used to decrypt tickets.
|
|
.PP
|
|
If called with a non-zero second argument,
|
|
.I krb_set_key
|
|
will first convert the input from a string of arbitrary length to a DES
|
|
key by encrypting it with a one-way function.
|
|
.PP
|
|
In most cases it should not be necessary to call
|
|
.I krb_set_key.
|
|
The necessary keys will usually be obtained and set inside
|
|
.I krb_rd_req. krb_set_key
|
|
is provided for those applications that do not wish to place the
|
|
application keys on disk.
|
|
.PP
|
|
.I 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.
|
|
.PP
|
|
If the ticket was found,
|
|
.I 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.
|
|
.PP
|
|
.I krb_mk_priv
|
|
creates an encrypted, authenticated
|
|
message from any arbitrary application data, pointed to by
|
|
.I in
|
|
and
|
|
.I in_length
|
|
bytes long.
|
|
The private session key, pointed to by
|
|
.I key
|
|
and the key schedule,
|
|
.I schedule,
|
|
are used to encrypt the data and some header information using
|
|
.I pcbc_encrypt.
|
|
.I sender
|
|
and
|
|
.I receiver
|
|
point to the Internet address of the two parties.
|
|
In addition to providing privacy, this protocol message protects
|
|
against modifications, insertions or replays. The encapsulated message and
|
|
header are placed in the area pointed to by
|
|
.I out
|
|
and the routine returns the length of the output, or -1 indicating
|
|
an error.
|
|
.PP
|
|
.I krb_rd_priv
|
|
decrypts and authenticates a received
|
|
.I krb_mk_priv
|
|
message.
|
|
.I in
|
|
points to the beginning of the received message, whose length
|
|
is specified in
|
|
.I in_length.
|
|
The private session key, pointed to by
|
|
.I key,
|
|
and the key schedule,
|
|
.I schedule,
|
|
are used to decrypt and verify the received message.
|
|
.I msg_data
|
|
is a pointer to a
|
|
.I MSG_DAT
|
|
struct, defined in
|
|
.I krb.h.
|
|
The routine fills in the
|
|
.I app_data
|
|
field with a pointer to the decrypted application data,
|
|
.I app_length
|
|
with the length of the
|
|
.I app_data
|
|
field,
|
|
.I time_sec
|
|
and
|
|
.I time_5ms
|
|
with the timestamps in the message, and
|
|
.I 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
|
|
.I hash
|
|
field returns a value useful as input to the
|
|
.I krb_ck_repl
|
|
routine.
|
|
|
|
The routine returns zero if ok, or a Kerberos error code. Modified messages
|
|
and old messages cause errors, but it is up to the caller to
|
|
check the time sequence of messages, and to check against recently replayed
|
|
messages using
|
|
.I krb_ck_repl
|
|
if so desired.
|
|
.PP
|
|
.I krb_mk_safe
|
|
creates an authenticated, but unencrypted message from any arbitrary
|
|
application data,
|
|
pointed to by
|
|
.I in
|
|
and
|
|
.I in_length
|
|
bytes long.
|
|
The private session key, pointed to by
|
|
.I key,
|
|
is used to seed the
|
|
.I quad_cksum()
|
|
checksum algorithm used as part of the authentication.
|
|
.I sender
|
|
and
|
|
.I 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
|
|
.I out
|
|
and the routine returns the length of the output, or -1 indicating
|
|
an error.
|
|
The authentication provided by this routine is not as strong as that
|
|
provided by
|
|
.I krb_mk_priv
|
|
or by computing the checksum using
|
|
.I cbc_cksum
|
|
instead, both of which authenticate via DES.
|
|
.PP
|
|
|
|
.I krb_rd_safe
|
|
authenticates a received
|
|
.I krb_mk_safe
|
|
message.
|
|
.I in
|
|
points to the beginning of the received message, whose length
|
|
is specified in
|
|
.I in_length.
|
|
The private session key, pointed to by
|
|
.I key,
|
|
is used to seed the quad_cksum() routine as part of the authentication.
|
|
.I msg_data
|
|
is a pointer to a
|
|
.I MSG_DAT
|
|
struct, defined in
|
|
.I krb.h .
|
|
The routine fills in these
|
|
.I MSG_DAT
|
|
fields:
|
|
the
|
|
.I app_data
|
|
field with a pointer to the application data,
|
|
.I app_length
|
|
with the length of the
|
|
.I app_data
|
|
field,
|
|
.I time_sec
|
|
and
|
|
.I time_5ms
|
|
with the timestamps in the message, and
|
|
.I 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
|
|
.I hash
|
|
field returns a value useful as input to the
|
|
.I krb_ck_repl
|
|
routine.
|
|
|
|
The routine returns zero if ok, or a Kerberos error code. Modified messages
|
|
and old messages cause errors, but it is up to the caller to
|
|
check the time sequence of messages, and to check against recently replayed
|
|
messages using
|
|
.I krb_ck_repl
|
|
if so desired.
|
|
.PP
|
|
.I krb_mk_err
|
|
constructs an application level error message that may be used along
|
|
with
|
|
.I krb_mk_priv
|
|
or
|
|
.I krb_mk_safe.
|
|
.I out
|
|
is a pointer to the output buffer,
|
|
.I code
|
|
is an application specific error code, and
|
|
.I string
|
|
is an application specific error string.
|
|
|
|
.PP
|
|
.I krb_rd_err
|
|
unpacks a received
|
|
.I krb_mk_err
|
|
message.
|
|
.I in
|
|
points to the beginning of the received message, whose length
|
|
is specified in
|
|
.I in_length.
|
|
.I code
|
|
is a pointer to a value to be filled in with the error
|
|
value provided by the application.
|
|
.I msg_data
|
|
is a pointer to a
|
|
.I MSG_DAT
|
|
struct, defined in
|
|
.I krb.h .
|
|
The routine fills in these
|
|
.I MSG_DAT
|
|
fields: the
|
|
.I app_data
|
|
field with a pointer to the application error text,
|
|
.I app_length
|
|
with the length of the
|
|
.I app_data
|
|
field, and
|
|
.I 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 received,
|
|
or a Kerberos error code.
|
|
.PP
|
|
The
|
|
.I 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 returns 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.
|
|
.PP
|
|
The
|
|
.I AUTH_DAT
|
|
structure is filled in by krb_rd_req. It must be allocated before
|
|
calling krb_rd_req, and a pointer to it is passed. The structure is
|
|
filled in with data obtained from Kerberos.
|
|
.I 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 Kerberos.
|
|
.PP
|
|
.SH FILES
|
|
/usr/include/krb.h
|
|
.br
|
|
/usr/lib/libkrb.a
|
|
.br
|
|
/usr/include/des.h
|
|
.br
|
|
/usr/lib/libdes.a
|
|
.br
|
|
/etc/aname
|
|
.br
|
|
/etc/srvtab
|
|
.br
|
|
/tmp/tkt[uid]
|
|
.SH "SEE ALSO"
|
|
kerberos(1), des_crypt(3)
|
|
.SH DIAGNOSTICS
|
|
.SH BUGS
|
|
The caller of
|
|
.I krb_rd_req, krb_rd_priv, and krb_rd_safe
|
|
must check time order and for replay attempts.
|
|
.I krb_ck_repl
|
|
is not implemented yet.
|
|
.SH AUTHORS
|
|
Clifford Neuman, MIT Project Athena
|
|
.br
|
|
Steve Miller, MIT Project Athena/Digital Equipment Corporation
|
|
.SH RESTRICTIONS
|
|
COPYRIGHT 1985,1986,1989 Massachusetts Institute of Technology
|