diff options
Diffstat (limited to 'kerberosIV/krb/kerberos.3')
| -rw-r--r-- | kerberosIV/krb/kerberos.3 | 462 |
1 files changed, 462 insertions, 0 deletions
diff --git a/kerberosIV/krb/kerberos.3 b/kerberosIV/krb/kerberos.3 new file mode 100644 index 00000000000..4434508dc59 --- /dev/null +++ b/kerberosIV/krb/kerberos.3 @@ -0,0 +1,462 @@ +.\" $Source: /cvs/OpenBSD/src/kerberosIV/krb/Attic/kerberos.3,v $ +.\" $Author: tholo $ +.\" $Header: /cvs/OpenBSD/src/kerberosIV/krb/Attic/kerberos.3,v 1.1 1995/12/14 06:52:41 tholo Exp $ +.\" 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 <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 |