462 lines
12 KiB
Groff
462 lines
12 KiB
Groff
.\" $Id: kerberos.3,v 1.2 1996/06/12 21:29:18 bg Exp $
|
|
.\" $FreeBSD$
|
|
.\" Copyright 1989 by the Massachusetts Institute of Technology.
|
|
.\"
|
|
.\" For copying and distribution information,
|
|
.\" please see the file <mit-copyright.h>.
|
|
.\"
|
|
.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 <openssl/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
|