The first revision after the creation of the

implementor's guide

git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@3770 dc483132-0cff-0310-8789-dd5450dbe970

1 files changed, 298 insertions, 0 deletions

diff --git a/doc/api/intro.tex b/doc/api/intro.tex
new file mode 100644
index 000000000..b0c8d731d
--- /dev/null
+++ b/doc/api/intro.tex
@@ -0,0 +1,298 @@
+	This document describes the routines that make up the Kerberos
+V5 application programming interface.  It is geared towards
+programmers who already have a basic familiarity with Kerberos and are
+in the process of including Kerberos authentication as part of 
+applications being developed.
+
+	The function descriptions included are up to date, even if the
+description of the functions may be hard to understand for the novice
+Kerberos programmer.
+
+\subsection{Acknoledgments}
+
+
+The Kerberos model is based in part on Needham and Schroeder's trusted
+third-party authentication protocol and on modifications suggested by
+Denning and Sacco.  The original design and implementation of Kerberos
+Versions 1 through 4 was the work of Steve Miller of Digital Equipment
+Corporation and Clifford Neuman (now at the Information Sciences
+Institute of the University of Southern California), along with Jerome
+Saltzer, Technical Director of Project Athena, and Jeffrey Schiller,
+MIT Campus Network Manager.  Many other members of Project Athena have
+also contributed to the work on Kerberos.  Version 4 is publicly
+available, and has seen wide use across the Internet.
+
+Version 5 (described in this document) has evolved from Version 4 based
+on new requirements and desires for features not available in Version 4.
+
+%nlg- a bunch more probably needs to be added here to credit all
+%those that have contributed to V5 -nlg
+
+\subsection{Kerberos Basics}
+
+Kerberos performs authentication as a trusted third-party
+authentication service by using conventional (shared secret
+key\footnote{ {\em Secret} and {\em private} are often used
+interchangeably in the literature.  In our usage, it takes two (or
+more) to share a secret, thus a shared DES key is a {\em secret} key.
+Something is only private when no one but its owner knows it.  Thus,
+in public key cryptosystems, one has a public and a {\em private} key.
+}) cryptography.  Kerberos provides a means of verifying the
+identities of principals, without relying on authentication by the
+host operating system, without basing trust on host addresses, without
+requiring physical security of all the hosts on the network, and under
+the assumption that packets traveling along the network can be read,
+modified, and inserted at will.
+
+When integrating Kerberos into an application it is important to
+review how and when Kerberos functions are used to ensure that the
+application's design does not compromise the authentication.  For
+instance, an application which uses Kerberos' functions only upon the
+{\em initiation} of a stream-based network connection, and assumes the
+absence of any active attackers who might be able to ``hijack'' the
+stream connection.
+
+%{\Huge nlg- It would be nice to include more examples here of common
+%mistakes one can make in deisgning kerberized systems -nlg}
+
+The Kerberos protocol code libraries, whose API is described in this
+document, can be used to provide encryption to any application.  In
+order to add authentication to its transactions, a typical network
+application adds one or two calls to the Kerberos library, which
+results in the transmission of the necessary messages to achieve
+authentication.
+
+The two methods for obtaining credentials, the inital ticket exchange
+and the ticket granting ticket exchange, use slightly different
+protocols and require different API routines.  The basic difference an
+API programmer will see is that the initial request does not require a
+ticket granting ticket (TGT) but does require the client's secret key
+because the reply is sent back encrypted in the client's secret key.
+Usually this request is for a TGT and TGT based exchanges are used
+from then on.  In a TGT exchange the TGT is sent as part of the
+request for tickets and the reply is encrypted in the session key from
+the TGT.  For example, once a user's password is used to obtain a TGT,
+it is not required for subsequent TGT exchanges.
+
+The reply consists of a ticket and a session key, encrypted either in
+the user's secret key (i.e., pasword), or the TGT session key.  The
+combination of a ticket and a session key is known as a set of {\em
+credentials}.\footnote{In Kerberos V4, the ``ticket file'' was a bit of
+a misnomer, since it contained both tickets and their associated session
+keys.  In Kerberos V5, the ``ticket file'' has been renamed to be the
+{\em credentials cache}.} An application client can use these
+credentials to authenticate to the application server by sending the
+ticket and an {\em authenticator} to the server.  The authenticator is
+encrypted in the session key of the ticket, and contains the name of the
+client, the name of the server, the time the authenticator was created.
+
+In order to verify the authentication, the application server decrypts
+the ticket using its service key, which is only known by the application
+server and the Kerberos server.  Inside the ticket, the Kerberos server
+had placed the name of the client, the name of the server, a DES key
+assocuated with this ticket, and some additional information.  The
+application server then uses the ticket session key to decrypt the
+authenticator, and verifies that the information in the authenticator
+matches the information in the ticket, and that the timestamp in the
+authenticator is recent (to prvent reply attacks).  Since the session
+key was generated randomly by the Kerberos server, and delivered only
+encrypted in the service key, and in a key known only by the user, the
+application server can be confident that user is really who he or she
+claims to be, by virtue of the fact that the user was able to encrypt
+the authenticator in the correct key.
+
+To provide detection of both replay
+attacks and message stream modification attacks, the integrity of all
+the messages exchanged between principals can also be 
+guaranteed\footnote{Using
+\funcname{krb5_mk_safe} and \funcname{krb5_rd_safe} to create and
+verify KRB5_SAFE messages} by generating and transmitting a
+collision-proof checksum \footnote{aka cryptographic checksum,
+elsewhere this is called a hash or digest function} of the client's
+message, keyed with the session key.  Privacy and integrity of the
+messages exchanged between principals can be secured\footnote{Using
+\funcname{krb5_mk_priv} and \funcname{krb5_rd_priv} to create and
+verify KRB5_PRIV messages} by encrypting the data to be passed using
+the session key.
+
+\subsubsection{The purpose of Realms}
+
+The Kerberos protocol is designed to operate across organizational
+boundaries.   Each organization wishing to run a Kerberos
+server establishes its own {\em realm}.  The name of the realm in which a
+client is registered is part of the client's name, and can be used by the
+end-service to decide whether to honor a request.
+
+By establishing {\em inter-realm} keys, the administrators of two
+realms can allow a client authenticated in the local realm to use its
+credentials remotely.  The exchange of inter-realm keys (a separate
+key may be used for each direction) registers the ticket-granting
+service of each realm as a principal in the other realm.  A client is
+then able to obtain a ticket-granting ticket for the remote realm's
+ticket-granting service from its local realm.  When that
+ticket-granting ticket is used, the remote ticket-granting service
+uses the inter-realm key (which usually differs from its own normal
+TGS key) to decrypt the ticket-granting ticket, and is thus certain
+that it was issued by the client's own TGS. Tickets issued by the
+remote ticket-granting service will indicate to the end-service that
+the client was authenticated from another realm.   
+
+
+This method can be repeated to authenticate throughout an organization
+accross multiple relms.  To build a valid authentication
+path\footnote{An {\em authentication path} is the sequence of
+intermediate realms that are transited in communicating from one realm
+to another.} to a distant relm, the local realm must share an
+inter-realm key with an intermediate realm which
+communicates\footnote{A realm is said to {\em communicate} with
+another realm if the two realms share an inter-realm key} with either
+the distant remote realm or yet another intermediate relm.
+
+Realms are typically organized hierarchically.  Each realm shares a
+key with its parent and a different key with each child.  If an
+inter-realm key is not directly shared by two realms, the hierarchical
+organization allows an authentication path to be easily constructed.
+If a hierarchical organization is not used, it may be necessary to
+consult some database in order to construct an authentication path
+between realms.
+
+Although realms are typically hierarchical, intermediate realms may be
+bypassed to achieve cross-realm authentication through alternate
+authentication paths\footnote{These might be established to make communication
+between two realms more efficient}.  It is important for the
+end-service to know which realms were transited when deciding how much
+faith to place in the authentication process.  To facilitate this
+decision, a field in each ticket contains the names of the realms that
+were involved in authenticating the client.
+
+\subsubsection{Fundamental assumptions about the environment}
+
+Kerberos has certain limitations that should be kept in mind when
+designing security measures:
+
+\begin{itemize}
+\item
+Kerberos does not address ``Denial of service'' attacks.  There are
+places in these protocols where an intruder can prevent an application
+from participating in the proper authentication steps.  Detection and
+solution of such attacks (some of which can appear to be not-uncommon
+``normal'' failure modes for the system) is usually best left to
+the human administrators and users.
+
+\item
+Principals must keep their secret keys secret.  If an intruder somehow
+steals a principal's key, it will be able to masquerade as that
+principal or impersonate any server to the legitimate principal.
+
+\item
+``Password guessing'' attacks are not solved by Kerberos.  If a user
+chooses a poor password, it is possible for an attacker to
+successfully mount an offline dictionary attack by repeatedly
+attempting to decrypt, with successive entries from a dictionary,
+messages obtained which are encrypted under a key derived from the
+user's password.
+
+\end{itemize}
+
+\subsection{Glossary of terms}
+
+Below is a list of terms used throughout this document.
+
+\begin{description}
+\item [Authentication] 
+Verifying the claimed identity of a principal.
+
+\item [Authentication header]
+A record containing a Ticket and an Authenticator to be presented to a
+server as part of the authentication process.
+
+\item [Authentication path]
+A sequence of intermediate realms transited in the authentication
+process when communicating from one realm to another.
+
+\item [Authenticator]
+A record containing information that can be shown to
+have been recently generated using the session key known only by the 
+client and server.
+
+\item [Authorization]
+The process of determining whether a client may use a
+service,  which objects the client is allowed to access, and the 
+type of access allowed for each.
+
+\item [Ciphertext]
+The output of an encryption function.  Encryption transforms plaintext
+into ciphertext.
+
+\item [Client]
+A process that makes use of a network service on behalf of a
+user.  Note that in some cases a {\em Server} may itself be a client of
+some other server (e.g. a print server may be a client of a file server).
+
+\item [Credentials]
+A ticket plus the secret session key necessary to
+successfully use that ticket in an authentication exchange.
+
+\item [KDC]
+Key Distribution Center, a network service that supplies
+tickets and temporary session keys; or an
+instance of that service or the host on which it runs.
+The KDC services both initial ticket and ticket-granting ticket
+requests.
+The initial ticket portion is sometimes referred to as the
+Authentication Server (or service).
+The ticket-granting ticket portion is sometimes referred to as the
+ticket-granting server (or service).
+
+\item [Kerberos]
+Aside from the 3-headed dog guarding Hades, the name given
+to Project Athena's authentication service, the protocol used by that
+service, or the code used to implement the authentication service.
+
+\item [Plaintext]
+The input to an encryption function or the output of a decryption
+function.  Decryption transforms ciphertext into plaintext.
+
+\item [Principal]
+A uniquely named client or server instance that participates in
+a network communication.
+
+\item [Principal identifier]
+The name used to uniquely identify each different
+principal.
+
+\item [Seal]
+To encipher a record containing several fields in such a way
+that the fields cannot be individually replaced without either
+knowledge of the encryption key or leaving evidence of tampering.
+
+\item [Secret key]
+An encryption key shared by a principal and the KDC,
+distributed outside the bounds of the system, with a long lifetime.
+In the case of a human user's principal, the secret key is derived from a
+password.
+
+\item [Server]
+A particular Principal which provides a resource to network clients.
+
+\item [Service]
+A resource provided to network clients; often provided by more than one
+server (for example, remote file service).
+
+\item [Session key]
+A temporary encryption key used between two principals,
+with a lifetime limited to the duration of a single login
+{\em session}.
+
+\item [Sub-session key] 
+A temporary encryption key used between two
+principals, selected and exchanged by the principals using the session
+key, and with a lifetime limited to the duration of a single
+association.
+
+\item [Ticket]
+A record that helps a client authenticate itself to a server; it contains
+the client's identity, a session key, a timestamp, and other
+information, all sealed using the server's secret key.  It only serves to
+authenticate a client when presented along with a fresh Authenticator.
+\end{description}