Bump copyright year.

[shishi.git] / doc / shishi.texi

\input texinfo   @c -*- mode: texinfo; coding: us-ascii; -*-
@c This file is part of Shishi.
@c See below for copyright and license.

@setfilename shishi.info
@include version.texi
@settitle Shishi
@finalout

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

@copying
This manual is last updated @value{UPDATED} for version
@value{VERSION} of Shishi.

Copyright @copyright{} 2002, 2003, 2004, 2005, 2006, 2007 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.2 or
any later version published by the Free Software Foundation; with no
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
copy of the license is included in the section entitled ``GNU Free
Documentation License''.
@end quotation
@end copying

@dircategory GNU utilities
@direntry
* shishi: (shishi).             A Kerberos 5 implementation
@end direntry

@dircategory GNU Libraries
@direntry
* libshishi: (shishi).          Library implementing Kerberos 5.
@end direntry

@titlepage
@title Shishi
@subtitle Kerberos 5 implementation for the GNU system
@subtitle for version @value{VERSION}, @value{UPDATED}
@author Simon Josefsson
@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

* Criticism of Kerberos::       Why you maybe shouldn't use Kerberos.
* Protocol Extensions::         Description of protocol extensions used.
* Copying Information::         How you can copy and share Shishi.

Indices

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


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

Shishi is a (still incomplete) implementation of the Kerberos 5
network authentication system.  Shishi can be used to authenticate
users in distributed systems.

Shishi contains a library ('libshishi') that can be used by
application developers to add support for Kerberos 5.  Shishi contains
a command line utility ('shishi') that is used by users to acquire and
manage tickets (and more).  The server side, a Key Distribution
Center, is implemented by 'shishid'.  Of course, a manual documenting
usage aspects as well as the programming API is included.

Shishi currently supports AS/TGS exchanges for acquiring tickets,
pre-authentication, the AP exchange for performing client and server
authentication, and SAFE/PRIV for integrity/privacy protected
application data exchanges.

Shishi is internationalized; error and status messages can be
translated into the users' language; user name and passwords can be
converted into any available character set (normally including
ISO-8859-1 and UTF-8) and also be processed using an experimental
Stringprep profile.

Most, if not all, of the widely used encryption and checksum types are
supported, such as 3DES, AES, ARCFOUR and HMAC-SHA1.

Shishi is developed for the GNU/Linux system, but runs on over 20
platforms including most major Unix platforms and Windows, and many
kind of devices including iPAQ handhelds and S/390 mainframes.

Shishi is free software licensed under the GNU General Public License.

@menu
* Getting Started::
* Features and Status::
* Overview::
* Cryptographic Overview::
* Supported Platforms::
* Getting help::
* Commercial Support::
* 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{GNU GPL}).

@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.

@item Modularized low-level crypto interface.
Currently Gnulib and Libgcrypt are supported.  If you wish to add
support for another low-level cryptographic library, you only have to
implement a few APIs for DES, AES, MD5, SHA1, HMAC, etc. Look at
@file{gl/gc-gnulib.c} or @file{gl/gc-libgcrypt.c} as a starting
pointer.

@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, including some reasonable startup-time to get familiar
with Shishi in general.  If you like to start working on anything,
please let me know so work duplication can be avoided.

@itemize @bullet

@item Parse @file{/etc/krb5.keytab} to extract keys to use for telnetd etc (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 KDC (initiated, weeks)

@item LDAP backend for Shisa.

@item Set/Change password protocol (weeks?)

@item Port applications to use Shishi (indefinite)

@item Finish server-realm stuff

@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.

@item GUI applet for managing tickets.
This is supported via the ticket-applet, of which a Shishi port is
published on the Shishi home page.

@item Authorization library (months?)
The shishi_authorized_p() is not a good solution, better would be to
have a generic and flexible authorization library.  Possibly based on
S-EXP's in tickets?  Should support non-Kerberos uses as well, of
course.

@item Proof read manual.

@item X.500 support, including DOMAIN-X500-COMPRESS.
I will accept patches that implement this, if it causes minimal
changes to the current code.

@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, copyright likely owned by the RFC 1510 authors or some
contributor.}.

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.
In this section we give the names of the supported encryption suites,
and some notes about them, and their associated checksum suite.

Statements such as ``it is weak'' should be read as meaning that there
is no credible security analysis of the mechanism available, and/or
that should an attack be published publicly, few people would likely
be surprised.  Also keep in mind that the key size mentioned is the
actual key size, not the effective key space as far as a brute force
attack is concerned.

As you may infer from the descriptions, there is currently no
encryption algorithm and only one checksum algorithm that inspire
great confidence in its design.  Hopefully this will change over time.

@cindex DES
@cindex 3DES
@cindex AES
@cindex ARCFOUR

@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 arcfour-hmac
@itemx arcfour-hmac-exp

@code{arcfour-hmac-*} are a proprietary stream cipher with 56 bit
(@code{arcfour-hmac-exp}) or 128 bit (@code{arcfour-hmac}) keys, used
in a proprietary way described in an expired IETF draft
@file{draft-brezak-win2k-krb-rc4-hmac-04.txt}.  Deriving keys from
passwords is supported, and is done by computing a message digest
(MD4) of a 16-bit Unicode representation of the ASCII password, with
no salt.  Data is integrity protected with a keyed hash (HMAC-MD5),
where the key is derived from the base key in a creative way.  It is
weak.  It is associated with the @code{arcfour-hmac-md5} checksum.

@item des-cbc-none

@code{des-cbc-none} is DES encryption and decryption with 56 bit keys
and 8 byte blocks in CBC mode, using a zero IV.  The keys can be
derived from passwords by an obscure application specific algorithm.
It is weak, because it offers no integrity protection.  This is
typically only used by RFC 1964 GSS-API implementations (which try to
protect integrity using an ad-hoc solution).  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, using the key as IV (@pxref{Key as
initialization vector}).  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, using a zero IV.  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, using a zero IV.  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 encryption mechanism.

@item des3-cbc-none

@code{des3-cbc-none} 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 the same algorithm as
@code{des3-cbc-sha1-kd}.  It is weak, because it offers no integrity
protection.  This is typically only used by GSS-API implementations
(which try to protect integrity using an ad-hoc solution) for
interoperability with some existing Kerberos GSS implementations.  It
is associated with the @code{NULL} checksum.

@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
@itemx 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 AES cipher encryption mode (CBC with Ciphertext
Stealing, and a non-standard IV output) 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 arcfour-hmac-md5

@code{arcfour-hmac-md5} is a keyed HMAC-MD5 checksum computed on a MD5
message digest, in turn computed on a four byte message type indicator
concatenated with the application data.  (The @code{arcfour}
designation is thus somewhat misleading, but since this checksum
mechanism is described in the same document as the @code{arcfour}
encryption mechanisms, it is not a completely unnatural designation.)
It is weak.  It is compatible with all encryption mechanisms.

@item rsa-md4

@code{rsa-md4} is a unkeyed MD4 hash computed over the message.  It is
weak, because it is unkeyed.  However applications can, with care, use
it non-weak ways (e.g., by including the hash in other messages that
are protected by other means).  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.  It is
weak, because it is unkeyed.  However applications can, with care, use
it non-weak ways (e.g., by including the hash in other messages that
are protected by other means).  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}, which does not appear
to be widely used outside Kerberos and hence not widely studied).  It
has no security proof, but is assumed to provide good security.  The
weakest part is likely the proprietary key derivation function.  It is
compatible with the @code{des3-cbc-sha1-kd} encryption mechanism.

@item hmac-sha1-96-aes128
@itemx 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{aes*-cts-hmac-sha1-96}, i.e., PKCS#5).  It has no security
proof, but is assumed to provide good security.  It is compatible with
the @code{aes*-cts-hmac-sha1-96} encryption mechanisms.

@end table

Several of the cipher suites have long names that can be hard to
memorize.  For your convenience, the following short-hand aliases
exists.  They can be used wherever the full encryption names are used.

@table @code

@item arcfour

Alias for @code{arcfour-hmac}.

@item des-crc

Alias for @code{des-cbc-crc}.

@item des-md4

Alias for @code{des-cbc-md4}.

@item des-md5
@itemx des

Alias for @code{des-cbc-md5}.

@item des3
@itemx 3des

Alias for @code{des3-cbc-sha1-kd}.

@item aes128

Alias for @code{aes128-cts-hmac-sha1-96}.

@item aes
@itemx aes256

Alias for @code{aes256-cts-hmac-sha1-96}.

@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}.

@item MacOS X 10.2 Server Edition
@cindex MacOS X

GCC 3.1 and GNU Make. @code{powerpc-apple-darwin6.5}.

@item Cross compiled to uClinux/uClibc on Motorola Coldfire.
@cindex Motorola Coldfire
@cindex uClinux
@cindex uClibc

GCC 3.4 and GNU Make @code{m68k-uclinux-elf}.

@end enumerate

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

@node Getting help
@section Getting help

A mailing list where users of Shishi may help each other exists, and
you can reach it by sending e-mail to @email{help-shishi@@gnu.org}.
Archives of the mailing list discussions, and an interface to manage
subscriptions, is available through the World Wide Web at
@url{http://lists.gnu.org/mailman/listinfo/help-shishi}.

@node Commercial Support
@section Commercial Support

Commercial support is available for users of Shishi.  The kind of
support that can be purchased may include:

@itemize

@item Implement new features.
Such as support for some optional part of the Kerberos standards,
e.g. PKINIT, hardware token authentication.

@item Port Shishi to new platforms.
This could include porting Shishi to an embedded platforms that may
need memory or size optimization.

@item Integrate Kerberos 5 support in your existing project.

@item System design of components related to Kerberos 5.

@end itemize

If you are interested, please write to:

@verbatim
Simon Josefsson Datakonsult
Hagagatan 24
113 47 Stockholm
Sweden

E-mail: simon@josefsson.org
@end verbatim

If your company provide support related to Shishi and would like to be
mentioned here, contact 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-@value{VERSION}.tar.gz} where the @samp{@value{VERSION}}
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-@value{VERSION}.tar.gz
$ tar xfz shishi-@value{VERSION}.tar.gz
$ cd shishi-@value{VERSION}/
$ ./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.

A few @code{configure} options may be relevant, summarized in the
table.

@table @code

@item --disable-des
@itemx --disable-3des
@itemx --disable-aes
@itemx --disable-md
@itemx --disable-null
@itemx --disable-arcfour
Disable a cryptographic algorithm at compile time.  Usually it is
better to disable algorithms during run-time with the configuration
file, but this allows you to reduce the code size slightly.

@item --disable-starttls
Disable the experimental TLS support for KDC connections.  If you do
not use a Shishi KDC, this support is of no use so you could safely
disable it.

@item --without-stringprep
Disable internationalized string processing.

@end table

For the complete list, refer to the output from @code{configure
--help}.

@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
$ 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 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
$ 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 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
$ 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 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
$ 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 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
$ 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 example

Refer to the reference manual for all available parameters
(@pxref{Parameters for shishi}).  The rest of this section contains
description of more specialized usage modes that can be ignored by
most users.

@section Proxiable and Proxy Tickets

At times it may be necessary for a principal to allow a service to
perform an operation on its behalf. The service must be able to take
on the identity of the client, but only for a particular purpose. A
principal can allow a service to take on the principal's identity for
a particular purpose by granting it a proxy.

The process of granting a proxy using the proxy and proxiable flags is
used to provide credentials for use with specific services. Though
conceptually also a proxy, users wishing to delegate their identity in
a form usable for all purpose MUST use the ticket forwarding mechanism
described in the next section to forward a ticket-granting ticket.

The PROXIABLE flag in a ticket is normally only interpreted by the
ticket-granting service. It can be ignored by application servers.
When set, this flag tells the ticket-granting server that it is OK to
issue a new ticket (but not a ticket-granting ticket) with a different
network address based on this ticket. This flag is set if requested by
the client on initial authentication. By default, the client will
request that it be set when requesting a ticket-granting ticket, and
reset when requesting any other ticket.

This flag allows a client to pass a proxy to a server to perform a
remote request on its behalf (e.g. a print service client can give the
print server a proxy to access the client's files on a particular file
server in order to satisfy a print request).

In order to complicate the use of stolen credentials, Kerberos tickets
are usually valid from only those network addresses specifically
included in the ticket[4]. When granting a proxy, the client MUST
specify the new network address from which the proxy is to be used, or
indicate that the proxy is to be issued for use from any address.

The PROXY flag is set in a ticket by the TGS when it issues a proxy
ticket.  Application servers MAY check this flag and at their option
they MAY require additional authentication from the agent presenting
the proxy in order to provide an audit trail.

Here is how you would acquire a PROXY ticket for the service
@samp{imap/latte.josefsson.org}:

@example
$ shishi jas@@JOSEFSSON.ORG imap/latte.josefsson.org --proxy
Enter password for `jas@@JOSEFSSON.ORG':
libshishi: warning: KDC bug: Reply encrypted using wrong key.
jas@@JOSEFSSON.ORG:
Authtime:       Mon Sep  8 20:02:35 2003
Starttime:      Mon Sep  8 20:02:36 2003
Endtime:        Tue Sep  9 04:02:35 2003
Server:         imap/latte.josefsson.org key des3-cbc-sha1-kd (16)
Ticket key:     des3-cbc-sha1-kd (16) protected by des3-cbc-sha1-kd (16)
Ticket flags:   PROXY (16)
$
@end example

As you noticed, this asked for your password.  The reason is that
proxy tickets must be acquired using a proxiable ticket granting
ticket, which was not present.  If you often need to get proxy
tickets, you may acquire a proxiable ticket granting ticket from the
start:

@example
$ shishi --proxiable
Enter password for `jas@@JOSEFSSON.ORG':
jas@@JOSEFSSON.ORG:
Authtime:       Mon Sep  8 20:04:27 2003
Endtime:        Tue Sep  9 04:04:27 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:   PROXIABLE INITIAL (520)
@end example

Then you should be able to acquire proxy tickets based on that ticket
granting ticket, as follows:

@example
$ shishi jas@@JOSEFSSON.ORG imap/latte.josefsson.org --proxy
libshishi: warning: KDC bug: Reply encrypted using wrong key.
jas@@JOSEFSSON.ORG:
Authtime:       Mon Sep  8 20:04:27 2003
Starttime:      Mon Sep  8 20:04:32 2003
Endtime:        Tue Sep  9 04:04:27 2003
Server:         imap/latte.josefsson.org key des3-cbc-sha1-kd (16)
Ticket key:     des3-cbc-sha1-kd (16) protected by des3-cbc-sha1-kd (16)
Ticket flags:   PROXY (16)
$
@end example

@section Forwardable and Forwarded Tickets

Authentication forwarding is an instance of a proxy where the service
that is granted is complete use of the client's identity. An example
where it might be used is when a user logs in to a remote system and
wants authentication to work from that system as if the login were
local.

The FORWARDABLE flag in a ticket is normally only interpreted by the
ticket-granting service. It can be ignored by application servers.
The FORWARDABLE flag has an interpretation similar to that of the
PROXIABLE flag, except ticket-granting tickets may also be issued with
different network addresses. This flag is reset by default, but users
MAY request that it be set by setting the FORWARDABLE option in the AS
request when they request their initial ticket-granting ticket.

This flag allows for authentication forwarding without requiring the
user to enter a password again. If the flag is not set, then
authentication forwarding is not permitted, but the same result can
still be achieved if the user engages in the AS exchange specifying
the requested network addresses and supplies a password.

The FORWARDED flag is set by the TGS when a client presents a ticket
with the FORWARDABLE flag set and requests a forwarded ticket by
specifying the FORWARDED KDC option and supplying a set of addresses
for the new ticket. It is also set in all tickets issued based on
tickets with the FORWARDED flag set. Application servers may choose to
process FORWARDED tickets differently than non-FORWARDED tickets.

If addressless tickets are forwarded from one system to another,
clients SHOULD still use this option to obtain a new TGT in order to
have different session keys on the different systems.

Here is how you would acquire a FORWARDED ticket for the service
@samp{host/latte.josefsson.org}:

@example
$ shishi jas@@JOSEFSSON.ORG host/latte.josefsson.org --forwarded
Enter password for `jas@@JOSEFSSON.ORG':
libshishi: warning: KDC bug: Reply encrypted using wrong key.
jas@@JOSEFSSON.ORG:
Authtime:       Mon Sep  8 20:07:11 2003
Starttime:      Mon Sep  8 20:07:12 2003
Endtime:        Tue Sep  9 04:07:11 2003
Server:         host/latte.josefsson.org key des3-cbc-sha1-kd (16)
Ticket key:     des3-cbc-sha1-kd (16) protected by des3-cbc-sha1-kd (16)
Ticket flags:   FORWARDED (4)
$
@end example

As you noticed, this asked for your password.  The reason is that
forwarded tickets must be acquired using a forwardable ticket granting
ticket, which was not present.  If you often need to get forwarded
tickets, you may acquire a forwardable ticket granting ticket from the
start:

@example
$ shishi --forwardable
Enter password for `jas@@JOSEFSSON.ORG':
jas@@JOSEFSSON.ORG:
Authtime:       Mon Sep  8 20:08:53 2003
Endtime:        Tue Sep  9 04:08:53 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:   FORWARDABLE INITIAL (514)
$
@end example

Then you should be able to acquire forwarded tickets based on that
ticket granting ticket, as follows:

@example
$ shishi jas@@JOSEFSSON.ORG host/latte.josefsson.org --forwarded
libshishi: warning: KDC bug: Reply encrypted using wrong key.
jas@@JOSEFSSON.ORG:
Authtime:       Mon Sep  8 20:08:53 2003
Starttime:      Mon Sep  8 20:08:57 2003
Endtime:        Tue Sep  9 04:08:53 2003
Server:         host/latte.josefsson.org key des3-cbc-sha1-kd (16)
Ticket key:     des3-cbc-sha1-kd (16) protected by des3-cbc-sha1-kd (16)
Ticket flags:   FORWARDED (4)
$
@end example


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

Here you will learn how to set up, run and maintain the Shishi
Kerberos server.  Kerberos is incompatible with the standard Unix
@file{/etc/passwd} password database@footnote{And besides, Shishi is
intended to work on non-Unix platforms as well.}, therefor the first
step will be to create a Kerberos user database.  Shishi's user
database system is called Shisa.  Once Shisa is configured, you can
then start the server and begin issuing Kerberos tickets to your
users.  The Shishi server is called @file{shishid}.  After getting the
server up and running, we discuss how you can set up multiple Kerberos
servers, to increase availability or offer load-balancing.  Finally,
we include some information intended for developers, that will enable
you to customize Shisa to use an external user database, such as a
@acronym{LDAP} server or @acronym{SQL} database.

@menu
* Introduction to Shisa::       Explanation of the Shishi user database.
* Configuring Shisa::           Define the user database in Shisa.
* Using Shisa::                 How to add realms and principals to database.
* Starting Shishid::            Issue Kerberos tickets to your users.
* Configuring DNS for KDC::     Placing the KDC address in DNS is useful.
* Kerberos via TLS::            How to setup Shishi to use TLS.
* Multiple servers::            High availability and load-balancing.
* Developer information::       Writing your own Shisa database backend.
@end menu

@node Introduction to Shisa
@section Introduction to Shisa

The user database part of Shishi is called Shisa.  The Shisa library
is independent of the core Shishi library.  Shisa is responsible for
storing the name of your realms, the name of your principals (users),
accounting information for the users (i.e., when each account start to
be valid and when it expire), and the cryptographic keys each user
have.  Some Kerberos internal data can also be stored, such as the key
version number, the last dates for when various ticket requests were
made, the cryptographic salt, string-to-key parameters and password
for each user.  Not all information need to be stored.  For example,
in some situations it is prudent to leave the password field empty, so
that somebody who manage to steal the user database will only be able
to compromise your system, and not other systems were your user may
have re-used the same password.  On the other hand, you may already
store the password in your customized database, in which case being
able to change it via the Shisa interface can be useful.

Shisa is a small (a few thousand lines of @acronym{C} code) standalone
library.  Shisa does not depend on the Shishi library.  Because a user
database with passwords may be useful for other applications as well
(e.g., @acronym{GNU} @acronym{SASL}), it may be separated into its own
project later on.  You should keep this in mind, so that you don't
consider writing a Shisa backend for your own database a purely Shishi
specific project.  You may, for example, chose to use the Shisa
interface in your own applications to have a simple interface to your
user database.  Your experience and feedback is appreciated if you
chose to explore this.

Note that the Shisa database does not expose everything you may want
to know about a user, such as its full human name, telephone number or
even the user's login account name or home directory.  It only store
what is needed to authenticate a peer claiming to be an entity.  Thus
it does not make sense to replace your current user database or
@file{/etc/passwd} with data derived from the Shisa database.
Instead, it is intended that you write a Shisa backend that export
@i{some} of the information stored in your user database.  You may be
able to replace some existing functionality, such as the password
field in @file{/etc/passwd} with a Kerberos PAM module, but there is
no requirement for doing so.

@node Configuring Shisa
@section Configuring Shisa

The configuration file for Shisa is typically stored in
@file{/usr/local/etc/shishi/shisa.conf}.  You do not have to configure
this file, the defaults should be acceptable to first-time users.  The
file is used to define where you user database reside, and some
options such as making the database read-only or whether errors
detected when accessing the database should be ignored.  (The latter
may be useful if the server is a remote @acronym{LDAP} server that may
be unavailable, and you want to fail over to a local copy of the
database.)

The default will store the user database using directories and files,
rooted by default in @file{/usr/local/var/shishi}.  You may use
standard file permission settings to control access to the directory
hierarchy.  It is strongly recommended to restrict access to the
directory.  Storing the directory on local storage (i.e., hard disk or
removal media) is recommended.  We discourage placing the database on
a network file system, but realize it can be useful in some situations
(@pxref{Multiple servers}).

See the reference manual (@pxref{Shisa Configuration}) for the details
of the configuration file.  Again, you are not expected to need to
modify anything unless you are an experienced Shishi administrator.

@node Using Shisa
@section Using Shisa

There is a command line interface to the Shisa library, aptly named
@file{shisa}.  You will use this tool to add, remove and change
information stored in the database about realms, principals and keys.
The tool can also be used to ``dump'' all information in the database,
for backup or debugging purposes.  (Currently the output format cannot
be read by any tool, but functionality to do this will be added in the
future, possibly as a read-only file-based Shisa database backend.)

The reference manual (@pxref{Parameters for shisa}) explains all
parameters, but here we will give you a walk-through of the typical
uses of the tool.

Installing Shishi usually create a realm with two principals; one
ticket granting ticket for the realm, and one host key for the server.
This is what you typically need to get started, but it doesn't serve
our purposes.  So we start by removing the principals and the realm.
To do that, we need to figure out the name of the realm.  The
@samp{--list} or @samp{--dump} parameters can be used for this.  (Most
``long'' parameters, like @samp{--dump}, have shorter names as well,
in this case @samp{-d}, @ref{Parameters for shisa}).

@example
jas@@latte:~$ shisa -d
latte
        krbtgt/latte
                Account is enabled.
                Current key version 0 (0x0).
                Key 0 (0x0).
                        Etype aes256-cts-hmac-sha1-96 (0x12, 18).
                        Salt lattekrbtgt/latte.
        host/latte
                Account is enabled.
                Current key version 0 (0x0).
                Key 0 (0x0).
                        Etype aes256-cts-hmac-sha1-96 (0x12, 18).
                        Salt lattehost/latte.
jas@@latte:~$
@end example

The realm names are printed at column 0, the principal names are
indented with one @samp{TAB} character (aka @samp{\t} or ASCII 0x09
Horizontal Tabulation), and the information about each principal are
indented with two @samp{TAB} characters.  The above output means that
there is one realm @samp{latte} with two principals;
@samp{krbtgt/latte} (which is used to authenticate Kerberos ticket
requests) and @samp{host/latte} (used to authenticate host-based
applications like Telnet).  They were created during @samp{make
install} on a host called @samp{latte}.

If the installation did not create a default database for you, you
might get an error similar to the following.

@example
jas@@latte:~$ shisa -d
shisa: Cannot initialize `file' database backend.
Location `/usr/local/var/shishi' and options `N/A'.
shisa: Initialization failed:
Shisa database could not be opened.
jas@@latte:~$
@end example

This indicate the database do not exist.  For a file database, you can
create it by simply creating the directory, as follows.  Note the
access permission change with @samp{chmod}.  Typically the @samp{root}
user would own the files, but as these examples demonstrate, setting
up a Kerberos server does not require root access.  Indeed, it may be
prudent to run all Shishi applications as a special non-@samp{root}
user, and have all Shishi related files owned by that user, so that
any security vulnerabilities does not lead to a system compromise.
(However, if the user database is stolen, system compromises of other
systems may be possible if you use, e.g., Kerberos Telnet.)

@example
jas@@latte:~$ mkdir /usr/local/var/shishi
jas@@latte:~$ chmod go-rwx /usr/local/var/shishi
@end example

Back to the first example, where you have a realm @samp{latte} with
some principals.  We want to remove the realm to demonstrate how you
create the realm from scratch.  (Of course, you can have more than one
realm in the database, but for this example we assume you want to set
up a realm named the same as Shishi guessed you would name it, so the
existing realm need to be removed first.)  The @samp{--remove} (short
form @samp{-r}) parameter is used for this purpose, as follows.

@example
jas@@latte:~$ shisa -r latte host/latte
Removing principal `host/latte@@latte'...
Removing principal `host/latte@@latte'...done
jas@@latte:~$ shisa -r latte krbtgt/latte
Removing principal `krbtgt/latte@@latte'...
Removing principal `krbtgt/latte@@latte'...done
jas@@latte:~$ shisa -r latte
Removing realm `latte'...
Removing realm `latte'...done
jas@@latte:~$
@end example

You may be asking yourself ``What if the realm has many more
principals?''.  If you fear manual labor (or a small @samp{sed}
script, recall the format of @samp{--list}?), don't worry, there is a
@samp{--force} (short form @samp{-f}) flag.  Use with care.  Here is a
faster way to do the above:

@example
jas@@latte:~$ shisa -r latte -f
Removing principal `krbtgt/latte@@latte'...
Removing principal `krbtgt/latte@@latte'...done
Removing principal `host/latte@@latte'...
Removing principal `host/latte@@latte'...done
Removing realm `latte'...
Removing realm `latte'...done
jas@@latte:~$
@end example

You should now have a working, but empty, Shisa database.  Let's set
up the realm manually, step by step.  The first step is to decide on
name for your realm.  The full story is explained elsewhere
(@pxref{Realm and Principal Naming}) but the short story is to take
your @acronym{DNS} domain name and translate it to upper case.  For
example, if your organization uses @code{example.org} it is a good
idea to use @code{EXAMPLE.ORG} as the name of your Kerberos realm.
We'll use @code{EXAMPLE.ORG} as the realm name in these examples.
Let's create the realm.

@example
jas@@latte:~$ shisa -a EXAMPLE.ORG
Adding realm `EXAMPLE.ORG'...
Adding realm `EXAMPLE.ORG'...done
jas@@latte:~$
@end example

Currently, there are no properties associated with entire realms.  In
the future, it may be possible to set a default realm-wide password
expiry policy or similar.  Each realm normally have one principal that
is used for authenticating against the ``ticket granting service'' on
the Kerberos server with a ticket instead of using the password.  This
is used by the user when she acquire a ticket for servers.  This
principal must look like @samp{krbtgt/REALM} (@pxref{krbtgt,,Name of
the TGS}).  Let's create it.

@example
jas@@latte:~$ shisa -a EXAMPLE.ORG krbtgt/EXAMPLE.ORG
Adding principal `krbtgt/EXAMPLE.ORG@@EXAMPLE.ORG'...
Adding principal `krbtgt/EXAMPLE.ORG@@EXAMPLE.ORG'...done
jas@@latte:~$
@end example

Now that wasn't difficult, although not very satisfying either.  What
does adding a principal mean?  The name is created, obviously, but it
also mean setting a few values in the database.  Let's view the entry
to find out which values.

@example
jas@@latte:~$ shisa -d
EXAMPLE.ORG
        krbtgt/EXAMPLE.ORG
                Account is enabled.
                Current key version 0 (0x0).
                Key 0 (0x0).
                        Etype aes256-cts-hmac-sha1-96 (0x12, 18).
                        Salt EXAMPLE.ORGkrbtgt/EXAMPLE.ORG.
jas@@latte:~$
@end example

To use host based security services like @acronym{SSH} or Telnet with
Kerberos, each host must have a key shared between the host and the
KDC.  The key is typically stored in
@file{/usr/local/etc/shishi/shishi.keys}.  We assume your server is
called @samp{mail.example.org} and create the principal.  To
illustrate a new parameter, we also set the specific algorithm to use
by using the @samp{--encryption-type} (short form @samp{-E})
parameter.

@example
jas@@latte:~$ shisa -a EXAMPLE.ORG host/mail.example.org -E des3
Adding principal `host/mail.example.org@@EXAMPLE.ORG'...
Adding principal `host/mail.example.org@@EXAMPLE.ORG'...done
jas@@latte:~$
@end example

To export the key, there is another Shisa parameter @samp{--keys} that
will print the key in a format that is recognized by Shishi.  Let's
use it to print the host key.

@example
jas@@latte:~$ shisa -d --keys EXAMPLE.ORG host/mail.example.org
EXAMPLE.ORG
        host/mail.example.org
                Account is enabled.
                Current key version 0 (0x0).
                Key 0 (0x0).
                        Etype des3-cbc-sha1-kd (0x10, 16).
-----BEGIN SHISHI KEY-----
Keytype: 16 (des3-cbc-sha1-kd)
Principal: host/mail.example.org
Realm: EXAMPLE.ORG
 
iQdA8hxdvOUHZNliZJv7noM02rXHV8gq
-----END SHISHI KEY-----
                        Salt EXAMPLE.ORGhost/mail.example.org.
jas@@latte:~$
@end example

So to set up the host, simply redirect output to the host key file.

@example
jas@@latte:~$ shisa -d --keys EXAMPLE.ORG \
     host/mail.example.org > /usr/local/etc/shishi/shishi.keys
jas@@latte:~$
@end example

The next logical step is to create a principal for some user, so you
can use your password to get a Ticket Granting Ticket via the
Authentication Service (AS) from the KDC, and then use the Ticket
Granting Service (TGS) from the KDC to get a ticket for a specific
host, and then send that ticket to the host to authenticate yourself.
Creating this end-user principle is slightly different from the
earlier steps, because you want the key to be derived from a password
instead of being a random key.  The @samp{--password} parameter
indicate this.  This make the tool ask you for the password.

@example
jas@@latte:~$ shisa -a EXAMPLE.ORG simon --password
Password for `simon@@EXAMPLE.ORG':
Adding principal `simon@@EXAMPLE.ORG'...
Adding principal `simon@@EXAMPLE.ORG'...done
jas@@latte:~$
@end example

The only special thing about this principal now is that it has a
@code{password} field set in the database.

@example
jas@@latte:~$ shisa -d EXAMPLE.ORG simon --keys
EXAMPLE.ORG
        simon
                Account is enabled.
                Current key version 0 (0x0).
                Key 0 (0x0).
                        Etype aes256-cts-hmac-sha1-96 (0x12, 18).
-----BEGIN SHISHI KEY-----
Keytype: 18 (aes256-cts-hmac-sha1-96)
Principal: simon
Realm: EXAMPLE.ORG
 
Ja7ciNtrAI3gtodLaVDQ5zhcH58ffk0kS5tGAM7ILvM=
-----END SHISHI KEY-----
                        Salt EXAMPLE.ORGsimon.
                        Password foo.
jas@@latte:~$
@end example

You should now be ready to start the KDC, which is explained in the
next section (@pxref{Starting Shishid}), and get tickets as explained
earlier (@pxref{User Manual}).

@node Starting Shishid
@section Starting Shishid

The Shishi server, or Key Distribution Center (KDC), is called
Shishid.  Shishid is responsible for listening on UDP and TCP ports
for Kerberos requests.  Currently it can handle initial ticket
requests (Authentication Service, or AS), typically authenticated with
keys derived from passwords, and subsequent ticket requests (Ticket
Granting Service, or TGS), typically authenticated with the key
acquired during an AS exchange.

Currently there is very little configuration available, the only
variables are which ports the server should listen on and an optional
user name to @code{setuid} into after successfully listening to the
ports.

By default, Shishid listens on the @samp{kerberos} service port
(typically translated to 88 via @file{/etc/services}) on the UDP and
TCP protocols via IPv4 and (if your machine support it) IPv6 on all
interfaces on your machine.  Here is a typical startup.

@example
latte:/home/jas/src/shishi# /usr/local/sbin/shishid
Initializing GNUTLS...
Initializing GNUTLS...done
Listening on IPv4:*:kerberos/udp...done
Listening on IPv4:*:kerberos/tcp...done
Listening on IPv6:*:kerberos/udp...failed
socket: Address family not supported by protocol
Listening on IPv6:*:kerberos/tcp...failed
socket: Address family not supported by protocol
Listening on 2 ports...
@end example

Running as root is not recommended.  Any security problem in shishid
and your host may be compromised.  Therefor, we recommend using the
@samp{--setuid} parameter, as follows.

@example
latte:/home/jas/src/shishi# /usr/local/sbin/shishid --setuid=jas
Initializing GNUTLS...
Initializing GNUTLS...done
Listening on IPv4:*:kerberos/udp...done
Listening on IPv4:*:kerberos/tcp...done
Listening on IPv6:*:kerberos/udp...failed
socket: Address family not supported by protocol
Listening on IPv6:*:kerberos/tcp...failed
socket: Address family not supported by protocol
Listening on 2 ports...
User identity set to `jas' (22541)...
@end example

An alternative is to run shishid on an alternative port as a
non-privileged user.  To continue the example of setting up the
@code{EXAMPLE.ORG} realm as a non-privileged user from the preceding
section, we start the server listen on port 4711 via UDP on IPv4.

@example
jas@@latte:~$ /usr/local/sbin/shishid -l IPv4:*:4711/udp
Initializing GNUTLS...
Initializing GNUTLS...done
Listening on *:4711/tcp...
Listening on 1 ports...
shishid: Starting (GNUTLS `1.0.4')
shishid: Listening on *:4711/tcp socket 4
@end example

If you have set up the Shisa database as in the previous example, you
can now acquire tickets as follows.

@example
jas@@latte:~$ shishi -o 'realm-kdc=EXAMPLE.ORG,localhost:4711' \
   simon@@EXAMPLE.ORG
Enter password for `simon@@EXAMPLE.ORG':
simon@@EXAMPLE.ORG:
Authtime:       Fri Dec 12 01:41:01 2003
Endtime:        Fri Dec 12 01:57:41 2003
Server:         krbtgt/EXAMPLE.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 RENEWABLE INITIAL (12)
jas@@latte:~$
@end example

The output from Shishid on a successful invocation would look like:

@example
shishid: Has 131 bytes from *:4711/udp on socket 4
shishid: Processing 131 from *:4711/udp on socket 4
shishid: Trying AS-REQ
shishid: AS-REQ from simon@@EXAMPLE.ORG for krbtgt/EXAMPLE.ORG@@EXAMPLE.ORG
shishid: Matching client etype 18 against user key etype 18
shishid: Have 511 bytes for *:4711/udp on socket 4
shishid: Sending 511 bytes to *:4711/udp socket 4 via UDP
shishid: Listening on *:4711/udp socket 4
@end example

You may use the '-v' parameter for Shishid and Shishi to generate more
debugging information.

To illustrate what an application, such as the Shishi patched versions
of @acronym{GNU} lsh or Telnet from @acronym{GNU} InetUtils, would do
when contacting the host @samp{mail.example.org} we illustrate using
the TGS service as well.

@example
jas@@latte:~$ shishi -o 'realm-kdc=EXAMPLE.ORG,localhost:4711' \
   simon@@EXAMPLE.ORG host/mail.example.org
simon@@EXAMPLE.ORG:
Authtime:       Fri Dec 12 01:46:54 2003
Endtime:        Fri Dec 12 02:03:34 2003
Server:         host/mail.example.org key des3-cbc-sha1-kd (16)
Ticket key:     des3-cbc-sha1-kd (16) protected by aes256-cts-hmac-sha1-96 (18)
Ticket flags:   FORWARDED PROXIABLE (45398796)
jas@@latte:~$
@end example

This conclude our walk-through of setting up a new Kerberos realm
using Shishi.  It is quite likely that one or more steps failed, and
if so we encourage you to debug it and submit a patch, or at least
report it as a problem.  Heck, even letting us know if you got this
far would be of interest.  @xref{Bug Reports}.

@node Configuring DNS for KDC
@section Configuring DNS for KDC

Making sure the configuration files on all hosts running Shishi
clients include the addresses of your server is tedious.  If the
configuration files do not mention the KDC address for a realm, Shishi
will try to look up the information from DNS.  In order for Shishi to
find that information, you need to add the information to DNS.  For
this to work well, you need to set up a DNS zone with the same name as
your Kerberos realm.  The easiest is if you own the publicly visible
DNS name, such as @samp{example.org} if your realm is
@samp{EXAMPLE.ORG}, but you can set up an internal DNS server with the
information for your realm only.  If this is done, you do not need to
keep configuration files updated for the KDC addressing information.

@subsection DNS vs. Kerberos - Case Sensitivity of Realm Names

In Kerberos, realm names are case sensitive.  While it is strongly
encouraged that all realm names be all upper case this recommendation
has not been adopted by all sites.  Some sites use all lower case
names and other use mixed case.  DNS on the other hand is case
insensitive for queries but is case preserving for responses to TXT
queries.  Since "MYREALM", "myrealm", and "MyRealm" are all different
it is necessary that only one of the possible combinations of upper
and lower case characters be used.  This restriction may be lifted in
the future as the DNS naming scheme is expanded to support non-ASCII
names.

@subsection Overview - KDC location information

KDC location information is to be stored using the DNS SRV RR [RFC
2052].  The format of this RR is as follows:

Service.Proto.Realm TTL Class SRV Priority Weight Port Target

The Service name for Kerberos is always "_kerberos".

The Proto can be either "_udp", "_tcp", or "_tls._tcp".  If these SRV
records are to be used, a "_udp" record MUST be included.  If the
Kerberos implementation supports TCP transport, a "_tcp" record MUST
be included.  When using "_tcp" with "_kerberos", this indicates a
"raw" TCP connection without any additional encapsulation.  A
"_tls._tcp" record MUST be specified for all Kerberos implementations
that support communication with the KDC across TCP sockets
encapsulated using TLS [RFC2246] (@pxref{STARTTLS protected KDC exchanges}).

The Realm is the Kerberos realm that this record corresponds to.

TTL, Class, SRV, Priority, Weight, and Target have the standard
meaning as defined in RFC 2052.

As per RFC 2052 the Port number should be the value assigned to
"kerberos" by the Internet Assigned Number Authority (88).

@subsection Example - KDC location information

These are DNS records for a Kerberos realm ASDF.COM.  It has two
Kerberos servers, kdc1.asdf.com and kdc2.asdf.com.  Queries should be
directed to kdc1.asdf.com first as per the specified priority.
Weights are not used in these records.

@example
_kerberos._udp.ASDF.COM.        IN      SRV     0 0 88 kdc1.asdf.com.
_kerberos._udp.ASDF.COM.        IN      SRV     1 0 88 kdc2.asdf.com.
_kerberos._tcp.ASDF.COM.        IN      SRV     0 0 88 kdc1.asdf.com.
_kerberos._tcp.ASDF.COM.        IN      SRV     1 0 88 kdc2.asdf.com.
_kerberos._tls._tcp.ASDF.COM.   IN      SRV     0 0 88 kdc1.asdf.com.
_kerberos._tls._tcp.ASDF.COM.   IN      SRV     1 0 88 kdc2.asdf.com.
@end example

@subsection Security considerations

As DNS is deployed today, it is an unsecure service.  Thus the infor-
mation returned by it cannot be trusted.

Current practice for REALM to KDC mapping is to use hostnames to
indicate KDC hosts (stored in some implementation-dependent location,
but generally a local config file).  These hostnames are vulnerable
to the standard set of DNS attacks (denial of service, spoofed
entries, etc).  The design of the Kerberos protocol limits attacks of
this sort to denial of service.  However, the use of SRV records does
not change this attack in any way.  They have the same vulnerabilities
that already exist in the common practice of using hostnames for
KDC locations.

Implementations SHOULD provide a way of specifying this information
locally without the use of DNS.  However, to make this feature
worthwhile a lack of any configuration information on a client should
be interpretted as permission to use DNS.

@node Kerberos via TLS
@section Kerberos via TLS
@cindex GNUTLS
@cindex TLS
@cindex STARTTLS

If Shishi is built with support for GNUTLS, the messages exchanged
between clients and Shishid can be protected with TLS.  TLS is only
available over TCP connections.  A full discussion of the features TLS
have is out of scope here, but in short it means the communication is
integrity and privacy protected, and that users can use OpenPGP, X.509
or SRP (i.e., any mechanism supported by TLS) to authenticate
themselves to the Kerberos server.  For details on the implementation,
@xref{STARTTLS protected KDC exchanges}.

@subsection Setting up TLS resume
@cindex tls resume

Resuming earlier TLS session is supported and enabled by default.
This improves the speed of the TLS handshake, because results from
earlier negotiations can be re-used.  Currently the TLS resume
database is stored in memory (in constract to storing it on disk), in
both the client and in the server.  Because the server typically runs
for a long time, this is not a problem for that side.  The client is
typically not a long-running process though; the client usually is
invoked as part of applications like @samp{telnet} or @samp{login}.
However, because each use of the client library typically result in a
ticket, which is stored on disk and re-used by later processes, this
is likely not a serious problem because the number of different
tickets required by a user is usually quite small.  For the client,
TLS resume is typically only useful when you perform an initial
authentication (using a password) followed by a ticket request for a
service, in the same process.

You can configure the server, @samp{shishid} to never use TLS resume,
or to increase or decrease the number of distinct TLS connections that
can be resumed before they are garbage collected, see the
@samp{--resume-limit} parameter (@pxref{Parameters for shishid}).

@subsection Setting up Anonymous TLS
@cindex anonymous tls
@cindex Diffie Hellman key exchange

Anonymous TLS is the simplest to set up and use.  In fact, only the
client need to be informed that your KDC support TLS.  This can be
done in the configuration file with the @samp{/tls} parameter for
@samp{kdc-realm} (@pxref{realm-kdc,, Shishi Configuration}), or by
placing the KDC address in DNS using the @samp{_tls} SRV record
(@pxref{Configuring DNS for KDC}).

Let's start Shishid, listening on a TCP socket.  TLS require TCP.  TCP
sockets are automatically upgraded to TLS if the client request it.

@example
jas@@latte:~$ /usr/local/sbin/shishid -l IPv4:*:4711/tcp
Initializing GNUTLS...done
Listening on IPv4:*:4711/tcp...
Listening on 1 ports...
shishid: Starting (GNUTLS `1.0.4')
shishid: Listening on IPv4:*:4711/tcp socket 4
@end example

Let's use the client to talk with it, using TLS.

@example
jas@@latte:~$ shishi -o 'realm-kdc=EXAMPLE.ORG,localhost:4711/tls \
    simon@@EXAMPLE.ORG
Enter password for `simon@@EXAMPLE.ORG':
simon@@EXAMPLE.ORG:
Authtime:       Tue Dec 16 05:20:47 2003
Endtime:        Tue Dec 16 05:37:27 2003
Server:         krbtgt/EXAMPLE.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)
jas@@latte:~$
@end example

On success, the server will print the following debug information.

@example
shishid: Accepted socket 6 from socket 4 as IPv4:*:4711/tcp peer 127.0.0.1
shishid: Listening on IPv4:*:4711/tcp socket 4
shishid: Listening on IPv4:*:4711/tcp peer 127.0.0.1 socket 6
shishid: Has 4 bytes from IPv4:*:4711/tcp peer 127.0.0.1 on socket 6
shishid: Trying STARTTLS
shishid: TLS handshake negotiated protocol `TLS 1.0', key exchange `Anon DH', certficate type `X.509', cipher `AES 256 CBC', mac `SHA', compression `NULL', session not resumed
shishid: TLS anonymous authentication with 1024 bit Diffie-Hellman
shishid: Listening on IPv4:*:4711/tcp socket 4
shishid: Listening on IPv4:*:4711/tcp peer 127.0.0.1 socket 6
shishid: Has 131 bytes from IPv4:*:4711/tcp peer 127.0.0.1 on socket 6
shishid: Processing 131 from IPv4:*:4711/tcp peer 127.0.0.1 on socket 6
shishid: Trying AS-REQ
shishid: AS-REQ from simon@@EXAMPLE.ORG for krbtgt/EXAMPLE.ORG@@EXAMPLE.ORG
shishid: Matching client etype 18 against user key etype 18
shishid: Have 511 bytes for IPv4:*:4711/tcp peer 127.0.0.1 on socket 6
shishid: Sending 511 bytes to IPv4:*:4711/tcp peer 127.0.0.1 socket 6 via TLS
shishid: Listening on IPv4:*:4711/tcp socket 4
shishid: Listening on IPv4:*:4711/tcp peer 127.0.0.1 socket 6
shishid: Peer IPv4:*:4711/tcp peer 127.0.0.1 disconnected on socket 6
shishid: Closing IPv4:*:4711/tcp peer 127.0.0.1 socket 6
shishid: Listening on IPv4:*:4711/tcp socket 4
@end example

@subsection Setting up X.509 authenticated TLS
@cindex X.509 authentication
@cindex authenticated tls
@cindex client authentication
@cindex server authentication
@cindex certificate authority (@acronym{CA})

Setting up X.509 authentication is slightly more complicated than
anonymous authentication.  You need a X.509 certificate authority
(@acronym{CA}) that can generate certificates for your Kerberos server
and Kerberos clients.  It is often easiest to setup the @acronym{CA}
yourself.  Managing a @acronym{CA} can be a daunting task, and we only
give the bare essentials to get things up and running.  We suggest
that you study the relevant literature.  As a first step beyond this
introduction, you may wish to explore more secure forms of key storage
than storing them unencrypted on disk.

The following three sections describe how you create the @acronym{CA},
KDC certificate, and client certificates.  You can use any tool you
like for this task, as long as they generate X.509 (PKIX) certificates
in PEM format and RSA keys in PKCS#1 format.  Here we use
@file{certtool} that come with @acronym{GNUTLS}, which is widely
available.  We conclude by discussing how you use these certificates
in the KDC and in the Shishi client.

@subsubsection Create a Kerberos Certificate Authority

First create a @acronym{CA} key.

@example
jas@@latte:~$ certtool --generate-privkey \
   --outfile /usr/local/etc/shishi/shishi.key
Generating a private key...
Generating a 1024 bit RSA private key...
jas@@latte:~$
@end example

Then create the @acronym{CA} certificate.  Use whatever details you
prefer.

@example
jas@@latte:~$ certtool --generate-self-signed \
   --load-privkey /usr/local/etc/shishi/shishi.key \
   --outfile /usr/local/etc/shishi/shishi.cert
Generating a self signed certificate...
Please enter the details of the certificate's distinguished name. \
Just press enter to ignore a field.
Country name (2 chars): SE
Organization name: Shishi Example CA
Organizational unit name:
Locality name:
State or province name:
Common name: CA
This field should not be used in new certificates.
E-mail:
Enter the certificate's serial number (decimal): 0
 
 
Activation/Expiration time.
The generated certificate will expire in (days): 180
 
 
Extensions.
Does the certificate belong to an authority? (Y/N): y
Is this a web server certificate? (Y/N): n
Enter the e-mail of the subject of the certificate:
 
 
X.509 certificate info:
 
Version: 3
Serial Number (hex): 00
Validity:
        Not Before: Sun Dec 21 10:59:00 2003
        Not After: Fri Jun 18 11:59:00 2004
Subject: C=SE,O=Shishi Example CA,CN=CA
Subject Public Key Info:
        Public Key Algorithm: RSA
 
X.509 Extensions:
        Basic Constraints: (critical)
                CA:TRUE
 
Is the above information ok? (Y/N): y
 
 
Signing certificate...
jas@@latte:~$
@end example

@subsubsection Create a Kerberos KDC Certificate

First create the key for the KDC.

@example
jas@@latte:~$ certtool --generate-privkey \
   --outfile /usr/local/etc/shishi/shishid.key
Generating a private key...
Generating a 1024 bit RSA private key...
jas@@latte:~$
@end example

Then create actual KDC certificate, signed by the @acronym{CA}
certificate created in the previous step.

@example
jas@@latte:~$ certtool --generate-certificate \
   --load-ca-certificate /usr/local/etc/shishi/shishi.cert \
   --load-ca-privkey /usr/local/etc/shishi/shishi.key \
   --load-privkey /usr/local/etc/shishi/shishid.key \
   --outfile /usr/local/etc/shishi/shishid.cert
Generating a signed certificate...
Loading CA's private key...
Loading CA's certificate...
Please enter the details of the certificate's distinguished name. \
Just press enter to ignore a field.
Country name (2 chars): SE
Organization name: Shishi Example KDC
Organizational unit name:
Locality name:
State or province name:
Common name: KDC
This field should not be used in new certificates.
E-mail:
Enter the certificate's serial number (decimal): 0
 
 
Activation/Expiration time.
The generated certificate will expire in (days): 180
 
 
Extensions.
Does the certificate belong to an authority? (Y/N): n
Is this a web server certificate? (Y/N): n
Enter the e-mail of the subject of the certificate:
 
 
X.509 certificate info:
 
Version: 3
Serial Number (hex): 00
Validity:
        Not Before: Sun Dec 21 11:02:00 2003
        Not After: Fri Jun 18 12:02:00 2004
Subject: C=SE,O=Shishi Example KDC,CN=KDC
Subject Public Key Info:
        Public Key Algorithm: RSA
 
X.509 Extensions:
        Basic Constraints: (critical)
                CA:FALSE
 
Is the above information ok? (Y/N): y
 
 
Signing certificate...
jas@@latte:~$
@end example

@subsubsection Create a Kerberos Client Certificate

First create the key for the client.

@example
jas@@latte:~$ certtool --generate-privkey \
   --outfile ~/.shishi/client.key
Generating a private key...
Generating a 1024 bit RSA private key...
jas@@latte:~$
@end example

Then create the client certificate, signed by the @acronym{CA}.  An
alternative would be to have the KDC sign the client certificates.

@example
jas@@latte:~$ certtool --generate-certificate \
   --load-ca-certificate /usr/local/etc/shishi/shishi.cert \
   --load-ca-privkey /usr/local/etc/shishi/shishi.key \
   --load-privkey ~/.shishi/client.key \
   --outfile ~/.shishi/client.certs
Generating a signed certificate...
Loading CA's private key...
Loading CA's certificate...
Please enter the details of the certificate's distinguished name. \
Just press enter to ignore a field.
Country name (2 chars): SE
Organization name: Shishi Example Client
Organizational unit name:
Locality name:
State or province name:
Common name: Client
This field should not be used in new certificates.
E-mail:
Enter the certificate's serial number (decimal): 0
 
 
Activation/Expiration time.
The generated certificate will expire in (days): 180
 
 
Extensions.
Does the certificate belong to an authority? (Y/N): n
Is this a web server certificate? (Y/N): n
Enter the e-mail of the subject of the certificate:
 
 
X.509 certificate info:
 
Version: 3
Serial Number (hex): 00
Validity:
        Not Before: Sun Dec 21 11:04:00 2003
        Not After: Fri Jun 18 12:04:00 2004
Subject: C=SE,O=Shishi Example Client,CN=Client
Subject Public Key Info:
        Public Key Algorithm: RSA
 
X.509 Extensions:
        Basic Constraints: (critical)
                CA:FALSE
 
Is the above information ok? (Y/N): y
 
 
Signing certificate...
jas@@latte:~$
@end example

@subsubsection Starting KDC with X.509 authentication support

The KDC need the @acronym{CA} certificate (to verify client
certificates) and the server certificate and key (to authenticate
itself to the clients).  See elsewhere (@pxref{Parameters for
shishid}) for the entire description of the parameters.

@example
jas@@latte:~$ shishid -l *:4711/tcp \
   --x509cafile /usr/local/etc/shishi/shishi.cert \
   --x509certfile /usr/local/etc/shishi/shishid.cert \
   --x509keyfile /usr/local/etc/shishi/shishid.key
Initializing GNUTLS...
Parsed 1 CAs...
Loaded server certificate/key...
Generating Diffie-Hellman parameters...
Initializing GNUTLS...done
Listening on *:4711/tcp...
Listening on 1 ports...
shishid: Starting (GNUTLS `1.0.4')
shishid: Listening on *:4711/tcp socket 4
@end example

Then acquire tickets as usual.  In case you wonder how shishi finds
the client certificate and key, the filenames used above when
generating the client certificates happen to be the default filenames
for these files.  So it pick them up automatically.

@example
jas@@latte:~$ shishi -o 'realm-kdc=EXAMPLE.ORG,localhost:4711/tls' \
   simon@@EXAMPLE.ORG
Enter password for `simon@@EXAMPLE.ORG':
simon@@EXAMPLE.ORG:
Authtime:       Sun Dec 21 11:15:47 2003
Endtime:        Sun Dec 21 11:32:27 2003
Server:         krbtgt/EXAMPLE.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 RENEWABLE HWAUTHENT TRANSITEDPOLICYCHECKED OKASDELEGATE (12)
jas@@latte:~$
@end example

Here is what the server would print.

@example
shishid: Accepted socket 6 from socket 4 as *:4711/tcp peer 127.0.0.1
shishid: Listening on *:4711/tcp socket 4
shishid: Listening on *:4711/tcp peer 127.0.0.1 socket 6
shishid: Has 4 bytes from *:4711/tcp peer 127.0.0.1 on socket 6
shishid: Trying STARTTLS
shishid: TLS handshake negotiated protocol `TLS 1.0', key exchange `RSA', certficate type `X.509', cipher `AES 256 CBC', mac `SHA', compression `NULL', session not resumed
shishid: TLS client certificate `C=SE,O=Shishi Example Client,CN=Client', issued by `C=SE,O=Shishi Example CA,CN=CA', serial number `00', MD5 fingerprint `a5:d3:1f:58:76:e3:58:cd:2d:eb:f7:45:a2:4b:52:f9:', activated `Sun Dec 21 11:04:00 2003', expires `Fri Jun 18 12:04:00 2004', version #3, key RSA modulus 1024 bits, currently EXPIRED
shishid: Listening on *:4711/tcp socket 4
shishid: Listening on *:4711/tcp peer 127.0.0.1 socket 6
shishid: Has 131 bytes from *:4711/tcp peer 127.0.0.1 on socket 6
shishid: Processing 131 from *:4711/tcp peer 127.0.0.1 on socket 6
shishid: Trying AS-REQ
shishid: AS-REQ from simon@@EXAMPLE.ORG for krbtgt/EXAMPLE.ORG@@EXAMPLE.ORG
shishid: Matching client etype 18 against user key etype 18
shishid: Have 511 bytes for *:4711/tcp peer 127.0.0.1 on socket 6
shishid: Sending 511 bytes to *:4711/tcp peer 127.0.0.1 socket 6 via TLS
shishid: Listening on *:4711/tcp socket 4
shishid: Listening on *:4711/tcp peer 127.0.0.1 socket 6
shishid: Peer *:4711/tcp peer 127.0.0.1 disconnected on socket 6
shishid: Closing *:4711/tcp peer 127.0.0.1 socket 6
shishid: Listening on *:4711/tcp socket 4
@end example


@node Multiple servers
@section Multiple servers
@cindex remote databases
@cindex LDAP
@cindex SQL

@cindex NFS
@cindex IPSEC
@cindex rsync
Setting up multiple servers is as easy as replicating the user
database.  Since the default @samp{file} user database is stored in
the normal file system, you can use any common tools to replicate a
file system.  Network file system like @acronym{NFS} (properly secured
by, e.g., a point-to-point symmetrically encrypted @acronym{IPSEC}
connection) and file synchronizing tools like @samp{rsync} are typical
choices.

@cindex master server
@cindex secondary server
The secondary server should be configured just like the master server.
If you use the @samp{file} database over @acronym{NFS} you do not have
to make any modifications.  If you use, e.g., a cron job to
@samp{rsync} the directory every hour or so, you may want to add a
@samp{--read-only} flag to the Shisa @samp{db} definition
(@pxref{Shisa Configuration}).  That way, nobody will be lured into
creating or changing information in the database on the secondary
server, which only would be overwritten during the next
synchronization.

@example
db --read-only file /usr/local/var/backup-shishi
@end example

@cindex concurrent writers
The @samp{file} database is designed so it doesn't require file
locking in the file system, which may be unreliable in some network
file systems or implementations.  It is also designed so that multiple
concurrent readers and writers may access the database without causing
corruption.

@strong{Warning:} The last paragraph is currently not completely
accurate.  There may be race conditions with concurrent writers.  None
should cause infinite loops or data loss.  However, unexpected results
might occur if two writers try to update information about a principal
simultaneous.

If you use a remote @acronym{LDAP} server or @acronym{SQL} database to
store the user database, and access it via a Shisa backend, you have
make sure your Shisa backend handle concurrent writers properly.  If
you use a modern @acronym{SQL} database, this probably is not a
concern.  If it is a problem, you may be able to work around it by
implementing some kind of synchronization or semaphore mechanism.  If
all else sounds too complicated, you can set up the secondary servers
as @samp{--read-only} servers, although you will lose some
functionality (like changing passwords via the secondary server, or
updating timestamps when the last ticket request occurred).

One function that is of particular use for users with remote databases
(be it @acronym{LDAP} or @acronym{SQL}) is the ``database override''
feature.  Using this you can have the security critical principals
(such as the ticket granting ticket) stored on local file system
storage, but use the remote database for user principals.  Of course,
you must keep the local file system storage synchronized between all
servers, as before.  Here is an example configuration.

@example
db --read-only file /var/local/master
db ldap kdc.example.org ca=/etc/shisa/kdc-ca.pem
@end example

This instruct the Shisa library to access the two databases
sequentially, for each query using the first database that know about
the requested principal.  If you put the @samp{krbtgt/REALM} principal
in the local @samp{file} database, this will override the
@acronym{LDAP} interface.  Naturally, you can have as many @samp{db}
definition lines as you wish.

@cindex High Availability
Users with remote databases can also investigate a so called @i{High
Availability} mode.  This is useful if you wish to have your Kerberos
servers be able to continue to operate even when the remote database
is offline.  This is achieved via the @samp{--ignore-errors} flag in
the database definition.  Here is a sample configuration.

@example
db --ignore-errors ldap kdc.example.org ca=/etc/shisa/kdc-ca.pem
db --read-only file /var/cache/ldap-copy
@end example

This instruct the Shisa library to try the @acronym{LDAP} backend
first, but if it fails, instead of returning an error, continue to try
the operation on a read only local @samp{file} based database.  Of
course, write requests will still fail, but it may be better than
halting the server completely.  To make this work, you first need to
set up a cron job on a, say, hourly basis, to make a copy of the
remote database and store it in the local file database.  That way,
when the remote server goes away, fairly current information will
still be available locally.

@cindex fail over
If you also wish to experiment with read-write fail over, here is an
idea for the configuration.

@example
db --ignore-errors ldap kdc.example.org ca=/etc/shisa/kdc-ca.pem
db --ignore-errors --read-only file /var/cache/ldap-copy
db file /var/cache/local-updates
@end example

This is similar to the previous, but it will ignore errors reading and
writing from the first two databases, ultimately causing write
attempts to end up in the final @samp{file} based database.  Of
course, you would need to create tools to feed back any local updates
made while the remote server was down.  It may also be necessary to
create a special backend for this purpose, which can auto create
principals that are used.

We finish with an example that demonstrate all the ideas presented.

@example
db --read-only file /var/local/master
db --ignore-errors ldap kdc.example.org ca=/etc/shisa/kdc-ca.pem
db --ignore-errors --read-only file /var/cache/ldap-copy
db file /var/cache/local-updates
@end example

@node Developer information
@section Developer information

The Programming API for Shisa is described below (@pxref{Kerberos
Database Functions}); this section is about extending Shisa, and
consequently Shishi, to use your own user database system.  You may
want to store your Kerberos user information on an LDAP database
server, for example.

Adding a new backend is straight forward.  You need to implement the
backend API function set, add the list of API functions to
@file{db/db.c} and possibly also add any library dependencies to the
Makefile.

The simplest way to write a new backend is to start from the existing
@samp{file} based database, in @file{db/file.c}, and modify the entry
points as needed.

Note that the current backend API will likely change before it is
frozen.  We may describe it in detail here when it has matured.
However, currently it is similar to the external Shisa API
(@pxref{Kerberos Database Functions}).

There should be no need to modify anything else in the Shisa library,
and certainly not in the Shishi library or the @file{shishid} server.

Naturally, we would appreciate if you would send us your new backend,
if you believe it is generally useful (@pxref{Bug Reports}).

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

This chapter discuss the underlying assumptions of Kerberos, contain a
glossary to Kerberos concepts, give you background information on
choosing realm and principal names, and describe all parameters and
configuration file syntaxes for the Shishi tools.

@menu
* Environmental Assumptions::   Kerberos 5 assumptions about your system.
* Glossary of terms::           Glossary of Kerberos related terminology.
* Realm and Principal Naming::  How to name your realm and principals.
* Shishi Configuration::        Explains the Core Shishi configuration file.
* Shisa Configuration::         Explains the Shisa database definition file.
* Parameters for shishi::       Command line parameters for 'shishi'.
* Parameters for shishid::      Command line parameters for 'shishid'.
* Parameters for shisa::        Command line parameters for 'shisa'.
* Environment variables::       Overriding compile-time defaults at run-time.
* Date input formats::          Details of the understood date formats.
@end menu

@node Environmental Assumptions
@section Environmental Assumptions

Kerberos imposes a few assumptions on the environment in which it can
properly function:

@itemize @bullet

@item
"Denial of service" attacks are not solved with Kerberos. There
are places in the 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.
@item
Each host on the network MUST have a clock which is "loosely
synchronized" to the time of the other hosts; this synchronization
is used to reduce the bookkeeping needs of application servers
when they do replay detection. The degree of "looseness" can be
configured on a per-server basis, but is typically on the order of
5 minutes. If the clocks are synchronized over the network, the
clock synchronization protocol MUST itself be secured from network
attackers.
@item
Principal identifiers are not recycled on a short-term basis. A
typical mode of access control will use access control lists
(ACLs) to grant permissions to particular principals. If a stale
ACL entry remains for a deleted principal and the principal
identifier is reused, the new principal will inherit rights
specified in the stale ACL entry. By not re-using principal
identifiers, the danger of inadvertent access is removed.
@end itemize

@node Glossary of terms
@section Glossary of terms

@table @asis
@item Authentication
@cindex Authentication
Verifying the claimed identity of a principal.

@item Authentication header
@cindex 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
@cindex Authentication path
A sequence of intermediate realms transited in the authentication
process when communicating from one realm to another.

@item Authenticator
@cindex 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
@cindex 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 Capability
@cindex Capability
A token that grants the bearer permission to access an object or
service. In Kerberos, this might be a ticket whose use is
restricted by the contents of the authorization data field, but
which lists no network addresses, together with the session key
necessary to use the ticket.

@item Ciphertext
@cindex Ciphertext
The output of an encryption function. Encryption transforms
plaintext into ciphertext.

@item Client
@cindex Client
A process that makes use of a network service on behalf of a user.
Note that in some cases a 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
@cindex Credentials
A ticket plus the secret session key necessary to successfully use
that ticket in an authentication exchange.

@item Encryption Type (etype)
@cindex Encryption Type (etype)
When associated with encrypted data, an encryption type identifies
the algorithm used to encrypt the data and is used to select the
appropriate algorithm for decrypting the data.  Encryption type
tags are communicated in other messages to enumerate algorithms
that are desired, supported, preferred, or allowed to be used for
encryption of data between parties.  This preference is combined
with local information and policy to select an algorithm to be
used.

@item KDC
@cindex 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
@cindex Kerberos
The name given to the Project Athena's authentication service, the
protocol used by that service, or the code used to implement the
authentication service.  The name is adopted from the three-headed
dog which guards Hades.

@item Key Version Number (kvno)
@cindex Key Version Number (kvno)
A tag associated with encrypted data identifies which key was used
for encryption when a long lived key associated with a principal
changes over time.  It is used during the transition to a new key
so that the party decrypting a message can tell whether the data
was encrypted using the old or the new key.

@item Plaintext
@cindex Plaintext
The input to an encryption function or the output of a decryption
function. Decryption transforms ciphertext into plaintext.

@item Principal
@cindex Principal
A named client or server entity that participates in a network
communication, with one name that is considered canonical.

@item Principal identifier
@cindex Principal identifier
The canonical name used to uniquely identify each different
principal.

@item Seal
@cindex 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
@cindex 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 MAY be derived
from a password.

@item Server
@cindex Server
A particular Principal which provides a resource to network
clients.  The server is sometimes referred to as the Application
Server.

@item Service
@cindex Service
A resource provided to network clients; often provided by more
than one server (for example, remote file service).

@item Session key
@cindex Session key
A temporary encryption key used between two principals, with a
lifetime limited to the duration of a single login "session".  In
the Kerberos system, a session key is generated by the KDC.  The
session key is distinct from the sub-session key, described next..

@item Sub-session key
@cindex 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. The sub-
session key is also referred to as the subkey.

@item Ticket
@cindex Ticket
@cindex Kerberos 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 table

@node Realm and Principal Naming
@section Realm and Principal Naming

This section contains the discussion on naming realms and principals
from the Kerberos specification.

@subsection Realm Names

Although realm names are encoded as GeneralStrings and although a
realm can technically select any name it chooses, interoperability
across realm boundaries requires agreement on how realm names are to
be assigned, and what information they imply.

To enforce these conventions, each realm MUST conform to the
conventions itself, and it MUST require that any realms with which
inter-realm keys are shared also conform to the conventions and
require the same from its neighbors.

Kerberos realm names are case sensitive. Realm names that differ only
in the case of the characters are not equivalent. There are presently
three styles of realm names: domain, X500, and other. Examples of
each style follow:

@example
     domain:   ATHENA.MIT.EDU
       X500:   C=US/O=OSF
      other:   NAMETYPE:rest/of.name=without-restrictions
@end example

Domain syle realm names MUST look like domain names: they consist of
components separated by periods (.) and they contain neither colons
(:) nor slashes (/). Though domain names themselves are case
insensitive, in order for realms to match, the case must match as
well. When establishing a new realm name based on an internet domain
name it is recommended by convention that the characters be converted
to upper case.

X.500 names contain an equal (=) and cannot contain a colon (:)
before the equal. The realm names for X.500 names will be string
representations of the names with components separated by slashes.
Leading and trailing slashes will not be included. Note that the
slash separator is consistent with Kerberos implementations based on
RFC1510, but it is different from the separator recommended in
RFC2253.

Names that fall into the other category MUST begin with a prefix that
contains no equal (=) or period (.) and the prefix MUST be followed
by a colon (:) and the rest of the name. All prefixes must be
assigned before they may be used. Presently none are assigned.

The reserved category includes strings which do not fall into the
first three categories. All names in this category are reserved. It
is unlikely that names will be assigned to this category unless there
is a very strong argument for not using the 'other' category.

These rules guarantee that there will be no conflicts between the
various name styles. The following additional constraints apply to
the assignment of realm names in the domain and X.500 categories: the
name of a realm for the domain or X.500 formats must either be used
by the organization owning (to whom it was assigned) an Internet
domain name or X.500 name, or in the case that no such names are
registered, authority to use a realm name MAY be derived from the
authority of the parent realm. For example, if there is no domain
name for E40.MIT.EDU, then the administrator of the MIT.EDU realm can
authorize the creation of a realm with that name.

This is acceptable because the organization to which the parent is
assigned is presumably the organization authorized to assign names to
its children in the X.500 and domain name systems as well. If the
parent assigns a realm name without also registering it in the domain
name or X.500 hierarchy, it is the parent's responsibility to make
sure that there will not in the future exist a name identical to the
realm name of the child unless it is assigned to the same entity as
the realm name.

@subsection Principal Names

As was the case for realm names, conventions are needed to ensure
that all agree on what information is implied by a principal name.
The name-type field that is part of the principal name indicates the
kind of information implied by the name. The name-type SHOULD be
treated only as a hint to interpreting the meaning of a name. It is
not significant when checking for equivalence. Principal names that
differ only in the name-type identify the same principal. The name
type does not partition the name space. Ignoring the name type, no
two names can be the same (i.e. at least one of the components, or
the realm, MUST be different). The following name types are defined:

@example
name-type      value   meaning

NT-UNKNOWN        0  Name type not known
NT-PRINCIPAL      1  Just the name of the principal as in DCE, or for users
NT-SRV-INST       2  Service and other unique instance (krbtgt)
NT-SRV-HST        3  Service with host name as instance (telnet, rcommands)
NT-SRV-XHST       4  Service with host as remaining components
NT-UID            5  Unique ID
NT-X500-PRINCIPAL 6  Encoded X.509 Distingished name [RFC 2253]
NT-SMTP-NAME      7  Name in form of SMTP email name (e.g. user@@foo.com)
NT-ENTERPRISE    10   Enterprise name - may be mapped to principal name
@end example

When a name implies no information other than its uniqueness at a
particular time the name type PRINCIPAL SHOULD be used. The principal
name type SHOULD be used for users, and it might also be used for a
unique server. If the name is a unique machine generated ID that is
guaranteed never to be reassigned then the name type of UID SHOULD be
used (note that it is generally a bad idea to reassign names of any
type since stale entries might remain in access control lists).

If the first component of a name identifies a service and the
remaining components identify an instance of the service in a server
specified manner, then the name type of SRV-INST SHOULD be used. An
example of this name type is the Kerberos ticket-granting service
whose name has a first component of krbtgt and a second component
identifying the realm for which the ticket is valid.

If the first component of a name identifies a service and there is a
single component following the service name identifying the instance
as the host on which the server is running, then the name type SRV-
HST SHOULD be used. This type is typically used for Internet services
such as telnet and the Berkeley R commands. If the separate
components of the host name appear as successive components following
the name of the service, then the name type SRV-XHST SHOULD be used.
This type might be used to identify servers on hosts with X.500 names
where the slash (/) might otherwise be ambiguous.

A name type of NT-X500-PRINCIPAL SHOULD be used when a name from an
X.509 certificate is translated into a Kerberos name. The encoding of
the X.509 name as a Kerberos principal shall conform to the encoding
rules specified in RFC 2253.

A name type of SMTP allows a name to be of a form that resembles a
SMTP email name. This name, including an "@@" and a domain name, is
used as the one component of the principal name.

A name type of UNKNOWN SHOULD be used when the form of the name is
not known. When comparing names, a name of type UNKNOWN will match
principals authenticated with names of any type. A principal
authenticated with a name of type UNKNOWN, however, will only match
other names of type UNKNOWN.

Names of any type with an initial component of 'krbtgt' are reserved
for the Kerberos ticket granting service. @xref{krbtgt,, Name of the
TGS}, for the form of such names.

@subsubsection Name of server principals

The principal identifier for a server on a host will generally be
composed of two parts: (1) the realm of the KDC with which the server
is registered, and (2) a two-component name of type NT-SRV-HST if the
host name is an Internet domain name or a multi-component name of
type NT-SRV-XHST if the name of the host is of a form such as X.500
that allows slash (/) separators. The first component of the two- or
multi-component name will identify the service and the latter
components will identify the host. Where the name of the host is not
case sensitive (for example, with Internet domain names) the name of
the host MUST be lower case. If specified by the application protocol
for services such as telnet and the Berkeley R commands which run
with system privileges, the first component MAY be the string 'host'
instead of a service specific identifier.

@subsubsection Name of the TGS
@anchor{krbtgt}

The principal identifier of the ticket-granting service shall be
composed of three parts: (1) the realm of the KDC issuing the TGS
ticket (2) a two-part name of type NT-SRV-INST, with the first part
"krbtgt" and the second part the name of the realm which will accept
the ticket-granting ticket. For example, a ticket-granting ticket
issued by the ATHENA.MIT.EDU realm to be used to get tickets from the
ATHENA.MIT.EDU KDC has a principal identifier of "ATHENA.MIT.EDU"
(realm), ("krbtgt", "ATHENA.MIT.EDU") (name). A ticket-granting
ticket issued by the ATHENA.MIT.EDU realm to be used to get tickets
from the MIT.EDU realm has a principal identifier of "ATHENA.MIT.EDU"
(realm), ("krbtgt", "MIT.EDU") (name).

@subsection Choosing a principal with which to communicate

The Kerberos protocol provides the means for verifying (subject to
the assumptions in @ref{Environmental Assumptions}) that the entity with which one communicates
is the same entity that was registered with the KDC using the claimed
identity (principal name). It is still necessary to determine whether
that identity corresponds to the entity with which one intends to
communicate.

When appropriate data has been exchanged in advance, this
determination may be performed syntactically by the application based
on the application protocol specification, information provided by
the user, and configuration files. For example, the server principal
name (including realm) for a telnet server might be derived from the
user specified host name (from the telnet command line), the "host/"
prefix specified in the application protocol specification, and a
mapping to a Kerberos realm derived syntactically from the domain
part of the specified hostname and information from the local
Kerberos realms database.

One can also rely on trusted third parties to make this
determination, but only when the data obtained from the third party
is suitably integrity protected while resident on the third party
server and when transmitted.  Thus, for example, one should not rely
on an unprotected domain name system record to map a host alias to
the primary name of a server, accepting the primary name as the party
one intends to contact, since an attacker can modify the mapping and
impersonate the party with which one intended to communicate.

Implementations of Kerberos and protocols based on Kerberos MUST NOT
use insecure DNS queries to canonicalize the hostname components of
the service principal names.  In an environment without secure name
service, application authors MAY append a statically configured
domain name to unqualified hostnames before passing the name to the
security mechanisms, but should do no more than that.  Secure name
service facilities, if available, might be trusted for hostname
canonicalization, but such canonicalization by the client SHOULD NOT
be required by KDC implementations.

Implementation note: Many current implementations do some degree of
canonicalization of the provided service name, often using DNS even
though it creates security problems. However there is no consistency
among implementations about whether the service name is case folded
to lower case or whether reverse resolution is used. To maximize
interoperability and security, applications SHOULD provide security
mechanisms with names which result from folding the user-entered name
to lower case, without performing any other modifications or
canonicalization.

@subsection Principal Name Form

Principal names consist of a sequence of strings, which is often
tedious to parse.  Therefor, Shishi often uses a ``printed'' form of
principal which embed the entire principal name string sequence, and
optionally also the realm, into one string.  The format is taken from
the Kerberos 5 @acronym{GSS-API} mechanism (@acronym{RFC} 1964).

The elements included within this name representation are as follows,
proceeding from the beginning of the string:

@enumerate
@item
One or more principal name components; if more than one
principal name component is included, the components are
separated by `/`.  Arbitrary octets may be included within
principal name components, with the following constraints and
special considerations:
@enumerate a
@item
Any occurrence of the characters `@@` or `/` within a
name component must be immediately preceded by the `\`
quoting character, to prevent interpretation as a component
or realm separator.
@item
The ASCII newline, tab, backspace, and null characters
may occur directly within the component or may be
represented, respectively, by `\n`, `\t`, `\b`, or `\0`.
@item
If the `\` quoting character occurs outside the contexts
described in (1a) and (1b) above, the following character is
interpreted literally.  As a special case, this allows the
doubled representation `\\` to represent a single occurrence
of the quoting character.
@item
An occurrence of the `\` quoting character as the last
character of a component is illegal.
@end enumerate
@item
Optionally, a `@@` character, signifying that a realm name
immediately follows. If no realm name element is included, the
local realm name is assumed.  The `/` , `:`, and null characters
may not occur within a realm name; the `@@`, newline, tab, and
backspace characters may be included using the quoting
conventions described in (1a), (1b), and (1c) above.
@end enumerate

@node Shishi Configuration
@section Shishi Configuration
@cindex 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 typically
located in @file{/usr/local/etc/shishi/shishi.conf} (compare
@samp{shishi --system-configuration-file}).  If the first non white
space character of a line is a '#', the line is ignored.  Empty lines
are also ignored.

All tokens are valid in both the system and the user configuration
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 that file.  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-noise}, @samp{verbose-crypto}, @samp{verbose-crypto-noise}

Enable verbose library messages.  E.g.,

@example
verbose
verbose-noise
@end example

@subsection @samp{realm-kdc}
@anchor{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.
@xref{Date input formats}, for the long story.

As an extra feature, if the time specified by your string correspond
to a time during the last 24 hours, an extra day is added to it.  This
allows you to specify relative times such as "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 Shisa Configuration
@section Shisa Configuration
@cindex database definition
@cindex specifying user database
@cindex user database definition

The configuration file for Shisa is typically stored in
@file{/usr/local/etc/shishi/shisa.conf}.  If the first non white space
character of a line is a '#', the line is ignored.  Empty lines are
also ignored.

@subsection @samp{db}

Currently the only configuration options available is the @code{db}
token that define the databases to use.  The syntax is:

@example
db [OPTIONS] <TYPE> [LOCATION] [PARAMETERS ...]
@end example

Specify the data sources for Kerberos 5 data.  Multiple entries,
even of the same data source type, are allowed.  The data sources
are accessed in the same sequence as they are defined here.  If an
entry is found in one data source, it will be used for the
operations, without searching the remaining data sources.  Valid
OPTIONS include:

@example
--read-only       No data is written to this data source.
--ignore-errors   Ignore failures in this backend.
@end example

The default (when the configuration file is empty) uses one "file"
data source (see below), but for a larger installation you may want to
combine several data sources.  Here is an example.

@example
db --read-only file /var/local/master
db --ignore-errors ldap kdc.example.org ca=/etc/shisa/kdc-ca.pem
db --read-only file /var/cache/ldap-copy
@end example

This demonstrate how you can store critical principals on local disk
(the first entry, /var/local/master) that will always be found without
looking in the LDAP directory.  The critical principals could be,
e.g., krbtgt/EXAMPLE.ORG.  The second entry denote a LDAP server that
could hold user principals.  As you can see, Shisa will not let the
caller know about errors with the LDAP source (they will be logged,
however).  Instead, if for instance the LDAP server has crashed, Shisa
would continue and read from the /var/cache/ldap-copy file source.
That file source may have been set up to contain a copy of the data in
the LDAP server, perhaps made on an hourly basis, so that your server
will be able to serve recent data even in case of a crash.  Any
updates or passwords change requests will however not be possible
while the LDAP server is inaccessible, to reduce the problem of
synchronizing data back into the LDAP server once it is online again.

Currently only the "file" data source is supported, and denote a
data source that use the standard file system for storage.

Valid syntaxes for the "file" database:

@example
db file PATH
@end example

Examples:

@example
db file /var/shishi
db file /usr/share/shishi read-only
@end example

If no @samp{db} tokens are present, the default will be:

@example
db file /usr/local/var/shishi
@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 arguments to long options are mandatory for short options
too.

@example
Usage: shishi [OPTIONS]... [CLIENT [SERVER]]...
 
  -h, --help                              Print help and exit
  -V, --version                           Print version and exit
 
Commands:
  -d, --destroy                           Destroy tickets in local cache,
                                            limited by any --client-name or
                                            --server-name.  (default=off)
  -l, --list                              List tickets in local cache, limited
                                            by any --client-name and
                                            --server-name.  (default=off)
  -r, --renew                             Renew ticket.  Use --server-name to
                                            specify ticket, default is the
                                            most recent renewable ticket
                                            granting ticket for the default
                                            realm.  (default=off)
 
Flags:
      --forwardable                       Get a forwardable ticket, i.e., one
                                            that can be used to get forwarded
                                            tickets.  (default=off)
      --forwarded                         Get a forwarded ticket.  (default=
                                            off)
      --proxiable                         Get a proxiable ticket, i.e., one
                                            that can be used to get proxy
                                            tickets.  (default=off)
      --proxy                             Get a proxy ticket.  (default=off)
      --renewable                         Get a renewable ticket.  (default=
                                            off)
 
Options:
      --client-name=NAME                  Client name. Default is login
                                            username.
  -E, --encryption-type=ETYPE,[ETYPE...]  Encryption types to use.  ETYPE is
                                            either registered name or integer.
                                             Valid values include 'aes128',
                                            'aes256', 'aes' (same as
                                            'aes256'), '3des', 'des-md5',
                                            'des-md4', 'des-crc', 'des' (same
                                            as 'des-md5'), and 'arcfour'.
  -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.
      --realm=STRING                      Set default realm.
      --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.
      --server-name=NAME                  Server name. Default is
                                            'krbtgt/REALM' where REALM is
                                            client 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 client realm.
 
Other options:
      --configuration-file=FILE           Read user configuration from FILE.
  -c, --ticket-file=FILE                  Read tickets from FILE.
  -o, --library-options=STRING            Parse STRING as a configuration file
                                            statement.
  -q, --quiet                             Don't produce any diagnostic output.
                                              (default=off)
      --system-configuration-file=FILE    Read system configuration from FILE.
      --ticket-write-file=FILE            Write tickets from FILE.  Default is
                                            to write them back to where they
                                            were read from.
  -v, --verbose                           Produce verbose output.
                                              (default=off)
@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 arguments to long options are mandatory for short options
too.

@example
Usage: shishid [OPTIONS]...
 
  -h, --help                            Print help and exit
  -V, --version                         Print version and exit
 
Commands:
  -l, --listen=[FAMILY:]ADDR:PORT/TYPE  Sockets to listen for queries on.
                                          Family is `IPv4' or `IPv6', if
                                          absent the family is decided by
                                          gethostbyname(ADDR). 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'.
  -u, --setuid=NAME                     After binding socket, set user
                                          identity.
 
TLS settings:
      --x509cafile=FILE                 X.509 certificate authorities used to
                                          verify client certificates, in PEM
                                          format.
      --x509certfile=FILE               X.509 server certificate, in PEM
                                          format.
      --x509crlfile=FILE                X.509 certificate revocation list to
                                          check for revoked client
                                          certificates, in PEM format.
      --x509keyfile=FILE                X.509 server certificate key, in PEM
                                          format.
       --resume-limit=SHORT             Keep track of up to this many TLS
                                         sessions for resume purposes (0 to
                                         disable TLS resume).  (default=`50')
 
Other options:
  -c, --configuration-file=FILE         Use specified configuration file.
  -v, --verbose                         Produce verbose output.
                                            (default=off)
  -q, --quiet                           Don't produce any diagnostic output.
                                            (default=off)
@end example

@node Parameters for shisa
@section Parameters for shisa

The purpose of @samp{shisa} is to manipulate information stored in the
Kerberos 5 database used by Shishi.

Mandatory arguments to long options are mandatory for short options
too.

@example
Usage: shisa [OPTIONS]... [REALM [PRINCIPAL]]...

  -h, --help                         Print help and exit
  -V, --version                      Print version and exit
 
Operations:
  -a, --add                          Add realm or principal to database.
  -d, --dump                         Dump entries in database.
  -n, --key-add                      Add new key to a principal in database.
      --key-remove                   Remove a key from a principal in
                                       database.
  -l, --list                         List entries in database.
  -m, --modify                       Modify principal entry in database.
  -r, --remove                       Remove realm or principal from database.
 
Parameters:
  -f, --force                        Allow removal of non-empty realms.
                                         (default=off)
      --enabled                      Only dump or list enabled principals.
                                         (default=off)
      --disabled                     Only dump or list disabled principals.
                                         (default=off)
      --keys                         Print cryptographic key and password in
                                       hostkey format.  (default=off)
 
Values:
  -E, --encryption-type=STRING       Override default key encryption type.
                                       Valid values include 'aes128',
                                       'aes256', 'aes' (same as 'aes256'),
                                       '3des', 'des-md5', 'des-md4',
                                       'des-crc', 'des' (same as 'des-md5'),
                                       and 'arcfour'.
      --key-version=NUMBER           Version of key.
      --password[=STRING]            Derive key from this password.
      --random                       Use a random key.  (default)
      --salt=STRING                  Use specified salt for deriving key.
                                       Defaults to concatenation of realm and
                                       (unwrapped) principal name.
      --string-to-key-parameter=HEX  Encryption algorithm specific parameter
                                       for password derivation.  Currently
                                       only the AES algorithm can utilize
                                       this, where it is interpreted as the
                                       iteration count of the PKCS#5 PBKDF2
                                       key deriver.
 
Other options:
  -c, --configuration-file=FILE      Use specified configuration file.
  -o, --library-options=STRING       Parse string as configuration file
                                       statement.
  -v, --verbose                      Produce verbose output.
                                         (default=off)
  -q, --quiet                        Don't produce any diagnostic output.
                                         (default=off)
@end example

@node Environment variables
@section Environment variables

A few of the compile-time defaults may be overridden at run-time by
using environment variables.  The following variables are supported.

@itemize @bullet

@item @env{SHISHI_CONFIG}
Specify the location of the default system configuration file.  Used
by the Shishi library.  If not specified, the default is specified at
compile-time and is usually @file{$prefix/etc/shishi.conf}.

@item @env{SHISHI_HOME}
Specify the user specific directory for configuration files, ticket
cache, etc.  Used by the Shishi library.  If not specified, it is
computed as @code{$HOME/.shishi}.

@item @env{SHISHI_USER}
Specify the default principal user name.  Used by the Shishi library.
If not specified, it is taken from the environment variable
@env{USER}.

@item @env{SHISHI_TICKETS}
Specify the file name of the ticket cache.  Used by the Shishi
library.  If not specified, it will be @code{$SHISHI_HOME/tickets}, or
@code{$HOME/.shishi/tickets} if @code{$SHISHI_HOME} is not specified.

@end itemize

@lowersections
@include getdate.texi
@raisesections

@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.
* KRB-ERROR Functions::         Low-level KRB-ERROR functions.
* Cryptographic Functions::     Low-level cryptographic functions.
* X.509 Functions::             Utility functions for X.509 support.
* Utility Functions::           Utilities for use in the global context.
* ASN.1 Functions::             Perform low-level ASN.1 manipulations.
* Error Handling::              Error codes and such.
* Examples::                    Example code.
* Kerberos Database Functions:: The Shisa generic database interface.
* 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 texi/version.c.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 texi/init.c.texi
@include texi/cfg.c.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 texi/tkts.c.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 texi/ap.c.texi
@include texi/apreq.c.texi
@include texi/aprep.c.texi
@include texi/encapreppart.c.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 texi/safe.c.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

@include texi/priv.c.texi


@node Ticket Functions
@section Ticket Functions

A Ticket is an ASN.1 structured that can be used to authenticate the
holder to services.  It contain an encrypted part, which the ticket
holder cannot see, but can be encrypted by the service, and various
information about the user and service, including an encryption key to
use for the connection.  @xref{Ticket (ASN.1) Functions}, for more
details on the ASN.1 structure of a ticket.

@include texi/tkt.c.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 texi/as.c.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 texi/tgs.c.texi


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

@xref{Ticket Functions}, for an high-level overview of tickets.  The
following illustrates the Ticket and EncTicketPart ASN.1 structures.

@verbatim
Ticket          ::= [APPLICATION 1] SEQUENCE {
        tkt-vno         [0] INTEGER (5),
        realm           [1] Realm,
        sname           [2] PrincipalName,
        enc-part        [3] EncryptedData -- EncTicketPart
}

-- Encrypted part of ticket
EncTicketPart   ::= [APPLICATION 3] SEQUENCE {
        flags                   [0] TicketFlags,
        key                     [1] EncryptionKey,
        crealm                  [2] Realm,
        cname                   [3] PrincipalName,
        transited               [4] TransitedEncoding,
        authtime                [5] KerberosTime,
        starttime               [6] KerberosTime OPTIONAL,
        endtime                 [7] KerberosTime,
        renew-till              [8] KerberosTime OPTIONAL,
        caddr                   [9] HostAddresses OPTIONAL,
        authorization-data      [10] AuthorizationData OPTIONAL
}
@end verbatim

@include texi/ticket.c.texi
@include texi/encticketpart.c.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 texi/kdc.c.texi
@include texi/kdcreq.c.texi
@include texi/kdcrep.c.texi
@include texi/enckdcreppart.c.texi


@node Authenticator Functions
@section Authenticator Functions

An ``Authenticator'' is an 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 texi/authenticator.c.texi


@node KRB-ERROR Functions
@section KRB-ERROR Functions

The ``KRB-ERROR'' is an ASN.1 structure that can be returned, instead
of, e.g., KDC-REP or AP-REP, to indicate various error conditions.
Unfortunately, the semantics of several of the fields are ill
specified, so the typically procedure is to extract ``e-text'' and/or
``e-data'' and show it to the user.  The following illustrates the
KRB-ERROR ASN.1 structure.

@verbatim
KRB-ERROR       ::= [APPLICATION 30] SEQUENCE {
        pvno            [0] INTEGER (5),
        msg-type        [1] INTEGER (30),
        ctime           [2] KerberosTime OPTIONAL,
        cusec           [3] Microseconds OPTIONAL,
        stime           [4] KerberosTime,
        susec           [5] Microseconds,
        error-code      [6] Int32,
        crealm          [7] Realm OPTIONAL,
        cname           [8] PrincipalName OPTIONAL,
        realm           [9] Realm -- service realm --,
        sname           [10] PrincipalName -- service name --,
        e-text          [11] KerberosString OPTIONAL,
        e-data          [12] OCTET STRING OPTIONAL
}
@end verbatim

@include texi/krberror.c.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 texi/key.c.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 texi/keys.c.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 texi/hostkeys.c.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 texi/crypto.c.texi

An easier way to use encryption and decryption if your application
repeatedly calls, e.g., @code{shishi_encrypt_ivupdate}, is to use the
following functions.  They store the key, initialization vector, etc,
in a context, and the encryption and decryption operations update the
IV within the context automatically.

@include texi/crypto-ctx.c.texi

Also included in Shishi is an interface to the really low-level
cryptographic primitives.  They map directly on the underlying
cryptographic library used (i.e., Gnulib or Libgcrypt) and is used
internally by Shishi.

@include texi/low-crypto.c.texi


@node X.509 Functions
@section X.509 Functions

The functions described in this section are used by the STARTTLS
functionality, see @ref{Kerberos via TLS}.

@include texi/pki.c.texi


@node Utility Functions
@section Utility Functions

@include texi/realm.c.texi
@include texi/principal.c.texi
@include texi/authorize.c.texi
@include texi/gztime.c.texi
@include texi/password.c.texi
@include texi/resolv.c.texi


@node ASN.1 Functions
@section ASN.1 Functions

@include texi/asn1.c.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 texi/error.c.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 Kerberos Database Functions
@section Kerberos Database Functions
@cindex Shisa API
@cindex Database interface

Shisa is a separate and standalone library from Shishi
(@pxref{Introduction to Shisa}).  If you only wish to manipulate the
information stored in the Kerberos user database used by Shishi, you
do not need to link or use the Shishi library at all.  However, you
may find it useful to combine the two libraries.

For two real world examples on using the Shisa library, refer to
@file{src/shisa.c} (Shisa command line tool) and @file{src/kdc.c}
(part of Shishid server).

Shisa uses two @samp{struct}s to carry information.  The first,
@code{Shisa_principal}, is used to hold information about principals.
The struct does not contain pointers to strings etc, so the library
assumes the caller is responsible for allocating and deallocating the
struct itself.  Each such struct is (uniquely) identified by the
combination of principal name and realm name.

@example
struct Shisa_principal
@{
  int isdisabled;
  uint32_t kvno;
  time_t notusedbefore;
  time_t lastinitialtgt;      /* time of last initial request for a TGT */
  time_t lastinitialrequest;  /* time of last initial request */
  time_t lasttgt;             /* time of issue for the newest TGT used */
  time_t lastrenewal;         /* time of the last renewal */
  time_t passwordexpire;      /* time when the password will expire */
  time_t accountexpire;       /* time when the account will expire. */
@};
typedef struct Shisa_principal Shisa_principal;
@end example

The second structure is called @code{Shisa_key} and hold information
about cryptographic keys.  Because the struct contain pointers, and
the caller cannot know how many keys a principal have, the Shisa
library manages memory for the struct.  The library allocate the
structs, and the pointers within them.  The caller may deallocate
them, but it is recommended to use @code{shisa_key_free} or
@code{shisa_keys_free} instead.  Note that each principal may have
multiple keys.

@example
struct Shisa_key
@{
  uint32_t kvno;
  int32_t etype;
  int priority;
  char *key;
  size_t keylen;
  char *salt;
  size_t saltlen;
  char *str2keyparam;
  size_t str2keyparamlen;
  char *password;
@};
typedef struct Shisa_key Shisa_key;
@end example

Shisa is typically initialized by calling @code{shisa_init}, and
deinitialized (when the application no longer need to use Shisa,
typically when it shuts down) by calling @code{shisa_done}, but here
are the complete (de)initialization interface functions.

@include texi/setup.c.texi

The default configuration file is typically read automatically by
calling @code{shisa_init}, but if you wish to manually access the
Shisa configuration file functions, here is the complete interface.

@include texi/config.c.texi

The core part of the Shisa interface follows.  The typical procedure
is to use @code{shisa_principal_find} to verify that a specific
principal exists, and to extract some information about it, and then
use @code{shisa_keys_find} to get the cryptographic keys for the
principal, usually suppliying some hints as to which of all keys you
are interested in (e.g., key version number and encryption algorithm
number).

@include texi/core.c.texi

Error handling is similar to that for Shishi in general (@pxref{Error
Handling}), i.e., you invoke @code{shisa_strerror} on the integer
return value received by some function, if the return value is
non-zero.  Below is the complete interface.

@include texi/err.c.texi

@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, 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.

Nicolas Pouvesle wrote the section about the Kerberos rsh/rlogin
protocol.

This manual borrows text from the Kerberos 5 specification.

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

@node Criticism of Kerberos
@appendix Criticism of Kerberos

The intention with this section is to discuss various problems with
Kerberos 5, so you can form a conscious decision how to deploy and use
Shishi correctly in your organization.  Currently the issues below are
condensed, and mostly serve as a reminder for the author to elaborate
on them.

No encryption scheme with security proof.

No standardized API, and GSS mechanism lack important functionality.

Lack of authorization system.  (krb5_kuserok())

Host to realm mapping relies on insecure DNS or static configuration
files.

Informational model and user database administration.

Non-formal specification.  Unclear on the etype to use for session
keys (etype in request or database?).  Unclear on how to populate some
``evident'' fields (e.g., cname in tickets for AS-REQ, or crealm,
cname, realm, sname, ctime and cusec in KRB-ERROR).  Unclear error
code semantics (e.g., logic for when to use S_PRINCIPAL_UNKNOWN
absent).  Some KRB-ERROR fields are required, but can't be usefully
populated in some situations, and no guidance is given on what they
should contain.

RFC 1510/1510bis incompatibilities.  NULL enctype removed without
discussion, and it is still used by some 1964 GSSAPI implementations.
KRB_SAFE text (3.4.1) says the checksum is generated using the session
or sub-session key, which contradicts itself (compare section 3.2.6)
and also RFC 1510, which both allow the application to define the key.
Verification of KRB_SAFE now require the key to be compatible with the
(sub-)session key, in 1510 the only requirement was that it was
collision proof.

Problems with RFC 1510bis.  Uses bignum INTEGER for TYPED-DATA and
AD-AND-OR.

Problems with crypto specification.  It uses the word ``random'' many
times, but there is no discussion on the randomness requirements.
Practical experience indicate it is impossible to use true randomness
for all ``random'' fields, and no implementation does this.  A post by
Don Davis on the ietf-krb-wg list tried to provide insight, but the
information was never added to the specification.

@node Protocol Extensions
@appendix Protocol Extensions

This appendix specifies the non-standard protocol elements implemented
by Shishi.  By nature of being non-standard, everything described here
is experimental.  Comments and feedback is appreciated.

@menu
* STARTTLS protected KDC exchanges::    How Shishi talks to KDC protected by TLS.
* Telnet encryption with AES-CCM::      Integrity and privacy protected telnet.
* Kerberized rsh and rlogin::           Description of KCMD protocol.
* Key as initialization vector::        Some cryptography discussion.
* The Keytab Binary File Format::       Format of keytab files.
* The Credential Cache Binary File Format:: Format of ccache files.
@end menu

@node STARTTLS protected KDC exchanges
@section STARTTLS protected KDC exchanges

Shishi is able to ``upgrade'' TCP communications with the KDC to use
the Transport Layer Security (TLS) protocol.  The TLS protocol offers
integrity and privacy protected exchanges.  TLS also offers
authentication using username and passwords, X.509 certificates, or
OpenPGP certificates.  Kerberos 5 claims to offer some of these
features, although it is not as rich as the TLS protocol.  An
inconclusive list of the motivation for using TLS is given below.

@itemize @bullet

@item Server authentication of the KDC to the client.
In traditional Kerberos 5, KDC authentication is only proved as a side
effect that the KDC knows your encryption key (i.e., your password).

@item Client authentication against KDC.
Kerberos 5 assume the user knows a key (usually in the form of a
password).  Sometimes external factors make this hard to fulfill.  In
some situations, users are equipped with smart cards with a RSA
authentication key.  In others, users have a OpenPGP client on their
desktop, with a public OpenPGP key known to the server.  In some
situations, the policy may be that password authentication may only be
done through SRP.

@item Kerberos exchanges are privacy protected.
Part of many Kerberos packets are transfered without privacy
protection (i.e., encryption).  That part contains information, such
as the client principal name, the server principal name, the
encryption types supported by the client, the lifetime of tickets,
etc.  Revealing such information is, in some threat models, considered
a problem.  Thus, this enables ``anonymity''.

@item Prevents downgrade attacks affecting encryption types.
The encryption type of the ticket in KDC-REQ are sent in the clear in
Kerberos 5.  This allows an attacker to replace the encryption type
with a compromised mechanisms, e.g. 56-bit DES.  Since clients in
general cannot know the encryption types other servers support, it is
difficult for the client to detect if there was a man-in-the-middle or
if the remote server simply did not support a stronger mechanism.
Clients may chose to refuse 56-bit DES altogether, but in some
environments this leads to operational difficulties.

@item TLS is well-proved and the protocol is studied by many parties.
This is an advantage in network design, where TLS is often already
assumed as part of the solution since it is used to protect HTTP,
IMAP, SMTP etc.  In some threat models, the designer prefer to reduce
the number of protocols that can hurt the overall system security if
they are compromised.

@end itemize

Other reasons for using TLS exists.

@subsection TCP/IP transport with TLS upgrade (STARTTLS)

RFC 1510bis requires Kerberos servers (KDCs) to accept TCP requests.
Each request and response is prefixed by a 4 octet integer in network
byte order, indicating the length of the packet.  The high bit of the
length was reserved for future expansion, and servers that do not
understand how to interpret a set high bit must return a
@code{KRB-ERROR} with a @code{KRB_ERR_FIELD_TOOLONG} and close the TCP
stream.

The TCP/IP transport with TLS upgrade (STARTTLS) uses this reserved
bit as follows.  First we define a new extensible typed hole for
Kerberos 5 messages, because we used the only reserved bit.  It is
thus prudent to offer future extensions on our proposal.  Secondly we
reserve two values in this new typed hole, and described how they are
used to implement STARTTLS.

@subsection Extensible typed hole based on reserved high bit

When the high bit is set, the remaining 31 bits of the 4 octets are
treated as an extensible typed hole, and thus form a 31 bit integer
enumerating various extensions.  Each of the values indicate a
specific extended operation mode, two of which are used and defined
here, and the rest are left for others to use.  If the KDC do not
understand a requested extension, it MUST return a @code{KRB-ERROR}
with a @code{KRB_ERR_FIELD_TOOLONG} value (prefixed by the 4 octet
length integer, with the high bit clear, as usual) and close the TCP
stream.

Meaning of the 31 lower bits in the 4 octet field, when the high bit
is set:

@verbatim
 0               RESERVED.
 1               STARTTLS requested by client.
 2               STARTTLS request accepted by server.
 3...2147483647  AVAILABLE for registration (via bug-shishi@josefsson.org).
 2147483648      RESERVED.
@end verbatim

@subsection STARTTLS requested by client (extension mode 1)

When this is sent by the client, the client is requesting the server
to start TLS negotiation on the TCP stream.  The client MUST NOT start
TLS negotiation immediately.  Instead, the client wait for either a
KRB-ERROR (sent normally, prefixed by a 4 octet length integer)
indicating the server do not understand the set high bit, or 4 octet
which is to interpreted as an integer in network byte order, where the
high bit is set and the remaining 31 bit are interpreted as an integer
specifying the ``STARTTLS request accepted by server''.  In the first
case, the client infer that the server do not understand (or wish to
support) STARTTLS, and can re-try using normal TCP, if unprotected
Kerberos 5 exchanges are acceptable to the client policy.  In the
latter case, it should invoke TLS negotiation on the stream.  If any
other data is received, the client MUST close the TCP stream.

@subsection STARTTLS request accepted by server (extension mode 2)

This 4 octet message should be sent by the server when it has received
the previous 4 octet message.  The message is an acknowledgment of the
client's request to initiate STARTTLS on the channel.  The server MUST
then invoke a TLS negotiation.

@subsection Proceeding after successful TLS negotiation

If the TLS negotiation ended successfully, possibly also considering
client or server policies, the exchange within the TLS protected
stream is performed like normal UDP Kerberos 5 exchanges, i.e., there
is no TCP 4 octet length field before each packet.  Instead each
Kerberos packet MUST be sent within one TLS record, so the application
can use the TLS record length as the Kerberos 5 packet length.

@subsection Proceeding after failed TLS negotiation

If the TLS negotiation fails, possibly due to client or server policy
(e.g., inadequate support of encryption types in TLS, or lack of
client or server authentication) the entity that detect the failure
MUST disconnected the connection.  It is expected that any error
messages that explain the error condition is transfered by TLS.

@subsection Interaction with KDC addresses in DNS

Administrators for a KDC may announce the KDC address by placing SRV
records in DNS for the realm, as described in
@file{draft-ietf-krb-wg-krb-dns-locate-03.txt}.  That document mention
TLS, but do not reference any work that describe how KDCs uses TLS.
Until further clarified, consider the TLS field in that document to
refer to implementation supporting this STARTTLS protocol.

@subsection Using TLS authentication logic in Kerberos

The server MAY consider the authentication performed by the TLS
exchange as sufficient to issue Kerberos 5 tickets to the client,
without requiring, e.g., pre-authentication.  However, it is not an
error to require or use pre-authentication as well.

The client may also indicate that it wishes to use TLS both for
authentication and data protection by using the @samp{NULL} encryption
type in its request.  The server can decide from its local policy
whether or not issuing tickets based solely on TLS authentication, and
whether @samp{NULL} encryption within TLS, is acceptable or not.  This
mode is currently under investigation.

@subsection Security considerations

Because the initial token is not protected, it is possible for an
active attacker to make it appear to the client that the server do not
support this extension.  It is up to client configuration to disallow
non-TLS connections, if this vulnerability is deemed unacceptable.
For interoperability, we suggest the default behaviour should be to
allow automatic fallback to TCP or UDP.

The security considerations of both TLS and Kerberos 5 are inherited.
Using TLS for authentication and/or data protection together with
Kerberos alter the authentication logic fundamentally.  Thus, it may
be that even if the TLS and Kerberos 5 protocols and implementations
were secure, the combination of TLS and Kerberos 5 described here
could be insecure.

No channel bindings are provided in the Kerberos messages.  It is an
open question whether, and how, this should be fixed.

@node Telnet encryption with AES-CCM
@section Telnet encryption with AES-CCM

This appendix describe how Shishi use the Advanced Encryption Standard
(AES) encryption algorithm in Counter with CBC-MAC mode (RFC 3610)
with the telnet encryption option (RFC 2946).

@subsection Command Names and Codes

@verbatim
Encryption Type

      AES_CCM             12

Suboption Commands

      AES_CCM_INFO         1
      AES_CCM_INFO_OK      2
      AES_CCM_INFO_BAD     3
@end verbatim

@subsection Command Meanings

@verbatim
   IAC SB ENCRYPT IS AES_CCM AES_CCM_INFO <M> <L> <nonce> IAC SE
@end verbatim

The sender of this command select desired M and L parameters, and
nonce, as described in RFC 3610, and sends it to the other side of the
connection.  The parameters and the nonce are sent in clear text.
Only the side of the connection that is WILL ENCRYPT may send the
AES_CCM_INFO command.

@verbatim
   IAC SB ENCRYPT REPLY AES_CCM AES_CCM_INFO_BAD IAC SE
@end verbatim

The sender of this command reject the parameters received in the
AES_CCM_INFO command.  Only the side of the connection that is DO
ENCRYPT may send the AES_CCM_INFO_BAD command.  The command MUST be
sent if the nonce field length does not match the selected value for
L.  The command MAY be sent if the receiver do not accept the
parameters for reason such as policy.  No capability is provided to
negotiate these parameters.

@verbatim
   IAC SB ENCRYPT REPLY AES_CCM AES_CCM_INFO_OK IAC SE
@end verbatim

The sender of this command accepts the parameters received in the
AES_CCM_INFO command.  Only the side of the connection that is DO
ENCRYPT may send the AES_CCM_INFO_BAD command.  The command MUST NOT
be sent if the nonce field length does not match the selected value
for L.

@subsection Implementation Rules

Once a AES_CCM_INFO_OK command has been received, the WILL ENCRYPT
side of the connection should do keyid negotiation using the ENC_KEYID
command.  Once the keyid negotiation has successfully identified a
common keyid, then START and END commands may be sent by the side of
the connection that is WILL ENCRYPT.  Data will be encrypted using the
AES-CCM algorithm, with the negotiated nonce and parameters M and L.
After each successful encryption and decryption, the nonce is treated
as an integer in network byte order, and incremented by one.

If encryption (decryption) is turned off and back on again, and the
same keyid is used when re-starting the encryption (decryption), the
intervening clear text must not change the state of the encryption
(decryption) machine.  In particular, the AES-CCM nonce must not be
re-set.

If a START command is sent (received) with a different keyid, the
encryption (decryption) machine must be re-initialized immediately
following the end of the START command with the new key and the
parameters sent (received) in the last AES_CCM_INFO command.

If a new AES_CCM_INFO command is sent (received), and encryption
(decryption) is enabled, the encryption (decryption) machine must be
re-initialized immediately following the end of the AES_CCM_INFO
command with the new nonce and parameters, and the keyid sent
(received) in the last START command.

If encryption (decryption) is not enabled when a AES_CCM_INFO command
is sent (received), the encryption (decryption) machine must be re-
initialized after the next START command, with the keyid sent
(received) in that START command, and the nonce and parameters sent
(received) in this AES_CCM_INFO command.

At all times MUST each end make sure that a AES-CCM nonce is not used
twice under the same encryption key.  The rules above help accomplish
this in an interoperable way.

@subsection Integration with the AUTHENTICATION telnet option

<<This section is slightly complicated.  Can't we simplify this?>>

As noted in the telnet ENCRYPTION option specifications, a keyid value
of zero indicates the default encryption key, as might be derived from
the telnet AUTHENTICATION option.  If the default encryption key
negotiated as a result of the telnet AUTHENTICATION option contains
less than 32 bytes (corresponding to two 128 bit keys), then the
AES_CCM option MUST NOT be offered or used as a valid telnet
encryption option.  Furthermore, depending on policy for key lengths,
the AES_CCM option MAY be disabled if the default encryption key
contain less than 48 bytes (for two 192 bit keys), or less than 64
bytes (for two 256 bit keys), as well.

The available encrypt key data is divided on two halves, where the
first half is used to encrypt data sent from the server (decrypt data
received by the client), and the second half is used to encrypt data
sent from the client (decrypt data received by the server).

Note that the above algorithm assumes that the AUTHENTICATION
mechanism generate keying material suitable for AES-CCM as used in
this specification.  This is not necessarily true in general, but we
specify this behaviour as the default since it is true for most
authentication systems in popular use today.  New telnet
AUTHENTICATION mechanisms may specify alternative methods for
determining the keys to be used for this cipher suite in their
specification, if the session key negotiated by that authentication
mechanism is not a DES key and and where this algorithm may not be
safely used.

Kerberos 5 authentication clarification: The key used to encrypt data
from the client to the server is taken from the sub-session key in the
AP-REQ.  The key used to decrypt data from the server to the client is
taken from the sub-session key in the AP-REP.  If mutual
authentication is not negotiated, the key used to encrypt data from
the client to the server is taken from the session key in the ticket,
and the key used to decrypt data from the server to the client is
taken from the sub-session key in the AP-REQ.  Leaving the AP-REQ
sub-key field empty MUST disable the AES_CCM option.

@subsection Security Considerations

The protocol must be properly and securely implemented.  For example,
an implementation should not be vulnerable to various
implementation-specific attacks such as buffer overflows or
side-channel analysis.

We wish to repeat the suggestion from RFC 2946, to investigate in a
STARTTLS approach for Telnet encryption (and also authentication),
when the security level provided by this specification is not
adequate.

@subsubsection Telnet Encryption Protocol Security Considerations

The security consideration of the Telnet encryption protocol are
inherited.

It should be noted that the it is up to the authentication protocol
used, if any, to bind the authenticity of the peers to a specific
session.

The Telnet encryption protocol does not, in general, protect against
possibly malicious downgrading to any mutually acceptable, but not
preferred, encryption type.  This places a requirement on each peer to
only accept encryption types it trust fully.  In other words, the
Telnet encryption protocol do not guarantee that the strongest
mutually acceptable encryption type is always selected.

@subsubsection AES-CCM Security Considerations

The integrity and privacy claims are inherited from AES-CCM.  In
particular, the implementation must make sure a nonce is not used more
than once together with the same key.

Furthermore, the encryption key is assumed to be random, i.e., it
should not be possible to guess it with probability of success higher
than guessing any uniformly selected random key.  RFC 1750 gives an
overview of issues and recommendations related to randomness.

@subsection Acknowledgments

This document is based on the various Telnet Encryption RFCs (RFC
2946, RFC 2947, RFC 2948, RFC 2952 and RFC 2953).

@node Kerberized rsh and rlogin
@section Kerberized rsh and rlogin

This appendix describe the KCMDV0.2 protocol used in shishi patched
version of inetutils. The KCMD protocol was developped by the MIT
Kerberos team for kerberized rsh an rlogin programs. Differences
between rlogin an rsh will be explained, like those between v0.1 and
v0.2 of the protocol for compatibility reasons.
It is possible that some parts of this document are not in conformity
with original KCMD protocol because there is no official specification
about it. However, it seems that shishi implementation is compatible
with MIT's one.

@strong{Warning:} If you are seriously considering using Kerberos rsh
or rlogin, instead of more robust remote access protocols such as
@acronym{SSH}, you may first want to explore
@url{http://www.cs.berkeley.edu/~hildrum/kerberos/} and the full paper
at @url{http://www.cs.berkeley.edu/~hildrum/043.pdf}.

@subsection Establish connection

First the client should establish a TCP connection with the
server. Default ports are 543 (klogin), 544 (kshell), 2105 (eklogin).
eklogin is the same as klogin but with encryption. Their is no longer
ekshell port because encrypted and normal connection use the same port
(kshell).
Kshell need a second connection for stderr. The client should send a
null terminated string that represent the port of this second
connection.
Klogin and eklogin does not use a second connection for stderr so the
client must send a null byte to the server.
Contrary to classic rsh/rlogin, server must not check if the client
port is in the range 0-1023. 

@subsection Kerberos identification

When connections are established, first thing to do is to indicate
kerberos authentication must be used.
So the client will send a string to indicate it will used kerberos
5. It will call a length-string "strl" the couple (lenght of the string
strl, null terminated string strl). Length of the string is an int32
(32bits int) in MSB order (for the network).
So the client send this length-string strl :

@verbatim
   KRB5_SENDAUTH_V1.0
@end verbatim

After that the client must indicate which version of the protocol it
will used by sending this length-string strl :

@verbatim
   KCMDV0.2
@end verbatim

It can be V0.1 for older versions.
If indentification from client is good, server will send a null
byte (0x00). Else if authentication message is wrong, server send byte
0x01, else if protocol version message is wrong server send byte 0x02.

@subsection Kerberos authentication

When client is indentified, kerberos authentication can begin. The
client must send an AP-REQ to the server. AP-REQ authenticator must
have a subkey (only for KCMDV0.2) and a checksum.
Authenticator checksum is created on following string :

@example
"serverport:""terminaltype""remoteusername"
@end example

for example :

@example
543:linux/38400user
@end example

remoteusername corresponds to the identity of the client on remote machine.

AP-REQ is sended in der encoded format. The length (int32) of der
encoded AP-REQ is sended in network format (MSB), following by the der
encoded AP-REQ.
If all is correct, server send a null int32 (MSB format but like it is
null it is not important).
KCMD protocol use mutual authentication, so server must now send and
AP-REP : (in32 lenght in MSB of der encoded AP-REP)(der encoded
AP-REP).

Now server and client are partially authenticated.

@subsection Extended authentication

Client must now send 3 different null terminated strings (without
lenght) :

@itemize
@item remote user name (user identity on remote machine)
@item terminal type for rlogin or command for rsh
@item local user name (user identity on client machine)
@end itemize

example for rsh :

@example
"rname\0"
"cat /usr/local/etc/shishi.conf"
"lname\0"
@end example

Server must verify that checksum in AP-REQ authenticator is correct by
computing a new hash like client has done.

Server must verify that principal (in AP-REQ) has right to log in on
the remote user account.
For the moment shishi only check if remote user name is equal to
principal. A more complex authorization code is planned.
Look at the end to know how MIT/Heimdal do to check authorization.

If all is correct server send a null byte, else an error message
string (null terminated string) is sent. User read the first byte. If
it is equal to zero, authentication is correct and is logged on the
remote host. Else user can read the error messsage send by the server.

@subsection Window size

For rlogin protocol, when authentication is complete, the server can
optionnaly send a message to ask for window terminal size of
user. Then the user can respond but it is not an obligation.

In KCMDV0.1 server send an urgent TCP message (MSG_OOB) with one byte
:

@example
TIOCPKT_WINDOW = 0x80
@end example

In KCMDV0.2 server does not send an urgent message but write on the
socket 5 bytes :

@example
'\377', '\377', 'o', 'o', TIOCPKT_WINDOW
@end example

If encryption is enabled (eklogin) server must send this 5 bytes
encrypted.

Client can answer in both protocol version with :
       
@example
'\377', '\377', 's', 's', "struct winsize"
@end example

The winsize structure is filled with corresponding setting to client's
terminal.
If encryption is enabled this answer must be send encrypted.

@subsection End of authentication

The "classic" rsh/rlogin can be used now.


@subsection Encryption

Encryption mode is used when a connection with eklogin is established.
Encryption with krsh can be used too. Before, there was a specific port
for that (ekshell), but now to indicate that encryption must be used with
krsh, client must add "-x " before the command when it send it between
remote user name and local user name.
When the client compute the checksum for AP-REQ authenticator the "-
x" must not be included.

Encryption in KCMDV0.2 is not the same as in KCMDV0.1. 
KCMDV0.1 uses ticket session key as encryption key, and use standard
Kerberos encryption functions. This protocol only supports des-cbc-crc,
des-cbc-md4, des-cbc-md5 and does not use initialisation vectors.

For example on each encryption/decryption calls, the following
prototype kerberos function should be used :
         
@example
kerberos_encrypt (key, keyusage, in, out)  (or decrypt)
@end example

KCMDV0.2 can be used with all kerberos encryption modes (des, 3des,
aes, arcfour) and use AP-REQ authenticator subkey. In opposite to
KCMDV0.1 initialisation vectors are used. All encryptions/descryptions
must be made using a cryptographic context (for example to use the
updated iv, or sbox) :

@example
kerberos_init(ctx, iv, key, keyusage)
kerberos_encrypt (ctx, in, out)
@end example

For both protocols, keyusage id for des-cbc-md5, des-cbc-md4,
des-cbc-crc and des3-cbc-sha1 (for KCMDV0.2) :
        
@example    
keyusage = 1026
@end example

For other KCMDV0.2 modes keyusage is different for each
encryption/decryption usage.
To understand, eklogin use 1 socket. It encrypts data (output 1) to
send and decrypts (input 1) received data.
Kshell use 2 sockets (1 for transmit data, 1 for stderr). So there are
four modes :
     
@verbatim
   transmit  : input  1 
               output 1

   stderr    : input  2
               output 2
@end verbatim

There is a keyusage for each modes. The keyusage must correspond on
client and server side. For example in klogin client input 1 keyusage
will be server output 1 keyusage.

@multitable @columnfractions .15 .15 .15
@item I/O @tab Client @tab Server
@item intput 1 @tab 1028 @tab 1030
@item output 1 @tab 1030 @tab 1028
@item intput 2 @tab 1032 @tab 1034
@item output 2 @tab 1034 @tab 1032
@end multitable

Those keyusages must be used with AES and ARCFOUR modes.

KCMDV0.2 uses IV (initialisation vector). Like for keyusage, client IV
must correspond to server IV. IV size is equal to key type,
blocksize. All bytes of IV must be initialised to :

@multitable @columnfractions .15 .15 .15
@item I/O @tab Client @tab Server
@item intput 1 @tab 0 @tab 1
@item output 1 @tab 1 @tab 0
@item intput 2 @tab 2 @tab 3
@item output 2 @tab 3 @tab 2
@end multitable

ARCFOUR mode does not use IV. However, like it is said before, a context
must be used to keep the updated sbox.

Normal message with klogin and kshell are sent like that :

@example
(int 32 lenght of message in MSB order)
(message)
@end example

In encrypted mode it is a bit different :

@example
(int 32 length of unencrypted message in MSB order)
(encrypted message)
@end example

In KCMDV0.2 encrypted message is create like that :

@example
encrypt (
(int 32 length of message in MSB order)
(message)
)
@end example

A check on message size can be made in second version of the protocol.

@subsection  KCMDV0.3


This part only gives possible ways to extend KCMD protocol. Does not
take that as must have in KCMD implementation.

Extensions of KCMV0.2 could be made. For example kshell supposes there
are no files with name "-x *". I think the same thing can be supposed
with terminal name for klogin. So client could add "-x " to terminal
type it sends to server to indicate it will use encryption. Like that
there will be only one port for klogin/eklogin : 543.

In encrypted mode kshell send command in clear on the network, this
could be considered as insecure as user have decided to use
encryption.
This is not really a problem for klogin because it just sends terminal
type.

In encrypted mode, klogin and kshell clients could only send "-x" as
command or terminal type.
After that encryption is activated, and the client could send terminal
type or command encrypted.
The server will send the null byte to say that all is correct, or
error message in encrypted form.

@subsection MIT/Heimdal authorization

This part describes how MIT/Heimdal version check authorization of the
user to log in on the remote machine.

Authorization check is made by looking if the file .k5login exists on
the account of the remote user.
If this file does not exist, remote user name must be the same as
principal in AP-REQ to valid authorization.
Else if this file exists, check first verify that remote user or root
are the owner of .k5login.
If it is not the case, the check fails.
If it is good, check reads each line of that file and compare each
readed name to principal.
If principal is found in .k5login, authorization is valid, else user
is not allowed to connect on remote host with the specified remote
user name (that can be the same as principal).

So someone (for example user "user1") can remote log into "user2"
account if .k5login is present in user2 home dir and this file is owned
by user2 or root and user1 name is present in this file.

@node Key as initialization vector
@section Key as initialization vector

The @code{des-cbc-crc} algorithm (@pxref{Cryptographic Overview}) uses
the @acronym{DES} key as the initialization vector.  This is
problematic in general (see below@footnote{The post is copyrighted by
David Wagner, included here with permission, the canonical location is
@url{http://www.cs.berkeley.edu/~daw/my-posts/key-as-iv-broken}}), but
may be mitigated in Kerberos by the CRC checksum that is also
included.

@verbatim
From daw@espresso.CS.Berkeley.EDU Fri Mar  1 13:32:34 PST 1996
Article: 50440 of sci.crypt
Path: agate!daw
From: daw@espresso.CS.Berkeley.EDU (David A Wagner)
Newsgroups: sci.crypt
Subject: Re: DES-CBC and Initialization Vectors
Date: 29 Feb 1996 21:48:16 GMT
Organization: University of California, Berkeley
Lines: 31
Message-ID: <4h56v0$3no@agate.berkeley.edu>
References: <4h39li$33o@gaia.ns.utk.edu>
NNTP-Posting-Host: espresso.cs.berkeley.edu

In article <4h39li$33o@gaia.ns.utk.edu>,
Nair Venugopal <venu@mars.utcc.utk.edu> wrote:
> Is there anything wrong in using the key as the I.V. in DES-CBC mode?

Yes, you're open to a chosen-ciphertext attack which recovers the key.

Alice is sending stuff DES-CBC encrypted with key K to Bob.  Mary is an
active adversary in the middle.  Suppose Alice encrypts some plaintext
blocks P_1, P_2, P_3, ... in DES-CBC mode with K as the IV, and sends off
the resulting ciphertext
        A->B: C_1, C_2, C_3, ...
where each C_j is a 8-byte DES ciphertext block.  Mary wants to discover
the key K, but doesn't even know any of the P_j's.  She replaces the above
message by
        M->B: C_1, 0, C_1
where 0 is the 8-byte all-zeros block.  Bob will decrypt under DES-CBC,
recovering the blocks
        Q_1, Q_2, Q_3
where
        Q_1 = DES-decrypt(K, C_1) xor K = P_1
        Q_2 = DES-decrypt(K, C_2) xor C_1 = (some unimportant junk)
        Q_3 = DES-decrypt(K, C_1) xor 0 = P_1 xor K
Bob gets this garbage-looking message Q_1,Q_2,Q_3 which Mary recovers
(under the chosen-ciphertext assumption: this is like a known-plaintext
attack, which isn't too implausible).  Notice that Mary can recover K by
        K = Q_1 xor Q_3;
so after this one simple active attack, Mary gets the key back!

So, if you must use a fixed IV, don't use the key-- use 0 or something
like that.  Even better, don't use a fixed IV-- use the DES encryption
of a counter, or something like that.
@end verbatim

@node The Keytab Binary File Format
@section The Keytab Binary File Format

The keytab file format is described in the file @file{keytab.txt},
included in verbatim below.

@verbatiminclude keytab.txt

@node The Credential Cache Binary File Format
@section The Credential Cache Binary File Format

The credential cache file format is described in the file
@file{keytab.txt}, included in verbatim below.

@verbatiminclude ccache.txt

@node Copying Information
@appendix Copying Information

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

@include fdl.texi
@include gpl.texi

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

@printindex fn

@node Concept Index
@unnumbered Concept Index

@printindex cp

@summarycontents
@contents
@bye