[2596] in Release_Engineering
rkinit documentation
daemon@ATHENA.MIT.EDU (qjb@ATHENA.MIT.EDU)
Wed May 22 14:56:35 1991
From: qjb@ATHENA.MIT.EDU
Date: Wed, 22 May 91 14:56:24 -0400
To: rel-eng@ATHENA.MIT.EDU
I found a sketch of a design document for rkinit in my home
directory. Before I remove it, I will post it here so that it
can be stored somewhere with the rkinit sources. This document
describes the rkinit protocol. Please copy it into the source
tree. I'd suggest /source/athena/usr.athena/rkinit/rkinit.tex.
Jay
======== rkinit.tex ========
\documentstyle[11pt]{article}
\raggedbottom
\setlength{\topmargin}{.5in}
\setlength{\headsep}{0in}
\setlength{\textwidth}{6.5in}
\setlength{\textheight}{8in}
\setlength{\parskip}{2ex}
\setlength{\oddsidemargin}{0in}
\setlength{\evensidemargin}{0in}
\setlength{\parindent}{2em}
\setlength{\unitlength}{1mm}
\begin{document}
\section{Overview}
In the current implementation of kerberos, there is no server
support for proxiable or forwardable tickets. It is often
necessary or convenient to have this functionality. {\em
rkinit}\/ is designed to satisfy this need.
{\em rkinit}\/ is implemented as a library and a server. A
sample client is provided, although the functionality of {\em
rkinit}\/ is available to a programmer with a single library
call.
com_err is used for error handling.
\section{Protocol}
The {\em rkinit}\/ protocol is based on top of TCP. There are
three stages to the communication between {\em rkinit}\/ and
{\em rkinitd}:
\begin{enumerate}
\item Establishment of version number.
Clients and servers can both support multiple versions of the
rkinit protocol. For this reason, the client and server must
first agree on a version to use for all transactions.
\item Delivery of information
The client must send to the server the information it needs in
order to create tickets. In version 3 of rkinit, this includes
the following:
\begin{itemize}
\item name, instance, and realm of principal for whom tickets
are to be obtained
\item name of local user on remote host who will own the ticket
file created
\item name of remote ticket file
\item lifetime of remote tickets
\end{itemize}
\item Exchange of authentication information and tickets
The rkinit server gets initial tickets for the principal
requested and sends those tickets back to the client for
decryption. The client decrypts the tickets and sends the
usable tickets along with an authenticator back to the server
encrypted in the session key for the transaction.
\end{enumerate}
Here is a more detailed discussion of the protocol from each
side.
\subsection{Rkinit client}
\begin{enumerate}
\item Send a range of version numbers supported to server and receive
the range of version numbers that can be supported by the
server. Choose the version according to an agreed upon
algorithm (discussed below).
\item Send the information packet (containing
name, instance, realm, etc.). The rkinit server responds with
the information it receives from kerberos (encrypted in the
principal's password) while making the initial ticket request.
\item Request initial tickets for the principal being requested on
the server with a hook that, in addition to decrypting the
packets from kerberos, decrypts the packet from the rkinit
server and saves the result. After the initial tickets have
been received, if failure, report giving up to the server, issue
an error message, and exit. If successful, build authenticator,
re-encrypt packets from rkinit server in session key, and send
both (together) back to the rkinit server. The rkinit server
responds with a success or failure message.
\end{enumerate}
\subsection{Rkinit server}
\item Receive version information from rkinit client and send
version information to client according to version choosing
protocol. Choose a version with the agreed upon algorithm.
\item Receive information packet from the
rkinit client. Request initial tickets for the principal sent in
the information packet with a decryption hook. This hook sends
the packet from kerberos to the rkinit client.
\item Receive either indication that the client gave up and exit
or receive an authenticator and the packet sent to the client
re-encrypted in the session key from the authenticator. Return
from hook and report status to rkinit client of obtaining
initial tickets.
\end{enumerate}
\subsection{Version Choosing}
Both client and server have copies of range of versions each
supports. The version that will be used is the maximum version
in the intersection of the two ranges. If the two ranges do not
intersect, an error should be flagged and the transaction should
be aborted.
\section{General comments}
rkinit error messages are handled by the routine
char *rkinit_errmsg(string)
which, when passed a non-zero argument, sets a static buffer to
the value of the error message and always returns the value of
the error message.
Thus, rather that sort out a huge number of
\section{Diagnostics}
Make sure relevant parts of krb configuration files match
between client and server. (Local realm is not relevant as long
as the two hosts can authenticate)
\end{document}
