Shishi ¶

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.

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 4120 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 (see 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.

1.3 Overview ¶

This section describes RFC 1510 from a protocol point of view¹.

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.

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 (see 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" ² 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³, 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.

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 (see Bug Reports).

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.

1.7 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.3.tar.gz’ where the ‘1.0.3’ 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.3.tar.gz
$ tar xfz shishi-1.0.3.tar.gz
$ cd shishi-1.0.3/
$ ./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.

1.8 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:

1.9 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 (see 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 (see GNU Coding Standards).

  If you normally code using another coding standard, there is no problem, but you should use ‘indent’ to reformat the code (see GNU Indent) 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.

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)
$

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.

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 (see Multiple servers).

See the reference manual (see 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.

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 (see 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’, 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 (see 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’ (see Name of the TGS). 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 (see Starting Shishid), and get tickets as explained earlier (see User 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. See Bug Reports.

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.

• DNS vs. Kerberos - Case Sensitivity of Realm Names
• Overview - KDC location information
• Example - KDC location information
• Security considerations

_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.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, See STARTTLS protected KDC exchanges.

• Setting up TLS resume
• Setting up Anonymous TLS
• Setting up X.509 authenticated TLS

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

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:~$

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

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:~$

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:~$

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:~$

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:~$

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

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:~$

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

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:~$

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

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 (see 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

3.8 Developer information ¶

The Programming API for Shisa is described below (see 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 (see 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 (see Bug Reports).

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.

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.

4.3 Realm and Principal Naming ¶

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

• Realm Names
• Principal Names
• Choosing a principal with which to communicate
• Principal Name Form

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

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

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.

• ‘default-realm’
• ‘default-principal’
• ‘client-kdc-etypes’
• ‘verbose’, ‘verbose-asn1’, ‘verbose-noise’, ‘verbose-crypto’, ‘verbose-crypto-noise’
• ‘realm-kdc’
• ‘server-realm’
• ‘kdc-timeout’, ‘kdc-retries’
• ‘stringprocess’
• ‘ticket-life’
• ‘renew-life’

default-realm JOSEFSSON.ORG

default-principal jas

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

verbose
verbose-noise

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

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

kdc-timeout=10

kdc-retries=5

stringprocess=UTF-8

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

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

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.

• ‘db’

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

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

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

db file PATH

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

db file /usr/local/var/shishi

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)

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)

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)

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.

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.

• General date syntax
• Calendar date items
• Time of day items
• Time zone items
• Combined date and time of day items
• Day of week items
• Relative items in date strings
• Pure numbers in date strings
• Seconds since the Epoch
• Specifying time zone rules
• Authors of parse_datetime

$ LC_ALL=C TZ=UTC0 date
Tue Jul 21 23:00:37 UTC 2020
$ TZ=UTC0 date +'%Y-%m-%d %H:%M:%SZ'
2020-07-21 23:00:37Z
$ date --rfc-3339=ns  # --rfc-3339 is a GNU extension.
2020-07-21 19:00:37.692722128-04:00
$ date --rfc-2822  # a GNU extension
Tue, 21 Jul 2020 19:00:37 -0400
$ date +'%Y-%m-%d %H:%M:%S %z'  # %z is a GNU extension.
2020-07-21 19:00:37 -0400
$ date +'@%s.%N'  # %s and %N are GNU extensions.
@1595372437.692722128

2020-07-20     # ISO 8601.
20-7-20        # Assume 19xx for 69 through 99,
               # 20xx for 00 through 68 (not recommended).
7/20/2020      # Common U.S. writing.
20 July 2020
20 Jul 2020    # Three-letter abbreviations always allowed.
Jul 20, 2020
20-jul-2020
20jul2020

7/20
jul 20

day month year
day month
month day year
day-month-year

month day

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

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

1 year
1 year ago
3 years
2 days

$ date -R
Thu, 31 Jul 2020 13:02:39 -0400
$ 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!

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

$ TZ="<+0530>-5:30" date --date='TZ="<-07>+7" 2022-07-12 21:50'
Wed Jul 13 10:20:00 +0530 2022

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 (see Examples).

• Header
• Initialization
• Version Check
• Building the source
• Autoconf tests

#include <shishi.h>

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

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

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

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

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)

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.2 Initialization Functions ¶

shishi ¶

Function: Shishi * shishi () ¶

Description: Initializes the Shishi library, and primes logging so that future warnings and informational messages are printed on stderr. If this function fails, it may send its own diagnostic errors to stderr.

Return value: Returns a Shishi library handle, or NULL on error.

shishi_server ¶

Function: Shishi * shishi_server () ¶

Description: Initializes the Shishi library, and primes logging so that future warnings and informational messages are sent to the syslog system. If this function fails, it may print diagnostic errors in the syslog.

Return value: Returns a Shishi library handle, or NULL on error.

shishi_done ¶

Function: void shishi_done (Shishi * handle) ¶

handle: Shishi handle as allocated by shishi_init().

Description: Deallocates the Shishi library handle. The handle must not be used in any call to a shishi function after an execution of shishi_done().

If there is a default tkts, it is written to the default tkts file. If you do not wish to write the default tkts file, close the default file before calling this function. It is closed with a simple shishi_tkts_done(handle, NULL). For related information, see shishi_tkts_default_file_set().

shishi_init ¶

Function: int shishi_init (Shishi ** handle) ¶

handle: Pointer to a Shishi handle created by this call.

Description: Creates a Shishi library handle, using shishi(), and reads 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 value. The single exception being SHISHI_HANDLE_ERROR, which indicates a problem in allocating the handle. Other error conditions could arise while reading 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 a Shishi handle created by this call.
tktsfile: Filename of ticket file, or NULL.
systemcfgfile: Filename of system configuration, or NULL.
usercfgfile: Filename of user configuration, or NULL.

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

The handle is allocated regardless of return value. The single exception being SHISHI_HANDLE_ERROR, which indicates a problem in allocating the handle. Other error conditions could arise while reading files.

Return value: Returns SHISHI_OK iff successful.

shishi_init_server ¶

Function: int shishi_init_server (Shishi ** handle) ¶

handle: Pointer to a Shishi handle created by this call.

Description: Creates a Shishi library handle, using shishi_server(), and reads the system configuration file. The path to the system configuration file is decided at compile time, and is sysconfdir/shishi.conf.

The handle is allocated regardless of return value. The single exception being SHISHI_HANDLE_ERROR, which indicates a problem in allocating the handle. Other error conditions could arise while 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 a Shishi handle created by this call.
systemcfgfile: Filename of system configuration, or NULL.

Description: Creates a Shishi library handle, using shishi_server(), and reads the system configuration file from the specified location. The path to the system configuration file is decided at compile time, and is sysconfdir/shishi.conf.

The handle is allocated regardless of return value. The single exception being SHISHI_HANDLE_ERROR, which indicates a problem in allocating the handle. Other error conditions could arise while 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 created by shishi_init().
option: String containing shishi library options.

Description: Configures the shishi library according to the options given in option.

Return value: Returns SHISHI_OK if option is valid and configuration was successful.

shishi_cfg_from_file ¶

Function: int shishi_cfg_from_file (Shishi * handle, const char * cfg) ¶

handle: Shishi library handle created by shishi_init().
cfg: Name of configuration file.

Description: Configures the shishi library using a configuration file located at cfg.

Return value: Returns SHISHI_OK if successful.

shishi_cfg_print ¶

Function: int shishi_cfg_print (Shishi * handle, FILE * fh) ¶

handle: Shishi library handle created by shishi_init().
fh: File stream handle opened for writing.

Description: Prints library configuration status to fh. This function is mostly intended for debugging purposes.

Return value: Always returns SHISHI_OK.

shishi_cfg_default_systemfile ¶

Function: const char * shishi_cfg_default_systemfile (Shishi * handle) ¶

handle: Shishi library handle created by shishi_init().

Description: The system configuration file name is decided at compile time, but is replaced by assigning another file name to the environment variable SHISHI_CONFIG. This call offers a single interface for determining the file name, to which the library turns for its settings.

Return value: Returns file name of present system configuration.

shishi_cfg_default_userdirectory ¶

Function: const char * shishi_cfg_default_userdirectory (Shishi * handle) ¶

handle: Shishi library handle created by shishi_init().

Description: The default user directory, referred to for Shishi ticket cache and other purposes, is normally computed by appending the fixed string "/.shishi" to the content of the environment variable HOME.

This hard coded directory, i.e., "HOME/.shishi/", can be replaced by whatever complete path is stored in the environment variable SHISHI_HOME.

Return value: Returns the user’s directory name where the Shishi library will search for configuration files, ticket caches, etcetera.

shishi_cfg_userdirectory_file ¶

Function: char * shishi_cfg_userdirectory_file (Shishi * handle, const char * file) ¶

handle: Shishi library handle created by shishi_init().
file: Basename of file to use for the user’s configuration settings of the library.

Description: Reports the full path to the file where the Shishi library expects to find the user’s library configuration, given that the file itself is named by the parameter file.

The answer is composed from the value of file and the directory returned by shishi_cfg_default_userdirectory(). Typically, the returned string would be expanded from "HOME/.shishi/file".

Return value: Returns the absolute filename to the argument file, relative to the user specific Shishi configuration directory.

shishi_cfg_default_userfile ¶

Function: const char * shishi_cfg_default_userfile (Shishi * handle) ¶

handle: Shishi library handle created by shishi_init().

Description: Reports the absolute filename of the default user configuration file. This is typically "HOME/.shishi/shishi.conf".

The value of SHISHI_HOME will change the directory part, as stated regarding shishi_cfg_default_userdirectory().

Return value: Returns the user’s configuration filename.

shishi_cfg_clientkdcetype ¶

Function: int shishi_cfg_clientkdcetype (Shishi * handle, int32_t ** etypes) ¶

handle: Shishi library handle created by shishi_init().
etypes: Pointer to an array of encryption types.

Description: Sets the variable etypes to a static array of preferred encryption types applicable to clients.

Return value: Returns the number of encryption types referred to by the updated array pointer, or zero, should no type exist.

shishi_cfg_clientkdcetype_fast ¶

Function: int32_t shishi_cfg_clientkdcetype_fast (Shishi * handle) ¶

handle: Shishi library handle created by shishi_init().

Description: Extracts the default encryption type from the list of preferred encryption types acceptable to the client.

When the preferred list is empty, SHISHI_AES256_CTS_HMAC_SHA1_96 is returned as a sensible default type.

Return value: Returns the default encryption type.

shishi_cfg_clientkdcetype_set ¶

Function: int shishi_cfg_clientkdcetype_set (Shishi * handle, char * value) ¶

handle: Shishi library handle created by shishi_init().
value: String naming acceptable encryption types.

Description: Sets the configuration option "client-kdc-etypes" from value. The string contains encryption types, integers or names, separated by comma or by whitespace. An example naming three encryption types could be:

aes256-cts-hmac-sha1-96 des3-cbc-sha1-kd des-cbc-md5

Return value: Returns SHISHI_OK if successful, and SHISHI_INVALID_ARGUMENT otherwise.

shishi_cfg_authorizationtype_set ¶

Function: int shishi_cfg_authorizationtype_set (Shishi * handle, char * value) ¶

handle: Shishi library handle created by shishi_init().
value: String listing acceptable authorization types.

Description: Sets the configuration option "authorization-types" from value. The string contains authorization types, integers or names, separated by comma or whitespace.

As an example, "k5login basic" would first check Kerberos5 authentication based on preset principals, and then fall back to the basic test of identical principal names.

Return value: Returns SHISHI_OK if successful, and SHISHI_INVALID_ARGUMENT otherwise.

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 (see AS Functions) or subsequent authentication (see TGS Functions) and storing the new ticket in the ticket set are also provided.

See Ticket Functions, to manipulate each individual ticket. See 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().

Description: 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().

Description: 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.

Description: 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().

Description: 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.

Description: 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().

Description: 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().

Description: 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.

Description: 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.

Description: 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.

Description: 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.

Description: 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.

Description: 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.

Description: 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().

Description: 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.

Description: 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.

Description: 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.

Description: 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.

Description: 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.

Description: 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.

Description: 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.

Description: 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.

Description: 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.

Description: 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.

Description: 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.

Description: 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.

Description: 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.

Description: 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.

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 (see 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

Description: 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.

Description: 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

Description: 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

Description: 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.

Description: 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.

Description: 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.

Description: 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.

Description: 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.

Description: 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.

Description: 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.

Description: 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.

Description: 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.

Description: 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

Description: 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.

Description: 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.

Description: 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.

Description: 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.

Description: 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

Description: 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.

Description: 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

Description: 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.

Description: 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

Description: 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.

Description: 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.

Description: 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.

Description: 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

Description: 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

Description: 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.

Description: 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.

Description: 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.

Description: 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

Description: 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

Description: 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.

Description: 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.

Description: 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.

Description: 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

Description: 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.

Description: 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

Description: 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.

Description: 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.

Description: 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

Description: 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.

Description: 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.

Description: 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".

Description: 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().

Description: 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.

Description: 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.

Description: 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.

Description: 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.

Description: 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.

Description: 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.

Description: 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.

Description: 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().

Description: 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.

Description: 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.

Description: 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().

Description: 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().

Description: 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.

Description: 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.

Description: 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.

Description: 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.

Description: 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.

Description: 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().

Description: 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.

Description: 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.

Description: 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.

Description: 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.

Description: 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.

Description: 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.

Description: 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.

Description: 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().

Description: 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.

Description: 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.

Description: 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.

Description: 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.

Description: 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.

Description: 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.

Description: 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.

Description: 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.

Description: 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.

Description: 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.

Description: 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.

Description: 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.

Description: 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().

Description: 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.

Description: 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.

Description: Copy time fields from Authenticator into EncAPRepPart.

Return value: Returns SHISHI_OK iff successful.

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 (see 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

Description: 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

Description: 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

Description: 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.

Description: 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

Description: 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.

Description: 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.

Description: 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.

Description: 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.

Description: 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.

Description: 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.

Description: 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.

Description: 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.

Description: 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.

Description: 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.

Description: 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.

Description: 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.

Description: 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.

Description: 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.

Description: 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.

Description: 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 (see 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

Description: 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

Description: 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

Description: 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.

Description: 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

Description: 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.

Description: 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.

Description: 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.

Description: 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

Description: 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.

Description: 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.

Description: 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.

Description: 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.

Description: 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.

Description: 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.

Description: 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.

Description: 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.

Description: 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.

Description: 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.

Description: 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.

Description: 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.

Description: 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.

Description: 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.

Description: 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.

Description: 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.

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. See 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.

Description: 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.

Description: 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.

Description: 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.

Description: 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.

Description: 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.

Description: 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.

Description: Set the EncKDCRepPart in the Ticket.

shishi_tkt_kdcrep ¶

Function: Shishi_asn1 shishi_tkt_kdcrep (Shishi_tkt * tkt) ¶

tkt: input variable with ticket info.

Description: 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.

Description: 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.

Description: Set the EncTicketPart in the Ticket.

shishi_tkt_key ¶

Function: Shishi_key * shishi_tkt_key (Shishi_tkt * tkt) ¶

tkt: input variable with ticket info.

Description: 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.

Description: 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).

Description: 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.

Description: 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).

Description: 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.

Description: Determine if ticket is for specified client principal.

Return value: Returns non-0 iff ticket is for specified client principal.