doc/shishi.texi

   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
  16
  17 @c Unify some of the indices.
  18 @syncodeindex tp fn
  19 @syncodeindex pg fn
  20
  21 @copying
  22 This is @cite{The Shishi Manual}, last updated @value{UPDATED}, for
  23 Version @value{VERSION} of Shishi.
  24
  25 Copyright @copyright{} 2002, 2003 Simon Josefsson.
  26
  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.''
  35
  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
  41
  42 @dircategory Net Utilities
  43 @direntry
  44 * shishi: (shishi).             A Kerberos 5 implementation
  45 @end direntry
  46
  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
  55
  56 @contents
  57
  58 @ifnottex
  59 @node Top
  60 @top Shishi
  61 @insertcopying
  62 @end ifnottex
  63
  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 * Reference Manual::            Detailed description of config files, etc.
  69 * Programming Manual::          Calling Shishi from a programming language.
  70 * Acknowledgements::            Whom to blame.
  71
  72 Appendices
  73
  74 * Copying This Manual::         How you can copy and share this manual.
  75 * Copying::                     How you can copy and share the source.
  76
  77 Indices
  78
  79 * Concept Index::               Index of concepts and programs.
  80 * Function and Data Index::     Index of functions, variables and data types.
  81 @end menu
  82
  83
  84 @c **********************************************************
  85 @c ********************  Introduction  **********************
  86 @c **********************************************************
  87 @node Introduction
  88 @chapter Introduction
  89
  90 Shishi implements the Kerberos 5 network security system.
  91
  92 @menu
  93 * Getting Started::
  94 * Features and Status::
  95 * Overview::
  96 * Cryptographic Overview::
  97 * Supported Platforms::
  98 * Downloading and Installing::
  99 * Bug Reports::
 100 * Contributing::
 101 @end menu
 102
 103 @node Getting Started
 104 @section Getting Started
 105
 106 This manual documents the Shishi application and library programming
 107 interface.  All commands, functions and data types provided by Shishi
 108 are explained.
 109
 110 The reader is assumed to possess basic familiarity with network
 111 security and the Kerberos 5 security system.
 112
 113 This manual can be used in several ways.  If read from the beginning
 114 to the end, it gives a good introduction into the library and how it
 115 can be used in an application.  Forward references are included where
 116 necessary.  Later on, the manual can be used as a reference manual to
 117 get just the information needed about any particular interface of the
 118 library.  Experienced programmers might want to start looking at the
 119 examples at the end of the manual, and then only read up those parts
 120 of the interface which are unclear.
 121
 122 @node Features and Status
 123 @section Features and Status
 124
 125 Shishi might have a couple of advantages over other packages doing a
 126 similar job.
 127
 128 @table @asis
 129 @item It's Free Software
 130 Anybody can use, modify, and redistribute it under the terms of the GNU
 131 General Public License (@pxref{Copying}).
 132
 133 @item It's thread-safe
 134 The library uses no global variables.
 135
 136 @item It's internationalized
 137 It handles non-ASCII username and passwords and user visible strings
 138 used in the library (error messages) can be translated into the users'
 139 language.
 140
 141 @item It's portable
 142 It should work on all Unix like operating systems, including Windows.
 143
 144 @end table
 145
 146 Shishi is far from feature complete, it is not even a full RFC 1510
 147 implementation yet.  However, some basic functionality is implemented.
 148 A few implemented feature are mentioned below.
 149
 150 @itemize @bullet
 151
 152 @item Initial authentication (AS) from raw key or password.
 153 This step is typically used to acquire a ticket granting ticket and,
 154 less commonly, a server ticket.
 155
 156 @item Subsequent authentication (TGS).
 157 This step is typically used to acquire a server ticket, by
 158 authenticating yourself using the ticket granting ticket.
 159
 160 @item Client-Server authentication (AP).
 161 This step is used by clients and servers to prove to each other who
 162 they are, using negotiated tickets.
 163
 164 @item Integrity protected communication (SAFE).
 165 This step is used by clients and servers to exchange integrity
 166 protected data with each other.  The key is typically agreed on using
 167 the Client-Server authentication step.
 168
 169 @item Ticket cache, supporting multiple principals and realms.
 170 As tickets have a life time of typically several hours, they are
 171 managed in disk files.  There can be multiple ticket caches, and each
 172 ticket cache can store tickets for multiple clients (users), servers,
 173 encryption types, etc.  Functionality is provided for locating the
 174 proper ticket for every use.
 175
 176 @item Most standard cryptographic primitives.
 177 The believed most secure algorithms are supported
 178 (@pxref{Cryptographic Overview}).
 179
 180 @item Telnet client and server.
 181 This is used to remotely login to other machines, after authenticating
 182 yourself with a ticket.
 183
 184 @item PAM module.
 185 This is used to login locally on a machine.
 186
 187 @item KDC addresses located using DNS SRV RRs.
 188
 189 @item Modularized low-level crypto interface.
 190 Currently Nettle and Libgcrypt are supported.  If you wish to add
 191 support for another low-level cryptographic library, you only have to
 192 implement a few APIs to DES, AES, MD5, SHA1, HMAC, etc, look at
 193 @file{lib/nettle.c} or @file{lib/libgcrypt.c} as a starting pointer.
 194
 195 @end itemize
 196
 197 The following table summarize what the current objectives are (i.e.,
 198 the todo list) and an estimate on how long it will take to implement
 199 the feature.  If you like to start working on anything, please let me
 200 know so work duplication can be avoided.
 201
 202 @itemize @bullet
 203
 204 @item Pre-authentication support (week).
 205
 206 @item Cross-realm support (week).
 207
 208 @item PKINIT (use libksba, weeks)
 209
 210 @item Finish GSSAPI support via GSSLib (weeks)
 211 Shishi will not support GSSLib natively, but a separate project
 212 ``GSSLib'' is under way to produce a generic GSS implementation, and
 213 it will use Shishi to implement the Kerberos 5 mechanism.
 214
 215 @item Port to cyclone (cyclone need to mature first)
 216
 217 @item Modularize ASN.1 library so it can be replaced (days).
 218 Almost done, all ASN.1 functionality is found in lib/asn1.c, although
 219 the interface is rather libtasn1 centric.
 220
 221 @item KDC (initiated, weeks)
 222
 223 @item Set/Change password protocol (weeks?)
 224
 225 @item Port applications to use Shishi (indefinite)
 226
 227 @item Improve documentation
 228
 229 @item Improve internationalization
 230
 231 @item Add AP-REQ replay cache (week).
 232
 233 @item Study benefits by introducing a PA-TGS-REP.
 234 This would provide mutual authentication of the KDC in a way that is
 235 easier to analyze.  Currently the mutual authentication property is
 236 only implicit from successful decryption of the KDC-REP and the 4 byte
 237 nonce.
 238
 239 @end itemize
 240
 241 @node Overview
 242 @section Overview
 243
 244 This section describes RFC 1510 from a protocol point of
 245 view@footnote{The text is a lightly adapted version of the
 246 introduction section from RFC 1510 by J. Kohl and C. Neuman, September
 247 1993, unclear copyrights, but presumably owned by The Internet
 248 Society.}.
 249
 250 Kerberos provides a means of verifying the identities of principals,
 251 (e.g., a workstation user or a network server) on an open
 252 (unprotected) network.  This is accomplished without relying on
 253 authentication by the host operating system, without basing trust on
 254 host addresses, without requiring physical security of all the hosts
 255 on the network, and under the assumption that packets traveling along
 256 the network can be read, modified, and inserted at will. (Note,
 257 however, that many applications use Kerberos' functions only upon the
 258 initiation of a stream-based network connection, and assume the
 259 absence of any "hijackers" who might subvert such a connection.  Such
 260 use implicitly trusts the host addresses involved.)  Kerberos performs
 261 authentication under these conditions as a trusted third- party
 262 authentication service by using conventional cryptography, i.e.,
 263 shared secret key.  (shared secret key - Secret and private are often
 264 used interchangeably in the literature.  In our usage, it takes two
 265 (or more) to share a secret, thus a shared DES key is a secret key.
 266 Something is only private when no one but its owner knows it.  Thus,
 267 in public key cryptosystems, one has a public and a private key.)
 268
 269 The authentication process proceeds as follows: A client sends a
 270 request to the authentication server (AS) requesting "credentials" for
 271 a given server.  The AS responds with these credentials, encrypted in
 272 the client's key.  The credentials consist of 1) a "ticket" for the
 273 server and 2) a temporary encryption key (often called a "session
 274 key").  The client transmits the ticket (which contains the client's
 275 identity and a copy of the session key, all encrypted in the server's
 276 key) to the server.  The session key (now shared by the client and
 277 server) is used to authenticate the client, and may optionally be used
 278 to authenticate the server.  It may also be used to encrypt further
 279 communication between the two parties or to exchange a separate
 280 sub-session key to be used to encrypt further communication.
 281
 282 The implementation consists of one or more authentication servers
 283 running on physically secure hosts.  The authentication servers
 284 maintain a database of principals (i.e., users and servers) and their
 285 secret keys. Code libraries provide encryption and implement the
 286 Kerberos protocol.  In order to add authentication to its
 287 transactions, a typical network application adds one or two calls to
 288 the Kerberos library, which results in the transmission of the
 289 necessary messages to achieve authentication.
 290
 291 The Kerberos protocol consists of several sub-protocols (or
 292 exchanges).  There are two methods by which a client can ask a
 293 Kerberos server for credentials.  In the first approach, the client
 294 sends a cleartext request for a ticket for the desired server to the
 295 AS. The reply is sent encrypted in the client's secret key. Usually
 296 this request is for a ticket-granting ticket (TGT) which can later be
 297 used with the ticket-granting server (TGS).  In the second method, the
 298 client sends a request to the TGS.  The client sends the TGT to the
 299 TGS in the same manner as if it were contacting any other application
 300 server which requires Kerberos credentials.  The reply is encrypted in
 301 the session key from the TGT.
 302
 303 Once obtained, credentials may be used to verify the identity of the
 304 principals in a transaction, to ensure the integrity of messages
 305 exchanged between them, or to preserve privacy of the messages.  The
 306 application is free to choose whatever protection may be necessary.
 307
 308 To verify the identities of the principals in a transaction, the
 309 client transmits the ticket to the server.  Since the ticket is sent
 310 "in the clear" (parts of it are encrypted, but this encryption doesn't
 311 thwart replay) and might be intercepted and reused by an attacker,
 312 additional information is sent to prove that the message was
 313 originated by the principal to whom the ticket was issued.  This
 314 information (called the authenticator) is encrypted in the session
 315 key, and includes a timestamp.  The timestamp proves that the message
 316 was recently generated and is not a replay.  Encrypting the
 317 authenticator in the session key proves that it was generated by a
 318 party possessing the session key.  Since no one except the requesting
 319 principal and the server know the session key (it is never sent over
 320 the network in the clear) this guarantees the identity of the client.
 321
 322 The integrity of the messages exchanged between principals can also be
 323 guaranteed using the session key (passed in the ticket and contained
 324 in the credentials).  This approach provides detection of both replay
 325 attacks and message stream modification attacks.  It is accomplished
 326 by generating and transmitting a collision-proof checksum (elsewhere
 327 called a hash or digest function) of the client's message, keyed with
 328 the session key.  Privacy and integrity of the messages exchanged
 329 between principals can be secured by encrypting the data to be passed
 330 using the session key passed in the ticket, and contained in the
 331 credentials.
 332
 333 @node Cryptographic Overview
 334 @section Cryptographic Overview
 335
 336 Shishi implements several of the standard cryptographic primitives.
 337 Here are the names of the supported encryption suites, with some notes
 338 on their status and there associated checksum suite.  They are ordered
 339 by increased security as perceived by the author.
 340
 341 @cindex DES
 342 @cindex 3DES
 343 @cindex AES
 344
 345 @table @code
 346
 347 @item NULL
 348
 349 @code{NULL} is a dummy encryption suite for debugging.  Encryption and
 350 decryption are identity functions.  No integrity protection.  It is
 351 weak.  It is associated with the @code{NULL} checksum.
 352
 353 @item des-cbc-crc
 354
 355 @code{des-cbc-crc} is DES encryption and decryption with 56 bit keys
 356 and 8 byte blocks in CBC mode. The keys can be derived from passwords
 357 by an obscure application specific algorithm. Data is integrity
 358 protected with an unkeyed but encrypted @code{CRC32}-like checksum.
 359 It is weak. It is associated with the @code{rsa-md5-des} checksum.
 360
 361 @item des-cbc-md4
 362
 363 @code{des-cbc-md4} is DES encryption and decryption with 56 bit keys
 364 and 8 byte blocks in CBC mode. The keys can be derived from passwords
 365 by an obscure application specific algorithm. Data is integrity
 366 protected with an unkeyed but encrypted MD4 hash.  It is weak. It is
 367 associated with the @code{rsa-md4-des} checksum.
 368
 369 @item des-cbc-md5
 370
 371 @code{des-cbc-md5} is DES encryption and decryption with 56 bit keys
 372 and 8 byte blocks in CBC mode.  The keys can be derived from passwords
 373 by an obscure application specific algorithm. Data is integrity
 374 protected with an unkeyed but encrypted MD5 hash.  It is weak.  It is
 375 associated with the @code{rsa-md5-des} checksum.  This is the
 376 strongest RFC 1510 interoperable mechanism.
 377
 378 @item des3-cbc-sha1-kd
 379
 380 @code{des3-cbc-sha1-kd} is DES encryption and decryption with three 56
 381 bit keys (effective key size 112 bits) and 8 byte blocks in CBC
 382 mode. The keys can be derived from passwords by a algorithm based on
 383 the paper "A Better Key Schedule For DES-like Ciphers"
 384 @footnote{@url{http://www.research.att.com/~smb/papers/ides.pdf}} by
 385 Uri Blumenthal and Steven M. Bellovin (it is not clear if the
 386 algorithm, and the way it is used, is used by any other protocols,
 387 although it seems unlikely).  Data is integrity protected with a keyed
 388 SHA1 hash in HMAC mode.  It has no security proof, but is assumed to
 389 provide adequate security in the sense that knowledge on how to crack
 390 it is not known to the public.  Note that the key derivation function
 391 is not widely used outside of Kerberos, hence not widely studied.  It
 392 is associated with the @code{hmac-sha1-des3-kd} checksum.
 393
 394 @item aes128-cts-hmac-sha1-96
 395 @item aes256-cts-hmac-sha1-96.
 396
 397 @code{aes128-cts-hmac-sha1-96} and @code{aes256-cts-hmac-sha1-96} is
 398 AES encryption and decryption with 128 bit and 256 bit key,
 399 respectively, and 16 byte blocks in CBC mode with Cipher Text
 400 Stealing.  Cipher Text Stealing means data length of encrypted data is
 401 preserved (pure CBC add up to 7 pad characters).  The keys can be
 402 derived from passwords with RSA Laboratories PKCS#5 Password Based Key
 403 Derivation Function
 404 2@footnote{@url{http://www.rsasecurity.com/rsalabs/pkcs/pkcs-5/}},
 405 which is allegedly provably secure in a random oracle model.  Data is
 406 integrity protected with a keyed SHA1 hash, in HMAC mode, truncated to
 407 96 bits.  There is no security proof, but the schemes are assumed to
 408 provide adequate security in the sense that knowledge on how to crack
 409 them is not known to the public.  Note that AES has yet to receive the
 410 test of time, and the CBC variation used is not widely standardized
 411 (hence not widely studied).  It is associated with the
 412 @code{hmac-sha1-96-aes128} and @code{hmac-sha1-96-aes256} checksums,
 413 respectively.
 414
 415 @end table
 416
 417 The protocol do not include any way to negotiate which checksum
 418 mechanisms to use, so in most cases the associated checksum will be
 419 used.  However, checksum mechanisms can be used with other encryption
 420 mechanisms, as long as they are compatible in terms of key format etc.
 421 Here are the names of the supported checksum mechanisms, with some
 422 notes on their status and the compatible encryption mechanisms. They
 423 are ordered by increased security as perceived by the author.
 424
 425 @table @code
 426
 427 @item NULL
 428
 429 @code{NULL} is a dummy checksum suite for debugging.  It provides no
 430 integrity.  It is weak.  It is compatible with the @code{NULL}
 431 encryption mechanism.
 432
 433 @item rsa-md4
 434
 435 @code{rsa-md4} is a unkeyed MD4 hash computed over the message.  Since
 436 it is unkeyed, it is in general a weak checksum, however applications
 437 can, with care, use it non-weak ways (e.g., by including the hash in
 438 other messages that are encrypted or checksummed).  It is compatible
 439 with all encryption mechanisms.
 440
 441 @item rsa-md4-des
 442
 443 @code{rsa-md4-des} is a DES CBC encryption of one block of random data
 444 and a unkeyed MD4 hash computed over the random data and the message
 445 to integrity protect.  The key used is derived from the base protocol
 446 key by XOR with a constant.  It is weak. It is compatible with the
 447 @code{des-cbc-crc}, @code{des-cbc-md4}, @code{des-cbc-md5} encryption
 448 mechanisms.
 449
 450 @item rsa-md5
 451
 452 @code{rsa-md5} is a unkeyed MD5 hash computed over the message.  Since
 453 it is unkeyed, it is in general a weak checksum, however applications
 454 can, with care, use it non-weak ways (e.g., by including the hash in
 455 other messages that are encrypted or checksummed).  It is compatible
 456 with all encryption mechanisms.
 457
 458 @item rsa-md5-des
 459
 460 @code{rsa-md5-des} is a DES CBC encryption of one block of random data
 461 and a unkeyed MD5 hash computed over the random data and the message
 462 to integrity protect.  The key used is derived from the base protocol
 463 key by XOR with a constant.  It is weak.  It is compatible with the
 464 @code{des-cbc-crc}, @code{des-cbc-md4}, @code{des-cbc-md5} encryption
 465 mechanisms.
 466
 467 @item hmac-sha1-des3-kd
 468
 469 @code{hmac-sha1-des3-kd} is a keyed SHA1 hash in HMAC mode computed
 470 over the message.  The key is derived from the base protocol by the
 471 simplified key derivation function (similar to the password key
 472 derivation functions of @code{des3-cbc-sha1-kd}).  It has no security
 473 proof, but is assumed to provide good security, if the key derivation
 474 function is good.  It is compatible with the @code{des3-cbc-sha1-kd}
 475 encryption mechanism.
 476
 477 @item hmac-sha1-96-aes128
 478 @item hmac-sha1-96-aes256
 479
 480 @code{hmac-sha1-96-aes*} are keyed SHA1 hashes in HMAC mode computed
 481 over the message and then truncated to 96 bits.  The key is derived
 482 from the base protocol by the simplified key derivation function
 483 (similar to the password key derivation functions of
 484 @code{des3-cbc-sha1-kd}).  It has no security proof, but is assumed to
 485 provide good security, if the key derivation function is good.  It is
 486 compatible with the @code{aes*-cts-hmac-sha1-96} encryption
 487 mechanisms.
 488
 489 @end table
 490
 491
 492 @node Supported Platforms
 493 @section Supported Platforms
 494
 495 Shishi has at some point in time been tested on the following
 496 platforms.  Online build reports for each platforms and Shishi version
 497 is available at @url{http://josefsson.org/autobuild/}.
 498
 499 @enumerate
 500
 501 @item Debian GNU/Linux 3.0 (Woody)
 502 @cindex Debian
 503
 504 GCC 2.95.4 and GNU Make. This is the main development platform.
 505 @code{alphaev67-unknown-linux-gnu}, @code{alphaev6-unknown-linux-gnu},
 506 @code{arm-unknown-linux-gnu}, @code{armv4l-unknown-linux-gnu},
 507 @code{hppa-unknown-linux-gnu}, @code{hppa64-unknown-linux-gnu},
 508 @code{i686-pc-linux-gnu}, @code{ia64-unknown-linux-gnu},
 509 @code{m68k-unknown-linux-gnu}, @code{mips-unknown-linux-gnu},
 510 @code{mipsel-unknown-linux-gnu}, @code{powerpc-unknown-linux-gnu},
 511 @code{s390-ibm-linux-gnu}, @code{sparc-unknown-linux-gnu},
 512 @code{sparc64-unknown-linux-gnu}.
 513
 514 @item Debian GNU/Linux 2.1
 515 @cindex Debian
 516
 517 GCC 2.95.4 and GNU Make. @code{armv4l-unknown-linux-gnu}.
 518
 519 @item Tru64 UNIX
 520 @cindex Tru64
 521
 522 Tru64 UNIX C compiler and Tru64 Make. @code{alphaev67-dec-osf5.1},
 523 @code{alphaev68-dec-osf5.1}.
 524
 525 @item SuSE Linux 7.1
 526 @cindex SuSE
 527
 528 GCC 2.96 and GNU Make. @code{alphaev6-unknown-linux-gnu},
 529 @code{alphaev67-unknown-linux-gnu}.
 530
 531 @item SuSE Linux 7.2a
 532 @cindex SuSE Linux
 533
 534 GCC 3.0 and GNU Make. @code{ia64-unknown-linux-gnu}.
 535
 536 @item SuSE Linux
 537 @cindex SuSE Linux
 538
 539 GCC 3.2.2 and GNU Make.  @code{x86_64-unknown-linux-gnu} (AMD64
 540 Opteron ``Melody'').
 541
 542 @item RedHat Linux 7.2
 543 @cindex RedHat
 544
 545 GCC 2.96 and GNU Make. @code{alphaev6-unknown-linux-gnu},
 546 @code{alphaev67-unknown-linux-gnu}, @code{ia64-unknown-linux-gnu}.
 547
 548 @item RedHat Linux 8.0
 549 @cindex RedHat
 550
 551 GCC 3.2 and GNU Make. @code{i686-pc-linux-gnu}.
 552
 553 @item RedHat Advanced Server 2.1
 554 @cindex RedHat Advanced Server
 555
 556 GCC 2.96 and GNU Make. @code{i686-pc-linux-gnu}.
 557
 558 @item Slackware Linux 8.0.01
 559 @cindex RedHat
 560
 561 GCC 2.95.3 and GNU Make. @code{i686-pc-linux-gnu}.
 562
 563 @item Mandrake Linux 9.0
 564 @cindex Mandrake
 565
 566 GCC 3.2 and GNU Make. @code{i686-pc-linux-gnu}.
 567
 568 @item IRIX 6.5
 569 @cindex IRIX
 570
 571 MIPS C compiler, IRIX Make. @code{mips-sgi-irix6.5}.
 572
 573 @item AIX 4.3.2
 574 @cindex AIX
 575
 576 IBM C for AIX compiler, AIX Make.  @code{rs6000-ibm-aix4.3.2.0}.
 577
 578 @c @item Microsoft Windows 2000 (Cygwin)
 579 @c @cindex Windows
 580 @c
 581 @c GCC 3.2, GNU make. @code{i686-pc-cygwin}.
 582
 583 @item HP-UX 11
 584 @cindex HP-UX
 585
 586 HP-UX C compiler and HP Make. @code{ia64-hp-hpux11.22},
 587 @code{hppa2.0w-hp-hpux11.11}.
 588
 589 @item SUN Solaris 2.8
 590 @cindex Solaris
 591
 592 Sun WorkShop Compiler C 6.0 and SUN Make. @code{sparc-sun-solaris2.8}.
 593
 594 @item NetBSD 1.6
 595 @cindex NetBSD
 596
 597 GCC 2.95.3 and GNU Make. @code{alpha-unknown-netbsd1.6},
 598 @code{i386-unknown-netbsdelf1.6}.
 599
 600 @item OpenBSD 3.1 and 3.2
 601 @cindex OpenBSD
 602
 603 GCC 2.95.3 and GNU Make. @code{alpha-unknown-openbsd3.1},
 604 @code{i386-unknown-openbsd3.1}.
 605
 606 @item FreeBSD 4.7 and 4.8
 607 @cindex FreeBSD
 608
 609 GCC 2.95.4 and GNU Make. @code{alpha-unknown-freebsd4.7},
 610 @code{alpha-unknown-freebsd4.8}, @code{i386-unknown-freebsd4.7},
 611 @code{i386-unknown-freebsd4.8}.
 612
 613 @end enumerate
 614
 615 If you use Shishi on, or port Shishi to, a new platform please report
 616 it to the author (@pxref{Bug Reports}).
 617
 618 @node Downloading and Installing
 619 @section Downloading and Installing
 620 @cindex Installation
 621 @cindex Download
 622
 623 The package can be downloaded from several places, including
 624 @url{http://josefsson.org/shishi/releases/}.  The latest version is
 625 stored in a file, e.g., @samp{shishi-0.0.42.tar.gz} where the
 626 @samp{0.0.42} indicate the highest version number.
 627
 628 The package is then extracted, configured and built like many other
 629 packages that use Autoconf.  For detailed information on configuring
 630 and building it, refer to the @file{INSTALL} file that is part of the
 631 distribution archive.
 632
 633 Here is an example terminal session that download, configure, build
 634 and install the package.  You will need a few basic tools, such as
 635 @samp{sh}, @samp{make} and @samp{cc}.
 636
 637 @example
 638 $ wget -q http://josefsson.org/shishi/releases/shishi-0.0.4.tar.gz
 639 $ tar xfz shishi-0.0.4.tar.gz
 640 $ cd shishi-0.0.4/
 641 $ ./configure
 642 ...
 643 $ make
 644 ...
 645 $ make install
 646 ...
 647 @end example
 648
 649 After this you should be prepared to continue with the user,
 650 administration or programming manual, depending on how you want to use
 651 Shishi.
 652
 653 @node Bug Reports
 654 @section Bug Reports
 655 @cindex Reporting Bugs
 656
 657 If you think you have found a bug in Shishi, please investigate it and
 658 report it.
 659
 660 @itemize @bullet
 661
 662 @item Please make sure that the bug is really in Shishi, and
 663 preferably also check that it hasn't already been fixed in the latest
 664 version.
 665
 666 @item You have to send us a test case that makes it possible for us to
 667 reproduce the bug.
 668
 669 @item You also have to explain what is wrong; if you get a crash, or
 670 if the results printed are not good and in that case, in what way.
 671 Make sure that the bug report includes all information you would need
 672 to fix this kind of bug for someone else.
 673
 674 @end itemize
 675
 676 Please make an effort to produce a self-contained report, with
 677 something definite that can be tested or debugged.  Vague queries or
 678 piecemeal messages are difficult to act on and don't help the
 679 development effort.
 680
 681 If your bug report is good, we will do our best to help you to get a
 682 corrected version of the software; if the bug report is poor, we won't
 683 do anything about it (apart from asking you to send better bug
 684 reports).
 685
 686 If you think something in this manual is unclear, or downright
 687 incorrect, or if the language needs to be improved, please also send a
 688 note.
 689
 690 Send your bug report to:
 691
 692 @center @samp{bug-shishi@@josefsson.org}
 693
 694 @node Contributing
 695 @section Contributing
 696 @cindex Contributing
 697 @cindex Hacking
 698
 699 If you want to submit a patch for inclusion -- from solve a typo you
 700 discovered, up to adding support for a new feature -- you should
 701 submit it as a bug report (@pxref{Bug Reports}).  There are some
 702 things that you can do to increase the chances for it to be included
 703 in the official package.
 704
 705 Unless your patch is very small (say, under 10 lines) we require that
 706 you assign the copyright of your work to the Free Software Foundation.
 707 This is to protect the freedom of the project.  If you have not
 708 already signed papers, we will send you the necessary information when
 709 you submit your contribution.
 710
 711 For contributions that doesn't consist of actual programming code, the
 712 only guidelines are common sense.  Use it.
 713
 714 For code contributions, a number of style guides will help you:
 715
 716 @itemize @bullet
 717
 718 @item Coding Style.
 719 Follow the GNU Standards document (@pxref{top, GNU Coding Standards,,
 720 standards}).
 721
 722 If you normally code using another coding standard, there is no
 723 problem, but you should use @samp{indent} to reformat the code
 724 (@pxref{top, GNU Indent,, indent}) before submitting your work.
 725
 726 @item Use the unified diff format @samp{diff -u}.
 727
 728 @item Return errors.
 729 The only valid reason for ever aborting the execution of the program
 730 is due to memory allocation errors, but for that you should call
 731 @samp{xalloc_die} to allow the application to recover if it wants to.
 732
 733 @item Design with thread safety in mind.
 734 Don't use global variables.  Don't even write to per-handle global
 735 variables unless the documented behaviour of the function you write is
 736 to write to the per-handle global variable.
 737
 738 @item Avoid using the C math library.
 739 It causes problems for embedded implementations, and in most
 740 situations it is very easy to avoid using it.
 741
 742 @item Document your functions.
 743 Use comments before each function headers, that, if properly
 744 formatted, are extracted into Texinfo manuals and GTK-DOC web pages.
 745
 746 @item Supply a ChangeLog and NEWS entries, where appropriate.
 747
 748 @end itemize
 749
 750 @c **********************************************************
 751 @c ********************  User Manual  **********************
 752 @c **********************************************************
 753 @node User Manual
 754 @chapter User Manual
 755 @cindex End-user Shishi usage
 756
 757 Usually Shishi interacts with you to get some initial authentication
 758 information like a password, and then contacts a server to receive a
 759 so called ticket granting ticket.  From now on, you rarely interacts
 760 with Shishi directly.  Applications that needs security services
 761 instruct the Shishi library to use the ticket granting ticket to get
 762 new tickets for various servers.  An example could be if you log on to
 763 a host remotely via @samp{telnet}.  The host usually requires
 764 authentication before permitting you in.  The @samp{telnet} client
 765 uses the ticket granting ticket to get a ticket for the server, and
 766 then use this ticket to authenticate you against the server (typically
 767 the server is also authenticated to you).  You perform the initial
 768 authentication by typing @command{shishi} at the prompt.  Sometimes it
 769 is necessary to supply options telling Shishi what your principal name
 770 (user name in the Kerberos realm) or realm is.  In the example, I
 771 specify the client name @code{simon@@JOSEFSSON.ORG}.
 772
 773 @example
 774 @cartouche
 775 $ shishi simon@@JOSEFSSON.ORG
 776 Enter password for `simon@@JOSEFSSON.ORG':
 777 simon@@JOSEFSSON.ORG:
 778 Authtime:       Fri Aug 15 04:44:49 2003
 779 Endtime:        Fri Aug 15 05:01:29 2003
 780 Server:         krbtgt/JOSEFSSON.ORG key des3-cbc-sha1-kd (16)
 781 Ticket key:     des3-cbc-sha1-kd (16) protected by des3-cbc-sha1-kd (16)
 782 Ticket flags:   INITIAL (512)
 783 $
 784 @end cartouche
 785 @end example
 786
 787 As you can see, Shishi also prints a short description of the ticket
 788 received.
 789
 790 A logical next step is to display all tickets you have received (by
 791 the way, the tickets are usually stored as text in
 792 @file{~/.shishi/tickets}).  This is achieved by typing @command{shishi
 793 --list}.
 794
 795 @example
 796 @cartouche
 797 $ shishi --list
 798 Tickets in `/home/jas/.shishi/tickets':
 799
 800 jas@@JOSEFSSON.ORG:
 801 Authtime:       Fri Aug 15 04:49:46 2003
 802 Endtime:        Fri Aug 15 05:06:26 2003
 803 Server:         krbtgt/JOSEFSSON.ORG key des-cbc-md5 (3)
 804 Ticket key:     des-cbc-md5 (3) protected by des-cbc-md5 (3)
 805 Ticket flags:   INITIAL (512)
 806
 807 jas@@JOSEFSSON.ORG:
 808 Authtime:       Fri Aug 15 04:49:46 2003
 809 Starttime:      Fri Aug 15 04:49:49 2003
 810 Endtime:        Fri Aug 15 05:06:26 2003
 811 Server:         host/latte.josefsson.org key des-cbc-md5 (3)
 812 Ticket key:     des-cbc-md5 (3) protected by des-cbc-md5 (3)
 813
 814 2 tickets found.
 815 $
 816 @end cartouche
 817 @end example
 818
 819 As you can see, I had a ticket for the server
 820 @samp{host/latte.josefsson.org} which was generated by
 821 @samp{telnet}:ing to that host.
 822
 823 If, for some reason, you want to manually get a ticket for a specific
 824 server, you can use the @command{shishi --server-name} command.
 825 Normally, however, the application that uses Shishi will take care of
 826 getting a ticket for the appropriate server, so you normally wouldn't
 827 need this command.
 828
 829 @example
 830 @cartouche
 831 $ shishi --server-name=user/billg --encryption-type=des-cbc-md4
 832 jas@@JOSEFSSON.ORG:
 833 Authtime:       Fri Aug 15 04:49:46 2003
 834 Starttime:      Fri Aug 15 04:54:33 2003
 835 Endtime:        Fri Aug 15 05:06:26 2003
 836 Server:         user/billg key des-cbc-md4 (2)
 837 Ticket key:     des-cbc-md4 (2) protected by des-cbc-md5 (3)
 838 $
 839 @end cartouche
 840 @end example
 841
 842 As you can see, I acquired a ticket for @samp{user/billg} with a
 843 @samp{des-cbc-md4} (@pxref{Cryptographic Overview}) encryption key
 844 specified with the @samp{--encryption-type} parameter.
 845
 846 To wrap up this introduction, lets see how you can remove tickets.
 847 You may want to do this if you leave your terminal for lunch or
 848 similar, and don't want someone to be able to copy the file and then
 849 use your credentials.  Note that this only destroy the tickets
 850 locally, it does not contact any server and tell it that these
 851 credentials are no longer valid.  So if someone stole your ticket
 852 file, you must contact your administrator and have them reset your
 853 account, simply using this parameter is not sufficient.
 854
 855 @example
 856 @cartouche
 857 $ shishi --server-name=imap/latte.josefsson.org --destroy
 858 1 ticket removed.
 859 $ shishi --server-name=foobar --destroy
 860 No tickets removed.
 861 $ shishi --destroy
 862 3 tickets removed.
 863 $
 864 @end cartouche
 865 @end example
 866
 867 Since the @samp{--server-name} parameter takes a long to type, it is
 868 possible to type the server name directly, after the client name.  The
 869 following example demonstrate a AS-REQ followed by a TGS-REQ for a
 870 specific server (assuming you did not have any tickets from the
 871 start).
 872
 873 @example
 874 @cartouche
 875 $ src/shishi simon@@latte.josefsson.org imap/latte.josefsson.org
 876 Enter password for `simon@@latte.josefsson.org':
 877 simon@@latte.josefsson.org:
 878 Acquired:       Wed Aug 27 17:21:06 2003
 879 Expires:        Wed Aug 27 17:37:46 2003
 880 Server:         imap/latte.josefsson.org key aes256-cts-hmac-sha1-96 (18)
 881 Ticket key:     aes256-cts-hmac-sha1-96 (18) protected by aes256-cts-hmac-sha1-96 (18)
 882 Ticket flags:   FORWARDED PROXIABLE (12)
 883 $
 884 @end cartouche
 885 @end example
 886
 887 Refer to the reference manual for all available parameters
 888 (@pxref{Parameters for shishi}).
 889
 890 @c **********************************************************
 891 @c ****************  Administration Manual  *****************
 892 @c **********************************************************
 893 @node Administration Manual
 894 @chapter Administration Manual
 895
 896 This section describe how you get the KDC server up and running to
 897 answer queries from clients.
 898
 899 First you must create a user database.  Currently this is rather
 900 simplistic, and the database only contains cryptographic keys.  Use
 901 the @samp{shishi --string-to-key} command to generate keys, and store
 902 them in the @file{shishid.keys} file.  The file path is
 903 @file{/usr/local/etc/shishid.keys} by default, although you can use
 904 @samp{shishid -k} to specify another location.
 905
 906 Create a random key for the Kerberos Ticket Granting Service for your
 907 realm:
 908
 909 @example
 910 @cartouche
 911 $ shishi --string-to-key --random \
 912 krbtgt/latte.josefsson.org@@latte.josefsson.org | \
 913 tee /usr/local/etc/shishid.keys
 914 -----BEGIN SHISHI KEY-----
 915 Keytype: 18 (aes256-cts-hmac-sha1-96)
 916 Principal: krbtgt/latte.josefsson.org
 917 Realm: latte.josefsson.org
 918
 919 oconxMTf59B5bvTylY+KE4mchA/gtmYI2Qok+48tnSM=
 920 -----END SHISHI KEY-----
 921 $
 922 @end cartouche
 923 @end example
 924
 925 Create a key for a user from a specified password:
 926
 927 @example
 928 @cartouche
 929 $ shishi --string-to-key=fnord \
 930 simon@@latte.josefsson.org | tee --append \
 931 /usr/local/etc/shishid.keys
 932 -----BEGIN SHISHI KEY-----
 933 Keytype: 18 (aes256-cts-hmac-sha1-96)
 934 Principal: simon
 935 Realm: latte.josefsson.org
 936
 937 c1rqwvYwuDFrABvqWVq9bWUsQWg/xbErsIUmLN+3lYM=
 938 -----END SHISHI KEY-----
 939 $
 940 @end cartouche
 941 @end example
 942
 943 There is nothing special with a ticket granting key, you could have
 944 created it based on a password similar to the user key.  However,
 945 please keep in mind that passwords typically have little entropy.
 946
 947 Finally, create a random key for a service:
 948
 949 @example
 950 @cartouche
 951 $ shishi --string-to-key --random \
 952 imap/latte.josefsson.org@@latte.josefsson.org | \
 953 tee --append /usr/local/etc/shishid.keys
 954 -----BEGIN SHISHI KEY-----
 955 Keytype: 18 (aes256-cts-hmac-sha1-96)
 956 Principal: imap/latte.josefsson.org
 957 Realm: latte.josefsson.org
 958
 959 ts2v0QHWyW9FyXbWtCvLPqdEc60qPq5Yvat3p82rp5c=
 960 -----END SHISHI KEY-----
 961 $
 962 @end cartouche
 963 @end example
 964
 965 You are now ready to start the KDC.  Refer to the reference manual for
 966 available parameters (@pxref{Parameters for shishid}).
 967
 968 @example
 969 @cartouche
 970 $ shishid
 971 @end cartouche
 972 @end example
 973
 974 Then you can use @samp{shishi} as usual to acquire tickets
 975 (@pxref{User Manual}).  The following example demonstrate a AS-REQ for
 976 @samp{krbtgt/latte.josefsson.org} followed by a TGS-REQ for
 977 @samp{imap/latte.josefsson.org}.
 978
 979 @example
 980 @cartouche
 981 $ shishi simon@@latte.josefsson.org imap/latte.josefsson.org
 982 Enter password for `simon@@latte.josefsson.org':
 983 simon@@latte.josefsson.org:
 984 Acquired:       Wed Aug 27 17:16:37 2003
 985 Expires:        Wed Aug 27 17:33:17 2003
 986 Server:         imap/latte.josefsson.org key aes256-cts-hmac-sha1-96 (18)
 987 Ticket key:     aes256-cts-hmac-sha1-96 (18) protected by aes256-cts-hmac-sha1-96 (18)
 988 Ticket flags:   FORWARDED PROXIABLE (12)
 989 $
 990 @end cartouche
 991 @end example
 992
 993 @c **********************************************************
 994 @c ****************  Reference Manual  **********************
 995 @c **********************************************************
 996 @node Reference Manual
 997 @chapter Reference Manual
 998
 999 This chapter describes in high detail all parameters, configuration
1000 file verbs, etc.
1001
1002 @menu
1003 * Configuration file::          Meaning of tokens used in configuration file.
1004 * Parameters for shishi::       Command line parameters for 'shishi'.
1005 * Parameters for shishid::      Command line parameters for 'shishid'.
1006 @end menu
1007
1008 @node Configuration file
1009 @section Configuration file
1010
1011 The valid configuration file tokens are described here.  The user
1012 configuration file is typically located in
1013 @file{~/.shishi/shishi.conf} (compare @samp{shishi
1014 --configuration-file}) and the system configuration is typicall
1015 located in @file{/usr/local/etc/shishi.conf}.  All tokens are valid in
1016 both files, and have the same meaning.  However, as the system file is
1017 supposed to apply to all users on a system, it would not make sense to
1018 use some tokens in both files.  For example, the
1019 @samp{default-principal} is rarely useful in a system configuration
1020 file.
1021
1022 @subsection @samp{default-realm}
1023 Specify the default realm, by default the hostname of the host is
1024 used.  E.g.,
1025
1026 @example
1027 default-realm JOSEFSSON.ORG
1028 @end example
1029
1030 @subsection @samp{default-principal}
1031
1032 Specify the default principal, by default the login username is
1033 used. E.g.,
1034
1035 @example
1036 default-principal jas
1037 @end example
1038
1039 @subsection @samp{client-kdc-etypes}
1040
1041 Specify which encryption types client asks server to respond in during
1042 AS/TGS exchanges. List valid encryption types, in preference order.
1043 Supported algorithms include aes256-cts-hmac-sha1-96,
1044 aes128-cts-hmac-sha1-96, des3-cbc-sha1-kd, des-cbc-md5, des-cbc-md4,
1045 des-cbc-crc and null.  This option also indicates which encryption
1046 types are accepted by the client when receiving the response.  Note
1047 that the preference order is not cryptographically protected, so a man
1048 in the middle can modify the order without being detected.  Thus, only
1049 specify encryption types you trust completely here. The default only
1050 includes aes256-cts-hmac-sha1-96, as suggested by RFC1510bis.  E.g.,
1051
1052 @example
1053 client-kdc-etypes=aes256-cts-hmac-sha1-96 des3-cbc-sha1-kd des-cbc-md5
1054 @end example
1055
1056 @subsection @samp{verbose}, @samp{verbose-asn1}, @samp{verbose-noice}, @samp{verbose-crypto}
1057
1058 Enable verbose library messages.  E.g.,
1059
1060 @example
1061 verbose
1062 verbose-noice
1063 @end example
1064
1065 @subsection @samp{realm-kdc}
1066
1067 Specify KDC addresses for realms.  Value is
1068 @samp{REALM,KDCADDRESS[/PROTOCOL][,KDCADDRESS[/PROTOCOL]...]}.
1069
1070 KDCADDRESS is the hostname or IP address of KDC.
1071
1072 Optional PROTOCOL is udp for UDP, tcp for TCP, and TLS for TLS
1073 connections.  By default UDP is tried first, and TCP used as a
1074 fallback if the KRB_ERR_RESPONSE_TOO_BIG error is received.
1075
1076 If not specified, Shishi tries to locate the KDC using SRV RRs,
1077 which is recommended.  This option should normally only be
1078 used during experiments, or to access badly maintained realms.
1079
1080 @example
1081 realm-kdc=JOSEFSSON.ORG,ristretto.josefsson.org
1082 @end example
1083
1084 @subsection @samp{server-realm}
1085
1086 Specify realm for servers. Value is
1087 @samp{REALM,SERVERREGEXP[,SERVERREGEXP...]}.
1088
1089 SERVERREGEXP is a regular expression matching servers in the realm.
1090 The first match is used.  E.g.,
1091
1092 @example
1093 server-realm=JOSEFSSON.ORG,.josefsson.org
1094 @end example
1095
1096 Note: currently not used.
1097
1098 @subsection @samp{kdc-timeout}, @samp{kdc-retries}
1099
1100 How long shishi waits for a response from a KDC before continuing to
1101 next KDC for realm.  The default is 5 seconds.  E.g.,
1102
1103 @example
1104 kdc-timeout=10
1105 @end example
1106
1107 How many times shishi sends a request to a KDC before giving up.  The
1108 default is 3 times.  E.g.,
1109
1110 @example
1111 kdc-retries=5
1112 @end example
1113
1114 @subsection @samp{stringprocess}
1115
1116 How username and passwords entered from the terminal, or taken from
1117 the command line, are processed.
1118
1119 "none": no processing is used.
1120
1121 "stringprep": convert from locale charset to UTF-8 and process using
1122               experimental RFC 1510 stringprep profile.
1123
1124 It can also be a string indicating a character set supported by
1125 iconv via libstringprep, in which case data is converted from locale
1126 charset into the indicated character set. E.g., UTF-8, ISO-8859-1,
1127 KOI-8, EBCDIC-IS-FRISS are supported on GNU systems.  On some systems
1128 you can use "locale -m" to list available character sets.  By default,
1129 the "none" setting is used which is consistent with RFC 1510 that is
1130 silent on the issue.  In practice, however, converting to UTF-8
1131 improves interoperability.
1132
1133 E.g.,
1134
1135 @example
1136 stringprocess=UTF-8
1137 @end example
1138
1139 @subsection @samp{ticket-life}
1140 Specify default ticket life time.
1141
1142 The string can be in almost any common format.  It can contain month
1143 names, time zones, `am' and `pm', `yesterday', `ago', `next', etc.
1144 Refer to the "Date input formats" in the GNU CoreUtils package for
1145 entire story (@pxref{Date input formats, ,Date input formats,
1146 coreutils, GNU CoreUtils}).  As an extra feature, if the resulting
1147 string you specify has expired within the last 24 hours, an extra day
1148 is added to it.  This allows you to specify "17:00" to always mean the
1149 next 17:00, even if your system clock happens to be 17:30.
1150
1151 The default is 8 hours.
1152
1153 E.g.,
1154
1155 @example
1156 #ticket-life=8 hours
1157 #ticket-life=1 day
1158 ticket-life=17:00
1159 @end example
1160
1161 @subsection @samp{renew-life}
1162
1163 Specify how long a renewable ticket should remain renewable.
1164
1165 See ticket-life for the syntax.  The extra feature that handles
1166 negative values within the last 2 hours is not active here.
1167
1168 The default is 7 days.
1169
1170 E.g.,
1171
1172 @example
1173 #renew-life=1 week
1174 #renew-life=friday 17:00
1175 renew-life=sunday
1176 @end example
1177
1178 @node Parameters for shishi
1179 @section Parameters for shishi
1180
1181 If no command is given, Shishi try to make sure you have a ticket
1182 granting ticket for the default realm, and then display it.
1183
1184 Mandatory or optional arguments to long options are also mandatory or optional
1185 for any corresponding short options.
1186
1187 @example
1188 Usage: lt-shishi [OPTION...] [CLIENT [SERVER]] [OPTION...]
1189   or:  lt-shishi [OPTION...] --list [CLIENT [SERVER]]
1190   or:  lt-shishi [OPTION...] --destroy [CLIENT [SERVER]]
1191   or:  lt-shishi [OPTION...] --string-to-key
1192   or:  lt-shishi [OPTION...]
1193
1194       --client-name=NAME     Client name. Default is login username. Only for
1195                              AS.
1196   -d, --destroy              Destroy tickets in local cache, subject to
1197                              --server-name limiting.
1198   -e, --endtime=STRING       Specify when ticket validity should expire.  The
1199                              time syntax may be relative (to the start time),
1200                              such as "20 hours", or absolute, such as
1201                              "2001-02-03 04:05:06 CET". The default is 8 hours
1202                              after the start time.
1203   -E, --encryption-type=ETYPE,[ETYPE...]
1204                              Encryption types to use.  ETYPE is either
1205                              registered name or integer.
1206       --force-as             Force AS mode. Default is to use TGS iff a TGT is
1207                              found.
1208       --force-tgs            Force TGS mode. Default is to use TGS iff a TGT is
1209                              found.
1210       --key-value=KEY        Cipher key to decrypt response (discouraged).
1211   -l, --list                 List tickets in local cache, subject to
1212                              --server-name limiting.
1213       --proxiable            Get a proxiable ticket.  Only valid for initial
1214                              authentication, or when the ticket-granting ticket
1215                              is proxiable.
1216       --realm=REALM          Realm of server. Default is DNS domain of local
1217                              host. For AS, this also indicates realm of
1218                              client.
1219       --renew-till=STRING    Specify renewable life of ticket.  Implies
1220                              --renewable.  Accepts same time syntax as
1221                              --endtime.  If --renewable is specified, the
1222                              default is 1 week after the start time.
1223       --renewable            Get a renewable ticket.
1224   -R, --renew                Renew ticket.  Use --server-name to specify
1225                              ticket, default is the most recent renewable
1226                              ticket granting ticket for the default realm.
1227       --server=[FAMILY:]ADDRESS:SERVICE/TYPE
1228                              Send all requests to HOST instead of using normal
1229                              logic to locate KDC addresses (discouraged).
1230       --server-name=NAME     Server name. Default is "krbtgt/REALM" where REALM
1231                              is server realm (see --realm).
1232   -s, --starttime=STRING     Specify when ticket should start to be valid.
1233                              Accepts same time syntax as --endtime. The default
1234                              is to become valid immediately.
1235       --ticket-granter=NAME  Service name in ticket to use for authenticating
1236                              request. Only for TGS. Defaults to
1237                              "krbtgt/REALM@@REALM" where REALM is server realm
1238                              (see --realm).
1239
1240  Options for low-level cryptography (CRYPTO-OPTIONS):
1241       --client-name=NAME     Username. Default is login name.
1242       --key-value=KEY        Base64 encoded key value.
1243       --key-version=INTEGER  Version number of key.
1244       --parameter=STRING     String-to-key parameter to use when --password is
1245                              specified. This data is specific for each
1246                              encryption algorithm and rarely needed.
1247       --password=PASSWORD    Password used to generate key (discouraged).
1248       --random               Generate key from random data.
1249       --realm=REALM          Realm of principal. Defaults to DNS domain of
1250                              local host.
1251       --salt=SALT            Salt to use for --string-to-key. Defaults to
1252                              concatenation of realm and (unwrapped) client
1253                              name.
1254       --string-to-key[=[PASSWORD]]
1255                              Convert password into Kerberos key.  Note that
1256                              --client-name, --realm, and --salt influence the
1257                              generated key.
1258       --write-key-file=FILE  Append cipher key to FILE
1259
1260  Other options:
1261       --configuration-file=FILE   Read user configuration from file.  Default
1262                              is ~/.shishi/config.
1263   -c, --ticket-file=FILE     Read tickets from FILE. Default is
1264                              $HOME/.shishi/tickets.
1265   -o, --library-options=STRING   Parse STRING as a configuration file
1266                              statement.
1267   -q, --quiet, --silent      Don't produce any output.
1268       --system-configuration-file=FILE
1269                              Read system wide configuration from file.  Default
1270                              is /usr/local/etc/shishi.conf.
1271       --ticket-write-file=FILE   Write tickets to FILE.  Default is to write
1272                              them back to ticket file.
1273   -v, --verbose              Produce verbose output.
1274       --verbose-library      Produce verbose output in the library.
1275   CLIENT                     Set client name and realm from NAME.  The
1276                              --client-name and --realm parameters can be used
1277                              to override part of NAME.
1278   SERVER                     Set server name and realm from NAME.  The
1279                              --server-name and --server-realm parameters can be
1280                              used to override part of SERVER.
1281
1282   -?, --help                 Give this help list
1283       --usage                Give a short usage message
1284   -V, --version              Print program version
1285 @end example
1286
1287 @node Parameters for shishid
1288 @section Parameters for shishid
1289
1290 If no parameters are specified, @samp{shishid} listens on the defaults
1291 interfaces and answers incoming requests using the keys in the default
1292 key file.
1293
1294 Mandatory or optional arguments to long options are also mandatory or optional
1295 for any corresponding short options.
1296
1297 @example
1298   -c, --configuration-file=FILE   Read configuration from file.  Default is
1299                              /usr/local/etc/shishi.conf.
1300   -k, --key-file=FILE        Read keys from file.  Default is
1301                              /usr/local/etc/shishid.keys.
1302   -l, --listen=[FAMILY:]ADDRESS:SERVICE/TYPE,...
1303                              What to listen on. Family is "IPv4" or "IPv6", if
1304                              absent the family is decided by
1305                              gethostbyname(ADDRESS). An address of "*"
1306                              indicates all addresses on the local host. The
1307                              default is "IPv4:*:kerberos/udp,
1308                              IPv4:*:kerberos/tcp, IPv6:*:kerberos/udp,
1309                              IPv6:*:kerberos/tcp".
1310   -q, -s, --quiet, --silent  Don't produce any output.
1311   -u, --setuid=NAME          After binding socket, set user identity.
1312   -v, --verbose              Produce verbose output.
1313   -?, --help                 Give this help list
1314       --usage                Give a short usage message
1315   -V, --version              Print program version
1316 @end example
1317
1318 @c **********************************************************
1319 @c ***************  Programming Manual  *********************
1320 @c **********************************************************
1321 @node Programming Manual
1322 @chapter Programming Manual
1323 @cindex Application Programming Interface (API)
1324
1325 This chapter describes all the publicly available functions in the
1326 library.
1327
1328 @menu
1329 * Preparation::                 What you should do before using the library.
1330 * Initialization Functions::    Creating library handle, configuration file.
1331 * Ticket Set Functions::        High-level ticket management functions.
1332 * AP-REQ and AP-REP Functions:: Client/Server authentication functions.
1333 * SAFE and PRIV Functions::     Client/Server session data functions.
1334 * Ticket Functions::            Medium-level ticket manipulation functions.
1335 * AS Functions::                Medium-level initial authentication functions.
1336 * TGS Functions::               Medium-level authentication functions.
1337 * Ticket (ASN.1) Functions::    Low-level Ticket functions.
1338 * AS/TGS Functions::            Low-level KDC functions; AS and TGS.
1339 * Authenticator Functions::     Low-level authenticator functions.
1340 * Cryptographic Functions::     Low-level cryptographic functions.
1341 * Utility Functions::           Utilities for use in the global context.
1342 * Error Handling::              Error codes and such.
1343 * Examples::                    Example code.
1344 * Generic Security Service::    If you want to use the GSS API instead.
1345 @end menu
1346
1347 @node Preparation
1348 @section Preparation
1349
1350 To use `Libshishi', you have to perform some changes to your sources
1351 and the build system.  The necessary changes are small and explained
1352 in the following sections.  At the end of this chapter, it is
1353 described how the library is initialized, and how the requirements of
1354 the library are verified.
1355
1356 A faster way to find out how to adapt your application for use with
1357 `Libshishi' may be to look at the examples at the end of this manual
1358 (@pxref{Examples}).
1359
1360 @menu
1361 * Header::
1362 * Initialization::
1363 * Version Check::
1364 * Building the source::
1365 * Autoconf tests::
1366 @end menu
1367
1368 @node Header
1369 @subsection Header
1370
1371 All interfaces (data types and functions) of the library are defined
1372 in the header file `shishi.h'.  You must include this in all programs
1373 using the library, either directly or through some other header file,
1374 like this:
1375
1376 @example
1377 #include <shishi.h>
1378 @end example
1379
1380 The name space of `Libshishi' is @code{shishi_*} for function names,
1381 @code{Shishi*} for data types and @code{SHISHI_*} for other symbols.  In
1382 addition the same name prefixes with one prepended underscore are
1383 reserved for internal use and should never be used by an application.
1384
1385 @node Initialization
1386 @subsection Initialization
1387
1388 `Libshishi' must be initialized before it can be used.  The library is
1389 initialized by calling @code{shishi_init} (@pxref{Initialization
1390 Functions}).  The resources allocated by the initialization process
1391 can be released if the application no longer has a need to call
1392 `Libshishi' functions, this is done by calling @code{shishi_done}.
1393
1394 In order to take advantage of the internationalisation features in
1395 `Libshishi', such as translated error messages, the application must
1396 set the current locale using @code{setlocale} before initializing
1397 `Libshishi'.
1398
1399 @node Version Check
1400 @subsection Version Check
1401
1402 It is often desirable to check that the version of `Libshishi' used is
1403 indeed one which fits all requirements.  Even with binary
1404 compatibility new features may have been introduced but due to problem
1405 with the dynamic linker an old version is actually used.  So you may
1406 want to check that the version is okay right after program startup.
1407
1408 @include shishi-api-version.texi
1409
1410 The normal way to use the function is to put something similar to the
1411 following early in your @code{main}:
1412
1413 @example
1414   if (!shishi_check_version (SHISHI_VERSION))
1415     @{
1416       printf ("shishi_check_version failed:\n"
1417               "Header file incompatible with shared library.\n");
1418       exit(1);
1419     @}
1420 @end example
1421
1422 @node Building the source
1423 @subsection Building the source
1424 @cindex Compiling your application
1425
1426 If you want to compile a source file including the `shishi.h' header
1427 file, you must make sure that the compiler can find it in the
1428 directory hierarchy.  This is accomplished by adding the path to the
1429 directory in which the header file is located to the compilers include
1430 file search path (via the @option{-I} option).
1431
1432 However, the path to the include file is determined at the time the
1433 source is configured.  To solve this problem, `Libshishi' uses the
1434 external package @command{pkg-config} that knows the path to the
1435 include file and other configuration options.  The options that need
1436 to be added to the compiler invocation at compile time are output by
1437 the @option{--cflags} option to @command{pkg-config shishi}.  The
1438 following example shows how it can be used at the command line:
1439
1440 @example
1441 gcc -c foo.c `pkg-config shishi --cflags`
1442 @end example
1443
1444 Adding the output of @samp{pkg-config shishi --cflags} to the
1445 compilers command line will ensure that the compiler can find the
1446 `Libshishi' header file.
1447
1448 A similar problem occurs when linking the program with the library.
1449 Again, the compiler has to find the library files.  For this to work,
1450 the path to the library files has to be added to the library search path
1451 (via the @option{-L} option).  For this, the option @option{--libs} to
1452 @command{pkg-config shishi} can be used.  For convenience, this option
1453 also outputs all other options that are required to link the program
1454 with the `Libshishi' libararies (in particular, the @samp{-lshishi}
1455 option).  The example shows how to link @file{foo.o} with the `Libshishi'
1456 library to a program @command{foo}.
1457
1458 @example
1459 gcc -o foo foo.o `pkg-config shishi --libs`
1460 @end example
1461
1462 Of course you can also combine both examples to a single command by
1463 specifying both options to @command{pkg-config}:
1464
1465 @example
1466 gcc -o foo foo.c `pkg-config shishi --cflags --libs`
1467 @end example
1468
1469 @node Autoconf tests
1470 @subsection Autoconf tests
1471 @cindex Autoconf tests
1472 @cindex Configure tests
1473
1474 If you work on a project that uses Autoconf (@pxref{top, GNU
1475 Autoconf,, autoconf}) to help find installed libraries, the
1476 suggestions in the previous section are not the entire story.  There
1477 are a few methods to detect and incorporate Shishi into your Autoconf
1478 based package.  The preferred approach, is to use Libtool in your
1479 project, and use the normal Autoconf header file and library tests.
1480
1481 @subsubsection Autoconf test via @samp{pkg-config}
1482
1483 If your audience is a typical GNU/Linux desktop, you can often assume
1484 they have the @samp{pkg-config} tool installed, in which you can use
1485 its Autoconf M4 macro to find and set up your package for use with
1486 Shishi.  The following illustrate this scenario.
1487
1488 @example
1489 AC_ARG_ENABLE(kerberos_v5,
1490         AC_HELP_STRING([--disable-kerberos_v5],
1491                        [don't use the KERBEROS_V5 mechanism]),
1492         kerberos_v5=$enableval)
1493 if test "$kerberos_v5" != "no" ; then
1494         PKG_CHECK_MODULES(SHISHI, shishi >= 0.0.0,
1495                         [kerberos_v5=yes],
1496                         [kerberos_v5=no])
1497         if test "$kerberos_v5" != "yes" ; then
1498                 kerberos_v5=no
1499                 AC_MSG_WARN([shishi not found, disabling Kerberos 5])
1500         else
1501                 kerberos_v5=yes
1502                 AC_DEFINE(USE_KERBEROS_V5, 1,
1503                           [Define to 1 if you want Kerberos 5.])
1504         fi
1505 fi
1506 AC_MSG_CHECKING([if Kerberos 5 should be used])
1507 AC_MSG_RESULT($kerberos_v5)
1508 @end example
1509
1510 @subsubsection Standalone Autoconf test using Libtool
1511
1512 If your package uses Libtool(@pxref{top, GNU Libtool,, libtool}), you
1513 can use the normal Autoconf tests to find the Shishi library and rely
1514 on the Libtool dependency tracking to include the proper dependency
1515 libraries (e.g., Libidn).  The following illustrate this scenario.
1516
1517 @example
1518 AC_CHECK_HEADER(shishi.h,
1519         AC_CHECK_LIB(shishi, shishi_check_version,
1520                 [kerberos5=yes AC_SUBST(SHISHI_LIBS, -lshishi)],
1521                 kerberos5=no),
1522         kerberos5=no)
1523 AC_ARG_ENABLE(kerberos5,
1524         AC_HELP_STRING([--disable-kerberos5],
1525                        [disable Kerberos 5 unconditionally]),
1526         kerberos5=$enableval)
1527 if test "$kerberos5" != "no" ; then
1528         AC_DEFINE(USE_KERBEROS_V5, 1,
1529                   [Define to 1 if you want Kerberos 5.])
1530 else
1531         AC_MSG_WARN([Shishi not found, disabling Kerberos 5])
1532 fi
1533 AC_MSG_CHECKING([if Kerberos 5 should be used])
1534 AC_MSG_RESULT($kerberos5)
1535 @end example
1536
1537 @subsubsection Standalone Autoconf test
1538
1539 If your package does not use Libtool, as well as detecting the Shishi
1540 library as in the previous case, you must also detect whatever
1541 dependencies Shishi requires to work (e.g., libidn).  Since the
1542 dependencies are in a state of flux, we do not provide an example and
1543 we do not recommend this approach, unless you are experienced
1544 developer.
1545
1546 @node Initialization Functions
1547 @section Initialization Functions
1548
1549 @include shishi-api-init.texi
1550
1551
1552 @node Ticket Set Functions
1553 @section Ticket Set Functions
1554
1555 A ``ticket set'' is, as the name implies, a collection of tickets.
1556 Functions are provided to read tickets from file into a ticket set, to
1557 query number of tickets in the set, to extract a given ticket from the
1558 set, to search the ticket set for tickets matching certain criterium,
1559 to write the ticket set to a file, etc.  High level functions for
1560 performing a initial authentication (@pxref{AS Functions}) or
1561 subsequent authentication (@pxref{TGS Functions}) and storing the new
1562 ticket in the ticket set are also provided.
1563
1564 To manipulate each individual ticket, @xref{Ticket Functions}.  For
1565 low-level ASN.1 manipulation see @xref{Ticket (ASN.1) Functions}.
1566
1567 @include shishi-api-tkts.texi
1568
1569
1570 @node AP-REQ and AP-REP Functions
1571 @section AP-REQ and AP-REP Functions
1572
1573 The ``AP-REQ'' and ``AP-REP'' are ASN.1 structures used by application
1574 client and servers to prove to each other who they are.  The
1575 structures contain auxilliary information, together with an
1576 authenticator (@pxref{Authenticator Functions}) which is the real
1577 cryptographic proof.  The following illustrates the AP-REQ and AP-REP
1578 ASN.1 structures.
1579
1580 @verbatim
1581 AP-REQ          ::= [APPLICATION 14] SEQUENCE {
1582         pvno            [0] INTEGER (5),
1583         msg-type        [1] INTEGER (14),
1584         ap-options      [2] APOptions,
1585         ticket          [3] Ticket,
1586         authenticator   [4] EncryptedData {Authenticator,
1587                                 { keyuse-pa-TGSReq-authenticator
1588                                   | keyuse-APReq-authenticator }}
1589 }
1590
1591 AP-REP          ::= [APPLICATION 15] SEQUENCE {
1592         pvno            [0] INTEGER (5),
1593         msg-type        [1] INTEGER (15),
1594         enc-part        [2] EncryptedData {EncAPRepPart,
1595                                 { keyuse-EncAPRepPart }}
1596 }
1597
1598 EncAPRepPart    ::= [APPLICATION 27] SEQUENCE {
1599         ctime           [0] KerberosTime,
1600         cusec           [1] Microseconds,
1601         subkey          [2] EncryptionKey OPTIONAL,
1602         seq-number      [3] UInt32 OPTIONAL
1603 }
1604 @end verbatim
1605
1606 @include shishi-api-ap.texi
1607
1608
1609 @node SAFE and PRIV Functions
1610 @section SAFE and PRIV Functions
1611
1612 The ``KRB-SAFE'' is an ASN.1 structure used by application client and
1613 servers to exchange integrity protected data.  The integrity
1614 protection is keyed, usually with a key agreed on via the AP exchange
1615 (@pxref{AP-REQ and AP-REP Functions}).  The following illustrates the
1616 KRB-SAFE ASN.1 structure.
1617
1618 @verbatim
1619    KRB-SAFE        ::= [APPLICATION 20] SEQUENCE {
1620            pvno            [0] INTEGER (5),
1621            msg-type        [1] INTEGER (20),
1622            safe-body       [2] KRB-SAFE-BODY,
1623            cksum           [3] Checksum
1624    }
1625
1626    KRB-SAFE-BODY   ::= SEQUENCE {
1627            user-data       [0] OCTET STRING,
1628            timestamp       [1] KerberosTime OPTIONAL,
1629            usec            [2] Microseconds OPTIONAL,
1630            seq-number      [3] UInt32 OPTIONAL,
1631            s-address       [4] HostAddress,
1632            r-address       [5] HostAddress OPTIONAL
1633    }
1634 @end verbatim
1635
1636 @include shishi-api-safe.texi
1637
1638 The ``KRB-PRIV'' is an ASN.1 structure used by application client and
1639 servers to exchange confidential data.  The confidentiality is keyed,
1640 usually with a key agreed on via the AP exchange (@pxref{AP-REQ and
1641 AP-REP Functions}).  The following illustrates the KRB-PRIV ASN.1
1642 structure.
1643
1644 @verbatim
1645    KRB-PRIV        ::= [APPLICATION 21] SEQUENCE {
1646            pvno            [0] INTEGER (5),
1647            msg-type        [1] INTEGER (21),
1648                            -- NOTE: there is no [2] tag
1649            enc-part        [3] EncryptedData -- EncKrbPrivPart
1650    }
1651
1652    EncKrbPrivPart  ::= [APPLICATION 28] SEQUENCE {
1653            user-data       [0] OCTET STRING,
1654            timestamp       [1] KerberosTime OPTIONAL,
1655            usec            [2] Microseconds OPTIONAL,
1656            seq-number      [3] UInt32 OPTIONAL,
1657            s-address       [4] HostAddress -- sender's addr --,
1658            r-address       [5] HostAddress OPTIONAL -- recip's addr
1659    }
1660 @end verbatim
1661
1662 @include shishi-api-priv.texi
1663
1664
1665 @node Ticket Functions
1666 @section Ticket Functions
1667
1668 @include shishi-api-tkt.texi
1669
1670
1671 @node AS Functions
1672 @section AS Functions
1673
1674 The Authentication Service (AS) is used to get an initial ticket using
1675 e.g. your password.  The following illustrates the AS-REQ and AS-REP
1676 ASN.1 structures.
1677
1678 @verbatim
1679 -- Request --
1680
1681 AS-REQ          ::= KDC-REQ {10}
1682
1683 KDC-REQ {INTEGER:tagnum}        ::= [APPLICATION tagnum] SEQUENCE {
1684         pvno            [1] INTEGER (5) -- first tag is [1], not [0] --,
1685         msg-type        [2] INTEGER (tagnum),
1686         padata          [3] SEQUENCE OF PA-DATA OPTIONAL,
1687         req-body        [4] KDC-REQ-BODY
1688 }
1689
1690 KDC-REQ-BODY    ::= SEQUENCE {
1691         kdc-options             [0] KDCOptions,
1692         cname                   [1] PrincipalName OPTIONAL
1693                                     -- Used only in AS-REQ --,
1694         realm                   [2] Realm
1695                                     -- Server's realm
1696                                     -- Also client's in AS-REQ --,
1697         sname                   [3] PrincipalName OPTIONAL,
1698         from                    [4] KerberosTime OPTIONAL,
1699         till                    [5] KerberosTime,
1700         rtime                   [6] KerberosTime OPTIONAL,
1701         nonce                   [7] UInt32,
1702         etype                   [8] SEQUENCE OF Int32 -- EncryptionType
1703                                     -- in preference order --,
1704         addresses               [9] HostAddresses OPTIONAL,
1705         enc-authorization-data  [10] EncryptedData {
1706                                         AuthorizationData,
1707                                         { keyuse-TGSReqAuthData-sesskey
1708                                           | keyuse-TGSReqAuthData-subkey }
1709                                      } OPTIONAL,
1710         additional-tickets      [11] SEQUENCE OF Ticket OPTIONAL
1711 }
1712
1713 -- Reply --
1714
1715 AS-REP          ::= KDC-REP {11, EncASRepPart, {keyuse-EncASRepPart}}
1716
1717 KDC-REP {INTEGER:tagnum,
1718          TypeToEncrypt,
1719          UInt32:KeyUsages}      ::= [APPLICATION tagnum] SEQUENCE {
1720         pvno            [0] INTEGER (5),
1721         msg-type        [1] INTEGER (tagnum),
1722         padata          [2] SEQUENCE OF PA-DATA OPTIONAL,
1723         crealm          [3] Realm,
1724         cname           [4] PrincipalName,
1725         ticket          [5] Ticket,
1726         enc-part        [6] EncryptedData {TypeToEncrypt, KeyUsages}
1727 }
1728
1729 EncASRepPart    ::= [APPLICATION 25] EncKDCRepPart
1730
1731 EncKDCRepPart   ::= SEQUENCE {
1732         key             [0] EncryptionKey,
1733         last-req        [1] LastReq,
1734         nonce           [2] UInt32,
1735         key-expiration  [3] KerberosTime OPTIONAL,
1736         flags           [4] TicketFlags,
1737         authtime        [5] KerberosTime,
1738         starttime       [6] KerberosTime OPTIONAL,
1739         endtime         [7] KerberosTime,
1740         renew-till      [8] KerberosTime OPTIONAL,
1741         srealm          [9] Realm,
1742         sname           [10] PrincipalName,
1743         caddr           [11] HostAddresses OPTIONAL
1744 }
1745 @end verbatim
1746
1747 @include shishi-api-as.texi
1748
1749
1750 @node TGS Functions
1751 @section TGS Functions
1752
1753 The Ticket Granting Service (TGS) is used to get subsequent tickets,
1754 authenticated by other tickets (so called ticket granting tickets).
1755 The following illustrates the TGS-REQ and TGS-REP ASN.1 structures.
1756
1757 @verbatim
1758 -- Request --
1759
1760 TGS-REQ         ::= KDC-REQ {12}
1761
1762 KDC-REQ {INTEGER:tagnum}        ::= [APPLICATION tagnum] SEQUENCE {
1763         pvno            [1] INTEGER (5) -- first tag is [1], not [0] --,
1764         msg-type        [2] INTEGER (tagnum),
1765         padata          [3] SEQUENCE OF PA-DATA OPTIONAL,
1766         req-body        [4] KDC-REQ-BODY
1767 }
1768
1769 KDC-REQ-BODY    ::= SEQUENCE {
1770         kdc-options             [0] KDCOptions,
1771         cname                   [1] PrincipalName OPTIONAL
1772                                     -- Used only in AS-REQ --,
1773         realm                   [2] Realm
1774                                     -- Server's realm
1775                                     -- Also client's in AS-REQ --,
1776         sname                   [3] PrincipalName OPTIONAL,
1777         from                    [4] KerberosTime OPTIONAL,
1778         till                    [5] KerberosTime,
1779         rtime                   [6] KerberosTime OPTIONAL,
1780         nonce                   [7] UInt32,
1781         etype                   [8] SEQUENCE OF Int32 -- EncryptionType
1782                                     -- in preference order --,
1783         addresses               [9] HostAddresses OPTIONAL,
1784         enc-authorization-data  [10] EncryptedData {
1785                                         AuthorizationData,
1786                                         { keyuse-TGSReqAuthData-sesskey
1787                                           | keyuse-TGSReqAuthData-subkey }
1788                                      } OPTIONAL,
1789         additional-tickets      [11] SEQUENCE OF Ticket OPTIONAL
1790 }
1791
1792 -- Reply --
1793
1794 TGS-REP         ::= KDC-REP {13, EncTGSRepPart,
1795                         { keyuse-EncTGSRepPart-sesskey
1796                           | keyuse-EncTGSRepPart-subkey }}
1797
1798 KDC-REP {INTEGER:tagnum,
1799          TypeToEncrypt,
1800          UInt32:KeyUsages}      ::= [APPLICATION tagnum] SEQUENCE {
1801         pvno            [0] INTEGER (5),
1802         msg-type        [1] INTEGER (tagnum),
1803         padata          [2] SEQUENCE OF PA-DATA OPTIONAL,
1804         crealm          [3] Realm,
1805         cname           [4] PrincipalName,
1806         ticket          [5] Ticket,
1807         enc-part        [6] EncryptedData {TypeToEncrypt, KeyUsages}
1808 }
1809
1810 EncTGSRepPart   ::= [APPLICATION 26] EncKDCRepPart
1811
1812 EncKDCRepPart   ::= SEQUENCE {
1813         key             [0] EncryptionKey,
1814         last-req        [1] LastReq,
1815         nonce           [2] UInt32,
1816         key-expiration  [3] KerberosTime OPTIONAL,
1817         flags           [4] TicketFlags,
1818         authtime        [5] KerberosTime,
1819         starttime       [6] KerberosTime OPTIONAL,
1820         endtime         [7] KerberosTime,
1821         renew-till      [8] KerberosTime OPTIONAL,
1822         srealm          [9] Realm,
1823         sname           [10] PrincipalName,
1824         caddr           [11] HostAddresses OPTIONAL
1825 }
1826 @end verbatim
1827
1828 @include shishi-api-tgs.texi
1829
1830
1831 @node Ticket (ASN.1) Functions
1832 @section Ticket (ASN.1) Functions
1833
1834 @include shishi-api-ticket.texi
1835
1836 @node AS/TGS Functions
1837 @section AS/TGS Functions
1838
1839 The Authentication Service (AS) is used to get an initial ticket using
1840 e.g. your password.  The Ticket Granting Service (TGS) is used to get
1841 subsequent tickets using other tickets.  Protocol wise the procedures
1842 are very similar, which is the reason they are described together.
1843 The following illustrates the AS-REQ, TGS-REQ and AS-REP, TGS-REP
1844 ASN.1 structures.  Most of the functions use the mnemonic ``KDC''
1845 instead of either AS or TGS, which means the function operates on both
1846 AS and TGS types.  Only where the distinction between AS and TGS is
1847 important are the AS and TGS names used.  Remember, these are
1848 low-level functions, and normal applications will likely be satisfied
1849 with the AS (@pxref{AS Functions}) and TGS (@pxref{TGS Functions})
1850 interfaces, or the even more high-level Ticket Set (@pxref{Ticket Set
1851 Functions}) interface.
1852
1853 @verbatim
1854 -- Request --
1855
1856 AS-REQ          ::= KDC-REQ {10}
1857 TGS-REQ         ::= KDC-REQ {12}
1858
1859 KDC-REQ {INTEGER:tagnum}        ::= [APPLICATION tagnum] SEQUENCE {
1860         pvno            [1] INTEGER (5) -- first tag is [1], not [0] --,
1861         msg-type        [2] INTEGER (tagnum),
1862         padata          [3] SEQUENCE OF PA-DATA OPTIONAL,
1863         req-body        [4] KDC-REQ-BODY
1864 }
1865
1866 KDC-REQ-BODY    ::= SEQUENCE {
1867         kdc-options             [0] KDCOptions,
1868         cname                   [1] PrincipalName OPTIONAL
1869                                     -- Used only in AS-REQ --,
1870         realm                   [2] Realm
1871                                     -- Server's realm
1872                                     -- Also client's in AS-REQ --,
1873         sname                   [3] PrincipalName OPTIONAL,
1874         from                    [4] KerberosTime OPTIONAL,
1875         till                    [5] KerberosTime,
1876         rtime                   [6] KerberosTime OPTIONAL,
1877         nonce                   [7] UInt32,
1878         etype                   [8] SEQUENCE OF Int32 -- EncryptionType
1879                                     -- in preference order --,
1880         addresses               [9] HostAddresses OPTIONAL,
1881         enc-authorization-data  [10] EncryptedData {
1882                                         AuthorizationData,
1883                                         { keyuse-TGSReqAuthData-sesskey
1884                                           | keyuse-TGSReqAuthData-subkey }
1885                                      } OPTIONAL,
1886         additional-tickets      [11] SEQUENCE OF Ticket OPTIONAL
1887 }
1888
1889 -- Reply --
1890
1891 AS-REP          ::= KDC-REP {11, EncASRepPart, {keyuse-EncASRepPart}}
1892 TGS-REP         ::= KDC-REP {13, EncTGSRepPart,
1893                         { keyuse-EncTGSRepPart-sesskey
1894                           | keyuse-EncTGSRepPart-subkey }}
1895
1896 KDC-REP {INTEGER:tagnum,
1897          TypeToEncrypt,
1898          UInt32:KeyUsages}      ::= [APPLICATION tagnum] SEQUENCE {
1899         pvno            [0] INTEGER (5),
1900         msg-type        [1] INTEGER (tagnum),
1901         padata          [2] SEQUENCE OF PA-DATA OPTIONAL,
1902         crealm          [3] Realm,
1903         cname           [4] PrincipalName,
1904         ticket          [5] Ticket,
1905         enc-part        [6] EncryptedData {TypeToEncrypt, KeyUsages}
1906 }
1907
1908 EncASRepPart    ::= [APPLICATION 25] EncKDCRepPart
1909 EncTGSRepPart   ::= [APPLICATION 26] EncKDCRepPart
1910
1911 EncKDCRepPart   ::= SEQUENCE {
1912         key             [0] EncryptionKey,
1913         last-req        [1] LastReq,
1914         nonce           [2] UInt32,
1915         key-expiration  [3] KerberosTime OPTIONAL,
1916         flags           [4] TicketFlags,
1917         authtime        [5] KerberosTime,
1918         starttime       [6] KerberosTime OPTIONAL,
1919         endtime         [7] KerberosTime,
1920         renew-till      [8] KerberosTime OPTIONAL,
1921         srealm          [9] Realm,
1922         sname           [10] PrincipalName,
1923         caddr           [11] HostAddresses OPTIONAL
1924 }
1925 @end verbatim
1926
1927 @include shishi-api-kdc.texi
1928
1929
1930 @node Authenticator Functions
1931 @section Authenticator Functions
1932
1933 An ``Authenticator'' is a ASN.1 structure that work as a proof that an
1934 entity owns a ticket.  It is usually embedded in the AP-REQ structure
1935 (@pxref{AP-REQ and AP-REP Functions}), and you most likely want to use
1936 an AP-REQ instead of a Authenticator in normal applications.  The
1937 following illustrates the Authenticator ASN.1 structure.
1938
1939 @verbatim
1940 Authenticator   ::= [APPLICATION 2] SEQUENCE  {
1941         authenticator-vno       [0] INTEGER (5),
1942         crealm                  [1] Realm,
1943         cname                   [2] PrincipalName,
1944         cksum                   [3] Checksum OPTIONAL,
1945         cusec                   [4] Microseconds,
1946         ctime                   [5] KerberosTime,
1947         subkey                  [6] EncryptionKey OPTIONAL,
1948         seq-number              [7] UInt32 OPTIONAL,
1949         authorization-data      [8] AuthorizationData OPTIONAL
1950 }
1951 @end verbatim
1952
1953 @include shishi-api-authenticator.texi
1954
1955
1956 @node Cryptographic Functions
1957 @section Cryptographic Functions
1958
1959 Underneath the high-level functions described earlier, cryptographic
1960 operations are happening.  If you need to access these cryptographic
1961 primitives directly, this section describes the functions available.
1962
1963 Most cryptographic operations need keying material, and cryptographic
1964 keys have been isolated into it's own data structure
1965 @code{Shishi_key}.  The following illustrates it's contents, but note
1966 that you cannot access it's elements directly but must use the
1967 accessor functions described below.
1968
1969 @verbatim
1970 struct Shishi_key
1971 {
1972   int type;    /* RFC 1510 encryption integer type */
1973   char *value; /* Cryptographic key data */
1974   int version; /* RFC 1510 ``kvno'' */
1975 };
1976 @end verbatim
1977
1978 All functions that operate on this data structure are described now.
1979
1980 @include shishi-api-key.texi
1981
1982 Applications that run uninteractively may need keying material.  In
1983 these cases, the keys are stored in a file, a file that is normally
1984 stored on the local host.  The file should be protected from
1985 unauthorized access.  The file is in ASCII format and contains keys as
1986 outputed by @code{shishi_key_print}.  All functions that handle these
1987 keys sets are described now.
1988
1989 @include shishi-api-keys.texi
1990
1991 The previous functions require that the filename is known.  For some
1992 applications, servers, it makes sense to provide a system default.
1993 These key sets used by server applications are known as ``hostkeys''.
1994 Here are the functions that operate on hostkeys (they are mostly
1995 wrappers around generic key sets).
1996
1997 @include shishi-api-hostkeys.texi
1998
1999 After creating the key structure, it can be used to encrypt and
2000 decrypt data, calculate checksum on data etc.  All available functions
2001 are described now.
2002
2003 @include shishi-api-crypto.texi
2004
2005 Also included in Shishi is an interface to the really low-level
2006 cryptographic primitives.  They map directly on the underlying
2007 cryptographic library used (e.g., Nettle) and is used internally by
2008 Shishi.
2009
2010 @include shishi-api-nettle.texi
2011
2012
2013 @node Utility Functions
2014 @section Utility Functions
2015
2016 @include shishi-api-utility.texi
2017
2018
2019 @node Error Handling
2020 @section Error Handling
2021 @cindex Error Handling
2022
2023 Most functions in `Libshishi' are returning an error if they fail.
2024 For this reason, the application should always catch the error
2025 condition and take appropriate measures, for example by releasing the
2026 resources and passing the error up to the caller, or by displaying a
2027 descriptive message to the user and cancelling the operation.
2028
2029 Some error values do not indicate a system error or an error in the
2030 operation, but the result of an operation that failed properly.
2031
2032 @menu
2033 * Error Values::                A list of all error values used.
2034 * Error Functions::             Error handling related functions.
2035 @end menu
2036
2037 @node Error Values
2038 @subsection Error Values
2039
2040 Errors are returned as an @code{int}.  Except for the SHISHI_OK case,
2041 an application should always use the constants instead of their
2042 numeric value.  Applications are encouraged to use the constants even
2043 for SHISHI_OK as it improves readability.  Possible values are:
2044
2045 @table @code
2046 @item SHISHI_OK
2047 This value indicates success.  The value of this error is guaranteed
2048 to always be @code{0} so you may use it in boolean constructs.
2049
2050 @include shishi-api-error-labels.texi
2051
2052 @end table
2053
2054 @node Error Functions
2055 @subsection Error Functions
2056
2057 @include shishi-api-error.texi
2058
2059 @node Examples
2060 @section Examples
2061 @cindex Examples
2062
2063 This section will be extended to contain walk-throughs of example code
2064 that demonstrate how `Shishi' is used to write your own applications
2065 that support Kerberos 5.  The rest of the current section consists of
2066 some crude hints for the example client/server applications that is
2067 part of Shishi, taken from an email but saved here for lack of a
2068 better place to put it.
2069
2070 There are two programs: 'client' and 'server' in src/.
2071
2072 The client output an AP-REQ, waits for an AP-REP, and then simply
2073 reads data from stdin.
2074
2075 The server waits for an AP-REQ, parses it and prints an AP-REP, and
2076 then read data from stdin.
2077
2078 Both programs accept a Kerberos server name as the first command line
2079 argument.  Your KDC must know this server, since the client tries to
2080 get a ticket for it (first it gets a ticket granting ticket for the
2081 default username), and you must write the key for the server into
2082 /usr/local/etc/shishi.keys on the Shishi format, e.g.:
2083
2084 @example
2085 -----BEGIN SHISHI KEY-----
2086 Keytype: 16 (des3-cbc-sha1-kd)
2087 Principal: sample/latte.josefsson.org
2088 Realm: JOSEFSSON.ORG
2089
2090 8W0VrQQBpxlACPQEqN91EHxbvFFo2ltt
2091 -----END SHISHI KEY-----
2092 @end example
2093
2094 You must extract the proper encryption key from the KDC in some way.
2095 (This part will be easier when Shishi include a KDC, a basic one isn't
2096 far away, give me a week or to.)
2097
2098 The intention is that the data read, after the authentication phase,
2099 should be protected using KRB_SAFE (see RFC) but I haven't added this
2100 yet.
2101
2102 @node Generic Security Service
2103 @section Generic Security Service
2104 @cindex Generic Security Service
2105 @cindex GSS-API
2106 @cindex GSSLib
2107
2108 As an alternative to the native Shishi programming API, it is possible
2109 to program Shishi through the Generic Security Services (GSS) API.
2110 The advantage of using GSS-API in your security application, instead
2111 of the native Shishi API, is that it will be easier to port your
2112 application between different Kerberos 5 implementations, and even
2113 beyond Kerberos 5 to different security systems, that support GSS-API.
2114 In the free software world, however, almost the only widely used
2115 security system that supports GSS-API is Kerberos 5, so the last
2116 advantage is somewhat academic.  But if you are porting applications
2117 using GSS-API for other Kerberos 5 implementations, or want a more
2118 mature and stable API than the native Shishi API, you may find using
2119 Shishi's GSS-API interface compelling.  Note that GSS-API only offer
2120 basic services, for more advanced uses you must use the native API.
2121
2122 Since the GSS-API is not specific to Shishi, it is distributed
2123 independently from Shishi.  Further information on the GSS project can
2124 be found at @url{http://josefsson.org/gss/}.
2125
2126 @c **********************************************************
2127 @c *******************  Acknowledgements  *******************
2128 @c **********************************************************
2129 @node Acknowledgements
2130 @chapter Acknowledgements
2131
2132 Shishi uses Libtasn1 by Fabio Fiorina, Libnettle by Niels Möller,
2133 Libgcrypt and Libgpg-error by Werner Koch, Libidn by Simon Josefsson,
2134 cvs2cl by Karl Fogel, and gdoc by Michael Zucchi.
2135
2136 Several GNU packages simplified development considerably, those
2137 packages include Autoconf, Automake, Libtool, Gnulib, Gettext, Indent,
2138 CVS, Texinfo, Help2man and Emacs.
2139
2140 Several people reported bugs, sent patches or suggested improvements,
2141 see the file THANKS.
2142
2143 @c **********************************************************
2144 @c *******************  Appendices  *************************
2145 @c **********************************************************
2146
2147 @node Copying This Manual
2148 @appendix Copying This Manual
2149
2150 @menu
2151 * GNU Free Documentation License::  License for copying this manual.
2152 @end menu
2153
2154 @include fdl.texi
2155
2156 @include gpl.texi
2157
2158 @node Concept Index
2159 @unnumbered Concept Index
2160
2161 @printindex cp
2162
2163 @node Function and Data Index
2164 @unnumbered Function and Data Index
2165
2166 @printindex fn
2167
2168 @summarycontents
2169 @contents
2170 @bye