Fix.

[shishi.git] / doc / shishi.texi

\input texinfo                  @c -*- Texinfo -*-
@c Copyright (C) 2002, 2003 Simon Josefsson
@c
@c This file is part of the shishi
@c Permission is granted to copy, distribute and/or modify this document
@c under the terms of the GNU Free Documentation License, Version 1.1
@c or any later version published by the Free Software Foundation;
@c with the Invariant Sections being with no Invariant Sections, with the
@c no Front-Cover Texts, and with the no Back-Cover Texts.
@c A copy of the license is included in the section entitled ``GNU
@c Free Documentation License'' in the file 'fdl.texi'.
@c
@setfilename shishi.info
@include version.texi
@settitle The Shishi Manual

@c Unify some of the indices.
@syncodeindex tp fn
@syncodeindex pg fn

@copying
This is @cite{The Shishi Manual}, last updated @value{UPDATED}, for
Version @value{VERSION} of Shishi.

Copyright @copyright{} 2002, 2003 Simon Josefsson.

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with the Front-Cover texts being ``A GNU Manual,''
and with the Back-Cover Texts as in (a) below.  A copy of the license
is included in the section entitled ``GNU Free Documentation
License.''

(a) The FSF's Back-Cover Text is: ``You have freedom to copy and
modify this GNU Manual, like GNU software.  Copies published by the
Free Software Foundation raise funds for GNU development.''
@end quotation
@end copying

@dircategory Net Utilities
@direntry
* shishi: (shishi).             A Kerberos 5 implementation
@end direntry

@titlepage
@title The Shishi Manual
@subtitle for version @value{VERSION}, @value{UPDATED}
@author Simon Josefsson (@email{bug-shishi@@josefsson.org})
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@contents

@ifnottex
@node Top
@top Shishi
@insertcopying
@end ifnottex

@menu
* Introduction::                How to use this manual.
* User Manual::                 Using Shishi as end-user.
* Administration Manual::       Administrating server aspects of Shishi.
* Reference Manual::            Detailed description of config files, etc.
* Programming Manual::          Calling Shishi from a programming language.
* Acknowledgements::            Whom to blame.

Appendices

* Copying This Manual::         How you can copy and share this manual.
* Copying::                     How you can copy and share the source.

Indices

* Concept Index::               Index of concepts and programs.
* Function and Data Index::     Index of functions, variables and data types.
@end menu


@c **********************************************************
@c ********************  Introduction  **********************
@c **********************************************************
@node Introduction
@chapter Introduction

Shishi implements the Kerberos 5 network security system.

@menu
* Getting Started::
* Features and Status::
* Overview::
* Cryptographic Overview::
* Supported Platforms::
* Downloading and Installing::
* Bug Reports::
* Contributing::
@end menu

@node Getting Started
@section Getting Started

This manual documents the Shishi application and library programming
interface.  All commands, functions and data types provided by Shishi
are explained.

The reader is assumed to possess basic familiarity with network
security and the Kerberos 5 security system.

This manual can be used in several ways.  If read from the beginning
to the end, it gives a good introduction into the library and how it
can be used in an application.  Forward references are included where
necessary.  Later on, the manual can be used as a reference manual to
get just the information needed about any particular interface of the
library.  Experienced programmers might want to start looking at the
examples at the end of the manual, and then only read up those parts
of the interface which are unclear.

@node Features and Status
@section Features and Status

Shishi might have a couple of advantages over other packages doing a
similar job.

@table @asis
@item It's Free Software
Anybody can use, modify, and redistribute it under the terms of the GNU
General Public License (@pxref{Copying}).

@item It's thread-safe
The library uses no global variables.

@item It's internationalized
It handles non-ASCII username and passwords and user visible strings
used in the library (error messages) can be translated into the users'
language.

@item It's portable
It should work on all Unix like operating systems, including Windows.

@end table

Shishi is far from feature complete, it is not even a full RFC 1510
implementation yet.  However, some basic functionality is implemented.
A few implemented feature are mentioned below.

@itemize @bullet

@item Initial authentication (AS) from raw key or password.
This step is typically used to acquire a ticket granting ticket and,
less commonly, a server ticket.

@item Subsequent authentication (TGS).
This step is typically used to acquire a server ticket, by
authenticating yourself using the ticket granting ticket.

@item Client-Server authentication (AP).
This step is used by clients and servers to prove to each other who
they are, using negotiated tickets.

@item Integrity protected communication (SAFE).
This step is used by clients and servers to exchange integrity
protected data with each other.  The key is typically agreed on using
the Client-Server authentication step.

@item Ticket cache, supporting multiple principals and realms.
As tickets have a life time of typically several hours, they are
managed in disk files.  There can be multiple ticket caches, and each
ticket cache can store tickets for multiple clients (users), servers,
encryption types, etc.  Functionality is provided for locating the
proper ticket for every use.

@item Most standard cryptographic primitives.
The believed most secure algorithms are supported
(@pxref{Cryptographic Overview}).

@item Telnet client and server.
This is used to remotely login to other machines, after authenticating
yourself with a ticket.

@item PAM module.
This is used to login locally on a machine.

@item KDC addresses located using DNS SRV RRs.

@end itemize

The following table summarize what the current objectives are (i.e.,
the todo list) and an estimate on how long it will take to implement
the feature.  If you like to start working on anything, please let me
know so work duplication can be avoided.

@itemize @bullet

@item Pre-authentication support (week).

@item Cross-realm support (week).

@item PKINIT (use libksba, weeks)

@item Finish GSSAPI support via GSSLib (weeks)
Shishi will not support GSSLib natively, but a separate project
``GSSLib'' is under way to produce a generic GSS implementation, and
it will use Shishi to implement the Kerberos 5 mechanism.

@item Port to cyclone (cyclone need to mature first)

@item Modularize ASN.1 library so it can be replaced (days).
Almost done, all ASN.1 functionality is found in lib/asn1.c, although
the interface is rather libtasn1 centric.

@item Modularize Crypto library so it can be replaced (days).
Nettle and libgcrypt are currently supported, but not via an abstract
interface.  All crypto operations has been isolated into
lib/crypto*.c.

@item KDC (initiated, weeks)

@item Set/Change password protocol (weeks?)

@item Port applications to use Shishi (indefinite)

@item Improve documentation

@item Improve internationalization

@item Add AP-REQ replay cache (week).

@item Study benefits by introducing a PA-TGS-REP.
This would provide mutual authentication of the KDC in a way that is
easier to analyze.  Currently the mutual authentication property is
only implicit from successful decryption of the KDC-REP and the 4 byte
nonce.

@end itemize

@node Overview
@section Overview

This section describes RFC 1510 from a protocol point of
view@footnote{The text is a lightly adapted version of the
introduction section from RFC 1510 by J. Kohl and C. Neuman, September
1993, unclear copyrights, but presumably owned by The Internet
Society.}.

Kerberos provides a means of verifying the identities of principals,
(e.g., a workstation user or a network server) on an open
(unprotected) network.  This is accomplished 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. (Note,
however, that many applications use Kerberos' functions only upon the
initiation of a stream-based network connection, and assume the
absence of any "hijackers" who might subvert such a connection.  Such
use implicitly trusts the host addresses involved.)  Kerberos performs
authentication under these conditions as a trusted third- party
authentication service by using conventional cryptography, i.e.,
shared secret key.  (shared secret key - Secret and 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 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 private key.)

The authentication process proceeds as follows: A client sends a
request to the authentication server (AS) requesting "credentials" for
a given server.  The AS responds with these credentials, encrypted in
the client's key.  The credentials consist of 1) a "ticket" for the
server and 2) a temporary encryption key (often called a "session
key").  The client transmits the ticket (which contains the client's
identity and a copy of the session key, all encrypted in the server's
key) to the server.  The session key (now shared by the client and
server) is used to authenticate the client, and may optionally be used
to authenticate the server.  It may also be used to encrypt further
communication between the two parties or to exchange a separate
sub-session key to be used to encrypt further communication.

The implementation consists of one or more authentication servers
running on physically secure hosts.  The authentication servers
maintain a database of principals (i.e., users and servers) and their
secret keys. Code libraries provide encryption and implement the
Kerberos protocol.  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 Kerberos protocol consists of several sub-protocols (or
exchanges).  There are two methods by which a client can ask a
Kerberos server for credentials.  In the first approach, the client
sends a cleartext request for a ticket for the desired server to the
AS. The reply is sent encrypted in the client's secret key. Usually
this request is for a ticket-granting ticket (TGT) which can later be
used with the ticket-granting server (TGS).  In the second method, the
client sends a request to the TGS.  The client sends the TGT to the
TGS in the same manner as if it were contacting any other application
server which requires Kerberos credentials.  The reply is encrypted in
the session key from the TGT.

Once obtained, credentials may be used to verify the identity of the
principals in a transaction, to ensure the integrity of messages
exchanged between them, or to preserve privacy of the messages.  The
application is free to choose whatever protection may be necessary.

To verify the identities of the principals in a transaction, the
client transmits the ticket to the server.  Since the ticket is sent
"in the clear" (parts of it are encrypted, but this encryption doesn't
thwart replay) and might be intercepted and reused by an attacker,
additional information is sent to prove that the message was
originated by the principal to whom the ticket was issued.  This
information (called the authenticator) is encrypted in the session
key, and includes a timestamp.  The timestamp proves that the message
was recently generated and is not a replay.  Encrypting the
authenticator in the session key proves that it was generated by a
party possessing the session key.  Since no one except the requesting
principal and the server know the session key (it is never sent over
the network in the clear) this guarantees the identity of the client.

The integrity of the messages exchanged between principals can also be
guaranteed using the session key (passed in the ticket and contained
in the credentials).  This approach provides detection of both replay
attacks and message stream modification attacks.  It is accomplished
by generating and transmitting a collision-proof checksum (elsewhere
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 by encrypting the data to be passed
using the session key passed in the ticket, and contained in the
credentials.

@node Cryptographic Overview
@section Cryptographic Overview

Shishi implements several of the standard cryptographic primitives.
Here are the names of the supported encryption suites, with some notes
on their status and there associated checksum suite.  They are ordered
by increased security as perceived by the author.

@cindex DES
@cindex 3DES
@cindex AES

@table @code

@item NULL

@code{NULL} is a dummy encryption suite for debugging.  Encryption and
decryption are identity functions.  No integrity protection.  It is
weak.  It is associated with the @code{NULL} checksum.

@item des-cbc-crc

@code{des-cbc-crc} is DES encryption and decryption with 56 bit keys
and 8 byte blocks in CBC mode. The keys can be derived from passwords
by an obscure application specific algorithm. Data is integrity
protected with an unkeyed but encrypted @code{CRC32}-like checksum.
It is weak. It is associated with the @code{rsa-md5-des} checksum.

@item des-cbc-md4

@code{des-cbc-md4} is DES encryption and decryption with 56 bit keys
and 8 byte blocks in CBC mode. The keys can be derived from passwords
by an obscure application specific algorithm. Data is integrity
protected with an unkeyed but encrypted MD4 hash.  It is weak. It is
associated with the @code{rsa-md4-des} checksum.

@item des-cbc-md5

@code{des-cbc-md5} is DES encryption and decryption with 56 bit keys
and 8 byte blocks in CBC mode.  The keys can be derived from passwords
by an obscure application specific algorithm. Data is integrity
protected with an unkeyed but encrypted MD5 hash.  It is weak.  It is
associated with the @code{rsa-md5-des} checksum.  This is the
strongest RFC 1510 interoperable mechanism.

@item des3-cbc-sha1-kd

@code{des3-cbc-sha1-kd} is DES encryption and decryption with three 56
bit keys (effective key size 112 bits) and 8 byte blocks in CBC
mode. The keys can be derived from passwords by a algorithm based on
the paper "A Better Key Schedule For DES-like Ciphers"
@footnote{@url{http://www.research.att.com/~smb/papers/ides.pdf}} by
Uri Blumenthal and Steven M. Bellovin (it is not clear if the
algorithm, and the way it is used, is used by any other protocols,
although it seems unlikely).  Data is integrity protected with a keyed
SHA1 hash in HMAC mode.  It has no security proof, but is assumed to
provide adequate security in the sense that knowledge on how to crack
it is not known to the public.  Note that the key derivation function
is not widely used outside of Kerberos, hence not widely studied.  It
is associated with the @code{hmac-sha1-des3-kd} checksum.

@item aes128-cts-hmac-sha1-96
@item aes256-cts-hmac-sha1-96.

@code{aes128-cts-hmac-sha1-96} and @code{aes256-cts-hmac-sha1-96} is
AES encryption and decryption with 128 bit and 256 bit key,
respectively, and 16 byte blocks in CBC mode with Cipher Text
Stealing.  Cipher Text Stealing means data length of encrypted data is
preserved (pure CBC add up to 7 pad characters).  The keys can be
derived from passwords with RSA Laboratories PKCS#5 Password Based Key
Derivation Function
2@footnote{@url{http://www.rsasecurity.com/rsalabs/pkcs/pkcs-5/}},
which is allegedly provably secure in a random oracle model.  Data is
integrity protected with a keyed SHA1 hash, in HMAC mode, truncated to
96 bits.  There is no security proof, but the schemes are assumed to
provide adequate security in the sense that knowledge on how to crack
them is not known to the public.  Note that AES has yet to receive the
test of time, and the CBC variation used is not widely standardized
(hence not widely studied).  It is associated with the
@code{hmac-sha1-96-aes128} and @code{hmac-sha1-96-aes256} checksums,
respectively.

@end table

The protocol do not include any way to negotiate which checksum
mechanisms to use, so in most cases the associated checksum will be
used.  However, checksum mechanisms can be used with other encryption
mechanisms, as long as they are compatible in terms of key format etc.
Here are the names of the supported checksum mechanisms, with some
notes on their status and the compatible encryption mechanisms. They
are ordered by increased security as perceived by the author.

@table @code

@item NULL

@code{NULL} is a dummy checksum suite for debugging.  It provides no
integrity.  It is weak.  It is compatible with the @code{NULL}
encryption mechanism.

@item rsa-md4

@code{rsa-md4} is a unkeyed MD4 hash computed over the message.  Since
it is unkeyed, it is in general a weak checksum, however applications
can, with care, use it non-weak ways (e.g., by including the hash in
other messages that are encrypted or checksummed).  It is compatible
with all encryption mechanisms.

@item rsa-md4-des

@code{rsa-md4-des} is a DES CBC encryption of one block of random data
and a unkeyed MD4 hash computed over the random data and the message
to integrity protect.  The key used is derived from the base protocol
key by XOR with a constant.  It is weak. It is compatible with the
@code{des-cbc-crc}, @code{des-cbc-md4}, @code{des-cbc-md5} encryption
mechanisms.

@item rsa-md5

@code{rsa-md5} is a unkeyed MD5 hash computed over the message.  Since
it is unkeyed, it is in general a weak checksum, however applications
can, with care, use it non-weak ways (e.g., by including the hash in
other messages that are encrypted or checksummed).  It is compatible
with all encryption mechanisms.

@item rsa-md5-des

@code{rsa-md5-des} is a DES CBC encryption of one block of random data
and a unkeyed MD5 hash computed over the random data and the message
to integrity protect.  The key used is derived from the base protocol
key by XOR with a constant.  It is weak.  It is compatible with the
@code{des-cbc-crc}, @code{des-cbc-md4}, @code{des-cbc-md5} encryption
mechanisms.

@item hmac-sha1-des3-kd

@code{hmac-sha1-des3-kd} is a keyed SHA1 hash in HMAC mode computed
over the message.  The key is derived from the base protocol by the
simplified key derivation function (similar to the password key
derivation functions of @code{des3-cbc-sha1-kd}).  It has no security
proof, but is assumed to provide good security, if the key derivation
function is good.  It is compatible with the @code{des3-cbc-sha1-kd}
encryption mechanism.

@item hmac-sha1-96-aes128
@item hmac-sha1-96-aes256

@code{hmac-sha1-96-aes*} are keyed SHA1 hashes in HMAC mode computed
over the message and then truncated to 96 bits.  The key is derived
from the base protocol by the simplified key derivation function
(similar to the password key derivation functions of
@code{des3-cbc-sha1-kd}).  It has no security proof, but is assumed to
provide good security, if the key derivation function is good.  It is
compatible with the @code{aes*-cts-hmac-sha1-96} encryption
mechanisms.

@end table


@node Supported Platforms
@section Supported Platforms

Shishi has at some point in time been tested on the following
platforms.  Online build reports for each platforms and Shishi version
is available at @url{http://josefsson.org/autobuild/}.

@enumerate

@item Debian GNU/Linux 3.0 (Woody)
@cindex Debian

GCC 2.95.4 and GNU Make. This is the main development platform.
@code{alphaev67-unknown-linux-gnu}, @code{alphaev6-unknown-linux-gnu},
@code{arm-unknown-linux-gnu}, @code{armv4l-unknown-linux-gnu},
@code{hppa-unknown-linux-gnu}, @code{hppa64-unknown-linux-gnu},
@code{i686-pc-linux-gnu}, @code{ia64-unknown-linux-gnu},
@code{m68k-unknown-linux-gnu}, @code{mips-unknown-linux-gnu},
@code{mipsel-unknown-linux-gnu}, @code{powerpc-unknown-linux-gnu},
@code{s390-ibm-linux-gnu}, @code{sparc-unknown-linux-gnu},
@code{sparc64-unknown-linux-gnu}.

@item Debian GNU/Linux 2.1
@cindex Debian

GCC 2.95.4 and GNU Make. @code{armv4l-unknown-linux-gnu}.

@item Tru64 UNIX
@cindex Tru64

Tru64 UNIX C compiler and Tru64 Make. @code{alphaev67-dec-osf5.1},
@code{alphaev68-dec-osf5.1}.

@item SuSE Linux 7.1
@cindex SuSE

GCC 2.96 and GNU Make. @code{alphaev6-unknown-linux-gnu},
@code{alphaev67-unknown-linux-gnu}.

@item SuSE Linux 7.2a
@cindex SuSE Linux

GCC 3.0 and GNU Make. @code{ia64-unknown-linux-gnu}.

@item SuSE Linux
@cindex SuSE Linux

GCC 3.2.2 and GNU Make.  @code{x86_64-unknown-linux-gnu} (AMD64
Opteron ``Melody'').

@item RedHat Linux 7.2
@cindex RedHat

GCC 2.96 and GNU Make. @code{alphaev6-unknown-linux-gnu},
@code{alphaev67-unknown-linux-gnu}, @code{ia64-unknown-linux-gnu}.

@item RedHat Linux 8.0
@cindex RedHat

GCC 3.2 and GNU Make. @code{i686-pc-linux-gnu}.

@item RedHat Advanced Server 2.1
@cindex RedHat Advanced Server

GCC 2.96 and GNU Make. @code{i686-pc-linux-gnu}.

@item Slackware Linux 8.0.01
@cindex RedHat

GCC 2.95.3 and GNU Make. @code{i686-pc-linux-gnu}.

@item Mandrake Linux 9.0
@cindex Mandrake

GCC 3.2 and GNU Make. @code{i686-pc-linux-gnu}.

@item IRIX 6.5
@cindex IRIX

MIPS C compiler, IRIX Make. @code{mips-sgi-irix6.5}.

@item AIX 4.3.2
@cindex AIX

IBM C for AIX compiler, AIX Make.  @code{rs6000-ibm-aix4.3.2.0}.

@c @item Microsoft Windows 2000 (Cygwin)
@c @cindex Windows
@c
@c GCC 3.2, GNU make. @code{i686-pc-cygwin}.

@item HP-UX 11
@cindex HP-UX

HP-UX C compiler and HP Make. @code{ia64-hp-hpux11.22},
@code{hppa2.0w-hp-hpux11.11}.

@item SUN Solaris 2.8
@cindex Solaris

Sun WorkShop Compiler C 6.0 and SUN Make. @code{sparc-sun-solaris2.8}.

@item NetBSD 1.6
@cindex NetBSD

GCC 2.95.3 and GNU Make. @code{alpha-unknown-netbsd1.6},
@code{i386-unknown-netbsdelf1.6}.

@item OpenBSD 3.1 and 3.2
@cindex OpenBSD

GCC 2.95.3 and GNU Make. @code{alpha-unknown-openbsd3.1},
@code{i386-unknown-openbsd3.1}.

@item FreeBSD 4.7 and 4.8
@cindex FreeBSD

GCC 2.95.4 and GNU Make. @code{alpha-unknown-freebsd4.7},
@code{alpha-unknown-freebsd4.8}, @code{i386-unknown-freebsd4.7},
@code{i386-unknown-freebsd4.8}.

@end enumerate

If you use Shishi on, or port Shishi to, a new platform please report
it to the author (@pxref{Bug Reports}).

@node Downloading and Installing
@section Downloading and Installing
@cindex Installation
@cindex Download

The package can be downloaded from several places, including
@url{http://josefsson.org/shishi/releases/}.  The latest version is
stored in a file, e.g., @samp{shishi-0.0.42.tar.gz} where the
@samp{0.0.42} indicate the highest version number.

The package is then extracted, configured and built like many other
packages that use Autoconf.  For detailed information on configuring
and building it, refer to the @file{INSTALL} file that is part of the
distribution archive.

Here is an example terminal session that download, configure, build
and install the package.  You will need a few basic tools, such as
@samp{sh}, @samp{make} and @samp{cc}.

@example
$ wget -q http://josefsson.org/shishi/releases/shishi-0.0.4.tar.gz
$ tar xfz shishi-0.0.4.tar.gz
$ cd shishi-0.0.4/
$ ./configure
...
$ make
...
$ make install
...
@end example

After this you should be prepared to continue with the user,
administration or programming manual, depending on how you want to use
Shishi.

@node Bug Reports
@section Bug Reports
@cindex Reporting Bugs

If you think you have found a bug in Shishi, please investigate it and
report it.

@itemize @bullet

@item Please make sure that the bug is really in Shishi, and
preferably also check that it hasn't already been fixed in the latest
version.

@item You have to send us a test case that makes it possible for us to
reproduce the bug.

@item You also have to explain what is wrong; if you get a crash, or
if the results printed are not good and in that case, in what way.
Make sure that the bug report includes all information you would need
to fix this kind of bug for someone else.

@end itemize

Please make an effort to produce a self-contained report, with
something definite that can be tested or debugged.  Vague queries or
piecemeal messages are difficult to act on and don't help the
development effort.

If your bug report is good, we will do our best to help you to get a
corrected version of the software; if the bug report is poor, we won't
do anything about it (apart from asking you to send better bug
reports).

If you think something in this manual is unclear, or downright
incorrect, or if the language needs to be improved, please also send a
note.

Send your bug report to:

@center @samp{bug-shishi@@josefsson.org}

@node Contributing
@section Contributing
@cindex Contributing
@cindex Hacking

If you want to submit a patch for inclusion -- from solve a typo you
discovered, up to adding support for a new feature -- you should
submit it as a bug report (@pxref{Bug Reports}).  There are some
things that you can do to increase the chances for it to be included
in the official package.

Unless your patch is very small (say, under 10 lines) we require that
you assign the copyright of your work to the Free Software Foundation.
This is to protect the freedom of the project.  If you have not
already signed papers, we will send you the necessary information when
you submit your contribution.

For contributions that doesn't consist of actual programming code, the
only guidelines are common sense.  Use it.

For code contributions, a number of style guides will help you:

@itemize @bullet

@item Coding Style.
Follow the GNU Standards document (@pxref{top, GNU Coding Standards,,
standards}).

If you normally code using another coding standard, there is no
problem, but you should use @samp{indent} to reformat the code
(@pxref{top, GNU Indent,, indent}) before submitting your work.

@item Use the unified diff format @samp{diff -u}.

@item Return errors.
The only valid reason for ever aborting the execution of the program
is due to memory allocation errors, but for that you should call
@samp{xalloc_die} to allow the application to recover if it wants to.

@item Design with thread safety in mind.
Don't use global variables.  Don't even write to per-handle global
variables unless the documented behaviour of the function you write is
to write to the per-handle global variable.

@item Avoid using the C math library.
It causes problems for embedded implementations, and in most
situations it is very easy to avoid using it.

@item Document your functions.
Use comments before each function headers, that, if properly
formatted, are extracted into Texinfo manuals and GTK-DOC web pages.

@item Supply a ChangeLog and NEWS entries, where appropriate.

@end itemize

@c **********************************************************
@c ********************  User Manual  **********************
@c **********************************************************
@node User Manual
@chapter User Manual
@cindex End-user Shishi usage

Usually Shishi interacts with you to get some initial authentication
information like a password, and then contacts a server to receive a
so called ticket granting ticket.  From now on, you rarely interacts
with Shishi directly.  Applications that needs security services
instruct the Shishi library to use the ticket granting ticket to get
new tickets for various servers.  An example could be if you log on to
a host remotely via @samp{telnet}.  The host usually requires
authentication before permitting you in.  The @samp{telnet} client
uses the ticket granting ticket to get a ticket for the server, and
then use this ticket to authenticate you against the server (typically
the server is also authenticated to you).  You perform the initial
authentication by typing @command{shishi} at the prompt.  Sometimes it
is necessary to supply options telling Shishi what your principal name
(user name in the Kerberos realm) or realm is.  In the example, I
specify the client name @code{simon@@JOSEFSSON.ORG}.

@example
@cartouche
$ shishi simon@@JOSEFSSON.ORG
Enter password for `simon@@JOSEFSSON.ORG':
simon@@JOSEFSSON.ORG:
Authtime:       Fri Aug 15 04:44:49 2003
Endtime:        Fri Aug 15 05:01:29 2003
Server:         krbtgt/JOSEFSSON.ORG key des3-cbc-sha1-kd (16)
Ticket key:     des3-cbc-sha1-kd (16) protected by des3-cbc-sha1-kd (16)
Ticket flags:   INITIAL (512)
$ 
@end cartouche
@end example

As you can see, Shishi also prints a short description of the ticket
received.

A logical next step is to display all tickets you have received (by
the way, the tickets are usually stored as text in
@file{~/.shishi/tickets}).  This is achieved by typing @command{shishi
--list}.

@example
@cartouche
$ shishi --list
Tickets in `/home/jas/.shishi/tickets':
                                                                                
jas@@JOSEFSSON.ORG:
Authtime:       Fri Aug 15 04:49:46 2003
Endtime:        Fri Aug 15 05:06:26 2003
Server:         krbtgt/JOSEFSSON.ORG key des-cbc-md5 (3)
Ticket key:     des-cbc-md5 (3) protected by des-cbc-md5 (3)
Ticket flags:   INITIAL (512)
                                                                                
jas@@JOSEFSSON.ORG:
Authtime:       Fri Aug 15 04:49:46 2003
Starttime:      Fri Aug 15 04:49:49 2003
Endtime:        Fri Aug 15 05:06:26 2003
Server:         host/latte.josefsson.org key des-cbc-md5 (3)
Ticket key:     des-cbc-md5 (3) protected by des-cbc-md5 (3)
                                                                                
2 tickets found.
$
@end cartouche
@end example

As you can see, I had a ticket for the server
@samp{host/latte.josefsson.org} which was generated by
@samp{telnet}:ing to that host.

If, for some reason, you want to manually get a ticket for a specific
server, you can use the @command{shishi --server-name} command.
Normally, however, the application that uses Shishi will take care of
getting a ticket for the appropriate server, so you normally wouldn't
need this command.

@example
@cartouche
$ shishi --server-name=user/billg --encryption-type=des-cbc-md4
jas@@JOSEFSSON.ORG:
Authtime:       Fri Aug 15 04:49:46 2003
Starttime:      Fri Aug 15 04:54:33 2003
Endtime:        Fri Aug 15 05:06:26 2003
Server:         user/billg key des-cbc-md4 (2)
Ticket key:     des-cbc-md4 (2) protected by des-cbc-md5 (3)
$
@end cartouche
@end example

As you can see, I acquired a ticket for @samp{user/billg} with a
@samp{des-cbc-md4} (@pxref{Cryptographic Overview}) encryption key
specified with the @samp{--encryption-type} parameter.

To wrap up this introduction, lets see how you can remove tickets.
You may want to do this if you leave your terminal for lunch or
similar, and don't want someone to be able to copy the file and then
use your credentials.  Note that this only destroy the tickets
locally, it does not contact any server and tell it that these
credentials are no longer valid.  So if someone stole your ticket
file, you must contact your administrator and have them reset your
account, simply using this parameter is not sufficient.

@example
@cartouche
$ shishi --server-name=imap/latte.josefsson.org --destroy
1 ticket removed.
$ shishi --server-name=foobar --destroy
No tickets removed.
$ shishi --destroy
3 tickets removed.
$
@end cartouche
@end example

Since the @samp{--server-name} parameter takes a long to type, it is
possible to type the server name directly, after the client name.  The
following example demonstrate a AS-REQ followed by a TGS-REQ for a
specific server (assuming you did not have any tickets from the
start).

@example
@cartouche
$ src/shishi simon@@latte.josefsson.org imap/latte.josefsson.org
Enter password for `simon@@latte.josefsson.org':
simon@@latte.josefsson.org:
Acquired:       Wed Aug 27 17:21:06 2003
Expires:        Wed Aug 27 17:37:46 2003
Server:         imap/latte.josefsson.org key aes256-cts-hmac-sha1-96 (18)
Ticket key:     aes256-cts-hmac-sha1-96 (18) protected by aes256-cts-hmac-sha1-96 (18)
Ticket flags:   FORWARDED PROXIABLE (12)
$
@end cartouche
@end example

Refer to the reference manual for all available parameters
(@pxref{Parameters for shishi}).

@c **********************************************************
@c ****************  Administration Manual  *****************
@c **********************************************************
@node Administration Manual
@chapter Administration Manual

This section describe how you get the KDC server up and running to
answer queries from clients.

First you must create a user database.  Currently this is rather
simplistic, and the database only contains cryptographic keys.  Use
the @samp{shishi --string-to-key} command to generate keys, and store
them in the @file{shishid.keys} file.  The file path is
@file{/usr/local/etc/shishid.keys} by default, although you can use
@samp{shishid -k} to specify another location.

Create a random key for the Kerberos Ticket Granting Service for your
realm:

@example
@cartouche
$ shishi --string-to-key --random \
krbtgt/latte.josefsson.org@@latte.josefsson.org | \
tee /usr/local/etc/shishid.keys
-----BEGIN SHISHI KEY-----
Keytype: 18 (aes256-cts-hmac-sha1-96)
Principal: krbtgt/latte.josefsson.org
Realm: latte.josefsson.org

oconxMTf59B5bvTylY+KE4mchA/gtmYI2Qok+48tnSM=
-----END SHISHI KEY-----
$
@end cartouche
@end example

Create a key for a user from a specified password:

@example
@cartouche
$ shishi --string-to-key=fnord \
simon@@latte.josefsson.org | tee --append \
/usr/local/etc/shishid.keys
-----BEGIN SHISHI KEY-----
Keytype: 18 (aes256-cts-hmac-sha1-96)
Principal: simon
Realm: latte.josefsson.org

c1rqwvYwuDFrABvqWVq9bWUsQWg/xbErsIUmLN+3lYM=
-----END SHISHI KEY-----
$
@end cartouche
@end example

There is nothing special with a ticket granting key, you could have
created it based on a password similar to the user key.  However,
please keep in mind that passwords typically have little entropy.

Finally, create a random key for a service:

@example
@cartouche
$ shishi --string-to-key --random \
imap/latte.josefsson.org@@latte.josefsson.org | \
tee --append /usr/local/etc/shishid.keys
-----BEGIN SHISHI KEY-----
Keytype: 18 (aes256-cts-hmac-sha1-96)
Principal: imap/latte.josefsson.org
Realm: latte.josefsson.org

ts2v0QHWyW9FyXbWtCvLPqdEc60qPq5Yvat3p82rp5c=
-----END SHISHI KEY-----
$
@end cartouche
@end example

You are now ready to start the KDC.  Refer to the reference manual for
available parameters (@pxref{Parameters for shishid}).

@example
@cartouche
$ shishid
@end cartouche
@end example

Then you can use @samp{shishi} as usual to acquire tickets
(@pxref{User Manual}).  The following example demonstrate a AS-REQ for
@samp{krbtgt/latte.josefsson.org} followed by a TGS-REQ for
@samp{imap/latte.josefsson.org}.

@example
@cartouche
$ shishi simon@@latte.josefsson.org imap/latte.josefsson.org
Enter password for `simon@@latte.josefsson.org':
simon@@latte.josefsson.org:
Acquired:       Wed Aug 27 17:16:37 2003
Expires:        Wed Aug 27 17:33:17 2003
Server:         imap/latte.josefsson.org key aes256-cts-hmac-sha1-96 (18)
Ticket key:     aes256-cts-hmac-sha1-96 (18) protected by aes256-cts-hmac-sha1-96 (18)
Ticket flags:   FORWARDED PROXIABLE (12)
$
@end cartouche
@end example

@c **********************************************************
@c ****************  Reference Manual  **********************
@c **********************************************************
@node Reference Manual
@chapter Reference Manual

This chapter describes in high detail all parameters, configuration
file verbs, etc.

@menu
* Configuration file::          Meaning of tokens used in configuration file.
* Parameters for shishi::       Command line parameters for 'shishi'.
* Parameters for shishid::      Command line parameters for 'shishid'.
@end menu

@node Configuration file
@section Configuration file

The valid configuration file tokens are described here.  The user
configuration file is typically located in
@file{~/.shishi/shishi.conf} (compare @samp{shishi
--configuration-file}) and the system configuration is typicall
located in @file{/usr/local/etc/shishi.conf}.  All tokens are valid in
both files, and have the same meaning.  However, as the system file is
supposed to apply to all users on a system, it would not make sense to
use some tokens in both files.  For example, the
@samp{default-principal} is rarely useful in a system configuration
file.

@subsection @samp{default-realm}
Specify the default realm, by default the hostname of the host is
used.  E.g.,

@example
default-realm JOSEFSSON.ORG
@end example

@subsection @samp{default-principal}

Specify the default principal, by default the login username is
used. E.g.,

@example
default-principal jas
@end example

@subsection @samp{client-kdc-etypes}

Specify which encryption types client asks server to respond in during
AS/TGS exchanges. List valid encryption types, in preference order.
Supported algorithms include aes256-cts-hmac-sha1-96,
aes128-cts-hmac-sha1-96, des3-cbc-sha1-kd, des-cbc-md5, des-cbc-md4,
des-cbc-crc and null.  This option also indicates which encryption
types are accepted by the client when receiving the response.  Note
that the preference order is not cryptographically protected, so a man
in the middle can modify the order without being detected.  Thus, only
specify encryption types you trust completely here. The default only
includes aes256-cts-hmac-sha1-96, as suggested by RFC1510bis.  E.g.,

@example
client-kdc-etypes=aes256-cts-hmac-sha1-96 des3-cbc-sha1-kd des-cbc-md5
@end example

@subsection @samp{verbose}, @samp{verbose-asn1}, @samp{verbose-noice}, @samp{verbose-crypto}

Enable verbose library messages.  E.g.,

@example
verbose
verbose-noice
@end example

@subsection @samp{realm-kdc}

Specify KDC addresses for realms.  Value is
@samp{REALM,KDCADDRESS[/PROTOCOL][,KDCADDRESS[/PROTOCOL]...]}.

KDCADDRESS is the hostname or IP address of KDC.

Optional PROTOCOL is udp for UDP, tcp for TCP, and TLS for TLS
connections.  By default UDP is tried first, and TCP used as a
fallback if the KRB_ERR_RESPONSE_TOO_BIG error is received.

If not specified, Shishi tries to locate the KDC using SRV RRs,
which is recommended.  This option should normally only be
used during experiments, or to access badly maintained realms.

@example
realm-kdc=JOSEFSSON.ORG,ristretto.josefsson.org
@end example

@subsection @samp{server-realm}

Specify realm for servers. Value is
@samp{REALM,SERVERREGEXP[,SERVERREGEXP...]}.

SERVERREGEXP is a regular expression matching servers in the realm.
The first match is used.  E.g.,

@example
server-realm=JOSEFSSON.ORG,.josefsson.org
@end example

Note: currently not used.

@subsection @samp{kdc-timeout}, @samp{kdc-retries}

How long shishi waits for a response from a KDC before continuing to
next KDC for realm.  The default is 5 seconds.  E.g.,

@example
kdc-timeout=10
@end example

How many times shishi sends a request to a KDC before giving up.  The
default is 3 times.  E.g.,

@example
kdc-retries=5
@end example

@subsection @samp{stringprocess}

How username and passwords entered from the terminal, or taken from
the command line, are processed.

"none": no processing is used.

"stringprep": convert from locale charset to UTF-8 and process using
              experimental RFC 1510 stringprep profile.

It can also be a string indicating a character set supported by
iconv() via libstringprep, in which case data is converted from locale
charset into the indicated character set. E.g., UTF-8, ISO-8859-1,
KOI-8, EBCDIC-IS-FRISS are supported on GNU systems.  On some systems
you can use "locale -m" to list available character sets.  By default,
the "none" setting is used which is consistent with RFC 1510 that is
silent on the issue.  In practice, however, converting to UTF-8
improves interoperability.

E.g.,

@example
stringprocess=UTF-8
@end example

@subsection @samp{ticket-life}
Specify default ticket life time.

The string can be in almost any common format.  It can contain month
names, time zones, `am' and `pm', `yesterday', `ago', `next', etc.
Refer to the "Date input formats" in the GNU CoreUtils package for
entire story (@pxref{Date input formats, ,Date input formats,
coreutils, GNU CoreUtils}).  As an extra feature, if the resulting
string you specify has expired within the last 24 hours, an extra day
is added to it.  This allows you to specify "17:00" to always mean the
next 17:00, even if your system clock happens to be 17:30.

The default is 8 hours.

E.g.,

@example
#ticket-life=8 hours
#ticket-life=1 day
ticket-life=17:00
@end example

@subsection @samp{renew-life}

Specify how long a renewable ticket should remain renewable.

See ticket-life for the syntax.  The extra feature that handles
negative values within the last 2 hours is not active here.

The default is 7 days.

E.g.,

@example
#renew-life=1 week
#renew-life=friday 17:00
renew-life=sunday
@end example

@node Parameters for shishi
@section Parameters for shishi

If no command is given, Shishi try to make sure you have a ticket
granting ticket for the default realm, and then display it.

Mandatory or optional arguments to long options are also mandatory or optional
for any corresponding short options.

@example
Usage: lt-shishi [OPTION...] [CLIENT [SERVER]] [OPTION...]
  or:  lt-shishi [OPTION...] --list [CLIENT [SERVER]]
  or:  lt-shishi [OPTION...] --destroy [CLIENT [SERVER]]
  or:  lt-shishi [OPTION...] --string-to-key
  or:  lt-shishi [OPTION...]

      --client-name=NAME     Client name. Default is login username. Only for
                             AS.
  -d, --destroy              Destroy tickets in local cache, subject to
                             --server-name limiting.
  -e, --endtime=STRING       Specify when ticket validity should expire.  The
                             time syntax may be relative (to the start time),
                             such as "20 hours", or absolute, such as
                             "2001-02-03 04:05:06 CET". The default is 8 hours
                             after the start time.
  -E, --encryption-type=ETYPE,[ETYPE...]
                             Encryption types to use.  ETYPE is either
                             registered name or integer.
      --force-as             Force AS mode. Default is to use TGS iff a TGT is
                             found.
      --force-tgs            Force TGS mode. Default is to use TGS iff a TGT is
                             found.
      --key-value=KEY        Cipher key to decrypt response (discouraged).
  -l, --list                 List tickets in local cache, subject to
                             --server-name limiting.
      --realm=REALM          Realm of server. Default is DNS domain of local
                             host. For AS, this also indicates realm of
                             client.
      --renew-till=STRING    Specify renewable life of ticket.  Implies
                             --renewable.  Accepts same time syntax as
                             --endtime.  If --renewable is specified, the
                             default is 1 week after the start time.
      --renewable            Get a renewable ticket.
  -R, --renew                Renew ticket.  Use --server-name to specify
                             ticket, default is the most recent renewable
                             ticket granting ticket for the default realm.
      --server=[FAMILY:]ADDRESS:SERVICE/TYPE
                             Send all requests to HOST instead of using normal
                             logic to locate KDC addresses (discouraged).
      --server-name=NAME     Server name. Default is "krbtgt/REALM" where REALM
                             is server realm (see --realm).
  -s, --starttime=STRING     Specify when ticket should start to be valid.
                             Accepts same time syntax as --endtime. The default
                             is to become valid immediately.
      --ticket-granter=NAME  Service name in ticket to use for authenticating
                             request. Only for TGS. Defaults to
                             "krbtgt/REALM@@REALM" where REALM is server realm
                             (see --realm).

 Options for low-level cryptography (CRYPTO-OPTIONS):
      --client-name=NAME     Username. Default is login name.
      --key-value=KEY        Base64 encoded key value.
      --key-version=INTEGER  Version number of key.
      --parameter=STRING     String-to-key parameter to use when --password is
                             specified. This data is specific for each
                             encryption algorithm and rarely needed.
      --password=PASSWORD    Password used to generate key (discouraged).
      --random               Generate key from random data.
      --realm=REALM          Realm of principal. Defaults to DNS domain of
                             local host.
      --salt=SALT            Salt to use for --string-to-key. Defaults to
                             concatenation of realm and (unwrapped) client
                             name.
      --string-to-key[=[PASSWORD]]
                             Convert password into Kerberos key.  Note that
                             --client-name, --realm, and --salt influence the
                             generated key.
      --write-key-file=FILE  Append cipher key to FILE

 Other options:
      --configuration-file=FILE   Read user configuration from file.  Default
                             is ~/.shishi/config.
  -c, --ticket-file=FILE     Read tickets from FILE. Default is
                             $HOME/.shishi/tickets.
  -o, --library-options=STRING   Parse STRING as a configuration file
                             statement.
  -q, --quiet, --silent      Don't produce any output.
      --system-configuration-file=FILE
                             Read system wide configuration from file.  Default
                             is /usr/local/etc/shishi.conf.
      --ticket-write-file=FILE   Write tickets to FILE.  Default is to write
                             them back to ticket file.
  -v, --verbose              Produce verbose output.
      --verbose-library      Produce verbose output in the library.
  CLIENT                     Set client name and realm from NAME.  The
                             --client-name and --realm parameters can be used
                             to override part of NAME.
  SERVER                     Set server name and realm from NAME.  The
                             --server-name and --server-realm parameters can be
                             used to override part of SERVER.

  -?, --help                 Give this help list
      --usage                Give a short usage message
  -V, --version              Print program version
@end example

@node Parameters for shishid
@section Parameters for shishid

If no parameters are specified, @samp{shishid} listens on the defaults
interfaces and answers incoming requests using the keys in the default
key file.

Mandatory or optional arguments to long options are also mandatory or optional
for any corresponding short options.

@example
  -c, --configuration-file=FILE   Read configuration from file.  Default is
                             /usr/local/etc/shishi.conf.
  -k, --key-file=FILE        Read keys from file.  Default is
                             /usr/local/etc/shishid.keys.
  -l, --listen=[FAMILY:]ADDRESS:SERVICE/TYPE,...
                             What to listen on. Family is "IPv4" or "IPv6", if
                             absent the family is decided by
                             gethostbyname(ADDRESS). An address of "*"
                             indicates all addresses on the local host. The
                             default is "IPv4:*:kerberos/udp,
                             IPv4:*:kerberos/tcp, IPv6:*:kerberos/udp,
                             IPv6:*:kerberos/tcp".
  -q, -s, --quiet, --silent  Don't produce any output.
  -u, --setuid=NAME          After binding socket, set user identity.
  -v, --verbose              Produce verbose output.
  -?, --help                 Give this help list
      --usage                Give a short usage message
  -V, --version              Print program version
@end example

@c **********************************************************
@c ***************  Programming Manual  *********************
@c **********************************************************
@node Programming Manual
@chapter Programming Manual
@cindex Application Programming Interface (API)

This chapter describes all the publicly available functions in the
library.

@menu
* Preparation::                 What you should do before using the library.
* Initialization Functions::    Creating library handle, configuration file.
* Ticket Set Functions::        High-level ticket management functions.
* AP-REQ and AP-REP Functions:: Client/Server authentication functions.
* SAFE and PRIV Functions::     Client/Server session data functions.
* Ticket Functions::            Medium-level ticket manipulation functions.
* AS Functions::                Medium-level initial authentication functions.
* TGS Functions::               Medium-level authentication functions.
* Ticket (ASN.1) Functions::    Low-level Ticket functions.
* AS/TGS Functions::            Low-level KDC functions; AS and TGS.
* Authenticator Functions::     Low-level authenticator functions.
* Cryptographic Functions::     Low-level cryptographic functions.
* Utility Functions::           Utilities for use in the global context.
* Error Handling::              Error codes and such.
* Examples::                    Example code.
* Generic Security Service::    If you want to use the GSS API instead.
@end menu

@node Preparation
@section Preparation

To use `Libshishi', you have to perform some changes to your sources
and the build system.  The necessary changes are small and explained
in the following sections.  At the end of this chapter, it is
described how the library is initialized, and how the requirements of
the library are verified.

A faster way to find out how to adapt your application for use with
`Libshishi' may be to look at the examples at the end of this manual
(@pxref{Examples}).

@menu
* Header::
* Initialization::
* Version Check::
* Building the source::
* Autoconf tests::
@end menu

@node Header
@subsection Header

All interfaces (data types and functions) of the library are defined
in the header file `shishi.h'.  You must include this in all programs
using the library, either directly or through some other header file,
like this:

@example
#include <shishi.h>
@end example

The name space of `Libshishi' is @code{shishi_*} for function names,
@code{Shishi*} for data types and @code{SHISHI_*} for other symbols.  In
addition the same name prefixes with one prepended underscore are
reserved for internal use and should never be used by an application.

@node Initialization
@subsection Initialization

`Libshishi' must be initialized before it can be used.  The library is
initialized by calling @code{shishi_init()} (@pxref{Initialization
Functions}).  The resources allocated by the initialization process
can be released if the application no longer has a need to call
`Libshishi' functions, this is done by calling @code{shishi_done()}.

In order to take advantage of the internationalisation features in
`Libshishi', such as translated error messages, the application must
set the current locale using @code{setlocale()} before initializing
`Libshishi'.

@node Version Check
@subsection Version Check

It is often desirable to check that the version of `Libshishi' used is
indeed one which fits all requirements.  Even with binary
compatibility new features may have been introduced but due to problem
with the dynamic linker an old version is actually used.  So you may
want to check that the version is okay right after program startup.

@include shishi-api-version.texi

The normal way to use the function is to put something similar to the
following early in your @code{main()}:

@example
  if (!shishi_check_version (SHISHI_VERSION))
    @{
      printf ("shishi_check_version() failed:\n"
              "Header file incompatible with shared library.\n");
      exit(1);
    @}
@end example

@node Building the source
@subsection Building the source
@cindex Compiling your application

If you want to compile a source file including the `shishi.h' header
file, you must make sure that the compiler can find it in the
directory hierarchy.  This is accomplished by adding the path to the
directory in which the header file is located to the compilers include
file search path (via the @option{-I} option).

However, the path to the include file is determined at the time the
source is configured.  To solve this problem, `Libshishi' uses the
external package @command{pkg-config} that knows the path to the
include file and other configuration options.  The options that need
to be added to the compiler invocation at compile time are output by
the @option{--cflags} option to @command{pkg-config shishi}.  The
following example shows how it can be used at the command line:

@example
gcc -c foo.c `pkg-config shishi --cflags`
@end example

Adding the output of @samp{pkg-config shishi --cflags} to the
compilers command line will ensure that the compiler can find the
`Libshishi' header file.

A similar problem occurs when linking the program with the library.
Again, the compiler has to find the library files.  For this to work,
the path to the library files has to be added to the library search path
(via the @option{-L} option).  For this, the option @option{--libs} to
@command{pkg-config shishi} can be used.  For convenience, this option
also outputs all other options that are required to link the program
with the `Libshishi' libararies (in particular, the @samp{-lshishi}
option).  The example shows how to link @file{foo.o} with the `Libshishi'
library to a program @command{foo}.

@example
gcc -o foo foo.o `pkg-config shishi --libs`
@end example

Of course you can also combine both examples to a single command by
specifying both options to @command{pkg-config}:

@example
gcc -o foo foo.c `pkg-config shishi --cflags --libs`
@end example

@node Autoconf tests
@subsection Autoconf tests
@cindex Autoconf tests
@cindex Configure tests

If you work on a project that uses Autoconf (@pxref{top, GNU
Autoconf,, autoconf}) to help find installed libraries, the
suggestions in the previous section are not the entire story.  There
are a few methods to detect and incorporate Shishi into your Autoconf
based package.  The preferred approach, is to use Libtool in your
project, and use the normal Autoconf header file and library tests.

@subsubsection Autoconf test via @samp{pkg-config}

If your audience is a typical GNU/Linux desktop, you can often assume
they have the @samp{pkg-config} tool installed, in which you can use
its Autoconf M4 macro to find and set up your package for use with
Shishi.  The following illustrate this scenario.

@example
AC_ARG_ENABLE(kerberos_v5,
        AC_HELP_STRING([--disable-kerberos_v5],
                       [don't use the KERBEROS_V5 mechanism]),
        kerberos_v5=$enableval)
if test "$kerberos_v5" != "no" ; then
        PKG_CHECK_MODULES(SHISHI, shishi >= 0.0.0,
                        [kerberos_v5=yes],
                        [kerberos_v5=no])
        if test "$kerberos_v5" != "yes" ; then
                kerberos_v5=no
                AC_MSG_WARN([shishi not found, disabling Kerberos 5])
        else
                kerberos_v5=yes
                AC_DEFINE(USE_KERBEROS_V5, 1,
                          [Define to 1 if you want Kerberos 5.])
        fi
fi
AC_MSG_CHECKING([if Kerberos 5 should be used])
AC_MSG_RESULT($kerberos_v5)
@end example

@subsubsection Standalone Autoconf test using Libtool

If your package uses Libtool(@pxref{top, GNU Libtool,, libtool}), you
can use the normal Autoconf tests to find the Shishi library and rely
on the Libtool dependency tracking to include the proper dependency
libraries (e.g., Libidn).  The following illustrate this scenario.

@example
AC_CHECK_HEADER(shishi.h,
        AC_CHECK_LIB(shishi, shishi_check_version,
                [kerberos5=yes AC_SUBST(SHISHI_LIBS, -lshishi)],
                kerberos5=no),
        kerberos5=no)
AC_ARG_ENABLE(kerberos5,
        AC_HELP_STRING([--disable-kerberos5],
                       [disable Kerberos 5 unconditionally]),
        kerberos5=$enableval)
if test "$kerberos5" != "no" ; then
        AC_DEFINE(USE_KERBEROS_V5, 1,
                  [Define to 1 if you want Kerberos 5.])
else
        AC_MSG_WARN([Shishi not found, disabling Kerberos 5])
fi
AC_MSG_CHECKING([if Kerberos 5 should be used])
AC_MSG_RESULT($kerberos5)
@end example

@subsubsection Standalone Autoconf test

If your package does not use Libtool, as well as detecting the Shishi
library as in the previous case, you must also detect whatever
dependencies Shishi requires to work (e.g., libidn).  Since the
dependencies are in a state of flux, we do not provide an example and
we do not recommend this approach, unless you are experienced
developer.

@node Initialization Functions
@section Initialization Functions

@include shishi-api-init.texi


@node Ticket Set Functions
@section Ticket Set Functions

A ``ticket set'' is, as the name implies, a collection of tickets.
Functions are provided to read tickets from file into a ticket set, to
query number of tickets in the set, to extract a given ticket from the
set, to search the ticket set for tickets matching certain criterium,
to write the ticket set to a file, etc.  High level functions for
performing a initial authentication (@pxref{AS Functions}) or
subsequent authentication (@pxref{TGS Functions}) and storing the new
ticket in the ticket set are also provided.

To manipulate each individual ticket, @xref{Ticket Functions}.  For
low-level ASN.1 manipulation see @xref{Ticket (ASN.1) Functions}.

@include shishi-api-tkts.texi


@node AP-REQ and AP-REP Functions
@section AP-REQ and AP-REP Functions

The ``AP-REQ'' and ``AP-REP'' are ASN.1 structures used by application
client and servers to prove to each other who they are.  The
structures contain auxilliary information, together with an
authenticator (@pxref{Authenticator Functions}) which is the real
cryptographic proof.  The following illustrates the AP-REQ and AP-REP
ASN.1 structures.

@verbatim
AP-REQ          ::= [APPLICATION 14] SEQUENCE {
        pvno            [0] INTEGER (5),
        msg-type        [1] INTEGER (14),
        ap-options      [2] APOptions,
        ticket          [3] Ticket,
        authenticator   [4] EncryptedData {Authenticator,
                                { keyuse-pa-TGSReq-authenticator
                                  | keyuse-APReq-authenticator }}
}

AP-REP          ::= [APPLICATION 15] SEQUENCE {
        pvno            [0] INTEGER (5),
        msg-type        [1] INTEGER (15),
        enc-part        [2] EncryptedData {EncAPRepPart,
                                { keyuse-EncAPRepPart }}
}

EncAPRepPart    ::= [APPLICATION 27] SEQUENCE {
        ctime           [0] KerberosTime,
        cusec           [1] Microseconds,
        subkey          [2] EncryptionKey OPTIONAL,
        seq-number      [3] UInt32 OPTIONAL
}
@end verbatim

@include shishi-api-ap.texi


@node SAFE and PRIV Functions
@section SAFE and PRIV Functions

The ``KRB-SAFE'' is an ASN.1 structure used by application client and
servers to exchange integrity protected data.  The integrity
protection is keyed, usually with a key agreed on via the AP exchange
(@pxref{AP-REQ and AP-REP Functions}).  The following illustrates the
KRB-SAFE ASN.1 structure.

@verbatim
   KRB-SAFE        ::= [APPLICATION 20] SEQUENCE {
           pvno            [0] INTEGER (5),
           msg-type        [1] INTEGER (20),
           safe-body       [2] KRB-SAFE-BODY,
           cksum           [3] Checksum
   }

   KRB-SAFE-BODY   ::= SEQUENCE {
           user-data       [0] OCTET STRING,
           timestamp       [1] KerberosTime OPTIONAL,
           usec            [2] Microseconds OPTIONAL,
           seq-number      [3] UInt32 OPTIONAL,
           s-address       [4] HostAddress,
           r-address       [5] HostAddress OPTIONAL
   }
@end verbatim

@include shishi-api-safe.texi

The ``KRB-PRIV'' is an ASN.1 structure used by application client and
servers to exchange confidential data.  The confidentiality is keyed,
usually with a key agreed on via the AP exchange (@pxref{AP-REQ and
AP-REP Functions}).  The following illustrates the KRB-PRIV ASN.1
structure.

@verbatim
   KRB-PRIV        ::= [APPLICATION 21] SEQUENCE {
           pvno            [0] INTEGER (5),
           msg-type        [1] INTEGER (21),
                           -- NOTE: there is no [2] tag
           enc-part        [3] EncryptedData -- EncKrbPrivPart
   }

   EncKrbPrivPart  ::= [APPLICATION 28] SEQUENCE {
           user-data       [0] OCTET STRING,
           timestamp       [1] KerberosTime OPTIONAL,
           usec            [2] Microseconds OPTIONAL,
           seq-number      [3] UInt32 OPTIONAL,
           s-address       [4] HostAddress -- sender's addr --,
           r-address       [5] HostAddress OPTIONAL -- recip's addr
   }
@end verbatim

@c @include shishi-api-safe.texi


@node Ticket Functions
@section Ticket Functions

@include shishi-api-tkt.texi


@node AS Functions
@section AS Functions

The Authentication Service (AS) is used to get an initial ticket using
e.g. your password.  The following illustrates the AS-REQ and AS-REP
ASN.1 structures.

@verbatim
-- Request --

AS-REQ          ::= KDC-REQ {10}

KDC-REQ {INTEGER:tagnum}        ::= [APPLICATION tagnum] SEQUENCE {
        pvno            [1] INTEGER (5) -- first tag is [1], not [0] --,
        msg-type        [2] INTEGER (tagnum),
        padata          [3] SEQUENCE OF PA-DATA OPTIONAL,
        req-body        [4] KDC-REQ-BODY
}

KDC-REQ-BODY    ::= SEQUENCE {
        kdc-options             [0] KDCOptions,
        cname                   [1] PrincipalName OPTIONAL
                                    -- Used only in AS-REQ --,
        realm                   [2] Realm
                                    -- Server's realm
                                    -- Also client's in AS-REQ --,
        sname                   [3] PrincipalName OPTIONAL,
        from                    [4] KerberosTime OPTIONAL,
        till                    [5] KerberosTime,
        rtime                   [6] KerberosTime OPTIONAL,
        nonce                   [7] UInt32,
        etype                   [8] SEQUENCE OF Int32 -- EncryptionType
                                    -- in preference order --,
        addresses               [9] HostAddresses OPTIONAL,
        enc-authorization-data  [10] EncryptedData {
                                        AuthorizationData,
                                        { keyuse-TGSReqAuthData-sesskey
                                          | keyuse-TGSReqAuthData-subkey }
                                     } OPTIONAL,
        additional-tickets      [11] SEQUENCE OF Ticket OPTIONAL
}

-- Reply --

AS-REP          ::= KDC-REP {11, EncASRepPart, {keyuse-EncASRepPart}}

KDC-REP {INTEGER:tagnum,
         TypeToEncrypt,
         UInt32:KeyUsages}      ::= [APPLICATION tagnum] SEQUENCE {
        pvno            [0] INTEGER (5),
        msg-type        [1] INTEGER (tagnum),
        padata          [2] SEQUENCE OF PA-DATA OPTIONAL,
        crealm          [3] Realm,
        cname           [4] PrincipalName,
        ticket          [5] Ticket,
        enc-part        [6] EncryptedData {TypeToEncrypt, KeyUsages}
}

EncASRepPart    ::= [APPLICATION 25] EncKDCRepPart

EncKDCRepPart   ::= SEQUENCE {
        key             [0] EncryptionKey,
        last-req        [1] LastReq,
        nonce           [2] UInt32,
        key-expiration  [3] KerberosTime OPTIONAL,
        flags           [4] TicketFlags,
        authtime        [5] KerberosTime,
        starttime       [6] KerberosTime OPTIONAL,
        endtime         [7] KerberosTime,
        renew-till      [8] KerberosTime OPTIONAL,
        srealm          [9] Realm,
        sname           [10] PrincipalName,
        caddr           [11] HostAddresses OPTIONAL
}
@end verbatim

@include shishi-api-as.texi


@node TGS Functions
@section TGS Functions

The Ticket Granting Service (TGS) is used to get subsequent tickets,
authenticated by other tickets (so called ticket granting tickets).
The following illustrates the TGS-REQ and TGS-REP ASN.1 structures.

@verbatim
-- Request --

TGS-REQ         ::= KDC-REQ {12}

KDC-REQ {INTEGER:tagnum}        ::= [APPLICATION tagnum] SEQUENCE {
        pvno            [1] INTEGER (5) -- first tag is [1], not [0] --,
        msg-type        [2] INTEGER (tagnum),
        padata          [3] SEQUENCE OF PA-DATA OPTIONAL,
        req-body        [4] KDC-REQ-BODY
}

KDC-REQ-BODY    ::= SEQUENCE {
        kdc-options             [0] KDCOptions,
        cname                   [1] PrincipalName OPTIONAL
                                    -- Used only in AS-REQ --,
        realm                   [2] Realm
                                    -- Server's realm
                                    -- Also client's in AS-REQ --,
        sname                   [3] PrincipalName OPTIONAL,
        from                    [4] KerberosTime OPTIONAL,
        till                    [5] KerberosTime,
        rtime                   [6] KerberosTime OPTIONAL,
        nonce                   [7] UInt32,
        etype                   [8] SEQUENCE OF Int32 -- EncryptionType
                                    -- in preference order --,
        addresses               [9] HostAddresses OPTIONAL,
        enc-authorization-data  [10] EncryptedData {
                                        AuthorizationData,
                                        { keyuse-TGSReqAuthData-sesskey
                                          | keyuse-TGSReqAuthData-subkey }
                                     } OPTIONAL,
        additional-tickets      [11] SEQUENCE OF Ticket OPTIONAL
}

-- Reply --

TGS-REP         ::= KDC-REP {13, EncTGSRepPart,
                        { keyuse-EncTGSRepPart-sesskey
                          | keyuse-EncTGSRepPart-subkey }}

KDC-REP {INTEGER:tagnum,
         TypeToEncrypt,
         UInt32:KeyUsages}      ::= [APPLICATION tagnum] SEQUENCE {
        pvno            [0] INTEGER (5),
        msg-type        [1] INTEGER (tagnum),
        padata          [2] SEQUENCE OF PA-DATA OPTIONAL,
        crealm          [3] Realm,
        cname           [4] PrincipalName,
        ticket          [5] Ticket,
        enc-part        [6] EncryptedData {TypeToEncrypt, KeyUsages}
}

EncTGSRepPart   ::= [APPLICATION 26] EncKDCRepPart

EncKDCRepPart   ::= SEQUENCE {
        key             [0] EncryptionKey,
        last-req        [1] LastReq,
        nonce           [2] UInt32,
        key-expiration  [3] KerberosTime OPTIONAL,
        flags           [4] TicketFlags,
        authtime        [5] KerberosTime,
        starttime       [6] KerberosTime OPTIONAL,
        endtime         [7] KerberosTime,
        renew-till      [8] KerberosTime OPTIONAL,
        srealm          [9] Realm,
        sname           [10] PrincipalName,
        caddr           [11] HostAddresses OPTIONAL
}
@end verbatim

@include shishi-api-tgs.texi


@node Ticket (ASN.1) Functions
@section Ticket (ASN.1) Functions

@include shishi-api-ticket.texi

@node AS/TGS Functions
@section AS/TGS Functions

The Authentication Service (AS) is used to get an initial ticket using
e.g. your password.  The Ticket Granting Service (TGS) is used to get
subsequent tickets using other tickets.  Protocol wise the procedures
are very similar, which is the reason they are described together.
The following illustrates the AS-REQ, TGS-REQ and AS-REP, TGS-REP
ASN.1 structures.  Most of the functions use the mnemonic ``KDC''
instead of either AS or TGS, which means the function operates on both
AS and TGS types.  Only where the distinction between AS and TGS is
important are the AS and TGS names used.  Remember, these are
low-level functions, and normal applications will likely be satisfied
with the AS (@pxref{AS Functions}) and TGS (@pxref{TGS Functions})
interfaces, or the even more high-level Ticket Set (@pxref{Ticket Set
Functions}) interface.

@verbatim
-- Request --

AS-REQ          ::= KDC-REQ {10}
TGS-REQ         ::= KDC-REQ {12}

KDC-REQ {INTEGER:tagnum}        ::= [APPLICATION tagnum] SEQUENCE {
        pvno            [1] INTEGER (5) -- first tag is [1], not [0] --,
        msg-type        [2] INTEGER (tagnum),
        padata          [3] SEQUENCE OF PA-DATA OPTIONAL,
        req-body        [4] KDC-REQ-BODY
}

KDC-REQ-BODY    ::= SEQUENCE {
        kdc-options             [0] KDCOptions,
        cname                   [1] PrincipalName OPTIONAL
                                    -- Used only in AS-REQ --,
        realm                   [2] Realm
                                    -- Server's realm
                                    -- Also client's in AS-REQ --,
        sname                   [3] PrincipalName OPTIONAL,
        from                    [4] KerberosTime OPTIONAL,
        till                    [5] KerberosTime,
        rtime                   [6] KerberosTime OPTIONAL,
        nonce                   [7] UInt32,
        etype                   [8] SEQUENCE OF Int32 -- EncryptionType
                                    -- in preference order --,
        addresses               [9] HostAddresses OPTIONAL,
        enc-authorization-data  [10] EncryptedData {
                                        AuthorizationData,
                                        { keyuse-TGSReqAuthData-sesskey
                                          | keyuse-TGSReqAuthData-subkey }
                                     } OPTIONAL,
        additional-tickets      [11] SEQUENCE OF Ticket OPTIONAL
}

-- Reply --

AS-REP          ::= KDC-REP {11, EncASRepPart, {keyuse-EncASRepPart}}
TGS-REP         ::= KDC-REP {13, EncTGSRepPart,
                        { keyuse-EncTGSRepPart-sesskey
                          | keyuse-EncTGSRepPart-subkey }}

KDC-REP {INTEGER:tagnum,
         TypeToEncrypt,
         UInt32:KeyUsages}      ::= [APPLICATION tagnum] SEQUENCE {
        pvno            [0] INTEGER (5),
        msg-type        [1] INTEGER (tagnum),
        padata          [2] SEQUENCE OF PA-DATA OPTIONAL,
        crealm          [3] Realm,
        cname           [4] PrincipalName,
        ticket          [5] Ticket,
        enc-part        [6] EncryptedData {TypeToEncrypt, KeyUsages}
}

EncASRepPart    ::= [APPLICATION 25] EncKDCRepPart
EncTGSRepPart   ::= [APPLICATION 26] EncKDCRepPart

EncKDCRepPart   ::= SEQUENCE {
        key             [0] EncryptionKey,
        last-req        [1] LastReq,
        nonce           [2] UInt32,
        key-expiration  [3] KerberosTime OPTIONAL,
        flags           [4] TicketFlags,
        authtime        [5] KerberosTime,
        starttime       [6] KerberosTime OPTIONAL,
        endtime         [7] KerberosTime,
        renew-till      [8] KerberosTime OPTIONAL,
        srealm          [9] Realm,
        sname           [10] PrincipalName,
        caddr           [11] HostAddresses OPTIONAL
}
@end verbatim

@include shishi-api-kdc.texi


@node Authenticator Functions
@section Authenticator Functions

An ``Authenticator'' is a ASN.1 structure that work as a proof that an
entity owns a ticket.  It is usually embedded in the AP-REQ structure
(@pxref{AP-REQ and AP-REP Functions}), and you most likely want to use
an AP-REQ instead of a Authenticator in normal applications.  The
following illustrates the Authenticator ASN.1 structure.

@verbatim
Authenticator   ::= [APPLICATION 2] SEQUENCE  {
        authenticator-vno       [0] INTEGER (5),
        crealm                  [1] Realm,
        cname                   [2] PrincipalName,
        cksum                   [3] Checksum OPTIONAL,
        cusec                   [4] Microseconds,
        ctime                   [5] KerberosTime,
        subkey                  [6] EncryptionKey OPTIONAL,
        seq-number              [7] UInt32 OPTIONAL,
        authorization-data      [8] AuthorizationData OPTIONAL
}
@end verbatim

@include shishi-api-authenticator.texi


@node Cryptographic Functions
@section Cryptographic Functions

Underneath the high-level functions described earlier, cryptographic
operations are happening.  If you need to access these cryptographic
primitives directly, this section describes the functions available.

Most cryptographic operations need keying material, and cryptographic
keys have been isolated into it's own data structure
@code{Shishi_key}.  The following illustrates it's contents, but note
that you cannot access it's elements directly but must use the
accessor functions described below.

@verbatim
struct Shishi_key
{
  int type;    /* RFC 1510 encryption integer type */
  char *value; /* Cryptographic key data */
  int version; /* RFC 1510 ``kvno'' */
};
@end verbatim

All functions that operate on this data structure are described now.

@include shishi-api-key.texi

Applications that run uninteractively may need keying material.  In
these cases, the keys are stored in a file, a file that is normally
stored on the local host.  The file should be protected from
unauthorized access.  The file is in ASCII format and contains keys as
outputed by @code{shishi_key_print()}.  All functions that handle
these keys sets are described now.

@include shishi-api-keys.texi

The previous functions require that the filename is known.  For some
applications, servers, it makes sense to provide a system default.
These key sets used by server applications are known as ``hostkeys''.
Here are the functions that operate on hostkeys (they are mostly
wrappers around generic key sets).

@include shishi-api-hostkeys.texi

After creating the key structure, it can be used to encrypt and
decrypt data, calculate checksum on data etc.  All available functions
are described now.

@include shishi-api-crypto.texi


@node Utility Functions
@section Utility Functions

@include shishi-api-utility.texi


@node Error Handling
@section Error Handling
@cindex Error Handling

Most functions in `Libshishi' are returning an error if they fail.
For this reason, the application should always catch the error
condition and take appropriate measures, for example by releasing the
resources and passing the error up to the caller, or by displaying a
descriptive message to the user and cancelling the operation.

Some error values do not indicate a system error or an error in the
operation, but the result of an operation that failed properly.

@menu
* Error Values::                A list of all error values used.
* Error Functions::             Error handling related functions.
@end menu

@node Error Values
@subsection Error Values

Errors are returned as an @code{int}.  Except for the SHISHI_OK case,
an application should always use the constants instead of their
numeric value.  Applications are encouraged to use the constants even
for SHISHI_OK as it improves readability.  Possible values are:

@table @code
@item SHISHI_OK
This value indicates success.  The value of this error is guaranteed
to always be @code{0} so you may use it in boolean constructs.

@include shishi-api-error-labels.texi

@end table

@node Error Functions
@subsection Error Functions

@include shishi-api-error.texi

@node Examples
@section Examples
@cindex Examples

This section will be extended to contain walk-throughs of example code
that demonstrate how `Shishi' is used to write your own applications
that support Kerberos 5.  The rest of the current section consists of
some crude hints for the example client/server applications that is
part of Shishi, taken from an email but saved here for lack of a
better place to put it.

There are two programs: 'client' and 'server' in src/.

The client output an AP-REQ, waits for an AP-REP, and then simply
reads data from stdin.

The server waits for an AP-REQ, parses it and prints an AP-REP, and
then read data from stdin.

Both programs accept a Kerberos server name as the first command line
argument.  Your KDC must know this server, since the client tries to
get a ticket for it (first it gets a ticket granting ticket for the
default username), and you must write the key for the server into
/usr/local/etc/shishi.keys on the Shishi format, e.g.:

@example
-----BEGIN SHISHI KEY-----
Keytype: 16 (des3-cbc-sha1-kd)
Principal: sample/latte.josefsson.org
Realm: JOSEFSSON.ORG
 
8W0VrQQBpxlACPQEqN91EHxbvFFo2ltt
-----END SHISHI KEY-----
@end example

You must extract the proper encryption key from the KDC in some way.
(This part will be easier when Shishi include a KDC, a basic one isn't
far away, give me a week or to.)

The intention is that the data read, after the authentication phase,
should be protected using KRB_SAFE (see RFC) but I haven't added this
yet.

@node Generic Security Service
@section Generic Security Service
@cindex Generic Security Service
@cindex GSS-API
@cindex GSSLib

As an alternative to the native Shishi programming API, it is possible
to program Shishi through the Generic Security Services (GSS) API.
The advantage of using GSS-API in your security application, instead
of the native Shishi API, is that it will be easier to port your
application between different Kerberos 5 implementations, and even
beyond Kerberos 5 to different security systems, that support GSS-API.
In the free software world, however, almost the only widely used
security system that supports GSS-API is Kerberos 5, so the last
advantage is somewhat academic.  But if you are porting applications
using GSS-API for other Kerberos 5 implementations, or want a more
mature and stable API than the native Shishi API, you may find using
Shishi's GSS-API interface compelling.  Note that GSS-API only offer
basic services, for more advanced uses you must use the native API.

Since the GSS-API is not specific to Shishi, it is distributed
independently from Shishi.  Further information on the GSS project can
be found at @url{http://josefsson.org/gss/}.

@c **********************************************************
@c *******************  Acknowledgements  *******************
@c **********************************************************
@node Acknowledgements
@chapter Acknowledgements

Shishi uses Libtasn1 by Fabio Fiorina, Libnettle by Niels Möller,
Libgcrypt and Libgpg-error by Werner Koch, Libidn by Simon Josefsson,
cvs2cl by Karl Fogel, and gdoc by Michael Zucchi.

Several GNU packages simplified development considerably, those
packages include Autoconf, Automake, Libtool, Gnulib, Gettext, Indent,
CVS, Texinfo, Help2man and Emacs.

Several people reported bugs, sent patches or suggested improvements,
see the file THANKS.

@c **********************************************************
@c *******************  Appendices  *************************
@c **********************************************************

@node Copying This Manual
@appendix Copying This Manual

@menu
* GNU Free Documentation License::  License for copying this manual.
@end menu

@include fdl.texi

@include gpl.texi

@node Concept Index
@unnumbered Concept Index

@printindex cp

@node Function and Data Index
@unnumbered Function and Data Index

@printindex fn

@summarycontents
@contents
@bye