This manual is last updated 24 June 2008 for version 0.0.37 of Shishi.
Copyright © 2002, 2003, 2004, 2005, 2006, 2007, 2008 Simon Josefsson.
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled “GNU Free Documentation License”.
Appendices
Indices
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.
This manual documents the Shishi application and library programming interface. All commands, functions and data types provided by Shishi are explained.
The reader is assumed to possess basic familiarity with network security and the Kerberos 5 security system.
This manual can be used in several ways. If read from the beginning to the end, it gives a good introduction into the library and how it can be used in an application. Forward references are included where necessary. Later on, the manual can be used as a reference manual to get just the information needed about any particular interface of the library. Experienced programmers might want to start looking at the examples at the end of the manual, and then only read up those parts of the interface which are unclear.
Shishi might have a couple of advantages over other packages doing a similar job.
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.
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.
This section describes RFC 1510 from a protocol point of view1.
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.
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.
NULLNULL 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-hmacarcfour-hmac-exparcfour-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-nonedes-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-crcdes-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-md4des-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-md5des-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-nonedes3-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-kddes3-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"
2 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-96aes256-cts-hmac-sha1-96aes128-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
23,
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.
NULLNULL is a dummy checksum suite for debugging. It provides no
integrity. It is weak. It is compatible with the NULL
encryption mechanism.
arcfour-hmac-md5arcfour-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-md4rsa-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-desrsa-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-md5rsa-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-desrsa-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-kdhmac-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-aes128hmac-sha1-96-aes256hmac-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.
arcfourarcfour-hmac.
des-crcdes-cbc-crc.
des-md4des-cbc-md4.
des-md5desdes-cbc-md5.
des33desdes3-cbc-sha1-kd.
aes128aes128-cts-hmac-sha1-96.
aesaes256aes256-cts-hmac-sha1-96.
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://josefsson.org/autobuild/.
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.
armv4l-unknown-linux-gnu.
alphaev67-dec-osf5.1,
alphaev68-dec-osf5.1.
alphaev6-unknown-linux-gnu,
alphaev67-unknown-linux-gnu.
ia64-unknown-linux-gnu.
x86_64-unknown-linux-gnu (AMD64
Opteron “Melody”).
alphaev6-unknown-linux-gnu,
alphaev67-unknown-linux-gnu, ia64-unknown-linux-gnu.
i686-pc-linux-gnu.
i686-pc-linux-gnu.
i686-pc-linux-gnu.
i686-pc-linux-gnu.
mips-sgi-irix6.5.
rs6000-ibm-aix4.3.2.0.
ia64-hp-hpux11.22,
hppa2.0w-hp-hpux11.11.
sparc-sun-solaris2.8.
alpha-unknown-netbsd1.6,
i386-unknown-netbsdelf1.6.
alpha-unknown-openbsd3.1,
i386-unknown-openbsd3.1.
alpha-unknown-freebsd4.7,
alpha-unknown-freebsd4.8, i386-unknown-freebsd4.7,
i386-unknown-freebsd4.8.
powerpc-apple-darwin6.5.
m68k-uclinux-elf.
If you use Shishi on, or port Shishi to, a new platform please report it to the author (see Bug Reports).
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 is available for users of Shishi. The kind of support that can be purchased may include:
If you are interested, please write to:
Simon Josefsson Datakonsult Hagagatan 24 113 47 Stockholm Sweden E-mail: simon@josefsson.org
If your company provide support related to Shishi and would like to be mentioned here, contact the author (see Bug Reports).
The package can be downloaded from several places, including:
http://josefsson.org/shishi/releases/
The latest version is stored in a file, e.g., ‘shishi-0.0.37.tar.gz’ where the ‘0.0.37’ 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 http://josefsson.org/shishi/releases/shishi-0.0.37.tar.gz
$ tar xfz shishi-0.0.37.tar.gz
$ cd shishi-0.0.37/
$ ./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-starttls--without-stringprepFor the complete list, refer to the output from configure
--help.
If you think you have found a bug in Shishi, please investigate it and report it.
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:
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:
If you normally code using another coding standard, there is no problem, but you should use ‘indent’ to reformat the code (see GNU Indent) before submitting your work.
Usually Shishi interacts with you to get some initial authentication
information like a password, and then contacts a server to receive a
so called ticket granting ticket. From now on, you rarely interacts
with Shishi directly. Applications that needs security services
instruct the Shishi library to use the ticket granting ticket to get
new tickets for various servers. An example could be if you log on to
a host remotely via ‘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 use 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 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 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, lets see how you can remove tickets. You may want to do this if you leave your terminal for lunch or similar, and don't want someone to be able to copy the file and then use your credentials. Note that this only destroy the tickets locally, it does not contact any server and tell it that these credentials are no longer valid. So if someone stole your ticket file, you must contact your administrator and have them reset your account, simply using this parameter is not sufficient.
$ 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 to type, it is possible to type the server name directly, after the client name. The following example demonstrate a AS-REQ followed by a TGS-REQ for a specific server (assuming you did not have any tickets from the start).
$ 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 description of more specialized usage modes that can be ignored by most users.
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)
$
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)
$
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 database4, therefor the first step will be to create a Kerberos user database. Shishi's user database system is called Shisa. Once Shisa is configured, you can then start the server and begin issuing Kerberos tickets to your users. The Shishi server is called 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.
The user database part of Shishi is called Shisa. The Shisa library is independent of the core Shishi library. Shisa is responsible for storing the name of your realms, the name of your principals (users), accounting information for the users (i.e., when each account start to be valid and when it expire), and the cryptographic keys each user have. Some Kerberos internal data can also be stored, such as the key version number, the last dates for when various ticket requests were made, the cryptographic salt, string-to-key parameters and password for each user. Not all information need to be stored. For example, in some situations it is prudent to leave the password field empty, so that somebody who manage to steal the user database will only be able to compromise your system, and not other systems were your user may have re-used the same password. On the other hand, you may already store the password in your customized database, in which case being able to change it via the Shisa interface can be useful.
Shisa is a small (a few thousand lines of 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 may be separated into its own project later on. You should keep this in mind, so that you don't consider writing a Shisa backend for your own database a purely Shishi specific project. You may, for example, chose to use the Shisa interface in your own applications to have a simple interface to your user database. Your experience and feedback is appreciated if you chose to explore this.
Note that the Shisa database does not expose everything you may want to know about a user, such as its full human name, telephone number or even the user's login account name or home directory. It only store what is needed to authenticate a peer claiming to be an entity. Thus it does not make sense to replace your current user database or /etc/passwd with data derived from the Shisa database. Instead, it is intended that you write a Shisa backend that export 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.
The configuration file for Shisa is typically stored in /usr/local/etc/shishi/shisa.conf. You do not have to configure this file, the defaults should be acceptable to first-time users. The file is used to define where you user database reside, and some options such as making the database read-only or whether errors detected when accessing the database should be ignored. (The latter may be useful if the server is a remote LDAP server that may be unavailable, and you want to fail over to a local copy of the database.)
The default will store the user database using directories and files, rooted by default in /usr/local/var/shishi. You may use standard file permission settings to control access to the directory hierarchy. It is strongly recommended to restrict access to the directory. Storing the directory on local storage (i.e., hard disk or removal media) is recommended. We discourage placing the database on a network file system, but realize it can be useful in some situations (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.
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 create a realm with two principals; one ticket granting ticket for the realm, and one host key for the server. This is what you typically need to get started, but it doesn't serve our purposes. So we start by removing the principals and the realm. To do that, we need to figure out the name of the realm. The ‘--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 are 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.
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 indicate the database do not exist. For a file database, you can create it by simply creating the directory, as follows. Note the access permission change with ‘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 does not lead to a system compromise. (However, if the user database is stolen, system compromises of other systems may be possible if you use, e.g., Kerberos Telnet.)
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 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
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 have one principal that is used for authenticating against the “ticket granting service” on the Kerberos server with a ticket instead of using the password. This is used by the user when she acquire a ticket for servers. This principal must look like ‘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 mean 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 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).
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 protocols 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.
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.
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.
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).
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.
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.
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.
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).
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 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.
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:~$
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:~$
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:~$
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
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
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).
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.
Kerberos imposes a few assumptions on the environment in which it can properly function: