| blob | 6accf6bb9b3839453de6c2308988963ceb623be0 |
1 \input texinfo @c -*- Texinfo -*-
2 @c Copyright (C) 2002, 2003 Simon Josefsson
3 @c
4 @c This file is part of the shishi
5 @c Permission is granted to copy, distribute and/or modify this document
6 @c under the terms of the GNU Free Documentation License, Version 1.1
7 @c or any later version published by the Free Software Foundation;
8 @c with the Invariant Sections being with no Invariant Sections, with the
9 @c no Front-Cover Texts, and with the no Back-Cover Texts.
10 @c A copy of the license is included in the section entitled ``GNU
11 @c Free Documentation License'' in the file 'fdl.texi'.
12 @c
13 @setfilename shishi.info
14 @include version.texi
15 @settitle The Shishi Manual
17 @c Unify some of the indices.
18 @syncodeindex tp fn
19 @syncodeindex pg fn
21 @copying
22 This is @cite{The Shishi Manual}, last updated @value{UPDATED}, for
23 Version @value{VERSION} of Shishi.
25 Copyright @copyright{} 2002, 2003 Simon Josefsson.
27 @quotation
28 Permission is granted to copy, distribute and/or modify this document
29 under the terms of the GNU Free Documentation License, Version 1.1 or
30 any later version published by the Free Software Foundation; with no
31 Invariant Sections, with the Front-Cover texts being ``A GNU Manual,''
32 and with the Back-Cover Texts as in (a) below. A copy of the license
33 is included in the section entitled ``GNU Free Documentation
34 License.''
36 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and
37 modify this GNU Manual, like GNU software. Copies published by the
38 Free Software Foundation raise funds for GNU development.''
39 @end quotation
40 @end copying
42 @dircategory Net Utilities
43 @direntry
44 * shishi: (shishi). An RFC 1510 implementation
45 @end direntry
47 @titlepage
48 @title The Shishi Manual
49 @subtitle for version @value{VERSION}, @value{UPDATED}
50 @author Simon Josefsson (@email{bug-shishi@@josefsson.org})
51 @page
52 @vskip 0pt plus 1filll
53 @insertcopying
54 @end titlepage
56 @contents
58 @ifnottex
59 @node Top
60 @top Shishi
61 @insertcopying
62 @end ifnottex
64 @menu
65 * Introduction:: How to use this manual.
66 * User Manual:: Using Shishi as end-user.
67 * Administration Manual:: Administrating server aspects of Shishi.
68 * Programming Manual:: Calling Shishi from a programming language.
69 * Acknowledgements:: Whom to blame.
71 Appendices
73 * Copying This Manual:: How you can copy and share this manual.
74 * Copying:: How you can copy and share the source.
76 Indices
78 * Concept Index:: Index of concepts and programs.
79 * Function and Data Index:: Index of functions, variables and data types.
80 @end menu
83 @c **********************************************************
84 @c ******************** Introduction **********************
85 @c **********************************************************
86 @node Introduction
87 @chapter Introduction
89 Shishi implements the RFC 1510 network security system, also known as
90 Kerberos 5.
92 @menu
93 * Getting Started::
94 * Features and Status::
95 * Overview::
96 * Cryptographic Overview::
97 * Supported Platforms::
98 * Bug Reports::
99 @end menu
101 @node Getting Started
102 @section Getting Started
104 This manual documents the Shishi application and library programming
105 interface. All commands, functions and data types provided by Shishi
106 are explained.
108 The reader is assumed to possess basic familiarity with network
109 security and the RFC 1510 security system.
111 This manual can be used in several ways. If read from the beginning
112 to the end, it gives a good introduction into the library and how it
113 can be used in an application. Forward references are included where
114 necessary. Later on, the manual can be used as a reference manual to
115 get just the information needed about any particular interface of the
116 library. Experienced programmers might want to start looking at the
117 examples at the end of the manual, and then only read up those parts
118 of the interface which are unclear.
120 @node Features and Status
121 @section Features and Status
123 Shishi might have a couple of advantages over other packages doing a
124 similar job.
126 @table @asis
127 @item It's Free Software
128 Anybody can use, modify, and redistribute it under the terms of the GNU
129 General Public License (@pxref{Copying}).
131 @item It's thread-safe
132 The library uses no global variables.
134 @item It's internationalized
135 It handles non-ASCII username and passwords and user visible strings
136 used in the library (error messages) can be translated into the users'
137 language.
139 @item It's portable
140 It should work on all Unix like operating systems, including Windows.
142 @end table
144 Shishi is far from feature complete, it is not even a full RFC 1510
145 implementation yet. However, some basic functionality is implemented.
146 A few implemented feature are mentioned below.
148 @itemize @bullet
150 @item Initial authentication (AS) from raw key or password.
151 This step is typically used to acquire a ticket granting ticket and,
152 less commonly, a server ticket.
154 @item Subsequent authentication (TGS).
155 This step is typically used to acquire a server ticket, by
156 authenticating yourself using the ticket granting ticket.
158 @item Client-Server authentication (AP).
159 This step is used by clients and servers to prove to each other who
160 they are, using negotiated tickets.
162 @item Integrity protected communication (SAFE).
163 This step is used by clients and servers to exchange integrity
164 protected data with each other. The key is typically agreed on using
165 the Client-Server authentication step.
167 @item Ticket cache, supporting multiple principals and realms.
168 As tickets have a life time of typically several hours, they are
169 managed in disk files. There can be multiple ticket caches, and each
170 ticket cache can store tickets for multiple clients (users), servers,
171 encryption types, etc. Functionality is provided for locating the
172 proper ticket for every use.
174 @item Most standard cryptographic primitives.
175 The believed most secure algorithms are supported
176 (@pxref{Cryptographic Overview}).
178 @item Telnet client and server.
179 This is used to remotely login to other machines, after authenticating
180 yourself with a ticket.
182 @item PAM module.
183 This is used to login locally on a machine.
185 @item KDC addresses located using DNS SRV RRs.
187 @end itemize
189 The following table summarize what the current objectives are (i.e.,
190 the todo list) and an estimate on how long it will take to implement
191 the feature. If you like to start working on anything, please let me
192 know so work duplication can be avoided.
194 @itemize @bullet
196 @item Pre-authentication support (week).
198 @item Cross-realm support (week).
200 @item Session keys in AP (week).
202 @item PKINIT (use libksba, weeks)
204 @item Finish GSSAPI support via GPL GSS (weeks)
205 Shishi will not support GSS, but a separate project ``GPL GSS'' is
206 under way to produce a generic GSS implementation, and it will use
207 Shishi to implement the Kerberos 5 mechanism.
209 @item Port to cyclone (cyclone need to mature first)
211 @item Modularize ASN.1 library so it can be replaced (days).
212 Almost done, all ASN.1 functionality is found in lib/asn1.c.
214 @item Modularize Crypto library so it can be replaced (days).
215 Nettle and libgcrypt are currently supported, but not via an abstract
216 interface. All crypto operations has been isolated into
217 lib/crypto*.c.
219 @item KDC (initiated, weeks)
221 @item Set/Change password protocol (weeks?)
223 @item Port applications to use Shishi (indefinite)
225 @item Improve documentation
227 @item Improve internationalization
229 @item Add AP-REQ replay cache (week).
231 @end itemize
233 @node Overview
234 @section Overview
236 This section describes RFC 1510 from a protocol point of
237 view@footnote{The text is a lightly adapted version of the
238 introduction section from RFC 1510 by J. Kohl and C. Neuman, September
239 1993, unclear copyrights, but presumably owned by The Internet
240 Society.}.
242 Kerberos provides a means of verifying the identities of principals,
243 (e.g., a workstation user or a network server) on an open
244 (unprotected) network. This is accomplished without relying on
245 authentication by the host operating system, without basing trust on
246 host addresses, without requiring physical security of all the hosts
247 on the network, and under the assumption that packets traveling along
248 the network can be read, modified, and inserted at will. (Note,
249 however, that many applications use Kerberos' functions only upon the
250 initiation of a stream-based network connection, and assume the
251 absence of any "hijackers" who might subvert such a connection. Such
252 use implicitly trusts the host addresses involved.) Kerberos performs
253 authentication under these conditions as a trusted third- party
254 authentication service by using conventional cryptography, i.e.,
255 shared secret key. (shared secret key - Secret and private are often
256 used interchangeably in the literature. In our usage, it takes two
257 (or more) to share a secret, thus a shared DES key is a secret key.
258 Something is only private when no one but its owner knows it. Thus,
259 in public key cryptosystems, one has a public and a private key.)
261 The authentication process proceeds as follows: A client sends a
262 request to the authentication server (AS) requesting "credentials" for
263 a given server. The AS responds with these credentials, encrypted in
264 the client's key. The credentials consist of 1) a "ticket" for the
265 server and 2) a temporary encryption key (often called a "session
266 key"). The client transmits the ticket (which contains the client's
267 identity and a copy of the session key, all encrypted in the server's
268 key) to the server. The session key (now shared by the client and
269 server) is used to authenticate the client, and may optionally be used
270 to authenticate the server. It may also be used to encrypt further
271 communication between the two parties or to exchange a separate
272 sub-session key to be used to encrypt further communication.
274 The implementation consists of one or more authentication servers
275 running on physically secure hosts. The authentication servers
276 maintain a database of principals (i.e., users and servers) and their
277 secret keys. Code libraries provide encryption and implement the
278 Kerberos protocol. In order to add authentication to its
279 transactions, a typical network application adds one or two calls to
280 the Kerberos library, which results in the transmission of the
281 necessary messages to achieve authentication.
283 The Kerberos protocol consists of several sub-protocols (or
284 exchanges). There are two methods by which a client can ask a
285 Kerberos server for credentials. In the first approach, the client
286 sends a cleartext request for a ticket for the desired server to the
287 AS. The reply is sent encrypted in the client's secret key. Usually
288 this request is for a ticket-granting ticket (TGT) which can later be
289 used with the ticket-granting server (TGS). In the second method, the
290 client sends a request to the TGS. The client sends the TGT to the
291 TGS in the same manner as if it were contacting any other application
292 server which requires Kerberos credentials. The reply is encrypted in
293 the session key from the TGT.
295 Once obtained, credentials may be used to verify the identity of the
296 principals in a transaction, to ensure the integrity of messages
297 exchanged between them, or to preserve privacy of the messages. The
298 application is free to choose whatever protection may be necessary.
300 To verify the identities of the principals in a transaction, the
301 client transmits the ticket to the server. Since the ticket is sent
302 "in the clear" (parts of it are encrypted, but this encryption doesn't
303 thwart replay) and might be intercepted and reused by an attacker,
304 additional information is sent to prove that the message was
305 originated by the principal to whom the ticket was issued. This
306 information (called the authenticator) is encrypted in the session
307 key, and includes a timestamp. The timestamp proves that the message
308 was recently generated and is not a replay. Encrypting the
309 authenticator in the session key proves that it was generated by a
310 party possessing the session key. Since no one except the requesting
311 principal and the server know the session key (it is never sent over
312 the network in the clear) this guarantees the identity of the client.
314 The integrity of the messages exchanged between principals can also be
315 guaranteed using the session key (passed in the ticket and contained
316 in the credentials). This approach provides detection of both replay
317 attacks and message stream modification attacks. It is accomplished
318 by generating and transmitting a collision-proof checksum (elsewhere
319 called a hash or digest function) of the client's message, keyed with
320 the session key. Privacy and integrity of the messages exchanged
321 between principals can be secured by encrypting the data to be passed
322 using the session key passed in the ticket, and contained in the
323 credentials.
325 @node Cryptographic Overview
326 @section Cryptographic Overview
328 Shishi implements several of the standard cryptographic primitives.
329 Here are the names of the supported encryption suites, with some notes
330 on their status and there associated checksum suite. They are ordered
331 by increased security as perceived by the author.
333 @cindex DES
334 @cindex 3DES
335 @cindex AES
337 @table @code
339 @item NULL
341 @code{NULL} is a dummy encryption suite for debugging. Encryption and
342 decryption are identity functions. No integrity protection. It is
343 weak. It is associated with the @code{NULL} checksum.
345 @item des-cbc-crc
347 @code{des-cbc-crc} is DES encryption and decryption with 56 bit keys
348 and 8 byte blocks in CBC mode. The keys can be derived from passwords
349 by an obscure application specific algorithm. Data is integrity
350 protected with an unkeyed but encrypted @code{CRC32}-like checksum.
351 It is weak. It is associated with the @code{rsa-md5-des} checksum.
353 @item des-cbc-md4
355 @code{des-cbc-md4} is DES encryption and decryption with 56 bit keys
356 and 8 byte blocks in CBC mode. The keys can be derived from passwords
357 by an obscure application specific algorithm. Data is integrity
358 protected with an unkeyed but encrypted MD4 hash. It is weak. It is
359 associated with the @code{rsa-md4-des} checksum.
361 @item des-cbc-md5
363 @code{des-cbc-md5} is DES encryption and decryption with 56 bit keys
364 and 8 byte blocks in CBC mode. The keys can be derived from passwords
365 by an obscure application specific algorithm. Data is integrity
366 protected with an unkeyed but encrypted MD5 hash. It is weak. It is
367 associated with the @code{rsa-md5-des} checksum. This is the
368 strongest RFC 1510 interoperable mechanism.
370 @item des3-cbc-sha1-kd
372 @code{des3-cbc-sha1-kd} is DES encryption and decryption with three 56
373 bit keys (effective key size 112 bits) and 8 byte blocks in CBC
374 mode. The keys can be derived from passwords by a algorithm based on
375 the paper "A Better Key Schedule For DES-like Ciphers"
376 @footnote{@url{http://www.research.att.com/~smb/papers/ides.pdf}} by
377 Uri Blumenthal and Steven M. Bellovin (it is not clear if the
378 algorithm, and the way it is used, is used by any other protocols,
379 although it seems unlikely). Data is integrity protected with a keyed
380 (HMAC) SHA1 hash. It has no security proof, but is assumed to provide
381 adequate security in the sense that knowledge on how to crack it is
382 not known to the public. It is associated with the
383 @code{hmac-sha1-des3-kd} checksum.
385 @item aes128-cts-hmac-sha1-96
386 @item aes256-cts-hmac-sha1-96.
388 @code{aes128-cts-hmac-sha1-96} and @code{aes256-cts-hmac-sha1-96} is
389 AES encryption and decryption with 128 bit and 256 bit key,
390 respectively, and 16 byte blocks in CBC mode with Cipher Text
391 Stealing. Cipher Text Stealing means data length of encrypted data is
392 preserved (pure CBC add up to 7 pad characters). The keys can be
393 derived from passwords with RSA Laboratories PKCS#5 Password Based Key
394 Derivation Function
395 2@footnote{@url{http://www.rsasecurity.com/rsalabs/pkcs/pkcs-5/}},
396 which is allegedly provably secure in a random oracle model. Data is
397 integrity protected with a keyed (HMAC) SHA1 hash truncated to 96
398 bits. There is no security proof, but the schemes are assumed to
399 provide good security, but has, as AES itself, yet to receive the test
400 of time. It is associated with the @code{hmac-sha1-96-aes128} and
401 @code{hmac-sha1-96-aes256} checksums, respectively.
403 @end table
405 The protocol do not include any way to negotiate which checksum
406 mechanisms to use, so in most cases the associated checksum will be
407 used. However, checksum mechanisms can be used with other encryption
408 mechanisms, as long as they are compatible in terms of key format etc.
409 Here are the names of the supported checksum mechanisms, with some
410 notes on their status and the compatible encryption mechanisms. They
411 are ordered by increased security as perceived by the author.
413 @table @code
415 @item NULL
417 @code{NULL} is a dummy checksum suite for debugging. It provides no
418 integrity. It is weak. It is compatible with the @code{NULL}
419 encryption mechanism.
421 @item rsa-md4-des
423 @code{rsa-md4-des} is a DES CBC encryption of one block of random data
424 and a unkeyed MD4 hash computed over the random data and the message
425 to integrity protect. The key used is derived from the base protocol
426 key by XOR with a constant. It is weak. It is compatible with the
427 @code{des-cbc-crc}, @code{des-cbc-md4}, @code{des-cbc-md5} encryption
428 mechanisms.
430 @item rsa-md5-des
432 @code{rsa-md5-des} is a DES CBC encryption of one block of random data
433 and a unkeyed MD5 hash computed over the random data and the message
434 to integrity protect. The key used is derived from the base protocol
435 key by XOR with a constant. It is weak. It is compatible with the
436 @code{des-cbc-crc}, @code{des-cbc-md4}, @code{des-cbc-md5} encryption
437 mechanisms.
439 @item hmac-sha1-des3-kd
441 @code{hmac-sha1-des3-kd} is a keyed (HMAC) SHA1 hash computed over the
442 message. The key is derived from the base protocol by the simplified
443 key derivation function (similar to the password key derivation
444 functions of @code{des3-cbc-sha1-kd}). It has no security proof, but
445 is assumed to provide good security. It is compatible with the
446 @code{des3-cbc-sha1-kd} encryption mechanism.
448 @item hmac-sha1-96-aes128
449 @item hmac-sha1-96-aes256
451 @code{hmac-sha1-96-aes*} are keyed (HMAC) SHA1 hashes computed over
452 the message and then truncated to 96 bits. The key is derived from
453 the base protocol by the simplified key derivation function (similar
454 to the password key derivation functions of @code{des3-cbc-sha1-kd}).
455 It has no security proof, but is assumed to provide good security. It
456 is compatible with the @code{des3-cbc-sha1-kd} encryption mechanism.
458 @end table
461 @node Supported Platforms
462 @section Supported Platforms
464 Shishi has at some point in time been tested on the following
465 platforms.
467 @enumerate
469 @item Debian GNU/Linux 3.0r0 (Woody)
470 @cindex Debian
472 GCC 2.95.4 and GNU Make. alphaev67-unknown-linux-gnu,
473 alphaev6-unknown-linux-gnu, hppa64-unknown-linux-gnu,
474 i686-pc-linux-gnu, ia64-unknown-linux-gnu.
476 @item Tru64 UNIX
477 @cindex Tru64
479 Tru64 UNIX C compiler and Tru64 Make. alphaev68-dec-osf5.1.
481 @item SuSE Linux 7.1
482 @cindex SuSE
484 GCC 2.96 and GNU Make. alphaev67-unknown-linux-gnu.
486 @item SuSE Linux 7.2a
487 @cindex SuSE Linux
489 GCC 3.0 and GNU Make. ia64-unknown-linux-gnu.
491 @item RedHat Linux 7.2
492 @cindex RedHat
494 GCC 2.96 and GNU Make. i686-pc-linux-gnu.
496 @item RedHat Linux 8.0
497 @cindex RedHat
499 GCC 3.2 and GNU Make. i686-pc-linux-gnu.
501 @item Red Hat Advanced Server 2.1
502 @cindex RedHat
504 GCC 2.96 and GNU Make. ia64-unknown-linux-gnu (Intel Madison).
506 @c @item IRIX 6.5
507 @c @cindex IRIX
508 @c
509 @c mips-sgi-irix6.5, MIPS C compiler, IRIX Make.
511 @c @item AIX 4.3.2
512 @c @cindex AIX
513 @c
514 @c rs6000-ibm-aix4.3.2.0, IBM C for AIX compiler, AIX Make.
516 @c @item Microsoft Windows 2000
517 @c @cindex Windows
518 @c
519 @c GCC 2.95.2-6, GNU make. i686-pc-cygwin
521 @c @item HP-UX 11.11
522 @c @cindex HP-UX
523 @c
524 @c HP-UX C compiler and HP Make. hppa2.0w-hp-hpux11.11.
526 @item SUN Solaris 2.8
527 @cindex Solaris
529 Sun WorkShop Compiler C 6.0 and SUN Make. sparc-sun-solaris2.8.
531 @item NetBSD 1.6
532 @cindex NetBSD
534 GCC 2.95.3 and GNU Make. alpha-unknown-netbsd1.6,
535 i386-unknown-netbsdelf1.6.
537 @item OpenBSD 3.1
538 @cindex OpenBSD
540 GCC 2.95.3 and GNU Make.
541 @c alpha-unknown-openbsd3.1, (alignment problems)
542 i386-unknown-openbsd3.1.
544 @item FreeBSD 4.7
545 @cindex FreeBSD
547 GCC 2.95.4 and GNU Make. alpha-unknown-freebsd4.7,
548 i386-unknown-freebsd4.7.
550 @end enumerate
552 If you use Shishi on, or port Shishi to, a new platform please report
553 it to the author (@pxref{Bug Reports}).
555 @node Bug Reports
556 @section Bug Reports
557 @cindex Reporting Bugs
559 If you think you have found a bug in Shishi, please investigate it and
560 report it.
562 @itemize @bullet
564 @item Please make sure that the bug is really in Shishi, and
565 preferably also check that it hasn't already been fixed in the latest
566 version.
568 @item You have to send us a test case that makes it possible for us to
569 reproduce the bug.
571 @item You also have to explain what is wrong; if you get a crash, or
572 if the results printed are not good and in that case, in what way.
573 Make sure that the bug report includes all information you would need
574 to fix this kind of bug for someone else.
576 @end itemize
578 Please make an effort to produce a self-contained report, with
579 something definite that can be tested or debugged. Vague queries or
580 piecemeal messages are difficult to act on and don't help the
581 development effort.
583 If your bug report is good, we will do our best to help you to get a
584 corrected version of the software; if the bug report is poor, we won't
585 do anything about it (apart from asking you to send better bug
586 reports).
588 If you think something in this manual is unclear, or downright
589 incorrect, or if the language needs to be improved, please also send a
590 note.
592 Send your bug report to:
594 @center @samp{bug-shishi@@josefsson.org}
597 @c **********************************************************
598 @c ******************** User Manual **********************
599 @c **********************************************************
600 @node User Manual
601 @chapter User Manual
602 @cindex End-user Shishi usage
604 Usually Shishi interacts with you to get some initial authentication
605 information like a password, and then contacts a server to receive a
606 so called ticket granting ticket. From now on, you rarely interacts
607 with Shishi directly. Applications that needs security services
608 instruct the Shishi library to use the ticket granting ticket to get
609 new tickets for various servers. An example could be if you log on to
610 a host remotely via @samp{telnet}. The host usually requires
611 authentication before permitting you in. The @samp{telnet} client
612 uses the ticket granting ticket to get a ticket for the server, and
613 then use this ticket to authenticate you against the server (typically
614 the server is also authenticated to you). You perform the initial
615 authentication by typing @command{shishi} at the prompt. Sometimes it
616 is necessary to supply options telling Shishi what your principal name
617 (user name in the Kerberos realm) or realm is. In the example, I
618 specify the client name @code{simon@@JOSEFSSON.ORG}.
620 @example
621 @cartouche
622 $ shishi simon@@JOSEFSSON.ORG
623 Enter password for `jas@@JOSEFSSON.ORG':
624 jas@@JOSEFSSON.ORG:
625 Authtime: Fri Aug 15 04:44:49 2003
626 Endtime: Fri Aug 15 05:01:29 2003
627 Server: krbtgt/JOSEFSSON.ORG key des3-cbc-sha1-kd (16)
628 Ticket key: des3-cbc-sha1-kd (16) protected by des3-cbc-sha1-kd (16)
629 Ticket flags: INITIAL (512)
630 $
631 @end cartouche
632 @end example
634 As you can see, Shishi also prints a short description of the ticket
635 received.
637 A logical next step is to display all tickets you have received (by
638 the way, the tickets are usually stored as text in
639 @file{~/.shishi/tickets}). This is achieved by typing @command{shishi
640 --list}.
642 @example
643 @cartouche
644 $ shishi --list
645 Tickets in `/home/jas/.shishi/tickets':
647 jas@@JOSEFSSON.ORG:
648 Authtime: Fri Aug 15 04:49:46 2003
649 Endtime: Fri Aug 15 05:06:26 2003
650 Server: krbtgt/JOSEFSSON.ORG key des-cbc-md5 (3)
651 Ticket key: des-cbc-md5 (3) protected by des-cbc-md5 (3)
652 Ticket flags: INITIAL (512)
654 jas@@JOSEFSSON.ORG:
655 Authtime: Fri Aug 15 04:49:46 2003
656 Starttime: Fri Aug 15 04:49:49 2003
657 Endtime: Fri Aug 15 05:06:26 2003
658 Server: host/latte.josefsson.org key des-cbc-md5 (3)
659 Ticket key: des-cbc-md5 (3) protected by des-cbc-md5 (3)
661 2 tickets found.
662 $
663 @end cartouche
664 @end example
666 As you can see, I had a ticket for the server
667 @samp{host/latte.josefsson.org} which was generated by
668 @samp{telnet}:ing to that host.
670 If, for some reason, you want to manually get a ticket for a specific
671 server, you can use the @command{shishi --server-name} command.
672 Normally, however, the application that uses Shishi will take care of
673 getting a ticket for the appropriate server, so you normally wouldn't
674 need this command.
676 @example
677 @cartouche
678 $ shishi --server-name=user/billg --encryption-type=des-cbc-md4
679 jas@@JOSEFSSON.ORG:
680 Authtime: Fri Aug 15 04:49:46 2003
681 Starttime: Fri Aug 15 04:54:33 2003
682 Endtime: Fri Aug 15 05:06:26 2003
683 Server: user/billg key des-cbc-md4 (2)
684 Ticket key: des-cbc-md4 (2) protected by des-cbc-md5 (3)
685 $
686 @end cartouche
687 @end example
689 As you can see, I acquired a ticket for @samp{user/billg} with a
690 @samp{des-cbc-md4} (@pxref{Cryptographic Overview}) encryption key
691 specified with the @samp{--encryption-type} parameter.
693 To wrap up this introduction, lets see how you can remove tickets.
694 You may want to do this if you leave your terminal for lunch or
695 similar, and don't want someone to be able to copy the file and then
696 use your credentials. Note that this only destroy the tickets
697 locally, it does not contact any server and tell it that these
698 credentials are no longer valid. So if someone stole your ticket
699 file, you must contact your administrator and have them reset your
700 account, simply using this parameter is not sufficient.
702 @example
703 @cartouche
704 $ shishi --server-name=imap/latte.josefsson.org --destroy
705 1 ticket removed.
706 $ shishi --server-name=foobar --destroy
707 No tickets removed.
708 $ shishi --destroy
709 3 tickets removed.
710 $
711 @end cartouche
712 @end example
714 Below follows a list of all parameters.
716 Mandatory or optional arguments to long options are also mandatory or optional
717 for any corresponding short options.
719 @example
720 Usage: shishi [OPTION...] [NAME] [OPTION...]
721 or: shishi [OPTION...] --list [--server-name=NAME]
722 or: shishi [OPTION...] --destroy [--server-name=NAME]
723 or: shishi [OPTION...] --crypto [CRYPTO-OPTION...]
724 or: shishi [OPTION...]
726 --client-name=NAME Client name. Default is login username. Only for
727 AS.
728 -d, --destroy Destroy tickets in local cache, subject to
729 --server-name limiting.
730 -e, --endtime=STRING Specify when ticket validity should expire. The
731 time syntax may be relative (to the start time),
732 such as "20 hours", or absolute, such as
733 "2001-02-03 04:05:06 CET". The default is 8 hours
734 after the start time.
735 -E, --encryption-type=ETYPE,[ETYPE...]
736 Encryption types to use. ETYPE is either
737 registered name or integer.
738 --force-as Force AS mode. Default is to use TGS iff a TGT is
739 found.
740 --force-tgs Force TGS mode. Default is to use TGS iff a TGT is
741 found.
742 --key-value=KEY Cipher key to decrypt response (discouraged).
743 -l, --list List tickets in local cache, subject to
744 --server-name limiting.
745 --password=PASSWORD Password to decrypt response (discouraged). Only
746 for AS.
747 --realm=REALM Realm of server. Default is DNS domain of local
748 host. For AS, this also indicates realm of client.
750 --renew-till=STRING Specify renewable life of ticket. Implies
751 --renewable. Accepts same time syntax as
752 --endtime. If --renewable is specified, the
753 default is 1 week after the start time.
754 --renewable Get a renewable ticket.
755 -R, --renew Renew ticket. Use --server-name to specify
756 ticket, default is the most recent renewable
757 ticket granting ticket for the default realm.
758 --server=[FAMILY:]ADDRESS:SERVICE/TYPE
759 Send all requests to HOST instead of using normal
760 logic to locate KDC addresses (discouraged).
761 --server-name=NAME Server name. Default is "krbtgt/REALM" where REALM
762 is server realm (see --realm).
763 -s, --starttime=STRING Specify when ticket should start to be valid.
764 Accepts same time syntax as --endtime. The default
765 is to become valid immediately.
766 --ticket-granter=NAME Service name in ticket to use for authenticating
767 request. Only for TGS. Defaults to
768 "krbtgt/REALM@@REALM" where REALM is server realm
769 (see --realm).
771 Options for low-level cryptography (CRYPTO-OPTIONS):
772 --algorithm=ALGORITHM Cipher algorithm, expressed either as the etype
773 integer or the registered name.
774 --client-name=NAME Username. Default is login name.
775 --decrypt Decrypt data.
776 --encrypt Encrypt data.
777 --key-usage=KEYUSAGE Encrypt or decrypt using specified key usage.
778 Default is 0, which means no key derivation are
779 performed.
780 --key-value=KEY Base64 encoded key value.
781 --key-version=INTEGER Version number of key.
782 --parameter=STRING String-to-key parameter to use when --password is
783 specified. This data is specific for each
784 encryption algorithm and rarely needed.
785 --password=PASSWORD Password used to generate key. --client-name and
786 --realm also modify the computed key value.
787 --random Generate key from random data.
788 --read-data-file=[TYPE,]FILE
789 Read data from FILE in TYPE, BASE64, HEX or BINARY
790 (default).
791 --read-key-file=FILE Read cipher key from FILE
792 --realm=REALM Realm of principal. Defaults to DNS domain of
793 local host.
794 --salt=SALT Salt to use when --password is specified. Defaults
795 to using theusername (--client-name) and realm
796 (--realm).
797 --write-data-file=[TYPE,]FILE
798 Write data to FILE in TYPE, BASE64, HEX or BINARY
799 (default).
800 --write-key-file=FILE Append cipher key to FILE
802 Other options:
803 --configuration-file=FILE Read user configuration from file. Default
804 is ~/.shishi/config.
805 -c, --ticket-file=FILE Read tickets from FILE. Default is
806 $HOME/.shishi/tickets.
807 -o, --library-options=STRING Parse STRING as a configuration file
808 statement.
809 -q, --quiet, --silent Don't produce any output.
810 --system-configuration-file=FILE
811 Read system wide configuration from file. Default
812 is /usr/local/etc/shishi.conf.
813 --ticket-write-file=FILE Write tickets to FILE. Default is to write
814 them back to ticket file.
815 -v, --verbose Produce verbose output.
816 --verbose-library Produce verbose output in the library.
817 NAME Set client name and realm from NAME. The
818 --client-name and --realm can be used to override
819 part of NAME.
820 -?, --help Give this help list
821 --usage Give a short usage message
822 -V, --version Print program version
823 @end example
825 @c **********************************************************
826 @c **************** Administration Manual *****************
827 @c **********************************************************
828 @node Administration Manual
829 @chapter Administration Manual
831 TBW.
834 @c **********************************************************
835 @c *************** Programming Manual *********************
836 @c **********************************************************
837 @node Programming Manual
838 @chapter Programming Manual
839 @cindex Application Programming Interface (API)
841 This chapter describes all the publicly available functions in the
842 library.
844 @menu
845 * Preparation:: What you should do before using the library.
846 * Initialization Functions:: Creating library handle, configuration file.
847 * Ticket Set Functions:: High-level ticket management functions.
848 * AP-REQ and AP-REP Functions:: Client/Server authentication functions.
849 * SAFE and PRIV Functions:: Client/Server session data functions.
850 * Ticket Functions:: Medium-level ticket manipulation functions.
851 * AS Functions:: Medium-level initial authentication functions.
852 * TGS Functions:: Medium-level authentication functions.
853 * Ticket (ASN.1) Functions:: Low-level Ticket functions.
854 * AS/TGS Functions:: Low-level KDC functions; AS and TGS.
855 * Authenticator Functions:: Low-level authenticator functions.
856 * Cryptographic Functions:: Low-level cryptographic functions.
857 * Utility Functions:: Utilities for use in the global context.
858 * Error Handling:: Error codes and such.
859 * Examples:: Example code.
860 * Generic Security Service:: If you want to use the GSS API instead.
861 @end menu
863 @node Preparation
864 @section Preparation
866 To use `Libshishi', you have to perform some changes to your sources
867 and the build system. The necessary changes are small and explained
868 in the following sections. At the end of this chapter, it is
869 described how the library is initialized, and how the requirements of
870 the library are verified.
872 A faster way to find out how to adapt your application for use with
873 `Libshishi' may be to look at the examples at the end of this manual
874 (@pxref{Examples}).
876 @menu
877 * Header::
878 * Initialization::
879 * Version Check::
880 * Building the source::
881 @end menu
883 @node Header
884 @subsection Header
886 All interfaces (data types and functions) of the library are defined
887 in the header file `shishi.h'. You must include this in all programs
888 using the library, either directly or through some other header file,
889 like this:
891 @example
892 #include <shishi.h>
893 @end example
895 The name space of `Libshishi' is @code{shishi_*} for function names,
896 @code{Shishi*} for data types and @code{SHISHI_*} for other symbols. In
897 addition the same name prefixes with one prepended underscore are
898 reserved for internal use and should never be used by an application.
900 @node Initialization
901 @subsection Initialization
903 `Libshishi' must be initialized before it can be used. The library is
904 initialized by calling @code{shishi_init()} (@pxref{Initialization
905 Functions}). The resources allocated by the initialization process
906 can be released if the application no longer has a need to call
907 `Libshishi' functions, this is done by calling @code{shishi_done()}.
909 In order to take advantage of the internationalisation features in
910 `Libshishi', such as translated error messages, the application must
911 set the current locale using @code{setlocale()} before initializing
912 `Libshishi'.
914 @node Version Check
915 @subsection Version Check
917 It is often desirable to check that the version of `Libshishi' used is
918 indeed one which fits all requirements. Even with binary
919 compatibility new features may have been introduced but due to problem
920 with the dynamic linker an old version is actually used. So you may
921 want to check that the version is okay right after program startup.
923 @include shishi-api-version.texi
925 The normal way to use the function is to put something similar to the
926 following early in your @code{main()}:
928 @example
929 if (!shishi_check_version (SHISHI_VERSION))
930 @{
931 printf ("shishi_check_version() failed:\n"
932 "Header file incompatible with shared library.\n");
933 exit(1);
934 @}
935 @end example
937 @node Building the source
938 @subsection Building the source
939 @cindex Compiling your application
941 If you want to compile a source file including the `shishi.h' header
942 file, you must make sure that the compiler can find it in the
943 directory hierarchy. This is accomplished by adding the path to the
944 directory in which the header file is located to the compilers include
945 file search path (via the @option{-I} option).
947 However, the path to the include file is determined at the time the
948 source is configured. To solve this problem, `Libshishi' uses the
949 external package @command{pkg-config} that knows the path to the
950 include file and other configuration options. The options that need
951 to be added to the compiler invocation at compile time are output by
952 the @option{--cflags} option to @command{pkg-config shishi}. The
953 following example shows how it can be used at the command line:
955 @example
956 gcc -c foo.c `pkg-config shishi --cflags`
957 @end example
959 Adding the output of @samp{pkg-config shishi --cflags} to the
960 compilers command line will ensure that the compiler can find the
961 `Libshishi' header file.
963 A similar problem occurs when linking the program with the library.
964 Again, the compiler has to find the library files. For this to work,
965 the path to the library files has to be added to the library search path
966 (via the @option{-L} option). For this, the option @option{--libs} to
967 @command{pkg-config shishi} can be used. For convenience, this option
968 also outputs all other options that are required to link the program
969 with the `Libshishi' libararies (in particular, the @samp{-lshishi}
970 option). The example shows how to link @file{foo.o} with the `Libshishi'
971 library to a program @command{foo}.
973 @example
974 gcc -o foo foo.o `pkg-config shishi --libs`
975 @end example
977 Of course you can also combine both examples to a single command by
978 specifying both options to @command{pkg-config}:
980 @example
981 gcc -o foo foo.c `pkg-config shishi --cflags --libs`
982 @end example
984 @node Initialization Functions
985 @section Initialization Functions
987 @include shishi-api-init.texi
990 @node Ticket Set Functions
991 @section Ticket Set Functions
993 A ``ticket set'' is, as the name implies, a collection of tickets.
994 Functions are provided to read tickets from file into a ticket set, to
995 query number of tickets in the set, to extract a given ticket from the
996 set, to search the ticket set for tickets matching certain criterium,
997 to write the ticket set to a file, etc. High level functions for
998 performing a initial authentication (@pxref{AS Functions}) or
999 subsequent authentication (@pxref{TGS Functions}) and storing the new
1000 ticket in the ticket set are also provided.
1002 To manipulate each individual ticket, @xref{Ticket Functions}. For
1003 low-level ASN.1 manipulation see @xref{Ticket (ASN.1) Functions}.
1005 @include shishi-api-tkts.texi
1008 @node AP-REQ and AP-REP Functions
1009 @section AP-REQ and AP-REP Functions
1011 The ``AP-REQ'' and ``AP-REP'' are ASN.1 structures used by application
1012 client and servers to prove to each other who they are. The
1013 structures contain auxilliary information, together with an
1014 authenticator (@pxref{Authenticator Functions}) which is the real
1015 cryptographic proof. The following illustrates the AP-REQ and AP-REP
1016 ASN.1 structures.
1018 @verbatim
1019 AP-REQ ::= [APPLICATION 14] SEQUENCE {
1020 pvno [0] INTEGER (5),
1021 msg-type [1] INTEGER (14),
1022 ap-options [2] APOptions,
1023 ticket [3] Ticket,
1024 authenticator [4] EncryptedData {Authenticator,
1025 { keyuse-pa-TGSReq-authenticator
1026 | keyuse-APReq-authenticator }}
1027 }
1029 AP-REP ::= [APPLICATION 15] SEQUENCE {
1030 pvno [0] INTEGER (5),
1031 msg-type [1] INTEGER (15),
1032 enc-part [2] EncryptedData {EncAPRepPart,
1033 { keyuse-EncAPRepPart }}
1034 }
1036 EncAPRepPart ::= [APPLICATION 27] SEQUENCE {
1037 ctime [0] KerberosTime,
1038 cusec [1] Microseconds,
1039 subkey [2] EncryptionKey OPTIONAL,
1040 seq-number [3] UInt32 OPTIONAL
1041 }
1042 @end verbatim
1044 @include shishi-api-ap.texi
1047 @node SAFE and PRIV Functions
1048 @section SAFE and PRIV Functions
1050 The ``KRB-SAFE'' is an ASN.1 structure used by application client and
1051 servers to exchange integrity protected data. The integrity
1052 protection is keyed, usually with a key agreed on via the AP exchange
1053 (@pxref{AP-REQ and AP-REP Functions}). The following illustrates the
1054 KRB-SAFE ASN.1 structure.
1056 @verbatim
1057 KRB-SAFE ::= [APPLICATION 20] SEQUENCE {
1058 pvno [0] INTEGER (5),
1059 msg-type [1] INTEGER (20),
1060 safe-body [2] KRB-SAFE-BODY,
1061 cksum [3] Checksum
1062 }
1064 KRB-SAFE-BODY ::= SEQUENCE {
1065 user-data [0] OCTET STRING,
1066 timestamp [1] KerberosTime OPTIONAL,
1067 usec [2] Microseconds OPTIONAL,
1068 seq-number [3] UInt32 OPTIONAL,
1069 s-address [4] HostAddress,
1070 r-address [5] HostAddress OPTIONAL
1071 }
1072 @end verbatim
1074 @include shishi-api-safe.texi
1076 The ``KRB-PRIV'' is an ASN.1 structure used by application client and
1077 servers to exchange confidential data. The confidentiality is keyed,
1078 usually with a key agreed on via the AP exchange (@pxref{AP-REQ and
1079 AP-REP Functions}). The following illustrates the KRB-PRIV ASN.1
1080 structure.
1082 @verbatim
1083 KRB-PRIV ::= [APPLICATION 21] SEQUENCE {
1084 pvno [0] INTEGER (5),
1085 msg-type [1] INTEGER (21),
1086 -- NOTE: there is no [2] tag
1087 enc-part [3] EncryptedData -- EncKrbPrivPart
1088 }
1090 EncKrbPrivPart ::= [APPLICATION 28] SEQUENCE {
1091 user-data [0] OCTET STRING,
1092 timestamp [1] KerberosTime OPTIONAL,
1093 usec [2] Microseconds OPTIONAL,
1094 seq-number [3] UInt32 OPTIONAL,
1095 s-address [4] HostAddress -- sender's addr --,
1096 r-address [5] HostAddress OPTIONAL -- recip's addr
1097 }
1098 @end verbatim
1100 @c @include shishi-api-safe.texi
1103 @node Ticket Functions
1104 @section Ticket Functions
1106 @include shishi-api-tkt.texi
1109 @node AS Functions
1110 @section AS Functions
1112 The Authentication Service (AS) is used to get an initial ticket using
1113 e.g. your password. The following illustrates the AS-REQ and AS-REP
1114 ASN.1 structures.
1116 @verbatim
1117 -- Request --
1119 AS-REQ ::= KDC-REQ {10}
1121 KDC-REQ {INTEGER:tagnum} ::= [APPLICATION tagnum] SEQUENCE {
1122 pvno [1] INTEGER (5) -- first tag is [1], not [0] --,
1123 msg-type [2] INTEGER (tagnum),
1124 padata [3] SEQUENCE OF PA-DATA OPTIONAL,
1125 req-body [4] KDC-REQ-BODY
1126 }
1128 KDC-REQ-BODY ::= SEQUENCE {
1129 kdc-options [0] KDCOptions,
1130 cname [1] PrincipalName OPTIONAL
1131 -- Used only in AS-REQ --,
1132 realm [2] Realm
1133 -- Server's realm
1134 -- Also client's in AS-REQ --,
1135 sname [3] PrincipalName OPTIONAL,
1136 from [4] KerberosTime OPTIONAL,
1137 till [5] KerberosTime,
1138 rtime [6] KerberosTime OPTIONAL,
1139 nonce [7] UInt32,
1140 etype [8] SEQUENCE OF Int32 -- EncryptionType
1141 -- in preference order --,
1142 addresses [9] HostAddresses OPTIONAL,
1143 enc-authorization-data [10] EncryptedData {
1144 AuthorizationData,
1145 { keyuse-TGSReqAuthData-sesskey
1146 | keyuse-TGSReqAuthData-subkey }
1147 } OPTIONAL,
1148 additional-tickets [11] SEQUENCE OF Ticket OPTIONAL
1149 }
1151 -- Reply --
1153 AS-REP ::= KDC-REP {11, EncASRepPart, {keyuse-EncASRepPart}}
1155 KDC-REP {INTEGER:tagnum,
1156 TypeToEncrypt,
1157 UInt32:KeyUsages} ::= [APPLICATION tagnum] SEQUENCE {
1158 pvno [0] INTEGER (5),
1159 msg-type [1] INTEGER (tagnum),
1160 padata [2] SEQUENCE OF PA-DATA OPTIONAL,
1161 crealm [3] Realm,
1162 cname [4] PrincipalName,
1163 ticket [5] Ticket,
1164 enc-part [6] EncryptedData {TypeToEncrypt, KeyUsages}
1165 }
1167 EncASRepPart ::= [APPLICATION 25] EncKDCRepPart
1169 EncKDCRepPart ::= SEQUENCE {
1170 key [0] EncryptionKey,
1171 last-req [1] LastReq,
1172 nonce [2] UInt32,
1173 key-expiration [3] KerberosTime OPTIONAL,
1174 flags [4] TicketFlags,
1175 authtime [5] KerberosTime,
1176 starttime [6] KerberosTime OPTIONAL,
1177 endtime [7] KerberosTime,
1178 renew-till [8] KerberosTime OPTIONAL,
1179 srealm [9] Realm,
1180 sname [10] PrincipalName,
1181 caddr [11] HostAddresses OPTIONAL
1182 }
1183 @end verbatim
1185 @include shishi-api-as.texi
1188 @node TGS Functions
1189 @section TGS Functions
1191 The Ticket Granting Service (TGS) is used to get subsequent tickets,
1192 authenticated by other tickets (so called ticket granting tickets).
1193 The following illustrates the TGS-REQ and TGS-REP ASN.1 structures.
1195 @verbatim
1196 -- Request --
1198 TGS-REQ ::= KDC-REQ {12}
1200 KDC-REQ {INTEGER:tagnum} ::= [APPLICATION tagnum] SEQUENCE {
1201 pvno [1] INTEGER (5) -- first tag is [1], not [0] --,
1202 msg-type [2] INTEGER (tagnum),
1203 padata [3] SEQUENCE OF PA-DATA OPTIONAL,
1204 req-body [4] KDC-REQ-BODY
1205 }
1207 KDC-REQ-BODY ::= SEQUENCE {
1208 kdc-options [0] KDCOptions,
1209 cname [1] PrincipalName OPTIONAL
1210 -- Used only in AS-REQ --,
1211 realm [2] Realm
1212 -- Server's realm
1213 -- Also client's in AS-REQ --,
1214 sname [3] PrincipalName OPTIONAL,
1215 from [4] KerberosTime OPTIONAL,
1216 till [5] KerberosTime,
1217 rtime [6] KerberosTime OPTIONAL,
1218 nonce [7] UInt32,
1219 etype [8] SEQUENCE OF Int32 -- EncryptionType
1220 -- in preference order --,
1221 addresses [9] HostAddresses OPTIONAL,
1222 enc-authorization-data [10] EncryptedData {
1223 AuthorizationData,
1224 { keyuse-TGSReqAuthData-sesskey
1225 | keyuse-TGSReqAuthData-subkey }
1226 } OPTIONAL,
1227 additional-tickets [11] SEQUENCE OF Ticket OPTIONAL
1228 }
1230 -- Reply --
1232 TGS-REP ::= KDC-REP {13, EncTGSRepPart,
1233 { keyuse-EncTGSRepPart-sesskey
1234 | keyuse-EncTGSRepPart-subkey }}
1236 KDC-REP {INTEGER:tagnum,
1237 TypeToEncrypt,
1238 UInt32:KeyUsages} ::= [APPLICATION tagnum] SEQUENCE {
1239 pvno [0] INTEGER (5),
1240 msg-type [1] INTEGER (tagnum),
1241 padata [2] SEQUENCE OF PA-DATA OPTIONAL,
1242 crealm [3] Realm,
1243 cname [4] PrincipalName,
1244 ticket [5] Ticket,
1245 enc-part [6] EncryptedData {TypeToEncrypt, KeyUsages}
1246 }
1248 EncTGSRepPart ::= [APPLICATION 26] EncKDCRepPart
1250 EncKDCRepPart ::= SEQUENCE {
1251 key [0] EncryptionKey,
1252 last-req [1] LastReq,
1253 nonce [2] UInt32,
1254 key-expiration [3] KerberosTime OPTIONAL,
1255 flags [4] TicketFlags,
1256 authtime [5] KerberosTime,
1257 starttime [6] KerberosTime OPTIONAL,
1258 endtime [7] KerberosTime,
1259 renew-till [8] KerberosTime OPTIONAL,
1260 srealm [9] Realm,
1261 sname [10] PrincipalName,
1262 caddr [11] HostAddresses OPTIONAL
1263 }
1264 @end verbatim
1266 @include shishi-api-tgs.texi
1269 @node Ticket (ASN.1) Functions
1270 @section Ticket (ASN.1) Functions
1272 @include shishi-api-ticket.texi
1274 @node AS/TGS Functions
1275 @section AS/TGS Functions
1277 The Authentication Service (AS) is used to get an initial ticket using
1278 e.g. your password. The Ticket Granting Service (TGS) is used to get
1279 subsequent tickets using other tickets. Protocol wise the procedures
1280 are very similar, which is the reason they are described together.
1281 The following illustrates the AS-REQ, TGS-REQ and AS-REP, TGS-REP
1282 ASN.1 structures. Most of the functions use the mnemonic ``KDC''
1283 instead of either AS or TGS, which means the function operates on both
1284 AS and TGS types. Only where the distinction between AS and TGS is
1285 important are the AS and TGS names used. Remember, these are
1286 low-level functions, and normal applications will likely be satisfied
1287 with the AS (@pxref{AS Functions}) and TGS (@pxref{TGS Functions})
1288 interfaces, or the even more high-level Ticket Set (@pxref{Ticket Set
1289 Functions}) interface.
1291 @verbatim
1292 -- Request --
1294 AS-REQ ::= KDC-REQ {10}
1295 TGS-REQ ::= KDC-REQ {12}
1297 KDC-REQ {INTEGER:tagnum} ::= [APPLICATION tagnum] SEQUENCE {
1298 pvno [1] INTEGER (5) -- first tag is [1], not [0] --,
1299 msg-type [2] INTEGER (tagnum),
1300 padata [3] SEQUENCE OF PA-DATA OPTIONAL,
1301 req-body [4] KDC-REQ-BODY
1302 }
1304 KDC-REQ-BODY ::= SEQUENCE {
1305 kdc-options [0] KDCOptions,
1306 cname [1] PrincipalName OPTIONAL
1307 -- Used only in AS-REQ --,
1308 realm [2] Realm
1309 -- Server's realm
1310 -- Also client's in AS-REQ --,
1311 sname [3] PrincipalName OPTIONAL,
1312 from [4] KerberosTime OPTIONAL,
1313 till [5] KerberosTime,
1314 rtime [6] KerberosTime OPTIONAL,
1315 nonce [7] UInt32,
1316 etype [8] SEQUENCE OF Int32 -- EncryptionType
1317 -- in preference order --,
1318 addresses [9] HostAddresses OPTIONAL,
1319 enc-authorization-data [10] EncryptedData {
1320 AuthorizationData,
1321 { keyuse-TGSReqAuthData-sesskey
1322 | keyuse-TGSReqAuthData-subkey }
1323 } OPTIONAL,
1324 additional-tickets [11] SEQUENCE OF Ticket OPTIONAL
1325 }
1327 -- Reply --
1329 AS-REP ::= KDC-REP {11, EncASRepPart, {keyuse-EncASRepPart}}
1330 TGS-REP ::= KDC-REP {13, EncTGSRepPart,
1331 { keyuse-EncTGSRepPart-sesskey
1332 | keyuse-EncTGSRepPart-subkey }}
1334 KDC-REP {INTEGER:tagnum,
1335 TypeToEncrypt,
1336 UInt32:KeyUsages} ::= [APPLICATION tagnum] SEQUENCE {
1337 pvno [0] INTEGER (5),
1338 msg-type [1] INTEGER (tagnum),
1339 padata [2] SEQUENCE OF PA-DATA OPTIONAL,
1340 crealm [3] Realm,
1341 cname [4] PrincipalName,
1342 ticket [5] Ticket,
1343 enc-part [6] EncryptedData {TypeToEncrypt, KeyUsages}
1344 }
1346 EncASRepPart ::= [APPLICATION 25] EncKDCRepPart
1347 EncTGSRepPart ::= [APPLICATION 26] EncKDCRepPart
1349 EncKDCRepPart ::= SEQUENCE {
1350 key [0] EncryptionKey,
1351 last-req [1] LastReq,
1352 nonce [2] UInt32,
1353 key-expiration [3] KerberosTime OPTIONAL,
1354 flags [4] TicketFlags,
1355 authtime [5] KerberosTime,
1356 starttime [6] KerberosTime OPTIONAL,
1357 endtime [7] KerberosTime,
1358 renew-till [8] KerberosTime OPTIONAL,
1359 srealm [9] Realm,
1360 sname [10] PrincipalName,
1361 caddr [11] HostAddresses OPTIONAL
1362 }
1363 @end verbatim
1365 @include shishi-api-kdc.texi
1368 @node Authenticator Functions
1369 @section Authenticator Functions
1371 An ``Authenticator'' is a ASN.1 structure that work as a proof that an
1372 entity owns a ticket. It is usually embedded in the AP-REQ structure
1373 (@pxref{AP-REQ and AP-REP Functions}), and you most likely want to use
1374 an AP-REQ instead of a Authenticator in normal applications. The
1375 following illustrates the Authenticator ASN.1 structure.
1377 @verbatim
1378 Authenticator ::= [APPLICATION 2] SEQUENCE {
1379 authenticator-vno [0] INTEGER (5),
1380 crealm [1] Realm,
1381 cname [2] PrincipalName,
1382 cksum [3] Checksum OPTIONAL,
1383 cusec [4] Microseconds,
1384 ctime [5] KerberosTime,
1385 subkey [6] EncryptionKey OPTIONAL,
1386 seq-number [7] UInt32 OPTIONAL,
1387 authorization-data [8] AuthorizationData OPTIONAL
1388 }
1389 @end verbatim
1391 @include shishi-api-authenticator.texi
1394 @node Cryptographic Functions
1395 @section Cryptographic Functions
1397 Underneath the high-level functions described earlier, cryptographic
1398 operations are happening. If you need to access these cryptographic
1399 primitives directly, this section describes the functions available.
1401 Most cryptographic operations need keying material, and cryptographic
1402 keys have been isolated into it's own data structure
1403 @code{Shishi_key}. The following illustrates it's contents, but note
1404 that you cannot access it's elements directly but must use the
1405 accessor functions described below.
1407 @verbatim
1408 struct Shishi_key
1409 {
1410 int type; /* RFC 1510 encryption integer type */
1411 char *value; /* Cryptographic key data */
1412 int version; /* RFC 1510 ``kvno'' */
1413 };
1414 @end verbatim
1416 All functions that operate on this data structure are described now.
1418 @include shishi-api-key.texi
1420 Applications that run uninteractively may need keying material. In
1421 these cases, the keys are stored in a file, a file that is normally
1422 stored on the local host. The file should be protected from
1423 unauthorized access. The file is in ASCII format and contains keys as
1424 outputed by @code{shishi_key_print()}. All functions that handle
1425 these keys sets are described now.
1427 @include shishi-api-keys.texi
1429 The previous functions require that the filename is known. For some
1430 applications, servers, it makes sense to provide a system default.
1431 These key sets used by server applications are known as ``hostkeys''.
1432 Here are the functions that operate on hostkeys (they are mostly
1433 wrappers around generic key sets).
1435 @include shishi-api-hostkeys.texi
1437 After creating the key structure, it can be used to encrypt and
1438 decrypt data, calculate checksum on data etc. All available functions
1439 are described now.
1441 @include shishi-api-crypto.texi
1444 @node Utility Functions
1445 @section Utility Functions
1447 @include shishi-api-utility.texi
1450 @node Error Handling
1451 @section Error Handling
1452 @cindex Error Handling
1454 Most functions in `Libshishi' are returning an error if they fail.
1455 For this reason, the application should always catch the error
1456 condition and take appropriate measures, for example by releasing the
1457 resources and passing the error up to the caller, or by displaying a
1458 descriptive message to the user and cancelling the operation.
1460 Some error values do not indicate a system error or an error in the
1461 operation, but the result of an operation that failed properly.
1463 @menu
1464 * Error values:: A list of all error values used.
1465 * Error strings:: How to get a descriptive string from a value.
1466 @end menu
1468 @node Error values
1469 @subsection Error values
1471 Errors are returned as an @code{int}. Except for the SHISHI_OK case,
1472 an application should always use the constants instead of their
1473 numeric value. Applications are encouraged to use the constants even
1474 for SHISHI_OK as it improves readability. Possible values are:
1476 @table @code
1477 @item SHISHI_OK
1478 This value indicates success. The value of this error is guaranteed
1479 to always be @code{0} so you may use it in boolean constructs.
1481 @include shishi-api-error-labels.texi
1483 @end table
1485 @node Error strings
1486 @subsection Error strings
1488 @include shishi-api-error.texi
1490 @node Examples
1491 @section Examples
1492 @cindex Examples
1494 This section will be extended to contain walk-throughs of example code
1495 that demonstrate how `Shishi' is used to write your own applications
1496 that support Kerberos 5. The rest of the current section consists of
1497 some crude hints for the example client/server applications that is
1498 part of Shishi, taken from an email but saved here for lack of a
1499 better place to put it.
1501 There are two programs: 'client' and 'server' in src/.
1503 The client output an AP-REQ, waits for an AP-REP, and then simply
1504 reads data from stdin.
1506 The server waits for an AP-REQ, parses it and prints an AP-REP, and
1507 then read data from stdin.
1509 Both programs accept a Kerberos server name as the first command line
1510 argument. Your KDC must know this server, since the client tries to
1511 get a ticket for it (first it gets a ticket granting ticket for the
1512 default username), and you must write the key for the server into
1513 /usr/local/etc/shishi.keys on the Shishi format, e.g.:
1515 @example
1516 -----BEGIN SHISHI KEY-----
1517 Keytype: 16 (des3-cbc-sha1-kd)
1518 Principal: sample/latte.josefsson.org
1519 Realm: JOSEFSSON.ORG
1521 8W0VrQQBpxlACPQEqN91EHxbvFFo2ltt
1522 -----END SHISHI KEY-----
1523 @end example
1525 You must extract the proper encryption key from the KDC in some way.
1526 (This part will be easier when Shishi include a KDC, a basic one isn't
1527 far away, give me a week or to.)
1529 The intention is that the data read, after the authentication phase,
1530 should be protected using KRB_SAFE (see RFC) but I haven't added this
1531 yet.
1533 @node Generic Security Service
1534 @section Generic Security Service
1535 @cindex Generic Security Service (GSS)
1537 As an alternative to the native Shishi programming API, it is possible
1538 to program Shishi through the Generic Security Services (GSS) API.
1539 The advantage of using GSS-API in your security application, instead
1540 of the native Shishi API, is that it will be easier to port your
1541 application between different Kerberos 5 implementations, and even
1542 beyond Kerberos 5 to different security systems, that support GSS-API.
1543 In the free software world, however, the only widely used security
1544 system that supports GSS-API is Kerberos 5, so the last advantage is
1545 somewhat academic. But if you are porting applications using GSS-API
1546 for other Kerberos 5 implementations, or want a more mature and stable
1547 API than the native Shishi API, you may find using Shishi's GSS-API
1548 interface compelling. Note that GSS-API only offer basic services,
1549 for more advanced uses you must use the native API.
1551 Since the GSS is not specific to Shishi, it is distributed
1552 independently from Shishi. Further information on the GSS project can
1553 be found at @url{http://josefsson.org/gss/}.
1555 @c **********************************************************
1556 @c ******************* Acknowledgements *******************
1557 @c **********************************************************
1558 @node Acknowledgements
1559 @chapter Acknowledgements
1561 Shishi uses Libtasn1 by Fabio Fiorina, Libnettle by Niels Möller,
1562 Libgcrypt and Libgpg-error by Werner Koch, Libidn by Simon Josefsson,
1563 cvs2cl by Karl Fogel, and gdoc by Michael Zucchi.
1565 Several GNU packages simplified development considerably, those
1566 packages include Autoconf, Automake, Libtool, Gnulib, Gettext, Indent,
1567 CVS, Texinfo, Help2man and Emacs.
1569 Several people reported bugs, sent patches or suggested improvements,
1570 see the file THANKS.
1572 @c **********************************************************
1573 @c ******************* Appendices *************************
1574 @c **********************************************************
1576 @node Copying This Manual
1577 @appendix Copying This Manual
1579 @menu
1580 * GNU Free Documentation License:: License for copying this manual.
1581 @end menu
1583 @include fdl.texi
1585 @include gpl.texi
1587 @node Concept Index
1588 @unnumbered Concept Index
1590 @printindex cp
1592 @node Function and Data Index
1593 @unnumbered Function and Data Index
1595 @printindex fn
1597 @summarycontents
1598 @contents
1599 @bye