| blob | cdfc17d88784828dc0864224aa09518bac466044 |
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 Cross-realm support (week).
198 @item Session keys in AP (week).
200 @item PKINIT (use libksba, weeks)
202 @item Finish GSSAPI support via GPL GSS (weeks)
203 Shishi will not support GSS, but a separate project ``GPL GSS'' is
204 under way to produce a generic GSS implementation, and it will use
205 Shishi to implement the Kerberos 5 mechanism.
207 @item Port to cyclone (cyclone need to mature first)
209 @item Modularize ASN.1 library so it can be replaced (days)
211 @item Modularize Crypto library so it can be replaced (days)
213 @item KDC (initiated, weeks)
215 @item PAM module (week)
216 Finished.
218 @item Set/Change password protocol (weeks?)
220 @item Port applications to use Shishi (indefinite)
222 @item Improve documentation
224 @item Improve internationalization
226 @item Add AP-REQ reply cache (week).
228 @end itemize
230 @node Overview
231 @section Overview
233 This section describes RFC 1510 from a protocol point of
234 view@footnote{The text is a lightly adapted version of the
235 introduction section from RFC 1510 by J. Kohl and C. Neuman, September
236 1993, unclear copyrights, but presumably owned by The Internet
237 Society.}.
239 Kerberos provides a means of verifying the identities of principals,
240 (e.g., a workstation user or a network server) on an open
241 (unprotected) network. This is accomplished without relying on
242 authentication by the host operating system, without basing trust on
243 host addresses, without requiring physical security of all the hosts
244 on the network, and under the assumption that packets traveling along
245 the network can be read, modified, and inserted at will. (Note,
246 however, that many applications use Kerberos' functions only upon the
247 initiation of a stream-based network connection, and assume the
248 absence of any "hijackers" who might subvert such a connection. Such
249 use implicitly trusts the host addresses involved.) Kerberos performs
250 authentication under these conditions as a trusted third- party
251 authentication service by using conventional cryptography, i.e.,
252 shared secret key. (shared secret key - Secret and private are often
253 used interchangeably in the literature. In our usage, it takes two
254 (or more) to share a secret, thus a shared DES key is a secret key.
255 Something is only private when no one but its owner knows it. Thus,
256 in public key cryptosystems, one has a public and a private key.)
258 The authentication process proceeds as follows: A client sends a
259 request to the authentication server (AS) requesting "credentials" for
260 a given server. The AS responds with these credentials, encrypted in
261 the client's key. The credentials consist of 1) a "ticket" for the
262 server and 2) a temporary encryption key (often called a "session
263 key"). The client transmits the ticket (which contains the client's
264 identity and a copy of the session key, all encrypted in the server's
265 key) to the server. The session key (now shared by the client and
266 server) is used to authenticate the client, and may optionally be used
267 to authenticate the server. It may also be used to encrypt further
268 communication between the two parties or to exchange a separate
269 sub-session key to be used to encrypt further communication.
271 The implementation consists of one or more authentication servers
272 running on physically secure hosts. The authentication servers
273 maintain a database of principals (i.e., users and servers) and their
274 secret keys. Code libraries provide encryption and implement the
275 Kerberos protocol. In order to add authentication to its
276 transactions, a typical network application adds one or two calls to
277 the Kerberos library, which results in the transmission of the
278 necessary messages to achieve authentication.
280 The Kerberos protocol consists of several sub-protocols (or
281 exchanges). There are two methods by which a client can ask a
282 Kerberos server for credentials. In the first approach, the client
283 sends a cleartext request for a ticket for the desired server to the
284 AS. The reply is sent encrypted in the client's secret key. Usually
285 this request is for a ticket-granting ticket (TGT) which can later be
286 used with the ticket-granting server (TGS). In the second method, the
287 client sends a request to the TGS. The client sends the TGT to the
288 TGS in the same manner as if it were contacting any other application
289 server which requires Kerberos credentials. The reply is encrypted in
290 the session key from the TGT.
292 Once obtained, credentials may be used to verify the identity of the
293 principals in a transaction, to ensure the integrity of messages
294 exchanged between them, or to preserve privacy of the messages. The
295 application is free to choose whatever protection may be necessary.
297 To verify the identities of the principals in a transaction, the
298 client transmits the ticket to the server. Since the ticket is sent
299 "in the clear" (parts of it are encrypted, but this encryption doesn't
300 thwart replay) and might be intercepted and reused by an attacker,
301 additional information is sent to prove that the message was
302 originated by the principal to whom the ticket was issued. This
303 information (called the authenticator) is encrypted in the session
304 key, and includes a timestamp. The timestamp proves that the message
305 was recently generated and is not a replay. Encrypting the
306 authenticator in the session key proves that it was generated by a
307 party possessing the session key. Since no one except the requesting
308 principal and the server know the session key (it is never sent over
309 the network in the clear) this guarantees the identity of the client.
311 The integrity of the messages exchanged between principals can also be
312 guaranteed using the session key (passed in the ticket and contained
313 in the credentials). This approach provides detection of both replay
314 attacks and message stream modification attacks. It is accomplished
315 by generating and transmitting a collision-proof checksum (elsewhere
316 called a hash or digest function) of the client's message, keyed with
317 the session key. Privacy and integrity of the messages exchanged
318 between principals can be secured by encrypting the data to be passed
319 using the session key passed in the ticket, and contained in the
320 credentials.
322 @node Cryptographic Overview
323 @section Cryptographic Overview
325 Shishi implements several of the standard cryptographic primitives.
326 Here are the names of the supported encryption suites, with some notes
327 on their status and there associated checksum suite. They are ordered
328 by increased security as perceived by the author.
330 @cindex DES
331 @cindex 3DES
332 @cindex AES
334 @table @code
336 @item NULL
338 @code{NULL} is a dummy encryption suite for debugging. Encryption and
339 decryption are identity functions. No integrity protection. It is
340 weak. It is associated with the @code{NULL} checksum.
342 @item des-cbc-crc
344 @code{des-cbc-crc} is DES encryption and decryption with 56 bit keys
345 and 8 byte blocks in CBC mode. The keys can be derived from passwords
346 by an obscure application specific algorithm. Data is integrity
347 protected with an unkeyed but encrypted @code{CRC32}-like checksum.
348 It is weak. It is associated with the @code{rsa-md5-des} checksum.
350 @item des-cbc-md4
352 @code{des-cbc-md4} is DES encryption and decryption with 56 bit keys
353 and 8 byte blocks in CBC mode. The keys can be derived from passwords
354 by an obscure application specific algorithm. Data is integrity
355 protected with an unkeyed but encrypted MD4 hash. It is weak. It is
356 associated with the @code{rsa-md4-des} checksum.
358 @item des-cbc-md5
360 @code{des-cbc-md5} is DES encryption and decryption with 56 bit keys
361 and 8 byte blocks in CBC mode. The keys can be derived from passwords
362 by an obscure application specific algorithm. Data is integrity
363 protected with an unkeyed but encrypted MD5 hash. It is weak. It is
364 associated with the @code{rsa-md5-des} checksum. This is the
365 strongest RFC 1510 interoperable mechanism.
367 @item des3-cbc-sha1-kd
369 @code{des3-cbc-sha1-kd} is DES encryption and decryption with three 56
370 bit keys (effective key size 112 bits) and 8 byte blocks in CBC
371 mode. The keys can be derived from passwords by a algorithm based on
372 the paper "A Better Key Schedule For DES-like Ciphers"
373 @footnote{@url{http://www.research.att.com/~smb/papers/ides.pdf}} by
374 Uri Blumenthal and Steven M. Bellovin (it is not clear if the
375 algorithm, and the way it is used, is used by any other protocols,
376 although it seems unlikely). Data is integrity protected with a keyed
377 (HMAC) SHA1 hash. It has no security proof, but is assumed to provide
378 adequate security in the sense that knowledge on how to crack it is
379 not known to the public. It is associated with the
380 @code{hmac-sha1-des3-kd} checksum.
382 @item aes128-cts-hmac-sha1-96
383 @item aes256-cts-hmac-sha1-96.
385 @code{aes128-cts-hmac-sha1-96} and @code{aes256-cts-hmac-sha1-96} is
386 AES encryption and decryption with 128 bit and 256 bit key,
387 respectively, and 16 byte blocks in CBC mode with Cipher Text
388 Stealing. Cipher Text Stealing means data length of encrypted data is
389 preserved (pure CBC add up to 7 pad characters). The keys can be
390 derived from passwords with RSA Laboratories PKCS#5 Password Based Key
391 Derivation Function
392 2@footnote{@url{http://www.rsasecurity.com/rsalabs/pkcs/pkcs-5/}},
393 which is allegedly provably secure in a random oracle model. Data is
394 integrity protected with a keyed (HMAC) SHA1 hash truncated to 96
395 bits. There is no security proof, but the schemes are assumed to
396 provide good security, but has, as AES itself, yet to receive the test
397 of time. It is associated with the @code{hmac-sha1-96-aes128} and
398 @code{hmac-sha1-96-aes256} checksums, respectively.
400 @end table
402 The protocol do not include any way to negotiate which checksum
403 mechanisms to use, so in most cases the associated checksum will be
404 used. However, checksum mechanisms can be used with other encryption
405 mechanisms, as long as they are compatible in terms of key format etc.
406 Here are the names of the supported checksum mechanisms, with some
407 notes on their status and the compatible encryption mechanisms. They
408 are ordered by increased security as perceived by the author.
410 @table @code
412 @item NULL
414 @code{NULL} is a dummy checksum suite for debugging. It provides no
415 integrity. It is weak. It is compatible with the @code{NULL}
416 encryption mechanism.
418 @item rsa-md4-des
420 @code{rsa-md4-des} is a DES CBC encryption of one block of random data
421 and a unkeyed MD4 hash computed over the random data and the message
422 to integrity protect. The key used is derived from the base protocol
423 key by XOR with a constant. It is weak. It is compatible with the
424 @code{des-cbc-crc}, @code{des-cbc-md4}, @code{des-cbc-md5} encryption
425 mechanisms.
427 @item rsa-md5-des
429 @code{rsa-md5-des} is a DES CBC encryption of one block of random data
430 and a unkeyed MD5 hash computed over the random data and the message
431 to integrity protect. The key used is derived from the base protocol
432 key by XOR with a constant. It is weak. It is compatible with the
433 @code{des-cbc-crc}, @code{des-cbc-md4}, @code{des-cbc-md5} encryption
434 mechanisms.
436 @item hmac-sha1-des3-kd
438 @code{hmac-sha1-des3-kd} is a keyed (HMAC) SHA1 hash computed over the
439 message. The key is derived from the base protocol by the simplified
440 key derivation function (similar to the password key derivation
441 functions of @code{des3-cbc-sha1-kd}). It has no security proof, but
442 is assumed to provide good security. It is compatible with the
443 @code{des3-cbc-sha1-kd} encryption mechanism.
445 @item hmac-sha1-96-aes128
446 @item hmac-sha1-96-aes256
448 @code{hmac-sha1-96-aes*} are keyed (HMAC) SHA1 hashes computed over
449 the message and then truncated to 96 bits. The key is derived from
450 the base protocol by the simplified key derivation function (similar
451 to the password key derivation functions of @code{des3-cbc-sha1-kd}).
452 It has no security proof, but is assumed to provide good security. It
453 is compatible with the @code{des3-cbc-sha1-kd} encryption mechanism.
455 @end table
458 @node Supported Platforms
459 @section Supported Platforms
461 Shishi has at some point in time been tested on the following
462 platforms.
464 @enumerate
466 @item Debian GNU/Linux 3.0r0 (Woody)
467 @cindex Debian
469 GCC 2.95.4 and GNU Make. alphaev67-unknown-linux-gnu,
470 alphaev6-unknown-linux-gnu, hppa64-unknown-linux-gnu,
471 i686-pc-linux-gnu, ia64-unknown-linux-gnu.
473 @item Tru64 UNIX
474 @cindex Tru64
476 Tru64 UNIX C compiler and Tru64 Make. alphaev68-dec-osf5.1.
478 @item SuSE Linux 7.1
479 @cindex SuSE
481 GCC 2.96 and GNU Make. alphaev67-unknown-linux-gnu.
483 @item SuSE Linux 7.2a
484 @cindex SuSE Linux
486 GCC 3.0 and GNU Make. ia64-unknown-linux-gnu.
488 @item RedHat Linux 7.2
489 @cindex RedHat
491 GCC 2.96 and GNU Make. i686-pc-linux-gnu.
493 @item RedHat Linux 8.0
494 @cindex RedHat
496 GCC 3.2 and GNU Make. i686-pc-linux-gnu.
498 @item Red Hat Advanced Server 2.1
499 @cindex RedHat
501 GCC 2.96 and GNU Make. ia64-unknown-linux-gnu (Intel Madison).
503 @c @item IRIX 6.5
504 @c @cindex IRIX
505 @c
506 @c mips-sgi-irix6.5, MIPS C compiler, IRIX Make.
508 @c @item AIX 4.3.2
509 @c @cindex AIX
510 @c
511 @c rs6000-ibm-aix4.3.2.0, IBM C for AIX compiler, AIX Make.
513 @c @item Microsoft Windows 2000
514 @c @cindex Windows
515 @c
516 @c GCC 2.95.2-6, GNU make. i686-pc-cygwin
518 @c @item HP-UX 11.11
519 @c @cindex HP-UX
520 @c
521 @c HP-UX C compiler and HP Make. hppa2.0w-hp-hpux11.11.
523 @item SUN Solaris 2.8
524 @cindex Solaris
526 Sun WorkShop Compiler C 6.0 and SUN Make. sparc-sun-solaris2.8.
528 @item NetBSD 1.6
529 @cindex NetBSD
531 GCC 2.95.3 and GNU Make. alpha-unknown-netbsd1.6,
532 i386-unknown-netbsdelf1.6.
534 @item OpenBSD 3.1
535 @cindex OpenBSD
537 GCC 2.95.3 and GNU Make.
538 @c alpha-unknown-openbsd3.1, (alignment problems)
539 i386-unknown-openbsd3.1.
541 @item FreeBSD 4.7
542 @cindex FreeBSD
544 GCC 2.95.4 and GNU Make. alpha-unknown-freebsd4.7,
545 i386-unknown-freebsd4.7.
547 @end enumerate
549 If you use Shishi on, or port Shishi to, a new platform please report
550 it to the author (@pxref{Bug Reports}).
552 @node Bug Reports
553 @section Bug Reports
554 @cindex Reporting Bugs
556 If you think you have found a bug in Shishi, please investigate it and
557 report it.
559 @itemize @bullet
561 @item Please make sure that the bug is really in Shishi, and
562 preferably also check that it hasn't already been fixed in the latest
563 version.
565 @item You have to send us a test case that makes it possible for us to
566 reproduce the bug.
568 @item You also have to explain what is wrong; if you get a crash, or
569 if the results printed are not good and in that case, in what way.
570 Make sure that the bug report includes all information you would need
571 to fix this kind of bug for someone else.
573 @end itemize
575 Please make an effort to produce a self-contained report, with
576 something definite that can be tested or debugged. Vague queries or
577 piecemeal messages are difficult to act on and don't help the
578 development effort.
580 If your bug report is good, we will do our best to help you to get a
581 corrected version of the software; if the bug report is poor, we won't
582 do anything about it (apart from asking you to send better bug
583 reports).
585 If you think something in this manual is unclear, or downright
586 incorrect, or if the language needs to be improved, please also send a
587 note.
589 Send your bug report to:
591 @center @samp{bug-shishi@@josefsson.org}
594 @c **********************************************************
595 @c ******************** User Manual **********************
596 @c **********************************************************
597 @node User Manual
598 @chapter User Manual
599 @cindex End-user Shishi usage
601 Usually Shishi interacts with you to get some initial authentication
602 information like a password, and then contacts a server to receive a
603 so called ticket granting ticket. From now on, you rarely interacts
604 with Shishi directly. Applications that needs security services
605 instruct the Shishi library to use the ticket granting ticket to get
606 new tickets for various servers. An example could be if you log on to
607 a host remotely via @samp{telnet}. The host usually requires
608 authentication before permitting you in. The @samp{telnet} client
609 uses the ticket granting ticket to get a ticket for the server, and
610 then use this ticket to authenticate you against the server (typically
611 the server is also authenticated to you). You perform the initial
612 authentication by typing @command{shishi} at the prompt. Sometimes it
613 is necessary to supply options telling Shishi what your principal name
614 (user name in the Kerberos realm) or realm is. In the example, I
615 specify the client name @code{simon@@JOSEFSSON.ORG}.
617 @example
618 @cartouche
619 $ shishi simon@@JOSEFSSON.ORG
620 Enter password for `jas@@JOSEFSSON.ORG':
621 jas@@JOSEFSSON.ORG:
622 Authtime: Fri Aug 15 04:44:49 2003
623 Endtime: Fri Aug 15 05:01:29 2003
624 Server: krbtgt/JOSEFSSON.ORG key des3-cbc-sha1-kd (16)
625 Ticket key: des3-cbc-sha1-kd (16) protected by des3-cbc-sha1-kd (16)
626 Ticket flags: INITIAL (512)
627 $
628 @end cartouche
629 @end example
631 As you can see, Shishi also prints a short description of the ticket
632 received.
634 A logical next step is to display all tickets you have received (by
635 the way, the tickets are usually stored as text in
636 @file{~/.shishi/tickets}). This is achieved by typing @command{shishi
637 --list}.
639 @example
640 @cartouche
641 $ shishi --list
642 Tickets in `/home/jas/.shishi/tickets':
644 jas@@JOSEFSSON.ORG:
645 Authtime: Fri Aug 15 04:49:46 2003
646 Endtime: Fri Aug 15 05:06:26 2003
647 Server: krbtgt/JOSEFSSON.ORG key des-cbc-md5 (3)
648 Ticket key: des-cbc-md5 (3) protected by des-cbc-md5 (3)
649 Ticket flags: INITIAL (512)
651 jas@@JOSEFSSON.ORG:
652 Authtime: Fri Aug 15 04:49:46 2003
653 Starttime: Fri Aug 15 04:49:49 2003
654 Endtime: Fri Aug 15 05:06:26 2003
655 Server: host/latte.josefsson.org key des-cbc-md5 (3)
656 Ticket key: des-cbc-md5 (3) protected by des-cbc-md5 (3)
658 2 tickets found.
659 $
660 @end cartouche
661 @end example
663 As you can see, I had a ticket for the server
664 @samp{host/latte.josefsson.org} which was generated by
665 @samp{telnet}:ing to that host.
667 If, for some reason, you want to manually get a ticket for a specific
668 server, you can use the @command{shishi --server-name} command.
669 Normally, however, the application that uses Shishi will take care of
670 getting a ticket for the appropriate server, so you normally wouldn't
671 need this command.
673 @example
674 @cartouche
675 $ shishi --server-name=user/billg --encryption-type=des-cbc-md4
676 jas@@JOSEFSSON.ORG:
677 Authtime: Fri Aug 15 04:49:46 2003
678 Starttime: Fri Aug 15 04:54:33 2003
679 Endtime: Fri Aug 15 05:06:26 2003
680 Server: user/billg key des-cbc-md4 (2)
681 Ticket key: des-cbc-md4 (2) protected by des-cbc-md5 (3)
682 $
683 @end cartouche
684 @end example
686 As you can see, I acquired a ticket for @samp{user/billg} with a
687 @samp{des-cbc-md4} (@pxref{Cryptographic Overview}) encryption key
688 specified with the @samp{--encryption-type} parameter.
690 To wrap up this introduction, lets see how you can remove tickets.
691 You may want to do this if you leave your terminal for lunch or
692 similar, and don't want someone to be able to copy the file and then
693 use your credentials. Note that this only destroy the tickets
694 locally, it does not contact any server and tell it that these
695 credentials are no longer valid. So if someone stole your ticket
696 file, you must contact your administrator and have them reset your
697 account, simply using this parameter is not sufficient.
699 @example
700 @cartouche
701 $ shishi --server-name=imap/latte.josefsson.org --destroy
702 1 ticket removed.
703 $ shishi --server-name=foobar --destroy
704 No tickets removed.
705 $ shishi --destroy
706 3 tickets removed.
707 $
708 @end cartouche
709 @end example
711 Below follows a list of all parameters.
713 Mandatory or optional arguments to long options are also mandatory or optional
714 for any corresponding short options.
716 @example
717 --client-name=NAME Client name. Default is login username. Only for
718 AS.
719 --destroy Destroy tickets in local cache, subject to
720 --server-name limiting.
721 -e, --encryption-type=ETYPE,[ETYPE...]
722 Encryption types to use. ETYPE is either
723 registered name or integer.
724 --force-as Force AS mode. Default is to use TGS iff a TGT is
725 found.
726 --force-tgs Force TGS mode. Default is to use TGS iff a TGT is
727 found.
728 --key-value=KEY Cipher key to decrypt response (discouraged).
729 --list List tickets in local cache, subject to
730 --server-name limiting.
731 --password=PASSWORD Password to decrypt response (discouraged). Only
732 for AS.
733 -r, --realm=REALM Realm of server. Default is DNS domain of local
734 host. For AS, this also indicates realm of client.
736 --server=HOST Send request to HOST. Default uses address from
737 configuration file.
738 --server-name=NAME Server name. Default is "krbtgt/REALM" where REALM
739 is server realm (see --realm).
740 --ticket-granter=NAME Service name in ticket to use for authenticating
741 request. Only for TGS. Defaults to
742 "krbtgt/REALM@@REALM" where REALM is server realm
743 (see --realm).
745 Options for low-level cryptography (CRYPTO-OPTIONS):
746 --algorithm=ALGORITHM Cipher algorithm, expressed either as the etype
747 integer or the registered name.
748 --client-name=NAME Username. Default is login name.
749 --decrypt Decrypt data.
750 --encrypt Encrypt data.
751 --key-usage=KEYUSAGE Encrypt or decrypt using specified key usage.
752 Default is 0, which means no key derivation are
753 performed.
754 --key-value=KEY Base64 encoded key value.
755 --key-version=INTEGER Version number of key.
756 --parameter=STRING String-to-key parameter to use when --password is
757 specified. This data is specific for each
758 encryption algorithm and rarely needed.
759 --password=PASSWORD Password used to generate key. --client-name and
760 --realm also modify the computed key value.
761 --random Generate key from random data.
762 --read-data-file=[TYPE,]FILE
763 Read data from FILE in TYPE, BASE64, HEX or BINARY
764 (default).
765 --read-key-file=FILE Read cipher key from FILE
766 --realm=REALM Realm of principal. Defaults to DNS domain of
767 local host.
768 --salt=SALT Salt to use when --password is specified. Defaults
769 to using theusername (--client-name) and realm
770 (--realm).
771 --write-data-file=[TYPE,]FILE
772 Write data to FILE in TYPE, BASE64, HEX or BINARY
773 (default).
774 --write-key-file=FILE Append cipher key to FILE
776 Other options:
777 -c, --configuration-file=FILE Read user configuration from file. Default
778 is ~/.shishi/config.
779 -o, --library-options=STRING Parse STRING as a configuration file
780 statement.
781 -q, --quiet, --silent Don't produce any output.
782 -s, --system-configuration-file=FILE
783 Read system wide configuration from file. Default
784 is /usr/local/etc/shishi.conf.
785 -t, --ticket-file=FILE Read tickets from FILE. Default is
786 $HOME/.shishi/tickets.
787 -v, --verbose Produce verbose output.
788 --verbose-library Produce verbose output in the library.
789 -w, --ticket-write-file=FILE Write tickets to FILE. Default is to write
790 them back to ticket file.
791 NAME Set client name and realm from NAME. The
792 --client-name and --realm can be used to override
793 part of NAME.
795 -?, --help Give this help list
796 --usage Give a short usage message
797 -V, --version Print program version
798 @end example
800 @c **********************************************************
801 @c **************** Administration Manual *****************
802 @c **********************************************************
803 @node Administration Manual
804 @chapter Administration Manual
806 TBW.
809 @c **********************************************************
810 @c *************** Programming Manual *********************
811 @c **********************************************************
812 @node Programming Manual
813 @chapter Programming Manual
814 @cindex Application Programming Interface (API)
816 This chapter describes all the publicly available functions in the
817 library.
819 @menu
820 * Preparation:: What you should do before using the library.
821 * Initialization Functions:: Creating library handle, configuration file.
822 * Ticket Set Functions:: High-level ticket management functions.
823 * AP-REQ and AP-REP Functions:: Client/Server authentication functions.
824 * SAFE and PRIV Functions:: Client/Server session data functions.
825 * Ticket Functions:: Medium-level ticket manipulation functions.
826 * AS Functions:: Medium-level initial authentication functions.
827 * TGS Functions:: Medium-level authentication functions.
828 * Ticket (ASN.1) Functions:: Low-level Ticket functions.
829 * AS/TGS Functions:: Low-level KDC functions; AS and TGS.
830 * Authenticator Functions:: Low-level authenticator functions.
831 * Cryptographic Functions:: Low-level cryptographic functions.
832 * Utility Functions:: Utilities for use in the global context.
833 * Error Handling:: Error codes and such.
834 * Examples:: Example code.
835 * Generic Security Service:: If you want to use the GSS API instead.
836 @end menu
838 @node Preparation
839 @section Preparation
841 To use `Libshishi', you have to perform some changes to your sources
842 and the build system. The necessary changes are small and explained
843 in the following sections. At the end of this chapter, it is
844 described how the library is initialized, and how the requirements of
845 the library are verified.
847 A faster way to find out how to adapt your application for use with
848 `Libshishi' may be to look at the examples at the end of this manual
849 (@pxref{Examples}).
851 @menu
852 * Header::
853 * Initialization::
854 * Version Check::
855 * Building the source::
856 @end menu
858 @node Header
859 @subsection Header
861 All interfaces (data types and functions) of the library are defined
862 in the header file `shishi.h'. You must include this in all programs
863 using the library, either directly or through some other header file,
864 like this:
866 @example
867 #include <shishi.h>
868 @end example
870 The name space of `Libshishi' is @code{shishi_*} for function names,
871 @code{Shishi*} for data types and @code{SHISHI_*} for other symbols. In
872 addition the same name prefixes with one prepended underscore are
873 reserved for internal use and should never be used by an application.
875 @node Initialization
876 @subsection Initialization
878 `Libshishi' must be initialized before it can be used. The library is
879 initialized by calling @code{shishi_init()} (@pxref{Initialization
880 Functions}). The resources allocated by the initialization process
881 can be released if the application no longer has a need to call
882 `Libshishi' functions, this is done by calling @code{shishi_done()}.
884 In order to take advantage of the internationalisation features in
885 `Libshishi', such as translated error messages, the application must
886 set the current locale using @code{setlocale()} before initializing
887 `Libshishi'.
889 @node Version Check
890 @subsection Version Check
892 It is often desirable to check that the version of `Libshishi' used is
893 indeed one which fits all requirements. Even with binary
894 compatibility new features may have been introduced but due to problem
895 with the dynamic linker an old version is actually used. So you may
896 want to check that the version is okay right after program startup.
898 @include shishi-api-version.texi
900 The normal way to use the function is to put something similar to the
901 following early in your @code{main()}:
903 @example
904 if (!shishi_check_version (SHISHI_VERSION))
905 @{
906 printf ("shishi_check_version() failed:\n"
907 "Header file incompatible with shared library.\n");
908 exit(1);
909 @}
910 @end example
912 @node Building the source
913 @subsection Building the source
914 @cindex Compiling your application
916 If you want to compile a source file including the `shishi.h' header
917 file, you must make sure that the compiler can find it in the
918 directory hierarchy. This is accomplished by adding the path to the
919 directory in which the header file is located to the compilers include
920 file search path (via the @option{-I} option).
922 However, the path to the include file is determined at the time the
923 source is configured. To solve this problem, `Libshishi' uses the
924 external package @command{pkg-config} that knows the path to the
925 include file and other configuration options. The options that need
926 to be added to the compiler invocation at compile time are output by
927 the @option{--cflags} option to @command{pkg-config shishi}. The
928 following example shows how it can be used at the command line:
930 @example
931 gcc -c foo.c `pkg-config shishi --cflags`
932 @end example
934 Adding the output of @samp{pkg-config shishi --cflags} to the
935 compilers command line will ensure that the compiler can find the
936 `Libshishi' header file.
938 A similar problem occurs when linking the program with the library.
939 Again, the compiler has to find the library files. For this to work,
940 the path to the library files has to be added to the library search path
941 (via the @option{-L} option). For this, the option @option{--libs} to
942 @command{pkg-config shishi} can be used. For convenience, this option
943 also outputs all other options that are required to link the program
944 with the `Libshishi' libararies (in particular, the @samp{-lshishi}
945 option). The example shows how to link @file{foo.o} with the `Libshishi'
946 library to a program @command{foo}.
948 @example
949 gcc -o foo foo.o `pkg-config shishi --libs`
950 @end example
952 Of course you can also combine both examples to a single command by
953 specifying both options to @command{pkg-config}:
955 @example
956 gcc -o foo foo.c `pkg-config shishi --cflags --libs`
957 @end example
959 @node Initialization Functions
960 @section Initialization Functions
962 @include shishi-api-init.texi
965 @node Ticket Set Functions
966 @section Ticket Set Functions
968 A ``ticket set'' is, as the name implies, a collection of tickets.
969 Functions are provided to read tickets from file into a ticket set, to
970 query number of tickets in the set, to extract a given ticket from the
971 set, to search the ticket set for tickets matching certain criterium,
972 to write the ticket set to a file, etc. High level functions for
973 performing a initial authentication (@pxref{AS Functions}) or
974 subsequent authentication (@pxref{TGS Functions}) and storing the new
975 ticket in the ticket set are also provided.
977 To manipulate each individual ticket, @xref{Ticket Functions}. For
978 low-level ASN.1 manipulation see @xref{Ticket (ASN.1) Functions}.
980 @include shishi-api-tkts.texi
983 @node AP-REQ and AP-REP Functions
984 @section AP-REQ and AP-REP Functions
986 The ``AP-REQ'' and ``AP-REP'' are ASN.1 structures used by application
987 client and servers to prove to each other who they are. The
988 structures contain auxilliary information, together with an
989 authenticator (@pxref{Authenticator Functions}) which is the real
990 cryptographic proof. The following illustrates the AP-REQ and AP-REP
991 ASN.1 structures.
993 @verbatim
994 AP-REQ ::= [APPLICATION 14] SEQUENCE {
995 pvno [0] INTEGER (5),
996 msg-type [1] INTEGER (14),
997 ap-options [2] APOptions,
998 ticket [3] Ticket,
999 authenticator [4] EncryptedData {Authenticator,
1000 { keyuse-pa-TGSReq-authenticator
1001 | keyuse-APReq-authenticator }}
1002 }
1004 AP-REP ::= [APPLICATION 15] SEQUENCE {
1005 pvno [0] INTEGER (5),
1006 msg-type [1] INTEGER (15),
1007 enc-part [2] EncryptedData {EncAPRepPart,
1008 { keyuse-EncAPRepPart }}
1009 }
1011 EncAPRepPart ::= [APPLICATION 27] SEQUENCE {
1012 ctime [0] KerberosTime,
1013 cusec [1] Microseconds,
1014 subkey [2] EncryptionKey OPTIONAL,
1015 seq-number [3] UInt32 OPTIONAL
1016 }
1017 @end verbatim
1019 @include shishi-api-ap.texi
1022 @node SAFE and PRIV Functions
1023 @section SAFE and PRIV Functions
1025 The ``KRB-SAFE'' is an ASN.1 structure used by application client and
1026 servers to exchange integrity protected data. The integrity
1027 protection is keyed, usually with a key agreed on via the AP exchange
1028 (@pxref{AP-REQ and AP-REP Functions}). The following illustrates the
1029 KRB-SAFE ASN.1 structure.
1031 @verbatim
1032 KRB-SAFE ::= [APPLICATION 20] SEQUENCE {
1033 pvno [0] INTEGER (5),
1034 msg-type [1] INTEGER (20),
1035 safe-body [2] KRB-SAFE-BODY,
1036 cksum [3] Checksum
1037 }
1039 KRB-SAFE-BODY ::= SEQUENCE {
1040 user-data [0] OCTET STRING,
1041 timestamp [1] KerberosTime OPTIONAL,
1042 usec [2] Microseconds OPTIONAL,
1043 seq-number [3] UInt32 OPTIONAL,
1044 s-address [4] HostAddress,
1045 r-address [5] HostAddress OPTIONAL
1046 }
1047 @end verbatim
1049 @include shishi-api-safe.texi
1051 The ``KRB-PRIV'' is an ASN.1 structure used by application client and
1052 servers to exchange confidential data. The confidentiality is keyed,
1053 usually with a key agreed on via the AP exchange (@pxref{AP-REQ and
1054 AP-REP Functions}). The following illustrates the KRB-PRIV ASN.1
1055 structure.
1057 @verbatim
1058 KRB-PRIV ::= [APPLICATION 21] SEQUENCE {
1059 pvno [0] INTEGER (5),
1060 msg-type [1] INTEGER (21),
1061 -- NOTE: there is no [2] tag
1062 enc-part [3] EncryptedData -- EncKrbPrivPart
1063 }
1065 EncKrbPrivPart ::= [APPLICATION 28] SEQUENCE {
1066 user-data [0] OCTET STRING,
1067 timestamp [1] KerberosTime OPTIONAL,
1068 usec [2] Microseconds OPTIONAL,
1069 seq-number [3] UInt32 OPTIONAL,
1070 s-address [4] HostAddress -- sender's addr --,
1071 r-address [5] HostAddress OPTIONAL -- recip's addr
1072 }
1073 @end verbatim
1075 @c @include shishi-api-safe.texi
1078 @node Ticket Functions
1079 @section Ticket Functions
1081 @include shishi-api-tkt.texi
1084 @node AS Functions
1085 @section AS Functions
1087 The Authentication Service (AS) is used to get an initial ticket using
1088 e.g. your password. The following illustrates the AS-REQ and AS-REP
1089 ASN.1 structures.
1091 @verbatim
1092 -- Request --
1094 AS-REQ ::= KDC-REQ {10}
1096 KDC-REQ {INTEGER:tagnum} ::= [APPLICATION tagnum] SEQUENCE {
1097 pvno [1] INTEGER (5) -- first tag is [1], not [0] --,
1098 msg-type [2] INTEGER (tagnum),
1099 padata [3] SEQUENCE OF PA-DATA OPTIONAL,
1100 req-body [4] KDC-REQ-BODY
1101 }
1103 KDC-REQ-BODY ::= SEQUENCE {
1104 kdc-options [0] KDCOptions,
1105 cname [1] PrincipalName OPTIONAL
1106 -- Used only in AS-REQ --,
1107 realm [2] Realm
1108 -- Server's realm
1109 -- Also client's in AS-REQ --,
1110 sname [3] PrincipalName OPTIONAL,
1111 from [4] KerberosTime OPTIONAL,
1112 till [5] KerberosTime,
1113 rtime [6] KerberosTime OPTIONAL,
1114 nonce [7] UInt32,
1115 etype [8] SEQUENCE OF Int32 -- EncryptionType
1116 -- in preference order --,
1117 addresses [9] HostAddresses OPTIONAL,
1118 enc-authorization-data [10] EncryptedData {
1119 AuthorizationData,
1120 { keyuse-TGSReqAuthData-sesskey
1121 | keyuse-TGSReqAuthData-subkey }
1122 } OPTIONAL,
1123 additional-tickets [11] SEQUENCE OF Ticket OPTIONAL
1124 }
1126 -- Reply --
1128 AS-REP ::= KDC-REP {11, EncASRepPart, {keyuse-EncASRepPart}}
1130 KDC-REP {INTEGER:tagnum,
1131 TypeToEncrypt,
1132 UInt32:KeyUsages} ::= [APPLICATION tagnum] SEQUENCE {
1133 pvno [0] INTEGER (5),
1134 msg-type [1] INTEGER (tagnum),
1135 padata [2] SEQUENCE OF PA-DATA OPTIONAL,
1136 crealm [3] Realm,
1137 cname [4] PrincipalName,
1138 ticket [5] Ticket,
1139 enc-part [6] EncryptedData {TypeToEncrypt, KeyUsages}
1140 }
1142 EncASRepPart ::= [APPLICATION 25] EncKDCRepPart
1144 EncKDCRepPart ::= SEQUENCE {
1145 key [0] EncryptionKey,
1146 last-req [1] LastReq,
1147 nonce [2] UInt32,
1148 key-expiration [3] KerberosTime OPTIONAL,
1149 flags [4] TicketFlags,
1150 authtime [5] KerberosTime,
1151 starttime [6] KerberosTime OPTIONAL,
1152 endtime [7] KerberosTime,
1153 renew-till [8] KerberosTime OPTIONAL,
1154 srealm [9] Realm,
1155 sname [10] PrincipalName,
1156 caddr [11] HostAddresses OPTIONAL
1157 }
1158 @end verbatim
1160 @include shishi-api-as.texi
1163 @node TGS Functions
1164 @section TGS Functions
1166 The Ticket Granting Service (TGS) is used to get subsequent tickets,
1167 authenticated by other tickets (so called ticket granting tickets).
1168 The following illustrates the TGS-REQ and TGS-REP ASN.1 structures.
1170 @verbatim
1171 -- Request --
1173 TGS-REQ ::= KDC-REQ {12}
1175 KDC-REQ {INTEGER:tagnum} ::= [APPLICATION tagnum] SEQUENCE {
1176 pvno [1] INTEGER (5) -- first tag is [1], not [0] --,
1177 msg-type [2] INTEGER (tagnum),
1178 padata [3] SEQUENCE OF PA-DATA OPTIONAL,
1179 req-body [4] KDC-REQ-BODY
1180 }
1182 KDC-REQ-BODY ::= SEQUENCE {
1183 kdc-options [0] KDCOptions,
1184 cname [1] PrincipalName OPTIONAL
1185 -- Used only in AS-REQ --,
1186 realm [2] Realm
1187 -- Server's realm
1188 -- Also client's in AS-REQ --,
1189 sname [3] PrincipalName OPTIONAL,
1190 from [4] KerberosTime OPTIONAL,
1191 till [5] KerberosTime,
1192 rtime [6] KerberosTime OPTIONAL,
1193 nonce [7] UInt32,
1194 etype [8] SEQUENCE OF Int32 -- EncryptionType
1195 -- in preference order --,
1196 addresses [9] HostAddresses OPTIONAL,
1197 enc-authorization-data [10] EncryptedData {
1198 AuthorizationData,
1199 { keyuse-TGSReqAuthData-sesskey
1200 | keyuse-TGSReqAuthData-subkey }
1201 } OPTIONAL,
1202 additional-tickets [11] SEQUENCE OF Ticket OPTIONAL
1203 }
1205 -- Reply --
1207 TGS-REP ::= KDC-REP {13, EncTGSRepPart,
1208 { keyuse-EncTGSRepPart-sesskey
1209 | keyuse-EncTGSRepPart-subkey }}
1211 KDC-REP {INTEGER:tagnum,
1212 TypeToEncrypt,
1213 UInt32:KeyUsages} ::= [APPLICATION tagnum] SEQUENCE {
1214 pvno [0] INTEGER (5),
1215 msg-type [1] INTEGER (tagnum),
1216 padata [2] SEQUENCE OF PA-DATA OPTIONAL,
1217 crealm [3] Realm,
1218 cname [4] PrincipalName,
1219 ticket [5] Ticket,
1220 enc-part [6] EncryptedData {TypeToEncrypt, KeyUsages}
1221 }
1223 EncTGSRepPart ::= [APPLICATION 26] EncKDCRepPart
1225 EncKDCRepPart ::= SEQUENCE {
1226 key [0] EncryptionKey,
1227 last-req [1] LastReq,
1228 nonce [2] UInt32,
1229 key-expiration [3] KerberosTime OPTIONAL,
1230 flags [4] TicketFlags,
1231 authtime [5] KerberosTime,
1232 starttime [6] KerberosTime OPTIONAL,
1233 endtime [7] KerberosTime,
1234 renew-till [8] KerberosTime OPTIONAL,
1235 srealm [9] Realm,
1236 sname [10] PrincipalName,
1237 caddr [11] HostAddresses OPTIONAL
1238 }
1239 @end verbatim
1241 @include shishi-api-tgs.texi
1244 @node Ticket (ASN.1) Functions
1245 @section Ticket (ASN.1) Functions
1247 @include shishi-api-ticket.texi
1249 @node AS/TGS Functions
1250 @section AS/TGS Functions
1252 The Authentication Service (AS) is used to get an initial ticket using
1253 e.g. your password. The Ticket Granting Service (TGS) is used to get
1254 subsequent tickets using other tickets. Protocol wise the procedures
1255 are very similar, which is the reason they are described together.
1256 The following illustrates the AS-REQ, TGS-REQ and AS-REP, TGS-REP
1257 ASN.1 structures. Most of the functions use the mnemonic ``KDC''
1258 instead of either AS or TGS, which means the function operates on both
1259 AS and TGS types. Only where the distinction between AS and TGS is
1260 important are the AS and TGS names used. Remember, these are
1261 low-level functions, and normal applications will likely be satisfied
1262 with the AS (@pxref{AS Functions}) and TGS (@pxref{TGS Functions})
1263 interfaces, or the even more high-level Ticket Set (@pxref{Ticket Set
1264 Functions}) interface.
1266 @verbatim
1267 -- Request --
1269 AS-REQ ::= KDC-REQ {10}
1270 TGS-REQ ::= KDC-REQ {12}
1272 KDC-REQ {INTEGER:tagnum} ::= [APPLICATION tagnum] SEQUENCE {
1273 pvno [1] INTEGER (5) -- first tag is [1], not [0] --,
1274 msg-type [2] INTEGER (tagnum),
1275 padata [3] SEQUENCE OF PA-DATA OPTIONAL,
1276 req-body [4] KDC-REQ-BODY
1277 }
1279 KDC-REQ-BODY ::= SEQUENCE {
1280 kdc-options [0] KDCOptions,
1281 cname [1] PrincipalName OPTIONAL
1282 -- Used only in AS-REQ --,
1283 realm [2] Realm
1284 -- Server's realm
1285 -- Also client's in AS-REQ --,
1286 sname [3] PrincipalName OPTIONAL,
1287 from [4] KerberosTime OPTIONAL,
1288 till [5] KerberosTime,
1289 rtime [6] KerberosTime OPTIONAL,
1290 nonce [7] UInt32,
1291 etype [8] SEQUENCE OF Int32 -- EncryptionType
1292 -- in preference order --,
1293 addresses [9] HostAddresses OPTIONAL,
1294 enc-authorization-data [10] EncryptedData {
1295 AuthorizationData,
1296 { keyuse-TGSReqAuthData-sesskey
1297 | keyuse-TGSReqAuthData-subkey }
1298 } OPTIONAL,
1299 additional-tickets [11] SEQUENCE OF Ticket OPTIONAL
1300 }
1302 -- Reply --
1304 AS-REP ::= KDC-REP {11, EncASRepPart, {keyuse-EncASRepPart}}
1305 TGS-REP ::= KDC-REP {13, EncTGSRepPart,
1306 { keyuse-EncTGSRepPart-sesskey
1307 | keyuse-EncTGSRepPart-subkey }}
1309 KDC-REP {INTEGER:tagnum,
1310 TypeToEncrypt,
1311 UInt32:KeyUsages} ::= [APPLICATION tagnum] SEQUENCE {
1312 pvno [0] INTEGER (5),
1313 msg-type [1] INTEGER (tagnum),
1314 padata [2] SEQUENCE OF PA-DATA OPTIONAL,
1315 crealm [3] Realm,
1316 cname [4] PrincipalName,
1317 ticket [5] Ticket,
1318 enc-part [6] EncryptedData {TypeToEncrypt, KeyUsages}
1319 }
1321 EncASRepPart ::= [APPLICATION 25] EncKDCRepPart
1322 EncTGSRepPart ::= [APPLICATION 26] EncKDCRepPart
1324 EncKDCRepPart ::= SEQUENCE {
1325 key [0] EncryptionKey,
1326 last-req [1] LastReq,
1327 nonce [2] UInt32,
1328 key-expiration [3] KerberosTime OPTIONAL,
1329 flags [4] TicketFlags,
1330 authtime [5] KerberosTime,
1331 starttime [6] KerberosTime OPTIONAL,
1332 endtime [7] KerberosTime,
1333 renew-till [8] KerberosTime OPTIONAL,
1334 srealm [9] Realm,
1335 sname [10] PrincipalName,
1336 caddr [11] HostAddresses OPTIONAL
1337 }
1338 @end verbatim
1340 @include shishi-api-kdc.texi
1343 @node Authenticator Functions
1344 @section Authenticator Functions
1346 An ``Authenticator'' is a ASN.1 structure that work as a proof that an
1347 entity owns a ticket. It is usually embedded in the AP-REQ structure
1348 (@pxref{AP-REQ and AP-REP Functions}), and you most likely want to use
1349 an AP-REQ instead of a Authenticator in normal applications. The
1350 following illustrates the Authenticator ASN.1 structure.
1352 @verbatim
1353 Authenticator ::= [APPLICATION 2] SEQUENCE {
1354 authenticator-vno [0] INTEGER (5),
1355 crealm [1] Realm,
1356 cname [2] PrincipalName,
1357 cksum [3] Checksum OPTIONAL,
1358 cusec [4] Microseconds,
1359 ctime [5] KerberosTime,
1360 subkey [6] EncryptionKey OPTIONAL,
1361 seq-number [7] UInt32 OPTIONAL,
1362 authorization-data [8] AuthorizationData OPTIONAL
1363 }
1364 @end verbatim
1366 @include shishi-api-authenticator.texi
1369 @node Cryptographic Functions
1370 @section Cryptographic Functions
1372 Underneath the high-level functions described earlier, cryptographic
1373 operations are happening. If you need to access these cryptographic
1374 primitives directly, this section describes the functions available.
1376 Most cryptographic operations need keying material, and cryptographic
1377 keys have been isolated into it's own data structure
1378 @code{Shishi_key}. The following illustrates it's contents, but note
1379 that you cannot access it's elements directly but must use the
1380 accessor functions described below.
1382 @verbatim
1383 struct Shishi_key
1384 {
1385 int type; /* RFC 1510 encryption integer type */
1386 char *value; /* Cryptographic key data */
1387 int version; /* RFC 1510 ``kvno'' */
1388 };
1389 @end verbatim
1391 All functions that operate on this data structure are described now.
1393 @include shishi-api-key.texi
1395 Applications that run uninteractively may need keying material. In
1396 these cases, the keys are stored in a file, a file that is normally
1397 stored on the local host. The file should be protected from
1398 unauthorized access. The file is in ASCII format and contains keys as
1399 outputed by @code{shishi_key_print()}. All functions that handle
1400 these keys sets are described now.
1402 @include shishi-api-keys.texi
1404 The previous functions require that the filename is known. For some
1405 applications, servers, it makes sense to provide a system default.
1406 These key sets used by server applications are known as ``hostkeys''.
1407 Here are the functions that operate on hostkeys (they are mostly
1408 wrappers around generic key sets).
1410 @include shishi-api-hostkeys.texi
1412 After creating the key structure, it can be used to encrypt and
1413 decrypt data, calculate checksum on data etc. All available functions
1414 are described now.
1416 @include shishi-api-crypto.texi
1419 @node Utility Functions
1420 @section Utility Functions
1422 @include shishi-api-utility.texi
1425 @node Error Handling
1426 @section Error Handling
1427 @cindex Error Handling
1429 Most functions in `Libshishi' are returning an error if they fail.
1430 For this reason, the application should always catch the error
1431 condition and take appropriate measures, for example by releasing the
1432 resources and passing the error up to the caller, or by displaying a
1433 descriptive message to the user and cancelling the operation.
1435 Some error values do not indicate a system error or an error in the
1436 operation, but the result of an operation that failed properly.
1438 @menu
1439 * Error values:: A list of all error values used.
1440 * Error strings:: How to get a descriptive string from a value.
1441 @end menu
1443 @node Error values
1444 @subsection Error values
1446 Errors are returned as an @code{int}. Except for the SHISHI_OK case,
1447 an application should always use the constants instead of their
1448 numeric value. Applications are encouraged to use the constants even
1449 for SHISHI_OK as it improves readability. Possible values are:
1451 @table @code
1452 @item SHISHI_OK
1453 This value indicates success. The value of this error is guaranteed
1454 to always be @code{0} so you may use it in boolean constructs.
1456 @include shishi-api-error-labels.texi
1458 @end table
1460 @node Error strings
1461 @subsection Error strings
1463 @include shishi-api-error.texi
1465 @node Examples
1466 @section Examples
1467 @cindex Examples
1469 This section will be extended to contain walk-throughs of example code
1470 that demonstrate how `Shishi' is used to write your own applications
1471 that support Kerberos 5. The rest of the current section consists of
1472 some crude hints for the example client/server applications that is
1473 part of Shishi, taken from an email but saved here for lack of a
1474 better place to put it.
1476 There are two programs: 'client' and 'server' in src/.
1478 The client output an AP-REQ, waits for an AP-REP, and then simply
1479 reads data from stdin.
1481 The server waits for an AP-REQ, parses it and prints an AP-REP, and
1482 then read data from stdin.
1484 Both programs accept a Kerberos server name as the first command line
1485 argument. Your KDC must know this server, since the client tries to
1486 get a ticket for it (first it gets a ticket granting ticket for the
1487 default username), and you must write the key for the server into
1488 /usr/local/etc/shishi.keys on the Shishi format, e.g.:
1490 @example
1491 -----BEGIN SHISHI KEY-----
1492 Keytype: 16 (des3-cbc-sha1-kd)
1493 Principal: sample/latte.josefsson.org
1494 Realm: JOSEFSSON.ORG
1496 8W0VrQQBpxlACPQEqN91EHxbvFFo2ltt
1497 -----END SHISHI KEY-----
1498 @end example
1500 You must extract the proper encryption key from the KDC in some way.
1501 (This part will be easier when Shishi include a KDC, a basic one isn't
1502 far away, give me a week or to.)
1504 The intention is that the data read, after the authentication phase,
1505 should be protected using KRB_SAFE (see RFC) but I haven't added this
1506 yet.
1508 @node Generic Security Service
1509 @section Generic Security Service
1510 @cindex Generic Security Service (GSS)
1512 As an alternative to the native Shishi programming API, it is possible
1513 to program Shishi through the Generic Security Services (GSS) API.
1514 The advantage of using GSS-API in your security application, instead
1515 of the native Shishi API, is that it will be easier to port your
1516 application between different Kerberos 5 implementations, and even
1517 beyond Kerberos 5 to different security systems, that support GSS-API.
1518 In the free software world, however, the only widely used security
1519 system that supports GSS-API is Kerberos 5, so the last advantage is
1520 somewhat academic. But if you are porting applications using GSS-API
1521 for other Kerberos 5 implementations, or want a more mature and stable
1522 API than the native Shishi API, you may find using Shishi's GSS-API
1523 interface compelling. Note that GSS-API only offer basic services,
1524 for more advanced uses you must use the native API.
1526 Since the GSS is not specific to Shishi, it is distributed
1527 independently from Shishi. Further information on the GSS project can
1528 be found at @url{http://josefsson.org/gss/}.
1530 @c **********************************************************
1531 @c ******************* Acknowledgements *******************
1532 @c **********************************************************
1533 @node Acknowledgements
1534 @chapter Acknowledgements
1536 Shishi uses Libtasn1 by Fabio Fiorina, Libnettle by Niels Möller,
1537 Libgcrypt and Libgpg-error by Werner Koch, Libidn by Simon Josefsson,
1538 cvs2cl by Karl Fogel, and gdoc by Michael Zucchi.
1540 Several GNU packages simplified development considerably, those
1541 packages include Autoconf, Automake, Libtool, Gnulib, Gettext, Indent,
1542 CVS, Texinfo, Help2man and Emacs.
1544 Several people reported bugs, sent patches or suggested improvements,
1545 see the file THANKS.
1547 @c **********************************************************
1548 @c ******************* Appendices *************************
1549 @c **********************************************************
1551 @node Copying This Manual
1552 @appendix Copying This Manual
1554 @menu
1555 * GNU Free Documentation License:: License for copying this manual.
1556 @end menu
1558 @include fdl.texi
1560 @include gpl.texi
1562 @node Concept Index
1563 @unnumbered Concept Index
1565 @printindex cp
1567 @node Function and Data Index
1568 @unnumbered Function and Data Index
1570 @printindex fn
1572 @summarycontents
1573 @contents
1574 @bye