Return to krb.3 CVS log

Up to [CSRG BSD Unix] / 43BSDReno / kerberosIV / man

Annotation of 43BSDReno/kerberosIV/man/krb.3, revision 1.1

1.1     ! root        1: .\" $Source: /usr/src/kerberosIV/man/RCS/kerberos.3,v $
        !             2: .\" $Author: kfall $
        !             3: .\" $Header: /usr/src/kerberosIV/man/RCS/kerberos.3,v 4.10 90/06/25 21:12:11 kfall Exp $
        !             4: .\" Copyright 1989 by the Massachusetts Institute of Technology.
        !             5: .\"
        !             6: .\" For copying and distribution information,
        !             7: .\" please see the file <mit-copyright.h>.
        !             8: .\"
        !             9: .TH KERBEROS 3 "Kerberos Version 4.0" "MIT Project Athena"
        !            10: .SH NAME
        !            11: krb_mk_req, krb_rd_req, krb_kntoln, krb_set_key, krb_get_cred,
        !            12: krb_mk_priv, krb_rd_priv, krb_mk_safe, krb_rd_safe, krb_mk_err,
        !            13: krb_rd_err, krb_ck_repl \- Kerberos authentication library
        !            14: .SH SYNOPSIS
        !            15: .nf
        !            16: .nj
        !            17: .ft B
        !            18: #include <kerberosIV/des.h>
        !            19: #include <kerberosIV/krb.h>
        !            20: .PP
        !            21: .ft B
        !            22: extern char *krb_err_txt[];
        !            23: .PP
        !            24: .ft B
        !            25: int krb_mk_req(authent,service,instance,realm,checksum)
        !            26: KTEXT authent;
        !            27: char *service;
        !            28: char *instance;
        !            29: char *realm;
        !            30: u_long checksum;
        !            31: .PP
        !            32: .ft B
        !            33: int krb_rd_req(authent,service,instance,from_addr,ad,fn)
        !            34: KTEXT authent;
        !            35: char *service;
        !            36: char *instance;
        !            37: u_long from_addr;
        !            38: AUTH_DAT *ad;
        !            39: char *fn;
        !            40: .PP
        !            41: .ft B
        !            42: int krb_kntoln(ad,lname)
        !            43: AUTH_DAT *ad;
        !            44: char *lname;
        !            45: .PP
        !            46: .ft B
        !            47: int krb_set_key(key,cvt)
        !            48: char *key;
        !            49: int cvt;
        !            50: .PP
        !            51: .ft B
        !            52: int krb_get_cred(service,instance,realm,c)
        !            53: char *service;
        !            54: char *instance;
        !            55: char *realm;
        !            56: CREDENTIALS *c;
        !            57: .PP
        !            58: .ft B
        !            59: long krb_mk_priv(in,out,in_length,schedule,key,sender,receiver)
        !            60: u_char *in;
        !            61: u_char *out;
        !            62: u_long in_length;
        !            63: des_cblock key;
        !            64: des_key_schedule schedule;
        !            65: struct sockaddr_in *sender;
        !            66: struct sockaddr_in *receiver;
        !            67: .PP
        !            68: .ft B
        !            69: long krb_rd_priv(in,in_length,schedule,key,sender,receiver,msg_data)
        !            70: u_char *in;
        !            71: u_long in_length;
        !            72: Key_schedule schedule;
        !            73: des_cblock key;
        !            74: struct sockaddr_in *sender;
        !            75: struct sockaddr_in *receiver;
        !            76: MSG_DAT *msg_data;
        !            77: .PP
        !            78: .ft B
        !            79: long krb_mk_safe(in,out,in_length,key,sender,receiver)
        !            80: u_char *in;
        !            81: u_char *out;
        !            82: u_long in_length;
        !            83: des_cblock key;
        !            84: struct sockaddr_in *sender;
        !            85: struct sockaddr_in *receiver;
        !            86: .PP
        !            87: .ft B
        !            88: long krb_rd_safe(in,length,key,sender,receiver,msg_data)
        !            89: u_char *in;
        !            90: u_long length;
        !            91: des_cblock key;
        !            92: struct sockaddr_in *sender;
        !            93: struct sockaddr_in *receiver;
        !            94: MSG_DAT *msg_data;
        !            95: .PP
        !            96: .ft B
        !            97: long krb_mk_err(out,code,string)
        !            98: u_char *out;
        !            99: long code;
        !           100: char *string;
        !           101: .PP
        !           102: .ft B
        !           103: long krb_rd_err(in,length,code,msg_data)
        !           104: u_char *in;
        !           105: u_long length;
        !           106: long code;
        !           107: MSG_DAT *msg_data;
        !           108: .fi
        !           109: .ft R
        !           110: .SH DESCRIPTION
        !           111: This library supports network authentication and various related
        !           112: operations.  The library contains many routines beyond those described
        !           113: in this man page, but they are not intended to be used directly.
        !           114: Instead, they are called by the routines that are described, the
        !           115: authentication server and the login program.
        !           116: .PP
        !           117: .I krb_err_txt[]
        !           118: contains text string descriptions of various Kerberos error codes returned
        !           119: by some of the routines below.
        !           120: .PP
        !           121: .I krb_mk_req
        !           122: takes a pointer to a text structure in which an authenticator is to be
        !           123: built.  It also takes the name, instance, and realm of the service to be
        !           124: used and an optional checksum.  It is up to the application to decide
        !           125: how to generate the checksum.
        !           126: .I krb_mk_req
        !           127: then retrieves a ticket for the desired service and creates an
        !           128: authenticator.  The authenticator is built in
        !           129: .I authent
        !           130: and is accessible
        !           131: to the calling procedure.
        !           132: .PP
        !           133: It is up to the application to get the authenticator to the service
        !           134: where it will be read by
        !           135: .I krb_rd_req.
        !           136: Unless an attacker posesses the session key contained in the ticket, it
        !           137: will be unable to modify the authenticator.  Thus, the checksum can be
        !           138: used to verify the authenticity of the other data that will pass through
        !           139: a connection.
        !           140: .PP
        !           141: .I krb_rd_req
        !           142: takes an authenticator of type
        !           143: .B KTEXT,
        !           144: a service name, an instance, the address of the
        !           145: host originating the request, and a pointer to a structure of type
        !           146: .B AUTH_DAT
        !           147: which is filled in with information obtained from the authenticator.
        !           148: It also optionally takes the name of the file in which it will find the
        !           149: secret key(s) for the service.
        !           150: If the supplied
        !           151: .I instance
        !           152: contains "*", then the first service key with the same service name
        !           153: found in the service key file will be used, and the
        !           154: .I instance
        !           155: argument will be filled in with the chosen instance.  This means that
        !           156: the caller must provide space for such an instance name.
        !           157: .PP
        !           158: It is used to find out information about the principal when a request
        !           159: has been made to a service.  It is up to the application protocol to get
        !           160: the authenticator from the client to the service.  The authenticator is
        !           161: then passed to
        !           162: .I krb_rd_req
        !           163: to extract the desired information.
        !           164: .PP
        !           165: .I krb_rd_req
        !           166: returns zero (RD_AP_OK) upon successful authentication.  If a packet was
        !           167: forged, modified, or replayed, authentication will fail.  If the
        !           168: authentication fails, a non-zero value is returned indicating the
        !           169: particular problem encountered.  See
        !           170: .I krb.h
        !           171: for the list of error codes.
        !           172: .PP
        !           173: If the last argument is the null string (""), krb_rd_req will use the
        !           174: file /etc/srvtab to find its keys.  If the last argument is NULL, it
        !           175: will assume that the key has been set by
        !           176: .I krb_set_key
        !           177: and will not bother looking further.
        !           178: .PP
        !           179: .I krb_kntoln
        !           180: converts a Kerberos name to a local name.  It takes a structure
        !           181: of type AUTH_DAT and uses the name and instance to look in the database
        !           182: /etc/aname to find the corresponding local name.  The local name is
        !           183: returned and can be used by an application to change uids, directories,
        !           184: or other parameters.  It is not an integral part of Kerberos, but is
        !           185: instead provided to support the use of Kerberos in existing utilities.
        !           186: .PP
        !           187: .I krb_set_key
        !           188: takes as an argument a des key.  It then creates
        !           189: a key schedule from it and saves the original key to be used as an
        !           190: initialization vector.
        !           191: It is used to set the server's key which
        !           192: must be used to decrypt tickets.
        !           193: .PP
        !           194: If called with a non-zero second argument,
        !           195: .I krb_set_key
        !           196: will first convert the input from a string of arbitrary length to a DES
        !           197: key by encrypting it with a one-way function.
        !           198: .PP
        !           199: In most cases it should not be necessary to call
        !           200: .I krb_set_key.
        !           201: The necessary keys will usually be obtained and set inside
        !           202: .I krb_rd_req.  krb_set_key
        !           203: is provided for those applications that do not wish to place the
        !           204: application keys on disk.
        !           205: .PP
        !           206: .I krb_get_cred
        !           207: searches the caller's ticket file for a ticket for the given service, instance,
        !           208: and realm; and, if a ticket is found, fills in the given CREDENTIALS structure
        !           209: with the ticket information.
        !           210: .PP
        !           211: If the ticket was found,
        !           212: .I krb_get_cred
        !           213: returns GC_OK.
        !           214: If the ticket file can't be found, can't be read, doesn't belong to
        !           215: the user (other than root), isn't a regular file, or is in the wrong
        !           216: mode, the error GC_TKFIL is returned.
        !           217: .PP
        !           218: .I krb_mk_priv
        !           219: creates an encrypted, authenticated
        !           220: message from any arbitrary application data, pointed to by
        !           221: .I in
        !           222: and
        !           223: .I in_length
        !           224: bytes long.
        !           225: The private session key, pointed to by
        !           226: .I key
        !           227: and the key schedule,
        !           228: .I schedule,
        !           229: are used to encrypt the data and some header information using
        !           230: .I pcbc_encrypt.
        !           231: .I sender
        !           232: and
        !           233: .I receiver
        !           234: point to the Internet address of the two parties.
        !           235: In addition to providing privacy, this protocol message protects
        !           236: against modifications, insertions or replays.  The encapsulated message and
        !           237: header are placed in the area pointed to by
        !           238: .I out
        !           239: and the routine returns the length of the output, or -1 indicating
        !           240: an error.
        !           241: .PP
        !           242: .I krb_rd_priv
        !           243: decrypts and authenticates a received
        !           244: .I krb_mk_priv
        !           245: message.
        !           246: .I in
        !           247: points to the beginning of the received message, whose length
        !           248: is specified in
        !           249: .I in_length.
        !           250: The private session key, pointed to by
        !           251: .I key,
        !           252: and the key schedule,
        !           253: .I schedule,
        !           254: are used to decrypt and verify the received message.
        !           255: .I msg_data
        !           256: is a pointer to a
        !           257: .I MSG_DAT
        !           258: struct, defined in
        !           259: .I krb.h.
        !           260: The routine fills in the
        !           261: .I app_data
        !           262: field with a pointer to the decrypted application data,
        !           263: .I app_length
        !           264: with the length of the
        !           265: .I app_data
        !           266: field,
        !           267: .I time_sec
        !           268: and
        !           269: .I time_5ms
        !           270: with the timestamps in the message, and
        !           271: .I swap
        !           272: with a 1 if the byte order of the receiver is different than that of
        !           273: the sender.  (The application must still determine if it is appropriate
        !           274: to byte-swap application data; the Kerberos protocol fields are already taken
        !           275: care of).  The
        !           276: .I hash
        !           277: field returns a value useful as input to the
        !           278: .I krb_ck_repl
        !           279: routine.
        !           280: 
        !           281: The routine returns zero if ok, or a Kerberos error code. Modified messages
        !           282: and old messages cause errors, but it is up to the caller to
        !           283: check the time sequence of messages, and to check against recently replayed
        !           284: messages using
        !           285: .I krb_ck_repl
        !           286: if so desired.
        !           287: .PP
        !           288: .I krb_mk_safe
        !           289: creates an authenticated, but unencrypted message from any arbitrary
        !           290: application data,
        !           291: pointed to by
        !           292: .I in
        !           293: and
        !           294: .I in_length
        !           295: bytes long.
        !           296: The private session key, pointed to by
        !           297: .I key,
        !           298: is used to seed the
        !           299: .I quad_cksum()
        !           300: checksum algorithm used as part of the authentication.
        !           301: .I sender
        !           302: and
        !           303: .I receiver
        !           304: point to the Internet address of the two parties.
        !           305: This message does not provide privacy, but does protect (via detection)
        !           306: against modifications, insertions or replays.  The encapsulated message and
        !           307: header are placed in the area pointed to by
        !           308: .I out
        !           309: and the routine returns the length of the output, or -1 indicating
        !           310: an error.
        !           311: The authentication provided by this routine is not as strong as that
        !           312: provided by
        !           313: .I krb_mk_priv
        !           314: or by computing the checksum using
        !           315: .I cbc_cksum
        !           316: instead, both of which authenticate via DES.
        !           317: .PP
        !           318: 
        !           319: .I krb_rd_safe
        !           320: authenticates a received
        !           321: .I krb_mk_safe
        !           322: message.
        !           323: .I in
        !           324: points to the beginning of the received message, whose length
        !           325: is specified in
        !           326: .I in_length.
        !           327: The private session key, pointed to by
        !           328: .I key,
        !           329: is used to seed the quad_cksum() routine as part of the authentication.
        !           330: .I msg_data
        !           331: is a pointer to a
        !           332: .I MSG_DAT
        !           333: struct, defined in
        !           334: .I krb.h .
        !           335: The routine fills in these
        !           336: .I MSG_DAT
        !           337: fields:
        !           338: the
        !           339: .I app_data
        !           340: field with a pointer to the application data,
        !           341: .I app_length
        !           342: with the length of the
        !           343: .I app_data
        !           344: field,
        !           345: .I time_sec
        !           346: and
        !           347: .I time_5ms
        !           348: with the timestamps in the message, and
        !           349: .I swap
        !           350: with a 1 if the byte order of the receiver is different than that of
        !           351: the sender.
        !           352: (The application must still determine if it is appropriate
        !           353: to byte-swap application data; the Kerberos protocol fields are already taken
        !           354: care of).  The
        !           355: .I hash
        !           356: field returns a value useful as input to the
        !           357: .I krb_ck_repl
        !           358: routine.
        !           359: 
        !           360: The routine returns zero if ok, or a Kerberos error code. Modified messages
        !           361: and old messages cause errors, but it is up to the caller to
        !           362: check the time sequence of messages, and to check against recently replayed
        !           363: messages using
        !           364: .I krb_ck_repl
        !           365: if so desired.
        !           366: .PP
        !           367: .I krb_mk_err
        !           368: constructs an application level error message that may be used along
        !           369: with
        !           370: .I krb_mk_priv
        !           371: or
        !           372: .I krb_mk_safe.
        !           373: .I out
        !           374: is a pointer to the output buffer,
        !           375: .I code
        !           376: is an application specific error code, and
        !           377: .I string
        !           378: is an application specific error string.
        !           379: 
        !           380: .PP
        !           381: .I krb_rd_err
        !           382: unpacks a received
        !           383: .I krb_mk_err
        !           384: message.
        !           385: .I in
        !           386: points to the beginning of the received message, whose length
        !           387: is specified in
        !           388: .I in_length.
        !           389: .I code
        !           390: is a pointer to a value to be filled in with the error
        !           391: value provided by the application.
        !           392: .I msg_data
        !           393: is a pointer to a
        !           394: .I MSG_DAT
        !           395: struct, defined in
        !           396: .I krb.h .
        !           397: The routine fills in these
        !           398: .I MSG_DAT
        !           399: fields: the
        !           400: .I app_data
        !           401: field with a pointer to the application error text,
        !           402: .I app_length
        !           403: with the length of the
        !           404: .I app_data
        !           405: field, and
        !           406: .I swap
        !           407: with a 1 if the byte order of the receiver is different than that of
        !           408: the sender.  (The application must still determine if it is appropriate
        !           409: to byte-swap application data; the Kerberos protocol fields are already taken
        !           410: care of).
        !           411: 
        !           412: The routine returns zero if the error message has been successfully received,
        !           413: or a Kerberos error code.
        !           414: .PP
        !           415: The
        !           416: .I KTEXT
        !           417: structure is used to pass around text of varying lengths.  It consists
        !           418: of a buffer for the data, and a length.  krb_rd_req takes an argument of this
        !           419: type containing the authenticator, and krb_mk_req returns the
        !           420: authenticator in a structure of this type.  KTEXT itself is really a
        !           421: pointer to the structure.   The actual structure is of type KTEXT_ST.
        !           422: .PP
        !           423: The
        !           424: .I AUTH_DAT
        !           425: structure is filled in by krb_rd_req.  It must be allocated before
        !           426: calling krb_rd_req, and a pointer to it is passed.  The structure is
        !           427: filled in with data obtained from Kerberos.
        !           428: .I MSG_DAT
        !           429: structure is filled in by either krb_rd_priv, krb_rd_safe, or
        !           430: krb_rd_err.  It must be allocated before the call and a pointer to it
        !           431: is passed.  The structure is
        !           432: filled in with data obtained from Kerberos.
        !           433: .PP
        !           434: .SH FILES
        !           435: /usr/include/kerberosIV/krb.h
        !           436: .br
        !           437: /usr/lib/libkrb.a
        !           438: .br
        !           439: /usr/include/kerberosIV/des.h
        !           440: .br
        !           441: /usr/lib/libdes.a
        !           442: .br
        !           443: /etc/kerberosIV/aname
        !           444: .br
        !           445: /etc/kerberosIV/srvtab
        !           446: .br
        !           447: /tmp/tkt[uid]
        !           448: .SH "SEE ALSO"
        !           449: kerberos(1), des_crypt(3)
        !           450: .SH DIAGNOSTICS
        !           451: .SH BUGS
        !           452: The caller of
        !           453: .I krb_rd_req, krb_rd_priv, and krb_rd_safe
        !           454: must check time order and for replay attempts.
        !           455: .I krb_ck_repl
        !           456: is not implemented yet.
        !           457: .SH AUTHORS
        !           458: Clifford Neuman, MIT Project Athena
        !           459: .br
        !           460: Steve Miller, MIT Project Athena/Digital Equipment Corporation
        !           461: .SH RESTRICTIONS
        !           462: COPYRIGHT 1985,1986,1989 Massachusetts Institute of Technology

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.