     [file version.texi not included]

Shishi
******

This manual is last updated UPDATED for version VERSION of Shishi.

Copyright © 2002-2013 Simon Josefsson.

     Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 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''.

Introduction
************

Shishi is an implementation of the Kerberos 5 network authentication system, as specified in RFC 4120.  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 version 3.0 or later.

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 on those parts of the interface which are unclear.

Features and Status
===================

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

It's Free Software
     Anybody can use, modify, and redistribute it under the terms of the GNU General Public License version 3.0 or later.

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

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.

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

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.

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

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

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

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

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

  * Most standard cryptographic primitives. The believed most secure algorithms are supported (see Cryptographic Overview).

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

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

  * KDC addresses located using DNS SRV RRs.

  * 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 gl/gc-gnulib.c or gl/gc-libgcrypt.c as a starting pointer.

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.

  * Parse /etc/krb5.keytab to extract keys to use for telnetd etc (week)

  * Cross-realm support (week).

  * PKINIT (use libksba, weeks)

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

  * Port to cyclone (cyclone need to mature first)

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

  * KDC (initiated, weeks)

  * LDAP backend for Shisa.

  * Set/Change password protocol (weeks?)

  * Port applications to use Shishi (indefinite)

  * Finish server-realm stuff

  * Improve documentation

  * Improve internationalization

  * Add AP-REQ replay cache (week).

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

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

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

  * Proof read manual.

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

Overview
========

This section describes RFC 1510 from a protocol point of view (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.

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.

NULL

     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 NULL checksum.

arcfour-hmac
arcfour-hmac-exp

     arcfour-hmac-* are a proprietary stream cipher with 56 bit (arcfour-hmac-exp) or 128 bit (arcfour-hmac) keys, used in a proprietary way described in an expired IETF draft 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 arcfour-hmac-md5 checksum.

des-cbc-none

     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 NULL checksum.

des-cbc-crc

     des-cbc-crc is DES encryption and decryption with 56 bit keys and 8 byte blocks in CBC mode, using the key as IV (see 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 CRC32-like checksum.  It is weak. It is associated with the rsa-md5-des checksum.

des-cbc-md4

     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 rsa-md4-des checksum.

des-cbc-md5

     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 rsa-md5-des checksum. This is the strongest RFC 1510 interoperable encryption mechanism.

des3-cbc-none

     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 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 NULL checksum.

des3-cbc-sha1-kd

     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" (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 hmac-sha1-des3-kd checksum.

aes128-cts-hmac-sha1-96
aes256-cts-hmac-sha1-96

     aes128-cts-hmac-sha1-96 and 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 (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 hmac-sha1-96-aes128 and hmac-sha1-96-aes256 checksums, respectively.

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.

NULL

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

arcfour-hmac-md5

     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 arcfour designation is thus somewhat misleading, but since this checksum mechanism is described in the same document as the arcfour encryption mechanisms, it is not a completely unnatural designation.) It is weak.  It is compatible with all encryption mechanisms.

rsa-md4

     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.

rsa-md4-des

     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 des-cbc-crc, des-cbc-md4, des-cbc-md5 encryption mechanisms.

rsa-md5

     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.

rsa-md5-des

     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 des-cbc-crc, des-cbc-md4, des-cbc-md5 encryption mechanisms.

hmac-sha1-des3-kd

     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 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 des3-cbc-sha1-kd encryption mechanism.

hmac-sha1-96-aes128
hmac-sha1-96-aes256

     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 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 aes*-cts-hmac-sha1-96 encryption mechanisms.

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.

arcfour

     Alias for arcfour-hmac.

des-crc

     Alias for des-cbc-crc.

des-md4

     Alias for des-cbc-md4.

des-md5
des

     Alias for des-cbc-md5.

des3
3des

     Alias for des3-cbc-sha1-kd.

aes128

     Alias for aes128-cts-hmac-sha1-96.

aes
aes256

     Alias for aes256-cts-hmac-sha1-96.

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 http://autobuild.josefsson.org/shishi/.

 1. Debian GNU/Linux 3.0 (Woody)

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

 2. Debian GNU/Linux 2.1

     GCC 2.95.4 and GNU Make. armv4l-unknown-linux-gnu.

 3. Tru64 UNIX

     Tru64 UNIX C compiler and Tru64 Make. alphaev67-dec-osf5.1, alphaev68-dec-osf5.1.

 4. SuSE Linux 7.1

     GCC 2.96 and GNU Make. alphaev6-unknown-linux-gnu, alphaev67-unknown-linux-gnu.

 5. SuSE Linux 7.2a

     GCC 3.0 and GNU Make. ia64-unknown-linux-gnu.

 6. SuSE Linux

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

 7. RedHat Linux 7.2

     GCC 2.96 and GNU Make. alphaev6-unknown-linux-gnu, alphaev67-unknown-linux-gnu, ia64-unknown-linux-gnu.

 8. RedHat Linux 8.0

     GCC 3.2 and GNU Make. i686-pc-linux-gnu.

 9. RedHat Advanced Server 2.1

     GCC 2.96 and GNU Make. i686-pc-linux-gnu.

 10. Slackware Linux 8.0.01

     GCC 2.95.3 and GNU Make. i686-pc-linux-gnu.

 11. Mandrake Linux 9.0

     GCC 3.2 and GNU Make. i686-pc-linux-gnu.

 12. IRIX 6.5

     MIPS C compiler, IRIX Make. mips-sgi-irix6.5.

 13. AIX 4.3.2

     IBM C for AIX compiler, AIX Make.  rs6000-ibm-aix4.3.2.0.

 14. HP-UX 11

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

 15. SUN Solaris 2.8

     Sun WorkShop Compiler C 6.0 and SUN Make. sparc-sun-solaris2.8.

 16. NetBSD 1.6

     GCC 2.95.3 and GNU Make. alpha-unknown-netbsd1.6, i386-unknown-netbsdelf1.6.

 17. OpenBSD 3.1 and 3.2

     GCC 2.95.3 and GNU Make. alpha-unknown-openbsd3.1, i386-unknown-openbsd3.1.

 18. FreeBSD 4.7 and 4.8

     GCC 2.95.4 and GNU Make. alpha-unknown-freebsd4.7, alpha-unknown-freebsd4.8, i386-unknown-freebsd4.7, i386-unknown-freebsd4.8.

 19. MacOS X 10.2 Server Edition

     GCC 3.1 and GNU Make. powerpc-apple-darwin6.5.

 20. Cross compiled to uClinux/uClibc on Motorola Coldfire.

     GCC 3.4 and GNU Make m68k-uclinux-elf.

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

Getting help
============

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

Commercial Support
==================

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

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

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

  * Integrate Kerberos 5 support in your existing project.

  * System design of components related to Kerberos 5.

If you are interested, please write to:

Simon Josefsson Datakonsult
Hagagatan 24
113 47 Stockholm
Sweden

E-mail: simon@josefsson.org

If your company provides support related to Shishi and would like to be mentioned here, contact the author (see Bug Reports).

Downloading and Installing
==========================

The package can be downloaded from several places, including:

ftp://alpha.gnu.org/pub/gnu/shishi/

The latest version is stored in a file, e.g., shishi-VERSION.tar.gz where the 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 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 sh, make and cc.

     $ wget -q ftp://alpha.gnu.org/pub/gnu/shishi/shishi-VERSION.tar.gz
     $ tar xfz shishi-VERSION.tar.gz
     $ cd shishi-VERSION/
     $ ./configure
     ...
     $ make
     ...
     $ make install
     ...

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 configure options may be relevant, summarized in the table.

--disable-des
--disable-3des
--disable-aes
--disable-md
--disable-null
--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.

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

--without-stringprep
     Disable internationalized string processing.

For the complete list, refer to the output from configure --help.

Bug Reports
===========

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

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

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

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

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:

bug-shishi@josefsson.org

Contributing
============

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 (see 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:

  * Coding Style. Follow the GNU Standards document (see GNU Coding Standards (standards)).

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

  * Use the unified diff format diff -u.

  * 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 shishi_xalloc_die to allow the application to recover if it wants to.

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

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

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

  * Supply a ChangeLog and NEWS entries, where appropriate.

User Manual
***********

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 interact with Shishi directly.  Applications that need 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 telnet.  The host usually requires authentication before permitting you in.  The telnet client uses the ticket granting ticket to get a ticket for the server, and then uses this ticket to authenticate you against the server (typically the server is also authenticated to you).  You perform the initial authentication by typing shishi at the prompt.  Sometimes it is necessary to supply options telling Shishi what your principal name (user name in the Kerberos realm) or your realm is.  In the example, I specify the client name simon@JOSEFSSON.ORG.

     $ 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)
     $

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 ~/.shishi/tickets.  This is achieved by typing shishi --list.

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

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

If, for some reason, you want to manually get a ticket for a specific server, you can use the 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 to issue this command.

     $ 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)
     $

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

To wrap up this introduction, let us 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 destroys the tickets locally, it does not contact any server telling that these credentials are no longer valid.  So, if someone stole your ticket file, you must still contact your administrator and have them reset your account. Simply using this switch is not sufficient.

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

Since the --server-name parameter takes a long string to type, it is possible to type the server name directly, after the client name. The following example demonstrates an AS-REQ followed by a TGS-REQ for a specific server (assuming you did not have any tickets to begin with).

     $ 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)
     $

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

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 imap/latte.josefsson.org:

     $ 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)
     $

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:

     $ 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)

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

     $ 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)
     $

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 host/latte.josefsson.org:

     $ 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)
     $

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:

     $ 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)
     $

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

     $ 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)
     $

Administration Manual
*********************

Here you will learn how to set up, run and maintain the Shishi Kerberos server.  Kerberos is incompatible with the standard Unix /etc/passwd password database (And besides, Shishi is intended to work on non-Unix platforms as well.), therefore the first step will be to create a Kerberos user database.  Shishi's user database system is called Shisa.  Once Shisa has been configured, you can then start the server and begin issuing Kerberos tickets to your users.  The Shishi server is called 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 LDAP server or SQL database.

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 starts to be valid and when it expires), and the cryptographic keys each user has.  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 manages to steal the user database will only be able to compromise your system, and not any other systems were your user may have re-used the same password.  On the other hand, you may already be storing 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 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., GNU SASL), it might 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 as a purely Shishi specific project.  You can, for example, choose 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 have chosen 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 stores 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 /etc/passwd with data derived from the Shisa database. Instead, it is intended that you write a Shisa backend that exports some of the information stored in your user database.  You may be able to replace some existing functionality, such as the password field in /etc/passwd with a Kerberos PAM module, but there is no requirement for doing so.

Configuring Shisa
=================

The configuration file for Shisa is typically stored in /usr/local/etc/shishi/shisa.conf.  You do not have to modify this file, the defaults should be acceptable to first-time users.  The file is used to define where your user database resides, and some options such as making the database read-only, or whether errors detected when accessing the database should be ignored.  (The latter could be useful if the server is a remote LDAP server that might be unavailable, and then you would want to fall back to a local copy of the database.)

The default will store the user database using directories and files, rooted by default in /usr/local/var/shishi.  You can 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 removable media, is recommended.  We discourage placing the database on a network file system, but realize this can be useful in some situations (see Multiple servers).

See the reference manual (see 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.

Using Shisa
===========

There is a command line interface to the Shisa library, aptly named 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 (see 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 creates 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 --list or --dump parameters can be used for this.  (Most ``long'' parameters, like --dump, have shorter names as well, in this case -d, Parameters for shisa).

     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:~$

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

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

     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:~$

This indicates that the database does not exist.  For a file database, you can create it simply by creating the directory, as follows.  Note the access permission change with chmod.  Typically the 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-root user, and have all Shishi related files owned by that user, so that any security vulnerabilities do not lead to a system compromise. (However, if the user database is ever stolen, system compromises of other systems may be inoccured, should you use, e.g., a kerberized Telnet.)

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

Back to the first example, where you have a realm 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 --remove (short form -r) parameter is used for this purpose, as follows.

     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:~$

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

     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:~$

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 a name for your realm.  The full story is explained elsewhere (see Realm and Principal Naming), but the short story is to take your DNS domain name and translate it to upper case.  For example, if your organization uses example.org it is a good idea to use EXAMPLE.ORG as the name of your Kerberos realm. We'll use EXAMPLE.ORG as the realm name in these examples. Let's create the realm.

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

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 has 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 a server.  The principal must look like krbtgt/REALM (see Name of the TGS).  Let's create it.

     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:~$

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

     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:~$

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

     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:~$

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

     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:~$

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

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

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 --password parameter indicate this.  This make the tool ask you for the password.

     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:~$

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

     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:~$

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

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 setuid into after successfully listening to the ports.

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

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

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

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

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

     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

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

     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:~$

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

     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

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 GNU lsh or Telnet from GNU InetUtils, would do when contacting the host mail.example.org we illustrate using the TGS service as well.

     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:~$

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.  See Bug Reports.

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 example.org if your realm is 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.

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.

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] (see 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).

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.

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

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.

Kerberos via TLS
================

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, see STARTTLS protected KDC exchanges.

Setting up 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 telnet or 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, 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 --resume-limit parameter (see Parameters for shishid).

Setting up Anonymous TLS
------------------------

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 /tls parameter for kdc-realm (see Shishi Configuration), or by placing the KDC address in DNS using the _tls SRV record (see 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.

     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

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

     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:~$

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

     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

Setting up X.509 authenticated TLS
----------------------------------

Setting up X.509 authentication is slightly more complicated than anonymous authentication.  You need a X.509 certificate authority (CA) that can generate certificates for your Kerberos server and Kerberos clients.  It is often easiest to setup the CA yourself.  Managing a 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 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 certtool that come with GNUTLS, which is widely available.  We conclude by discussing how you use these certificates in the KDC and in the Shishi client.

Create a Kerberos Certificate Authority
.......................................

First create a CA key.

     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:~$

Then create the CA certificate.  Use whatever details you prefer.

     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:~$

Create a Kerberos KDC Certificate
.................................

First create the key for the KDC.

     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:~$

Then create actual KDC certificate, signed by the CA certificate created in the previous step.

     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:~$

Create a Kerberos Client Certificate
....................................

First create the key for the client.

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

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

     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:~$

Starting KDC with X.509 authentication support
..............................................

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

     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

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.

     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:~$

Here is what the server would print.

     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

Multiple servers
================

Setting up multiple servers is as easy as replicating the user database.  Since the default 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 NFS (properly secured by, e.g., a point-to-point symmetrically encrypted IPSEC connection) and file synchronizing tools like rsync are typical choices.

The secondary server should be configured just like the master server. If you use the file database over NFS you do not have to make any modifications.  If you use, e.g., a cron job to rsync the directory every hour or so, you may want to add a --read-only flag to the Shisa db definition (see 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.

     db --read-only file /usr/local/var/backup-shishi

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

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 LDAP server or 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 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 --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 LDAP or 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.

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

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 krbtgt/REALM principal in the local file database, this will override the LDAP interface.  Naturally, you can have as many db definition lines as you wish.

Users with remote databases can also investigate a so called 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 --ignore-errors flag in the database definition.  Here is a sample configuration.

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

This instruct the Shisa library to try the LDAP backend first, but if it fails, instead of returning an error, continue to try the operation on a read only local 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.

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

     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

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

     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

Developer information
=====================

The Programming API for Shisa is described below (see 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 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 file based database, in 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 (see 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 shishid server.

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

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.

Environmental Assumptions
=========================

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

  * "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.

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

  * "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.

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

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

Glossary of terms
=================

Authentication
     Verifying the claimed identity of a principal.

Authentication header
     A record containing a Ticket and an Authenticator to be presented to a server as part of the authentication process.

Authentication path
     A sequence of intermediate realms transited in the authentication process when communicating from one realm to another.

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.

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.

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.

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

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

Credentials
     A ticket plus the secret session key necessary to successfully use that ticket in an authentication exchange.

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.

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

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.

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.

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

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

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

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.

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.

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

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

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

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.

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.

Realm and Principal Naming
==========================

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

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:

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

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.

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:

     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

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. See Name of the TGS, for the form of such names.

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.

Name of the TGS
...............

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

Choosing a principal with which to communicate
----------------------------------------------

The Kerberos protocol provides the means for verifying (subject to the assumptions in 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.

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 GSS-API mechanism (RFC 1964).

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

 1. 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:

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

      b. 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`.

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

      d. An occurrence of the `\` quoting character as the last character of a component is illegal.

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

Shishi Configuration
====================

The valid configuration file tokens are described here.  The user configuration file is typically located in ~/.shishi/shishi.conf (compare shishi --configuration-file) and the system configuration is typically located in /usr/local/etc/shishi/shishi.conf (compare 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 default-principal is rarely useful in a system configuration file.

default-realm
-------------

Specify the default realm, by default the hostname of the host is used.  E.g.,

     default-realm JOSEFSSON.ORG

default-principal
-----------------

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

     default-principal jas

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

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

verbose, verbose-asn1, verbose-noise, verbose-crypto, verbose-crypto-noise
--------------------------------------------------------------------------

Enable verbose library messages.  E.g.,

     verbose
     verbose-noise

realm-kdc
---------

Specify KDC addresses for realms.  Value is REALM,KDCADDRESS[/TRANSPORT][,KDCADDRESS[/TRANSPORT]...].

KDCADDRESS is the hostname or IP address of KDC.

Optional TRANSPORT 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.

     realm-kdc=JOSEFSSON.ORG,ristretto.josefsson.org

server-realm
------------

Specify realm for servers. Value is REALM,SERVERREGEXP[,SERVERREGEXP...].

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

     server-realm=JOSEFSSON.ORG,.josefsson.org

Note: currently not used.

kdc-timeout, 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.,

     kdc-timeout=10

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

     kdc-retries=5

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

     stringprocess=UTF-8

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

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

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

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

Shisa Configuration
===================

The configuration file for Shisa is typically stored in /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.

db
--

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

     db [OPTIONS] <TYPE> [LOCATION] [PARAMETERS ...]

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:

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

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.

     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

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:

     db file PATH

Examples:

     db file /var/shishi
     db file /usr/share/shishi read-only

If no db tokens are present, the default will be:

     db file /usr/local/var/shishi

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.

     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)

Parameters for shishid
======================

If no parameters are specified, 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.

     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 `*:kerberos/udp,
                                       *:kerberos/tcp'.
       -u, --setuid=NAME             After binding socket, set user identity.

     TLS settings:
           --no-tls                  Disable TLS support  (default=off)
           --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.
                                       Use multiple times to increase amount of
                                       information.
       -q, --quiet                   Don't produce any diagnostic output.
                                         (default=off)

Parameters for shisa
====================

The purpose of 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.

     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)

Environment variables
=====================

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

  * 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 $prefix/etc/shishi.conf.

  * 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 $HOME/.shishi.

  * SHISHI_USER Specify the default principal user name.  Used by the Shishi library. If not specified, it is taken from the environment variable USER.

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

     [file parse-datetime.texi not included]

Programming Manual
******************

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

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 (see Examples).

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:

     #include <shishi.h>

The name space of `Libshishi' is shishi_* for function names, Shishi* for data types and 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.

Initialization
--------------

`Libshishi' must be initialized before it can be used.  The library is initialized by calling shishi_init (see 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 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 setlocale before initializing `Libshishi'.

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.

     [file version.c.texi not included]

The normal way to use the function is to put something similar to the following early in your main:

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

Building the source
-------------------

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 -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 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 --cflags option to pkg-config shishi.  The following example shows how it can be used at the command line:

     gcc -c foo.c `pkg-config shishi --cflags`

Adding the output of 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 -L option).  For this, the option --libs to 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 -lshishi option).  The example shows how to link foo.o with the `Libshishi' library to a program foo.

     gcc -o foo foo.o `pkg-config shishi --libs`

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

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

Autoconf tests
--------------

If you work on a project that uses Autoconf (see 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.

Autoconf test via pkg-config
............................

If your audience is a typical GNU/Linux desktop, you can often assume they have the 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.

     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)

Standalone Autoconf test using Libtool
......................................

If your package uses Libtool(see 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.

     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)

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.

Initialization Functions
========================

     [file init.c.texi not included]
     [file cfg.c.texi not included]

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 (see AS Functions) or subsequent authentication (see TGS Functions) and storing the new ticket in the ticket set are also provided.

See Ticket Functions, to manipulate each individual ticket. See Ticket (ASN.1) Functions, for low-level ASN.1 manipulation.

     [file tkts.c.texi not included]

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 (see Authenticator Functions) which is the real cryptographic proof.  The following illustrates the AP-REQ and AP-REP ASN.1 structures.

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
}

     [file ap.c.texi not included]
     [file apreq.c.texi not included]
     [file aprep.c.texi not included]
     [file encapreppart.c.texi not included]

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 (see AP-REQ and AP-REP Functions).  The following illustrates the KRB-SAFE ASN.1 structure.

   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
   }

     [file safe.c.texi not included]

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 (see AP-REQ and AP-REP Functions).  The following illustrates the KRB-PRIV ASN.1 structure.

   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
   }

     [file priv.c.texi not included]

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.  See Ticket (ASN.1) Functions, for more details on the ASN.1 structure of a ticket.

     [file tkt.c.texi not included]

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.

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

     [file as.c.texi not included]

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.

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

     [file tgs.c.texi not included]

Ticket (ASN.1) Functions
========================

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

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
}

     [file ticket.c.texi not included]
     [file encticketpart.c.texi not included]

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 (see AS Functions) and TGS (see TGS Functions) interfaces, or the even more high-level Ticket Set (see Ticket Set Functions) interface.

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

     [file kdc.c.texi not included]
     [file kdcreq.c.texi not included]
     [file kdcrep.c.texi not included]
     [file enckdcreppart.c.texi not included]

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 (see 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.

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
}

     [file authenticator.c.texi not included]

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.

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
}

     [file krberror.c.texi not included]

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

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

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

     [file key.c.texi not included]

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 shishi_key_print.  All functions that handle these keys sets are described now.

     [file keys.c.texi not included]

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

     [file hostkeys.c.texi not included]

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.

     [file crypto.c.texi not included]

An easier way to use encryption and decryption if your application repeatedly calls, e.g., 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.

     [file crypto-ctx.c.texi not included]

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.

     [file low-crypto.c.texi not included]

X.509 Functions
===============

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

     [file pki.c.texi not included]

Utility Functions
=================

     [file realm.c.texi not included]
     [file principal.c.texi not included]
     [file authorize.c.texi not included]
     [file gztime.c.texi not included]
     [file password.c.texi not included]
     [file resolv.c.texi not included]

ASN.1 Functions
===============

     [file asn1.c.texi not included]

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.

Error Values
------------

Errors are returned as an 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:

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

          [file shishi-api-error-labels.texi not included]

Error Functions
---------------

     [file error.c.texi not included]

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

     -----BEGIN SHISHI KEY-----
     Keytype: 16 (des3-cbc-sha1-kd)
     Principal: sample/latte.josefsson.org
     Realm: JOSEFSSON.ORG

     8W0VrQQBpxlACPQEqN91EHxbvFFo2ltt
     -----END SHISHI KEY-----

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.

Kerberos Database Functions
===========================

Shisa is a separate and standalone library from Shishi (see 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 src/shisa.c (Shisa command line tool) and src/kdc.c (part of Shishid server).

Shisa uses two structs to carry information.  The first, 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.

     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;

The second structure is called 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 shisa_key_free or shisa_keys_free instead.  Note that each principal may have multiple keys.

     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;

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

     [file setup.c.texi not included]

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

     [file config.c.texi not included]

The core part of the Shisa interface follows.  The typical procedure is to use shisa_principal_find to verify that a specific principal exists, and to extract some information about it, and then use 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).

     [file core.c.texi not included]

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

     [file err.c.texi not included]

Generic Security Service
========================

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 http://www.gnu.org/software/gss/.

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.

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.

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.

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.

  * 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).

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

  * 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''.

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

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

Other reasons for using TLS exists.

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 KRB-ERROR with a 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.

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 KRB-ERROR with a 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:

 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.

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.

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.

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.

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.

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

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 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 NULL encryption within TLS, is acceptable or not.  This mode is currently under investigation.

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.

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

Command Names and Codes
-----------------------

Encryption Type

      AES_CCM             12

Suboption Commands

      AES_CCM_INFO         1
      AES_CCM_INFO_OK      2
      AES_CCM_INFO_BAD     3

Command Meanings
----------------

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

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.

   IAC SB ENCRYPT REPLY AES_CCM AES_CCM_INFO_BAD IAC SE

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.

   IAC SB ENCRYPT REPLY AES_CCM AES_CCM_INFO_OK IAC SE

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.

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.

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

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.

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.

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.

Acknowledgments
---------------

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

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.

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

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.

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 :

   KRB5_SENDAUTH_V1.0

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

   KCMDV0.2

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.

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 :

     "serverport:""terminaltype""remoteusername"

for example :

     543:linux/38400user

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.

Extended authentication
-----------------------

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

  * remote user name (user identity on remote machine)

  * terminal type for rlogin or command for rsh

  * local user name (user identity on client machine)

example for rsh :

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

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.

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 :

     TIOCPKT_WINDOW = 0x80

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

     '\377', '\377', 'o', 'o', TIOCPKT_WINDOW

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

Client can answer in both protocol version with :

     '\377', '\377', 's', 's', "struct winsize"

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

End of authentication
---------------------

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

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 :

     kerberos_encrypt (key, keyusage, in, out)  (or decrypt)

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) :

     kerberos_init(ctx, iv, key, keyusage)
     kerberos_encrypt (ctx, in, out)

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

     keyusage = 1026

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 :

   transmit  : input  1
	       output 1

   stderr    : input  2
	       output 2

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.

I/O   Client   Server
intput 1   1028   1030
output 1   1030   1028
intput 2   1032   1034
output 2   1034   1032

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 :

I/O   Client   Server
intput 1   0   1
output 1   1   0
intput 2   2   3
output 2   3   2

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 :

     (int 32 lenght of message in MSB order)
     (message)

In encrypted mode it is a bit different :

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

In KCMDV0.2 encrypted message is create like that :

     encrypt (
     (int 32 length of message in MSB order)
     (message)
     )

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

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.

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.

Key as initialization vector
============================

The des-cbc-crc algorithm (see Cryptographic Overview) uses the DES key as the initialization vector.  This is problematic in general (see below (The post is copyrighted by David Wagner, included here with permission, the canonical location is 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.

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.

The Keytab Binary File Format
=============================

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

     [file keytab.txt not included]

The Credential Cache Binary File Format
=======================================

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

     [file ccache.txt not included]

Copying Information
*******************

GNU Free Documentation License
==============================

     [file fdl-1.3.texi not included]