This is ./shishi.info, produced by makeinfo version 4.8 from
./shishi.texi.

   This manual is last updated 2 April 2013 for version 1.0.2 of Shishi.

   Copyright (C) 2002-2013 Simon Josefsson.

     Permission is granted to copy, distribute and/or modify this
     document under the terms of the GNU Free Documentation License,
     Version 1.3 or any later version published by the Free Software
     Foundation; with no Invariant Sections, no Front-Cover Texts, and
     no Back-Cover Texts.  A copy of the license is included in the
     section entitled "GNU Free Documentation License".

INFO-DIR-SECTION GNU utilities
START-INFO-DIR-ENTRY
* shishi: (shishi).		A Kerberos 5 implementation
END-INFO-DIR-ENTRY

INFO-DIR-SECTION GNU Libraries
START-INFO-DIR-ENTRY
* libshishi: (shishi).		Library implementing Kerberos 5.
END-INFO-DIR-ENTRY


File: shishi.info,  Node: Top,  Next: Introduction,  Up: (dir)

Shishi
******

This manual is last updated 2 April 2013 for version 1.0.2 of Shishi.

   Copyright (C) 2002-2013 Simon Josefsson.

     Permission is granted to copy, distribute and/or modify this
     document under the terms of the GNU Free Documentation License,
     Version 1.3 or any later version published by the Free Software
     Foundation; with no Invariant Sections, no Front-Cover Texts, and
     no Back-Cover Texts.  A copy of the license is included in the
     section entitled "GNU Free Documentation License".

* Menu:

* Introduction::                How to use this manual.
* User Manual::                 Using Shishi as end-user.
* Administration Manual::       Administrating server aspects of Shishi.
* Reference Manual::            Detailed description of config files, etc.
* Programming Manual::          Calling Shishi from a programming language.
* Acknowledgements::            Whom to blame.

Appendices

* Criticism of Kerberos::       Why you maybe shouldn't use Kerberos.
* Protocol Extensions::         Description of protocol extensions used.
* Copying Information::         How you can copy and share Shishi.

Indices

* Function and Data Index::     Index of functions, variables and data types.
* Concept Index::               Index of concepts and programs.


File: shishi.info,  Node: Introduction,  Next: User Manual,  Prev: Top,  Up: Top

1 Introduction
**************

Shishi is an implementation of the Kerberos 5 network authentication
system, as specified in RFC 4120.  Shishi can be used to authenticate
users in distributed systems.

   Shishi contains a library ('libshishi') that can be used by
application developers to add support for Kerberos 5.  Shishi contains
a command line utility ('shishi') that is used by users to acquire and
manage tickets (and more).  The server side, a Key Distribution Center,
is implemented by 'shishid'.  Of course, a manual documenting usage
aspects as well as the programming API is included.

   Shishi currently supports AS/TGS exchanges for acquiring tickets,
pre-authentication, the AP exchange for performing client and server
authentication, and SAFE/PRIV for integrity/privacy protected
application data exchanges.

   Shishi is internationalized; error and status messages can be
translated into the users' language; user name and passwords can be
converted into any available character set (normally including
ISO-8859-1 and UTF-8) and also be processed using an experimental
Stringprep profile.

   Most, if not all, of the widely used encryption and checksum types
are supported, such as 3DES, AES, ARCFOUR and HMAC-SHA1.

   Shishi is developed for the GNU/Linux system, but runs on over 20
platforms including most major Unix platforms and Windows, and many
kind of devices including iPAQ handhelds and S/390 mainframes.

   Shishi is free software licensed under the GNU General Public License
version 3.0 or later.

* Menu:

* Getting Started::
* Features and Status::
* Overview::
* Cryptographic Overview::
* Supported Platforms::
* Getting help::
* Commercial Support::
* Downloading and Installing::
* Bug Reports::
* Contributing::


File: shishi.info,  Node: Getting Started,  Next: Features and Status,  Up: Introduction

1.1 Getting Started
===================

This manual documents the Shishi application and library programming
interface.  All commands, functions and data types provided by Shishi
are explained.

   The reader is assumed to possess basic familiarity with network
security and the Kerberos 5 security system.

   This manual can be used in several ways.  If read from the beginning
to the end, it gives a good introduction into the library and how it
can be used in an application.  Forward references are included where
necessary.  Later on, the manual can be used as a reference manual to
get just the information needed about any particular interface of the
library.  Experienced programmers might want to start looking at the
examples at the end of the manual, and then only read up on those parts
of the interface which are unclear.


File: shishi.info,  Node: Features and Status,  Next: Overview,  Prev: Getting Started,  Up: Introduction

1.2 Features and Status
=======================

Shishi might have a couple of advantages over other packages doing a
similar job.

It's Free Software
     Anybody can use, modify, and redistribute it under the terms of the
     GNU General Public License version 3.0 or later.

It's thread-safe
     The library uses no global variables.

It's internationalized
     It handles non-ASCII username and passwords, and user visible
     strings used in the library (error messages) can be translated
     into the users' language.

It's portable
     It should work on all Unix like operating systems, including
     Windows.


   Shishi is far from feature complete, it is not even a full RFC 1510
implementation yet.  However, some basic functionality is implemented.
A few implemented feature are mentioned below.

   * Initial authentication (AS) from raw key or password.  This step
     is typically used to acquire a ticket granting ticket and, less
     commonly, a server ticket.

   * Subsequent authentication (TGS).  This step is typically used to
     acquire a server ticket, by authenticating yourself using the
     ticket granting ticket.

   * Client-Server authentication (AP).  This step is used by clients
     and servers to prove to each other who they are, using negotiated
     tickets.

   * Integrity protected communication (SAFE).  This step is used by
     clients and servers to exchange integrity protected data with each
     other.  The key is typically agreed on using the Client-Server
     authentication step.

   * Ticket cache, supporting multiple principals and realms.  As
     tickets have a life time of typically several hours, they are
     managed in disk files.  There can be multiple ticket caches, and
     each ticket cache can store tickets for multiple clients (users),
     servers, encryption types, etc.  Functionality is provided for
     locating the proper ticket for every use.

   * Most standard cryptographic primitives.  The believed most secure
     algorithms are supported (*note Cryptographic Overview::).

   * Telnet client and server.  This is used to remotely login to other
     machines, after authenticating yourself with a ticket.

   * PAM module.  This is used to login locally on a machine.

   * KDC addresses located using DNS SRV RRs.

   * Modularized low-level crypto interface.  Currently Gnulib and
     Libgcrypt are supported.  If you wish to add support for another
     low-level cryptographic library, you only have to implement a few
     APIs for DES, AES, MD5, SHA1, HMAC, etc. Look at `gl/gc-gnulib.c'
     or `gl/gc-libgcrypt.c' as a starting pointer.


   The following table summarize what the current objectives are (i.e.,
the todo list) and an estimate on how long it will take to implement
the feature, including some reasonable startup-time to get familiar
with Shishi in general.  If you like to start working on anything,
please let me know so work duplication can be avoided.

   * Parse `/etc/krb5.keytab' to extract keys to use for telnetd etc
     (week)

   * Cross-realm support (week).

   * PKINIT (use libksba, weeks)

   * Finish GSSAPI support via GSSLib (weeks) Shishi will not support
     GSSLib natively, but a separate project "GSSLib" is under way to
     produce a generic GSS implementation, and it will use Shishi to
     implement the Kerberos 5 mechanism.

   * Port to cyclone (cyclone need to mature first)

   * Modularize ASN.1 library so it can be replaced (days).  Almost
     done, all ASN.1 functionality is found in lib/asn1.c, although the
     interface is rather libtasn1 centric.

   * KDC (initiated, weeks)

   * LDAP backend for Shisa.

   * Set/Change password protocol (weeks?)

   * Port applications to use Shishi (indefinite)

   * Finish server-realm stuff

   * Improve documentation

   * Improve internationalization

   * Add AP-REQ replay cache (week).

   * Study benefits by introducing a PA-TGS-REP.  This would provide
     mutual authentication of the KDC in a way that is easier to
     analyze.  Currently the mutual authentication property is only
     implicit from successful decryption of the KDC-REP and the 4 byte
     nonce.

   * GUI applet for managing tickets.  This is supported via the
     ticket-applet, of which a Shishi port is published on the Shishi
     home page.

   * Authorization library (months?)  The shishi_authorized_p() is not
     a good solution, better would be to have a generic and flexible
     authorization library.  Possibly based on S-EXP's in tickets?
     Should support non-Kerberos uses as well, of course.

   * Proof read manual.

   * X.500 support, including DOMAIN-X500-COMPRESS.  I will accept
     patches that implement this, if it causes minimal changes to the
     current code.



File: shishi.info,  Node: Overview,  Next: Cryptographic Overview,  Prev: Features and Status,  Up: Introduction

1.3 Overview
============

This section describes RFC 1510 from a protocol point of view(1).

   Kerberos provides a means of verifying the identities of principals,
(e.g., a workstation user or a network server) on an open (unprotected)
network.  This is accomplished without relying on authentication by the
host operating system, without basing trust on host addresses, without
requiring physical security of all the hosts on the network, and under
the assumption that packets traveling along the network can be read,
modified, and inserted at will. (Note, however, that many applications
use Kerberos' functions only upon the initiation of a stream-based
network connection, and assume the absence of any "hijackers" who might
subvert such a connection.  Such use implicitly trusts the host
addresses involved.)  Kerberos performs authentication under these
conditions as a trusted third- party authentication service by using
conventional cryptography, i.e., shared secret key.  (shared secret key
- Secret and private are often used interchangeably in the literature.
In our usage, it takes two (or more) to share a secret, thus a shared
DES key is a secret key.  Something is only private when no one but its
owner knows it.  Thus, in public key cryptosystems, one has a public
and a private key.)

   The authentication process proceeds as follows: A client sends a
request to the authentication server (AS) requesting "credentials" for
a given server.  The AS responds with these credentials, encrypted in
the client's key.  The credentials consist of 1) a "ticket" for the
server and 2) a temporary encryption key (often called a "session
key").  The client transmits the ticket (which contains the client's
identity and a copy of the session key, all encrypted in the server's
key) to the server.  The session key (now shared by the client and
server) is used to authenticate the client, and may optionally be used
to authenticate the server.  It may also be used to encrypt further
communication between the two parties or to exchange a separate
sub-session key to be used to encrypt further communication.

   The implementation consists of one or more authentication servers
running on physically secure hosts.  The authentication servers
maintain a database of principals (i.e., users and servers) and their
secret keys. Code libraries provide encryption and implement the
Kerberos protocol.  In order to add authentication to its transactions,
a typical network application adds one or two calls to the Kerberos
library, which results in the transmission of the necessary messages to
achieve authentication.

   The Kerberos protocol consists of several sub-protocols (or
exchanges).  There are two methods by which a client can ask a Kerberos
server for credentials.  In the first approach, the client sends a
cleartext request for a ticket for the desired server to the AS. The
reply is sent encrypted in the client's secret key. Usually this
request is for a ticket-granting ticket (TGT) which can later be used
with the ticket-granting server (TGS).  In the second method, the
client sends a request to the TGS.  The client sends the TGT to the TGS
in the same manner as if it were contacting any other application
server which requires Kerberos credentials.  The reply is encrypted in
the session key from the TGT.

   Once obtained, credentials may be used to verify the identity of the
principals in a transaction, to ensure the integrity of messages
exchanged between them, or to preserve privacy of the messages.  The
application is free to choose whatever protection may be necessary.

   To verify the identities of the principals in a transaction, the
client transmits the ticket to the server.  Since the ticket is sent
"in the clear" (parts of it are encrypted, but this encryption doesn't
thwart replay) and might be intercepted and reused by an attacker,
additional information is sent to prove that the message was originated
by the principal to whom the ticket was issued.  This information
(called the authenticator) is encrypted in the session key, and
includes a timestamp.  The timestamp proves that the message was
recently generated and is not a replay.  Encrypting the authenticator
in the session key proves that it was generated by a party possessing
the session key.  Since no one except the requesting principal and the
server know the session key (it is never sent over the network in the
clear) this guarantees the identity of the client.

   The integrity of the messages exchanged between principals can also
be guaranteed using the session key (passed in the ticket and contained
in the credentials).  This approach provides detection of both replay
attacks and message stream modification attacks.  It is accomplished by
generating and transmitting a collision-proof checksum (elsewhere
called a hash or digest function) of the client's message, keyed with
the session key.  Privacy and integrity of the messages exchanged
between principals can be secured by encrypting the data to be passed
using the session key passed in the ticket, and contained in the
credentials.

   ---------- Footnotes ----------

   (1) The text is a lightly adapted version of the introduction
section from RFC 1510 by J. Kohl and C. Neuman, September 1993,
copyright likely owned by the RFC 1510 authors or some contributor.


File: shishi.info,  Node: Cryptographic Overview,  Next: Supported Platforms,  Prev: Overview,  Up: Introduction

1.4 Cryptographic Overview
==========================

Shishi implements several of the standard cryptographic primitives.  In
this section we give the names of the supported encryption suites, and
some notes about them, and their associated checksum suite.

   Statements such as "it is weak" should be read as meaning that there
is no credible security analysis of the mechanism available, and/or
that should an attack be published publicly, few people would likely be
surprised.  Also keep in mind that the key size mentioned is the actual
key size, not the effective key space as far as a brute force attack is
concerned.

   As you may infer from the descriptions, there is currently no
encryption algorithm and only one checksum algorithm that inspire great
confidence in its design.  Hopefully this will change over time.

`NULL'
     `NULL' is a dummy encryption suite for debugging.  Encryption and
     decryption are identity functions.  No integrity protection.  It is
     weak.  It is associated with the `NULL' checksum.

`arcfour-hmac'
`arcfour-hmac-exp'
     `arcfour-hmac-*' are a proprietary stream cipher with 56 bit
     (`arcfour-hmac-exp') or 128 bit (`arcfour-hmac') keys, used in a
     proprietary way described in an expired IETF draft
     `draft-brezak-win2k-krb-rc4-hmac-04.txt'.  Deriving keys from
     passwords is supported, and is done by computing a message digest
     (MD4) of a 16-bit Unicode representation of the ASCII password,
     with no salt.  Data is integrity protected with a keyed hash
     (HMAC-MD5), where the key is derived from the base key in a
     creative way.  It is weak.  It is associated with the
     `arcfour-hmac-md5' checksum.

`des-cbc-none'
     `des-cbc-none' is DES encryption and decryption with 56 bit keys
     and 8 byte blocks in CBC mode, using a zero IV.  The keys can be
     derived from passwords by an obscure application specific
     algorithm.  It is weak, because it offers no integrity protection.
     This is typically only used by RFC 1964 GSS-API implementations
     (which try to protect integrity using an ad-hoc solution).  It is
     associated with the `NULL' checksum.

`des-cbc-crc'
     `des-cbc-crc' is DES encryption and decryption with 56 bit keys
     and 8 byte blocks in CBC mode, using the key as IV (*note Key as
     initialization vector::).  The keys can be derived from passwords
     by an obscure application specific algorithm.  Data is integrity
     protected with an unkeyed but encrypted `CRC32'-like checksum.  It
     is weak. It is associated with the `rsa-md5-des' checksum.

`des-cbc-md4'
     `des-cbc-md4' is DES encryption and decryption with 56 bit keys
     and 8 byte blocks in CBC mode, using a zero IV.  The keys can be
     derived from passwords by an obscure application specific
     algorithm.  Data is integrity protected with an unkeyed but
     encrypted MD4 hash.  It is weak. It is associated with the
     `rsa-md4-des' checksum.

`des-cbc-md5'
     `des-cbc-md5' is DES encryption and decryption with 56 bit keys
     and 8 byte blocks in CBC mode, using a zero IV.  The keys can be
     derived from passwords by an obscure application specific
     algorithm.  Data is integrity protected with an unkeyed but
     encrypted MD5 hash.  It is weak.  It is associated with the
     `rsa-md5-des' checksum.  This is the strongest RFC 1510
     interoperable encryption mechanism.

`des3-cbc-none'
     `des3-cbc-none' is DES encryption and decryption with three 56 bit
     keys (effective key size 112 bits) and 8 byte blocks in CBC mode.
     The keys can be derived from passwords by the same algorithm as
     `des3-cbc-sha1-kd'.  It is weak, because it offers no integrity
     protection.  This is typically only used by GSS-API implementations
     (which try to protect integrity using an ad-hoc solution) for
     interoperability with some existing Kerberos GSS implementations.
     It is associated with the `NULL' checksum.

`des3-cbc-sha1-kd'
     `des3-cbc-sha1-kd' is DES encryption and decryption with three 56
     bit keys (effective key size 112 bits) and 8 byte blocks in CBC
     mode.  The keys can be derived from passwords by a algorithm based
     on the paper "A Better Key Schedule For DES-like Ciphers" (1) by
     Uri Blumenthal and Steven M. Bellovin (it is not clear if the
     algorithm, and the way it is used, is used by any other protocols,
     although it seems unlikely).  Data is integrity protected with a
     keyed SHA1 hash in HMAC mode.  It has no security proof, but is
     assumed to provide adequate security in the sense that knowledge
     on how to crack it is not known to the public.  Note that the key
     derivation function is not widely used outside of Kerberos, hence
     not widely studied.  It is associated with the `hmac-sha1-des3-kd'
     checksum.

`aes128-cts-hmac-sha1-96'
`aes256-cts-hmac-sha1-96'
     `aes128-cts-hmac-sha1-96' and `aes256-cts-hmac-sha1-96' is AES
     encryption and decryption with 128 bit and 256 bit key,
     respectively, and 16 byte blocks in CBC mode with Cipher Text
     Stealing.  Cipher Text Stealing means data length of encrypted
     data is preserved (pure CBC add up to 7 pad characters).  The keys
     can be derived from passwords with RSA Laboratories PKCS#5
     Password Based Key Derivation Function 2(2), which is allegedly
     provably secure in a random oracle model.  Data is integrity
     protected with a keyed SHA1 hash, in HMAC mode, truncated to 96
     bits.  There is no security proof, but the schemes are assumed to
     provide adequate security in the sense that knowledge on how to
     crack them is not known to the public.  Note that AES has yet to
     receive the test of time, and the AES cipher encryption mode (CBC
     with Ciphertext Stealing, and a non-standard IV output) is not
     widely standardized (hence not widely studied).  It is associated
     with the `hmac-sha1-96-aes128' and `hmac-sha1-96-aes256' checksums,
     respectively.


   The protocol do not include any way to negotiate which checksum
mechanisms to use, so in most cases the associated checksum will be
used.  However, checksum mechanisms can be used with other encryption
mechanisms, as long as they are compatible in terms of key format etc.
Here are the names of the supported checksum mechanisms, with some
notes on their status and the compatible encryption mechanisms.  They
are ordered by increased security as perceived by the author.

`NULL'
     `NULL' is a dummy checksum suite for debugging.  It provides no
     integrity.  It is weak.  It is compatible with the `NULL'
     encryption mechanism.

`arcfour-hmac-md5'
     `arcfour-hmac-md5' is a keyed HMAC-MD5 checksum computed on a MD5
     message digest, in turn computed on a four byte message type
     indicator concatenated with the application data.  (The `arcfour'
     designation is thus somewhat misleading, but since this checksum
     mechanism is described in the same document as the `arcfour'
     encryption mechanisms, it is not a completely unnatural
     designation.)  It is weak.  It is compatible with all encryption
     mechanisms.

`rsa-md4'
     `rsa-md4' is a unkeyed MD4 hash computed over the message.  It is
     weak, because it is unkeyed.  However applications can, with care,
     use it non-weak ways (e.g., by including the hash in other
     messages that are protected by other means).  It is compatible
     with all encryption mechanisms.

`rsa-md4-des'
     `rsa-md4-des' is a DES CBC encryption of one block of random data
     and a unkeyed MD4 hash computed over the random data and the
     message to integrity protect.  The key used is derived from the
     base protocol key by XOR with a constant.  It is weak. It is
     compatible with the `des-cbc-crc', `des-cbc-md4', `des-cbc-md5'
     encryption mechanisms.

`rsa-md5'
     `rsa-md5' is a unkeyed MD5 hash computed over the message.  It is
     weak, because it is unkeyed.  However applications can, with care,
     use it non-weak ways (e.g., by including the hash in other
     messages that are protected by other means).  It is compatible
     with all encryption mechanisms.

`rsa-md5-des'
     `rsa-md5-des' is a DES CBC encryption of one block of random data
     and a unkeyed MD5 hash computed over the random data and the
     message to integrity protect.  The key used is derived from the
     base protocol key by XOR with a constant.  It is weak.  It is
     compatible with the `des-cbc-crc', `des-cbc-md4', `des-cbc-md5'
     encryption mechanisms.

`hmac-sha1-des3-kd'
     `hmac-sha1-des3-kd' is a keyed SHA1 hash in HMAC mode computed
     over the message.  The key is derived from the base protocol by the
     simplified key derivation function (similar to the password key
     derivation functions of `des3-cbc-sha1-kd', which does not appear
     to be widely used outside Kerberos and hence not widely studied).
     It has no security proof, but is assumed to provide good security.
     The weakest part is likely the proprietary key derivation
     function.  It is compatible with the `des3-cbc-sha1-kd' encryption
     mechanism.

`hmac-sha1-96-aes128'
`hmac-sha1-96-aes256'
     `hmac-sha1-96-aes*' are keyed SHA1 hashes in HMAC mode computed
     over the message and then truncated to 96 bits.  The key is derived
     from the base protocol by the simplified key derivation function
     (similar to the password key derivation functions of
     `aes*-cts-hmac-sha1-96', i.e., PKCS#5).  It has no security proof,
     but is assumed to provide good security.  It is compatible with
     the `aes*-cts-hmac-sha1-96' encryption mechanisms.


   Several of the cipher suites have long names that can be hard to
memorize.  For your convenience, the following short-hand aliases
exists.  They can be used wherever the full encryption names are used.

`arcfour'
     Alias for `arcfour-hmac'.

`des-crc'
     Alias for `des-cbc-crc'.

`des-md4'
     Alias for `des-cbc-md4'.

`des-md5'
`des'
     Alias for `des-cbc-md5'.

`des3'
`3des'
     Alias for `des3-cbc-sha1-kd'.

`aes128'
     Alias for `aes128-cts-hmac-sha1-96'.

`aes'
`aes256'
     Alias for `aes256-cts-hmac-sha1-96'.


   ---------- Footnotes ----------

   (1) `http://www.research.att.com/~smb/papers/ides.pdf'

   (2) `http://www.rsasecurity.com/rsalabs/pkcs/pkcs-5/'


File: shishi.info,  Node: Supported Platforms,  Next: Getting help,  Prev: Cryptographic Overview,  Up: Introduction

1.5 Supported Platforms
=======================

Shishi has at some point in time been tested on the following
platforms.  Online build reports for each platforms and Shishi version
is available at `http://autobuild.josefsson.org/shishi/'.

  1. Debian GNU/Linux 3.0 (Woody) 

     GCC 2.95.4 and GNU Make. This is the main development platform.
     `alphaev67-unknown-linux-gnu', `alphaev6-unknown-linux-gnu',
     `arm-unknown-linux-gnu', `armv4l-unknown-linux-gnu',
     `hppa-unknown-linux-gnu', `hppa64-unknown-linux-gnu',
     `i686-pc-linux-gnu', `ia64-unknown-linux-gnu',
     `m68k-unknown-linux-gnu', `mips-unknown-linux-gnu',
     `mipsel-unknown-linux-gnu', `powerpc-unknown-linux-gnu',
     `s390-ibm-linux-gnu', `sparc-unknown-linux-gnu',
     `sparc64-unknown-linux-gnu'.

  2. Debian GNU/Linux 2.1 

     GCC 2.95.4 and GNU Make. `armv4l-unknown-linux-gnu'.

  3. Tru64 UNIX 

     Tru64 UNIX C compiler and Tru64 Make. `alphaev67-dec-osf5.1',
     `alphaev68-dec-osf5.1'.

  4. SuSE Linux 7.1 

     GCC 2.96 and GNU Make. `alphaev6-unknown-linux-gnu',
     `alphaev67-unknown-linux-gnu'.

  5. SuSE Linux 7.2a 

     GCC 3.0 and GNU Make. `ia64-unknown-linux-gnu'.

  6. SuSE Linux 

     GCC 3.2.2 and GNU Make.  `x86_64-unknown-linux-gnu' (AMD64 Opteron
     "Melody").

  7. RedHat Linux 7.2 

     GCC 2.96 and GNU Make. `alphaev6-unknown-linux-gnu',
     `alphaev67-unknown-linux-gnu', `ia64-unknown-linux-gnu'.

  8. RedHat Linux 8.0 

     GCC 3.2 and GNU Make. `i686-pc-linux-gnu'.

  9. RedHat Advanced Server 2.1 

     GCC 2.96 and GNU Make. `i686-pc-linux-gnu'.

 10. Slackware Linux 8.0.01 

     GCC 2.95.3 and GNU Make. `i686-pc-linux-gnu'.

 11. Mandrake Linux 9.0 

     GCC 3.2 and GNU Make. `i686-pc-linux-gnu'.

 12. IRIX 6.5 

     MIPS C compiler, IRIX Make. `mips-sgi-irix6.5'.

 13. AIX 4.3.2 

     IBM C for AIX compiler, AIX Make.  `rs6000-ibm-aix4.3.2.0'.

 14. HP-UX 11 

     HP-UX C compiler and HP Make. `ia64-hp-hpux11.22',
     `hppa2.0w-hp-hpux11.11'.

 15. SUN Solaris 2.8 

     Sun WorkShop Compiler C 6.0 and SUN Make. `sparc-sun-solaris2.8'.

 16. NetBSD 1.6 

     GCC 2.95.3 and GNU Make. `alpha-unknown-netbsd1.6',
     `i386-unknown-netbsdelf1.6'.

 17. OpenBSD 3.1 and 3.2 

     GCC 2.95.3 and GNU Make. `alpha-unknown-openbsd3.1',
     `i386-unknown-openbsd3.1'.

 18. FreeBSD 4.7 and 4.8 

     GCC 2.95.4 and GNU Make. `alpha-unknown-freebsd4.7',
     `alpha-unknown-freebsd4.8', `i386-unknown-freebsd4.7',
     `i386-unknown-freebsd4.8'.

 19. MacOS X 10.2 Server Edition 

     GCC 3.1 and GNU Make. `powerpc-apple-darwin6.5'.

 20. Cross compiled to uClinux/uClibc on Motorola Coldfire.  

     GCC 3.4 and GNU Make `m68k-uclinux-elf'.


   If you use Shishi on, or port Shishi to, a new platform please report
it to the author (*note Bug Reports::).


File: shishi.info,  Node: Getting help,  Next: Commercial Support,  Prev: Supported Platforms,  Up: Introduction

1.6 Getting help
================

A mailing list where users of Shishi may help each other exists, and
you can reach it by sending e-mail to <help-shishi@gnu.org>.  Archives
of the mailing list discussions, and an interface to manage
subscriptions, is available through the World Wide Web at
`http://lists.gnu.org/mailman/listinfo/help-shishi'.


File: shishi.info,  Node: Commercial Support,  Next: Downloading and Installing,  Prev: Getting help,  Up: Introduction

1.7 Commercial Support
======================

Commercial support is available for users of Shishi.  The kind of
support that can be purchased may include:

   * Implement new features.  Such as support for some optional part of
     the Kerberos standards, e.g. PKINIT, hardware token authentication.

   * Port Shishi to new platforms.  This could include porting Shishi
     to an embedded platforms that may need memory or size optimization.

   * Integrate Kerberos 5 support in your existing project.

   * System design of components related to Kerberos 5.


   If you are interested, please write to:


Simon Josefsson Datakonsult
Hagagatan 24
113 47 Stockholm
Sweden

E-mail: simon@josefsson.org

   If your company provides support related to Shishi and would like to
be mentioned here, contact the author (*note Bug Reports::).


File: shishi.info,  Node: Downloading and Installing,  Next: Bug Reports,  Prev: Commercial Support,  Up: Introduction

1.8 Downloading and Installing
==============================

The package can be downloaded from several places, including:

   `ftp://alpha.gnu.org/pub/gnu/shishi/'

   The latest version is stored in a file, e.g., `shishi-1.0.2.tar.gz'
where the `1.0.2' indicate the highest version number.

   The package is then extracted, configured and built like many other
packages that use Autoconf.  For detailed information on configuring
and building it, refer to the `INSTALL' file that is part of the
distribution archive.

   Here is an example terminal session that download, configure, build
and install the package.  You will need a few basic tools, such as
`sh', `make' and `cc'.

     $ wget -q ftp://alpha.gnu.org/pub/gnu/shishi/shishi-1.0.2.tar.gz
     $ tar xfz shishi-1.0.2.tar.gz
     $ cd shishi-1.0.2/
     $ ./configure
     ...
     $ make
     ...
     $ make install
     ...

   After this you should be prepared to continue with the user,
administration or programming manual, depending on how you want to use
Shishi.

   A few `configure' options may be relevant, summarized in the table.

`--disable-des'
`--disable-3des'
`--disable-aes'
`--disable-md'
`--disable-null'
`--disable-arcfour'
     Disable a cryptographic algorithm at compile time.  Usually it is
     better to disable algorithms during run-time with the configuration
     file, but this allows you to reduce the code size slightly.

`--disable-starttls'
     Disable the experimental TLS support for KDC connections.  If you
     do not use a Shishi KDC, this support is of no use so you could
     safely disable it.

`--without-stringprep'
     Disable internationalized string processing.


   For the complete list, refer to the output from `configure --help'.


File: shishi.info,  Node: Bug Reports,  Next: Contributing,  Prev: Downloading and Installing,  Up: Introduction

1.9 Bug Reports
===============

If you think you have found a bug in Shishi, please investigate it and
report it.

   * Please make sure that the bug is really in Shishi, and preferably
     also check that it hasn't already been fixed in the latest version.

   * You have to send us a test case that makes it possible for us to
     reproduce the bug.

   * You also have to explain what is wrong; if you get a crash, or if
     the results printed are not good and in that case, in what way.
     Make sure that the bug report includes all information you would
     need to fix this kind of bug for someone else.


   Please make an effort to produce a self-contained report, with
something definite that can be tested or debugged.  Vague queries or
piecemeal messages are difficult to act on and don't help the
development effort.

   If your bug report is good, we will do our best to help you to get a
corrected version of the software; if the bug report is poor, we won't
do anything about it (apart from asking you to send better bug reports).

   If you think something in this manual is unclear, or downright
incorrect, or if the language needs to be improved, please also send a
note.

   Send your bug report to:

                      `bug-shishi@josefsson.org'


File: shishi.info,  Node: Contributing,  Prev: Bug Reports,  Up: Introduction

1.10 Contributing
=================

If you want to submit a patch for inclusion - from solve a typo you
discovered, up to adding support for a new feature - you should submit
it as a bug report (*note Bug Reports::).  There are some things that
you can do to increase the chances for it to be included in the
official package.

   Unless your patch is very small (say, under 10 lines) we require that
you assign the copyright of your work to the Free Software Foundation.
This is to protect the freedom of the project.  If you have not already
signed papers, we will send you the necessary information when you
submit your contribution.

   For contributions that doesn't consist of actual programming code,
the only guidelines are common sense.  Use it.

   For code contributions, a number of style guides will help you:

   * Coding Style.  Follow the GNU Standards document (*note GNU Coding
     Standards: (standards)top.).

     If you normally code using another coding standard, there is no
     problem, but you should use `indent' to reformat the code (*note
     GNU Indent: (indent)top.) before submitting your work.

   * Use the unified diff format `diff -u'.

   * Return errors.  The only valid reason for ever aborting the
     execution of the program is due to memory allocation errors, but
     for that you should call `shishi_xalloc_die' to allow the
     application to recover if it wants to.

   * Design with thread safety in mind.  Don't use global variables.
     Don't even write to per-handle global variables unless the
     documented behaviour of the function you write is to write to the
     per-handle global variable.

   * Avoid using the C math library.  It causes problems for embedded
     implementations, and in most situations it is very easy to avoid
     using it.

   * Document your functions.  Use comments before each function
     headers, that, if properly formatted, are extracted into Texinfo
     manuals and GTK-DOC web pages.

   * Supply a ChangeLog and NEWS entries, where appropriate.



File: shishi.info,  Node: User Manual,  Next: Administration Manual,  Prev: Introduction,  Up: Top

2 User Manual
*************

Usually Shishi interacts with you to get some initial authentication
information like a password, and then contacts a server to receive a so
called ticket granting ticket.  From now on, you rarely interact with
Shishi directly.  Applications that need security services instruct the
Shishi library to use the ticket granting ticket to get new tickets for
various servers.  An example could be if you log on to a host remotely
via `telnet'.  The host usually requires authentication before
permitting you in.  The `telnet' client uses the ticket granting ticket
to get a ticket for the server, and then uses this ticket to
authenticate you against the server (typically the server is also
authenticated to you).  You perform the initial authentication by
typing `shishi' at the prompt.  Sometimes it is necessary to supply
options telling Shishi what your principal name (user name in the
Kerberos realm) or your realm is.  In the example, I specify the client
name `simon@JOSEFSSON.ORG'.

     $ shishi simon@JOSEFSSON.ORG
     Enter password for `simon@JOSEFSSON.ORG':
     simon@JOSEFSSON.ORG:
     Authtime:       Fri Aug 15 04:44:49 2003
     Endtime:        Fri Aug 15 05:01:29 2003
     Server:         krbtgt/JOSEFSSON.ORG key des3-cbc-sha1-kd (16)
     Ticket key:     des3-cbc-sha1-kd (16) protected by des3-cbc-sha1-kd (16)
     Ticket flags:   INITIAL (512)
     $

   As you can see, Shishi also prints a short description of the ticket
received.

   A logical next step is to display all tickets you have received.  By
the way, the tickets are usually stored as text in `~/.shishi/tickets'.
This is achieved by typing `shishi --list'.

     $ shishi --list
     Tickets in `/home/jas/.shishi/tickets':

     jas@JOSEFSSON.ORG:
     Authtime:       Fri Aug 15 04:49:46 2003
     Endtime:        Fri Aug 15 05:06:26 2003
     Server:         krbtgt/JOSEFSSON.ORG key des-cbc-md5 (3)
     Ticket key:     des-cbc-md5 (3) protected by des-cbc-md5 (3)
     Ticket flags:   INITIAL (512)

     jas@JOSEFSSON.ORG:
     Authtime:       Fri Aug 15 04:49:46 2003
     Starttime:      Fri Aug 15 04:49:49 2003
     Endtime:        Fri Aug 15 05:06:26 2003
     Server:         host/latte.josefsson.org key des-cbc-md5 (3)
     Ticket key:     des-cbc-md5 (3) protected by des-cbc-md5 (3)

     2 tickets found.
     $

   As you can see, I had a ticket for the server
`host/latte.josefsson.org' which was generated by `telnet':ing to that
host.

   If, for some reason, you want to manually get a ticket for a specific
server, you can use the `shishi --server-name' command.  Normally,
however, the application that uses Shishi will take care of getting a
ticket for the appropriate server, so you normally wouldn't need to
issue this command.

     $ shishi --server-name=user/billg --encryption-type=des-cbc-md4
     jas@JOSEFSSON.ORG:
     Authtime:       Fri Aug 15 04:49:46 2003
     Starttime:      Fri Aug 15 04:54:33 2003
     Endtime:        Fri Aug 15 05:06:26 2003
     Server:         user/billg key des-cbc-md4 (2)
     Ticket key:     des-cbc-md4 (2) protected by des-cbc-md5 (3)
     $

   As you can see, I acquired a ticket for `user/billg' with a
`des-cbc-md4' (*note Cryptographic Overview::) encryption key specified
with the `--encryption-type' parameter.

   To wrap up this introduction, let us see how you can remove tickets.
You may want to do this if you leave your terminal for lunch or
similar, and don't want someone to be able to copy the file and then
use your credentials.  Note that this only destroys the tickets
locally, it does not contact any server telling that these credentials
are no longer valid.  So, if someone stole your ticket file, you must
still contact your administrator and have them reset your account.
Simply using this switch is not sufficient.

     $ shishi --server-name=imap/latte.josefsson.org --destroy
     1 ticket removed.
     $ shishi --server-name=foobar --destroy
     No tickets removed.
     $ shishi --destroy
     3 tickets removed.
     $

   Since the `--server-name' parameter takes a long string to type, it
is possible to type the server name directly, after the client name.
The following example demonstrates an AS-REQ followed by a TGS-REQ for a
specific server (assuming you did not have any tickets to begin with).

     $ src/shishi simon@latte.josefsson.org imap/latte.josefsson.org
     Enter password for `simon@latte.josefsson.org':
     simon@latte.josefsson.org:
     Acquired:       Wed Aug 27 17:21:06 2003
     Expires:        Wed Aug 27 17:37:46 2003
     Server:         imap/latte.josefsson.org key aes256-cts-hmac-sha1-96 (18)
     Ticket key:     aes256-cts-hmac-sha1-96 (18) protected by aes256-cts-hmac-sha1-96 (18)
     Ticket flags:   FORWARDED PROXIABLE (12)
     $

   Refer to the reference manual for all available parameters (*note
Parameters for shishi::).  The rest of this section contains
descriptions of more specialized usage modes that can be ignored by
most users.

2.1 Proxiable and Proxy Tickets
===============================

At times it may be necessary for a principal to allow a service to
perform an operation on its behalf. The service must be able to take on
the identity of the client, but only for a particular purpose. A
principal can allow a service to take on the principal's identity for a
particular purpose by granting it a proxy.

   The process of granting a proxy using the proxy and proxiable flags
is used to provide credentials for use with specific services. Though
conceptually also a proxy, users wishing to delegate their identity in
a form usable for all purpose MUST use the ticket forwarding mechanism
described in the next section to forward a ticket-granting ticket.

   The PROXIABLE flag in a ticket is normally only interpreted by the
ticket-granting service. It can be ignored by application servers.
When set, this flag tells the ticket-granting server that it is OK to
issue a new ticket (but not a ticket-granting ticket) with a different
network address based on this ticket. This flag is set if requested by
the client on initial authentication. By default, the client will
request that it be set when requesting a ticket-granting ticket, and
reset when requesting any other ticket.

   This flag allows a client to pass a proxy to a server to perform a
remote request on its behalf (e.g. a print service client can give the
print server a proxy to access the client's files on a particular file
server in order to satisfy a print request).

   In order to complicate the use of stolen credentials, Kerberos
tickets are usually valid from only those network addresses specifically
included in the ticket[4]. When granting a proxy, the client MUST
specify the new network address from which the proxy is to be used, or
indicate that the proxy is to be issued for use from any address.

   The PROXY flag is set in a ticket by the TGS when it issues a proxy
ticket.  Application servers MAY check this flag and at their option
they MAY require additional authentication from the agent presenting
the proxy in order to provide an audit trail.

   Here is how you would acquire a PROXY ticket for the service
`imap/latte.josefsson.org':

     $ shishi jas@JOSEFSSON.ORG imap/latte.josefsson.org --proxy
     Enter password for `jas@JOSEFSSON.ORG':
     libshishi: warning: KDC bug: Reply encrypted using wrong key.
     jas@JOSEFSSON.ORG:
     Authtime:       Mon Sep  8 20:02:35 2003
     Starttime:      Mon Sep  8 20:02:36 2003
     Endtime:        Tue Sep  9 04:02:35 2003
     Server:         imap/latte.josefsson.org key des3-cbc-sha1-kd (16)
     Ticket key:     des3-cbc-sha1-kd (16) protected by des3-cbc-sha1-kd (16)
     Ticket flags:   PROXY (16)
     $

   As you noticed, this asked for your password.  The reason is that
proxy tickets must be acquired using a proxiable ticket granting
ticket, which was not present.  If you often need to get proxy tickets,
you may acquire a proxiable ticket granting ticket from the start:

     $ shishi --proxiable
     Enter password for `jas@JOSEFSSON.ORG':
     jas@JOSEFSSON.ORG:
     Authtime:       Mon Sep  8 20:04:27 2003
     Endtime:        Tue Sep  9 04:04:27 2003
     Server:         krbtgt/JOSEFSSON.ORG key des3-cbc-sha1-kd (16)
     Ticket key:     des3-cbc-sha1-kd (16) protected by des3-cbc-sha1-kd (16)
     Ticket flags:   PROXIABLE INITIAL (520)

   Then you should be able to acquire proxy tickets based on that ticket
granting ticket, as follows:

     $ shishi jas@JOSEFSSON.ORG imap/latte.josefsson.org --proxy
     libshishi: warning: KDC bug: Reply encrypted using wrong key.
     jas@JOSEFSSON.ORG:
     Authtime:       Mon Sep  8 20:04:27 2003
     Starttime:      Mon Sep  8 20:04:32 2003
     Endtime:        Tue Sep  9 04:04:27 2003
     Server:         imap/latte.josefsson.org key des3-cbc-sha1-kd (16)
     Ticket key:     des3-cbc-sha1-kd (16) protected by des3-cbc-sha1-kd (16)
     Ticket flags:   PROXY (16)
     $

2.2 Forwardable and Forwarded Tickets
=====================================

Authentication forwarding is an instance of a proxy where the service
that is granted is complete use of the client's identity. An example
where it might be used is when a user logs in to a remote system and
wants authentication to work from that system as if the login were
local.

   The FORWARDABLE flag in a ticket is normally only interpreted by the
ticket-granting service. It can be ignored by application servers.  The
FORWARDABLE flag has an interpretation similar to that of the PROXIABLE
flag, except ticket-granting tickets may also be issued with different
network addresses. This flag is reset by default, but users MAY request
that it be set by setting the FORWARDABLE option in the AS request when
they request their initial ticket-granting ticket.

   This flag allows for authentication forwarding without requiring the
user to enter a password again. If the flag is not set, then
authentication forwarding is not permitted, but the same result can
still be achieved if the user engages in the AS exchange specifying the
requested network addresses and supplies a password.

   The FORWARDED flag is set by the TGS when a client presents a ticket
with the FORWARDABLE flag set and requests a forwarded ticket by
specifying the FORWARDED KDC option and supplying a set of addresses
for the new ticket. It is also set in all tickets issued based on
tickets with the FORWARDED flag set. Application servers may choose to
process FORWARDED tickets differently than non-FORWARDED tickets.

   If addressless tickets are forwarded from one system to another,
clients SHOULD still use this option to obtain a new TGT in order to
have different session keys on the different systems.

   Here is how you would acquire a FORWARDED ticket for the service
`host/latte.josefsson.org':

     $ shishi jas@JOSEFSSON.ORG host/latte.josefsson.org --forwarded
     Enter password for `jas@JOSEFSSON.ORG':
     libshishi: warning: KDC bug: Reply encrypted using wrong key.
     jas@JOSEFSSON.ORG:
     Authtime:       Mon Sep  8 20:07:11 2003
     Starttime:      Mon Sep  8 20:07:12 2003
     Endtime:        Tue Sep  9 04:07:11 2003
     Server:         host/latte.josefsson.org key des3-cbc-sha1-kd (16)
     Ticket key:     des3-cbc-sha1-kd (16) protected by des3-cbc-sha1-kd (16)
     Ticket flags:   FORWARDED (4)
     $

   As you noticed, this asked for your password.  The reason is that
forwarded tickets must be acquired using a forwardable ticket granting
ticket, which was not present.  If you often need to get forwarded
tickets, you may acquire a forwardable ticket granting ticket from the
start:

     $ shishi --forwardable
     Enter password for `jas@JOSEFSSON.ORG':
     jas@JOSEFSSON.ORG:
     Authtime:       Mon Sep  8 20:08:53 2003
     Endtime:        Tue Sep  9 04:08:53 2003
     Server:         krbtgt/JOSEFSSON.ORG key des3-cbc-sha1-kd (16)
     Ticket key:     des3-cbc-sha1-kd (16) protected by des3-cbc-sha1-kd (16)
     Ticket flags:   FORWARDABLE INITIAL (514)
     $

   Then you should be able to acquire forwarded tickets based on that
ticket granting ticket, as follows:

     $ shishi jas@JOSEFSSON.ORG host/latte.josefsson.org --forwarded
     libshishi: warning: KDC bug: Reply encrypted using wrong key.
     jas@JOSEFSSON.ORG:
     Authtime:       Mon Sep  8 20:08:53 2003
     Starttime:      Mon Sep  8 20:08:57 2003
     Endtime:        Tue Sep  9 04:08:53 2003
     Server:         host/latte.josefsson.org key des3-cbc-sha1-kd (16)
     Ticket key:     des3-cbc-sha1-kd (16) protected by des3-cbc-sha1-kd (16)
     Ticket flags:   FORWARDED (4)
     $


File: shishi.info,  Node: Administration Manual,  Next: Reference Manual,  Prev: User Manual,  Up: Top

3 Administration Manual
***********************

Here you will learn how to set up, run and maintain the Shishi Kerberos
server.  Kerberos is incompatible with the standard Unix `/etc/passwd'
password database(1), therefore the first step will be to create a
Kerberos user database.  Shishi's user database system is called Shisa.
Once Shisa has been configured, you can then start the server and
begin issuing Kerberos tickets to your users.  The Shishi server is
called `shishid'.  After getting the server up and running, we discuss
how you can set up multiple Kerberos servers, to increase availability
or offer load-balancing.  Finally, we include some information intended
for developers, that will enable you to customize Shisa to use an
external user database, such as a LDAP server or SQL database.

* Menu:

* Introduction to Shisa::       Explanation of the Shishi user database.
* Configuring Shisa::           Define the user database in Shisa.
* Using Shisa::                 How to add realms and principals to database.
* Starting Shishid::            Issue Kerberos tickets to your users.
* Configuring DNS for KDC::     Placing the KDC address in DNS is useful.
* Kerberos via TLS::            How to setup Shishi to use TLS.
* Multiple servers::            High availability and load-balancing.
* Developer information::       Writing your own Shisa database backend.

   ---------- Footnotes ----------

   (1) And besides, Shishi is intended to work on non-Unix platforms as
well.


File: shishi.info,  Node: Introduction to Shisa,  Next: Configuring Shisa,  Up: Administration Manual

3.1 Introduction to Shisa
=========================

The user database part of Shishi is called Shisa.  The Shisa library is
independent of the core Shishi library.  Shisa is responsible for
storing the name of your realms, the name of your principals (users),
accounting information for the users (i.e., when each account starts to
be valid and when it expires), and the cryptographic keys each user
has.  Some Kerberos internal data can also be stored, such as the key
version number, the last dates for when various ticket requests were
made, the cryptographic salt, string-to-key parameters and password for
each user.  Not all information need to be stored.  For example, in
some situations it is prudent to leave the password field empty, so
that somebody who manages to steal the user database will only be able
to compromise your system, and not any other systems were your user may
have re-used the same password.  On the other hand, you may already be
storing the password in your customized database, in which case being
able to change it via the Shisa interface can be useful.

   Shisa is a small (a few thousand lines of C code) standalone
library.  Shisa does not depend on the Shishi library.  Because a user
database with passwords may be useful for other applications as well
(e.g., GNU SASL), it might be separated into its own project later on.
You should keep this in mind, so that you don't consider writing a
Shisa backend for your own database as a purely Shishi specific
project.  You can, for example, choose to use the Shisa interface in
your own applications to have a simple interface to your user database.
Your experience and feedback is appreciated if you have chosen to
explore this.

   Note that the Shisa database does not expose everything you may want
to know about a user, such as its full human name, telephone number or
even the user's login account name or home directory.  It only stores
what is needed to authenticate a peer claiming to be an entity.  Thus
it does not make sense to replace your current user database or
`/etc/passwd' with data derived from the Shisa database.  Instead, it
is intended that you write a Shisa backend that exports some of the
information stored in your user database.  You may be able to replace
some existing functionality, such as the password field in
`/etc/passwd' with a Kerberos PAM module, but there is no requirement
for doing so.


File: shishi.info,  Node: Configuring Shisa,  Next: Using Shisa,  Prev: Introduction to Shisa,  Up: Administration Manual

3.2 Configuring Shisa
=====================

The configuration file for Shisa is typically stored in
`/usr/local/etc/shishi/shisa.conf'.  You do not have to modify this
file, the defaults should be acceptable to first-time users.  The file
is used to define where your user database resides, and some options
such as making the database read-only, or whether errors detected when
accessing the database should be ignored.  (The latter could be useful
if the server is a remote LDAP server that might be unavailable, and
then you would want to fall back to a local copy of the database.)

   The default will store the user database using directories and files,
rooted by default in `/usr/local/var/shishi'.  You can use standard
file permission settings to control access to the directory hierarchy.
It is strongly recommended to restrict access to the directory.
Storing the directory on local storage, i.e., hard disk or removable
media, is recommended.  We discourage placing the database on a network
file system, but realize this can be useful in some situations (*note
Multiple servers::).

   See the reference manual (*note Shisa Configuration::) for the
details of the configuration file.  Again, you are not expected to need
to modify anything unless you are an experienced Shishi administrator.


File: shishi.info,  Node: Using Shisa,  Next: Starting Shishid,  Prev: Configuring Shisa,  Up: Administration Manual

3.3 Using Shisa
===============

There is a command line interface to the Shisa library, aptly named
`shisa'.  You will use this tool to add, remove, and change information
stored in the database about realms, principals, and keys.  The tool
can also be used to "dump" all information in the database, for backup
or debugging purposes.  (Currently the output format cannot be read by
any tool, but functionality to do this will be added in the future,
possibly as a read-only file-based Shisa database backend.)

   The reference manual (*note Parameters for shisa::) explains all
parameters, but here we will give you a walk-through of the typical
uses of the tool.

   Installing Shishi usually creates a realm with two principals: one
ticket granting ticket for the realm, and one host key for the server.
This is what you typically need to get started, but it doesn't serve
our purposes, so we start by removing the principals and the realm.  To
do that, we need to figure out the name of the realm.  The `--list' or
`--dump' parameters can be used for this.  (Most "long" parameters,
like `--dump', have shorter names as well, in this case `-d', *Note
Parameters for shisa::).

     jas@latte:~$ shisa -d
     latte
             krbtgt/latte
                     Account is enabled.
                     Current key version 0 (0x0).
                     Key 0 (0x0).
                             Etype aes256-cts-hmac-sha1-96 (0x12, 18).
                             Salt lattekrbtgt/latte.
             host/latte
                     Account is enabled.
                     Current key version 0 (0x0).
                     Key 0 (0x0).
                             Etype aes256-cts-hmac-sha1-96 (0x12, 18).
                             Salt lattehost/latte.
     jas@latte:~$

   The realm names are printed at column 0, the principal names are
indented with one `TAB' character (aka `\t' or ASCII 0x09 Horizontal
Tabulation), and the information about each principal is indented with
two `TAB' characters.  The above output means that there is one realm
`latte' with two principals: `krbtgt/latte' (which is used to
authenticate Kerberos ticket requests) and `host/latte' (used to
authenticate host-based applications like Telnet).  They were created
during `make install' on a host called `latte'.

   If the installation did not create a default database for you, you
might get an error similar to the following output.

     jas@latte:~$ shisa -d
     shisa: Cannot initialize `file' database backend.
     Location `/usr/local/var/shishi' and options `N/A'.
     shisa: Initialization failed:
     Shisa database could not be opened.
     jas@latte:~$

   This indicates that the database does not exist.  For a file
database, you can create it simply by creating the directory, as
follows.  Note the access permission change with `chmod'.  Typically
the `root' user would own the files, but as these examples demonstrate,
setting up a Kerberos server does not require root access.  Indeed, it
may be prudent to run all Shishi applications as a special non-`root'
user, and have all Shishi related files owned by that user, so that any
security vulnerabilities do not lead to a system compromise.  (However,
if the user database is ever stolen, system compromises of other
systems may be inoccured, should you use, e.g., a kerberized Telnet.)

     jas@latte:~$ mkdir /usr/local/var/shishi
     jas@latte:~$ chmod go-rwx /usr/local/var/shishi

   Back to the first example, where you have a realm `latte' with some
principals.  We want to remove the realm to demonstrate how you create
the realm from scratch.  (Of course, you can have more than one realm
in the database, but for this example we assume you want to set up a
realm named the same as Shishi guessed you would name it, so the
existing realm need to be removed first.)  The `--remove' (short form
`-r') parameter is used for this purpose, as follows.

     jas@latte:~$ shisa -r latte host/latte
     Removing principal `host/latte@latte'...
     Removing principal `host/latte@latte'...done
     jas@latte:~$ shisa -r latte krbtgt/latte
     Removing principal `krbtgt/latte@latte'...
     Removing principal `krbtgt/latte@latte'...done
     jas@latte:~$ shisa -r latte
     Removing realm `latte'...
     Removing realm `latte'...done
     jas@latte:~$

   You may be asking yourself "What if the realm has many more
principals?".  If you fear manual labor (or a small `sed' script,
recall the format of `--list'?), don't worry, there is a `--force'
(short form `-f') flag.  Use it with care.  Here is a faster way to do
the above:

     jas@latte:~$ shisa -r latte -f
     Removing principal `krbtgt/latte@latte'...
     Removing principal `krbtgt/latte@latte'...done
     Removing principal `host/latte@latte'...
     Removing principal `host/latte@latte'...done
     Removing realm `latte'...
     Removing realm `latte'...done
     jas@latte:~$

   You should now have a working, but empty, Shisa database.  Let's set
up the realm manually, step by step.  The first step is to decide on a
name for your realm.  The full story is explained elsewhere (*note
Realm and Principal Naming::), but the short story is to take your DNS
domain name and translate it to upper case.  For example, if your
organization uses `example.org' it is a good idea to use `EXAMPLE.ORG'
as the name of your Kerberos realm.  We'll use `EXAMPLE.ORG' as the
realm name in these examples.  Let's create the realm.

     jas@latte:~$ shisa -a EXAMPLE.ORG
     Adding realm `EXAMPLE.ORG'...
     Adding realm `EXAMPLE.ORG'...done
     jas@latte:~$

   Currently, there are no properties associated with entire realms.  In
the future, it may be possible to set a default realm-wide password
expiry policy or similar.  Each realm normally has one principal that
is used for authenticating against the "ticket granting service" on the
Kerberos server with a ticket instead of using the password.  This is
used by the user when she acquire a ticket for a server.  The principal
must look like `krbtgt/REALM' (*note Name of the TGS: krbtgt.).  Let's
create it.

     jas@latte:~$ shisa -a EXAMPLE.ORG krbtgt/EXAMPLE.ORG
     Adding principal `krbtgt/EXAMPLE.ORG@EXAMPLE.ORG'...
     Adding principal `krbtgt/EXAMPLE.ORG@EXAMPLE.ORG'...done
     jas@latte:~$

   Now that wasn't difficult, although not very satisfying either.  What
does adding a principal mean?  The name is created, obviously, but it
also means setting a few values in the database.  Let's view the entry
to find out which values.

     jas@latte:~$ shisa -d
     EXAMPLE.ORG
             krbtgt/EXAMPLE.ORG
                     Account is enabled.
                     Current key version 0 (0x0).
                     Key 0 (0x0).
                             Etype aes256-cts-hmac-sha1-96 (0x12, 18).
                             Salt EXAMPLE.ORGkrbtgt/EXAMPLE.ORG.
     jas@latte:~$

   To use host based security services like SSH or Telnet with
Kerberos, each host must have a key shared between the host and the
KDC.  The key is typically stored in
`/usr/local/etc/shishi/shishi.keys'.  We assume your server is called
`mail.example.org' and we create the principal.  To illustrate a new
parameter, we also set the specific algorithm to use by using the
`--encryption-type' (short form `-E') parameter.

     jas@latte:~$ shisa -a EXAMPLE.ORG host/mail.example.org -E des3
     Adding principal `host/mail.example.org@EXAMPLE.ORG'...
     Adding principal `host/mail.example.org@EXAMPLE.ORG'...done
     jas@latte:~$

   To export the key, there is another Shisa parameter `--keys' that
will print the key in a format that is recognized by Shishi.  Let's use
it to print the host key.

     jas@latte:~$ shisa -d --keys EXAMPLE.ORG host/mail.example.org
     EXAMPLE.ORG
             host/mail.example.org
                     Account is enabled.
                     Current key version 0 (0x0).
                     Key 0 (0x0).
                             Etype des3-cbc-sha1-kd (0x10, 16).
     -----BEGIN SHISHI KEY-----
     Keytype: 16 (des3-cbc-sha1-kd)
     Principal: host/mail.example.org
     Realm: EXAMPLE.ORG

     iQdA8hxdvOUHZNliZJv7noM02rXHV8gq
     -----END SHISHI KEY-----
                             Salt EXAMPLE.ORGhost/mail.example.org.
     jas@latte:~$

   So to set up the host, simply redirect output to the host key file.

     jas@latte:~$ shisa -d --keys EXAMPLE.ORG \
          host/mail.example.org >> /usr/local/etc/shishi/shishi.keys
     jas@latte:~$

   The next logical step is to create a principal for some user, so you
can use your password to get a Ticket Granting Ticket via the
Authentication Service (AS) from the KDC, and then use the Ticket
Granting Service (TGS) from the KDC to get a ticket for a specific
host, and then send that ticket to the host to authenticate yourself.
Creating this end-user principle is slightly different from the earlier
steps, because you want the key to be derived from a password instead
of being a random key.  The `--password' parameter indicate this.  This
make the tool ask you for the password.

     jas@latte:~$ shisa -a EXAMPLE.ORG simon --password
     Password for `simon@EXAMPLE.ORG':
     Adding principal `simon@EXAMPLE.ORG'...
     Adding principal `simon@EXAMPLE.ORG'...done
     jas@latte:~$

   The only special thing about this principal now is that it has a
`password' field set in the database.

     jas@latte:~$ shisa -d EXAMPLE.ORG simon --keys
     EXAMPLE.ORG
             simon
                     Account is enabled.
                     Current key version 0 (0x0).
                     Key 0 (0x0).
                             Etype aes256-cts-hmac-sha1-96 (0x12, 18).
     -----BEGIN SHISHI KEY-----
     Keytype: 18 (aes256-cts-hmac-sha1-96)
     Principal: simon
     Realm: EXAMPLE.ORG

     Ja7ciNtrAI3gtodLaVDQ5zhcH58ffk0kS5tGAM7ILvM=
     -----END SHISHI KEY-----
                             Salt EXAMPLE.ORGsimon.
                             Password foo.
     jas@latte:~$

   You should now be ready to start the KDC, which is explained in the
next section (*note Starting Shishid::), and get tickets as explained
earlier (*note User Manual::).


File: shishi.info,  Node: Starting Shishid,  Next: Configuring DNS for KDC,  Prev: Using Shisa,  Up: Administration Manual

3.4 Starting Shishid
====================

The Shishi server, or Key Distribution Center (KDC), is called Shishid.
Shishid is responsible for listening on UDP and TCP ports for Kerberos
requests.  Currently it can handle initial ticket requests
(Authentication Service, or AS), typically authenticated with keys
derived from passwords, and subsequent ticket requests (Ticket Granting
Service, or TGS), typically authenticated with the key acquired during
an AS exchange.

   Currently there is very little configuration available, the only
variables are which ports the server should listen on and an optional
user name to `setuid' into after successfully listening to the ports.

   By default, Shishid listens on the `kerberos' service port
(typically translated to 88 via `/etc/services') on the UDP and TCP
transports via IPv4 and (if your machine support it) IPv6 on all
interfaces on your machine.  Here is a typical startup.

     latte:/home/jas/src/shishi# /usr/local/sbin/shishid
     Initializing GNUTLS...
     Initializing GNUTLS...done
     Listening on IPv4:*:kerberos/udp...done
     Listening on IPv4:*:kerberos/tcp...done
     Listening on IPv6:*:kerberos/udp...failed
     socket: Address family not supported by protocol
     Listening on IPv6:*:kerberos/tcp...failed
     socket: Address family not supported by protocol
     Listening on 2 ports...

   Running as root is not recommended.  Any security problem in shishid
and your host may be compromised.  Therefor, we recommend using the
`--setuid' parameter, as follows.

     latte:/home/jas/src/shishi# /usr/local/sbin/shishid --setuid=jas
     Initializing GNUTLS...
     Initializing GNUTLS...done
     Listening on IPv4:*:kerberos/udp...done
     Listening on IPv4:*:kerberos/tcp...done
     Listening on IPv6:*:kerberos/udp...failed
     socket: Address family not supported by protocol
     Listening on IPv6:*:kerberos/tcp...failed
     socket: Address family not supported by protocol
     Listening on 2 ports...
     User identity set to `jas' (22541)...

   An alternative is to run shishid on an alternative port as a
non-privileged user.  To continue the example of setting up the
`EXAMPLE.ORG' realm as a non-privileged user from the preceding
section, we start the server listen on port 4711 via UDP on IPv4.

     jas@latte:~$ /usr/local/sbin/shishid -l IPv4:*:4711/udp
     Initializing GNUTLS...
     Initializing GNUTLS...done
     Listening on *:4711/tcp...
     Listening on 1 ports...
     shishid: Starting (GNUTLS `1.0.4')
     shishid: Listening on *:4711/tcp socket 4

   If you have set up the Shisa database as in the previous example, you
can now acquire tickets as follows.

     jas@latte:~$ shishi -o 'realm-kdc=EXAMPLE.ORG,localhost:4711' \
        simon@EXAMPLE.ORG
     Enter password for `simon@EXAMPLE.ORG':
     simon@EXAMPLE.ORG:
     Authtime:       Fri Dec 12 01:41:01 2003
     Endtime:        Fri Dec 12 01:57:41 2003
     Server:         krbtgt/EXAMPLE.ORG key aes256-cts-hmac-sha1-96 (18)
     Ticket key:     aes256-cts-hmac-sha1-96 (18) protected by aes256-cts-hmac-sha1-96 (18)
     Ticket flags:   FORWARDED PROXIABLE RENEWABLE INITIAL (12)
     jas@latte:~$

   The output from Shishid on a successful invocation would look like:

     shishid: Has 131 bytes from *:4711/udp on socket 4
     shishid: Processing 131 from *:4711/udp on socket 4
     shishid: Trying AS-REQ
     shishid: AS-REQ from simon@EXAMPLE.ORG for krbtgt/EXAMPLE.ORG@EXAMPLE.ORG
     shishid: Matching client etype 18 against user key etype 18
     shishid: Have 511 bytes for *:4711/udp on socket 4
     shishid: Sending 511 bytes to *:4711/udp socket 4 via UDP
     shishid: Listening on *:4711/udp socket 4

   You may use the '-v' parameter for Shishid and Shishi to generate
more debugging information.

   To illustrate what an application, such as the Shishi patched
versions of GNU lsh or Telnet from GNU InetUtils, would do when
contacting the host `mail.example.org' we illustrate using the TGS
service as well.

     jas@latte:~$ shishi -o 'realm-kdc=EXAMPLE.ORG,localhost:4711' \
        simon@EXAMPLE.ORG host/mail.example.org
     simon@EXAMPLE.ORG:
     Authtime:       Fri Dec 12 01:46:54 2003
     Endtime:        Fri Dec 12 02:03:34 2003
     Server:         host/mail.example.org key des3-cbc-sha1-kd (16)
     Ticket key:     des3-cbc-sha1-kd (16) protected by aes256-cts-hmac-sha1-96 (18)
     Ticket flags:   FORWARDED PROXIABLE (45398796)
     jas@latte:~$

   This conclude our walk-through of setting up a new Kerberos realm
using Shishi.  It is quite likely that one or more steps failed, and if
so we encourage you to debug it and submit a patch, or at least report
it as a problem.  Heck, even letting us know if you got this far would
be of interest.  *Note Bug Reports::.


File: shishi.info,  Node: Configuring DNS for KDC,  Next: Kerberos via TLS,  Prev: Starting Shishid,  Up: Administration Manual

3.5 Configuring DNS for KDC
===========================

Making sure the configuration files on all hosts running Shishi clients
include the addresses of your server is tedious.  If the configuration
files do not mention the KDC address for a realm, Shishi will try to
look up the information from DNS.  In order for Shishi to find that
information, you need to add the information to DNS.  For this to work
well, you need to set up a DNS zone with the same name as your Kerberos
realm.  The easiest is if you own the publicly visible DNS name, such
as `example.org' if your realm is `EXAMPLE.ORG', but you can set up an
internal DNS server with the information for your realm only.  If this
is done, you do not need to keep configuration files updated for the
KDC addressing information.

3.5.1 DNS vs. Kerberos - Case Sensitivity of Realm Names
--------------------------------------------------------

In Kerberos, realm names are case sensitive.  While it is strongly
encouraged that all realm names be all upper case this recommendation
has not been adopted by all sites.  Some sites use all lower case names
and other use mixed case.  DNS on the other hand is case insensitive
for queries but is case preserving for responses to TXT queries.  Since
"MYREALM", "myrealm", and "MyRealm" are all different it is necessary
that only one of the possible combinations of upper and lower case
characters be used.  This restriction may be lifted in the future as
the DNS naming scheme is expanded to support non-ASCII names.

3.5.2 Overview - KDC location information
-----------------------------------------

KDC location information is to be stored using the DNS SRV RR [RFC
2052].  The format of this RR is as follows:

   Service.Proto.Realm TTL Class SRV Priority Weight Port Target

   The Service name for Kerberos is always "_kerberos".

   The Proto can be either "_udp", "_tcp", or "_tls._tcp".  If these SRV
records are to be used, a "_udp" record MUST be included.  If the
Kerberos implementation supports TCP transport, a "_tcp" record MUST be
included.  When using "_tcp" with "_kerberos", this indicates a "raw"
TCP connection without any additional encapsulation.  A "_tls._tcp"
record MUST be specified for all Kerberos implementations that support
communication with the KDC across TCP sockets encapsulated using TLS
[RFC2246] (*note STARTTLS protected KDC exchanges::).

   The Realm is the Kerberos realm that this record corresponds to.

   TTL, Class, SRV, Priority, Weight, and Target have the standard
meaning as defined in RFC 2052.

   As per RFC 2052 the Port number should be the value assigned to
"kerberos" by the Internet Assigned Number Authority (88).

3.5.3 Example - KDC location information
----------------------------------------

These are DNS records for a Kerberos realm ASDF.COM.  It has two
Kerberos servers, kdc1.asdf.com and kdc2.asdf.com.  Queries should be
directed to kdc1.asdf.com first as per the specified priority.  Weights
are not used in these records.

     _kerberos._udp.ASDF.COM.        IN      SRV     0 0 88 kdc1.asdf.com.
     _kerberos._udp.ASDF.COM.        IN      SRV     1 0 88 kdc2.asdf.com.
     _kerberos._tcp.ASDF.COM.        IN      SRV     0 0 88 kdc1.asdf.com.
     _kerberos._tcp.ASDF.COM.        IN      SRV     1 0 88 kdc2.asdf.com.
     _kerberos._tls._tcp.ASDF.COM.   IN      SRV     0 0 88 kdc1.asdf.com.
     _kerberos._tls._tcp.ASDF.COM.   IN      SRV     1 0 88 kdc2.asdf.com.

3.5.4 Security considerations
-----------------------------

As DNS is deployed today, it is an unsecure service.  Thus the infor-
mation returned by it cannot be trusted.

   Current practice for REALM to KDC mapping is to use hostnames to
indicate KDC hosts (stored in some implementation-dependent location,
but generally a local config file).  These hostnames are vulnerable to
the standard set of DNS attacks (denial of service, spoofed entries,
etc).  The design of the Kerberos protocol limits attacks of this sort
to denial of service.  However, the use of SRV records does not change
this attack in any way.  They have the same vulnerabilities that
already exist in the common practice of using hostnames for KDC
locations.

   Implementations SHOULD provide a way of specifying this information
locally without the use of DNS.  However, to make this feature
worthwhile a lack of any configuration information on a client should
be interpretted as permission to use DNS.


File: shishi.info,  Node: Kerberos via TLS,  Next: Multiple servers,  Prev: Configuring DNS for KDC,  Up: Administration Manual

3.6 Kerberos via TLS
====================

If Shishi is built with support for GNUTLS, the messages exchanged
between clients and Shishid can be protected with TLS.  TLS is only
available over TCP connections.  A full discussion of the features TLS
have is out of scope here, but in short it means the communication is
integrity and privacy protected, and that users can use OpenPGP, X.509
or SRP (i.e., any mechanism supported by TLS) to authenticate
themselves to the Kerberos server.  For details on the implementation,
*Note STARTTLS protected KDC exchanges::.

3.6.1 Setting up TLS resume
---------------------------

Resuming earlier TLS session is supported and enabled by default.  This
improves the speed of the TLS handshake, because results from earlier
negotiations can be re-used.  Currently the TLS resume database is
stored in memory (in constract to storing it on disk), in both the
client and in the server.  Because the server typically runs for a long
time, this is not a problem for that side.  The client is typically not
a long-running process though; the client usually is invoked as part of
applications like `telnet' or `login'.  However, because each use of
the client library typically result in a ticket, which is stored on
disk and re-used by later processes, this is likely not a serious
problem because the number of different tickets required by a user is
usually quite small.  For the client, TLS resume is typically only
useful when you perform an initial authentication (using a password)
followed by a ticket request for a service, in the same process.

   You can configure the server, `shishid' to never use TLS resume, or
to increase or decrease the number of distinct TLS connections that can
be resumed before they are garbage collected, see the `--resume-limit'
parameter (*note Parameters for shishid::).

3.6.2 Setting up Anonymous TLS
------------------------------

Anonymous TLS is the simplest to set up and use.  In fact, only the
client need to be informed that your KDC support TLS.  This can be done
in the configuration file with the `/tls' parameter for `kdc-realm'
(*note Shishi Configuration: realm-kdc.), or by placing the KDC address
in DNS using the `_tls' SRV record (*note Configuring DNS for KDC::).

   Let's start Shishid, listening on a TCP socket.  TLS require TCP.
TCP sockets are automatically upgraded to TLS if the client request it.

     jas@latte:~$ /usr/local/sbin/shishid -l IPv4:*:4711/tcp
     Initializing GNUTLS...done
     Listening on IPv4:*:4711/tcp...
     Listening on 1 ports...
     shishid: Starting (GNUTLS `1.0.4')
     shishid: Listening on IPv4:*:4711/tcp socket 4

   Let's use the client to talk with it, using TLS.

     jas@latte:~$ shishi -o 'realm-kdc=EXAMPLE.ORG,localhost:4711/tls \
         simon@EXAMPLE.ORG
     Enter password for `simon@EXAMPLE.ORG':
     simon@EXAMPLE.ORG:
     Authtime:       Tue Dec 16 05:20:47 2003
     Endtime:        Tue Dec 16 05:37:27 2003
     Server:         krbtgt/EXAMPLE.ORG key aes256-cts-hmac-sha1-96 (18)
     Ticket key:     aes256-cts-hmac-sha1-96 (18) protected by aes256-cts-hmac-sha1-96 (18)
     Ticket flags:   FORWARDED PROXIABLE (12)
     jas@latte:~$

   On success, the server will print the following debug information.

     shishid: Accepted socket 6 from socket 4 as IPv4:*:4711/tcp peer 127.0.0.1
     shishid: Listening on IPv4:*:4711/tcp socket 4
     shishid: Listening on IPv4:*:4711/tcp peer 127.0.0.1 socket 6
     shishid: Has 4 bytes from IPv4:*:4711/tcp peer 127.0.0.1 on socket 6
     shishid: Trying STARTTLS
     shishid: TLS handshake negotiated protocol `TLS 1.0', key exchange `Anon DH', certficate type `X.509', cipher `AES 256 CBC', mac `SHA', compression `NULL', session not resumed
     shishid: TLS anonymous authentication with 1024 bit Diffie-Hellman
     shishid: Listening on IPv4:*:4711/tcp socket 4
     shishid: Listening on IPv4:*:4711/tcp peer 127.0.0.1 socket 6
     shishid: Has 131 bytes from IPv4:*:4711/tcp peer 127.0.0.1 on socket 6
     shishid: Processing 131 from IPv4:*:4711/tcp peer 127.0.0.1 on socket 6
     shishid: Trying AS-REQ
     shishid: AS-REQ from simon@EXAMPLE.ORG for krbtgt/EXAMPLE.ORG@EXAMPLE.ORG
     shishid: Matching client etype 18 against user key etype 18
     shishid: Have 511 bytes for IPv4:*:4711/tcp peer 127.0.0.1 on socket 6
     shishid: Sending 511 bytes to IPv4:*:4711/tcp peer 127.0.0.1 socket 6 via TLS
     shishid: Listening on IPv4:*:4711/tcp socket 4
     shishid: Listening on IPv4:*:4711/tcp peer 127.0.0.1 socket 6
     shishid: Peer IPv4:*:4711/tcp peer 127.0.0.1 disconnected on socket 6
     shishid: Closing IPv4:*:4711/tcp peer 127.0.0.1 socket 6
     shishid: Listening on IPv4:*:4711/tcp socket 4

3.6.3 Setting up X.509 authenticated TLS
----------------------------------------

Setting up X.509 authentication is slightly more complicated than
anonymous authentication.  You need a X.509 certificate authority (CA)
that can generate certificates for your Kerberos server and Kerberos
clients.  It is often easiest to setup the CA yourself.  Managing a CA
can be a daunting task, and we only give the bare essentials to get
things up and running.  We suggest that you study the relevant
literature.  As a first step beyond this introduction, you may wish to
explore more secure forms of key storage than storing them unencrypted
on disk.

   The following three sections describe how you create the CA, KDC
certificate, and client certificates.  You can use any tool you like
for this task, as long as they generate X.509 (PKIX) certificates in
PEM format and RSA keys in PKCS#1 format.  Here we use `certtool' that
come with GNUTLS, which is widely available.  We conclude by discussing
how you use these certificates in the KDC and in the Shishi client.

3.6.3.1 Create a Kerberos Certificate Authority
...............................................

First create a CA key.

     jas@latte:~$ certtool --generate-privkey \
        --outfile /usr/local/etc/shishi/shishi.key
     Generating a private key...
     Generating a 1024 bit RSA private key...
     jas@latte:~$

   Then create the CA certificate.  Use whatever details you prefer.

     jas@latte:~$ certtool --generate-self-signed \
        --load-privkey /usr/local/etc/shishi/shishi.key \
        --outfile /usr/local/etc/shishi/shishi.cert
     Generating a self signed certificate...
     Please enter the details of the certificate's distinguished name. \
     Just press enter to ignore a field.
     Country name (2 chars): SE
     Organization name: Shishi Example CA
     Organizational unit name:
     Locality name:
     State or province name:
     Common name: CA
     This field should not be used in new certificates.
     E-mail:
     Enter the certificate's serial number (decimal): 0


     Activation/Expiration time.
     The generated certificate will expire in (days): 180


     Extensions.
     Does the certificate belong to an authority? (Y/N): y
     Is this a web server certificate? (Y/N): n
     Enter the e-mail of the subject of the certificate:


     X.509 certificate info:

     Version: 3
     Serial Number (hex): 00
     Validity:
             Not Before: Sun Dec 21 10:59:00 2003
             Not After: Fri Jun 18 11:59:00 2004
     Subject: C=SE,O=Shishi Example CA,CN=CA
     Subject Public Key Info:
             Public Key Algorithm: RSA

     X.509 Extensions:
             Basic Constraints: (critical)
                     CA:TRUE

     Is the above information ok? (Y/N): y


     Signing certificate...
     jas@latte:~$

3.6.3.2 Create a Kerberos KDC Certificate
.........................................

First create the key for the KDC.

     jas@latte:~$ certtool --generate-privkey \
        --outfile /usr/local/etc/shishi/shishid.key
     Generating a private key...
     Generating a 1024 bit RSA private key...
     jas@latte:~$

   Then create actual KDC certificate, signed by the CA certificate
created in the previous step.

     jas@latte:~$ certtool --generate-certificate \
        --load-ca-certificate /usr/local/etc/shishi/shishi.cert \
        --load-ca-privkey /usr/local/etc/shishi/shishi.key \
        --load-privkey /usr/local/etc/shishi/shishid.key \
        --outfile /usr/local/etc/shishi/shishid.cert
     Generating a signed certificate...
     Loading CA's private key...
     Loading CA's certificate...
     Please enter the details of the certificate's distinguished name. \
     Just press enter to ignore a field.
     Country name (2 chars): SE
     Organization name: Shishi Example KDC
     Organizational unit name:
     Locality name:
     State or province name:
     Common name: KDC
     This field should not be used in new certificates.
     E-mail:
     Enter the certificate's serial number (decimal): 0


     Activation/Expiration time.
     The generated certificate will expire in (days): 180


     Extensions.
     Does the certificate belong to an authority? (Y/N): n
     Is this a web server certificate? (Y/N): n
     Enter the e-mail of the subject of the certificate:


     X.509 certificate info:

     Version: 3
     Serial Number (hex): 00
     Validity:
             Not Before: Sun Dec 21 11:02:00 2003
             Not After: Fri Jun 18 12:02:00 2004
     Subject: C=SE,O=Shishi Example KDC,CN=KDC
     Subject Public Key Info:
             Public Key Algorithm: RSA

     X.509 Extensions:
             Basic Constraints: (critical)
                     CA:FALSE

     Is the above information ok? (Y/N): y


     Signing certificate...
     jas@latte:~$

3.6.3.3 Create a Kerberos Client Certificate
............................................

First create the key for the client.

     jas@latte:~$ certtool --generate-privkey \
        --outfile ~/.shishi/client.key
     Generating a private key...
     Generating a 1024 bit RSA private key...
     jas@latte:~$

   Then create the client certificate, signed by the CA.  An
alternative would be to have the KDC sign the client certificates.

     jas@latte:~$ certtool --generate-certificate \
        --load-ca-certificate /usr/local/etc/shishi/shishi.cert \
        --load-ca-privkey /usr/local/etc/shishi/shishi.key \
        --load-privkey ~/.shishi/client.key \
        --outfile ~/.shishi/client.certs
     Generating a signed certificate...
     Loading CA's private key...
     Loading CA's certificate...
     Please enter the details of the certificate's distinguished name. \
     Just press enter to ignore a field.
     Country name (2 chars): SE
     Organization name: Shishi Example Client
     Organizational unit name:
     Locality name:
     State or province name:
     Common name: Client
     This field should not be used in new certificates.
     E-mail:
     Enter the certificate's serial number (decimal): 0


     Activation/Expiration time.
     The generated certificate will expire in (days): 180


     Extensions.
     Does the certificate belong to an authority? (Y/N): n
     Is this a web server certificate? (Y/N): n
     Enter the e-mail of the subject of the certificate:


     X.509 certificate info:

     Version: 3
     Serial Number (hex): 00
     Validity:
             Not Before: Sun Dec 21 11:04:00 2003
             Not After: Fri Jun 18 12:04:00 2004
     Subject: C=SE,O=Shishi Example Client,CN=Client
     Subject Public Key Info:
             Public Key Algorithm: RSA

     X.509 Extensions:
             Basic Constraints: (critical)
                     CA:FALSE

     Is the above information ok? (Y/N): y


     Signing certificate...
     jas@latte:~$

3.6.3.4 Starting KDC with X.509 authentication support
......................................................

The KDC need the CA certificate (to verify client certificates) and the
server certificate and key (to authenticate itself to the clients).
See elsewhere (*note Parameters for shishid::) for the entire
description of the parameters.

     jas@latte:~$ shishid -l *:4711/tcp \
        --x509cafile /usr/local/etc/shishi/shishi.cert \
        --x509certfile /usr/local/etc/shishi/shishid.cert \
        --x509keyfile /usr/local/etc/shishi/shishid.key
     Initializing GNUTLS...
     Parsed 1 CAs...
     Loaded server certificate/key...
     Generating Diffie-Hellman parameters...
     Initializing GNUTLS...done
     Listening on *:4711/tcp...
     Listening on 1 ports...
     shishid: Starting (GNUTLS `1.0.4')
     shishid: Listening on *:4711/tcp socket 4

   Then acquire tickets as usual.  In case you wonder how shishi finds
the client certificate and key, the filenames used above when
generating the client certificates happen to be the default filenames
for these files.  So it pick them up automatically.

     jas@latte:~$ shishi -o 'realm-kdc=EXAMPLE.ORG,localhost:4711/tls' \
        simon@EXAMPLE.ORG
     Enter password for `simon@EXAMPLE.ORG':
     simon@EXAMPLE.ORG:
     Authtime:       Sun Dec 21 11:15:47 2003
     Endtime:        Sun Dec 21 11:32:27 2003
     Server:         krbtgt/EXAMPLE.ORG key aes256-cts-hmac-sha1-96 (18)
     Ticket key:     aes256-cts-hmac-sha1-96 (18) protected by aes256-cts-hmac-sha1-96 (18)
     Ticket flags:   FORWARDED PROXIABLE RENEWABLE HWAUTHENT TRANSITEDPOLICYCHECKED OKASDELEGATE (12)
     jas@latte:~$

   Here is what the server would print.

     shishid: Accepted socket 6 from socket 4 as *:4711/tcp peer 127.0.0.1
     shishid: Listening on *:4711/tcp socket 4
     shishid: Listening on *:4711/tcp peer 127.0.0.1 socket 6
     shishid: Has 4 bytes from *:4711/tcp peer 127.0.0.1 on socket 6
     shishid: Trying STARTTLS
     shishid: TLS handshake negotiated protocol `TLS 1.0', key exchange `RSA', certficate type `X.509', cipher `AES 256 CBC', mac `SHA', compression `NULL', session not resumed
     shishid: TLS client certificate `C=SE,O=Shishi Example Client,CN=Client', issued by `C=SE,O=Shishi Example CA,CN=CA', serial number `00', MD5 fingerprint `a5:d3:1f:58:76:e3:58:cd:2d:eb:f7:45:a2:4b:52:f9:', activated `Sun Dec 21 11:04:00 2003', expires `Fri Jun 18 12:04:00 2004', version #3, key RSA modulus 1024 bits, currently EXPIRED
     shishid: Listening on *:4711/tcp socket 4
     shishid: Listening on *:4711/tcp peer 127.0.0.1 socket 6
     shishid: Has 131 bytes from *:4711/tcp peer 127.0.0.1 on socket 6
     shishid: Processing 131 from *:4711/tcp peer 127.0.0.1 on socket 6
     shishid: Trying AS-REQ
     shishid: AS-REQ from simon@EXAMPLE.ORG for krbtgt/EXAMPLE.ORG@EXAMPLE.ORG
     shishid: Matching client etype 18 against user key etype 18
     shishid: Have 511 bytes for *:4711/tcp peer 127.0.0.1 on socket 6
     shishid: Sending 511 bytes to *:4711/tcp peer 127.0.0.1 socket 6 via TLS
     shishid: Listening on *:4711/tcp socket 4
     shishid: Listening on *:4711/tcp peer 127.0.0.1 socket 6
     shishid: Peer *:4711/tcp peer 127.0.0.1 disconnected on socket 6
     shishid: Closing *:4711/tcp peer 127.0.0.1 socket 6
     shishid: Listening on *:4711/tcp socket 4


File: shishi.info,  Node: Multiple servers,  Next: Developer information,  Prev: Kerberos via TLS,  Up: Administration Manual

3.7 Multiple servers
====================

Setting up multiple servers is as easy as replicating the user
database.  Since the default `file' user database is stored in the
normal file system, you can use any common tools to replicate a file
system.  Network file system like NFS (properly secured by, e.g., a
point-to-point symmetrically encrypted IPSEC connection) and file
synchronizing tools like `rsync' are typical choices.

   The secondary server should be configured just like the master
server.  If you use the `file' database over NFS you do not have to
make any modifications.  If you use, e.g., a cron job to `rsync' the
directory every hour or so, you may want to add a `--read-only' flag to
the Shisa `db' definition (*note Shisa Configuration::).  That way,
nobody will be lured into creating or changing information in the
database on the secondary server, which only would be overwritten
during the next synchronization.

     db --read-only file /usr/local/var/backup-shishi

   The `file' database is designed so it doesn't require file locking
in the file system, which may be unreliable in some network file
systems or implementations.  It is also designed so that multiple
concurrent readers and writers may access the database without causing
corruption.

   *Warning:* The last paragraph is currently not completely accurate.
There may be race conditions with concurrent writers.  None should
cause infinite loops or data loss.  However, unexpected results might
occur if two writers try to update information about a principal
simultaneous.

   If you use a remote LDAP server or SQL database to store the user
database, and access it via a Shisa backend, you have make sure your
Shisa backend handle concurrent writers properly.  If you use a modern
SQL database, this probably is not a concern.  If it is a problem, you
may be able to work around it by implementing some kind of
synchronization or semaphore mechanism.  If all else sounds too
complicated, you can set up the secondary servers as `--read-only'
servers, although you will lose some functionality (like changing
passwords via the secondary server, or updating timestamps when the
last ticket request occurred).

   One function that is of particular use for users with remote
databases (be it LDAP or SQL) is the "database override" feature.
Using this you can have the security critical principals (such as the
ticket granting ticket) stored on local file system storage, but use
the remote database for user principals.  Of course, you must keep the
local file system storage synchronized between all servers, as before.
Here is an example configuration.

     db --read-only file /var/local/master
     db ldap kdc.example.org ca=/etc/shisa/kdc-ca.pem

   This instruct the Shisa library to access the two databases
sequentially, for each query using the first database that know about
the requested principal.  If you put the `krbtgt/REALM' principal in
the local `file' database, this will override the LDAP interface.
Naturally, you can have as many `db' definition lines as you wish.

   Users with remote databases can also investigate a so called High
Availability mode.  This is useful if you wish to have your Kerberos
servers be able to continue to operate even when the remote database is
offline.  This is achieved via the `--ignore-errors' flag in the
database definition.  Here is a sample configuration.

     db --ignore-errors ldap kdc.example.org ca=/etc/shisa/kdc-ca.pem
     db --read-only file /var/cache/ldap-copy

   This instruct the Shisa library to try the LDAP backend first, but
if it fails, instead of returning an error, continue to try the
operation on a read only local `file' based database.  Of course, write
requests will still fail, but it may be better than halting the server
completely.  To make this work, you first need to set up a cron job on
a, say, hourly basis, to make a copy of the remote database and store
it in the local file database.  That way, when the remote server goes
away, fairly current information will still be available locally.

   If you also wish to experiment with read-write fail over, here is an
idea for the configuration.

     db --ignore-errors ldap kdc.example.org ca=/etc/shisa/kdc-ca.pem
     db --ignore-errors --read-only file /var/cache/ldap-copy
     db file /var/cache/local-updates

   This is similar to the previous, but it will ignore errors reading
and writing from the first two databases, ultimately causing write
attempts to end up in the final `file' based database.  Of course, you
would need to create tools to feed back any local updates made while
the remote server was down.  It may also be necessary to create a
special backend for this purpose, which can auto create principals that
are used.

   We finish with an example that demonstrate all the ideas presented.

     db --read-only file /var/local/master
     db --ignore-errors ldap kdc.example.org ca=/etc/shisa/kdc-ca.pem
     db --ignore-errors --read-only file /var/cache/ldap-copy
     db file /var/cache/local-updates


File: shishi.info,  Node: Developer information,  Prev: Multiple servers,  Up: Administration Manual

3.8 Developer information
=========================

The Programming API for Shisa is described below (*note Kerberos
Database Functions::); this section is about extending Shisa, and
consequently Shishi, to use your own user database system.  You may
want to store your Kerberos user information on an LDAP database
server, for example.

   Adding a new backend is straight forward.  You need to implement the
backend API function set, add the list of API functions to `db/db.c'
and possibly also add any library dependencies to the Makefile.

   The simplest way to write a new backend is to start from the existing
`file' based database, in `db/file.c', and modify the entry points as
needed.

   Note that the current backend API will likely change before it is
frozen.  We may describe it in detail here when it has matured.
However, currently it is similar to the external Shisa API (*note
Kerberos Database Functions::).

   There should be no need to modify anything else in the Shisa library,
and certainly not in the Shishi library or the `shishid' server.

   Naturally, we would appreciate if you would send us your new backend,
if you believe it is generally useful (*note Bug Reports::).


File: shishi.info,  Node: Reference Manual,  Next: Programming Manual,  Prev: Administration Manual,  Up: Top

4 Reference Manual
******************

This chapter discuss the underlying assumptions of Kerberos, contain a
glossary to Kerberos concepts, give you background information on
choosing realm and principal names, and describe all parameters and
configuration file syntaxes for the Shishi tools.

* Menu:

* Environmental Assumptions::   Kerberos 5 assumptions about your system.
* Glossary of terms::           Glossary of Kerberos related terminology.
* Realm and Principal Naming::  How to name your realm and principals.
* Shishi Configuration::        Explains the Core Shishi configuration file.
* Shisa Configuration::         Explains the Shisa database definition file.
* Parameters for shishi::       Command line parameters for 'shishi'.
* Parameters for shishid::      Command line parameters for 'shishid'.
* Parameters for shisa::        Command line parameters for 'shisa'.
* Environment variables::       Overriding compile-time defaults at run-time.
* Date input formats::          Details of the understood date formats.


File: shishi.info,  Node: Environmental Assumptions,  Next: Glossary of terms,  Up: Reference Manual

4.1 Environmental Assumptions
=============================

Kerberos imposes a few assumptions on the environment in which it can
properly function:

   * "Denial of service" attacks are not solved with Kerberos. There
     are places in the protocols where an intruder can prevent an
     application from participating in the proper authentication steps.
     Detection and solution of such attacks (some of which can appear
     to be not-uncommon "normal" failure modes for the system) is
     usually best left to the human administrators and users.

   * Principals MUST keep their secret keys secret. If an intruder
     somehow steals a principal's key, it will be able to masquerade as
     that principal or impersonate any server to the legitimate
     principal.

   * "Password guessing" attacks are not solved by Kerberos. If a user
     chooses a poor password, it is possible for an attacker to
     successfully mount an offline dictionary attack by repeatedly
     attempting to decrypt, with successive entries from a dictionary,
     messages obtained which are encrypted under a key derived from the
     user's password.

   * Each host on the network MUST have a clock which is "loosely
     synchronized" to the time of the other hosts; this synchronization
     is used to reduce the bookkeeping needs of application servers
     when they do replay detection. The degree of "looseness" can be
     configured on a per-server basis, but is typically on the order of
     5 minutes. If the clocks are synchronized over the network, the
     clock synchronization protocol MUST itself be secured from network
     attackers.

   * Principal identifiers are not recycled on a short-term basis. A
     typical mode of access control will use access control lists
     (ACLs) to grant permissions to particular principals. If a stale
     ACL entry remains for a deleted principal and the principal
     identifier is reused, the new principal will inherit rights
     specified in the stale ACL entry. By not re-using principal
     identifiers, the danger of inadvertent access is removed.


File: shishi.info,  Node: Glossary of terms,  Next: Realm and Principal Naming,  Prev: Environmental Assumptions,  Up: Reference Manual

4.2 Glossary of terms
=====================

Authentication
     Verifying the claimed identity of a principal.

Authentication header
     A record containing a Ticket and an Authenticator to be presented
     to a server as part of the authentication process.

Authentication path
     A sequence of intermediate realms transited in the authentication
     process when communicating from one realm to another.

Authenticator
     A record containing information that can be shown to have been
     recently generated using the session key known only by the client
     and server.

Authorization
     The process of determining whether a client may use a service,
     which objects the client is allowed to access, and the type of
     access allowed for each.

Capability
     A token that grants the bearer permission to access an object or
     service. In Kerberos, this might be a ticket whose use is
     restricted by the contents of the authorization data field, but
     which lists no network addresses, together with the session key
     necessary to use the ticket.

Ciphertext
     The output of an encryption function. Encryption transforms
     plaintext into ciphertext.

Client
     A process that makes use of a network service on behalf of a user.
     Note that in some cases a Server may itself be a client of some
     other server (e.g. a print server may be a client of a file
     server).

Credentials
     A ticket plus the secret session key necessary to successfully use
     that ticket in an authentication exchange.

Encryption Type (etype)
     When associated with encrypted data, an encryption type identifies
     the algorithm used to encrypt the data and is used to select the
     appropriate algorithm for decrypting the data.  Encryption type
     tags are communicated in other messages to enumerate algorithms
     that are desired, supported, preferred, or allowed to be used for
     encryption of data between parties.  This preference is combined
     with local information and policy to select an algorithm to be
     used.

KDC
     Key Distribution Center, a network service that supplies tickets
     and temporary session keys; or an instance of that service or the
     host on which it runs. The KDC services both initial ticket and
     ticket-granting ticket requests. The initial ticket portion is
     sometimes referred to as the Authentication Server (or service).
     The ticket-granting ticket portion is sometimes referred to as the
     ticket-granting server (or service).

Kerberos
     The name given to the Project Athena's authentication service, the
     protocol used by that service, or the code used to implement the
     authentication service.  The name is adopted from the three-headed
     dog which guards Hades.

Key Version Number (kvno)
     A tag associated with encrypted data identifies which key was used
     for encryption when a long lived key associated with a principal
     changes over time.  It is used during the transition to a new key
     so that the party decrypting a message can tell whether the data
     was encrypted using the old or the new key.

Plaintext
     The input to an encryption function or the output of a decryption
     function. Decryption transforms ciphertext into plaintext.

Principal
     A named client or server entity that participates in a network
     communication, with one name that is considered canonical.

Principal identifier
     The canonical name used to uniquely identify each different
     principal.

Seal
     To encipher a record containing several fields in such a way that
     the fields cannot be individually replaced without either
     knowledge of the encryption key or leaving evidence of tampering.

Secret key
     An encryption key shared by a principal and the KDC, distributed
     outside the bounds of the system, with a long lifetime. In the
     case of a human user's principal, the secret key MAY be derived
     from a password.

Server
     A particular Principal which provides a resource to network
     clients.  The server is sometimes referred to as the Application
     Server.

Service
     A resource provided to network clients; often provided by more
     than one server (for example, remote file service).

Session key
     A temporary encryption key used between two principals, with a
     lifetime limited to the duration of a single login "session".  In
     the Kerberos system, a session key is generated by the KDC.  The
     session key is distinct from the sub-session key, described next..

Sub-session key
     A temporary encryption key used between two principals, selected
     and exchanged by the principals using the session key, and with a
     lifetime limited to the duration of a single association. The sub-
     session key is also referred to as the subkey.

Ticket
     A record that helps a client authenticate itself to a server; it
     contains the client's identity, a session key, a timestamp, and
     other information, all sealed using the server's secret key. It
     only serves to authenticate a client when presented along with a
     fresh Authenticator.


File: shishi.info,  Node: Realm and Principal Naming,  Next: Shishi Configuration,  Prev: Glossary of terms,  Up: Reference Manual

4.3 Realm and Principal Naming
==============================

This section contains the discussion on naming realms and principals
from the Kerberos specification.

4.3.1 Realm Names
-----------------

Although realm names are encoded as GeneralStrings and although a realm
can technically select any name it chooses, interoperability across
realm boundaries requires agreement on how realm names are to be
assigned, and what information they imply.

   To enforce these conventions, each realm MUST conform to the
conventions itself, and it MUST require that any realms with which
inter-realm keys are shared also conform to the conventions and require
the same from its neighbors.

   Kerberos realm names are case sensitive. Realm names that differ only
in the case of the characters are not equivalent. There are presently
three styles of realm names: domain, X500, and other. Examples of each
style follow:

          domain:   ATHENA.MIT.EDU
            X500:   C=US/O=OSF
           other:   NAMETYPE:rest/of.name=without-restrictions

   Domain syle realm names MUST look like domain names: they consist of
components separated by periods (.) and they contain neither colons (:)
nor slashes (/). Though domain names themselves are case insensitive,
in order for realms to match, the case must match as well. When
establishing a new realm name based on an internet domain name it is
recommended by convention that the characters be converted to upper
case.

   X.500 names contain an equal (=) and cannot contain a colon (:)
before the equal. The realm names for X.500 names will be string
representations of the names with components separated by slashes.
Leading and trailing slashes will not be included. Note that the slash
separator is consistent with Kerberos implementations based on RFC1510,
but it is different from the separator recommended in RFC2253.

   Names that fall into the other category MUST begin with a prefix that
contains no equal (=) or period (.) and the prefix MUST be followed by
a colon (:) and the rest of the name. All prefixes must be assigned
before they may be used. Presently none are assigned.

   The reserved category includes strings which do not fall into the
first three categories. All names in this category are reserved. It is
unlikely that names will be assigned to this category unless there is a
very strong argument for not using the 'other' category.

   These rules guarantee that there will be no conflicts between the
various name styles. The following additional constraints apply to the
assignment of realm names in the domain and X.500 categories: the name
of a realm for the domain or X.500 formats must either be used by the
organization owning (to whom it was assigned) an Internet domain name
or X.500 name, or in the case that no such names are registered,
authority to use a realm name MAY be derived from the authority of the
parent realm. For example, if there is no domain name for E40.MIT.EDU,
then the administrator of the MIT.EDU realm can authorize the creation
of a realm with that name.

   This is acceptable because the organization to which the parent is
assigned is presumably the organization authorized to assign names to
its children in the X.500 and domain name systems as well. If the
parent assigns a realm name without also registering it in the domain
name or X.500 hierarchy, it is the parent's responsibility to make sure
that there will not in the future exist a name identical to the realm
name of the child unless it is assigned to the same entity as the realm
name.

4.3.2 Principal Names
---------------------

As was the case for realm names, conventions are needed to ensure that
all agree on what information is implied by a principal name.  The
name-type field that is part of the principal name indicates the kind
of information implied by the name. The name-type SHOULD be treated
only as a hint to interpreting the meaning of a name. It is not
significant when checking for equivalence. Principal names that differ
only in the name-type identify the same principal. The name type does
not partition the name space. Ignoring the name type, no two names can
be the same (i.e. at least one of the components, or the realm, MUST be
different). The following name types are defined:

     name-type      value   meaning

     NT-UNKNOWN        0  Name type not known
     NT-PRINCIPAL      1  Just the name of the principal as in DCE, or for users
     NT-SRV-INST       2  Service and other unique instance (krbtgt)
     NT-SRV-HST        3  Service with host name as instance (telnet, rcommands)
     NT-SRV-XHST       4  Service with host as remaining components
     NT-UID            5  Unique ID
     NT-X500-PRINCIPAL 6  Encoded X.509 Distingished name [RFC 2253]
     NT-SMTP-NAME      7  Name in form of SMTP email name (e.g. user@foo.com)
     NT-ENTERPRISE    10   Enterprise name - may be mapped to principal name

   When a name implies no information other than its uniqueness at a
particular time the name type PRINCIPAL SHOULD be used. The principal
name type SHOULD be used for users, and it might also be used for a
unique server. If the name is a unique machine generated ID that is
guaranteed never to be reassigned then the name type of UID SHOULD be
used (note that it is generally a bad idea to reassign names of any
type since stale entries might remain in access control lists).

   If the first component of a name identifies a service and the
remaining components identify an instance of the service in a server
specified manner, then the name type of SRV-INST SHOULD be used. An
example of this name type is the Kerberos ticket-granting service whose
name has a first component of krbtgt and a second component identifying
the realm for which the ticket is valid.

   If the first component of a name identifies a service and there is a
single component following the service name identifying the instance as
the host on which the server is running, then the name type SRV- HST
SHOULD be used. This type is typically used for Internet services such
as telnet and the Berkeley R commands. If the separate components of
the host name appear as successive components following the name of the
service, then the name type SRV-XHST SHOULD be used.  This type might
be used to identify servers on hosts with X.500 names where the slash
(/) might otherwise be ambiguous.

   A name type of NT-X500-PRINCIPAL SHOULD be used when a name from an
X.509 certificate is translated into a Kerberos name. The encoding of
the X.509 name as a Kerberos principal shall conform to the encoding
rules specified in RFC 2253.

   A name type of SMTP allows a name to be of a form that resembles a
SMTP email name. This name, including an "@" and a domain name, is used
as the one component of the principal name.

   A name type of UNKNOWN SHOULD be used when the form of the name is
not known. When comparing names, a name of type UNKNOWN will match
principals authenticated with names of any type. A principal
authenticated with a name of type UNKNOWN, however, will only match
other names of type UNKNOWN.

   Names of any type with an initial component of 'krbtgt' are reserved
for the Kerberos ticket granting service. *Note Name of the TGS:
krbtgt, for the form of such names.

4.3.2.1 Name of server principals
.................................

The principal identifier for a server on a host will generally be
composed of two parts: (1) the realm of the KDC with which the server
is registered, and (2) a two-component name of type NT-SRV-HST if the
host name is an Internet domain name or a multi-component name of type
NT-SRV-XHST if the name of the host is of a form such as X.500 that
allows slash (/) separators. The first component of the two- or
multi-component name will identify the service and the latter
components will identify the host. Where the name of the host is not
case sensitive (for example, with Internet domain names) the name of
the host MUST be lower case. If specified by the application protocol
for services such as telnet and the Berkeley R commands which run with
system privileges, the first component MAY be the string 'host' instead
of a service specific identifier.

4.3.2.2 Name of the TGS
.......................

The principal identifier of the ticket-granting service shall be
composed of three parts: (1) the realm of the KDC issuing the TGS
ticket (2) a two-part name of type NT-SRV-INST, with the first part
"krbtgt" and the second part the name of the realm which will accept
the ticket-granting ticket. For example, a ticket-granting ticket
issued by the ATHENA.MIT.EDU realm to be used to get tickets from the
ATHENA.MIT.EDU KDC has a principal identifier of "ATHENA.MIT.EDU"
(realm), ("krbtgt", "ATHENA.MIT.EDU") (name). A ticket-granting ticket
issued by the ATHENA.MIT.EDU realm to be used to get tickets from the
MIT.EDU realm has a principal identifier of "ATHENA.MIT.EDU" (realm),
("krbtgt", "MIT.EDU") (name).

4.3.3 Choosing a principal with which to communicate
----------------------------------------------------

The Kerberos protocol provides the means for verifying (subject to the
assumptions in *Note Environmental Assumptions::) that the entity with
which one communicates is the same entity that was registered with the
KDC using the claimed identity (principal name). It is still necessary
to determine whether that identity corresponds to the entity with which
one intends to communicate.

   When appropriate data has been exchanged in advance, this
determination may be performed syntactically by the application based
on the application protocol specification, information provided by the
user, and configuration files. For example, the server principal name
(including realm) for a telnet server might be derived from the user
specified host name (from the telnet command line), the "host/" prefix
specified in the application protocol specification, and a mapping to a
Kerberos realm derived syntactically from the domain part of the
specified hostname and information from the local Kerberos realms
database.

   One can also rely on trusted third parties to make this
determination, but only when the data obtained from the third party is
suitably integrity protected while resident on the third party server
and when transmitted.  Thus, for example, one should not rely on an
unprotected domain name system record to map a host alias to the
primary name of a server, accepting the primary name as the party one
intends to contact, since an attacker can modify the mapping and
impersonate the party with which one intended to communicate.

   Implementations of Kerberos and protocols based on Kerberos MUST NOT
use insecure DNS queries to canonicalize the hostname components of the
service principal names.  In an environment without secure name
service, application authors MAY append a statically configured domain
name to unqualified hostnames before passing the name to the security
mechanisms, but should do no more than that.  Secure name service
facilities, if available, might be trusted for hostname
canonicalization, but such canonicalization by the client SHOULD NOT be
required by KDC implementations.

   Implementation note: Many current implementations do some degree of
canonicalization of the provided service name, often using DNS even
though it creates security problems. However there is no consistency
among implementations about whether the service name is case folded to
lower case or whether reverse resolution is used. To maximize
interoperability and security, applications SHOULD provide security
mechanisms with names which result from folding the user-entered name
to lower case, without performing any other modifications or
canonicalization.

4.3.4 Principal Name Form
-------------------------

Principal names consist of a sequence of strings, which is often
tedious to parse.  Therefor, Shishi often uses a "printed" form of
principal which embed the entire principal name string sequence, and
optionally also the realm, into one string.  The format is taken from
the Kerberos 5 GSS-API mechanism (RFC 1964).

   The elements included within this name representation are as follows,
proceeding from the beginning of the string:

  1. One or more principal name components; if more than one principal
     name component is included, the components are separated by `/`.
     Arbitrary octets may be included within principal name components,
     with the following constraints and special considerations:
       a. Any occurrence of the characters `@` or `/` within a name
          component must be immediately preceded by the `\` quoting
          character, to prevent interpretation as a component or realm
          separator.

       b. The ASCII newline, tab, backspace, and null characters may
          occur directly within the component or may be represented,
          respectively, by `\n`, `\t`, `\b`, or `\0`.

       c. If the `\` quoting character occurs outside the contexts
          described in (1a) and (1b) above, the following character is
          interpreted literally.  As a special case, this allows the
          doubled representation `\\` to represent a single occurrence
          of the quoting character.

       d. An occurrence of the `\` quoting character as the last
          character of a component is illegal.

  2. Optionally, a `@` character, signifying that a realm name
     immediately follows. If no realm name element is included, the
     local realm name is assumed.  The `/` , `:`, and null characters
     may not occur within a realm name; the `@`, newline, tab, and
     backspace characters may be included using the quoting conventions
     described in (1a), (1b), and (1c) above.


File: shishi.info,  Node: Shishi Configuration,  Next: Shisa Configuration,  Prev: Realm and Principal Naming,  Up: Reference Manual

4.4 Shishi Configuration
========================

The valid configuration file tokens are described here.  The user
configuration file is typically located in `~/.shishi/shishi.conf'
(compare `shishi --configuration-file') and the system configuration is
typically located in `/usr/local/etc/shishi/shishi.conf' (compare
`shishi --system-configuration-file').  If the first non white space
character of a line is a '#', the line is ignored.  Empty lines are
also ignored.

   All tokens are valid in both the system and the user configuration
files, and have the same meaning.  However, as the system file is
supposed to apply to all users on a system, it would not make sense to
use some tokens in that file.  For example, the `default-principal' is
rarely useful in a system configuration file.

4.4.1 `default-realm'
---------------------

Specify the default realm, by default the hostname of the host is used.
E.g.,

     default-realm JOSEFSSON.ORG

4.4.2 `default-principal'
-------------------------

Specify the default principal, by default the login username is used.
E.g.,

     default-principal jas

4.4.3 `client-kdc-etypes'
-------------------------

Specify which encryption types client asks server to respond in during
AS/TGS exchanges. List valid encryption types, in preference order.
Supported algorithms include aes256-cts-hmac-sha1-96,
aes128-cts-hmac-sha1-96, des3-cbc-sha1-kd, des-cbc-md5, des-cbc-md4,
des-cbc-crc and null.  This option also indicates which encryption
types are accepted by the client when receiving the response.  Note
that the preference order is not cryptographically protected, so a man
in the middle can modify the order without being detected.  Thus, only
specify encryption types you trust completely here. The default only
includes aes256-cts-hmac-sha1-96, as suggested by RFC1510bis.  E.g.,

     client-kdc-etypes=aes256-cts-hmac-sha1-96 des3-cbc-sha1-kd des-cbc-md5

4.4.4 `verbose', `verbose-asn1', `verbose-noise', `verbose-crypto', `verbose-crypto-noise'
------------------------------------------------------------------------------------------

Enable verbose library messages.  E.g.,

     verbose
     verbose-noise

4.4.5 `realm-kdc'
-----------------

Specify KDC addresses for realms.  Value is
`REALM,KDCADDRESS[/TRANSPORT][,KDCADDRESS[/TRANSPORT]...]'.

   KDCADDRESS is the hostname or IP address of KDC.

   Optional TRANSPORT is "udp" for UDP, "tcp" for TCP, and "tls" for
TLS connections.  By default UDP is tried first, and TCP used as a
fallback if the KRB_ERR_RESPONSE_TOO_BIG error is received.

   If not specified, Shishi tries to locate the KDC using SRV RRs,
which is recommended.  This option should normally only be used during
experiments, or to access badly maintained realms.

     realm-kdc=JOSEFSSON.ORG,ristretto.josefsson.org

4.4.6 `server-realm'
--------------------

Specify realm for servers. Value is
`REALM,SERVERREGEXP[,SERVERREGEXP...]'.

   SERVERREGEXP is a regular expression matching servers in the realm.
The first match is used.  E.g.,

     server-realm=JOSEFSSON.ORG,.josefsson.org

   Note: currently not used.

4.4.7 `kdc-timeout', `kdc-retries'
----------------------------------

How long shishi waits for a response from a KDC before continuing to
next KDC for realm.  The default is 5 seconds.  E.g.,

     kdc-timeout=10

   How many times shishi sends a request to a KDC before giving up.  The
default is 3 times.  E.g.,

     kdc-retries=5

4.4.8 `stringprocess'
---------------------

How username and passwords entered from the terminal, or taken from the
command line, are processed.

   "none": no processing is used.

   "stringprep": convert from locale charset to UTF-8 and process using
             experimental RFC 1510 stringprep profile.

   It can also be a string indicating a character set supported by
iconv via libstringprep, in which case data is converted from locale
charset into the indicated character set. E.g., UTF-8, ISO-8859-1,
KOI-8, EBCDIC-IS-FRISS are supported on GNU systems.  On some systems
you can use "locale -m" to list available character sets.  By default,
the "none" setting is used which is consistent with RFC 1510 that is
silent on the issue.  In practice, however, converting to UTF-8
improves interoperability.

   E.g.,

     stringprocess=UTF-8

4.4.9 `ticket-life'
-------------------

Specify default ticket life time.

   The string can be in almost any common format.  It can contain month
names, time zones, `am' and `pm', `yesterday', `ago', `next', etc.
*Note Date input formats::, for the long story.

   As an extra feature, if the time specified by your string correspond
to a time during the last 24 hours, an extra day is added to it.  This
allows you to specify relative times such as "17:00" to always mean the
next 17:00, even if your system clock happens to be 17:30.

   The default is 8 hours.

   E.g.,

     #ticket-life=8 hours
     #ticket-life=1 day
     ticket-life=17:00

4.4.10 `renew-life'
-------------------

Specify how long a renewable ticket should remain renewable.

   See ticket-life for the syntax.  The extra feature that handles
negative values within the last 2 hours is not active here.

   The default is 7 days.

   E.g.,

     #renew-life=1 week
     #renew-life=friday 17:00
     renew-life=sunday


File: shishi.info,  Node: Shisa Configuration,  Next: Parameters for shishi,  Prev: Shishi Configuration,  Up: Reference Manual

4.5 Shisa Configuration
=======================

The configuration file for Shisa is typically stored in
`/usr/local/etc/shishi/shisa.conf'.  If the first non white space
character of a line is a '#', the line is ignored.  Empty lines are
also ignored.

4.5.1 `db'
----------

Currently the only configuration options available is the `db' token
that define the databases to use.  The syntax is:

     db [OPTIONS] <TYPE> [LOCATION] [PARAMETERS ...]

   Specify the data sources for Kerberos 5 data.  Multiple entries,
even of the same data source type, are allowed.  The data sources are
accessed in the same sequence as they are defined here.  If an entry is
found in one data source, it will be used for the operations, without
searching the remaining data sources.  Valid OPTIONS include:

     --read-only       No data is written to this data source.
     --ignore-errors   Ignore failures in this backend.

   The default (when the configuration file is empty) uses one "file"
data source (see below), but for a larger installation you may want to
combine several data sources.  Here is an example.

     db --read-only file /var/local/master
     db --ignore-errors ldap kdc.example.org ca=/etc/shisa/kdc-ca.pem
     db --read-only file /var/cache/ldap-copy

   This demonstrate how you can store critical principals on local disk
(the first entry, /var/local/master) that will always be found without
looking in the LDAP directory.  The critical principals could be, e.g.,
krbtgt/EXAMPLE.ORG.  The second entry denote a LDAP server that could
hold user principals.  As you can see, Shisa will not let the caller
know about errors with the LDAP source (they will be logged, however).
Instead, if for instance the LDAP server has crashed, Shisa would
continue and read from the /var/cache/ldap-copy file source.  That file
source may have been set up to contain a copy of the data in the LDAP
server, perhaps made on an hourly basis, so that your server will be
able to serve recent data even in case of a crash.  Any updates or
passwords change requests will however not be possible while the LDAP
server is inaccessible, to reduce the problem of synchronizing data
back into the LDAP server once it is online again.

   Currently only the "file" data source is supported, and denote a
data source that use the standard file system for storage.

   Valid syntaxes for the "file" database:

     db file PATH

   Examples:

     db file /var/shishi
     db file /usr/share/shishi read-only

   If no `db' tokens are present, the default will be:

     db file /usr/local/var/shishi


File: shishi.info,  Node: Parameters for shishi,  Next: Parameters for shishid,  Prev: Shisa Configuration,  Up: Reference Manual

4.6 Parameters for shishi
=========================

If no command is given, Shishi try to make sure you have a ticket
granting ticket for the default realm, and then display it.

   Mandatory arguments to long options are mandatory for short options
too.

     Usage: shishi [OPTIONS]... [CLIENT [SERVER]]...

       -h, --help                              Print help and exit
       -V, --version                           Print version and exit

     Commands:
       -d, --destroy                           Destroy tickets in local cache,
                                                 limited by any --client-name or
                                                 --server-name.  (default=off)
       -l, --list                              List tickets in local cache, limited
                                                 by any --client-name and
                                                 --server-name.  (default=off)
       -r, --renew                             Renew ticket.  Use --server-name to
                                                 specify ticket, default is the
                                                 most recent renewable ticket
                                                 granting ticket for the default
                                                 realm.  (default=off)

     Flags:
           --forwardable                       Get a forwardable ticket, i.e., one
                                                 that can be used to get forwarded
                                                 tickets.  (default=off)
           --forwarded                         Get a forwarded ticket.  (default=
                                                 off)
           --proxiable                         Get a proxiable ticket, i.e., one
                                                 that can be used to get proxy
                                                 tickets.  (default=off)
           --proxy                             Get a proxy ticket.  (default=off)
           --renewable                         Get a renewable ticket.  (default=
                                                 off)

     Options:
           --client-name=NAME                  Client name. Default is login
                                                 username.
       -E, --encryption-type=ETYPE,[ETYPE...]  Encryption types to use.  ETYPE is
                                                 either registered name or integer.
                                                  Valid values include 'aes128',
                                                 'aes256', 'aes' (same as
                                                 'aes256'), '3des', 'des-md5',
                                                 'des-md4', 'des-crc', 'des' (same
                                                 as 'des-md5'), and 'arcfour'.
       -e, --endtime=STRING                    Specify when ticket validity should
                                                 expire.  The time syntax may be
                                                 relative (to the start time), such
                                                 as '20 hours', or absolute, such
                                                 as '2001-02-03 04:05:06 CET'. The
                                                 default is 8 hours after the start
                                                 time.
           --realm=STRING                      Set default realm.
           --renew-till=STRING                 Specify renewable life of ticket.
                                                 Implies --renewable.  Accepts same
                                                 time syntax as --endtime.  If
                                                 --renewable is specified, the
                                                 default is 1 week after the start
                                                 time.
           --server-name=NAME                  Server name. Default is
                                                 'krbtgt/REALM' where REALM is
                                                 client realm.
       -s, --starttime=STRING                  Specify when ticket should start to
                                                 be valid.  Accepts same time
                                                 syntax as --endtime. The default
                                                 is to become valid immediately.
           --ticket-granter=NAME               Service name in ticket to use for
                                                 authenticating request. Only for
                                                 TGS. Defaults to
                                                 'krbtgt/REALM@REALM' where REALM
                                                 is client realm.

     Other options:
           --configuration-file=FILE           Read user configuration from FILE.
       -c, --ticket-file=FILE                  Read tickets from FILE.
       -o, --library-options=STRING            Parse STRING as a configuration file
                                                 statement.
       -q, --quiet                             Don't produce any diagnostic output.
                                                   (default=off)
           --system-configuration-file=FILE    Read system configuration from FILE.
           --ticket-write-file=FILE            Write tickets from FILE.  Default is
                                                 to write them back to where they
                                                 were read from.
       -v, --verbose                           Produce verbose output.
                                                   (default=off)


File: shishi.info,  Node: Parameters for shishid,  Next: Parameters for shisa,  Prev: Parameters for shishi,  Up: Reference Manual

4.7 Parameters for shishid
==========================

If no parameters are specified, `shishid' listens on the defaults
interfaces and answers incoming requests using the keys in the default
key file.

   Mandatory arguments to long options are mandatory for short options
too.

     Usage: shishid [OPTIONS]...

       -h, --help                    Print help and exit
       -V, --version                 Print version and exit

     Commands:
       -l, --listen=[FAMILY:]ADDR:PORT/TYPE
                                     Sockets to listen for queries on.  Family is
                                       `IPv4' or `IPv6', if absent the family is
                                       decided by gethostbyname(ADDR). An address of
                                       `*' indicates all addresses on the local
                                       host. The default is `*:kerberos/udp,
                                       *:kerberos/tcp'.
       -u, --setuid=NAME             After binding socket, set user identity.

     TLS settings:
           --no-tls                  Disable TLS support  (default=off)
           --x509cafile=FILE         X.509 certificate authorities used to verify
                                       client certificates, in PEM format.
           --x509certfile=FILE       X.509 server certificate, in PEM format.
           --x509crlfile=FILE        X.509 certificate revocation list to check for
                                       revoked client certificates, in PEM format.
           --x509keyfile=FILE        X.509 server certificate key, in PEM format.
           --resume-limit=SHORT      Keep track of up to this many TLS sessions for
                                       resume purposes (0 to disable TLS resume).
                                       (default=`50')

     Other options:
       -c, --configuration-file=FILE Use specified configuration file.
       -v, --verbose                 Produce verbose output.
                                       Use multiple times to increase amount of
                                       information.
       -q, --quiet                   Don't produce any diagnostic output.
                                         (default=off)


File: shishi.info,  Node: Parameters for shisa,  Next: Environment variables,  Prev: Parameters for shishid,  Up: Reference Manual

4.8 Parameters for shisa
========================

The purpose of `shisa' is to manipulate information stored in the
Kerberos 5 database used by Shishi.

   Mandatory arguments to long options are mandatory for short options
too.

     Usage: shisa [OPTIONS]... [REALM [PRINCIPAL]]...

       -h, --help                         Print help and exit
       -V, --version                      Print version and exit

     Operations:
       -a, --add                          Add realm or principal to database.
       -d, --dump                         Dump entries in database.
       -n, --key-add                      Add new key to a principal in database.
           --key-remove                   Remove a key from a principal in
                                            database.
       -l, --list                         List entries in database.
       -m, --modify                       Modify principal entry in database.
       -r, --remove                       Remove realm or principal from database.

     Parameters:
       -f, --force                        Allow removal of non-empty realms.
                                              (default=off)
           --enabled                      Only dump or list enabled principals.
                                              (default=off)
           --disabled                     Only dump or list disabled principals.
                                              (default=off)
           --keys                         Print cryptographic key and password in
                                            hostkey format.  (default=off)

     Values:
       -E, --encryption-type=STRING       Override default key encryption type.
                                            Valid values include 'aes128',
                                            'aes256', 'aes' (same as 'aes256'),
                                            '3des', 'des-md5', 'des-md4',
                                            'des-crc', 'des' (same as 'des-md5'),
                                            and 'arcfour'.
           --key-version=NUMBER           Version of key.
           --password[=STRING]            Derive key from this password.
           --random                       Use a random key.  (default)
           --salt=STRING                  Use specified salt for deriving key.
                                            Defaults to concatenation of realm and
                                            (unwrapped) principal name.
           --string-to-key-parameter=HEX  Encryption algorithm specific parameter
                                            for password derivation.  Currently
                                            only the AES algorithm can utilize
                                            this, where it is interpreted as the
                                            iteration count of the PKCS#5 PBKDF2
                                            key deriver.

     Other options:
       -c, --configuration-file=FILE      Use specified configuration file.
       -o, --library-options=STRING       Parse string as configuration file
                                            statement.
       -v, --verbose                      Produce verbose output.
                                              (default=off)
       -q, --quiet                        Don't produce any diagnostic output.
                                              (default=off)


File: shishi.info,  Node: Environment variables,  Next: Date input formats,  Prev: Parameters for shisa,  Up: Reference Manual

4.9 Environment variables
=========================

A few of the compile-time defaults may be overridden at run-time by
using environment variables.  The following variables are supported.

   * `SHISHI_CONFIG' Specify the location of the default system
     configuration file.  Used by the Shishi library.  If not
     specified, the default is specified at compile-time and is usually
     `$prefix/etc/shishi.conf'.

   * `SHISHI_HOME' Specify the user specific directory for
     configuration files, ticket cache, etc.  Used by the Shishi
     library.  If not specified, it is computed as `$HOME/.shishi'.

   * `SHISHI_USER' Specify the default principal user name.  Used by
     the Shishi library.  If not specified, it is taken from the
     environment variable `USER'.

   * `SHISHI_TICKETS' Specify the file name of the ticket cache.  Used
     by the Shishi library.  If not specified, it will be
     `$SHISHI_HOME/tickets', or `$HOME/.shishi/tickets' if
     `$SHISHI_HOME' is not specified.



File: shishi.info,  Node: Date input formats,  Prev: Environment variables,  Up: Reference Manual

4.10 Date input formats
=======================

First, a quote:

     Our units of temporal measurement, from seconds on up to months,
     are so complicated, asymmetrical and disjunctive so as to make
     coherent mental reckoning in time all but impossible.  Indeed, had
     some tyrannical god contrived to enslave our minds to time, to
     make it all but impossible for us to escape subjection to sodden
     routines and unpleasant surprises, he could hardly have done
     better than handing down our present system.  It is like a set of
     trapezoidal building blocks, with no vertical or horizontal
     surfaces, like a language in which the simplest thought demands
     ornate constructions, useless particles and lengthy
     circumlocutions.  Unlike the more successful patterns of language
     and science, which enable us to face experience boldly or at least
     level-headedly, our system of temporal calculation silently and
     persistently encourages our terror of time.

     ...  It is as though architects had to measure length in feet,
     width in meters and height in ells; as though basic instruction
     manuals demanded a knowledge of five different languages.  It is
     no wonder then that we often look into our own immediate past or
     future, last Tuesday or a week from Sunday, with feelings of
     helpless confusion.  ...

     --Robert Grudin, `Time and the Art of Living'.

   This section describes the textual date representations that GNU
programs accept.  These are the strings you, as a user, can supply as
arguments to the various programs.  The C interface (via the
`parse_datetime' function) is not described here.

* Menu:

* General date syntax::            Common rules.
* Calendar date items::            19 Dec 1994.
* Time of day items::              9:20pm.
* Time zone items::                EST, PDT, UTC, ...
* Combined date and time of day items:: 1972-09-24T20:02:00,000000-0500.
* Day of week items::              Monday and others.
* Relative items in date strings:: next tuesday, 2 years ago.
* Pure numbers in date strings::   19931219, 1440.
* Seconds since the Epoch::        @1078100502.
* Specifying time zone rules::     TZ="America/New_York", TZ="UTC0".
* Authors of parse_datetime::      Bellovin, Eggert, Salz, Berets, et al.


File: shishi.info,  Node: General date syntax,  Next: Calendar date items,  Up: Date input formats

4.10.1 General date syntax
--------------------------

A "date" is a string, possibly empty, containing many items separated
by whitespace.  The whitespace may be omitted when no ambiguity arises.
The empty string means the beginning of today (i.e., midnight).  Order
of the items is immaterial.  A date string may contain many flavors of
items:

   * calendar date items

   * time of day items

   * time zone items

   * combined date and time of day items

   * day of the week items

   * relative items

   * pure numbers.

We describe each of these item types in turn, below.

   A few ordinal numbers may be written out in words in some contexts.
This is most useful for specifying day of the week items or relative
items (see below).  Among the most commonly used ordinal numbers, the
word `last' stands for -1, `this' stands for 0, and `first' and `next'
both stand for 1.  Because the word `second' stands for the unit of
time there is no way to write the ordinal number 2, but for convenience
`third' stands for 3, `fourth' for 4, `fifth' for 5, `sixth' for 6,
`seventh' for 7, `eighth' for 8, `ninth' for 9, `tenth' for 10,
`eleventh' for 11 and `twelfth' for 12.

   When a month is written this way, it is still considered to be
written numerically, instead of being "spelled in full"; this changes
the allowed strings.

   In the current implementation, only English is supported for words
and abbreviations like `AM', `DST', `EST', `first', `January',
`Sunday', `tomorrow', and `year'.

   The output of the `date' command is not always acceptable as a date
string, not only because of the language problem, but also because
there is no standard meaning for time zone items like `IST'.  When using
`date' to generate a date string intended to be parsed later, specify a
date format that is independent of language and that does not use time
zone items other than `UTC' and `Z'.  Here are some ways to do this:

     $ LC_ALL=C TZ=UTC0 date
     Mon Mar  1 00:21:42 UTC 2004
     $ TZ=UTC0 date +'%Y-%m-%d %H:%M:%SZ'
     2004-03-01 00:21:42Z
     $ date --rfc-3339=ns  # --rfc-3339 is a GNU extension.
     2004-02-29 16:21:42.692722128-08:00
     $ date --rfc-2822  # a GNU extension
     Sun, 29 Feb 2004 16:21:42 -0800
     $ date +'%Y-%m-%d %H:%M:%S %z'  # %z is a GNU extension.
     2004-02-29 16:21:42 -0800
     $ date +'@%s.%N'  # %s and %N are GNU extensions.
     @1078100502.692722128

   Alphabetic case is completely ignored in dates.  Comments may be
introduced between round parentheses, as long as included parentheses
are properly nested.  Hyphens not followed by a digit are currently
ignored.  Leading zeros on numbers are ignored.

   Invalid dates like `2005-02-29' or times like `24:00' are rejected.
In the typical case of a host that does not support leap seconds, a
time like `23:59:60' is rejected even if it corresponds to a valid leap
second.


File: shishi.info,  Node: Calendar date items,  Next: Time of day items,  Prev: General date syntax,  Up: Date input formats

4.10.2 Calendar date items
--------------------------

A "calendar date item" specifies a day of the year.  It is specified
differently, depending on whether the month is specified numerically or
literally.  All these strings specify the same calendar date:

     1972-09-24     # ISO 8601.
     72-9-24        # Assume 19xx for 69 through 99,
                    # 20xx for 00 through 68.
     72-09-24       # Leading zeros are ignored.
     9/24/72        # Common U.S. writing.
     24 September 1972
     24 Sept 72     # September has a special abbreviation.
     24 Sep 72      # Three-letter abbreviations always allowed.
     Sep 24, 1972
     24-sep-72
     24sep72

   The year can also be omitted.  In this case, the last specified year
is used, or the current year if none.  For example:

     9/24
     sep 24

   Here are the rules.

   For numeric months, the ISO 8601 format `YEAR-MONTH-DAY' is allowed,
where YEAR is any positive number, MONTH is a number between 01 and 12,
and DAY is a number between 01 and 31.  A leading zero must be present
if a number is less than ten.  If YEAR is 68 or smaller, then 2000 is
added to it; otherwise, if YEAR is less than 100, then 1900 is added to
it.  The construct `MONTH/DAY/YEAR', popular in the United States, is
accepted.  Also `MONTH/DAY', omitting the year.

   Literal months may be spelled out in full: `January', `February',
`March', `April', `May', `June', `July', `August', `September',
`October', `November' or `December'.  Literal months may be abbreviated
to their first three letters, possibly followed by an abbreviating dot.
It is also permitted to write `Sept' instead of `September'.

   When months are written literally, the calendar date may be given as
any of the following:

     DAY MONTH YEAR
     DAY MONTH
     MONTH DAY YEAR
     DAY-MONTH-YEAR

   Or, omitting the year:

     MONTH DAY


File: shishi.info,  Node: Time of day items,  Next: Time zone items,  Prev: Calendar date items,  Up: Date input formats

4.10.3 Time of day items
------------------------

A "time of day item" in date strings specifies the time on a given day.
Here are some examples, all of which represent the same time:

     20:02:00.000000
     20:02
     8:02pm
     20:02-0500      # In EST (U.S. Eastern Standard Time).

   More generally, the time of day may be given as
`HOUR:MINUTE:SECOND', where HOUR is a number between 0 and 23, MINUTE
is a number between 0 and 59, and SECOND is a number between 0 and 59
possibly followed by `.' or `,' and a fraction containing one or more
digits.  Alternatively, `:SECOND' can be omitted, in which case it is
taken to be zero.  On the rare hosts that support leap seconds, SECOND
may be 60.

   If the time is followed by `am' or `pm' (or `a.m.' or `p.m.'), HOUR
is restricted to run from 1 to 12, and `:MINUTE' may be omitted (taken
to be zero).  `am' indicates the first half of the day, `pm' indicates
the second half of the day.  In this notation, 12 is the predecessor of
1: midnight is `12am' while noon is `12pm'.  (This is the zero-oriented
interpretation of `12am' and `12pm', as opposed to the old tradition
derived from Latin which uses `12m' for noon and `12pm' for midnight.)

   The time may alternatively be followed by a time zone correction,
expressed as `SHHMM', where S is `+' or `-', HH is a number of zone
hours and MM is a number of zone minutes.  The zone minutes term, MM,
may be omitted, in which case the one- or two-digit correction is
interpreted as a number of hours.  You can also separate HH from MM
with a colon.  When a time zone correction is given this way, it forces
interpretation of the time relative to Coordinated Universal Time
(UTC), overriding any previous specification for the time zone or the
local time zone.  For example, `+0530' and `+05:30' both stand for the
time zone 5.5 hours ahead of UTC (e.g., India).  This is the best way to
specify a time zone correction by fractional parts of an hour.  The
maximum zone correction is 24 hours.

   Either `am'/`pm' or a time zone correction may be specified, but not
both.


File: shishi.info,  Node: Time zone items,  Next: Combined date and time of day items,  Prev: Time of day items,  Up: Date input formats

4.10.4 Time zone items
----------------------

A "time zone item" specifies an international time zone, indicated by a
small set of letters, e.g., `UTC' or `Z' for Coordinated Universal
Time.  Any included periods are ignored.  By following a
non-daylight-saving time zone by the string `DST' in a separate word
(that is, separated by some white space), the corresponding daylight
saving time zone may be specified.  Alternatively, a
non-daylight-saving time zone can be followed by a time zone
correction, to add the two values.  This is normally done only for
`UTC'; for example, `UTC+05:30' is equivalent to `+05:30'.

   Time zone items other than `UTC' and `Z' are obsolescent and are not
recommended, because they are ambiguous; for example, `EST' has a
different meaning in Australia than in the United States.  Instead,
it's better to use unambiguous numeric time zone corrections like
`-0500', as described in the previous section.

   If neither a time zone item nor a time zone correction is supplied,
time stamps are interpreted using the rules of the default time zone
(*note Specifying time zone rules::).


File: shishi.info,  Node: Combined date and time of day items,  Next: Day of week items,  Prev: Time zone items,  Up: Date input formats

4.10.5 Combined date and time of day items
------------------------------------------

The ISO 8601 date and time of day extended format consists of an ISO
8601 date, a `T' character separator, and an ISO 8601 time of day.
This format is also recognized if the `T' is replaced by a space.

   In this format, the time of day should use 24-hour notation.
Fractional seconds are allowed, with either comma or period preceding
the fraction.  ISO 8601 fractional minutes and hours are not supported.
Typically, hosts support nanosecond timestamp resolution; excess
precision is silently discarded.

   Here are some examples:

     2012-09-24T20:02:00.052-0500
     2012-12-31T23:59:59,999999999+1100
     1970-01-01 00:00Z


File: shishi.info,  Node: Day of week items,  Next: Relative items in date strings,  Prev: Combined date and time of day items,  Up: Date input formats

4.10.6 Day of week items
------------------------

The explicit mention of a day of the week will forward the date (only
if necessary) to reach that day of the week in the future.

   Days of the week may be spelled out in full: `Sunday', `Monday',
`Tuesday', `Wednesday', `Thursday', `Friday' or `Saturday'.  Days may
be abbreviated to their first three letters, optionally followed by a
period.  The special abbreviations `Tues' for `Tuesday', `Wednes' for
`Wednesday' and `Thur' or `Thurs' for `Thursday' are also allowed.

   A number may precede a day of the week item to move forward
supplementary weeks.  It is best used in expression like `third
monday'.  In this context, `last DAY' or `next DAY' is also acceptable;
they move one week before or after the day that DAY by itself would
represent.

   A comma following a day of the week item is ignored.


File: shishi.info,  Node: Relative items in date strings,  Next: Pure numbers in date strings,  Prev: Day of week items,  Up: Date input formats

4.10.7 Relative items in date strings
-------------------------------------

"Relative items" adjust a date (or the current date if none) forward or
backward.  The effects of relative items accumulate.  Here are some
examples:

     1 year
     1 year ago
     3 years
     2 days

   The unit of time displacement may be selected by the string `year'
or `month' for moving by whole years or months.  These are fuzzy units,
as years and months are not all of equal duration.  More precise units
are `fortnight' which is worth 14 days, `week' worth 7 days, `day'
worth 24 hours, `hour' worth 60 minutes, `minute' or `min' worth 60
seconds, and `second' or `sec' worth one second.  An `s' suffix on
these units is accepted and ignored.

   The unit of time may be preceded by a multiplier, given as an
optionally signed number.  Unsigned numbers are taken as positively
signed.  No number at all implies 1 for a multiplier.  Following a
relative item by the string `ago' is equivalent to preceding the unit
by a multiplier with value -1.

   The string `tomorrow' is worth one day in the future (equivalent to
`day'), the string `yesterday' is worth one day in the past (equivalent
to `day ago').

   The strings `now' or `today' are relative items corresponding to
zero-valued time displacement, these strings come from the fact a
zero-valued time displacement represents the current time when not
otherwise changed by previous items.  They may be used to stress other
items, like in `12:00 today'.  The string `this' also has the meaning
of a zero-valued time displacement, but is preferred in date strings
like `this thursday'.

   When a relative item causes the resulting date to cross a boundary
where the clocks were adjusted, typically for daylight saving time, the
resulting date and time are adjusted accordingly.

   The fuzz in units can cause problems with relative items.  For
example, `2003-07-31 -1 month' might evaluate to 2003-07-01, because
2003-06-31 is an invalid date.  To determine the previous month more
reliably, you can ask for the month before the 15th of the current
month.  For example:

     $ date -R
     Thu, 31 Jul 2003 13:02:39 -0700
     $ date --date='-1 month' +'Last month was %B?'
     Last month was July?
     $ date --date="$(date +%Y-%m-15) -1 month" +'Last month was %B!'
     Last month was June!

   Also, take care when manipulating dates around clock changes such as
daylight saving leaps.  In a few cases these have added or subtracted
as much as 24 hours from the clock, so it is often wise to adopt
universal time by setting the `TZ' environment variable to `UTC0'
before embarking on calendrical calculations.


File: shishi.info,  Node: Pure numbers in date strings,  Next: Seconds since the Epoch,  Prev: Relative items in date strings,  Up: Date input formats

4.10.8 Pure numbers in date strings
-----------------------------------

The precise interpretation of a pure decimal number depends on the
context in the date string.

   If the decimal number is of the form YYYYMMDD and no other calendar
date item (*note Calendar date items::) appears before it in the date
string, then YYYY is read as the year, MM as the month number and DD as
the day of the month, for the specified calendar date.

   If the decimal number is of the form HHMM and no other time of day
item appears before it in the date string, then HH is read as the hour
of the day and MM as the minute of the hour, for the specified time of
day.  MM can also be omitted.

   If both a calendar date and a time of day appear to the left of a
number in the date string, but no relative item, then the number
overrides the year.


File: shishi.info,  Node: Seconds since the Epoch,  Next: Specifying time zone rules,  Prev: Pure numbers in date strings,  Up: Date input formats

4.10.9 Seconds since the Epoch
------------------------------

If you precede a number with `@', it represents an internal time stamp
as a count of seconds.  The number can contain an internal decimal
point (either `.' or `,'); any excess precision not supported by the
internal representation is truncated toward minus infinity.  Such a
number cannot be combined with any other date item, as it specifies a
complete time stamp.

   Internally, computer times are represented as a count of seconds
since an epoch--a well-defined point of time.  On GNU and POSIX
systems, the epoch is 1970-01-01 00:00:00 UTC, so `@0' represents this
time, `@1' represents 1970-01-01 00:00:01 UTC, and so forth.  GNU and
most other POSIX-compliant systems support such times as an extension
to POSIX, using negative counts, so that `@-1' represents 1969-12-31
23:59:59 UTC.

   Traditional Unix systems count seconds with 32-bit two's-complement
integers and can represent times from 1901-12-13 20:45:52 through
2038-01-19 03:14:07 UTC.  More modern systems use 64-bit counts of
seconds with nanosecond subcounts, and can represent all the times in
the known lifetime of the universe to a resolution of 1 nanosecond.

   On most hosts, these counts ignore the presence of leap seconds.
For example, on most hosts `@915148799' represents 1998-12-31 23:59:59
UTC, `@915148800' represents 1999-01-01 00:00:00 UTC, and there is no
way to represent the intervening leap second 1998-12-31 23:59:60 UTC.


File: shishi.info,  Node: Specifying time zone rules,  Next: Authors of parse_datetime,  Prev: Seconds since the Epoch,  Up: Date input formats

4.10.10 Specifying time zone rules
----------------------------------

Normally, dates are interpreted using the rules of the current time
zone, which in turn are specified by the `TZ' environment variable, or
by a system default if `TZ' is not set.  To specify a different set of
default time zone rules that apply just to one date, start the date
with a string of the form `TZ="RULE"'.  The two quote characters (`"')
must be present in the date, and any quotes or backslashes within RULE
must be escaped by a backslash.

   For example, with the GNU `date' command you can answer the question
"What time is it in New York when a Paris clock shows 6:30am on October
31, 2004?" by using a date beginning with `TZ="Europe/Paris"' as shown
in the following shell transcript:

     $ export TZ="America/New_York"
     $ date --date='TZ="Europe/Paris" 2004-10-31 06:30'
     Sun Oct 31 01:30:00 EDT 2004

   In this example, the `--date' operand begins with its own `TZ'
setting, so the rest of that operand is processed according to
`Europe/Paris' rules, treating the string `2004-10-31 06:30' as if it
were in Paris.  However, since the output of the `date' command is
processed according to the overall time zone rules, it uses New York
time.  (Paris was normally six hours ahead of New York in 2004, but
this example refers to a brief Halloween period when the gap was five
hours.)

   A `TZ' value is a rule that typically names a location in the `tz'
database (http://www.twinsun.com/tz/tz-link.htm).  A recent catalog of
location names appears in the TWiki Date and Time Gateway
(http://twiki.org/cgi-bin/xtra/tzdate).  A few non-GNU hosts require a
colon before a location name in a `TZ' setting, e.g.,
`TZ=":America/New_York"'.

   The `tz' database includes a wide variety of locations ranging from
`Arctic/Longyearbyen' to `Antarctica/South_Pole', but if you are at sea
and have your own private time zone, or if you are using a non-GNU host
that does not support the `tz' database, you may need to use a POSIX
rule instead.  Simple POSIX rules like `UTC0' specify a time zone
without daylight saving time; other rules can specify simple daylight
saving regimes.  *Note Specifying the Time Zone with `TZ': (libc)TZ
Variable.


File: shishi.info,  Node: Authors of parse_datetime,  Prev: Specifying time zone rules,  Up: Date input formats

4.10.11 Authors of `parse_datetime'
-----------------------------------

`parse_datetime' started life as `getdate', as originally implemented
by Steven M. Bellovin (<smb@research.att.com>) while at the University
of North Carolina at Chapel Hill.  The code was later tweaked by a
couple of people on Usenet, then completely overhauled by Rich $alz
(<rsalz@bbn.com>) and Jim Berets (<jberets@bbn.com>) in August, 1990.
Various revisions for the GNU system were made by David MacKenzie, Jim
Meyering, Paul Eggert and others, including renaming it to `get_date' to
avoid a conflict with the alternative Posix function `getdate', and a
later rename to `parse_datetime'.  The Posix function `getdate' can
parse more locale-specific dates using `strptime', but relies on an
environment variable and external file, and lacks the thread-safety of
`parse_datetime'.

   This chapter was originally produced by Franc,ois Pinard
(<pinard@iro.umontreal.ca>) from the `parse_datetime.y' source code,
and then edited by K. Berry (<kb@cs.umb.edu>).


File: shishi.info,  Node: Programming Manual,  Next: Acknowledgements,  Prev: Reference Manual,  Up: Top

5 Programming Manual
********************

This chapter describes all the publicly available functions in the
library.

* Menu:

* Preparation::                 What you should do before using the library.
* Initialization Functions::    Creating library handle, configuration file.
* Ticket Set Functions::        High-level ticket management functions.
* AP-REQ and AP-REP Functions:: Client/Server authentication functions.
* SAFE and PRIV Functions::     Client/Server session data functions.
* Ticket Functions::            Medium-level ticket manipulation functions.
* AS Functions::                Medium-level initial authentication functions.
* TGS Functions::               Medium-level authentication functions.
* Ticket (ASN.1) Functions::    Low-level Ticket functions.
* AS/TGS Functions::            Low-level KDC functions; AS and TGS.
* Authenticator Functions::     Low-level authenticator functions.
* KRB-ERROR Functions::         Low-level KRB-ERROR functions.
* Cryptographic Functions::     Low-level cryptographic functions.
* X.509 Functions::             Utility functions for X.509 support.
* Utility Functions::           Utilities for use in the global context.
* ASN.1 Functions::             Perform low-level ASN.1 manipulations.
* Error Handling::              Error codes and such.
* Examples::                    Example code.
* Kerberos Database Functions:: The Shisa generic database interface.
* Generic Security Service::    If you want to use the GSS API instead.


File: shishi.info,  Node: Preparation,  Next: Initialization Functions,  Up: Programming Manual

5.1 Preparation
===============

To use `Libshishi', you have to perform some changes to your sources
and the build system.  The necessary changes are small and explained in
the following sections.  At the end of this chapter, it is described
how the library is initialized, and how the requirements of the library
are verified.

   A faster way to find out how to adapt your application for use with
`Libshishi' may be to look at the examples at the end of this manual
(*note Examples::).

* Menu:

* Header::
* Initialization::
* Version Check::
* Building the source::
* Autoconf tests::


File: shishi.info,  Node: Header,  Next: Initialization,  Up: Preparation

5.1.1 Header
------------

All interfaces (data types and functions) of the library are defined in
the header file `shishi.h'.  You must include this in all programs
using the library, either directly or through some other header file,
like this:

     #include <shishi.h>

   The name space of `Libshishi' is `shishi_*' for function names,
`Shishi*' for data types and `SHISHI_*' for other symbols.  In addition
the same name prefixes with one prepended underscore are reserved for
internal use and should never be used by an application.


File: shishi.info,  Node: Initialization,  Next: Version Check,  Prev: Header,  Up: Preparation

5.1.2 Initialization
--------------------

`Libshishi' must be initialized before it can be used.  The library is
initialized by calling `shishi_init' (*note Initialization
Functions::).  The resources allocated by the initialization process
can be released if the application no longer has a need to call
`Libshishi' functions, this is done by calling `shishi_done'.

   In order to take advantage of the internationalisation features in
`Libshishi', such as translated error messages, the application must
set the current locale using `setlocale' before initializing
`Libshishi'.


File: shishi.info,  Node: Version Check,  Next: Building the source,  Prev: Initialization,  Up: Preparation

5.1.3 Version Check
-------------------

It is often desirable to check that the version of `Libshishi' used is
indeed one which fits all requirements.  Even with binary compatibility
new features may have been introduced but due to problem with the
dynamic linker an old version is actually used.  So you may want to
check that the version is okay right after program startup.

shishi_check_version
--------------------

 -- Function: const char * shishi_check_version (const char *
          REQ_VERSION)
     REQ_VERSION: version string to compare with, or NULL

     Check that the version of the library is at minimum the one given
     as a string in `req_version'.

     *Return value:* the actual version string of the library; NULL if
     the condition is not met.  If `NULL' is passed to this function no
     check is done and only the version string is returned.

   The normal way to use the function is to put something similar to the
following early in your `main':

       if (!shishi_check_version (SHISHI_VERSION))
         {
           printf ("shishi_check_version failed:\n"
                   "Header file incompatible with shared library.\n");
           exit (EXIT_FAILURE);
         }


File: shishi.info,  Node: Building the source,  Next: Autoconf tests,  Prev: Version Check,  Up: Preparation

5.1.4 Building the source
-------------------------

If you want to compile a source file including the `shishi.h' header
file, you must make sure that the compiler can find it in the directory
hierarchy.  This is accomplished by adding the path to the directory in
which the header file is located to the compilers include file search
path (via the `-I' option).

   However, the path to the include file is determined at the time the
source is configured.  To solve this problem, `Libshishi' uses the
external package `pkg-config' that knows the path to the include file
and other configuration options.  The options that need to be added to
the compiler invocation at compile time are output by the `--cflags'
option to `pkg-config shishi'.  The following example shows how it can
be used at the command line:

     gcc -c foo.c `pkg-config shishi --cflags`

   Adding the output of `pkg-config shishi --cflags' to the compilers
command line will ensure that the compiler can find the `Libshishi'
header file.

   A similar problem occurs when linking the program with the library.
Again, the compiler has to find the library files.  For this to work,
the path to the library files has to be added to the library search path
(via the `-L' option).  For this, the option `--libs' to `pkg-config
shishi' can be used.  For convenience, this option also outputs all
other options that are required to link the program with the
`Libshishi' libararies (in particular, the `-lshishi' option).  The
example shows how to link `foo.o' with the `Libshishi' library to a
program `foo'.

     gcc -o foo foo.o `pkg-config shishi --libs`

   Of course you can also combine both examples to a single command by
specifying both options to `pkg-config':

     gcc -o foo foo.c `pkg-config shishi --cflags --libs`


File: shishi.info,  Node: Autoconf tests,  Prev: Building the source,  Up: Preparation

5.1.5 Autoconf tests
--------------------

If you work on a project that uses Autoconf (*note GNU Autoconf:
(autoconf)top.) to help find installed libraries, the suggestions in
the previous section are not the entire story.  There are a few methods
to detect and incorporate Shishi into your Autoconf based package.  The
preferred approach, is to use Libtool in your project, and use the
normal Autoconf header file and library tests.

5.1.5.1 Autoconf test via `pkg-config'
......................................

If your audience is a typical GNU/Linux desktop, you can often assume
they have the `pkg-config' tool installed, in which you can use its
Autoconf M4 macro to find and set up your package for use with Shishi.
The following illustrate this scenario.

     AC_ARG_ENABLE(kerberos_v5,
     	AC_HELP_STRING([--disable-kerberos_v5],
                            [don't use the KERBEROS_V5 mechanism]),
     	kerberos_v5=$enableval)
     if test "$kerberos_v5" != "no" ; then
     	PKG_CHECK_MODULES(SHISHI, shishi >= 0.0.0,
     			[kerberos_v5=yes],
                             [kerberos_v5=no])
     	if test "$kerberos_v5" != "yes" ; then
     		kerberos_v5=no
     		AC_MSG_WARN([shishi not found, disabling Kerberos 5])
     	else
     		kerberos_v5=yes
     		AC_DEFINE(USE_KERBEROS_V5, 1,
                               [Define to 1 if you want Kerberos 5.])
     	fi
     fi
     AC_MSG_CHECKING([if Kerberos 5 should be used])
     AC_MSG_RESULT($kerberos_v5)

5.1.5.2 Standalone Autoconf test using Libtool
..............................................

If your package uses Libtool(*note GNU Libtool: (libtool)top.), you can
use the normal Autoconf tests to find the Shishi library and rely on
the Libtool dependency tracking to include the proper dependency
libraries (e.g., Libidn).  The following illustrate this scenario.

     AC_CHECK_HEADER(shishi.h,
     	AC_CHECK_LIB(shishi, shishi_check_version,
     		[kerberos5=yes AC_SUBST(SHISHI_LIBS, -lshishi)],
     		kerberos5=no),
     	kerberos5=no)
     AC_ARG_ENABLE(kerberos5,
     	AC_HELP_STRING([--disable-kerberos5],
                            [disable Kerberos 5 unconditionally]),
     	kerberos5=$enableval)
     if test "$kerberos5" != "no" ; then
     	AC_DEFINE(USE_KERBEROS_V5, 1,
     		  [Define to 1 if you want Kerberos 5.])
     else
     	AC_MSG_WARN([Shishi not found, disabling Kerberos 5])
     fi
     AC_MSG_CHECKING([if Kerberos 5 should be used])
     AC_MSG_RESULT($kerberos5)

5.1.5.3 Standalone Autoconf test
................................

If your package does not use Libtool, as well as detecting the Shishi
library as in the previous case, you must also detect whatever
dependencies Shishi requires to work (e.g., libidn).  Since the
dependencies are in a state of flux, we do not provide an example and
we do not recommend this approach, unless you are experienced developer.


File: shishi.info,  Node: Initialization Functions,  Next: Ticket Set Functions,  Prev: Preparation,  Up: Programming Manual

5.2 Initialization Functions
============================

shishi
------

 -- Function: Shishi * shishi ( VOID)
     Initializes the Shishi library, and set up, using
     `shishi_error_set_outputtype()', the library so that future
     warnings and informational messages are printed to stderr.  If
     this function fails, it may print diagnostic errors to stderr.

     *Return value:* Returns Shishi library handle, or `NULL' on error.

shishi_server
-------------

 -- Function: Shishi * shishi_server ( VOID)
     Initializes the Shishi library, and set up, using
     `shishi_error_set_outputtype()', the library so that future
     warnings and informational messages are printed to the syslog.  If
     this function fails, it may print diagnostic errors to the syslog.

     *Return value:* Returns Shishi library handle, or `NULL' on error.

shishi_done
-----------

 -- Function: void shishi_done (Shishi * HANDLE)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     Deallocates the shishi library handle.  The handle must not be used
     in any calls to shishi functions after this.

     If there is a default tkts, it is written to the default tkts file
     (call `shishi_tkts_default_file_set()' to change the default tkts
     file). If you do not wish to write the default tkts file, close the
     default tkts with shishi_tkts_done(handle, NULL) before calling
     this function.

shishi_init
-----------

 -- Function: int shishi_init (Shishi ** HANDLE)
     HANDLE: pointer to handle to be created.

     Create a Shishi library handle, using `shishi()', and read the
     system configuration file, user configuration file and user
     tickets from their default locations.  The paths to the system
     configuration file is decided at compile time, and is
     $sysconfdir/shishi.conf.  The user configuration file is
     $HOME/.shishi/config, and the user ticket file is
     $HOME/.shishi/ticket.

     The handle is allocated regardless of return values, except for
     SHISHI_HANDLE_ERROR which indicates a problem allocating the
     handle.  (The other error conditions comes from reading the files.)

     *Return value:* Returns SHISHI_OK iff successful.

shishi_init_with_paths
----------------------

 -- Function: int shishi_init_with_paths (Shishi ** HANDLE, const char
          * TKTSFILE, const char * SYSTEMCFGFILE, const char *
          USERCFGFILE)
     HANDLE: pointer to handle to be created.

     TKTSFILE: Filename of ticket file, or NULL.

     SYSTEMCFGFILE: Filename of system configuration, or NULL.

     USERCFGFILE: Filename of user configuration, or NULL.

     Create a Shishi library handle, using `shishi()', and read the
     system configuration file, user configuration file, and user
     tickets from the specified locations.  If any of `usercfgfile' or
     `systemcfgfile' is NULL, the file is read from its default
     location, which for the system configuration file is decided at
     compile time, and is $sysconfdir/shishi.conf, and for the user
     configuration file is $HOME/.shishi/config.  If the ticket file is
     NULL, a ticket file is not read at all.

     The handle is allocated regardless of return values, except for
     SHISHI_HANDLE_ERROR which indicates a problem allocating the
     handle.  (The other error conditions comes from reading the files.)

     *Return value:* Returns SHISHI_OK iff successful.

shishi_init_server
------------------

 -- Function: int shishi_init_server (Shishi ** HANDLE)
     HANDLE: pointer to handle to be created.

     Create a Shishi library handle, using `shishi_server()', and read
     the system configuration file.  The paths to the system
     configuration file is decided at compile time, and is
     $sysconfdir/shishi.conf.

     The handle is allocated regardless of return values, except for
     SHISHI_HANDLE_ERROR which indicates a problem allocating the
     handle.  (The other error conditions comes from reading the file.)

     *Return value:* Returns SHISHI_OK iff successful.

shishi_init_server_with_paths
-----------------------------

 -- Function: int shishi_init_server_with_paths (Shishi ** HANDLE,
          const char * SYSTEMCFGFILE)
     HANDLE: pointer to handle to be created.

     SYSTEMCFGFILE: Filename of system configuration, or NULL.

     Create a Shishi library handle, using `shishi_server()', and read
     the system configuration file from specified location.  The paths
     to the system configuration file is decided at compile time, and is
     $sysconfdir/shishi.conf.  The handle is allocated regardless of
     return values, except for SHISHI_HANDLE_ERROR which indicates a
     problem allocating the handle.  (The other error conditions comes
     from reading the file.)

     *Return value:* Returns SHISHI_OK iff successful.

shishi_cfg
----------

 -- Function: int shishi_cfg (Shishi * HANDLE, const char * OPTION)
     HANDLE: Shishi library handle create by `shishi_init()'.

     OPTION: string with shishi library option.

     Configure shishi library with given option.

     *Return Value:* Returns SHISHI_OK if option was valid.

shishi_cfg_from_file
--------------------

 -- Function: int shishi_cfg_from_file (Shishi * HANDLE, const char *
          CFG)
     HANDLE: Shishi library handle create by `shishi_init()'.

     CFG: filename to read configuration from.

     Configure shishi library using configuration file.

     *Return Value:* Returns `SHISHI_OK' iff successful.

shishi_cfg_print
----------------

 -- Function: int shishi_cfg_print (Shishi * HANDLE, FILE * FH)
     HANDLE: Shishi library handle create by `shishi_init()'.

     FH: file descriptor opened for writing.

     Print library configuration status, mostly for debugging purposes.

     *Return Value:* Returns SHISHI_OK.

shishi_cfg_default_systemfile
-----------------------------

 -- Function: const char * shishi_cfg_default_systemfile (Shishi *
          HANDLE)
     HANDLE: Shishi library handle create by `shishi_init()'.

     The system configuration file name is decided at compile-time, but
     may be overridden by the environment variable SHISHI_CONFIG.

     *Return value:* Return system configuration file name.

shishi_cfg_default_userdirectory
--------------------------------

 -- Function: const char * shishi_cfg_default_userdirectory (Shishi *
          HANDLE)
     HANDLE: Shishi library handle create by `shishi_init()'.

     The default user directory (used for, e.g. Shishi ticket cache) is
     normally computed by appending BASE_DIR ("/.shishi") to the content
     of the environment variable $HOME, but can be overridden by
     specifying the complete path in the environment variable
     SHISHI_HOME.

     *Return value:* Return directory with configuration files etc.

shishi_cfg_userdirectory_file
-----------------------------

 -- Function: char * shishi_cfg_userdirectory_file (Shishi * HANDLE,
          const char * FILE)
     HANDLE: Shishi library handle create by `shishi_init()'.

     FILE: basename of file to find in user directory.

     Get the full path to specified `file' in the users' configuration
     directory.

     *Return value:* Return full path to given relative filename,
     relative to the user specific Shishi configuration directory as
     returned by `shishi_cfg_default_userdirectory()' (typically
     $HOME/.shishi).

shishi_cfg_default_userfile
---------------------------

 -- Function: const char * shishi_cfg_default_userfile (Shishi * HANDLE)
     HANDLE: Shishi library handle create by `shishi_init()'.

     Get filename of default user configuration file, typically
     $HOME/shishi.conf.

     *Return value:* Return user configuration filename.

shishi_cfg_clientkdcetype
-------------------------

 -- Function: int shishi_cfg_clientkdcetype (Shishi * HANDLE, int32_t
          ** ETYPES)
     HANDLE: Shishi library handle create by `shishi_init()'.

     ETYPES: output array with encryption types.

     Set the etypes variable to the array of preferred client etypes.

     *Return value:* Return the number of encryption types in the array,
     0 means none.

shishi_cfg_clientkdcetype_fast
------------------------------

 -- Function: int32_t shishi_cfg_clientkdcetype_fast (Shishi * HANDLE)
     HANDLE: Shishi library handle create by `shishi_init()'.

     Extract the default etype from the list of preferred client etypes.

     *Return value:* Return the default encryption types.

shishi_cfg_clientkdcetype_set
-----------------------------

 -- Function: int shishi_cfg_clientkdcetype_set (Shishi * HANDLE, char
          * VALUE)
     HANDLE: Shishi library handle created by `shishi_init()'.

     VALUE: string with encryption types.

     Set the "client-kdc-etypes" configuration option from given string.
     The string contains encryption types (integer or names) separated
     by comma or whitespace, e.g. "aes256-cts-hmac-sha1-96
     des3-cbc-sha1-kd des-cbc-md5".

     *Return value:* Returns SHISHI_OK if successful.

shishi_cfg_authorizationtype_set
--------------------------------

 -- Function: int shishi_cfg_authorizationtype_set (Shishi * HANDLE,
          char * VALUE)
     HANDLE: Shishi library handle created by `shishi_init()'.

     VALUE: string with authorization types.

     Set the "authorization-types" configuration option from given
     string.  The string contains authorization types (integer or
     names) separated by comma or whitespace, e.g. "basic k5login".

     *Return value:* Returns SHISHI_OK if successful.


File: shishi.info,  Node: Ticket Set Functions,  Next: AP-REQ and AP-REP Functions,  Prev: Initialization Functions,  Up: Programming Manual

5.3 Ticket Set Functions
========================

A "ticket set" is, as the name implies, a collection of tickets.
Functions are provided to read tickets from file into a ticket set, to
query number of tickets in the set, to extract a given ticket from the
set, to search the ticket set for tickets matching certain criterium,
to write the ticket set to a file, etc.  High level functions for
performing a initial authentication (*note AS Functions::) or
subsequent authentication (*note TGS Functions::) and storing the new
ticket in the ticket set are also provided.

   *Note Ticket Functions::, to manipulate each individual ticket.
*Note Ticket (ASN.1) Functions::, for low-level ASN.1 manipulation.

shishi_tkts_default_file_guess
------------------------------

 -- Function: char * shishi_tkts_default_file_guess (Shishi * HANDLE)
     HANDLE: Shishi library handle create by `shishi_init()'.

     Guesses the default ticket filename; it is $SHISHI_TICKETS,
     $SHISHI_HOME/tickets, or $HOME/.shishi/tickets.

     *Return value:* Returns default tkts filename as a string that has
     to be deallocated with `free()' by the caller.

shishi_tkts_default_file
------------------------

 -- Function: const char * shishi_tkts_default_file (Shishi * HANDLE)
     HANDLE: Shishi library handle create by `shishi_init()'.

     Get filename of default ticket set.

     *Return value:* Returns the default ticket set filename used in the
     library.  The string is not a copy, so don't modify or deallocate
     it.

shishi_tkts_default_file_set
----------------------------

 -- Function: void shishi_tkts_default_file_set (Shishi * HANDLE, const
          char * TKTSFILE)
     HANDLE: Shishi library handle create by `shishi_init()'.

     TKTSFILE: string with new default tkts file name, or NULL to reset
     to default.

     Set the default ticket set filename used in the library.  The
     string is copied into the library, so you can dispose of the
     variable immediately after calling this function.

shishi_tkts_default
-------------------

 -- Function: Shishi_tkts * shishi_tkts_default (Shishi * HANDLE)
     HANDLE: Shishi library handle create by `shishi_init()'.

     Get the default ticket set for library handle.

     *Return value:* Return the handle global ticket set.

shishi_tkts
-----------

 -- Function: int shishi_tkts (Shishi * HANDLE, Shishi_tkts ** TKTS)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     TKTS: output pointer to newly allocated tkts handle.

     Get a new ticket set handle.

     *Return value:* Returns `SHISHI_OK' iff successful.

shishi_tkts_done
----------------

 -- Function: void shishi_tkts_done (Shishi_tkts ** TKTS)
     TKTS: ticket set handle as allocated by `shishi_tkts()'.

     Deallocates all resources associated with ticket set.  The ticket
     set handle must not be used in calls to other shishi_tkts_*()
     functions after this.

shishi_tkts_size
----------------

 -- Function: int shishi_tkts_size (Shishi_tkts * TKTS)
     TKTS: ticket set handle as allocated by `shishi_tkts()'.

     Get size of ticket set.

     *Return value:* Returns number of tickets stored in ticket set.

shishi_tkts_nth
---------------

 -- Function: Shishi_tkt * shishi_tkts_nth (Shishi_tkts * TKTS, int
          TICKETNO)
     TKTS: ticket set handle as allocated by `shishi_tkts()'.

     TICKETNO: integer indicating requested ticket in ticket set.

     *Get the n:* th ticket in ticket set.

     *Return value:* Returns a ticket handle to the ticketno:th ticket
     in the ticket set, or NULL if ticket set is invalid or ticketno is
     out of bounds.  The first ticket is ticketno 0, the second
     ticketno 1, and so on.

shishi_tkts_remove
------------------

 -- Function: int shishi_tkts_remove (Shishi_tkts * TKTS, int TICKETNO)
     TKTS: ticket set handle as allocated by `shishi_tkts()'.

     TICKETNO: ticket number of ticket in the set to remove.  The first
     ticket is ticket number 0.

     Remove a ticket, indexed by `ticketno', in ticket set.

     *Return value:* `SHISHI_OK' if successful or if `ticketno' larger
     than size of ticket set.

shishi_tkts_add
---------------

 -- Function: int shishi_tkts_add (Shishi_tkts * TKTS, Shishi_tkt * TKT)
     TKTS: ticket set handle as allocated by `shishi_tkts()'.

     TKT: ticket to be added to ticket set.

     Add a ticket to the ticket set.  Only the pointer is stored, so if
     you modify `tkt', the ticket in the ticket set will also be
     modified.

     *Return value:* Returns `SHISHI_OK' iff successful.

shishi_tkts_new
---------------

 -- Function: int shishi_tkts_new (Shishi_tkts * TKTS, Shishi_asn1
          TICKET, Shishi_asn1 ENCKDCREPPART, Shishi_asn1 KDCREP)
     TKTS: ticket set handle as allocated by `shishi_tkts()'.

     TICKET: input ticket variable.

     ENCKDCREPPART: input ticket detail variable.

     KDCREP: input KDC-REP variable.

     Allocate a new ticket and add it to the ticket set.

     Note that `ticket', `enckdcreppart' and `kdcrep' are stored by
     reference, so you must not de-allocate them before the ticket is
     removed from the ticket set and de-allocated.

     *Return value:* Returns `SHISHI_OK' iff successful.

shishi_tkts_read
----------------

 -- Function: int shishi_tkts_read (Shishi_tkts * TKTS, FILE * FH)
     TKTS: ticket set handle as allocated by `shishi_tkts()'.

     FH: file descriptor to read from.

     Read tickets from file descriptor and add them to the ticket set.

     *Return value:* Returns `SHISHI_OK' iff successful.

shishi_tkts_from_file
---------------------

 -- Function: int shishi_tkts_from_file (Shishi_tkts * TKTS, const char
          * FILENAME)
     TKTS: ticket set handle as allocated by `shishi_tkts()'.

     FILENAME: filename to read tickets from.

     Read tickets from file and add them to the ticket set.

     *Return value:* Returns `SHISHI_OK' iff successful.

shishi_tkts_write
-----------------

 -- Function: int shishi_tkts_write (Shishi_tkts * TKTS, FILE * FH)
     TKTS: ticket set handle as allocated by `shishi_tkts()'.

     FH: file descriptor to write tickets to.

     Write tickets in set to file descriptor.

     *Return value:* Returns `SHISHI_OK' iff successful.

shishi_tkts_expire
------------------

 -- Function: int shishi_tkts_expire (Shishi_tkts * TKTS)
     TKTS: ticket set handle as allocated by `shishi_tkts()'.

     Remove expired tickets from ticket set.

     *Return value:* Returns `SHISHI_OK' iff successful.

shishi_tkts_to_file
-------------------

 -- Function: int shishi_tkts_to_file (Shishi_tkts * TKTS, const char *
          FILENAME)
     TKTS: ticket set handle as allocated by `shishi_tkts()'.

     FILENAME: filename to write tickets to.

     Write tickets in set to file.

     *Return value:* Returns `SHISHI_OK' iff successful.

shishi_tkts_print_for_service
-----------------------------

 -- Function: int shishi_tkts_print_for_service (Shishi_tkts * TKTS,
          FILE * FH, const char * SERVICE)
     TKTS: ticket set handle as allocated by `shishi_tkts()'.

     FH: file descriptor to print to.

     SERVICE: service to limit tickets printed to, or NULL.

     Print description of tickets for specified service to file
     descriptor.  If service is NULL, all tickets are printed.

     *Return value:* Returns `SHISHI_OK' iff successful.

shishi_tkts_print
-----------------

 -- Function: int shishi_tkts_print (Shishi_tkts * TKTS, FILE * FH)
     TKTS: ticket set handle as allocated by `shishi_tkts()'.

     FH: file descriptor to print to.

     Print description of all tickets to file descriptor.

     *Return value:* Returns `SHISHI_OK' iff successful.

shishi_tkt_match_p
------------------

 -- Function: int shishi_tkt_match_p (Shishi_tkt * TKT,
          Shishi_tkts_hint * HINT)
     TKT: ticket to test hints on.

     HINT: structure with characteristics of ticket to be found.

     Test if a ticket matches specified hints.

     *Return value:* Returns 0 iff ticket fails to match given criteria.

shishi_tkts_find
----------------

 -- Function: Shishi_tkt * shishi_tkts_find (Shishi_tkts * TKTS,
          Shishi_tkts_hint * HINT)
     TKTS: ticket set handle as allocated by `shishi_tkts()'.

     HINT: structure with characteristics of ticket to be found.

     Search the ticketset sequentially (from ticket number 0 through all
     tickets in the set) for a ticket that fits the given
     characteristics.  If a ticket is found, the hint->startpos field is
     updated to point to the next ticket in the set, so this function
     can be called repeatedly with the same hint argument in order to
     find all tickets matching a certain criterium.  Note that if
     tickets are added to, or removed from, the ticketset during a query
     with the same hint argument, the hint->startpos field must be
     updated appropriately.

     *Here is how you would typically use this function:*
     Shishi_tkts_hint  hint;

     Shishi_tkt  tkt;

     memset(&hint, 0, sizeof(hint));

     hint.server = "imap/mail.example.org";

     tkt = shishi_tkts_find (shishi_tkts_default(handle), &hint);

     if (!tkt)

     printf("No ticket found...\n");

     else

     do_something_with_ticket (tkt);

     *Return value:* Returns a ticket if found, or NULL if no further
     matching tickets could be found.

shishi_tkts_find_for_clientserver
---------------------------------

 -- Function: Shishi_tkt * shishi_tkts_find_for_clientserver
          (Shishi_tkts * TKTS, const char * CLIENT, const char * SERVER)
     TKTS: ticket set handle as allocated by `shishi_tkts()'.

     CLIENT: client name to find ticket for.

     SERVER: server name to find ticket for.

     Short-hand function for searching the ticket set for a ticket for
     the given client and server.  See `shishi_tkts_find()'.

     *Return value:* Returns a ticket if found, or NULL.

shishi_tkts_find_for_server
---------------------------

 -- Function: Shishi_tkt * shishi_tkts_find_for_server (Shishi_tkts *
          TKTS, const char * SERVER)
     TKTS: ticket set handle as allocated by `shishi_tkts()'.

     SERVER: server name to find ticket for.

     Short-hand function for searching the ticket set for a ticket for
     the given server using the default client principal.  See
     `shishi_tkts_find_for_clientserver()' and `shishi_tkts_find()'.

     *Return value:* Returns a ticket if found, or NULL.

shishi_tkts_get_tgt
-------------------

 -- Function: Shishi_tkt * shishi_tkts_get_tgt (Shishi_tkts * TKTS,
          Shishi_tkts_hint * HINT)
     TKTS: ticket set handle as allocated by `shishi_tkts()'.

     HINT: structure with characteristics of ticket to begot.

     Get a ticket granting ticket (TGT) suitable for acquiring ticket
     matching the hint.  I.e., get a TGT for the server realm in the
     hint structure (hint->serverrealm), or the default realm if the
     serverrealm field is NULL.  Can result in AS exchange.

     Currently this function do not implement cross realm logic.

     This function is used by `shishi_tkts_get()', which is probably
     what you really want to use unless you have special needs.

     *Return value:* Returns a ticket granting ticket if successful, or
     NULL if this function is unable to acquire on.

shishi_tkts_get_tgs
-------------------

 -- Function: Shishi_tkt * shishi_tkts_get_tgs (Shishi_tkts * TKTS,
          Shishi_tkts_hint * HINT, Shishi_tkt * TGT)
     TKTS: ticket set handle as allocated by `shishi_tkts()'.

     HINT: structure with characteristics of ticket to begot.

     TGT: ticket granting ticket to use.

     Get a ticket via TGS exchange using specified ticket granting
     ticket.

     This function is used by `shishi_tkts_get()', which is probably
     what you really want to use unless you have special needs.

     *Return value:* Returns a ticket if successful, or NULL if this
     function is unable to acquire on.

shishi_tkts_get
---------------

 -- Function: Shishi_tkt * shishi_tkts_get (Shishi_tkts * TKTS,
          Shishi_tkts_hint * HINT)
     TKTS: ticket set handle as allocated by `shishi_tkts()'.

     HINT: structure with characteristics of ticket to be found.

     Get a ticket matching given characteristics.  This function first
     looks in the ticket set for a ticket, then tries to find a
     suitable TGT, possibly via an AS exchange, using
     `shishi_tkts_get_tgt()', and then uses that TGT in a TGS exchange
     to get the ticket.

     Currently this function does not implement cross realm logic.

     *Return value:* Returns a ticket if found, or NULL if this function
     is unable to get the ticket.

shishi_tkts_get_for_clientserver
--------------------------------

 -- Function: Shishi_tkt * shishi_tkts_get_for_clientserver
          (Shishi_tkts * TKTS, const char * CLIENT, const char * SERVER)
     TKTS: ticket set handle as allocated by `shishi_tkts()'.

     CLIENT: client name to get ticket for.

     SERVER: server name to get ticket for.

     Short-hand function for getting a ticket for the given client and
     server.  See `shishi_tkts_get()'.

     *Return value:* Returns a ticket if found, or NULL.

shishi_tkts_get_for_server
--------------------------

 -- Function: Shishi_tkt * shishi_tkts_get_for_server (Shishi_tkts *
          TKTS, const char * SERVER)
     TKTS: ticket set handle as allocated by `shishi_tkts()'.

     SERVER: server name to get ticket for.

     Short-hand function for getting a ticket to the given server and
     for the default principal client.  See `shishi_tkts_get()'.

     *Return value:* Returns a ticket if found, or NULL.

shishi_tkts_get_for_localservicepasswd
--------------------------------------

 -- Function: Shishi_tkt * shishi_tkts_get_for_localservicepasswd
          (Shishi_tkts * TKTS, const char * SERVICE, const char *
          PASSWD)
     TKTS: ticket set handle as allocated by `shishi_tkts()'.

     SERVICE: service name to get ticket for.

     PASSWD: password for the default client principal.

     Short-hand function for getting a ticket to the given local
     service, and for the default principal client.  The latter's
     password is given as argument.  See `shishi_tkts_get()'.

     *Return value:* Returns a ticket if found, or NULL otherwise.


File: shishi.info,  Node: AP-REQ and AP-REP Functions,  Next: SAFE and PRIV Functions,  Prev: Ticket Set Functions,  Up: Programming Manual

5.4 AP-REQ and AP-REP Functions
===============================

The "AP-REQ" and "AP-REP" are ASN.1 structures used by application
client and servers to prove to each other who they are.  The structures
contain auxilliary information, together with an authenticator (*note
Authenticator Functions::) which is the real cryptographic proof.  The
following illustrates the AP-REQ and AP-REP ASN.1 structures.


AP-REQ		::= [APPLICATION 14] SEQUENCE {
	pvno		[0] INTEGER (5),
	msg-type	[1] INTEGER (14),
	ap-options	[2] APOptions,
	ticket		[3] Ticket,
	authenticator	[4] EncryptedData {Authenticator,
				{ keyuse-pa-TGSReq-authenticator
				  | keyuse-APReq-authenticator }}
}

AP-REP		::= [APPLICATION 15] SEQUENCE {
	pvno		[0] INTEGER (5),
	msg-type	[1] INTEGER (15),
	enc-part	[2] EncryptedData {EncAPRepPart,
				{ keyuse-EncAPRepPart }}
}

EncAPRepPart	::= [APPLICATION 27] SEQUENCE {
	ctime		[0] KerberosTime,
	cusec		[1] Microseconds,
	subkey		[2] EncryptionKey OPTIONAL,
	seq-number	[3] UInt32 OPTIONAL
}

shishi_ap
---------

 -- Function: int shishi_ap (Shishi * HANDLE, Shishi_ap ** AP)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     AP: pointer to new structure that holds information about AP
     exchange

     Create a new AP exchange with a random subkey of the default
     encryption type from configuration.  Note that there is no
     guarantee that the receiver will understand that key type, you
     should probably use `shishi_ap_etype()' or `shishi_ap_nosubkey()'
     instead.  In the future, this function will likely behave as
     `shishi_ap_nosubkey()' and `shishi_ap_nosubkey()' will be removed.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_ap_etype
---------------

 -- Function: int shishi_ap_etype (Shishi * HANDLE, Shishi_ap ** AP,
          int ETYPE)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     AP: pointer to new structure that holds information about AP
     exchange

     ETYPE: encryption type of newly generated random subkey.

     Create a new AP exchange with a random subkey of indicated
     encryption type.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_ap_nosubkey
------------------

 -- Function: int shishi_ap_nosubkey (Shishi * HANDLE, Shishi_ap ** AP)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     AP: pointer to new structure that holds information about AP
     exchange

     Create a new AP exchange without subkey in authenticator.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_ap_done
--------------

 -- Function: void shishi_ap_done (Shishi_ap * AP)
     AP: structure that holds information about AP exchange

     Deallocate resources associated with AP exchange.  This should be
     called by the application when it no longer need to utilize the AP
     exchange handle.

shishi_ap_set_tktoptions
------------------------

 -- Function: int shishi_ap_set_tktoptions (Shishi_ap * AP, Shishi_tkt
          * TKT, int OPTIONS)
     AP: structure that holds information about AP exchange

     TKT: ticket to set in AP.

     OPTIONS: AP-REQ options to set in AP.

     Set the ticket (see `shishi_ap_tkt_set()') and set the AP-REQ
     apoptions (see `shishi_apreq_options_set()').

     *Return value:* Returns SHISHI_OK iff successful.

shishi_ap_set_tktoptionsdata
----------------------------

 -- Function: int shishi_ap_set_tktoptionsdata (Shishi_ap * AP,
          Shishi_tkt * TKT, int OPTIONS, const char * DATA, size_t LEN)
     AP: structure that holds information about AP exchange

     TKT: ticket to set in AP.

     OPTIONS: AP-REQ options to set in AP.

     DATA: input array with data to checksum in Authenticator.

     LEN: length of input array with data to checksum in Authenticator.

     Set the ticket (see `shishi_ap_tkt_set()') and set the AP-REQ
     apoptions (see `shishi_apreq_options_set()') and set the
     Authenticator checksum data.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_ap_set_tktoptionsraw
---------------------------

 -- Function: int shishi_ap_set_tktoptionsraw (Shishi_ap * AP,
          Shishi_tkt * TKT, int OPTIONS, int32_t CKSUMTYPE, const char
          * DATA, size_t LEN)
     AP: structure that holds information about AP exchange

     TKT: ticket to set in AP.

     OPTIONS: AP-REQ options to set in AP.

     CKSUMTYPE: authenticator checksum type to set in AP.

     DATA: input array with data to store in checksum field in
     Authenticator.

     LEN: length of input array with data to store in checksum field in
     Authenticator.

     Set the ticket (see `shishi_ap_tkt_set()') and set the AP-REQ
     apoptions (see `shishi_apreq_options_set()') and set the raw
     Authenticator checksum data.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_ap_set_tktoptionsasn1usage
---------------------------------

 -- Function: int shishi_ap_set_tktoptionsasn1usage (Shishi_ap * AP,
          Shishi_tkt * TKT, int OPTIONS, Shishi_asn1 NODE, const char *
          FIELD, int AUTHENTICATORCKSUMKEYUSAGE, int
          AUTHENTICATORKEYUSAGE)
     AP: structure that holds information about AP exchange

     TKT: ticket to set in AP.

     OPTIONS: AP-REQ options to set in AP.

     NODE: input ASN.1 structure to store as authenticator checksum
     data.

     FIELD: field in ASN.1 structure to use.

     AUTHENTICATORCKSUMKEYUSAGE: key usage for checksum in
     authenticator.

     AUTHENTICATORKEYUSAGE: key usage for authenticator.

     Set ticket, options and authenticator checksum data using
     `shishi_ap_set_tktoptionsdata()'.  The authenticator checksum data
     is the DER encoding of the ASN.1 field provided.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_ap_tktoptions
--------------------

 -- Function: int shishi_ap_tktoptions (Shishi * HANDLE, Shishi_ap **
          AP, Shishi_tkt * TKT, int OPTIONS)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     AP: pointer to new structure that holds information about AP
     exchange

     TKT: ticket to set in newly created AP.

     OPTIONS: AP-REQ options to set in newly created AP.

     Create a new AP exchange using `shishi_ap()', and set the ticket
     and AP-REQ apoptions using `shishi_ap_set_tktoptions()'.  A random
     session key is added to the authenticator, using the same keytype
     as the ticket.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_ap_tktoptionsdata
------------------------

 -- Function: int shishi_ap_tktoptionsdata (Shishi * HANDLE, Shishi_ap
          ** AP, Shishi_tkt * TKT, int OPTIONS, const char * DATA,
          size_t LEN)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     AP: pointer to new structure that holds information about AP
     exchange

     TKT: ticket to set in newly created AP.

     OPTIONS: AP-REQ options to set in newly created AP.

     DATA: input array with data to checksum in Authenticator.

     LEN: length of input array with data to checksum in Authenticator.

     Create a new AP exchange using `shishi_ap()', and set the ticket,
     AP-REQ apoptions and the Authenticator checksum data using
     `shishi_ap_set_tktoptionsdata()'. A random session key is added to
     the authenticator, using the same keytype as the ticket.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_ap_tktoptionsraw
-----------------------

 -- Function: int shishi_ap_tktoptionsraw (Shishi * HANDLE, Shishi_ap
          ** AP, Shishi_tkt * TKT, int OPTIONS, int32_t CKSUMTYPE,
          const char * DATA, size_t LEN)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     AP: pointer to new structure that holds information about AP
     exchange

     TKT: ticket to set in newly created AP.

     OPTIONS: AP-REQ options to set in newly created AP.

     CKSUMTYPE: authenticator checksum type to set in AP.

     DATA: input array with data to store in checksum field in
     Authenticator.

     LEN: length of input array with data to store in checksum field in
     Authenticator.

     Create a new AP exchange using `shishi_ap()', and set the ticket,
     AP-REQ apoptions and the raw Authenticator checksum data field
     using `shishi_ap_set_tktoptionsraw()'.  A random session key is
     added to the authenticator, using the same keytype as the ticket.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_ap_etype_tktoptionsdata
------------------------------

 -- Function: int shishi_ap_etype_tktoptionsdata (Shishi * HANDLE,
          Shishi_ap ** AP, int32_t ETYPE, Shishi_tkt * TKT, int
          OPTIONS, const char * DATA, size_t LEN)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     AP: pointer to new structure that holds information about AP
     exchange

     ETYPE: encryption type of newly generated random subkey.

     TKT: ticket to set in newly created AP.

     OPTIONS: AP-REQ options to set in newly created AP.

     DATA: input array with data to checksum in Authenticator.

     LEN: length of input array with data to checksum in Authenticator.

     Create a new AP exchange using `shishi_ap()', and set the ticket,
     AP-REQ apoptions and the Authenticator checksum data using
     `shishi_ap_set_tktoptionsdata()'. A random session key is added to
     the authenticator, using the same keytype as the ticket.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_ap_tktoptionsasn1usage
-----------------------------

 -- Function: int shishi_ap_tktoptionsasn1usage (Shishi * HANDLE,
          Shishi_ap ** AP, Shishi_tkt * TKT, int OPTIONS, Shishi_asn1
          NODE, const char * FIELD, int AUTHENTICATORCKSUMKEYUSAGE, int
          AUTHENTICATORKEYUSAGE)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     AP: pointer to new structure that holds information about AP
     exchange

     TKT: ticket to set in newly created AP.

     OPTIONS: AP-REQ options to set in newly created AP.

     NODE: input ASN.1 structure to store as authenticator checksum
     data.

     FIELD: field in ASN.1 structure to use.

     AUTHENTICATORCKSUMKEYUSAGE: key usage for checksum in
     authenticator.

     AUTHENTICATORKEYUSAGE: key usage for authenticator.

     Create a new AP exchange using `shishi_ap()', and set ticket,
     options and authenticator checksum data from the DER encoding of
     the ASN.1 field using `shishi_ap_set_tktoptionsasn1usage()'.  A
     random session key is added to the authenticator, using the same
     keytype as the ticket.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_ap_tkt
-------------

 -- Function: Shishi_tkt * shishi_ap_tkt (Shishi_ap * AP)
     AP: structure that holds information about AP exchange

     Get Ticket from AP exchange.

     *Return value:* Returns the ticket from the AP exchange, or NULL if
     not yet set or an error occured.

shishi_ap_tkt_set
-----------------

 -- Function: void shishi_ap_tkt_set (Shishi_ap * AP, Shishi_tkt * TKT)
     AP: structure that holds information about AP exchange

     TKT: ticket to store in AP.

     Set the Ticket in the AP exchange.

shishi_ap_authenticator_cksumdata
---------------------------------

 -- Function: int shishi_ap_authenticator_cksumdata (Shishi_ap * AP,
          char * OUT, size_t * LEN)
     AP: structure that holds information about AP exchange

     OUT: output array that holds authenticator checksum data.

     LEN: on input, maximum length of output array that holds
     authenticator checksum data, on output actual length of output
     array that holds authenticator checksum data.

     Get checksum data from Authenticator.

     *Return value:* Returns `SHISHI_OK' if successful, or
     `SHISHI_TOO_SMALL_BUFFER' if buffer provided was too small (then
     `len' will hold necessary buffer size).

shishi_ap_authenticator_cksumdata_set
-------------------------------------

 -- Function: void shishi_ap_authenticator_cksumdata_set (Shishi_ap *
          AP, const char * AUTHENTICATORCKSUMDATA, size_t
          AUTHENTICATORCKSUMDATALEN)
     AP: structure that holds information about AP exchange

     AUTHENTICATORCKSUMDATA: input array with data to compute checksum
     on and store in Authenticator in AP-REQ.

     AUTHENTICATORCKSUMDATALEN: length of input array with data to
     compute checksum on and store in Authenticator in AP-REQ.

     Set the Authenticator Checksum Data in the AP exchange.  This is
     the data that will be checksumed, and the checksum placed in the
     checksum field.  It is not the actual checksum field.  See also
     shishi_ap_authenticator_cksumraw_set.

shishi_ap_authenticator_cksumraw_set
------------------------------------

 -- Function: void shishi_ap_authenticator_cksumraw_set (Shishi_ap *
          AP, int32_t AUTHENTICATORCKSUMTYPE, const char *
          AUTHENTICATORCKSUMRAW, size_t AUTHENTICATORCKSUMRAWLEN)
     AP: structure that holds information about AP exchange

     AUTHENTICATORCKSUMTYPE: authenticator checksum type to set in AP.

     AUTHENTICATORCKSUMRAW: input array with authenticator checksum
     field value to set in Authenticator in AP-REQ.

     AUTHENTICATORCKSUMRAWLEN: length of input array with authenticator
     checksum field value to set in Authenticator in AP-REQ.

     Set the Authenticator Checksum Data in the AP exchange.  This is
     the actual checksum field, not data to compute checksum on and then
     store in the checksum field.  See also
     shishi_ap_authenticator_cksumdata_set.

shishi_ap_authenticator_cksumtype
---------------------------------

 -- Function: int32_t shishi_ap_authenticator_cksumtype (Shishi_ap * AP)
     AP: structure that holds information about AP exchange

     Get the Authenticator Checksum Type in the AP exchange.

     *Return value:* Return the authenticator checksum type.

shishi_ap_authenticator_cksumtype_set
-------------------------------------

 -- Function: void shishi_ap_authenticator_cksumtype_set (Shishi_ap *
          AP, int32_t CKSUMTYPE)
     AP: structure that holds information about AP exchange

     CKSUMTYPE: authenticator checksum type to set in AP.

     Set the Authenticator Checksum Type in the AP exchange.

shishi_ap_authenticator
-----------------------

 -- Function: Shishi_asn1 shishi_ap_authenticator (Shishi_ap * AP)
     AP: structure that holds information about AP exchange

     Get ASN.1 Authenticator structure from AP exchange.

     *Return value:* Returns the Authenticator from the AP exchange, or
     NULL if not yet set or an error occured.

shishi_ap_authenticator_set
---------------------------

 -- Function: void shishi_ap_authenticator_set (Shishi_ap * AP,
          Shishi_asn1 AUTHENTICATOR)
     AP: structure that holds information about AP exchange

     AUTHENTICATOR: authenticator to store in AP.

     Set the Authenticator in the AP exchange.

shishi_ap_req
-------------

 -- Function: Shishi_asn1 shishi_ap_req (Shishi_ap * AP)
     AP: structure that holds information about AP exchange

     Get ASN.1 AP-REQ structure from AP exchange.

     *Return value:* Returns the AP-REQ from the AP exchange, or NULL if
     not yet set or an error occured.

shishi_ap_req_set
-----------------

 -- Function: void shishi_ap_req_set (Shishi_ap * AP, Shishi_asn1 APREQ)
     AP: structure that holds information about AP exchange

     APREQ: apreq to store in AP.

     Set the AP-REQ in the AP exchange.

shishi_ap_req_der
-----------------

 -- Function: int shishi_ap_req_der (Shishi_ap * AP, char ** OUT,
          size_t * OUTLEN)
     AP: structure that holds information about AP exchange

     OUT: pointer to output array with der encoding of AP-REQ.

     OUTLEN: pointer to length of output array with der encoding of
     AP-REQ.

     Build AP-REQ using `shishi_ap_req_build()' and DER encode it.
     `out' is allocated by this function, and it is the responsibility
     of caller to deallocate it.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_ap_req_der_set
---------------------

 -- Function: int shishi_ap_req_der_set (Shishi_ap * AP, char * DER,
          size_t DERLEN)
     AP: structure that holds information about AP exchange

     DER: input array with DER encoded AP-REQ.

     DERLEN: length of input array with DER encoded AP-REQ.

     DER decode AP-REQ and set it AP exchange.  If decoding fails, the
     AP-REQ in the AP exchange is lost.

     *Return value:* Returns SHISHI_OK.

shishi_ap_req_build
-------------------

 -- Function: int shishi_ap_req_build (Shishi_ap * AP)
     AP: structure that holds information about AP exchange

     Checksum data in authenticator and add ticket and authenticator to
     AP-REQ.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_ap_req_decode
--------------------

 -- Function: int shishi_ap_req_decode (Shishi_ap * AP)
     AP: structure that holds information about AP exchange

     Decode ticket in AP-REQ and set the Ticket fields in the AP
     exchange.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_ap_req_process_keyusage
------------------------------

 -- Function: int shishi_ap_req_process_keyusage (Shishi_ap * AP,
          Shishi_key * KEY, int32_t KEYUSAGE)
     AP: structure that holds information about AP exchange

     KEY: cryptographic key used to decrypt ticket in AP-REQ.

     KEYUSAGE: key usage to use during decryption, for normal AP-REQ's
     this is normally SHISHI_KEYUSAGE_APREQ_AUTHENTICATOR, for AP-REQ's
     part of TGS-REQ's, this is normally
     SHISHI_KEYUSAGE_TGSREQ_APREQ_AUTHENTICATOR.

     Decrypt ticket in AP-REQ using supplied key and decrypt
     Authenticator in AP-REQ using key in decrypted ticket, and on
     success set the Ticket and Authenticator fields in the AP exchange.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_ap_req_process
---------------------

 -- Function: int shishi_ap_req_process (Shishi_ap * AP, Shishi_key *
          KEY)
     AP: structure that holds information about AP exchange

     KEY: cryptographic key used to decrypt ticket in AP-REQ.

     Decrypt ticket in AP-REQ using supplied key and decrypt
     Authenticator in AP-REQ using key in decrypted ticket, and on
     success set the Ticket and Authenticator fields in the AP exchange.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_ap_req_asn1
------------------

 -- Function: int shishi_ap_req_asn1 (Shishi_ap * AP, Shishi_asn1 *
          APREQ)
     AP: structure that holds information about AP exchange

     APREQ: output AP-REQ variable.

     Build AP-REQ using `shishi_ap_req_build()' and return it.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_ap_key
-------------

 -- Function: Shishi_key * shishi_ap_key (Shishi_ap * AP)
     AP: structure that holds information about AP exchange

     Extract the application key from AP.  If subkeys are used, it is
     taken from the Authenticator, otherwise the session key is used.

     *Return value:* Return application key from AP.

shishi_ap_rep
-------------

 -- Function: Shishi_asn1 shishi_ap_rep (Shishi_ap * AP)
     AP: structure that holds information about AP exchange

     Get ASN.1 AP-REP structure from AP exchange.

     *Return value:* Returns the AP-REP from the AP exchange, or NULL if
     not yet set or an error occured.

shishi_ap_rep_set
-----------------

 -- Function: void shishi_ap_rep_set (Shishi_ap * AP, Shishi_asn1 APREP)
     AP: structure that holds information about AP exchange

     APREP: aprep to store in AP.

     Set the AP-REP in the AP exchange.

shishi_ap_rep_der
-----------------

 -- Function: int shishi_ap_rep_der (Shishi_ap * AP, char ** OUT,
          size_t * OUTLEN)
     AP: structure that holds information about AP exchange

     OUT: output array with newly allocated DER encoding of AP-REP.

     OUTLEN: length of output array with DER encoding of AP-REP.

     Build AP-REP using `shishi_ap_rep_build()' and DER encode it.
     `out' is allocated by this function, and it is the responsibility
     of caller to deallocate it.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_ap_rep_der_set
---------------------

 -- Function: int shishi_ap_rep_der_set (Shishi_ap * AP, char * DER,
          size_t DERLEN)
     AP: structure that holds information about AP exchange

     DER: input array with DER encoded AP-REP.

     DERLEN: length of input array with DER encoded AP-REP.

     DER decode AP-REP and set it AP exchange.  If decoding fails, the
     AP-REP in the AP exchange remains.

     *Return value:* Returns SHISHI_OK.

shishi_ap_rep_build
-------------------

 -- Function: int shishi_ap_rep_build (Shishi_ap * AP)
     AP: structure that holds information about AP exchange

     Checksum data in authenticator and add ticket and authenticator to
     AP-REP.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_ap_rep_asn1
------------------

 -- Function: int shishi_ap_rep_asn1 (Shishi_ap * AP, Shishi_asn1 *
          APREP)
     AP: structure that holds information about AP exchange

     APREP: output AP-REP variable.

     Build AP-REP using `shishi_ap_rep_build()' and return it.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_ap_rep_verify
--------------------

 -- Function: int shishi_ap_rep_verify (Shishi_ap * AP)
     AP: structure that holds information about AP exchange

     Verify AP-REP compared to Authenticator.

     *Return value:* Returns SHISHI_OK, SHISHI_APREP_VERIFY_FAILED or an
     error.

shishi_ap_rep_verify_der
------------------------

 -- Function: int shishi_ap_rep_verify_der (Shishi_ap * AP, char * DER,
          size_t DERLEN)
     AP: structure that holds information about AP exchange

     DER: input array with DER encoded AP-REP.

     DERLEN: length of input array with DER encoded AP-REP.

     DER decode AP-REP and set it in AP exchange using
     `shishi_ap_rep_der_set()' and verify it using
     `shishi_ap_rep_verify()'.

     *Return value:* Returns SHISHI_OK, SHISHI_APREP_VERIFY_FAILED or an
     error.

shishi_ap_rep_verify_asn1
-------------------------

 -- Function: int shishi_ap_rep_verify_asn1 (Shishi_ap * AP,
          Shishi_asn1 APREP)
     AP: structure that holds information about AP exchange

     APREP: input AP-REP.

     Set the AP-REP in the AP exchange using `shishi_ap_rep_set()' and
     verify it using `shishi_ap_rep_verify()'.

     *Return value:* Returns SHISHI_OK, SHISHI_APREP_VERIFY_FAILED or an
     error.

shishi_ap_encapreppart
----------------------

 -- Function: Shishi_asn1 shishi_ap_encapreppart (Shishi_ap * AP)
     AP: structure that holds information about AP exchange

     Get ASN.1 EncAPRepPart structure from AP exchange.

     *Return value:* Returns the EncAPREPPart from the AP exchange, or
     NULL if not yet set or an error occured.

shishi_ap_encapreppart_set
--------------------------

 -- Function: void shishi_ap_encapreppart_set (Shishi_ap * AP,
          Shishi_asn1 ENCAPREPPART)
     AP: structure that holds information about AP exchange

     ENCAPREPPART: EncAPRepPart to store in AP.

     Set the EncAPRepPart in the AP exchange.

shishi_ap_option2string
-----------------------

 -- Function: const char * shishi_ap_option2string (Shishi_apoptions
          OPTION)
     OPTION: enumerated AP-Option type, see Shishi_apoptions.

     Convert AP-Option type to AP-Option name string.  Note that
     `option' must be just one of the AP-Option types, it cannot be an
     binary ORed indicating several AP-Options.

     *Return value:* Returns static string with name of AP-Option that
     must not be deallocated, or "unknown" if AP-Option was not
     understood.

shishi_ap_string2option
-----------------------

 -- Function: Shishi_apoptions shishi_ap_string2option (const char *
          STR)
     STR: zero terminated character array with name of AP-Option, e.g.
     "use-session-key".

     Convert AP-Option name to AP-Option type.

     *Return value:* Returns enumerated type member corresponding to
     AP-Option, or 0 if string was not understood.

shishi_apreq
------------

 -- Function: Shishi_asn1 shishi_apreq (Shishi * HANDLE)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     This function creates a new AP-REQ, populated with some default
     values.

     *Return value:* Returns the AP-REQ or NULL on failure.

shishi_apreq_print
------------------

 -- Function: int shishi_apreq_print (Shishi * HANDLE, FILE * FH,
          Shishi_asn1 APREQ)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     FH: file handle open for writing.

     APREQ: AP-REQ to print.

     Print ASCII armored DER encoding of AP-REQ to file.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_apreq_save
-----------------

 -- Function: int shishi_apreq_save (Shishi * HANDLE, FILE * FH,
          Shishi_asn1 APREQ)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     FH: file handle open for writing.

     APREQ: AP-REQ to save.

     Save DER encoding of AP-REQ to file.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_apreq_to_file
--------------------

 -- Function: int shishi_apreq_to_file (Shishi * HANDLE, Shishi_asn1
          APREQ, int FILETYPE, const char * FILENAME)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     APREQ: AP-REQ to save.

     FILETYPE: input variable specifying type of file to be written,
     see Shishi_filetype.

     FILENAME: input variable with filename to write to.

     Write AP-REQ to file in specified TYPE.  The file will be
     truncated if it exists.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_apreq_parse
------------------

 -- Function: int shishi_apreq_parse (Shishi * HANDLE, FILE * FH,
          Shishi_asn1 * APREQ)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     FH: file handle open for reading.

     APREQ: output variable with newly allocated AP-REQ.

     Read ASCII armored DER encoded AP-REQ from file and populate given
     variable.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_apreq_read
-----------------

 -- Function: int shishi_apreq_read (Shishi * HANDLE, FILE * FH,
          Shishi_asn1 * APREQ)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     FH: file handle open for reading.

     APREQ: output variable with newly allocated AP-REQ.

     Read DER encoded AP-REQ from file and populate given variable.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_apreq_from_file
----------------------

 -- Function: int shishi_apreq_from_file (Shishi * HANDLE, Shishi_asn1
          * APREQ, int FILETYPE, const char * FILENAME)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     APREQ: output variable with newly allocated AP-REQ.

     FILETYPE: input variable specifying type of file to be read, see
     Shishi_filetype.

     FILENAME: input variable with filename to read from.

     Read AP-REQ from file in specified TYPE.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_apreq_set_authenticator
------------------------------

 -- Function: int shishi_apreq_set_authenticator (Shishi * HANDLE,
          Shishi_asn1 APREQ, int32_t ETYPE, uint32_t KVNO, const char *
          BUF, size_t BUFLEN)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     APREQ: AP-REQ to add authenticator field to.

     ETYPE: encryption type used to encrypt authenticator.

     KVNO: version of the key used to encrypt authenticator.

     BUF: input array with encrypted authenticator.

     BUFLEN: size of input array with encrypted authenticator.

     Set the encrypted authenticator field in the AP-REP.  The encrypted
     data is usually created by calling `shishi_encrypt()' on the DER
     encoded authenticator.  To save time, you may want to use
     `shishi_apreq_add_authenticator()' instead, which calculates the
     encrypted data and calls this function in one step.

     *Return value:* Returns SHISHI_OK on success.

shishi_apreq_add_authenticator
------------------------------

 -- Function: int shishi_apreq_add_authenticator (Shishi * HANDLE,
          Shishi_asn1 APREQ, Shishi_key * KEY, int KEYUSAGE,
          Shishi_asn1 AUTHENTICATOR)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     APREQ: AP-REQ to add authenticator field to.

     KEY: key to to use for encryption.

     KEYUSAGE: cryptographic key usage value to use in encryption.

     AUTHENTICATOR: authenticator as allocated by
     `shishi_authenticator()'.

     Encrypts DER encoded authenticator using key and store it in the
     AP-REQ.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_apreq_set_ticket
-----------------------

 -- Function: int shishi_apreq_set_ticket (Shishi * HANDLE, Shishi_asn1
          APREQ, Shishi_asn1 TICKET)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     APREQ: AP-REQ to add ticket field to.

     TICKET: input ticket to copy into AP-REQ ticket field.

     Copy ticket into AP-REQ.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_apreq_options
--------------------

 -- Function: int shishi_apreq_options (Shishi * HANDLE, Shishi_asn1
          APREQ, uint32_t * FLAGS)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     APREQ: AP-REQ to get options from.

     FLAGS: Output integer containing options from AP-REQ.

     Extract the AP-Options from AP-REQ into output integer.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_apreq_use_session_key_p
------------------------------

 -- Function: int shishi_apreq_use_session_key_p (Shishi * HANDLE,
          Shishi_asn1 APREQ)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     APREQ: AP-REQ as allocated by `shishi_apreq()'.

     Return non-0 iff the "Use session key" option is set in the AP-REQ.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_apreq_mutual_required_p
------------------------------

 -- Function: int shishi_apreq_mutual_required_p (Shishi * HANDLE,
          Shishi_asn1 APREQ)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     APREQ: AP-REQ as allocated by `shishi_apreq()'.

     Return non-0 iff the "Mutual required" option is set in the AP-REQ.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_apreq_options_set
------------------------

 -- Function: int shishi_apreq_options_set (Shishi * HANDLE,
          Shishi_asn1 APREQ, uint32_t OPTIONS)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     APREQ: AP-REQ as allocated by `shishi_apreq()'.

     OPTIONS: Options to set in AP-REQ.

     Set the AP-Options in AP-REQ to indicate integer.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_apreq_options_add
------------------------

 -- Function: int shishi_apreq_options_add (Shishi * HANDLE,
          Shishi_asn1 APREQ, uint32_t OPTION)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     APREQ: AP-REQ as allocated by `shishi_apreq()'.

     OPTION: Options to add in AP-REQ.

     Add the AP-Options in AP-REQ.  Options not set in input parameter
     `option' are preserved in the AP-REQ.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_apreq_options_remove
---------------------------

 -- Function: int shishi_apreq_options_remove (Shishi * HANDLE,
          Shishi_asn1 APREQ, uint32_t OPTION)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     APREQ: AP-REQ as allocated by `shishi_apreq()'.

     OPTION: Options to remove from AP-REQ.

     Remove the AP-Options from AP-REQ.  Options not set in input
     parameter `option' are preserved in the AP-REQ.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_apreq_get_authenticator_etype
------------------------------------

 -- Function: int shishi_apreq_get_authenticator_etype (Shishi *
          HANDLE, Shishi_asn1 APREQ, int32_t * ETYPE)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     APREQ: AP-REQ variable to get value from.

     ETYPE: output variable that holds the value.

     Extract AP-REQ.authenticator.etype.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_apreq_get_ticket
-----------------------

 -- Function: int shishi_apreq_get_ticket (Shishi * HANDLE, Shishi_asn1
          APREQ, Shishi_asn1 * TICKET)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     APREQ: AP-REQ variable to get ticket from.

     TICKET: output variable to hold extracted ticket.

     Extract ticket from AP-REQ.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_aprep
------------

 -- Function: Shishi_asn1 shishi_aprep (Shishi * HANDLE)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     This function creates a new AP-REP, populated with some default
     values.

     *Return value:* Returns the authenticator or NULL on failure.

shishi_aprep_print
------------------

 -- Function: int shishi_aprep_print (Shishi * HANDLE, FILE * FH,
          Shishi_asn1 APREP)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     FH: file handle open for writing.

     APREP: AP-REP to print.

     Print ASCII armored DER encoding of AP-REP to file.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_aprep_save
-----------------

 -- Function: int shishi_aprep_save (Shishi * HANDLE, FILE * FH,
          Shishi_asn1 APREP)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     FH: file handle open for writing.

     APREP: AP-REP to save.

     Save DER encoding of AP-REP to file.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_aprep_to_file
--------------------

 -- Function: int shishi_aprep_to_file (Shishi * HANDLE, Shishi_asn1
          APREP, int FILETYPE, const char * FILENAME)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     APREP: AP-REP to save.

     FILETYPE: input variable specifying type of file to be written,
     see Shishi_filetype.

     FILENAME: input variable with filename to write to.

     Write AP-REP to file in specified TYPE.  The file will be
     truncated if it exists.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_aprep_parse
------------------

 -- Function: int shishi_aprep_parse (Shishi * HANDLE, FILE * FH,
          Shishi_asn1 * APREP)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     FH: file handle open for reading.

     APREP: output variable with newly allocated AP-REP.

     Read ASCII armored DER encoded AP-REP from file and populate given
     variable.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_aprep_read
-----------------

 -- Function: int shishi_aprep_read (Shishi * HANDLE, FILE * FH,
          Shishi_asn1 * APREP)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     FH: file handle open for reading.

     APREP: output variable with newly allocated AP-REP.

     Read DER encoded AP-REP from file and populate given variable.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_aprep_from_file
----------------------

 -- Function: int shishi_aprep_from_file (Shishi * HANDLE, Shishi_asn1
          * APREP, int FILETYPE, const char * FILENAME)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     APREP: output variable with newly allocated AP-REP.

     FILETYPE: input variable specifying type of file to be read, see
     Shishi_filetype.

     FILENAME: input variable with filename to read from.

     Read AP-REP from file in specified TYPE.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_aprep_get_enc_part_etype
-------------------------------

 -- Function: int shishi_aprep_get_enc_part_etype (Shishi * HANDLE,
          Shishi_asn1 APREP, int32_t * ETYPE)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     APREP: AP-REP variable to get value from.

     ETYPE: output variable that holds the value.

     Extract AP-REP.enc-part.etype.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_encapreppart
-------------------

 -- Function: Shishi_asn1 shishi_encapreppart (Shishi * HANDLE)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     This function creates a new EncAPRepPart, populated with some
     default values.  It uses the current time as returned by the system
     for the ctime and cusec fields.

     *Return value:* Returns the encapreppart or NULL on failure.

shishi_encapreppart_print
-------------------------

 -- Function: int shishi_encapreppart_print (Shishi * HANDLE, FILE *
          FH, Shishi_asn1 ENCAPREPPART)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     FH: file handle open for writing.

     ENCAPREPPART: EncAPRepPart to print.

     Print ASCII armored DER encoding of EncAPRepPart to file.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_encapreppart_save
------------------------

 -- Function: int shishi_encapreppart_save (Shishi * HANDLE, FILE * FH,
          Shishi_asn1 ENCAPREPPART)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     FH: file handle open for writing.

     ENCAPREPPART: EncAPRepPart to save.

     Save DER encoding of EncAPRepPart to file.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_encapreppart_to_file
---------------------------

 -- Function: int shishi_encapreppart_to_file (Shishi * HANDLE,
          Shishi_asn1 ENCAPREPPART, int FILETYPE, const char * FILENAME)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     ENCAPREPPART: EncAPRepPart to save.

     FILETYPE: input variable specifying type of file to be written,
     see Shishi_filetype.

     FILENAME: input variable with filename to write to.

     Write EncAPRepPart to file in specified TYPE.  The file will be
     truncated if it exists.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_encapreppart_parse
-------------------------

 -- Function: int shishi_encapreppart_parse (Shishi * HANDLE, FILE *
          FH, Shishi_asn1 * ENCAPREPPART)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     FH: file handle open for reading.

     ENCAPREPPART: output variable with newly allocated EncAPRepPart.

     Read ASCII armored DER encoded EncAPRepPart from file and populate
     given variable.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_encapreppart_read
------------------------

 -- Function: int shishi_encapreppart_read (Shishi * HANDLE, FILE * FH,
          Shishi_asn1 * ENCAPREPPART)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     FH: file handle open for reading.

     ENCAPREPPART: output variable with newly allocated EncAPRepPart.

     Read DER encoded EncAPRepPart from file and populate given
     variable.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_encapreppart_from_file
-----------------------------

 -- Function: int shishi_encapreppart_from_file (Shishi * HANDLE,
          Shishi_asn1 * ENCAPREPPART, int FILETYPE, const char *
          FILENAME)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     ENCAPREPPART: output variable with newly allocated EncAPRepPart.

     FILETYPE: input variable specifying type of file to be read, see
     Shishi_filetype.

     FILENAME: input variable with filename to read from.

     Read EncAPRepPart from file in specified TYPE.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_encapreppart_get_key
---------------------------

 -- Function: int shishi_encapreppart_get_key (Shishi * HANDLE,
          Shishi_asn1 ENCAPREPPART, Shishi_key ** KEY)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     ENCAPREPPART: input EncAPRepPart variable.

     KEY: newly allocated key.

     Extract the subkey from the encrypted AP-REP part.

     *Return value:* Returns `SHISHI_OK' iff successful.

shishi_encapreppart_ctime
-------------------------

 -- Function: int shishi_encapreppart_ctime (Shishi * HANDLE,
          Shishi_asn1 ENCAPREPPART, char ** T)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     ENCAPREPPART: EncAPRepPart as allocated by `shishi_encapreppart()'.

     T: newly allocated zero-terminated character array with client
     time.

     Extract client time from EncAPRepPart.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_encapreppart_ctime_set
-----------------------------

 -- Function: int shishi_encapreppart_ctime_set (Shishi * HANDLE,
          Shishi_asn1 ENCAPREPPART, const char * T)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     ENCAPREPPART: EncAPRepPart as allocated by `shishi_encapreppart()'.

     T: string with generalized time value to store in EncAPRepPart.

     Store client time in EncAPRepPart.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_encapreppart_cusec_get
-----------------------------

 -- Function: int shishi_encapreppart_cusec_get (Shishi * HANDLE,
          Shishi_asn1 ENCAPREPPART, uint32_t * CUSEC)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     ENCAPREPPART: EncAPRepPart as allocated by `shishi_encapreppart()'.

     CUSEC: output integer with client microseconds field.

     Extract client microseconds field from EncAPRepPart.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_encapreppart_cusec_set
-----------------------------

 -- Function: int shishi_encapreppart_cusec_set (Shishi * HANDLE,
          Shishi_asn1 ENCAPREPPART, uint32_t CUSEC)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     ENCAPREPPART: EncAPRepPart as allocated by `shishi_encapreppart()'.

     CUSEC: client microseconds to set in authenticator, 0-999999.

     Set the cusec field in the Authenticator.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_encapreppart_seqnumber_get
---------------------------------

 -- Function: int shishi_encapreppart_seqnumber_get (Shishi * HANDLE,
          Shishi_asn1 ENCAPREPPART, uint32_t * SEQNUMBER)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     ENCAPREPPART: EncAPRepPart as allocated by `shishi_encapreppart()'.

     SEQNUMBER: output integer with sequence number field.

     Extract sequence number field from EncAPRepPart.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_encapreppart_seqnumber_remove
------------------------------------

 -- Function: int shishi_encapreppart_seqnumber_remove (Shishi *
          HANDLE, Shishi_asn1 ENCAPREPPART)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     ENCAPREPPART: encapreppart as allocated by `shishi_encapreppart()'.

     Remove sequence number field in EncAPRepPart.

     *Return value:* Returns `SHISHI_OK' iff successful.

shishi_encapreppart_seqnumber_set
---------------------------------

 -- Function: int shishi_encapreppart_seqnumber_set (Shishi * HANDLE,
          Shishi_asn1 ENCAPREPPART, uint32_t SEQNUMBER)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     ENCAPREPPART: encapreppart as allocated by `shishi_encapreppart()'.

     SEQNUMBER: integer with sequence number field to store in
     encapreppart.

     Store sequence number field in EncAPRepPart.

     *Return value:* Returns `SHISHI_OK' iff successful.

shishi_encapreppart_time_copy
-----------------------------

 -- Function: int shishi_encapreppart_time_copy (Shishi * HANDLE,
          Shishi_asn1 ENCAPREPPART, Shishi_asn1 AUTHENTICATOR)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     ENCAPREPPART: EncAPRepPart as allocated by `shishi_encapreppart()'.

     AUTHENTICATOR: Authenticator to copy time fields from.

     Copy time fields from Authenticator into EncAPRepPart.

     *Return value:* Returns SHISHI_OK iff successful.


File: shishi.info,  Node: SAFE and PRIV Functions,  Next: Ticket Functions,  Prev: AP-REQ and AP-REP Functions,  Up: Programming Manual

5.5 SAFE and PRIV Functions
===========================

The "KRB-SAFE" is an ASN.1 structure used by application client and
servers to exchange integrity protected data.  The integrity protection
is keyed, usually with a key agreed on via the AP exchange (*note
AP-REQ and AP-REP Functions::).  The following illustrates the KRB-SAFE
ASN.1 structure.


   KRB-SAFE        ::= [APPLICATION 20] SEQUENCE {
           pvno            [0] INTEGER (5),
           msg-type        [1] INTEGER (20),
           safe-body       [2] KRB-SAFE-BODY,
           cksum           [3] Checksum
   }

   KRB-SAFE-BODY   ::= SEQUENCE {
           user-data       [0] OCTET STRING,
           timestamp       [1] KerberosTime OPTIONAL,
           usec            [2] Microseconds OPTIONAL,
           seq-number      [3] UInt32 OPTIONAL,
           s-address       [4] HostAddress,
           r-address       [5] HostAddress OPTIONAL
   }

shishi_safe
-----------

 -- Function: int shishi_safe (Shishi * HANDLE, Shishi_safe ** SAFE)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     SAFE: pointer to new structure that holds information about SAFE
     exchange

     Create a new SAFE exchange.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_safe_done
----------------

 -- Function: void shishi_safe_done (Shishi_safe * SAFE)
     SAFE: structure that holds information about SAFE exchange

     Deallocate resources associated with SAFE exchange.  This should be
     called by the application when it no longer need to utilize the
     SAFE exchange handle.

shishi_safe_key
---------------

 -- Function: Shishi_key * shishi_safe_key (Shishi_safe * SAFE)
     SAFE: structure that holds information about SAFE exchange

     Get key structured from SAFE exchange.

     *Return value:* Returns the key used in the SAFE exchange, or NULL
     if not yet set or an error occured.

shishi_safe_key_set
-------------------

 -- Function: void shishi_safe_key_set (Shishi_safe * SAFE, Shishi_key
          * KEY)
     SAFE: structure that holds information about SAFE exchange

     KEY: key to store in SAFE.

     Set the Key in the SAFE exchange.

shishi_safe_safe
----------------

 -- Function: Shishi_asn1 shishi_safe_safe (Shishi_safe * SAFE)
     SAFE: structure that holds information about SAFE exchange

     Get ASN.1 SAFE structured from SAFE exchange.

     *Return value:* Returns the ASN.1 safe in the SAFE exchange, or
     NULL if not yet set or an error occured.

shishi_safe_safe_set
--------------------

 -- Function: void shishi_safe_safe_set (Shishi_safe * SAFE,
          Shishi_asn1 ASN1SAFE)
     SAFE: structure that holds information about SAFE exchange

     ASN1SAFE: KRB-SAFE to store in SAFE exchange.

     Set the KRB-SAFE in the SAFE exchange.

shishi_safe_safe_der
--------------------

 -- Function: int shishi_safe_safe_der (Shishi_safe * SAFE, char **
          OUT, size_t * OUTLEN)
     SAFE: safe as allocated by `shishi_safe()'.

     OUT: output array with newly allocated DER encoding of SAFE.

     OUTLEN: length of output array with DER encoding of SAFE.

     DER encode SAFE structure.  Typically `shishi_safe_build()' is used
     to build the SAFE structure first.  `out' is allocated by this
     function, and it is the responsibility of caller to deallocate it.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_safe_safe_der_set
------------------------

 -- Function: int shishi_safe_safe_der_set (Shishi_safe * SAFE, char *
          DER, size_t DERLEN)
     SAFE: safe as allocated by `shishi_safe()'.

     DER: input array with DER encoded KRB-SAFE.

     DERLEN: length of input array with DER encoded KRB-SAFE.

     DER decode KRB-SAFE and set it SAFE exchange.  If decoding fails,
     the KRB-SAFE in the SAFE exchange remains.

     *Return value:* Returns SHISHI_OK.

shishi_safe_print
-----------------

 -- Function: int shishi_safe_print (Shishi * HANDLE, FILE * FH,
          Shishi_asn1 SAFE)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     FH: file handle open for writing.

     SAFE: SAFE to print.

     Print ASCII armored DER encoding of SAFE to file.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_safe_save
----------------

 -- Function: int shishi_safe_save (Shishi * HANDLE, FILE * FH,
          Shishi_asn1 SAFE)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     FH: file handle open for writing.

     SAFE: SAFE to save.

     Save DER encoding of SAFE to file.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_safe_to_file
-------------------

 -- Function: int shishi_safe_to_file (Shishi * HANDLE, Shishi_asn1
          SAFE, int FILETYPE, const char * FILENAME)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     SAFE: SAFE to save.

     FILETYPE: input variable specifying type of file to be written,
     see Shishi_filetype.

     FILENAME: input variable with filename to write to.

     Write SAFE to file in specified TYPE.  The file will be truncated
     if it exists.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_safe_parse
-----------------

 -- Function: int shishi_safe_parse (Shishi * HANDLE, FILE * FH,
          Shishi_asn1 * SAFE)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     FH: file handle open for reading.

     SAFE: output variable with newly allocated SAFE.

     Read ASCII armored DER encoded SAFE from file and populate given
     variable.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_safe_read
----------------

 -- Function: int shishi_safe_read (Shishi * HANDLE, FILE * FH,
          Shishi_asn1 * SAFE)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     FH: file handle open for reading.

     SAFE: output variable with newly allocated SAFE.

     Read DER encoded SAFE from file and populate given variable.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_safe_from_file
---------------------

 -- Function: int shishi_safe_from_file (Shishi * HANDLE, Shishi_asn1 *
          SAFE, int FILETYPE, const char * FILENAME)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     SAFE: output variable with newly allocated SAFE.

     FILETYPE: input variable specifying type of file to be read, see
     Shishi_filetype.

     FILENAME: input variable with filename to read from.

     Read SAFE from file in specified TYPE.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_safe_cksum
-----------------

 -- Function: int shishi_safe_cksum (Shishi * HANDLE, Shishi_asn1 SAFE,
          int32_t * CKSUMTYPE, char ** CKSUM, size_t * CKSUMLEN)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     SAFE: safe as allocated by `shishi_safe()'.

     CKSUMTYPE: output checksum type.

     CKSUM: output array with newly allocated checksum data from SAFE.

     CKSUMLEN: output size of output checksum data buffer.

     Read checksum value from KRB-SAFE.  `cksum' is allocated by this
     function, and it is the responsibility of caller to deallocate it.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_safe_set_cksum
---------------------

 -- Function: int shishi_safe_set_cksum (Shishi * HANDLE, Shishi_asn1
          SAFE, int32_t CKSUMTYPE, const char * CKSUM, size_t CKSUMLEN)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     SAFE: safe as allocated by `shishi_safe()'.

     CKSUMTYPE: input checksum type to store in SAFE.

     CKSUM: input checksum data to store in SAFE.

     CKSUMLEN: size of input checksum data to store in SAFE.

     Store checksum value in SAFE.  A checksum is usually created by
     calling `shishi_checksum()' on some application specific data using
     the key from the ticket that is being used.  To save time, you may
     want to use `shishi_safe_build()' instead, which calculates the
     checksum and calls this function in one step.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_safe_user_data
---------------------

 -- Function: int shishi_safe_user_data (Shishi * HANDLE, Shishi_asn1
          SAFE, char ** USERDATA, size_t * USERDATALEN)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     SAFE: safe as allocated by `shishi_safe()'.

     USERDATA: output array with newly allocated user data from
     KRB-SAFE.

     USERDATALEN: output size of output user data buffer.

     Read user data value from KRB-SAFE.  `userdata' is allocated by
     this function, and it is the responsibility of caller to
     deallocate it.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_safe_set_user_data
-------------------------

 -- Function: int shishi_safe_set_user_data (Shishi * HANDLE,
          Shishi_asn1 SAFE, const char * USERDATA, size_t USERDATALEN)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     SAFE: safe as allocated by `shishi_safe()'.

     USERDATA: input user application to store in SAFE.

     USERDATALEN: size of input user application to store in SAFE.

     Set the application data in SAFE.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_safe_build
-----------------

 -- Function: int shishi_safe_build (Shishi_safe * SAFE, Shishi_key *
          KEY)
     SAFE: safe as allocated by `shishi_safe()'.

     KEY: key for session, used to compute checksum.

     Build checksum and set it in KRB-SAFE.  Note that this follows RFC
     1510bis and is incompatible with RFC 1510, although presumably few
     implementations use the RFC1510 algorithm.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_safe_verify
------------------

 -- Function: int shishi_safe_verify (Shishi_safe * SAFE, Shishi_key *
          KEY)
     SAFE: safe as allocated by `shishi_safe()'.

     KEY: key for session, used to verify checksum.

     Verify checksum in KRB-SAFE.  Note that this follows RFC 1510bis
     and is incompatible with RFC 1510, although presumably few
     implementations use the RFC1510 algorithm.

     *Return value:* Returns SHISHI_OK iff successful,
     SHISHI_SAFE_BAD_KEYTYPE if an incompatible key type is used, or
     SHISHI_SAFE_VERIFY_FAILED if the actual verification failed.

   The "KRB-PRIV" is an ASN.1 structure used by application client and
servers to exchange confidential data.  The confidentiality is keyed,
usually with a key agreed on via the AP exchange (*note AP-REQ and
AP-REP Functions::).  The following illustrates the KRB-PRIV ASN.1
structure.


   KRB-PRIV        ::= [APPLICATION 21] SEQUENCE {
           pvno            [0] INTEGER (5),
           msg-type        [1] INTEGER (21),
                           -- NOTE: there is no [2] tag
           enc-part        [3] EncryptedData -- EncKrbPrivPart
   }

   EncKrbPrivPart  ::= [APPLICATION 28] SEQUENCE {
           user-data       [0] OCTET STRING,
           timestamp       [1] KerberosTime OPTIONAL,
           usec            [2] Microseconds OPTIONAL,
           seq-number      [3] UInt32 OPTIONAL,
           s-address       [4] HostAddress -- sender's addr --,
           r-address       [5] HostAddress OPTIONAL -- recip's addr
   }

shishi_priv
-----------

 -- Function: int shishi_priv (Shishi * HANDLE, Shishi_priv ** PRIV)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     PRIV: pointer to new structure that holds information about PRIV
     exchange

     Create a new PRIV exchange.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_priv_done
----------------

 -- Function: void shishi_priv_done (Shishi_priv * PRIV)
     PRIV: structure that holds information about PRIV exchange

     Deallocate resources associated with PRIV exchange.  This should be
     called by the application when it no longer need to utilize the
     PRIV exchange handle.

shishi_priv_key
---------------

 -- Function: Shishi_key * shishi_priv_key (Shishi_priv * PRIV)
     PRIV: structure that holds information about PRIV exchange

     Get key from PRIV exchange.

     *Return value:* Returns the key used in the PRIV exchange, or NULL
     if not yet set or an error occured.

shishi_priv_key_set
-------------------

 -- Function: void shishi_priv_key_set (Shishi_priv * PRIV, Shishi_key
          * KEY)
     PRIV: structure that holds information about PRIV exchange

     KEY: key to store in PRIV.

     Set the Key in the PRIV exchange.

shishi_priv_priv
----------------

 -- Function: Shishi_asn1 shishi_priv_priv (Shishi_priv * PRIV)
     PRIV: structure that holds information about PRIV exchange

     Get ASN.1 PRIV structure in PRIV exchange.

     *Return value:* Returns the ASN.1 priv in the PRIV exchange, or
     NULL if not yet set or an error occured.

shishi_priv_priv_set
--------------------

 -- Function: void shishi_priv_priv_set (Shishi_priv * PRIV,
          Shishi_asn1 ASN1PRIV)
     PRIV: structure that holds information about PRIV exchange

     ASN1PRIV: KRB-PRIV to store in PRIV exchange.

     Set the KRB-PRIV in the PRIV exchange.

shishi_priv_priv_der
--------------------

 -- Function: int shishi_priv_priv_der (Shishi_priv * PRIV, char **
          OUT, size_t * OUTLEN)
     PRIV: priv as allocated by `shishi_priv()'.

     OUT: output array with newly allocated DER encoding of PRIV.

     OUTLEN: length of output array with DER encoding of PRIV.

     DER encode PRIV structure.  Typically `shishi_priv_build()' is used
     to build the PRIV structure first.  `out' is allocated by this
     function, and it is the responsibility of caller to deallocate it.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_priv_priv_der_set
------------------------

 -- Function: int shishi_priv_priv_der_set (Shishi_priv * PRIV, char *
          DER, size_t DERLEN)
     PRIV: priv as allocated by `shishi_priv()'.

     DER: input array with DER encoded KRB-PRIV.

     DERLEN: length of input array with DER encoded KRB-PRIV.

     DER decode KRB-PRIV and set it PRIV exchange.  If decoding fails,
     the KRB-PRIV in the PRIV exchange remains.

     *Return value:* Returns SHISHI_OK.

shishi_priv_encprivpart
-----------------------

 -- Function: Shishi_asn1 shishi_priv_encprivpart (Shishi_priv * PRIV)
     PRIV: structure that holds information about PRIV exchange

     Get ASN.1 EncPrivPart structure from PRIV exchange.

     *Return value:* Returns the ASN.1 encprivpart in the PRIV
     exchange, or NULL if not yet set or an error occured.

shishi_priv_encprivpart_set
---------------------------

 -- Function: void shishi_priv_encprivpart_set (Shishi_priv * PRIV,
          Shishi_asn1 ASN1ENCPRIVPART)
     PRIV: structure that holds information about PRIV exchange

     ASN1ENCPRIVPART: ENCPRIVPART to store in PRIV exchange.

     Set the ENCPRIVPART in the PRIV exchange.

shishi_priv_encprivpart_der
---------------------------

 -- Function: int shishi_priv_encprivpart_der (Shishi_priv * PRIV, char
          ** OUT, size_t * OUTLEN)
     PRIV: priv as allocated by `shishi_priv()'.

     OUT: output array with newly allocated DER encoding of ENCPRIVPART.

     OUTLEN: length of output array with DER encoding of ENCPRIVPART.

     DER encode ENCPRIVPART structure.  `out' is allocated by this
     function, and it is the responsibility of caller to deallocate it.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_priv_encprivpart_der_set
-------------------------------

 -- Function: int shishi_priv_encprivpart_der_set (Shishi_priv * PRIV,
          char * DER, size_t DERLEN)
     PRIV: priv as allocated by `shishi_priv()'.

     DER: input array with DER encoded ENCPRIVPART.

     DERLEN: length of input array with DER encoded ENCPRIVPART.

     DER decode ENCPRIVPART and set it PRIV exchange.  If decoding
     fails, the ENCPRIVPART in the PRIV exchange remains.

     *Return value:* Returns SHISHI_OK.

shishi_priv_print
-----------------

 -- Function: int shishi_priv_print (Shishi * HANDLE, FILE * FH,
          Shishi_asn1 PRIV)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     FH: file handle open for writing.

     PRIV: PRIV to print.

     Print ASCII armored DER encoding of PRIV to file.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_priv_save
----------------

 -- Function: int shishi_priv_save (Shishi * HANDLE, FILE * FH,
          Shishi_asn1 PRIV)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     FH: file handle open for writing.

     PRIV: PRIV to save.

     Save DER encoding of PRIV to file.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_priv_to_file
-------------------

 -- Function: int shishi_priv_to_file (Shishi * HANDLE, Shishi_asn1
          PRIV, int FILETYPE, const char * FILENAME)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     PRIV: PRIV to save.

     FILETYPE: input variable specifying type of file to be written,
     see Shishi_filetype.

     FILENAME: input variable with filename to write to.

     Write PRIV to file in specified TYPE.  The file will be truncated
     if it exists.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_priv_parse
-----------------

 -- Function: int shishi_priv_parse (Shishi * HANDLE, FILE * FH,
          Shishi_asn1 * PRIV)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     FH: file handle open for reading.

     PRIV: output variable with newly allocated PRIV.

     Read ASCII armored DER encoded PRIV from file and populate given
     variable.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_priv_read
----------------

 -- Function: int shishi_priv_read (Shishi * HANDLE, FILE * FH,
          Shishi_asn1 * PRIV)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     FH: file handle open for reading.

     PRIV: output variable with newly allocated PRIV.

     Read DER encoded PRIV from file and populate given variable.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_priv_from_file
---------------------

 -- Function: int shishi_priv_from_file (Shishi * HANDLE, Shishi_asn1 *
          PRIV, int FILETYPE, const char * FILENAME)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     PRIV: output variable with newly allocated PRIV.

     FILETYPE: input variable specifying type of file to be read, see
     Shishi_filetype.

     FILENAME: input variable with filename to read from.

     Read PRIV from file in specified TYPE.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_priv_enc_part_etype
--------------------------

 -- Function: int shishi_priv_enc_part_etype (Shishi * HANDLE,
          Shishi_asn1 PRIV, int32_t * ETYPE)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     PRIV: PRIV variable to get value from.

     ETYPE: output variable that holds the value.

     Extract PRIV.enc-part.etype.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_priv_set_enc_part
------------------------

 -- Function: int shishi_priv_set_enc_part (Shishi * HANDLE,
          Shishi_asn1 PRIV, int32_t ETYPE, const char * ENCPART, size_t
          ENCPARTLEN)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     PRIV: priv as allocated by `shishi_priv()'.

     ETYPE: input encryption type to store in PRIV.

     ENCPART: input encrypted data to store in PRIV.

     ENCPARTLEN: size of input encrypted data to store in PRIV.

     Store encrypted data in PRIV.  The encrypted data is usually
     created by calling `shishi_encrypt()' on some application specific
     data using the key from the ticket that is being used.  To save
     time, you may want to use `shishi_priv_build()' instead, which
     encryptes the data and calls this function in one step.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_encprivpart_user_data
----------------------------

 -- Function: int shishi_encprivpart_user_data (Shishi * HANDLE,
          Shishi_asn1 ENCPRIVPART, char ** USERDATA, size_t *
          USERDATALEN)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     ENCPRIVPART: encprivpart as allocated by `shishi_priv()'.

     USERDATA: output array with newly allocated user data from
     KRB-PRIV.

     USERDATALEN: output size of output user data buffer.

     Read user data value from KRB-PRIV.  `userdata' is allocated by
     this function, and it is the responsibility of caller to
     deallocate it.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_encprivpart_set_user_data
--------------------------------

 -- Function: int shishi_encprivpart_set_user_data (Shishi * HANDLE,
          Shishi_asn1 ENCPRIVPART, const char * USERDATA, size_t
          USERDATALEN)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     ENCPRIVPART: encprivpart as allocated by `shishi_priv()'.

     USERDATA: input user application to store in PRIV.

     USERDATALEN: size of input user application to store in PRIV.

     Set the application data in PRIV.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_priv_build
-----------------

 -- Function: int shishi_priv_build (Shishi_priv * PRIV, Shishi_key *
          KEY)
     PRIV: priv as allocated by `shishi_priv()'.

     KEY: key for session, used to encrypt data.

     Build checksum and set it in KRB-PRIV.  Note that this follows RFC
     1510bis and is incompatible with RFC 1510, although presumably few
     implementations use the RFC1510 algorithm.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_priv_process
-------------------

 -- Function: int shishi_priv_process (Shishi_priv * PRIV, Shishi_key *
          KEY)
     PRIV: priv as allocated by `shishi_priv()'.

     KEY: key to use to decrypt EncPrivPart.

     Decrypt encrypted data in KRB-PRIV and set the EncPrivPart in the
     PRIV exchange.

     *Return value:* Returns SHISHI_OK iff successful,
     SHISHI_PRIV_BAD_KEYTYPE if an incompatible key type is used, or
     SHISHI_CRYPTO_ERROR if the actual decryption failed.


File: shishi.info,  Node: Ticket Functions,  Next: AS Functions,  Prev: SAFE and PRIV Functions,  Up: Programming Manual

5.6 Ticket Functions
====================

A Ticket is an ASN.1 structured that can be used to authenticate the
holder to services.  It contain an encrypted part, which the ticket
holder cannot see, but can be encrypted by the service, and various
information about the user and service, including an encryption key to
use for the connection.  *Note Ticket (ASN.1) Functions::, for more
details on the ASN.1 structure of a ticket.

shishi_tkt
----------

 -- Function: int shishi_tkt (Shishi * HANDLE, Shishi_tkt ** TKT)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     TKT: output variable with newly allocated ticket.

     Create a new ticket handle.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_tkt2
-----------

 -- Function: Shishi_tkt * shishi_tkt2 (Shishi * HANDLE, Shishi_asn1
          TICKET, Shishi_asn1 ENCKDCREPPART, Shishi_asn1 KDCREP)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     TICKET: input variable with ticket.

     ENCKDCREPPART: input variable with auxiliary ticket information.

     KDCREP: input variable with KDC-REP ticket information.

     Create a new ticket handle.

     *Return value:* Returns new ticket handle, or `NULL' on error.

shishi_tkt_done
---------------

 -- Function: void shishi_tkt_done (Shishi_tkt * TKT)
     TKT: input variable with ticket info.

     Deallocate resources associated with ticket.  The ticket must not
     be used again after this call.

shishi_tkt_ticket
-----------------

 -- Function: Shishi_asn1 shishi_tkt_ticket (Shishi_tkt * TKT)
     TKT: input variable with ticket info.

     Get ASN.1 Ticket structure from ticket.

     *Return value:* Returns actual ticket.

shishi_tkt_ticket_set
---------------------

 -- Function: void shishi_tkt_ticket_set (Shishi_tkt * TKT, Shishi_asn1
          TICKET)
     TKT: input variable with ticket info.

     TICKET: ASN.1 Ticket to store in ticket.

     Set the ASN.1 Ticket in the Ticket.

shishi_tkt_enckdcreppart
------------------------

 -- Function: Shishi_asn1 shishi_tkt_enckdcreppart (Shishi_tkt * TKT)
     TKT: input variable with ticket info.

     Get ASN.1 EncKDCRepPart structure from ticket.

     *Return value:* Returns auxiliary ticket information.

shishi_tkt_enckdcreppart_set
----------------------------

 -- Function: void shishi_tkt_enckdcreppart_set (Shishi_tkt * TKT,
          Shishi_asn1 ENCKDCREPPART)
     TKT: structure that holds information about Ticket exchange

     ENCKDCREPPART: EncKDCRepPart to store in Ticket.

     Set the EncKDCRepPart in the Ticket.

shishi_tkt_kdcrep
-----------------

 -- Function: Shishi_asn1 shishi_tkt_kdcrep (Shishi_tkt * TKT)
     TKT: input variable with ticket info.

     Get ASN.1 KDCRep structure from ticket.

     *Return value:* Returns KDC-REP information.

shishi_tkt_encticketpart
------------------------

 -- Function: Shishi_asn1 shishi_tkt_encticketpart (Shishi_tkt * TKT)
     TKT: input variable with ticket info.

     Get ASN.1 EncTicketPart structure from ticket.

     *Return value:* Returns EncTicketPart information.

shishi_tkt_encticketpart_set
----------------------------

 -- Function: void shishi_tkt_encticketpart_set (Shishi_tkt * TKT,
          Shishi_asn1 ENCTICKETPART)
     TKT: input variable with ticket info.

     ENCTICKETPART: encticketpart to store in ticket.

     Set the EncTicketPart in the Ticket.

shishi_tkt_key
--------------

 -- Function: Shishi_key * shishi_tkt_key (Shishi_tkt * TKT)
     TKT: input variable with ticket info.

     Get key used in ticket, by looking first in EncKDCRepPart and then
     in EncTicketPart.  If key is already populated, it is not extracted
     again.

     *Return value:* Returns key extracted from EncKDCRepPart or
     EncTicketPart.

shishi_tkt_key_set
------------------

 -- Function: int shishi_tkt_key_set (Shishi_tkt * TKT, Shishi_key *
          KEY)
     TKT: input variable with ticket info.

     KEY: key to store in ticket.

     Set the key in the EncTicketPart.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_tkt_client
-----------------

 -- Function: int shishi_tkt_client (Shishi_tkt * TKT, char ** CLIENT,
          size_t * CLIENTLEN)
     TKT: input variable with ticket info.

     CLIENT: pointer to newly allocated zero terminated string
     containing principal name.  May be `NULL' (to only populate
     `clientlen').

     CLIENTLEN: pointer to length of `client' on output, excluding
     terminating zero.  May be `NULL' (to only populate `client').

     Represent client principal name in Ticket KDC-REP as
     zero-terminated string.  The string is allocate by this function,
     and it is the responsibility of the caller to deallocate it.  Note
     that the output length `clientlen' does not include the terminating
     zero.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_tkt_client_p
-------------------

 -- Function: int shishi_tkt_client_p (Shishi_tkt * TKT, const char *
          CLIENT)
     TKT: input variable with ticket info.

     CLIENT: client name of ticket.

     Determine if ticket is for specified client.

     *Return value:* Returns non-0 iff ticket is for specified client.

shishi_tkt_clientrealm
----------------------

 -- Function: int shishi_tkt_clientrealm (Shishi_tkt * TKT, char **
          CLIENT, size_t * CLIENTLEN)
     TKT: input variable with ticket info.

     CLIENT: pointer to newly allocated zero terminated string
     containing principal name and realm.  May be `NULL' (to only
     populate `clientlen').

     CLIENTLEN: pointer to length of `client' on output, excluding
     terminating zero.  May be `NULL' (to only populate `client').

     Convert cname and realm fields from AS-REQ to printable principal
     name format.  The string is allocate by this function, and it is
     the responsibility of the caller to deallocate it.  Note that the
     output length `clientlen' does not include the terminating zero.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_tkt_clientrealm_p
------------------------

 -- Function: int shishi_tkt_clientrealm_p (Shishi_tkt * TKT, const
          char * CLIENT)
     TKT: input variable with ticket info.

     CLIENT: principal name (client name and realm) of ticket.

     Determine if ticket is for specified client principal.

     *Return value:* Returns non-0 iff ticket is for specified client
     principal.

shishi_tkt_realm
----------------

 -- Function: int shishi_tkt_realm (Shishi_tkt * TKT, char ** REALM,
          size_t * REALMLEN)
     TKT: input variable with ticket info.

     REALM: pointer to newly allocated character array with realm name.

     REALMLEN: length of newly allocated character array with realm
     name.

     Extract realm of server in ticket.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_tkt_server
-----------------

 -- Function: int shishi_tkt_server (Shishi_tkt * TKT, char ** SERVER,
          size_t * SERVERLEN)
     TKT: input variable with ticket info.

     SERVER: pointer to newly allocated zero terminated string
     containing principal name.  May be `NULL' (to only populate
     `serverlen').

     SERVERLEN: pointer to length of `server' on output, excluding
     terminating zero.  May be `NULL' (to only populate `server').

     Represent server principal name in Ticket as zero-terminated
     string.  The string is allocate by this function, and it is the
     responsibility of the caller to deallocate it.  Note that the
     output length `serverlen' does not include the terminating zero.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_tkt_server_p
-------------------

 -- Function: int shishi_tkt_server_p (Shishi_tkt * TKT, const char *
          SERVER)
     TKT: input variable with ticket info.

     SERVER: server name of ticket.

     Determine if ticket is for specified server.

     *Return value:* Returns non-0 iff ticket is for specified server.

shishi_tkt_flags
----------------

 -- Function: int shishi_tkt_flags (Shishi_tkt * TKT, uint32_t * FLAGS)
     TKT: input variable with ticket info.

     FLAGS: pointer to output integer with flags.

     Extract flags in ticket (i.e., EncKDCRepPart).

     *Return value:* Returns SHISHI_OK iff successful.

shishi_tkt_flags_set
--------------------

 -- Function: int shishi_tkt_flags_set (Shishi_tkt * TKT, uint32_t
          FLAGS)
     TKT: input variable with ticket info.

     FLAGS: integer with flags to store in ticket.

     Set flags in ticket, i.e., both EncTicketPart and EncKDCRepPart.
     Note that this reset any already existing flags.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_tkt_flags_add
--------------------

 -- Function: int shishi_tkt_flags_add (Shishi_tkt * TKT, uint32_t FLAG)
     TKT: input variable with ticket info.

     FLAG: integer with flags to store in ticket.

     Add ticket flags to Ticket and EncKDCRepPart.  This preserves all
     existing options.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_tkt_forwardable_p
------------------------

 -- Function: int shishi_tkt_forwardable_p (Shishi_tkt * TKT)
     TKT: input variable with ticket info.

     Determine if ticket is forwardable.

     The FORWARDABLE flag in a ticket is normally only interpreted by
     the ticket-granting service. It can be ignored by application
     servers.  The FORWARDABLE flag has an interpretation similar to
     that of the PROXIABLE flag, except ticket-granting tickets may also
     be issued with different network addresses. This flag is reset by
     default, but users MAY request that it be set by setting the
     FORWARDABLE option in the AS request when they request their
     initial ticket-granting ticket.

     *Return value:* Returns non-0 iff forwardable flag is set in
     ticket.

shishi_tkt_forwarded_p
----------------------

 -- Function: int shishi_tkt_forwarded_p (Shishi_tkt * TKT)
     TKT: input variable with ticket info.

     Determine if ticket is forwarded.

     The FORWARDED flag is set by the TGS when a client presents a
     ticket with the FORWARDABLE flag set and requests a forwarded
     ticket by specifying the FORWARDED KDC option and supplying a set
     of addresses for the new ticket. It is also set in all tickets
     issued based on tickets with the FORWARDED flag set. Application
     servers may choose to process FORWARDED tickets differently than
     non-FORWARDED tickets.

     *Return value:* Returns non-0 iff forwarded flag is set in ticket.

shishi_tkt_proxiable_p
----------------------

 -- Function: int shishi_tkt_proxiable_p (Shishi_tkt * TKT)
     TKT: input variable with ticket info.

     Determine if ticket is proxiable.

     The PROXIABLE flag in a ticket is normally only interpreted by the
     ticket-granting service. It can be ignored by application servers.
     When set, this flag tells the ticket-granting server that it is OK
     to issue a new ticket (but not a ticket-granting ticket) with a
     different network address based on this ticket. This flag is set if
     requested by the client on initial authentication. By default, the
     client will request that it be set when requesting a
     ticket-granting ticket, and reset when requesting any other ticket.

     *Return value:* Returns non-0 iff proxiable flag is set in ticket.

shishi_tkt_proxy_p
------------------

 -- Function: int shishi_tkt_proxy_p (Shishi_tkt * TKT)
     TKT: input variable with ticket info.

     Determine if ticket is proxy ticket.

     The PROXY flag is set in a ticket by the TGS when it issues a proxy
     ticket.  Application servers MAY check this flag and at their
     option they MAY require additional authentication from the agent
     presenting the proxy in order to provide an audit trail.

     *Return value:* Returns non-0 iff proxy flag is set in ticket.

shishi_tkt_may_postdate_p
-------------------------

 -- Function: int shishi_tkt_may_postdate_p (Shishi_tkt * TKT)
     TKT: input variable with ticket info.

     Determine if ticket may be used to grant postdated tickets.

     The MAY-POSTDATE flag in a ticket is normally only interpreted by
     the ticket-granting service. It can be ignored by application
     servers.  This flag MUST be set in a ticket-granting ticket in
     order to issue a postdated ticket based on the presented ticket. It
     is reset by default; it MAY be requested by a client by setting the
     ALLOW- POSTDATE option in the KRB_AS_REQ message.  This flag does
     not allow a client to obtain a postdated ticket-granting ticket;
     postdated ticket-granting tickets can only by obtained by
     requesting the postdating in the KRB_AS_REQ message. The life
     (endtime-starttime) of a postdated ticket will be the remaining
     life of the ticket-granting ticket at the time of the request,
     unless the RENEWABLE option is also set, in which case it can be
     the full life (endtime-starttime) of the ticket-granting ticket.
     The KDC MAY limit how far in the future a ticket may be postdated.

     *Return value:* Returns non-0 iff may-postdate flag is set in
     ticket.

shishi_tkt_postdated_p
----------------------

 -- Function: int shishi_tkt_postdated_p (Shishi_tkt * TKT)
     TKT: input variable with ticket info.

     Determine if ticket is postdated.

     The POSTDATED flag indicates that a ticket has been postdated. The
     application server can check the authtime field in the ticket to
     see when the original authentication occurred. Some services MAY
     choose to reject postdated tickets, or they may only accept them
     within a certain period after the original authentication. When the
     KDC issues a POSTDATED ticket, it will also be marked as INVALID,
     so that the application client MUST present the ticket to the KDC
     to be validated before use.

     *Return value:* Returns non-0 iff postdated flag is set in ticket.

shishi_tkt_invalid_p
--------------------

 -- Function: int shishi_tkt_invalid_p (Shishi_tkt * TKT)
     TKT: input variable with ticket info.

     Determine if ticket is invalid.

     The INVALID flag indicates that a ticket is invalid. Application
     servers MUST reject tickets which have this flag set. A postdated
     ticket will be issued in this form. Invalid tickets MUST be
     validated by the KDC before use, by presenting them to the KDC in a
     TGS request with the VALIDATE option specified. The KDC will only
     validate tickets after their starttime has passed. The validation
     is required so that postdated tickets which have been stolen before
     their starttime can be rendered permanently invalid (through a
     hot-list mechanism).

     *Return value:* Returns non-0 iff invalid flag is set in ticket.

shishi_tkt_renewable_p
----------------------

 -- Function: int shishi_tkt_renewable_p (Shishi_tkt * TKT)
     TKT: input variable with ticket info.

     Determine if ticket is renewable.

     The RENEWABLE flag in a ticket is normally only interpreted by the
     ticket-granting service (discussed below in section 3.3). It can
     usually be ignored by application servers. However, some
     particularly careful application servers MAY disallow renewable
     tickets.

     *Return value:* Returns non-0 iff renewable flag is set in ticket.

shishi_tkt_initial_p
--------------------

 -- Function: int shishi_tkt_initial_p (Shishi_tkt * TKT)
     TKT: input variable with ticket info.

     Determine if ticket was issued using AS exchange.

     The INITIAL flag indicates that a ticket was issued using the AS
     protocol, rather than issued based on a ticket-granting ticket.
     Application servers that want to require the demonstrated knowledge
     of a client's secret key (e.g. a password-changing program) can
     insist that this flag be set in any tickets they accept, and thus
     be assured that the client's key was recently presented to the
     application client.

     *Return value:* Returns non-0 iff initial flag is set in ticket.

shishi_tkt_pre_authent_p
------------------------

 -- Function: int shishi_tkt_pre_authent_p (Shishi_tkt * TKT)
     TKT: input variable with ticket info.

     Determine if ticket was pre-authenticated.

     The PRE-AUTHENT and HW-AUTHENT flags provide additional information
     about the initial authentication, regardless of whether the current
     ticket was issued directly (in which case INITIAL will also be set)
     or issued on the basis of a ticket-granting ticket (in which case
     the INITIAL flag is clear, but the PRE-AUTHENT and HW-AUTHENT flags
     are carried forward from the ticket-granting ticket).

     *Return value:* Returns non-0 iff pre-authent flag is set in
     ticket.

shishi_tkt_hw_authent_p
-----------------------

 -- Function: int shishi_tkt_hw_authent_p (Shishi_tkt * TKT)
     TKT: input variable with ticket info.

     Determine if ticket is authenticated using a hardware token.

     The PRE-AUTHENT and HW-AUTHENT flags provide additional information
     about the initial authentication, regardless of whether the current
     ticket was issued directly (in which case INITIAL will also be set)
     or issued on the basis of a ticket-granting ticket (in which case
     the INITIAL flag is clear, but the PRE-AUTHENT and HW-AUTHENT flags
     are carried forward from the ticket-granting ticket).

     *Return value:* Returns non-0 iff hw-authent flag is set in ticket.

shishi_tkt_transited_policy_checked_p
-------------------------------------

 -- Function: int shishi_tkt_transited_policy_checked_p (Shishi_tkt *
          TKT)
     TKT: input variable with ticket info.

     Determine if ticket has been policy checked for transit.

     The application server is ultimately responsible for accepting or
     rejecting authentication and SHOULD check that only suitably
     trusted KDCs are relied upon to authenticate a principal.  The
     transited field in the ticket identifies which realms (and thus
     which KDCs) were involved in the authentication process and an
     application server would normally check this field. If any of these
     are untrusted to authenticate the indicated client principal
     (probably determined by a realm-based policy), the authentication
     attempt MUST be rejected. The presence of trusted KDCs in this list
     does not provide any guarantee; an untrusted KDC may have
     fabricated the list.

     While the end server ultimately decides whether authentication is
     valid, the KDC for the end server's realm MAY apply a realm
     specific policy for validating the transited field and accepting
     credentials for cross-realm authentication. When the KDC applies
     such checks and accepts such cross-realm authentication it will set
     the TRANSITED-POLICY-CHECKED flag in the service tickets it issues
     based on the cross-realm TGT. A client MAY request that the KDCs
     not check the transited field by setting the
     DISABLE-TRANSITED-CHECK flag. KDCs are encouraged but not required
     to honor this flag.

     Application servers MUST either do the transited-realm checks
     themselves, or reject cross-realm tickets without TRANSITED-POLICY-
     CHECKED set.

     *Return value:* Returns non-0 iff transited-policy-checked flag is
     set in ticket.

shishi_tkt_ok_as_delegate_p
---------------------------

 -- Function: int shishi_tkt_ok_as_delegate_p (Shishi_tkt * TKT)
     TKT: input variable with ticket info.

     Determine if ticket is ok as delegated ticket.

     The copy of the ticket flags in the encrypted part of the KDC reply
     may have the OK-AS-DELEGATE flag set to indicates to the client
     that the server specified in the ticket has been determined by
     policy of the realm to be a suitable recipient of delegation.  A
     client can use the presence of this flag to help it make a decision
     whether to delegate credentials (either grant a proxy or a
     forwarded ticket- granting ticket) to this server.  It is
     acceptable to ignore the value of this flag. When setting this
     flag, an administrator should consider the security and placement
     of the server on which the service will run, as well as whether the
     service requires the use of delegated credentials.

     *Return value:* Returns non-0 iff ok-as-delegate flag is set in
     ticket.

shishi_tkt_keytype
------------------

 -- Function: int shishi_tkt_keytype (Shishi_tkt * TKT, int32_t * ETYPE)
     TKT: input variable with ticket info.

     ETYPE: pointer to encryption type that is set, see Shishi_etype.

     Extract encryption type of key in ticket (really EncKDCRepPart).

     *Return value:* Returns SHISHI_OK iff successful.

shishi_tkt_keytype_fast
-----------------------

 -- Function: int32_t shishi_tkt_keytype_fast (Shishi_tkt * TKT)
     TKT: input variable with ticket info.

     Extract encryption type of key in ticket (really EncKDCRepPart).

     *Return value:* Returns encryption type of session key in ticket
     (really EncKDCRepPart), or -1 on error.

shishi_tkt_keytype_p
--------------------

 -- Function: int shishi_tkt_keytype_p (Shishi_tkt * TKT, int32_t ETYPE)
     TKT: input variable with ticket info.

     ETYPE: encryption type, see Shishi_etype.

     Determine if key in ticket (really EncKDCRepPart) is of specified
     key type (really encryption type).

     *Return value:* Returns non-0 iff key in ticket is of specified
     encryption type.

shishi_tkt_lastreqc
-------------------

 -- Function: time_t shishi_tkt_lastreqc (Shishi_tkt * TKT,
          Shishi_lrtype LRTYPE)
     TKT: input variable with ticket info.

     LRTYPE: lastreq type to extract, see Shishi_lrtype.  E.g.,
     SHISHI_LRTYPE_LAST_REQUEST.

     Extract C time corresponding to given lastreq type field in the
     ticket.

     *Return value:* Returns C time interpretation of the specified
     lastreq field, or (time_t) -1.

shishi_tkt_authctime
--------------------

 -- Function: time_t shishi_tkt_authctime (Shishi_tkt * TKT)
     TKT: input variable with ticket info.

     Extract C time corresponding to the authtime field.  The field
     holds the time when the original authentication took place that
     later resulted in this ticket.

     *Return value:* Returns C time interpretation of the endtime in
     ticket.

shishi_tkt_startctime
---------------------

 -- Function: time_t shishi_tkt_startctime (Shishi_tkt * TKT)
     TKT: input variable with ticket info.

     Extract C time corresponding to the starttime field.  The field
     holds the time where the ticket start to be valid (typically in the
     past).

     *Return value:* Returns C time interpretation of the endtime in
     ticket.

shishi_tkt_endctime
-------------------

 -- Function: time_t shishi_tkt_endctime (Shishi_tkt * TKT)
     TKT: input variable with ticket info.

     Extract C time corresponding to the endtime field.  The field holds
     the time where the ticket stop being valid.

     *Return value:* Returns C time interpretation of the endtime in
     ticket.

shishi_tkt_renew_tillc
----------------------

 -- Function: time_t shishi_tkt_renew_tillc (Shishi_tkt * TKT)
     TKT: input variable with ticket info.

     Extract C time corresponding to the renew-till field.  The field
     holds the time where the ticket stop being valid for renewal.

     *Return value:* Returns C time interpretation of the renew-till in
     ticket.

shishi_tkt_valid_at_time_p
--------------------------

 -- Function: int shishi_tkt_valid_at_time_p (Shishi_tkt * TKT, time_t
          NOW)
     TKT: input variable with ticket info.

     NOW: time to check for.

     Determine if ticket is valid at a specific point in time.

     *Return value:* Returns non-0 iff ticket is valid (not expired and
     after starttime) at specified time.

shishi_tkt_valid_now_p
----------------------

 -- Function: int shishi_tkt_valid_now_p (Shishi_tkt * TKT)
     TKT: input variable with ticket info.

     Determine if ticket is valid now.

     *Return value:* Returns 0 iff ticket is invalid (expired or not yet
     valid).

shishi_tkt_expired_p
--------------------

 -- Function: int shishi_tkt_expired_p (Shishi_tkt * TKT)
     TKT: input variable with ticket info.

     Determine if ticket has expired (i.e., endtime is in the past).

     *Return value:* Returns 0 iff ticket has expired.

shishi_tkt_lastreq_pretty_print
-------------------------------

 -- Function: void shishi_tkt_lastreq_pretty_print (Shishi_tkt * TKT,
          FILE * FH)
     TKT: input variable with ticket info.

     FH: file handle open for writing.

     Print a human readable representation of the various lastreq fields
     in the ticket (really EncKDCRepPart).

shishi_tkt_pretty_print
-----------------------

 -- Function: void shishi_tkt_pretty_print (Shishi_tkt * TKT, FILE * FH)
     TKT: input variable with ticket info.

     FH: file handle open for writing.

     Print a human readable representation of a ticket to file handle.


File: shishi.info,  Node: AS Functions,  Next: TGS Functions,  Prev: Ticket Functions,  Up: Programming Manual

5.7 AS Functions
================

The Authentication Service (AS) is used to get an initial ticket using
e.g. your password.  The following illustrates the AS-REQ and AS-REP
ASN.1 structures.


-- Request --

AS-REQ		::= KDC-REQ {10}

KDC-REQ {INTEGER:tagnum}	::= [APPLICATION tagnum] SEQUENCE {
	pvno		[1] INTEGER (5) -- first tag is [1], not [0] --,
	msg-type	[2] INTEGER (tagnum),
	padata		[3] SEQUENCE OF PA-DATA OPTIONAL,
	req-body	[4] KDC-REQ-BODY
}

KDC-REQ-BODY	::= SEQUENCE {
	kdc-options		[0] KDCOptions,
	cname			[1] PrincipalName OPTIONAL
				    -- Used only in AS-REQ --,
	realm			[2] Realm
				    -- Server's realm
				    -- Also client's in AS-REQ --,
	sname			[3] PrincipalName OPTIONAL,
	from			[4] KerberosTime OPTIONAL,
	till			[5] KerberosTime,
	rtime			[6] KerberosTime OPTIONAL,
	nonce			[7] UInt32,
	etype			[8] SEQUENCE OF Int32 -- EncryptionType
				    -- in preference order --,
	addresses		[9] HostAddresses OPTIONAL,
	enc-authorization-data	[10] EncryptedData {
					AuthorizationData,
					{ keyuse-TGSReqAuthData-sesskey
					  | keyuse-TGSReqAuthData-subkey }
				     } OPTIONAL,
	additional-tickets	[11] SEQUENCE OF Ticket OPTIONAL
}

-- Reply --

AS-REP		::= KDC-REP {11, EncASRepPart, {keyuse-EncASRepPart}}

KDC-REP {INTEGER:tagnum,
	 TypeToEncrypt,
	 UInt32:KeyUsages}	::= [APPLICATION tagnum] SEQUENCE {
	pvno		[0] INTEGER (5),
	msg-type	[1] INTEGER (tagnum),
	padata		[2] SEQUENCE OF PA-DATA OPTIONAL,
	crealm		[3] Realm,
	cname		[4] PrincipalName,
	ticket		[5] Ticket,
	enc-part	[6] EncryptedData {TypeToEncrypt, KeyUsages}
}

EncASRepPart	::= [APPLICATION 25] EncKDCRepPart

EncKDCRepPart	::= SEQUENCE {
	key		[0] EncryptionKey,
	last-req	[1] LastReq,
	nonce		[2] UInt32,
	key-expiration	[3] KerberosTime OPTIONAL,
	flags		[4] TicketFlags,
	authtime	[5] KerberosTime,
	starttime	[6] KerberosTime OPTIONAL,
	endtime		[7] KerberosTime,
	renew-till	[8] KerberosTime OPTIONAL,
	srealm		[9] Realm,
	sname		[10] PrincipalName,
	caddr		[11] HostAddresses OPTIONAL
}

shishi_as
---------

 -- Function: int shishi_as (Shishi * HANDLE, Shishi_as ** AS)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     AS: holds pointer to newly allocate Shishi_as structure.

     Allocate a new AS exchange variable.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_as_done
--------------

 -- Function: void shishi_as_done (Shishi_as * AS)
     AS: structure that holds information about AS exchange

     Deallocate resources associated with AS exchange.  This should be
     called by the application when it no longer need to utilize the AS
     exchange handle.

shishi_as_req
-------------

 -- Function: Shishi_asn1 shishi_as_req (Shishi_as * AS)
     AS: structure that holds information about AS exchange

     Get ASN.1 AS-REQ structure from AS exchange.

     *Return value:* Returns the generated AS-REQ packet from the AS
     exchange, or NULL if not yet set or an error occured.

shishi_as_req_build
-------------------

 -- Function: int shishi_as_req_build (Shishi_as * AS)
     AS: structure that holds information about AS exchange

     Possibly remove unset fields (e.g., rtime).

     *Return value:* Returns SHISHI_OK iff successful.

shishi_as_req_set
-----------------

 -- Function: void shishi_as_req_set (Shishi_as * AS, Shishi_asn1 ASREQ)
     AS: structure that holds information about AS exchange

     ASREQ: asreq to store in AS.

     Set the AS-REQ in the AS exchange.

shishi_as_req_der
-----------------

 -- Function: int shishi_as_req_der (Shishi_as * AS, char ** OUT,
          size_t * OUTLEN)
     AS: structure that holds information about AS exchange

     OUT: output array with newly allocated DER encoding of AS-REQ.

     OUTLEN: length of output array with DER encoding of AS-REQ.

     DER encode AS-REQ.  `out' is allocated by this function, and it is
     the responsibility of caller to deallocate it.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_as_req_der_set
---------------------

 -- Function: int shishi_as_req_der_set (Shishi_as * AS, char * DER,
          size_t DERLEN)
     AS: structure that holds information about AS exchange

     DER: input array with DER encoded AP-REQ.

     DERLEN: length of input array with DER encoded AP-REQ.

     DER decode AS-REQ and set it AS exchange.  If decoding fails, the
     AS-REQ in the AS exchange remains.

     *Return value:* Returns SHISHI_OK.

shishi_as_rep
-------------

 -- Function: Shishi_asn1 shishi_as_rep (Shishi_as * AS)
     AS: structure that holds information about AS exchange

     Get ASN.1 AS-REP structure from AS exchange.

     *Return value:* Returns the received AS-REP packet from the AS
     exchange, or NULL if not yet set or an error occured.

shishi_as_rep_process
---------------------

 -- Function: int shishi_as_rep_process (Shishi_as * AS, Shishi_key *
          KEY, const char * PASSWORD)
     AS: structure that holds information about AS exchange

     KEY: user's key, used to encrypt the encrypted part of the AS-REP.

     PASSWORD: user's password, used if key is NULL.

     Process new AS-REP and set ticket.  The key is used to decrypt the
     AP-REP.  If both key and password is NULL, the user is queried for
     it.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_as_rep_build
-------------------

 -- Function: int shishi_as_rep_build (Shishi_as * AS, Shishi_key * KEY)
     AS: structure that holds information about AS exchange

     KEY: user's key, used to encrypt the encrypted part of the AS-REP.

     Build AS-REP.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_as_rep_der
-----------------

 -- Function: int shishi_as_rep_der (Shishi_as * AS, char ** OUT,
          size_t * OUTLEN)
     AS: structure that holds information about AS exchange

     OUT: output array with newly allocated DER encoding of AS-REP.

     OUTLEN: length of output array with DER encoding of AS-REP.

     DER encode AS-REP. `out' is allocated by this function, and it is
     the responsibility of caller to deallocate it.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_as_rep_set
-----------------

 -- Function: void shishi_as_rep_set (Shishi_as * AS, Shishi_asn1 ASREP)
     AS: structure that holds information about AS exchange

     ASREP: asrep to store in AS.

     Set the AS-REP in the AS exchange.

shishi_as_rep_der_set
---------------------

 -- Function: int shishi_as_rep_der_set (Shishi_as * AS, char * DER,
          size_t DERLEN)
     AS: structure that holds information about AS exchange

     DER: input array with DER encoded AP-REP.

     DERLEN: length of input array with DER encoded AP-REP.

     DER decode AS-REP and set it AS exchange.  If decoding fails, the
     AS-REP in the AS exchange remains.

     *Return value:* Returns SHISHI_OK.

shishi_as_krberror
------------------

 -- Function: Shishi_asn1 shishi_as_krberror (Shishi_as * AS)
     AS: structure that holds information about AS exchange

     Get ASN.1 KRB-ERROR structure from AS exchange.

     *Return value:* Returns the received KRB-ERROR packet from the AS
     exchange, or NULL if not yet set or an error occured.

shishi_as_krberror_der
----------------------

 -- Function: int shishi_as_krberror_der (Shishi_as * AS, char ** OUT,
          size_t * OUTLEN)
     AS: structure that holds information about AS exchange

     OUT: output array with newly allocated DER encoding of KRB-ERROR.

     OUTLEN: length of output array with DER encoding of KRB-ERROR.

     DER encode KRB-ERROR. `out' is allocated by this function, and it
     is the responsibility of caller to deallocate it.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_as_krberror_set
----------------------

 -- Function: void shishi_as_krberror_set (Shishi_as * AS, Shishi_asn1
          KRBERROR)
     AS: structure that holds information about AS exchange

     KRBERROR: krberror to store in AS.

     Set the KRB-ERROR in the AS exchange.

shishi_as_tkt
-------------

 -- Function: Shishi_tkt * shishi_as_tkt (Shishi_as * AS)
     AS: structure that holds information about AS exchange

     Get Ticket in AS exchange.

     *Return value:* Returns the newly acquired tkt from the AS
     exchange, or NULL if not yet set or an error occured.

shishi_as_tkt_set
-----------------

 -- Function: void shishi_as_tkt_set (Shishi_as * AS, Shishi_tkt * TKT)
     AS: structure that holds information about AS exchange

     TKT: tkt to store in AS.

     Set the Tkt in the AS exchange.

shishi_as_sendrecv_hint
-----------------------

 -- Function: int shishi_as_sendrecv_hint (Shishi_as * AS,
          Shishi_tkts_hint * HINT)
     AS: structure that holds information about AS exchange

     HINT: additional parameters that modify connection behaviour, or
     `NULL'.

     Send AS-REQ and receive AS-REP or KRB-ERROR.  This is the initial
     authentication, usually used to acquire a Ticket Granting Ticket.
     The `hint' structure can be used to set, e.g., parameters for TLS
     authentication.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_as_sendrecv
------------------

 -- Function: int shishi_as_sendrecv (Shishi_as * AS)
     AS: structure that holds information about AS exchange

     Send AS-REQ and receive AS-REP or KRB-ERROR.  This is the initial
     authentication, usually used to acquire a Ticket Granting Ticket.

     *Return value:* Returns SHISHI_OK iff successful.


File: shishi.info,  Node: TGS Functions,  Next: Ticket (ASN.1) Functions,  Prev: AS Functions,  Up: Programming Manual

5.8 TGS Functions
=================

The Ticket Granting Service (TGS) is used to get subsequent tickets,
authenticated by other tickets (so called ticket granting tickets).
The following illustrates the TGS-REQ and TGS-REP ASN.1 structures.


-- Request --

TGS-REQ		::= KDC-REQ {12}

KDC-REQ {INTEGER:tagnum}	::= [APPLICATION tagnum] SEQUENCE {
	pvno		[1] INTEGER (5) -- first tag is [1], not [0] --,
	msg-type	[2] INTEGER (tagnum),
	padata		[3] SEQUENCE OF PA-DATA OPTIONAL,
	req-body	[4] KDC-REQ-BODY
}

KDC-REQ-BODY	::= SEQUENCE {
	kdc-options		[0] KDCOptions,
	cname			[1] PrincipalName OPTIONAL
				    -- Used only in AS-REQ --,
	realm			[2] Realm
				    -- Server's realm
				    -- Also client's in AS-REQ --,
	sname			[3] PrincipalName OPTIONAL,
	from			[4] KerberosTime OPTIONAL,
	till			[5] KerberosTime,
	rtime			[6] KerberosTime OPTIONAL,
	nonce			[7] UInt32,
	etype			[8] SEQUENCE OF Int32 -- EncryptionType
				    -- in preference order --,
	addresses		[9] HostAddresses OPTIONAL,
	enc-authorization-data	[10] EncryptedData {
					AuthorizationData,
					{ keyuse-TGSReqAuthData-sesskey
					  | keyuse-TGSReqAuthData-subkey }
				     } OPTIONAL,
	additional-tickets	[11] SEQUENCE OF Ticket OPTIONAL
}

-- Reply --

TGS-REP		::= KDC-REP {13, EncTGSRepPart,
			{ keyuse-EncTGSRepPart-sesskey
			  | keyuse-EncTGSRepPart-subkey }}

KDC-REP {INTEGER:tagnum,
	 TypeToEncrypt,
	 UInt32:KeyUsages}	::= [APPLICATION tagnum] SEQUENCE {
	pvno		[0] INTEGER (5),
	msg-type	[1] INTEGER (tagnum),
	padata		[2] SEQUENCE OF PA-DATA OPTIONAL,
	crealm		[3] Realm,
	cname		[4] PrincipalName,
	ticket		[5] Ticket,
	enc-part	[6] EncryptedData {TypeToEncrypt, KeyUsages}
}

EncTGSRepPart	::= [APPLICATION 26] EncKDCRepPart

EncKDCRepPart	::= SEQUENCE {
	key		[0] EncryptionKey,
	last-req	[1] LastReq,
	nonce		[2] UInt32,
	key-expiration	[3] KerberosTime OPTIONAL,
	flags		[4] TicketFlags,
	authtime	[5] KerberosTime,
	starttime	[6] KerberosTime OPTIONAL,
	endtime		[7] KerberosTime,
	renew-till	[8] KerberosTime OPTIONAL,
	srealm		[9] Realm,
	sname		[10] PrincipalName,
	caddr		[11] HostAddresses OPTIONAL
}

shishi_tgs
----------

 -- Function: int shishi_tgs (Shishi * HANDLE, Shishi_tgs ** TGS)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     TGS: holds pointer to newly allocate Shishi_tgs structure.

     Allocate a new TGS exchange variable.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_tgs_done
---------------

 -- Function: void shishi_tgs_done (Shishi_tgs * TGS)
     TGS: structure that holds information about AS exchange

     Deallocate resources associated with TGS exchange.  This should be
     called by the application when it no longer need to utilize the TGS
     exchange handle.

shishi_tgs_tgtkt
----------------

 -- Function: Shishi_tkt * shishi_tgs_tgtkt (Shishi_tgs * TGS)
     TGS: structure that holds information about TGS exchange

     Get Ticket-granting-ticket from TGS exchange.

     *Return value:* Returns the ticket-granting-ticket used in the TGS
     exchange, or NULL if not yet set or an error occured.

shishi_tgs_tgtkt_set
--------------------

 -- Function: void shishi_tgs_tgtkt_set (Shishi_tgs * TGS, Shishi_tkt *
          TGTKT)
     TGS: structure that holds information about TGS exchange

     TGTKT: ticket granting ticket to store in TGS.

     Set the Ticket in the TGS exchange.

shishi_tgs_ap
-------------

 -- Function: Shishi_ap * shishi_tgs_ap (Shishi_tgs * TGS)
     TGS: structure that holds information about TGS exchange

     Get the AP from TGS exchange.

     *Return value:* Returns the AP exchange (part of TGS-REQ) from the
     TGS exchange, or NULL if not yet set or an error occured.

shishi_tgs_req
--------------

 -- Function: Shishi_asn1 shishi_tgs_req (Shishi_tgs * TGS)
     TGS: structure that holds information about TGS exchange

     Get the TGS-REQ from TGS exchange.

     *Return value:* Returns the generated TGS-REQ from the TGS
     exchange, or NULL if not yet set or an error occured.

shishi_tgs_req_set
------------------

 -- Function: void shishi_tgs_req_set (Shishi_tgs * TGS, Shishi_asn1
          TGSREQ)
     TGS: structure that holds information about TGS exchange

     TGSREQ: tgsreq to store in TGS.

     Set the TGS-REQ in the TGS exchange.

shishi_tgs_req_der
------------------

 -- Function: int shishi_tgs_req_der (Shishi_tgs * TGS, char ** OUT,
          size_t * OUTLEN)
     TGS: structure that holds information about TGS exchange

     OUT: output array with newly allocated DER encoding of TGS-REQ.

     OUTLEN: length of output array with DER encoding of TGS-REQ.

     DER encode TGS-REQ. `out' is allocated by this function, and it is
     the responsibility of caller to deallocate it.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_tgs_req_der_set
----------------------

 -- Function: int shishi_tgs_req_der_set (Shishi_tgs * TGS, char * DER,
          size_t DERLEN)
     TGS: structure that holds information about TGS exchange

     DER: input array with DER encoded AP-REQ.

     DERLEN: length of input array with DER encoded AP-REQ.

     DER decode TGS-REQ and set it TGS exchange.  If decoding fails, the
     TGS-REQ in the TGS exchange remains.

     *Return value:* Returns SHISHI_OK.

shishi_tgs_req_process
----------------------

 -- Function: int shishi_tgs_req_process (Shishi_tgs * TGS)
     TGS: structure that holds information about TGS exchange

     Process new TGS-REQ and set ticket.  The key to decrypt the TGS-REQ
     is taken from the EncKDCReqPart of the TGS tgticket.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_tgs_req_build
--------------------

 -- Function: int shishi_tgs_req_build (Shishi_tgs * TGS)
     TGS: structure that holds information about TGS exchange

     Checksum data in authenticator and add ticket and authenticator to
     TGS-REQ.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_tgs_rep
--------------

 -- Function: Shishi_asn1 shishi_tgs_rep (Shishi_tgs * TGS)
     TGS: structure that holds information about TGS exchange

     Get TGS-REP from TGS exchange.

     *Return value:* Returns the received TGS-REP from the TGS exchange,
     or NULL if not yet set or an error occured.

shishi_tgs_rep_der
------------------

 -- Function: int shishi_tgs_rep_der (Shishi_tgs * TGS, char ** OUT,
          size_t * OUTLEN)
     TGS: structure that holds information about TGS exchange

     OUT: output array with newly allocated DER encoding of TGS-REP.

     OUTLEN: length of output array with DER encoding of TGS-REP.

     DER encode TGS-REP. `out' is allocated by this function, and it is
     the responsibility of caller to deallocate it.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_tgs_rep_process
----------------------

 -- Function: int shishi_tgs_rep_process (Shishi_tgs * TGS)
     TGS: structure that holds information about TGS exchange

     Process new TGS-REP and set ticket.  The key to decrypt the TGS-REP
     is taken from the EncKDCRepPart of the TGS tgticket.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_tgs_rep_build
--------------------

 -- Function: int shishi_tgs_rep_build (Shishi_tgs * TGS, int KEYUSAGE,
          Shishi_key * KEY)
     TGS: structure that holds information about TGS exchange

     KEYUSAGE: keyusage integer.

     KEY: user's key, used to encrypt the encrypted part of the TGS-REP.

     Build TGS-REP.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_tgs_krberror
-------------------

 -- Function: Shishi_asn1 shishi_tgs_krberror (Shishi_tgs * TGS)
     TGS: structure that holds information about TGS exchange

     Get KRB-ERROR from TGS exchange.

     *Return value:* Returns the received TGS-REP from the TGS exchange,
     or NULL if not yet set or an error occured.

shishi_tgs_krberror_der
-----------------------

 -- Function: int shishi_tgs_krberror_der (Shishi_tgs * TGS, char **
          OUT, size_t * OUTLEN)
     TGS: structure that holds information about TGS exchange

     OUT: output array with newly allocated DER encoding of KRB-ERROR.

     OUTLEN: length of output array with DER encoding of KRB-ERROR.

     DER encode KRB-ERROR.  `out' is allocated by this function, and it
     is the responsibility of caller to deallocate it.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_tgs_krberror_set
-----------------------

 -- Function: void shishi_tgs_krberror_set (Shishi_tgs * TGS,
          Shishi_asn1 KRBERROR)
     TGS: structure that holds information about TGS exchange

     KRBERROR: krberror to store in TGS.

     Set the KRB-ERROR in the TGS exchange.

shishi_tgs_tkt
--------------

 -- Function: Shishi_tkt * shishi_tgs_tkt (Shishi_tgs * TGS)
     TGS: structure that holds information about TGS exchange

     Get Ticket from TGS exchange.

     *Return value:* Returns the newly acquired ticket from the TGS
     exchange, or NULL if not yet set or an error occured.

shishi_tgs_tkt_set
------------------

 -- Function: void shishi_tgs_tkt_set (Shishi_tgs * TGS, Shishi_tkt *
          TKT)
     TGS: structure that holds information about TGS exchange

     TKT: ticket to store in TGS.

     Set the Ticket in the TGS exchange.

shishi_tgs_sendrecv_hint
------------------------

 -- Function: int shishi_tgs_sendrecv_hint (Shishi_tgs * TGS,
          Shishi_tkts_hint * HINT)
     TGS: structure that holds information about TGS exchange

     HINT: additional parameters that modify connection behaviour, or
     `NULL'.

     Send TGS-REQ and receive TGS-REP or KRB-ERROR.  This is the
     subsequent authentication, usually used to acquire server tickets.
     The `hint' structure can be used to set, e.g., parameters for TLS
     authentication.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_tgs_sendrecv
-------------------

 -- Function: int shishi_tgs_sendrecv (Shishi_tgs * TGS)
     TGS: structure that holds information about TGS exchange

     Send TGS-REQ and receive TGS-REP or KRB-ERROR.  This is the
     subsequent authentication, usually used to acquire server tickets.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_tgs_set_server
---------------------

 -- Function: int shishi_tgs_set_server (Shishi_tgs * TGS, const char *
          SERVER)
     TGS: structure that holds information about TGS exchange

     SERVER: indicates the server to acquire ticket for.

     Set the server in the TGS-REQ.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_tgs_set_realm
--------------------

 -- Function: int shishi_tgs_set_realm (Shishi_tgs * TGS, const char *
          REALM)
     TGS: structure that holds information about TGS exchange

     REALM: indicates the realm to acquire ticket for.

     Set the server in the TGS-REQ.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_tgs_set_realmserver
--------------------------

 -- Function: int shishi_tgs_set_realmserver (Shishi_tgs * TGS, const
          char * REALM, const char * SERVER)
     TGS: structure that holds information about TGS exchange

     REALM: indicates the realm to acquire ticket for.

     SERVER: indicates the server to acquire ticket for.

     Set the realm and server in the TGS-REQ.

     *Return value:* Returns SHISHI_OK iff successful.


File: shishi.info,  Node: Ticket (ASN.1) Functions,  Next: AS/TGS Functions,  Prev: TGS Functions,  Up: Programming Manual

5.9 Ticket (ASN.1) Functions
============================

*Note Ticket Functions::, for an high-level overview of tickets.  The
following illustrates the Ticket and EncTicketPart ASN.1 structures.


Ticket          ::= [APPLICATION 1] SEQUENCE {
        tkt-vno         [0] INTEGER (5),
        realm           [1] Realm,
        sname           [2] PrincipalName,
        enc-part        [3] EncryptedData -- EncTicketPart
}

-- Encrypted part of ticket
EncTicketPart   ::= [APPLICATION 3] SEQUENCE {
        flags                   [0] TicketFlags,
        key                     [1] EncryptionKey,
        crealm                  [2] Realm,
        cname                   [3] PrincipalName,
        transited               [4] TransitedEncoding,
        authtime                [5] KerberosTime,
        starttime               [6] KerberosTime OPTIONAL,
        endtime                 [7] KerberosTime,
        renew-till              [8] KerberosTime OPTIONAL,
        caddr                   [9] HostAddresses OPTIONAL,
        authorization-data      [10] AuthorizationData OPTIONAL
}

shishi_ticket
-------------

 -- Function: Shishi_asn1 shishi_ticket (Shishi * HANDLE)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     This function creates a new ASN.1 Ticket, populated with some
     default values.

     *Return value:* Returns the ticket or NULL on failure.

shishi_ticket_realm_get
-----------------------

 -- Function: int shishi_ticket_realm_get (Shishi * HANDLE, Shishi_asn1
          TICKET, char ** REALM, size_t * REALMLEN)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     TICKET: input variable with ticket info.

     REALM: output array with newly allocated name of realm in ticket.

     REALMLEN: size of output array.

     Extract realm from ticket.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_ticket_realm_set
-----------------------

 -- Function: int shishi_ticket_realm_set (Shishi * HANDLE, Shishi_asn1
          TICKET, const char * REALM)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     TICKET: input variable with ticket info.

     REALM: input array with name of realm.

     Set the realm field in the Ticket.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_ticket_server
--------------------

 -- Function: int shishi_ticket_server (Shishi * HANDLE, Shishi_asn1
          TICKET, char ** SERVER, size_t * SERVERLEN)
     HANDLE: Shishi library handle create by `shishi_init()'.

     TICKET: ASN.1 Ticket variable to get server name from.

     SERVER: pointer to newly allocated zero terminated string
     containing principal name.  May be `NULL' (to only populate
     `serverlen').

     SERVERLEN: pointer to length of `server' on output, excluding
     terminating zero.  May be `NULL' (to only populate `server').

     Represent server principal name in Ticket as zero-terminated
     string.  The string is allocate by this function, and it is the
     responsibility of the caller to deallocate it.  Note that the
     output length `serverlen' does not include the terminating zero.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_ticket_sname_set
-----------------------

 -- Function: int shishi_ticket_sname_set (Shishi * HANDLE, Shishi_asn1
          TICKET, Shishi_name_type NAME_TYPE, char * [] SNAME)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     TICKET: Ticket variable to set server name field in.

     NAME_TYPE: type of principial, see Shishi_name_type, usually
     SHISHI_NT_UNKNOWN.

     SNAME: input array with principal name.

     Set the server name field in the Ticket.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_ticket_get_enc_part_etype
--------------------------------

 -- Function: int shishi_ticket_get_enc_part_etype (Shishi * HANDLE,
          Shishi_asn1 TICKET, int32_t * ETYPE)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     TICKET: Ticket variable to get value from.

     ETYPE: output variable that holds the value.

     Extract Ticket.enc-part.etype.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_ticket_set_enc_part
--------------------------

 -- Function: int shishi_ticket_set_enc_part (Shishi * HANDLE,
          Shishi_asn1 TICKET, int32_t ETYPE, uint32_t KVNO, const char
          * BUF, size_t BUFLEN)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     TICKET: Ticket to add enc-part field to.

     ETYPE: encryption type used to encrypt enc-part.

     KVNO: key version number.

     BUF: input array with encrypted enc-part.

     BUFLEN: size of input array with encrypted enc-part.

     Set the encrypted enc-part field in the Ticket.  The encrypted data
     is usually created by calling `shishi_encrypt()' on the DER encoded
     enc-part.  To save time, you may want to use
     `shishi_ticket_add_enc_part()' instead, which calculates the
     encrypted data and calls this function in one step.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_ticket_add_enc_part
--------------------------

 -- Function: int shishi_ticket_add_enc_part (Shishi * HANDLE,
          Shishi_asn1 TICKET, Shishi_key * KEY, Shishi_asn1
          ENCTICKETPART)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     TICKET: Ticket to add enc-part field to.

     KEY: key used to encrypt enc-part.

     ENCTICKETPART: EncTicketPart to add.

     Encrypts DER encoded EncTicketPart using key and stores it in the
     Ticket.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_encticketpart_get_key
----------------------------

 -- Function: int shishi_encticketpart_get_key (Shishi * HANDLE,
          Shishi_asn1 ENCTICKETPART, Shishi_key ** KEY)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     ENCTICKETPART: input EncTicketPart variable.

     KEY: newly allocated key.

     Extract the session key in the Ticket.

     *Return value:* Returns `SHISHI_OK' iff successful.

shishi_encticketpart_key_set
----------------------------

 -- Function: int shishi_encticketpart_key_set (Shishi * HANDLE,
          Shishi_asn1 ENCTICKETPART, Shishi_key * KEY)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     ENCTICKETPART: input EncTicketPart variable.

     KEY: key handle with information to store in encticketpart.

     Set the EncTicketPart.key field to key type and value of supplied
     key.

     *Return value:* Returns `SHISHI_OK' iff successful.

shishi_encticketpart_flags_set
------------------------------

 -- Function: int shishi_encticketpart_flags_set (Shishi * HANDLE,
          Shishi_asn1 ENCTICKETPART, int FLAGS)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     ENCTICKETPART: input EncTicketPart variable.

     FLAGS: flags to set in encticketpart.

     Set the EncTicketPart.flags to supplied value.

     *Return value:* Returns `SHISHI_OK' iff successful.

shishi_encticketpart_crealm_set
-------------------------------

 -- Function: int shishi_encticketpart_crealm_set (Shishi * HANDLE,
          Shishi_asn1 ENCTICKETPART, const char * REALM)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     ENCTICKETPART: input EncTicketPart variable.

     REALM: input array with name of realm.

     Set the realm field in the KDC-REQ.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_encticketpart_cname_set
------------------------------

 -- Function: int shishi_encticketpart_cname_set (Shishi * HANDLE,
          Shishi_asn1 ENCTICKETPART, Shishi_name_type NAME_TYPE, const
          char * PRINCIPAL)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     ENCTICKETPART: input EncTicketPart variable.

     NAME_TYPE: type of principial, see Shishi_name_type, usually
     SHISHI_NT_UNKNOWN.

     PRINCIPAL: input array with principal name.

     Set the client name field in the EncTicketPart.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_encticketpart_transited_set
----------------------------------

 -- Function: int shishi_encticketpart_transited_set (Shishi * HANDLE,
          Shishi_asn1 ENCTICKETPART, int32_t TRTYPE, const char *
          TRDATA, size_t TRDATALEN)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     ENCTICKETPART: input EncTicketPart variable.

     TRTYPE: transitedencoding type, e.g.
     SHISHI_TR_DOMAIN_X500_COMPRESS.

     TRDATA: actual transited realm data.

     TRDATALEN: length of actual transited realm data.

     Set the EncTicketPart.transited field to supplied value.

     *Return value:* Returns `SHISHI_OK' iff successful.

shishi_encticketpart_authtime_set
---------------------------------

 -- Function: int shishi_encticketpart_authtime_set (Shishi * HANDLE,
          Shishi_asn1 ENCTICKETPART, const char * AUTHTIME)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     ENCTICKETPART: input EncTicketPart variable.

     AUTHTIME: character buffer containing a generalized time string.

     Set the EncTicketPart.authtime to supplied value.

     *Return value:* Returns `SHISHI_OK' iff successful.

shishi_encticketpart_endtime_set
--------------------------------

 -- Function: int shishi_encticketpart_endtime_set (Shishi * HANDLE,
          Shishi_asn1 ENCTICKETPART, const char * ENDTIME)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     ENCTICKETPART: input EncTicketPart variable.

     ENDTIME: character buffer containing a generalized time string.

     Set the EncTicketPart.endtime to supplied value.

     *Return value:* Returns `SHISHI_OK' iff successful.

shishi_encticketpart_client
---------------------------

 -- Function: int shishi_encticketpart_client (Shishi * HANDLE,
          Shishi_asn1 ENCTICKETPART, char ** CLIENT, size_t * CLIENTLEN)
     HANDLE: Shishi library handle create by `shishi_init()'.

     ENCTICKETPART: EncTicketPart variable to get client name from.

     CLIENT: pointer to newly allocated zero terminated string
     containing principal name.  May be `NULL' (to only populate
     `clientlen').

     CLIENTLEN: pointer to length of `client' on output, excluding
     terminating zero.  May be `NULL' (to only populate `client').

     Represent client principal name in EncTicketPart as zero-terminated
     string.  The string is allocate by this function, and it is the
     responsibility of the caller to deallocate it.  Note that the
     output length `clientlen' does not include the terminating zero.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_encticketpart_clientrealm
--------------------------------

 -- Function: int shishi_encticketpart_clientrealm (Shishi * HANDLE,
          Shishi_asn1 ENCTICKETPART, char ** CLIENT, size_t * CLIENTLEN)
     HANDLE: Shishi library handle create by `shishi_init()'.

     ENCTICKETPART: EncTicketPart variable to get client name and realm
     from.

     CLIENT: pointer to newly allocated zero terminated string
     containing principal name and realm.  May be `NULL' (to only
     populate `clientlen').

     CLIENTLEN: pointer to length of `client' on output, excluding
     terminating zero.  May be `NULL' (to only populate `client').

     Convert cname and realm fields from EncTicketPart to printable
     principal name format.  The string is allocate by this function,
     and it is the responsibility of the caller to deallocate it.  Note
     that the output length `clientlen' does not include the terminating
     zero.

     *Return value:* Returns SHISHI_OK iff successful.


File: shishi.info,  Node: AS/TGS Functions,  Next: Authenticator Functions,  Prev: Ticket (ASN.1) Functions,  Up: Programming Manual

5.10 AS/TGS Functions
=====================

The Authentication Service (AS) is used to get an initial ticket using
e.g. your password.  The Ticket Granting Service (TGS) is used to get
subsequent tickets using other tickets.  Protocol wise the procedures
are very similar, which is the reason they are described together.  The
following illustrates the AS-REQ, TGS-REQ and AS-REP, TGS-REP ASN.1
structures.  Most of the functions use the mnemonic "KDC" instead of
either AS or TGS, which means the function operates on both AS and TGS
types.  Only where the distinction between AS and TGS is important are
the AS and TGS names used.  Remember, these are low-level functions,
and normal applications will likely be satisfied with the AS (*note AS
Functions::) and TGS (*note TGS Functions::) interfaces, or the even
more high-level Ticket Set (*note Ticket Set Functions::) interface.


-- Request --

AS-REQ		::= KDC-REQ {10}
TGS-REQ		::= KDC-REQ {12}

KDC-REQ {INTEGER:tagnum}	::= [APPLICATION tagnum] SEQUENCE {
	pvno		[1] INTEGER (5) -- first tag is [1], not [0] --,
	msg-type	[2] INTEGER (tagnum),
	padata		[3] SEQUENCE OF PA-DATA OPTIONAL,
	req-body	[4] KDC-REQ-BODY
}

KDC-REQ-BODY	::= SEQUENCE {
	kdc-options		[0] KDCOptions,
	cname			[1] PrincipalName OPTIONAL
				    -- Used only in AS-REQ --,
	realm			[2] Realm
				    -- Server's realm
				    -- Also client's in AS-REQ --,
	sname			[3] PrincipalName OPTIONAL,
	from			[4] KerberosTime OPTIONAL,
	till			[5] KerberosTime,
	rtime			[6] KerberosTime OPTIONAL,
	nonce			[7] UInt32,
	etype			[8] SEQUENCE OF Int32 -- EncryptionType
				    -- in preference order --,
	addresses		[9] HostAddresses OPTIONAL,
	enc-authorization-data	[10] EncryptedData {
					AuthorizationData,
					{ keyuse-TGSReqAuthData-sesskey
					  | keyuse-TGSReqAuthData-subkey }
				     } OPTIONAL,
	additional-tickets	[11] SEQUENCE OF Ticket OPTIONAL
}

-- Reply --

AS-REP		::= KDC-REP {11, EncASRepPart, {keyuse-EncASRepPart}}
TGS-REP		::= KDC-REP {13, EncTGSRepPart,
			{ keyuse-EncTGSRepPart-sesskey
			  | keyuse-EncTGSRepPart-subkey }}

KDC-REP {INTEGER:tagnum,
	 TypeToEncrypt,
	 UInt32:KeyUsages}	::= [APPLICATION tagnum] SEQUENCE {
	pvno		[0] INTEGER (5),
	msg-type	[1] INTEGER (tagnum),
	padata		[2] SEQUENCE OF PA-DATA OPTIONAL,
	crealm		[3] Realm,
	cname		[4] PrincipalName,
	ticket		[5] Ticket,
	enc-part	[6] EncryptedData {TypeToEncrypt, KeyUsages}
}

EncASRepPart	::= [APPLICATION 25] EncKDCRepPart
EncTGSRepPart	::= [APPLICATION 26] EncKDCRepPart

EncKDCRepPart	::= SEQUENCE {
	key		[0] EncryptionKey,
	last-req	[1] LastReq,
	nonce		[2] UInt32,
	key-expiration	[3] KerberosTime OPTIONAL,
	flags		[4] TicketFlags,
	authtime	[5] KerberosTime,
	starttime	[6] KerberosTime OPTIONAL,
	endtime		[7] KerberosTime,
	renew-till	[8] KerberosTime OPTIONAL,
	srealm		[9] Realm,
	sname		[10] PrincipalName,
	caddr		[11] HostAddresses OPTIONAL
}

shishi_as_derive_salt
---------------------

 -- Function: int shishi_as_derive_salt (Shishi * HANDLE, Shishi_asn1
          ASREQ, Shishi_asn1 ASREP, char ** SALT, size_t * SALTLEN)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     ASREQ: input AS-REQ variable.

     ASREP: input AS-REP variable.

     SALT: newly allocated output array with salt.

     SALTLEN: holds actual size of output array with salt.

     Derive the salt that should be used when deriving a key via
     `shishi_string_to_key()' for an AS exchange.  Currently this
     searches for PA-DATA of type SHISHI_PA_PW_SALT in the AS-REP and
     returns it if found, otherwise the salt is derived from the client
     name and realm in AS-REQ.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_kdc_copy_crealm
----------------------

 -- Function: int shishi_kdc_copy_crealm (Shishi * HANDLE, Shishi_asn1
          KDCREP, Shishi_asn1 ENCTICKETPART)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KDCREP: KDC-REP to read crealm from.

     ENCTICKETPART: EncTicketPart to set crealm in.

     Set crealm in KDC-REP to value in EncTicketPart.

     *Return value:* Returns SHISHI_OK if successful.

shishi_as_check_crealm
----------------------

 -- Function: int shishi_as_check_crealm (Shishi * HANDLE, Shishi_asn1
          ASREQ, Shishi_asn1 ASREP)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     ASREQ: AS-REQ to compare realm field in.

     ASREP: AS-REP to compare realm field in.

     Verify that AS-REQ.req-body.realm and AS-REP.crealm fields matches.
     This is one of the steps that has to be performed when processing a
     AS-REQ and AS-REP exchange, see `shishi_kdc_process()'.

     *Return value:* Returns SHISHI_OK if successful,
     SHISHI_REALM_MISMATCH if the values differ, or an error code.

shishi_kdc_copy_cname
---------------------

 -- Function: int shishi_kdc_copy_cname (Shishi * HANDLE, Shishi_asn1
          KDCREP, Shishi_asn1 ENCTICKETPART)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KDCREP: KDC-REQ to read cname from.

     ENCTICKETPART: EncTicketPart to set cname in.

     Set cname in KDC-REP to value in EncTicketPart.

     *Return value:* Returns SHISHI_OK if successful.

shishi_as_check_cname
---------------------

 -- Function: int shishi_as_check_cname (Shishi * HANDLE, Shishi_asn1
          ASREQ, Shishi_asn1 ASREP)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     ASREQ: AS-REQ to compare client name field in.

     ASREP: AS-REP to compare client name field in.

     Verify that AS-REQ.req-body.realm and AS-REP.crealm fields matches.
     This is one of the steps that has to be performed when processing a
     AS-REQ and AS-REP exchange, see `shishi_kdc_process()'.

     *Return value:* Returns SHISHI_OK if successful,
     SHISHI_CNAME_MISMATCH if the values differ, or an error code.

shishi_kdc_copy_nonce
---------------------

 -- Function: int shishi_kdc_copy_nonce (Shishi * HANDLE, Shishi_asn1
          KDCREQ, Shishi_asn1 ENCKDCREPPART)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KDCREQ: KDC-REQ to read nonce from.

     ENCKDCREPPART: EncKDCRepPart to set nonce in.

     Set nonce in EncKDCRepPart to value in KDC-REQ.

     *Return value:* Returns SHISHI_OK if successful.

shishi_kdc_check_nonce
----------------------

 -- Function: int shishi_kdc_check_nonce (Shishi * HANDLE, Shishi_asn1
          KDCREQ, Shishi_asn1 ENCKDCREPPART)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KDCREQ: KDC-REQ to compare nonce field in.

     ENCKDCREPPART: Encrypted KDC-REP part to compare nonce field in.

     Verify that KDC-REQ.req-body.nonce and EncKDCRepPart.nonce fields
     matches.  This is one of the steps that has to be performed when
     processing a KDC-REQ and KDC-REP exchange.

     *Return value:* Returns SHISHI_OK if successful,
     SHISHI_NONCE_LENGTH_MISMATCH if the nonces have different lengths
     (usually indicates that buggy server truncated nonce to 4 bytes),
     SHISHI_NONCE_MISMATCH if the values differ, or an error code.

shishi_tgs_process
------------------

 -- Function: int shishi_tgs_process (Shishi * HANDLE, Shishi_asn1
          TGSREQ, Shishi_asn1 TGSREP, Shishi_asn1 AUTHENTICATOR,
          Shishi_asn1 OLDENCKDCREPPART, Shishi_asn1 * ENCKDCREPPART)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     TGSREQ: input variable that holds the sent KDC-REQ.

     TGSREP: input variable that holds the received KDC-REP.

     AUTHENTICATOR: input variable with Authenticator from AP-REQ in
     KDC-REQ.

     OLDENCKDCREPPART: input variable with EncKDCRepPart used in
     request.

     ENCKDCREPPART: output variable that holds new EncKDCRepPart.

     Process a TGS client exchange and output decrypted EncKDCRepPart
     which holds details for the new ticket received.  This function
     simply derives the encryption key from the ticket used to construct
     the TGS request and calls `shishi_kdc_process()', which see.

     *Return value:* Returns SHISHI_OK iff the TGS client exchange was
     successful.

shishi_as_process
-----------------

 -- Function: int shishi_as_process (Shishi * HANDLE, Shishi_asn1
          ASREQ, Shishi_asn1 ASREP, const char * STRING, Shishi_asn1 *
          ENCKDCREPPART)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     ASREQ: input variable that holds the sent KDC-REQ.

     ASREP: input variable that holds the received KDC-REP.

     STRING: input variable with zero terminated password.

     ENCKDCREPPART: output variable that holds new EncKDCRepPart.

     Process an AS client exchange and output decrypted EncKDCRepPart
     which holds details for the new ticket received.  This function
     simply derives the encryption key from the password and calls
     `shishi_kdc_process()', which see.

     *Return value:* Returns SHISHI_OK iff the AS client exchange was
     successful.

shishi_kdc_process
------------------

 -- Function: int shishi_kdc_process (Shishi * HANDLE, Shishi_asn1
          KDCREQ, Shishi_asn1 KDCREP, Shishi_key * KEY, int KEYUSAGE,
          Shishi_asn1 * ENCKDCREPPART)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KDCREQ: input variable that holds the sent KDC-REQ.

     KDCREP: input variable that holds the received KDC-REP.

     KEY: input array with key to decrypt encrypted part of KDC-REP
     with.

     KEYUSAGE: kereros key usage value.

     ENCKDCREPPART: output variable that holds new EncKDCRepPart.

     Process a KDC client exchange and output decrypted EncKDCRepPart
     which holds details for the new ticket received.  Use
     `shishi_kdcrep_get_ticket()' to extract the ticket.  This function
     verifies the various conditions that must hold if the response is
     to be considered valid, specifically it compares nonces
     (`shishi_kdc_check_nonce()') and if the exchange was a AS exchange,
     it also compares cname and crealm (`shishi_as_check_cname()' and
     `shishi_as_check_crealm()').

     Usually the `shishi_as_process()' and `shishi_tgs_process()'
     functions should be used instead, since they simplify the
     decryption key computation.

     *Return value:* Returns SHISHI_OK iff the KDC client exchange was
     successful.

shishi_asreq
------------

 -- Function: Shishi_asn1 shishi_asreq (Shishi * HANDLE)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     This function creates a new AS-REQ, populated with some default
     values.

     *Return value:* Returns the AS-REQ or NULL on failure.

shishi_tgsreq
-------------

 -- Function: Shishi_asn1 shishi_tgsreq (Shishi * HANDLE)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     This function creates a new TGS-REQ, populated with some default
     values.

     *Return value:* Returns the TGS-REQ or NULL on failure.

shishi_kdcreq_print
-------------------

 -- Function: int shishi_kdcreq_print (Shishi * HANDLE, FILE * FH,
          Shishi_asn1 KDCREQ)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     FH: file handle open for writing.

     KDCREQ: KDC-REQ to print.

     Print ASCII armored DER encoding of KDC-REQ to file.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_kdcreq_save
------------------

 -- Function: int shishi_kdcreq_save (Shishi * HANDLE, FILE * FH,
          Shishi_asn1 KDCREQ)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     FH: file handle open for writing.

     KDCREQ: KDC-REQ to save.

     Print DER encoding of KDC-REQ to file.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_kdcreq_to_file
---------------------

 -- Function: int shishi_kdcreq_to_file (Shishi * HANDLE, Shishi_asn1
          KDCREQ, int FILETYPE, const char * FILENAME)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KDCREQ: KDC-REQ to save.

     FILETYPE: input variable specifying type of file to be written,
     see Shishi_filetype.

     FILENAME: input variable with filename to write to.

     Write KDC-REQ to file in specified TYPE.  The file will be
     truncated if it exists.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_kdcreq_parse
-------------------

 -- Function: int shishi_kdcreq_parse (Shishi * HANDLE, FILE * FH,
          Shishi_asn1 * KDCREQ)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     FH: file handle open for reading.

     KDCREQ: output variable with newly allocated KDC-REQ.

     Read ASCII armored DER encoded KDC-REQ from file and populate given
     variable.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_kdcreq_read
------------------

 -- Function: int shishi_kdcreq_read (Shishi * HANDLE, FILE * FH,
          Shishi_asn1 * KDCREQ)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     FH: file handle open for reading.

     KDCREQ: output variable with newly allocated KDC-REQ.

     Read DER encoded KDC-REQ from file and populate given variable.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_kdcreq_from_file
-----------------------

 -- Function: int shishi_kdcreq_from_file (Shishi * HANDLE, Shishi_asn1
          * KDCREQ, int FILETYPE, const char * FILENAME)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KDCREQ: output variable with newly allocated KDC-REQ.

     FILETYPE: input variable specifying type of file to be read, see
     Shishi_filetype.

     FILENAME: input variable with filename to read from.

     Read KDC-REQ from file in specified TYPE.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_kdcreq_nonce_set
-----------------------

 -- Function: int shishi_kdcreq_nonce_set (Shishi * HANDLE, Shishi_asn1
          KDCREQ, uint32_t NONCE)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KDCREQ: KDC-REQ variable to set client name field in.

     NONCE: integer nonce to store in KDC-REQ.

     Store nonce number field in KDC-REQ.

     *Return value:* Returns `SHISHI_OK' iff successful.

shishi_kdcreq_set_cname
-----------------------

 -- Function: int shishi_kdcreq_set_cname (Shishi * HANDLE, Shishi_asn1
          KDCREQ, Shishi_name_type NAME_TYPE, const char * PRINCIPAL)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KDCREQ: KDC-REQ variable to set client name field in.

     NAME_TYPE: type of principial, see Shishi_name_type, usually
     SHISHI_NT_UNKNOWN.

     PRINCIPAL: input array with principal name.

     Set the client name field in the KDC-REQ.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_kdcreq_client
--------------------

 -- Function: int shishi_kdcreq_client (Shishi * HANDLE, Shishi_asn1
          KDCREQ, char ** CLIENT, size_t * CLIENTLEN)
     HANDLE: Shishi library handle create by `shishi_init()'.

     KDCREQ: KDC-REQ variable to get client name from.

     CLIENT: pointer to newly allocated zero terminated string
     containing principal name.  May be `NULL' (to only populate
     `clientlen').

     CLIENTLEN: pointer to length of `client' on output, excluding
     terminating zero.  May be `NULL' (to only populate `client').

     Represent client principal name in KDC-REQ as zero-terminated
     string.  The string is allocate by this function, and it is the
     responsibility of the caller to deallocate it.  Note that the
     output length `clientlen' does not include the terminating zero.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_asreq_clientrealm
------------------------

 -- Function: int shishi_asreq_clientrealm (Shishi * HANDLE,
          Shishi_asn1 ASREQ, char ** CLIENT, size_t * CLIENTLEN)
     HANDLE: Shishi library handle create by `shishi_init()'.

     ASREQ: AS-REQ variable to get client name and realm from.

     CLIENT: pointer to newly allocated zero terminated string
     containing principal name and realm.  May be `NULL' (to only
     populate `clientlen').

     CLIENTLEN: pointer to length of `client' on output, excluding
     terminating zero.  May be `NULL' (to only populate `client').

     Convert cname and realm fields from AS-REQ to printable principal
     name format.  The string is allocate by this function, and it is
     the responsibility of the caller to deallocate it.  Note that the
     output length `clientlen' does not include the terminating zero.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_kdcreq_realm
-------------------

 -- Function: int shishi_kdcreq_realm (Shishi * HANDLE, Shishi_asn1
          KDCREQ, char ** REALM, size_t * REALMLEN)
     HANDLE: Shishi library handle create by `shishi_init()'.

     KDCREQ: KDC-REQ variable to get client name from.

     REALM: pointer to newly allocated zero terminated string containing
     realm.  May be `NULL' (to only populate `realmlen').

     REALMLEN: pointer to length of `realm' on output, excluding
     terminating zero.  May be `NULL' (to only populate `realmlen').

     Get realm field in KDC-REQ as zero-terminated string.  The string
     is allocate by this function, and it is the responsibility of the
     caller to deallocate it.  Note that the output length `realmlen'
     does not include the terminating zero.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_kdcreq_set_realm
-----------------------

 -- Function: int shishi_kdcreq_set_realm (Shishi * HANDLE, Shishi_asn1
          KDCREQ, const char * REALM)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KDCREQ: KDC-REQ variable to set realm field in.

     REALM: input array with name of realm.

     Set the realm field in the KDC-REQ.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_kdcreq_server
--------------------

 -- Function: int shishi_kdcreq_server (Shishi * HANDLE, Shishi_asn1
          KDCREQ, char ** SERVER, size_t * SERVERLEN)
     HANDLE: Shishi library handle create by `shishi_init()'.

     KDCREQ: KDC-REQ variable to get server name from.

     SERVER: pointer to newly allocated zero terminated string
     containing principal name.  May be `NULL' (to only populate
     `serverlen').

     SERVERLEN: pointer to length of `server' on output, excluding
     terminating zero.  May be `NULL' (to only populate `server').

     Represent server principal name in KDC-REQ as zero-terminated
     string.  The string is allocate by this function, and it is the
     responsibility of the caller to deallocate it.  Note that the
     output length `serverlen' does not include the terminating zero.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_kdcreq_set_sname
-----------------------

 -- Function: int shishi_kdcreq_set_sname (Shishi * HANDLE, Shishi_asn1
          KDCREQ, Shishi_name_type NAME_TYPE, const char * [] SNAME)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KDCREQ: KDC-REQ variable to set server name field in.

     NAME_TYPE: type of principial, see Shishi_name_type, usually
     SHISHI_NT_UNKNOWN.

     SNAME: input array with principal name.

     Set the server name field in the KDC-REQ.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_kdcreq_till
------------------

 -- Function: int shishi_kdcreq_till (Shishi * HANDLE, Shishi_asn1
          KDCREQ, char ** TILL, size_t * TILLLEN)
     HANDLE: Shishi library handle create by `shishi_init()'.

     KDCREQ: KDC-REQ variable to get client name from.

     TILL: pointer to newly allocated zero terminated string containing
     "till" field with generalized time.  May be `NULL' (to only
     populate `realmlen').

     TILLLEN: pointer to length of `till' on output, excluding
     terminating zero.  May be `NULL' (to only populate `tilllen').

     Get "till" field (i.e. "endtime") in KDC-REQ, as zero-terminated
     string.  The string is typically 15 characters long.  The string is
     allocated by this function, and it is the responsibility of the
     caller to deallocate it.  Note that the output length `realmlen'
     does not include the terminating zero.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_kdcreq_tillc
-------------------

 -- Function: time_t shishi_kdcreq_tillc (Shishi * HANDLE, Shishi_asn1
          KDCREQ)
     HANDLE: Shishi library handle create by `shishi_init()'.

     KDCREQ: KDC-REQ variable to get till field from.

     Extract C time corresponding to the "till" field.

     *Return value:* Returns C time interpretation of the "till" field
     in KDC-REQ.

shishi_kdcreq_etype
-------------------

 -- Function: int shishi_kdcreq_etype (Shishi * HANDLE, Shishi_asn1
          KDCREQ, int32_t * ETYPE, int NETYPE)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KDCREQ: KDC-REQ variable to get etype field from.

     ETYPE: output encryption type.

     NETYPE: element number to return.

     *Return the netype:* th encryption type from KDC-REQ.  The first
     etype is number 1.

     *Return value:* Returns SHISHI_OK iff etype successful set.

shishi_kdcreq_set_etype
-----------------------

 -- Function: int shishi_kdcreq_set_etype (Shishi * HANDLE, Shishi_asn1
          KDCREQ, int32_t * ETYPE, int NETYPE)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KDCREQ: KDC-REQ variable to set etype field in.

     ETYPE: input array with encryption types.

     NETYPE: number of elements in input array with encryption types.

     Set the list of supported or wanted encryption types in the
     request.  The list should be sorted in priority order.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_kdcreq_options
---------------------

 -- Function: int shishi_kdcreq_options (Shishi * HANDLE, Shishi_asn1
          KDCREQ, uint32_t * FLAGS)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KDCREQ: KDC-REQ variable to get kdc-options field from.

     FLAGS: pointer to output integer with flags.

     Extract KDC-Options from KDC-REQ.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_kdcreq_forwardable_p
---------------------------

 -- Function: int shishi_kdcreq_forwardable_p (Shishi * HANDLE,
          Shishi_asn1 KDCREQ)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KDCREQ: KDC-REQ variable to get kdc-options field from.

     Determine if KDC-Option forwardable flag is set.

     The FORWARDABLE option indicates that the ticket to be issued is to
     have its forwardable flag set. It may only be set on the initial
     request, or in a subsequent request if the ticket-granting ticket
     on which it is based is also forwardable.

     *Return value:* Returns non-0 iff forwardable flag is set in
     KDC-REQ.

shishi_kdcreq_forwarded_p
-------------------------

 -- Function: int shishi_kdcreq_forwarded_p (Shishi * HANDLE,
          Shishi_asn1 KDCREQ)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KDCREQ: KDC-REQ variable to get kdc-options field from.

     Determine if KDC-Option forwarded flag is set.

     The FORWARDED option is only specified in a request to the
     ticket-granting server and will only be honored if the
     ticket-granting ticket in the request has its FORWARDABLE bit set.
     This option indicates that this is a request for forwarding. The
     address(es) of the host from which the resulting ticket is to be
     valid are included in the addresses field of the request.

     *Return value:* Returns non-0 iff forwarded flag is set in KDC-REQ.

shishi_kdcreq_proxiable_p
-------------------------

 -- Function: int shishi_kdcreq_proxiable_p (Shishi * HANDLE,
          Shishi_asn1 KDCREQ)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KDCREQ: KDC-REQ variable to get kdc-options field from.

     Determine if KDC-Option proxiable flag is set.

     The PROXIABLE option indicates that the ticket to be issued is to
     have its proxiable flag set. It may only be set on the initial
     request, or in a subsequent request if the ticket-granting ticket
     on which it is based is also proxiable.

     *Return value:* Returns non-0 iff proxiable flag is set in KDC-REQ.

shishi_kdcreq_proxy_p
---------------------

 -- Function: int shishi_kdcreq_proxy_p (Shishi * HANDLE, Shishi_asn1
          KDCREQ)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KDCREQ: KDC-REQ variable to get kdc-options field from.

     Determine if KDC-Option proxy flag is set.

     The PROXY option indicates that this is a request for a proxy. This
     option will only be honored if the ticket-granting ticket in the
     request has its PROXIABLE bit set.  The address(es) of the host
     from which the resulting ticket is to be valid are included in the
     addresses field of the request.

     *Return value:* Returns non-0 iff proxy flag is set in KDC-REQ.

shishi_kdcreq_allow_postdate_p
------------------------------

 -- Function: int shishi_kdcreq_allow_postdate_p (Shishi * HANDLE,
          Shishi_asn1 KDCREQ)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KDCREQ: KDC-REQ variable to get kdc-options field from.

     Determine if KDC-Option allow-postdate flag is set.

     The ALLOW-POSTDATE option indicates that the ticket to be issued is
     to have its MAY-POSTDATE flag set. It may only be set on the
     initial request, or in a subsequent request if the ticket-granting
     ticket on which it is based also has its MAY-POSTDATE flag set.

     *Return value:* Returns non-0 iff allow-postdate flag is set in
     KDC-REQ.

shishi_kdcreq_postdated_p
-------------------------

 -- Function: int shishi_kdcreq_postdated_p (Shishi * HANDLE,
          Shishi_asn1 KDCREQ)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KDCREQ: KDC-REQ variable to get kdc-options field from.

     Determine if KDC-Option postdated flag is set.

     The POSTDATED option indicates that this is a request for a
     postdated ticket. This option will only be honored if the
     ticket-granting ticket on which it is based has its MAY-POSTDATE
     flag set. The resulting ticket will also have its INVALID flag set,
     and that flag may be reset by a subsequent request to the KDC after
     the starttime in the ticket has been reached.

     *Return value:* Returns non-0 iff postdated flag is set in KDC-REQ.

shishi_kdcreq_renewable_p
-------------------------

 -- Function: int shishi_kdcreq_renewable_p (Shishi * HANDLE,
          Shishi_asn1 KDCREQ)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KDCREQ: KDC-REQ variable to get kdc-options field from.

     Determine if KDC-Option renewable flag is set.

     The RENEWABLE option indicates that the ticket to be issued is to
     have its RENEWABLE flag set. It may only be set on the initial
     request, or when the ticket-granting ticket on which the request is
     based is also renewable. If this option is requested, then the
     rtime field in the request contains the desired absolute expiration
     time for the ticket.

     *Return value:* Returns non-0 iff renewable flag is set in KDC-REQ.

shishi_kdcreq_disable_transited_check_p
---------------------------------------

 -- Function: int shishi_kdcreq_disable_transited_check_p (Shishi *
          HANDLE, Shishi_asn1 KDCREQ)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KDCREQ: KDC-REQ variable to get kdc-options field from.

     Determine if KDC-Option disable-transited-check flag is set.

     By default the KDC will check the transited field of a
     ticket-granting-ticket against the policy of the local realm before
     it will issue derivative tickets based on the ticket-granting
     ticket. If this flag is set in the request, checking of the
     transited field is disabled. Tickets issued without the performance
     of this check will be noted by the reset (0) value of the
     TRANSITED-POLICY-CHECKED flag, indicating to the application server
     that the tranisted field must be checked locally. KDCs are
     encouraged but not required to honor the DISABLE-TRANSITED-CHECK
     option.

     This flag is new since RFC 1510

     *Return value:* Returns non-0 iff disable-transited-check flag is
     set in KDC-REQ.

shishi_kdcreq_renewable_ok_p
----------------------------

 -- Function: int shishi_kdcreq_renewable_ok_p (Shishi * HANDLE,
          Shishi_asn1 KDCREQ)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KDCREQ: KDC-REQ variable to get kdc-options field from.

     Determine if KDC-Option renewable-ok flag is set.

     The RENEWABLE-OK option indicates that a renewable ticket will be
     acceptable if a ticket with the requested life cannot otherwise be
     provided. If a ticket with the requested life cannot be provided,
     then a renewable ticket may be issued with a renew-till equal to
     the requested endtime. The value of the renew-till field may still
     be limited by local limits, or limits selected by the individual
     principal or server.

     *Return value:* Returns non-0 iff renewable-ok flag is set in
     KDC-REQ.

shishi_kdcreq_enc_tkt_in_skey_p
-------------------------------

 -- Function: int shishi_kdcreq_enc_tkt_in_skey_p (Shishi * HANDLE,
          Shishi_asn1 KDCREQ)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KDCREQ: KDC-REQ variable to get kdc-options field from.

     Determine if KDC-Option enc-tkt-in-skey flag is set.

     This option is used only by the ticket-granting service. The
     ENC-TKT-IN-SKEY option indicates that the ticket for the end server
     is to be encrypted in the session key from the additional
     ticket-granting ticket provided.

     *Return value:* Returns non-0 iff enc-tkt-in-skey flag is set in
     KDC-REQ.

shishi_kdcreq_renew_p
---------------------

 -- Function: int shishi_kdcreq_renew_p (Shishi * HANDLE, Shishi_asn1
          KDCREQ)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KDCREQ: KDC-REQ variable to get kdc-options field from.

     Determine if KDC-Option renew flag is set.

     This option is used only by the ticket-granting service. The RENEW
     option indicates that the present request is for a renewal. The
     ticket provided is encrypted in the secret key for the server on
     which it is valid. This option will only be honored if the ticket
     to be renewed has its RENEWABLE flag set and if the time in its
     renew-till field has not passed. The ticket to be renewed is passed
     in the padata field as part of the authentication header.

     *Return value:* Returns non-0 iff renew flag is set in KDC-REQ.

shishi_kdcreq_validate_p
------------------------

 -- Function: int shishi_kdcreq_validate_p (Shishi * HANDLE,
          Shishi_asn1 KDCREQ)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KDCREQ: KDC-REQ variable to get kdc-options field from.

     Determine if KDC-Option validate flag is set.

     This option is used only by the ticket-granting service. The
     VALIDATE option indicates that the request is to validate a
     postdated ticket. It will only be honored if the ticket presented
     is postdated, presently has its INVALID flag set, and would be
     otherwise usable at this time. A ticket cannot be validated before
     its starttime. The ticket presented for validation is encrypted in
     the key of the server for which it is valid and is passed in the
     padata field as part of the authentication header.

     *Return value:* Returns non-0 iff validate flag is set in KDC-REQ.

shishi_kdcreq_options_set
-------------------------

 -- Function: int shishi_kdcreq_options_set (Shishi * HANDLE,
          Shishi_asn1 KDCREQ, uint32_t OPTIONS)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KDCREQ: KDC-REQ variable to set etype field in.

     OPTIONS: integer with flags to store in KDC-REQ.

     Set options in KDC-REQ.  Note that this reset any already existing
     flags.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_kdcreq_options_add
-------------------------

 -- Function: int shishi_kdcreq_options_add (Shishi * HANDLE,
          Shishi_asn1 KDCREQ, uint32_t OPTION)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KDCREQ: KDC-REQ variable to set etype field in.

     OPTION: integer with options to add in KDC-REQ.

     Add KDC-Option to KDC-REQ.  This preserves all existing options.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_kdcreq_clear_padata
--------------------------

 -- Function: int shishi_kdcreq_clear_padata (Shishi * HANDLE,
          Shishi_asn1 KDCREQ)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KDCREQ: KDC-REQ to remove PA-DATA from.

     Remove the padata field from KDC-REQ.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_kdcreq_get_padata
------------------------

 -- Function: int shishi_kdcreq_get_padata (Shishi * HANDLE,
          Shishi_asn1 KDCREQ, Shishi_padata_type PADATATYPE, char **
          OUT, size_t * OUTLEN)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KDCREQ: KDC-REQ to get PA-DATA from.

     PADATATYPE: type of PA-DATA, see Shishi_padata_type.

     OUT: output array with newly allocated PA-DATA value.

     OUTLEN: size of output array with PA-DATA value.

     Get pre authentication data (PA-DATA) from KDC-REQ.  Pre
     authentication data is used to pass various information to KDC,
     such as in case of a SHISHI_PA_TGS_REQ padatatype the AP-REQ that
     authenticates the user to get the ticket.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_kdcreq_get_padata_tgs
----------------------------

 -- Function: int shishi_kdcreq_get_padata_tgs (Shishi * HANDLE,
          Shishi_asn1 KDCREQ, Shishi_asn1 * APREQ)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KDCREQ: KDC-REQ to get PA-TGS-REQ from.

     APREQ: Output variable with newly allocated AP-REQ.

     Extract TGS pre-authentication data from KDC-REQ.  The data is an
     AP-REQ that authenticates the request.  This function call
     `shishi_kdcreq_get_padata()' with a SHISHI_PA_TGS_REQ padatatype
     and DER decode the result (if any).

     *Return value:* Returns SHISHI_OK iff successful.

shishi_kdcreq_add_padata
------------------------

 -- Function: int shishi_kdcreq_add_padata (Shishi * HANDLE,
          Shishi_asn1 KDCREQ, int PADATATYPE, const char * DATA, size_t
          DATALEN)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KDCREQ: KDC-REQ to add PA-DATA to.

     PADATATYPE: type of PA-DATA, see Shishi_padata_type.

     DATA: input array with PA-DATA value.

     DATALEN: size of input array with PA-DATA value.

     Add new pre authentication data (PA-DATA) to KDC-REQ.  This is used
     to pass various information to KDC, such as in case of a
     SHISHI_PA_TGS_REQ padatatype the AP-REQ that authenticates the user
     to get the ticket.  (But also see `shishi_kdcreq_add_padata_tgs()'
     which takes an AP-REQ directly.)

     *Return value:* Returns SHISHI_OK iff successful.

shishi_kdcreq_add_padata_tgs
----------------------------

 -- Function: int shishi_kdcreq_add_padata_tgs (Shishi * HANDLE,
          Shishi_asn1 KDCREQ, Shishi_asn1 APREQ)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KDCREQ: KDC-REQ to add PA-DATA to.

     APREQ: AP-REQ to add as PA-DATA.

     Add TGS pre-authentication data to KDC-REQ.  The data is an AP-REQ
     that authenticates the request.  This functions simply DER encodes
     the AP-REQ and calls `shishi_kdcreq_add_padata()' with a
     SHISHI_PA_TGS_REQ padatatype.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_kdcreq_add_padata_preauth
--------------------------------

 -- Function: int shishi_kdcreq_add_padata_preauth (Shishi * HANDLE,
          Shishi_asn1 KDCREQ, Shishi_key * KEY)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KDCREQ: KDC-REQ to add pre-authentication data to.

     KEY: Key used to encrypt pre-auth data.

     Add pre-authentication data to KDC-REQ.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_asrep
------------

 -- Function: Shishi_asn1 shishi_asrep (Shishi * HANDLE)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     This function creates a new AS-REP, populated with some default
     values.

     *Return value:* Returns the AS-REP or NULL on failure.

shishi_tgsrep
-------------

 -- Function: Shishi_asn1 shishi_tgsrep (Shishi * HANDLE)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     This function creates a new TGS-REP, populated with some default
     values.

     *Return value:* Returns the TGS-REP or NULL on failure.

shishi_kdcrep_print
-------------------

 -- Function: int shishi_kdcrep_print (Shishi * HANDLE, FILE * FH,
          Shishi_asn1 KDCREP)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     FH: file handle open for writing.

     KDCREP: KDC-REP to print.

     Print ASCII armored DER encoding of KDC-REP to file.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_kdcrep_save
------------------

 -- Function: int shishi_kdcrep_save (Shishi * HANDLE, FILE * FH,
          Shishi_asn1 KDCREP)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     FH: file handle open for writing.

     KDCREP: KDC-REP to save.

     Print  DER encoding of KDC-REP to file.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_kdcrep_to_file
---------------------

 -- Function: int shishi_kdcrep_to_file (Shishi * HANDLE, Shishi_asn1
          KDCREP, int FILETYPE, const char * FILENAME)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KDCREP: KDC-REP to save.

     FILETYPE: input variable specifying type of file to be written,
     see Shishi_filetype.

     FILENAME: input variable with filename to write to.

     Write KDC-REP to file in specified TYPE.  The file will be
     truncated if it exists.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_kdcrep_parse
-------------------

 -- Function: int shishi_kdcrep_parse (Shishi * HANDLE, FILE * FH,
          Shishi_asn1 * KDCREP)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     FH: file handle open for reading.

     KDCREP: output variable with newly allocated KDC-REP.

     Read ASCII armored DER encoded KDC-REP from file and populate given
     variable.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_kdcrep_read
------------------

 -- Function: int shishi_kdcrep_read (Shishi * HANDLE, FILE * FH,
          Shishi_asn1 * KDCREP)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     FH: file handle open for reading.

     KDCREP: output variable with newly allocated KDC-REP.

     Read DER encoded KDC-REP from file and populate given variable.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_kdcrep_from_file
-----------------------

 -- Function: int shishi_kdcrep_from_file (Shishi * HANDLE, Shishi_asn1
          * KDCREP, int FILETYPE, const char * FILENAME)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KDCREP: output variable with newly allocated KDC-REP.

     FILETYPE: input variable specifying type of file to be read, see
     Shishi_filetype.

     FILENAME: input variable with filename to read from.

     Read KDC-REP from file in specified TYPE.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_kdcrep_crealm_set
------------------------

 -- Function: int shishi_kdcrep_crealm_set (Shishi * HANDLE,
          Shishi_asn1 KDCREP, const char * CREALM)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KDCREP: Kdcrep variable to set realm field in.

     CREALM: input array with name of realm.

     Set the client realm field in the KDC-REP.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_kdcrep_cname_set
-----------------------

 -- Function: int shishi_kdcrep_cname_set (Shishi * HANDLE, Shishi_asn1
          KDCREP, Shishi_name_type NAME_TYPE, const char * [] CNAME)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KDCREP: Kdcrep variable to set server name field in.

     NAME_TYPE: type of principial, see Shishi_name_type, usually
     SHISHI_NT_UNKNOWN.

     CNAME: input array with principal name.

     Set the client name field in the KDC-REP.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_kdcrep_client_set
------------------------

 -- Function: int shishi_kdcrep_client_set (Shishi * HANDLE,
          Shishi_asn1 KDCREP, const char * CLIENT)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KDCREP: Kdcrep variable to set server name field in.

     CLIENT: zero-terminated string with principal name on RFC 1964
     form.

     Set the client name field in the KDC-REP.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_kdcrep_get_enc_part_etype
--------------------------------

 -- Function: int shishi_kdcrep_get_enc_part_etype (Shishi * HANDLE,
          Shishi_asn1 KDCREP, int32_t * ETYPE)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KDCREP: KDC-REP variable to get value from.

     ETYPE: output variable that holds the value.

     Extract KDC-REP.enc-part.etype.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_kdcrep_get_ticket
------------------------

 -- Function: int shishi_kdcrep_get_ticket (Shishi * HANDLE,
          Shishi_asn1 KDCREP, Shishi_asn1 * TICKET)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KDCREP: KDC-REP variable to get ticket from.

     TICKET: output variable to hold extracted ticket.

     Extract ticket from KDC-REP.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_kdcrep_set_ticket
------------------------

 -- Function: int shishi_kdcrep_set_ticket (Shishi * HANDLE,
          Shishi_asn1 KDCREP, Shishi_asn1 TICKET)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KDCREP: KDC-REP to add ticket field to.

     TICKET: input ticket to copy into KDC-REP ticket field.

     Copy ticket into KDC-REP.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_kdcrep_set_enc_part
--------------------------

 -- Function: int shishi_kdcrep_set_enc_part (Shishi * HANDLE,
          Shishi_asn1 KDCREP, int32_t ETYPE, uint32_t KVNO, const char
          * BUF, size_t BUFLEN)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KDCREP: KDC-REP to add enc-part field to.

     ETYPE: encryption type used to encrypt enc-part.

     KVNO: key version number.

     BUF: input array with encrypted enc-part.

     BUFLEN: size of input array with encrypted enc-part.

     Set the encrypted enc-part field in the KDC-REP.  The encrypted
     data is usually created by calling `shishi_encrypt()' on the DER
     encoded enc-part.  To save time, you may want to use
     `shishi_kdcrep_add_enc_part()' instead, which calculates the
     encrypted data and calls this function in one step.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_kdcrep_add_enc_part
--------------------------

 -- Function: int shishi_kdcrep_add_enc_part (Shishi * HANDLE,
          Shishi_asn1 KDCREP, Shishi_key * KEY, int KEYUSAGE,
          Shishi_asn1 ENCKDCREPPART)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KDCREP: KDC-REP to add enc-part field to.

     KEY: key used to encrypt enc-part.

     KEYUSAGE: key usage to use, normally SHISHI_KEYUSAGE_ENCASREPPART,
     SHISHI_KEYUSAGE_ENCTGSREPPART_SESSION_KEY or
     SHISHI_KEYUSAGE_ENCTGSREPPART_AUTHENTICATOR_KEY.

     ENCKDCREPPART: EncKDCRepPart to add.

     Encrypts DER encoded EncKDCRepPart using key and stores it in the
     KDC-REP.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_kdcrep_clear_padata
--------------------------

 -- Function: int shishi_kdcrep_clear_padata (Shishi * HANDLE,
          Shishi_asn1 KDCREP)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KDCREP: KDC-REP to remove PA-DATA from.

     Remove the padata field from KDC-REP.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_enckdcreppart_get_key
----------------------------

 -- Function: int shishi_enckdcreppart_get_key (Shishi * HANDLE,
          Shishi_asn1 ENCKDCREPPART, Shishi_key ** KEY)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     ENCKDCREPPART: input EncKDCRepPart variable.

     KEY: newly allocated encryption key handle.

     Extract the key to use with the ticket sent in the KDC-REP
     associated with the EncKDCRepPart input variable.

     *Return value:* Returns `SHISHI_OK' iff successful.

shishi_enckdcreppart_key_set
----------------------------

 -- Function: int shishi_enckdcreppart_key_set (Shishi * HANDLE,
          Shishi_asn1 ENCKDCREPPART, Shishi_key * KEY)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     ENCKDCREPPART: input EncKDCRepPart variable.

     KEY: key handle with information to store in enckdcreppart.

     Set the EncKDCRepPart.key field to key type and value of supplied
     key.

     *Return value:* Returns `SHISHI_OK' iff successful.

shishi_enckdcreppart_nonce_set
------------------------------

 -- Function: int shishi_enckdcreppart_nonce_set (Shishi * HANDLE,
          Shishi_asn1 ENCKDCREPPART, uint32_t NONCE)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     ENCKDCREPPART: input EncKDCRepPart variable.

     NONCE: nonce to set in EncKDCRepPart.

     Set the EncKDCRepPart.nonce field.

     *Return value:* Returns `SHISHI_OK' iff successful.

shishi_enckdcreppart_flags_set
------------------------------

 -- Function: int shishi_enckdcreppart_flags_set (Shishi * HANDLE,
          Shishi_asn1 ENCKDCREPPART, int FLAGS)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     ENCKDCREPPART: input EncKDCRepPart variable.

     FLAGS: flags to set in EncKDCRepPart.

     Set the EncKDCRepPart.flags field.

     *Return value:* Returns `SHISHI_OK' iff successful.

shishi_enckdcreppart_authtime_set
---------------------------------

 -- Function: int shishi_enckdcreppart_authtime_set (Shishi * HANDLE,
          Shishi_asn1 ENCKDCREPPART, const char * AUTHTIME)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     ENCKDCREPPART: input EncKDCRepPart variable.

     AUTHTIME: character buffer containing a generalized time string.

     Set the EncTicketPart.authtime to supplied value.

     *Return value:* Returns `SHISHI_OK' iff successful.

shishi_enckdcreppart_starttime_set
----------------------------------

 -- Function: int shishi_enckdcreppart_starttime_set (Shishi * HANDLE,
          Shishi_asn1 ENCKDCREPPART, const char * STARTTIME)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     ENCKDCREPPART: input EncKDCRepPart variable.

     STARTTIME: character buffer containing a generalized time string.

     Set the EncTicketPart.starttime to supplied value.  Use a NULL
     value for `starttime' to remove the field.

     *Return value:* Returns `SHISHI_OK' iff successful.

shishi_enckdcreppart_endtime_set
--------------------------------

 -- Function: int shishi_enckdcreppart_endtime_set (Shishi * HANDLE,
          Shishi_asn1 ENCKDCREPPART, const char * ENDTIME)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     ENCKDCREPPART: input EncKDCRepPart variable.

     ENDTIME: character buffer containing a generalized time string.

     Set the EncTicketPart.endtime to supplied value.

     *Return value:* Returns `SHISHI_OK' iff successful.

shishi_enckdcreppart_renew_till_set
-----------------------------------

 -- Function: int shishi_enckdcreppart_renew_till_set (Shishi * HANDLE,
          Shishi_asn1 ENCKDCREPPART, const char * RENEW_TILL)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     ENCKDCREPPART: input EncKDCRepPart variable.

     RENEW_TILL: character buffer containing a generalized time string.

     Set the EncTicketPart.renew-till to supplied value.  Use a NULL
     value for `renew_till' to remove the field.

     *Return value:* Returns `SHISHI_OK' iff successful.

shishi_enckdcreppart_srealm_set
-------------------------------

 -- Function: int shishi_enckdcreppart_srealm_set (Shishi * HANDLE,
          Shishi_asn1 ENCKDCREPPART, const char * SREALM)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     ENCKDCREPPART: EncKDCRepPart variable to set realm field in.

     SREALM: input array with name of realm.

     Set the server realm field in the EncKDCRepPart.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_enckdcreppart_sname_set
------------------------------

 -- Function: int shishi_enckdcreppart_sname_set (Shishi * HANDLE,
          Shishi_asn1 ENCKDCREPPART, Shishi_name_type NAME_TYPE, char *
          [] SNAME)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     ENCKDCREPPART: EncKDCRepPart variable to set server name field in.

     NAME_TYPE: type of principial, see Shishi_name_type, usually
     SHISHI_NT_UNKNOWN.

     SNAME: input array with principal name.

     Set the server name field in the EncKDCRepPart.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_enckdcreppart_populate_encticketpart
-------------------------------------------

 -- Function: int shishi_enckdcreppart_populate_encticketpart (Shishi *
          HANDLE, Shishi_asn1 ENCKDCREPPART, Shishi_asn1 ENCTICKETPART)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     ENCKDCREPPART: input EncKDCRepPart variable.

     ENCTICKETPART: input EncTicketPart variable.

     Set the flags, authtime, starttime, endtime, renew-till and caddr
     fields of the EncKDCRepPart to the corresponding values in the
     EncTicketPart.

     *Return value:* Returns `SHISHI_OK' iff successful.


File: shishi.info,  Node: Authenticator Functions,  Next: KRB-ERROR Functions,  Prev: AS/TGS Functions,  Up: Programming Manual

5.11 Authenticator Functions
============================

An "Authenticator" is an ASN.1 structure that work as a proof that an
entity owns a ticket.  It is usually embedded in the AP-REQ structure
(*note AP-REQ and AP-REP Functions::), and you most likely want to use
an AP-REQ instead of a Authenticator in normal applications.  The
following illustrates the Authenticator ASN.1 structure.


Authenticator	::= [APPLICATION 2] SEQUENCE  {
	authenticator-vno	[0] INTEGER (5),
	crealm			[1] Realm,
	cname			[2] PrincipalName,
	cksum			[3] Checksum OPTIONAL,
	cusec			[4] Microseconds,
	ctime			[5] KerberosTime,
	subkey			[6] EncryptionKey OPTIONAL,
	seq-number		[7] UInt32 OPTIONAL,
	authorization-data	[8] AuthorizationData OPTIONAL
}

shishi_authenticator
--------------------

 -- Function: Shishi_asn1 shishi_authenticator (Shishi * HANDLE)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     This function creates a new Authenticator, populated with some
     default values.  It uses the current time as returned by the system
     for the ctime and cusec fields.

     *Return value:* Returns the authenticator or NULL on failure.

shishi_authenticator_subkey
---------------------------

 -- Function: Shishi_asn1 shishi_authenticator_subkey (Shishi * HANDLE)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     This function creates a new Authenticator, populated with some
     default values.  It uses the current time as returned by the system
     for the ctime and cusec fields. It adds a random subkey.

     *Return value:* Returns the authenticator or NULL on failure.

shishi_authenticator_print
--------------------------

 -- Function: int shishi_authenticator_print (Shishi * HANDLE, FILE *
          FH, Shishi_asn1 AUTHENTICATOR)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     FH: file handle open for writing.

     AUTHENTICATOR: authenticator as allocated by
     `shishi_authenticator()'.

     Print ASCII armored DER encoding of authenticator to file.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_authenticator_save
-------------------------

 -- Function: int shishi_authenticator_save (Shishi * HANDLE, FILE *
          FH, Shishi_asn1 AUTHENTICATOR)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     FH: file handle open for writing.

     AUTHENTICATOR: authenticator as allocated by
     `shishi_authenticator()'.

     Save DER encoding of authenticator to file.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_authenticator_to_file
----------------------------

 -- Function: int shishi_authenticator_to_file (Shishi * HANDLE,
          Shishi_asn1 AUTHENTICATOR, int FILETYPE, const char *
          FILENAME)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     AUTHENTICATOR: Authenticator to save.

     FILETYPE: input variable specifying type of file to be written,
     see Shishi_filetype.

     FILENAME: input variable with filename to write to.

     Write Authenticator to file in specified TYPE.  The file will be
     truncated if it exists.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_authenticator_parse
--------------------------

 -- Function: int shishi_authenticator_parse (Shishi * HANDLE, FILE *
          FH, Shishi_asn1 * AUTHENTICATOR)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     FH: file handle open for reading.

     AUTHENTICATOR: output variable with newly allocated authenticator.

     Read ASCII armored DER encoded authenticator from file and populate
     given authenticator variable.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_authenticator_read
-------------------------

 -- Function: int shishi_authenticator_read (Shishi * HANDLE, FILE *
          FH, Shishi_asn1 * AUTHENTICATOR)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     FH: file handle open for reading.

     AUTHENTICATOR: output variable with newly allocated authenticator.

     Read DER encoded authenticator from file and populate given
     authenticator variable.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_authenticator_from_file
------------------------------

 -- Function: int shishi_authenticator_from_file (Shishi * HANDLE,
          Shishi_asn1 * AUTHENTICATOR, int FILETYPE, const char *
          FILENAME)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     AUTHENTICATOR: output variable with newly allocated Authenticator.

     FILETYPE: input variable specifying type of file to be read, see
     Shishi_filetype.

     FILENAME: input variable with filename to read from.

     Read Authenticator from file in specified TYPE.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_authenticator_set_crealm
-------------------------------

 -- Function: int shishi_authenticator_set_crealm (Shishi * HANDLE,
          Shishi_asn1 AUTHENTICATOR, const char * CREALM)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     AUTHENTICATOR: authenticator as allocated by
     `shishi_authenticator()'.

     CREALM: input array with realm.

     Set realm field in authenticator to specified value.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_authenticator_set_cname
------------------------------

 -- Function: int shishi_authenticator_set_cname (Shishi * HANDLE,
          Shishi_asn1 AUTHENTICATOR, Shishi_name_type NAME_TYPE, const
          char * [] CNAME)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     AUTHENTICATOR: authenticator as allocated by
     `shishi_authenticator()'.

     NAME_TYPE: type of principial, see Shishi_name_type, usually
     SHISHI_NT_UNKNOWN.

     CNAME: input array with principal name.

     Set principal field in authenticator to specified value.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_authenticator_client_set
-------------------------------

 -- Function: int shishi_authenticator_client_set (Shishi * HANDLE,
          Shishi_asn1 AUTHENTICATOR, const char * CLIENT)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     AUTHENTICATOR: Authenticator to set client name field in.

     CLIENT: zero-terminated string with principal name on RFC 1964
     form.

     Set the client name field in the Authenticator.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_authenticator_ctime
--------------------------

 -- Function: int shishi_authenticator_ctime (Shishi * HANDLE,
          Shishi_asn1 AUTHENTICATOR, char ** T)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     AUTHENTICATOR: Authenticator as allocated by
     `shishi_authenticator()'.

     T: newly allocated zero-terminated character array with client
     time.

     Extract client time from Authenticator.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_authenticator_ctime_set
------------------------------

 -- Function: int shishi_authenticator_ctime_set (Shishi * HANDLE,
          Shishi_asn1 AUTHENTICATOR, const char * T)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     AUTHENTICATOR: Authenticator as allocated by
     `shishi_authenticator()'.

     T: string with generalized time value to store in Authenticator.

     Store client time in Authenticator.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_authenticator_cusec_get
------------------------------

 -- Function: int shishi_authenticator_cusec_get (Shishi * HANDLE,
          Shishi_asn1 AUTHENTICATOR, uint32_t * CUSEC)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     AUTHENTICATOR: Authenticator as allocated by
     `shishi_authenticator()'.

     CUSEC: output integer with client microseconds field.

     Extract client microseconds field from Authenticator.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_authenticator_cusec_set
------------------------------

 -- Function: int shishi_authenticator_cusec_set (Shishi * HANDLE,
          Shishi_asn1 AUTHENTICATOR, uint32_t CUSEC)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     AUTHENTICATOR: authenticator as allocated by
     `shishi_authenticator()'.

     CUSEC: client microseconds to set in authenticator, 0-999999.

     Set the cusec field in the Authenticator.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_authenticator_seqnumber_get
----------------------------------

 -- Function: int shishi_authenticator_seqnumber_get (Shishi * HANDLE,
          Shishi_asn1 AUTHENTICATOR, uint32_t * SEQNUMBER)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     AUTHENTICATOR: authenticator as allocated by
     `shishi_authenticator()'.

     SEQNUMBER: output integer with sequence number field.

     Extract sequence number field from Authenticator.

     *Return value:* Returns `SHISHI_OK' iff successful.

shishi_authenticator_seqnumber_remove
-------------------------------------

 -- Function: int shishi_authenticator_seqnumber_remove (Shishi *
          HANDLE, Shishi_asn1 AUTHENTICATOR)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     AUTHENTICATOR: authenticator as allocated by
     `shishi_authenticator()'.

     Remove sequence number field in Authenticator.

     *Return value:* Returns `SHISHI_OK' iff successful.

shishi_authenticator_seqnumber_set
----------------------------------

 -- Function: int shishi_authenticator_seqnumber_set (Shishi * HANDLE,
          Shishi_asn1 AUTHENTICATOR, uint32_t SEQNUMBER)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     AUTHENTICATOR: authenticator as allocated by
     `shishi_authenticator()'.

     SEQNUMBER: integer with sequence number field to store in
     Authenticator.

     Store sequence number field in Authenticator.

     *Return value:* Returns `SHISHI_OK' iff successful.

shishi_authenticator_client
---------------------------

 -- Function: int shishi_authenticator_client (Shishi * HANDLE,
          Shishi_asn1 AUTHENTICATOR, char ** CLIENT, size_t * CLIENTLEN)
     HANDLE: Shishi library handle create by `shishi_init()'.

     AUTHENTICATOR: Authenticator variable to get client name from.

     CLIENT: pointer to newly allocated zero terminated string
     containing principal name.  May be `NULL' (to only populate
     `clientlen').

     CLIENTLEN: pointer to length of `client' on output, excluding
     terminating zero.  May be `NULL' (to only populate `client').

     Represent client principal name in Authenticator as zero-terminated
     string.  The string is allocate by this function, and it is the
     responsibility of the caller to deallocate it.  Note that the
     output length `clientlen' does not include the terminating zero.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_authenticator_clientrealm
--------------------------------

 -- Function: int shishi_authenticator_clientrealm (Shishi * HANDLE,
          Shishi_asn1 AUTHENTICATOR, char ** CLIENT, size_t * CLIENTLEN)
     HANDLE: Shishi library handle create by `shishi_init()'.

     AUTHENTICATOR: Authenticator variable to get client name and realm
     from.

     CLIENT: pointer to newly allocated zero terminated string
     containing principal name and realm.  May be `NULL' (to only
     populate `clientlen').

     CLIENTLEN: pointer to length of `client' on output, excluding
     terminating zero.  May be `NULL' (to only populate `client').

     Convert cname and realm fields from Authenticator to printable
     principal name format.  The string is allocate by this function,
     and it is the responsibility of the caller to deallocate it.  Note
     that the output length `clientlen' does not include the terminating
     zero.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_authenticator_cksum
--------------------------

 -- Function: int shishi_authenticator_cksum (Shishi * HANDLE,
          Shishi_asn1 AUTHENTICATOR, int32_t * CKSUMTYPE, char **
          CKSUM, size_t * CKSUMLEN)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     AUTHENTICATOR: authenticator as allocated by
     `shishi_authenticator()'.

     CKSUMTYPE: output checksum type.

     CKSUM: newly allocated output checksum data from authenticator.

     CKSUMLEN: on output, actual size of allocated output checksum data
     buffer.

     Read checksum value from authenticator.  `cksum' is allocated by
     this function, and it is the responsibility of caller to deallocate
     it.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_authenticator_set_cksum
------------------------------

 -- Function: int shishi_authenticator_set_cksum (Shishi * HANDLE,
          Shishi_asn1 AUTHENTICATOR, int32_t CKSUMTYPE, char * CKSUM,
          size_t CKSUMLEN)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     AUTHENTICATOR: authenticator as allocated by
     `shishi_authenticator()'.

     CKSUMTYPE: input checksum type to store in authenticator.

     CKSUM: input checksum data to store in authenticator.

     CKSUMLEN: size of input checksum data to store in authenticator.

     Store checksum value in authenticator.  A checksum is usually
     created by calling `shishi_checksum()' on some application
     specific data using the key from the ticket that is being used.
     To save time, you may want to use
     `shishi_authenticator_add_cksum()' instead, which calculates the
     checksum and calls this function in one step.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_authenticator_add_cksum
------------------------------

 -- Function: int shishi_authenticator_add_cksum (Shishi * HANDLE,
          Shishi_asn1 AUTHENTICATOR, Shishi_key * KEY, int KEYUSAGE,
          char * DATA, size_t DATALEN)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     AUTHENTICATOR: authenticator as allocated by
     `shishi_authenticator()'.

     KEY: key to to use for encryption.

     KEYUSAGE: cryptographic key usage value to use in encryption.

     DATA: input array with data to calculate checksum on.

     DATALEN: size of input array with data to calculate checksum on.

     Calculate checksum for data and store it in the authenticator.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_authenticator_add_cksum_type
-----------------------------------

 -- Function: int shishi_authenticator_add_cksum_type (Shishi * HANDLE,
          Shishi_asn1 AUTHENTICATOR, Shishi_key * KEY, int KEYUSAGE,
          int CKSUMTYPE, char * DATA, size_t DATALEN)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     AUTHENTICATOR: authenticator as allocated by
     `shishi_authenticator()'.

     KEY: key to to use for encryption.

     KEYUSAGE: cryptographic key usage value to use in encryption.

     CKSUMTYPE: checksum to type to calculate checksum.

     DATA: input array with data to calculate checksum on.

     DATALEN: size of input array with data to calculate checksum on.

     Calculate checksum for data and store it in the authenticator.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_authenticator_clear_authorizationdata
--------------------------------------------

 -- Function: int shishi_authenticator_clear_authorizationdata (Shishi
          * HANDLE, Shishi_asn1 AUTHENTICATOR)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     AUTHENTICATOR: Authenticator as allocated by
     `shishi_authenticator()'.

     Remove the authorization-data field from Authenticator.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_authenticator_add_authorizationdata
------------------------------------------

 -- Function: int shishi_authenticator_add_authorizationdata (Shishi *
          HANDLE, Shishi_asn1 AUTHENTICATOR, int32_t ADTYPE, const char
          * ADDATA, size_t ADDATALEN)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     AUTHENTICATOR: authenticator as allocated by
     `shishi_authenticator()'.

     ADTYPE: input authorization data type to add.

     ADDATA: input authorization data to add.

     ADDATALEN: size of input authorization data to add.

     Add authorization data to authenticator.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_authenticator_authorizationdata
--------------------------------------

 -- Function: int shishi_authenticator_authorizationdata (Shishi *
          HANDLE, Shishi_asn1 AUTHENTICATOR, int32_t * ADTYPE, char **
          ADDATA, size_t * ADDATALEN, size_t NTH)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     AUTHENTICATOR: authenticator as allocated by
     `shishi_authenticator()'.

     ADTYPE: output authorization data type.

     ADDATA: newly allocated output authorization data.

     ADDATALEN: on output, actual size of newly allocated authorization
     data.

     NTH: element number of authorization-data to extract.

     *Extract n:* th authorization data from authenticator.  The first
     field is 1.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_authenticator_remove_subkey
----------------------------------

 -- Function: int shishi_authenticator_remove_subkey (Shishi * HANDLE,
          Shishi_asn1 AUTHENTICATOR)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     AUTHENTICATOR: authenticator as allocated by
     `shishi_authenticator()'.

     Remove subkey from the authenticator.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_authenticator_get_subkey
-------------------------------

 -- Function: int shishi_authenticator_get_subkey (Shishi * HANDLE,
          Shishi_asn1 AUTHENTICATOR, Shishi_key ** SUBKEY)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     AUTHENTICATOR: authenticator as allocated by
     `shishi_authenticator()'.

     SUBKEY: output newly allocated subkey from authenticator.

     Read subkey value from authenticator.

     *Return value:* Returns SHISHI_OK if successful or
     SHISHI_ASN1_NO_ELEMENT if subkey is not present.

shishi_authenticator_set_subkey
-------------------------------

 -- Function: int shishi_authenticator_set_subkey (Shishi * HANDLE,
          Shishi_asn1 AUTHENTICATOR, int32_t SUBKEYTYPE, const char *
          SUBKEY, size_t SUBKEYLEN)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     AUTHENTICATOR: authenticator as allocated by
     `shishi_authenticator()'.

     SUBKEYTYPE: input subkey type to store in authenticator.

     SUBKEY: input subkey data to store in authenticator.

     SUBKEYLEN: size of input subkey data to store in authenticator.

     Store subkey value in authenticator.  A subkey is usually created
     by calling `shishi_key_random()' using the default encryption type
     of the key from the ticket that is being used.  To save time, you
     may want to use `shishi_authenticator_add_subkey()' instead, which
     calculates the subkey and calls this function in one step.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_authenticator_add_random_subkey
--------------------------------------

 -- Function: int shishi_authenticator_add_random_subkey (Shishi *
          HANDLE, Shishi_asn1 AUTHENTICATOR)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     AUTHENTICATOR: authenticator as allocated by
     `shishi_authenticator()'.

     Generate random subkey, of the default encryption type from
     configuration, and store it in the authenticator.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_authenticator_add_random_subkey_etype
--------------------------------------------

 -- Function: int shishi_authenticator_add_random_subkey_etype (Shishi
          * HANDLE, Shishi_asn1 AUTHENTICATOR, int ETYPE)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     AUTHENTICATOR: authenticator as allocated by
     `shishi_authenticator()'.

     ETYPE: encryption type of random key to generate.

     Generate random subkey of indicated encryption type, and store it
     in the authenticator.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_authenticator_add_subkey
-------------------------------

 -- Function: int shishi_authenticator_add_subkey (Shishi * HANDLE,
          Shishi_asn1 AUTHENTICATOR, Shishi_key * SUBKEY)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     AUTHENTICATOR: authenticator as allocated by
     `shishi_authenticator()'.

     SUBKEY: subkey to add to authenticator.

     Store subkey in the authenticator.

     *Return value:* Returns SHISHI_OK iff successful.


File: shishi.info,  Node: KRB-ERROR Functions,  Next: Cryptographic Functions,  Prev: Authenticator Functions,  Up: Programming Manual

5.12 KRB-ERROR Functions
========================

The "KRB-ERROR" is an ASN.1 structure that can be returned, instead of,
e.g., KDC-REP or AP-REP, to indicate various error conditions.
Unfortunately, the semantics of several of the fields are ill
specified, so the typically procedure is to extract "e-text" and/or
"e-data" and show it to the user.  The following illustrates the
KRB-ERROR ASN.1 structure.


KRB-ERROR       ::= [APPLICATION 30] SEQUENCE {
        pvno            [0] INTEGER (5),
        msg-type        [1] INTEGER (30),
        ctime           [2] KerberosTime OPTIONAL,
        cusec           [3] Microseconds OPTIONAL,
        stime           [4] KerberosTime,
        susec           [5] Microseconds,
        error-code      [6] Int32,
        crealm          [7] Realm OPTIONAL,
        cname           [8] PrincipalName OPTIONAL,
        realm           [9] Realm -- service realm --,
        sname           [10] PrincipalName -- service name --,
        e-text          [11] KerberosString OPTIONAL,
        e-data          [12] OCTET STRING OPTIONAL
}

shishi_krberror
---------------

 -- Function: Shishi_asn1 shishi_krberror (Shishi * HANDLE)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     This function creates a new KRB-ERROR, populated with some default
     values.

     *Return value:* Returns the KRB-ERROR or NULL on failure.

shishi_krberror_print
---------------------

 -- Function: int shishi_krberror_print (Shishi * HANDLE, FILE * FH,
          Shishi_asn1 KRBERROR)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     FH: file handle open for writing.

     KRBERROR: KRB-ERROR to print.

     Print ASCII armored DER encoding of KRB-ERROR to file.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_krberror_save
--------------------

 -- Function: int shishi_krberror_save (Shishi * HANDLE, FILE * FH,
          Shishi_asn1 KRBERROR)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     FH: file handle open for writing.

     KRBERROR: KRB-ERROR to save.

     Save DER encoding of KRB-ERROR to file.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_krberror_to_file
-----------------------

 -- Function: int shishi_krberror_to_file (Shishi * HANDLE, Shishi_asn1
          KRBERROR, int FILETYPE, const char * FILENAME)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KRBERROR: KRB-ERROR to save.

     FILETYPE: input variable specifying type of file to be written,
     see Shishi_filetype.

     FILENAME: input variable with filename to write to.

     Write KRB-ERROR to file in specified TYPE.  The file will be
     truncated if it exists.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_krberror_parse
---------------------

 -- Function: int shishi_krberror_parse (Shishi * HANDLE, FILE * FH,
          Shishi_asn1 * KRBERROR)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     FH: file handle open for reading.

     KRBERROR: output variable with newly allocated KRB-ERROR.

     Read ASCII armored DER encoded KRB-ERROR from file and populate
     given variable.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_krberror_read
--------------------

 -- Function: int shishi_krberror_read (Shishi * HANDLE, FILE * FH,
          Shishi_asn1 * KRBERROR)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     FH: file handle open for reading.

     KRBERROR: output variable with newly allocated KRB-ERROR.

     Read DER encoded KRB-ERROR from file and populate given variable.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_krberror_from_file
-------------------------

 -- Function: int shishi_krberror_from_file (Shishi * HANDLE,
          Shishi_asn1 * KRBERROR, int FILETYPE, const char * FILENAME)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KRBERROR: output variable with newly allocated KRB-ERROR.

     FILETYPE: input variable specifying type of file to be read, see
     Shishi_filetype.

     FILENAME: input variable with filename to read from.

     Read KRB-ERROR from file in specified TYPE.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_krberror_build
---------------------

 -- Function: int shishi_krberror_build (Shishi * HANDLE, Shishi_asn1
          KRBERROR)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KRBERROR: krberror as allocated by `shishi_krberror()'.

     Finish KRB-ERROR, called before e.g. shishi_krberror_der.  This
     function removes empty but OPTIONAL fields (such as cname), and

     *Return value:* Returns SHISHI_OK iff successful.

shishi_krberror_der
-------------------

 -- Function: int shishi_krberror_der (Shishi * HANDLE, Shishi_asn1
          KRBERROR, char ** OUT, size_t * OUTLEN)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KRBERROR: krberror as allocated by `shishi_krberror()'.

     OUT: output array with newly allocated DER encoding of KRB-ERROR.

     OUTLEN: length of output array with DER encoding of KRB-ERROR.

     DER encode KRB-ERROR.  The caller must deallocate the OUT buffer.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_krberror_crealm
----------------------

 -- Function: int shishi_krberror_crealm (Shishi * HANDLE, Shishi_asn1
          KRBERROR, char ** REALM, size_t * REALMLEN)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KRBERROR: krberror as allocated by `shishi_krberror()'.

     REALM: output array with newly allocated name of realm in
     KRB-ERROR.

     REALMLEN: size of output array.

     Extract client realm from KRB-ERROR.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_krberror_remove_crealm
-----------------------------

 -- Function: int shishi_krberror_remove_crealm (Shishi * HANDLE,
          Shishi_asn1 KRBERROR)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KRBERROR: krberror as allocated by `shishi_krberror()'.

     Remove client realm field in KRB-ERROR.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_krberror_set_crealm
--------------------------

 -- Function: int shishi_krberror_set_crealm (Shishi * HANDLE,
          Shishi_asn1 KRBERROR, const char * CREALM)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KRBERROR: krberror as allocated by `shishi_krberror()'.

     CREALM: input array with realm.

     Set realm field in krberror to specified value.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_krberror_client
----------------------

 -- Function: int shishi_krberror_client (Shishi * HANDLE, Shishi_asn1
          KRBERROR, char ** CLIENT, size_t * CLIENTLEN)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KRBERROR: krberror as allocated by `shishi_krberror()'.

     CLIENT: pointer to newly allocated zero terminated string
     containing principal name.  May be `NULL' (to only populate
     `clientlen').

     CLIENTLEN: pointer to length of `client' on output, excluding
     terminating zero.  May be `NULL' (to only populate `client').

     Return client principal name in KRB-ERROR.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_krberror_set_cname
-------------------------

 -- Function: int shishi_krberror_set_cname (Shishi * HANDLE,
          Shishi_asn1 KRBERROR, Shishi_name_type NAME_TYPE, const char
          * [] CNAME)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KRBERROR: krberror as allocated by `shishi_krberror()'.

     NAME_TYPE: type of principial, see Shishi_name_type, usually
     SHISHI_NT_UNKNOWN.

     CNAME: input array with principal name.

     Set principal field in krberror to specified value.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_krberror_remove_cname
----------------------------

 -- Function: int shishi_krberror_remove_cname (Shishi * HANDLE,
          Shishi_asn1 KRBERROR)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KRBERROR: krberror as allocated by `shishi_krberror()'.

     Remove client realm field in KRB-ERROR.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_krberror_client_set
--------------------------

 -- Function: int shishi_krberror_client_set (Shishi * HANDLE,
          Shishi_asn1 KRBERROR, const char * CLIENT)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KRBERROR: Krberror to set client name field in.

     CLIENT: zero-terminated string with principal name on RFC 1964
     form.

     Set the client name field in the Krberror.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_krberror_realm
---------------------

 -- Function: int shishi_krberror_realm (Shishi * HANDLE, Shishi_asn1
          KRBERROR, char ** REALM, size_t * REALMLEN)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KRBERROR: krberror as allocated by `shishi_krberror()'.

     REALM: output array with newly allocated name of realm in
     KRB-ERROR.

     REALMLEN: size of output array.

     Extract (server) realm from KRB-ERROR.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_krberror_set_realm
-------------------------

 -- Function: int shishi_krberror_set_realm (Shishi * HANDLE,
          Shishi_asn1 KRBERROR, const char * REALM)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KRBERROR: krberror as allocated by `shishi_krberror()'.

     REALM: input array with (server) realm.

     Set (server) realm field in krberror to specified value.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_krberror_server
----------------------

 -- Function: int shishi_krberror_server (Shishi * HANDLE, Shishi_asn1
          KRBERROR, char ** SERVER, size_t * SERVERLEN)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KRBERROR: krberror as allocated by `shishi_krberror()'.

     SERVER: pointer to newly allocated zero terminated string
     containing server name.  May be `NULL' (to only populate
     `serverlen').

     SERVERLEN: pointer to length of `server' on output, excluding
     terminating zero.  May be `NULL' (to only populate `server').

     Return server principal name in KRB-ERROR.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_krberror_remove_sname
----------------------------

 -- Function: int shishi_krberror_remove_sname (Shishi * HANDLE,
          Shishi_asn1 KRBERROR)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KRBERROR: Krberror to set server name field in.

     Remove server name field in KRB-ERROR.  (Since it is not marked
     OPTIONAL in the ASN.1 profile, what is done is to set the name-type
     to UNKNOWN and make sure the name-string sequence is empty.)

     *Return value:* Returns SHISHI_OK iff successful.

shishi_krberror_set_sname
-------------------------

 -- Function: int shishi_krberror_set_sname (Shishi * HANDLE,
          Shishi_asn1 KRBERROR, Shishi_name_type NAME_TYPE, const char
          * [] SNAME)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KRBERROR: krberror as allocated by `shishi_krberror()'.

     NAME_TYPE: type of principial, see Shishi_name_type, usually
     SHISHI_NT_UNKNOWN.

     SNAME: input array with principal name.

     Set principal field in krberror to specified value.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_krberror_server_set
--------------------------

 -- Function: int shishi_krberror_server_set (Shishi * HANDLE,
          Shishi_asn1 KRBERROR, const char * SERVER)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KRBERROR: Krberror to set server name field in.

     SERVER: zero-terminated string with principal name on RFC 1964
     form.

     Set the server name field in the Krberror.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_krberror_ctime
---------------------

 -- Function: int shishi_krberror_ctime (Shishi * HANDLE, Shishi_asn1
          KRBERROR, char ** T)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KRBERROR: Krberror to set client name field in.

     T: newly allocated zero-terminated output array with client time.

     Extract client time from KRB-ERROR.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_krberror_ctime_set
-------------------------

 -- Function: int shishi_krberror_ctime_set (Shishi * HANDLE,
          Shishi_asn1 KRBERROR, const char * T)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KRBERROR: Krberror as allocated by `shishi_krberror()'.

     T: string with generalized time value to store in Krberror.

     Store client time in Krberror.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_krberror_remove_ctime
----------------------------

 -- Function: int shishi_krberror_remove_ctime (Shishi * HANDLE,
          Shishi_asn1 KRBERROR)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KRBERROR: Krberror as allocated by `shishi_krberror()'.

     Remove client time field in Krberror.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_krberror_cusec
---------------------

 -- Function: int shishi_krberror_cusec (Shishi * HANDLE, Shishi_asn1
          KRBERROR, uint32_t * CUSEC)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KRBERROR: Krberror as allocated by `shishi_krberror()'.

     CUSEC: output integer with client microseconds field.

     Extract client microseconds field from Krberror.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_krberror_cusec_set
-------------------------

 -- Function: int shishi_krberror_cusec_set (Shishi * HANDLE,
          Shishi_asn1 KRBERROR, uint32_t CUSEC)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KRBERROR: krberror as allocated by `shishi_krberror()'.

     CUSEC: client microseconds to set in krberror, 0-999999.

     Set the cusec field in the Krberror.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_krberror_remove_cusec
----------------------------

 -- Function: int shishi_krberror_remove_cusec (Shishi * HANDLE,
          Shishi_asn1 KRBERROR)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KRBERROR: Krberror as allocated by `shishi_krberror()'.

     Remove client usec field in Krberror.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_krberror_stime
---------------------

 -- Function: int shishi_krberror_stime (Shishi * HANDLE, Shishi_asn1
          KRBERROR, char ** T)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KRBERROR: Krberror to set client name field in.

     T: newly allocated zero-terminated output array with server time.

     Extract server time from KRB-ERROR.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_krberror_stime_set
-------------------------

 -- Function: int shishi_krberror_stime_set (Shishi * HANDLE,
          Shishi_asn1 KRBERROR, const char * T)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KRBERROR: Krberror as allocated by `shishi_krberror()'.

     T: string with generalized time value to store in Krberror.

     Store server time in Krberror.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_krberror_susec
---------------------

 -- Function: int shishi_krberror_susec (Shishi * HANDLE, Shishi_asn1
          KRBERROR, uint32_t * SUSEC)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KRBERROR: Krberror as allocated by `shishi_krberror()'.

     SUSEC: output integer with server microseconds field.

     Extract server microseconds field from Krberror.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_krberror_susec_set
-------------------------

 -- Function: int shishi_krberror_susec_set (Shishi * HANDLE,
          Shishi_asn1 KRBERROR, uint32_t SUSEC)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KRBERROR: krberror as allocated by `shishi_krberror()'.

     SUSEC: server microseconds to set in krberror, 0-999999.

     Set the susec field in the Krberror.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_krberror_errorcode
-------------------------

 -- Function: int shishi_krberror_errorcode (Shishi * HANDLE,
          Shishi_asn1 KRBERROR, int32_t * ERRORCODE)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KRBERROR: KRB-ERROR structure with error code.

     ERRORCODE: output integer KRB-ERROR error code.

     Extract error code from KRB-ERROR.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_krberror_errorcode_fast
------------------------------

 -- Function: int shishi_krberror_errorcode_fast (Shishi * HANDLE,
          Shishi_asn1 KRBERROR)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KRBERROR: KRB-ERROR structure with error code.

     Get error code from KRB-ERROR, without error checking.

     *Return value:* Return error code (see
     `shishi_krberror_errorcode()') directly, or -1 on error.

shishi_krberror_errorcode_set
-----------------------------

 -- Function: int shishi_krberror_errorcode_set (Shishi * HANDLE,
          Shishi_asn1 KRBERROR, int ERRORCODE)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KRBERROR: KRB-ERROR structure with error code to set.

     ERRORCODE: new error code to set in krberror.

     Set the error-code field to a new error code.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_krberror_etext
---------------------

 -- Function: int shishi_krberror_etext (Shishi * HANDLE, Shishi_asn1
          KRBERROR, char ** ETEXT, size_t * ETEXTLEN)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KRBERROR: KRB-ERROR structure with error code.

     ETEXT: output array with newly allocated error text.

     ETEXTLEN: output length of error text.

     Extract additional error text from server (possibly empty).

     *Return value:* Returns SHISHI_OK iff successful.

shishi_krberror_set_etext
-------------------------

 -- Function: int shishi_krberror_set_etext (Shishi * HANDLE,
          Shishi_asn1 KRBERROR, const char * ETEXT)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KRBERROR: krberror as allocated by `shishi_krberror()'.

     ETEXT: input array with error text to set.

     Set error text (e-text) field in KRB-ERROR to specified value.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_krberror_remove_etext
----------------------------

 -- Function: int shishi_krberror_remove_etext (Shishi * HANDLE,
          Shishi_asn1 KRBERROR)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KRBERROR: krberror as allocated by `shishi_krberror()'.

     Remove error text (e-text) field in KRB-ERROR.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_krberror_edata
---------------------

 -- Function: int shishi_krberror_edata (Shishi * HANDLE, Shishi_asn1
          KRBERROR, char ** EDATA, size_t * EDATALEN)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KRBERROR: KRB-ERROR structure with error code.

     EDATA: output array with newly allocated error data.

     EDATALEN: output length of error data.

     Extract additional error data from server (possibly empty).

     *Return value:* Returns SHISHI_OK iff successful.

shishi_krberror_methoddata
--------------------------

 -- Function: int shishi_krberror_methoddata (Shishi * HANDLE,
          Shishi_asn1 KRBERROR, Shishi_asn1 * METHODDATA)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KRBERROR: KRB-ERROR structure with error code.

     METHODDATA: output ASN.1 METHOD-DATA.

     Extract METHOD-DATA ASN.1 object from the e-data field.  The e-data
     field will only contain a METHOD-DATA if the krberror error code is
     `SHISHI_KDC_ERR_PREAUTH_REQUIRED'.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_krberror_set_edata
-------------------------

 -- Function: int shishi_krberror_set_edata (Shishi * HANDLE,
          Shishi_asn1 KRBERROR, const char * EDATA)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KRBERROR: krberror as allocated by `shishi_krberror()'.

     EDATA: input array with error text to set.

     Set error text (e-data) field in KRB-ERROR to specified value.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_krberror_remove_edata
----------------------------

 -- Function: int shishi_krberror_remove_edata (Shishi * HANDLE,
          Shishi_asn1 KRBERROR)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KRBERROR: krberror as allocated by `shishi_krberror()'.

     Remove error text (e-data) field in KRB-ERROR.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_krberror_pretty_print
----------------------------

 -- Function: int shishi_krberror_pretty_print (Shishi * HANDLE, FILE *
          FH, Shishi_asn1 KRBERROR)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     FH: file handle opened for writing.

     KRBERROR: KRB-ERROR structure with error code.

     Print KRB-ERROR error condition and some explanatory text to file
     descriptor.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_krberror_errorcode_message
---------------------------------

 -- Function: const char * shishi_krberror_errorcode_message (Shishi *
          HANDLE, int ERRORCODE)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     ERRORCODE: integer KRB-ERROR error code.

     Get human readable string describing KRB-ERROR code.

     *Return value:* Return a string describing error code.  This
     function will always return a string even if the error code isn't
     known.

shishi_krberror_message
-----------------------

 -- Function: const char * shishi_krberror_message (Shishi * HANDLE,
          Shishi_asn1 KRBERROR)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KRBERROR: KRB-ERROR structure with error code.

     Extract error code (see `shishi_krberror_errorcode_fast()') and
     return error message (see `shishi_krberror_errorcode_message()').

     *Return value:* Return a string describing error code.  This
     function will always return a string even if the error code isn't
     known.


File: shishi.info,  Node: Cryptographic Functions,  Next: X.509 Functions,  Prev: KRB-ERROR Functions,  Up: Programming Manual

5.13 Cryptographic Functions
============================

Underneath the high-level functions described earlier, cryptographic
operations are happening.  If you need to access these cryptographic
primitives directly, this section describes the functions available.

   Most cryptographic operations need keying material, and cryptographic
keys have been isolated into it's own data structure `Shishi_key'.  The
following illustrates it's contents, but note that you cannot access
it's elements directly but must use the accessor functions described
below.


struct Shishi_key
{
  int type;    /* RFC 1510 encryption integer type */
  char *value; /* Cryptographic key data */
  int version; /* RFC 1510 ``kvno'' */
};

   All functions that operate on this data structure are described now.

shishi_key_principal
--------------------

 -- Function: const char * shishi_key_principal (const Shishi_key * KEY)
     KEY: structure that holds key information

     Get the principal part of the key owner principal name, i.e.,
     except the realm.

     *Return value:* Returns the principal owning the key.  (Not a copy
     of it, so don't modify or deallocate it.)

shishi_key_principal_set
------------------------

 -- Function: void shishi_key_principal_set (Shishi_key * KEY, const
          char * PRINCIPAL)
     KEY: structure that holds key information

     PRINCIPAL: string with new principal name.

     Set the principal owning the key. The string is copied into the
     key, so you can dispose of the variable immediately after calling
     this function.

shishi_key_realm
----------------

 -- Function: const char * shishi_key_realm (const Shishi_key * KEY)
     KEY: structure that holds key information

     Get the realm part of the key owner principal name.

     *Return value:* Returns the realm for the principal owning the key.
     (Not a copy of it, so don't modify or deallocate it.)

shishi_key_realm_set
--------------------

 -- Function: void shishi_key_realm_set (Shishi_key * KEY, const char *
          REALM)
     KEY: structure that holds key information

     REALM: string with new realm name.

     Set the realm for the principal owning the key. The string is
     copied into the key, so you can dispose of the variable immediately
     after calling this function.

shishi_key_type
---------------

 -- Function: int shishi_key_type (const Shishi_key * KEY)
     KEY: structure that holds key information

     Get key type.

     *Return value:* Returns the type of key as an integer as described
     in the standard.

shishi_key_type_set
-------------------

 -- Function: void shishi_key_type_set (Shishi_key * KEY, int32_t TYPE)
     KEY: structure that holds key information

     TYPE: type to set in key.

     Set the type of key in key structure.

shishi_key_value
----------------

 -- Function: const char * shishi_key_value (const Shishi_key * KEY)
     KEY: structure that holds key information

     Get the raw key bytes.

     *Return value:* Returns the key value as a pointer which is valid
     throughout the lifetime of the key structure.

shishi_key_value_set
--------------------

 -- Function: void shishi_key_value_set (Shishi_key * KEY, const char *
          VALUE)
     KEY: structure that holds key information

     VALUE: input array with key data.

     Set the key value and length in key structure.  The value is copied
     into the key (in other words, you can deallocate `value' right
     after calling this function without modifying the value inside the
     key).

shishi_key_version
------------------

 -- Function: uint32_t shishi_key_version (const Shishi_key * KEY)
     KEY: structure that holds key information

     Get the "kvno" (key version) of key.  It will be UINT32_MAX if the
     key is not long-lived.

     *Return value:* Returns the version of key ("kvno").

shishi_key_version_set
----------------------

 -- Function: void shishi_key_version_set (Shishi_key * KEY, uint32_t
          KVNO)
     KEY: structure that holds key information

     KVNO: new version integer.

     Set the version of key ("kvno") in key structure.  Use UINT32_MAX
     for non-ptermanent keys.

shishi_key_timestamp
--------------------

 -- Function: time_t shishi_key_timestamp (const Shishi_key * KEY)
     KEY: structure that holds key information

     Get the time the key was established.  Typically only present when
     the key was imported from a keytab format.

     *Return value:* Returns the time the key was established, or
     (time_t)-1 if not available.

     *Since:* 0.0.42

shishi_key_timestamp_set
------------------------

 -- Function: void shishi_key_timestamp_set (Shishi_key * KEY, time_t
          TIMESTAMP)
     KEY: structure that holds key information

     TIMESTAMP: new timestamp.

     Set the time the key was established.  Typically only relevant when
     exporting the key to keytab format.

     *Since:* 0.0.42

shishi_key_name
---------------

 -- Function: const char * shishi_key_name (Shishi_key * KEY)
     KEY: structure that holds key information

     Calls shishi_cipher_name for key type.

     *Return value:* Return name of key.

shishi_key_length
-----------------

 -- Function: size_t shishi_key_length (const Shishi_key * KEY)
     KEY: structure that holds key information

     Calls shishi_cipher_keylen for key type.

     *Return value:* Returns the length of the key value.

shishi_key
----------

 -- Function: int shishi_key (Shishi * HANDLE, Shishi_key ** KEY)
     HANDLE: Shishi library handle create by `shishi_init()'.

     KEY: pointer to structure that will hold newly created key
     information

     Create a new Key information structure.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_key_done
---------------

 -- Function: void shishi_key_done (Shishi_key * KEY)
     KEY: pointer to structure that holds key information.

     Deallocates key information structure.

shishi_key_copy
---------------

 -- Function: void shishi_key_copy (Shishi_key * DSTKEY, Shishi_key *
          SRCKEY)
     DSTKEY: structure that holds destination key information

     SRCKEY: structure that holds source key information

     Copies source key into existing allocated destination key.

shishi_key_from_value
---------------------

 -- Function: int shishi_key_from_value (Shishi * HANDLE, int32_t TYPE,
          const char * VALUE, Shishi_key ** KEY)
     HANDLE: Shishi library handle create by `shishi_init()'.

     TYPE: type of key.

     VALUE: input array with key value, or NULL.

     KEY: pointer to structure that will hold newly created key
     information

     Create a new Key information structure, and set the key type and
     key value. KEY contains a newly allocated structure only if this
     function is successful.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_key_from_base64
----------------------

 -- Function: int shishi_key_from_base64 (Shishi * HANDLE, int32_t
          TYPE, const char * VALUE, Shishi_key ** KEY)
     HANDLE: Shishi library handle create by `shishi_init()'.

     TYPE: type of key.

     VALUE: input string with base64 encoded key value, or NULL.

     KEY: pointer to structure that will hold newly created key
     information

     Create a new Key information structure, and set the key type and
     key value. KEY contains a newly allocated structure only if this
     function is successful.

     *Return value:* Returns SHISHI_INVALID_KEY if the base64 encoded
     key length doesn't match the key type, and SHISHI_OK on success.

shishi_key_random
-----------------

 -- Function: int shishi_key_random (Shishi * HANDLE, int32_t TYPE,
          Shishi_key ** KEY)
     HANDLE: Shishi library handle create by `shishi_init()'.

     TYPE: type of key.

     KEY: pointer to structure that will hold newly created key
     information

     Create a new Key information structure for the key type and some
     random data.  KEY contains a newly allocated structure only if this
     function is successful.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_key_from_random
----------------------

 -- Function: int shishi_key_from_random (Shishi * HANDLE, int32_t
          TYPE, const char * RND, size_t RNDLEN, Shishi_key ** OUTKEY)
     HANDLE: Shishi library handle create by `shishi_init()'.

     TYPE: type of key.

     RND: random data.

     RNDLEN: length of random data.

     OUTKEY: pointer to structure that will hold newly created key
     information

     Create a new Key information structure, and set the key type and
     key value using `shishi_random_to_key()'.  KEY contains a newly
     allocated structure only if this function is successful.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_key_from_string
----------------------

 -- Function: int shishi_key_from_string (Shishi * HANDLE, int32_t
          TYPE, const char * PASSWORD, size_t PASSWORDLEN, const char *
          SALT, size_t SALTLEN, const char * PARAMETER, Shishi_key **
          OUTKEY)
     HANDLE: Shishi library handle create by `shishi_init()'.

     TYPE: type of key.

     PASSWORD: input array containing password.

     PASSWORDLEN: length of input array containing password.

     SALT: input array containing salt.

     SALTLEN: length of input array containing salt.

     PARAMETER: input array with opaque encryption type specific
     information.

     OUTKEY: pointer to structure that will hold newly created key
     information

     Create a new Key information structure, and set the key type and
     key value using `shishi_string_to_key()'.  KEY contains a newly
     allocated structure only if this function is successful.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_key_from_name
--------------------

 -- Function: int shishi_key_from_name (Shishi * HANDLE, int32_t TYPE,
          const char * NAME, const char * PASSWORD, size_t PASSWORDLEN,
          const char * PARAMETER, Shishi_key ** OUTKEY)
     HANDLE: Shishi library handle create by `shishi_init()'.

     TYPE: type of key.

     NAME: principal name of user.

     PASSWORD: input array containing password.

     PASSWORDLEN: length of input array containing password.

     PARAMETER: input array with opaque encryption type specific
     information.

     OUTKEY: pointer to structure that will hold newly created key
     information

     Create a new Key information structure, and derive the key from
     principal name and password using `shishi_key_from_name()'.  The
     salt is derived from the principal name by concatenating the
     decoded realm and principal.

     *Return value:* Returns SHISHI_OK iff successful.

   Applications that run uninteractively may need keying material.  In
these cases, the keys are stored in a file, a file that is normally
stored on the local host.  The file should be protected from
unauthorized access.  The file is in ASCII format and contains keys as
outputed by `shishi_key_print'.  All functions that handle these keys
sets are described now.

shishi_keys
-----------

 -- Function: int shishi_keys (Shishi * HANDLE, Shishi_keys ** KEYS)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KEYS: output pointer to newly allocated keys handle.

     Get a new key set handle.

     *Return value:* Returns `SHISHI_OK' iff successful.

shishi_keys_done
----------------

 -- Function: void shishi_keys_done (Shishi_keys ** KEYS)
     KEYS: key set handle as allocated by `shishi_keys()'.

     Deallocates all resources associated with key set.  The key set
     handle must not be used in calls to other shishi_keys_*() functions
     after this.

shishi_keys_size
----------------

 -- Function: int shishi_keys_size (Shishi_keys * KEYS)
     KEYS: key set handle as allocated by `shishi_keys()'.

     Get size of key set.

     *Return value:* Returns number of keys stored in key set.

shishi_keys_nth
---------------

 -- Function: const Shishi_key * shishi_keys_nth (Shishi_keys * KEYS,
          int KEYNO)
     KEYS: key set handle as allocated by `shishi_keys()'.

     KEYNO: integer indicating requested key in key set.

     *Get the n:* th ticket in key set.

     *Return value:* Returns a key handle to the keyno:th key in the key
     set, or NULL if `keys' is invalid or `keyno' is out of bounds.  The
     first key is `keyno' 0, the second key `keyno' 1, and so on.

shishi_keys_remove
------------------

 -- Function: void shishi_keys_remove (Shishi_keys * KEYS, int KEYNO)
     KEYS: key set handle as allocated by `shishi_keys()'.

     KEYNO: key number of key in the set to remove.  The first key is
     key number 0.

     Remove a key, indexed by `keyno', in given key set.

shishi_keys_add
---------------

 -- Function: int shishi_keys_add (Shishi_keys * KEYS, Shishi_key * KEY)
     KEYS: key set handle as allocated by `shishi_keys()'.

     KEY: key to be added to key set.

     Add a key to the key set.  A deep copy of the key is stored, so
     changing `key', or deallocating it, will not modify the value
     stored in the key set.

     *Return value:* Returns `SHISHI_OK' iff successful.

shishi_keys_print
-----------------

 -- Function: int shishi_keys_print (Shishi_keys * KEYS, FILE * FH)
     KEYS: key set to print.

     FH: file handle, open for writing, to print keys to.

     Print all keys in set using shishi_key_print.

     *Returns:* Returns `SHISHI_OK' on success.

shishi_keys_to_file
-------------------

 -- Function: int shishi_keys_to_file (Shishi * HANDLE, const char *
          FILENAME, Shishi_keys * KEYS)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     FILENAME: filename to append key to.

     KEYS: set of keys to print.

     Print an ASCII representation of a key structure to a file, for
     each key in the key set.  The file is appended to if it exists.
     See `shishi_key_print()' for the format of the output.

     *Return value:* Returns `SHISHI_OK' iff successful.

shishi_keys_from_file
---------------------

 -- Function: int shishi_keys_from_file (Shishi_keys * KEYS, const char
          * FILENAME)
     KEYS: key set handle as allocated by `shishi_keys()'.

     FILENAME: filename to read keys from.

     Read zero or more keys from file `filename' and append them to the
     keyset `keys'.  See `shishi_key_print()' for the format of the
     input.

     *Return value:* Returns `SHISHI_OK' iff successful.

     *Since:* 0.0.42

shishi_keys_for_serverrealm_in_file
-----------------------------------

 -- Function: Shishi_key * shishi_keys_for_serverrealm_in_file (Shishi
          * HANDLE, const char * FILENAME, const char * SERVER, const
          char * REALM)
     HANDLE: Shishi library handle create by `shishi_init()'.

     FILENAME: file to read keys from.

     SERVER: server name to get key for.

     REALM: realm of server to get key for.

     Get keys that match specified `server' and `realm' from the key set
     file `filename'.

     *Return value:* Returns the key for specific server and realm, read
     from the indicated file, or NULL if no key could be found or an
     error encountered.

shishi_keys_for_server_in_file
------------------------------

 -- Function: Shishi_key * shishi_keys_for_server_in_file (Shishi *
          HANDLE, const char * FILENAME, const char * SERVER)
     HANDLE: Shishi library handle create by `shishi_init()'.

     FILENAME: file to read keys from.

     SERVER: server name to get key for.

     Get key for specified `server' from `filename'.

     *Return value:* Returns the key for specific server, read from the
     indicated file, or NULL if no key could be found or an error
     encountered.

shishi_keys_for_localservicerealm_in_file
-----------------------------------------

 -- Function: Shishi_key * shishi_keys_for_localservicerealm_in_file
          (Shishi * HANDLE, const char * FILENAME, const char *
          SERVICE, const char * REALM)
     HANDLE: Shishi library handle create by `shishi_init()'.

     FILENAME: file to read keys from.

     SERVICE: service to get key for.

     REALM: realm of server to get key for, or NULL for default realm.

     Get key for specified `service' and `realm' from `filename'.

     *Return value:* Returns the key for the server
     "SERVICE/HOSTNAME`REALM'" (where HOSTNAME is the current system's
     hostname), read from the default host keys file (see
     `shishi_hostkeys_default_file()'), or NULL if no key could be found
     or an error encountered.

   The previous functions require that the filename is known.  For some
applications, servers, it makes sense to provide a system default.
These key sets used by server applications are known as "hostkeys".
Here are the functions that operate on hostkeys (they are mostly
wrappers around generic key sets).

shishi_hostkeys_default_file
----------------------------

 -- Function: const char * shishi_hostkeys_default_file (Shishi *
          HANDLE)
     HANDLE: Shishi library handle create by `shishi_init()'.

     Get file name of default host key file.

     *Return value:* Returns the default host key filename used in the
     library.  (Not a copy of it, so don't modify or deallocate it.)

shishi_hostkeys_default_file_set
--------------------------------

 -- Function: void shishi_hostkeys_default_file_set (Shishi * HANDLE,
          const char * HOSTKEYSFILE)
     HANDLE: Shishi library handle create by `shishi_init()'.

     HOSTKEYSFILE: string with new default hostkeys file name, or NULL
     to reset to default.

     Set the default host key filename used in the library.  The string
     is copied into the library, so you can dispose of the variable
     immediately after calling this function.

shishi_hostkeys_for_server
--------------------------

 -- Function: Shishi_key * shishi_hostkeys_for_server (Shishi * HANDLE,
          const char * SERVER)
     HANDLE: Shishi library handle create by `shishi_init()'.

     SERVER: server name to get key for

     Get host key for `server'.

     *Return value:* Returns the key for specific server, read from the
     default host keys file (see `shishi_hostkeys_default_file()'), or
     NULL if no key could be found or an error encountered.

shishi_hostkeys_for_serverrealm
-------------------------------

 -- Function: Shishi_key * shishi_hostkeys_for_serverrealm (Shishi *
          HANDLE, const char * SERVER, const char * REALM)
     HANDLE: Shishi library handle create by `shishi_init()'.

     SERVER: server name to get key for

     REALM: realm of server to get key for.

     Get host key for `server' in `realm'.

     *Return value:* Returns the key for specific server and realm, read
     from the default host keys file (see
     `shishi_hostkeys_default_file()'), or NULL if no key could be found
     or an error encountered.

shishi_hostkeys_for_localservicerealm
-------------------------------------

 -- Function: Shishi_key * shishi_hostkeys_for_localservicerealm
          (Shishi * HANDLE, const char * SERVICE, const char * REALM)
     HANDLE: Shishi library handle create by `shishi_init()'.

     SERVICE: service to get key for.

     REALM: realm of server to get key for, or NULL for default realm.

     Get host key for `service' on current host in `realm'.

     *Return value:* Returns the key for the server
     "SERVICE/HOSTNAME`REALM'" (where HOSTNAME is the current system's
     hostname), read from the default host keys file (see
     `shishi_hostkeys_default_file()'), or NULL if no key could be found
     or an error encountered.

shishi_hostkeys_for_localservice
--------------------------------

 -- Function: Shishi_key * shishi_hostkeys_for_localservice (Shishi *
          HANDLE, const char * SERVICE)
     HANDLE: Shishi library handle create by `shishi_init()'.

     SERVICE: service to get key for.

     Get host key for `service' on current host in default realm.

     *Return value:* Returns the key for the server "SERVICE/HOSTNAME"
     (where HOSTNAME is the current system's hostname), read from the
     default host keys file (see `shishi_hostkeys_default_file()'), or
     NULL if no key could be found or an error encountered.

   After creating the key structure, it can be used to encrypt and
decrypt data, calculate checksum on data etc.  All available functions
are described now.

shishi_cipher_supported_p
-------------------------

 -- Function: int shishi_cipher_supported_p (int32_t TYPE)
     TYPE: encryption type, see Shishi_etype.

     Find out if cipher is supported.

     *Return value:* Return 0 iff cipher is unsupported.

shishi_cipher_name
------------------

 -- Function: const char * shishi_cipher_name (int32_t TYPE)
     TYPE: encryption type, see Shishi_etype.

     Read humanly readable string for cipher.

     *Return value:* Return name of encryption type, e.g.
     "des3-cbc-sha1-kd", as defined in the standards.

shishi_cipher_blocksize
-----------------------

 -- Function: int shishi_cipher_blocksize (int32_t TYPE)
     TYPE: encryption type, see Shishi_etype.

     Get block size for cipher.

     *Return value:* Return block size for encryption type, as defined
     in the standards.

shishi_cipher_confoundersize
----------------------------

 -- Function: int shishi_cipher_confoundersize (int32_t TYPE)
     TYPE: encryption type, see Shishi_etype.

     Get length of confounder for cipher.

     *Return value:* Returns the size of the confounder (random data)
     for encryption type, as defined in the standards, or (size_t)-1 on
     error (e.g., unsupported encryption type).

shishi_cipher_keylen
--------------------

 -- Function: size_t shishi_cipher_keylen (int32_t TYPE)
     TYPE: encryption type, see Shishi_etype.

     Get key length for cipher.

     *Return value:* Return length of key used for the encryption type,
     as defined in the standards.

shishi_cipher_randomlen
-----------------------

 -- Function: size_t shishi_cipher_randomlen (int32_t TYPE)
     TYPE: encryption type, see Shishi_etype.

     Get length of random data for cipher.

     *Return value:* Return length of random used for the encryption
     type, as defined in the standards, or (size_t)-1 on error (e.g.,
     unsupported encryption type).

shishi_cipher_defaultcksumtype
------------------------------

 -- Function: int shishi_cipher_defaultcksumtype (int32_t TYPE)
     TYPE: encryption type, see Shishi_etype.

     Get the default checksum associated with cipher.

     *Return value:* Return associated checksum mechanism for the
     encryption type, as defined in the standards.

shishi_cipher_parse
-------------------

 -- Function: int shishi_cipher_parse (const char * CIPHER)
     CIPHER: name of encryption type, e.g. "des3-cbc-sha1-kd".

     Get cipher number by parsing string.

     *Return value:* Return encryption type corresponding to a string.

shishi_checksum_supported_p
---------------------------

 -- Function: int shishi_checksum_supported_p (int32_t TYPE)
     TYPE: checksum type, see Shishi_cksumtype.

     Find out whether checksum is supported.

     *Return value:* Return 0 iff checksum is unsupported.

shishi_checksum_name
--------------------

 -- Function: const char * shishi_checksum_name (int32_t TYPE)
     TYPE: checksum type, see Shishi_cksumtype.

     Get name of checksum.

     *Return value:* Return name of checksum type, e.g.
     "hmac-sha1-96-aes256", as defined in the standards.

shishi_checksum_cksumlen
------------------------

 -- Function: size_t shishi_checksum_cksumlen (int32_t TYPE)
     TYPE: checksum type, see Shishi_cksumtype.

     Get length of checksum output.

     *Return value:* Return length of checksum used for the checksum
     type, as defined in the standards.

shishi_checksum_parse
---------------------

 -- Function: int shishi_checksum_parse (const char * CHECKSUM)
     CHECKSUM: name of checksum type, e.g. "hmac-sha1-96-aes256".

     Get checksum number by parsing a string.

     *Return value:* Return checksum type, see Shishi_cksumtype,
     corresponding to a string.

shishi_string_to_key
--------------------

 -- Function: int shishi_string_to_key (Shishi * HANDLE, int32_t
          KEYTYPE, const char * PASSWORD, size_t PASSWORDLEN, const
          char * SALT, size_t SALTLEN, const char * PARAMETER,
          Shishi_key * OUTKEY)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KEYTYPE: cryptographic encryption type, see Shishi_etype.

     PASSWORD: input array with password.

     PASSWORDLEN: length of input array with password.

     SALT: input array with salt.

     SALTLEN: length of input array with salt.

     PARAMETER: input array with opaque encryption type specific
     information.

     OUTKEY: allocated key handle that will contain new key.

     Derive key from a string (password) and salt (commonly
     concatenation of realm and principal) for specified key type, and
     set the type and value in the given key to the computed values.
     The parameter value is specific for each keytype, and can be set if
     the parameter information is not available.

     *Return value:* Returns `SHISHI_OK' iff successful.

shishi_random_to_key
--------------------

 -- Function: int shishi_random_to_key (Shishi * HANDLE, int32_t
          KEYTYPE, const char * RND, size_t RNDLEN, Shishi_key * OUTKEY)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KEYTYPE: cryptographic encryption type, see Shishi_etype.

     RND: input array with random data.

     RNDLEN: length of input array with random data.

     OUTKEY: allocated key handle that will contain new key.

     Derive key from random data for specified key type, and set the
     type and value in the given key to the computed values.

     *Return value:* Returns `SHISHI_OK' iff successful.

shishi_checksum
---------------

 -- Function: int shishi_checksum (Shishi * HANDLE, Shishi_key * KEY,
          int KEYUSAGE, int CKSUMTYPE, const char * IN, size_t INLEN,
          char ** OUT, size_t * OUTLEN)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KEY: key to compute checksum with.

     KEYUSAGE: integer specifying what this key is used for.

     CKSUMTYPE: the checksum algorithm to use.

     IN: input array with data to integrity protect.

     INLEN: size of input array with data to integrity protect.

     OUT: output array with newly allocated integrity protected data.

     OUTLEN: output variable with length of output array with checksum.

     Integrity protect data using key, possibly altered by supplied key
     usage.  If key usage is 0, no key derivation is used.  The OUT
     buffer must be deallocated by the caller.

     *Return value:* Returns `SHISHI_OK' iff successful.

shishi_verify
-------------

 -- Function: int shishi_verify (Shishi * HANDLE, Shishi_key * KEY, int
          KEYUSAGE, int CKSUMTYPE, const char * IN, size_t INLEN, const
          char * CKSUM, size_t CKSUMLEN)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KEY: key to verify checksum with.

     KEYUSAGE: integer specifying what this key is used for.

     CKSUMTYPE: the checksum algorithm to use.

     IN: input array with data that was integrity protected.

     INLEN: size of input array with data that was integrity protected.

     CKSUM: input array with alleged checksum of data.

     CKSUMLEN: size of input array with alleged checksum of data.

     Verify checksum of data using key, possibly altered by supplied key
     usage.  If key usage is 0, no key derivation is used.

     *Return value:* Returns `SHISHI_OK' iff successful.

shishi_encrypt_ivupdate_etype
-----------------------------

 -- Function: int shishi_encrypt_ivupdate_etype (Shishi * HANDLE,
          Shishi_key * KEY, int KEYUSAGE, int32_t ETYPE, const char *
          IV, size_t IVLEN, char ** IVOUT, size_t * IVOUTLEN, const
          char * IN, size_t INLEN, char ** OUT, size_t * OUTLEN)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KEY: key to encrypt with.

     KEYUSAGE: integer specifying what this key is encrypting.

     ETYPE: integer specifying what cipher to use.

     IV: input array with initialization vector

     IVLEN: size of input array with initialization vector.

     IVOUT: output array with newly allocated updated initialization
     vector.

     IVOUTLEN: size of output array with updated initialization vector.

     IN: input array with data to encrypt.

     INLEN: size of input array with data to encrypt.

     OUT: output array with newly allocated encrypted data.

     OUTLEN: output variable with size of newly allocated output array.

     Encrypts data as per encryption method using specified
     initialization vector and key.  The key actually used is derived
     using the key usage.  If key usage is 0, no key derivation is used.
     The OUT buffer must be deallocated by the caller.  If IVOUT or
     IVOUTLEN is NULL, the updated IV is not saved anywhere.

     Note that DECRYPT(ENCRYPT(data)) does not necessarily yield data
     exactly.  Some encryption types add pad to make the data fit into
     the block size of the encryption algorithm.  Furthermore, the pad
     is not guaranteed to look in any special way, although existing
     implementations often pad with the zero byte.  This means that you
     may have to "frame" data, so it is possible to infer the original
     length after decryption.  Compare ASN.1 DER which contains such
     information.

     *Return value:* Returns `SHISHI_OK' iff successful.

shishi_encrypt_iv_etype
-----------------------

 -- Function: int shishi_encrypt_iv_etype (Shishi * HANDLE, Shishi_key
          * KEY, int KEYUSAGE, int32_t ETYPE, const char * IV, size_t
          IVLEN, const char * IN, size_t INLEN, char ** OUT, size_t *
          OUTLEN)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KEY: key to encrypt with.

     KEYUSAGE: integer specifying what this key is encrypting.

     ETYPE: integer specifying what cipher to use.

     IV: input array with initialization vector

     IVLEN: size of input array with initialization vector.

     IN: input array with data to encrypt.

     INLEN: size of input array with data to encrypt.

     OUT: output array with newly allocated encrypted data.

     OUTLEN: output variable with size of newly allocated output array.

     Encrypts data as per encryption method using specified
     initialization vector and key.  The key actually used is derived
     using the key usage.  If key usage is 0, no key derivation is used.
     The OUT buffer must be deallocated by the caller.  The next IV is
     lost, see shishi_encrypt_ivupdate_etype if you need it.

     Note that DECRYPT(ENCRYPT(data)) does not necessarily yield data
     exactly.  Some encryption types add pad to make the data fit into
     the block size of the encryption algorithm.  Furthermore, the pad
     is not guaranteed to look in any special way, although existing
     implementations often pad with the zero byte.  This means that you
     may have to "frame" data, so it is possible to infer the original
     length after decryption.  Compare ASN.1 DER which contains such
     information.

     *Return value:* Returns `SHISHI_OK' iff successful.

shishi_encrypt_etype
--------------------

 -- Function: int shishi_encrypt_etype (Shishi * HANDLE, Shishi_key *
          KEY, int KEYUSAGE, int32_t ETYPE, const char * IN, size_t
          INLEN, char ** OUT, size_t * OUTLEN)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KEY: key to encrypt with.

     KEYUSAGE: integer specifying what this key is encrypting.

     ETYPE: integer specifying what cipher to use.

     IN: input array with data to encrypt.

     INLEN: size of input array with data to encrypt.

     OUT: output array with newly allocated encrypted data.

     OUTLEN: output variable with size of newly allocated output array.

     Encrypts data as per encryption method using specified
     initialization vector and key.  The key actually used is derived
     using the key usage.  If key usage is 0, no key derivation is used.
     The OUT buffer must be deallocated by the caller.  The default IV
     is used, see shishi_encrypt_iv_etype if you need to alter it. The
     next IV is lost, see shishi_encrypt_ivupdate_etype if you need it.

     Note that DECRYPT(ENCRYPT(data)) does not necessarily yield data
     exactly.  Some encryption types add pad to make the data fit into
     the block size of the encryption algorithm.  Furthermore, the pad
     is not guaranteed to look in any special way, although existing
     implementations often pad with the zero byte.  This means that you
     may have to "frame" data, so it is possible to infer the original
     length after decryption.  Compare ASN.1 DER which contains such
     information.

     *Return value:* Returns `SHISHI_OK' iff successful.

shishi_encrypt_ivupdate
-----------------------

 -- Function: int shishi_encrypt_ivupdate (Shishi * HANDLE, Shishi_key
          * KEY, int KEYUSAGE, const char * IV, size_t IVLEN, char **
          IVOUT, size_t * IVOUTLEN, const char * IN, size_t INLEN, char
          ** OUT, size_t * OUTLEN)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KEY: key to encrypt with.

     KEYUSAGE: integer specifying what this key is encrypting.

     IV: input array with initialization vector

     IVLEN: size of input array with initialization vector.

     IVOUT: output array with newly allocated updated initialization
     vector.

     IVOUTLEN: size of output array with updated initialization vector.

     IN: input array with data to encrypt.

     INLEN: size of input array with data to encrypt.

     OUT: output array with newly allocated encrypted data.

     OUTLEN: output variable with size of newly allocated output array.

     Encrypts data using specified initialization vector and key.  The
     key actually used is derived using the key usage.  If key usage is
     0, no key derivation is used.  The OUT buffer must be deallocated
     by the caller.  If IVOUT or IVOUTLEN is NULL, the updated IV is not
     saved anywhere.

     Note that DECRYPT(ENCRYPT(data)) does not necessarily yield data
     exactly.  Some encryption types add pad to make the data fit into
     the block size of the encryption algorithm.  Furthermore, the pad
     is not guaranteed to look in any special way, although existing
     implementations often pad with the zero byte.  This means that you
     may have to "frame" data, so it is possible to infer the original
     length after decryption.  Compare ASN.1 DER which contains such
     information.

     *Return value:* Returns `SHISHI_OK' iff successful.

shishi_encrypt_iv
-----------------

 -- Function: int shishi_encrypt_iv (Shishi * HANDLE, Shishi_key * KEY,
          int KEYUSAGE, const char * IV, size_t IVLEN, const char * IN,
          size_t INLEN, char ** OUT, size_t * OUTLEN)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KEY: key to encrypt with.

     KEYUSAGE: integer specifying what this key is encrypting.

     IV: input array with initialization vector

     IVLEN: size of input array with initialization vector.

     IN: input array with data to encrypt.

     INLEN: size of input array with data to encrypt.

     OUT: output array with newly allocated encrypted data.

     OUTLEN: output variable with size of newly allocated output array.

     Encrypts data using specified initialization vector and key.  The
     key actually used is derived using the key usage.  If key usage is
     0, no key derivation is used.  The OUT buffer must be deallocated
     by the caller.  The next IV is lost, see shishi_encrypt_ivupdate if
     you need it.

     Note that DECRYPT(ENCRYPT(data)) does not necessarily yield data
     exactly.  Some encryption types add pad to make the data fit into
     the block size of the encryption algorithm.  Furthermore, the pad
     is not guaranteed to look in any special way, although existing
     implementations often pad with the zero byte.  This means that you
     may have to "frame" data, so it is possible to infer the original
     length after decryption.  Compare ASN.1 DER which contains such
     information.

     *Return value:* Returns `SHISHI_OK' iff successful.

shishi_encrypt
--------------

 -- Function: int shishi_encrypt (Shishi * HANDLE, Shishi_key * KEY,
          int KEYUSAGE, char * IN, size_t INLEN, char ** OUT, size_t *
          OUTLEN)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KEY: key to encrypt with.

     KEYUSAGE: integer specifying what this key is encrypting.

     IN: input array with data to encrypt.

     INLEN: size of input array with data to encrypt.

     OUT: output array with newly allocated encrypted data.

     OUTLEN: output variable with size of newly allocated output array.

     Encrypts data using specified key.  The key actually used is
     derived using the key usage.  If key usage is 0, no key derivation
     is used.  The OUT buffer must be deallocated by the caller.  The
     default IV is used, see shishi_encrypt_iv if you need to alter it.
     The next IV is lost, see shishi_encrypt_ivupdate if you need it.

     Note that DECRYPT(ENCRYPT(data)) does not necessarily yield data
     exactly.  Some encryption types add pad to make the data fit into
     the block size of the encryption algorithm.  Furthermore, the pad
     is not guaranteed to look in any special way, although existing
     implementations often pad with the zero byte.  This means that you
     may have to "frame" data, so it is possible to infer the original
     length after decryption.  Compare ASN.1 DER which contains such
     information.

     *Return value:* Returns `SHISHI_OK' iff successful.

shishi_decrypt_ivupdate_etype
-----------------------------

 -- Function: int shishi_decrypt_ivupdate_etype (Shishi * HANDLE,
          Shishi_key * KEY, int KEYUSAGE, int32_t ETYPE, const char *
          IV, size_t IVLEN, char ** IVOUT, size_t * IVOUTLEN, const
          char * IN, size_t INLEN, char ** OUT, size_t * OUTLEN)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KEY: key to decrypt with.

     KEYUSAGE: integer specifying what this key is decrypting.

     ETYPE: integer specifying what cipher to use.

     IV: input array with initialization vector

     IVLEN: size of input array with initialization vector.

     IVOUT: output array with newly allocated updated initialization
     vector.

     IVOUTLEN: size of output array with updated initialization vector.

     IN: input array with data to decrypt.

     INLEN: size of input array with data to decrypt.

     OUT: output array with newly allocated decrypted data.

     OUTLEN: output variable with size of newly allocated output array.

     Decrypts data as per encryption method using specified
     initialization vector and key.  The key actually used is derived
     using the key usage.  If key usage is 0, no key derivation is used.
     The OUT buffer must be deallocated by the caller.  If IVOUT or
     IVOUTLEN is NULL, the updated IV is not saved anywhere.

     Note that DECRYPT(ENCRYPT(data)) does not necessarily yield data
     exactly.  Some encryption types add pad to make the data fit into
     the block size of the encryption algorithm.  Furthermore, the pad
     is not guaranteed to look in any special way, although existing
     implementations often pad with the zero byte.  This means that you
     may have to "frame" data, so it is possible to infer the original
     length after decryption.  Compare ASN.1 DER which contains such
     information.

     *Return value:* Returns `SHISHI_OK' iff successful.

shishi_decrypt_iv_etype
-----------------------

 -- Function: int shishi_decrypt_iv_etype (Shishi * HANDLE, Shishi_key
          * KEY, int KEYUSAGE, int32_t ETYPE, const char * IV, size_t
          IVLEN, const char * IN, size_t INLEN, char ** OUT, size_t *
          OUTLEN)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KEY: key to decrypt with.

     KEYUSAGE: integer specifying what this key is decrypting.

     ETYPE: integer specifying what cipher to use.

     IV: input array with initialization vector

     IVLEN: size of input array with initialization vector.

     IN: input array with data to decrypt.

     INLEN: size of input array with data to decrypt.

     OUT: output array with newly allocated decrypted data.

     OUTLEN: output variable with size of newly allocated output array.

     Decrypts data as per encryption method using specified
     initialization vector and key.  The key actually used is derived
     using the key usage.  If key usage is 0, no key derivation is used.
     The OUT buffer must be deallocated by the caller.  The next IV is
     lost, see shishi_decrypt_ivupdate_etype if you need it.

     Note that DECRYPT(ENCRYPT(data)) does not necessarily yield data
     exactly.  Some encryption types add pad to make the data fit into
     the block size of the encryption algorithm.  Furthermore, the pad
     is not guaranteed to look in any special way, although existing
     implementations often pad with the zero byte.  This means that you
     may have to "frame" data, so it is possible to infer the original
     length after decryption.  Compare ASN.1 DER which contains such
     information.

     *Return value:* Returns `SHISHI_OK' iff successful.

shishi_decrypt_etype
--------------------

 -- Function: int shishi_decrypt_etype (Shishi * HANDLE, Shishi_key *
          KEY, int KEYUSAGE, int32_t ETYPE, const char * IN, size_t
          INLEN, char ** OUT, size_t * OUTLEN)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KEY: key to decrypt with.

     KEYUSAGE: integer specifying what this key is decrypting.

     ETYPE: integer specifying what cipher to use.

     IN: input array with data to decrypt.

     INLEN: size of input array with data to decrypt.

     OUT: output array with newly allocated decrypted data.

     OUTLEN: output variable with size of newly allocated output array.

     Decrypts data as per encryption method using specified key.  The
     key actually used is derived using the key usage.  If key usage is
     0, no key derivation is used.  The OUT buffer must be deallocated
     by the caller.  The default IV is used, see shishi_decrypt_iv_etype
     if you need to alter it.  The next IV is lost, see
     shishi_decrypt_ivupdate_etype if you need it.

     Note that DECRYPT(ENCRYPT(data)) does not necessarily yield data
     exactly.  Some encryption types add pad to make the data fit into
     the block size of the encryption algorithm.  Furthermore, the pad
     is not guaranteed to look in any special way, although existing
     implementations often pad with the zero byte.  This means that you
     may have to "frame" data, so it is possible to infer the original
     length after decryption.  Compare ASN.1 DER which contains such
     information.

     *Return value:* Returns `SHISHI_OK' iff successful.

shishi_decrypt_ivupdate
-----------------------

 -- Function: int shishi_decrypt_ivupdate (Shishi * HANDLE, Shishi_key
          * KEY, int KEYUSAGE, const char * IV, size_t IVLEN, char **
          IVOUT, size_t * IVOUTLEN, const char * IN, size_t INLEN, char
          ** OUT, size_t * OUTLEN)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KEY: key to decrypt with.

     KEYUSAGE: integer specifying what this key is decrypting.

     IV: input array with initialization vector

     IVLEN: size of input array with initialization vector.

     IVOUT: output array with newly allocated updated initialization
     vector.

     IVOUTLEN: size of output array with updated initialization vector.

     IN: input array with data to decrypt.

     INLEN: size of input array with data to decrypt.

     OUT: output array with newly allocated decrypted data.

     OUTLEN: output variable with size of newly allocated output array.

     Decrypts data using specified initialization vector and key.  The
     key actually used is derived using the key usage.  If key usage is
     0, no key derivation is used.  The OUT buffer must be deallocated
     by the caller.  If IVOUT or IVOUTLEN is NULL, the updated IV is not
     saved anywhere.

     Note that DECRYPT(ENCRYPT(data)) does not necessarily yield data
     exactly.  Some encryption types add pad to make the data fit into
     the block size of the encryption algorithm.  Furthermore, the pad
     is not guaranteed to look in any special way, although existing
     implementations often pad with the zero byte.  This means that you
     may have to "frame" data, so it is possible to infer the original
     length after decryption.  Compare ASN.1 DER which contains such
     information.

     *Return value:* Returns `SHISHI_OK' iff successful.

shishi_decrypt_iv
-----------------

 -- Function: int shishi_decrypt_iv (Shishi * HANDLE, Shishi_key * KEY,
          int KEYUSAGE, const char * IV, size_t IVLEN, const char * IN,
          size_t INLEN, char ** OUT, size_t * OUTLEN)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KEY: key to decrypt with.

     KEYUSAGE: integer specifying what this key is decrypting.

     IV: input array with initialization vector

     IVLEN: size of input array with initialization vector.

     IN: input array with data to decrypt.

     INLEN: size of input array with data to decrypt.

     OUT: output array with newly allocated decrypted data.

     OUTLEN: output variable with size of newly allocated output array.

     Decrypts data using specified initialization vector and key.  The
     key actually used is derived using the key usage.  If key usage is
     0, no key derivation is used.  The OUT buffer must be deallocated
     by the caller.  The next IV is lost, see
     shishi_decrypt_ivupdate_etype if you need it.

     Note that DECRYPT(ENCRYPT(data)) does not necessarily yield data
     exactly.  Some encryption types add pad to make the data fit into
     the block size of the encryption algorithm.  Furthermore, the pad
     is not guaranteed to look in any special way, although existing
     implementations often pad with the zero byte.  This means that you
     may have to "frame" data, so it is possible to infer the original
     length after decryption.  Compare ASN.1 DER which contains such
     information.

     *Return value:* Returns `SHISHI_OK' iff successful.

shishi_decrypt
--------------

 -- Function: int shishi_decrypt (Shishi * HANDLE, Shishi_key * KEY,
          int KEYUSAGE, const char * IN, size_t INLEN, char ** OUT,
          size_t * OUTLEN)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KEY: key to decrypt with.

     KEYUSAGE: integer specifying what this key is decrypting.

     IN: input array with data to decrypt.

     INLEN: size of input array with data to decrypt.

     OUT: output array with newly allocated decrypted data.

     OUTLEN: output variable with size of newly allocated output array.

     Decrypts data specified key.  The key actually used is derived
     using the key usage.  If key usage is 0, no key derivation is used.
     The OUT buffer must be deallocated by the caller.  The default IV
     is used, see shishi_decrypt_iv if you need to alter it.  The next
     IV is lost, see shishi_decrypt_ivupdate if you need it.

     Note that DECRYPT(ENCRYPT(data)) does not necessarily yield data
     exactly.  Some encryption types add pad to make the data fit into
     the block size of the encryption algorithm.  Furthermore, the pad
     is not guaranteed to look in any special way, although existing
     implementations often pad with the zero byte.  This means that you
     may have to "frame" data, so it is possible to infer the original
     length after decryption.  Compare ASN.1 DER which contains such
     information.

     *Return value:* Returns `SHISHI_OK' iff successful.

shishi_n_fold
-------------

 -- Function: int shishi_n_fold (Shishi * HANDLE, const char * IN,
          size_t INLEN, char * OUT, size_t OUTLEN)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     IN: input array with data to decrypt.

     INLEN: size of input array with data to decrypt ("M").

     OUT: output array with decrypted data.

     OUTLEN: size of output array ("N").

     Fold data into a fixed length output array, with the intent to give
     each input bit approximately equal weight in determining the value
     of each output bit.

     The algorithm is from "A Better Key Schedule For DES-like Ciphers"
     by Uri Blumenthal and Steven M. Bellovin,
     http://www.research.att.com/~smb/papers/ides.pdf, although the
     sample vectors provided by the paper are incorrect.

     *Return value:* Returns `SHISHI_OK' iff successful.

shishi_dr
---------

 -- Function: int shishi_dr (Shishi * HANDLE, Shishi_key * KEY, const
          char * PRFCONSTANT, size_t PRFCONSTANTLEN, char *
          DERIVEDRANDOM, size_t DERIVEDRANDOMLEN)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KEY: input array with cryptographic key to use.

     PRFCONSTANT: input array with the constant string.

     PRFCONSTANTLEN: size of input array with the constant string.

     DERIVEDRANDOM: output array with derived random data.

     DERIVEDRANDOMLEN: size of output array with derived random data.

     Derive "random" data from a key and a constant thusly: DR(KEY,
     PRFCONSTANT) = TRUNCATE(DERIVEDRANDOMLEN, SHISHI_ENCRYPT(KEY,
     PRFCONSTANT)).

     *Return value:* Returns `SHISHI_OK' iff successful.

shishi_dk
---------

 -- Function: int shishi_dk (Shishi * HANDLE, Shishi_key * KEY, const
          char * PRFCONSTANT, size_t PRFCONSTANTLEN, Shishi_key *
          DERIVEDKEY)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KEY: input cryptographic key to use.

     PRFCONSTANT: input array with the constant string.

     PRFCONSTANTLEN: size of input array with the constant string.

     DERIVEDKEY: pointer to derived key (allocated by caller).

     *Derive a key from a key and a constant thusly:* DK(KEY,
     PRFCONSTANT) = SHISHI_RANDOM-TO-KEY(SHISHI_DR(KEY, PRFCONSTANT)).

     *Return value:* Returns `SHISHI_OK' iff successful.

   An easier way to use encryption and decryption if your application
repeatedly calls, e.g., `shishi_encrypt_ivupdate', is to use the
following functions.  They store the key, initialization vector, etc,
in a context, and the encryption and decryption operations update the
IV within the context automatically.

shishi_crypto
-------------

 -- Function: Shishi_crypto * shishi_crypto (Shishi * HANDLE,
          Shishi_key * KEY, int KEYUSAGE, int32_t ETYPE, const char *
          IV, size_t IVLEN)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KEY: key to encrypt with.

     KEYUSAGE: integer specifying what this key will encrypt/decrypt.

     ETYPE: integer specifying what cipher to use.

     IV: input array with initialization vector

     IVLEN: size of input array with initialization vector.

     Initialize a crypto context.  This store a key, keyusage,
     encryption type and initialization vector in a "context", and the
     caller can then use this context to perform encryption via
     `shishi_crypto_encrypt()' and decryption via
     `shishi_crypto_encrypt()' without supplying all those details
     again.  The functions also takes care of propagating the IV
     between calls.

     When the application no longer need to use the context, it should
     deallocate resources associated with it by calling
     `shishi_crypto_close()'.

     *Return value:* Return a newly allocated crypto context.

shishi_crypto_encrypt
---------------------

 -- Function: int shishi_crypto_encrypt (Shishi_crypto * CTX, const
          char * IN, size_t INLEN, char ** OUT, size_t * OUTLEN)
     CTX: crypto context as returned by `shishi_crypto()'.

     IN: input array with data to encrypt.

     INLEN: size of input array with data to encrypt.

     OUT: output array with newly allocated encrypted data.

     OUTLEN: output variable with size of newly allocated output array.

     Encrypt data, using information (e.g., key and initialization
     vector) from context.  The IV is updated inside the context after
     this call.

     When the application no longer need to use the context, it should
     deallocate resources associated with it by calling
     `shishi_crypto_close()'.

     *Return value:* Returns `SHISHI_OK' iff successful.

shishi_crypto_decrypt
---------------------

 -- Function: int shishi_crypto_decrypt (Shishi_crypto * CTX, const
          char * IN, size_t INLEN, char ** OUT, size_t * OUTLEN)
     CTX: crypto context as returned by `shishi_crypto()'.

     IN: input array with data to decrypt.

     INLEN: size of input array with data to decrypt.

     OUT: output array with newly allocated decrypted data.

     OUTLEN: output variable with size of newly allocated output array.

     Decrypt data, using information (e.g., key and initialization
     vector) from context.  The IV is updated inside the context after
     this call.

     When the application no longer need to use the context, it should
     deallocate resources associated with it by calling
     `shishi_crypto_close()'.

     *Return value:* Returns `SHISHI_OK' iff successful.

shishi_crypto_close
-------------------

 -- Function: void shishi_crypto_close (Shishi_crypto * CTX)
     CTX: crypto context as returned by `shishi_crypto()'.

     Deallocate resources associated with the crypto context.

   Also included in Shishi is an interface to the really low-level
cryptographic primitives.  They map directly on the underlying
cryptographic library used (i.e., Gnulib or Libgcrypt) and is used
internally by Shishi.

shishi_randomize
----------------

 -- Function: int shishi_randomize (Shishi * HANDLE, int STRONG, void *
          DATA, size_t DATALEN)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     STRONG: 0 iff operation should not block, non-0 for very strong
     randomness.

     DATA: output array to be filled with random data.

     DATALEN: size of output array.

     Store cryptographically random data of given size in the provided
     buffer.

     *Return value:* Returns `SHISHI_OK' iff successful.

shishi_crc
----------

 -- Function: int shishi_crc (Shishi * HANDLE, const char * IN, size_t
          INLEN, char * OUT[4])
     HANDLE: shishi handle as allocated by `shishi_init()'.

     IN: input character array of data to checksum.

     INLEN: length of input character array of data to checksum.

     Compute checksum of data using CRC32 modified according to RFC
     1510.  The `out' buffer must be deallocated by the caller.

     The modifications compared to standard CRC32 is that no initial and
     final XOR is performed, and that the output is returned in
     LSB-first order.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_md4
----------

 -- Function: int shishi_md4 (Shishi * HANDLE, const char * IN, size_t
          INLEN, char * OUT[16])
     HANDLE: shishi handle as allocated by `shishi_init()'.

     IN: input character array of data to hash.

     INLEN: length of input character array of data to hash.

     Compute hash of data using MD4.  The `out' buffer must be
     deallocated by the caller.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_md5
----------

 -- Function: int shishi_md5 (Shishi * HANDLE, const char * IN, size_t
          INLEN, char * OUT[16])
     HANDLE: shishi handle as allocated by `shishi_init()'.

     IN: input character array of data to hash.

     INLEN: length of input character array of data to hash.

     Compute hash of data using MD5.  The `out' buffer must be
     deallocated by the caller.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_hmac_md5
---------------

 -- Function: int shishi_hmac_md5 (Shishi * HANDLE, const char * KEY,
          size_t KEYLEN, const char * IN, size_t INLEN, char *
          OUTHASH[16])
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KEY: input character array with key to use.

     KEYLEN: length of input character array with key to use.

     IN: input character array of data to hash.

     INLEN: length of input character array of data to hash.

     Compute keyed checksum of data using HMAC-MD5.  The `outhash'
     buffer must be deallocated by the caller.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_hmac_sha1
----------------

 -- Function: int shishi_hmac_sha1 (Shishi * HANDLE, const char * KEY,
          size_t KEYLEN, const char * IN, size_t INLEN, char *
          OUTHASH[20])
     HANDLE: shishi handle as allocated by `shishi_init()'.

     KEY: input character array with key to use.

     KEYLEN: length of input character array with key to use.

     IN: input character array of data to hash.

     INLEN: length of input character array of data to hash.

     Compute keyed checksum of data using HMAC-SHA1.  The `outhash'
     buffer must be deallocated by the caller.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_des_cbc_mac
------------------

 -- Function: int shishi_des_cbc_mac (Shishi * HANDLE, const char
          KEY[8], const char IV[8], const char * IN, size_t INLEN, char
          * OUT[8])
     HANDLE: shishi handle as allocated by `shishi_init()'.

     IN: input character array of data to hash.

     INLEN: length of input character array of data to hash.

     Computed keyed checksum of data using DES-CBC-MAC.  The `out'
     buffer must be deallocated by the caller.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_arcfour
--------------

 -- Function: int shishi_arcfour (Shishi * HANDLE, int DECRYPTP, const
          char * KEY, size_t KEYLEN, const char IV[258], char *
          IVOUT[258], const char * IN, size_t INLEN, char ** OUT)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     DECRYPTP: 0 to indicate encryption, non-0 to indicate decryption.

     KEY: input character array with key to use.

     KEYLEN: length of input key array.

     IN: input character array of data to encrypt/decrypt.

     INLEN: length of input character array of data to encrypt/decrypt.

     OUT: newly allocated character array with encrypted/decrypted data.

     Encrypt or decrypt data (depending on `decryptp') using ARCFOUR.
     The `out' buffer must be deallocated by the caller.

     The "initialization vector" used here is the concatenation of the
     sbox and i and j, and is thus always of size 256 + 1 + 1.  This is
     a slight abuse of terminology, and assumes you know what you are
     doing.  Don't use it if you can avoid to.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_des
----------

 -- Function: int shishi_des (Shishi * HANDLE, int DECRYPTP, const char
          KEY[8], const char IV[8], char * IVOUT[8], const char * IN,
          size_t INLEN, char ** OUT)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     DECRYPTP: 0 to indicate encryption, non-0 to indicate decryption.

     IN: input character array of data to encrypt/decrypt.

     INLEN: length of input character array of data to encrypt/decrypt.

     OUT: newly allocated character array with encrypted/decrypted data.

     Encrypt or decrypt data (depending on `decryptp') using DES in CBC
     mode.  The `out' buffer must be deallocated by the caller.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_3des
-----------

 -- Function: int shishi_3des (Shishi * HANDLE, int DECRYPTP, const
          char KEY[8], const char IV[8], char * IVOUT[8], const char *
          IN, size_t INLEN, char ** OUT)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     DECRYPTP: 0 to indicate encryption, non-0 to indicate decryption.

     IN: input character array of data to encrypt/decrypt.

     INLEN: length of input character array of data to encrypt/decrypt.

     OUT: newly allocated character array with encrypted/decrypted data.

     Encrypt or decrypt data (depending on `decryptp') using 3DES in CBC
     mode.  The `out' buffer must be deallocated by the caller.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_aes_cts
--------------

 -- Function: int shishi_aes_cts (Shishi * HANDLE, int DECRYPTP, const
          char * KEY, size_t KEYLEN, const char IV[16], char *
          IVOUT[16], const char * IN, size_t INLEN, char ** OUT)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     DECRYPTP: 0 to indicate encryption, non-0 to indicate decryption.

     KEY: input character array with key to use.

     KEYLEN: length of input character array with key to use.

     IN: input character array of data to encrypt/decrypt.

     INLEN: length of input character array of data to encrypt/decrypt.

     OUT: newly allocated character array with encrypted/decrypted data.

     Encrypt or decrypt data (depending on `decryptp') using AES in
     CBC-CTS mode.  The length of the key, `keylen', decide if AES 128
     or AES 256 should be used.  The `out' buffer must be deallocated
     by the caller.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_pbkdf2_sha1
------------------

 -- Function: int shishi_pbkdf2_sha1 (Shishi * HANDLE, const char * P,
          size_t PLEN, const char * S, size_t SLEN, unsigned int C,
          unsigned int DKLEN, char * DK)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     P: input password, an octet string

     PLEN: length of password, an octet string

     S: input salt, an octet string

     SLEN: length of salt, an octet string

     C: iteration count, a positive integer

     DKLEN: intended length in octets of the derived key, a positive
     integer, at most (2^32 - 1) * hLen.  The DK array must have room
     for this many characters.

     DK: output derived key, a dkLen-octet string

     Derive key using the PBKDF2 defined in PKCS5.  PBKDF2 applies a
     pseudorandom function to derive keys. The length of the derived key
     is essentially unbounded. (However, the maximum effective search
     space for the derived key may be limited by the structure of the
     underlying pseudorandom function, which is this function is always
     SHA1.)

     *Return value:* Returns SHISHI_OK iff successful.


File: shishi.info,  Node: X.509 Functions,  Next: Utility Functions,  Prev: Cryptographic Functions,  Up: Programming Manual

5.14 X.509 Functions
====================

The functions described in this section are used by the STARTTLS
functionality, see *Note Kerberos via TLS::.

shishi_x509ca_default_file_guess
--------------------------------

 -- Function: char * shishi_x509ca_default_file_guess (Shishi * HANDLE)
     HANDLE: Shishi library handle create by `shishi_init()'.

     Guesses the default X.509 CA certificate filename; it is
     $HOME/.shishi/client.ca.

     *Return value:* Returns default X.509 client certificate filename
     as a string that has to be deallocated with `free()' by the caller.

shishi_x509ca_default_file_set
------------------------------

 -- Function: void shishi_x509ca_default_file_set (Shishi * HANDLE,
          const char * X509CAFILE)
     HANDLE: Shishi library handle create by `shishi_init()'.

     X509CAFILE: string with new default x509 client certificate file
     name, or NULL to reset to default.

     Set the default X.509 CA certificate filename used in the library.
     The certificate is used during TLS connections with the KDC to
     authenticate the KDC.  The string is copied into the library, so
     you can dispose of the variable immediately after calling this
     function.

shishi_x509ca_default_file
--------------------------

 -- Function: const char * shishi_x509ca_default_file (Shishi * HANDLE)
     HANDLE: Shishi library handle create by `shishi_init()'.

     Get filename for default X.509 CA certificate.

     *Return value:* Returns the default X.509 CA certificate filename
     used in the library.  The certificate is used during TLS
     connections with the KDC to authenticate the KDC.  The string is
     not a copy, so don't modify or deallocate it.

shishi_x509cert_default_file_guess
----------------------------------

 -- Function: char * shishi_x509cert_default_file_guess (Shishi *
          HANDLE)
     HANDLE: Shishi library handle create by `shishi_init()'.

     Guesses the default X.509 client certificate filename; it is
     $HOME/.shishi/client.certs.

     *Return value:* Returns default X.509 client certificate filename
     as a string that has to be deallocated with `free()' by the caller.

shishi_x509cert_default_file_set
--------------------------------

 -- Function: void shishi_x509cert_default_file_set (Shishi * HANDLE,
          const char * X509CERTFILE)
     HANDLE: Shishi library handle create by `shishi_init()'.

     X509CERTFILE: string with new default x509 client certificate file
     name, or NULL to reset to default.

     Set the default X.509 client certificate filename used in the
     library.  The certificate is used during TLS connections with the
     KDC to authenticate the client.  The string is copied into the
     library, so you can dispose of the variable immediately after
     calling this function.

shishi_x509cert_default_file
----------------------------

 -- Function: const char * shishi_x509cert_default_file (Shishi *
          HANDLE)
     HANDLE: Shishi library handle create by `shishi_init()'.

     Get filename for default X.509 certificate.

     *Return value:* Returns the default X.509 client certificate
     filename used in the library.  The certificate is used during TLS
     connections with the KDC to authenticate the client.  The string is
     not a copy, so don't modify or deallocate it.

shishi_x509key_default_file_guess
---------------------------------

 -- Function: char * shishi_x509key_default_file_guess (Shishi * HANDLE)
     HANDLE: Shishi library handle create by `shishi_init()'.

     Guesses the default X.509 client key filename; it is
     $HOME/.shishi/client.key.

     *Return value:* Returns default X.509 client key filename as a
     string that has to be deallocated with `free()' by the caller.

shishi_x509key_default_file_set
-------------------------------

 -- Function: void shishi_x509key_default_file_set (Shishi * HANDLE,
          const char * X509KEYFILE)
     HANDLE: Shishi library handle create by `shishi_init()'.

     X509KEYFILE: string with new default x509 client key file name, or
     NULL to reset to default.

     Set the default X.509 client key filename used in the library.  The
     key is used during TLS connections with the KDC to authenticate the
     client.  The string is copied into the library, so you can dispose
     of the variable immediately after calling this function.

shishi_x509key_default_file
---------------------------

 -- Function: const char * shishi_x509key_default_file (Shishi * HANDLE)
     HANDLE: Shishi library handle create by `shishi_init()'.

     Get filename for default X.509 key.

     *Return value:* Returns the default X.509 client key filename used
     in the library.  The key is used during TLS connections with the
     KDC to authenticate the client.  The string is not a copy, so
     don't modify or deallocate it.


File: shishi.info,  Node: Utility Functions,  Next: ASN.1 Functions,  Prev: X.509 Functions,  Up: Programming Manual

5.15 Utility Functions
======================

shishi_realm_default_guess
--------------------------

 -- Function: char * shishi_realm_default_guess ( VOID)
     Guesses a realm based on `getdomainname()' (which really is NIS/YP
     domain, but if it is set it might be a good guess), or if it fails,
     based on `gethostname()', or if it fails, the string
     "could-not-guess-default-realm". Note that the hostname is not
     trimmed off of the data returned by `gethostname()' to get the
     domain name and use that as the realm.

     *Return value:* Returns guessed realm for host as a string that has
     to be deallocated with `free()' by the caller.

shishi_realm_default
--------------------

 -- Function: const char * shishi_realm_default (Shishi * HANDLE)
     HANDLE: Shishi library handle create by `shishi_init()'.

     Get name of default realm.

     *Return value:* Returns the default realm used in the library.
     (Not a copy of it, so don't modify or deallocate it.)

shishi_realm_default_set
------------------------

 -- Function: void shishi_realm_default_set (Shishi * HANDLE, const
          char * REALM)
     HANDLE: Shishi library handle create by `shishi_init()'.

     REALM: string with new default realm name, or NULL to reset to
     default.

     Set the default realm used in the library.  The string is copied
     into the library, so you can dispose of the variable immediately
     after calling this function.

shishi_realm_for_server_file
----------------------------

 -- Function: char * shishi_realm_for_server_file (Shishi * HANDLE,
          char * SERVER)
     HANDLE: Shishi library handle create by `shishi_init()'.

     SERVER: hostname to find realm for.

     Find realm for a host using configuration file.

     *Return value:* Returns realm for host, or NULL if not found.

shishi_realm_for_server_dns
---------------------------

 -- Function: char * shishi_realm_for_server_dns (Shishi * HANDLE, char
          * SERVER)
     HANDLE: Shishi library handle create by `shishi_init()'.

     SERVER: hostname to find realm for.

     Find realm for a host using DNS lookups, according to
     draft-ietf-krb-wg-krb-dns-locate-03.txt.  Since DNS lookups may be
     spoofed, relying on the realm information may result in a
     redirection attack.  In a single-realm scenario, this only achieves
     a denial of service, but with cross-realm trust it may redirect you
     to a compromised realm.  For this reason, Shishi prints a warning,
     suggesting that the user should add the proper 'server-realm'
     configuration tokens instead.

     To illustrate the DNS information used, here is an extract from a
     zone file for the domain ASDF.COM:

     _kerberos.asdf.com.             IN      TXT     "ASDF.COM"
     _kerberos.mrkserver.asdf.com.   IN      TXT
     "MARKETING.ASDF.COM" _kerberos.salesserver.asdf.com. IN      TXT
      "SALES.ASDF.COM"

     Let us suppose that in this case, a client wishes to use a service
     on the host foo.asdf.com.  It would first query:

     _kerberos.foo.asdf.com. IN TXT

     Finding no match, it would then query:

     _kerberos.asdf.com. IN TXT

     *Return value:* Returns realm for host, or NULL if not found.

shishi_realm_for_server
-----------------------

 -- Function: char * shishi_realm_for_server (Shishi * HANDLE, char *
          SERVER)
     HANDLE: Shishi library handle create by `shishi_init()'.

     SERVER: hostname to find realm for.

     Find realm for a host, using various methods.  Currently this
     includes static configuration files (see
     `shishi_realm_for_server_file()') and DNS (see
     `shishi_realm_for_server_dns()').

     *Return value:* Returns realm for host, or NULL if not found.

shishi_principal_default_guess
------------------------------

 -- Function: char * shishi_principal_default_guess ( VOID)
     Guesses the principal name for the user, looking at environment
     variables SHISHI_USER, USER and LOGNAME, or if that fails, returns
     the string "user".

     *Return value:* Returns guessed default principal for user as a
     string that has to be deallocated by the caller with `free()'.

shishi_principal_default
------------------------

 -- Function: const char * shishi_principal_default (Shishi * HANDLE)
     HANDLE: Shishi library handle created by `shishi_init()'.

     The default principal name is the name in the environment variable
     USER, or LOGNAME for some systems, but it can be overridden by
     specifying the environment variable SHISHI_USER.

     *Return value:* Returns the default principal name used by the
     library.  (Not a copy of it, so don't modify or deallocate it.)

shishi_principal_default_set
----------------------------

 -- Function: void shishi_principal_default_set (Shishi * HANDLE, const
          char * PRINCIPAL)
     HANDLE: Shishi library handle created by `shishi_init()'.

     PRINCIPAL: string with new default principal name, or NULL to
     reset to default.

     Set the default principal used by the library.  The string is
     copied into the library, so you can dispose of the variable
     immediately after calling this function.

shishi_parse_name
-----------------

 -- Function: int shishi_parse_name (Shishi * HANDLE, const char *
          NAME, char ** PRINCIPAL, char ** REALM)
     HANDLE: Shishi library handle created by `shishi_init()'.

     NAME: input principal name string, e.g.
     imap/mail.gnu.org\`GNU'.ORG.

     PRINCIPAL: newly allocated output string with principal name.

     REALM: newly allocated output string with realm name.

     Split principal name (e.g., "simon\`JOSEFSSON'.ORG") into two
     newly allocated strings, the `principal' ("simon"), and the `realm'
     ("JOSEFSSON.ORG").  If there is no realm part in `name', `realm'
     is set to NULL.

     *Return value:* Returns SHISHI_INVALID_PRINCIPAL_NAME if `name' is
     NULL or ends with the escape character "\", and SHISHI_OK if
     successful.

shishi_principal_name
---------------------

 -- Function: int shishi_principal_name (Shishi * HANDLE, Shishi_asn1
          NAMENODE, const char * NAMEFIELD, char ** OUT, size_t *
          OUTLEN)
     HANDLE: Shishi library handle created by `shishi_init()'.

     NAMENODE: ASN.1 structure with principal in `namefield'.

     NAMEFIELD: name of field in `namenode' containing principal name.

     OUT: pointer to newly allocated, null terminated, string containing
     principal name.  May be `NULL' (to only populate `outlen').

     OUTLEN: pointer to length of `out' on output, excluding terminating
     null.  May be `NULL' (to only populate `out').

     Represent principal name in ASN.1 structure as null-terminated
     string.  The string is allocated by this function, and it is the
     responsibility of the caller to deallocate it.  Note that the
     output length `outlen' does not include the terminating null.

     *Return value:* Returns SHISHI_OK if successful.

shishi_principal_name_realm
---------------------------

 -- Function: int shishi_principal_name_realm (Shishi * HANDLE,
          Shishi_asn1 NAMENODE, const char * NAMEFIELD, Shishi_asn1
          REALMNODE, const char * REALMFIELD, char ** OUT, size_t *
          OUTLEN)
     HANDLE: Shishi library handle created by `shishi_init()'.

     NAMENODE: ASN.1 structure with principal name in `namefield'.

     NAMEFIELD: name of field in `namenode' containing principal name.

     REALMNODE: ASN.1 structure with principal realm in `realmfield'.

     REALMFIELD: name of field in `realmnode' containing principal
     realm.

     OUT: pointer to newly allocated null terminated string containing
     principal name.  May be `NULL' (to only populate `outlen').

     OUTLEN: pointer to length of `out' on output, excluding terminating
     null.  May be `NULL' (to only populate `out').

     Represent principal name and realm in ASN.1 structure as
     null-terminated string.  The string is allocated by this function.
     It is the responsibility of the caller to deallocate it.  Note
     that the output length `outlen' does not include the terminating
     null character.

     *Return value:* Returns SHISHI_OK if successful.

shishi_principal_name_set
-------------------------

 -- Function: int shishi_principal_name_set (Shishi * HANDLE,
          Shishi_asn1 NAMENODE, const char * NAMEFIELD,
          Shishi_name_type NAME_TYPE, const char * [] NAME)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     NAMENODE: ASN.1 structure with principal in `namefield'.

     NAMEFIELD: name of field in `namenode' containing principal name.

     NAME_TYPE: type of principal, see Shishi_name_type, usually
     SHISHI_NT_UNKNOWN.

     NAME: null-terminated input array with principal name.

     Set the given principal name field to the given name.

     *Return value:* Returns SHISHI_OK if successful.

shishi_principal_set
--------------------

 -- Function: int shishi_principal_set (Shishi * HANDLE, Shishi_asn1
          NAMENODE, const char * NAMEFIELD, const char * NAME)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     NAMENODE: ASN.1 structure with principal in `namefield'.

     NAMEFIELD: name of field in `namenode' containing principal name.

     NAME: null-terminated string with principal name in RFC 1964 form.

     Set principal name field in an ASN.1 structure to the given name.

     *Return value:* Returns SHISHI_OK if successful.

shishi_derive_default_salt
--------------------------

 -- Function: int shishi_derive_default_salt (Shishi * HANDLE, const
          char * NAME, char ** SALT)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     NAME: principal name of user.

     SALT: output variable with newly allocated salt string.

     Derive the default salt from a principal.  The default salt is the
     concatenation of the decoded realm and the principal.

     *Return value:* Return SHISHI_OK if successful.

shishi_server_for_local_service
-------------------------------

 -- Function: char * shishi_server_for_local_service (Shishi * HANDLE,
          const char * SERVICE)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     SERVICE: null terminated string with name of service, e.g., "host".

     Construct a service principal (e.g., "imap/yxa.extuno.com") based
     on supplied service name (i.e., "imap") and the system's hostname
     as returned by `hostname()' (i.e., "yxa.extundo.com").  The string
     must be deallocated by the caller.

     *Return value:* Return newly allocated service name string.

shishi_authorize_strcmp
-----------------------

 -- Function: int shishi_authorize_strcmp (Shishi * HANDLE, const char
          * PRINCIPAL, const char * AUTHZNAME)
     HANDLE: shishi handle allocated by `shishi_init()'.

     PRINCIPAL: string with desired principal name.

     AUTHZNAME: authorization name.

     Authorization of `authzname' against desired `principal' according
     to "basic" authentication, i.e., testing for identical strings.

     *Return value:* Returns 1 if `authzname' is authorized for services
     by the encrypted principal, and 0 otherwise.

shishi_authorize_k5login
------------------------

 -- Function: int shishi_authorize_k5login (Shishi * HANDLE, const char
          * PRINCIPAL, const char * AUTHZNAME)
     HANDLE: shishi handle allocated by `shishi_init()'.

     PRINCIPAL: string with desired principal name and realm.

     AUTHZNAME: authorization name.

     Authorization of `authzname' against desired `principal' in
     accordance with the MIT/Heimdal authorization method.

     *Return value:* Returns 1 if `authzname' is authorized for services
     by `principal', and returns 0 otherwise.

shishi_authorization_parse
--------------------------

 -- Function: int shishi_authorization_parse (const char *
          AUTHORIZATION)
     AUTHORIZATION: name of authorization type, "basic" or "k5login".

     Parse authorization type name.

     *Return value:* Returns authorization type corresponding to a
     string.

shishi_authorized_p
-------------------

 -- Function: int shishi_authorized_p (Shishi * HANDLE, Shishi_tkt *
          TKT, const char * AUTHZNAME)
     HANDLE: shishi handle allocated by `shishi_init()'.

     TKT: input variable with ticket info.

     AUTHZNAME: authorization name.

     Simplistic authorization of `authzname' against encrypted client
     principal name inside ticket.  For "basic" authentication type,
     the principal name must coincide with `authzname'. The "k5login"
     authentication type attempts the MIT/Heimdal method of parsing the
     file "~/.k5login" for additional equivalence names.

     *Return value:* Returns 1 if `authzname' is authorized for services
     by the encrypted principal, and 0 otherwise.

shishi_generalize_time
----------------------

 -- Function: const char * shishi_generalize_time (Shishi * HANDLE,
          time_t T)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     T: C time to convert.

     Convert C time to KerberosTime.  The string must not be deallocate
     by caller.

     *Return value:* Return a KerberosTime time string corresponding to
     C time t.

shishi_generalize_now
---------------------

 -- Function: const char * shishi_generalize_now (Shishi * HANDLE)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     Convert current time to KerberosTime.  The string must not be
     deallocate by caller.

     *Return value:* Return a KerberosTime time string corresponding to
     current time.

shishi_generalize_ctime
-----------------------

 -- Function: time_t shishi_generalize_ctime (Shishi * HANDLE, const
          char * T)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     T: KerberosTime to convert.

     Convert KerberosTime to C time.

     *Return value:* Returns C time corresponding to KerberosTime t.

shishi_time
-----------

 -- Function: int shishi_time (Shishi * HANDLE, Shishi_asn1 NODE, const
          char * FIELD, char ** T)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     NODE: ASN.1 node to get time from.

     FIELD: Name of field in ASN.1 node to get time from.

     T: newly allocated output array with zero terminated time string.

     Extract time from ASN.1 structure.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_ctime
------------

 -- Function: int shishi_ctime (Shishi * HANDLE, Shishi_asn1 NODE,
          const char * FIELD, time_t * T)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     NODE: ASN.1 variable to read field from.

     FIELD: name of field in `node' to read.

     T: pointer to time field to set.

     Extract time from ASN.1 structure.

     *Return value:* Returns SHISHI_OK if successful,
     SHISHI_ASN1_NO_ELEMENT if the element do not exist,
     SHISHI_ASN1_NO_VALUE if the field has no value, ot
     SHISHI_ASN1_ERROR otherwise.

shishi_prompt_password_callback_set
-----------------------------------

 -- Function: void shishi_prompt_password_callback_set (Shishi *
          HANDLE, shishi_prompt_password_func CB)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     CB: function pointer to application password callback, a
     `shishi_prompt_password_func' type.

     Set a callback function that will be used by
     `shishi_prompt_password()' to query the user for a password.  The
     function pointer can be retrieved using
     `shishi_prompt_password_callback_get()'.

     The `cb' function should follow the `shishi_prompt_password_func'
     prototype:

     int prompt_password (Shishi * `handle', char **`s', const char
     *`format', va_list `ap');

     If the function returns 0, the `s' variable should contain a newly
     allocated string with the password read from the user.

shishi_prompt_password_callback_get
-----------------------------------

 -- Function: shishi_prompt_password_func
shishi_prompt_password_callback_get (Shishi * HANDLE)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     Get the application password prompt function callback as set by
     `shishi_prompt_password_callback_set()'.

     *Returns:* Returns the callback, a `shishi_prompt_password_func'
     type, or `NULL'.

shishi_prompt_password
----------------------

 -- Function: int shishi_prompt_password (Shishi * HANDLE, char ** S,
          const char * FORMAT, ...)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     S: pointer to newly allocated output string with read password.

     FORMAT: printf(3) style format string.  ...: printf(3) style
     arguments.

     Format and print a prompt, and read a password from user.  The
     password is possibly converted (e.g., converted from Latin-1 to
     UTF-8, or processed using Stringprep profile) following any
     "stringprocess" keywords in configuration files.

     *Return value:* Returns SHISHI_OK iff successful.

shishi_resolv
-------------

 -- Function: Shishi_dns shishi_resolv (const char * ZONE, uint16_t
          QUERYTYPE)
     ZONE: owner name of data, e.g. "EXAMPLE.ORG"

     QUERYTYPE: type of data to query for, e.g., SHISHI_DNS_TXT.

     Query DNS resolver for data of type `querytype' at owner name
     `zone'.  Currently TXT and SRV types are supported.

     *Return value:* Returns linked list of DNS records, or NULL if
     query failed.

shishi_resolv_free
------------------

 -- Function: void shishi_resolv_free (Shishi_dns RRS)
     RRS: list of DNS RR as returned by `shishi_resolv()'.

     Deallocate list of DNS RR as returned by `shishi_resolv()'.


File: shishi.info,  Node: ASN.1 Functions,  Next: Error Handling,  Prev: Utility Functions,  Up: Programming Manual

5.16 ASN.1 Functions
====================

shishi_asn1_read_inline
-----------------------

 -- Function: int shishi_asn1_read_inline (Shishi * HANDLE, Shishi_asn1
          NODE, const char * FIELD, char * DATA, size_t * DATALEN)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     NODE: ASN.1 variable to read field from.

     FIELD: name of field in `node' to read.

     DATA: pre-allocated output buffer that will hold ASN.1 field data.

     DATALEN: on input, maximum size of output buffer, on output,
     actual size of output buffer.

     Extract data stored in a ASN.1 field into a fixed size buffer
     allocated by caller.

     Note that since it is difficult to predict the length of the field,
     it is often better to use `shishi_asn1_read()' instead.

     *Return value:* Returns SHISHI_OK if successful,
     SHISHI_ASN1_NO_ELEMENT if the element do not exist,
     SHISHI_ASN1_NO_VALUE if the field has no value, ot
     SHISHI_ASN1_ERROR otherwise.

shishi_asn1_read
----------------

 -- Function: int shishi_asn1_read (Shishi * HANDLE, Shishi_asn1 NODE,
          const char * FIELD, char ** DATA, size_t * DATALEN)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     NODE: ASN.1 variable to read field from.

     FIELD: name of field in `node' to read.

     DATA: newly allocated output buffer that will hold ASN.1 field
     data.

     DATALEN: actual size of output buffer.

     Extract data stored in a ASN.1 field into a newly allocated buffer.
     The buffer will always be zero terminated, even though `datalen'
     will not include the added zero.

     *Return value:* Returns SHISHI_OK if successful,
     SHISHI_ASN1_NO_ELEMENT if the element do not exist,
     SHISHI_ASN1_NO_VALUE if the field has no value, ot
     SHISHI_ASN1_ERROR otherwise.

shishi_asn1_read_optional
-------------------------

 -- Function: int shishi_asn1_read_optional (Shishi * HANDLE,
          Shishi_asn1 NODE, const char * FIELD, char ** DATA, size_t *
          DATALEN)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     NODE: ASN.1 variable to read field from.

     FIELD: name of field in `node' to read.

     DATA: newly allocated output buffer that will hold ASN.1 field
     data.

     DATALEN: actual size of output buffer.

     Extract data stored in a ASN.1 field into a newly allocated buffer.
     If the field does not exist (i.e., SHISHI_ASN1_NO_ELEMENT), this
     function set datalen to 0 and succeeds.  Can be useful to read
     ASN.1 fields which are marked OPTIONAL in the grammar, if you want
     to avoid special error handling in your code.

     *Return value:* Returns SHISHI_OK if successful,
     SHISHI_ASN1_NO_VALUE if the field has no value, ot
     SHISHI_ASN1_ERROR otherwise.

shishi_asn1_done
----------------

 -- Function: void shishi_asn1_done (Shishi * HANDLE, Shishi_asn1 NODE)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     NODE: ASN.1 node to dellocate.

     Deallocate resources associated with ASN.1 structure.  Note that
     the node must not be used after this call.

shishi_asn1_pa_enc_ts_enc
-------------------------

 -- Function: Shishi_asn1 shishi_asn1_pa_enc_ts_enc (Shishi * HANDLE)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     Create new ASN.1 structure for PA-ENC-TS-ENC.

     *Return value:* Returns ASN.1 structure.

shishi_asn1_encrypteddata
-------------------------

 -- Function: Shishi_asn1 shishi_asn1_encrypteddata (Shishi * HANDLE)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     Create new ASN.1 structure for EncryptedData

     *Return value:* Returns ASN.1 structure.

shishi_asn1_padata
------------------

 -- Function: Shishi_asn1 shishi_asn1_padata (Shishi * HANDLE)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     Create new ASN.1 structure for PA-DATA.

     *Return value:* Returns ASN.1 structure.

shishi_asn1_methoddata
----------------------

 -- Function: Shishi_asn1 shishi_asn1_methoddata (Shishi * HANDLE)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     Create new ASN.1 structure for METHOD-DATA.

     *Return value:* Returns ASN.1 structure.

shishi_asn1_etype_info
----------------------

 -- Function: Shishi_asn1 shishi_asn1_etype_info (Shishi * HANDLE)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     Create new ASN.1 structure for ETYPE-INFO.

     *Return value:* Returns ASN.1 structure.

shishi_asn1_etype_info2
-----------------------

 -- Function: Shishi_asn1 shishi_asn1_etype_info2 (Shishi * HANDLE)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     Create new ASN.1 structure for ETYPE-INFO2.

     *Return value:* Returns ASN.1 structure.

shishi_asn1_asreq
-----------------

 -- Function: Shishi_asn1 shishi_asn1_asreq (Shishi * HANDLE)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     Create new ASN.1 structure for AS-REQ.

     *Return value:* Returns ASN.1 structure.

shishi_asn1_asrep
-----------------

 -- Function: Shishi_asn1 shishi_asn1_asrep (Shishi * HANDLE)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     Create new ASN.1 structure for AS-REP.

     *Return value:* Returns ASN.1 structure.

shishi_asn1_tgsreq
------------------

 -- Function: Shishi_asn1 shishi_asn1_tgsreq (Shishi * HANDLE)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     Create new ASN.1 structure for TGS-REQ.

     *Return value:* Returns ASN.1 structure.

shishi_asn1_tgsrep
------------------

 -- Function: Shishi_asn1 shishi_asn1_tgsrep (Shishi * HANDLE)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     Create new ASN.1 structure for TGS-REP.

     *Return value:* Returns ASN.1 structure.

shishi_asn1_apreq
-----------------

 -- Function: Shishi_asn1 shishi_asn1_apreq (Shishi * HANDLE)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     Create new ASN.1 structure for AP-REQ.

     *Return value:* Returns ASN.1 structure.

shishi_asn1_aprep
-----------------

 -- Function: Shishi_asn1 shishi_asn1_aprep (Shishi * HANDLE)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     Create new ASN.1 structure for AP-REP.

     *Return value:* Returns ASN.1 structure.

shishi_asn1_encapreppart
------------------------

 -- Function: Shishi_asn1 shishi_asn1_encapreppart (Shishi * HANDLE)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     Create new ASN.1 structure for AP-REP.

     *Return value:* Returns ASN.1 structure.

shishi_asn1_ticket
------------------

 -- Function: Shishi_asn1 shishi_asn1_ticket (Shishi * HANDLE)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     Create new ASN.1 structure for Ticket.

     *Return value:* Returns ASN.1 structure.

shishi_asn1_encticketpart
-------------------------

 -- Function: Shishi_asn1 shishi_asn1_encticketpart (Shishi * HANDLE)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     Create new ASN.1 structure for EncTicketPart.

     *Return value:* Returns ASN.1 structure.

shishi_asn1_authenticator
-------------------------

 -- Function: Shishi_asn1 shishi_asn1_authenticator (Shishi * HANDLE)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     Create new ASN.1 structure for Authenticator.

     *Return value:* Returns ASN.1 structure.

shishi_asn1_enckdcreppart
-------------------------

 -- Function: Shishi_asn1 shishi_asn1_enckdcreppart (Shishi * HANDLE)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     Create new ASN.1 structure for EncKDCRepPart.

     *Return value:* Returns ASN.1 structure.

shishi_asn1_encasreppart
------------------------

 -- Function: Shishi_asn1 shishi_asn1_encasreppart (Shishi * HANDLE)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     Create new ASN.1 structure for EncASRepPart.

     *Return value:* Returns ASN.1 structure.

shishi_asn1_krberror
--------------------

 -- Function: Shishi_asn1 shishi_asn1_krberror (Shishi * HANDLE)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     Create new ASN.1 structure for KRB-ERROR.

     *Return value:* Returns ASN.1 structure.

shishi_asn1_krbsafe
-------------------

 -- Function: Shishi_asn1 shishi_asn1_krbsafe (Shishi * HANDLE)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     Create new ASN.1 structure for KRB-SAFE.

     *Return value:* Returns ASN.1 structure.

shishi_asn1_priv
----------------

 -- Function: Shishi_asn1 shishi_asn1_priv (Shishi * HANDLE)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     Create new ASN.1 structure for KRB-PRIV.

     *Return value:* Returns ASN.1 structure.

shishi_asn1_encprivpart
-----------------------

 -- Function: Shishi_asn1 shishi_asn1_encprivpart (Shishi * HANDLE)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     Create new ASN.1 structure for EncKrbPrivPart.

     *Return value:* Returns ASN.1 structure.

shishi_asn1_to_der_field
------------------------

 -- Function: int shishi_asn1_to_der_field (Shishi * HANDLE,
          Shishi_asn1 NODE, const char * FIELD, char ** DER, size_t *
          LEN)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     NODE: ASN.1 data that have field to extract.

     FIELD: name of field in `node' to extract.

     DER: output array that holds DER encoding of `field' in `node'.

     LEN: output variable with length of `der' output array.

     Extract newly allocated DER representation of specified ASN.1
     field.

     *Return value:* Returns SHISHI_OK if successful, or
     SHISHI_ASN1_ERROR if DER encoding fails (common reasons for this
     is that the ASN.1 is missing required values).

shishi_asn1_to_der
------------------

 -- Function: int shishi_asn1_to_der (Shishi * HANDLE, Shishi_asn1
          NODE, char ** DER, size_t * LEN)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     NODE: ASN.1 data to convert to DER.

     DER: output array that holds DER encoding of `node'.

     LEN: output variable with length of `der' output array.

     Extract newly allocated DER representation of specified ASN.1 data.

     *Return value:* Returns SHISHI_OK if successful, or
     SHISHI_ASN1_ERROR if DER encoding fails (common reasons for this
     is that the ASN.1 is missing required values).

shishi_asn1_msgtype
-------------------

 -- Function: Shishi_msgtype shishi_asn1_msgtype (Shishi * HANDLE,
          Shishi_asn1 NODE)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     NODE: ASN.1 type to get msg type for.

     Determine msg-type of ASN.1 type of a packet. Currently this uses
     the msg-type field instead of the APPLICATION tag, but this may be
     changed in the future.

     *Return value:* Returns msg-type of ASN.1 type, 0 on failure.

shishi_der_msgtype
------------------

 -- Function: Shishi_msgtype shishi_der_msgtype (Shishi * HANDLE, const
          char * DER, size_t DERLEN)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     DER: input character array with DER encoding.

     DERLEN: length of input character array with DER encoding.

     Determine msg-type of DER coded data of a packet.

     *Return value:* Returns msg-type of DER data, 0 on failure.

shishi_der2asn1
---------------

 -- Function: Shishi_asn1 shishi_der2asn1 (Shishi * HANDLE, const char
          * DER, size_t DERLEN)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     DER: input character array with DER encoding.

     DERLEN: length of input character array with DER encoding.

     Convert arbitrary DER data of a packet to a ASN.1 type.

     *Return value:* Returns newly allocate ASN.1 corresponding to DER
     data, or `NULL' on failure.

shishi_der2asn1_padata
----------------------

 -- Function: Shishi_asn1 shishi_der2asn1_padata (Shishi * HANDLE,
          const char * DER, size_t DERLEN)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     DER: input character array with DER encoding.

     DERLEN: length of input character array with DER encoding.

     Decode DER encoding of PA-DATA and create a ASN.1 structure.

     *Return value:* Returns ASN.1 structure corresponding to DER data.

shishi_der2asn1_methoddata
--------------------------

 -- Function: Shishi_asn1 shishi_der2asn1_methoddata (Shishi * HANDLE,
          const char * DER, size_t DERLEN)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     DER: input character array with DER encoding.

     DERLEN: length of input character array with DER encoding.

     Decode DER encoding of METHOD-DATA and create a ASN.1 structure.

     *Return value:* Returns ASN.1 structure corresponding to DER data.

shishi_der2asn1_etype_info
--------------------------

 -- Function: Shishi_asn1 shishi_der2asn1_etype_info (Shishi * HANDLE,
          const char * DER, size_t DERLEN)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     DER: input character array with DER encoding.

     DERLEN: length of input character array with DER encoding.

     Decode DER encoding of ETYPE-INFO and create a ASN.1 structure.

     *Return value:* Returns ASN.1 structure corresponding to DER data.

shishi_der2asn1_etype_info2
---------------------------

 -- Function: Shishi_asn1 shishi_der2asn1_etype_info2 (Shishi * HANDLE,
          const char * DER, size_t DERLEN)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     DER: input character array with DER encoding.

     DERLEN: length of input character array with DER encoding.

     Decode DER encoding of ETYPE-INFO2 and create a ASN.1 structure.

     *Return value:* Returns ASN.1 structure corresponding to DER data.

shishi_der2asn1_ticket
----------------------

 -- Function: Shishi_asn1 shishi_der2asn1_ticket (Shishi * HANDLE,
          const char * DER, size_t DERLEN)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     DER: input character array with DER encoding.

     DERLEN: length of input character array with DER encoding.

     Decode DER encoding of Ticket and create a ASN.1 structure.

     *Return value:* Returns ASN.1 structure corresponding to DER data.

shishi_der2asn1_encticketpart
-----------------------------

 -- Function: Shishi_asn1 shishi_der2asn1_encticketpart (Shishi *
          HANDLE, const char * DER, size_t DERLEN)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     DER: input character array with DER encoding.

     DERLEN: length of input character array with DER encoding.

     Decode DER encoding of EncTicketPart and create a ASN.1 structure.

     *Return value:* Returns ASN.1 structure corresponding to DER data.

shishi_der2asn1_asreq
---------------------

 -- Function: Shishi_asn1 shishi_der2asn1_asreq (Shishi * HANDLE, const
          char * DER, size_t DERLEN)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     DER: input character array with DER encoding.

     DERLEN: length of input character array with DER encoding.

     Decode DER encoding of AS-REQ and create a ASN.1 structure.

     *Return value:* Returns ASN.1 structure corresponding to DER data.

shishi_der2asn1_tgsreq
----------------------

 -- Function: Shishi_asn1 shishi_der2asn1_tgsreq (Shishi * HANDLE,
          const char * DER, size_t DERLEN)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     DER: input character array with DER encoding.

     DERLEN: length of input character array with DER encoding.

     Decode DER encoding of TGS-REQ and create a ASN.1 structure.

     *Return value:* Returns ASN.1 structure corresponding to DER data.

shishi_der2asn1_asrep
---------------------

 -- Function: Shishi_asn1 shishi_der2asn1_asrep (Shishi * HANDLE, const
          char * DER, size_t DERLEN)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     DER: input character array with DER encoding.

     DERLEN: length of input character array with DER encoding.

     Decode DER encoding of AS-REP and create a ASN.1 structure.

     *Return value:* Returns ASN.1 structure corresponding to DER data.

shishi_der2asn1_tgsrep
----------------------

 -- Function: Shishi_asn1 shishi_der2asn1_tgsrep (Shishi * HANDLE,
          const char * DER, size_t DERLEN)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     DER: input character array with DER encoding.

     DERLEN: length of input character array with DER encoding.

     Decode DER encoding of TGS-REP and create a ASN.1 structure.

     *Return value:* Returns ASN.1 structure corresponding to DER data.

shishi_der2asn1_kdcrep
----------------------

 -- Function: Shishi_asn1 shishi_der2asn1_kdcrep (Shishi * HANDLE,
          const char * DER, size_t DERLEN)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     DER: input character array with DER encoding.

     DERLEN: length of input character array with DER encoding.

     Decode DER encoding of KDC-REP and create a ASN.1 structure.

     *Return value:* Returns ASN.1 structure corresponding to DER data.

shishi_der2asn1_encasreppart
----------------------------

 -- Function: Shishi_asn1 shishi_der2asn1_encasreppart (Shishi *
          HANDLE, const char * DER, size_t DERLEN)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     DER: input character array with DER encoding.

     DERLEN: length of input character array with DER encoding.

     Decode DER encoding of EncASRepPart and create a ASN.1 structure.

     *Return value:* Returns ASN.1 structure corresponding to DER data.

shishi_der2asn1_enctgsreppart
-----------------------------

 -- Function: Shishi_asn1 shishi_der2asn1_enctgsreppart (Shishi *
          HANDLE, const char * DER, size_t DERLEN)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     DER: input character array with DER encoding.

     DERLEN: length of input character array with DER encoding.

     Decode DER encoding of EncTGSRepPart and create a ASN.1 structure.

     *Return value:* Returns ASN.1 structure corresponding to DER data.

shishi_der2asn1_enckdcreppart
-----------------------------

 -- Function: Shishi_asn1 shishi_der2asn1_enckdcreppart (Shishi *
          HANDLE, const char * DER, size_t DERLEN)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     DER: input character array with DER encoding.

     DERLEN: length of input character array with DER encoding.

     Decode DER encoding of EncKDCRepPart and create a ASN.1 structure.

     *Return value:* Returns ASN.1 structure corresponding to DER data.

shishi_der2asn1_authenticator
-----------------------------

 -- Function: Shishi_asn1 shishi_der2asn1_authenticator (Shishi *
          HANDLE, const char * DER, size_t DERLEN)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     DER: input character array with DER encoding.

     DERLEN: length of input character array with DER encoding.

     Decode DER encoding of Authenticator and create a ASN.1 structure.

     *Return value:* Returns ASN.1 structure corresponding to DER data.

shishi_der2asn1_krberror
------------------------

 -- Function: Shishi_asn1 shishi_der2asn1_krberror (Shishi * HANDLE,
          const char * DER, size_t DERLEN)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     DER: input character array with DER encoding.

     DERLEN: length of input character array with DER encoding.

     Decode DER encoding of KRB-ERROR and create a ASN.1 structure.

     *Return value:* Returns ASN.1 structure corresponding to DER data.

shishi_der2asn1_krbsafe
-----------------------

 -- Function: Shishi_asn1 shishi_der2asn1_krbsafe (Shishi * HANDLE,
          const char * DER, size_t DERLEN)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     DER: input character array with DER encoding.

     DERLEN: length of input character array with DER encoding.

     Decode DER encoding of KRB-SAFE and create a ASN.1 structure.

     *Return value:* Returns ASN.1 structure corresponding to DER data.

shishi_der2asn1_priv
--------------------

 -- Function: Shishi_asn1 shishi_der2asn1_priv (Shishi * HANDLE, const
          char * DER, size_t DERLEN)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     DER: input character array with DER encoding.

     DERLEN: length of input character array with DER encoding.

     Decode DER encoding of KRB-PRIV and create a ASN.1 structure.

     *Return value:* Returns ASN.1 structure corresponding to DER data.

shishi_der2asn1_encprivpart
---------------------------

 -- Function: Shishi_asn1 shishi_der2asn1_encprivpart (Shishi * HANDLE,
          const char * DER, size_t DERLEN)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     DER: input character array with DER encoding.

     DERLEN: length of input character array with DER encoding.

     Decode DER encoding of EncKrbPrivPart and create a ASN.1 structure.

     *Return value:* Returns ASN.1 structure corresponding to DER data.

shishi_der2asn1_apreq
---------------------

 -- Function: Shishi_asn1 shishi_der2asn1_apreq (Shishi * HANDLE, const
          char * DER, size_t DERLEN)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     DER: input character array with DER encoding.

     DERLEN: length of input character array with DER encoding.

     Decode DER encoding of AP-REQ and create a ASN.1 structure.

     *Return value:* Returns ASN.1 structure corresponding to DER data.

shishi_der2asn1_aprep
---------------------

 -- Function: Shishi_asn1 shishi_der2asn1_aprep (Shishi * HANDLE, const
          char * DER, size_t DERLEN)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     DER: input character array with DER encoding.

     DERLEN: length of input character array with DER encoding.

     Decode DER encoding of AP-REP and create a ASN.1 structure.

     *Return value:* Returns ASN.1 structure corresponding to DER data.

shishi_der2asn1_encapreppart
----------------------------

 -- Function: Shishi_asn1 shishi_der2asn1_encapreppart (Shishi *
          HANDLE, const char * DER, size_t DERLEN)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     DER: input character array with DER encoding.

     DERLEN: length of input character array with DER encoding.

     Decode DER encoding of EncAPRepPart and create a ASN.1 structure.

     *Return value:* Returns ASN.1 structure corresponding to DER data.

shishi_der2asn1_kdcreq
----------------------

 -- Function: Shishi_asn1 shishi_der2asn1_kdcreq (Shishi * HANDLE,
          const char * DER, size_t DERLEN)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     DER: input character array with DER encoding.

     DERLEN: length of input character array with DER encoding.

     Decode DER encoding of AS-REQ, TGS-REQ or KDC-REQ and create a
     ASN.1 structure.

     *Return value:* Returns ASN.1 structure corresponding to DER data.

shishi_asn1_print
-----------------

 -- Function: void shishi_asn1_print (Shishi * HANDLE, Shishi_asn1
          NODE, FILE * FH)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     NODE: ASN.1 data that have field to extract.

     FH: file descriptor to print to, e.g. stdout.

     Print ASN.1 structure in human readable form, typically for
     debugging purposes.


File: shishi.info,  Node: Error Handling,  Next: Examples,  Prev: ASN.1 Functions,  Up: Programming Manual

5.17 Error Handling
===================

Most functions in `Libshishi' are returning an error if they fail.  For
this reason, the application should always catch the error condition
and take appropriate measures, for example by releasing the resources
and passing the error up to the caller, or by displaying a descriptive
message to the user and cancelling the operation.

   Some error values do not indicate a system error or an error in the
operation, but the result of an operation that failed properly.

* Menu:

* Error Values::                A list of all error values used.
* Error Functions::             Error handling related functions.


File: shishi.info,  Node: Error Values,  Next: Error Functions,  Up: Error Handling

5.17.1 Error Values
-------------------

Errors are returned as an `int'.  Except for the SHISHI_OK case, an
application should always use the constants instead of their numeric
value.  Applications are encouraged to use the constants even for
SHISHI_OK as it improves readability.  Possible values are:

`SHISHI_OK'
     This value indicates success.  The value of this error is
     guaranteed to always be `0' so you may use it in boolean
     constructs.

`SHISHI_ASN1_ERROR'
     Error in ASN.1 function (corrupt data?)

`SHISHI_FOPEN_ERROR'
     Could not open file

`SHISHI_IO_ERROR'
     File input/output error

`SHISHI_MALLOC_ERROR'
     Memory allocation error in shishi library.

`SHISHI_BASE64_ERROR'
     Base64 encoding or decoding failed. Data corrupt?

`SHISHI_REALM_MISMATCH'
     Client realm value differ between request and reply.

`SHISHI_CNAME_MISMATCH'
     Client name value differ between request and reply.

`SHISHI_NONCE_MISMATCH'
     Replay protection value (nonce) differ between request and reply.

`SHISHI_TGSREP_BAD_KEYTYPE'
     Incorrect key type used in TGS reply.

`SHISHI_KDCREP_BAD_KEYTYPE'
     Incorrect key type used in reply from KDC.

`SHISHI_APREP_BAD_KEYTYPE'
     Incorrect key type used in AP reply.

`SHISHI_APREP_VERIFY_FAILED'
     Failed verification of AP reply.

`SHISHI_APREQ_BAD_KEYTYPE'
     Incorrect key type used in AP request.

`SHISHI_TOO_SMALL_BUFFER'
     Provided buffer was too small.

`SHISHI_DERIVEDKEY_TOO_SMALL'
     Derived key material is too short to be applicable.

`SHISHI_KEY_TOO_LARGE'
     The key is too large to be usable.

`SHISHI_CRYPTO_ERROR'
     Low-level cryptographic primitive failed.  This usually indicates
     bad password or data corruption.

`SHISHI_CRYPTO_INTERNAL_ERROR'
     Internal error in low-level crypto routines.

`SHISHI_SOCKET_ERROR'
     The system call socket() failed.  This usually indicates that your
     system does not support the socket type.

`SHISHI_BIND_ERROR'
     The system call bind() failed.  This usually indicates
     insufficient permissions.

`SHISHI_SENDTO_ERROR'
     The system call sendto() failed.

`SHISHI_RECVFROM_ERROR'
     Error receiving data from server

`SHISHI_CLOSE_ERROR'
     The system call close() failed.

`SHISHI_KDC_TIMEOUT'
     Timed out talking to KDC. This usually indicates a network or KDC
     address problem.

`SHISHI_KDC_NOT_KNOWN_FOR_REALM'
     No KDC known for given realm.

`SHISHI_TTY_ERROR'
     No TTY assigned to process.

`SHISHI_GOT_KRBERROR'
     Server replied to the request with an error message.

`SHISHI_HANDLE_ERROR'
     Failure to use handle.  Missing handle, or misconfigured.

`SHISHI_INVALID_TKTS'
     Ticket set not initialized.  This usually indicates an internal
     application error.

`SHISHI_TICKET_BAD_KEYTYPE'
     Key type used to encrypt ticket doesn't match provided key. This
     usually indicates an internal application error.

`SHISHI_INVALID_KEY'
     Reference to invalid encryption key.

`SHISHI_APREQ_DECRYPT_FAILED'
     Could not decrypt AP-REQ using provided key. This usually
     indicates an internal application error.

`SHISHI_TICKET_DECRYPT_FAILED'
     Could not decrypt Ticket using provided key. This usually
     indicates an internal application error.

`SHISHI_INVALID_TICKET'
     Invalid ticked passed in call.

`SHISHI_OUT_OF_RANGE'
     Argument lies outside of valid range.

`SHISHI_ASN1_NO_ELEMENT'
     The ASN.1 structure does not contain the indicated element.

`SHISHI_SAFE_BAD_KEYTYPE'
     Attempted access to non-existent key type.

`SHISHI_SAFE_VERIFY_FAILED'
     Verification failed on either side.

`SHISHI_PKCS5_INVALID_PRF'
     Invalid PKCS5 descriptor.

`SHISHI_PKCS5_INVALID_ITERATION_COUNT'
     Invalid claim of iteration count in PKCS5 descriptor.

`SHISHI_PKCS5_INVALID_DERIVED_KEY_LENGTH'
     Derived key length is incorrect for PKCS5 descriptor.

`SHISHI_PKCS5_DERIVED_KEY_TOO_LONG'
     Derived key is too long for PKCS5 descriptor.

`SHISHI_INVALID_PRINCIPAL_NAME'
     Principal name syntax error.

`SHISHI_INVALID_ARGUMENT'
     Invalid argument passed in call.  Wrong or unknown value.

`SHISHI_ASN1_NO_VALUE'
     The indicated ASN.1 element does not carry a value.

`SHISHI_CONNECT_ERROR'
     Connection attempt failed.  Try again, or check availability.

`SHISHI_VERIFY_FAILED'
     Verification failed on either side.

`SHISHI_PRIV_BAD_KEYTYPE'
     The private key uses an incompatible encryption type.

`SHISHI_FILE_ERROR'
     The desired file could not be accessed.  Check permissions.

`SHISHI_ENCAPREPPART_BAD_KEYTYPE'
     The present AP reply specifies an inpermissible key type.

`SHISHI_GETTIMEOFDAY_ERROR'
     A request for present time of day has failed. This is usually
     internal, but a valid time is imperative for us.

`SHISHI_KEYTAB_ERROR'
     Failed to parse keytab file

`SHISHI_CCACHE_ERROR'
     Failed to parse credential cache file



File: shishi.info,  Node: Error Functions,  Prev: Error Values,  Up: Error Handling

5.17.2 Error Functions
----------------------

shishi_strerror
---------------

 -- Function: const char * shishi_strerror (int ERR)
     ERR: shishi error code.

     Convert return code to human readable string.

     *Return value:* Returns a pointer to a statically allocated string
     containing a description of the error with the error value `err'.
     This string can be used to output a diagnostic message to the user.

shishi_error
------------

 -- Function: const char * shishi_error (Shishi * HANDLE)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     Extract detailed error information string.  Note that the memory is
     managed by the Shishi library, so you must not deallocate the
     string.

     *Return value:* Returns pointer to error information string, that
     must not be deallocate by caller.

shishi_error_clear
------------------

 -- Function: void shishi_error_clear (Shishi * HANDLE)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     Clear the detailed error information string.  See `shishi_error()'
     for how to access the error string, and `shishi_error_set()' and
     `shishi_error_printf()' for how to set the error string.  This
     function is mostly for Shishi internal use, but if you develop an
     extension of Shishi, it may be useful to use the same error
     handling infrastructure.

shishi_error_set
----------------

 -- Function: void shishi_error_set (Shishi * HANDLE, const char *
          ERRSTR)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     ERRSTR: Zero terminated character array containing error
     description, or NULL to clear the error description string.

     Set the detailed error information string to specified string.  The
     string is copied into the Shishi internal structure, so you can
     deallocate the string passed to this function after the call.  This
     function is mostly for Shishi internal use, but if you develop an
     extension of Shishi, it may be useful to use the same error
     handling infrastructure.

shishi_error_printf
-------------------

 -- Function: void shishi_error_printf (Shishi * HANDLE, const char *
          FORMAT, ...)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     FORMAT: printf style format string.  ...: print style arguments.

     Set the detailed error information string to a printf formatted
     string.  This function is mostly for Shishi internal use, but if
     you develop an extension of Shishi, it may be useful to use the
     same error handling infrastructure.

shishi_error_outputtype
-----------------------

 -- Function: int shishi_error_outputtype (Shishi * HANDLE)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     Get the current output type for logging messages.

     *Return value:* Return output type (NULL, stderr or syslog) for
     informational and warning messages.

shishi_error_set_outputtype
---------------------------

 -- Function: void shishi_error_set_outputtype (Shishi * HANDLE, int
          TYPE)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     TYPE: output type.

     Set output type (NULL, stderr or syslog) for informational and
     warning messages.

shishi_info
-----------

 -- Function: void shishi_info (Shishi * HANDLE, const char * FORMAT,
          ...)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     FORMAT: printf style format string.  ...: print style arguments.

     Print informational message to output as defined in handle.

shishi_warn
-----------

 -- Function: void shishi_warn (Shishi * HANDLE, const char * FORMAT,
          ...)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     FORMAT: printf style format string.  ...: print style arguments.

     Print a warning to output as defined in handle.

shishi_verbose
--------------

 -- Function: void shishi_verbose (Shishi * HANDLE, const char *
          FORMAT, ...)
     HANDLE: shishi handle as allocated by `shishi_init()'.

     FORMAT: printf style format string.  ...: print style arguments.

     Print a diagnostic message to output as defined in handle.


File: shishi.info,  Node: Examples,  Next: Kerberos Database Functions,  Prev: Error Handling,  Up: Programming Manual

5.18 Examples
=============

This section will be extended to contain walk-throughs of example code
that demonstrate how `Shishi' is used to write your own applications
that support Kerberos 5.  The rest of the current section consists of
some crude hints for the example client/server applications that is
part of Shishi, taken from an email but saved here for lack of a better
place to put it.

   There are two programs: 'client' and 'server' in src/.

   The client output an AP-REQ, waits for an AP-REP, and then simply
reads data from stdin.

   The server waits for an AP-REQ, parses it and prints an AP-REP, and
then read data from stdin.

   Both programs accept a Kerberos server name as the first command line
argument.  Your KDC must know this server, since the client tries to
get a ticket for it (first it gets a ticket granting ticket for the
default username), and you must write the key for the server into
/usr/local/etc/shishi.keys on the Shishi format, e.g.:

     -----BEGIN SHISHI KEY-----
     Keytype: 16 (des3-cbc-sha1-kd)
     Principal: sample/latte.josefsson.org
     Realm: JOSEFSSON.ORG

     8W0VrQQBpxlACPQEqN91EHxbvFFo2ltt
     -----END SHISHI KEY-----

   You must extract the proper encryption key from the KDC in some way.
(This part will be easier when Shishi include a KDC, a basic one isn't
far away, give me a week or to.)

   The intention is that the data read, after the authentication phase,
should be protected using KRB_SAFE (see RFC) but I haven't added this
yet.


File: shishi.info,  Node: Kerberos Database Functions,  Next: Generic Security Service,  Prev: Examples,  Up: Programming Manual

5.19 Kerberos Database Functions
================================

Shisa is a separate and standalone library from Shishi (*note
Introduction to Shisa::).  If you only wish to manipulate the
information stored in the Kerberos user database used by Shishi, you do
not need to link or use the Shishi library at all.  However, you may
find it useful to combine the two libraries.

   For two real world examples on using the Shisa library, refer to
`src/shisa.c' (Shisa command line tool) and `src/kdc.c' (part of
Shishid server).

   Shisa uses two `struct's to carry information.  The first,
`Shisa_principal', is used to hold information about principals.  The
struct does not contain pointers to strings etc, so the library assumes
the caller is responsible for allocating and deallocating the struct
itself.  Each such struct is (uniquely) identified by the combination
of principal name and realm name.

     struct Shisa_principal
     {
       int isdisabled;
       uint32_t kvno;
       time_t notusedbefore;
       time_t lastinitialtgt;      /* time of last initial request for a TGT */
       time_t lastinitialrequest;  /* time of last initial request */
       time_t lasttgt;             /* time of issue for the newest TGT used */
       time_t lastrenewal;         /* time of the last renewal */
       time_t passwordexpire;      /* time when the password will expire */
       time_t accountexpire;       /* time when the account will expire. */
     };
     typedef struct Shisa_principal Shisa_principal;

   The second structure is called `Shisa_key' and hold information
about cryptographic keys.  Because the struct contain pointers, and the
caller cannot know how many keys a principal have, the Shisa library
manages memory for the struct.  The library allocate the structs, and
the pointers within them.  The caller may deallocate them, but it is
recommended to use `shisa_key_free' or `shisa_keys_free' instead.  Note
that each principal may have multiple keys.

     struct Shisa_key
     {
       uint32_t kvno;
       int32_t etype;
       int priority;
       char *key;
       size_t keylen;
       char *salt;
       size_t saltlen;
       char *str2keyparam;
       size_t str2keyparamlen;
       char *password;
     };
     typedef struct Shisa_key Shisa_key;

   Shisa is typically initialized by calling `shisa_init', and
deinitialized (when the application no longer need to use Shisa,
typically when it shuts down) by calling `shisa_done', but here are the
complete (de)initialization interface functions.

shisa
-----

 -- Function: Shisa * shisa ( VOID)
     Initializes the Shisa library.  If this function fails, it may
     print diagnostic errors to stderr.

     *Return value:* Returns Shisa library handle, or `NULL' on error.

shisa_done
----------

 -- Function: void shisa_done (Shisa * DBH)
     Deallocates the shisa library handle.  The handle must not be used
     in any calls to shisa functions after this.

shisa_init
----------

 -- Function: int shisa_init (Shisa ** DBH)
     DBH: pointer to library handle to be created.

     Create a Shisa library handle, using `shisa()', and read the system
     configuration file from their default locations.  The paths to the
     default system configuration file is decided at compile time
     ($sysconfdir/shisa.conf).

     The handle is allocated regardless of return values, except for
     SHISA_INIT_ERROR which indicates a problem allocating the handle.
     (The other error conditions comes from reading the files.)

     *Return value:* Returns `SHISA_OK' iff successful.

shisa_init_with_paths
---------------------

 -- Function: int shisa_init_with_paths (Shisa ** DBH, const char *
          FILE)
     DBH: pointer to library handle to be created.

     FILE: Filename of system configuration, or NULL.

     Create a Shisa library handle, using `shisa()', and read the system
     configuration file indicated location (or the default location, if
     `NULL').  The paths to the default system configuration file is
     decided at compile time ($sysconfdir/shisa.conf).

     The handle is allocated regardless of return values, except for
     SHISA_INIT_ERROR which indicates a problem allocating the handle.
     (The other error conditions comes from reading the files.)

     *Return value:* Returns `SHISA_OK' iff successful.

   The default configuration file is typically read automatically by
calling `shisa_init', but if you wish to manually access the Shisa
configuration file functions, here is the complete interface.

shisa_cfg_db
------------

 -- Function: int shisa_cfg_db (Shisa * DBH, const char * VALUE)
     DBH: Shisa library handle created by `shisa()'.

     VALUE: string with database definition.

     Setup and open a new database.  The syntax of the `value' parameter
     is "TYPE[ LOCATION[ PARAMETER]]", where TYPE is one of the
     supported database types (e.g., "file") and LOCATION and PARAMETER
     are optional strings passed to the database during initialization.
     Neither TYPE nor LOCATION can contain " " (SPC), but PARAMETER may.

     *Return Value:* Returns `SHISA_OK' if database was parsed and open
     successfully.

shisa_cfg
---------

 -- Function: int shisa_cfg (Shisa * DBH, const char * OPTION)
     DBH: Shisa library handle created by `shisa()'.

     OPTION: string with shisa library option.

     Configure shisa library with given option.

     *Return Value:* Returns SHISA_OK if option was valid.

shisa_cfg_from_file
-------------------

 -- Function: int shisa_cfg_from_file (Shisa * DBH, const char * CFG)
     DBH: Shisa library handle created by `shisa()'.

     CFG: filename to read configuration from.

     Configure shisa library using configuration file.

     *Return Value:* Returns `SHISA_OK' iff successful.

shisa_cfg_default_systemfile
----------------------------

 -- Function: const char * shisa_cfg_default_systemfile (Shisa * DBH)
     DBH: Shisa library handle created by `shisa()'.

     *Return value:* Return system configuration filename.

   The core part of the Shisa interface follows.  The typical procedure
is to use `shisa_principal_find' to verify that a specific principal
exists, and to extract some information about it, and then use
`shisa_keys_find' to get the cryptographic keys for the principal,
usually suppliying some hints as to which of all keys you are
interested in (e.g., key version number and encryption algorithm
number).

shisa_enumerate_realms
----------------------

 -- Function: int shisa_enumerate_realms (Shisa * DBH, char *** REALMS,
          size_t * NREALMS)
     DBH: Shisa library handle created by `shisa()'.

     REALMS: Pointer to newly allocated array of newly allocated
     zero-terminated UTF-8 strings indicating name of realm.

     NREALMS: Pointer to number indicating number of allocated realm
     strings.

     Extract a list of all realm names in backend, as zero-terminated
     UTF-8 strings.  The caller must deallocate the strings.

     *Return value:* Returns SHISA_OK on success, or error code.

shisa_enumerate_principals
--------------------------

 -- Function: int shisa_enumerate_principals (Shisa * DBH, const char *
          REALM, char *** PRINCIPALS, size_t * NPRINCIPALS)
     DBH: Shisa library handle created by `shisa()'.

     REALM: Name of realm, as zero-terminated UTF-8 string.

     NPRINCIPALS: Pointer to number indicating number of allocated
     realm strings.

     Extract a list of all principal names in realm in backend, as
     zero-terminated UTF-8 strings.  The caller must deallocate the
     strings.

     *Return value:* Returns SHISA_OK on success, SHISA_NO_REALM if the
     specified realm does not exist, or error code.

shisa_principal_find
--------------------

 -- Function: int shisa_principal_find (Shisa * DBH, const char *
          REALM, const char * PRINCIPAL, Shisa_principal * PH)
     DBH: Shisa library handle created by `shisa()'.

     REALM: Name of realm the principal belongs in.

     PRINCIPAL: Name of principal to get information on.

     PH: Pointer to previously allocated principal structure to fill
     out with information about principal.

     Extract information about given PRINCIPAL`REALM'.

     *Return value:* Returns `SHISA_OK' iff successful,
     `SHISA_NO_REALM' if the indicated realm does not exist,
     `SHISA_NO_PRINCIPAL' if the indicated principal does not exist, or
     an error code.

shisa_principal_update
----------------------

 -- Function: int shisa_principal_update (Shisa * DBH, const char *
          REALM, const char * PRINCIPAL, const Shisa_principal * PH)
     DBH: Shisa library handle created by `shisa()'.

     REALM: Name of realm the principal belongs in.

     PRINCIPAL: Name of principal to get information on.

     PH: Pointer to principal structure with information to store in
     database.

     Modify information stored for given PRINCIPAL`REALM'.  Note that it
     is usually a good idea to only set the fields in `ph' that you
     actually want to update.  Specifically, first calling
     `shisa_principal_find()' to get the current information, then
     modifying one field, and calling `shisa_principal_update()' is not
     recommended in general, as this will 1) overwrite any modifications
     made to other fields between the two calls (by other processes) and
     2) will cause all values to be written again, which may generate
     more overhead.

     *Return value:* Returns SHISA_OK if successful, `SHISA_NO_REALM' if
     the indicated realm does not exist, `SHISA_NO_PRINCIPAL' if the
     indicated principal does not exist, or an error code.

shisa_principal_add
-------------------

 -- Function: int shisa_principal_add (Shisa * DBH, const char * REALM,
          const char * PRINCIPAL, const Shisa_principal * PH, const
          Shisa_key * KEY)
     DBH: Shisa library handle created by `shisa()'.

     REALM: Name of realm the principal belongs in.

     PRINCIPAL: Name of principal to add, may be `NULL' to indicate that
     the `realm' should be created, in which case `ph' and `key' are
     not used.

     PH: Pointer to principal structure with information to store in
     database.

     KEY: Pointer to key structure with information to store in
     database.

     Add given information to database as PRINCIPAL`REALM'.

     *Return value:* Returns SHISA_OK iff successfully added, or an
     error code.

shisa_principal_remove
----------------------

 -- Function: int shisa_principal_remove (Shisa * DBH, const char *
          REALM, const char * PRINCIPAL)
     DBH: Shisa library handle created by `shisa()'.

     REALM: Name of realm the principal belongs in.

     PRINCIPAL: Name of principal to remove, may be `NULL' to indicate
     that the `realm' itself should be removed (requires that the realm
     to be empty).

     Remove all information stored in the database for given
     PRINCIPAL`REALM'.

     *Return value:* Returns `SHISA_OK' if successful, or an error code.

shisa_keys_find
---------------

 -- Function: int shisa_keys_find (Shisa * DBH, const char * REALM,
          const char * PRINCIPAL, const Shisa_key * HINT, Shisa_key ***
          KEYS, size_t * NKEYS)
     DBH: Shisa library handle created by `shisa()'.

     REALM: Name of realm the principal belongs in.

     PRINCIPAL: Name of principal to add key for.

     HINT: Pointer to Shisa key structure with hints on matching the key
     to modify, may be `NULL' to match all keys.

     KEYS: pointer to newly allocated array with Shisa key structures.

     NKEYS: pointer to number of newly allocated Shisa key structures
     in `keys'.

     Iterate through keys for given PRINCIPAL`REALM' and extract any
     keys that match `hint'.  Not all elements of `hint' need to be
     filled out, only use the fields you are interested in.  For
     example, if you want to extract all keys with an etype of 3
     (DES-CBC-MD5), set the `key'->etype field to 3, and set all other
     fields to 0.

     *Return value:* Returns `SHISA_OK' iff successful, or an error
     code.

shisa_key_add
-------------

 -- Function: int shisa_key_add (Shisa * DBH, const char * REALM, const
          char * PRINCIPAL, const Shisa_key * KEY)
     DBH: Shisa library handle created by `shisa()'.

     REALM: Name of realm the principal belongs in.

     PRINCIPAL: Name of principal to add key for.

     KEY: Pointer to Shisa key structure with key to add.

     Add key to database for given PRINCIPAL`REALM'.

     *Return value:* Returns `SHISA_OK' iff successful, or an error
     code.

shisa_key_update
----------------

 -- Function: int shisa_key_update (Shisa * DBH, const char * REALM,
          const char * PRINCIPAL, const Shisa_key * OLDKEY, const
          Shisa_key * NEWKEY)
     DBH: Shisa library handle created by `shisa()'.

     REALM: Name of realm the principal belongs in.

     PRINCIPAL: Name of principal to remove key for.

     OLDKEY: Pointer to Shisa key structure with hints on matching the
     key to modify.

     NEWKEY: Pointer to Shisa key structure with new values for the
     key, note that all fields are used (and not just the ones specified
     by `oldkey').

     Modify data about a key in the database, for the given
     PRINCIPAL`REALM'.  First the `oldkey' is used to locate the key to
     update (similar to `shisa_keys_find()'), then that key is modified
     to contain whatever information is stored in `newkey'.  Not all
     elements of `oldkey' need to be filled out, only enough as to
     identify the key uniquely.  For example, if you want to modify the
     information stored for the only key with an etype of 3
     (DES-CBC-MD5), set the `key'->etype field to 3, and set all other
     fields to 0.

     *Return value:* Returns `SHISA_OK' on success, `SHISA_NO_KEY' if
     no key could be identified, and `SHISA_MULTIPLE_KEY_MATCH' if more
     than one key matched the given criteria, or an error code.

shisa_key_remove
----------------

 -- Function: int shisa_key_remove (Shisa * DBH, const char * REALM,
          const char * PRINCIPAL, const Shisa_key * KEY)
     DBH: Shisa library handle created by `shisa()'.

     REALM: Name of realm the principal belongs in.

     PRINCIPAL: Name of principal to remove key for.

     KEY: Pointer to Shisa key structure with hints on matching the key
     to remove.

     Remove a key, matching the hints in `key', from the Shisa database
     for the user PRINCIPAL`REALM'.  Not all elements of `key' need to
     be filled out, only those you are interested in.  For example, if
     you want to remove the only key with an etype of 3 (DES-CBC-MD5),
     set the `key'->etype field to 3, and set all other fields to 0.

     *Return value:* Returns `SHISA_OK' on success, `SHISA_NO_KEY' if
     no key could be identified, and `SHISA_MULTIPLE_KEY_MATCH' if more
     than one key matched the given criteria, or an error code.

shisa_key_free
--------------

 -- Function: void shisa_key_free (Shisa * DBH, Shisa_key * KEY)
     DBH: Shisa library handle created by `shisa()'.

     KEY: Pointer to Shisa key structure to deallocate.

     Deallocate the fields of a Shisa key structure, and the structure
     itself.

shisa_keys_free
---------------

 -- Function: void shisa_keys_free (Shisa * DBH, Shisa_key ** KEYS,
          size_t NKEYS)
     DBH: Shisa library handle created by `shisa()'.

     KEYS: Pointer to array with `nkeys' elements of keys.

     NKEYS: Number of key elements in `keys' array.

     Deallocate each element of an array with Shisa database keys, using
     `shisa_key_free()'.

   Error handling is similar to that for Shishi in general (*note Error
Handling::), i.e., you invoke `shisa_strerror' on the integer return
value received by some function, if the return value is non-zero.
Below is the complete interface.

shisa_strerror
--------------

 -- Function: const char * shisa_strerror (int ERR)
     ERR: shisa error code

     *Return value:* Returns a pointer to a statically allocated string
     containing a description of the error with the error value `err'.
     This string can be used to output a diagnostic message to the user.

shisa_info
----------

 -- Function: void shisa_info (Shisa * DBH, const char * FORMAT, ...)
     DBH: Shisa library handle created by `shisa()'.

     FORMAT: printf style format string.  ...: print style arguments.

     Print informational message to standard error.


File: shishi.info,  Node: Generic Security Service,  Prev: Kerberos Database Functions,  Up: Programming Manual

5.20 Generic Security Service
=============================

As an alternative to the native Shishi programming API, it is possible
to program Shishi through the Generic Security Services (GSS) API.  The
advantage of using GSS-API in your security application, instead of the
native Shishi API, is that it will be easier to port your application
between different Kerberos 5 implementations, and even beyond Kerberos
5 to different security systems, that support GSS-API.  In the free
software world, however, almost the only widely used security system
that supports GSS-API is Kerberos 5, so the last advantage is somewhat
academic.  But if you are porting applications using GSS-API for other
Kerberos 5 implementations, or want a more mature and stable API than
the native Shishi API, you may find using Shishi's GSS-API interface
compelling.  Note that GSS-API only offer basic services, for more
advanced uses you must use the native API.

   Since the GSS-API is not specific to Shishi, it is distributed
independently from Shishi.  Further information on the GSS project can
be found at `http://www.gnu.org/software/gss/'.


File: shishi.info,  Node: Acknowledgements,  Next: Criticism of Kerberos,  Prev: Programming Manual,  Up: Top

6 Acknowledgements
******************

Shishi uses Libtasn1 by Fabio Fiorina, Libgcrypt and Libgpg-error by
Werner Koch, Libidn by Simon Josefsson, cvs2cl by Karl Fogel, and gdoc
by Michael Zucchi.

   Several GNU packages simplified development considerably, those
packages include Autoconf, Automake, Libtool, Gnulib, Gettext, Indent,
CVS, Texinfo, Help2man and Emacs.

   Several people reported bugs, sent patches or suggested improvements,
see the file THANKS.

   Nicolas Pouvesle wrote the section about the Kerberos rsh/rlogin
protocol.

   This manual borrows text from the Kerberos 5 specification.


File: shishi.info,  Node: Criticism of Kerberos,  Next: Protocol Extensions,  Prev: Acknowledgements,  Up: Top

Appendix A Criticism of Kerberos
********************************

The intention with this section is to discuss various problems with
Kerberos 5, so you can form a conscious decision how to deploy and use
Shishi correctly in your organization.  Currently the issues below are
condensed, and mostly serve as a reminder for the author to elaborate
on them.

   No encryption scheme with security proof.

   No standardized API, and GSS mechanism lack important functionality.

   Lack of authorization system.  (krb5_kuserok())

   Host to realm mapping relies on insecure DNS or static configuration
files.

   Informational model and user database administration.

   Non-formal specification.  Unclear on the etype to use for session
keys (etype in request or database?).  Unclear on how to populate some
"evident" fields (e.g., cname in tickets for AS-REQ, or crealm, cname,
realm, sname, ctime and cusec in KRB-ERROR).  Unclear error code
semantics (e.g., logic for when to use S_PRINCIPAL_UNKNOWN absent).
Some KRB-ERROR fields are required, but can't be usefully populated in
some situations, and no guidance is given on what they should contain.

   RFC 1510/1510bis incompatibilities.  NULL enctype removed without
discussion, and it is still used by some 1964 GSSAPI implementations.
KRB_SAFE text (3.4.1) says the checksum is generated using the session
or sub-session key, which contradicts itself (compare section 3.2.6)
and also RFC 1510, which both allow the application to define the key.
Verification of KRB_SAFE now require the key to be compatible with the
(sub-)session key, in 1510 the only requirement was that it was
collision proof.

   Problems with RFC 1510bis.  Uses bignum INTEGER for TYPED-DATA and
AD-AND-OR.

   Problems with crypto specification.  It uses the word "random" many
times, but there is no discussion on the randomness requirements.
Practical experience indicate it is impossible to use true randomness
for all "random" fields, and no implementation does this.  A post by
Don Davis on the ietf-krb-wg list tried to provide insight, but the
information was never added to the specification.


File: shishi.info,  Node: Protocol Extensions,  Next: Copying Information,  Prev: Criticism of Kerberos,  Up: Top

Appendix B Protocol Extensions
******************************

This appendix specifies the non-standard protocol elements implemented
by Shishi.  By nature of being non-standard, everything described here
is experimental.  Comments and feedback is appreciated.

* Menu:

* STARTTLS protected KDC exchanges::	How Shishi talks to KDC protected by TLS.
* Telnet encryption with AES-CCM::      Integrity and privacy protected telnet.
* Kerberized rsh and rlogin::           Description of KCMD protocol.
* Key as initialization vector::        Some cryptography discussion.
* The Keytab Binary File Format::       Format of keytab files.
* The Credential Cache Binary File Format:: Format of ccache files.


File: shishi.info,  Node: STARTTLS protected KDC exchanges,  Next: Telnet encryption with AES-CCM,  Up: Protocol Extensions

B.1 STARTTLS protected KDC exchanges
====================================

Shishi is able to "upgrade" TCP communications with the KDC to use the
Transport Layer Security (TLS) protocol.  The TLS protocol offers
integrity and privacy protected exchanges.  TLS also offers
authentication using username and passwords, X.509 certificates, or
OpenPGP certificates.  Kerberos 5 claims to offer some of these
features, although it is not as rich as the TLS protocol.  An
inconclusive list of the motivation for using TLS is given below.

   * Server authentication of the KDC to the client.  In traditional
     Kerberos 5, KDC authentication is only proved as a side effect
     that the KDC knows your encryption key (i.e., your password).

   * Client authentication against KDC.  Kerberos 5 assume the user
     knows a key (usually in the form of a password).  Sometimes
     external factors make this hard to fulfill.  In some situations,
     users are equipped with smart cards with a RSA authentication key.
     In others, users have a OpenPGP client on their desktop, with a
     public OpenPGP key known to the server.  In some situations, the
     policy may be that password authentication may only be done
     through SRP.

   * Kerberos exchanges are privacy protected.  Part of many Kerberos
     packets are transfered without privacy protection (i.e.,
     encryption).  That part contains information, such as the client
     principal name, the server principal name, the encryption types
     supported by the client, the lifetime of tickets, etc.  Revealing
     such information is, in some threat models, considered a problem.
     Thus, this enables "anonymity".

   * Prevents downgrade attacks affecting encryption types.  The
     encryption type of the ticket in KDC-REQ are sent in the clear in
     Kerberos 5.  This allows an attacker to replace the encryption type
     with a compromised mechanisms, e.g. 56-bit DES.  Since clients in
     general cannot know the encryption types other servers support, it
     is difficult for the client to detect if there was a
     man-in-the-middle or if the remote server simply did not support a
     stronger mechanism.  Clients may chose to refuse 56-bit DES
     altogether, but in some environments this leads to operational
     difficulties.

   * TLS is well-proved and the protocol is studied by many parties.
     This is an advantage in network design, where TLS is often already
     assumed as part of the solution since it is used to protect HTTP,
     IMAP, SMTP etc.  In some threat models, the designer prefer to
     reduce the number of protocols that can hurt the overall system
     security if they are compromised.


   Other reasons for using TLS exists.

B.1.1 TCP/IP transport with TLS upgrade (STARTTLS)
--------------------------------------------------

RFC 1510bis requires Kerberos servers (KDCs) to accept TCP requests.
Each request and response is prefixed by a 4 octet integer in network
byte order, indicating the length of the packet.  The high bit of the
length was reserved for future expansion, and servers that do not
understand how to interpret a set high bit must return a `KRB-ERROR'
with a `KRB_ERR_FIELD_TOOLONG' and close the TCP stream.

   The TCP/IP transport with TLS upgrade (STARTTLS) uses this reserved
bit as follows.  First we define a new extensible typed hole for
Kerberos 5 messages, because we used the only reserved bit.  It is thus
prudent to offer future extensions on our proposal.  Secondly we
reserve two values in this new typed hole, and described how they are
used to implement STARTTLS.

B.1.2 Extensible typed hole based on reserved high bit
------------------------------------------------------

When the high bit is set, the remaining 31 bits of the 4 octets are
treated as an extensible typed hole, and thus form a 31 bit integer
enumerating various extensions.  Each of the values indicate a specific
extended operation mode, two of which are used and defined here, and
the rest are left for others to use.  If the KDC do not understand a
requested extension, it MUST return a `KRB-ERROR' with a
`KRB_ERR_FIELD_TOOLONG' value (prefixed by the 4 octet length integer,
with the high bit clear, as usual) and close the TCP stream.

   Meaning of the 31 lower bits in the 4 octet field, when the high bit
is set:


 0               RESERVED.
 1               STARTTLS requested by client.
 2               STARTTLS request accepted by server.
 3...2147483647  AVAILABLE for registration (via bug-shishi@josefsson.org).
 2147483648      RESERVED.

B.1.3 STARTTLS requested by client (extension mode 1)
-----------------------------------------------------

When this is sent by the client, the client is requesting the server to
start TLS negotiation on the TCP stream.  The client MUST NOT start TLS
negotiation immediately.  Instead, the client wait for either a
KRB-ERROR (sent normally, prefixed by a 4 octet length integer)
indicating the server do not understand the set high bit, or 4 octet
which is to interpreted as an integer in network byte order, where the
high bit is set and the remaining 31 bit are interpreted as an integer
specifying the "STARTTLS request accepted by server".  In the first
case, the client infer that the server do not understand (or wish to
support) STARTTLS, and can re-try using normal TCP, if unprotected
Kerberos 5 exchanges are acceptable to the client policy.  In the
latter case, it should invoke TLS negotiation on the stream.  If any
other data is received, the client MUST close the TCP stream.

B.1.4 STARTTLS request accepted by server (extension mode 2)
------------------------------------------------------------

This 4 octet message should be sent by the server when it has received
the previous 4 octet message.  The message is an acknowledgment of the
client's request to initiate STARTTLS on the channel.  The server MUST
then invoke a TLS negotiation.

B.1.5 Proceeding after successful TLS negotiation
-------------------------------------------------

If the TLS negotiation ended successfully, possibly also considering
client or server policies, the exchange within the TLS protected stream
is performed like normal UDP Kerberos 5 exchanges, i.e., there is no
TCP 4 octet length field before each packet.  Instead each Kerberos
packet MUST be sent within one TLS record, so the application can use
the TLS record length as the Kerberos 5 packet length.

B.1.6 Proceeding after failed TLS negotiation
---------------------------------------------

If the TLS negotiation fails, possibly due to client or server policy
(e.g., inadequate support of encryption types in TLS, or lack of client
or server authentication) the entity that detect the failure MUST
disconnected the connection.  It is expected that any error messages
that explain the error condition is transfered by TLS.

B.1.7 Interaction with KDC addresses in DNS
-------------------------------------------

Administrators for a KDC may announce the KDC address by placing SRV
records in DNS for the realm, as described in
`draft-ietf-krb-wg-krb-dns-locate-03.txt'.  That document mention TLS,
but do not reference any work that describe how KDCs uses TLS.  Until
further clarified, consider the TLS field in that document to refer to
implementation supporting this STARTTLS protocol.

B.1.8 Using TLS authentication logic in Kerberos
------------------------------------------------

The server MAY consider the authentication performed by the TLS
exchange as sufficient to issue Kerberos 5 tickets to the client,
without requiring, e.g., pre-authentication.  However, it is not an
error to require or use pre-authentication as well.

   The client may also indicate that it wishes to use TLS both for
authentication and data protection by using the `NULL' encryption type
in its request.  The server can decide from its local policy whether or
not issuing tickets based solely on TLS authentication, and whether
`NULL' encryption within TLS, is acceptable or not.  This mode is
currently under investigation.

B.1.9 Security considerations
-----------------------------

Because the initial token is not protected, it is possible for an
active attacker to make it appear to the client that the server do not
support this extension.  It is up to client configuration to disallow
non-TLS connections, if this vulnerability is deemed unacceptable.  For
interoperability, we suggest the default behaviour should be to allow
automatic fallback to TCP or UDP.

   The security considerations of both TLS and Kerberos 5 are inherited.
Using TLS for authentication and/or data protection together with
Kerberos alter the authentication logic fundamentally.  Thus, it may be
that even if the TLS and Kerberos 5 protocols and implementations were
secure, the combination of TLS and Kerberos 5 described here could be
insecure.

   No channel bindings are provided in the Kerberos messages.  It is an
open question whether, and how, this should be fixed.


File: shishi.info,  Node: Telnet encryption with AES-CCM,  Next: Kerberized rsh and rlogin,  Prev: STARTTLS protected KDC exchanges,  Up: Protocol Extensions

B.2 Telnet encryption with AES-CCM
==================================

This appendix describe how Shishi use the Advanced Encryption Standard
(AES) encryption algorithm in Counter with CBC-MAC mode (RFC 3610) with
the telnet encryption option (RFC 2946).

B.2.1 Command Names and Codes
-----------------------------


Encryption Type

      AES_CCM             12

Suboption Commands

      AES_CCM_INFO         1
      AES_CCM_INFO_OK      2
      AES_CCM_INFO_BAD     3

B.2.2 Command Meanings
----------------------


   IAC SB ENCRYPT IS AES_CCM AES_CCM_INFO <M> <L> <nonce> IAC SE

The sender of this command select desired M and L parameters, and
nonce, as described in RFC 3610, and sends it to the other side of the
connection.  The parameters and the nonce are sent in clear text.  Only
the side of the connection that is WILL ENCRYPT may send the
AES_CCM_INFO command.


   IAC SB ENCRYPT REPLY AES_CCM AES_CCM_INFO_BAD IAC SE

   The sender of this command reject the parameters received in the
AES_CCM_INFO command.  Only the side of the connection that is DO
ENCRYPT may send the AES_CCM_INFO_BAD command.  The command MUST be
sent if the nonce field length does not match the selected value for L.
The command MAY be sent if the receiver do not accept the parameters
for reason such as policy.  No capability is provided to negotiate
these parameters.


   IAC SB ENCRYPT REPLY AES_CCM AES_CCM_INFO_OK IAC SE

   The sender of this command accepts the parameters received in the
AES_CCM_INFO command.  Only the side of the connection that is DO
ENCRYPT may send the AES_CCM_INFO_BAD command.  The command MUST NOT be
sent if the nonce field length does not match the selected value for L.

B.2.3 Implementation Rules
--------------------------

Once a AES_CCM_INFO_OK command has been received, the WILL ENCRYPT side
of the connection should do keyid negotiation using the ENC_KEYID
command.  Once the keyid negotiation has successfully identified a
common keyid, then START and END commands may be sent by the side of
the connection that is WILL ENCRYPT.  Data will be encrypted using the
AES-CCM algorithm, with the negotiated nonce and parameters M and L.
After each successful encryption and decryption, the nonce is treated
as an integer in network byte order, and incremented by one.

   If encryption (decryption) is turned off and back on again, and the
same keyid is used when re-starting the encryption (decryption), the
intervening clear text must not change the state of the encryption
(decryption) machine.  In particular, the AES-CCM nonce must not be
re-set.

   If a START command is sent (received) with a different keyid, the
encryption (decryption) machine must be re-initialized immediately
following the end of the START command with the new key and the
parameters sent (received) in the last AES_CCM_INFO command.

   If a new AES_CCM_INFO command is sent (received), and encryption
(decryption) is enabled, the encryption (decryption) machine must be
re-initialized immediately following the end of the AES_CCM_INFO
command with the new nonce and parameters, and the keyid sent
(received) in the last START command.

   If encryption (decryption) is not enabled when a AES_CCM_INFO command
is sent (received), the encryption (decryption) machine must be re-
initialized after the next START command, with the keyid sent
(received) in that START command, and the nonce and parameters sent
(received) in this AES_CCM_INFO command.

   At all times MUST each end make sure that a AES-CCM nonce is not used
twice under the same encryption key.  The rules above help accomplish
this in an interoperable way.

B.2.4 Integration with the AUTHENTICATION telnet option
-------------------------------------------------------

<<This section is slightly complicated.  Can't we simplify this?>>

   As noted in the telnet ENCRYPTION option specifications, a keyid
value of zero indicates the default encryption key, as might be derived
from the telnet AUTHENTICATION option.  If the default encryption key
negotiated as a result of the telnet AUTHENTICATION option contains
less than 32 bytes (corresponding to two 128 bit keys), then the
AES_CCM option MUST NOT be offered or used as a valid telnet encryption
option.  Furthermore, depending on policy for key lengths, the AES_CCM
option MAY be disabled if the default encryption key contain less than
48 bytes (for two 192 bit keys), or less than 64 bytes (for two 256 bit
keys), as well.

   The available encrypt key data is divided on two halves, where the
first half is used to encrypt data sent from the server (decrypt data
received by the client), and the second half is used to encrypt data
sent from the client (decrypt data received by the server).

   Note that the above algorithm assumes that the AUTHENTICATION
mechanism generate keying material suitable for AES-CCM as used in this
specification.  This is not necessarily true in general, but we specify
this behaviour as the default since it is true for most authentication
systems in popular use today.  New telnet AUTHENTICATION mechanisms may
specify alternative methods for determining the keys to be used for
this cipher suite in their specification, if the session key negotiated
by that authentication mechanism is not a DES key and where this
algorithm may not be safely used.

   Kerberos 5 authentication clarification: The key used to encrypt data
from the client to the server is taken from the sub-session key in the
AP-REQ.  The key used to decrypt data from the server to the client is
taken from the sub-session key in the AP-REP.  If mutual authentication
is not negotiated, the key used to encrypt data from the client to the
server is taken from the session key in the ticket, and the key used to
decrypt data from the server to the client is taken from the
sub-session key in the AP-REQ.  Leaving the AP-REQ sub-key field empty
MUST disable the AES_CCM option.

B.2.5 Security Considerations
-----------------------------

The protocol must be properly and securely implemented.  For example,
an implementation should not be vulnerable to various
implementation-specific attacks such as buffer overflows or
side-channel analysis.

   We wish to repeat the suggestion from RFC 2946, to investigate in a
STARTTLS approach for Telnet encryption (and also authentication), when
the security level provided by this specification is not adequate.

B.2.5.1 Telnet Encryption Protocol Security Considerations
..........................................................

The security consideration of the Telnet encryption protocol are
inherited.

   It should be noted that the it is up to the authentication protocol
used, if any, to bind the authenticity of the peers to a specific
session.

   The Telnet encryption protocol does not, in general, protect against
possibly malicious downgrading to any mutually acceptable, but not
preferred, encryption type.  This places a requirement on each peer to
only accept encryption types it trust fully.  In other words, the
Telnet encryption protocol do not guarantee that the strongest mutually
acceptable encryption type is always selected.

B.2.5.2 AES-CCM Security Considerations
.......................................

The integrity and privacy claims are inherited from AES-CCM.  In
particular, the implementation must make sure a nonce is not used more
than once together with the same key.

   Furthermore, the encryption key is assumed to be random, i.e., it
should not be possible to guess it with probability of success higher
than guessing any uniformly selected random key.  RFC 1750 gives an
overview of issues and recommendations related to randomness.

B.2.6 Acknowledgments
---------------------

This document is based on the various Telnet Encryption RFCs (RFC 2946,
RFC 2947, RFC 2948, RFC 2952 and RFC 2953).


File: shishi.info,  Node: Kerberized rsh and rlogin,  Next: Key as initialization vector,  Prev: Telnet encryption with AES-CCM,  Up: Protocol Extensions

B.3 Kerberized rsh and rlogin
=============================

This appendix describe the KCMDV0.2 protocol used in shishi patched
version of inetutils. The KCMD protocol was developped by the MIT
Kerberos team for kerberized rsh an rlogin programs. Differences
between rlogin an rsh will be explained, like those between v0.1 and
v0.2 of the protocol for compatibility reasons.  It is possible that
some parts of this document are not in conformity with original KCMD
protocol because there is no official specification about it. However,
it seems that shishi implementation is compatible with MIT's one.

   *Warning:* If you are seriously considering using Kerberos rsh or
rlogin, instead of more robust remote access protocols such as SSH, you
may first want to explore
`http://www.cs.berkeley.edu/~hildrum/kerberos/' and the full paper at
`http://www.cs.berkeley.edu/~hildrum/043.pdf'.

B.3.1 Establish connection
--------------------------

First the client should establish a TCP connection with the server.
Default ports are 543 (klogin), 544 (kshell), 2105 (eklogin).  eklogin
is the same as klogin but with encryption. Their is no longer ekshell
port because encrypted and normal connection use the same port (kshell).
Kshell need a second connection for stderr. The client should send a
null terminated string that represent the port of this second
connection.  Klogin and eklogin does not use a second connection for
stderr so the client must send a null byte to the server.  Contrary to
classic rsh/rlogin, server must not check if the client port is in the
range 0-1023.

B.3.2 Kerberos identification
-----------------------------

When connections are established, first thing to do is to indicate
kerberos authentication must be used.  So the client will send a string
to indicate it will used kerberos 5. It will call a length-string
"strl" the couple (lenght of the string strl, null terminated string
strl). Length of the string is an int32 (32bits int) in MSB order (for
the network).  So the client send this length-string strl :


   KRB5_SENDAUTH_V1.0

   After that the client must indicate which version of the protocol it
will used by sending this length-string strl :


   KCMDV0.2

   It can be V0.1 for older versions.  If indentification from client
is good, server will send a null byte (0x00). Else if authentication
message is wrong, server send byte 0x01, else if protocol version
message is wrong server send byte 0x02.

B.3.3 Kerberos authentication
-----------------------------

When client is indentified, kerberos authentication can begin. The
client must send an AP-REQ to the server. AP-REQ authenticator must
have a subkey (only for KCMDV0.2) and a checksum.  Authenticator
checksum is created on following string :

     "serverport:""terminaltype""remoteusername"

   for example :

     543:linux/38400user

   remoteusername corresponds to the identity of the client on remote
machine.

   AP-REQ is sended in der encoded format. The length (int32) of der
encoded AP-REQ is sended in network format (MSB), following by the der
encoded AP-REQ.  If all is correct, server send a null int32 (MSB
format but like it is null it is not important).  KCMD protocol use
mutual authentication, so server must now send and AP-REP : (in32
lenght in MSB of der encoded AP-REP)(der encoded AP-REP).

   Now server and client are partially authenticated.

B.3.4 Extended authentication
-----------------------------

Client must now send 3 different null terminated strings (without
lenght) :

   * remote user name (user identity on remote machine)

   * terminal type for rlogin or command for rsh

   * local user name (user identity on client machine)

   example for rsh :

     "rname\0"
     "cat /usr/local/etc/shishi.conf"
     "lname\0"

   Server must verify that checksum in AP-REQ authenticator is correct
by computing a new hash like client has done.

   Server must verify that principal (in AP-REQ) has right to log in on
the remote user account.  For the moment shishi only check if remote
user name is equal to principal. A more complex authorization code is
planned.  Look at the end to know how MIT/Heimdal do to check
authorization.

   If all is correct server send a null byte, else an error message
string (null terminated string) is sent. User read the first byte. If
it is equal to zero, authentication is correct and is logged on the
remote host. Else user can read the error messsage send by the server.

B.3.5 Window size
-----------------

For rlogin protocol, when authentication is complete, the server can
optionnaly send a message to ask for window terminal size of user. Then
the user can respond but it is not an obligation.

   In KCMDV0.1 server send an urgent TCP message (MSG_OOB) with one byte
:

     TIOCPKT_WINDOW = 0x80

   In KCMDV0.2 server does not send an urgent message but write on the
socket 5 bytes :

     '\377', '\377', 'o', 'o', TIOCPKT_WINDOW

   If encryption is enabled (eklogin) server must send this 5 bytes
encrypted.

   Client can answer in both protocol version with :

     '\377', '\377', 's', 's', "struct winsize"

   The winsize structure is filled with corresponding setting to
client's terminal.  If encryption is enabled this answer must be send
encrypted.

B.3.6 End of authentication
---------------------------

The "classic" rsh/rlogin can be used now.

B.3.7 Encryption
----------------

Encryption mode is used when a connection with eklogin is established.
Encryption with krsh can be used too. Before, there was a specific port
for that (ekshell), but now to indicate that encryption must be used
with krsh, client must add "-x " before the command when it send it
between remote user name and local user name.  When the client compute
the checksum for AP-REQ authenticator the "- x" must not be included.

   Encryption in KCMDV0.2 is not the same as in KCMDV0.1.  KCMDV0.1
uses ticket session key as encryption key, and use standard Kerberos
encryption functions. This protocol only supports des-cbc-crc,
des-cbc-md4, des-cbc-md5 and does not use initialisation vectors.

   For example on each encryption/decryption calls, the following
prototype kerberos function should be used :

     kerberos_encrypt (key, keyusage, in, out)  (or decrypt)

   KCMDV0.2 can be used with all kerberos encryption modes (des, 3des,
aes, arcfour) and use AP-REQ authenticator subkey. In opposite to
KCMDV0.1 initialisation vectors are used. All encryptions/descryptions
must be made using a cryptographic context (for example to use the
updated iv, or sbox) :

     kerberos_init(ctx, iv, key, keyusage)
     kerberos_encrypt (ctx, in, out)

   For both protocols, keyusage id for des-cbc-md5, des-cbc-md4,
des-cbc-crc and des3-cbc-sha1 (for KCMDV0.2) :

     keyusage = 1026

   For other KCMDV0.2 modes keyusage is different for each
encryption/decryption usage.  To understand, eklogin use 1 socket. It
encrypts data (output 1) to send and decrypts (input 1) received data.
Kshell use 2 sockets (1 for transmit data, 1 for stderr). So there are
four modes :


   transmit  : input  1
	       output 1

   stderr    : input  2
	       output 2

   There is a keyusage for each modes. The keyusage must correspond on
client and server side. For example in klogin client input 1 keyusage
will be server output 1 keyusage.

I/O         Client      Server
intput 1    1028        1030
output 1    1030        1028
intput 2    1032        1034
output 2    1034        1032

   Those keyusages must be used with AES and ARCFOUR modes.

   KCMDV0.2 uses IV (initialisation vector). Like for keyusage, client
IV must correspond to server IV. IV size is equal to key type,
blocksize. All bytes of IV must be initialised to :

I/O         Client      Server
intput 1    0           1
output 1    1           0
intput 2    2           3
output 2    3           2

   ARCFOUR mode does not use IV. However, like it is said before, a
context must be used to keep the updated sbox.

   Normal message with klogin and kshell are sent like that :

     (int 32 lenght of message in MSB order)
     (message)

   In encrypted mode it is a bit different :

     (int 32 length of unencrypted message in MSB order)
     (encrypted message)

   In KCMDV0.2 encrypted message is create like that :

     encrypt (
     (int 32 length of message in MSB order)
     (message)
     )

   A check on message size can be made in second version of the
protocol.

B.3.8 KCMDV0.3
--------------

This part only gives possible ways to extend KCMD protocol. Does not
take that as must have in KCMD implementation.

   Extensions of KCMV0.2 could be made. For example kshell supposes
there are no files with name "-x *". I think the same thing can be
supposed with terminal name for klogin. So client could add "-x " to
terminal type it sends to server to indicate it will use encryption.
Like that there will be only one port for klogin/eklogin : 543.

   In encrypted mode kshell send command in clear on the network, this
could be considered as insecure as user have decided to use encryption.
This is not really a problem for klogin because it just sends terminal
type.

   In encrypted mode, klogin and kshell clients could only send "-x" as
command or terminal type.  After that encryption is activated, and the
client could send terminal type or command encrypted.  The server will
send the null byte to say that all is correct, or error message in
encrypted form.

B.3.9 MIT/Heimdal authorization
-------------------------------

This part describes how MIT/Heimdal version check authorization of the
user to log in on the remote machine.

   Authorization check is made by looking if the file .k5login exists on
the account of the remote user.  If this file does not exist, remote
user name must be the same as principal in AP-REQ to valid
authorization.  Else if this file exists, check first verify that
remote user or root are the owner of .k5login.  If it is not the case,
the check fails.  If it is good, check reads each line of that file and
compare each readed name to principal.  If principal is found in
.k5login, authorization is valid, else user is not allowed to connect
on remote host with the specified remote user name (that can be the
same as principal).

   So someone (for example user "user1") can remote log into "user2"
account if .k5login is present in user2 home dir and this file is owned
by user2 or root and user1 name is present in this file.


File: shishi.info,  Node: Key as initialization vector,  Next: The Keytab Binary File Format,  Prev: Kerberized rsh and rlogin,  Up: Protocol Extensions

B.4 Key as initialization vector
================================

The `des-cbc-crc' algorithm (*note Cryptographic Overview::) uses the
DES key as the initialization vector.  This is problematic in general
(see below(1)), but may be mitigated in Kerberos by the CRC checksum
that is also included.


From daw@espresso.CS.Berkeley.EDU Fri Mar  1 13:32:34 PST 1996
Article: 50440 of sci.crypt
Path: agate!daw
From: daw@espresso.CS.Berkeley.EDU (David A Wagner)
Newsgroups: sci.crypt
Subject: Re: DES-CBC and Initialization Vectors
Date: 29 Feb 1996 21:48:16 GMT
Organization: University of California, Berkeley
Lines: 31
Message-ID: <4h56v0$3no@agate.berkeley.edu>
References: <4h39li$33o@gaia.ns.utk.edu>
NNTP-Posting-Host: espresso.cs.berkeley.edu

In article <4h39li$33o@gaia.ns.utk.edu>,
Nair Venugopal <venu@mars.utcc.utk.edu> wrote:
> Is there anything wrong in using the key as the I.V. in DES-CBC mode?

Yes, you're open to a chosen-ciphertext attack which recovers the key.

Alice is sending stuff DES-CBC encrypted with key K to Bob.  Mary is an
active adversary in the middle.  Suppose Alice encrypts some plaintext
blocks P_1, P_2, P_3, ... in DES-CBC mode with K as the IV, and sends off
the resulting ciphertext
	A->B: C_1, C_2, C_3, ...
where each C_j is a 8-byte DES ciphertext block.  Mary wants to discover
the key K, but doesn't even know any of the P_j's.  She replaces the above
message by
	M->B: C_1, 0, C_1
where 0 is the 8-byte all-zeros block.  Bob will decrypt under DES-CBC,
recovering the blocks
	Q_1, Q_2, Q_3
where
	Q_1 = DES-decrypt(K, C_1) xor K = P_1
	Q_2 = DES-decrypt(K, C_2) xor C_1 = (some unimportant junk)
	Q_3 = DES-decrypt(K, C_1) xor 0 = P_1 xor K
Bob gets this garbage-looking message Q_1,Q_2,Q_3 which Mary recovers
(under the chosen-ciphertext assumption: this is like a known-plaintext
attack, which isn't too implausible).  Notice that Mary can recover K by
	K = Q_1 xor Q_3;
so after this one simple active attack, Mary gets the key back!

So, if you must use a fixed IV, don't use the key-- use 0 or something
like that.  Even better, don't use a fixed IV-- use the DES encryption
of a counter, or something like that.

   ---------- Footnotes ----------

   (1) The post is copyrighted by David Wagner, included here with
permission, the canonical location is
`http://www.cs.berkeley.edu/~daw/my-posts/key-as-iv-broken'


File: shishi.info,  Node: The Keytab Binary File Format,  Next: The Credential Cache Binary File Format,  Prev: Key as initialization vector,  Up: Protocol Extensions

B.5 The Keytab Binary File Format
=================================

The keytab file format is described in the file `keytab.txt', included
in verbatim below.

The Kerberos Keytab Binary File Format
Copyright (C) 2006 Michael B Allen <mba2000 ioplex.com>
http://www.ioplex.com/utilities/keytab.txt
Last updated: Fri May  5 13:39:40 EDT 2006

The MIT keytab binary format is not a standard format, nor is it
documented anywhere in detail. The format has evolved and may continue
to. It is however understood by several Kerberos implementations including
Heimdal and of course MIT and keytab files are created by the ktpass.exe
utility from Windows. So it has established itself as the defacto format
for storing Kerberos keys.

The following C-like structure definitions illustrate the MIT keytab
file format. All values are in network byte order. All text is ASCII.

  keytab {
      uint16_t file_format_version;                    /* 0x502 */
      keytab_entry entries[*];
  };

  keytab_entry {
      int32_t size;
      uint16_t num_components;    /* sub 1 if version 0x501 */
      counted_octet_string realm;
      counted_octet_string components[num_components];
      uint32_t name_type;   /* not present if version 0x501 */
      uint32_t timestamp;
      uint8_t vno8;
      keyblock key;
      uint32_t vno; /* only present if >= 4 bytes left in entry */
  };

  counted_octet_string {
      uint16_t length;
      uint8_t data[length];
  };

  keyblock {
      uint16_t type;
      counted_octet_string;
  };

The keytab file format begins with the 16 bit file_format_version which
at the time this document was authored is 0x502. The format of older
keytabs is described at the end of this document.

The file_format_version is immediately followed by an array of
keytab_entry structures which are prefixed with a 32 bit size indicating
the number of bytes that follow in the entry. Note that the size should be
evaluated as signed. This is because a negative value indicates that the
entry is in fact empty (e.g. it has been deleted) and that the negative
value of that negative value (which is of course a positive value) is
the offset to the next keytab_entry. Based on these size values alone
the entire keytab file can be traversed.

The size is followed by a 16 bit num_components field indicating the
number of counted_octet_string components in the components array.

The num_components field is followed by a counted_octet_string
representing the realm of the principal.

A counted_octet_string is simply an array of bytes prefixed with a 16
bit length. For the realm and name components, the counted_octet_string
bytes are ASCII encoded text with no zero terminator.

Following the realm is the components array that represents the name of
the principal. The text of these components may be joined with slashs
to construct the typical SPN representation. For example, the service
principal HTTP/www.foo.net@FOO.NET would consist of name components
"HTTP" followed by "www.foo.net".

Following the components array is the 32 bit name_type (e.g. 1 is
KRB5_NT_PRINCIPAL, 2 is KRB5_NT_SRV_INST, 5 is KRB5_NT_UID, etc). In
practice the name_type is almost certainly 1 meaning KRB5_NT_PRINCIPAL.

The 32 bit timestamp indicates the time the key was established for that
principal. The value represents the number of seconds since Jan 1, 1970.

The 8 bit vno8 field is the version number of the key. This value is
overridden by the 32 bit vno field if it is present.

The keyblock structure consists of a 16 bit value indicating the keytype
(e.g. 3 is des-cbc-md5, 23 is arcfour-hmac-md5, 16 is des3-cbc-sha1,
etc). This is followed by a counted_octet_string containing the key.

The last field of the keytab_entry structure is optional. If the size of
the keytab_entry indicates that there are at least 4 bytes remaining,
a 32 bit value representing the key version number is present. This
value supersedes the 8 bit vno8 value preceeding the keyblock.

Older keytabs with a file_format_version of 0x501 are different in
three ways:

  1) All integers are in host byte order [1].
  2) The num_components field is 1 too large (i.e. after decoding,
     decrement by 1).
  3) The 32 bit name_type field is not present.

[1] The file_format_version field should really be treated as two
    separate 8 bit quantities representing the major and minor version
    number respectively.

Permission to copy, modify, and distribute this document, with or
without modification, for any purpose and without fee or royalty is
hereby granted, provided that you include this copyright notice in ALL
copies of the document or portions thereof, including modifications.


File: shishi.info,  Node: The Credential Cache Binary File Format,  Prev: The Keytab Binary File Format,  Up: Protocol Extensions

B.6 The Credential Cache Binary File Format
===========================================

The credential cache file format is described in the file `keytab.txt',
included in verbatim below.

The Kerberos Credential Cache Binary File Format
Copyright (C) 2006-2013 Simon Josefsson <simon josefsson.org>
http://josefsson.org/shishi/ccache.txt
Last updated: Sat Sep 23 12:04:11 CEST 2006

Like the MIT keytab binary format (see Michael B Allen's reverse
engineered description in keytab.txt), the credential cache format is
not standard nor documented anywhere.

In C style notation, the MIT credential cache file format is as
follows.  All values are in network byte order.  All text is ASCII.

ccache {
          uint16_t file_format_version; /* 0x0504 */
          uint16_t headerlen;           /* only if version is 0x0504 */
          header headers[];             /* only if version is 0x0504 */
          principal primary_principal;
          credential credentials[*];
};

header {
       uint16_t tag;                    /* 1 = DeltaTime */
       uint16_t taglen;
       uint8_t tagdata[taglen]
};

The ccache.taglen and ccache.tags fields are only present in 0x0504
versions, not in earlier.  Both MIT and Heimdal appear to correctly
ignore unknown tags, so it appears safe to add them (although there is
no central place to "register" tags).

Currently only one tag is widely implemented, DeltaTime (0x0001).  Its
taglen is always 8, and tagdata will contain:

DeltaTime {
       uint32_t time_offset;
       uint32_t usec_offset;
};

After reading the file_format_version, header tags, and default
principal, a list of credentials follow.  You deduce from the file
length when there are no more credentials.

credential {
           principal client;
           principal server;
           keyblock key;
           times    time;
           uint8_t  is_skey;            /* 1 if skey, 0 otherwise */
           uint32_t tktflags;           /* stored in reversed byte order */
           uint32_t num_address;
           address  addrs[num_address];
           uint32_t num_authdata;
           authdata authdata[num_authdata];
           countet_octet_string ticket;
           countet_octet_string second_ticket;
};

keyblock {
         uint16_t keytype;
         uint16_t etype;                /* only present if version 0x0503 */
         uint16_t keylen;
         uint8_t keyvalue[keylen];
};

times {
      uint32_t  authtime;
      uint32_t  starttime;
      uint32_t  endtime;
      uint32_t  renew_till;
};

address {
        uint16_t addrtype;
        counted_octet_string addrdata;
};

authdata {
         uint16_t authtype;
         counted_octet_string authdata;
};

principal {
          uint32_t name_type;           /* not present if version 0x0501 */
          uint32_t num_components;      /* sub 1 if version 0x501 */
          counted_octet_string realm;
          counted_octet_string components[num_components];
};

counted_octet_string {
    uint32_t length;
    uint8_t data[length];
};

Permission to copy, modify, and distribute this document, with or
without modification, for any purpose and without fee or royalty is
hereby granted, provided that you include this copyright notice in ALL
copies of the document or portions thereof, including modifications.


File: shishi.info,  Node: Copying Information,  Next: Function and Data Index,  Prev: Protocol Extensions,  Up: Top

Appendix C Copying Information
******************************

* Menu:

* GNU Free Documentation License::   License for copying this manual.


File: shishi.info,  Node: GNU Free Documentation License,  Up: Copying Information

C.1 GNU Free Documentation License
==================================

                     Version 1.3, 3 November 2008

     Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
     `http://fsf.org/'

     Everyone is permitted to copy and distribute verbatim copies
     of this license document, but changing it is not allowed.

  0. PREAMBLE

     The purpose of this License is to make a manual, textbook, or other
     functional and useful document "free" in the sense of freedom: to
     assure everyone the effective freedom to copy and redistribute it,
     with or without modifying it, either commercially or
     noncommercially.  Secondarily, this License preserves for the
     author and publisher a way to get credit for their work, while not
     being considered responsible for modifications made by others.

     This License is a kind of "copyleft", which means that derivative
     works of the document must themselves be free in the same sense.
     It complements the GNU General Public License, which is a copyleft
     license designed for free software.

     We have designed this License in order to use it for manuals for
     free software, because free software needs free documentation: a
     free program should come with manuals providing the same freedoms
     that the software does.  But this License is not limited to
     software manuals; it can be used for any textual work, regardless
     of subject matter or whether it is published as a printed book.
     We recommend this License principally for works whose purpose is
     instruction or reference.

  1. APPLICABILITY AND DEFINITIONS

     This License applies to any manual or other work, in any medium,
     that contains a notice placed by the copyright holder saying it
     can be distributed under the terms of this License.  Such a notice
     grants a world-wide, royalty-free license, unlimited in duration,
     to use that work under the conditions stated herein.  The
     "Document", below, refers to any such manual or work.  Any member
     of the public is a licensee, and is addressed as "you".  You
     accept the license if you copy, modify or distribute the work in a
     way requiring permission under copyright law.

     A "Modified Version" of the Document means any work containing the
     Document or a portion of it, either copied verbatim, or with
     modifications and/or translated into another language.

     A "Secondary Section" is a named appendix or a front-matter section
     of the Document that deals exclusively with the relationship of the
     publishers or authors of the Document to the Document's overall
     subject (or to related matters) and contains nothing that could
     fall directly within that overall subject.  (Thus, if the Document
     is in part a textbook of mathematics, a Secondary Section may not
     explain any mathematics.)  The relationship could be a matter of
     historical connection with the subject or with related matters, or
     of legal, commercial, philosophical, ethical or political position
     regarding them.

     The "Invariant Sections" are certain Secondary Sections whose
     titles are designated, as being those of Invariant Sections, in
     the notice that says that the Document is released under this
     License.  If a section does not fit the above definition of
     Secondary then it is not allowed to be designated as Invariant.
     The Document may contain zero Invariant Sections.  If the Document
     does not identify any Invariant Sections then there are none.

     The "Cover Texts" are certain short passages of text that are
     listed, as Front-Cover Texts or Back-Cover Texts, in the notice
     that says that the Document is released under this License.  A
     Front-Cover Text may be at most 5 words, and a Back-Cover Text may
     be at most 25 words.

     A "Transparent" copy of the Document means a machine-readable copy,
     represented in a format whose specification is available to the
     general public, that is suitable for revising the document
     straightforwardly with generic text editors or (for images
     composed of pixels) generic paint programs or (for drawings) some
     widely available drawing editor, and that is suitable for input to
     text formatters or for automatic translation to a variety of
     formats suitable for input to text formatters.  A copy made in an
     otherwise Transparent file format whose markup, or absence of
     markup, has been arranged to thwart or discourage subsequent
     modification by readers is not Transparent.  An image format is
     not Transparent if used for any substantial amount of text.  A
     copy that is not "Transparent" is called "Opaque".

     Examples of suitable formats for Transparent copies include plain
     ASCII without markup, Texinfo input format, LaTeX input format,
     SGML or XML using a publicly available DTD, and
     standard-conforming simple HTML, PostScript or PDF designed for
     human modification.  Examples of transparent image formats include
     PNG, XCF and JPG.  Opaque formats include proprietary formats that
     can be read and edited only by proprietary word processors, SGML or
     XML for which the DTD and/or processing tools are not generally
     available, and the machine-generated HTML, PostScript or PDF
     produced by some word processors for output purposes only.

     The "Title Page" means, for a printed book, the title page itself,
     plus such following pages as are needed to hold, legibly, the
     material this License requires to appear in the title page.  For
     works in formats which do not have any title page as such, "Title
     Page" means the text near the most prominent appearance of the
     work's title, preceding the beginning of the body of the text.

     The "publisher" means any person or entity that distributes copies
     of the Document to the public.

     A section "Entitled XYZ" means a named subunit of the Document
     whose title either is precisely XYZ or contains XYZ in parentheses
     following text that translates XYZ in another language.  (Here XYZ
     stands for a specific section name mentioned below, such as
     "Acknowledgements", "Dedications", "Endorsements", or "History".)
     To "Preserve the Title" of such a section when you modify the
     Document means that it remains a section "Entitled XYZ" according
     to this definition.

     The Document may include Warranty Disclaimers next to the notice
     which states that this License applies to the Document.  These
     Warranty Disclaimers are considered to be included by reference in
     this License, but only as regards disclaiming warranties: any other
     implication that these Warranty Disclaimers may have is void and
     has no effect on the meaning of this License.

  2. VERBATIM COPYING

     You may copy and distribute the Document in any medium, either
     commercially or noncommercially, provided that this License, the
     copyright notices, and the license notice saying this License
     applies to the Document are reproduced in all copies, and that you
     add no other conditions whatsoever to those of this License.  You
     may not use technical measures to obstruct or control the reading
     or further copying of the copies you make or distribute.  However,
     you may accept compensation in exchange for copies.  If you
     distribute a large enough number of copies you must also follow
     the conditions in section 3.

     You may also lend copies, under the same conditions stated above,
     and you may publicly display copies.

  3. COPYING IN QUANTITY

     If you publish printed copies (or copies in media that commonly
     have printed covers) of the Document, numbering more than 100, and
     the Document's license notice requires Cover Texts, you must
     enclose the copies in covers that carry, clearly and legibly, all
     these Cover Texts: Front-Cover Texts on the front cover, and
     Back-Cover Texts on the back cover.  Both covers must also clearly
     and legibly identify you as the publisher of these copies.  The
     front cover must present the full title with all words of the
     title equally prominent and visible.  You may add other material
     on the covers in addition.  Copying with changes limited to the
     covers, as long as they preserve the title of the Document and
     satisfy these conditions, can be treated as verbatim copying in
     other respects.

     If the required texts for either cover are too voluminous to fit
     legibly, you should put the first ones listed (as many as fit
     reasonably) on the actual cover, and continue the rest onto
     adjacent pages.

     If you publish or distribute Opaque copies of the Document
     numbering more than 100, you must either include a
     machine-readable Transparent copy along with each Opaque copy, or
     state in or with each Opaque copy a computer-network location from
     which the general network-using public has access to download
     using public-standard network protocols a complete Transparent
     copy of the Document, free of added material.  If you use the
     latter option, you must take reasonably prudent steps, when you
     begin distribution of Opaque copies in quantity, to ensure that
     this Transparent copy will remain thus accessible at the stated
     location until at least one year after the last time you
     distribute an Opaque copy (directly or through your agents or
     retailers) of that edition to the public.

     It is requested, but not required, that you contact the authors of
     the Document well before redistributing any large number of
     copies, to give them a chance to provide you with an updated
     version of the Document.

  4. MODIFICATIONS

     You may copy and distribute a Modified Version of the Document
     under the conditions of sections 2 and 3 above, provided that you
     release the Modified Version under precisely this License, with
     the Modified Version filling the role of the Document, thus
     licensing distribution and modification of the Modified Version to
     whoever possesses a copy of it.  In addition, you must do these
     things in the Modified Version:

       A. Use in the Title Page (and on the covers, if any) a title
          distinct from that of the Document, and from those of
          previous versions (which should, if there were any, be listed
          in the History section of the Document).  You may use the
          same title as a previous version if the original publisher of
          that version gives permission.

       B. List on the Title Page, as authors, one or more persons or
          entities responsible for authorship of the modifications in
          the Modified Version, together with at least five of the
          principal authors of the Document (all of its principal
          authors, if it has fewer than five), unless they release you
          from this requirement.

       C. State on the Title page the name of the publisher of the
          Modified Version, as the publisher.

       D. Preserve all the copyright notices of the Document.

       E. Add an appropriate copyright notice for your modifications
          adjacent to the other copyright notices.

       F. Include, immediately after the copyright notices, a license
          notice giving the public permission to use the Modified
          Version under the terms of this License, in the form shown in
          the Addendum below.

       G. Preserve in that license notice the full lists of Invariant
          Sections and required Cover Texts given in the Document's
          license notice.

       H. Include an unaltered copy of this License.

       I. Preserve the section Entitled "History", Preserve its Title,
          and add to it an item stating at least the title, year, new
          authors, and publisher of the Modified Version as given on
          the Title Page.  If there is no section Entitled "History" in
          the Document, create one stating the title, year, authors,
          and publisher of the Document as given on its Title Page,
          then add an item describing the Modified Version as stated in
          the previous sentence.

       J. Preserve the network location, if any, given in the Document
          for public access to a Transparent copy of the Document, and
          likewise the network locations given in the Document for
          previous versions it was based on.  These may be placed in
          the "History" section.  You may omit a network location for a
          work that was published at least four years before the
          Document itself, or if the original publisher of the version
          it refers to gives permission.

       K. For any section Entitled "Acknowledgements" or "Dedications",
          Preserve the Title of the section, and preserve in the
          section all the substance and tone of each of the contributor
          acknowledgements and/or dedications given therein.

       L. Preserve all the Invariant Sections of the Document,
          unaltered in their text and in their titles.  Section numbers
          or the equivalent are not considered part of the section
          titles.

       M. Delete any section Entitled "Endorsements".  Such a section
          may not be included in the Modified Version.

       N. Do not retitle any existing section to be Entitled
          "Endorsements" or to conflict in title with any Invariant
          Section.

       O. Preserve any Warranty Disclaimers.

     If the Modified Version includes new front-matter sections or
     appendices that qualify as Secondary Sections and contain no
     material copied from the Document, you may at your option
     designate some or all of these sections as invariant.  To do this,
     add their titles to the list of Invariant Sections in the Modified
     Version's license notice.  These titles must be distinct from any
     other section titles.

     You may add a section Entitled "Endorsements", provided it contains
     nothing but endorsements of your Modified Version by various
     parties--for example, statements of peer review or that the text
     has been approved by an organization as the authoritative
     definition of a standard.

     You may add a passage of up to five words as a Front-Cover Text,
     and a passage of up to 25 words as a Back-Cover Text, to the end
     of the list of Cover Texts in the Modified Version.  Only one
     passage of Front-Cover Text and one of Back-Cover Text may be
     added by (or through arrangements made by) any one entity.  If the
     Document already includes a cover text for the same cover,
     previously added by you or by arrangement made by the same entity
     you are acting on behalf of, you may not add another; but you may
     replace the old one, on explicit permission from the previous
     publisher that added the old one.

     The author(s) and publisher(s) of the Document do not by this
     License give permission to use their names for publicity for or to
     assert or imply endorsement of any Modified Version.

  5. COMBINING DOCUMENTS

     You may combine the Document with other documents released under
     this License, under the terms defined in section 4 above for
     modified versions, provided that you include in the combination
     all of the Invariant Sections of all of the original documents,
     unmodified, and list them all as Invariant Sections of your
     combined work in its license notice, and that you preserve all
     their Warranty Disclaimers.

     The combined work need only contain one copy of this License, and
     multiple identical Invariant Sections may be replaced with a single
     copy.  If there are multiple Invariant Sections with the same name
     but different contents, make the title of each such section unique
     by adding at the end of it, in parentheses, the name of the
     original author or publisher of that section if known, or else a
     unique number.  Make the same adjustment to the section titles in
     the list of Invariant Sections in the license notice of the
     combined work.

     In the combination, you must combine any sections Entitled
     "History" in the various original documents, forming one section
     Entitled "History"; likewise combine any sections Entitled
     "Acknowledgements", and any sections Entitled "Dedications".  You
     must delete all sections Entitled "Endorsements."

  6. COLLECTIONS OF DOCUMENTS

     You may make a collection consisting of the Document and other
     documents released under this License, and replace the individual
     copies of this License in the various documents with a single copy
     that is included in the collection, provided that you follow the
     rules of this License for verbatim copying of each of the
     documents in all other respects.

     You may extract a single document from such a collection, and
     distribute it individually under this License, provided you insert
     a copy of this License into the extracted document, and follow
     this License in all other respects regarding verbatim copying of
     that document.

  7. AGGREGATION WITH INDEPENDENT WORKS

     A compilation of the Document or its derivatives with other
     separate and independent documents or works, in or on a volume of
     a storage or distribution medium, is called an "aggregate" if the
     copyright resulting from the compilation is not used to limit the
     legal rights of the compilation's users beyond what the individual
     works permit.  When the Document is included in an aggregate, this
     License does not apply to the other works in the aggregate which
     are not themselves derivative works of the Document.

     If the Cover Text requirement of section 3 is applicable to these
     copies of the Document, then if the Document is less than one half
     of the entire aggregate, the Document's Cover Texts may be placed
     on covers that bracket the Document within the aggregate, or the
     electronic equivalent of covers if the Document is in electronic
     form.  Otherwise they must appear on printed covers that bracket
     the whole aggregate.

  8. TRANSLATION

     Translation is considered a kind of modification, so you may
     distribute translations of the Document under the terms of section
     4.  Replacing Invariant Sections with translations requires special
     permission from their copyright holders, but you may include
     translations of some or all Invariant Sections in addition to the
     original versions of these Invariant Sections.  You may include a
     translation of this License, and all the license notices in the
     Document, and any Warranty Disclaimers, provided that you also
     include the original English version of this License and the
     original versions of those notices and disclaimers.  In case of a
     disagreement between the translation and the original version of
     this License or a notice or disclaimer, the original version will
     prevail.

     If a section in the Document is Entitled "Acknowledgements",
     "Dedications", or "History", the requirement (section 4) to
     Preserve its Title (section 1) will typically require changing the
     actual title.

  9. TERMINATION

     You may not copy, modify, sublicense, or distribute the Document
     except as expressly provided under this License.  Any attempt
     otherwise to copy, modify, sublicense, or distribute it is void,
     and will automatically terminate your rights under this License.

     However, if you cease all violation of this License, then your
     license from a particular copyright holder is reinstated (a)
     provisionally, unless and until the copyright holder explicitly
     and finally terminates your license, and (b) permanently, if the
     copyright holder fails to notify you of the violation by some
     reasonable means prior to 60 days after the cessation.

     Moreover, your license from a particular copyright holder is
     reinstated permanently if the copyright holder notifies you of the
     violation by some reasonable means, this is the first time you have
     received notice of violation of this License (for any work) from
     that copyright holder, and you cure the violation prior to 30 days
     after your receipt of the notice.

     Termination of your rights under this section does not terminate
     the licenses of parties who have received copies or rights from
     you under this License.  If your rights have been terminated and
     not permanently reinstated, receipt of a copy of some or all of
     the same material does not give you any rights to use it.

 10. FUTURE REVISIONS OF THIS LICENSE

     The Free Software Foundation may publish new, revised versions of
     the GNU Free Documentation License from time to time.  Such new
     versions will be similar in spirit to the present version, but may
     differ in detail to address new problems or concerns.  See
     `http://www.gnu.org/copyleft/'.

     Each version of the License is given a distinguishing version
     number.  If the Document specifies that a particular numbered
     version of this License "or any later version" applies to it, you
     have the option of following the terms and conditions either of
     that specified version or of any later version that has been
     published (not as a draft) by the Free Software Foundation.  If
     the Document does not specify a version number of this License,
     you may choose any version ever published (not as a draft) by the
     Free Software Foundation.  If the Document specifies that a proxy
     can decide which future versions of this License can be used, that
     proxy's public statement of acceptance of a version permanently
     authorizes you to choose that version for the Document.

 11. RELICENSING

     "Massive Multiauthor Collaboration Site" (or "MMC Site") means any
     World Wide Web server that publishes copyrightable works and also
     provides prominent facilities for anybody to edit those works.  A
     public wiki that anybody can edit is an example of such a server.
     A "Massive Multiauthor Collaboration" (or "MMC") contained in the
     site means any set of copyrightable works thus published on the MMC
     site.

     "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0
     license published by Creative Commons Corporation, a not-for-profit
     corporation with a principal place of business in San Francisco,
     California, as well as future copyleft versions of that license
     published by that same organization.

     "Incorporate" means to publish or republish a Document, in whole or
     in part, as part of another Document.

     An MMC is "eligible for relicensing" if it is licensed under this
     License, and if all works that were first published under this
     License somewhere other than this MMC, and subsequently
     incorporated in whole or in part into the MMC, (1) had no cover
     texts or invariant sections, and (2) were thus incorporated prior
     to November 1, 2008.

     The operator of an MMC Site may republish an MMC contained in the
     site under CC-BY-SA on the same site at any time before August 1,
     2009, provided the MMC is eligible for relicensing.


ADDENDUM: How to use this License for your documents
====================================================

To use this License in a document you have written, include a copy of
the License in the document and put the following copyright and license
notices just after the title page:

       Copyright (C)  YEAR  YOUR NAME.
       Permission is granted to copy, distribute and/or modify this document
       under the terms of the GNU Free Documentation License, Version 1.3
       or any later version published by the Free Software Foundation;
       with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
       Texts.  A copy of the license is included in the section entitled ``GNU
       Free Documentation License''.

   If you have Invariant Sections, Front-Cover Texts and Back-Cover
Texts, replace the "with...Texts." line with this:

         with the Invariant Sections being LIST THEIR TITLES, with
         the Front-Cover Texts being LIST, and with the Back-Cover Texts
         being LIST.

   If you have Invariant Sections without Cover Texts, or some other
combination of the three, merge those two alternatives to suit the
situation.

   If your document contains nontrivial examples of program code, we
recommend releasing these examples in parallel under your choice of
free software license, such as the GNU General Public License, to
permit their use in free software.


File: shishi.info,  Node: Function and Data Index,  Next: Concept Index,  Prev: Copying Information,  Up: Top

Function and Data Index
***********************

[index]
* Menu:

* ago in date strings:                   Relative items in date strings.
                                                             (line   23)
* am in date strings:                    Time of day items.  (line   22)
* day in date strings:                   Relative items in date strings.
                                                             (line   29)
* first in date strings:                 General date syntax.
                                                             (line   28)
* fortnight in date strings:             Relative items in date strings.
                                                             (line   15)
* hour in date strings:                  Relative items in date strings.
                                                             (line   15)
* last DAY:                              Day of week items.  (line   15)
* last in date strings:                  General date syntax.
                                                             (line   28)
* midnight in date strings:              Time of day items.  (line   22)
* minute in date strings:                Relative items in date strings.
                                                             (line   15)
* month in date strings:                 Relative items in date strings.
                                                             (line   15)
* next DAY:                              Day of week items.  (line   15)
* next in date strings:                  General date syntax.
                                                             (line   28)
* noon in date strings:                  Time of day items.  (line   22)
* now in date strings:                   Relative items in date strings.
                                                             (line   33)
* parse_datetime:                        Date input formats. (line    6)
* pm in date strings:                    Time of day items.  (line   22)
* shisa:                                 Kerberos Database Functions.
                                                             (line   69)
* shisa_cfg:                             Kerberos Database Functions.
                                                             (line  143)
* shisa_cfg_db:                          Kerberos Database Functions.
                                                             (line  126)
* shisa_cfg_default_systemfile:          Kerberos Database Functions.
                                                             (line  167)
* shisa_cfg_from_file:                   Kerberos Database Functions.
                                                             (line  155)
* shisa_done:                            Kerberos Database Functions.
                                                             (line   78)
* shisa_enumerate_principals:            Kerberos Database Functions.
                                                             (line  202)
* shisa_enumerate_realms:                Kerberos Database Functions.
                                                             (line  184)
* shisa_info:                            Kerberos Database Functions.
                                                             (line  457)
* shisa_init:                            Kerberos Database Functions.
                                                             (line   85)
* shisa_init_with_paths:                 Kerberos Database Functions.
                                                             (line  103)
* shisa_key_add:                         Kerberos Database Functions.
                                                             (line  343)
* shisa_key_free:                        Kerberos Database Functions.
                                                             (line  417)
* shisa_key_remove:                      Kerberos Database Functions.
                                                             (line  394)
* shisa_key_update:                      Kerberos Database Functions.
                                                             (line  362)
* shisa_keys_find:                       Kerberos Database Functions.
                                                             (line  314)
* shisa_keys_free:                       Kerberos Database Functions.
                                                             (line  429)
* shisa_principal_add:                   Kerberos Database Functions.
                                                             (line  271)
* shisa_principal_find:                  Kerberos Database Functions.
                                                             (line  221)
* shisa_principal_remove:                Kerberos Database Functions.
                                                             (line  295)
* shisa_principal_update:                Kerberos Database Functions.
                                                             (line  242)
* shisa_strerror:                        Kerberos Database Functions.
                                                             (line  447)
* shishi:                                Initialization Functions.
                                                             (line   10)
* shishi_3des:                           Cryptographic Functions.
                                                             (line 1767)
* shishi_aes_cts:                        Cryptographic Functions.
                                                             (line 1788)
* shishi_ap:                             AP-REQ and AP-REP Functions.
                                                             (line   41)
* shishi_ap_authenticator:               AP-REQ and AP-REP Functions.
                                                             (line  431)
* shishi_ap_authenticator_cksumdata:     AP-REQ and AP-REP Functions.
                                                             (line  352)
* shishi_ap_authenticator_cksumdata_set: AP-REQ and AP-REP Functions.
                                                             (line  372)
* shishi_ap_authenticator_cksumraw_set:  AP-REQ and AP-REP Functions.
                                                             (line  391)
* shishi_ap_authenticator_cksumtype:     AP-REQ and AP-REP Functions.
                                                             (line  410)
* shishi_ap_authenticator_cksumtype_set: AP-REQ and AP-REP Functions.
                                                             (line  421)
* shishi_ap_authenticator_set:           AP-REQ and AP-REP Functions.
                                                             (line  443)
* shishi_ap_done:                        AP-REQ and AP-REP Functions.
                                                             (line   89)
* shishi_ap_encapreppart:                AP-REQ and AP-REP Functions.
                                                             (line  711)
* shishi_ap_encapreppart_set:            AP-REQ and AP-REP Functions.
                                                             (line  723)
* shishi_ap_etype:                       AP-REQ and AP-REP Functions.
                                                             (line   60)
* shishi_ap_etype_tktoptionsdata:        AP-REQ and AP-REP Functions.
                                                             (line  270)
* shishi_ap_key:                         AP-REQ and AP-REP Functions.
                                                             (line  578)
* shishi_ap_nosubkey:                    AP-REQ and AP-REP Functions.
                                                             (line   76)
* shishi_ap_option2string:               AP-REQ and AP-REP Functions.
                                                             (line  734)
* shishi_ap_rep:                         AP-REQ and AP-REP Functions.
                                                             (line  589)
* shishi_ap_rep_asn1:                    AP-REQ and AP-REP Functions.
                                                             (line  655)
* shishi_ap_rep_build:                   AP-REQ and AP-REP Functions.
                                                             (line  643)
* shishi_ap_rep_der:                     AP-REQ and AP-REP Functions.
                                                             (line  611)
* shishi_ap_rep_der_set:                 AP-REQ and AP-REP Functions.
                                                             (line  628)
* shishi_ap_rep_set:                     AP-REQ and AP-REP Functions.
                                                             (line  600)
* shishi_ap_rep_verify:                  AP-REQ and AP-REP Functions.
                                                             (line  667)
* shishi_ap_rep_verify_asn1:             AP-REQ and AP-REP Functions.
                                                             (line  697)
* shishi_ap_rep_verify_der:              AP-REQ and AP-REP Functions.
                                                             (line  679)
* shishi_ap_req:                         AP-REQ and AP-REP Functions.
                                                             (line  453)
* shishi_ap_req_asn1:                    AP-REQ and AP-REP Functions.
                                                             (line  566)
* shishi_ap_req_build:                   AP-REQ and AP-REP Functions.
                                                             (line  508)
* shishi_ap_req_decode:                  AP-REQ and AP-REP Functions.
                                                             (line  519)
* shishi_ap_req_der:                     AP-REQ and AP-REP Functions.
                                                             (line  475)
* shishi_ap_req_der_set:                 AP-REQ and AP-REP Functions.
                                                             (line  493)
* shishi_ap_req_process:                 AP-REQ and AP-REP Functions.
                                                             (line  551)
* shishi_ap_req_process_keyusage:        AP-REQ and AP-REP Functions.
                                                             (line  531)
* shishi_ap_req_set:                     AP-REQ and AP-REP Functions.
                                                             (line  464)
* shishi_ap_set_tktoptions:              AP-REQ and AP-REP Functions.
                                                             (line  100)
* shishi_ap_set_tktoptionsasn1usage:     AP-REQ and AP-REP Functions.
                                                             (line  165)
* shishi_ap_set_tktoptionsdata:          AP-REQ and AP-REP Functions.
                                                             (line  116)
* shishi_ap_set_tktoptionsraw:           AP-REQ and AP-REP Functions.
                                                             (line  138)
* shishi_ap_string2option:               AP-REQ and AP-REP Functions.
                                                             (line  749)
* shishi_ap_tkt:                         AP-REQ and AP-REP Functions.
                                                             (line  330)
* shishi_ap_tkt_set:                     AP-REQ and AP-REP Functions.
                                                             (line  341)
* shishi_ap_tktoptions:                  AP-REQ and AP-REP Functions.
                                                             (line  192)
* shishi_ap_tktoptionsasn1usage:         AP-REQ and AP-REP Functions.
                                                             (line  299)
* shishi_ap_tktoptionsdata:              AP-REQ and AP-REP Functions.
                                                             (line  214)
* shishi_ap_tktoptionsraw:               AP-REQ and AP-REP Functions.
                                                             (line  240)
* shishi_aprep:                          AP-REQ and AP-REP Functions.
                                                             (line 1051)
* shishi_aprep_from_file:                AP-REQ and AP-REP Functions.
                                                             (line 1143)
* shishi_aprep_get_enc_part_etype:       AP-REQ and AP-REP Functions.
                                                             (line 1161)
* shishi_aprep_parse:                    AP-REQ and AP-REP Functions.
                                                             (line 1112)
* shishi_aprep_print:                    AP-REQ and AP-REP Functions.
                                                             (line 1063)
* shishi_aprep_read:                     AP-REQ and AP-REP Functions.
                                                             (line 1128)
* shishi_aprep_save:                     AP-REQ and AP-REP Functions.
                                                             (line 1078)
* shishi_aprep_to_file:                  AP-REQ and AP-REP Functions.
                                                             (line 1093)
* shishi_apreq:                          AP-REQ and AP-REP Functions.
                                                             (line  761)
* shishi_apreq_add_authenticator:        AP-REQ and AP-REP Functions.
                                                             (line  898)
* shishi_apreq_from_file:                AP-REQ and AP-REP Functions.
                                                             (line  853)
* shishi_apreq_get_authenticator_etype:  AP-REQ and AP-REP Functions.
                                                             (line 1022)
* shishi_apreq_get_ticket:               AP-REQ and AP-REP Functions.
                                                             (line 1037)
* shishi_apreq_mutual_required_p:        AP-REQ and AP-REP Functions.
                                                             (line  962)
* shishi_apreq_options:                  AP-REQ and AP-REP Functions.
                                                             (line  934)
* shishi_apreq_options_add:              AP-REQ and AP-REP Functions.
                                                             (line  990)
* shishi_apreq_options_remove:           AP-REQ and AP-REP Functions.
                                                             (line 1006)
* shishi_apreq_options_set:              AP-REQ and AP-REP Functions.
                                                             (line  975)
* shishi_apreq_parse:                    AP-REQ and AP-REP Functions.
                                                             (line  822)
* shishi_apreq_print:                    AP-REQ and AP-REP Functions.
                                                             (line  773)
* shishi_apreq_read:                     AP-REQ and AP-REP Functions.
                                                             (line  838)
* shishi_apreq_save:                     AP-REQ and AP-REP Functions.
                                                             (line  788)
* shishi_apreq_set_authenticator:        AP-REQ and AP-REP Functions.
                                                             (line  872)
* shishi_apreq_set_ticket:               AP-REQ and AP-REP Functions.
                                                             (line  919)
* shishi_apreq_to_file:                  AP-REQ and AP-REP Functions.
                                                             (line  803)
* shishi_apreq_use_session_key_p:        AP-REQ and AP-REP Functions.
                                                             (line  949)
* shishi_arcfour:                        Cryptographic Functions.
                                                             (line 1716)
* shishi_as:                             AS Functions.       (line   82)
* shishi_as_check_cname:                 AS/TGS Functions.   (line  168)
* shishi_as_check_crealm:                AS/TGS Functions.   (line  135)
* shishi_as_derive_salt:                 AS/TGS Functions.   (line   97)
* shishi_as_done:                        AS Functions.       (line   94)
* shishi_as_krberror:                    AS Functions.       (line  249)
* shishi_as_krberror_der:                AS Functions.       (line  261)
* shishi_as_krberror_set:                AS Functions.       (line  277)
* shishi_as_process:                     AS/TGS Functions.   (line  250)
* shishi_as_rep:                         AS Functions.       (line  167)
* shishi_as_rep_build:                   AS Functions.       (line  195)
* shishi_as_rep_der:                     AS Functions.       (line  208)
* shishi_as_rep_der_set:                 AS Functions.       (line  234)
* shishi_as_rep_process:                 AS Functions.       (line  179)
* shishi_as_rep_set:                     AS Functions.       (line  223)
* shishi_as_req:                         AS Functions.       (line  104)
* shishi_as_req_build:                   AS Functions.       (line  115)
* shishi_as_req_der:                     AS Functions.       (line  136)
* shishi_as_req_der_set:                 AS Functions.       (line  152)
* shishi_as_req_set:                     AS Functions.       (line  125)
* shishi_as_sendrecv:                    AS Functions.       (line  325)
* shishi_as_sendrecv_hint:               AS Functions.       (line  309)
* shishi_as_tkt:                         AS Functions.       (line  287)
* shishi_as_tkt_set:                     AS Functions.       (line  298)
* shishi_asn1_aprep:                     ASN.1 Functions.    (line  210)
* shishi_asn1_apreq:                     ASN.1 Functions.    (line  200)
* shishi_asn1_asrep:                     ASN.1 Functions.    (line  170)
* shishi_asn1_asreq:                     ASN.1 Functions.    (line  160)
* shishi_asn1_authenticator:             ASN.1 Functions.    (line  250)
* shishi_asn1_done:                      ASN.1 Functions.    (line   89)
* shishi_asn1_encapreppart:              ASN.1 Functions.    (line  220)
* shishi_asn1_encasreppart:              ASN.1 Functions.    (line  270)
* shishi_asn1_enckdcreppart:             ASN.1 Functions.    (line  260)
* shishi_asn1_encprivpart:               ASN.1 Functions.    (line  310)
* shishi_asn1_encrypteddata:             ASN.1 Functions.    (line  110)
* shishi_asn1_encticketpart:             ASN.1 Functions.    (line  240)
* shishi_asn1_etype_info:                ASN.1 Functions.    (line  140)
* shishi_asn1_etype_info2:               ASN.1 Functions.    (line  150)
* shishi_asn1_krberror:                  ASN.1 Functions.    (line  280)
* shishi_asn1_krbsafe:                   ASN.1 Functions.    (line  290)
* shishi_asn1_methoddata:                ASN.1 Functions.    (line  130)
* shishi_asn1_msgtype:                   ASN.1 Functions.    (line  363)
* shishi_asn1_pa_enc_ts_enc:             ASN.1 Functions.    (line  100)
* shishi_asn1_padata:                    ASN.1 Functions.    (line  120)
* shishi_asn1_print:                     ASN.1 Functions.    (line  755)
* shishi_asn1_priv:                      ASN.1 Functions.    (line  300)
* shishi_asn1_read:                      ASN.1 Functions.    (line   38)
* shishi_asn1_read_inline:               ASN.1 Functions.    (line   11)
* shishi_asn1_read_optional:             ASN.1 Functions.    (line   64)
* shishi_asn1_tgsrep:                    ASN.1 Functions.    (line  190)
* shishi_asn1_tgsreq:                    ASN.1 Functions.    (line  180)
* shishi_asn1_ticket:                    ASN.1 Functions.    (line  230)
* shishi_asn1_to_der:                    ASN.1 Functions.    (line  344)
* shishi_asn1_to_der_field:              ASN.1 Functions.    (line  322)
* shishi_asrep:                          AS/TGS Functions.   (line 1061)
* shishi_asreq:                          AS/TGS Functions.   (line  307)
* shishi_asreq_clientrealm:              AS/TGS Functions.   (line  484)
* shishi_authenticator:                  Authenticator Functions.
                                                             (line   29)
* shishi_authenticator_add_authorizationdata: Authenticator Functions.
                                                             (line  482)
* shishi_authenticator_add_cksum:        Authenticator Functions.
                                                             (line  420)
* shishi_authenticator_add_cksum_type:   Authenticator Functions.
                                                             (line  443)
* shishi_authenticator_add_random_subkey: Authenticator Functions.
                                                             (line  583)
* shishi_authenticator_add_random_subkey_etype: Authenticator Functions.
                                                             (line  598)
* shishi_authenticator_add_subkey:       Authenticator Functions.
                                                             (line  615)
* shishi_authenticator_authorizationdata: Authenticator Functions.
                                                             (line  503)
* shishi_authenticator_cksum:            Authenticator Functions.
                                                             (line  370)
* shishi_authenticator_clear_authorizationdata: Authenticator Functions.
                                                             (line  467)
* shishi_authenticator_client:           Authenticator Functions.
                                                             (line  321)
* shishi_authenticator_client_set:       Authenticator Functions.
                                                             (line  193)
* shishi_authenticator_clientrealm:      Authenticator Functions.
                                                             (line  344)
* shishi_authenticator_ctime:            Authenticator Functions.
                                                             (line  209)
* shishi_authenticator_ctime_set:        Authenticator Functions.
                                                             (line  226)
* shishi_authenticator_cusec_get:        Authenticator Functions.
                                                             (line  242)
* shishi_authenticator_cusec_set:        Authenticator Functions.
                                                             (line  258)
* shishi_authenticator_from_file:        Authenticator Functions.
                                                             (line  139)
* shishi_authenticator_get_subkey:       Authenticator Functions.
                                                             (line  541)
* shishi_authenticator_parse:            Authenticator Functions.
                                                             (line  106)
* shishi_authenticator_print:            Authenticator Functions.
                                                             (line   54)
* shishi_authenticator_read:             Authenticator Functions.
                                                             (line  122)
* shishi_authenticator_remove_subkey:    Authenticator Functions.
                                                             (line  527)
* shishi_authenticator_save:             Authenticator Functions.
                                                             (line   70)
* shishi_authenticator_seqnumber_get:    Authenticator Functions.
                                                             (line  274)
* shishi_authenticator_seqnumber_remove: Authenticator Functions.
                                                             (line  290)
* shishi_authenticator_seqnumber_set:    Authenticator Functions.
                                                             (line  304)
* shishi_authenticator_set_cksum:        Authenticator Functions.
                                                             (line  394)
* shishi_authenticator_set_cname:        Authenticator Functions.
                                                             (line  174)
* shishi_authenticator_set_crealm:       Authenticator Functions.
                                                             (line  157)
* shishi_authenticator_set_subkey:       Authenticator Functions.
                                                             (line  559)
* shishi_authenticator_subkey:           Authenticator Functions.
                                                             (line   41)
* shishi_authenticator_to_file:          Authenticator Functions.
                                                             (line   87)
* shishi_authorization_parse:            Utility Functions.  (line  338)
* shishi_authorize_k5login:              Utility Functions.  (line  321)
* shishi_authorize_strcmp:               Utility Functions.  (line  304)
* shishi_authorized_p:                   Utility Functions.  (line  350)
* shishi_cfg:                            Initialization Functions.
                                                             (line  132)
* shishi_cfg_authorizationtype_set:      Initialization Functions.
                                                             (line  265)
* shishi_cfg_clientkdcetype:             Initialization Functions.
                                                             (line  225)
* shishi_cfg_clientkdcetype_fast:        Initialization Functions.
                                                             (line  238)
* shishi_cfg_clientkdcetype_set:         Initialization Functions.
                                                             (line  249)
* shishi_cfg_default_systemfile:         Initialization Functions.
                                                             (line  170)
* shishi_cfg_default_userdirectory:      Initialization Functions.
                                                             (line  182)
* shishi_cfg_default_userfile:           Initialization Functions.
                                                             (line  213)
* shishi_cfg_from_file:                  Initialization Functions.
                                                             (line  145)
* shishi_cfg_print:                      Initialization Functions.
                                                             (line  157)
* shishi_cfg_userdirectory_file:         Initialization Functions.
                                                             (line  197)
* shishi_check_version:                  Version Check.      (line   17)
* shishi_checksum:                       Cryptographic Functions.
                                                             (line  843)
* shishi_checksum_cksumlen:              Cryptographic Functions.
                                                             (line  767)
* shishi_checksum_name:                  Cryptographic Functions.
                                                             (line  756)
* shishi_checksum_parse:                 Cryptographic Functions.
                                                             (line  778)
* shishi_checksum_supported_p:           Cryptographic Functions.
                                                             (line  746)
* shishi_cipher_blocksize:               Cryptographic Functions.
                                                             (line  679)
* shishi_cipher_confoundersize:          Cryptographic Functions.
                                                             (line  690)
* shishi_cipher_defaultcksumtype:        Cryptographic Functions.
                                                             (line  725)
* shishi_cipher_keylen:                  Cryptographic Functions.
                                                             (line  702)
* shishi_cipher_name:                    Cryptographic Functions.
                                                             (line  668)
* shishi_cipher_parse:                   Cryptographic Functions.
                                                             (line  736)
* shishi_cipher_randomlen:               Cryptographic Functions.
                                                             (line  713)
* shishi_cipher_supported_p:             Cryptographic Functions.
                                                             (line  658)
* shishi_crc:                            Cryptographic Functions.
                                                             (line 1604)
* shishi_crypto:                         Cryptographic Functions.
                                                             (line 1491)
* shishi_crypto_close:                   Cryptographic Functions.
                                                             (line 1571)
* shishi_crypto_decrypt:                 Cryptographic Functions.
                                                             (line 1547)
* shishi_crypto_encrypt:                 Cryptographic Functions.
                                                             (line 1522)
* shishi_ctime:                          Utility Functions.  (line  427)
* shishi_decrypt:                        Cryptographic Functions.
                                                             (line 1377)
* shishi_decrypt_etype:                  Cryptographic Functions.
                                                             (line 1249)
* shishi_decrypt_iv:                     Cryptographic Functions.
                                                             (line 1336)
* shishi_decrypt_iv_etype:               Cryptographic Functions.
                                                             (line 1206)
* shishi_decrypt_ivupdate:               Cryptographic Functions.
                                                             (line 1290)
* shishi_decrypt_ivupdate_etype:         Cryptographic Functions.
                                                             (line 1157)
* shishi_der2asn1:                       ASN.1 Functions.    (line  393)
* shishi_der2asn1_aprep:                 ASN.1 Functions.    (line  709)
* shishi_der2asn1_apreq:                 ASN.1 Functions.    (line  694)
* shishi_der2asn1_asrep:                 ASN.1 Functions.    (line  529)
* shishi_der2asn1_asreq:                 ASN.1 Functions.    (line  499)
* shishi_der2asn1_authenticator:         ASN.1 Functions.    (line  619)
* shishi_der2asn1_encapreppart:          ASN.1 Functions.    (line  724)
* shishi_der2asn1_encasreppart:          ASN.1 Functions.    (line  574)
* shishi_der2asn1_enckdcreppart:         ASN.1 Functions.    (line  604)
* shishi_der2asn1_encprivpart:           ASN.1 Functions.    (line  679)
* shishi_der2asn1_enctgsreppart:         ASN.1 Functions.    (line  589)
* shishi_der2asn1_encticketpart:         ASN.1 Functions.    (line  484)
* shishi_der2asn1_etype_info:            ASN.1 Functions.    (line  439)
* shishi_der2asn1_etype_info2:           ASN.1 Functions.    (line  454)
* shishi_der2asn1_kdcrep:                ASN.1 Functions.    (line  559)
* shishi_der2asn1_kdcreq:                ASN.1 Functions.    (line  739)
* shishi_der2asn1_krberror:              ASN.1 Functions.    (line  634)
* shishi_der2asn1_krbsafe:               ASN.1 Functions.    (line  649)
* shishi_der2asn1_methoddata:            ASN.1 Functions.    (line  424)
* shishi_der2asn1_padata:                ASN.1 Functions.    (line  409)
* shishi_der2asn1_priv:                  ASN.1 Functions.    (line  664)
* shishi_der2asn1_tgsrep:                ASN.1 Functions.    (line  544)
* shishi_der2asn1_tgsreq:                ASN.1 Functions.    (line  514)
* shishi_der2asn1_ticket:                ASN.1 Functions.    (line  469)
* shishi_der_msgtype:                    ASN.1 Functions.    (line  378)
* shishi_derive_default_salt:            Utility Functions.  (line  272)
* shishi_des:                            Cryptographic Functions.
                                                             (line 1746)
* shishi_des_cbc_mac:                    Cryptographic Functions.
                                                             (line 1699)
* shishi_dk:                             Cryptographic Functions.
                                                             (line 1464)
* shishi_done:                           Initialization Functions.
                                                             (line   32)
* shishi_dr:                             Cryptographic Functions.
                                                             (line 1440)
* shishi_encapreppart:                   AP-REQ and AP-REP Functions.
                                                             (line 1175)
* shishi_encapreppart_ctime:             AP-REQ and AP-REP Functions.
                                                             (line 1303)
* shishi_encapreppart_ctime_set:         AP-REQ and AP-REP Functions.
                                                             (line 1319)
* shishi_encapreppart_cusec_get:         AP-REQ and AP-REP Functions.
                                                             (line 1334)
* shishi_encapreppart_cusec_set:         AP-REQ and AP-REP Functions.
                                                             (line 1349)
* shishi_encapreppart_from_file:         AP-REQ and AP-REP Functions.
                                                             (line 1270)
* shishi_encapreppart_get_key:           AP-REQ and AP-REP Functions.
                                                             (line 1288)
* shishi_encapreppart_parse:             AP-REQ and AP-REP Functions.
                                                             (line 1237)
* shishi_encapreppart_print:             AP-REQ and AP-REP Functions.
                                                             (line 1188)
* shishi_encapreppart_read:              AP-REQ and AP-REP Functions.
                                                             (line 1253)
* shishi_encapreppart_save:              AP-REQ and AP-REP Functions.
                                                             (line 1203)
* shishi_encapreppart_seqnumber_get:     AP-REQ and AP-REP Functions.
                                                             (line 1364)
* shishi_encapreppart_seqnumber_remove:  AP-REQ and AP-REP Functions.
                                                             (line 1379)
* shishi_encapreppart_seqnumber_set:     AP-REQ and AP-REP Functions.
                                                             (line 1392)
* shishi_encapreppart_time_copy:         AP-REQ and AP-REP Functions.
                                                             (line 1408)
* shishi_encapreppart_to_file:           AP-REQ and AP-REP Functions.
                                                             (line 1218)
* shishi_enckdcreppart_authtime_set:     AS/TGS Functions.   (line 1400)
* shishi_enckdcreppart_endtime_set:      AS/TGS Functions.   (line 1431)
* shishi_enckdcreppart_flags_set:        AS/TGS Functions.   (line 1385)
* shishi_enckdcreppart_get_key:          AS/TGS Functions.   (line 1338)
* shishi_enckdcreppart_key_set:          AS/TGS Functions.   (line 1354)
* shishi_enckdcreppart_nonce_set:        AS/TGS Functions.   (line 1370)
* shishi_enckdcreppart_populate_encticketpart: AS/TGS Functions.
                                                             (line 1496)
* shishi_enckdcreppart_renew_till_set:   AS/TGS Functions.   (line 1446)
* shishi_enckdcreppart_sname_set:        AS/TGS Functions.   (line 1478)
* shishi_enckdcreppart_srealm_set:       AS/TGS Functions.   (line 1462)
* shishi_enckdcreppart_starttime_set:    AS/TGS Functions.   (line 1415)
* shishi_encprivpart_set_user_data:      SAFE and PRIV Functions.
                                                             (line  680)
* shishi_encprivpart_user_data:          SAFE and PRIV Functions.
                                                             (line  659)
* shishi_encrypt:                        Cryptographic Functions.
                                                             (line 1119)
* shishi_encrypt_etype:                  Cryptographic Functions.
                                                             (line  991)
* shishi_encrypt_iv:                     Cryptographic Functions.
                                                             (line 1078)
* shishi_encrypt_iv_etype:               Cryptographic Functions.
                                                             (line  948)
* shishi_encrypt_ivupdate:               Cryptographic Functions.
                                                             (line 1032)
* shishi_encrypt_ivupdate_etype:         Cryptographic Functions.
                                                             (line  899)
* shishi_encticketpart_authtime_set:     Ticket (ASN.1) Functions.
                                                             (line  282)
* shishi_encticketpart_client:           Ticket (ASN.1) Functions.
                                                             (line  312)
* shishi_encticketpart_clientrealm:      Ticket (ASN.1) Functions.
                                                             (line  335)
* shishi_encticketpart_cname_set:        Ticket (ASN.1) Functions.
                                                             (line  243)
* shishi_encticketpart_crealm_set:       Ticket (ASN.1) Functions.
                                                             (line  227)
* shishi_encticketpart_endtime_set:      Ticket (ASN.1) Functions.
                                                             (line  297)
* shishi_encticketpart_flags_set:        Ticket (ASN.1) Functions.
                                                             (line  212)
* shishi_encticketpart_get_key:          Ticket (ASN.1) Functions.
                                                             (line  181)
* shishi_encticketpart_key_set:          Ticket (ASN.1) Functions.
                                                             (line  196)
* shishi_encticketpart_transited_set:    Ticket (ASN.1) Functions.
                                                             (line  262)
* shishi_error:                          Error Functions.    (line   22)
* shishi_error_clear:                    Error Functions.    (line   35)
* shishi_error_outputtype:               Error Functions.    (line   79)
* shishi_error_printf:                   Error Functions.    (line   66)
* shishi_error_set:                      Error Functions.    (line   49)
* shishi_error_set_outputtype:           Error Functions.    (line   91)
* shishi_generalize_ctime:               Utility Functions.  (line  397)
* shishi_generalize_now:                 Utility Functions.  (line  384)
* shishi_generalize_time:                Utility Functions.  (line  370)
* shishi_hmac_md5:                       Cryptographic Functions.
                                                             (line 1657)
* shishi_hmac_sha1:                      Cryptographic Functions.
                                                             (line 1678)
* shishi_hostkeys_default_file:          Cryptographic Functions.
                                                             (line  561)
* shishi_hostkeys_default_file_set:      Cryptographic Functions.
                                                             (line  573)
* shishi_hostkeys_for_localservice:      Cryptographic Functions.
                                                             (line  639)
* shishi_hostkeys_for_localservicerealm: Cryptographic Functions.
                                                             (line  620)
* shishi_hostkeys_for_server:            Cryptographic Functions.
                                                             (line  587)
* shishi_hostkeys_for_serverrealm:       Cryptographic Functions.
                                                             (line  602)
* shishi_info:                           Error Functions.    (line  103)
* shishi_init:                           Initialization Functions.
                                                             (line   47)
* shishi_init_server:                    Initialization Functions.
                                                             (line   96)
* shishi_init_server_with_paths:         Initialization Functions.
                                                             (line  114)
* shishi_init_with_paths:                Initialization Functions.
                                                             (line   69)
* shishi_kdc_check_nonce:                AS/TGS Functions.   (line  201)
* shishi_kdc_copy_cname:                 AS/TGS Functions.   (line  153)
* shishi_kdc_copy_crealm:                AS/TGS Functions.   (line  120)
* shishi_kdc_copy_nonce:                 AS/TGS Functions.   (line  186)
* shishi_kdc_process:                    AS/TGS Functions.   (line  274)
* shishi_kdcrep_add_enc_part:            AS/TGS Functions.   (line 1303)
* shishi_kdcrep_clear_padata:            AS/TGS Functions.   (line 1325)
* shishi_kdcrep_client_set:              AS/TGS Functions.   (line 1215)
* shishi_kdcrep_cname_set:               AS/TGS Functions.   (line 1197)
* shishi_kdcrep_crealm_set:              AS/TGS Functions.   (line 1182)
* shishi_kdcrep_from_file:               AS/TGS Functions.   (line 1164)
* shishi_kdcrep_get_enc_part_etype:      AS/TGS Functions.   (line 1231)
* shishi_kdcrep_get_ticket:              AS/TGS Functions.   (line 1246)
* shishi_kdcrep_parse:                   AS/TGS Functions.   (line 1133)
* shishi_kdcrep_print:                   AS/TGS Functions.   (line 1084)
* shishi_kdcrep_read:                    AS/TGS Functions.   (line 1149)
* shishi_kdcrep_save:                    AS/TGS Functions.   (line 1099)
* shishi_kdcrep_set_enc_part:            AS/TGS Functions.   (line 1277)
* shishi_kdcrep_set_ticket:              AS/TGS Functions.   (line 1261)
* shishi_kdcrep_to_file:                 AS/TGS Functions.   (line 1114)
* shishi_kdcreq_add_padata:              AS/TGS Functions.   (line 1006)
* shishi_kdcreq_add_padata_preauth:      AS/TGS Functions.   (line 1047)
* shishi_kdcreq_add_padata_tgs:          AS/TGS Functions.   (line 1029)
* shishi_kdcreq_allow_postdate_p:        AS/TGS Functions.   (line  750)
* shishi_kdcreq_clear_padata:            AS/TGS Functions.   (line  951)
* shishi_kdcreq_client:                  AS/TGS Functions.   (line  461)
* shishi_kdcreq_disable_transited_check_p: AS/TGS Functions. (line  809)
* shishi_kdcreq_enc_tkt_in_skey_p:       AS/TGS Functions.   (line  858)
* shishi_kdcreq_etype:                   AS/TGS Functions.   (line  623)
* shishi_kdcreq_forwardable_p:           AS/TGS Functions.   (line  674)
* shishi_kdcreq_forwarded_p:             AS/TGS Functions.   (line  693)
* shishi_kdcreq_from_file:               AS/TGS Functions.   (line  410)
* shishi_kdcreq_get_padata:              AS/TGS Functions.   (line  965)
* shishi_kdcreq_get_padata_tgs:          AS/TGS Functions.   (line  987)
* shishi_kdcreq_nonce_set:               AS/TGS Functions.   (line  428)
* shishi_kdcreq_options:                 AS/TGS Functions.   (line  659)
* shishi_kdcreq_options_add:             AS/TGS Functions.   (line  936)
* shishi_kdcreq_options_set:             AS/TGS Functions.   (line  920)
* shishi_kdcreq_parse:                   AS/TGS Functions.   (line  379)
* shishi_kdcreq_postdated_p:             AS/TGS Functions.   (line  769)
* shishi_kdcreq_print:                   AS/TGS Functions.   (line  330)
* shishi_kdcreq_proxiable_p:             AS/TGS Functions.   (line  713)
* shishi_kdcreq_proxy_p:                 AS/TGS Functions.   (line  731)
* shishi_kdcreq_read:                    AS/TGS Functions.   (line  395)
* shishi_kdcreq_realm:                   AS/TGS Functions.   (line  507)
* shishi_kdcreq_renew_p:                 AS/TGS Functions.   (line  877)
* shishi_kdcreq_renewable_ok_p:          AS/TGS Functions.   (line  836)
* shishi_kdcreq_renewable_p:             AS/TGS Functions.   (line  789)
* shishi_kdcreq_save:                    AS/TGS Functions.   (line  345)
* shishi_kdcreq_server:                  AS/TGS Functions.   (line  544)
* shishi_kdcreq_set_cname:               AS/TGS Functions.   (line  443)
* shishi_kdcreq_set_etype:               AS/TGS Functions.   (line  641)
* shishi_kdcreq_set_realm:               AS/TGS Functions.   (line  529)
* shishi_kdcreq_set_sname:               AS/TGS Functions.   (line  567)
* shishi_kdcreq_till:                    AS/TGS Functions.   (line  585)
* shishi_kdcreq_tillc:                   AS/TGS Functions.   (line  609)
* shishi_kdcreq_to_file:                 AS/TGS Functions.   (line  360)
* shishi_kdcreq_validate_p:              AS/TGS Functions.   (line  898)
* shishi_key:                            Cryptographic Functions.
                                                             (line  196)
* shishi_key_copy:                       Cryptographic Functions.
                                                             (line  218)
* shishi_key_done:                       Cryptographic Functions.
                                                             (line  209)
* shishi_key_from_base64:                Cryptographic Functions.
                                                             (line  249)
* shishi_key_from_name:                  Cryptographic Functions.
                                                             (line  342)
* shishi_key_from_random:                Cryptographic Functions.
                                                             (line  288)
* shishi_key_from_string:                Cryptographic Functions.
                                                             (line  312)
* shishi_key_from_value:                 Cryptographic Functions.
                                                             (line  229)
* shishi_key_length:                     Cryptographic Functions.
                                                             (line  186)
* shishi_key_name:                       Cryptographic Functions.
                                                             (line  176)
* shishi_key_principal:                  Cryptographic Functions.
                                                             (line   30)
* shishi_key_principal_set:              Cryptographic Functions.
                                                             (line   43)
* shishi_key_random:                     Cryptographic Functions.
                                                             (line  270)
* shishi_key_realm:                      Cryptographic Functions.
                                                             (line   55)
* shishi_key_realm_set:                  Cryptographic Functions.
                                                             (line   67)
* shishi_key_timestamp:                  Cryptographic Functions.
                                                             (line  148)
* shishi_key_timestamp_set:              Cryptographic Functions.
                                                             (line  163)
* shishi_key_type:                       Cryptographic Functions.
                                                             (line   79)
* shishi_key_type_set:                   Cryptographic Functions.
                                                             (line   90)
* shishi_key_value:                      Cryptographic Functions.
                                                             (line  100)
* shishi_key_value_set:                  Cryptographic Functions.
                                                             (line  112)
* shishi_key_version:                    Cryptographic Functions.
                                                             (line  125)
* shishi_key_version_set:                Cryptographic Functions.
                                                             (line  137)
* shishi_keys:                           Cryptographic Functions.
                                                             (line  376)
* shishi_keys_add:                       Cryptographic Functions.
                                                             (line  434)
* shishi_keys_done:                      Cryptographic Functions.
                                                             (line  388)
* shishi_keys_for_localservicerealm_in_file: Cryptographic Functions.
                                                             (line  534)
* shishi_keys_for_server_in_file:        Cryptographic Functions.
                                                             (line  516)
* shishi_keys_for_serverrealm_in_file:   Cryptographic Functions.
                                                             (line  496)
* shishi_keys_from_file:                 Cryptographic Functions.
                                                             (line  478)
* shishi_keys_nth:                       Cryptographic Functions.
                                                             (line  409)
* shishi_keys_print:                     Cryptographic Functions.
                                                             (line  448)
* shishi_keys_remove:                    Cryptographic Functions.
                                                             (line  423)
* shishi_keys_size:                      Cryptographic Functions.
                                                             (line  398)
* shishi_keys_to_file:                   Cryptographic Functions.
                                                             (line  461)
* shishi_krberror:                       KRB-ERROR Functions.
                                                             (line   34)
* shishi_krberror_build:                 KRB-ERROR Functions.
                                                             (line  144)
* shishi_krberror_client:                KRB-ERROR Functions.
                                                             (line  221)
* shishi_krberror_client_set:            KRB-ERROR Functions.
                                                             (line  273)
* shishi_krberror_crealm:                KRB-ERROR Functions.
                                                             (line  175)
* shishi_krberror_ctime:                 KRB-ERROR Functions.
                                                             (line  392)
* shishi_krberror_ctime_set:             KRB-ERROR Functions.
                                                             (line  407)
* shishi_krberror_cusec:                 KRB-ERROR Functions.
                                                             (line  435)
* shishi_krberror_cusec_set:             KRB-ERROR Functions.
                                                             (line  450)
* shishi_krberror_der:                   KRB-ERROR Functions.
                                                             (line  158)
* shishi_krberror_edata:                 KRB-ERROR Functions.
                                                             (line  627)
* shishi_krberror_errorcode:             KRB-ERROR Functions.
                                                             (line  538)
* shishi_krberror_errorcode_fast:        KRB-ERROR Functions.
                                                             (line  553)
* shishi_krberror_errorcode_message:     KRB-ERROR Functions.
                                                             (line  705)
* shishi_krberror_errorcode_set:         KRB-ERROR Functions.
                                                             (line  567)
* shishi_krberror_etext:                 KRB-ERROR Functions.
                                                             (line  582)
* shishi_krberror_from_file:             KRB-ERROR Functions.
                                                             (line  126)
* shishi_krberror_message:               KRB-ERROR Functions.
                                                             (line  720)
* shishi_krberror_methoddata:            KRB-ERROR Functions.
                                                             (line  644)
* shishi_krberror_parse:                 KRB-ERROR Functions.
                                                             (line   95)
* shishi_krberror_pretty_print:          KRB-ERROR Functions.
                                                             (line  689)
* shishi_krberror_print:                 KRB-ERROR Functions.
                                                             (line   46)
* shishi_krberror_read:                  KRB-ERROR Functions.
                                                             (line  111)
* shishi_krberror_realm:                 KRB-ERROR Functions.
                                                             (line  289)
* shishi_krberror_remove_cname:          KRB-ERROR Functions.
                                                             (line  260)
* shishi_krberror_remove_crealm:         KRB-ERROR Functions.
                                                             (line  193)
* shishi_krberror_remove_ctime:          KRB-ERROR Functions.
                                                             (line  422)
* shishi_krberror_remove_cusec:          KRB-ERROR Functions.
                                                             (line  465)
* shishi_krberror_remove_edata:          KRB-ERROR Functions.
                                                             (line  676)
* shishi_krberror_remove_etext:          KRB-ERROR Functions.
                                                             (line  614)
* shishi_krberror_remove_sname:          KRB-ERROR Functions.
                                                             (line  342)
* shishi_krberror_save:                  KRB-ERROR Functions.
                                                             (line   61)
* shishi_krberror_server:                KRB-ERROR Functions.
                                                             (line  322)
* shishi_krberror_server_set:            KRB-ERROR Functions.
                                                             (line  376)
* shishi_krberror_set_cname:             KRB-ERROR Functions.
                                                             (line  242)
* shishi_krberror_set_crealm:            KRB-ERROR Functions.
                                                             (line  206)
* shishi_krberror_set_edata:             KRB-ERROR Functions.
                                                             (line  661)
* shishi_krberror_set_etext:             KRB-ERROR Functions.
                                                             (line  599)
* shishi_krberror_set_realm:             KRB-ERROR Functions.
                                                             (line  307)
* shishi_krberror_set_sname:             KRB-ERROR Functions.
                                                             (line  358)
* shishi_krberror_stime:                 KRB-ERROR Functions.
                                                             (line  478)
* shishi_krberror_stime_set:             KRB-ERROR Functions.
                                                             (line  493)
* shishi_krberror_susec:                 KRB-ERROR Functions.
                                                             (line  508)
* shishi_krberror_susec_set:             KRB-ERROR Functions.
                                                             (line  523)
* shishi_krberror_to_file:               KRB-ERROR Functions.
                                                             (line   76)
* shishi_md4:                            Cryptographic Functions.
                                                             (line 1624)
* shishi_md5:                            Cryptographic Functions.
                                                             (line 1640)
* shishi_n_fold:                         Cryptographic Functions.
                                                             (line 1413)
* shishi_parse_name:                     Utility Functions.  (line  154)
* shishi_pbkdf2_sha1:                    Cryptographic Functions.
                                                             (line 1815)
* shishi_principal_default:              Utility Functions.  (line  126)
* shishi_principal_default_guess:        Utility Functions.  (line  115)
* shishi_principal_default_set:          Utility Functions.  (line  140)
* shishi_principal_name:                 Utility Functions.  (line  178)
* shishi_principal_name_realm:           Utility Functions.  (line  204)
* shishi_principal_name_set:             Utility Functions.  (line  235)
* shishi_principal_set:                  Utility Functions.  (line  255)
* shishi_priv:                           SAFE and PRIV Functions.
                                                             (line  366)
* shishi_priv_build:                     SAFE and PRIV Functions.
                                                             (line  697)
* shishi_priv_done:                      SAFE and PRIV Functions.
                                                             (line  379)
* shishi_priv_enc_part_etype:            SAFE and PRIV Functions.
                                                             (line  619)
* shishi_priv_encprivpart:               SAFE and PRIV Functions.
                                                             (line  466)
* shishi_priv_encprivpart_der:           SAFE and PRIV Functions.
                                                             (line  489)
* shishi_priv_encprivpart_der_set:       SAFE and PRIV Functions.
                                                             (line  505)
* shishi_priv_encprivpart_set:           SAFE and PRIV Functions.
                                                             (line  478)
* shishi_priv_from_file:                 SAFE and PRIV Functions.
                                                             (line  601)
* shishi_priv_key:                       SAFE and PRIV Functions.
                                                             (line  389)
* shishi_priv_key_set:                   SAFE and PRIV Functions.
                                                             (line  401)
* shishi_priv_parse:                     SAFE and PRIV Functions.
                                                             (line  570)
* shishi_priv_print:                     SAFE and PRIV Functions.
                                                             (line  521)
* shishi_priv_priv:                      SAFE and PRIV Functions.
                                                             (line  411)
* shishi_priv_priv_der:                  SAFE and PRIV Functions.
                                                             (line  434)
* shishi_priv_priv_der_set:              SAFE and PRIV Functions.
                                                             (line  451)
* shishi_priv_priv_set:                  SAFE and PRIV Functions.
                                                             (line  423)
* shishi_priv_process:                   SAFE and PRIV Functions.
                                                             (line  712)
* shishi_priv_read:                      SAFE and PRIV Functions.
                                                             (line  586)
* shishi_priv_save:                      SAFE and PRIV Functions.
                                                             (line  536)
* shishi_priv_set_enc_part:              SAFE and PRIV Functions.
                                                             (line  635)
* shishi_priv_to_file:                   SAFE and PRIV Functions.
                                                             (line  551)
* shishi_prompt_password:                Utility Functions.  (line  484)
* shishi_prompt_password_callback_get:   Utility Functions.  (line  471)
* shishi_prompt_password_callback_set:   Utility Functions.  (line  447)
* shishi_random_to_key:                  Cryptographic Functions.
                                                             (line  822)
* shishi_randomize:                      Cryptographic Functions.
                                                             (line 1585)
* shishi_realm_default:                  Utility Functions.  (line   24)
* shishi_realm_default_guess:            Utility Functions.  (line   10)
* shishi_realm_default_set:              Utility Functions.  (line   36)
* shishi_realm_for_server:               Utility Functions.  (line  100)
* shishi_realm_for_server_dns:           Utility Functions.  (line   63)
* shishi_realm_for_server_file:          Utility Functions.  (line   50)
* shishi_resolv:                         Utility Functions.  (line  503)
* shishi_resolv_free:                    Utility Functions.  (line  517)
* shishi_safe:                           SAFE and PRIV Functions.
                                                             (line   33)
* shishi_safe_build:                     SAFE and PRIV Functions.
                                                             (line  312)
* shishi_safe_cksum:                     SAFE and PRIV Functions.
                                                             (line  232)
* shishi_safe_done:                      SAFE and PRIV Functions.
                                                             (line   46)
* shishi_safe_from_file:                 SAFE and PRIV Functions.
                                                             (line  214)
* shishi_safe_key:                       SAFE and PRIV Functions.
                                                             (line   56)
* shishi_safe_key_set:                   SAFE and PRIV Functions.
                                                             (line   68)
* shishi_safe_parse:                     SAFE and PRIV Functions.
                                                             (line  183)
* shishi_safe_print:                     SAFE and PRIV Functions.
                                                             (line  134)
* shishi_safe_read:                      SAFE and PRIV Functions.
                                                             (line  199)
* shishi_safe_safe:                      SAFE and PRIV Functions.
                                                             (line   78)
* shishi_safe_safe_der:                  SAFE and PRIV Functions.
                                                             (line  101)
* shishi_safe_safe_der_set:              SAFE and PRIV Functions.
                                                             (line  118)
* shishi_safe_safe_set:                  SAFE and PRIV Functions.
                                                             (line   90)
* shishi_safe_save:                      SAFE and PRIV Functions.
                                                             (line  149)
* shishi_safe_set_cksum:                 SAFE and PRIV Functions.
                                                             (line  252)
* shishi_safe_set_user_data:             SAFE and PRIV Functions.
                                                             (line  295)
* shishi_safe_to_file:                   SAFE and PRIV Functions.
                                                             (line  164)
* shishi_safe_user_data:                 SAFE and PRIV Functions.
                                                             (line  275)
* shishi_safe_verify:                    SAFE and PRIV Functions.
                                                             (line  327)
* shishi_server:                         Initialization Functions.
                                                             (line   21)
* shishi_server_for_local_service:       Utility Functions.  (line  288)
* shishi_strerror:                       Error Functions.    (line   10)
* shishi_string_to_key:                  Cryptographic Functions.
                                                             (line  792)
* shishi_tgs:                            TGS Functions.      (line   84)
* shishi_tgs_ap:                         TGS Functions.      (line  128)
* shishi_tgs_done:                       TGS Functions.      (line   96)
* shishi_tgs_krberror:                   TGS Functions.      (line  268)
* shishi_tgs_krberror_der:               TGS Functions.      (line  280)
* shishi_tgs_krberror_set:               TGS Functions.      (line  296)
* shishi_tgs_process:                    AS/TGS Functions.   (line  222)
* shishi_tgs_rep:                        TGS Functions.      (line  215)
* shishi_tgs_rep_build:                  TGS Functions.      (line  254)
* shishi_tgs_rep_der:                    TGS Functions.      (line  227)
* shishi_tgs_rep_process:                TGS Functions.      (line  242)
* shishi_tgs_req:                        TGS Functions.      (line  139)
* shishi_tgs_req_build:                  TGS Functions.      (line  204)
* shishi_tgs_req_der:                    TGS Functions.      (line  162)
* shishi_tgs_req_der_set:                TGS Functions.      (line  178)
* shishi_tgs_req_process:                TGS Functions.      (line  193)
* shishi_tgs_req_set:                    TGS Functions.      (line  151)
* shishi_tgs_sendrecv:                   TGS Functions.      (line  345)
* shishi_tgs_sendrecv_hint:              TGS Functions.      (line  329)
* shishi_tgs_set_realm:                  TGS Functions.      (line  370)
* shishi_tgs_set_realmserver:            TGS Functions.      (line  383)
* shishi_tgs_set_server:                 TGS Functions.      (line  357)
* shishi_tgs_tgtkt:                      TGS Functions.      (line  106)
* shishi_tgs_tgtkt_set:                  TGS Functions.      (line  118)
* shishi_tgs_tkt:                        TGS Functions.      (line  306)
* shishi_tgs_tkt_set:                    TGS Functions.      (line  318)
* shishi_tgsrep:                         AS/TGS Functions.   (line 1072)
* shishi_tgsreq:                         AS/TGS Functions.   (line  318)
* shishi_ticket:                         Ticket (ASN.1) Functions.
                                                             (line   36)
* shishi_ticket_add_enc_part:            Ticket (ASN.1) Functions.
                                                             (line  163)
* shishi_ticket_get_enc_part_etype:      Ticket (ASN.1) Functions.
                                                             (line  121)
* shishi_ticket_realm_get:               Ticket (ASN.1) Functions.
                                                             (line   48)
* shishi_ticket_realm_set:               Ticket (ASN.1) Functions.
                                                             (line   65)
* shishi_ticket_server:                  Ticket (ASN.1) Functions.
                                                             (line   80)
* shishi_ticket_set_enc_part:            Ticket (ASN.1) Functions.
                                                             (line  137)
* shishi_ticket_sname_set:               Ticket (ASN.1) Functions.
                                                             (line  103)
* shishi_time:                           Utility Functions.  (line  410)
* shishi_tkt:                            Ticket Functions.   (line   17)
* shishi_tkt2:                           Ticket Functions.   (line   30)
* shishi_tkt_authctime:                  Ticket Functions.   (line  634)
* shishi_tkt_client:                     Ticket Functions.   (line  155)
* shishi_tkt_client_p:                   Ticket Functions.   (line  177)
* shishi_tkt_clientrealm:                Ticket Functions.   (line  190)
* shishi_tkt_clientrealm_p:              Ticket Functions.   (line  211)
* shishi_tkt_done:                       Ticket Functions.   (line   46)
* shishi_tkt_enckdcreppart:              Ticket Functions.   (line   76)
* shishi_tkt_enckdcreppart_set:          Ticket Functions.   (line   87)
* shishi_tkt_encticketpart:              Ticket Functions.   (line  107)
* shishi_tkt_encticketpart_set:          Ticket Functions.   (line  118)
* shishi_tkt_endctime:                   Ticket Functions.   (line  660)
* shishi_tkt_expired_p:                  Ticket Functions.   (line  709)
* shishi_tkt_flags:                      Ticket Functions.   (line  274)
* shishi_tkt_flags_add:                  Ticket Functions.   (line  300)
* shishi_tkt_flags_set:                  Ticket Functions.   (line  287)
* shishi_tkt_forwardable_p:              Ticket Functions.   (line  313)
* shishi_tkt_forwarded_p:                Ticket Functions.   (line  333)
* shishi_tkt_hw_authent_p:               Ticket Functions.   (line  502)
* shishi_tkt_initial_p:                  Ticket Functions.   (line  466)
* shishi_tkt_invalid_p:                  Ticket Functions.   (line  430)
* shishi_tkt_kdcrep:                     Ticket Functions.   (line   97)
* shishi_tkt_key:                        Ticket Functions.   (line  128)
* shishi_tkt_key_set:                    Ticket Functions.   (line  142)
* shishi_tkt_keytype:                    Ticket Functions.   (line  581)
* shishi_tkt_keytype_fast:               Ticket Functions.   (line  593)
* shishi_tkt_keytype_p:                  Ticket Functions.   (line  604)
* shishi_tkt_lastreq_pretty_print:       Ticket Functions.   (line  720)
* shishi_tkt_lastreqc:                   Ticket Functions.   (line  619)
* shishi_tkt_match_p:                    Ticket Set Functions.
                                                             (line  256)
* shishi_tkt_may_postdate_p:             Ticket Functions.   (line  385)
* shishi_tkt_ok_as_delegate_p:           Ticket Functions.   (line  558)
* shishi_tkt_postdated_p:                Ticket Functions.   (line  411)
* shishi_tkt_pre_authent_p:              Ticket Functions.   (line  484)
* shishi_tkt_pretty_print:               Ticket Functions.   (line  731)
* shishi_tkt_proxiable_p:                Ticket Functions.   (line  351)
* shishi_tkt_proxy_p:                    Ticket Functions.   (line  370)
* shishi_tkt_realm:                      Ticket Functions.   (line  225)
* shishi_tkt_renew_tillc:                Ticket Functions.   (line  672)
* shishi_tkt_renewable_p:                Ticket Functions.   (line  450)
* shishi_tkt_server:                     Ticket Functions.   (line  241)
* shishi_tkt_server_p:                   Ticket Functions.   (line  262)
* shishi_tkt_startctime:                 Ticket Functions.   (line  647)
* shishi_tkt_ticket:                     Ticket Functions.   (line   55)
* shishi_tkt_ticket_set:                 Ticket Functions.   (line   66)
* shishi_tkt_transited_policy_checked_p: Ticket Functions.   (line  520)
* shishi_tkt_valid_at_time_p:            Ticket Functions.   (line  685)
* shishi_tkt_valid_now_p:                Ticket Functions.   (line  698)
* shishi_tkts:                           Ticket Set Functions.
                                                             (line   70)
* shishi_tkts_add:                       Ticket Set Functions.
                                                             (line  132)
* shishi_tkts_default:                   Ticket Set Functions.
                                                             (line   60)
* shishi_tkts_default_file:              Ticket Set Functions.
                                                             (line   34)
* shishi_tkts_default_file_guess:        Ticket Set Functions.
                                                             (line   22)
* shishi_tkts_default_file_set:          Ticket Set Functions.
                                                             (line   47)
* shishi_tkts_done:                      Ticket Set Functions.
                                                             (line   82)
* shishi_tkts_expire:                    Ticket Set Functions.
                                                             (line  204)
* shishi_tkts_find:                      Ticket Set Functions.
                                                             (line  269)
* shishi_tkts_find_for_clientserver:     Ticket Set Functions.
                                                             (line  310)
* shishi_tkts_find_for_server:           Ticket Set Functions.
                                                             (line  326)
* shishi_tkts_from_file:                 Ticket Set Functions.
                                                             (line  180)
* shishi_tkts_get:                       Ticket Set Functions.
                                                             (line  383)
* shishi_tkts_get_for_clientserver:      Ticket Set Functions.
                                                             (line  403)
* shishi_tkts_get_for_localservicepasswd: Ticket Set Functions.
                                                             (line  434)
* shishi_tkts_get_for_server:            Ticket Set Functions.
                                                             (line  419)
* shishi_tkts_get_tgs:                   Ticket Set Functions.
                                                             (line  363)
* shishi_tkts_get_tgt:                   Ticket Set Functions.
                                                             (line  341)
* shishi_tkts_new:                       Ticket Set Functions.
                                                             (line  147)
* shishi_tkts_nth:                       Ticket Set Functions.
                                                             (line  103)
* shishi_tkts_print:                     Ticket Set Functions.
                                                             (line  243)
* shishi_tkts_print_for_service:         Ticket Set Functions.
                                                             (line  228)
* shishi_tkts_read:                      Ticket Set Functions.
                                                             (line  167)
* shishi_tkts_remove:                    Ticket Set Functions.
                                                             (line  118)
* shishi_tkts_size:                      Ticket Set Functions.
                                                             (line   92)
* shishi_tkts_to_file:                   Ticket Set Functions.
                                                             (line  215)
* shishi_tkts_write:                     Ticket Set Functions.
                                                             (line  192)
* shishi_verbose:                        Error Functions.    (line  125)
* shishi_verify:                         Cryptographic Functions.
                                                             (line  871)
* shishi_warn:                           Error Functions.    (line  114)
* shishi_x509ca_default_file:            X.509 Functions.    (line   41)
* shishi_x509ca_default_file_guess:      X.509 Functions.    (line   13)
* shishi_x509ca_default_file_set:        X.509 Functions.    (line   26)
* shishi_x509cert_default_file:          X.509 Functions.    (line   84)
* shishi_x509cert_default_file_guess:    X.509 Functions.    (line   55)
* shishi_x509cert_default_file_set:      X.509 Functions.    (line   68)
* shishi_x509key_default_file:           X.509 Functions.    (line  124)
* shishi_x509key_default_file_guess:     X.509 Functions.    (line   97)
* shishi_x509key_default_file_set:       X.509 Functions.    (line  110)
* this in date strings:                  Relative items in date strings.
                                                             (line   33)
* today in date strings:                 Relative items in date strings.
                                                             (line   33)
* tomorrow in date strings:              Relative items in date strings.
                                                             (line   29)
* week in date strings:                  Relative items in date strings.
                                                             (line   15)
* year in date strings:                  Relative items in date strings.
                                                             (line   15)
* yesterday in date strings:             Relative items in date strings.
                                                             (line   29)


File: shishi.info,  Node: Concept Index,  Prev: Function and Data Index,  Up: Top

Concept Index
*************

[index]
* Menu:

* 3DES:                                  Cryptographic Overview.
                                                              (line  21)
* abbreviations for months:              Calendar date items. (line  38)
* AES:                                   Cryptographic Overview.
                                                              (line  21)
* AIX:                                   Supported Platforms. (line  70)
* anonymous tls:                         Kerberos via TLS.    (line  41)
* Application Programming Interface (API): Programming Manual.
                                                              (line   6)
* ARCFOUR:                               Cryptographic Overview.
                                                              (line  21)
* authenticated tls:                     Kerberos via TLS.    (line  97)
* Authentication:                        Glossary of terms.   (line   7)
* Authentication header:                 Glossary of terms.   (line  10)
* Authentication path:                   Glossary of terms.   (line  14)
* Authenticator:                         Glossary of terms.   (line  18)
* Authorization:                         Glossary of terms.   (line  23)
* authors of parse_datetime:             Authors of parse_datetime.
                                                              (line   6)
* Autoconf tests:                        Autoconf tests.      (line   6)
* beginning of time, for POSIX:          Seconds since the Epoch.
                                                              (line  13)
* Bellovin, Steven M.:                   Authors of parse_datetime.
                                                              (line   6)
* Berets, Jim:                           Authors of parse_datetime.
                                                              (line   6)
* Berry, K.:                             Authors of parse_datetime.
                                                              (line  19)
* calendar date item:                    Calendar date items. (line   6)
* Capability:                            Glossary of terms.   (line  28)
* case, ignored in dates:                General date syntax. (line  66)
* certificate authority (CA):            Kerberos via TLS.    (line  97)
* Ciphertext:                            Glossary of terms.   (line  35)
* Client:                                Glossary of terms.   (line  39)
* client authentication:                 Kerberos via TLS.    (line  97)
* combined date and time of day item:    Combined date and time of day items.
                                                              (line   6)
* comments, in dates:                    General date syntax. (line  66)
* Compiling your application:            Building the source. (line   6)
* concurrent writers:                    Multiple servers.    (line  24)
* configuration file:                    Shishi Configuration.
                                                              (line   6)
* Configure tests:                       Autoconf tests.      (line   6)
* Contributing:                          Contributing.        (line   7)
* Credentials:                           Glossary of terms.   (line  45)
* database definition:                   Shisa Configuration. (line   6)
* Database interface:                    Kerberos Database Functions.
                                                              (line   6)
* date and time of day format, ISO 8601: Combined date and time of day items.
                                                              (line   6)
* date format, ISO 8601:                 Calendar date items. (line  30)
* date input formats:                    Date input formats.  (line   6)
* day of week item:                      Day of week items.   (line   6)
* Debian:                                Supported Platforms. (line  10)
* DES:                                   Cryptographic Overview.
                                                              (line  21)
* Diffie Hellman key exchange:           Kerberos via TLS.    (line  41)
* displacement of dates:                 Relative items in date strings.
                                                              (line   6)
* Download:                              Downloading and Installing.
                                                              (line   6)
* Eggert, Paul:                          Authors of parse_datetime.
                                                              (line   6)
* Encryption Type (etype):               Glossary of terms.   (line  49)
* End-user Shishi usage:                 User Manual.         (line   6)
* epoch, for POSIX:                      Seconds since the Epoch.
                                                              (line  13)
* Error Handling:                        Error Handling.      (line   6)
* Examples:                              Examples.            (line   6)
* fail over:                             Multiple servers.    (line  82)
* FDL, GNU Free Documentation License:   GNU Free Documentation License.
                                                              (line   6)
* FreeBSD:                               Supported Platforms. (line  93)
* general date syntax:                   General date syntax. (line   6)
* Generic Security Service:              Generic Security Service.
                                                              (line   6)
* GNUTLS:                                Kerberos via TLS.    (line   6)
* GSS-API:                               Generic Security Service.
                                                              (line   6)
* GSSLib:                                Generic Security Service.
                                                              (line   6)
* Hacking:                               Contributing.        (line   7)
* High Availability:                     Multiple servers.    (line  64)
* HP-UX:                                 Supported Platforms. (line  74)
* Installation:                          Downloading and Installing.
                                                              (line   6)
* IPSEC:                                 Multiple servers.    (line   6)
* IRIX:                                  Supported Platforms. (line  66)
* ISO 8601 date and time of day format:  Combined date and time of day items.
                                                              (line   6)
* ISO 8601 date format:                  Calendar date items. (line  30)
* items in date strings:                 General date syntax. (line   6)
* KDC:                                   Glossary of terms.   (line  59)
* Kerberos:                              Glossary of terms.   (line  68)
* Kerberos Ticket:                       Glossary of terms.   (line 125)
* Key Version Number (kvno):             Glossary of terms.   (line  74)
* language, in dates:                    General date syntax. (line  46)
* LDAP:                                  Multiple servers.    (line   6)
* leap seconds <1>:                      General date syntax. (line  71)
* leap seconds <2>:                      Seconds since the Epoch.
                                                              (line  27)
* leap seconds:                          Time of day items.   (line  14)
* MacKenzie, David:                      Authors of parse_datetime.
                                                              (line   6)
* MacOS X:                               Supported Platforms. (line  99)
* Mandrake:                              Supported Platforms. (line  62)
* master server:                         Multiple servers.    (line  13)
* Meyering, Jim:                         Authors of parse_datetime.
                                                              (line   6)
* minutes, time zone correction by:      Time of day items.   (line  30)
* month names in date strings:           Calendar date items. (line  38)
* months, written-out:                   General date syntax. (line  38)
* Motorola Coldfire:                     Supported Platforms. (line 103)
* NetBSD:                                Supported Platforms. (line  83)
* NFS:                                   Multiple servers.    (line   6)
* numbers, written-out:                  General date syntax. (line  28)
* OpenBSD:                               Supported Platforms. (line  88)
* ordinal numbers:                       General date syntax. (line  28)
* Pinard, F.:                            Authors of parse_datetime.
                                                              (line  19)
* Plaintext:                             Glossary of terms.   (line  81)
* Principal:                             Glossary of terms.   (line  85)
* Principal identifier:                  Glossary of terms.   (line  89)
* pure numbers in date strings:          Pure numbers in date strings.
                                                              (line   6)
* RedHat:                                Supported Platforms. (line  45)
* RedHat Advanced Server:                Supported Platforms. (line  54)
* relative items in date strings:        Relative items in date strings.
                                                              (line   6)
* remote databases:                      Multiple servers.    (line   6)
* Reporting Bugs:                        Bug Reports.         (line   6)
* rsync:                                 Multiple servers.    (line   6)
* Salz, Rich:                            Authors of parse_datetime.
                                                              (line   6)
* Seal:                                  Glossary of terms.   (line  93)
* secondary server:                      Multiple servers.    (line  13)
* Secret key:                            Glossary of terms.   (line  98)
* Server:                                Glossary of terms.   (line 104)
* server authentication:                 Kerberos via TLS.    (line  97)
* Service:                               Glossary of terms.   (line 109)
* Session key:                           Glossary of terms.   (line 113)
* Shisa API:                             Kerberos Database Functions.
                                                              (line   6)
* Solaris:                               Supported Platforms. (line  79)
* specifying user database:              Shisa Configuration. (line   6)
* SQL:                                   Multiple servers.    (line   6)
* STARTTLS:                              Kerberos via TLS.    (line   6)
* Sub-session key:                       Glossary of terms.   (line 119)
* SuSE:                                  Supported Platforms. (line  31)
* SuSE Linux:                            Supported Platforms. (line  36)
* Ticket:                                Glossary of terms.   (line 125)
* time of day item:                      Time of day items.   (line   6)
* time zone correction:                  Time of day items.   (line  30)
* time zone item <1>:                    Time zone items.     (line   6)
* time zone item:                        General date syntax. (line  46)
* TLS:                                   Kerberos via TLS.    (line   6)
* tls resume:                            Kerberos via TLS.    (line  18)
* Tru64:                                 Supported Platforms. (line  26)
* uClibc:                                Supported Platforms. (line 103)
* uClinux:                               Supported Platforms. (line 103)
* user database definition:              Shisa Configuration. (line   6)
* X.509 authentication:                  Kerberos via TLS.    (line  97)



Tag Table:
Node: Top846
Node: Introduction2213
Node: Getting Started4055
Node: Features and Status4985
Node: Overview9886
Ref: Overview-Footnote-115161
Node: Cryptographic Overview15359
Ref: Cryptographic Overview-Footnote-125757
Ref: Cryptographic Overview-Footnote-225816
Node: Supported Platforms25874
Node: Getting help28817
Node: Commercial Support29280
Node: Downloading and Installing30243
Node: Bug Reports32118
Node: Contributing33511
Node: User Manual35642
Node: Administration Manual48413
Ref: Administration Manual-Footnote-149943
Node: Introduction to Shisa50022
Node: Configuring Shisa52544
Node: Using Shisa53976
Node: Starting Shishid64289
Node: Configuring DNS for KDC69216
Node: Kerberos via TLS73786
Node: Multiple servers88890
Node: Developer information94089
Node: Reference Manual95396
Node: Environmental Assumptions96547
Node: Glossary of terms98765
Node: Realm and Principal Naming104083
Ref: krbtgt112481
Node: Shishi Configuration117981
Ref: realm-kdc120334
Node: Shisa Configuration123420
Node: Parameters for shishi126141
Node: Parameters for shishid132071
Node: Parameters for shisa134446
Node: Environment variables138045
Node: Date input formats139187
Node: General date syntax141604
Node: Calendar date items144596
Node: Time of day items146602
Node: Time zone items148807
Node: Combined date and time of day items150068
Node: Day of week items150929
Node: Relative items in date strings151947
Node: Pure numbers in date strings154758
Node: Seconds since the Epoch155748
Node: Specifying time zone rules157378
Node: Authors of parse_datetime159759
Ref: Authors of get_date159947
Node: Programming Manual160910
Node: Preparation162523
Node: Header163214
Node: Initialization163832
Node: Version Check164514
Ref: shishi_check_version165048
Node: Building the source165838
Node: Autoconf tests167750
Node: Initialization Functions170732
Ref: shishi170934
Ref: shishi_server171331
Ref: shishi_done171739
Ref: shishi_init172304
Ref: shishi_init_with_paths173117
Ref: shishi_init_server174323
Ref: shishi_init_server_with_paths174973
Ref: shishi_cfg175722
Ref: shishi_cfg_from_file176056
Ref: shishi_cfg_print176402
Ref: shishi_cfg_default_systemfile176750
Ref: shishi_cfg_default_userdirectory177165
Ref: shishi_cfg_userdirectory_file177737
Ref: shishi_cfg_default_userfile178321
Ref: shishi_cfg_clientkdcetype178657
Ref: shishi_cfg_clientkdcetype_fast179088
Ref: shishi_cfg_clientkdcetype_set179416
Ref: shishi_cfg_authorizationtype_set179975
Node: Ticket Set Functions180435
Ref: shishi_tkts_default_file_guess181349
Ref: shishi_tkts_default_file181777
Ref: shishi_tkts_default_file_set182165
Ref: shishi_tkts_default182647
Ref: shishi_tkts182913
Ref: shishi_tkts_done183230
Ref: shishi_tkts_size183552
Ref: shishi_tkts_nth183804
Ref: shishi_tkts_remove184341
Ref: shishi_tkts_add184777
Ref: shishi_tkts_new185202
Ref: shishi_tkts_read185864
Ref: shishi_tkts_from_file186209
Ref: shishi_tkts_write186569
Ref: shishi_tkts_expire186891
Ref: shishi_tkts_to_file187157
Ref: shishi_tkts_print_for_service187513
Ref: shishi_tkts_print188011
Ref: shishi_tkt_match_p188337
Ref: shishi_tkts_find188687
Ref: shishi_tkts_find_for_clientserver190037
Ref: shishi_tkts_find_for_server190574
Ref: shishi_tkts_get_tgt191093
Ref: shishi_tkts_get_tgs191957
Ref: shishi_tkts_get192603
Ref: shishi_tkts_get_for_clientserver193359
Ref: shishi_tkts_get_for_server193869
Ref: shishi_tkts_get_for_localservicepasswd194356
Node: AP-REQ and AP-REP Functions194935
Ref: shishi_ap196111
Ref: shishi_ap_etype196813
Ref: shishi_ap_nosubkey197290
Ref: shishi_ap_done197655
Ref: shishi_ap_set_tktoptions197984
Ref: shishi_ap_set_tktoptionsdata198456
Ref: shishi_ap_set_tktoptionsraw199143
Ref: shishi_ap_set_tktoptionsasn1usage199973
Ref: shishi_ap_tktoptions200890
Ref: shishi_ap_tktoptionsdata201592
Ref: shishi_ap_tktoptionsraw202510
Ref: shishi_ap_etype_tktoptionsdata203569
Ref: shishi_ap_tktoptionsasn1usage204583
Ref: shishi_ap_tkt205724
Ref: shishi_ap_tkt_set206027
Ref: shishi_ap_authenticator_cksumdata206304
Ref: shishi_ap_authenticator_cksumdata_set207012
Ref: shishi_ap_authenticator_cksumraw_set207815
Ref: shishi_ap_authenticator_cksumtype208698
Ref: shishi_ap_authenticator_cksumtype_set209033
Ref: shishi_ap_authenticator209367
Ref: shishi_ap_authenticator_set209729
Ref: shishi_ap_req210019
Ref: shishi_ap_req_set210337
Ref: shishi_ap_req_der210584
Ref: shishi_ap_req_der_set211157
Ref: shishi_ap_req_build211615
Ref: shishi_ap_req_decode211916
Ref: shishi_ap_req_process_keyusage212233
Ref: shishi_ap_req_process213006
Ref: shishi_ap_req_asn1213512
Ref: shishi_ap_key213844
Ref: shishi_ap_rep214187
Ref: shishi_ap_rep_set214505
Ref: shishi_ap_rep_der214752
Ref: shishi_ap_rep_der_set215314
Ref: shishi_ap_rep_build215772
Ref: shishi_ap_rep_asn1216069
Ref: shishi_ap_rep_verify216415
Ref: shishi_ap_rep_verify_der216716
Ref: shishi_ap_rep_verify_asn1217260
Ref: shishi_ap_encapreppart217690
Ref: shishi_ap_encapreppart_set218047
Ref: shishi_ap_option2string218352
Ref: shishi_ap_string2option218889
Ref: shishi_apreq219265
Ref: shishi_apreq_print219566
Ref: shishi_apreq_save219943
Ref: shishi_apreq_to_file220309
Ref: shishi_apreq_parse220864
Ref: shishi_apreq_read221301
Ref: shishi_apreq_from_file221728
Ref: shishi_apreq_set_authenticator222292
Ref: shishi_apreq_add_authenticator223261
Ref: shishi_apreq_set_ticket223918
Ref: shishi_apreq_options224323
Ref: shishi_apreq_use_session_key_p224770
Ref: shishi_apreq_mutual_required_p225174
Ref: shishi_apreq_options_set225566
Ref: shishi_apreq_options_add225993
Ref: shishi_apreq_options_remove226483
Ref: shishi_apreq_get_authenticator_etype227004
Ref: shishi_apreq_get_ticket227430
Ref: shishi_aprep227824
Ref: shishi_aprep_print228132
Ref: shishi_aprep_save228509
Ref: shishi_aprep_to_file228875
Ref: shishi_aprep_parse229430
Ref: shishi_aprep_read229867
Ref: shishi_aprep_from_file230294
Ref: shishi_aprep_get_enc_part_etype230860
Ref: shishi_encapreppart231268
Ref: shishi_encapreppart_print231691
Ref: shishi_encapreppart_save232115
Ref: shishi_encapreppart_to_file232528
Ref: shishi_encapreppart_parse233130
Ref: shishi_encapreppart_read233614
Ref: shishi_encapreppart_from_file234093
Ref: shishi_encapreppart_get_key234694
Ref: shishi_encapreppart_ctime235123
Ref: shishi_encapreppart_ctime_set235609
Ref: shishi_encapreppart_cusec_get236090
Ref: shishi_encapreppart_cusec_set236581
Ref: shishi_encapreppart_seqnumber_get237075
Ref: shishi_encapreppart_seqnumber_remove237584
Ref: shishi_encapreppart_seqnumber_set238007
Ref: shishi_encapreppart_time_copy238521
Node: SAFE and PRIV Functions238963
Ref: shishi_safe240050
Ref: shishi_safe_done240390
Ref: shishi_safe_key240715
Ref: shishi_safe_key_set241044
Ref: shishi_safe_safe241305
Ref: shishi_safe_safe_set241645
Ref: shishi_safe_safe_der241943
Ref: shishi_safe_safe_der_set242545
Ref: shishi_safe_print243007
Ref: shishi_safe_save243375
Ref: shishi_safe_to_file243732
Ref: shishi_safe_parse244278
Ref: shishi_safe_read244706
Ref: shishi_safe_from_file245124
Ref: shishi_safe_cksum245655
Ref: shishi_safe_set_cksum246318
Ref: shishi_safe_user_data247175
Ref: shishi_safe_set_user_data247812
Ref: shishi_safe_build248314
Ref: shishi_safe_verify248791
Ref: shishi_priv250322
Ref: shishi_priv_done250662
Ref: shishi_priv_key250987
Ref: shishi_priv_key_set251305
Ref: shishi_priv_priv251566
Ref: shishi_priv_priv_set251903
Ref: shishi_priv_priv_der252201
Ref: shishi_priv_priv_der_set252803
Ref: shishi_priv_encprivpart253277
Ref: shishi_priv_encprivpart_set253651
Ref: shishi_priv_encprivpart_der253990
Ref: shishi_priv_encprivpart_der_set254553
Ref: shishi_priv_print255034
Ref: shishi_priv_save255402
Ref: shishi_priv_to_file255759
Ref: shishi_priv_parse256305
Ref: shishi_priv_read256733
Ref: shishi_priv_from_file257151
Ref: shishi_priv_enc_part_etype257700
Ref: shishi_priv_set_enc_part258107
Ref: shishi_encprivpart_user_data258997
Ref: shishi_encprivpart_set_user_data259686
Ref: shishi_priv_build260226
Ref: shishi_priv_process260701
Node: Ticket Functions261159
Ref: shishi_tkt261738
Ref: shishi_tkt2262036
Ref: shishi_tkt_done262542
Ref: shishi_tkt_ticket262785
Ref: shishi_tkt_ticket_set263028
Ref: shishi_tkt_enckdcreppart263302
Ref: shishi_tkt_enckdcreppart_set263588
Ref: shishi_tkt_kdcrep263893
Ref: shishi_tkt_encticketpart264148
Ref: shishi_tkt_encticketpart_set264431
Ref: shishi_tkt_key264708
Ref: shishi_tkt_key_set265096
Ref: shishi_tkt_client265392
Ref: shishi_tkt_client_p266203
Ref: shishi_tkt_clientrealm266542
Ref: shishi_tkt_clientrealm_p267375
Ref: shishi_tkt_realm267759
Ref: shishi_tkt_server268188
Ref: shishi_tkt_server_p268986
Ref: shishi_tkt_flags269313
Ref: shishi_tkt_flags_set269632
Ref: shishi_tkt_flags_add270036
Ref: shishi_tkt_forwardable_p270406
Ref: shishi_tkt_forwarded_p271201
Ref: shishi_tkt_proxiable_p271907
Ref: shishi_tkt_proxy_p272725
Ref: shishi_tkt_may_postdate_p273263
Ref: shishi_tkt_postdated_p274537
Ref: shishi_tkt_invalid_p275328
Ref: shishi_tkt_renewable_p276175
Ref: shishi_tkt_initial_p276723
Ref: shishi_tkt_pre_authent_p277449
Ref: shishi_tkt_hw_authent_p278156
Ref: shishi_tkt_transited_policy_checked_p278902
Ref: shishi_tkt_ok_as_delegate_p280757
Ref: shishi_tkt_keytype281790
Ref: shishi_tkt_keytype_fast282154
Ref: shishi_tkt_keytype_p282493
Ref: shishi_tkt_lastreqc282903
Ref: shishi_tkt_authctime283368
Ref: shishi_tkt_startctime283775
Ref: shishi_tkt_endctime284160
Ref: shishi_tkt_renew_tillc284517
Ref: shishi_tkt_valid_at_time_p284903
Ref: shishi_tkt_valid_now_p285288
Ref: shishi_tkt_expired_p285562
Ref: shishi_tkt_lastreq_pretty_print285855
Ref: shishi_tkt_pretty_print286196
Node: AS Functions286425
Ref: shishi_as288566
Ref: shishi_as_done288883
Ref: shishi_as_req289190
Ref: shishi_as_req_build289529
Ref: shishi_as_req_set289788
Ref: shishi_as_req_der290035
Ref: shishi_as_req_der_set290550
Ref: shishi_as_rep290996
Ref: shishi_as_rep_process291338
Ref: shishi_as_rep_build291885
Ref: shishi_as_rep_der292205
Ref: shishi_as_rep_set292711
Ref: shishi_as_rep_der_set292966
Ref: shishi_as_krberror293422
Ref: shishi_as_krberror_der293777
Ref: shishi_as_krberror_set294307
Ref: shishi_as_tkt294573
Ref: shishi_as_tkt_set294886
Ref: shishi_as_sendrecv_hint295137
Ref: shishi_as_sendrecv295706
Node: TGS Functions296020
Ref: shishi_tgs298273
Ref: shishi_tgs_done298598
Ref: shishi_tgs_tgtkt298917
Ref: shishi_tgs_tgtkt_set299270
Ref: shishi_tgs_ap299546
Ref: shishi_tgs_req299871
Ref: shishi_tgs_req_set300198
Ref: shishi_tgs_req_der300468
Ref: shishi_tgs_req_der_set300992
Ref: shishi_tgs_req_process301465
Ref: shishi_tgs_req_build301819
Ref: shishi_tgs_rep302114
Ref: shishi_tgs_rep_der302436
Ref: shishi_tgs_rep_process302960
Ref: shishi_tgs_rep_build303314
Ref: shishi_tgs_krberror303703
Ref: shishi_tgs_krberror_der304042
Ref: shishi_tgs_krberror_set304580
Ref: shishi_tgs_tkt304855
Ref: shishi_tgs_tkt_set305182
Ref: shishi_tgs_sendrecv_hint305458
Ref: shishi_tgs_sendrecv306029
Ref: shishi_tgs_set_server306388
Ref: shishi_tgs_set_realm306735
Ref: shishi_tgs_set_realmserver307090
Node: Ticket (ASN.1) Functions307485
Ref: shishi_ticket308737
Ref: shishi_ticket_realm_get309055
Ref: shishi_ticket_realm_set309535
Ref: shishi_ticket_server309938
Ref: shishi_ticket_sname_set310846
Ref: shishi_ticket_get_enc_part_etype311408
Ref: shishi_ticket_set_enc_part311833
Ref: shishi_ticket_add_enc_part312732
Ref: shishi_encticketpart_get_key313272
Ref: shishi_encticketpart_key_set313699
Ref: shishi_encticketpart_flags_set314200
Ref: shishi_encticketpart_crealm_set314647
Ref: shishi_encticketpart_cname_set315090
Ref: shishi_encticketpart_transited_set315690
Ref: shishi_encticketpart_authtime_set316344
Ref: shishi_encticketpart_endtime_set316838
Ref: shishi_encticketpart_client317318
Ref: shishi_encticketpart_clientrealm318273
Node: AS/TGS Functions319206
Ref: shishi_as_derive_salt322273
Ref: shishi_kdc_copy_crealm323064
Ref: shishi_as_check_crealm323494
Ref: shishi_kdc_copy_cname324131
Ref: shishi_as_check_cname324555
Ref: shishi_kdc_copy_nonce325203
Ref: shishi_kdc_check_nonce325629
Ref: shishi_tgs_process326419
Ref: shishi_as_process327437
Ref: shishi_kdc_process328279
Ref: shishi_asreq329614
Ref: shishi_tgsreq329905
Ref: shishi_kdcreq_print330211
Ref: shishi_kdcreq_save330595
Ref: shishi_kdcreq_to_file330969
Ref: shishi_kdcreq_parse331531
Ref: shishi_kdcreq_read331975
Ref: shishi_kdcreq_from_file332409
Ref: shishi_kdcreq_nonce_set332964
Ref: shishi_kdcreq_set_cname333389
Ref: shishi_kdcreq_client333940
Ref: shishi_asreq_clientrealm334846
Ref: shishi_kdcreq_realm335772
Ref: shishi_kdcreq_set_realm336640
Ref: shishi_kdcreq_server337051
Ref: shishi_kdcreq_set_sname337955
Ref: shishi_kdcreq_till338497
Ref: shishi_kdcreq_tillc339454
Ref: shishi_kdcreq_etype339847
Ref: shishi_kdcreq_set_etype340366
Ref: shishi_kdcreq_options340946
Ref: shishi_kdcreq_forwardable_p341379
Ref: shishi_kdcreq_forwarded_p342047
Ref: shishi_kdcreq_proxiable_p342842
Ref: shishi_kdcreq_proxy_p343485
Ref: shishi_kdcreq_allow_postdate_p344200
Ref: shishi_kdcreq_postdated_p344896
Ref: shishi_kdcreq_renewable_p345687
Ref: shishi_kdcreq_disable_transited_check_p346490
Ref: shishi_kdcreq_renewable_ok_p347598
Ref: shishi_kdcreq_enc_tkt_in_skey_p348472
Ref: shishi_kdcreq_renew_p349123
Ref: shishi_kdcreq_validate_p349992
Ref: shishi_kdcreq_options_set350925
Ref: shishi_kdcreq_options_add351399
Ref: shishi_kdcreq_clear_padata351859
Ref: shishi_kdcreq_get_padata352210
Ref: shishi_kdcreq_get_padata_tgs353015
Ref: shishi_kdcreq_add_padata353650
Ref: shishi_kdcreq_add_padata_tgs354496
Ref: shishi_kdcreq_add_padata_preauth355116
Ref: shishi_asrep355526
Ref: shishi_tgsrep355817
Ref: shishi_kdcrep_print356123
Ref: shishi_kdcrep_save356507
Ref: shishi_kdcrep_to_file356882
Ref: shishi_kdcrep_parse357444
Ref: shishi_kdcrep_read357888
Ref: shishi_kdcrep_from_file358322
Ref: shishi_kdcrep_crealm_set358879
Ref: shishi_kdcrep_cname_set359305
Ref: shishi_kdcrep_client_set359858
Ref: shishi_kdcrep_get_enc_part_etype360341
Ref: shishi_kdcrep_get_ticket360764
Ref: shishi_kdcrep_set_ticket361187
Ref: shishi_kdcrep_set_enc_part361610
Ref: shishi_kdcrep_add_enc_part362511
Ref: shishi_kdcrep_clear_padata363240
Ref: shishi_enckdcreppart_get_key363599
Ref: shishi_enckdcreppart_key_set364119
Ref: shishi_enckdcreppart_nonce_set364620
Ref: shishi_enckdcreppart_flags_set365058
Ref: shishi_enckdcreppart_authtime_set365497
Ref: shishi_enckdcreppart_starttime_set365995
Ref: shishi_enckdcreppart_endtime_set366553
Ref: shishi_enckdcreppart_renew_till_set367049
Ref: shishi_enckdcreppart_srealm_set367610
Ref: shishi_enckdcreppart_sname_set368084
Ref: shishi_enckdcreppart_populate_encticketpart368713
Node: Authenticator Functions369238
Ref: shishi_authenticator370150
Ref: shishi_authenticator_subkey370580
Ref: shishi_authenticator_print371040
Ref: shishi_authenticator_save371508
Ref: shishi_authenticator_to_file371966
Ref: shishi_authenticator_parse372585
Ref: shishi_authenticator_read373090
Ref: shishi_authenticator_from_file373590
Ref: shishi_authenticator_set_crealm374204
Ref: shishi_authenticator_set_cname374689
Ref: shishi_authenticator_client_set375318
Ref: shishi_authenticator_ctime375814
Ref: shishi_authenticator_ctime_set376313
Ref: shishi_authenticator_cusec_get376808
Ref: shishi_authenticator_cusec_set377312
Ref: shishi_authenticator_seqnumber_get377818
Ref: shishi_authenticator_seqnumber_remove378342
Ref: shishi_authenticator_seqnumber_set378778
Ref: shishi_authenticator_client379300
Ref: shishi_authenticator_clientrealm380255
Ref: shishi_authenticator_cksum381243
Ref: shishi_authenticator_set_cksum382018
Ref: shishi_authenticator_add_cksum383000
Ref: shishi_authenticator_add_cksum_type383756
Ref: shishi_authenticator_clear_authorizationdata384607
Ref: shishi_authenticator_add_authorizationdata385073
Ref: shishi_authenticator_authorizationdata385736
Ref: shishi_authenticator_remove_subkey386530
Ref: shishi_authenticator_get_subkey386946
Ref: shishi_authenticator_set_subkey387500
Ref: shishi_authenticator_add_random_subkey388495
Ref: shishi_authenticator_add_random_subkey_etype389018
Ref: shishi_authenticator_add_subkey389566
Node: KRB-ERROR Functions389978
Ref: shishi_krberror391233
Ref: shishi_krberror_print391549
Ref: shishi_krberror_save391947
Ref: shishi_krberror_to_file392334
Ref: shishi_krberror_parse392910
Ref: shishi_krberror_read393368
Ref: shishi_krberror_from_file393816
Ref: shishi_krberror_build394377
Ref: shishi_krberror_der394826
Ref: shishi_krberror_crealm395383
Ref: shishi_krberror_remove_crealm395909
Ref: shishi_krberror_set_crealm396287
Ref: shishi_krberror_client396721
Ref: shishi_krberror_set_cname397412
Ref: shishi_krberror_remove_cname398000
Ref: shishi_krberror_client_set398377
Ref: shishi_krberror_realm398838
Ref: shishi_krberror_set_realm399357
Ref: shishi_krberror_server399806
Ref: shishi_krberror_remove_sname400500
Ref: shishi_krberror_set_sname401030
Ref: shishi_krberror_server_set401614
Ref: shishi_krberror_ctime402075
Ref: shishi_krberror_ctime_set402514
Ref: shishi_krberror_remove_ctime402965
Ref: shishi_krberror_cusec403330
Ref: shishi_krberror_cusec_set403785
Ref: shishi_krberror_remove_cusec404239
Ref: shishi_krberror_stime404604
Ref: shishi_krberror_stime_set405043
Ref: shishi_krberror_susec405480
Ref: shishi_krberror_susec_set405935
Ref: shishi_krberror_errorcode406383
Ref: shishi_krberror_errorcode_fast406826
Ref: shishi_krberror_errorcode_set407268
Ref: shishi_krberror_etext407707
Ref: shishi_krberror_set_etext408224
Ref: shishi_krberror_remove_etext408694
Ref: shishi_krberror_edata409068
Ref: shishi_krberror_methoddata409587
Ref: shishi_krberror_set_edata410162
Ref: shishi_krberror_remove_edata410632
Ref: shishi_krberror_pretty_print411020
Ref: shishi_krberror_errorcode_message411498
Ref: shishi_krberror_message411968
Node: Cryptographic Functions412474
Ref: shishi_key_principal413440
Ref: shishi_key_principal_set413823
Ref: shishi_key_realm414213
Ref: shishi_key_realm_set414564
Ref: shishi_key_type414950
Ref: shishi_key_type_set415213
Ref: shishi_key_value415444
Ref: shishi_key_value_set415756
Ref: shishi_key_version416197
Ref: shishi_key_version_set416519
Ref: shishi_key_timestamp416831
Ref: shishi_key_timestamp_set417241
Ref: shishi_key_name417582
Ref: shishi_key_length417816
Ref: shishi_key418057
Ref: shishi_key_done418403
Ref: shishi_key_copy418595
Ref: shishi_key_from_value418914
Ref: shishi_key_from_base64419528
Ref: shishi_key_random420234
Ref: shishi_key_from_random420777
Ref: shishi_key_from_string421454
Ref: shishi_key_from_name422445
Ref: shishi_keys423735
Ref: shishi_keys_done424049
Ref: shishi_keys_size424362
Ref: shishi_keys_nth424602
Ref: shishi_keys_remove425104
Ref: shishi_keys_add425415
Ref: shishi_keys_print425847
Ref: shishi_keys_to_file426146
Ref: shishi_keys_from_file426695
Ref: shishi_keys_for_serverrealm_in_file427199
Ref: shishi_keys_for_server_in_file427880
Ref: shishi_keys_for_localservicerealm_in_file428451
Ref: shishi_hostkeys_default_file429556
Ref: shishi_hostkeys_default_file_set429957
Ref: shishi_hostkeys_for_server430467
Ref: shishi_hostkeys_for_serverrealm430976
Ref: shishi_hostkeys_for_localservicerealm431593
Ref: shishi_hostkeys_for_localservice432315
Ref: shishi_cipher_supported_p433078
Ref: shishi_cipher_name433320
Ref: shishi_cipher_blocksize433637
Ref: shishi_cipher_confoundersize433928
Ref: shishi_cipher_keylen434314
Ref: shishi_cipher_randomlen434607
Ref: shishi_cipher_defaultcksumtype434996
Ref: shishi_cipher_parse435321
Ref: shishi_checksum_supported_p435617
Ref: shishi_checksum_name435876
Ref: shishi_checksum_cksumlen436181
Ref: shishi_checksum_parse436483
Ref: shishi_string_to_key436802
Ref: shishi_random_to_key437906
Ref: shishi_checksum438548
Ref: shishi_verify439478
Ref: shishi_encrypt_ivupdate_etype440384
Ref: shishi_encrypt_iv_etype442313
Ref: shishi_encrypt_etype444043
Ref: shishi_encrypt_ivupdate445707
Ref: shishi_encrypt_iv447527
Ref: shishi_encrypt449132
Ref: shishi_decrypt_ivupdate_etype450662
Ref: shishi_decrypt_iv_etype452591
Ref: shishi_decrypt_etype454321
Ref: shishi_decrypt_ivupdate455961
Ref: shishi_decrypt_iv457781
Ref: shishi_decrypt459392
Ref: shishi_n_fold460890
Ref: shishi_dr461756
Ref: shishi_dk462542
Ref: shishi_crypto463527
Ref: shishi_crypto_encrypt464680
Ref: shishi_crypto_decrypt465522
Ref: shishi_crypto_close466360
Ref: shishi_randomize466799
Ref: shishi_crc467310
Ref: shishi_md4467965
Ref: shishi_md5468416
Ref: shishi_hmac_md5468877
Ref: shishi_hmac_sha1469524
Ref: shishi_des_cbc_mac470177
Ref: shishi_arcfour470709
Ref: shishi_des471809
Ref: shishi_3des472546
Ref: shishi_aes_cts473291
Ref: shishi_pbkdf2_sha1474268
Node: X.509 Functions475369
Ref: shishi_x509ca_default_file_guess475718
Ref: shishi_x509ca_default_file_set476154
Ref: shishi_x509ca_default_file476780
Ref: shishi_x509cert_default_file_guess477294
Ref: shishi_x509cert_default_file_set477753
Ref: shishi_x509cert_default_file478397
Ref: shishi_x509key_default_file_guess478925
Ref: shishi_x509key_default_file_set479353
Ref: shishi_x509key_default_file479963
Node: Utility Functions480387
Ref: shishi_realm_default_guess480609
Ref: shishi_realm_default481218
Ref: shishi_realm_default_set481559
Ref: shishi_realm_for_server_file482031
Ref: shishi_realm_for_server_dns482408
Ref: shishi_realm_for_server483798
Ref: shishi_principal_default_guess484327
Ref: shishi_principal_default484742
Ref: shishi_principal_default_set485268
Ref: shishi_parse_name485739
Ref: shishi_principal_name486561
Ref: shishi_principal_name_realm487564
Ref: shishi_principal_name_set488802
Ref: shishi_principal_set489485
Ref: shishi_derive_default_salt490068
Ref: shishi_server_for_local_service490584
Ref: shishi_authorize_strcmp491192
Ref: shishi_authorize_k5login491775
Ref: shishi_authorization_parse492352
Ref: shishi_authorized_p492666
Ref: shishi_generalize_time493423
Ref: shishi_generalize_now493822
Ref: shishi_generalize_ctime494186
Ref: shishi_time494503
Ref: shishi_ctime494967
Ref: shishi_prompt_password_callback_set495585
Ref: shishi_prompt_password_callback_get496472
Ref: shishi_prompt_password496885
Ref: shishi_resolv497547
Ref: shishi_resolv_free498005
Node: ASN.1 Functions498186
Ref: shishi_asn1_read_inline498397
Ref: shishi_asn1_read499331
Ref: shishi_asn1_read_optional500180
Ref: shishi_asn1_done501126
Ref: shishi_asn1_pa_enc_ts_enc501468
Ref: shishi_asn1_encrypteddata501751
Ref: shishi_asn1_padata502019
Ref: shishi_asn1_methoddata502283
Ref: shishi_asn1_etype_info502555
Ref: shishi_asn1_etype_info2502828
Ref: shishi_asn1_asreq503091
Ref: shishi_asn1_asrep503343
Ref: shishi_asn1_tgsreq503597
Ref: shishi_asn1_tgsrep503853
Ref: shishi_asn1_apreq504107
Ref: shishi_asn1_aprep504359
Ref: shishi_asn1_encapreppart504625
Ref: shishi_asn1_ticket504886
Ref: shishi_asn1_encticketpart505155
Ref: shishi_asn1_authenticator505438
Ref: shishi_asn1_enckdcreppart505721
Ref: shishi_asn1_encasreppart506002
Ref: shishi_asn1_krberror506273
Ref: shishi_asn1_krbsafe506535
Ref: shishi_asn1_priv506789
Ref: shishi_asn1_encprivpart507054
Ref: shishi_asn1_to_der_field507334
Ref: shishi_asn1_to_der508072
Ref: shishi_asn1_msgtype508701
Ref: shishi_der_msgtype509180
Ref: shishi_der2asn1509622
Ref: shishi_der2asn1_padata510117
Ref: shishi_der2asn1_methoddata510600
Ref: shishi_der2asn1_etype_info511091
Ref: shishi_der2asn1_etype_info2511583
Ref: shishi_der2asn1_ticket512067
Ref: shishi_der2asn1_encticketpart512555
Ref: shishi_der2asn1_asreq513041
Ref: shishi_der2asn1_tgsreq513514
Ref: shishi_der2asn1_asrep513987
Ref: shishi_der2asn1_tgsrep514460
Ref: shishi_der2asn1_kdcrep514935
Ref: shishi_der2asn1_encasreppart515422
Ref: shishi_der2asn1_enctgsreppart515922
Ref: shishi_der2asn1_enckdcreppart516424
Ref: shishi_der2asn1_authenticator516926
Ref: shishi_der2asn1_krberror517418
Ref: shishi_der2asn1_krbsafe517899
Ref: shishi_der2asn1_priv518372
Ref: shishi_der2asn1_encprivpart518856
Ref: shishi_der2asn1_apreq519341
Ref: shishi_der2asn1_aprep519812
Ref: shishi_der2asn1_encapreppart520297
Ref: shishi_der2asn1_kdcreq520783
Ref: shishi_asn1_print521272
Node: Error Handling521621
Node: Error Values522382
Node: Error Functions527390
Ref: shishi_strerror527557
Ref: shishi_error527936
Ref: shishi_error_clear528359
Ref: shishi_error_set528888
Ref: shishi_error_printf529585
Ref: shishi_error_outputtype530109
Ref: shishi_error_set_outputtype530454
Ref: shishi_info530742
Ref: shishi_warn531050
Ref: shishi_verbose531352
Node: Examples531637
Node: Kerberos Database Functions533271
Ref: shisa535962
Ref: shisa_done536202
Ref: shisa_init536391
Ref: shisa_init_with_paths537037
Ref: shisa_cfg_db537986
Ref: shisa_cfg538619
Ref: shisa_cfg_from_file538934
Ref: shisa_cfg_default_systemfile539278
Ref: shisa_enumerate_realms539917
Ref: shisa_enumerate_principals540535
Ref: shisa_principal_find541188
Ref: shisa_principal_update541908
Ref: shisa_principal_add543114
Ref: shisa_principal_remove543905
Ref: shisa_keys_find544476
Ref: shisa_key_add545554
Ref: shisa_key_update546063
Ref: shisa_key_remove547446
Ref: shisa_key_free548415
Ref: shisa_keys_free548709
Ref: shisa_strerror549339
Ref: shisa_info549659
Node: Generic Security Service549907
Node: Acknowledgements551154
Node: Criticism of Kerberos551877
Node: Protocol Extensions554125
Node: STARTTLS protected KDC exchanges554945
Node: Telnet encryption with AES-CCM564083
Node: Kerberized rsh and rlogin572077
Node: Key as initialization vector582684
Ref: Key as initialization vector-Footnote-1585044
Node: The Keytab Binary File Format585210
Node: The Credential Cache Binary File Format590054
Node: Copying Information593483
Node: GNU Free Documentation License593745
Node: Function and Data Index618878
Node: Concept Index695633

End Tag Table
