1 \input texinfo @c -*- mode: texinfo; coding: us-ascii; -*-
2 @c This file is part of Shishi.
3 @c See below for copyright and license.
5 @setfilename shishi.info
10 @c Unify some of the indices.
15 This manual is last updated @value{UPDATED} for version
16 @value{VERSION} of Shishi.
18 Copyright @copyright{} 2002, 2003, 2004, 2005, 2006, 2007 Simon Josefsson.
21 Permission is granted to copy, distribute and/or modify this document
22 under the terms of the GNU Free Documentation License, Version 1.2 or
23 any later version published by the Free Software Foundation; with no
24 Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
25 copy of the license is included in the section entitled ``GNU Free
26 Documentation License''.
30 @dircategory GNU utilities
32 * shishi: (shishi). A Kerberos 5 implementation
35 @dircategory GNU Libraries
37 * libshishi: (shishi). Library implementing Kerberos 5.
42 @subtitle Kerberos 5 implementation for the GNU system
43 @subtitle for version @value{VERSION}, @value{UPDATED}
44 @author Simon Josefsson
46 @vskip 0pt plus 1filll
59 * Introduction:: How to use this manual.
60 * User Manual:: Using Shishi as end-user.
61 * Administration Manual:: Administrating server aspects of Shishi.
62 * Reference Manual:: Detailed description of config files, etc.
63 * Programming Manual:: Calling Shishi from a programming language.
64 * Acknowledgements:: Whom to blame.
68 * Criticism of Kerberos:: Why you maybe shouldn't use Kerberos.
69 * Protocol Extensions:: Description of protocol extensions used.
70 * Copying Information:: How you can copy and share Shishi.
74 * Function and Data Index:: Index of functions, variables and data types.
75 * Concept Index:: Index of concepts and programs.
79 @c **********************************************************
80 @c ******************** Introduction **********************
81 @c **********************************************************
85 Shishi is a (still incomplete) implementation of the Kerberos 5
86 network authentication system. Shishi can be used to authenticate
87 users in distributed systems.
89 Shishi contains a library ('libshishi') that can be used by
90 application developers to add support for Kerberos 5. Shishi contains
91 a command line utility ('shishi') that is used by users to acquire and
92 manage tickets (and more). The server side, a Key Distribution
93 Center, is implemented by 'shishid'. Of course, a manual documenting
94 usage aspects as well as the programming API is included.
96 Shishi currently supports AS/TGS exchanges for acquiring tickets,
97 pre-authentication, the AP exchange for performing client and server
98 authentication, and SAFE/PRIV for integrity/privacy protected
99 application data exchanges.
101 Shishi is internationalized; error and status messages can be
102 translated into the users' language; user name and passwords can be
103 converted into any available character set (normally including
104 ISO-8859-1 and UTF-8) and also be processed using an experimental
107 Most, if not all, of the widely used encryption and checksum types are
108 supported, such as 3DES, AES, ARCFOUR and HMAC-SHA1.
110 Shishi is developed for the GNU/Linux system, but runs on over 20
111 platforms including most major Unix platforms and Windows, and many
112 kind of devices including iPAQ handhelds and S/390 mainframes.
114 Shishi is free software licensed under the GNU General Public License.
118 * Features and Status::
120 * Cryptographic Overview::
121 * Supported Platforms::
123 * Commercial Support::
124 * Downloading and Installing::
129 @node Getting Started
130 @section Getting Started
132 This manual documents the Shishi application and library programming
133 interface. All commands, functions and data types provided by Shishi
136 The reader is assumed to possess basic familiarity with network
137 security and the Kerberos 5 security system.
139 This manual can be used in several ways. If read from the beginning
140 to the end, it gives a good introduction into the library and how it
141 can be used in an application. Forward references are included where
142 necessary. Later on, the manual can be used as a reference manual to
143 get just the information needed about any particular interface of the
144 library. Experienced programmers might want to start looking at the
145 examples at the end of the manual, and then only read up those parts
146 of the interface which are unclear.
148 @node Features and Status
149 @section Features and Status
151 Shishi might have a couple of advantages over other packages doing a
155 @item It's Free Software
156 Anybody can use, modify, and redistribute it under the terms of the GNU
157 General Public License (@pxref{GNU GPL}).
159 @item It's thread-safe
160 The library uses no global variables.
162 @item It's internationalized
163 It handles non-ASCII username and passwords and user visible strings
164 used in the library (error messages) can be translated into the users'
168 It should work on all Unix like operating systems, including Windows.
172 Shishi is far from feature complete, it is not even a full RFC 1510
173 implementation yet. However, some basic functionality is implemented.
174 A few implemented feature are mentioned below.
178 @item Initial authentication (AS) from raw key or password.
179 This step is typically used to acquire a ticket granting ticket and,
180 less commonly, a server ticket.
182 @item Subsequent authentication (TGS).
183 This step is typically used to acquire a server ticket, by
184 authenticating yourself using the ticket granting ticket.
186 @item Client-Server authentication (AP).
187 This step is used by clients and servers to prove to each other who
188 they are, using negotiated tickets.
190 @item Integrity protected communication (SAFE).
191 This step is used by clients and servers to exchange integrity
192 protected data with each other. The key is typically agreed on using
193 the Client-Server authentication step.
195 @item Ticket cache, supporting multiple principals and realms.
196 As tickets have a life time of typically several hours, they are
197 managed in disk files. There can be multiple ticket caches, and each
198 ticket cache can store tickets for multiple clients (users), servers,
199 encryption types, etc. Functionality is provided for locating the
200 proper ticket for every use.
202 @item Most standard cryptographic primitives.
203 The believed most secure algorithms are supported
204 (@pxref{Cryptographic Overview}).
206 @item Telnet client and server.
207 This is used to remotely login to other machines, after authenticating
208 yourself with a ticket.
211 This is used to login locally on a machine.
213 @item KDC addresses located using DNS SRV RRs.
215 @item Modularized low-level crypto interface.
216 Currently Gnulib and Libgcrypt are supported. If you wish to add
217 support for another low-level cryptographic library, you only have to
218 implement a few APIs for DES, AES, MD5, SHA1, HMAC, etc. Look at
219 @file{gl/gc-gnulib.c} or @file{gl/gc-libgcrypt.c} as a starting
224 The following table summarize what the current objectives are (i.e.,
225 the todo list) and an estimate on how long it will take to implement
226 the feature, including some reasonable startup-time to get familiar
227 with Shishi in general. If you like to start working on anything,
228 please let me know so work duplication can be avoided.
232 @item Parse @file{/etc/krb5.keytab} to extract keys to use for telnetd etc (week)
234 @item Cross-realm support (week).
236 @item PKINIT (use libksba, weeks)
238 @item Finish GSSAPI support via GSSLib (weeks)
239 Shishi will not support GSSLib natively, but a separate project
240 ``GSSLib'' is under way to produce a generic GSS implementation, and
241 it will use Shishi to implement the Kerberos 5 mechanism.
243 @item Port to cyclone (cyclone need to mature first)
245 @item Modularize ASN.1 library so it can be replaced (days).
246 Almost done, all ASN.1 functionality is found in lib/asn1.c, although
247 the interface is rather libtasn1 centric.
249 @item KDC (initiated, weeks)
251 @item LDAP backend for Shisa.
253 @item Set/Change password protocol (weeks?)
255 @item Port applications to use Shishi (indefinite)
257 @item Finish server-realm stuff
259 @item Improve documentation
261 @item Improve internationalization
263 @item Add AP-REQ replay cache (week).
265 @item Study benefits by introducing a PA-TGS-REP.
266 This would provide mutual authentication of the KDC in a way that is
267 easier to analyze. Currently the mutual authentication property is
268 only implicit from successful decryption of the KDC-REP and the 4 byte
271 @item GUI applet for managing tickets.
272 This is supported via the ticket-applet, of which a Shishi port is
273 published on the Shishi home page.
275 @item Authorization library (months?)
276 The shishi_authorized_p() is not a good solution, better would be to
277 have a generic and flexible authorization library. Possibly based on
278 S-EXP's in tickets? Should support non-Kerberos uses as well, of
281 @item Proof read manual.
283 @item X.500 support, including DOMAIN-X500-COMPRESS.
284 I will accept patches that implement this, if it causes minimal
285 changes to the current code.
292 This section describes RFC 1510 from a protocol point of
293 view@footnote{The text is a lightly adapted version of the
294 introduction section from RFC 1510 by J. Kohl and C. Neuman, September
295 1993, copyright likely owned by the RFC 1510 authors or some
298 Kerberos provides a means of verifying the identities of principals,
299 (e.g., a workstation user or a network server) on an open
300 (unprotected) network. This is accomplished without relying on
301 authentication by the host operating system, without basing trust on
302 host addresses, without requiring physical security of all the hosts
303 on the network, and under the assumption that packets traveling along
304 the network can be read, modified, and inserted at will. (Note,
305 however, that many applications use Kerberos' functions only upon the
306 initiation of a stream-based network connection, and assume the
307 absence of any "hijackers" who might subvert such a connection. Such
308 use implicitly trusts the host addresses involved.) Kerberos performs
309 authentication under these conditions as a trusted third- party
310 authentication service by using conventional cryptography, i.e.,
311 shared secret key. (shared secret key - Secret and private are often
312 used interchangeably in the literature. In our usage, it takes two
313 (or more) to share a secret, thus a shared DES key is a secret key.
314 Something is only private when no one but its owner knows it. Thus,
315 in public key cryptosystems, one has a public and a private key.)
317 The authentication process proceeds as follows: A client sends a
318 request to the authentication server (AS) requesting "credentials" for
319 a given server. The AS responds with these credentials, encrypted in
320 the client's key. The credentials consist of 1) a "ticket" for the
321 server and 2) a temporary encryption key (often called a "session
322 key"). The client transmits the ticket (which contains the client's
323 identity and a copy of the session key, all encrypted in the server's
324 key) to the server. The session key (now shared by the client and
325 server) is used to authenticate the client, and may optionally be used
326 to authenticate the server. It may also be used to encrypt further
327 communication between the two parties or to exchange a separate
328 sub-session key to be used to encrypt further communication.
330 The implementation consists of one or more authentication servers
331 running on physically secure hosts. The authentication servers
332 maintain a database of principals (i.e., users and servers) and their
333 secret keys. Code libraries provide encryption and implement the
334 Kerberos protocol. In order to add authentication to its
335 transactions, a typical network application adds one or two calls to
336 the Kerberos library, which results in the transmission of the
337 necessary messages to achieve authentication.
339 The Kerberos protocol consists of several sub-protocols (or
340 exchanges). There are two methods by which a client can ask a
341 Kerberos server for credentials. In the first approach, the client
342 sends a cleartext request for a ticket for the desired server to the
343 AS. The reply is sent encrypted in the client's secret key. Usually
344 this request is for a ticket-granting ticket (TGT) which can later be
345 used with the ticket-granting server (TGS). In the second method, the
346 client sends a request to the TGS. The client sends the TGT to the
347 TGS in the same manner as if it were contacting any other application
348 server which requires Kerberos credentials. The reply is encrypted in
349 the session key from the TGT.
351 Once obtained, credentials may be used to verify the identity of the
352 principals in a transaction, to ensure the integrity of messages
353 exchanged between them, or to preserve privacy of the messages. The
354 application is free to choose whatever protection may be necessary.
356 To verify the identities of the principals in a transaction, the
357 client transmits the ticket to the server. Since the ticket is sent
358 "in the clear" (parts of it are encrypted, but this encryption doesn't
359 thwart replay) and might be intercepted and reused by an attacker,
360 additional information is sent to prove that the message was
361 originated by the principal to whom the ticket was issued. This
362 information (called the authenticator) is encrypted in the session
363 key, and includes a timestamp. The timestamp proves that the message
364 was recently generated and is not a replay. Encrypting the
365 authenticator in the session key proves that it was generated by a
366 party possessing the session key. Since no one except the requesting
367 principal and the server know the session key (it is never sent over
368 the network in the clear) this guarantees the identity of the client.
370 The integrity of the messages exchanged between principals can also be
371 guaranteed using the session key (passed in the ticket and contained
372 in the credentials). This approach provides detection of both replay
373 attacks and message stream modification attacks. It is accomplished
374 by generating and transmitting a collision-proof checksum (elsewhere
375 called a hash or digest function) of the client's message, keyed with
376 the session key. Privacy and integrity of the messages exchanged
377 between principals can be secured by encrypting the data to be passed
378 using the session key passed in the ticket, and contained in the
381 @node Cryptographic Overview
382 @section Cryptographic Overview
384 Shishi implements several of the standard cryptographic primitives.
385 In this section we give the names of the supported encryption suites,
386 and some notes about them, and their associated checksum suite.
388 Statements such as ``it is weak'' should be read as meaning that there
389 is no credible security analysis of the mechanism available, and/or
390 that should an attack be published publicly, few people would likely
391 be surprised. Also keep in mind that the key size mentioned is the
392 actual key size, not the effective key space as far as a brute force
395 As you may infer from the descriptions, there is currently no
396 encryption algorithm and only one checksum algorithm that inspire
397 great confidence in its design. Hopefully this will change over time.
408 @code{NULL} is a dummy encryption suite for debugging. Encryption and
409 decryption are identity functions. No integrity protection. It is
410 weak. It is associated with the @code{NULL} checksum.
413 @itemx arcfour-hmac-exp
415 @code{arcfour-hmac-*} are a proprietary stream cipher with 56 bit
416 (@code{arcfour-hmac-exp}) or 128 bit (@code{arcfour-hmac}) keys, used
417 in a proprietary way described in an expired IETF draft
418 @file{draft-brezak-win2k-krb-rc4-hmac-04.txt}. Deriving keys from
419 passwords is supported, and is done by computing a message digest
420 (MD4) of a 16-bit Unicode representation of the ASCII password, with
421 no salt. Data is integrity protected with a keyed hash (HMAC-MD5),
422 where the key is derived from the base key in a creative way. It is
423 weak. It is associated with the @code{arcfour-hmac-md5} checksum.
427 @code{des-cbc-none} is DES encryption and decryption with 56 bit keys
428 and 8 byte blocks in CBC mode, using a zero IV. The keys can be
429 derived from passwords by an obscure application specific algorithm.
430 It is weak, because it offers no integrity protection. This is
431 typically only used by RFC 1964 GSS-API implementations (which try to
432 protect integrity using an ad-hoc solution). It is associated with
433 the @code{NULL} checksum.
437 @code{des-cbc-crc} is DES encryption and decryption with 56 bit keys
438 and 8 byte blocks in CBC mode, using the key as IV (@pxref{Key as
439 initialization vector}). The keys can be derived from passwords by an
440 obscure application specific algorithm. Data is integrity protected
441 with an unkeyed but encrypted @code{CRC32}-like checksum. It is
442 weak. It is associated with the @code{rsa-md5-des} checksum.
446 @code{des-cbc-md4} is DES encryption and decryption with 56 bit keys
447 and 8 byte blocks in CBC mode, using a zero IV. The keys can be
448 derived from passwords by an obscure application specific algorithm.
449 Data is integrity protected with an unkeyed but encrypted MD4 hash.
450 It is weak. It is associated with the @code{rsa-md4-des} checksum.
454 @code{des-cbc-md5} is DES encryption and decryption with 56 bit keys
455 and 8 byte blocks in CBC mode, using a zero IV. The keys can be
456 derived from passwords by an obscure application specific algorithm.
457 Data is integrity protected with an unkeyed but encrypted MD5 hash.
458 It is weak. It is associated with the @code{rsa-md5-des} checksum.
459 This is the strongest RFC 1510 interoperable encryption mechanism.
463 @code{des3-cbc-none} is DES encryption and decryption with three 56
464 bit keys (effective key size 112 bits) and 8 byte blocks in CBC mode.
465 The keys can be derived from passwords by the same algorithm as
466 @code{des3-cbc-sha1-kd}. It is weak, because it offers no integrity
467 protection. This is typically only used by GSS-API implementations
468 (which try to protect integrity using an ad-hoc solution) for
469 interoperability with some existing Kerberos GSS implementations. It
470 is associated with the @code{NULL} checksum.
472 @item des3-cbc-sha1-kd
474 @code{des3-cbc-sha1-kd} is DES encryption and decryption with three 56
475 bit keys (effective key size 112 bits) and 8 byte blocks in CBC mode.
476 The keys can be derived from passwords by a algorithm based on the
477 paper "A Better Key Schedule For DES-like Ciphers"
478 @footnote{@url{http://www.research.att.com/~smb/papers/ides.pdf}} by
479 Uri Blumenthal and Steven M. Bellovin (it is not clear if the
480 algorithm, and the way it is used, is used by any other protocols,
481 although it seems unlikely). Data is integrity protected with a keyed
482 SHA1 hash in HMAC mode. It has no security proof, but is assumed to
483 provide adequate security in the sense that knowledge on how to crack
484 it is not known to the public. Note that the key derivation function
485 is not widely used outside of Kerberos, hence not widely studied. It
486 is associated with the @code{hmac-sha1-des3-kd} checksum.
488 @item aes128-cts-hmac-sha1-96
489 @itemx aes256-cts-hmac-sha1-96
491 @code{aes128-cts-hmac-sha1-96} and @code{aes256-cts-hmac-sha1-96} is
492 AES encryption and decryption with 128 bit and 256 bit key,
493 respectively, and 16 byte blocks in CBC mode with Cipher Text
494 Stealing. Cipher Text Stealing means data length of encrypted data is
495 preserved (pure CBC add up to 7 pad characters). The keys can be
496 derived from passwords with RSA Laboratories PKCS#5 Password Based Key
498 2@footnote{@url{http://www.rsasecurity.com/rsalabs/pkcs/pkcs-5/}},
499 which is allegedly provably secure in a random oracle model. Data is
500 integrity protected with a keyed SHA1 hash, in HMAC mode, truncated to
501 96 bits. There is no security proof, but the schemes are assumed to
502 provide adequate security in the sense that knowledge on how to crack
503 them is not known to the public. Note that AES has yet to receive the
504 test of time, and the AES cipher encryption mode (CBC with Ciphertext
505 Stealing, and a non-standard IV output) is not widely standardized
506 (hence not widely studied). It is associated with the
507 @code{hmac-sha1-96-aes128} and @code{hmac-sha1-96-aes256} checksums,
512 The protocol do not include any way to negotiate which checksum
513 mechanisms to use, so in most cases the associated checksum will be
514 used. However, checksum mechanisms can be used with other encryption
515 mechanisms, as long as they are compatible in terms of key format etc.
516 Here are the names of the supported checksum mechanisms, with some
517 notes on their status and the compatible encryption mechanisms. They
518 are ordered by increased security as perceived by the author.
524 @code{NULL} is a dummy checksum suite for debugging. It provides no
525 integrity. It is weak. It is compatible with the @code{NULL}
526 encryption mechanism.
528 @item arcfour-hmac-md5
530 @code{arcfour-hmac-md5} is a keyed HMAC-MD5 checksum computed on a MD5
531 message digest, in turn computed on a four byte message type indicator
532 concatenated with the application data. (The @code{arcfour}
533 designation is thus somewhat misleading, but since this checksum
534 mechanism is described in the same document as the @code{arcfour}
535 encryption mechanisms, it is not a completely unnatural designation.)
536 It is weak. It is compatible with all encryption mechanisms.
540 @code{rsa-md4} is a unkeyed MD4 hash computed over the message. It is
541 weak, because it is unkeyed. However applications can, with care, use
542 it non-weak ways (e.g., by including the hash in other messages that
543 are protected by other means). It is compatible with all encryption
548 @code{rsa-md4-des} is a DES CBC encryption of one block of random data
549 and a unkeyed MD4 hash computed over the random data and the message
550 to integrity protect. The key used is derived from the base protocol
551 key by XOR with a constant. It is weak. It is compatible with the
552 @code{des-cbc-crc}, @code{des-cbc-md4}, @code{des-cbc-md5} encryption
557 @code{rsa-md5} is a unkeyed MD5 hash computed over the message. It is
558 weak, because it is unkeyed. However applications can, with care, use
559 it non-weak ways (e.g., by including the hash in other messages that
560 are protected by other means). It is compatible with all encryption
565 @code{rsa-md5-des} is a DES CBC encryption of one block of random data
566 and a unkeyed MD5 hash computed over the random data and the message
567 to integrity protect. The key used is derived from the base protocol
568 key by XOR with a constant. It is weak. It is compatible with the
569 @code{des-cbc-crc}, @code{des-cbc-md4}, @code{des-cbc-md5} encryption
572 @item hmac-sha1-des3-kd
574 @code{hmac-sha1-des3-kd} is a keyed SHA1 hash in HMAC mode computed
575 over the message. The key is derived from the base protocol by the
576 simplified key derivation function (similar to the password key
577 derivation functions of @code{des3-cbc-sha1-kd}, which does not appear
578 to be widely used outside Kerberos and hence not widely studied). It
579 has no security proof, but is assumed to provide good security. The
580 weakest part is likely the proprietary key derivation function. It is
581 compatible with the @code{des3-cbc-sha1-kd} encryption mechanism.
583 @item hmac-sha1-96-aes128
584 @itemx hmac-sha1-96-aes256
586 @code{hmac-sha1-96-aes*} are keyed SHA1 hashes in HMAC mode computed
587 over the message and then truncated to 96 bits. The key is derived
588 from the base protocol by the simplified key derivation function
589 (similar to the password key derivation functions of
590 @code{aes*-cts-hmac-sha1-96}, i.e., PKCS#5). It has no security
591 proof, but is assumed to provide good security. It is compatible with
592 the @code{aes*-cts-hmac-sha1-96} encryption mechanisms.
596 Several of the cipher suites have long names that can be hard to
597 memorize. For your convenience, the following short-hand aliases
598 exists. They can be used wherever the full encryption names are used.
604 Alias for @code{arcfour-hmac}.
608 Alias for @code{des-cbc-crc}.
612 Alias for @code{des-cbc-md4}.
617 Alias for @code{des-cbc-md5}.
622 Alias for @code{des3-cbc-sha1-kd}.
626 Alias for @code{aes128-cts-hmac-sha1-96}.
631 Alias for @code{aes256-cts-hmac-sha1-96}.
635 @node Supported Platforms
636 @section Supported Platforms
638 Shishi has at some point in time been tested on the following
639 platforms. Online build reports for each platforms and Shishi version
640 is available at @url{http://josefsson.org/autobuild/}.
644 @item Debian GNU/Linux 3.0 (Woody)
647 GCC 2.95.4 and GNU Make. This is the main development platform.
648 @code{alphaev67-unknown-linux-gnu}, @code{alphaev6-unknown-linux-gnu},
649 @code{arm-unknown-linux-gnu}, @code{armv4l-unknown-linux-gnu},
650 @code{hppa-unknown-linux-gnu}, @code{hppa64-unknown-linux-gnu},
651 @code{i686-pc-linux-gnu}, @code{ia64-unknown-linux-gnu},
652 @code{m68k-unknown-linux-gnu}, @code{mips-unknown-linux-gnu},
653 @code{mipsel-unknown-linux-gnu}, @code{powerpc-unknown-linux-gnu},
654 @code{s390-ibm-linux-gnu}, @code{sparc-unknown-linux-gnu},
655 @code{sparc64-unknown-linux-gnu}.
657 @item Debian GNU/Linux 2.1
660 GCC 2.95.4 and GNU Make. @code{armv4l-unknown-linux-gnu}.
665 Tru64 UNIX C compiler and Tru64 Make. @code{alphaev67-dec-osf5.1},
666 @code{alphaev68-dec-osf5.1}.
671 GCC 2.96 and GNU Make. @code{alphaev6-unknown-linux-gnu},
672 @code{alphaev67-unknown-linux-gnu}.
674 @item SuSE Linux 7.2a
677 GCC 3.0 and GNU Make. @code{ia64-unknown-linux-gnu}.
682 GCC 3.2.2 and GNU Make. @code{x86_64-unknown-linux-gnu} (AMD64
685 @item RedHat Linux 7.2
688 GCC 2.96 and GNU Make. @code{alphaev6-unknown-linux-gnu},
689 @code{alphaev67-unknown-linux-gnu}, @code{ia64-unknown-linux-gnu}.
691 @item RedHat Linux 8.0
694 GCC 3.2 and GNU Make. @code{i686-pc-linux-gnu}.
696 @item RedHat Advanced Server 2.1
697 @cindex RedHat Advanced Server
699 GCC 2.96 and GNU Make. @code{i686-pc-linux-gnu}.
701 @item Slackware Linux 8.0.01
704 GCC 2.95.3 and GNU Make. @code{i686-pc-linux-gnu}.
706 @item Mandrake Linux 9.0
709 GCC 3.2 and GNU Make. @code{i686-pc-linux-gnu}.
714 MIPS C compiler, IRIX Make. @code{mips-sgi-irix6.5}.
719 IBM C for AIX compiler, AIX Make. @code{rs6000-ibm-aix4.3.2.0}.
721 @c @item Microsoft Windows 2000 (Cygwin)
724 @c GCC 3.2, GNU make. @code{i686-pc-cygwin}.
729 HP-UX C compiler and HP Make. @code{ia64-hp-hpux11.22},
730 @code{hppa2.0w-hp-hpux11.11}.
732 @item SUN Solaris 2.8
735 Sun WorkShop Compiler C 6.0 and SUN Make. @code{sparc-sun-solaris2.8}.
740 GCC 2.95.3 and GNU Make. @code{alpha-unknown-netbsd1.6},
741 @code{i386-unknown-netbsdelf1.6}.
743 @item OpenBSD 3.1 and 3.2
746 GCC 2.95.3 and GNU Make. @code{alpha-unknown-openbsd3.1},
747 @code{i386-unknown-openbsd3.1}.
749 @item FreeBSD 4.7 and 4.8
752 GCC 2.95.4 and GNU Make. @code{alpha-unknown-freebsd4.7},
753 @code{alpha-unknown-freebsd4.8}, @code{i386-unknown-freebsd4.7},
754 @code{i386-unknown-freebsd4.8}.
756 @item MacOS X 10.2 Server Edition
759 GCC 3.1 and GNU Make. @code{powerpc-apple-darwin6.5}.
761 @item Cross compiled to uClinux/uClibc on Motorola Coldfire.
762 @cindex Motorola Coldfire
766 GCC 3.4 and GNU Make @code{m68k-uclinux-elf}.
770 If you use Shishi on, or port Shishi to, a new platform please report
771 it to the author (@pxref{Bug Reports}).
774 @section Getting help
776 A mailing list where users of Shishi may help each other exists, and
777 you can reach it by sending e-mail to @email{help-shishi@@gnu.org}.
778 Archives of the mailing list discussions, and an interface to manage
779 subscriptions, is available through the World Wide Web at
780 @url{http://lists.gnu.org/mailman/listinfo/help-shishi}.
782 @node Commercial Support
783 @section Commercial Support
785 Commercial support is available for users of Shishi. The kind of
786 support that can be purchased may include:
790 @item Implement new features.
791 Such as support for some optional part of the Kerberos standards,
792 e.g. PKINIT, hardware token authentication.
794 @item Port Shishi to new platforms.
795 This could include porting Shishi to an embedded platforms that may
796 need memory or size optimization.
798 @item Integrate Kerberos 5 support in your existing project.
800 @item System design of components related to Kerberos 5.
804 If you are interested, please write to:
807 Simon Josefsson Datakonsult
812 E-mail: simon@josefsson.org
815 If your company provide support related to Shishi and would like to be
816 mentioned here, contact the author (@pxref{Bug Reports}).
818 @node Downloading and Installing
819 @section Downloading and Installing
823 The package can be downloaded from several places, including:
825 @url{http://josefsson.org/shishi/releases/}
827 The latest version is stored in a file, e.g.,
828 @samp{shishi-@value{VERSION}.tar.gz} where the @samp{@value{VERSION}}
829 indicate the highest version number.
831 The package is then extracted, configured and built like many other
832 packages that use Autoconf. For detailed information on configuring
833 and building it, refer to the @file{INSTALL} file that is part of the
834 distribution archive.
836 Here is an example terminal session that download, configure, build
837 and install the package. You will need a few basic tools, such as
838 @samp{sh}, @samp{make} and @samp{cc}.
841 $ wget -q http://josefsson.org/shishi/releases/shishi-@value{VERSION}.tar.gz
842 $ tar xfz shishi-@value{VERSION}.tar.gz
843 $ cd shishi-@value{VERSION}/
852 After this you should be prepared to continue with the user,
853 administration or programming manual, depending on how you want to use
856 A few @code{configure} options may be relevant, summarized in the
862 @itemx --disable-3des
865 @itemx --disable-null
866 @itemx --disable-arcfour
867 Disable a cryptographic algorithm at compile time. Usually it is
868 better to disable algorithms during run-time with the configuration
869 file, but this allows you to reduce the code size slightly.
871 @item --disable-starttls
872 Disable the experimental TLS support for KDC connections. If you do
873 not use a Shishi KDC, this support is of no use so you could safely
876 @item --without-stringprep
877 Disable internationalized string processing.
881 For the complete list, refer to the output from @code{configure
886 @cindex Reporting Bugs
888 If you think you have found a bug in Shishi, please investigate it and
893 @item Please make sure that the bug is really in Shishi, and
894 preferably also check that it hasn't already been fixed in the latest
897 @item You have to send us a test case that makes it possible for us to
900 @item You also have to explain what is wrong; if you get a crash, or
901 if the results printed are not good and in that case, in what way.
902 Make sure that the bug report includes all information you would need
903 to fix this kind of bug for someone else.
907 Please make an effort to produce a self-contained report, with
908 something definite that can be tested or debugged. Vague queries or
909 piecemeal messages are difficult to act on and don't help the
912 If your bug report is good, we will do our best to help you to get a
913 corrected version of the software; if the bug report is poor, we won't
914 do anything about it (apart from asking you to send better bug
917 If you think something in this manual is unclear, or downright
918 incorrect, or if the language needs to be improved, please also send a
921 Send your bug report to:
923 @center @samp{bug-shishi@@josefsson.org}
926 @section Contributing
930 If you want to submit a patch for inclusion -- from solve a typo you
931 discovered, up to adding support for a new feature -- you should
932 submit it as a bug report (@pxref{Bug Reports}). There are some
933 things that you can do to increase the chances for it to be included
934 in the official package.
936 Unless your patch is very small (say, under 10 lines) we require that
937 you assign the copyright of your work to the Free Software Foundation.
938 This is to protect the freedom of the project. If you have not
939 already signed papers, we will send you the necessary information when
940 you submit your contribution.
942 For contributions that doesn't consist of actual programming code, the
943 only guidelines are common sense. Use it.
945 For code contributions, a number of style guides will help you:
950 Follow the GNU Standards document (@pxref{top, GNU Coding Standards,,
953 If you normally code using another coding standard, there is no
954 problem, but you should use @samp{indent} to reformat the code
955 (@pxref{top, GNU Indent,, indent}) before submitting your work.
957 @item Use the unified diff format @samp{diff -u}.
960 The only valid reason for ever aborting the execution of the program
961 is due to memory allocation errors, but for that you should call
962 @samp{xalloc_die} to allow the application to recover if it wants to.
964 @item Design with thread safety in mind.
965 Don't use global variables. Don't even write to per-handle global
966 variables unless the documented behaviour of the function you write is
967 to write to the per-handle global variable.
969 @item Avoid using the C math library.
970 It causes problems for embedded implementations, and in most
971 situations it is very easy to avoid using it.
973 @item Document your functions.
974 Use comments before each function headers, that, if properly
975 formatted, are extracted into Texinfo manuals and GTK-DOC web pages.
977 @item Supply a ChangeLog and NEWS entries, where appropriate.
981 @c **********************************************************
982 @c ******************** User Manual **********************
983 @c **********************************************************
986 @cindex End-user Shishi usage
988 Usually Shishi interacts with you to get some initial authentication
989 information like a password, and then contacts a server to receive a
990 so called ticket granting ticket. From now on, you rarely interacts
991 with Shishi directly. Applications that needs security services
992 instruct the Shishi library to use the ticket granting ticket to get
993 new tickets for various servers. An example could be if you log on to
994 a host remotely via @samp{telnet}. The host usually requires
995 authentication before permitting you in. The @samp{telnet} client
996 uses the ticket granting ticket to get a ticket for the server, and
997 then use this ticket to authenticate you against the server (typically
998 the server is also authenticated to you). You perform the initial
999 authentication by typing @command{shishi} at the prompt. Sometimes it
1000 is necessary to supply options telling Shishi what your principal name
1001 (user name in the Kerberos realm) or realm is. In the example, I
1002 specify the client name @code{simon@@JOSEFSSON.ORG}.
1005 $ shishi simon@@JOSEFSSON.ORG
1006 Enter password for `simon@@JOSEFSSON.ORG':
1007 simon@@JOSEFSSON.ORG:
1008 Authtime: Fri Aug 15 04:44:49 2003
1009 Endtime: Fri Aug 15 05:01:29 2003
1010 Server: krbtgt/JOSEFSSON.ORG key des3-cbc-sha1-kd (16)
1011 Ticket key: des3-cbc-sha1-kd (16) protected by des3-cbc-sha1-kd (16)
1012 Ticket flags: INITIAL (512)
1016 As you can see, Shishi also prints a short description of the ticket
1019 A logical next step is to display all tickets you have received (by
1020 the way, the tickets are usually stored as text in
1021 @file{~/.shishi/tickets}). This is achieved by typing @command{shishi
1026 Tickets in `/home/jas/.shishi/tickets':
1029 Authtime: Fri Aug 15 04:49:46 2003
1030 Endtime: Fri Aug 15 05:06:26 2003
1031 Server: krbtgt/JOSEFSSON.ORG key des-cbc-md5 (3)
1032 Ticket key: des-cbc-md5 (3) protected by des-cbc-md5 (3)
1033 Ticket flags: INITIAL (512)
1036 Authtime: Fri Aug 15 04:49:46 2003
1037 Starttime: Fri Aug 15 04:49:49 2003
1038 Endtime: Fri Aug 15 05:06:26 2003
1039 Server: host/latte.josefsson.org key des-cbc-md5 (3)
1040 Ticket key: des-cbc-md5 (3) protected by des-cbc-md5 (3)
1046 As you can see, I had a ticket for the server
1047 @samp{host/latte.josefsson.org} which was generated by
1048 @samp{telnet}:ing to that host.
1050 If, for some reason, you want to manually get a ticket for a specific
1051 server, you can use the @command{shishi --server-name} command.
1052 Normally, however, the application that uses Shishi will take care of
1053 getting a ticket for the appropriate server, so you normally wouldn't
1057 $ shishi --server-name=user/billg --encryption-type=des-cbc-md4
1059 Authtime: Fri Aug 15 04:49:46 2003
1060 Starttime: Fri Aug 15 04:54:33 2003
1061 Endtime: Fri Aug 15 05:06:26 2003
1062 Server: user/billg key des-cbc-md4 (2)
1063 Ticket key: des-cbc-md4 (2) protected by des-cbc-md5 (3)
1067 As you can see, I acquired a ticket for @samp{user/billg} with a
1068 @samp{des-cbc-md4} (@pxref{Cryptographic Overview}) encryption key
1069 specified with the @samp{--encryption-type} parameter.
1071 To wrap up this introduction, lets see how you can remove tickets.
1072 You may want to do this if you leave your terminal for lunch or
1073 similar, and don't want someone to be able to copy the file and then
1074 use your credentials. Note that this only destroy the tickets
1075 locally, it does not contact any server and tell it that these
1076 credentials are no longer valid. So if someone stole your ticket
1077 file, you must contact your administrator and have them reset your
1078 account, simply using this parameter is not sufficient.
1081 $ shishi --server-name=imap/latte.josefsson.org --destroy
1083 $ shishi --server-name=foobar --destroy
1090 Since the @samp{--server-name} parameter takes a long to type, it is
1091 possible to type the server name directly, after the client name. The
1092 following example demonstrate a AS-REQ followed by a TGS-REQ for a
1093 specific server (assuming you did not have any tickets from the
1097 $ src/shishi simon@@latte.josefsson.org imap/latte.josefsson.org
1098 Enter password for `simon@@latte.josefsson.org':
1099 simon@@latte.josefsson.org:
1100 Acquired: Wed Aug 27 17:21:06 2003
1101 Expires: Wed Aug 27 17:37:46 2003
1102 Server: imap/latte.josefsson.org key aes256-cts-hmac-sha1-96 (18)
1103 Ticket key: aes256-cts-hmac-sha1-96 (18) protected by aes256-cts-hmac-sha1-96 (18)
1104 Ticket flags: FORWARDED PROXIABLE (12)
1108 Refer to the reference manual for all available parameters
1109 (@pxref{Parameters for shishi}). The rest of this section contains
1110 description of more specialized usage modes that can be ignored by
1113 @section Proxiable and Proxy Tickets
1115 At times it may be necessary for a principal to allow a service to
1116 perform an operation on its behalf. The service must be able to take
1117 on the identity of the client, but only for a particular purpose. A
1118 principal can allow a service to take on the principal's identity for
1119 a particular purpose by granting it a proxy.
1121 The process of granting a proxy using the proxy and proxiable flags is
1122 used to provide credentials for use with specific services. Though
1123 conceptually also a proxy, users wishing to delegate their identity in
1124 a form usable for all purpose MUST use the ticket forwarding mechanism
1125 described in the next section to forward a ticket-granting ticket.
1127 The PROXIABLE flag in a ticket is normally only interpreted by the
1128 ticket-granting service. It can be ignored by application servers.
1129 When set, this flag tells the ticket-granting server that it is OK to
1130 issue a new ticket (but not a ticket-granting ticket) with a different
1131 network address based on this ticket. This flag is set if requested by
1132 the client on initial authentication. By default, the client will
1133 request that it be set when requesting a ticket-granting ticket, and
1134 reset when requesting any other ticket.
1136 This flag allows a client to pass a proxy to a server to perform a
1137 remote request on its behalf (e.g. a print service client can give the
1138 print server a proxy to access the client's files on a particular file
1139 server in order to satisfy a print request).
1141 In order to complicate the use of stolen credentials, Kerberos tickets
1142 are usually valid from only those network addresses specifically
1143 included in the ticket[4]. When granting a proxy, the client MUST
1144 specify the new network address from which the proxy is to be used, or
1145 indicate that the proxy is to be issued for use from any address.
1147 The PROXY flag is set in a ticket by the TGS when it issues a proxy
1148 ticket. Application servers MAY check this flag and at their option
1149 they MAY require additional authentication from the agent presenting
1150 the proxy in order to provide an audit trail.
1152 Here is how you would acquire a PROXY ticket for the service
1153 @samp{imap/latte.josefsson.org}:
1156 $ shishi jas@@JOSEFSSON.ORG imap/latte.josefsson.org --proxy
1157 Enter password for `jas@@JOSEFSSON.ORG':
1158 libshishi: warning: KDC bug: Reply encrypted using wrong key.
1160 Authtime: Mon Sep 8 20:02:35 2003
1161 Starttime: Mon Sep 8 20:02:36 2003
1162 Endtime: Tue Sep 9 04:02:35 2003
1163 Server: imap/latte.josefsson.org key des3-cbc-sha1-kd (16)
1164 Ticket key: des3-cbc-sha1-kd (16) protected by des3-cbc-sha1-kd (16)
1165 Ticket flags: PROXY (16)
1169 As you noticed, this asked for your password. The reason is that
1170 proxy tickets must be acquired using a proxiable ticket granting
1171 ticket, which was not present. If you often need to get proxy
1172 tickets, you may acquire a proxiable ticket granting ticket from the
1176 $ shishi --proxiable
1177 Enter password for `jas@@JOSEFSSON.ORG':
1179 Authtime: Mon Sep 8 20:04:27 2003
1180 Endtime: Tue Sep 9 04:04:27 2003
1181 Server: krbtgt/JOSEFSSON.ORG key des3-cbc-sha1-kd (16)
1182 Ticket key: des3-cbc-sha1-kd (16) protected by des3-cbc-sha1-kd (16)
1183 Ticket flags: PROXIABLE INITIAL (520)
1186 Then you should be able to acquire proxy tickets based on that ticket
1187 granting ticket, as follows:
1190 $ shishi jas@@JOSEFSSON.ORG imap/latte.josefsson.org --proxy
1191 libshishi: warning: KDC bug: Reply encrypted using wrong key.
1193 Authtime: Mon Sep 8 20:04:27 2003
1194 Starttime: Mon Sep 8 20:04:32 2003
1195 Endtime: Tue Sep 9 04:04:27 2003
1196 Server: imap/latte.josefsson.org key des3-cbc-sha1-kd (16)
1197 Ticket key: des3-cbc-sha1-kd (16) protected by des3-cbc-sha1-kd (16)
1198 Ticket flags: PROXY (16)
1202 @section Forwardable and Forwarded Tickets
1204 Authentication forwarding is an instance of a proxy where the service
1205 that is granted is complete use of the client's identity. An example
1206 where it might be used is when a user logs in to a remote system and
1207 wants authentication to work from that system as if the login were
1210 The FORWARDABLE flag in a ticket is normally only interpreted by the
1211 ticket-granting service. It can be ignored by application servers.
1212 The FORWARDABLE flag has an interpretation similar to that of the
1213 PROXIABLE flag, except ticket-granting tickets may also be issued with
1214 different network addresses. This flag is reset by default, but users
1215 MAY request that it be set by setting the FORWARDABLE option in the AS
1216 request when they request their initial ticket-granting ticket.
1218 This flag allows for authentication forwarding without requiring the
1219 user to enter a password again. If the flag is not set, then
1220 authentication forwarding is not permitted, but the same result can
1221 still be achieved if the user engages in the AS exchange specifying
1222 the requested network addresses and supplies a password.
1224 The FORWARDED flag is set by the TGS when a client presents a ticket
1225 with the FORWARDABLE flag set and requests a forwarded ticket by
1226 specifying the FORWARDED KDC option and supplying a set of addresses
1227 for the new ticket. It is also set in all tickets issued based on
1228 tickets with the FORWARDED flag set. Application servers may choose to
1229 process FORWARDED tickets differently than non-FORWARDED tickets.
1231 If addressless tickets are forwarded from one system to another,
1232 clients SHOULD still use this option to obtain a new TGT in order to
1233 have different session keys on the different systems.
1235 Here is how you would acquire a FORWARDED ticket for the service
1236 @samp{host/latte.josefsson.org}:
1239 $ shishi jas@@JOSEFSSON.ORG host/latte.josefsson.org --forwarded
1240 Enter password for `jas@@JOSEFSSON.ORG':
1241 libshishi: warning: KDC bug: Reply encrypted using wrong key.
1243 Authtime: Mon Sep 8 20:07:11 2003
1244 Starttime: Mon Sep 8 20:07:12 2003
1245 Endtime: Tue Sep 9 04:07:11 2003
1246 Server: host/latte.josefsson.org key des3-cbc-sha1-kd (16)
1247 Ticket key: des3-cbc-sha1-kd (16) protected by des3-cbc-sha1-kd (16)
1248 Ticket flags: FORWARDED (4)
1252 As you noticed, this asked for your password. The reason is that
1253 forwarded tickets must be acquired using a forwardable ticket granting
1254 ticket, which was not present. If you often need to get forwarded
1255 tickets, you may acquire a forwardable ticket granting ticket from the
1259 $ shishi --forwardable
1260 Enter password for `jas@@JOSEFSSON.ORG':
1262 Authtime: Mon Sep 8 20:08:53 2003
1263 Endtime: Tue Sep 9 04:08:53 2003
1264 Server: krbtgt/JOSEFSSON.ORG key des3-cbc-sha1-kd (16)
1265 Ticket key: des3-cbc-sha1-kd (16) protected by des3-cbc-sha1-kd (16)
1266 Ticket flags: FORWARDABLE INITIAL (514)
1270 Then you should be able to acquire forwarded tickets based on that
1271 ticket granting ticket, as follows:
1274 $ shishi jas@@JOSEFSSON.ORG host/latte.josefsson.org --forwarded
1275 libshishi: warning: KDC bug: Reply encrypted using wrong key.
1277 Authtime: Mon Sep 8 20:08:53 2003
1278 Starttime: Mon Sep 8 20:08:57 2003
1279 Endtime: Tue Sep 9 04:08:53 2003
1280 Server: host/latte.josefsson.org key des3-cbc-sha1-kd (16)
1281 Ticket key: des3-cbc-sha1-kd (16) protected by des3-cbc-sha1-kd (16)
1282 Ticket flags: FORWARDED (4)
1287 @c **********************************************************
1288 @c **************** Administration Manual *****************
1289 @c **********************************************************
1290 @node Administration Manual
1291 @chapter Administration Manual
1293 Here you will learn how to set up, run and maintain the Shishi
1294 Kerberos server. Kerberos is incompatible with the standard Unix
1295 @file{/etc/passwd} password database@footnote{And besides, Shishi is
1296 intended to work on non-Unix platforms as well.}, therefor the first
1297 step will be to create a Kerberos user database. Shishi's user
1298 database system is called Shisa. Once Shisa is configured, you can
1299 then start the server and begin issuing Kerberos tickets to your
1300 users. The Shishi server is called @file{shishid}. After getting the
1301 server up and running, we discuss how you can set up multiple Kerberos
1302 servers, to increase availability or offer load-balancing. Finally,
1303 we include some information intended for developers, that will enable
1304 you to customize Shisa to use an external user database, such as a
1305 @acronym{LDAP} server or @acronym{SQL} database.
1308 * Introduction to Shisa:: Explanation of the Shishi user database.
1309 * Configuring Shisa:: Define the user database in Shisa.
1310 * Using Shisa:: How to add realms and principals to database.
1311 * Starting Shishid:: Issue Kerberos tickets to your users.
1312 * Configuring DNS for KDC:: Placing the KDC address in DNS is useful.
1313 * Kerberos via TLS:: How to setup Shishi to use TLS.
1314 * Multiple servers:: High availability and load-balancing.
1315 * Developer information:: Writing your own Shisa database backend.
1318 @node Introduction to Shisa
1319 @section Introduction to Shisa
1321 The user database part of Shishi is called Shisa. The Shisa library
1322 is independent of the core Shishi library. Shisa is responsible for
1323 storing the name of your realms, the name of your principals (users),
1324 accounting information for the users (i.e., when each account start to
1325 be valid and when it expire), and the cryptographic keys each user
1326 have. Some Kerberos internal data can also be stored, such as the key
1327 version number, the last dates for when various ticket requests were
1328 made, the cryptographic salt, string-to-key parameters and password
1329 for each user. Not all information need to be stored. For example,
1330 in some situations it is prudent to leave the password field empty, so
1331 that somebody who manage to steal the user database will only be able
1332 to compromise your system, and not other systems were your user may
1333 have re-used the same password. On the other hand, you may already
1334 store the password in your customized database, in which case being
1335 able to change it via the Shisa interface can be useful.
1337 Shisa is a small (a few thousand lines of @acronym{C} code) standalone
1338 library. Shisa does not depend on the Shishi library. Because a user
1339 database with passwords may be useful for other applications as well
1340 (e.g., @acronym{GNU} @acronym{SASL}), it may be separated into its own
1341 project later on. You should keep this in mind, so that you don't
1342 consider writing a Shisa backend for your own database a purely Shishi
1343 specific project. You may, for example, chose to use the Shisa
1344 interface in your own applications to have a simple interface to your
1345 user database. Your experience and feedback is appreciated if you
1346 chose to explore this.
1348 Note that the Shisa database does not expose everything you may want
1349 to know about a user, such as its full human name, telephone number or
1350 even the user's login account name or home directory. It only store
1351 what is needed to authenticate a peer claiming to be an entity. Thus
1352 it does not make sense to replace your current user database or
1353 @file{/etc/passwd} with data derived from the Shisa database.
1354 Instead, it is intended that you write a Shisa backend that export
1355 @i{some} of the information stored in your user database. You may be
1356 able to replace some existing functionality, such as the password
1357 field in @file{/etc/passwd} with a Kerberos PAM module, but there is
1358 no requirement for doing so.
1360 @node Configuring Shisa
1361 @section Configuring Shisa
1363 The configuration file for Shisa is typically stored in
1364 @file{/usr/local/etc/shishi/shisa.conf}. You do not have to configure
1365 this file, the defaults should be acceptable to first-time users. The
1366 file is used to define where you user database reside, and some
1367 options such as making the database read-only or whether errors
1368 detected when accessing the database should be ignored. (The latter
1369 may be useful if the server is a remote @acronym{LDAP} server that may
1370 be unavailable, and you want to fail over to a local copy of the
1373 The default will store the user database using directories and files,
1374 rooted by default in @file{/usr/local/var/shishi}. You may use
1375 standard file permission settings to control access to the directory
1376 hierarchy. It is strongly recommended to restrict access to the
1377 directory. Storing the directory on local storage (i.e., hard disk or
1378 removal media) is recommended. We discourage placing the database on
1379 a network file system, but realize it can be useful in some situations
1380 (@pxref{Multiple servers}).
1382 See the reference manual (@pxref{Shisa Configuration}) for the details
1383 of the configuration file. Again, you are not expected to need to
1384 modify anything unless you are an experienced Shishi administrator.
1387 @section Using Shisa
1389 There is a command line interface to the Shisa library, aptly named
1390 @file{shisa}. You will use this tool to add, remove and change
1391 information stored in the database about realms, principals and keys.
1392 The tool can also be used to ``dump'' all information in the database,
1393 for backup or debugging purposes. (Currently the output format cannot
1394 be read by any tool, but functionality to do this will be added in the
1395 future, possibly as a read-only file-based Shisa database backend.)
1397 The reference manual (@pxref{Parameters for shisa}) explains all
1398 parameters, but here we will give you a walk-through of the typical
1401 Installing Shishi usually create a realm with two principals; one
1402 ticket granting ticket for the realm, and one host key for the server.
1403 This is what you typically need to get started, but it doesn't serve
1404 our purposes. So we start by removing the principals and the realm.
1405 To do that, we need to figure out the name of the realm. The
1406 @samp{--list} or @samp{--dump} parameters can be used for this. (Most
1407 ``long'' parameters, like @samp{--dump}, have shorter names as well,
1408 in this case @samp{-d}, @ref{Parameters for shisa}).
1411 jas@@latte:~$ shisa -d
1415 Current key version 0 (0x0).
1417 Etype aes256-cts-hmac-sha1-96 (0x12, 18).
1418 Salt lattekrbtgt/latte.
1421 Current key version 0 (0x0).
1423 Etype aes256-cts-hmac-sha1-96 (0x12, 18).
1424 Salt lattehost/latte.
1428 The realm names are printed at column 0, the principal names are
1429 indented with one @samp{TAB} character (aka @samp{\t} or ASCII 0x09
1430 Horizontal Tabulation), and the information about each principal are
1431 indented with two @samp{TAB} characters. The above output means that
1432 there is one realm @samp{latte} with two principals;
1433 @samp{krbtgt/latte} (which is used to authenticate Kerberos ticket
1434 requests) and @samp{host/latte} (used to authenticate host-based
1435 applications like Telnet). They were created during @samp{make
1436 install} on a host called @samp{latte}.
1438 If the installation did not create a default database for you, you
1439 might get an error similar to the following.
1442 jas@@latte:~$ shisa -d
1443 shisa: Cannot initialize `file' database backend.
1444 Location `/usr/local/var/shishi' and options `N/A'.
1445 shisa: Initialization failed:
1446 Shisa database could not be opened.
1450 This indicate the database do not exist. For a file database, you can
1451 create it by simply creating the directory, as follows. Note the
1452 access permission change with @samp{chmod}. Typically the @samp{root}
1453 user would own the files, but as these examples demonstrate, setting
1454 up a Kerberos server does not require root access. Indeed, it may be
1455 prudent to run all Shishi applications as a special non-@samp{root}
1456 user, and have all Shishi related files owned by that user, so that
1457 any security vulnerabilities does not lead to a system compromise.
1458 (However, if the user database is stolen, system compromises of other
1459 systems may be possible if you use, e.g., Kerberos Telnet.)
1462 jas@@latte:~$ mkdir /usr/local/var/shishi
1463 jas@@latte:~$ chmod go-rwx /usr/local/var/shishi
1466 Back to the first example, where you have a realm @samp{latte} with
1467 some principals. We want to remove the realm to demonstrate how you
1468 create the realm from scratch. (Of course, you can have more than one
1469 realm in the database, but for this example we assume you want to set
1470 up a realm named the same as Shishi guessed you would name it, so the
1471 existing realm need to be removed first.) The @samp{--remove} (short
1472 form @samp{-r}) parameter is used for this purpose, as follows.
1475 jas@@latte:~$ shisa -r latte host/latte
1476 Removing principal `host/latte@@latte'...
1477 Removing principal `host/latte@@latte'...done
1478 jas@@latte:~$ shisa -r latte krbtgt/latte
1479 Removing principal `krbtgt/latte@@latte'...
1480 Removing principal `krbtgt/latte@@latte'...done
1481 jas@@latte:~$ shisa -r latte
1482 Removing realm `latte'...
1483 Removing realm `latte'...done
1487 You may be asking yourself ``What if the realm has many more
1488 principals?''. If you fear manual labor (or a small @samp{sed}
1489 script, recall the format of @samp{--list}?), don't worry, there is a
1490 @samp{--force} (short form @samp{-f}) flag. Use with care. Here is a
1491 faster way to do the above:
1494 jas@@latte:~$ shisa -r latte -f
1495 Removing principal `krbtgt/latte@@latte'...
1496 Removing principal `krbtgt/latte@@latte'...done
1497 Removing principal `host/latte@@latte'...
1498 Removing principal `host/latte@@latte'...done
1499 Removing realm `latte'...
1500 Removing realm `latte'...done
1504 You should now have a working, but empty, Shisa database. Let's set
1505 up the realm manually, step by step. The first step is to decide on
1506 name for your realm. The full story is explained elsewhere
1507 (@pxref{Realm and Principal Naming}) but the short story is to take
1508 your @acronym{DNS} domain name and translate it to upper case. For
1509 example, if your organization uses @code{example.org} it is a good
1510 idea to use @code{EXAMPLE.ORG} as the name of your Kerberos realm.
1511 We'll use @code{EXAMPLE.ORG} as the realm name in these examples.
1512 Let's create the realm.
1515 jas@@latte:~$ shisa -a EXAMPLE.ORG
1516 Adding realm `EXAMPLE.ORG'...
1517 Adding realm `EXAMPLE.ORG'...done
1521 Currently, there are no properties associated with entire realms. In
1522 the future, it may be possible to set a default realm-wide password
1523 expiry policy or similar. Each realm normally have one principal that
1524 is used for authenticating against the ``ticket granting service'' on
1525 the Kerberos server with a ticket instead of using the password. This
1526 is used by the user when she acquire a ticket for servers. This
1527 principal must look like @samp{krbtgt/REALM} (@pxref{krbtgt,,Name of
1528 the TGS}). Let's create it.
1531 jas@@latte:~$ shisa -a EXAMPLE.ORG krbtgt/EXAMPLE.ORG
1532 Adding principal `krbtgt/EXAMPLE.ORG@@EXAMPLE.ORG'...
1533 Adding principal `krbtgt/EXAMPLE.ORG@@EXAMPLE.ORG'...done
1537 Now that wasn't difficult, although not very satisfying either. What
1538 does adding a principal mean? The name is created, obviously, but it
1539 also mean setting a few values in the database. Let's view the entry
1540 to find out which values.
1543 jas@@latte:~$ shisa -d
1547 Current key version 0 (0x0).
1549 Etype aes256-cts-hmac-sha1-96 (0x12, 18).
1550 Salt EXAMPLE.ORGkrbtgt/EXAMPLE.ORG.
1554 To use host based security services like @acronym{SSH} or Telnet with
1555 Kerberos, each host must have a key shared between the host and the
1556 KDC. The key is typically stored in
1557 @file{/usr/local/etc/shishi/shishi.keys}. We assume your server is
1558 called @samp{mail.example.org} and create the principal. To
1559 illustrate a new parameter, we also set the specific algorithm to use
1560 by using the @samp{--encryption-type} (short form @samp{-E})
1564 jas@@latte:~$ shisa -a EXAMPLE.ORG host/mail.example.org -E des3
1565 Adding principal `host/mail.example.org@@EXAMPLE.ORG'...
1566 Adding principal `host/mail.example.org@@EXAMPLE.ORG'...done
1570 To export the key, there is another Shisa parameter @samp{--keys} that
1571 will print the key in a format that is recognized by Shishi. Let's
1572 use it to print the host key.
1575 jas@@latte:~$ shisa -d --keys EXAMPLE.ORG host/mail.example.org
1577 host/mail.example.org
1579 Current key version 0 (0x0).
1581 Etype des3-cbc-sha1-kd (0x10, 16).
1582 -----BEGIN SHISHI KEY-----
1583 Keytype: 16 (des3-cbc-sha1-kd)
1584 Principal: host/mail.example.org
1587 iQdA8hxdvOUHZNliZJv7noM02rXHV8gq
1588 -----END SHISHI KEY-----
1589 Salt EXAMPLE.ORGhost/mail.example.org.
1593 So to set up the host, simply redirect output to the host key file.
1596 jas@@latte:~$ shisa -d --keys EXAMPLE.ORG \
1597 host/mail.example.org > /usr/local/etc/shishi/shishi.keys
1601 The next logical step is to create a principal for some user, so you
1602 can use your password to get a Ticket Granting Ticket via the
1603 Authentication Service (AS) from the KDC, and then use the Ticket
1604 Granting Service (TGS) from the KDC to get a ticket for a specific
1605 host, and then send that ticket to the host to authenticate yourself.
1606 Creating this end-user principle is slightly different from the
1607 earlier steps, because you want the key to be derived from a password
1608 instead of being a random key. The @samp{--password} parameter
1609 indicate this. This make the tool ask you for the password.
1612 jas@@latte:~$ shisa -a EXAMPLE.ORG simon --password
1613 Password for `simon@@EXAMPLE.ORG':
1614 Adding principal `simon@@EXAMPLE.ORG'...
1615 Adding principal `simon@@EXAMPLE.ORG'...done
1619 The only special thing about this principal now is that it has a
1620 @code{password} field set in the database.
1623 jas@@latte:~$ shisa -d EXAMPLE.ORG simon --keys
1627 Current key version 0 (0x0).
1629 Etype aes256-cts-hmac-sha1-96 (0x12, 18).
1630 -----BEGIN SHISHI KEY-----
1631 Keytype: 18 (aes256-cts-hmac-sha1-96)
1635 Ja7ciNtrAI3gtodLaVDQ5zhcH58ffk0kS5tGAM7ILvM=
1636 -----END SHISHI KEY-----
1637 Salt EXAMPLE.ORGsimon.
1642 You should now be ready to start the KDC, which is explained in the
1643 next section (@pxref{Starting Shishid}), and get tickets as explained
1644 earlier (@pxref{User Manual}).
1646 @node Starting Shishid
1647 @section Starting Shishid
1649 The Shishi server, or Key Distribution Center (KDC), is called
1650 Shishid. Shishid is responsible for listening on UDP and TCP ports
1651 for Kerberos requests. Currently it can handle initial ticket
1652 requests (Authentication Service, or AS), typically authenticated with
1653 keys derived from passwords, and subsequent ticket requests (Ticket
1654 Granting Service, or TGS), typically authenticated with the key
1655 acquired during an AS exchange.
1657 Currently there is very little configuration available, the only
1658 variables are which ports the server should listen on and an optional
1659 user name to @code{setuid} into after successfully listening to the
1662 By default, Shishid listens on the @samp{kerberos} service port
1663 (typically translated to 88 via @file{/etc/services}) on the UDP and
1664 TCP protocols via IPv4 and (if your machine support it) IPv6 on all
1665 interfaces on your machine. Here is a typical startup.
1668 latte:/home/jas/src/shishi# /usr/local/sbin/shishid
1669 Initializing GNUTLS...
1670 Initializing GNUTLS...done
1671 Listening on IPv4:*:kerberos/udp...done
1672 Listening on IPv4:*:kerberos/tcp...done
1673 Listening on IPv6:*:kerberos/udp...failed
1674 socket: Address family not supported by protocol
1675 Listening on IPv6:*:kerberos/tcp...failed
1676 socket: Address family not supported by protocol
1677 Listening on 2 ports...
1680 Running as root is not recommended. Any security problem in shishid
1681 and your host may be compromised. Therefor, we recommend using the
1682 @samp{--setuid} parameter, as follows.
1685 latte:/home/jas/src/shishi# /usr/local/sbin/shishid --setuid=jas
1686 Initializing GNUTLS...
1687 Initializing GNUTLS...done
1688 Listening on IPv4:*:kerberos/udp...done
1689 Listening on IPv4:*:kerberos/tcp...done
1690 Listening on IPv6:*:kerberos/udp...failed
1691 socket: Address family not supported by protocol
1692 Listening on IPv6:*:kerberos/tcp...failed
1693 socket: Address family not supported by protocol
1694 Listening on 2 ports...
1695 User identity set to `jas' (22541)...
1698 An alternative is to run shishid on an alternative port as a
1699 non-privileged user. To continue the example of setting up the
1700 @code{EXAMPLE.ORG} realm as a non-privileged user from the preceding
1701 section, we start the server listen on port 4711 via UDP on IPv4.
1704 jas@@latte:~$ /usr/local/sbin/shishid -l IPv4:*:4711/udp
1705 Initializing GNUTLS...
1706 Initializing GNUTLS...done
1707 Listening on *:4711/tcp...
1708 Listening on 1 ports...
1709 shishid: Starting (GNUTLS `1.0.4')
1710 shishid: Listening on *:4711/tcp socket 4
1713 If you have set up the Shisa database as in the previous example, you
1714 can now acquire tickets as follows.
1717 jas@@latte:~$ shishi -o 'realm-kdc=EXAMPLE.ORG,localhost:4711' \
1719 Enter password for `simon@@EXAMPLE.ORG':
1721 Authtime: Fri Dec 12 01:41:01 2003
1722 Endtime: Fri Dec 12 01:57:41 2003
1723 Server: krbtgt/EXAMPLE.ORG key aes256-cts-hmac-sha1-96 (18)
1724 Ticket key: aes256-cts-hmac-sha1-96 (18) protected by aes256-cts-hmac-sha1-96 (18)
1725 Ticket flags: FORWARDED PROXIABLE RENEWABLE INITIAL (12)
1729 The output from Shishid on a successful invocation would look like:
1732 shishid: Has 131 bytes from *:4711/udp on socket 4
1733 shishid: Processing 131 from *:4711/udp on socket 4
1734 shishid: Trying AS-REQ
1735 shishid: AS-REQ from simon@@EXAMPLE.ORG for krbtgt/EXAMPLE.ORG@@EXAMPLE.ORG
1736 shishid: Matching client etype 18 against user key etype 18
1737 shishid: Have 511 bytes for *:4711/udp on socket 4
1738 shishid: Sending 511 bytes to *:4711/udp socket 4 via UDP
1739 shishid: Listening on *:4711/udp socket 4
1742 You may use the '-v' parameter for Shishid and Shishi to generate more
1743 debugging information.
1745 To illustrate what an application, such as the Shishi patched versions
1746 of @acronym{GNU} lsh or Telnet from @acronym{GNU} InetUtils, would do
1747 when contacting the host @samp{mail.example.org} we illustrate using
1748 the TGS service as well.
1751 jas@@latte:~$ shishi -o 'realm-kdc=EXAMPLE.ORG,localhost:4711' \
1752 simon@@EXAMPLE.ORG host/mail.example.org
1754 Authtime: Fri Dec 12 01:46:54 2003
1755 Endtime: Fri Dec 12 02:03:34 2003
1756 Server: host/mail.example.org key des3-cbc-sha1-kd (16)
1757 Ticket key: des3-cbc-sha1-kd (16) protected by aes256-cts-hmac-sha1-96 (18)
1758 Ticket flags: FORWARDED PROXIABLE (45398796)
1762 This conclude our walk-through of setting up a new Kerberos realm
1763 using Shishi. It is quite likely that one or more steps failed, and
1764 if so we encourage you to debug it and submit a patch, or at least
1765 report it as a problem. Heck, even letting us know if you got this
1766 far would be of interest. @xref{Bug Reports}.
1768 @node Configuring DNS for KDC
1769 @section Configuring DNS for KDC
1771 Making sure the configuration files on all hosts running Shishi
1772 clients include the addresses of your server is tedious. If the
1773 configuration files do not mention the KDC address for a realm, Shishi
1774 will try to look up the information from DNS. In order for Shishi to
1775 find that information, you need to add the information to DNS. For
1776 this to work well, you need to set up a DNS zone with the same name as
1777 your Kerberos realm. The easiest is if you own the publicly visible
1778 DNS name, such as @samp{example.org} if your realm is
1779 @samp{EXAMPLE.ORG}, but you can set up an internal DNS server with the
1780 information for your realm only. If this is done, you do not need to
1781 keep configuration files updated for the KDC addressing information.
1783 @subsection DNS vs. Kerberos - Case Sensitivity of Realm Names
1785 In Kerberos, realm names are case sensitive. While it is strongly
1786 encouraged that all realm names be all upper case this recommendation
1787 has not been adopted by all sites. Some sites use all lower case
1788 names and other use mixed case. DNS on the other hand is case
1789 insensitive for queries but is case preserving for responses to TXT
1790 queries. Since "MYREALM", "myrealm", and "MyRealm" are all different
1791 it is necessary that only one of the possible combinations of upper
1792 and lower case characters be used. This restriction may be lifted in
1793 the future as the DNS naming scheme is expanded to support non-ASCII
1796 @subsection Overview - KDC location information
1798 KDC location information is to be stored using the DNS SRV RR [RFC
1799 2052]. The format of this RR is as follows:
1801 Service.Proto.Realm TTL Class SRV Priority Weight Port Target
1803 The Service name for Kerberos is always "_kerberos".
1805 The Proto can be either "_udp", "_tcp", or "_tls._tcp". If these SRV
1806 records are to be used, a "_udp" record MUST be included. If the
1807 Kerberos implementation supports TCP transport, a "_tcp" record MUST
1808 be included. When using "_tcp" with "_kerberos", this indicates a
1809 "raw" TCP connection without any additional encapsulation. A
1810 "_tls._tcp" record MUST be specified for all Kerberos implementations
1811 that support communication with the KDC across TCP sockets
1812 encapsulated using TLS [RFC2246] (@pxref{STARTTLS protected KDC exchanges}).
1814 The Realm is the Kerberos realm that this record corresponds to.
1816 TTL, Class, SRV, Priority, Weight, and Target have the standard
1817 meaning as defined in RFC 2052.
1819 As per RFC 2052 the Port number should be the value assigned to
1820 "kerberos" by the Internet Assigned Number Authority (88).
1822 @subsection Example - KDC location information
1824 These are DNS records for a Kerberos realm ASDF.COM. It has two
1825 Kerberos servers, kdc1.asdf.com and kdc2.asdf.com. Queries should be
1826 directed to kdc1.asdf.com first as per the specified priority.
1827 Weights are not used in these records.
1830 _kerberos._udp.ASDF.COM. IN SRV 0 0 88 kdc1.asdf.com.
1831 _kerberos._udp.ASDF.COM. IN SRV 1 0 88 kdc2.asdf.com.
1832 _kerberos._tcp.ASDF.COM. IN SRV 0 0 88 kdc1.asdf.com.
1833 _kerberos._tcp.ASDF.COM. IN SRV 1 0 88 kdc2.asdf.com.
1834 _kerberos._tls._tcp.ASDF.COM. IN SRV 0 0 88 kdc1.asdf.com.
1835 _kerberos._tls._tcp.ASDF.COM. IN SRV 1 0 88 kdc2.asdf.com.
1838 @subsection Security considerations
1840 As DNS is deployed today, it is an unsecure service. Thus the infor-
1841 mation returned by it cannot be trusted.
1843 Current practice for REALM to KDC mapping is to use hostnames to
1844 indicate KDC hosts (stored in some implementation-dependent location,
1845 but generally a local config file). These hostnames are vulnerable
1846 to the standard set of DNS attacks (denial of service, spoofed
1847 entries, etc). The design of the Kerberos protocol limits attacks of
1848 this sort to denial of service. However, the use of SRV records does
1849 not change this attack in any way. They have the same vulnerabilities
1850 that already exist in the common practice of using hostnames for
1853 Implementations SHOULD provide a way of specifying this information
1854 locally without the use of DNS. However, to make this feature
1855 worthwhile a lack of any configuration information on a client should
1856 be interpretted as permission to use DNS.
1858 @node Kerberos via TLS
1859 @section Kerberos via TLS
1864 If Shishi is built with support for GNUTLS, the messages exchanged
1865 between clients and Shishid can be protected with TLS. TLS is only
1866 available over TCP connections. A full discussion of the features TLS
1867 have is out of scope here, but in short it means the communication is
1868 integrity and privacy protected, and that users can use OpenPGP, X.509
1869 or SRP (i.e., any mechanism supported by TLS) to authenticate
1870 themselves to the Kerberos server. For details on the implementation,
1871 @xref{STARTTLS protected KDC exchanges}.
1873 @subsection Setting up TLS resume
1876 Resuming earlier TLS session is supported and enabled by default.
1877 This improves the speed of the TLS handshake, because results from
1878 earlier negotiations can be re-used. Currently the TLS resume
1879 database is stored in memory (in constract to storing it on disk), in
1880 both the client and in the server. Because the server typically runs
1881 for a long time, this is not a problem for that side. The client is
1882 typically not a long-running process though; the client usually is
1883 invoked as part of applications like @samp{telnet} or @samp{login}.
1884 However, because each use of the client library typically result in a
1885 ticket, which is stored on disk and re-used by later processes, this
1886 is likely not a serious problem because the number of different
1887 tickets required by a user is usually quite small. For the client,
1888 TLS resume is typically only useful when you perform an initial
1889 authentication (using a password) followed by a ticket request for a
1890 service, in the same process.
1892 You can configure the server, @samp{shishid} to never use TLS resume,
1893 or to increase or decrease the number of distinct TLS connections that
1894 can be resumed before they are garbage collected, see the
1895 @samp{--resume-limit} parameter (@pxref{Parameters for shishid}).
1897 @subsection Setting up Anonymous TLS
1898 @cindex anonymous tls
1899 @cindex Diffie Hellman key exchange
1901 Anonymous TLS is the simplest to set up and use. In fact, only the
1902 client need to be informed that your KDC support TLS. This can be
1903 done in the configuration file with the @samp{/tls} parameter for
1904 @samp{kdc-realm} (@pxref{realm-kdc,, Shishi Configuration}), or by
1905 placing the KDC address in DNS using the @samp{_tls} SRV record
1906 (@pxref{Configuring DNS for KDC}).
1908 Let's start Shishid, listening on a TCP socket. TLS require TCP. TCP
1909 sockets are automatically upgraded to TLS if the client request it.
1912 jas@@latte:~$ /usr/local/sbin/shishid -l IPv4:*:4711/tcp
1913 Initializing GNUTLS...done
1914 Listening on IPv4:*:4711/tcp...
1915 Listening on 1 ports...
1916 shishid: Starting (GNUTLS `1.0.4')
1917 shishid: Listening on IPv4:*:4711/tcp socket 4
1920 Let's use the client to talk with it, using TLS.
1923 jas@@latte:~$ shishi -o 'realm-kdc=EXAMPLE.ORG,localhost:4711/tls \
1925 Enter password for `simon@@EXAMPLE.ORG':
1927 Authtime: Tue Dec 16 05:20:47 2003
1928 Endtime: Tue Dec 16 05:37:27 2003
1929 Server: krbtgt/EXAMPLE.ORG key aes256-cts-hmac-sha1-96 (18)
1930 Ticket key: aes256-cts-hmac-sha1-96 (18) protected by aes256-cts-hmac-sha1-96 (18)
1931 Ticket flags: FORWARDED PROXIABLE (12)
1935 On success, the server will print the following debug information.
1938 shishid: Accepted socket 6 from socket 4 as IPv4:*:4711/tcp peer 127.0.0.1
1939 shishid: Listening on IPv4:*:4711/tcp socket 4
1940 shishid: Listening on IPv4:*:4711/tcp peer 127.0.0.1 socket 6
1941 shishid: Has 4 bytes from IPv4:*:4711/tcp peer 127.0.0.1 on socket 6
1942 shishid: Trying STARTTLS
1943 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
1944 shishid: TLS anonymous authentication with 1024 bit Diffie-Hellman
1945 shishid: Listening on IPv4:*:4711/tcp socket 4
1946 shishid: Listening on IPv4:*:4711/tcp peer 127.0.0.1 socket 6
1947 shishid: Has 131 bytes from IPv4:*:4711/tcp peer 127.0.0.1 on socket 6
1948 shishid: Processing 131 from IPv4:*:4711/tcp peer 127.0.0.1 on socket 6
1949 shishid: Trying AS-REQ
1950 shishid: AS-REQ from simon@@EXAMPLE.ORG for krbtgt/EXAMPLE.ORG@@EXAMPLE.ORG
1951 shishid: Matching client etype 18 against user key etype 18
1952 shishid: Have 511 bytes for IPv4:*:4711/tcp peer 127.0.0.1 on socket 6
1953 shishid: Sending 511 bytes to IPv4:*:4711/tcp peer 127.0.0.1 socket 6 via TLS
1954 shishid: Listening on IPv4:*:4711/tcp socket 4
1955 shishid: Listening on IPv4:*:4711/tcp peer 127.0.0.1 socket 6
1956 shishid: Peer IPv4:*:4711/tcp peer 127.0.0.1 disconnected on socket 6
1957 shishid: Closing IPv4:*:4711/tcp peer 127.0.0.1 socket 6
1958 shishid: Listening on IPv4:*:4711/tcp socket 4
1961 @subsection Setting up X.509 authenticated TLS
1962 @cindex X.509 authentication
1963 @cindex authenticated tls
1964 @cindex client authentication
1965 @cindex server authentication
1966 @cindex certificate authority (@acronym{CA})
1968 Setting up X.509 authentication is slightly more complicated than
1969 anonymous authentication. You need a X.509 certificate authority
1970 (@acronym{CA}) that can generate certificates for your Kerberos server
1971 and Kerberos clients. It is often easiest to setup the @acronym{CA}
1972 yourself. Managing a @acronym{CA} can be a daunting task, and we only
1973 give the bare essentials to get things up and running. We suggest
1974 that you study the relevant literature. As a first step beyond this
1975 introduction, you may wish to explore more secure forms of key storage
1976 than storing them unencrypted on disk.
1978 The following three sections describe how you create the @acronym{CA},
1979 KDC certificate, and client certificates. You can use any tool you
1980 like for this task, as long as they generate X.509 (PKIX) certificates
1981 in PEM format and RSA keys in PKCS#1 format. Here we use
1982 @file{certtool} that come with @acronym{GNUTLS}, which is widely
1983 available. We conclude by discussing how you use these certificates
1984 in the KDC and in the Shishi client.
1986 @subsubsection Create a Kerberos Certificate Authority
1988 First create a @acronym{CA} key.
1991 jas@@latte:~$ certtool --generate-privkey \
1992 --outfile /usr/local/etc/shishi/shishi.key
1993 Generating a private key...
1994 Generating a 1024 bit RSA private key...
1998 Then create the @acronym{CA} certificate. Use whatever details you
2002 jas@@latte:~$ certtool --generate-self-signed \
2003 --load-privkey /usr/local/etc/shishi/shishi.key \
2004 --outfile /usr/local/etc/shishi/shishi.cert
2005 Generating a self signed certificate...
2006 Please enter the details of the certificate's distinguished name. \
2007 Just press enter to ignore a field.
2008 Country name (2 chars): SE
2009 Organization name: Shishi Example CA
2010 Organizational unit name:
2012 State or province name:
2014 This field should not be used in new certificates.
2016 Enter the certificate's serial number (decimal): 0
2019 Activation/Expiration time.
2020 The generated certificate will expire in (days): 180
2024 Does the certificate belong to an authority? (Y/N): y
2025 Is this a web server certificate? (Y/N): n
2026 Enter the e-mail of the subject of the certificate:
2029 X.509 certificate info:
2032 Serial Number (hex): 00
2034 Not Before: Sun Dec 21 10:59:00 2003
2035 Not After: Fri Jun 18 11:59:00 2004
2036 Subject: C=SE,O=Shishi Example CA,CN=CA
2037 Subject Public Key Info:
2038 Public Key Algorithm: RSA
2041 Basic Constraints: (critical)
2044 Is the above information ok? (Y/N): y
2047 Signing certificate...
2051 @subsubsection Create a Kerberos KDC Certificate
2053 First create the key for the KDC.
2056 jas@@latte:~$ certtool --generate-privkey \
2057 --outfile /usr/local/etc/shishi/shishid.key
2058 Generating a private key...
2059 Generating a 1024 bit RSA private key...
2063 Then create actual KDC certificate, signed by the @acronym{CA}
2064 certificate created in the previous step.
2067 jas@@latte:~$ certtool --generate-certificate \
2068 --load-ca-certificate /usr/local/etc/shishi/shishi.cert \
2069 --load-ca-privkey /usr/local/etc/shishi/shishi.key \
2070 --load-privkey /usr/local/etc/shishi/shishid.key \
2071 --outfile /usr/local/etc/shishi/shishid.cert
2072 Generating a signed certificate...
2073 Loading CA's private key...
2074 Loading CA's certificate...
2075 Please enter the details of the certificate's distinguished name. \
2076 Just press enter to ignore a field.
2077 Country name (2 chars): SE
2078 Organization name: Shishi Example KDC
2079 Organizational unit name:
2081 State or province name:
2083 This field should not be used in new certificates.
2085 Enter the certificate's serial number (decimal): 0
2088 Activation/Expiration time.
2089 The generated certificate will expire in (days): 180
2093 Does the certificate belong to an authority? (Y/N): n
2094 Is this a web server certificate? (Y/N): n
2095 Enter the e-mail of the subject of the certificate:
2098 X.509 certificate info:
2101 Serial Number (hex): 00
2103 Not Before: Sun Dec 21 11:02:00 2003
2104 Not After: Fri Jun 18 12:02:00 2004
2105 Subject: C=SE,O=Shishi Example KDC,CN=KDC
2106 Subject Public Key Info:
2107 Public Key Algorithm: RSA
2110 Basic Constraints: (critical)
2113 Is the above information ok? (Y/N): y
2116 Signing certificate...
2120 @subsubsection Create a Kerberos Client Certificate
2122 First create the key for the client.
2125 jas@@latte:~$ certtool --generate-privkey \
2126 --outfile ~/.shishi/client.key
2127 Generating a private key...
2128 Generating a 1024 bit RSA private key...
2132 Then create the client certificate, signed by the @acronym{CA}. An
2133 alternative would be to have the KDC sign the client certificates.
2136 jas@@latte:~$ certtool --generate-certificate \
2137 --load-ca-certificate /usr/local/etc/shishi/shishi.cert \
2138 --load-ca-privkey /usr/local/etc/shishi/shishi.key \
2139 --load-privkey ~/.shishi/client.key \
2140 --outfile ~/.shishi/client.certs
2141 Generating a signed certificate...
2142 Loading CA's private key...
2143 Loading CA's certificate...
2144 Please enter the details of the certificate's distinguished name. \
2145 Just press enter to ignore a field.
2146 Country name (2 chars): SE
2147 Organization name: Shishi Example Client
2148 Organizational unit name:
2150 State or province name:
2152 This field should not be used in new certificates.
2154 Enter the certificate's serial number (decimal): 0
2157 Activation/Expiration time.
2158 The generated certificate will expire in (days): 180
2162 Does the certificate belong to an authority? (Y/N): n
2163 Is this a web server certificate? (Y/N): n
2164 Enter the e-mail of the subject of the certificate:
2167 X.509 certificate info:
2170 Serial Number (hex): 00
2172 Not Before: Sun Dec 21 11:04:00 2003
2173 Not After: Fri Jun 18 12:04:00 2004
2174 Subject: C=SE,O=Shishi Example Client,CN=Client
2175 Subject Public Key Info:
2176 Public Key Algorithm: RSA
2179 Basic Constraints: (critical)
2182 Is the above information ok? (Y/N): y
2185 Signing certificate...
2189 @subsubsection Starting KDC with X.509 authentication support
2191 The KDC need the @acronym{CA} certificate (to verify client
2192 certificates) and the server certificate and key (to authenticate
2193 itself to the clients). See elsewhere (@pxref{Parameters for
2194 shishid}) for the entire description of the parameters.
2197 jas@@latte:~$ shishid -l *:4711/tcp \
2198 --x509cafile /usr/local/etc/shishi/shishi.cert \
2199 --x509certfile /usr/local/etc/shishi/shishid.cert \
2200 --x509keyfile /usr/local/etc/shishi/shishid.key
2201 Initializing GNUTLS...
2203 Loaded server certificate/key...
2204 Generating Diffie-Hellman parameters...
2205 Initializing GNUTLS...done
2206 Listening on *:4711/tcp...
2207 Listening on 1 ports...
2208 shishid: Starting (GNUTLS `1.0.4')
2209 shishid: Listening on *:4711/tcp socket 4
2212 Then acquire tickets as usual. In case you wonder how shishi finds
2213 the client certificate and key, the filenames used above when
2214 generating the client certificates happen to be the default filenames
2215 for these files. So it pick them up automatically.
2218 jas@@latte:~$ shishi -o 'realm-kdc=EXAMPLE.ORG,localhost:4711/tls' \
2220 Enter password for `simon@@EXAMPLE.ORG':
2222 Authtime: Sun Dec 21 11:15:47 2003
2223 Endtime: Sun Dec 21 11:32:27 2003
2224 Server: krbtgt/EXAMPLE.ORG key aes256-cts-hmac-sha1-96 (18)
2225 Ticket key: aes256-cts-hmac-sha1-96 (18) protected by aes256-cts-hmac-sha1-96 (18)
2226 Ticket flags: FORWARDED PROXIABLE RENEWABLE HWAUTHENT TRANSITEDPOLICYCHECKED OKASDELEGATE (12)
2230 Here is what the server would print.
2233 shishid: Accepted socket 6 from socket 4 as *:4711/tcp peer 127.0.0.1
2234 shishid: Listening on *:4711/tcp socket 4
2235 shishid: Listening on *:4711/tcp peer 127.0.0.1 socket 6
2236 shishid: Has 4 bytes from *:4711/tcp peer 127.0.0.1 on socket 6
2237 shishid: Trying STARTTLS
2238 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
2239 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
2240 shishid: Listening on *:4711/tcp socket 4
2241 shishid: Listening on *:4711/tcp peer 127.0.0.1 socket 6
2242 shishid: Has 131 bytes from *:4711/tcp peer 127.0.0.1 on socket 6
2243 shishid: Processing 131 from *:4711/tcp peer 127.0.0.1 on socket 6
2244 shishid: Trying AS-REQ
2245 shishid: AS-REQ from simon@@EXAMPLE.ORG for krbtgt/EXAMPLE.ORG@@EXAMPLE.ORG
2246 shishid: Matching client etype 18 against user key etype 18
2247 shishid: Have 511 bytes for *:4711/tcp peer 127.0.0.1 on socket 6
2248 shishid: Sending 511 bytes to *:4711/tcp peer 127.0.0.1 socket 6 via TLS
2249 shishid: Listening on *:4711/tcp socket 4
2250 shishid: Listening on *:4711/tcp peer 127.0.0.1 socket 6
2251 shishid: Peer *:4711/tcp peer 127.0.0.1 disconnected on socket 6
2252 shishid: Closing *:4711/tcp peer 127.0.0.1 socket 6
2253 shishid: Listening on *:4711/tcp socket 4
2257 @node Multiple servers
2258 @section Multiple servers
2259 @cindex remote databases
2266 Setting up multiple servers is as easy as replicating the user
2267 database. Since the default @samp{file} user database is stored in
2268 the normal file system, you can use any common tools to replicate a
2269 file system. Network file system like @acronym{NFS} (properly secured
2270 by, e.g., a point-to-point symmetrically encrypted @acronym{IPSEC}
2271 connection) and file synchronizing tools like @samp{rsync} are typical
2274 @cindex master server
2275 @cindex secondary server
2276 The secondary server should be configured just like the master server.
2277 If you use the @samp{file} database over @acronym{NFS} you do not have
2278 to make any modifications. If you use, e.g., a cron job to
2279 @samp{rsync} the directory every hour or so, you may want to add a
2280 @samp{--read-only} flag to the Shisa @samp{db} definition
2281 (@pxref{Shisa Configuration}). That way, nobody will be lured into
2282 creating or changing information in the database on the secondary
2283 server, which only would be overwritten during the next
2287 db --read-only file /usr/local/var/backup-shishi
2290 @cindex concurrent writers
2291 The @samp{file} database is designed so it doesn't require file
2292 locking in the file system, which may be unreliable in some network
2293 file systems or implementations. It is also designed so that multiple
2294 concurrent readers and writers may access the database without causing
2297 @strong{Warning:} The last paragraph is currently not completely
2298 accurate. There may be race conditions with concurrent writers. None
2299 should cause infinite loops or data loss. However, unexpected results
2300 might occur if two writers try to update information about a principal
2303 If you use a remote @acronym{LDAP} server or @acronym{SQL} database to
2304 store the user database, and access it via a Shisa backend, you have
2305 make sure your Shisa backend handle concurrent writers properly. If
2306 you use a modern @acronym{SQL} database, this probably is not a
2307 concern. If it is a problem, you may be able to work around it by
2308 implementing some kind of synchronization or semaphore mechanism. If
2309 all else sounds too complicated, you can set up the secondary servers
2310 as @samp{--read-only} servers, although you will lose some
2311 functionality (like changing passwords via the secondary server, or
2312 updating timestamps when the last ticket request occurred).
2314 One function that is of particular use for users with remote databases
2315 (be it @acronym{LDAP} or @acronym{SQL}) is the ``database override''
2316 feature. Using this you can have the security critical principals
2317 (such as the ticket granting ticket) stored on local file system
2318 storage, but use the remote database for user principals. Of course,
2319 you must keep the local file system storage synchronized between all
2320 servers, as before. Here is an example configuration.
2323 db --read-only file /var/local/master
2324 db ldap kdc.example.org ca=/etc/shisa/kdc-ca.pem
2327 This instruct the Shisa library to access the two databases
2328 sequentially, for each query using the first database that know about
2329 the requested principal. If you put the @samp{krbtgt/REALM} principal
2330 in the local @samp{file} database, this will override the
2331 @acronym{LDAP} interface. Naturally, you can have as many @samp{db}
2332 definition lines as you wish.
2334 @cindex High Availability
2335 Users with remote databases can also investigate a so called @i{High
2336 Availability} mode. This is useful if you wish to have your Kerberos
2337 servers be able to continue to operate even when the remote database
2338 is offline. This is achieved via the @samp{--ignore-errors} flag in
2339 the database definition. Here is a sample configuration.
2342 db --ignore-errors ldap kdc.example.org ca=/etc/shisa/kdc-ca.pem
2343 db --read-only file /var/cache/ldap-copy
2346 This instruct the Shisa library to try the @acronym{LDAP} backend
2347 first, but if it fails, instead of returning an error, continue to try
2348 the operation on a read only local @samp{file} based database. Of
2349 course, write requests will still fail, but it may be better than
2350 halting the server completely. To make this work, you first need to
2351 set up a cron job on a, say, hourly basis, to make a copy of the
2352 remote database and store it in the local file database. That way,
2353 when the remote server goes away, fairly current information will
2354 still be available locally.
2357 If you also wish to experiment with read-write fail over, here is an
2358 idea for the configuration.
2361 db --ignore-errors ldap kdc.example.org ca=/etc/shisa/kdc-ca.pem
2362 db --ignore-errors --read-only file /var/cache/ldap-copy
2363 db file /var/cache/local-updates
2366 This is similar to the previous, but it will ignore errors reading and
2367 writing from the first two databases, ultimately causing write
2368 attempts to end up in the final @samp{file} based database. Of
2369 course, you would need to create tools to feed back any local updates
2370 made while the remote server was down. It may also be necessary to
2371 create a special backend for this purpose, which can auto create
2372 principals that are used.
2374 We finish with an example that demonstrate all the ideas presented.
2377 db --read-only file /var/local/master
2378 db --ignore-errors ldap kdc.example.org ca=/etc/shisa/kdc-ca.pem
2379 db --ignore-errors --read-only file /var/cache/ldap-copy
2380 db file /var/cache/local-updates
2383 @node Developer information
2384 @section Developer information
2386 The Programming API for Shisa is described below (@pxref{Kerberos
2387 Database Functions}); this section is about extending Shisa, and
2388 consequently Shishi, to use your own user database system. You may
2389 want to store your Kerberos user information on an LDAP database
2390 server, for example.
2392 Adding a new backend is straight forward. You need to implement the
2393 backend API function set, add the list of API functions to
2394 @file{db/db.c} and possibly also add any library dependencies to the
2397 The simplest way to write a new backend is to start from the existing
2398 @samp{file} based database, in @file{db/file.c}, and modify the entry
2401 Note that the current backend API will likely change before it is
2402 frozen. We may describe it in detail here when it has matured.
2403 However, currently it is similar to the external Shisa API
2404 (@pxref{Kerberos Database Functions}).
2406 There should be no need to modify anything else in the Shisa library,
2407 and certainly not in the Shishi library or the @file{shishid} server.
2409 Naturally, we would appreciate if you would send us your new backend,
2410 if you believe it is generally useful (@pxref{Bug Reports}).
2412 @c **********************************************************
2413 @c **************** Reference Manual **********************
2414 @c **********************************************************
2415 @node Reference Manual
2416 @chapter Reference Manual
2418 This chapter discuss the underlying assumptions of Kerberos, contain a
2419 glossary to Kerberos concepts, give you background information on
2420 choosing realm and principal names, and describe all parameters and
2421 configuration file syntaxes for the Shishi tools.
2424 * Environmental Assumptions:: Kerberos 5 assumptions about your system.
2425 * Glossary of terms:: Glossary of Kerberos related terminology.
2426 * Realm and Principal Naming:: How to name your realm and principals.
2427 * Shishi Configuration:: Explains the Core Shishi configuration file.
2428 * Shisa Configuration:: Explains the Shisa database definition file.
2429 * Parameters for shishi:: Command line parameters for 'shishi'.
2430 * Parameters for shishid:: Command line parameters for 'shishid'.
2431 * Parameters for shisa:: Command line parameters for 'shisa'.
2432 * Environment variables:: Overriding compile-time defaults at run-time.
2433 * Date input formats:: Details of the understood date formats.
2436 @node Environmental Assumptions
2437 @section Environmental Assumptions
2439 Kerberos imposes a few assumptions on the environment in which it can
2445 "Denial of service" attacks are not solved with Kerberos. There
2446 are places in the protocols where an intruder can prevent an
2447 application from participating in the proper authentication steps.
2448 Detection and solution of such attacks (some of which can appear
2449 to be not-uncommon "normal" failure modes for the system) is
2450 usually best left to the human administrators and users.
2452 Principals MUST keep their secret keys secret. If an intruder
2453 somehow steals a principal's key, it will be able to masquerade as
2454 that principal or impersonate any server to the legitimate
2457 "Password guessing" attacks are not solved by Kerberos. If a user
2458 chooses a poor password, it is possible for an attacker to
2459 successfully mount an offline dictionary attack by repeatedly
2460 attempting to decrypt, with successive entries from a dictionary,
2461 messages obtained which are encrypted under a key derived from the
2464 Each host on the network MUST have a clock which is "loosely
2465 synchronized" to the time of the other hosts; this synchronization
2466 is used to reduce the bookkeeping needs of application servers
2467 when they do replay detection. The degree of "looseness" can be
2468 configured on a per-server basis, but is typically on the order of
2469 5 minutes. If the clocks are synchronized over the network, the
2470 clock synchronization protocol MUST itself be secured from network
2473 Principal identifiers are not recycled on a short-term basis. A
2474 typical mode of access control will use access control lists
2475 (ACLs) to grant permissions to particular principals. If a stale
2476 ACL entry remains for a deleted principal and the principal
2477 identifier is reused, the new principal will inherit rights
2478 specified in the stale ACL entry. By not re-using principal
2479 identifiers, the danger of inadvertent access is removed.
2482 @node Glossary of terms
2483 @section Glossary of terms
2486 @item Authentication
2487 @cindex Authentication
2488 Verifying the claimed identity of a principal.
2490 @item Authentication header
2491 @cindex Authentication header
2492 A record containing a Ticket and an Authenticator to be presented
2493 to a server as part of the authentication process.
2495 @item Authentication path
2496 @cindex Authentication path
2497 A sequence of intermediate realms transited in the authentication
2498 process when communicating from one realm to another.
2501 @cindex Authenticator
2502 A record containing information that can be shown to have been
2503 recently generated using the session key known only by the client
2507 @cindex Authorization
2508 The process of determining whether a client may use a service,
2509 which objects the client is allowed to access, and the type of
2510 access allowed for each.
2514 A token that grants the bearer permission to access an object or
2515 service. In Kerberos, this might be a ticket whose use is
2516 restricted by the contents of the authorization data field, but
2517 which lists no network addresses, together with the session key
2518 necessary to use the ticket.
2522 The output of an encryption function. Encryption transforms
2523 plaintext into ciphertext.
2527 A process that makes use of a network service on behalf of a user.
2528 Note that in some cases a Server may itself be a client of some
2529 other server (e.g. a print server may be a client of a file
2534 A ticket plus the secret session key necessary to successfully use
2535 that ticket in an authentication exchange.
2537 @item Encryption Type (etype)
2538 @cindex Encryption Type (etype)
2539 When associated with encrypted data, an encryption type identifies
2540 the algorithm used to encrypt the data and is used to select the
2541 appropriate algorithm for decrypting the data. Encryption type
2542 tags are communicated in other messages to enumerate algorithms
2543 that are desired, supported, preferred, or allowed to be used for
2544 encryption of data between parties. This preference is combined
2545 with local information and policy to select an algorithm to be
2550 Key Distribution Center, a network service that supplies tickets
2551 and temporary session keys; or an instance of that service or the
2552 host on which it runs. The KDC services both initial ticket and
2553 ticket-granting ticket requests. The initial ticket portion is
2554 sometimes referred to as the Authentication Server (or service).
2555 The ticket-granting ticket portion is sometimes referred to as the
2556 ticket-granting server (or service).
2560 The name given to the Project Athena's authentication service, the
2561 protocol used by that service, or the code used to implement the
2562 authentication service. The name is adopted from the three-headed
2563 dog which guards Hades.
2565 @item Key Version Number (kvno)
2566 @cindex Key Version Number (kvno)
2567 A tag associated with encrypted data identifies which key was used
2568 for encryption when a long lived key associated with a principal
2569 changes over time. It is used during the transition to a new key
2570 so that the party decrypting a message can tell whether the data
2571 was encrypted using the old or the new key.
2575 The input to an encryption function or the output of a decryption
2576 function. Decryption transforms ciphertext into plaintext.
2580 A named client or server entity that participates in a network
2581 communication, with one name that is considered canonical.
2583 @item Principal identifier
2584 @cindex Principal identifier
2585 The canonical name used to uniquely identify each different
2590 To encipher a record containing several fields in such a way that
2591 the fields cannot be individually replaced without either
2592 knowledge of the encryption key or leaving evidence of tampering.
2596 An encryption key shared by a principal and the KDC, distributed
2597 outside the bounds of the system, with a long lifetime. In the
2598 case of a human user's principal, the secret key MAY be derived
2603 A particular Principal which provides a resource to network
2604 clients. The server is sometimes referred to as the Application
2609 A resource provided to network clients; often provided by more
2610 than one server (for example, remote file service).
2614 A temporary encryption key used between two principals, with a
2615 lifetime limited to the duration of a single login "session". In
2616 the Kerberos system, a session key is generated by the KDC. The
2617 session key is distinct from the sub-session key, described next..
2619 @item Sub-session key
2620 @cindex Sub-session key
2621 A temporary encryption key used between two principals, selected
2622 and exchanged by the principals using the session key, and with a
2623 lifetime limited to the duration of a single association. The sub-
2624 session key is also referred to as the subkey.
2628 @cindex Kerberos Ticket
2629 A record that helps a client authenticate itself to a server; it
2630 contains the client's identity, a session key, a timestamp, and
2631 other information, all sealed using the server's secret key. It
2632 only serves to authenticate a client when presented along with a
2633 fresh Authenticator.
2636 @node Realm and Principal Naming
2637 @section Realm and Principal Naming
2639 This section contains the discussion on naming realms and principals
2640 from the Kerberos specification.
2642 @subsection Realm Names
2644 Although realm names are encoded as GeneralStrings and although a
2645 realm can technically select any name it chooses, interoperability
2646 across realm boundaries requires agreement on how realm names are to
2647 be assigned, and what information they imply.
2649 To enforce these conventions, each realm MUST conform to the
2650 conventions itself, and it MUST require that any realms with which
2651 inter-realm keys are shared also conform to the conventions and
2652 require the same from its neighbors.
2654 Kerberos realm names are case sensitive. Realm names that differ only
2655 in the case of the characters are not equivalent. There are presently
2656 three styles of realm names: domain, X500, and other. Examples of
2660 domain: ATHENA.MIT.EDU
2662 other: NAMETYPE:rest/of.name=without-restrictions
2665 Domain syle realm names MUST look like domain names: they consist of
2666 components separated by periods (.) and they contain neither colons
2667 (:) nor slashes (/). Though domain names themselves are case
2668 insensitive, in order for realms to match, the case must match as
2669 well. When establishing a new realm name based on an internet domain
2670 name it is recommended by convention that the characters be converted
2673 X.500 names contain an equal (=) and cannot contain a colon (:)
2674 before the equal. The realm names for X.500 names will be string
2675 representations of the names with components separated by slashes.
2676 Leading and trailing slashes will not be included. Note that the
2677 slash separator is consistent with Kerberos implementations based on
2678 RFC1510, but it is different from the separator recommended in
2681 Names that fall into the other category MUST begin with a prefix that
2682 contains no equal (=) or period (.) and the prefix MUST be followed
2683 by a colon (:) and the rest of the name. All prefixes must be
2684 assigned before they may be used. Presently none are assigned.
2686 The reserved category includes strings which do not fall into the
2687 first three categories. All names in this category are reserved. It
2688 is unlikely that names will be assigned to this category unless there
2689 is a very strong argument for not using the 'other' category.
2691 These rules guarantee that there will be no conflicts between the
2692 various name styles. The following additional constraints apply to
2693 the assignment of realm names in the domain and X.500 categories: the
2694 name of a realm for the domain or X.500 formats must either be used
2695 by the organization owning (to whom it was assigned) an Internet
2696 domain name or X.500 name, or in the case that no such names are
2697 registered, authority to use a realm name MAY be derived from the
2698 authority of the parent realm. For example, if there is no domain
2699 name for E40.MIT.EDU, then the administrator of the MIT.EDU realm can
2700 authorize the creation of a realm with that name.
2702 This is acceptable because the organization to which the parent is
2703 assigned is presumably the organization authorized to assign names to
2704 its children in the X.500 and domain name systems as well. If the
2705 parent assigns a realm name without also registering it in the domain
2706 name or X.500 hierarchy, it is the parent's responsibility to make
2707 sure that there will not in the future exist a name identical to the
2708 realm name of the child unless it is assigned to the same entity as
2711 @subsection Principal Names
2713 As was the case for realm names, conventions are needed to ensure
2714 that all agree on what information is implied by a principal name.
2715 The name-type field that is part of the principal name indicates the
2716 kind of information implied by the name. The name-type SHOULD be
2717 treated only as a hint to interpreting the meaning of a name. It is
2718 not significant when checking for equivalence. Principal names that
2719 differ only in the name-type identify the same principal. The name
2720 type does not partition the name space. Ignoring the name type, no
2721 two names can be the same (i.e. at least one of the components, or
2722 the realm, MUST be different). The following name types are defined:
2725 name-type value meaning
2727 NT-UNKNOWN 0 Name type not known
2728 NT-PRINCIPAL 1 Just the name of the principal as in DCE, or for users
2729 NT-SRV-INST 2 Service and other unique instance (krbtgt)
2730 NT-SRV-HST 3 Service with host name as instance (telnet, rcommands)
2731 NT-SRV-XHST 4 Service with host as remaining components
2733 NT-X500-PRINCIPAL 6 Encoded X.509 Distingished name [RFC 2253]
2734 NT-SMTP-NAME 7 Name in form of SMTP email name (e.g. user@@foo.com)
2735 NT-ENTERPRISE 10 Enterprise name - may be mapped to principal name
2738 When a name implies no information other than its uniqueness at a
2739 particular time the name type PRINCIPAL SHOULD be used. The principal
2740 name type SHOULD be used for users, and it might also be used for a
2741 unique server. If the name is a unique machine generated ID that is
2742 guaranteed never to be reassigned then the name type of UID SHOULD be
2743 used (note that it is generally a bad idea to reassign names of any
2744 type since stale entries might remain in access control lists).
2746 If the first component of a name identifies a service and the
2747 remaining components identify an instance of the service in a server
2748 specified manner, then the name type of SRV-INST SHOULD be used. An
2749 example of this name type is the Kerberos ticket-granting service
2750 whose name has a first component of krbtgt and a second component
2751 identifying the realm for which the ticket is valid.
2753 If the first component of a name identifies a service and there is a
2754 single component following the service name identifying the instance
2755 as the host on which the server is running, then the name type SRV-
2756 HST SHOULD be used. This type is typically used for Internet services
2757 such as telnet and the Berkeley R commands. If the separate
2758 components of the host name appear as successive components following
2759 the name of the service, then the name type SRV-XHST SHOULD be used.
2760 This type might be used to identify servers on hosts with X.500 names
2761 where the slash (/) might otherwise be ambiguous.
2763 A name type of NT-X500-PRINCIPAL SHOULD be used when a name from an
2764 X.509 certificate is translated into a Kerberos name. The encoding of
2765 the X.509 name as a Kerberos principal shall conform to the encoding
2766 rules specified in RFC 2253.
2768 A name type of SMTP allows a name to be of a form that resembles a
2769 SMTP email name. This name, including an "@@" and a domain name, is
2770 used as the one component of the principal name.
2772 A name type of UNKNOWN SHOULD be used when the form of the name is
2773 not known. When comparing names, a name of type UNKNOWN will match
2774 principals authenticated with names of any type. A principal
2775 authenticated with a name of type UNKNOWN, however, will only match
2776 other names of type UNKNOWN.
2778 Names of any type with an initial component of 'krbtgt' are reserved
2779 for the Kerberos ticket granting service. @xref{krbtgt,, Name of the
2780 TGS}, for the form of such names.
2782 @subsubsection Name of server principals
2784 The principal identifier for a server on a host will generally be
2785 composed of two parts: (1) the realm of the KDC with which the server
2786 is registered, and (2) a two-component name of type NT-SRV-HST if the
2787 host name is an Internet domain name or a multi-component name of
2788 type NT-SRV-XHST if the name of the host is of a form such as X.500
2789 that allows slash (/) separators. The first component of the two- or
2790 multi-component name will identify the service and the latter
2791 components will identify the host. Where the name of the host is not
2792 case sensitive (for example, with Internet domain names) the name of
2793 the host MUST be lower case. If specified by the application protocol
2794 for services such as telnet and the Berkeley R commands which run
2795 with system privileges, the first component MAY be the string 'host'
2796 instead of a service specific identifier.
2798 @subsubsection Name of the TGS
2801 The principal identifier of the ticket-granting service shall be
2802 composed of three parts: (1) the realm of the KDC issuing the TGS
2803 ticket (2) a two-part name of type NT-SRV-INST, with the first part
2804 "krbtgt" and the second part the name of the realm which will accept
2805 the ticket-granting ticket. For example, a ticket-granting ticket
2806 issued by the ATHENA.MIT.EDU realm to be used to get tickets from the
2807 ATHENA.MIT.EDU KDC has a principal identifier of "ATHENA.MIT.EDU"
2808 (realm), ("krbtgt", "ATHENA.MIT.EDU") (name). A ticket-granting
2809 ticket issued by the ATHENA.MIT.EDU realm to be used to get tickets
2810 from the MIT.EDU realm has a principal identifier of "ATHENA.MIT.EDU"
2811 (realm), ("krbtgt", "MIT.EDU") (name).
2813 @subsection Choosing a principal with which to communicate
2815 The Kerberos protocol provides the means for verifying (subject to
2816 the assumptions in @ref{Environmental Assumptions}) that the entity with which one communicates
2817 is the same entity that was registered with the KDC using the claimed
2818 identity (principal name). It is still necessary to determine whether
2819 that identity corresponds to the entity with which one intends to
2822 When appropriate data has been exchanged in advance, this
2823 determination may be performed syntactically by the application based
2824 on the application protocol specification, information provided by
2825 the user, and configuration files. For example, the server principal
2826 name (including realm) for a telnet server might be derived from the
2827 user specified host name (from the telnet command line), the "host/"
2828 prefix specified in the application protocol specification, and a
2829 mapping to a Kerberos realm derived syntactically from the domain
2830 part of the specified hostname and information from the local
2831 Kerberos realms database.
2833 One can also rely on trusted third parties to make this
2834 determination, but only when the data obtained from the third party
2835 is suitably integrity protected while resident on the third party
2836 server and when transmitted. Thus, for example, one should not rely
2837 on an unprotected domain name system record to map a host alias to
2838 the primary name of a server, accepting the primary name as the party
2839 one intends to contact, since an attacker can modify the mapping and
2840 impersonate the party with which one intended to communicate.
2842 Implementations of Kerberos and protocols based on Kerberos MUST NOT
2843 use insecure DNS queries to canonicalize the hostname components of
2844 the service principal names. In an environment without secure name
2845 service, application authors MAY append a statically configured
2846 domain name to unqualified hostnames before passing the name to the
2847 security mechanisms, but should do no more than that. Secure name
2848 service facilities, if available, might be trusted for hostname
2849 canonicalization, but such canonicalization by the client SHOULD NOT
2850 be required by KDC implementations.
2852 Implementation note: Many current implementations do some degree of
2853 canonicalization of the provided service name, often using DNS even
2854 though it creates security problems. However there is no consistency
2855 among implementations about whether the service name is case folded
2856 to lower case or whether reverse resolution is used. To maximize
2857 interoperability and security, applications SHOULD provide security
2858 mechanisms with names which result from folding the user-entered name
2859 to lower case, without performing any other modifications or
2862 @subsection Principal Name Form
2864 Principal names consist of a sequence of strings, which is often
2865 tedious to parse. Therefor, Shishi often uses a ``printed'' form of
2866 principal which embed the entire principal name string sequence, and
2867 optionally also the realm, into one string. The format is taken from
2868 the Kerberos 5 @acronym{GSS-API} mechanism (@acronym{RFC} 1964).
2870 The elements included within this name representation are as follows,
2871 proceeding from the beginning of the string:
2875 One or more principal name components; if more than one
2876 principal name component is included, the components are
2877 separated by `/`. Arbitrary octets may be included within
2878 principal name components, with the following constraints and
2879 special considerations:
2882 Any occurrence of the characters `@@` or `/` within a
2883 name component must be immediately preceded by the `\`
2884 quoting character, to prevent interpretation as a component
2887 The ASCII newline, tab, backspace, and null characters
2888 may occur directly within the component or may be
2889 represented, respectively, by `\n`, `\t`, `\b`, or `\0`.
2891 If the `\` quoting character occurs outside the contexts
2892 described in (1a) and (1b) above, the following character is
2893 interpreted literally. As a special case, this allows the
2894 doubled representation `\\` to represent a single occurrence
2895 of the quoting character.
2897 An occurrence of the `\` quoting character as the last
2898 character of a component is illegal.
2901 Optionally, a `@@` character, signifying that a realm name
2902 immediately follows. If no realm name element is included, the
2903 local realm name is assumed. The `/` , `:`, and null characters
2904 may not occur within a realm name; the `@@`, newline, tab, and
2905 backspace characters may be included using the quoting
2906 conventions described in (1a), (1b), and (1c) above.
2909 @node Shishi Configuration
2910 @section Shishi Configuration
2911 @cindex configuration file
2913 The valid configuration file tokens are described here. The user
2914 configuration file is typically located in
2915 @file{~/.shishi/shishi.conf} (compare @samp{shishi
2916 --configuration-file}) and the system configuration is typically
2917 located in @file{/usr/local/etc/shishi/shishi.conf} (compare
2918 @samp{shishi --system-configuration-file}). If the first non white
2919 space character of a line is a '#', the line is ignored. Empty lines
2922 All tokens are valid in both the system and the user configuration
2923 files, and have the same meaning. However, as the system file is
2924 supposed to apply to all users on a system, it would not make sense to
2925 use some tokens in that file. For example, the
2926 @samp{default-principal} is rarely useful in a system configuration
2929 @subsection @samp{default-realm}
2930 Specify the default realm, by default the hostname of the host is
2934 default-realm JOSEFSSON.ORG
2937 @subsection @samp{default-principal}
2939 Specify the default principal, by default the login username is
2943 default-principal jas
2946 @subsection @samp{client-kdc-etypes}
2948 Specify which encryption types client asks server to respond in during
2949 AS/TGS exchanges. List valid encryption types, in preference order.
2950 Supported algorithms include aes256-cts-hmac-sha1-96,
2951 aes128-cts-hmac-sha1-96, des3-cbc-sha1-kd, des-cbc-md5, des-cbc-md4,
2952 des-cbc-crc and null. This option also indicates which encryption
2953 types are accepted by the client when receiving the response. Note
2954 that the preference order is not cryptographically protected, so a man
2955 in the middle can modify the order without being detected. Thus, only
2956 specify encryption types you trust completely here. The default only
2957 includes aes256-cts-hmac-sha1-96, as suggested by RFC1510bis. E.g.,
2960 client-kdc-etypes=aes256-cts-hmac-sha1-96 des3-cbc-sha1-kd des-cbc-md5
2963 @subsection @samp{verbose}, @samp{verbose-asn1}, @samp{verbose-noise}, @samp{verbose-crypto}, @samp{verbose-crypto-noise}
2965 Enable verbose library messages. E.g.,
2972 @subsection @samp{realm-kdc}
2975 Specify KDC addresses for realms. Value is
2976 @samp{REALM,KDCADDRESS[/PROTOCOL][,KDCADDRESS[/PROTOCOL]...]}.
2978 KDCADDRESS is the hostname or IP address of KDC.
2980 Optional PROTOCOL is udp for UDP, tcp for TCP, and TLS for TLS
2981 connections. By default UDP is tried first, and TCP used as a
2982 fallback if the KRB_ERR_RESPONSE_TOO_BIG error is received.
2984 If not specified, Shishi tries to locate the KDC using SRV RRs,
2985 which is recommended. This option should normally only be
2986 used during experiments, or to access badly maintained realms.
2989 realm-kdc=JOSEFSSON.ORG,ristretto.josefsson.org
2992 @subsection @samp{server-realm}
2994 Specify realm for servers. Value is
2995 @samp{REALM,SERVERREGEXP[,SERVERREGEXP...]}.
2997 SERVERREGEXP is a regular expression matching servers in the realm.
2998 The first match is used. E.g.,
3001 server-realm=JOSEFSSON.ORG,.josefsson.org
3004 Note: currently not used.
3006 @subsection @samp{kdc-timeout}, @samp{kdc-retries}
3008 How long shishi waits for a response from a KDC before continuing to
3009 next KDC for realm. The default is 5 seconds. E.g.,
3015 How many times shishi sends a request to a KDC before giving up. The
3016 default is 3 times. E.g.,
3022 @subsection @samp{stringprocess}
3024 How username and passwords entered from the terminal, or taken from
3025 the command line, are processed.
3027 "none": no processing is used.
3029 "stringprep": convert from locale charset to UTF-8 and process using
3030 experimental RFC 1510 stringprep profile.
3032 It can also be a string indicating a character set supported by
3033 iconv via libstringprep, in which case data is converted from locale
3034 charset into the indicated character set. E.g., UTF-8, ISO-8859-1,
3035 KOI-8, EBCDIC-IS-FRISS are supported on GNU systems. On some systems
3036 you can use "locale -m" to list available character sets. By default,
3037 the "none" setting is used which is consistent with RFC 1510 that is
3038 silent on the issue. In practice, however, converting to UTF-8
3039 improves interoperability.
3047 @subsection @samp{ticket-life}
3048 Specify default ticket life time.
3050 The string can be in almost any common format. It can contain month
3051 names, time zones, `am' and `pm', `yesterday', `ago', `next', etc.
3052 @xref{Date input formats}, for the long story.
3054 As an extra feature, if the time specified by your string correspond
3055 to a time during the last 24 hours, an extra day is added to it. This
3056 allows you to specify relative times such as "17:00" to always mean
3057 the next 17:00, even if your system clock happens to be 17:30.
3059 The default is 8 hours.
3064 #ticket-life=8 hours
3069 @subsection @samp{renew-life}
3071 Specify how long a renewable ticket should remain renewable.
3073 See ticket-life for the syntax. The extra feature that handles
3074 negative values within the last 2 hours is not active here.
3076 The default is 7 days.
3082 #renew-life=friday 17:00
3086 @node Shisa Configuration
3087 @section Shisa Configuration
3088 @cindex database definition
3089 @cindex specifying user database
3090 @cindex user database definition
3092 The configuration file for Shisa is typically stored in
3093 @file{/usr/local/etc/shishi/shisa.conf}. If the first non white space
3094 character of a line is a '#', the line is ignored. Empty lines are
3097 @subsection @samp{db}
3099 Currently the only configuration options available is the @code{db}
3100 token that define the databases to use. The syntax is:
3103 db [OPTIONS] <TYPE> [LOCATION] [PARAMETERS ...]
3106 Specify the data sources for Kerberos 5 data. Multiple entries,
3107 even of the same data source type, are allowed. The data sources
3108 are accessed in the same sequence as they are defined here. If an
3109 entry is found in one data source, it will be used for the
3110 operations, without searching the remaining data sources. Valid
3114 --read-only No data is written to this data source.
3115 --ignore-errors Ignore failures in this backend.
3118 The default (when the configuration file is empty) uses one "file"
3119 data source (see below), but for a larger installation you may want to
3120 combine several data sources. Here is an example.
3123 db --read-only file /var/local/master
3124 db --ignore-errors ldap kdc.example.org ca=/etc/shisa/kdc-ca.pem
3125 db --read-only file /var/cache/ldap-copy
3128 This demonstrate how you can store critical principals on local disk
3129 (the first entry, /var/local/master) that will always be found without
3130 looking in the LDAP directory. The critical principals could be,
3131 e.g., krbtgt/EXAMPLE.ORG. The second entry denote a LDAP server that
3132 could hold user principals. As you can see, Shisa will not let the
3133 caller know about errors with the LDAP source (they will be logged,
3134 however). Instead, if for instance the LDAP server has crashed, Shisa
3135 would continue and read from the /var/cache/ldap-copy file source.
3136 That file source may have been set up to contain a copy of the data in
3137 the LDAP server, perhaps made on an hourly basis, so that your server
3138 will be able to serve recent data even in case of a crash. Any
3139 updates or passwords change requests will however not be possible
3140 while the LDAP server is inaccessible, to reduce the problem of
3141 synchronizing data back into the LDAP server once it is online again.
3143 Currently only the "file" data source is supported, and denote a
3144 data source that use the standard file system for storage.
3146 Valid syntaxes for the "file" database:
3156 db file /usr/share/shishi read-only
3159 If no @samp{db} tokens are present, the default will be:
3162 db file /usr/local/var/shishi
3165 @node Parameters for shishi
3166 @section Parameters for shishi
3168 If no command is given, Shishi try to make sure you have a ticket
3169 granting ticket for the default realm, and then display it.
3171 Mandatory arguments to long options are mandatory for short options
3175 Usage: shishi [OPTIONS]... [CLIENT [SERVER]]...
3177 -h, --help Print help and exit
3178 -V, --version Print version and exit
3181 -d, --destroy Destroy tickets in local cache,
3182 limited by any --client-name or
3183 --server-name. (default=off)
3184 -l, --list List tickets in local cache, limited
3185 by any --client-name and
3186 --server-name. (default=off)
3187 -r, --renew Renew ticket. Use --server-name to
3188 specify ticket, default is the
3189 most recent renewable ticket
3190 granting ticket for the default
3191 realm. (default=off)
3194 --forwardable Get a forwardable ticket, i.e., one
3195 that can be used to get forwarded
3196 tickets. (default=off)
3197 --forwarded Get a forwarded ticket. (default=
3199 --proxiable Get a proxiable ticket, i.e., one
3200 that can be used to get proxy
3201 tickets. (default=off)
3202 --proxy Get a proxy ticket. (default=off)
3203 --renewable Get a renewable ticket. (default=
3207 --client-name=NAME Client name. Default is login
3209 -E, --encryption-type=ETYPE,[ETYPE...] Encryption types to use. ETYPE is
3210 either registered name or integer.
3211 Valid values include 'aes128',
3212 'aes256', 'aes' (same as
3213 'aes256'), '3des', 'des-md5',
3214 'des-md4', 'des-crc', 'des' (same
3215 as 'des-md5'), and 'arcfour'.
3216 -e, --endtime=STRING Specify when ticket validity should
3217 expire. The time syntax may be
3218 relative (to the start time), such
3219 as '20 hours', or absolute, such
3220 as '2001-02-03 04:05:06 CET'. The
3221 default is 8 hours after the start
3223 --realm=STRING Set default realm.
3224 --renew-till=STRING Specify renewable life of ticket.
3225 Implies --renewable. Accepts same
3226 time syntax as --endtime. If
3227 --renewable is specified, the
3228 default is 1 week after the start
3230 --server-name=NAME Server name. Default is
3231 'krbtgt/REALM' where REALM is
3233 -s, --starttime=STRING Specify when ticket should start to
3234 be valid. Accepts same time
3235 syntax as --endtime. The default
3236 is to become valid immediately.
3237 --ticket-granter=NAME Service name in ticket to use for
3238 authenticating request. Only for
3240 'krbtgt/REALM@@REALM' where REALM
3244 --configuration-file=FILE Read user configuration from FILE.
3245 -c, --ticket-file=FILE Read tickets from FILE.
3246 -o, --library-options=STRING Parse STRING as a configuration file
3248 -q, --quiet Don't produce any diagnostic output.
3250 --system-configuration-file=FILE Read system configuration from FILE.
3251 --ticket-write-file=FILE Write tickets from FILE. Default is
3252 to write them back to where they
3254 -v, --verbose Produce verbose output.
3258 @node Parameters for shishid
3259 @section Parameters for shishid
3261 If no parameters are specified, @samp{shishid} listens on the defaults
3262 interfaces and answers incoming requests using the keys in the default
3265 Mandatory arguments to long options are mandatory for short options
3269 Usage: shishid [OPTIONS]...
3271 -h, --help Print help and exit
3272 -V, --version Print version and exit
3275 -l, --listen=[FAMILY:]ADDR:PORT/TYPE Sockets to listen for queries on.
3276 Family is `IPv4' or `IPv6', if
3277 absent the family is decided by
3278 gethostbyname(ADDR). An address of
3279 `*' indicates all addresses on the
3280 local host. The default is
3281 `IPv4:*:kerberos/udp,
3282 IPv4:*:kerberos/tcp,
3283 IPv6:*:kerberos/udp,
3284 IPv6:*:kerberos/tcp'.
3285 -u, --setuid=NAME After binding socket, set user
3289 --x509cafile=FILE X.509 certificate authorities used to
3290 verify client certificates, in PEM
3292 --x509certfile=FILE X.509 server certificate, in PEM
3294 --x509crlfile=FILE X.509 certificate revocation list to
3295 check for revoked client
3296 certificates, in PEM format.
3297 --x509keyfile=FILE X.509 server certificate key, in PEM
3299 --resume-limit=SHORT Keep track of up to this many TLS
3300 sessions for resume purposes (0 to
3301 disable TLS resume). (default=`50')
3304 -c, --configuration-file=FILE Use specified configuration file.
3305 -v, --verbose Produce verbose output.
3307 -q, --quiet Don't produce any diagnostic output.
3311 @node Parameters for shisa
3312 @section Parameters for shisa
3314 The purpose of @samp{shisa} is to manipulate information stored in the
3315 Kerberos 5 database used by Shishi.
3317 Mandatory arguments to long options are mandatory for short options
3321 Usage: shisa [OPTIONS]... [REALM [PRINCIPAL]]...
3323 -h, --help Print help and exit
3324 -V, --version Print version and exit
3327 -a, --add Add realm or principal to database.
3328 -d, --dump Dump entries in database.
3329 -n, --key-add Add new key to a principal in database.
3330 --key-remove Remove a key from a principal in
3332 -l, --list List entries in database.
3333 -m, --modify Modify principal entry in database.
3334 -r, --remove Remove realm or principal from database.
3337 -f, --force Allow removal of non-empty realms.
3339 --enabled Only dump or list enabled principals.
3341 --disabled Only dump or list disabled principals.
3343 --keys Print cryptographic key and password in
3344 hostkey format. (default=off)
3347 -E, --encryption-type=STRING Override default key encryption type.
3348 Valid values include 'aes128',
3349 'aes256', 'aes' (same as 'aes256'),
3350 '3des', 'des-md5', 'des-md4',
3351 'des-crc', 'des' (same as 'des-md5'),
3353 --key-version=NUMBER Version of key.
3354 --password[=STRING] Derive key from this password.
3355 --random Use a random key. (default)
3356 --salt=STRING Use specified salt for deriving key.
3357 Defaults to concatenation of realm and
3358 (unwrapped) principal name.
3359 --string-to-key-parameter=HEX Encryption algorithm specific parameter
3360 for password derivation. Currently
3361 only the AES algorithm can utilize
3362 this, where it is interpreted as the
3363 iteration count of the PKCS#5 PBKDF2
3367 -c, --configuration-file=FILE Use specified configuration file.
3368 -o, --library-options=STRING Parse string as configuration file
3370 -v, --verbose Produce verbose output.
3372 -q, --quiet Don't produce any diagnostic output.
3376 @node Environment variables
3377 @section Environment variables
3379 A few of the compile-time defaults may be overridden at run-time by
3380 using environment variables. The following variables are supported.
3384 @item @env{SHISHI_CONFIG}
3385 Specify the location of the default system configuration file. Used
3386 by the Shishi library. If not specified, the default is specified at
3387 compile-time and is usually @file{$prefix/etc/shishi.conf}.
3389 @item @env{SHISHI_HOME}
3390 Specify the user specific directory for configuration files, ticket
3391 cache, etc. Used by the Shishi library. If not specified, it is
3392 computed as @code{$HOME/.shishi}.
3394 @item @env{SHISHI_USER}
3395 Specify the default principal user name. Used by the Shishi library.
3396 If not specified, it is taken from the environment variable
3399 @item @env{SHISHI_TICKETS}
3400 Specify the file name of the ticket cache. Used by the Shishi
3401 library. If not specified, it will be @code{$SHISHI_HOME/tickets}, or
3402 @code{$HOME/.shishi/tickets} if @code{$SHISHI_HOME} is not specified.
3407 @include getdate.texi
3410 @c **********************************************************
3411 @c *************** Programming Manual *********************
3412 @c **********************************************************
3413 @node Programming Manual
3414 @chapter Programming Manual
3415 @cindex Application Programming Interface (API)
3417 This chapter describes all the publicly available functions in the
3421 * Preparation:: What you should do before using the library.
3422 * Initialization Functions:: Creating library handle, configuration file.
3423 * Ticket Set Functions:: High-level ticket management functions.
3424 * AP-REQ and AP-REP Functions:: Client/Server authentication functions.
3425 * SAFE and PRIV Functions:: Client/Server session data functions.
3426 * Ticket Functions:: Medium-level ticket manipulation functions.
3427 * AS Functions:: Medium-level initial authentication functions.
3428 * TGS Functions:: Medium-level authentication functions.
3429 * Ticket (ASN.1) Functions:: Low-level Ticket functions.
3430 * AS/TGS Functions:: Low-level KDC functions; AS and TGS.
3431 * Authenticator Functions:: Low-level authenticator functions.
3432 * KRB-ERROR Functions:: Low-level KRB-ERROR functions.
3433 * Cryptographic Functions:: Low-level cryptographic functions.
3434 * X.509 Functions:: Utility functions for X.509 support.
3435 * Utility Functions:: Utilities for use in the global context.
3436 * ASN.1 Functions:: Perform low-level ASN.1 manipulations.
3437 * Error Handling:: Error codes and such.
3438 * Examples:: Example code.
3439 * Kerberos Database Functions:: The Shisa generic database interface.
3440 * Generic Security Service:: If you want to use the GSS API instead.
3444 @section Preparation
3446 To use `Libshishi', you have to perform some changes to your sources
3447 and the build system. The necessary changes are small and explained
3448 in the following sections. At the end of this chapter, it is
3449 described how the library is initialized, and how the requirements of
3450 the library are verified.
3452 A faster way to find out how to adapt your application for use with
3453 `Libshishi' may be to look at the examples at the end of this manual
3460 * Building the source::
3467 All interfaces (data types and functions) of the library are defined
3468 in the header file `shishi.h'. You must include this in all programs
3469 using the library, either directly or through some other header file,
3476 The name space of `Libshishi' is @code{shishi_*} for function names,
3477 @code{Shishi*} for data types and @code{SHISHI_*} for other symbols. In
3478 addition the same name prefixes with one prepended underscore are
3479 reserved for internal use and should never be used by an application.
3481 @node Initialization
3482 @subsection Initialization
3484 `Libshishi' must be initialized before it can be used. The library is
3485 initialized by calling @code{shishi_init} (@pxref{Initialization
3486 Functions}). The resources allocated by the initialization process
3487 can be released if the application no longer has a need to call
3488 `Libshishi' functions, this is done by calling @code{shishi_done}.
3490 In order to take advantage of the internationalisation features in
3491 `Libshishi', such as translated error messages, the application must
3492 set the current locale using @code{setlocale} before initializing
3496 @subsection Version Check
3498 It is often desirable to check that the version of `Libshishi' used is
3499 indeed one which fits all requirements. Even with binary
3500 compatibility new features may have been introduced but due to problem
3501 with the dynamic linker an old version is actually used. So you may
3502 want to check that the version is okay right after program startup.
3504 @include texi/version.c.texi
3506 The normal way to use the function is to put something similar to the
3507 following early in your @code{main}:
3510 if (!shishi_check_version (SHISHI_VERSION))
3512 printf ("shishi_check_version failed:\n"
3513 "Header file incompatible with shared library.\n");
3518 @node Building the source
3519 @subsection Building the source
3520 @cindex Compiling your application
3522 If you want to compile a source file including the `shishi.h' header
3523 file, you must make sure that the compiler can find it in the
3524 directory hierarchy. This is accomplished by adding the path to the
3525 directory in which the header file is located to the compilers include
3526 file search path (via the @option{-I} option).
3528 However, the path to the include file is determined at the time the
3529 source is configured. To solve this problem, `Libshishi' uses the
3530 external package @command{pkg-config} that knows the path to the
3531 include file and other configuration options. The options that need
3532 to be added to the compiler invocation at compile time are output by
3533 the @option{--cflags} option to @command{pkg-config shishi}. The
3534 following example shows how it can be used at the command line:
3537 gcc -c foo.c `pkg-config shishi --cflags`
3540 Adding the output of @samp{pkg-config shishi --cflags} to the
3541 compilers command line will ensure that the compiler can find the
3542 `Libshishi' header file.
3544 A similar problem occurs when linking the program with the library.
3545 Again, the compiler has to find the library files. For this to work,
3546 the path to the library files has to be added to the library search path
3547 (via the @option{-L} option). For this, the option @option{--libs} to
3548 @command{pkg-config shishi} can be used. For convenience, this option
3549 also outputs all other options that are required to link the program
3550 with the `Libshishi' libararies (in particular, the @samp{-lshishi}
3551 option). The example shows how to link @file{foo.o} with the `Libshishi'
3552 library to a program @command{foo}.
3555 gcc -o foo foo.o `pkg-config shishi --libs`
3558 Of course you can also combine both examples to a single command by
3559 specifying both options to @command{pkg-config}:
3562 gcc -o foo foo.c `pkg-config shishi --cflags --libs`
3565 @node Autoconf tests
3566 @subsection Autoconf tests
3567 @cindex Autoconf tests
3568 @cindex Configure tests
3570 If you work on a project that uses Autoconf (@pxref{top, GNU
3571 Autoconf,, autoconf}) to help find installed libraries, the
3572 suggestions in the previous section are not the entire story. There
3573 are a few methods to detect and incorporate Shishi into your Autoconf
3574 based package. The preferred approach, is to use Libtool in your
3575 project, and use the normal Autoconf header file and library tests.
3577 @subsubsection Autoconf test via @samp{pkg-config}
3579 If your audience is a typical GNU/Linux desktop, you can often assume
3580 they have the @samp{pkg-config} tool installed, in which you can use
3581 its Autoconf M4 macro to find and set up your package for use with
3582 Shishi. The following illustrate this scenario.
3585 AC_ARG_ENABLE(kerberos_v5,
3586 AC_HELP_STRING([--disable-kerberos_v5],
3587 [don't use the KERBEROS_V5 mechanism]),
3588 kerberos_v5=$enableval)
3589 if test "$kerberos_v5" != "no" ; then
3590 PKG_CHECK_MODULES(SHISHI, shishi >= 0.0.0,
3593 if test "$kerberos_v5" != "yes" ; then
3595 AC_MSG_WARN([shishi not found, disabling Kerberos 5])
3598 AC_DEFINE(USE_KERBEROS_V5, 1,
3599 [Define to 1 if you want Kerberos 5.])
3602 AC_MSG_CHECKING([if Kerberos 5 should be used])
3603 AC_MSG_RESULT($kerberos_v5)
3606 @subsubsection Standalone Autoconf test using Libtool
3608 If your package uses Libtool(@pxref{top, GNU Libtool,, libtool}), you
3609 can use the normal Autoconf tests to find the Shishi library and rely
3610 on the Libtool dependency tracking to include the proper dependency
3611 libraries (e.g., Libidn). The following illustrate this scenario.
3614 AC_CHECK_HEADER(shishi.h,
3615 AC_CHECK_LIB(shishi, shishi_check_version,
3616 [kerberos5=yes AC_SUBST(SHISHI_LIBS, -lshishi)],
3619 AC_ARG_ENABLE(kerberos5,
3620 AC_HELP_STRING([--disable-kerberos5],
3621 [disable Kerberos 5 unconditionally]),
3622 kerberos5=$enableval)
3623 if test "$kerberos5" != "no" ; then
3624 AC_DEFINE(USE_KERBEROS_V5, 1,
3625 [Define to 1 if you want Kerberos 5.])
3627 AC_MSG_WARN([Shishi not found, disabling Kerberos 5])
3629 AC_MSG_CHECKING([if Kerberos 5 should be used])
3630 AC_MSG_RESULT($kerberos5)
3633 @subsubsection Standalone Autoconf test
3635 If your package does not use Libtool, as well as detecting the Shishi
3636 library as in the previous case, you must also detect whatever
3637 dependencies Shishi requires to work (e.g., libidn). Since the
3638 dependencies are in a state of flux, we do not provide an example and
3639 we do not recommend this approach, unless you are experienced
3642 @node Initialization Functions
3643 @section Initialization Functions
3645 @include texi/init.c.texi
3646 @include texi/cfg.c.texi
3649 @node Ticket Set Functions
3650 @section Ticket Set Functions
3652 A ``ticket set'' is, as the name implies, a collection of tickets.
3653 Functions are provided to read tickets from file into a ticket set, to
3654 query number of tickets in the set, to extract a given ticket from the
3655 set, to search the ticket set for tickets matching certain criterium,
3656 to write the ticket set to a file, etc. High level functions for
3657 performing a initial authentication (@pxref{AS Functions}) or
3658 subsequent authentication (@pxref{TGS Functions}) and storing the new
3659 ticket in the ticket set are also provided.
3661 To manipulate each individual ticket, @xref{Ticket Functions}. For
3662 low-level ASN.1 manipulation see @xref{Ticket (ASN.1) Functions}.
3664 @include texi/tkts.c.texi
3667 @node AP-REQ and AP-REP Functions
3668 @section AP-REQ and AP-REP Functions
3670 The ``AP-REQ'' and ``AP-REP'' are ASN.1 structures used by application
3671 client and servers to prove to each other who they are. The
3672 structures contain auxilliary information, together with an
3673 authenticator (@pxref{Authenticator Functions}) which is the real
3674 cryptographic proof. The following illustrates the AP-REQ and AP-REP
3678 AP-REQ ::= [APPLICATION 14] SEQUENCE {
3679 pvno [0] INTEGER (5),
3680 msg-type [1] INTEGER (14),
3681 ap-options [2] APOptions,
3683 authenticator [4] EncryptedData {Authenticator,
3684 { keyuse-pa-TGSReq-authenticator
3685 | keyuse-APReq-authenticator }}
3688 AP-REP ::= [APPLICATION 15] SEQUENCE {
3689 pvno [0] INTEGER (5),
3690 msg-type [1] INTEGER (15),
3691 enc-part [2] EncryptedData {EncAPRepPart,
3692 { keyuse-EncAPRepPart }}
3695 EncAPRepPart ::= [APPLICATION 27] SEQUENCE {
3696 ctime [0] KerberosTime,
3697 cusec [1] Microseconds,
3698 subkey [2] EncryptionKey OPTIONAL,
3699 seq-number [3] UInt32 OPTIONAL
3703 @include texi/ap.c.texi
3704 @include texi/apreq.c.texi
3705 @include texi/aprep.c.texi
3706 @include texi/encapreppart.c.texi
3709 @node SAFE and PRIV Functions
3710 @section SAFE and PRIV Functions
3712 The ``KRB-SAFE'' is an ASN.1 structure used by application client and
3713 servers to exchange integrity protected data. The integrity
3714 protection is keyed, usually with a key agreed on via the AP exchange
3715 (@pxref{AP-REQ and AP-REP Functions}). The following illustrates the
3716 KRB-SAFE ASN.1 structure.
3719 KRB-SAFE ::= [APPLICATION 20] SEQUENCE {
3720 pvno [0] INTEGER (5),
3721 msg-type [1] INTEGER (20),
3722 safe-body [2] KRB-SAFE-BODY,
3726 KRB-SAFE-BODY ::= SEQUENCE {
3727 user-data [0] OCTET STRING,
3728 timestamp [1] KerberosTime OPTIONAL,
3729 usec [2] Microseconds OPTIONAL,
3730 seq-number [3] UInt32 OPTIONAL,
3731 s-address [4] HostAddress,
3732 r-address [5] HostAddress OPTIONAL
3736 @include texi/safe.c.texi
3738 The ``KRB-PRIV'' is an ASN.1 structure used by application client and
3739 servers to exchange confidential data. The confidentiality is keyed,
3740 usually with a key agreed on via the AP exchange (@pxref{AP-REQ and
3741 AP-REP Functions}). The following illustrates the KRB-PRIV ASN.1
3745 KRB-PRIV ::= [APPLICATION 21] SEQUENCE {
3746 pvno [0] INTEGER (5),
3747 msg-type [1] INTEGER (21),
3748 -- NOTE: there is no [2] tag
3749 enc-part [3] EncryptedData -- EncKrbPrivPart
3752 EncKrbPrivPart ::= [APPLICATION 28] SEQUENCE {
3753 user-data [0] OCTET STRING,
3754 timestamp [1] KerberosTime OPTIONAL,
3755 usec [2] Microseconds OPTIONAL,
3756 seq-number [3] UInt32 OPTIONAL,
3757 s-address [4] HostAddress -- sender's addr --,
3758 r-address [5] HostAddress OPTIONAL -- recip's addr
3762 @include texi/priv.c.texi
3765 @node Ticket Functions
3766 @section Ticket Functions
3768 A Ticket is an ASN.1 structured that can be used to authenticate the
3769 holder to services. It contain an encrypted part, which the ticket
3770 holder cannot see, but can be encrypted by the service, and various
3771 information about the user and service, including an encryption key to
3772 use for the connection. @xref{Ticket (ASN.1) Functions}, for more
3773 details on the ASN.1 structure of a ticket.
3775 @include texi/tkt.c.texi
3779 @section AS Functions
3781 The Authentication Service (AS) is used to get an initial ticket using
3782 e.g. your password. The following illustrates the AS-REQ and AS-REP
3788 AS-REQ ::= KDC-REQ {10}
3790 KDC-REQ {INTEGER:tagnum} ::= [APPLICATION tagnum] SEQUENCE {
3791 pvno [1] INTEGER (5) -- first tag is [1], not [0] --,
3792 msg-type [2] INTEGER (tagnum),
3793 padata [3] SEQUENCE OF PA-DATA OPTIONAL,
3794 req-body [4] KDC-REQ-BODY
3797 KDC-REQ-BODY ::= SEQUENCE {
3798 kdc-options [0] KDCOptions,
3799 cname [1] PrincipalName OPTIONAL
3800 -- Used only in AS-REQ --,
3803 -- Also client's in AS-REQ --,
3804 sname [3] PrincipalName OPTIONAL,
3805 from [4] KerberosTime OPTIONAL,
3806 till [5] KerberosTime,
3807 rtime [6] KerberosTime OPTIONAL,
3809 etype [8] SEQUENCE OF Int32 -- EncryptionType
3810 -- in preference order --,
3811 addresses [9] HostAddresses OPTIONAL,
3812 enc-authorization-data [10] EncryptedData {
3814 { keyuse-TGSReqAuthData-sesskey
3815 | keyuse-TGSReqAuthData-subkey }
3817 additional-tickets [11] SEQUENCE OF Ticket OPTIONAL
3822 AS-REP ::= KDC-REP {11, EncASRepPart, {keyuse-EncASRepPart}}
3824 KDC-REP {INTEGER:tagnum,
3826 UInt32:KeyUsages} ::= [APPLICATION tagnum] SEQUENCE {
3827 pvno [0] INTEGER (5),
3828 msg-type [1] INTEGER (tagnum),
3829 padata [2] SEQUENCE OF PA-DATA OPTIONAL,
3831 cname [4] PrincipalName,
3833 enc-part [6] EncryptedData {TypeToEncrypt, KeyUsages}
3836 EncASRepPart ::= [APPLICATION 25] EncKDCRepPart
3838 EncKDCRepPart ::= SEQUENCE {
3839 key [0] EncryptionKey,
3840 last-req [1] LastReq,
3842 key-expiration [3] KerberosTime OPTIONAL,
3843 flags [4] TicketFlags,
3844 authtime [5] KerberosTime,
3845 starttime [6] KerberosTime OPTIONAL,
3846 endtime [7] KerberosTime,
3847 renew-till [8] KerberosTime OPTIONAL,
3849 sname [10] PrincipalName,
3850 caddr [11] HostAddresses OPTIONAL
3854 @include texi/as.c.texi
3858 @section TGS Functions
3860 The Ticket Granting Service (TGS) is used to get subsequent tickets,
3861 authenticated by other tickets (so called ticket granting tickets).
3862 The following illustrates the TGS-REQ and TGS-REP ASN.1 structures.
3867 TGS-REQ ::= KDC-REQ {12}
3869 KDC-REQ {INTEGER:tagnum} ::= [APPLICATION tagnum] SEQUENCE {
3870 pvno [1] INTEGER (5) -- first tag is [1], not [0] --,
3871 msg-type [2] INTEGER (tagnum),
3872 padata [3] SEQUENCE OF PA-DATA OPTIONAL,
3873 req-body [4] KDC-REQ-BODY
3876 KDC-REQ-BODY ::= SEQUENCE {
3877 kdc-options [0] KDCOptions,
3878 cname [1] PrincipalName OPTIONAL
3879 -- Used only in AS-REQ --,
3882 -- Also client's in AS-REQ --,
3883 sname [3] PrincipalName OPTIONAL,
3884 from [4] KerberosTime OPTIONAL,
3885 till [5] KerberosTime,
3886 rtime [6] KerberosTime OPTIONAL,
3888 etype [8] SEQUENCE OF Int32 -- EncryptionType
3889 -- in preference order --,
3890 addresses [9] HostAddresses OPTIONAL,
3891 enc-authorization-data [10] EncryptedData {
3893 { keyuse-TGSReqAuthData-sesskey
3894 | keyuse-TGSReqAuthData-subkey }
3896 additional-tickets [11] SEQUENCE OF Ticket OPTIONAL
3901 TGS-REP ::= KDC-REP {13, EncTGSRepPart,
3902 { keyuse-EncTGSRepPart-sesskey
3903 | keyuse-EncTGSRepPart-subkey }}
3905 KDC-REP {INTEGER:tagnum,
3907 UInt32:KeyUsages} ::= [APPLICATION tagnum] SEQUENCE {
3908 pvno [0] INTEGER (5),
3909 msg-type [1] INTEGER (tagnum),
3910 padata [2] SEQUENCE OF PA-DATA OPTIONAL,
3912 cname [4] PrincipalName,
3914 enc-part [6] EncryptedData {TypeToEncrypt, KeyUsages}
3917 EncTGSRepPart ::= [APPLICATION 26] EncKDCRepPart
3919 EncKDCRepPart ::= SEQUENCE {
3920 key [0] EncryptionKey,
3921 last-req [1] LastReq,
3923 key-expiration [3] KerberosTime OPTIONAL,
3924 flags [4] TicketFlags,
3925 authtime [5] KerberosTime,
3926 starttime [6] KerberosTime OPTIONAL,
3927 endtime [7] KerberosTime,
3928 renew-till [8] KerberosTime OPTIONAL,
3930 sname [10] PrincipalName,
3931 caddr [11] HostAddresses OPTIONAL
3935 @include texi/tgs.c.texi
3938 @node Ticket (ASN.1) Functions
3939 @section Ticket (ASN.1) Functions
3941 @xref{Ticket Functions}, for an high-level overview of tickets. The
3942 following illustrates the Ticket and EncTicketPart ASN.1 structures.
3945 Ticket ::= [APPLICATION 1] SEQUENCE {
3946 tkt-vno [0] INTEGER (5),
3948 sname [2] PrincipalName,
3949 enc-part [3] EncryptedData -- EncTicketPart
3952 -- Encrypted part of ticket
3953 EncTicketPart ::= [APPLICATION 3] SEQUENCE {
3954 flags [0] TicketFlags,
3955 key [1] EncryptionKey,
3957 cname [3] PrincipalName,
3958 transited [4] TransitedEncoding,
3959 authtime [5] KerberosTime,
3960 starttime [6] KerberosTime OPTIONAL,
3961 endtime [7] KerberosTime,
3962 renew-till [8] KerberosTime OPTIONAL,
3963 caddr [9] HostAddresses OPTIONAL,
3964 authorization-data [10] AuthorizationData OPTIONAL
3968 @include texi/ticket.c.texi
3969 @include texi/encticketpart.c.texi
3971 @node AS/TGS Functions
3972 @section AS/TGS Functions
3974 The Authentication Service (AS) is used to get an initial ticket using
3975 e.g. your password. The Ticket Granting Service (TGS) is used to get
3976 subsequent tickets using other tickets. Protocol wise the procedures
3977 are very similar, which is the reason they are described together.
3978 The following illustrates the AS-REQ, TGS-REQ and AS-REP, TGS-REP
3979 ASN.1 structures. Most of the functions use the mnemonic ``KDC''
3980 instead of either AS or TGS, which means the function operates on both
3981 AS and TGS types. Only where the distinction between AS and TGS is
3982 important are the AS and TGS names used. Remember, these are
3983 low-level functions, and normal applications will likely be satisfied
3984 with the AS (@pxref{AS Functions}) and TGS (@pxref{TGS Functions})
3985 interfaces, or the even more high-level Ticket Set (@pxref{Ticket Set
3986 Functions}) interface.
3991 AS-REQ ::= KDC-REQ {10}
3992 TGS-REQ ::= KDC-REQ {12}
3994 KDC-REQ {INTEGER:tagnum} ::= [APPLICATION tagnum] SEQUENCE {
3995 pvno [1] INTEGER (5) -- first tag is [1], not [0] --,
3996 msg-type [2] INTEGER (tagnum),
3997 padata [3] SEQUENCE OF PA-DATA OPTIONAL,
3998 req-body [4] KDC-REQ-BODY
4001 KDC-REQ-BODY ::= SEQUENCE {
4002 kdc-options [0] KDCOptions,
4003 cname [1] PrincipalName OPTIONAL
4004 -- Used only in AS-REQ --,
4007 -- Also client's in AS-REQ --,
4008 sname [3] PrincipalName OPTIONAL,
4009 from [4] KerberosTime OPTIONAL,
4010 till [5] KerberosTime,
4011 rtime [6] KerberosTime OPTIONAL,
4013 etype [8] SEQUENCE OF Int32 -- EncryptionType
4014 -- in preference order --,
4015 addresses [9] HostAddresses OPTIONAL,
4016 enc-authorization-data [10] EncryptedData {
4018 { keyuse-TGSReqAuthData-sesskey
4019 | keyuse-TGSReqAuthData-subkey }
4021 additional-tickets [11] SEQUENCE OF Ticket OPTIONAL
4026 AS-REP ::= KDC-REP {11, EncASRepPart, {keyuse-EncASRepPart}}
4027 TGS-REP ::= KDC-REP {13, EncTGSRepPart,
4028 { keyuse-EncTGSRepPart-sesskey
4029 | keyuse-EncTGSRepPart-subkey }}
4031 KDC-REP {INTEGER:tagnum,
4033 UInt32:KeyUsages} ::= [APPLICATION tagnum] SEQUENCE {
4034 pvno [0] INTEGER (5),
4035 msg-type [1] INTEGER (tagnum),
4036 padata [2] SEQUENCE OF PA-DATA OPTIONAL,
4038 cname [4] PrincipalName,
4040 enc-part [6] EncryptedData {TypeToEncrypt, KeyUsages}
4043 EncASRepPart ::= [APPLICATION 25] EncKDCRepPart
4044 EncTGSRepPart ::= [APPLICATION 26] EncKDCRepPart
4046 EncKDCRepPart ::= SEQUENCE {
4047 key [0] EncryptionKey,
4048 last-req [1] LastReq,
4050 key-expiration [3] KerberosTime OPTIONAL,
4051 flags [4] TicketFlags,
4052 authtime [5] KerberosTime,
4053 starttime [6] KerberosTime OPTIONAL,
4054 endtime [7] KerberosTime,
4055 renew-till [8] KerberosTime OPTIONAL,
4057 sname [10] PrincipalName,
4058 caddr [11] HostAddresses OPTIONAL
4062 @include texi/kdc.c.texi
4063 @include texi/kdcreq.c.texi
4064 @include texi/kdcrep.c.texi
4065 @include texi/enckdcreppart.c.texi
4068 @node Authenticator Functions
4069 @section Authenticator Functions
4071 An ``Authenticator'' is an ASN.1 structure that work as a proof that
4072 an entity owns a ticket. It is usually embedded in the AP-REQ
4073 structure (@pxref{AP-REQ and AP-REP Functions}), and you most likely
4074 want to use an AP-REQ instead of a Authenticator in normal
4075 applications. The following illustrates the Authenticator ASN.1
4079 Authenticator ::= [APPLICATION 2] SEQUENCE {
4080 authenticator-vno [0] INTEGER (5),
4082 cname [2] PrincipalName,
4083 cksum [3] Checksum OPTIONAL,
4084 cusec [4] Microseconds,
4085 ctime [5] KerberosTime,
4086 subkey [6] EncryptionKey OPTIONAL,
4087 seq-number [7] UInt32 OPTIONAL,
4088 authorization-data [8] AuthorizationData OPTIONAL
4092 @include texi/authenticator.c.texi
4095 @node KRB-ERROR Functions
4096 @section KRB-ERROR Functions
4098 The ``KRB-ERROR'' is an ASN.1 structure that can be returned, instead
4099 of, e.g., KDC-REP or AP-REP, to indicate various error conditions.
4100 Unfortunately, the semantics of several of the fields are ill
4101 specified, so the typically procedure is to extract ``e-text'' and/or
4102 ``e-data'' and show it to the user. The following illustrates the
4103 KRB-ERROR ASN.1 structure.
4106 KRB-ERROR ::= [APPLICATION 30] SEQUENCE {
4107 pvno [0] INTEGER (5),
4108 msg-type [1] INTEGER (30),
4109 ctime [2] KerberosTime OPTIONAL,
4110 cusec [3] Microseconds OPTIONAL,
4111 stime [4] KerberosTime,
4112 susec [5] Microseconds,
4113 error-code [6] Int32,
4114 crealm [7] Realm OPTIONAL,
4115 cname [8] PrincipalName OPTIONAL,
4116 realm [9] Realm -- service realm --,
4117 sname [10] PrincipalName -- service name --,
4118 e-text [11] KerberosString OPTIONAL,
4119 e-data [12] OCTET STRING OPTIONAL
4123 @include texi/krberror.c.texi
4125 @node Cryptographic Functions
4126 @section Cryptographic Functions
4128 Underneath the high-level functions described earlier, cryptographic
4129 operations are happening. If you need to access these cryptographic
4130 primitives directly, this section describes the functions available.
4132 Most cryptographic operations need keying material, and cryptographic
4133 keys have been isolated into it's own data structure
4134 @code{Shishi_key}. The following illustrates it's contents, but note
4135 that you cannot access it's elements directly but must use the
4136 accessor functions described below.
4141 int type; /* RFC 1510 encryption integer type */
4142 char *value; /* Cryptographic key data */
4143 int version; /* RFC 1510 ``kvno'' */
4147 All functions that operate on this data structure are described now.
4149 @include texi/key.c.texi
4151 Applications that run uninteractively may need keying material. In
4152 these cases, the keys are stored in a file, a file that is normally
4153 stored on the local host. The file should be protected from
4154 unauthorized access. The file is in ASCII format and contains keys as
4155 outputed by @code{shishi_key_print}. All functions that handle these
4156 keys sets are described now.
4158 @include texi/keys.c.texi
4160 The previous functions require that the filename is known. For some
4161 applications, servers, it makes sense to provide a system default.
4162 These key sets used by server applications are known as ``hostkeys''.
4163 Here are the functions that operate on hostkeys (they are mostly
4164 wrappers around generic key sets).
4166 @include texi/hostkeys.c.texi
4168 After creating the key structure, it can be used to encrypt and
4169 decrypt data, calculate checksum on data etc. All available functions
4172 @include texi/crypto.c.texi
4174 An easier way to use encryption and decryption if your application
4175 repeatedly calls, e.g., @code{shishi_encrypt_ivupdate}, is to use the
4176 following functions. They store the key, initialization vector, etc,
4177 in a context, and the encryption and decryption operations update the
4178 IV within the context automatically.
4180 @include texi/crypto-ctx.c.texi
4182 Also included in Shishi is an interface to the really low-level
4183 cryptographic primitives. They map directly on the underlying
4184 cryptographic library used (i.e., Gnulib or Libgcrypt) and is used
4185 internally by Shishi.
4187 @include texi/low-crypto.c.texi
4190 @node X.509 Functions
4191 @section X.509 Functions
4193 The functions described in this section are used by the STARTTLS
4194 functionality, see @ref{Kerberos via TLS}.
4196 @include texi/pki.c.texi
4199 @node Utility Functions
4200 @section Utility Functions
4202 @include texi/realm.c.texi
4203 @include texi/principal.c.texi
4204 @include texi/authorize.c.texi
4205 @include texi/gztime.c.texi
4206 @include texi/password.c.texi
4207 @include texi/resolv.c.texi
4210 @node ASN.1 Functions
4211 @section ASN.1 Functions
4213 @include texi/asn1.c.texi
4216 @node Error Handling
4217 @section Error Handling
4218 @cindex Error Handling
4220 Most functions in `Libshishi' are returning an error if they fail.
4221 For this reason, the application should always catch the error
4222 condition and take appropriate measures, for example by releasing the
4223 resources and passing the error up to the caller, or by displaying a
4224 descriptive message to the user and cancelling the operation.
4226 Some error values do not indicate a system error or an error in the
4227 operation, but the result of an operation that failed properly.
4230 * Error Values:: A list of all error values used.
4231 * Error Functions:: Error handling related functions.
4235 @subsection Error Values
4237 Errors are returned as an @code{int}. Except for the SHISHI_OK case,
4238 an application should always use the constants instead of their
4239 numeric value. Applications are encouraged to use the constants even
4240 for SHISHI_OK as it improves readability. Possible values are:
4244 This value indicates success. The value of this error is guaranteed
4245 to always be @code{0} so you may use it in boolean constructs.
4247 @include shishi-api-error-labels.texi
4251 @node Error Functions
4252 @subsection Error Functions
4254 @include texi/error.c.texi
4260 This section will be extended to contain walk-throughs of example code
4261 that demonstrate how `Shishi' is used to write your own applications
4262 that support Kerberos 5. The rest of the current section consists of
4263 some crude hints for the example client/server applications that is
4264 part of Shishi, taken from an email but saved here for lack of a
4265 better place to put it.
4267 There are two programs: 'client' and 'server' in src/.
4269 The client output an AP-REQ, waits for an AP-REP, and then simply
4270 reads data from stdin.
4272 The server waits for an AP-REQ, parses it and prints an AP-REP, and
4273 then read data from stdin.
4275 Both programs accept a Kerberos server name as the first command line
4276 argument. Your KDC must know this server, since the client tries to
4277 get a ticket for it (first it gets a ticket granting ticket for the
4278 default username), and you must write the key for the server into
4279 /usr/local/etc/shishi.keys on the Shishi format, e.g.:
4282 -----BEGIN SHISHI KEY-----
4283 Keytype: 16 (des3-cbc-sha1-kd)
4284 Principal: sample/latte.josefsson.org
4285 Realm: JOSEFSSON.ORG
4287 8W0VrQQBpxlACPQEqN91EHxbvFFo2ltt
4288 -----END SHISHI KEY-----
4291 You must extract the proper encryption key from the KDC in some way.
4292 (This part will be easier when Shishi include a KDC, a basic one isn't
4293 far away, give me a week or to.)
4295 The intention is that the data read, after the authentication phase,
4296 should be protected using KRB_SAFE (see RFC) but I haven't added this
4299 @node Kerberos Database Functions
4300 @section Kerberos Database Functions
4302 @cindex Database interface
4304 Shisa is a separate and standalone library from Shishi
4305 (@pxref{Introduction to Shisa}). If you only wish to manipulate the
4306 information stored in the Kerberos user database used by Shishi, you
4307 do not need to link or use the Shishi library at all. However, you
4308 may find it useful to combine the two libraries.
4310 For two real world examples on using the Shisa library, refer to
4311 @file{src/shisa.c} (Shisa command line tool) and @file{src/kdc.c}
4312 (part of Shishid server).
4314 Shisa uses two @samp{struct}s to carry information. The first,
4315 @code{Shisa_principal}, is used to hold information about principals.
4316 The struct does not contain pointers to strings etc, so the library
4317 assumes the caller is responsible for allocating and deallocating the
4318 struct itself. Each such struct is (uniquely) identified by the
4319 combination of principal name and realm name.
4322 struct Shisa_principal
4326 time_t notusedbefore;
4327 time_t lastinitialtgt; /* time of last initial request for a TGT */
4328 time_t lastinitialrequest; /* time of last initial request */
4329 time_t lasttgt; /* time of issue for the newest TGT used */
4330 time_t lastrenewal; /* time of the last renewal */
4331 time_t passwordexpire; /* time when the password will expire */
4332 time_t accountexpire; /* time when the account will expire. */
4334 typedef struct Shisa_principal Shisa_principal;
4337 The second structure is called @code{Shisa_key} and hold information
4338 about cryptographic keys. Because the struct contain pointers, and
4339 the caller cannot know how many keys a principal have, the Shisa
4340 library manages memory for the struct. The library allocate the
4341 structs, and the pointers within them. The caller may deallocate
4342 them, but it is recommended to use @code{shisa_key_free} or
4343 @code{shisa_keys_free} instead. Note that each principal may have
4357 size_t str2keyparamlen;
4360 typedef struct Shisa_key Shisa_key;
4363 Shisa is typically initialized by calling @code{shisa_init}, and
4364 deinitialized (when the application no longer need to use Shisa,
4365 typically when it shuts down) by calling @code{shisa_done}, but here
4366 are the complete (de)initialization interface functions.
4368 @include texi/setup.c.texi
4370 The default configuration file is typically read automatically by
4371 calling @code{shisa_init}, but if you wish to manually access the
4372 Shisa configuration file functions, here is the complete interface.
4374 @include texi/config.c.texi
4376 The core part of the Shisa interface follows. The typical procedure
4377 is to use @code{shisa_principal_find} to verify that a specific
4378 principal exists, and to extract some information about it, and then
4379 use @code{shisa_keys_find} to get the cryptographic keys for the
4380 principal, usually suppliying some hints as to which of all keys you
4381 are interested in (e.g., key version number and encryption algorithm
4384 @include texi/core.c.texi
4386 Error handling is similar to that for Shishi in general (@pxref{Error
4387 Handling}), i.e., you invoke @code{shisa_strerror} on the integer
4388 return value received by some function, if the return value is
4389 non-zero. Below is the complete interface.
4391 @include texi/err.c.texi
4393 @node Generic Security Service
4394 @section Generic Security Service
4395 @cindex Generic Security Service
4399 As an alternative to the native Shishi programming API, it is possible
4400 to program Shishi through the Generic Security Services (GSS) API.
4401 The advantage of using GSS-API in your security application, instead
4402 of the native Shishi API, is that it will be easier to port your
4403 application between different Kerberos 5 implementations, and even
4404 beyond Kerberos 5 to different security systems, that support GSS-API.
4405 In the free software world, however, almost the only widely used
4406 security system that supports GSS-API is Kerberos 5, so the last
4407 advantage is somewhat academic. But if you are porting applications
4408 using GSS-API for other Kerberos 5 implementations, or want a more
4409 mature and stable API than the native Shishi API, you may find using
4410 Shishi's GSS-API interface compelling. Note that GSS-API only offer
4411 basic services, for more advanced uses you must use the native API.
4413 Since the GSS-API is not specific to Shishi, it is distributed
4414 independently from Shishi. Further information on the GSS project can
4415 be found at @url{http://josefsson.org/gss/}.
4417 @c **********************************************************
4418 @c ******************* Acknowledgements *******************
4419 @c **********************************************************
4420 @node Acknowledgements
4421 @chapter Acknowledgements
4423 Shishi uses Libtasn1 by Fabio Fiorina, Libgcrypt and Libgpg-error by
4424 Werner Koch, Libidn by Simon Josefsson, cvs2cl by Karl Fogel, and gdoc
4427 Several GNU packages simplified development considerably, those
4428 packages include Autoconf, Automake, Libtool, Gnulib, Gettext, Indent,
4429 CVS, Texinfo, Help2man and Emacs.
4431 Several people reported bugs, sent patches or suggested improvements,
4432 see the file THANKS.
4434 Nicolas Pouvesle wrote the section about the Kerberos rsh/rlogin
4437 This manual borrows text from the Kerberos 5 specification.
4439 @c **********************************************************
4440 @c ******************* Appendices *************************
4441 @c **********************************************************
4443 @node Criticism of Kerberos
4444 @appendix Criticism of Kerberos
4446 The intention with this section is to discuss various problems with
4447 Kerberos 5, so you can form a conscious decision how to deploy and use
4448 Shishi correctly in your organization. Currently the issues below are
4449 condensed, and mostly serve as a reminder for the author to elaborate
4452 No encryption scheme with security proof.
4454 No standardized API, and GSS mechanism lack important functionality.
4456 Lack of authorization system. (krb5_kuserok())
4458 Host to realm mapping relies on insecure DNS or static configuration
4461 Informational model and user database administration.
4463 Non-formal specification. Unclear on the etype to use for session
4464 keys (etype in request or database?). Unclear on how to populate some
4465 ``evident'' fields (e.g., cname in tickets for AS-REQ, or crealm,
4466 cname, realm, sname, ctime and cusec in KRB-ERROR). Unclear error
4467 code semantics (e.g., logic for when to use S_PRINCIPAL_UNKNOWN
4468 absent). Some KRB-ERROR fields are required, but can't be usefully
4469 populated in some situations, and no guidance is given on what they
4472 RFC 1510/1510bis incompatibilities. NULL enctype removed without
4473 discussion, and it is still used by some 1964 GSSAPI implementations.
4474 KRB_SAFE text (3.4.1) says the checksum is generated using the session
4475 or sub-session key, which contradicts itself (compare section 3.2.6)
4476 and also RFC 1510, which both allow the application to define the key.
4477 Verification of KRB_SAFE now require the key to be compatible with the
4478 (sub-)session key, in 1510 the only requirement was that it was
4481 Problems with RFC 1510bis. Uses bignum INTEGER for TYPED-DATA and
4484 Problems with crypto specification. It uses the word ``random'' many
4485 times, but there is no discussion on the randomness requirements.
4486 Practical experience indicate it is impossible to use true randomness
4487 for all ``random'' fields, and no implementation does this. A post by
4488 Don Davis on the ietf-krb-wg list tried to provide insight, but the
4489 information was never added to the specification.
4491 @node Protocol Extensions
4492 @appendix Protocol Extensions
4494 This appendix specifies the non-standard protocol elements implemented
4495 by Shishi. By nature of being non-standard, everything described here
4496 is experimental. Comments and feedback is appreciated.
4499 * STARTTLS protected KDC exchanges:: How Shishi talks to KDC protected by TLS.
4500 * Telnet encryption with AES-CCM:: Integrity and privacy protected telnet.
4501 * Kerberized rsh and rlogin:: Description of KCMD protocol.
4502 * Key as initialization vector:: Some cryptography discussion.
4503 * The Keytab Binary File Format:: Format of keytab files.
4504 * The Credential Cache Binary File Format:: Format of ccache files.
4507 @node STARTTLS protected KDC exchanges
4508 @section STARTTLS protected KDC exchanges
4510 Shishi is able to ``upgrade'' TCP communications with the KDC to use
4511 the Transport Layer Security (TLS) protocol. The TLS protocol offers
4512 integrity and privacy protected exchanges. TLS also offers
4513 authentication using username and passwords, X.509 certificates, or
4514 OpenPGP certificates. Kerberos 5 claims to offer some of these
4515 features, although it is not as rich as the TLS protocol. An
4516 inconclusive list of the motivation for using TLS is given below.
4520 @item Server authentication of the KDC to the client.
4521 In traditional Kerberos 5, KDC authentication is only proved as a side
4522 effect that the KDC knows your encryption key (i.e., your password).
4524 @item Client authentication against KDC.
4525 Kerberos 5 assume the user knows a key (usually in the form of a
4526 password). Sometimes external factors make this hard to fulfill. In
4527 some situations, users are equipped with smart cards with a RSA
4528 authentication key. In others, users have a OpenPGP client on their
4529 desktop, with a public OpenPGP key known to the server. In some
4530 situations, the policy may be that password authentication may only be
4533 @item Kerberos exchanges are privacy protected.
4534 Part of many Kerberos packets are transfered without privacy
4535 protection (i.e., encryption). That part contains information, such
4536 as the client principal name, the server principal name, the
4537 encryption types supported by the client, the lifetime of tickets,
4538 etc. Revealing such information is, in some threat models, considered
4539 a problem. Thus, this enables ``anonymity''.
4541 @item Prevents downgrade attacks affecting encryption types.
4542 The encryption type of the ticket in KDC-REQ are sent in the clear in
4543 Kerberos 5. This allows an attacker to replace the encryption type
4544 with a compromised mechanisms, e.g. 56-bit DES. Since clients in
4545 general cannot know the encryption types other servers support, it is
4546 difficult for the client to detect if there was a man-in-the-middle or
4547 if the remote server simply did not support a stronger mechanism.
4548 Clients may chose to refuse 56-bit DES altogether, but in some
4549 environments this leads to operational difficulties.
4551 @item TLS is well-proved and the protocol is studied by many parties.
4552 This is an advantage in network design, where TLS is often already
4553 assumed as part of the solution since it is used to protect HTTP,
4554 IMAP, SMTP etc. In some threat models, the designer prefer to reduce
4555 the number of protocols that can hurt the overall system security if
4556 they are compromised.
4560 Other reasons for using TLS exists.
4562 @subsection TCP/IP transport with TLS upgrade (STARTTLS)
4564 RFC 1510bis requires Kerberos servers (KDCs) to accept TCP requests.
4565 Each request and response is prefixed by a 4 octet integer in network
4566 byte order, indicating the length of the packet. The high bit of the
4567 length was reserved for future expansion, and servers that do not
4568 understand how to interpret a set high bit must return a
4569 @code{KRB-ERROR} with a @code{KRB_ERR_FIELD_TOOLONG} and close the TCP
4572 The TCP/IP transport with TLS upgrade (STARTTLS) uses this reserved
4573 bit as follows. First we define a new extensible typed hole for
4574 Kerberos 5 messages, because we used the only reserved bit. It is
4575 thus prudent to offer future extensions on our proposal. Secondly we
4576 reserve two values in this new typed hole, and described how they are
4577 used to implement STARTTLS.
4579 @subsection Extensible typed hole based on reserved high bit
4581 When the high bit is set, the remaining 31 bits of the 4 octets are
4582 treated as an extensible typed hole, and thus form a 31 bit integer
4583 enumerating various extensions. Each of the values indicate a
4584 specific extended operation mode, two of which are used and defined
4585 here, and the rest are left for others to use. If the KDC do not
4586 understand a requested extension, it MUST return a @code{KRB-ERROR}
4587 with a @code{KRB_ERR_FIELD_TOOLONG} value (prefixed by the 4 octet
4588 length integer, with the high bit clear, as usual) and close the TCP
4591 Meaning of the 31 lower bits in the 4 octet field, when the high bit
4596 1 STARTTLS requested by client.
4597 2 STARTTLS request accepted by server.
4598 3...2147483647 AVAILABLE for registration (via bug-shishi@josefsson.org).
4599 2147483648 RESERVED.
4602 @subsection STARTTLS requested by client (extension mode 1)
4604 When this is sent by the client, the client is requesting the server
4605 to start TLS negotiation on the TCP stream. The client MUST NOT start
4606 TLS negotiation immediately. Instead, the client wait for either a
4607 KRB-ERROR (sent normally, prefixed by a 4 octet length integer)
4608 indicating the server do not understand the set high bit, or 4 octet
4609 which is to interpreted as an integer in network byte order, where the
4610 high bit is set and the remaining 31 bit are interpreted as an integer
4611 specifying the ``STARTTLS request accepted by server''. In the first
4612 case, the client infer that the server do not understand (or wish to
4613 support) STARTTLS, and can re-try using normal TCP, if unprotected
4614 Kerberos 5 exchanges are acceptable to the client policy. In the
4615 latter case, it should invoke TLS negotiation on the stream. If any
4616 other data is received, the client MUST close the TCP stream.
4618 @subsection STARTTLS request accepted by server (extension mode 2)
4620 This 4 octet message should be sent by the server when it has received
4621 the previous 4 octet message. The message is an acknowledgment of the
4622 client's request to initiate STARTTLS on the channel. The server MUST
4623 then invoke a TLS negotiation.
4625 @subsection Proceeding after successful TLS negotiation
4627 If the TLS negotiation ended successfully, possibly also considering
4628 client or server policies, the exchange within the TLS protected
4629 stream is performed like normal UDP Kerberos 5 exchanges, i.e., there
4630 is no TCP 4 octet length field before each packet. Instead each
4631 Kerberos packet MUST be sent within one TLS record, so the application
4632 can use the TLS record length as the Kerberos 5 packet length.
4634 @subsection Proceeding after failed TLS negotiation
4636 If the TLS negotiation fails, possibly due to client or server policy
4637 (e.g., inadequate support of encryption types in TLS, or lack of
4638 client or server authentication) the entity that detect the failure
4639 MUST disconnected the connection. It is expected that any error
4640 messages that explain the error condition is transfered by TLS.
4642 @subsection Interaction with KDC addresses in DNS
4644 Administrators for a KDC may announce the KDC address by placing SRV
4645 records in DNS for the realm, as described in
4646 @file{draft-ietf-krb-wg-krb-dns-locate-03.txt}. That document mention
4647 TLS, but do not reference any work that describe how KDCs uses TLS.
4648 Until further clarified, consider the TLS field in that document to
4649 refer to implementation supporting this STARTTLS protocol.
4651 @subsection Using TLS authentication logic in Kerberos
4653 The server MAY consider the authentication performed by the TLS
4654 exchange as sufficient to issue Kerberos 5 tickets to the client,
4655 without requiring, e.g., pre-authentication. However, it is not an
4656 error to require or use pre-authentication as well.
4658 The client may also indicate that it wishes to use TLS both for
4659 authentication and data protection by using the @samp{NULL} encryption
4660 type in its request. The server can decide from its local policy
4661 whether or not issuing tickets based solely on TLS authentication, and
4662 whether @samp{NULL} encryption within TLS, is acceptable or not. This
4663 mode is currently under investigation.
4665 @subsection Security considerations
4667 Because the initial token is not protected, it is possible for an
4668 active attacker to make it appear to the client that the server do not
4669 support this extension. It is up to client configuration to disallow
4670 non-TLS connections, if this vulnerability is deemed unacceptable.
4671 For interoperability, we suggest the default behaviour should be to
4672 allow automatic fallback to TCP or UDP.
4674 The security considerations of both TLS and Kerberos 5 are inherited.
4675 Using TLS for authentication and/or data protection together with
4676 Kerberos alter the authentication logic fundamentally. Thus, it may
4677 be that even if the TLS and Kerberos 5 protocols and implementations
4678 were secure, the combination of TLS and Kerberos 5 described here
4681 No channel bindings are provided in the Kerberos messages. It is an
4682 open question whether, and how, this should be fixed.
4684 @node Telnet encryption with AES-CCM
4685 @section Telnet encryption with AES-CCM
4687 This appendix describe how Shishi use the Advanced Encryption Standard
4688 (AES) encryption algorithm in Counter with CBC-MAC mode (RFC 3610)
4689 with the telnet encryption option (RFC 2946).
4691 @subsection Command Names and Codes
4705 @subsection Command Meanings
4708 IAC SB ENCRYPT IS AES_CCM AES_CCM_INFO <M> <L> <nonce> IAC SE
4711 The sender of this command select desired M and L parameters, and
4712 nonce, as described in RFC 3610, and sends it to the other side of the
4713 connection. The parameters and the nonce are sent in clear text.
4714 Only the side of the connection that is WILL ENCRYPT may send the
4715 AES_CCM_INFO command.
4718 IAC SB ENCRYPT REPLY AES_CCM AES_CCM_INFO_BAD IAC SE
4721 The sender of this command reject the parameters received in the
4722 AES_CCM_INFO command. Only the side of the connection that is DO
4723 ENCRYPT may send the AES_CCM_INFO_BAD command. The command MUST be
4724 sent if the nonce field length does not match the selected value for
4725 L. The command MAY be sent if the receiver do not accept the
4726 parameters for reason such as policy. No capability is provided to
4727 negotiate these parameters.
4730 IAC SB ENCRYPT REPLY AES_CCM AES_CCM_INFO_OK IAC SE
4733 The sender of this command accepts the parameters received in the
4734 AES_CCM_INFO command. Only the side of the connection that is DO
4735 ENCRYPT may send the AES_CCM_INFO_BAD command. The command MUST NOT
4736 be sent if the nonce field length does not match the selected value
4739 @subsection Implementation Rules
4741 Once a AES_CCM_INFO_OK command has been received, the WILL ENCRYPT
4742 side of the connection should do keyid negotiation using the ENC_KEYID
4743 command. Once the keyid negotiation has successfully identified a
4744 common keyid, then START and END commands may be sent by the side of
4745 the connection that is WILL ENCRYPT. Data will be encrypted using the
4746 AES-CCM algorithm, with the negotiated nonce and parameters M and L.
4747 After each successful encryption and decryption, the nonce is treated
4748 as an integer in network byte order, and incremented by one.
4750 If encryption (decryption) is turned off and back on again, and the
4751 same keyid is used when re-starting the encryption (decryption), the
4752 intervening clear text must not change the state of the encryption
4753 (decryption) machine. In particular, the AES-CCM nonce must not be
4756 If a START command is sent (received) with a different keyid, the
4757 encryption (decryption) machine must be re-initialized immediately
4758 following the end of the START command with the new key and the
4759 parameters sent (received) in the last AES_CCM_INFO command.
4761 If a new AES_CCM_INFO command is sent (received), and encryption
4762 (decryption) is enabled, the encryption (decryption) machine must be
4763 re-initialized immediately following the end of the AES_CCM_INFO
4764 command with the new nonce and parameters, and the keyid sent
4765 (received) in the last START command.
4767 If encryption (decryption) is not enabled when a AES_CCM_INFO command
4768 is sent (received), the encryption (decryption) machine must be re-
4769 initialized after the next START command, with the keyid sent
4770 (received) in that START command, and the nonce and parameters sent
4771 (received) in this AES_CCM_INFO command.
4773 At all times MUST each end make sure that a AES-CCM nonce is not used
4774 twice under the same encryption key. The rules above help accomplish
4775 this in an interoperable way.
4777 @subsection Integration with the AUTHENTICATION telnet option
4779 <<This section is slightly complicated. Can't we simplify this?>>
4781 As noted in the telnet ENCRYPTION option specifications, a keyid value
4782 of zero indicates the default encryption key, as might be derived from
4783 the telnet AUTHENTICATION option. If the default encryption key
4784 negotiated as a result of the telnet AUTHENTICATION option contains
4785 less than 32 bytes (corresponding to two 128 bit keys), then the
4786 AES_CCM option MUST NOT be offered or used as a valid telnet
4787 encryption option. Furthermore, depending on policy for key lengths,
4788 the AES_CCM option MAY be disabled if the default encryption key
4789 contain less than 48 bytes (for two 192 bit keys), or less than 64
4790 bytes (for two 256 bit keys), as well.
4792 The available encrypt key data is divided on two halves, where the
4793 first half is used to encrypt data sent from the server (decrypt data
4794 received by the client), and the second half is used to encrypt data
4795 sent from the client (decrypt data received by the server).
4797 Note that the above algorithm assumes that the AUTHENTICATION
4798 mechanism generate keying material suitable for AES-CCM as used in
4799 this specification. This is not necessarily true in general, but we
4800 specify this behaviour as the default since it is true for most
4801 authentication systems in popular use today. New telnet
4802 AUTHENTICATION mechanisms may specify alternative methods for
4803 determining the keys to be used for this cipher suite in their
4804 specification, if the session key negotiated by that authentication
4805 mechanism is not a DES key and and where this algorithm may not be
4808 Kerberos 5 authentication clarification: The key used to encrypt data
4809 from the client to the server is taken from the sub-session key in the
4810 AP-REQ. The key used to decrypt data from the server to the client is
4811 taken from the sub-session key in the AP-REP. If mutual
4812 authentication is not negotiated, the key used to encrypt data from
4813 the client to the server is taken from the session key in the ticket,
4814 and the key used to decrypt data from the server to the client is
4815 taken from the sub-session key in the AP-REQ. Leaving the AP-REQ
4816 sub-key field empty MUST disable the AES_CCM option.
4818 @subsection Security Considerations
4820 The protocol must be properly and securely implemented. For example,
4821 an implementation should not be vulnerable to various
4822 implementation-specific attacks such as buffer overflows or
4823 side-channel analysis.
4825 We wish to repeat the suggestion from RFC 2946, to investigate in a
4826 STARTTLS approach for Telnet encryption (and also authentication),
4827 when the security level provided by this specification is not
4830 @subsubsection Telnet Encryption Protocol Security Considerations
4832 The security consideration of the Telnet encryption protocol are
4835 It should be noted that the it is up to the authentication protocol
4836 used, if any, to bind the authenticity of the peers to a specific
4839 The Telnet encryption protocol does not, in general, protect against
4840 possibly malicious downgrading to any mutually acceptable, but not
4841 preferred, encryption type. This places a requirement on each peer to
4842 only accept encryption types it trust fully. In other words, the
4843 Telnet encryption protocol do not guarantee that the strongest
4844 mutually acceptable encryption type is always selected.
4846 @subsubsection AES-CCM Security Considerations
4848 The integrity and privacy claims are inherited from AES-CCM. In
4849 particular, the implementation must make sure a nonce is not used more
4850 than once together with the same key.
4852 Furthermore, the encryption key is assumed to be random, i.e., it
4853 should not be possible to guess it with probability of success higher
4854 than guessing any uniformly selected random key. RFC 1750 gives an
4855 overview of issues and recommendations related to randomness.
4857 @subsection Acknowledgments
4859 This document is based on the various Telnet Encryption RFCs (RFC
4860 2946, RFC 2947, RFC 2948, RFC 2952 and RFC 2953).
4862 @node Kerberized rsh and rlogin
4863 @section Kerberized rsh and rlogin
4865 This appendix describe the KCMDV0.2 protocol used in shishi patched
4866 version of inetutils. The KCMD protocol was developped by the MIT
4867 Kerberos team for kerberized rsh an rlogin programs. Differences
4868 between rlogin an rsh will be explained, like those between v0.1 and
4869 v0.2 of the protocol for compatibility reasons.
4870 It is possible that some parts of this document are not in conformity
4871 with original KCMD protocol because there is no official specification
4872 about it. However, it seems that shishi implementation is compatible
4875 @strong{Warning:} If you are seriously considering using Kerberos rsh
4876 or rlogin, instead of more robust remote access protocols such as
4877 @acronym{SSH}, you may first want to explore
4878 @url{http://www.cs.berkeley.edu/~hildrum/kerberos/} and the full paper
4879 at @url{http://www.cs.berkeley.edu/~hildrum/043.pdf}.
4881 @subsection Establish connection
4883 First the client should establish a TCP connection with the
4884 server. Default ports are 543 (klogin), 544 (kshell), 2105 (eklogin).
4885 eklogin is the same as klogin but with encryption. Their is no longer
4886 ekshell port because encrypted and normal connection use the same port
4888 Kshell need a second connection for stderr. The client should send a
4889 null terminated string that represent the port of this second
4891 Klogin and eklogin does not use a second connection for stderr so the
4892 client must send a null byte to the server.
4893 Contrary to classic rsh/rlogin, server must not check if the client
4894 port is in the range 0-1023.
4896 @subsection Kerberos identification
4898 When connections are established, first thing to do is to indicate
4899 kerberos authentication must be used.
4900 So the client will send a string to indicate it will used kerberos
4901 5. It will call a length-string "strl" the couple (lenght of the string
4902 strl, null terminated string strl). Length of the string is an int32
4903 (32bits int) in MSB order (for the network).
4904 So the client send this length-string strl :
4910 After that the client must indicate which version of the protocol it
4911 will used by sending this length-string strl :
4917 It can be V0.1 for older versions.
4918 If indentification from client is good, server will send a null
4919 byte (0x00). Else if authentication message is wrong, server send byte
4920 0x01, else if protocol version message is wrong server send byte 0x02.
4922 @subsection Kerberos authentication
4924 When client is indentified, kerberos authentication can begin. The
4925 client must send an AP-REQ to the server. AP-REQ authenticator must
4926 have a subkey (only for KCMDV0.2) and a checksum.
4927 Authenticator checksum is created on following string :
4930 "serverport:""terminaltype""remoteusername"
4939 remoteusername corresponds to the identity of the client on remote machine.
4941 AP-REQ is sended in der encoded format. The length (int32) of der
4942 encoded AP-REQ is sended in network format (MSB), following by the der
4944 If all is correct, server send a null int32 (MSB format but like it is
4945 null it is not important).
4946 KCMD protocol use mutual authentication, so server must now send and
4947 AP-REP : (in32 lenght in MSB of der encoded AP-REP)(der encoded
4950 Now server and client are partially authenticated.
4952 @subsection Extended authentication
4954 Client must now send 3 different null terminated strings (without
4958 @item remote user name (user identity on remote machine)
4959 @item terminal type for rlogin or command for rsh
4960 @item local user name (user identity on client machine)
4967 "cat /usr/local/etc/shishi.conf"
4971 Server must verify that checksum in AP-REQ authenticator is correct by
4972 computing a new hash like client has done.
4974 Server must verify that principal (in AP-REQ) has right to log in on
4975 the remote user account.
4976 For the moment shishi only check if remote user name is equal to
4977 principal. A more complex authorization code is planned.
4978 Look at the end to know how MIT/Heimdal do to check authorization.
4980 If all is correct server send a null byte, else an error message
4981 string (null terminated string) is sent. User read the first byte. If
4982 it is equal to zero, authentication is correct and is logged on the
4983 remote host. Else user can read the error messsage send by the server.
4985 @subsection Window size
4987 For rlogin protocol, when authentication is complete, the server can
4988 optionnaly send a message to ask for window terminal size of
4989 user. Then the user can respond but it is not an obligation.
4991 In KCMDV0.1 server send an urgent TCP message (MSG_OOB) with one byte
4995 TIOCPKT_WINDOW = 0x80
4998 In KCMDV0.2 server does not send an urgent message but write on the
5002 '\377', '\377', 'o', 'o', TIOCPKT_WINDOW
5005 If encryption is enabled (eklogin) server must send this 5 bytes
5008 Client can answer in both protocol version with :
5011 '\377', '\377', 's', 's', "struct winsize"
5014 The winsize structure is filled with corresponding setting to client's
5016 If encryption is enabled this answer must be send encrypted.
5018 @subsection End of authentication
5020 The "classic" rsh/rlogin can be used now.
5023 @subsection Encryption
5025 Encryption mode is used when a connection with eklogin is established.
5026 Encryption with krsh can be used too. Before, there was a specific port
5027 for that (ekshell), but now to indicate that encryption must be used with
5028 krsh, client must add "-x " before the command when it send it between
5029 remote user name and local user name.
5030 When the client compute the checksum for AP-REQ authenticator the "-
5031 x" must not be included.
5033 Encryption in KCMDV0.2 is not the same as in KCMDV0.1.
5034 KCMDV0.1 uses ticket session key as encryption key, and use standard
5035 Kerberos encryption functions. This protocol only supports des-cbc-crc,
5036 des-cbc-md4, des-cbc-md5 and does not use initialisation vectors.
5038 For example on each encryption/decryption calls, the following
5039 prototype kerberos function should be used :
5042 kerberos_encrypt (key, keyusage, in, out) (or decrypt)
5045 KCMDV0.2 can be used with all kerberos encryption modes (des, 3des,
5046 aes, arcfour) and use AP-REQ authenticator subkey. In opposite to
5047 KCMDV0.1 initialisation vectors are used. All encryptions/descryptions
5048 must be made using a cryptographic context (for example to use the
5049 updated iv, or sbox) :
5052 kerberos_init(ctx, iv, key, keyusage)
5053 kerberos_encrypt (ctx, in, out)
5056 For both protocols, keyusage id for des-cbc-md5, des-cbc-md4,
5057 des-cbc-crc and des3-cbc-sha1 (for KCMDV0.2) :
5063 For other KCMDV0.2 modes keyusage is different for each
5064 encryption/decryption usage.
5065 To understand, eklogin use 1 socket. It encrypts data (output 1) to
5066 send and decrypts (input 1) received data.
5067 Kshell use 2 sockets (1 for transmit data, 1 for stderr). So there are
5078 There is a keyusage for each modes. The keyusage must correspond on
5079 client and server side. For example in klogin client input 1 keyusage
5080 will be server output 1 keyusage.
5082 @multitable @columnfractions .15 .15 .15
5083 @item I/O @tab Client @tab Server
5084 @item intput 1 @tab 1028 @tab 1030
5085 @item output 1 @tab 1030 @tab 1028
5086 @item intput 2 @tab 1032 @tab 1034
5087 @item output 2 @tab 1034 @tab 1032
5090 Those keyusages must be used with AES and ARCFOUR modes.
5092 KCMDV0.2 uses IV (initialisation vector). Like for keyusage, client IV
5093 must correspond to server IV. IV size is equal to key type,
5094 blocksize. All bytes of IV must be initialised to :
5096 @multitable @columnfractions .15 .15 .15
5097 @item I/O @tab Client @tab Server
5098 @item intput 1 @tab 0 @tab 1
5099 @item output 1 @tab 1 @tab 0
5100 @item intput 2 @tab 2 @tab 3
5101 @item output 2 @tab 3 @tab 2
5104 ARCFOUR mode does not use IV. However, like it is said before, a context
5105 must be used to keep the updated sbox.
5107 Normal message with klogin and kshell are sent like that :
5110 (int 32 lenght of message in MSB order)
5114 In encrypted mode it is a bit different :
5117 (int 32 length of unencrypted message in MSB order)
5121 In KCMDV0.2 encrypted message is create like that :
5125 (int 32 length of message in MSB order)
5130 A check on message size can be made in second version of the protocol.
5132 @subsection KCMDV0.3
5135 This part only gives possible ways to extend KCMD protocol. Does not
5136 take that as must have in KCMD implementation.
5138 Extensions of KCMV0.2 could be made. For example kshell supposes there
5139 are no files with name "-x *". I think the same thing can be supposed
5140 with terminal name for klogin. So client could add "-x " to terminal
5141 type it sends to server to indicate it will use encryption. Like that
5142 there will be only one port for klogin/eklogin : 543.
5144 In encrypted mode kshell send command in clear on the network, this
5145 could be considered as insecure as user have decided to use
5147 This is not really a problem for klogin because it just sends terminal
5150 In encrypted mode, klogin and kshell clients could only send "-x" as
5151 command or terminal type.
5152 After that encryption is activated, and the client could send terminal
5153 type or command encrypted.
5154 The server will send the null byte to say that all is correct, or
5155 error message in encrypted form.
5157 @subsection MIT/Heimdal authorization
5159 This part describes how MIT/Heimdal version check authorization of the
5160 user to log in on the remote machine.
5162 Authorization check is made by looking if the file .k5login exists on
5163 the account of the remote user.
5164 If this file does not exist, remote user name must be the same as
5165 principal in AP-REQ to valid authorization.
5166 Else if this file exists, check first verify that remote user or root
5167 are the owner of .k5login.
5168 If it is not the case, the check fails.
5169 If it is good, check reads each line of that file and compare each
5170 readed name to principal.
5171 If principal is found in .k5login, authorization is valid, else user
5172 is not allowed to connect on remote host with the specified remote
5173 user name (that can be the same as principal).
5175 So someone (for example user "user1") can remote log into "user2"
5176 account if .k5login is present in user2 home dir and this file is owned
5177 by user2 or root and user1 name is present in this file.
5179 @node Key as initialization vector
5180 @section Key as initialization vector
5182 The @code{des-cbc-crc} algorithm (@pxref{Cryptographic Overview}) uses
5183 the @acronym{DES} key as the initialization vector. This is
5184 problematic in general (see below@footnote{The post is copyrighted by
5185 David Wagner, included here with permission, the canonical location is
5186 @url{http://www.cs.berkeley.edu/~daw/my-posts/key-as-iv-broken}}), but
5187 may be mitigated in Kerberos by the CRC checksum that is also
5191 From daw@espresso.CS.Berkeley.EDU Fri Mar 1 13:32:34 PST 1996
5192 Article: 50440 of sci.crypt
5194 From: daw@espresso.CS.Berkeley.EDU (David A Wagner)
5195 Newsgroups: sci.crypt
5196 Subject: Re: DES-CBC and Initialization Vectors
5197 Date: 29 Feb 1996 21:48:16 GMT
5198 Organization: University of California, Berkeley
5200 Message-ID: <4h56v0$3no@agate.berkeley.edu>
5201 References: <4h39li$33o@gaia.ns.utk.edu>
5202 NNTP-Posting-Host: espresso.cs.berkeley.edu
5204 In article <4h39li$33o@gaia.ns.utk.edu>,
5205 Nair Venugopal <venu@mars.utcc.utk.edu> wrote:
5206 > Is there anything wrong in using the key as the I.V. in DES-CBC mode?
5208 Yes, you're open to a chosen-ciphertext attack which recovers the key.
5210 Alice is sending stuff DES-CBC encrypted with key K to Bob. Mary is an
5211 active adversary in the middle. Suppose Alice encrypts some plaintext
5212 blocks P_1, P_2, P_3, ... in DES-CBC mode with K as the IV, and sends off
5213 the resulting ciphertext
5214 A->B: C_1, C_2, C_3, ...
5215 where each C_j is a 8-byte DES ciphertext block. Mary wants to discover
5216 the key K, but doesn't even know any of the P_j's. She replaces the above
5219 where 0 is the 8-byte all-zeros block. Bob will decrypt under DES-CBC,
5220 recovering the blocks
5223 Q_1 = DES-decrypt(K, C_1) xor K = P_1
5224 Q_2 = DES-decrypt(K, C_2) xor C_1 = (some unimportant junk)
5225 Q_3 = DES-decrypt(K, C_1) xor 0 = P_1 xor K
5226 Bob gets this garbage-looking message Q_1,Q_2,Q_3 which Mary recovers
5227 (under the chosen-ciphertext assumption: this is like a known-plaintext
5228 attack, which isn't too implausible). Notice that Mary can recover K by
5230 so after this one simple active attack, Mary gets the key back!
5232 So, if you must use a fixed IV, don't use the key-- use 0 or something
5233 like that. Even better, don't use a fixed IV-- use the DES encryption
5234 of a counter, or something like that.
5237 @node The Keytab Binary File Format
5238 @section The Keytab Binary File Format
5240 The keytab file format is described in the file @file{keytab.txt},
5241 included in verbatim below.
5243 @verbatiminclude keytab.txt
5245 @node The Credential Cache Binary File Format
5246 @section The Credential Cache Binary File Format
5248 The credential cache file format is described in the file
5249 @file{keytab.txt}, included in verbatim below.
5251 @verbatiminclude ccache.txt
5253 @node Copying Information
5254 @appendix Copying Information
5257 * GNU Free Documentation License:: License for copying this manual.
5258 * GNU GPL:: License for copying the programs.
5264 @node Function and Data Index
5265 @unnumbered Function and Data Index
5270 @unnumbered Concept Index