| blob | 4408b06cdd17ab2b208a90605515fa6e6b65b066 |
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
23 @value{UPDATED}, for Version @value{VERSION} of the @acronym{Shishi}
24 library.
26 Copyright @copyright{} 2002 Simon Josefsson.
28 @quotation
29 Permission is granted to copy, distribute and/or modify this document
30 under the terms of the GNU Free Documentation License, Version 1.1 or
31 any later version published by the Free Software Foundation; with no
32 Invariant Sections, with the Front-Cover texts being ``A GNU Manual,''
33 and with the Back-Cover Texts as in (a) below. A copy of the license
34 is included in the section entitled ``GNU Free Documentation
35 License.''
37 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and
38 modify this GNU Manual, like GNU software. Copies published by the
39 Free Software Foundation raise funds for GNU development.''
40 @end quotation
41 @end copying
43 @dircategory Net Utilities
44 @direntry
45 * shishi: (shishi). An RFC 1510 implementation
46 @end direntry
48 @titlepage
49 @title The Shishi Manual
50 @subtitle for version @value{VERSION}, @value{UPDATED}
51 @author Simon Josefsson (@email{bug-shishi@@josefsson.org})
52 @page
53 @vskip 0pt plus 1filll
54 @insertcopying
55 @end titlepage
57 @contents
59 @ifnottex
60 @node Top
61 @top Shishi
62 @insertcopying
63 @end ifnottex
65 @menu
66 * Introduction:: How to use this manual.
67 * User Manual:: Using Shishi as end-user.
68 * Administration Manual:: Administrating server aspects of Shishi.
69 * Programming Manual:: Calling Shishi from a programming language.
70 * Acknowledgements:: Whom to blame.
72 Appendices
74 * Copying This Manual:: How you can copy and share this manual.
75 * Copying:: How you can copy and share the source.
77 Indices
79 * Concept Index:: Index of concepts and programs.
80 * Function and Data Index:: Index of functions, variables and data types.
81 @end menu
84 @c **********************************************************
85 @c ******************** Introduction **********************
86 @c **********************************************************
87 @node Introduction
88 @chapter Introduction
90 Shishi implements the RFC 1510 network security system, also known as
91 Kerberos 5.
93 @menu
94 * Getting Started::
95 * Features and Status::
96 * Overview::
97 * Cryptographic Overview::
98 * Supported Platforms::
99 * Bug Reports::
100 @end menu
102 @node Getting Started
103 @section Getting Started
105 This manual documents the Shishi application and library programming
106 interface. All commands, functions and data types provided by Shishi
107 are explained.
109 The reader is assumed to possess basic familiarity with network
110 security and the RFC 1510 security system.
112 This manual can be used in several ways. If read from the beginning
113 to the end, it gives a good introduction into the library and how it
114 can be used in an application. Forward references are included where
115 necessary. Later on, the manual can be used as a reference manual to
116 get just the information needed about any particular interface of the
117 library. Experienced programmers might want to start looking at the
118 examples at the end of the manual, and then only read up those parts
119 of the interface which are unclear.
121 @node Features and Status
122 @section Features and Status
124 Shishi might have a couple of advantages over other packages doing a
125 similar job.
127 @table @asis
128 @item It's Free Software
129 Anybody can use, modify, and redistribute it under the terms of the GNU
130 General Public License (@pxref{Copying}).
132 @item It's thread-safe
133 The library uses no global variables.
135 @item It's internationalized
136 It handles non-ASCII username and passwords and user visible strings
137 used in the library (error messages) can be translated into the users'
138 language.
140 @item It's portable
141 It should work on all Unix like operating systems, including Windows.
143 @end table
145 Shishi is far from feature complete, it is not even a full RFC 1510
146 implementation yet. However, some basic functionality is implemented.
147 A few implemented feature are mentioned below.
149 @itemize @bullet
151 @item Initial authentication (AS) from raw key or password.
152 This step is typically used to acquire a ticket granting ticket and,
153 less commonly, a server ticket.
155 @item Subsequent authentication (TGS).
156 This step is typically used to acquire a server ticket, by
157 authenticating yourself using the ticket granting ticket.
159 @item Client-Server authentication (AP).
160 This step is used by clients and servers to prove to each other who
161 they are, using negotiated tickets.
163 @item Integrity protected communication (SAFE).
164 This step is used by clients and servers to exchange integrity
165 protected data with each other. The key is typically agreed on using
166 the Client-Server authentication step.
168 @item Ticket cache, supporting multiple principals and realms.
169 As tickets have a life time of typically several hours, they are
170 managed in disk files. There can be multiple ticket caches, and each
171 ticket cache can store tickets for multiple clients (users), servers,
172 encryption types, etc. Functionality is provided for locating the
173 proper ticket for every use.
175 @item Most standard cryptographic primitives.
176 The believed most secure algorithms are supported
177 (@pxref{Cryptographic Overview}).
179 @item Telnet client and server.
180 This is used to remotely login to other machines, after authenticating
181 yourself with a ticket.
183 @item PAM module.
184 This is used to login locally on a machine.
186 @item KDC addresses located using DNS SRV RRs.
188 @end itemize
190 The following table summarize what the current objectives are (i.e.,
191 the todo list) and an estimate on how long it will take to implement
192 the feature. If you like to start working on anything, please let me
193 know so work duplication can be avoided.
195 @itemize @bullet
197 @item Cross-realm support (week).
199 @item Session keys in AP (week).
201 @item PKINIT (use libksba, weeks)
203 @item Finish GSSAPI support via GPL GSS (weeks)
204 Shishi will not support GSS, but a separate project ``GPL GSS'' is
205 under way to produce a generic GSS implementation, and it will use
206 Shishi to implement the Kerberos 5 mechanism.
208 @item Port to cyclone (cyclone need to mature first)
210 @item Modularize ASN.1 library so it can be replaced (days)
212 @item Modularize Crypto library so it can be replaced (days)
214 @item KDC (initiated, weeks)
216 @item PAM module (week)
217 Finished.
219 @item Set/Change password protocol (weeks?)
221 @item Port applications to use Shishi (indefinite)
223 @item Improve documentation
225 @item Improve internationalization
227 @item Fix fixed size buffers.
229 @end itemize
231 @node Overview
232 @section Overview
234 This section describes RFC 1510 from a protocol point of
235 view@footnote{The text is a lightly adapted version of the
236 introduction section from RFC 1510 by J. Kohl and C. Neuman, September
237 1993, unclear copyrights, but presumably owned by The Internet
238 Society.}.
240 Kerberos provides a means of verifying the identities of principals,
241 (e.g., a workstation user or a network server) on an open
242 (unprotected) network. This is accomplished without relying on
243 authentication by the host operating system, without basing trust on
244 host addresses, without requiring physical security of all the hosts
245 on the network, and under the assumption that packets traveling along
246 the network can be read, modified, and inserted at will. (Note,
247 however, that many applications use Kerberos' functions only upon the
248 initiation of a stream-based network connection, and assume the
249 absence of any "hijackers" who might subvert such a connection. Such
250 use implicitly trusts the host addresses involved.) Kerberos performs
251 authentication under these conditions as a trusted third- party
252 authentication service by using conventional cryptography, i.e.,
253 shared secret key. (shared secret key - Secret and private are often
254 used interchangeably in the literature. In our usage, it takes two
255 (or more) to share a secret, thus a shared DES key is a secret key.
256 Something is only private when no one but its owner knows it. Thus,
257 in public key cryptosystems, one has a public and a private key.)
259 The authentication process proceeds as follows: A client sends a
260 request to the authentication server (AS) requesting "credentials" for
261 a given server. The AS responds with these credentials, encrypted in
262 the client's key. The credentials consist of 1) a "ticket" for the
263 server and 2) a temporary encryption key (often called a "session
264 key"). The client transmits the ticket (which contains the client's
265 identity and a copy of the session key, all encrypted in the server's
266 key) to the server. The session key (now shared by the client and
267 server) is used to authenticate the client, and may optionally be used
268 to authenticate the server. It may also be used to encrypt further
269 communication between the two parties or to exchange a separate
270 sub-session key to be used to encrypt further communication.
272 The implementation consists of one or more authentication servers
273 running on physically secure hosts. The authentication servers
274 maintain a database of principals (i.e., users and servers) and their
275 secret keys. Code libraries provide encryption and implement the
276 Kerberos protocol. In order to add authentication to its
277 transactions, a typical network application adds one or two calls to
278 the Kerberos library, which results in the transmission of the
279 necessary messages to achieve authentication.
281 The Kerberos protocol consists of several sub-protocols (or
282 exchanges). There are two methods by which a client can ask a
283 Kerberos server for credentials. In the first approach, the client
284 sends a cleartext request for a ticket for the desired server to the
285 AS. The reply is sent encrypted in the client's secret key. Usually
286 this request is for a ticket-granting ticket (TGT) which can later be
287 used with the ticket-granting server (TGS). In the second method, the
288 client sends a request to the TGS. The client sends the TGT to the
289 TGS in the same manner as if it were contacting any other application
290 server which requires Kerberos credentials. The reply is encrypted in
291 the session key from the TGT.
293 Once obtained, credentials may be used to verify the identity of the
294 principals in a transaction, to ensure the integrity of messages
295 exchanged between them, or to preserve privacy of the messages. The
296 application is free to choose whatever protection may be necessary.
298 To verify the identities of the principals in a transaction, the
299 client transmits the ticket to the server. Since the ticket is sent
300 "in the clear" (parts of it are encrypted, but this encryption doesn't
301 thwart replay) and might be intercepted and reused by an attacker,
302 additional information is sent to prove that the message was
303 originated by the principal to whom the ticket was issued. This
304 information (called the authenticator) is encrypted in the session
305 key, and includes a timestamp. The timestamp proves that the message
306 was recently generated and is not a replay. Encrypting the
307 authenticator in the session key proves that it was generated by a
308 party possessing the session key. Since no one except the requesting
309 principal and the server know the session key (it is never sent over
310 the network in the clear) this guarantees the identity of the client.
312 The integrity of the messages exchanged between principals can also be
313 guaranteed using the session key (passed in the ticket and contained
314 in the credentials). This approach provides detection of both replay
315 attacks and message stream modification attacks. It is accomplished
316 by generating and transmitting a collision-proof checksum (elsewhere
317 called a hash or digest function) of the client's message, keyed with
318 the session key. Privacy and integrity of the messages exchanged
319 between principals can be secured by encrypting the data to be passed
320 using the session key passed in the ticket, and contained in the
321 credentials.
323 @node Cryptographic Overview
324 @section Cryptographic Overview
326 Shishi implements several of the standard cryptographic primitives.
327 Here are the names of the supported encryption suites, with some notes
328 on their status and there associated checksum suite. They are ordered
329 by increased security as perceived by the author.
331 @cindex DES
332 @cindex 3DES
333 @cindex AES
335 @table @code
337 @item NULL
339 @code{NULL} is a dummy encryption suite for debugging. Encryption and
340 decryption are identity functions. No integrity protection. It is
341 weak. It is associated with the @code{NULL} checksum.
343 @item des-cbc-crc
345 @code{des-cbc-crc} is DES encryption and decryption with 56 bit keys
346 and 8 byte blocks in CBC mode. The keys can be derived from passwords
347 by an obscure application specific algorithm. Data is integrity
348 protected with an unkeyed but encrypted @code{CRC32}-like checksum.
349 It is weak. It is associated with the @code{rsa-md5-des} checksum.
351 @item des-cbc-md4
353 @code{des-cbc-md4} is DES encryption and decryption with 56 bit keys
354 and 8 byte blocks in CBC mode. The keys can be derived from passwords
355 by an obscure application specific algorithm. Data is integrity
356 protected with an unkeyed but encrypted MD4 hash. It is weak. It is
357 associated with the @code{rsa-md4-des} checksum.
359 @item des-cbc-md5
361 @code{des-cbc-md5} is DES encryption and decryption with 56 bit keys
362 and 8 byte blocks in CBC mode. The keys can be derived from passwords
363 by an obscure application specific algorithm. Data is integrity
364 protected with an unkeyed but encrypted MD5 hash. It is weak. It is
365 associated with the @code{rsa-md5-des} checksum. This is the
366 strongest RFC 1510 interoperable mechanism.
368 @item des3-cbc-sha1-kd
370 @code{des3-cbc-sha1-kd} is DES encryption and decryption with three 56
371 bit keys (effective key size 112 bits) and 8 byte blocks in CBC
372 mode. The keys can be derived from passwords by a algorithm based on
373 the paper "A Better Key Schedule For DES-like Ciphers"
374 @footnote{@url{http://www.research.att.com/~smb/papers/ides.pdf}} by
375 Uri Blumenthal and Steven M. Bellovin (it is not clear if the
376 algorithm, and the way it is used, is used by any other protocols,
377 although it seems unlikely). Data is integrity protected with a keyed
378 (HMAC) SHA1 hash. It has no security proof, but is assumed to provide
379 adequate security in the sense that knowledge on how to crack it is
380 not known to the public. It is associated with the
381 @code{hmac-sha1-des3-kd} checksum.
383 @item aes128-cts-hmac-sha1-96
384 @item aes256-cts-hmac-sha1-96.
386 @code{aes128-cts-hmac-sha1-96} and @code{aes256-cts-hmac-sha1-96} is
387 AES encryption and decryption with 128 bit and 256 bit key,
388 respectively, and 16 byte blocks in CBC mode with Cipher Text
389 Stealing. Cipher Text Stealing means data length of encrypted data is
390 preserved (pure CBC add up to 7 pad characters). The keys can be
391 derived from passwords with RSA Laboratories PKCS#5 Password Based Key
392 Derivation Function
393 2@footnote{@url{http://www.rsasecurity.com/rsalabs/pkcs/pkcs-5/}},
394 which is allegedly provably secure in a random oracle model. Data is
395 integrity protected with a keyed (HMAC) SHA1 hash truncated to 96
396 bits. There is no security proof, but the schemes are assumed to
397 provide good security, but has, as AES itself, yet to receive the test
398 of time. It is associated with the @code{hmac-sha1-96-aes128} and
399 @code{hmac-sha1-96-aes256} checksums, respectively.
401 @end table
403 The protocol do not include any way to negotiate which checksum
404 mechanisms to use, so in most cases the associated checksum will be
405 used. However, checksum mechanisms can be used with other encryption
406 mechanisms, as long as they are compatible in terms of key format etc.
407 Here are the names of the supported checksum mechanisms, with some
408 notes on their status and the compatible encryption mechanisms. They
409 are ordered by increased security as perceived by the author.
411 @table @code
413 @item NULL
415 @code{NULL} is a dummy checksum suite for debugging. It provides no
416 integrity. It is weak. It is compatible with the @code{NULL}
417 encryption mechanism.
419 @item rsa-md4-des
421 @code{rsa-md4-des} is a DES CBC encryption of one block of random data
422 and a unkeyed MD4 hash computed over the random data and the message
423 to integrity protect. The key used is derived from the base protocol
424 key by XOR with a constant. It is weak. It is compatible with the
425 @code{des-cbc-crc}, @code{des-cbc-md4}, @code{des-cbc-md5} encryption
426 mechanisms.
428 @item rsa-md5-des
430 @code{rsa-md5-des} is a DES CBC encryption of one block of random data
431 and a unkeyed MD5 hash computed over the random data and the message
432 to integrity protect. The key used is derived from the base protocol
433 key by XOR with a constant. It is weak. It is compatible with the
434 @code{des-cbc-crc}, @code{des-cbc-md4}, @code{des-cbc-md5} encryption
435 mechanisms.
437 @item hmac-sha1-des3-kd
439 @code{hmac-sha1-des3-kd} is a keyed (HMAC) SHA1 hash computed over the
440 message. The key is derived from the base protocol by the simplified
441 key derivation function (similar to the password key derivation
442 functions of @code{des3-cbc-sha1-kd}). It has no security proof, but
443 is assumed to provide good security. It is compatible with the
444 @code{des3-cbc-sha1-kd} encryption mechanism.
446 @item hmac-sha1-96-aes128
447 @item hmac-sha1-96-aes256
449 @code{hmac-sha1-96-aes*} are keyed (HMAC) SHA1 hashes computed over
450 the message and then truncated to 96 bits. The key is derived from
451 the base protocol by the simplified key derivation function (similar
452 to the password key derivation functions of @code{des3-cbc-sha1-kd}).
453 It has no security proof, but is assumed to provide good security. It
454 is compatible with the @code{des3-cbc-sha1-kd} encryption mechanism.
456 @end table
459 @node Supported Platforms
460 @section Supported Platforms
462 Shishi has at some point in time been tested on the following
463 platforms.
465 @enumerate
467 @item Debian GNU/Linux 3.0r0 (Woody)
468 @cindex Debian
470 GCC 2.95.4 and GNU Make. alphaev67-unknown-linux-gnu,
471 alphaev6-unknown-linux-gnu, hppa64-unknown-linux-gnu,
472 i686-pc-linux-gnu, ia64-unknown-linux-gnu.
474 @item Tru64 UNIX
475 @cindex Tru64
477 Tru64 UNIX C compiler and Tru64 Make. alphaev68-dec-osf5.1.
479 @item SuSE Linux 7.1
480 @cindex SuSE
482 GCC 2.96 and GNU Make. alphaev67-unknown-linux-gnu.
484 @item SuSE Linux 7.2a
485 @cindex SuSE Linux
487 GCC 3.0 and GNU Make. ia64-unknown-linux-gnu.
489 @item RedHat Linux 7.2
490 @cindex RedHat
492 GCC 2.96 and GNU Make. i686-pc-linux-gnu.
494 @item RedHat Linux 8.0
495 @cindex RedHat
497 GCC 3.2 and GNU Make. i686-pc-linux-gnu.
499 @c @item IRIX 6.5
500 @c @cindex IRIX
501 @c
502 @c mips-sgi-irix6.5, MIPS C compiler, IRIX Make.
504 @c @item AIX 4.3.2
505 @c @cindex AIX
506 @c
507 @c rs6000-ibm-aix4.3.2.0, IBM C for AIX compiler, AIX Make.
509 @c @item Microsoft Windows 2000
510 @c @cindex Windows
511 @c
512 @c GCC 2.95.2-6, GNU make. i686-pc-cygwin
514 @c @item HP-UX 11.11
515 @c @cindex HP-UX
516 @c
517 @c HP-UX C compiler and HP Make. hppa2.0w-hp-hpux11.11.
519 @item SUN Solaris 2.8
520 @cindex Solaris
522 Sun WorkShop Compiler C 6.0 and SUN Make. sparc-sun-solaris2.8.
524 @item NetBSD 1.6
525 @cindex NetBSD
527 GCC 2.95.3 and GNU Make. alpha-unknown-netbsd1.6,
528 i386-unknown-netbsdelf1.6.
530 @item OpenBSD 3.1
531 @cindex OpenBSD
533 GCC 2.95.3 and GNU Make.
534 @c alpha-unknown-openbsd3.1, (alignment problems)
535 i386-unknown-openbsd3.1.
537 @item FreeBSD 4.7
538 @cindex FreeBSD
540 GCC 2.95.4 and GNU Make. alpha-unknown-freebsd4.7,
541 i386-unknown-freebsd4.7.
543 @end enumerate
545 If you use Shishi on, or port Shishi to, a new platform please report
546 it to the author (@pxref{Bug Reports}).
548 @node Bug Reports
549 @section Bug Reports
550 @cindex Reporting Bugs
552 If you think you have found a bug in Shishi, please investigate it and
553 report it.
555 @itemize @bullet
557 @item Please make sure that the bug is really in Shishi, and
558 preferably also check that it hasn't already been fixed in the latest
559 version.
561 @item You have to send us a test case that makes it possible for us to
562 reproduce the bug.
564 @item You also have to explain what is wrong; if you get a crash, or
565 if the results printed are not good and in that case, in what way.
566 Make sure that the bug report includes all information you would need
567 to fix this kind of bug for someone else.
569 @end itemize
571 Please make an effort to produce a self-contained report, with
572 something definite that can be tested or debugged. Vague queries or
573 piecemeal messages are difficult to act on and don't help the
574 development effort.
576 If your bug report is good, we will do our best to help you to get a
577 corrected version of the software; if the bug report is poor, we won't
578 do anything about it (apart from asking you to send better bug
579 reports).
581 If you think something in this manual is unclear, or downright
582 incorrect, or if the language needs to be improved, please also send a
583 note.
585 Send your bug report to:
587 @center @samp{bug-shishi@@josefsson.org}
590 @c **********************************************************
591 @c ******************** User Manual **********************
592 @c **********************************************************
593 @node User Manual
594 @chapter User Manual
595 @cindex End-user Shishi usage
597 Usually Shishi interacts with you to get some initial authentication
598 information like a password, and then contacts a server to receive a
599 so called ticket granting ticket. From now on, you rarely interacts
600 with Shishi directly. Applications that needs security services
601 instruct the Shishi library to use the ticket granting ticket to get
602 new tickets for various servers. An example could be if you log on to
603 a host remotely; the host usually requires authentication before
604 permitting you in. The @samp{telnet} application uses the ticket
605 granting ticket to get a ticket for the server, and then use this
606 ticket to authenticate you to the server (and usually also
607 authenticating the server to you, so you know who you are talking with
608 the right host). You perform the initial authentication by typing
609 @command{shishi as} at the prompt. The @samp{as} command is the
610 default command for Shishi, so you can type only @command{shishi} if
611 you want to save a few key strokes. Sometimes it is necessary to
612 supply options telling Shishi what your principal (username) or realm
613 is. @xref{as}, for the details. In the example, I need to specify my
614 name and realm.
616 @example
617 @cartouche
618 jas@@latte:~/src/shishi$ shishi as --client-name \
619 simon --realm JOSEFSSON.ORG
620 Unknown option `read-krb5conf=/etc/krb5.conf'
621 Unknown option `server-realm=lab.josefsson.org'
622 Unknown option `.josefsson.org'
623 Sending to latte.josefsson.org (217.208.172.73)...
624 Enter password for `simon@@JOSEFSSON.ORG':
625 Warning: using insecure memory!
626 simon@@JOSEFSSON.ORG:
627 Authtime: Fri Nov 22 23:44:02 2002
628 Endtime: Sat Nov 23 00:00:42 2002 valid
629 Service: krbtgt/JOSEFSSON.ORG
630 Key type: des3-cbc-sha1-kd (16)
631 Flags: 16384
632 jas@@latte:~/src/shishi$
633 @end cartouche
634 @end example
636 As you can see, Shishi also prints a short description of the ticket
637 received.
639 A logical next step is to display all tickets you have received (by
640 the way, the tickets are usually stored as text in
641 @file{~/.shishi/tickets}). This is achieved by typing @command{shishi
642 list}.
644 @example
645 @cartouche
646 jas@@latte:~/src/shishi$ shishi list
647 Unknown option `read-krb5conf=/etc/krb5.conf'
648 Unknown option `server-realm=lab.josefsson.org'
649 Unknown option `.josefsson.org'
650 Tickets in `/home/jas/.shishi/tickets':
652 jas@@JOSEFSSON.ORG:
653 Authtime: Fri Nov 22 23:46:18 2002
654 Endtime: Sat Nov 23 00:02:58 2002 valid
655 Service: krbtgt/JOSEFSSON.ORG
656 Key type: des3-cbc-sha1-kd (16)
657 Flags: 16384
659 jas@@JOSEFSSON.ORG:
660 Authtime: Fri Nov 22 23:46:18 2002
661 Endtime: Sat Nov 23 00:02:58 2002 valid
662 Service: host/h73n1c1o299.bredband.skanova.com
663 Key type: des3-cbc-sha1-kd (16)
664 Flags: 0
666 2 tickets found.
667 jas@@latte:~/src/shishi$
668 @end cartouche
669 @end example
671 As you can see, I had a ticket for the server
672 @samp{host/h73n1c1o299.bredband.skanova.com} which was generated by
673 @samp{telnet}:ing to that host. The observant reader might notice
674 that it now says the tickets are owned by @samp{jas@@JOSEFSSON.ORG}
675 instead of @samp{simon@@JOSEFSSON.ORG}. This is because the identity
676 of the ticket owner is not stored in the ticket file, but must be set
677 every time with @samp{--client-name} parameter. Since the parameter
678 was not given, Shishi defaults to using the username on the system.
679 Perhaps this has been fixed in your version of Shishi, if not you are
680 very welcome to fix the problem.
682 If, for some weird reason, you want to manually get a ticket for a
683 specific server, you can use the @command{shishi tgs} command
684 (@pxref{tgs}). Normally, however, the application that uses Shishi
685 will take care of getting a ticket for the appropriate server, so you
686 don't need this command. But maybe you just want to tinker with
687 things. Or maybe you are bored. What do I know. (If you read this
688 far you really must be bored though.) Anyway.
690 @example
691 @cartouche
692 jas@@latte:~/src/shishi$ src/shishi tgs \
693 --server-name user/billg --client-name simon \
694 -e des-cbc-md5
695 Unknown option `read-krb5conf=/etc/krb5.conf'
696 Unknown option `server-realm=lab.josefsson.org'
697 Unknown option `.josefsson.org'
698 Searching tickets for client `simon' and server `krbtgt/JOSEFSSON.ORG'
699 Warning: using insecure memory!
700 Sending to latte.josefsson.org (217.208.172.73)...
701 jas@@JOSEFSSON.ORG:
702 Authtime: Fri Nov 22 23:46:18 2002
703 Endtime: Sat Nov 23 00:02:58 2002 valid
704 Service: user/billg
705 Key type: des-cbc-md5 (3)
706 Flags: 0
707 jas@@latte:~/src/shishi$
708 @end cartouche
709 @end example
711 As you can see, I received a ticket for @samp{user/billg} with a
712 @samp{des-cbc-md5} (@pxref{Cryptographic Overview}) encryption key
713 specified with the @samp{-e} parameter.
715 The rest of the commands are rather esoteric, so I think it is better
716 if you read the following reference sections instead of trying to
717 understand any weird examples I may come up with. If you can think of
718 something neat that the other commands can be used for, feel free to
719 suggest a paragraph or two here.
721 @menu
722 * as:: Initial Authentication.
723 * list:: Listing tickets in cache.
724 * tgs:: Getting subsequent tickets manually.
725 * client:: Simple Client.
726 * server:: Simple Server.
727 * ap:: Low-level client-server authentication.
728 * crypto:: Low-level cryptographic functions.
729 * kdc:: Low-level AS/TGS exchange.
730 * miscellaneous:: Various options.
731 @end menu
733 @node as
734 @section as
736 @example
737 as Acquire ticket granting ticket using password and
738 the Authentication Service (AS) exchange.
740 Options for Authentication Service (AS-OPTIONS):
741 --client-name=NAME Client name. Default is login username.
742 -e, --encryption-type=ETYPE,[ETYPE...]
743 Encryption types to use. ETYPE is either
744 registered name or integer.
745 -r, --realm=REALM Realm of client and server. Default is DNS domain
746 of local host.
747 --string-to-key=PASSWORD Password to decrypt response (discouraged).
748 Default is to prompt user.
749 @end example
752 @node list
753 @section list
755 @example
756 list List tickets.
758 Options for the List command (LIST-OPTIONS):
759 --server-name=NAME Restrict list to tickets for specified server.
760 @end example
763 @node tgs
764 @section tgs
766 @example
767 tgs Acquire ticket using the ticket granting ticket
768 and the Ticket-Granting Service (TGS) exchange.
770 Options for Ticket Granting Service (TGS-OPTIONS):
771 --client-name=NAME Client name. Default is login username. Used to
772 locate ticket granting ticket.
773 --encryption-type=ETYPE,[ETYPE...]
774 Encryption types to use. ETYPE is either
775 registered name or integer.
776 --realm=REALM Realm of server. Default is DNS domain of local
777 host.
778 --server-name=NAME Name of server.
779 --ticket-granter=NAME Name of server field in the ticket to use as the
780 ticket granter. Defaults to "krbtgt/REALM@@REALM"
781 where REALM is server realm (see --realm).
782 @end example
785 @node client
786 @section client
788 @example
789 client Kerberos client.
791 Options for Network Client (CLIENT-OPTIONS):
792 --options=OPTION[,OPTION...]
793 Indicate AP-OPTIONS separated by comma (,) or
794 whitespace. Options are integers (ORed together)
795 or the pre-defined strings "use-session-key"
796 indicating that the ticket is encrypted in the
797 server's TGT key rather than its own key (not
798 implemented) or "mutual-required" indicating that
799 mutual authentication is required.
800 --realm=REALM Realm of server. Defaults to DNS domain of local
801 host.
802 --server-name=NAME Name of server. Defaults to "sample/REALM" where
803 REALM is realm of server (see --realm).
804 @end example
807 @node server
808 @section server
810 @example
811 server Kerberos server.
813 Options for Network Server (SERVER-OPTIONS):
814 --client-name=NAME Client name. Default is login username.
815 --key-value=KEY Cipher key of server.
816 --realm=REALM Realm of server. Defaults to DNS domain of local
817 host.
818 --server-name=NAME Name of server. Defaults to "sample/REALM" where
819 REALM is realm of server (see --realm).
820 --string-to-key=PASSWORD Password to decrypt response (discouraged).
821 @end example
824 @node ap
825 @section ap
827 @example
828 ap Kerberos Client/Server Authentication (AP-REQ and
829 AP-REP).
831 Options for low-level Client/Server Authentication (AP-OPTIONS):
832 --data=B64STRING Base64 encoded data to checksum in generated
833 authenticator. By default checksum is omitted
834 (indicating no application payload).
835 --read-ap-request-file=[TYPE,]FILE
836 Read AP-REQ from FILE in format TYPE; TEXT
837 (default) or DER. Default is to generate it.
838 --read-data-file=[TYPE,]FILE
839 Read data to checksum in generated authenticator
840 from FILE in format TYPE, BASE64, HEX or BINARY
841 (default). By default checksum is omitted
842 (indicating no application payload).
843 --realm=REALM Realm of server. Defaults to DNS domain of local
844 host. Used for locating the ticket to use.
845 --server-name=NAME Name of server. Defaults to "krbtgt.DEFAULTREALM"
846 where DEFAULTREALM is realm of server. Used for
847 locating the ticket to use.
848 --write-ap-request-file=[TYPE,]FILE
849 Write AP-REQ to FILE in format TYPE; TEXT
850 (default) or DER. Default is stdout.
851 --write-authenticator-file=[TYPE,]FILE
852 Write authenticator to FILE in format TYPE; TEXT
853 (default) or DER. Not written by default.
854 @end example
857 @node crypto
858 @section crypto
860 @example
861 crypto Cryptographic functions.
863 Options for low-level cryptography (CRYPTO-OPTIONS):
864 --algorithm=ALGORITHM Use ciphering algorithm, expressed either as the
865 etype integer or the registered name.
866 --client-name=NAME Client name. Default is login username. Used for
867 generating cipher key.
868 --decrypt Decrypt data
869 --encrypt Encrypt data
870 --input-file=[TYPE,]FILE Read data from FILE in TYPE, BASE64, HEX or
871 BINARY (default).
872 --key-file=[TYPE,]FILE Read/write cipher key from/to FILE in TYPE
873 --key-value=KEY Specify cipher key directly (discouraged)
874 --output-file=[TYPE,]FILE Write data to FILE in TYPE, BASE64, HEX or
875 BINARY (default).
876 --realm=REALM Realm of principal. Defaults to DNS domain of
877 local host. Used for generating cipher key.
878 --string-to-key=PASSWORD Convert password to key. Client-name and
879 realm also modify the key.
880 @end example
883 @node kdc
884 @section kdc
886 @example
887 kdc Key Distribution Center Services; Authentication
888 Service (AS) and Ticket-Granting Service (TGS).
890 Options for low-level Key Distribution Services (KDC-OPTIONS):
891 --client-name=NAME Client name. Default is login username. Only for
892 AS.
893 --encryption-type=ETYPE,[ETYPE...]
894 Encryption types to use. ETYPE is either
895 registered name or integer.
896 --force-as Force AS mode. Default is to use TGS iff a TGT is
897 found.
898 --force-tgs Force TGS mode. Default is to use TGS iff a TGT is
899 found.
900 --key-value=KEY Cipher key to decrypt response (discouraged).
901 --read-kdc-request-file=[TYPE,]FILE
902 Read KDC-REQ from FILE in format TYPE; TEXT
903 (default) or DER. Default is to generate it.
904 --read-kdc-response-file=[TYPE,]FILE
905 Read KDC-REP from FILE in format TYPE; TEXT
906 (default) or DER. Default is to receive it from
907 server.
908 --realm=REALM Realm of server. Default is DNS domain of local
909 host. For AS, this also indicates realm of
910 client.
911 --request Only generate the request.
912 --response Only parse request and response and output ticket.
914 --sendrecv Only send request and receive response.
915 --server=HOST Send request to HOST. Default uses address from
916 configuration file.
917 --server-name=NAME Server name. Default is "krbtgt/REALM" where REALM
918 is server realm (see --realm).
919 --short-nonce Use a 4 byte nonce. Required by some buggy
920 servers.
921 --string-to-key=PASSWORD Password to decrypt response (discouraged).
922 Only for AS.
923 --ticket-granter=NAME Service name in ticket to use for authenticating
924 request. Only for TGS. Defaults to
925 "krbtgt/REALM@@REALM" where REALM is server realm
926 (see --realm).
927 --write-ap-request-file=[TYPE,]FILE
928 Write AP-REQ to FILE in TYPE, either TEXT
929 (default) or DER. Only for TGS. Not written by
930 default.
931 --write-authenticator-file=[TYPE,]FILE
932 Write Authenticator to FILE in TYPE, either TEXT
933 (default) or DER. Only for TGS. Not written by
934 default.
935 --write-kdc-request-file=[TYPE,]FILE
936 Write KDC-REQ to FILE in format TYPE; TEXT
937 (default) or DER. Not written by default.
938 --write-kdc-response-file=[TYPE,]FILE
939 Write KDC-REP to FILE in format TYPE; TEXT
940 (default) or DER. Not written by default.
941 @end example
944 @node miscellaneous
945 @section miscellaneous
947 These parameters are applicable to all commands.
949 @example
950 --configuration-file=FILE Read user configuration from file. Default
951 is ~/.shishi/config.
952 -o, --library-options=STRING Parse STRING as a configuration file
953 statement.
954 -q, --quiet, --silent Don't produce any output.
955 -s, --system-configuration-file=FILE
956 Read system wide configuration from file. Default
957 is /usr/local/etc/shishi.conf.
958 -t, --ticket-file=FILE Read tickets from FILE. Default is
959 $HOME/.shishi/tickets.
960 -v, --verbose Produce verbose output.
961 -w, --ticket-write-file=FILE Write tickets to FILE. Default is to write
962 them back to ticket file.
963 -?, --help Give this help list
964 --usage Give a short usage message
965 -V, --version Print program version
966 @end example
969 @c **********************************************************
970 @c **************** Administration Manual *****************
971 @c **********************************************************
972 @node Administration Manual
973 @chapter Administration Manual
975 TBW.
978 @c **********************************************************
979 @c *************** Programming Manual *********************
980 @c **********************************************************
981 @node Programming Manual
982 @chapter Programming Manual
983 @cindex Application Programming Interface (API)
985 This chapter describes all the publicly available functions in the
986 library.
988 @menu
989 * Preparation:: What you should do before using the library.
990 * Initialization Functions:: Creating library handle, configuration file.
991 * Ticket Set Functions:: High-level ticket management functions.
992 * AP-REQ and AP-REP Functions:: Client/Server authentication functions.
993 * SAFE and PRIV Functions:: Client/Server session data functions.
994 * Ticket Functions:: Medium-level ticket manipulation functions.
995 * AS Functions:: Medium-level initial authentication functions.
996 * TGS Functions:: Medium-level authentication functions.
997 * Ticket (ASN.1) Functions:: Low-level Ticket functions.
998 * AS/TGS Functions:: Low-level KDC functions; AS and TGS.
999 * Authenticator Functions:: Low-level authenticator functions.
1000 * Cryptographic Functions:: Low-level cryptographic functions.
1001 * Utility Functions:: Utilities for use in the global context.
1002 * Error Handling:: Error codes and such.
1003 * Examples:: Example code.
1004 * Generic Security Service:: If you want to use the GSS API instead.
1005 @end menu
1007 @node Preparation
1008 @section Preparation
1010 To use `Libshishi', you have to perform some changes to your sources
1011 and the build system. The necessary changes are small and explained
1012 in the following sections. At the end of this chapter, it is
1013 described how the library is initialized, and how the requirements of
1014 the library are verified.
1016 A faster way to find out how to adapt your application for use with
1017 `Libshishi' may be to look at the examples at the end of this manual
1018 (@pxref{Examples}).
1020 @menu
1021 * Header::
1022 * Initialization::
1023 * Version Check::
1024 * Building the source::
1025 @end menu
1027 @node Header
1028 @subsection Header
1030 All interfaces (data types and functions) of the library are defined
1031 in the header file `shishi.h'. You must include this in all programs
1032 using the library, either directly or through some other header file,
1033 like this:
1035 @example
1036 #include <shishi.h>
1037 @end example
1039 The name space of `Libshishi' is @code{shishi_*} for function names,
1040 @code{Shishi*} for data types and @code{SHISHI_*} for other symbols. In
1041 addition the same name prefixes with one prepended underscore are
1042 reserved for internal use and should never be used by an application.
1044 @node Initialization
1045 @subsection Initialization
1047 `Libshishi' must be initialized before it can be used. The library is
1048 initialized by calling @code{shishi_init()} (@pxref{Initialization
1049 Functions}). The resources allocated by the initialization process
1050 can be released if the application no longer has a need to call
1051 `Libshishi' functions, this is done by calling @code{shishi_done()}.
1053 In order to take advantage of the internationalisation features in
1054 `Libshishi', such as translated error messages, the application must
1055 set the current locale using @code{setlocale()} before initializing
1056 `Libshishi'.
1058 @node Version Check
1059 @subsection Version Check
1061 It is often desirable to check that the version of `Libshishi' used is
1062 indeed one which fits all requirements. Even with binary
1063 compatibility new features may have been introduced but due to problem
1064 with the dynamic linker an old version is actually used. So you may
1065 want to check that the version is okay right after program startup.
1067 @include shishi-api-version.texi
1069 The normal way to use the function is to put something similar to the
1070 following early in your @code{main()}:
1072 @example
1073 if (!shishi_check_version (SHISHI_VERSION))
1074 @{
1075 printf ("shishi_check_version() failed:\n"
1076 "Header file incompatible with shared library.\n");
1077 exit(1);
1078 @}
1079 @end example
1081 @node Building the source
1082 @subsection Building the source
1083 @cindex Compiling your application
1085 If you want to compile a source file including the `shishi.h' header
1086 file, you must make sure that the compiler can find it in the
1087 directory hierarchy. This is accomplished by adding the path to the
1088 directory in which the header file is located to the compilers include
1089 file search path (via the @option{-I} option).
1091 However, the path to the include file is determined at the time the
1092 source is configured. To solve this problem, `Libshishi' uses the
1093 external package @command{pkg-config} that knows the path to the
1094 include file and other configuration options. The options that need
1095 to be added to the compiler invocation at compile time are output by
1096 the @option{--cflags} option to @command{pkg-config shishi}. The
1097 following example shows how it can be used at the command line:
1099 @example
1100 gcc -c foo.c `pkg-config shishi --cflags`
1101 @end example
1103 Adding the output of @samp{pkg-config shishi --cflags} to the
1104 compilers command line will ensure that the compiler can find the
1105 `Libshishi' header file.
1107 A similar problem occurs when linking the program with the library.
1108 Again, the compiler has to find the library files. For this to work,
1109 the path to the library files has to be added to the library search path
1110 (via the @option{-L} option). For this, the option @option{--libs} to
1111 @command{pkg-config shishi} can be used. For convenience, this option
1112 also outputs all other options that are required to link the program
1113 with the `Libshishi' libararies (in particular, the @samp{-lshishi}
1114 option). The example shows how to link @file{foo.o} with the `Libshishi'
1115 library to a program @command{foo}.
1117 @example
1118 gcc -o foo foo.o `pkg-config shishi --libs`
1119 @end example
1121 Of course you can also combine both examples to a single command by
1122 specifying both options to @command{pkg-config}:
1124 @example
1125 gcc -o foo foo.c `pkg-config shishi --cflags --libs`
1126 @end example
1128 @node Initialization Functions
1129 @section Initialization Functions
1131 @include shishi-api-init.texi
1134 @node Ticket Set Functions
1135 @section Ticket Set Functions
1137 A ``ticket set'' is, as the name implies, a collection of tickets.
1138 Functions are provided to read tickets from file into a ticket set, to
1139 query number of tickets in the set, to extract a given ticket from the
1140 set, to search the ticket set for tickets matching certain criterium,
1141 to write the ticket set to a file, etc. High level functions for
1142 performing a initial authentication (@pxref{AS Functions}) or
1143 subsequent authentication (@pxref{TGS Functions}) and storing the new
1144 ticket in the ticket set are also provided.
1146 To manipulate each individual ticket, @xref{Ticket Functions}. For
1147 low-level ASN.1 manipulation see @xref{Ticket (ASN.1) Functions}.
1149 @include shishi-api-tkts.texi
1152 @node AP-REQ and AP-REP Functions
1153 @section AP-REQ and AP-REP Functions
1155 The ``AP-REQ'' and ``AP-REP'' are ASN.1 structures used by application
1156 client and servers to prove to each other who they are. The
1157 structures contain auxilliary information, together with an
1158 authenticator (@pxref{Authenticator Functions}) which is the real
1159 cryptographic proof. The following illustrates the AP-REQ and AP-REP
1160 ASN.1 structures.
1162 @verbatim
1163 AP-REQ ::= [APPLICATION 14] SEQUENCE {
1164 pvno [0] INTEGER (5),
1165 msg-type [1] INTEGER (14),
1166 ap-options [2] APOptions,
1167 ticket [3] Ticket,
1168 authenticator [4] EncryptedData {Authenticator,
1169 { keyuse-pa-TGSReq-authenticator
1170 | keyuse-APReq-authenticator }}
1171 }
1173 AP-REP ::= [APPLICATION 15] SEQUENCE {
1174 pvno [0] INTEGER (5),
1175 msg-type [1] INTEGER (15),
1176 enc-part [2] EncryptedData {EncAPRepPart,
1177 { keyuse-EncAPRepPart }}
1178 }
1180 EncAPRepPart ::= [APPLICATION 27] SEQUENCE {
1181 ctime [0] KerberosTime,
1182 cusec [1] Microseconds,
1183 subkey [2] EncryptionKey OPTIONAL,
1184 seq-number [3] UInt32 OPTIONAL
1185 }
1186 @end verbatim
1188 @include shishi-api-ap.texi
1191 @node SAFE and PRIV Functions
1192 @section SAFE and PRIV Functions
1194 The ``KRB-SAFE'' is an ASN.1 structure used by application client and
1195 servers to exchange integrity protected data. The integrity
1196 protection is keyed, usually with a key agreed on via the AP exchange
1197 (@pxref{AP-REQ and AP-REP Functions}). The following illustrates the
1198 KRB-SAFE ASN.1 structure.
1200 @verbatim
1201 KRB-SAFE ::= [APPLICATION 20] SEQUENCE {
1202 pvno [0] INTEGER (5),
1203 msg-type [1] INTEGER (20),
1204 safe-body [2] KRB-SAFE-BODY,
1205 cksum [3] Checksum
1206 }
1208 KRB-SAFE-BODY ::= SEQUENCE {
1209 user-data [0] OCTET STRING,
1210 timestamp [1] KerberosTime OPTIONAL,
1211 usec [2] Microseconds OPTIONAL,
1212 seq-number [3] UInt32 OPTIONAL,
1213 s-address [4] HostAddress,
1214 r-address [5] HostAddress OPTIONAL
1215 }
1216 @end verbatim
1218 @include shishi-api-safe.texi
1220 The ``KRB-PRIV'' is an ASN.1 structure used by application client and
1221 servers to exchange confidential data. The confidentiality is keyed,
1222 usually with a key agreed on via the AP exchange (@pxref{AP-REQ and
1223 AP-REP Functions}). The following illustrates the KRB-PRIV ASN.1
1224 structure.
1226 @verbatim
1227 KRB-PRIV ::= [APPLICATION 21] SEQUENCE {
1228 pvno [0] INTEGER (5),
1229 msg-type [1] INTEGER (21),
1230 -- NOTE: there is no [2] tag
1231 enc-part [3] EncryptedData -- EncKrbPrivPart
1232 }
1234 EncKrbPrivPart ::= [APPLICATION 28] SEQUENCE {
1235 user-data [0] OCTET STRING,
1236 timestamp [1] KerberosTime OPTIONAL,
1237 usec [2] Microseconds OPTIONAL,
1238 seq-number [3] UInt32 OPTIONAL,
1239 s-address [4] HostAddress -- sender's addr --,
1240 r-address [5] HostAddress OPTIONAL -- recip's addr
1241 }
1242 @end verbatim
1244 @c @include shishi-api-safe.texi
1247 @node Ticket Functions
1248 @section Ticket Functions
1250 @include shishi-api-tkt.texi
1253 @node AS Functions
1254 @section AS Functions
1256 The Authentication Service (AS) is used to get an initial ticket using
1257 e.g. your password. The following illustrates the AS-REQ and AS-REP
1258 ASN.1 structures.
1260 @verbatim
1261 -- Request --
1263 AS-REQ ::= KDC-REQ {10}
1265 KDC-REQ {INTEGER:tagnum} ::= [APPLICATION tagnum] SEQUENCE {
1266 pvno [1] INTEGER (5) -- first tag is [1], not [0] --,
1267 msg-type [2] INTEGER (tagnum),
1268 padata [3] SEQUENCE OF PA-DATA OPTIONAL,
1269 req-body [4] KDC-REQ-BODY
1270 }
1272 KDC-REQ-BODY ::= SEQUENCE {
1273 kdc-options [0] KDCOptions,
1274 cname [1] PrincipalName OPTIONAL
1275 -- Used only in AS-REQ --,
1276 realm [2] Realm
1277 -- Server's realm
1278 -- Also client's in AS-REQ --,
1279 sname [3] PrincipalName OPTIONAL,
1280 from [4] KerberosTime OPTIONAL,
1281 till [5] KerberosTime,
1282 rtime [6] KerberosTime OPTIONAL,
1283 nonce [7] UInt32,
1284 etype [8] SEQUENCE OF Int32 -- EncryptionType
1285 -- in preference order --,
1286 addresses [9] HostAddresses OPTIONAL,
1287 enc-authorization-data [10] EncryptedData {
1288 AuthorizationData,
1289 { keyuse-TGSReqAuthData-sesskey
1290 | keyuse-TGSReqAuthData-subkey }
1291 } OPTIONAL,
1292 additional-tickets [11] SEQUENCE OF Ticket OPTIONAL
1293 }
1295 -- Reply --
1297 AS-REP ::= KDC-REP {11, EncASRepPart, {keyuse-EncASRepPart}}
1299 KDC-REP {INTEGER:tagnum,
1300 TypeToEncrypt,
1301 UInt32:KeyUsages} ::= [APPLICATION tagnum] SEQUENCE {
1302 pvno [0] INTEGER (5),
1303 msg-type [1] INTEGER (tagnum),
1304 padata [2] SEQUENCE OF PA-DATA OPTIONAL,
1305 crealm [3] Realm,
1306 cname [4] PrincipalName,
1307 ticket [5] Ticket,
1308 enc-part [6] EncryptedData {TypeToEncrypt, KeyUsages}
1309 }
1311 EncASRepPart ::= [APPLICATION 25] EncKDCRepPart
1313 EncKDCRepPart ::= SEQUENCE {
1314 key [0] EncryptionKey,
1315 last-req [1] LastReq,
1316 nonce [2] UInt32,
1317 key-expiration [3] KerberosTime OPTIONAL,
1318 flags [4] TicketFlags,
1319 authtime [5] KerberosTime,
1320 starttime [6] KerberosTime OPTIONAL,
1321 endtime [7] KerberosTime,
1322 renew-till [8] KerberosTime OPTIONAL,
1323 srealm [9] Realm,
1324 sname [10] PrincipalName,
1325 caddr [11] HostAddresses OPTIONAL
1326 }
1327 @end verbatim
1329 @include shishi-api-as.texi
1332 @node TGS Functions
1333 @section TGS Functions
1335 The Ticket Granting Service (TGS) is used to get subsequent tickets,
1336 authenticated by other tickets (so called ticket granting tickets).
1337 The following illustrates the TGS-REQ and TGS-REP ASN.1 structures.
1339 @verbatim
1340 -- Request --
1342 TGS-REQ ::= KDC-REQ {12}
1344 KDC-REQ {INTEGER:tagnum} ::= [APPLICATION tagnum] SEQUENCE {
1345 pvno [1] INTEGER (5) -- first tag is [1], not [0] --,
1346 msg-type [2] INTEGER (tagnum),
1347 padata [3] SEQUENCE OF PA-DATA OPTIONAL,
1348 req-body [4] KDC-REQ-BODY
1349 }
1351 KDC-REQ-BODY ::= SEQUENCE {
1352 kdc-options [0] KDCOptions,
1353 cname [1] PrincipalName OPTIONAL
1354 -- Used only in AS-REQ --,
1355 realm [2] Realm
1356 -- Server's realm
1357 -- Also client's in AS-REQ --,
1358 sname [3] PrincipalName OPTIONAL,
1359 from [4] KerberosTime OPTIONAL,
1360 till [5] KerberosTime,
1361 rtime [6] KerberosTime OPTIONAL,
1362 nonce [7] UInt32,
1363 etype [8] SEQUENCE OF Int32 -- EncryptionType
1364 -- in preference order --,
1365 addresses [9] HostAddresses OPTIONAL,
1366 enc-authorization-data [10] EncryptedData {
1367 AuthorizationData,
1368 { keyuse-TGSReqAuthData-sesskey
1369 | keyuse-TGSReqAuthData-subkey }
1370 } OPTIONAL,
1371 additional-tickets [11] SEQUENCE OF Ticket OPTIONAL
1372 }
1374 -- Reply --
1376 TGS-REP ::= KDC-REP {13, EncTGSRepPart,
1377 { keyuse-EncTGSRepPart-sesskey
1378 | keyuse-EncTGSRepPart-subkey }}
1380 KDC-REP {INTEGER:tagnum,
1381 TypeToEncrypt,
1382 UInt32:KeyUsages} ::= [APPLICATION tagnum] SEQUENCE {
1383 pvno [0] INTEGER (5),
1384 msg-type [1] INTEGER (tagnum),
1385 padata [2] SEQUENCE OF PA-DATA OPTIONAL,
1386 crealm [3] Realm,
1387 cname [4] PrincipalName,
1388 ticket [5] Ticket,
1389 enc-part [6] EncryptedData {TypeToEncrypt, KeyUsages}
1390 }
1392 EncTGSRepPart ::= [APPLICATION 26] EncKDCRepPart
1394 EncKDCRepPart ::= SEQUENCE {
1395 key [0] EncryptionKey,
1396 last-req [1] LastReq,
1397 nonce [2] UInt32,
1398 key-expiration [3] KerberosTime OPTIONAL,
1399 flags [4] TicketFlags,
1400 authtime [5] KerberosTime,
1401 starttime [6] KerberosTime OPTIONAL,
1402 endtime [7] KerberosTime,
1403 renew-till [8] KerberosTime OPTIONAL,
1404 srealm [9] Realm,
1405 sname [10] PrincipalName,
1406 caddr [11] HostAddresses OPTIONAL
1407 }
1408 @end verbatim
1410 @include shishi-api-tgs.texi
1413 @node Ticket (ASN.1) Functions
1414 @section Ticket (ASN.1) Functions
1416 @include shishi-api-ticket.texi
1418 @node AS/TGS Functions
1419 @section AS/TGS Functions
1421 The Authentication Service (AS) is used to get an initial ticket using
1422 e.g. your password. The Ticket Granting Service (TGS) is used to get
1423 subsequent tickets using other tickets. Protocol wise the procedures
1424 are very similar, which is the reason they are described together.
1425 The following illustrates the AS-REQ, TGS-REQ and AS-REP, TGS-REP
1426 ASN.1 structures. Most of the functions use the mnemonic ``KDC''
1427 instead of either AS or TGS, which means the function operates on both
1428 AS and TGS types. Only where the distinction between AS and TGS is
1429 important are the AS and TGS names used. Remember, these are
1430 low-level functions, and normal applications will likely be satisfied
1431 with the AS (@pxref{AS Functions}) and TGS (@pxref{TGS Functions})
1432 interfaces, or the even more high-level Ticket Set (@pxref{Ticket Set
1433 Functions}) interface.
1435 @verbatim
1436 -- Request --
1438 AS-REQ ::= KDC-REQ {10}
1439 TGS-REQ ::= KDC-REQ {12}
1441 KDC-REQ {INTEGER:tagnum} ::= [APPLICATION tagnum] SEQUENCE {
1442 pvno [1] INTEGER (5) -- first tag is [1], not [0] --,
1443 msg-type [2] INTEGER (tagnum),
1444 padata [3] SEQUENCE OF PA-DATA OPTIONAL,
1445 req-body [4] KDC-REQ-BODY
1446 }
1448 KDC-REQ-BODY ::= SEQUENCE {
1449 kdc-options [0] KDCOptions,
1450 cname [1] PrincipalName OPTIONAL
1451 -- Used only in AS-REQ --,
1452 realm [2] Realm
1453 -- Server's realm
1454 -- Also client's in AS-REQ --,
1455 sname [3] PrincipalName OPTIONAL,
1456 from [4] KerberosTime OPTIONAL,
1457 till [5] KerberosTime,
1458 rtime [6] KerberosTime OPTIONAL,
1459 nonce [7] UInt32,
1460 etype [8] SEQUENCE OF Int32 -- EncryptionType
1461 -- in preference order --,
1462 addresses [9] HostAddresses OPTIONAL,
1463 enc-authorization-data [10] EncryptedData {
1464 AuthorizationData,
1465 { keyuse-TGSReqAuthData-sesskey
1466 | keyuse-TGSReqAuthData-subkey }
1467 } OPTIONAL,
1468 additional-tickets [11] SEQUENCE OF Ticket OPTIONAL
1469 }
1471 -- Reply --
1473 AS-REP ::= KDC-REP {11, EncASRepPart, {keyuse-EncASRepPart}}
1474 TGS-REP ::= KDC-REP {13, EncTGSRepPart,
1475 { keyuse-EncTGSRepPart-sesskey
1476 | keyuse-EncTGSRepPart-subkey }}
1478 KDC-REP {INTEGER:tagnum,
1479 TypeToEncrypt,
1480 UInt32:KeyUsages} ::= [APPLICATION tagnum] SEQUENCE {
1481 pvno [0] INTEGER (5),
1482 msg-type [1] INTEGER (tagnum),
1483 padata [2] SEQUENCE OF PA-DATA OPTIONAL,
1484 crealm [3] Realm,
1485 cname [4] PrincipalName,
1486 ticket [5] Ticket,
1487 enc-part [6] EncryptedData {TypeToEncrypt, KeyUsages}
1488 }
1490 EncASRepPart ::= [APPLICATION 25] EncKDCRepPart
1491 EncTGSRepPart ::= [APPLICATION 26] EncKDCRepPart
1493 EncKDCRepPart ::= SEQUENCE {
1494 key [0] EncryptionKey,
1495 last-req [1] LastReq,
1496 nonce [2] UInt32,
1497 key-expiration [3] KerberosTime OPTIONAL,
1498 flags [4] TicketFlags,
1499 authtime [5] KerberosTime,
1500 starttime [6] KerberosTime OPTIONAL,
1501 endtime [7] KerberosTime,
1502 renew-till [8] KerberosTime OPTIONAL,
1503 srealm [9] Realm,
1504 sname [10] PrincipalName,
1505 caddr [11] HostAddresses OPTIONAL
1506 }
1507 @end verbatim
1509 @include shishi-api-kdc.texi
1512 @node Authenticator Functions
1513 @section Authenticator Functions
1515 An ``Authenticator'' is a ASN.1 structure that work as a proof that an
1516 entity owns a ticket. It is usually embedded in the AP-REQ structure
1517 (@pxref{AP-REQ and AP-REP Functions}), and you most likely want to use
1518 an AP-REQ instead of a Authenticator in normal applications. The
1519 following illustrates the Authenticator ASN.1 structure.
1521 @verbatim
1522 Authenticator ::= [APPLICATION 2] SEQUENCE {
1523 authenticator-vno [0] INTEGER (5),
1524 crealm [1] Realm,
1525 cname [2] PrincipalName,
1526 cksum [3] Checksum OPTIONAL,
1527 cusec [4] Microseconds,
1528 ctime [5] KerberosTime,
1529 subkey [6] EncryptionKey OPTIONAL,
1530 seq-number [7] UInt32 OPTIONAL,
1531 authorization-data [8] AuthorizationData OPTIONAL
1532 }
1533 @end verbatim
1535 @include shishi-api-authenticator.texi
1538 @node Cryptographic Functions
1539 @section Cryptographic Functions
1541 Underneath the high-level functions described earlier, cryptographic
1542 operations are happening. If you need to access these cryptographic
1543 primitives directly, this section describes the functions available.
1545 Most cryptographic operations need keying material, and cryptographic
1546 keys have been isolated into it's own data structure
1547 @code{Shishi_key}. The following illustrates it's contents, but note
1548 that you cannot access it's elements directly but must use the
1549 accessor functions described below.
1551 @verbatim
1552 struct Shishi_key
1553 {
1554 int type; /* RFC 1510 encryption integer type */
1555 char *value; /* Cryptographic key data */
1556 int version; /* RFC 1510 ``kvno'' */
1557 };
1558 @end verbatim
1560 All functions that operate on this data structure are described now.
1562 @include shishi-api-key.texi
1564 Many servers run uninteractively but still need keying material, and
1565 when they do they are normally read from a file stored on the local
1566 host. The file should be protected from unauthorized access. The
1567 file is in ASCII format and contains keys as outputed by
1568 @code{shishi_key_print()}. All functions that handle these hostkeys
1569 file are described now.
1571 @include shishi-api-hostkeys.texi
1573 After creating the key structure, it can be used to encrypt and
1574 decrypt data, calculate checksum on data etc. All available functions
1575 are described now.
1577 @include shishi-api-crypto.texi
1580 @node Utility Functions
1581 @section Utility Functions
1583 @include shishi-api-utility.texi
1586 @node Error Handling
1587 @section Error Handling
1588 @cindex Error Handling
1590 Most functions in `Libshishi' are returning an error if they fail.
1591 For this reason, the application should always catch the error
1592 condition and take appropriate measures, for example by releasing the
1593 resources and passing the error up to the caller, or by displaying a
1594 descriptive message to the user and cancelling the operation.
1596 Some error values do not indicate a system error or an error in the
1597 operation, but the result of an operation that failed properly.
1599 @menu
1600 * Error values:: A list of all error values used.
1601 * Error strings:: How to get a descriptive string from a value.
1602 @end menu
1604 @node Error values
1605 @subsection Error values
1607 Errors are returned as an @code{int}. Except for the SHISHI_OK case,
1608 an application should always use the constants instead of their
1609 numeric value. Applications are encouraged to use the constants even
1610 for SHISHI_OK as it improves readability. Possible values are:
1612 @table @code
1613 @item SHISHI_OK
1614 This value indicates success. The value of this error is guaranteed
1615 to always be @code{0} so you may use it in boolean constructs.
1617 @include shishi-api-error-labels.texi
1619 @end table
1621 @node Error strings
1622 @subsection Error strings
1624 @include shishi-api-error.texi
1626 @node Examples
1627 @section Examples
1628 @cindex Examples
1630 This chapter does not contain example code which illustrate how
1631 `Shishi' can be used when writing your own application.
1633 @node Generic Security Service
1634 @section Generic Security Service
1635 @cindex Generic Security Service (GSS)
1637 As an alternative to the native Shishi programming API, it is possible
1638 to program Shishi through the Generic Security Services (GSS) API.
1639 The advantage of using GSS-API in your security application, instead
1640 of the native Shishi API, is that it will be easier to port your
1641 application between different Kerberos 5 implementations, and even
1642 beyond Kerberos 5 to different security systems, that support GSS-API.
1643 In the free software world, however, the only widely used security
1644 system that supports GSS-API is Kerberos 5, so the last advantage is
1645 somewhat academic. But if you are porting applications using GSS-API
1646 for other Kerberos 5 implementations, or want a more mature and stable
1647 API than the native Shishi API, you may find using Shishi's GSS-API
1648 interface compelling. Note that GSS-API only offer basic services,
1649 for more advanced uses you must use the native API.
1651 Since the GSS is not specific to Shishi, it is distributed
1652 independently from Shishi. Further information on the GSS project can
1653 be found at @url{http://josefsson.org/gss/}.
1655 @c **********************************************************
1656 @c ******************* Acknowledgements *******************
1657 @c **********************************************************
1658 @node Acknowledgements
1659 @chapter Acknowledgements
1661 Shishi uses Libgcrypt and Libgpg-error by Werner Koch et al, Libtasn1
1662 by Fabio Fiorina et al.
1664 @c **********************************************************
1665 @c ******************* Appendices *************************
1666 @c **********************************************************
1668 @node Copying This Manual
1669 @appendix Copying This Manual
1671 @menu
1672 * GNU Free Documentation License:: License for copying this manual.
1673 @end menu
1675 @include fdl.texi
1677 @include gpl.texi
1679 @node Concept Index
1680 @unnumbered Concept Index
1682 @printindex cp
1684 @node Function and Data Index
1685 @unnumbered Function and Data Index
1687 @printindex fn
1689 @summarycontents
1690 @contents
1691 @bye