GNU Shishi 1.0.3
GNU Shishi 1.0.3
Table of Contents
1 Introduction
1.1 Getting Started
1.2 Features and Status
1.3 Overview
1.4 Cryptographic Overview
1.5 Supported Platforms
1.6 Getting help
1.7 Downloading and Installing
1.8 Bug Reports
1.9 Contributing
2 User Manual
2.1 Proxiable and Proxy Tickets
2.2 Forwardable and Forwarded Tickets
3 Administration Manual
3.1 Introduction to Shisa
3.2 Configuring Shisa
3.3 Using Shisa
3.4 Starting Shishid
3.5 Configuring DNS for KDC
3.5.1 DNS vs. Kerberos - Case Sensitivity of Realm Names
3.5.2 Overview - KDC location information
3.5.3 Example - KDC location information
3.5.4 Security considerations
3.6 Kerberos via TLS
3.6.1 Setting up TLS resume
3.6.2 Setting up Anonymous TLS
3.6.3 Setting up X.509 authenticated TLS
3.6.3.1 Create a Kerberos Certificate Authority
3.6.3.2 Create a Kerberos KDC Certificate
3.6.3.3 Create a Kerberos Client Certificate
3.6.3.4 Starting KDC with X.509 authentication support
3.7 Multiple servers
3.8 Developer information
4 Reference Manual
4.1 Environmental Assumptions
4.2 Glossary of terms
4.3 Realm and Principal Naming
4.3.1 Realm Names
4.3.2 Principal Names
4.3.2.1 Name of server principals
4.3.2.2 Name of the TGS
4.3.3 Choosing a principal with which to communicate
4.3.4 Principal Name Form
4.4 Shishi Configuration
4.4.1 ‘
default-realm
4.4.2 ‘
default-principal
4.4.3 ‘
client-kdc-etypes
4.4.4 ‘
verbose
’, ‘
verbose-asn1
’, ‘
verbose-noise
’, ‘
verbose-crypto
’, ‘
verbose-crypto-noise
4.4.5 ‘
realm-kdc
4.4.6 ‘
server-realm
4.4.7 ‘
kdc-timeout
’, ‘
kdc-retries
4.4.8 ‘
stringprocess
4.4.9 ‘
ticket-life
4.4.10 ‘
renew-life
4.5 Shisa Configuration
4.5.1 ‘
db
4.6 Parameters for shishi
4.7 Parameters for shishid
4.8 Parameters for shisa
4.9 Environment variables
4.10 Date input formats
4.10.1 General date syntax
4.10.2 Calendar date items
4.10.3 Time of day items
4.10.4 Time zone items
4.10.5 Combined date and time of day items
4.10.6 Day of week items
4.10.7 Relative items in date strings
4.10.8 Pure numbers in date strings
4.10.9 Seconds since the Epoch
4.10.10 Specifying time zone rules
4.10.11 Authors of
parse_datetime
5 Programming Manual
5.1 Preparation
5.1.1 Header
5.1.2 Initialization
5.1.3 Version Check
5.1.4 Building the source
5.1.5 Autoconf tests
5.1.5.1 Autoconf test via ‘
pkg-config
5.1.5.2 Standalone Autoconf test using Libtool
5.1.5.3 Standalone Autoconf test
5.2 Initialization Functions
5.3 Ticket Set Functions
5.4 AP-REQ and AP-REP Functions
5.5 SAFE and PRIV Functions
5.6 Ticket Functions
5.7 AS Functions
5.8 TGS Functions
5.9 Ticket (ASN.1) Functions
5.10 AS/TGS Functions
5.11 Authenticator Functions
5.12 KRB-ERROR Functions
5.13 Cryptographic Functions
5.14 X.509 Functions
5.15 Utility Functions
5.16 ASN.1 Functions
5.17 Error Handling
5.17.1 Error Values
5.17.2 Error Functions
5.18 Examples
5.19 Kerberos Database Functions
5.20 Generic Security Service
6 Acknowledgements
Appendix A Criticism of Kerberos
Appendix B Protocol Extensions
B.1 STARTTLS protected KDC exchanges
B.1.1 TCP/IP transport with TLS upgrade (STARTTLS)
B.1.2 Extensible typed hole based on reserved high bit
B.1.3 STARTTLS requested by client (extension mode 1)
B.1.4 STARTTLS request accepted by server (extension mode 2)
B.1.5 Proceeding after successful TLS negotiation
B.1.6 Proceeding after failed TLS negotiation
B.1.7 Interaction with KDC addresses in DNS
B.1.8 Using TLS authentication logic in Kerberos
B.1.9 Security considerations
B.2 Telnet encryption with AES-CCM
B.2.1 Command Names and Codes
B.2.2 Command Meanings
B.2.3 Implementation Rules
B.2.4 Integration with the AUTHENTICATION telnet option
B.2.5 Security Considerations
B.2.5.1 Telnet Encryption Protocol Security Considerations
B.2.5.2 AES-CCM Security Considerations
B.2.6 Acknowledgments
B.3 Kerberized rsh and rlogin
B.3.1 Establish connection
B.3.2 Kerberos identification
B.3.3 Kerberos authentication
B.3.4 Extended authentication
B.3.5 Window size
B.3.6 End of authentication
B.3.7 Encryption
B.3.8 KCMDV0.3
B.3.9 MIT/Heimdal authorization
B.4 Key as initialization vector
B.5 The Keytab Binary File Format
B.6 The Credential Cache Binary File Format
Appendix C Copying Information
C.1 GNU Free Documentation License
Function and Data Index
Concept Index
Next:
Introduction
, Up:
(dir)
Contents
][
Index
Shishi
This manual is last updated 7 August 2022 for version
1.0.3 of Shishi.
Copyright © 2002–2022 Simon Josefsson.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
copy of the license is included in the section entitled “GNU Free
Documentation License”.
Introduction
How to use this manual.
User Manual
Using Shishi as end-user.
Administration Manual
Administrating server aspects of Shishi.
Reference Manual
Detailed description of config files, etc.
Programming Manual
Calling Shishi from a programming language.
Acknowledgements
Whom to blame.
Appendices
Criticism of Kerberos
Why you maybe shouldn’t use Kerberos.
Protocol Extensions
Description of protocol extensions used.
Copying Information
How you can copy and share Shishi.
Indices
Function and Data Index
Index of functions, variables and data types.
Concept Index
Index of concepts and programs.
Next:
User Manual
, Previous:
Top
, Up:
Top
Contents
][
Index
1 Introduction
Shishi implements the Kerberos network authentication system. Shishi
can be used to authenticate users in distributed systems, and is most
often used via GSS-API for SSH or via SASL for IMAP/POP3.
Shishi contains a library (’libshishi’) that can be used by application
developers to add support for Kerberos 5. There is also a command line
utility (’shishi’) that is used by users to acquire and manage tickets.
The server side, a Key Distribution Center, is implemented by ’shishid’.
Of course, a manual documenting usage aspects as well as the programming
API is included.
Shishi currently supports AS/TGS exchanges for acquiring tickets,
pre-authentication, the AP exchange for performing client and server
authentication, and SAFE/PRIV for integrity/privacy protected
application data exchanges.
Shishi is internationalized; error and status messages can be translated
into the users’ language; user name and passwords can be converted into
any available character set (normally including ISO-8859-1 and UTF-8)
and also be processed using an experimental Stringprep profile.
Most, if not all, of the widely used encryption and checksum types are
supported, such as 3DES, AES, ARCFOUR and HMAC-SHA1.
Shishi is developed for the GNU/Linux system but works on many platforms
including most major Unix and Windows systems.
Shishi is free software licensed under the GNU General Public License
version 3.0 or later.
Getting Started
Features and Status
Overview
Cryptographic Overview
Supported Platforms
Getting help
Downloading and Installing
Bug Reports
Contributing
Next:
Features and Status
, Up:
Introduction
Contents
][
Index
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.
Next:
Overview
, Previous:
Getting Started
, Up:
Introduction
Contents
][
Index
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.
Next:
Cryptographic Overview
, Previous:
Features and Status
, Up:
Introduction
Contents
][
Index
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.
Next:
Supported Platforms
, Previous:
Overview
, Up:
Introduction
Contents
][
Index
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
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
Next:
Getting help
, Previous:
Cryptographic Overview
, Up:
Introduction
Contents
][
Index
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
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
Debian GNU/Linux 2.1
GCC 2.95.4 and GNU Make.
armv4l-unknown-linux-gnu
Tru64 UNIX
Tru64 UNIX C compiler and Tru64 Make.
alphaev67-dec-osf5.1
alphaev68-dec-osf5.1
SuSE Linux 7.1
GCC 2.96 and GNU Make.
alphaev6-unknown-linux-gnu
alphaev67-unknown-linux-gnu
SuSE Linux 7.2a
GCC 3.0 and GNU Make.
ia64-unknown-linux-gnu
SuSE Linux
GCC 3.2.2 and GNU Make.
x86_64-unknown-linux-gnu
(AMD64
Opteron “Melody”).
RedHat Linux 7.2
GCC 2.96 and GNU Make.
alphaev6-unknown-linux-gnu
alphaev67-unknown-linux-gnu
ia64-unknown-linux-gnu
RedHat Linux 8.0
GCC 3.2 and GNU Make.
i686-pc-linux-gnu
RedHat Advanced Server 2.1
GCC 2.96 and GNU Make.
i686-pc-linux-gnu
Slackware Linux 8.0.01
GCC 2.95.3 and GNU Make.
i686-pc-linux-gnu
Mandrake Linux 9.0
GCC 3.2 and GNU Make.
i686-pc-linux-gnu
IRIX 6.5
MIPS C compiler, IRIX Make.
mips-sgi-irix6.5
AIX 4.3.2
IBM C for AIX compiler, AIX Make.
rs6000-ibm-aix4.3.2.0
HP-UX 11
HP-UX C compiler and HP Make.
ia64-hp-hpux11.22
hppa2.0w-hp-hpux11.11
SUN Solaris 2.8
Sun WorkShop Compiler C 6.0 and SUN Make.
sparc-sun-solaris2.8
NetBSD 1.6
GCC 2.95.3 and GNU Make.
alpha-unknown-netbsd1.6
i386-unknown-netbsdelf1.6
OpenBSD 3.1 and 3.2
GCC 2.95.3 and GNU Make.
alpha-unknown-openbsd3.1
i386-unknown-openbsd3.1
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
MacOS X 10.2 Server Edition
GCC 3.1 and GNU Make.
powerpc-apple-darwin6.5
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
).
Next:
Downloading and Installing
, Previous:
Supported Platforms
, Up:
Introduction
Contents
][
Index
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
Next:
Bug Reports
, Previous:
Getting help
, Up:
Introduction
Contents
][
Index
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
Next:
Contributing
, Previous:
Downloading and Installing
, Up:
Introduction
Contents
][
Index
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:
bug-shishi@josefsson.org
Previous:
Bug Reports
, Up:
Introduction
Contents
][
Index
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
(standards)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
(indent)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.
Next:
Administration Manual
, Previous:
Introduction
, Up:
Top
Contents
][
Index
2 User Manual
Usually Shishi interacts with you to get some initial authentication
information like a password, and then contacts a server to receive a
so called ticket granting ticket. From now on, you rarely interact
with Shishi directly. Applications that need security services
instruct the Shishi library to use the ticket granting ticket to get
new tickets for various servers. An example could be if you log on to
a host remotely via ‘
telnet
’. The host usually requires
authentication before permitting you in. The ‘
telnet
’ client
uses the ticket granting ticket to get a ticket for the server, and
then uses this ticket to authenticate you against the server (typically
the server is also authenticated to you). You perform the initial
authentication by typing
shishi
at the prompt. Sometimes it
is necessary to supply options telling Shishi what your principal name
(user name in the Kerberos realm) or your realm is. In the example, I
specify the client name
simon@JOSEFSSON.ORG
$ shishi simon@JOSEFSSON.ORG
Enter password for `simon@JOSEFSSON.ORG':
simon@JOSEFSSON.ORG:
Authtime: Fri Aug 15 04:44:49 2003
Endtime: Fri Aug 15 05:01:29 2003
Server: krbtgt/JOSEFSSON.ORG key des3-cbc-sha1-kd (16)
Ticket key: des3-cbc-sha1-kd (16) protected by des3-cbc-sha1-kd (16)
Ticket flags: INITIAL (512)
As you can see, Shishi also prints a short description of the ticket
received.
A logical next step is to display all tickets you have received.
By the way, the tickets are usually stored as text in
~/.shishi/tickets
. This is achieved by typing
shishi --list
$ shishi --list
Tickets in `/home/jas/.shishi/tickets':
jas@JOSEFSSON.ORG:
Authtime: Fri Aug 15 04:49:46 2003
Endtime: Fri Aug 15 05:06:26 2003
Server: krbtgt/JOSEFSSON.ORG key des-cbc-md5 (3)
Ticket key: des-cbc-md5 (3) protected by des-cbc-md5 (3)
Ticket flags: INITIAL (512)
jas@JOSEFSSON.ORG:
Authtime: Fri Aug 15 04:49:46 2003
Starttime: Fri Aug 15 04:49:49 2003
Endtime: Fri Aug 15 05:06:26 2003
Server: host/latte.josefsson.org key des-cbc-md5 (3)
Ticket key: des-cbc-md5 (3) protected by des-cbc-md5 (3)
2 tickets found.
As you can see, I had a ticket for the server
host/latte.josefsson.org
’ which was generated by
telnet
’:ing to that host.
If, for some reason, you want to manually get a ticket for a specific
server, you can use the
shishi --server-name
command.
Normally, however, the application that uses Shishi will take care of
getting a ticket for the appropriate server, so you normally wouldn’t
need to issue this command.
$ shishi --server-name=user/billg --encryption-type=des-cbc-md4
jas@JOSEFSSON.ORG:
Authtime: Fri Aug 15 04:49:46 2003
Starttime: Fri Aug 15 04:54:33 2003
Endtime: Fri Aug 15 05:06:26 2003
Server: user/billg key des-cbc-md4 (2)
Ticket key: des-cbc-md4 (2) protected by des-cbc-md5 (3)
As you can see, I acquired a ticket for ‘
user/billg
’ with a
des-cbc-md4
’ (see
Cryptographic Overview
) encryption key
specified with the ‘
--encryption-type
’ parameter.
To wrap up this introduction, let us see how you can remove tickets.
You may want to do this if you leave your terminal for lunch or
similar, and don’t want someone to be able to copy the file and then
use your credentials. Note that this only destroys the tickets
locally, it does not contact any server telling that these
credentials are no longer valid. So, if someone stole your ticket
file, you must still contact your administrator and have them reset your
account. Simply using this switch is not sufficient.
$ shishi --server-name=imap/latte.josefsson.org --destroy
1 ticket removed.
$ shishi --server-name=foobar --destroy
No tickets removed.
$ shishi --destroy
3 tickets removed.
Since the ‘
--server-name
’ parameter takes a long string to type,
it is possible to type the server name directly, after the client name.
The following example demonstrates an AS-REQ followed by a TGS-REQ for a
specific server (assuming you did not have any tickets to begin with).
$ src/shishi simon@latte.josefsson.org imap/latte.josefsson.org
Enter password for `simon@latte.josefsson.org':
simon@latte.josefsson.org:
Acquired: Wed Aug 27 17:21:06 2003
Expires: Wed Aug 27 17:37:46 2003
Server: imap/latte.josefsson.org key aes256-cts-hmac-sha1-96 (18)
Ticket key: aes256-cts-hmac-sha1-96 (18) protected by aes256-cts-hmac-sha1-96 (18)
Ticket flags: FORWARDED PROXIABLE (12)
Refer to the reference manual for all available parameters
(see
Parameters for shishi
). The rest of this section contains
descriptions of more specialized usage modes that can be ignored by
most users.
2.1 Proxiable and Proxy Tickets
At times it may be necessary for a principal to allow a service to
perform an operation on its behalf. The service must be able to take
on the identity of the client, but only for a particular purpose. A
principal can allow a service to take on the principal’s identity for
a particular purpose by granting it a proxy.
The process of granting a proxy using the proxy and proxiable flags is
used to provide credentials for use with specific services. Though
conceptually also a proxy, users wishing to delegate their identity in
a form usable for all purpose MUST use the ticket forwarding mechanism
described in the next section to forward a ticket-granting ticket.
The PROXIABLE flag in a ticket is normally only interpreted by the
ticket-granting service. It can be ignored by application servers.
When set, this flag tells the ticket-granting server that it is OK to
issue a new ticket (but not a ticket-granting ticket) with a different
network address based on this ticket. This flag is set if requested by
the client on initial authentication. By default, the client will
request that it be set when requesting a ticket-granting ticket, and
reset when requesting any other ticket.
This flag allows a client to pass a proxy to a server to perform a
remote request on its behalf (e.g. a print service client can give the
print server a proxy to access the client’s files on a particular file
server in order to satisfy a print request).
In order to complicate the use of stolen credentials, Kerberos tickets
are usually valid from only those network addresses specifically
included in the ticket[4]. When granting a proxy, the client MUST
specify the new network address from which the proxy is to be used, or
indicate that the proxy is to be issued for use from any address.
The PROXY flag is set in a ticket by the TGS when it issues a proxy
ticket. Application servers MAY check this flag and at their option
they MAY require additional authentication from the agent presenting
the proxy in order to provide an audit trail.
Here is how you would acquire a PROXY ticket for the service
imap/latte.josefsson.org
’:
$ shishi jas@JOSEFSSON.ORG imap/latte.josefsson.org --proxy
Enter password for `jas@JOSEFSSON.ORG':
libshishi: warning: KDC bug: Reply encrypted using wrong key.
jas@JOSEFSSON.ORG:
Authtime: Mon Sep 8 20:02:35 2003
Starttime: Mon Sep 8 20:02:36 2003
Endtime: Tue Sep 9 04:02:35 2003
Server: imap/latte.josefsson.org key des3-cbc-sha1-kd (16)
Ticket key: des3-cbc-sha1-kd (16) protected by des3-cbc-sha1-kd (16)
Ticket flags: PROXY (16)
As you noticed, this asked for your password. The reason is that
proxy tickets must be acquired using a proxiable ticket granting
ticket, which was not present. If you often need to get proxy
tickets, you may acquire a proxiable ticket granting ticket from the
start:
$ shishi --proxiable
Enter password for `jas@JOSEFSSON.ORG':
jas@JOSEFSSON.ORG:
Authtime: Mon Sep 8 20:04:27 2003
Endtime: Tue Sep 9 04:04:27 2003
Server: krbtgt/JOSEFSSON.ORG key des3-cbc-sha1-kd (16)
Ticket key: des3-cbc-sha1-kd (16) protected by des3-cbc-sha1-kd (16)
Ticket flags: PROXIABLE INITIAL (520)
Then you should be able to acquire proxy tickets based on that ticket
granting ticket, as follows:
$ shishi jas@JOSEFSSON.ORG imap/latte.josefsson.org --proxy
libshishi: warning: KDC bug: Reply encrypted using wrong key.
jas@JOSEFSSON.ORG:
Authtime: Mon Sep 8 20:04:27 2003
Starttime: Mon Sep 8 20:04:32 2003
Endtime: Tue Sep 9 04:04:27 2003
Server: imap/latte.josefsson.org key des3-cbc-sha1-kd (16)
Ticket key: des3-cbc-sha1-kd (16) protected by des3-cbc-sha1-kd (16)
Ticket flags: PROXY (16)
2.2 Forwardable and Forwarded Tickets
Authentication forwarding is an instance of a proxy where the service
that is granted is complete use of the client’s identity. An example
where it might be used is when a user logs in to a remote system and
wants authentication to work from that system as if the login were
local.
The FORWARDABLE flag in a ticket is normally only interpreted by the
ticket-granting service. It can be ignored by application servers.
The FORWARDABLE flag has an interpretation similar to that of the
PROXIABLE flag, except ticket-granting tickets may also be issued with
different network addresses. This flag is reset by default, but users
MAY request that it be set by setting the FORWARDABLE option in the AS
request when they request their initial ticket-granting ticket.
This flag allows for authentication forwarding without requiring the
user to enter a password again. If the flag is not set, then
authentication forwarding is not permitted, but the same result can
still be achieved if the user engages in the AS exchange specifying
the requested network addresses and supplies a password.
The FORWARDED flag is set by the TGS when a client presents a ticket
with the FORWARDABLE flag set and requests a forwarded ticket by
specifying the FORWARDED KDC option and supplying a set of addresses
for the new ticket. It is also set in all tickets issued based on
tickets with the FORWARDED flag set. Application servers may choose to
process FORWARDED tickets differently than non-FORWARDED tickets.
If addressless tickets are forwarded from one system to another,
clients SHOULD still use this option to obtain a new TGT in order to
have different session keys on the different systems.
Here is how you would acquire a FORWARDED ticket for the service
host/latte.josefsson.org
’:
$ shishi jas@JOSEFSSON.ORG host/latte.josefsson.org --forwarded
Enter password for `jas@JOSEFSSON.ORG':
libshishi: warning: KDC bug: Reply encrypted using wrong key.
jas@JOSEFSSON.ORG:
Authtime: Mon Sep 8 20:07:11 2003
Starttime: Mon Sep 8 20:07:12 2003
Endtime: Tue Sep 9 04:07:11 2003
Server: host/latte.josefsson.org key des3-cbc-sha1-kd (16)
Ticket key: des3-cbc-sha1-kd (16) protected by des3-cbc-sha1-kd (16)
Ticket flags: FORWARDED (4)
As you noticed, this asked for your password. The reason is that
forwarded tickets must be acquired using a forwardable ticket granting
ticket, which was not present. If you often need to get forwarded
tickets, you may acquire a forwardable ticket granting ticket from the
start:
$ shishi --forwardable
Enter password for `jas@JOSEFSSON.ORG':
jas@JOSEFSSON.ORG:
Authtime: Mon Sep 8 20:08:53 2003
Endtime: Tue Sep 9 04:08:53 2003
Server: krbtgt/JOSEFSSON.ORG key des3-cbc-sha1-kd (16)
Ticket key: des3-cbc-sha1-kd (16) protected by des3-cbc-sha1-kd (16)
Ticket flags: FORWARDABLE INITIAL (514)
Then you should be able to acquire forwarded tickets based on that
ticket granting ticket, as follows:
$ shishi jas@JOSEFSSON.ORG host/latte.josefsson.org --forwarded
libshishi: warning: KDC bug: Reply encrypted using wrong key.
jas@JOSEFSSON.ORG:
Authtime: Mon Sep 8 20:08:53 2003
Starttime: Mon Sep 8 20:08:57 2003
Endtime: Tue Sep 9 04:08:53 2003
Server: host/latte.josefsson.org key des3-cbc-sha1-kd (16)
Ticket key: des3-cbc-sha1-kd (16) protected by des3-cbc-sha1-kd (16)
Ticket flags: FORWARDED (4)
Next:
Reference Manual
, Previous:
User Manual
, Up:
Top
Contents
][
Index
3 Administration Manual
Here you will learn how to set up, run and maintain the Shishi
Kerberos server. Kerberos is incompatible with the standard Unix
/etc/passwd
password database
, therefore the first
step will be to create a Kerberos user database. Shishi’s user
database system is called Shisa. Once Shisa has been configured, you can
then start the server and begin issuing Kerberos tickets to your
users. The Shishi server is called
shishid
. After getting the
server up and running, we discuss how you can set up multiple Kerberos
servers, to increase availability or offer load-balancing. Finally,
we include some information intended for developers, that will enable
you to customize Shisa to use an external user database, such as a
LDAP server or SQL database.
Introduction to Shisa
Explanation of the Shishi user database.
Configuring Shisa
Define the user database in Shisa.
Using Shisa
How to add realms and principals to database.
Starting Shishid
Issue Kerberos tickets to your users.
Configuring DNS for KDC
Placing the KDC address in DNS is useful.
Kerberos via TLS
How to setup Shishi to use TLS.
Multiple servers
High availability and load-balancing.
Developer information
Writing your own Shisa database backend.
Next:
Configuring Shisa
, Up:
Administration Manual
Contents
][
Index
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.
Next:
Using Shisa
, Previous:
Introduction to Shisa
, Up:
Administration Manual
Contents
][
Index
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.
Next:
Starting Shishid
, Previous:
Configuring Shisa
, Up:
Administration Manual
Contents
][
Index
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
).
Next:
Configuring DNS for KDC
, Previous:
Using Shisa
, Up:
Administration Manual
Contents
][
Index
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
Next:
Kerberos via TLS
, Previous:
Starting Shishid
, Up:
Administration Manual
Contents
][
Index
3.5 Configuring DNS for KDC
Making sure the configuration files on all hosts running Shishi
clients include the addresses of your server is tedious. If the
configuration files do not mention the KDC address for a realm, Shishi
will try to look up the information from DNS. In order for Shishi to
find that information, you need to add the information to DNS. For
this to work well, you need to set up a DNS zone with the same name as
your Kerberos realm. The easiest is if you own the publicly visible
DNS name, such as ‘
example.org
’ if your realm is
EXAMPLE.ORG
’, but you can set up an internal DNS server with the
information for your realm only. If this is done, you do not need to
keep configuration files updated for the KDC addressing information.
3.5.1 DNS vs. Kerberos - Case Sensitivity of Realm Names
In Kerberos, realm names are case sensitive. While it is strongly
encouraged that all realm names be all upper case this recommendation
has not been adopted by all sites. Some sites use all lower case
names and other use mixed case. DNS on the other hand is case
insensitive for queries but is case preserving for responses to TXT
queries. Since "MYREALM", "myrealm", and "MyRealm" are all different
it is necessary that only one of the possible combinations of upper
and lower case characters be used. This restriction may be lifted in
the future as the DNS naming scheme is expanded to support non-ASCII
names.
3.5.2 Overview - KDC location information
KDC location information is to be stored using the DNS SRV RR [RFC
2052]. The format of this RR is as follows:
Service.Proto.Realm TTL Class SRV Priority Weight Port Target
The Service name for Kerberos is always "_kerberos".
The Proto can be either "_udp", "_tcp", or "_tls._tcp". If these SRV
records are to be used, a "_udp" record MUST be included. If the
Kerberos implementation supports TCP transport, a "_tcp" record MUST
be included. When using "_tcp" with "_kerberos", this indicates a
"raw" TCP connection without any additional encapsulation. A
"_tls._tcp" record MUST be specified for all Kerberos implementations
that support communication with the KDC across TCP sockets
encapsulated using TLS [RFC2246] (see
STARTTLS protected KDC exchanges
).
The Realm is the Kerberos realm that this record corresponds to.
TTL, Class, SRV, Priority, Weight, and Target have the standard
meaning as defined in RFC 2052.
As per RFC 2052 the Port number should be the value assigned to
"kerberos" by the Internet Assigned Number Authority (88).
3.5.3 Example - KDC location information
These are DNS records for a Kerberos realm ASDF.COM. It has two
Kerberos servers, kdc1.asdf.com and kdc2.asdf.com. Queries should be
directed to kdc1.asdf.com first as per the specified priority.
Weights are not used in these records.
_kerberos._udp.ASDF.COM. IN SRV 0 0 88 kdc1.asdf.com.
_kerberos._udp.ASDF.COM. IN SRV 1 0 88 kdc2.asdf.com.
_kerberos._tcp.ASDF.COM. IN SRV 0 0 88 kdc1.asdf.com.
_kerberos._tcp.ASDF.COM. IN SRV 1 0 88 kdc2.asdf.com.
_kerberos._tls._tcp.ASDF.COM. IN SRV 0 0 88 kdc1.asdf.com.
_kerberos._tls._tcp.ASDF.COM. IN SRV 1 0 88 kdc2.asdf.com.
3.5.4 Security considerations
As DNS is deployed today, it is an unsecure service. Thus the infor-
mation returned by it cannot be trusted.
Current practice for REALM to KDC mapping is to use hostnames to
indicate KDC hosts (stored in some implementation-dependent location,
but generally a local config file). These hostnames are vulnerable
to the standard set of DNS attacks (denial of service, spoofed
entries, etc). The design of the Kerberos protocol limits attacks of
this sort to denial of service. However, the use of SRV records does
not change this attack in any way. They have the same vulnerabilities
that already exist in the common practice of using hostnames for
KDC locations.
Implementations SHOULD provide a way of specifying this information
locally without the use of DNS. However, to make this feature
worthwhile a lack of any configuration information on a client should
be interpretted as permission to use DNS.
Next:
Multiple servers
, Previous:
Configuring DNS for KDC
, Up:
Administration Manual
Contents
][
Index
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
3.6.1 Setting up TLS resume
Resuming earlier TLS session is supported and enabled by default.
This improves the speed of the TLS handshake, because results from
earlier negotiations can be re-used. Currently the TLS resume
database is stored in memory (in constract to storing it on disk), in
both the client and in the server. Because the server typically runs
for a long time, this is not a problem for that side. The client is
typically not a long-running process though; the client usually is
invoked as part of applications like ‘
telnet
’ or ‘
’.
However, because each use of the client library typically result in a
ticket, which is stored on disk and re-used by later processes, this
is likely not a serious problem because the number of different
tickets required by a user is usually quite small. For the client,
TLS resume is typically only useful when you perform an initial
authentication (using a password) followed by a ticket request for a
service, in the same process.
You can configure the server, ‘
shishid
’ to never use TLS resume,
or to increase or decrease the number of distinct TLS connections that
can be resumed before they are garbage collected, see the
--resume-limit
’ parameter (see
Parameters for shishid
).
3.6.2 Setting up Anonymous TLS
Anonymous TLS is the simplest to set up and use. In fact, only the
client need to be informed that your KDC support TLS. This can be
done in the configuration file with the ‘
/tls
’ parameter for
kdc-realm
’ (see
Shishi Configuration
), or by
placing the KDC address in DNS using the ‘
_tls
’ SRV record
(see
Configuring DNS for KDC
).
Let’s start Shishid, listening on a TCP socket. TLS require TCP. TCP
sockets are automatically upgraded to TLS if the client request it.
jas@latte:~$ /usr/local/sbin/shishid -l IPv4:*:4711/tcp
Initializing GNUTLS...done
Listening on IPv4:*:4711/tcp...
Listening on 1 ports...
shishid: Starting (GNUTLS `1.0.4')
shishid: Listening on IPv4:*:4711/tcp socket 4
Let’s use the client to talk with it, using TLS.
jas@latte:~$ shishi -o 'realm-kdc=EXAMPLE.ORG,localhost:4711/tls \
simon@EXAMPLE.ORG
Enter password for `simon@EXAMPLE.ORG':
simon@EXAMPLE.ORG:
Authtime: Tue Dec 16 05:20:47 2003
Endtime: Tue Dec 16 05:37:27 2003
Server: krbtgt/EXAMPLE.ORG key aes256-cts-hmac-sha1-96 (18)
Ticket key: aes256-cts-hmac-sha1-96 (18) protected by aes256-cts-hmac-sha1-96 (18)
Ticket flags: FORWARDED PROXIABLE (12)
jas@latte:~$
On success, the server will print the following debug information.
shishid: Accepted socket 6 from socket 4 as IPv4:*:4711/tcp peer 127.0.0.1
shishid: Listening on IPv4:*:4711/tcp socket 4
shishid: Listening on IPv4:*:4711/tcp peer 127.0.0.1 socket 6
shishid: Has 4 bytes from IPv4:*:4711/tcp peer 127.0.0.1 on socket 6
shishid: Trying STARTTLS
shishid: TLS handshake negotiated protocol `TLS 1.0', key exchange `Anon DH', certficate type `X.509', cipher `AES 256 CBC', mac `SHA', compression `NULL', session not resumed
shishid: TLS anonymous authentication with 1024 bit Diffie-Hellman
shishid: Listening on IPv4:*:4711/tcp socket 4
shishid: Listening on IPv4:*:4711/tcp peer 127.0.0.1 socket 6
shishid: Has 131 bytes from IPv4:*:4711/tcp peer 127.0.0.1 on socket 6
shishid: Processing 131 from IPv4:*:4711/tcp peer 127.0.0.1 on socket 6
shishid: Trying AS-REQ
shishid: AS-REQ from simon@EXAMPLE.ORG for krbtgt/EXAMPLE.ORG@EXAMPLE.ORG
shishid: Matching client etype 18 against user key etype 18
shishid: Have 511 bytes for IPv4:*:4711/tcp peer 127.0.0.1 on socket 6
shishid: Sending 511 bytes to IPv4:*:4711/tcp peer 127.0.0.1 socket 6 via TLS
shishid: Listening on IPv4:*:4711/tcp socket 4
shishid: Listening on IPv4:*:4711/tcp peer 127.0.0.1 socket 6
shishid: Peer IPv4:*:4711/tcp peer 127.0.0.1 disconnected on socket 6
shishid: Closing IPv4:*:4711/tcp peer 127.0.0.1 socket 6
shishid: Listening on IPv4:*:4711/tcp socket 4
3.6.3 Setting up X.509 authenticated TLS
Setting up X.509 authentication is slightly more complicated than
anonymous authentication. You need a X.509 certificate authority
(CA) that can generate certificates for your Kerberos server
and Kerberos clients. It is often easiest to setup the CA
yourself. Managing a CA can be a daunting task, and we only
give the bare essentials to get things up and running. We suggest
that you study the relevant literature. As a first step beyond this
introduction, you may wish to explore more secure forms of key storage
than storing them unencrypted on disk.
The following three sections describe how you create the CA,
KDC certificate, and client certificates. You can use any tool you
like for this task, as long as they generate X.509 (PKIX) certificates
in PEM format and RSA keys in PKCS#1 format. Here we use
certtool
that come with GNUTLS, which is widely
available. We conclude by discussing how you use these certificates
in the KDC and in the Shishi client.
3.6.3.1 Create a Kerberos Certificate Authority
First create a CA key.
jas@latte:~$ certtool --generate-privkey \
--outfile /usr/local/etc/shishi/shishi.key
Generating a private key...
Generating a 1024 bit RSA private key...
jas@latte:~$
Then create the CA certificate. Use whatever details you
prefer.
jas@latte:~$ certtool --generate-self-signed \
--load-privkey /usr/local/etc/shishi/shishi.key \
--outfile /usr/local/etc/shishi/shishi.cert
Generating a self signed certificate...
Please enter the details of the certificate's distinguished name. \
Just press enter to ignore a field.
Country name (2 chars): SE
Organization name: Shishi Example CA
Organizational unit name:
Locality name:
State or province name:
Common name: CA
This field should not be used in new certificates.
E-mail:
Enter the certificate's serial number (decimal): 0
Activation/Expiration time.
The generated certificate will expire in (days): 180
Extensions.
Does the certificate belong to an authority? (Y/N): y
Is this a web server certificate? (Y/N): n
Enter the e-mail of the subject of the certificate:
X.509 certificate info:
Version: 3
Serial Number (hex): 00
Validity:
Not Before: Sun Dec 21 10:59:00 2003
Not After: Fri Jun 18 11:59:00 2004
Subject: C=SE,O=Shishi Example CA,CN=CA
Subject Public Key Info:
Public Key Algorithm: RSA
X.509 Extensions:
Basic Constraints: (critical)
CA:TRUE
Is the above information ok? (Y/N): y
Signing certificate...
jas@latte:~$
3.6.3.2 Create a Kerberos KDC Certificate
First create the key for the KDC.
jas@latte:~$ certtool --generate-privkey \
--outfile /usr/local/etc/shishi/shishid.key
Generating a private key...
Generating a 1024 bit RSA private key...
jas@latte:~$
Then create actual KDC certificate, signed by the CA
certificate created in the previous step.
jas@latte:~$ certtool --generate-certificate \
--load-ca-certificate /usr/local/etc/shishi/shishi.cert \
--load-ca-privkey /usr/local/etc/shishi/shishi.key \
--load-privkey /usr/local/etc/shishi/shishid.key \
--outfile /usr/local/etc/shishi/shishid.cert
Generating a signed certificate...
Loading CA's private key...
Loading CA's certificate...
Please enter the details of the certificate's distinguished name. \
Just press enter to ignore a field.
Country name (2 chars): SE
Organization name: Shishi Example KDC
Organizational unit name:
Locality name:
State or province name:
Common name: KDC
This field should not be used in new certificates.
E-mail:
Enter the certificate's serial number (decimal): 0
Activation/Expiration time.
The generated certificate will expire in (days): 180
Extensions.
Does the certificate belong to an authority? (Y/N): n
Is this a web server certificate? (Y/N): n
Enter the e-mail of the subject of the certificate:
X.509 certificate info:
Version: 3
Serial Number (hex): 00
Validity:
Not Before: Sun Dec 21 11:02:00 2003
Not After: Fri Jun 18 12:02:00 2004
Subject: C=SE,O=Shishi Example KDC,CN=KDC
Subject Public Key Info:
Public Key Algorithm: RSA
X.509 Extensions:
Basic Constraints: (critical)
CA:FALSE
Is the above information ok? (Y/N): y
Signing certificate...
jas@latte:~$
3.6.3.3 Create a Kerberos Client Certificate
First create the key for the client.
jas@latte:~$ certtool --generate-privkey \
--outfile ~/.shishi/client.key
Generating a private key...
Generating a 1024 bit RSA private key...
jas@latte:~$
Then create the client certificate, signed by the CA. An
alternative would be to have the KDC sign the client certificates.
jas@latte:~$ certtool --generate-certificate \
--load-ca-certificate /usr/local/etc/shishi/shishi.cert \
--load-ca-privkey /usr/local/etc/shishi/shishi.key \
--load-privkey ~/.shishi/client.key \
--outfile ~/.shishi/client.certs
Generating a signed certificate...
Loading CA's private key...
Loading CA's certificate...
Please enter the details of the certificate's distinguished name. \
Just press enter to ignore a field.
Country name (2 chars): SE
Organization name: Shishi Example Client
Organizational unit name:
Locality name:
State or province name:
Common name: Client
This field should not be used in new certificates.
E-mail:
Enter the certificate's serial number (decimal): 0
Activation/Expiration time.
The generated certificate will expire in (days): 180
Extensions.
Does the certificate belong to an authority? (Y/N): n
Is this a web server certificate? (Y/N): n
Enter the e-mail of the subject of the certificate:
X.509 certificate info:
Version: 3
Serial Number (hex): 00
Validity:
Not Before: Sun Dec 21 11:04:00 2003
Not After: Fri Jun 18 12:04:00 2004
Subject: C=SE,O=Shishi Example Client,CN=Client
Subject Public Key Info:
Public Key Algorithm: RSA
X.509 Extensions:
Basic Constraints: (critical)
CA:FALSE
Is the above information ok? (Y/N): y
Signing certificate...
jas@latte:~$
3.6.3.4 Starting KDC with X.509 authentication support
The KDC need the CA certificate (to verify client
certificates) and the server certificate and key (to authenticate
itself to the clients). See elsewhere (see
Parameters for shishid
) for the entire description of the parameters.
jas@latte:~$ shishid -l *:4711/tcp \
--x509cafile /usr/local/etc/shishi/shishi.cert \
--x509certfile /usr/local/etc/shishi/shishid.cert \
--x509keyfile /usr/local/etc/shishi/shishid.key
Initializing GNUTLS...
Parsed 1 CAs...
Loaded server certificate/key...
Generating Diffie-Hellman parameters...
Initializing GNUTLS...done
Listening on *:4711/tcp...
Listening on 1 ports...
shishid: Starting (GNUTLS `1.0.4')
shishid: Listening on *:4711/tcp socket 4
Then acquire tickets as usual. In case you wonder how shishi finds
the client certificate and key, the filenames used above when
generating the client certificates happen to be the default filenames
for these files. So it pick them up automatically.
jas@latte:~$ shishi -o 'realm-kdc=EXAMPLE.ORG,localhost:4711/tls' \
simon@EXAMPLE.ORG
Enter password for `simon@EXAMPLE.ORG':
simon@EXAMPLE.ORG:
Authtime: Sun Dec 21 11:15:47 2003
Endtime: Sun Dec 21 11:32:27 2003
Server: krbtgt/EXAMPLE.ORG key aes256-cts-hmac-sha1-96 (18)
Ticket key: aes256-cts-hmac-sha1-96 (18) protected by aes256-cts-hmac-sha1-96 (18)
Ticket flags: FORWARDED PROXIABLE RENEWABLE HWAUTHENT TRANSITEDPOLICYCHECKED OKASDELEGATE (12)
jas@latte:~$
Here is what the server would print.
shishid: Accepted socket 6 from socket 4 as *:4711/tcp peer 127.0.0.1
shishid: Listening on *:4711/tcp socket 4
shishid: Listening on *:4711/tcp peer 127.0.0.1 socket 6
shishid: Has 4 bytes from *:4711/tcp peer 127.0.0.1 on socket 6
shishid: Trying STARTTLS
shishid: TLS handshake negotiated protocol `TLS 1.0', key exchange `RSA', certficate type `X.509', cipher `AES 256 CBC', mac `SHA', compression `NULL', session not resumed
shishid: TLS client certificate `C=SE,O=Shishi Example Client,CN=Client', issued by `C=SE,O=Shishi Example CA,CN=CA', serial number `00', MD5 fingerprint `a5:d3:1f:58:76:e3:58:cd:2d:eb:f7:45:a2:4b:52:f9:', activated `Sun Dec 21 11:04:00 2003', expires `Fri Jun 18 12:04:00 2004', version #3, key RSA modulus 1024 bits, currently EXPIRED
shishid: Listening on *:4711/tcp socket 4
shishid: Listening on *:4711/tcp peer 127.0.0.1 socket 6
shishid: Has 131 bytes from *:4711/tcp peer 127.0.0.1 on socket 6
shishid: Processing 131 from *:4711/tcp peer 127.0.0.1 on socket 6
shishid: Trying AS-REQ
shishid: AS-REQ from simon@EXAMPLE.ORG for krbtgt/EXAMPLE.ORG@EXAMPLE.ORG
shishid: Matching client etype 18 against user key etype 18
shishid: Have 511 bytes for *:4711/tcp peer 127.0.0.1 on socket 6
shishid: Sending 511 bytes to *:4711/tcp peer 127.0.0.1 socket 6 via TLS
shishid: Listening on *:4711/tcp socket 4
shishid: Listening on *:4711/tcp peer 127.0.0.1 socket 6
shishid: Peer *:4711/tcp peer 127.0.0.1 disconnected on socket 6
shishid: Closing *:4711/tcp peer 127.0.0.1 socket 6
shishid: Listening on *:4711/tcp socket 4
Next:
Developer information
, Previous:
Kerberos via TLS
, Up:
Administration Manual
Contents
][
Index
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
Previous:
Multiple servers
, Up:
Administration Manual
Contents
][
Index
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
).
Next:
Programming Manual
, Previous:
Administration Manual
, Up:
Top
Contents
][
Index
4 Reference Manual
This chapter discuss the underlying assumptions of Kerberos, contain a
glossary to Kerberos concepts, give you background information on
choosing realm and principal names, and describe all parameters and
configuration file syntaxes for the Shishi tools.
Environmental Assumptions
Kerberos 5 assumptions about your system.
Glossary of terms
Glossary of Kerberos related terminology.
Realm and Principal Naming
How to name your realm and principals.
Shishi Configuration
Explains the Core Shishi configuration file.
Shisa Configuration
Explains the Shisa database definition file.
Parameters for shishi
Command line parameters for ’shishi’.
Parameters for shishid
Command line parameters for ’shishid’.
Parameters for shisa
Command line parameters for ’shisa’.
Environment variables
Overriding compile-time defaults at run-time.
Date input formats
Details of the understood date formats.
Next:
Glossary of terms
, Up:
Reference Manual
Contents
][
Index
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.
Next:
Realm and Principal Naming
, Previous:
Environmental Assumptions
, Up:
Reference Manual
Contents
][
Index
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.
Next:
Shishi Configuration
, Previous:
Glossary of terms
, Up:
Reference Manual
Contents
][
Index
4.3 Realm and Principal Naming
This section contains the discussion on naming realms and principals
from the Kerberos specification.
4.3.1 Realm Names
Although realm names are encoded as GeneralStrings and although a
realm can technically select any name it chooses, interoperability
across realm boundaries requires agreement on how realm names are to
be assigned, and what information they imply.
To enforce these conventions, each realm MUST conform to the
conventions itself, and it MUST require that any realms with which
inter-realm keys are shared also conform to the conventions and
require the same from its neighbors.
Kerberos realm names are case sensitive. Realm names that differ only
in the case of the characters are not equivalent. There are presently
three styles of realm names: domain, X500, and other. Examples of
each style follow:
domain: ATHENA.MIT.EDU
X500: C=US/O=OSF
other: NAMETYPE:rest/of.name=without-restrictions
Domain syle realm names MUST look like domain names: they consist of
components separated by periods (.) and they contain neither colons
(:) nor slashes (/). Though domain names themselves are case
insensitive, in order for realms to match, the case must match as
well. When establishing a new realm name based on an internet domain
name it is recommended by convention that the characters be converted
to upper case.
X.500 names contain an equal (=) and cannot contain a colon (:)
before the equal. The realm names for X.500 names will be string
representations of the names with components separated by slashes.
Leading and trailing slashes will not be included. Note that the
slash separator is consistent with Kerberos implementations based on
RFC1510, but it is different from the separator recommended in
RFC2253.
Names that fall into the other category MUST begin with a prefix that
contains no equal (=) or period (.) and the prefix MUST be followed
by a colon (:) and the rest of the name. All prefixes must be
assigned before they may be used. Presently none are assigned.
The reserved category includes strings which do not fall into the
first three categories. All names in this category are reserved. It
is unlikely that names will be assigned to this category unless there
is a very strong argument for not using the ’other’ category.
These rules guarantee that there will be no conflicts between the
various name styles. The following additional constraints apply to
the assignment of realm names in the domain and X.500 categories: the
name of a realm for the domain or X.500 formats must either be used
by the organization owning (to whom it was assigned) an Internet
domain name or X.500 name, or in the case that no such names are
registered, authority to use a realm name MAY be derived from the
authority of the parent realm. For example, if there is no domain
name for E40.MIT.EDU, then the administrator of the MIT.EDU realm can
authorize the creation of a realm with that name.
This is acceptable because the organization to which the parent is
assigned is presumably the organization authorized to assign names to
its children in the X.500 and domain name systems as well. If the
parent assigns a realm name without also registering it in the domain
name or X.500 hierarchy, it is the parent’s responsibility to make
sure that there will not in the future exist a name identical to the
realm name of the child unless it is assigned to the same entity as
the realm name.
4.3.2 Principal Names
As was the case for realm names, conventions are needed to ensure
that all agree on what information is implied by a principal name.
The name-type field that is part of the principal name indicates the
kind of information implied by the name. The name-type SHOULD be
treated only as a hint to interpreting the meaning of a name. It is
not significant when checking for equivalence. Principal names that
differ only in the name-type identify the same principal. The name
type does not partition the name space. Ignoring the name type, no
two names can be the same (i.e. at least one of the components, or
the realm, MUST be different). The following name types are defined:
name-type value meaning
NT-UNKNOWN 0 Name type not known
NT-PRINCIPAL 1 Just the name of the principal as in DCE, or for users
NT-SRV-INST 2 Service and other unique instance (krbtgt)
NT-SRV-HST 3 Service with host name as instance (telnet, rcommands)
NT-SRV-XHST 4 Service with host as remaining components
NT-UID 5 Unique ID
NT-X500-PRINCIPAL 6 Encoded X.509 Distingished name [RFC 2253]
NT-SMTP-NAME 7 Name in form of SMTP email name (e.g. user@foo.com)
NT-ENTERPRISE 10 Enterprise name - may be mapped to principal name
When a name implies no information other than its uniqueness at a
particular time the name type PRINCIPAL SHOULD be used. The principal
name type SHOULD be used for users, and it might also be used for a
unique server. If the name is a unique machine generated ID that is
guaranteed never to be reassigned then the name type of UID SHOULD be
used (note that it is generally a bad idea to reassign names of any
type since stale entries might remain in access control lists).
If the first component of a name identifies a service and the
remaining components identify an instance of the service in a server
specified manner, then the name type of SRV-INST SHOULD be used. An
example of this name type is the Kerberos ticket-granting service
whose name has a first component of krbtgt and a second component
identifying the realm for which the ticket is valid.
If the first component of a name identifies a service and there is a
single component following the service name identifying the instance
as the host on which the server is running, then the name type SRV-
HST SHOULD be used. This type is typically used for Internet services
such as telnet and the Berkeley R commands. If the separate
components of the host name appear as successive components following
the name of the service, then the name type SRV-XHST SHOULD be used.
This type might be used to identify servers on hosts with X.500 names
where the slash (/) might otherwise be ambiguous.
A name type of NT-X500-PRINCIPAL SHOULD be used when a name from an
X.509 certificate is translated into a Kerberos name. The encoding of
the X.509 name as a Kerberos principal shall conform to the encoding
rules specified in RFC 2253.
A name type of SMTP allows a name to be of a form that resembles a
SMTP email name. This name, including an "@" and a domain name, is
used as the one component of the principal name.
A name type of UNKNOWN SHOULD be used when the form of the name is
not known. When comparing names, a name of type UNKNOWN will match
principals authenticated with names of any type. A principal
authenticated with a name of type UNKNOWN, however, will only match
other names of type UNKNOWN.
Names of any type with an initial component of ’krbtgt’ are reserved
for the Kerberos ticket granting service. See
Name of the
TGS
, for the form of such names.
4.3.2.1 Name of server principals
The principal identifier for a server on a host will generally be
composed of two parts: (1) the realm of the KDC with which the server
is registered, and (2) a two-component name of type NT-SRV-HST if the
host name is an Internet domain name or a multi-component name of
type NT-SRV-XHST if the name of the host is of a form such as X.500
that allows slash (/) separators. The first component of the two- or
multi-component name will identify the service and the latter
components will identify the host. Where the name of the host is not
case sensitive (for example, with Internet domain names) the name of
the host MUST be lower case. If specified by the application protocol
for services such as telnet and the Berkeley R commands which run
with system privileges, the first component MAY be the string ’host’
instead of a service specific identifier.
4.3.2.2 Name of the TGS
The principal identifier of the ticket-granting service shall be
composed of three parts: (1) the realm of the KDC issuing the TGS
ticket (2) a two-part name of type NT-SRV-INST, with the first part
"krbtgt" and the second part the name of the realm which will accept
the ticket-granting ticket. For example, a ticket-granting ticket
issued by the ATHENA.MIT.EDU realm to be used to get tickets from the
ATHENA.MIT.EDU KDC has a principal identifier of "ATHENA.MIT.EDU"
(realm), ("krbtgt", "ATHENA.MIT.EDU") (name). A ticket-granting
ticket issued by the ATHENA.MIT.EDU realm to be used to get tickets
from the MIT.EDU realm has a principal identifier of "ATHENA.MIT.EDU"
(realm), ("krbtgt", "MIT.EDU") (name).
4.3.3 Choosing a principal with which to communicate
The Kerberos protocol provides the means for verifying (subject to
the assumptions in
Environmental Assumptions
) that the entity with which one communicates
is the same entity that was registered with the KDC using the claimed
identity (principal name). It is still necessary to determine whether
that identity corresponds to the entity with which one intends to
communicate.
When appropriate data has been exchanged in advance, this
determination may be performed syntactically by the application based
on the application protocol specification, information provided by
the user, and configuration files. For example, the server principal
name (including realm) for a telnet server might be derived from the
user specified host name (from the telnet command line), the "host/"
prefix specified in the application protocol specification, and a
mapping to a Kerberos realm derived syntactically from the domain
part of the specified hostname and information from the local
Kerberos realms database.
One can also rely on trusted third parties to make this
determination, but only when the data obtained from the third party
is suitably integrity protected while resident on the third party
server and when transmitted. Thus, for example, one should not rely
on an unprotected domain name system record to map a host alias to
the primary name of a server, accepting the primary name as the party
one intends to contact, since an attacker can modify the mapping and
impersonate the party with which one intended to communicate.
Implementations of Kerberos and protocols based on Kerberos MUST NOT
use insecure DNS queries to canonicalize the hostname components of
the service principal names. In an environment without secure name
service, application authors MAY append a statically configured
domain name to unqualified hostnames before passing the name to the
security mechanisms, but should do no more than that. Secure name
service facilities, if available, might be trusted for hostname
canonicalization, but such canonicalization by the client SHOULD NOT
be required by KDC implementations.
Implementation note: Many current implementations do some degree of
canonicalization of the provided service name, often using DNS even
though it creates security problems. However there is no consistency
among implementations about whether the service name is case folded
to lower case or whether reverse resolution is used. To maximize
interoperability and security, applications SHOULD provide security
mechanisms with names which result from folding the user-entered name
to lower case, without performing any other modifications or
canonicalization.
4.3.4 Principal Name Form
Principal names consist of a sequence of strings, which is often
tedious to parse. Therefor, Shishi often uses a “printed” form of
principal which embed the entire principal name string sequence, and
optionally also the realm, into one string. The format is taken from
the Kerberos 5 GSS-API mechanism (RFC 1964).
The elements included within this name representation are as follows,
proceeding from the beginning of the string:
One or more principal name components; if more than one
principal name component is included, the components are
separated by ‘/‘. Arbitrary octets may be included within
principal name components, with the following constraints and
special considerations:
Any occurrence of the characters ‘@‘ or ‘/‘ within a
name component must be immediately preceded by the ‘\‘
quoting character, to prevent interpretation as a component
or realm separator.
The ASCII newline, tab, backspace, and null characters
may occur directly within the component or may be
represented, respectively, by ‘\n‘, ‘\t‘, ‘\b‘, or ‘\0‘.
If the ‘\‘ quoting character occurs outside the contexts
described in (1a) and (1b) above, the following character is
interpreted literally. As a special case, this allows the
doubled representation ‘\\‘ to represent a single occurrence
of the quoting character.
An occurrence of the ‘\‘ quoting character as the last
character of a component is illegal.
Optionally, a ‘@‘ character, signifying that a realm name
immediately follows. If no realm name element is included, the
local realm name is assumed. The ‘/‘ , ‘:‘, and null characters
may not occur within a realm name; the ‘@‘, newline, tab, and
backspace characters may be included using the quoting
conventions described in (1a), (1b), and (1c) above.
Next:
Shisa Configuration
, Previous:
Realm and Principal Naming
, Up:
Reference Manual
Contents
][
Index
4.4 Shishi Configuration
The valid configuration file tokens are described here. The user
configuration file is typically located in
~/.shishi/shishi.conf
(compare ‘
shishi
--configuration-file
’) and the system configuration is typically
located in
/usr/local/etc/shishi/shishi.conf
(compare
shishi --system-configuration-file
’). If the first non white
space character of a line is a ’#’, the line is ignored. Empty lines
are also ignored.
All tokens are valid in both the system and the user configuration
files, and have the same meaning. However, as the system file is
supposed to apply to all users on a system, it would not make sense to
use some tokens in that file. For example, the
default-principal
’ is rarely useful in a system configuration
file.
4.4.1 ‘
default-realm
Specify the default realm, by default the hostname of the host is
used. E.g.,
default-realm JOSEFSSON.ORG
4.4.2 ‘
default-principal
Specify the default principal, by default the login username is
used. E.g.,
default-principal jas
4.4.3 ‘
client-kdc-etypes
Specify which encryption types client asks server to respond in during
AS/TGS exchanges. List valid encryption types, in preference order.
Supported algorithms include aes256-cts-hmac-sha1-96,
aes128-cts-hmac-sha1-96, des3-cbc-sha1-kd, des-cbc-md5, des-cbc-md4,
des-cbc-crc and null. This option also indicates which encryption
types are accepted by the client when receiving the response. Note
that the preference order is not cryptographically protected, so a man
in the middle can modify the order without being detected. Thus, only
specify encryption types you trust completely here. The default only
includes aes256-cts-hmac-sha1-96, as suggested by RFC1510bis. E.g.,
client-kdc-etypes=aes256-cts-hmac-sha1-96 des3-cbc-sha1-kd des-cbc-md5
4.4.4 ‘
verbose
’, ‘
verbose-asn1
’, ‘
verbose-noise
’, ‘
verbose-crypto
’, ‘
verbose-crypto-noise
Enable verbose library messages. E.g.,
verbose
verbose-noise
4.4.5 ‘
realm-kdc
Specify KDC addresses for realms. Value is
REALM,KDCADDRESS[/TRANSPORT][,KDCADDRESS[/TRANSPORT]...]
’.
KDCADDRESS is the hostname or IP address of KDC.
Optional TRANSPORT is “udp” for UDP, “tcp” for TCP, and “tls”
for TLS connections. By default UDP is tried first, and TCP used as a
fallback if the KRB_ERR_RESPONSE_TOO_BIG error is received.
If not specified, Shishi tries to locate the KDC using SRV RRs,
which is recommended. This option should normally only be
used during experiments, or to access badly maintained realms.
realm-kdc=JOSEFSSON.ORG,ristretto.josefsson.org
4.4.6 ‘
server-realm
Specify realm for servers. Value is
REALM,SERVERREGEXP[,SERVERREGEXP...]
’.
SERVERREGEXP is a regular expression matching servers in the realm.
The first match is used. E.g.,
server-realm=JOSEFSSON.ORG,.josefsson.org
Note: currently not used.
4.4.7 ‘
kdc-timeout
’, ‘
kdc-retries
How long shishi waits for a response from a KDC before continuing to
next KDC for realm. The default is 5 seconds. E.g.,
kdc-timeout=10
How many times shishi sends a request to a KDC before giving up. The
default is 3 times. E.g.,
kdc-retries=5
4.4.8 ‘
stringprocess
How username and passwords entered from the terminal, or taken from
the command line, are processed.
"none": no processing is used.
"stringprep": convert from locale charset to UTF-8 and process using
experimental RFC 1510 stringprep profile.
It can also be a string indicating a character set supported by
iconv via libstringprep, in which case data is converted from locale
charset into the indicated character set. E.g., UTF-8, ISO-8859-1,
KOI-8, EBCDIC-IS-FRISS are supported on GNU systems. On some systems
you can use "locale -m" to list available character sets. By default,
the "none" setting is used which is consistent with RFC 1510 that is
silent on the issue. In practice, however, converting to UTF-8
improves interoperability.
E.g.,
stringprocess=UTF-8
4.4.9 ‘
ticket-life
Specify default ticket life time.
The string can be in almost any common format. It can contain month
names, time zones, ‘am’ and ‘pm’, ‘yesterday’, ‘ago’, ‘next’, etc.
See
Date input formats
, for the long story.
As an extra feature, if the time specified by your string correspond
to a time during the last 24 hours, an extra day is added to it. This
allows you to specify relative times such as "17:00" to always mean
the next 17:00, even if your system clock happens to be 17:30.
The default is 8 hours.
E.g.,
#ticket-life=8 hours
#ticket-life=1 day
ticket-life=17:00
4.4.10 ‘
renew-life
Specify how long a renewable ticket should remain renewable.
See ticket-life for the syntax. The extra feature that handles
negative values within the last 2 hours is not active here.
The default is 7 days.
E.g.,
#renew-life=1 week
#renew-life=friday 17:00
renew-life=sunday
Next:
Parameters for shishi
, Previous:
Shishi Configuration
, Up:
Reference Manual
Contents
][
Index
4.5 Shisa Configuration
The configuration file for Shisa is typically stored in
/usr/local/etc/shishi/shisa.conf
. If the first non white space
character of a line is a ’#’, the line is ignored. Empty lines are
also ignored.
4.5.1 ‘
db
Currently the only configuration options available is the
db
token that define the databases to use. The syntax is:
db [OPTIONS]
Specify the data sources for Kerberos 5 data. Multiple entries,
even of the same data source type, are allowed. The data sources
are accessed in the same sequence as they are defined here. If an
entry is found in one data source, it will be used for the
operations, without searching the remaining data sources. Valid
OPTIONS include:
--read-only No data is written to this data source.
--ignore-errors Ignore failures in this backend.
The default (when the configuration file is empty) uses one "file"
data source (see below), but for a larger installation you may want to
combine several data sources. Here is an example.
db --read-only file /var/local/master
db --ignore-errors ldap kdc.example.org ca=/etc/shisa/kdc-ca.pem
db --read-only file /var/cache/ldap-copy
This demonstrate how you can store critical principals on local disk
(the first entry, /var/local/master) that will always be found without
looking in the LDAP directory. The critical principals could be,
e.g., krbtgt/EXAMPLE.ORG. The second entry denote a LDAP server that
could hold user principals. As you can see, Shisa will not let the
caller know about errors with the LDAP source (they will be logged,
however). Instead, if for instance the LDAP server has crashed, Shisa
would continue and read from the /var/cache/ldap-copy file source.
That file source may have been set up to contain a copy of the data in
the LDAP server, perhaps made on an hourly basis, so that your server
will be able to serve recent data even in case of a crash. Any
updates or passwords change requests will however not be possible
while the LDAP server is inaccessible, to reduce the problem of
synchronizing data back into the LDAP server once it is online again.
Currently only the "file" data source is supported, and denote a
data source that use the standard file system for storage.
Valid syntaxes for the "file" database:
db file PATH
Examples:
db file /var/shishi
db file /usr/share/shishi read-only
If no ‘
db
’ tokens are present, the default will be:
db file /usr/local/var/shishi
Next:
Parameters for shishid
, Previous:
Shisa Configuration
, Up:
Reference Manual
Contents
][
Index
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)
Next:
Parameters for shisa
, Previous:
Parameters for shishi
, Up:
Reference Manual
Contents
][
Index
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)
Next:
Environment variables
, Previous:
Parameters for shishid
, Up:
Reference Manual
Contents
][
Index
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)
Next:
Date input formats
, Previous:
Parameters for shisa
, Up:
Reference Manual
Contents
][
Index
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.
Previous:
Environment variables
, Up:
Reference Manual
Contents
][
Index
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
Common rules
Calendar date items
21 Jul 2020
Time of day items
9:20pm
Time zone items
UTC, -0700, +0900, …
Combined date and time of day items
2020-07-21T20:02:00,000000-0400
Day of week items
Monday and others
Relative items in date strings
next tuesday, 2 years ago
Pure numbers in date strings
20200721, 1440
Seconds since the Epoch
@1595289600
Specifying time zone rules
TZ="America/New_York", TZ="UTC0"
Authors of parse_datetime
Bellovin, Eggert, Salz, Berets, et al.
Next:
Calendar date items
, Up:
Date input formats
Contents
][
Index
4.10.1 General date syntax
date
is a string, possibly empty, containing many items
separated by whitespace. The whitespace may be omitted when no
ambiguity arises. The empty string means the beginning of today (i.e.,
midnight). Order of the items is immaterial. A date string may contain
many flavors of items:
calendar date items
time of day items
time zone items
combined date and time of day items
day of the week items
relative items
pure numbers.
We describe each of these item types in turn, below.
A few ordinal numbers may be written out in words in some contexts. This is
most useful for specifying day of the week items or relative items (see
below). Among the most commonly used ordinal numbers, the word
last
’ stands for
-1
, ‘
this
’ stands for 0, and
first
’ and ‘
next
’ both stand for 1. Because the word
second
’ stands for the unit of time there is no way to write the
ordinal number 2, but for convenience ‘
third
’ stands for 3,
fourth
’ for 4, ‘
fifth
’ for 5,
sixth
’ for 6, ‘
seventh
’ for 7, ‘
eighth
’ for 8,
ninth
’ for 9, ‘
tenth
’ for 10, ‘
eleventh
’ for 11 and
twelfth
’ for 12.
When a month is written this way, it is still considered to be written
numerically, instead of being “spelled in full”; this changes the
allowed strings.
In the current implementation, only English is supported for words and
abbreviations like ‘
AM
’, ‘
DST
’, ‘
EST
’, ‘
first
’,
January
’, ‘
Sunday
’, ‘
tomorrow
’, and ‘
year
’.
The output of the
date
command
is not always acceptable as a date string,
not only because of the language problem, but also because there is no
standard meaning for time zone items like ‘
IST
’. When using
date
to generate a date string intended to be parsed later,
specify a date format that is independent of language and that does not
use time zone items other than ‘
UTC
’ and ‘
’. Here are some
ways to do this:
$ 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
Alphabetic case is completely ignored in dates. Comments may be introduced
between round parentheses, as long as included parentheses are properly
nested. Hyphens not followed by a digit are currently ignored. Leading
zeros on numbers are ignored.
Invalid dates like ‘
2019-02-29
’ or times like ‘
24:00
’ are
rejected. In the typical case of a host that does not support leap
seconds, a time like ‘
23:59:60
’ is rejected even if it
corresponds to a valid leap second.
Next:
Time of day items
, Previous:
General date syntax
, Up:
Date input formats
Contents
][
Index
4.10.2 Calendar date items
calendar date item
specifies a day of the year. It is
specified differently, depending on whether the month is specified
numerically or literally. All these strings specify the same calendar date:
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
The year can also be omitted. In this case, the last specified year is
used, or the current year if none. For example:
7/20
jul 20
Here are the rules.
For numeric months, the ISO 8601 format
year
month
day
’ is allowed, where
year
is
any positive number,
month
is a number between 01 and 12, and
day
is a number between 01 and 31. A leading zero must be present
if a number is less than ten. If
year
is 68 or smaller, then 2000
is added to it; otherwise, if
year
is less than 100,
then 1900 is added to it. The construct
month
day
year
’, popular in the United States,
is accepted. Also ‘
month
day
’, omitting the year.
Literal months may be spelled out in full: ‘
January
’,
February
’, ‘
March
’, ‘
April
’, ‘
May
’, ‘
June
’,
July
’, ‘
August
’, ‘
September
’, ‘
October
’,
November
’ or ‘
December
’. Literal months may be abbreviated
to their first three letters, possibly followed by an abbreviating dot.
It is also permitted to write ‘
Sept
’ instead of ‘
September
’.
When months are written literally, the calendar date may be given as any
of the following:
day
month
year
day
month
month
day
year
day
month
year
Or, omitting the year:
month
day
Next:
Time zone items
, Previous:
Calendar date items
, Up:
Date input formats
Contents
][
Index
4.10.3 Time of day items
time of day item
in date strings specifies the time on a given
day. Here are some examples, all of which represent the same time:
20:02:00.000000
20:02
8:02pm
20:02-0500 # In EST (U.S. Eastern Standard Time).
More generally, the time of day may be given as
hour
minute
second
’, where
hour
is
a number between 0 and 23,
minute
is a number between 0 and
59, and
second
is a number between 0 and 59 possibly followed by
’ or ‘
’ and a fraction containing one or more digits.
Alternatively,
second
’ can be omitted, in which case it is taken to
be zero. On the rare hosts that support leap seconds,
second
may be 60.
If the time is followed by ‘
am
’ or ‘
pm
’ (or ‘
a.m.
or ‘
p.m.
’),
hour
is restricted to run from 1 to 12, and
minute
’ may be omitted (taken to be zero). ‘
am
indicates the first half of the day, ‘
pm
’ indicates the second
half of the day. In this notation, 12 is the predecessor of 1:
midnight is ‘
12am
’ while noon is ‘
12pm
’.
(This is the zero-oriented interpretation of ‘
12am
’ and ‘
12pm
’,
as opposed to the old tradition derived from Latin
which uses ‘
12m
’ for noon and ‘
12pm
’ for midnight.)
The time may alternatively be followed by a time zone correction,
expressed as ‘
hh
mm
’, where
is ‘
or ‘
’,
hh
is a number of zone hours and
mm
is a number
of zone minutes.
The zone minutes term,
mm
, may be omitted, in which case
the one- or two-digit correction is interpreted as a number of hours.
You can also separate
hh
from
mm
with a colon.
When a time zone correction is given this way, it
forces interpretation of the time relative to
Coordinated Universal Time (UTC), overriding any previous
specification for the time zone or the local time zone. For example,
+0530
’ and ‘
+05:30
’ both stand for the time zone 5.5 hours
ahead of UTC (e.g., India).
This is the best way to
specify a time zone correction by fractional parts of an hour.
The maximum zone correction is 24 hours.
Either ‘
am
’/‘
pm
’ or a time zone correction may be specified,
but not both.
Next:
Combined date and time of day items
, Previous:
Time of day items
, Up:
Date input formats
Contents
][
Index
4.10.4 Time zone items
time zone item
specifies an international time zone, indicated
by a small set of letters, e.g., ‘
UTC
’ or ‘
for Coordinated Universal
Time. Any included periods are ignored. By following a
non-daylight-saving time zone by the string ‘
DST
’ in a separate
word (that is, separated by some white space), the corresponding
daylight saving time zone may be specified.
Alternatively, a non-daylight-saving time zone can be followed by a
time zone correction, to add the two values. This is normally done
only for ‘
UTC
’; for example, ‘
UTC+05:30
’ is equivalent to
+05:30
’.
Time zone items other than ‘
UTC
’ and ‘
are obsolescent and are not recommended, because they
are ambiguous; for example, ‘
EST
’ has a different meaning in
Australia than in the United States, and ‘
’ has different
meaning as a military time zone than as an obsolete
RFC 822 time zone. Instead, it’s better to use
unambiguous numeric time zone corrections like ‘
-0500
’, as
described in the previous section.
If neither a time zone item nor a time zone correction is supplied,
timestamps are interpreted using the rules of the default time zone
(see
Specifying time zone rules
).
Next:
Day of week items
, Previous:
Time zone items
, Up:
Date input formats
Contents
][
Index
4.10.5 Combined date and time of day items
The ISO 8601 date and time of day extended format consists of an ISO
8601 date, a ‘
’ character separator, and an ISO 8601 time of
day. This format is also recognized if the ‘
’ is replaced by a
space.
In this format, the time of day should use 24-hour notation.
Fractional seconds are allowed, with either comma or period preceding
the fraction. ISO 8601 fractional minutes and hours are not
supported. Typically, hosts support nanosecond timestamp resolution;
excess precision is silently discarded.
Here are some examples:
2012-09-24T20:02:00.052-05:00
2012-12-31T23:59:59,999999999+11:00
1970-01-01 00:00Z
Next:
Relative items in date strings
, Previous:
Combined date and time of day items
, Up:
Date input formats
Contents
][
Index
4.10.6 Day of week items
The explicit mention of a day of the week will forward the date
(only if necessary) to reach that day of the week in the future.
Days of the week may be spelled out in full: ‘
Sunday
’,
Monday
’, ‘
Tuesday
’, ‘
Wednesday
’, ‘
Thursday
’,
Friday
’ or ‘
Saturday
’. Days may be abbreviated to their
first three letters, optionally followed by a period. The special
abbreviations ‘
Tues
’ for ‘
Tuesday
’, ‘
Wednes
’ for
Wednesday
’ and ‘
Thur
’ or ‘
Thurs
’ for ‘
Thursday
’ are
also allowed.
A number may precede a day of the week item to move forward
supplementary weeks. It is best used in expression like ‘
third
monday
’. In this context, ‘
last
day
’ or ‘
next
day
’ is also acceptable; they move one week before or after
the day that
day
by itself would represent.
A comma following a day of the week item is ignored.
Next:
Pure numbers in date strings
, Previous:
Day of week items
, Up:
Date input formats
Contents
][
Index
4.10.7 Relative items in date strings
Relative items
adjust a date (or the current date if none) forward
or backward. The effects of relative items accumulate. Here are some
examples:
1 year
1 year ago
3 years
2 days
The unit of time displacement may be selected by the string ‘
year
or ‘
month
’ for moving by whole years or months. These are fuzzy
units, as years and months are not all of equal duration. More precise
units are ‘
fortnight
’ which is worth 14 days, ‘
week
’ worth 7
days, ‘
day
’ worth 24 hours, ‘
hour
’ worth 60 minutes,
minute
’ or ‘
min
’ worth 60 seconds, and ‘
second
’ or
sec
’ worth one second. An ‘
’ suffix on these units is
accepted and ignored.
The unit of time may be preceded by a multiplier, given as an optionally
signed number. Unsigned numbers are taken as positively signed. No
number at all implies 1 for a multiplier. Following a relative item by
the string ‘
ago
’ is equivalent to preceding the unit by a
multiplier with value
-1
The string ‘
tomorrow
’ is worth one day in the future (equivalent
to ‘
day
’), the string ‘
yesterday
’ is worth
one day in the past (equivalent to ‘
day ago
’).
The strings ‘
now
’ or ‘
today
’ are relative items corresponding
to zero-valued time displacement, these strings come from the fact
a zero-valued time displacement represents the current time when not
otherwise changed by previous items. They may be used to stress other
items, like in ‘
12:00 today
’. The string ‘
this
’ also has
the meaning of a zero-valued time displacement, but is preferred in
date strings like ‘
this thursday
’.
When a relative item causes the resulting date to cross a boundary
where the clocks were adjusted, typically for daylight saving time,
the resulting date and time are adjusted accordingly.
The fuzz in units can cause problems with relative items. For
example, ‘
2020-07-31 -1 month
’ might evaluate to 2020-07-01,
because 2020-06-31 is an invalid date. To determine the previous
month more reliably, you can ask for the month before the 15th of the
current month. For example:
$ date -R
Thu, 31 Jul 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!
Also, take care when manipulating dates around clock changes such as
daylight saving leaps. In a few cases these have added or subtracted
as much as 24 hours from the clock, so it is often wise to adopt
universal time by setting the
TZ
environment variable to
UTC0
’ before embarking on calendrical calculations.
Next:
Seconds since the Epoch
, Previous:
Relative items in date strings
, Up:
Date input formats
Contents
][
Index
4.10.8 Pure numbers in date strings
The precise interpretation of a pure decimal number depends
on the context in the date string.
If the decimal number is of the form
yyyy
mm
dd
and no
other calendar date item (see
Calendar date items
) appears before it
in the date string, then
yyyy
is read as the year,
mm
as the
month number and
dd
as the day of the month, for the specified
calendar date.
If the decimal number is of the form
hh
mm
and no other time
of day item appears before it in the date string, then
hh
is read
as the hour of the day and
mm
as the minute of the hour, for the
specified time of day.
mm
can also be omitted.
If both a calendar date and a time of day appear to the left of a number
in the date string, but no relative item, then the number overrides the
year.
Next:
Specifying time zone rules
, Previous:
Pure numbers in date strings
, Up:
Date input formats
Contents
][
Index
4.10.9 Seconds since the Epoch
If you precede a number with ‘
’, it represents an internal
timestamp as a count of seconds. The number can contain an internal
decimal point (either ‘
’ or ‘
’); any excess precision not
supported by the internal representation is truncated toward minus
infinity. Such a number cannot be combined with any other date
item, as it specifies a complete timestamp.
Internally, computer times are represented as a count of seconds since
an Epoch—a well-defined point of time. On GNU and
POSIX systems, the Epoch is 1970-01-01 00:00:00 UTC, so
@0
’ represents this time, ‘
@1
’ represents 1970-01-01
00:00:01 UTC, and so forth. GNU and most other
POSIX-compliant systems support such times as an extension
to POSIX, using negative counts, so that ‘
@-1
represents 1969-12-31 23:59:59 UTC.
Most modern systems count seconds with 64-bit two’s-complement integers
of seconds with nanosecond subcounts, which is a range that includes
the known lifetime of the universe with nanosecond resolution.
Some obsolescent systems count seconds with 32-bit two’s-complement
integers and can represent times from 1901-12-13 20:45:52 through
2038-01-19 03:14:07 UTC. A few systems sport other time ranges.
On most hosts, these counts ignore the presence of leap seconds.
For example, on most hosts ‘
@1483228799
’ represents 2016-12-31
23:59:59 UTC, ‘
@1483228800
’ represents 2017-01-01 00:00:00
UTC, and there is no way to represent the intervening leap second
2016-12-31 23:59:60 UTC.
Next:
Authors of parse_datetime
, Previous:
Seconds since the Epoch
, Up:
Date input formats
Contents
][
Index
4.10.10 Specifying time zone rules
Normally, dates are interpreted using the rules of the current time
zone, which in turn are specified by the
TZ
environment
variable, or by a system default if
TZ
is not set. To specify a
different set of default time zone rules that apply just to one date,
start the date with a string of the form ‘
TZ="
rule
’. The
two quote characters (‘
’) must be present in the date, and any
quotes or backslashes within
rule
must be escaped by a
backslash.
For example, with the GNU
date
command you can
answer the question “What time is it in New York when a Paris clock
shows 6:30am on October 31, 2019?” by using a date beginning with
TZ="Europe/Paris"
’ as shown in the following shell transcript:
$ export TZ="America/New_York"
$ date --date='TZ="Europe/Paris" 2019-10-31 06:30'
Sun Oct 31 01:30:00 EDT 2019
In this example, the
--date
operand begins with its own
TZ
setting, so the rest of that operand is processed according
to ‘
Europe/Paris
’ rules, treating the string ‘
2019-10-31
06:30
’ as if it were in Paris. However, since the output of the
date
command is processed according to the overall time zone
rules, it uses New York time. (Paris was normally six hours ahead of
New York in 2019, but this example refers to a brief Halloween period
when the gap was five hours.)
TZ
value is a rule that typically names a location in the
tz
’ database
A recent catalog of location names appears in the
TWiki Date and Time
Gateway
. A few non-GNU hosts require a colon before a
location name in a
TZ
setting, e.g.,
TZ=":America/New_York"
’.
The ‘
tz
’ database includes a wide variety of locations ranging
from ‘
Africa/Abidjan
’ to ‘
Pacific/Tongatapu
’, but
if you are at sea and have your own private time zone, or if you are
using a non-GNU host that does not support the ‘
tz
database, you may need to use a POSIX rule instead.
The previously-mentioned POSIX rule ‘
UTC0
’ says that the time zone
abbreviation is ‘
UTC
’, the zone is zero hours away from
Greenwich, and there is no daylight saving time.
POSIX rules can also specify nonzero Greenwich offsets.
For example, the following shell transcript answers the question
“What time is it five and a half hours east of Greenwich when a clock
seven hours west of Greenwich shows 9:50pm on July 12, 2022?”
$ TZ="<+0530>-5:30" date --date='TZ="<-07>+7" 2022-07-12 21:50'
Wed Jul 13 10:20:00 +0530 2022
This example uses the somewhat-confusing POSIX convention for rules.
TZ="<-07>+7"
’ says that the time zone abbreviation is ‘
-07
and the time zone is 7 hours west of Greenwich, and
TZ="<+0530>-5:30"
’ says that the time zone abbreviation is ‘
+0530
and the time zone is 5 hours 30 minutes east of Greenwich.
Although trickier POSIX
TZ
settings like
TZ="<-05>+5<-04>,M3.2.0/2,M11.1.0/2"
’ can specify some daylight
saving regimes, location-based settings like
TZ="America/New_York"
’ are typically simpler and more accurate
historically. See
Specifying the Time Zone with
TZ
in
The GNU C Library
Previous:
Specifying time zone rules
, Up:
Date input formats
Contents
][
Index
4.10.11 Authors of
parse_datetime
parse_datetime
started life as
getdate
, as originally
implemented by Steven M. Bellovin
smb@research.att.com
) while at the University of North Carolina
at Chapel Hill. The code was later tweaked by a couple of people on
Usenet, then completely overhauled by Rich $alz (
rsalz@bbn.com
and Jim Berets (
jberets@bbn.com
) in August, 1990. Various
revisions for the GNU system were made by David MacKenzie, Jim Meyering,
Paul Eggert and others, including renaming it to
get_date
to
avoid a conflict with the alternative Posix function
getdate
and a later rename to
parse_datetime
. The Posix function
getdate
can parse more locale-specific dates using
strptime
, but relies on an environment variable and external
file, and lacks the thread-safety of
parse_datetime
This chapter was originally produced by François Pinard
pinard@iro.umontreal.ca
) from the
parse_datetime.y
source code,
and then edited by K. Berry (
kb@cs.umb.edu
).
Next:
Acknowledgements
, Previous:
Reference Manual
, Up:
Top
Contents
][
Index
5 Programming Manual
This chapter describes all the publicly available functions in the
library.
Preparation
What you should do before using the library.
Initialization Functions
Creating library handle, configuration file.
Ticket Set Functions
High-level ticket management functions.
AP-REQ and AP-REP Functions
Client/Server authentication functions.
SAFE and PRIV Functions
Client/Server session data functions.
Ticket Functions
Medium-level ticket manipulation functions.
AS Functions
Medium-level initial authentication functions.
TGS Functions
Medium-level authentication functions.
Ticket (ASN.1) Functions
Low-level Ticket functions.
AS/TGS Functions
Low-level KDC functions; AS and TGS.
Authenticator Functions
Low-level authenticator functions.
KRB-ERROR Functions
Low-level KRB-ERROR functions.
Cryptographic Functions
Low-level cryptographic functions.
X.509 Functions
Utility functions for X.509 support.
Utility Functions
Utilities for use in the global context.
ASN.1 Functions
Perform low-level ASN.1 manipulations.
Error Handling
Error codes and such.
Examples
Example code.
Kerberos Database Functions
The Shisa generic database interface.
Generic Security Service
If you want to use the GSS API instead.
Next:
Initialization Functions
, Up:
Programming Manual
Contents
][
Index
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
Next:
Initialization
, Up:
Preparation
Contents
][
Index
5.1.1 Header
All interfaces (data types and functions) of the library are defined
in the header file ‘shishi.h’. You must include this in all programs
using the library, either directly or through some other header file,
like this:
#include
The name space of ‘Libshishi’ is
shishi_*
for function names,
Shishi*
for data types and
SHISHI_*
for other symbols. In
addition the same name prefixes with one prepended underscore are
reserved for internal use and should never be used by an application.
Next:
Version Check
, Previous:
Header
, Up:
Preparation
Contents
][
Index
5.1.2 Initialization
‘Libshishi’ must be initialized before it can be used. The library is
initialized by calling
shishi_init
(see
Initialization Functions
). The resources allocated by the initialization process
can be released if the application no longer has a need to call
‘Libshishi’ functions, this is done by calling
shishi_done
In order to take advantage of the internationalisation features in
‘Libshishi’, such as translated error messages, the application must
set the current locale using
setlocale
before initializing
‘Libshishi’.
Next:
Building the source
, Previous:
Initialization
, Up:
Preparation
Contents
][
Index
5.1.3 Version Check
It is often desirable to check that the version of ‘Libshishi’ used is
indeed one which fits all requirements. Even with binary
compatibility new features may have been introduced but due to problem
with the dynamic linker an old version is actually used. So you may
want to check that the version is okay right after program startup.
shishi_check_version
Function:
const char *
shishi_check_version
(const char *
req_version
req_version
: Oldest acceptable version, or
NULL
Description:
Checks that the installed library version is at least
as recent as the one provided in
req_version
The version string is formatted like "1.0.2".
Whenever
NULL
is passed to this function, the check is
suppressed, but the library version is still returned.
Return value:
Returns the active library version,
or
NULL
, should the running library be too old.
The normal way to use the function is to put something similar to the
following early in your
main
if (!shishi_check_version (SHISHI_VERSION))
printf ("shishi_check_version failed:\n"
"Header file incompatible with shared library.\n");
exit (EXIT_FAILURE);
Next:
Autoconf tests
, Previous:
Version Check
, Up:
Preparation
Contents
][
Index
5.1.4 Building the source
If you want to compile a source file including the ‘shishi.h’ header
file, you must make sure that the compiler can find it in the
directory hierarchy. This is accomplished by adding the path to the
directory in which the header file is located to the compilers include
file search path (via the
-I
option).
However, the path to the include file is determined at the time the
source is configured. To solve this problem, ‘Libshishi’ uses the
external package
pkg-config
that knows the path to the
include file and other configuration options. The options that need
to be added to the compiler invocation at compile time are output by
the
--cflags
option to
pkg-config shishi
. The
following example shows how it can be used at the command line:
gcc -c foo.c `pkg-config shishi --cflags`
Adding the output of ‘
pkg-config shishi --cflags
’ to the
compilers command line will ensure that the compiler can find the
‘Libshishi’ header file.
A similar problem occurs when linking the program with the library.
Again, the compiler has to find the library files. For this to work,
the path to the library files has to be added to the library search path
(via the
-L
option). For this, the option
--libs
to
pkg-config shishi
can be used. For convenience, this option
also outputs all other options that are required to link the program
with the ‘Libshishi’ libararies (in particular, the ‘
-lshishi
option). The example shows how to link
foo.o
with the ‘Libshishi’
library to a program
foo
gcc -o foo foo.o `pkg-config shishi --libs`
Of course you can also combine both examples to a single command by
specifying both options to
pkg-config
gcc -o foo foo.c `pkg-config shishi --cflags --libs`
Previous:
Building the source
, Up:
Preparation
Contents
][
Index
5.1.5 Autoconf tests
If you work on a project that uses Autoconf (see
(autoconf)GNU
Autoconf
) to help find installed libraries, the
suggestions in the previous section are not the entire story. There
are a few methods to detect and incorporate Shishi into your Autoconf
based package. The preferred approach, is to use Libtool in your
project, and use the normal Autoconf header file and library tests.
5.1.5.1 Autoconf test via ‘
pkg-config
If your audience is a typical GNU/Linux desktop, you can often assume
they have the ‘
pkg-config
’ tool installed, in which you can use
its Autoconf M4 macro to find and set up your package for use with
Shishi. The following illustrate this scenario.
AC_ARG_ENABLE(kerberos_v5,
AC_HELP_STRING([--disable-kerberos_v5],
[don't use the KERBEROS_V5 mechanism]),
kerberos_v5=$enableval)
if test "$kerberos_v5" != "no" ; then
PKG_CHECK_MODULES(SHISHI, shishi >= 0.0.0,
[kerberos_v5=yes],
[kerberos_v5=no])
if test "$kerberos_v5" != "yes" ; then
kerberos_v5=no
AC_MSG_WARN([shishi not found, disabling Kerberos 5])
else
kerberos_v5=yes
AC_DEFINE(USE_KERBEROS_V5, 1,
[Define to 1 if you want Kerberos 5.])
fi
fi
AC_MSG_CHECKING([if Kerberos 5 should be used])
AC_MSG_RESULT($kerberos_v5)
5.1.5.2 Standalone Autoconf test using Libtool
If your package uses Libtool(see
(libtool)GNU Libtool
), you
can use the normal Autoconf tests to find the Shishi library and rely
on the Libtool dependency tracking to include the proper dependency
libraries (e.g., Libidn). The following illustrate this scenario.
AC_CHECK_HEADER(shishi.h,
AC_CHECK_LIB(shishi, shishi_check_version,
[kerberos5=yes AC_SUBST(SHISHI_LIBS, -lshishi)],
kerberos5=no),
kerberos5=no)
AC_ARG_ENABLE(kerberos5,
AC_HELP_STRING([--disable-kerberos5],
[disable Kerberos 5 unconditionally]),
kerberos5=$enableval)
if test "$kerberos5" != "no" ; then
AC_DEFINE(USE_KERBEROS_V5, 1,
[Define to 1 if you want Kerberos 5.])
else
AC_MSG_WARN([Shishi not found, disabling Kerberos 5])
fi
AC_MSG_CHECKING([if Kerberos 5 should be used])
AC_MSG_RESULT($kerberos5)
5.1.5.3 Standalone Autoconf test
If your package does not use Libtool, as well as detecting the Shishi
library as in the previous case, you must also detect whatever
dependencies Shishi requires to work (e.g., libidn). Since the
dependencies are in a state of flux, we do not provide an example and
we do not recommend this approach, unless you are experienced
developer.
Next:
Ticket Set Functions
, Previous:
Preparation
, Up:
Programming Manual
Contents
][
Index
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
/.shishi/config, and the user
ticket file is
/.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
/.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
This hard coded directory, i.e., "
/.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 "
/.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 "
/.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.
Next:
AP-REQ and AP-REP Functions
, Previous:
Initialization Functions
, Up:
Programming Manual
Contents
][
Index
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
/.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.
Next:
SAFE and PRIV Functions
, Previous:
Ticket Set Functions
, Up:
Programming Manual
Contents
][
Index
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 **
handle
: shishi handle as allocated by
shishi_init()
encapreppart
: EncAPRepPart as allocated by
shishi_encapreppart()
: 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 *
handle
: shishi handle as allocated by
shishi_init()
encapreppart
: EncAPRepPart as allocated by
shishi_encapreppart()
: 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.
Next:
Ticket Functions
, Previous:
AP-REQ and AP-REP Functions
, Up:
Programming Manual
Contents
][
Index
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.
Next:
AS Functions
, Previous:
SAFE and PRIV Functions
, Up:
Programming Manual
Contents
][
Index
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.
shishi_tkt_realm
Function:
int
shishi_tkt_realm
Shishi_tkt
tkt
, char **
realm
size_t
realmlen
tkt
: input variable with ticket info.
realm
: pointer to newly allocated character array with realm name.
realmlen
: length of newly allocated character array with realm name.
Description:
Extract realm of server in ticket.
Return value:
Returns SHISHI_OK iff successful.
shishi_tkt_server
Function:
int
shishi_tkt_server
Shishi_tkt
tkt
, char **
server
size_t
serverlen
tkt
: input variable with ticket info.
server
: pointer to newly allocated zero terminated string containing
principal name. May be
NULL
(to only populate
serverlen
).
serverlen
: pointer to length of
server
on output, excluding terminating
zero. May be
NULL
(to only populate
server
).
Description:
Represent server principal name in Ticket as zero-terminated
string. The string is allocate by this function, and it is the
responsibility of the caller to deallocate it. Note that the
output length
serverlen
does not include the terminating zero.
Return value:
Returns SHISHI_OK iff successful.
shishi_tkt_server_p
Function:
int
shishi_tkt_server_p
Shishi_tkt
tkt
, const char *
server
tkt
: input variable with ticket info.
server
: server name of ticket.
Description:
Determine if ticket is for specified server.
Return value:
Returns non-0 iff ticket is for specified server.
shishi_tkt_flags
Function:
int
shishi_tkt_flags
Shishi_tkt
tkt
uint32_t
flags
tkt
: input variable with ticket info.
flags
: pointer to output integer with flags.
Description:
Extract flags in ticket (i.e., EncKDCRepPart).
Return value:
Returns SHISHI_OK iff successful.
shishi_tkt_flags_set
Function:
int
shishi_tkt_flags_set
Shishi_tkt
tkt
uint32_t
flags
tkt
: input variable with ticket info.
flags
: integer with flags to store in ticket.
Description:
Set flags in ticket, i.e., both EncTicketPart and EncKDCRepPart.
Note that this reset any already existing flags.
Return value:
Returns SHISHI_OK iff successful.
shishi_tkt_flags_add
Function:
int
shishi_tkt_flags_add
Shishi_tkt
tkt
uint32_t
flag
tkt
: input variable with ticket info.
flag
: integer with flags to store in ticket.
Description:
Add ticket flags to Ticket and EncKDCRepPart. This preserves all
existing options.
Return value:
Returns SHISHI_OK iff successful.
shishi_tkt_forwardable_p
Function:
int
shishi_tkt_forwardable_p
Shishi_tkt
tkt
tkt
: input variable with ticket info.
Description:
Determine if ticket is forwardable.
The FORWARDABLE flag in a ticket is normally only interpreted by
the ticket-granting service. It can be ignored by application
servers. The FORWARDABLE flag has an interpretation similar to
that of the PROXIABLE flag, except ticket-granting tickets may also
be issued with different network addresses. This flag is reset by
default, but users MAY request that it be set by setting the
FORWARDABLE option in the AS request when they request their
initial ticket-granting ticket.
Return value:
Returns non-0 iff forwardable flag is set in ticket.
shishi_tkt_forwarded_p
Function:
int
shishi_tkt_forwarded_p
Shishi_tkt
tkt
tkt
: input variable with ticket info.
Description:
Determine if ticket is forwarded.
The FORWARDED flag is set by the TGS when a client presents a
ticket with the FORWARDABLE flag set and requests a forwarded
ticket by specifying the FORWARDED KDC option and supplying a set
of addresses for the new ticket. It is also set in all tickets
issued based on tickets with the FORWARDED flag set. Application
servers may choose to process FORWARDED tickets differently than
non-FORWARDED tickets.
Return value:
Returns non-0 iff forwarded flag is set in ticket.
shishi_tkt_proxiable_p
Function:
int
shishi_tkt_proxiable_p
Shishi_tkt
tkt
tkt
: input variable with ticket info.
Description:
Determine if ticket is proxiable.
The PROXIABLE flag in a ticket is normally only interpreted by the
ticket-granting service. It can be ignored by application servers.
When set, this flag tells the ticket-granting server that it is OK
to issue a new ticket (but not a ticket-granting ticket) with a
different network address based on this ticket. This flag is set if
requested by the client on initial authentication. By default, the
client will request that it be set when requesting a
ticket-granting ticket, and reset when requesting any other ticket.
Return value:
Returns non-0 iff proxiable flag is set in ticket.
shishi_tkt_proxy_p
Function:
int
shishi_tkt_proxy_p
Shishi_tkt
tkt
tkt
: input variable with ticket info.
Description:
Determine if ticket is proxy ticket.
The PROXY flag is set in a ticket by the TGS when it issues a proxy
ticket. Application servers MAY check this flag and at their
option they MAY require additional authentication from the agent
presenting the proxy in order to provide an audit trail.
Return value:
Returns non-0 iff proxy flag is set in ticket.
shishi_tkt_may_postdate_p
Function:
int
shishi_tkt_may_postdate_p
Shishi_tkt
tkt
tkt
: input variable with ticket info.
Description:
Determine if ticket may be used to grant postdated tickets.
The MAY-POSTDATE flag in a ticket is normally only interpreted by
the ticket-granting service. It can be ignored by application
servers. This flag MUST be set in a ticket-granting ticket in
order to issue a postdated ticket based on the presented ticket. It
is reset by default; it MAY be requested by a client by setting the
ALLOW- POSTDATE option in the KRB_AS_REQ message. This flag does
not allow a client to obtain a postdated ticket-granting ticket;
postdated ticket-granting tickets can only by obtained by
requesting the postdating in the KRB_AS_REQ message. The life
(endtime-starttime) of a postdated ticket will be the remaining
life of the ticket-granting ticket at the time of the request,
unless the RENEWABLE option is also set, in which case it can be
the full life (endtime-starttime) of the ticket-granting
ticket. The KDC MAY limit how far in the future a ticket may be
postdated.
Return value:
Returns non-0 iff may-postdate flag is set in ticket.
shishi_tkt_postdated_p
Function:
int
shishi_tkt_postdated_p
Shishi_tkt
tkt
tkt
: input variable with ticket info.
Description:
Determine if ticket is postdated.
The POSTDATED flag indicates that a ticket has been postdated. The
application server can check the authtime field in the ticket to
see when the original authentication occurred. Some services MAY
choose to reject postdated tickets, or they may only accept them
within a certain period after the original authentication. When the
KDC issues a POSTDATED ticket, it will also be marked as INVALID,
so that the application client MUST present the ticket to the KDC
to be validated before use.
Return value:
Returns non-0 iff postdated flag is set in ticket.
shishi_tkt_invalid_p
Function:
int
shishi_tkt_invalid_p
Shishi_tkt
tkt
tkt
: input variable with ticket info.
Description:
Determine if ticket is invalid.
The INVALID flag indicates that a ticket is invalid. Application
servers MUST reject tickets which have this flag set. A postdated
ticket will be issued in this form. Invalid tickets MUST be
validated by the KDC before use, by presenting them to the KDC in a
TGS request with the VALIDATE option specified. The KDC will only
validate tickets after their starttime has passed. The validation
is required so that postdated tickets which have been stolen before
their starttime can be rendered permanently invalid (through a
hot-list mechanism).
Return value:
Returns non-0 iff invalid flag is set in ticket.
shishi_tkt_renewable_p
Function:
int
shishi_tkt_renewable_p
Shishi_tkt
tkt
tkt
: input variable with ticket info.
Description:
Determine if ticket is renewable.
The RENEWABLE flag in a ticket is normally only interpreted by the
ticket-granting service (discussed below in section 3.3). It can
usually be ignored by application servers. However, some
particularly careful application servers MAY disallow renewable
tickets.
Return value:
Returns non-0 iff renewable flag is set in ticket.
shishi_tkt_initial_p
Function:
int
shishi_tkt_initial_p
Shishi_tkt
tkt
tkt
: input variable with ticket info.
Description:
Determine if ticket was issued using AS exchange.
The INITIAL flag indicates that a ticket was issued using the AS
protocol, rather than issued based on a ticket-granting ticket.
Application servers that want to require the demonstrated knowledge
of a client’s secret key (e.g. a password-changing program) can
insist that this flag be set in any tickets they accept, and thus
be assured that the client’s key was recently presented to the
application client.
Return value:
Returns non-0 iff initial flag is set in ticket.
shishi_tkt_pre_authent_p
Function:
int
shishi_tkt_pre_authent_p
Shishi_tkt
tkt
tkt
: input variable with ticket info.
Description:
Determine if ticket was pre-authenticated.
The PRE-AUTHENT and HW-AUTHENT flags provide additional information
about the initial authentication, regardless of whether the current
ticket was issued directly (in which case INITIAL will also be set)
or issued on the basis of a ticket-granting ticket (in which case
the INITIAL flag is clear, but the PRE-AUTHENT and HW-AUTHENT flags
are carried forward from the ticket-granting ticket).
Return value:
Returns non-0 iff pre-authent flag is set in ticket.
shishi_tkt_hw_authent_p
Function:
int
shishi_tkt_hw_authent_p
Shishi_tkt
tkt
tkt
: input variable with ticket info.
Description:
Determine if ticket is authenticated using a hardware token.
The PRE-AUTHENT and HW-AUTHENT flags provide additional information
about the initial authentication, regardless of whether the current
ticket was issued directly (in which case INITIAL will also be set)
or issued on the basis of a ticket-granting ticket (in which case
the INITIAL flag is clear, but the PRE-AUTHENT and HW-AUTHENT flags
are carried forward from the ticket-granting ticket).
Return value:
Returns non-0 iff hw-authent flag is set in ticket.
shishi_tkt_transited_policy_checked_p
Function:
int
shishi_tkt_transited_policy_checked_p
Shishi_tkt
tkt
tkt
: input variable with ticket info.
Description:
Determine if ticket has been policy checked for transit.
The application server is ultimately responsible for accepting or
rejecting authentication and SHOULD check that only suitably
trusted KDCs are relied upon to authenticate a principal. The
transited field in the ticket identifies which realms (and thus
which KDCs) were involved in the authentication process and an
application server would normally check this field. If any of these
are untrusted to authenticate the indicated client principal
(probably determined by a realm-based policy), the authentication
attempt MUST be rejected. The presence of trusted KDCs in this list
does not provide any guarantee; an untrusted KDC may have
fabricated the list.
While the end server ultimately decides whether authentication is
valid, the KDC for the end server’s realm MAY apply a realm
specific policy for validating the transited field and accepting
credentials for cross-realm authentication. When the KDC applies
such checks and accepts such cross-realm authentication it will set
the TRANSITED-POLICY-CHECKED flag in the service tickets it issues
based on the cross-realm TGT. A client MAY request that the KDCs
not check the transited field by setting the
DISABLE-TRANSITED-CHECK flag. KDCs are encouraged but not required
to honor this flag.
Application servers MUST either do the transited-realm checks
themselves, or reject cross-realm tickets without TRANSITED-POLICY-
CHECKED set.
Return value:
Returns non-0 iff transited-policy-checked flag is
set in ticket.
shishi_tkt_ok_as_delegate_p
Function:
int
shishi_tkt_ok_as_delegate_p
Shishi_tkt
tkt
tkt
: input variable with ticket info.
Description:
Determine if ticket is ok as delegated ticket.
The copy of the ticket flags in the encrypted part of the KDC reply
may have the OK-AS-DELEGATE flag set to indicates to the client
that the server specified in the ticket has been determined by
policy of the realm to be a suitable recipient of delegation. A
client can use the presence of this flag to help it make a decision
whether to delegate credentials (either grant a proxy or a
forwarded ticket- granting ticket) to this server. It is
acceptable to ignore the value of this flag. When setting this
flag, an administrator should consider the security and placement
of the server on which the service will run, as well as whether the
service requires the use of delegated credentials.
Return value:
Returns non-0 iff ok-as-delegate flag is set in ticket.
shishi_tkt_keytype
Function:
int
shishi_tkt_keytype
Shishi_tkt
tkt
int32_t
etype
tkt
: input variable with ticket info.
etype
: pointer to encryption type that is set, see Shishi_etype.
Description:
Extract encryption type of key in ticket (really EncKDCRepPart).
Return value:
Returns SHISHI_OK iff successful.
shishi_tkt_keytype_fast
Function:
int32_t
shishi_tkt_keytype_fast
Shishi_tkt
tkt
tkt
: input variable with ticket info.
Description:
Extract encryption type of key in ticket (really EncKDCRepPart).
Return value:
Returns encryption type of session key in ticket
(really EncKDCRepPart), or -1 on error.
shishi_tkt_keytype_p
Function:
int
shishi_tkt_keytype_p
Shishi_tkt
tkt
int32_t
etype
tkt
: input variable with ticket info.
etype
: encryption type, see Shishi_etype.
Description:
Determine if key in ticket (really EncKDCRepPart) is of specified
key type (really encryption type).
Return value:
Returns non-0 iff key in ticket is of specified
encryption type.
shishi_tkt_lastreqc
Function:
time_t
shishi_tkt_lastreqc
Shishi_tkt
tkt
Shishi_lrtype
lrtype
tkt
: input variable with ticket info.
lrtype
: lastreq type to extract, see Shishi_lrtype. E.g.,
SHISHI_LRTYPE_LAST_REQUEST.
Description:
Extract C time corresponding to given lastreq type field in the
ticket.
Return value:
Returns C time interpretation of the specified
lastreq field, or (time_t) -1.
shishi_tkt_authctime
Function:
time_t
shishi_tkt_authctime
Shishi_tkt
tkt
tkt
: input variable with ticket info.
Description:
Extract C time corresponding to the authtime field. The field
holds the time when the original authentication took place that
later resulted in this ticket.
Return value:
Returns C time interpretation of the endtime in ticket.
shishi_tkt_startctime
Function:
time_t
shishi_tkt_startctime
Shishi_tkt
tkt
tkt
: input variable with ticket info.
Description:
Extract C time corresponding to the starttime field. The field
holds the time where the ticket start to be valid (typically in the
past).
Return value:
Returns C time interpretation of the endtime in ticket.
shishi_tkt_endctime
Function:
time_t
shishi_tkt_endctime
Shishi_tkt
tkt
tkt
: input variable with ticket info.
Description:
Extract C time corresponding to the endtime field. The field holds
the time where the ticket stop being valid.
Return value:
Returns C time interpretation of the endtime in ticket.
shishi_tkt_renew_tillc
Function:
time_t
shishi_tkt_renew_tillc
Shishi_tkt
tkt
tkt
: input variable with ticket info.
Description:
Extract C time corresponding to the renew-till field. The field
holds the time where the ticket stop being valid for renewal.
Return value:
Returns C time interpretation of the renew-till in ticket.
shishi_tkt_valid_at_time_p
Function:
int
shishi_tkt_valid_at_time_p
Shishi_tkt
tkt
time_t
now
tkt
: input variable with ticket info.
now
: time to check for.
Description:
Determine if ticket is valid at a specific point in time.
Return value:
Returns non-0 iff ticket is valid (not expired and
after starttime) at specified time.
shishi_tkt_valid_now_p
Function:
int
shishi_tkt_valid_now_p
Shishi_tkt
tkt
tkt
: input variable with ticket info.
Description:
Determine if ticket is valid now.
Return value:
Returns 0 iff ticket is invalid (expired or not yet
valid).
shishi_tkt_expired_p
Function:
int
shishi_tkt_expired_p
Shishi_tkt
tkt
tkt
: input variable with ticket info.
Description:
Determine if ticket has expired (i.e., endtime is in the past).
Return value:
Returns 0 iff ticket has expired.
shishi_tkt_lastreq_pretty_print
Function:
void
shishi_tkt_lastreq_pretty_print
Shishi_tkt
tkt
, FILE *
fh
tkt
: input variable with ticket info.
fh
: file handle open for writing.
Description:
Print a human readable representation of the various lastreq fields
in the ticket (really EncKDCRepPart).
shishi_tkt_pretty_print
Function:
void
shishi_tkt_pretty_print
Shishi_tkt
tkt
, FILE *
fh
tkt
: input variable with ticket info.
fh
: file handle open for writing.
Description:
Print a human readable representation of a ticket to file handle.
Next:
TGS Functions
, Previous:
Ticket Functions
, Up:
Programming Manual
Contents
][
Index
5.7 AS Functions
The Authentication Service (AS) is used to get an initial ticket using
e.g. your password. The following illustrates the AS-REQ and AS-REP
ASN.1 structures.
-- Request --
AS-REQ ::= KDC-REQ {10}
KDC-REQ {INTEGER:tagnum} ::= [APPLICATION tagnum] SEQUENCE {
pvno [1] INTEGER (5) -- first tag is [1], not [0] --,
msg-type [2] INTEGER (tagnum),
padata [3] SEQUENCE OF PA-DATA OPTIONAL,
req-body [4] KDC-REQ-BODY
KDC-REQ-BODY ::= SEQUENCE {
kdc-options [0] KDCOptions,
cname [1] PrincipalName OPTIONAL
-- Used only in AS-REQ --,
realm [2] Realm
-- Server's realm
-- Also client's in AS-REQ --,
sname [3] PrincipalName OPTIONAL,
from [4] KerberosTime OPTIONAL,
till [5] KerberosTime,
rtime [6] KerberosTime OPTIONAL,
nonce [7] UInt32,
etype [8] SEQUENCE OF Int32 -- EncryptionType
-- in preference order --,
addresses [9] HostAddresses OPTIONAL,
enc-authorization-data [10] EncryptedData {
AuthorizationData,
{ keyuse-TGSReqAuthData-sesskey
| keyuse-TGSReqAuthData-subkey }
} OPTIONAL,
additional-tickets [11] SEQUENCE OF Ticket OPTIONAL
-- Reply --
AS-REP ::= KDC-REP {11, EncASRepPart, {keyuse-EncASRepPart}}
KDC-REP {INTEGER:tagnum,
TypeToEncrypt,
UInt32:KeyUsages} ::= [APPLICATION tagnum] SEQUENCE {
pvno [0] INTEGER (5),
msg-type [1] INTEGER (tagnum),
padata [2] SEQUENCE OF PA-DATA OPTIONAL,
crealm [3] Realm,
cname [4] PrincipalName,
ticket [5] Ticket,
enc-part [6] EncryptedData {TypeToEncrypt, KeyUsages}
EncASRepPart ::= [APPLICATION 25] EncKDCRepPart
EncKDCRepPart ::= SEQUENCE {
key [0] EncryptionKey,
last-req [1] LastReq,
nonce [2] UInt32,
key-expiration [3] KerberosTime OPTIONAL,
flags [4] TicketFlags,
authtime [5] KerberosTime,
starttime [6] KerberosTime OPTIONAL,
endtime [7] KerberosTime,
renew-till [8] KerberosTime OPTIONAL,
srealm [9] Realm,
sname [10] PrincipalName,
caddr [11] HostAddresses OPTIONAL
shishi_as
Function:
int
shishi_as
(Shishi *
handle
Shishi_as
**
as
handle
: shishi handle as allocated by
shishi_init()
as
: holds pointer to newly allocate Shishi_as structure.
Description:
Allocate a new AS exchange variable.
Return value:
Returns SHISHI_OK iff successful.
shishi_as_done
Function:
void
shishi_as_done
Shishi_as
as
as
: structure that holds information about AS exchange
Description:
Deallocate resources associated with AS exchange. This should be
called by the application when it no longer need to utilize the AS
exchange handle.
shishi_as_req
Function:
Shishi_asn1
shishi_as_req
Shishi_as
as
as
: structure that holds information about AS exchange
Description:
Get ASN.1 AS-REQ structure from AS exchange.
Return value:
Returns the generated AS-REQ packet from the AS
exchange, or NULL if not yet set or an error occured.
shishi_as_req_build
Function:
int
shishi_as_req_build
Shishi_as
as
as
: structure that holds information about AS exchange
Description:
Possibly remove unset fields (e.g., rtime).
Return value:
Returns SHISHI_OK iff successful.
shishi_as_req_set
Function:
void
shishi_as_req_set
Shishi_as
as
Shishi_asn1
asreq
as
: structure that holds information about AS exchange
asreq
: asreq to store in AS.
Description:
Set the AS-REQ in the AS exchange.
shishi_as_req_der
Function:
int
shishi_as_req_der
Shishi_as
as
, char **
out
size_t
outlen
as
: structure that holds information about AS exchange
out
: output array with newly allocated DER encoding of AS-REQ.
outlen
: length of output array with DER encoding of AS-REQ.
Description:
DER encode AS-REQ.
out
is allocated by this function, and it is
the responsibility of caller to deallocate it.
Return value:
Returns SHISHI_OK iff successful.
shishi_as_req_der_set
Function:
int
shishi_as_req_der_set
Shishi_as
as
, char *
der
size_t
derlen
as
: structure that holds information about AS exchange
der
: input array with DER encoded AP-REQ.
derlen
: length of input array with DER encoded AP-REQ.
Description:
DER decode AS-REQ and set it AS exchange. If decoding fails, the
AS-REQ in the AS exchange remains.
Return value:
Returns SHISHI_OK.
shishi_as_rep
Function:
Shishi_asn1
shishi_as_rep
Shishi_as
as
as
: structure that holds information about AS exchange
Description:
Get ASN.1 AS-REP structure from AS exchange.
Return value:
Returns the received AS-REP packet from the AS
exchange, or NULL if not yet set or an error occured.
shishi_as_rep_process
Function:
int
shishi_as_rep_process
Shishi_as
as
Shishi_key
key
, const char *
password
as
: structure that holds information about AS exchange
key
: user’s key, used to encrypt the encrypted part of the AS-REP.
password
: user’s password, used if key is NULL.
Description:
Process new AS-REP and set ticket. The key is used to decrypt the
AP-REP. If both key and password is NULL, the user is queried for
it.
Return value:
Returns SHISHI_OK iff successful.
shishi_as_rep_build
Function:
int
shishi_as_rep_build
Shishi_as
as
Shishi_key
key
as
: structure that holds information about AS exchange
key
: user’s key, used to encrypt the encrypted part of the AS-REP.
Description:
Build AS-REP.
Return value:
Returns SHISHI_OK iff successful.
shishi_as_rep_der
Function:
int
shishi_as_rep_der
Shishi_as
as
, char **
out
size_t
outlen
as
: structure that holds information about AS exchange
out
: output array with newly allocated DER encoding of AS-REP.
outlen
: length of output array with DER encoding of AS-REP.
Description:
DER encode AS-REP.
out
is allocated by this function, and it is
the responsibility of caller to deallocate it.
Return value:
Returns SHISHI_OK iff successful.
shishi_as_rep_set
Function:
void
shishi_as_rep_set
Shishi_as
as
Shishi_asn1
asrep
as
: structure that holds information about AS exchange
asrep
: asrep to store in AS.
Description:
Set the AS-REP in the AS exchange.
shishi_as_rep_der_set
Function:
int
shishi_as_rep_der_set
Shishi_as
as
, char *
der
size_t
derlen
as
: structure that holds information about AS exchange
der
: input array with DER encoded AP-REP.
derlen
: length of input array with DER encoded AP-REP.
Description:
DER decode AS-REP and set it AS exchange. If decoding fails, the
AS-REP in the AS exchange remains.
Return value:
Returns SHISHI_OK.
shishi_as_krberror
Function:
Shishi_asn1
shishi_as_krberror
Shishi_as
as
as
: structure that holds information about AS exchange
Description:
Get ASN.1 KRB-ERROR structure from AS exchange.
Return value:
Returns the received KRB-ERROR packet from the AS
exchange, or NULL if not yet set or an error occured.
shishi_as_krberror_der
Function:
int
shishi_as_krberror_der
Shishi_as
as
, char **
out
size_t
outlen
as
: structure that holds information about AS exchange
out
: output array with newly allocated DER encoding of KRB-ERROR.
outlen
: length of output array with DER encoding of KRB-ERROR.
Description:
DER encode KRB-ERROR.
out
is allocated by this function, and it is
the responsibility of caller to deallocate it.
Return value:
Returns SHISHI_OK iff successful.
shishi_as_krberror_set
Function:
void
shishi_as_krberror_set
Shishi_as
as
Shishi_asn1
krberror
as
: structure that holds information about AS exchange
krberror
: krberror to store in AS.
Description:
Set the KRB-ERROR in the AS exchange.
shishi_as_tkt
Function:
Shishi_tkt *
shishi_as_tkt
Shishi_as
as
as
: structure that holds information about AS exchange
Description:
Get Ticket in AS exchange.
Return value:
Returns the newly acquired tkt from the AS
exchange, or NULL if not yet set or an error occured.
shishi_as_tkt_set
Function:
void
shishi_as_tkt_set
Shishi_as
as
Shishi_tkt
tkt
as
: structure that holds information about AS exchange
tkt
: tkt to store in AS.
Description:
Set the Tkt in the AS exchange.
shishi_as_sendrecv_hint
Function:
int
shishi_as_sendrecv_hint
Shishi_as
as
Shishi_tkts_hint
hint
as
: structure that holds information about AS exchange
hint
: additional parameters that modify connection behaviour, or
NULL
Description:
Send AS-REQ and receive AS-REP or KRB-ERROR. This is the initial
authentication, usually used to acquire a Ticket Granting Ticket.
The
hint
structure can be used to set, e.g., parameters for TLS
authentication.
Return value:
Returns SHISHI_OK iff successful.
shishi_as_sendrecv
Function:
int
shishi_as_sendrecv
Shishi_as
as
as
: structure that holds information about AS exchange
Description:
Send AS-REQ and receive AS-REP or KRB-ERROR. This is the initial
authentication, usually used to acquire a Ticket Granting Ticket.
Return value:
Returns SHISHI_OK iff successful.
Next:
Ticket (ASN.1) Functions
, Previous:
AS Functions
, Up:
Programming Manual
Contents
][
Index
5.8 TGS Functions
The Ticket Granting Service (TGS) is used to get subsequent tickets,
authenticated by other tickets (so called ticket granting tickets).
The following illustrates the TGS-REQ and TGS-REP ASN.1 structures.
-- Request --
TGS-REQ ::= KDC-REQ {12}
KDC-REQ {INTEGER:tagnum} ::= [APPLICATION tagnum] SEQUENCE {
pvno [1] INTEGER (5) -- first tag is [1], not [0] --,
msg-type [2] INTEGER (tagnum),
padata [3] SEQUENCE OF PA-DATA OPTIONAL,
req-body [4] KDC-REQ-BODY
KDC-REQ-BODY ::= SEQUENCE {
kdc-options [0] KDCOptions,
cname [1] PrincipalName OPTIONAL
-- Used only in AS-REQ --,
realm [2] Realm
-- Server's realm
-- Also client's in AS-REQ --,
sname [3] PrincipalName OPTIONAL,
from [4] KerberosTime OPTIONAL,
till [5] KerberosTime,
rtime [6] KerberosTime OPTIONAL,
nonce [7] UInt32,
etype [8] SEQUENCE OF Int32 -- EncryptionType
-- in preference order --,
addresses [9] HostAddresses OPTIONAL,
enc-authorization-data [10] EncryptedData {
AuthorizationData,
{ keyuse-TGSReqAuthData-sesskey
| keyuse-TGSReqAuthData-subkey }
} OPTIONAL,
additional-tickets [11] SEQUENCE OF Ticket OPTIONAL
-- Reply --
TGS-REP ::= KDC-REP {13, EncTGSRepPart,
{ keyuse-EncTGSRepPart-sesskey
| keyuse-EncTGSRepPart-subkey }}
KDC-REP {INTEGER:tagnum,
TypeToEncrypt,
UInt32:KeyUsages} ::= [APPLICATION tagnum] SEQUENCE {
pvno [0] INTEGER (5),
msg-type [1] INTEGER (tagnum),
padata [2] SEQUENCE OF PA-DATA OPTIONAL,
crealm [3] Realm,
cname [4] PrincipalName,
ticket [5] Ticket,
enc-part [6] EncryptedData {TypeToEncrypt, KeyUsages}
EncTGSRepPart ::= [APPLICATION 26] EncKDCRepPart
EncKDCRepPart ::= SEQUENCE {
key [0] EncryptionKey,
last-req [1] LastReq,
nonce [2] UInt32,
key-expiration [3] KerberosTime OPTIONAL,
flags [4] TicketFlags,
authtime [5] KerberosTime,
starttime [6] KerberosTime OPTIONAL,
endtime [7] KerberosTime,
renew-till [8] KerberosTime OPTIONAL,
srealm [9] Realm,
sname [10] PrincipalName,
caddr [11] HostAddresses OPTIONAL
shishi_tgs
Function:
int
shishi_tgs
(Shishi *
handle
Shishi_tgs
**
tgs
handle
: shishi handle as allocated by
shishi_init()
tgs
: holds pointer to newly allocate Shishi_tgs structure.
Description:
Allocate a new TGS exchange variable.
Return value:
Returns SHISHI_OK iff successful.
shishi_tgs_done
Function:
void
shishi_tgs_done
Shishi_tgs
tgs
tgs
: structure that holds information about AS exchange
Description:
Deallocate resources associated with TGS exchange. This should be
called by the application when it no longer need to utilize the TGS
exchange handle.
shishi_tgs_tgtkt
Function:
Shishi_tkt *
shishi_tgs_tgtkt
Shishi_tgs
tgs
tgs
: structure that holds information about TGS exchange
Description:
Get Ticket-granting-ticket from TGS exchange.
Return value:
Returns the ticket-granting-ticket used in the TGS
exchange, or NULL if not yet set or an error occured.
shishi_tgs_tgtkt_set
Function:
void
shishi_tgs_tgtkt_set
Shishi_tgs
tgs
Shishi_tkt
tgtkt
tgs
: structure that holds information about TGS exchange
tgtkt
: ticket granting ticket to store in TGS.
Description:
Set the Ticket in the TGS exchange.
shishi_tgs_ap
Function:
Shishi_ap *
shishi_tgs_ap
Shishi_tgs
tgs
tgs
: structure that holds information about TGS exchange
Description:
Get the AP from TGS exchange.
Return value:
Returns the AP exchange (part of TGS-REQ) from the
TGS exchange, or NULL if not yet set or an error
occured.
shishi_tgs_req
Function:
Shishi_asn1
shishi_tgs_req
Shishi_tgs
tgs
tgs
: structure that holds information about TGS exchange
Description:
Get the TGS-REQ from TGS exchange.
Return value:
Returns the generated TGS-REQ from the TGS exchange,
or NULL if not yet set or an error occured.
shishi_tgs_req_set
Function:
void
shishi_tgs_req_set
Shishi_tgs
tgs
Shishi_asn1
tgsreq
tgs
: structure that holds information about TGS exchange
tgsreq
: tgsreq to store in TGS.
Description:
Set the TGS-REQ in the TGS exchange.
shishi_tgs_req_der
Function:
int
shishi_tgs_req_der
Shishi_tgs
tgs
, char **
out
size_t
outlen
tgs
: structure that holds information about TGS exchange
out
: output array with newly allocated DER encoding of TGS-REQ.
outlen
: length of output array with DER encoding of TGS-REQ.
Description:
DER encode TGS-REQ.
out
is allocated by this function, and it is
the responsibility of caller to deallocate it.
Return value:
Returns SHISHI_OK iff successful.
shishi_tgs_req_der_set
Function:
int
shishi_tgs_req_der_set
Shishi_tgs
tgs
, char *
der
size_t
derlen
tgs
: structure that holds information about TGS exchange
der
: input array with DER encoded AP-REQ.
derlen
: length of input array with DER encoded AP-REQ.
Description:
DER decode TGS-REQ and set it TGS exchange. If decoding fails, the
TGS-REQ in the TGS exchange remains.
Return value:
Returns SHISHI_OK.
shishi_tgs_req_process
Function:
int
shishi_tgs_req_process
Shishi_tgs
tgs
tgs
: structure that holds information about TGS exchange
Description:
Process new TGS-REQ and set ticket. The key to decrypt the TGS-REQ
is taken from the EncKDCReqPart of the TGS tgticket.
Return value:
Returns SHISHI_OK iff successful.
shishi_tgs_req_build
Function:
int
shishi_tgs_req_build
Shishi_tgs
tgs
tgs
: structure that holds information about TGS exchange
Description:
Checksum data in authenticator and add ticket and authenticator to
TGS-REQ.
Return value:
Returns SHISHI_OK iff successful.
shishi_tgs_rep
Function:
Shishi_asn1
shishi_tgs_rep
Shishi_tgs
tgs
tgs
: structure that holds information about TGS exchange
Description:
Get TGS-REP from TGS exchange.
Return value:
Returns the received TGS-REP from the TGS exchange,
or NULL if not yet set or an error occured.
shishi_tgs_rep_der
Function:
int
shishi_tgs_rep_der
Shishi_tgs
tgs
, char **
out
size_t
outlen
tgs
: structure that holds information about TGS exchange
out
: output array with newly allocated DER encoding of TGS-REP.
outlen
: length of output array with DER encoding of TGS-REP.
Description:
DER encode TGS-REP.
out
is allocated by this function, and it is
the responsibility of caller to deallocate it.
Return value:
Returns SHISHI_OK iff successful.
shishi_tgs_rep_process
Function:
int
shishi_tgs_rep_process
Shishi_tgs
tgs
tgs
: structure that holds information about TGS exchange
Description:
Process new TGS-REP and set ticket. The key to decrypt the TGS-REP
is taken from the EncKDCRepPart of the TGS tgticket.
Return value:
Returns SHISHI_OK iff successful.
shishi_tgs_rep_build
Function:
int
shishi_tgs_rep_build
Shishi_tgs
tgs
, int
keyusage
Shishi_key
key
tgs
: structure that holds information about TGS exchange
keyusage
: keyusage integer.
key
: user’s key, used to encrypt the encrypted part of the TGS-REP.
Description:
Build TGS-REP.
Return value:
Returns SHISHI_OK iff successful.
shishi_tgs_krberror
Function:
Shishi_asn1
shishi_tgs_krberror
Shishi_tgs
tgs
tgs
: structure that holds information about TGS exchange
Description:
Get KRB-ERROR from TGS exchange.
Return value:
Returns the received TGS-REP from the TGS exchange,
or NULL if not yet set or an error occured.
shishi_tgs_krberror_der
Function:
int
shishi_tgs_krberror_der
Shishi_tgs
tgs
, char **
out
size_t
outlen
tgs
: structure that holds information about TGS exchange
out
: output array with newly allocated DER encoding of KRB-ERROR.
outlen
: length of output array with DER encoding of KRB-ERROR.
Description:
DER encode KRB-ERROR.
out
is allocated by this function, and it is
the responsibility of caller to deallocate it.
Return value:
Returns SHISHI_OK iff successful.
shishi_tgs_krberror_set
Function:
void
shishi_tgs_krberror_set
Shishi_tgs
tgs
Shishi_asn1
krberror
tgs
: structure that holds information about TGS exchange
krberror
: krberror to store in TGS.
Description:
Set the KRB-ERROR in the TGS exchange.
shishi_tgs_tkt
Function:
Shishi_tkt *
shishi_tgs_tkt
Shishi_tgs
tgs
tgs
: structure that holds information about TGS exchange
Description:
Get Ticket from TGS exchange.
Return value:
Returns the newly acquired ticket from the TGS
exchange, or NULL if not yet set or an error occured.
shishi_tgs_tkt_set
Function:
void
shishi_tgs_tkt_set
Shishi_tgs
tgs
Shishi_tkt
tkt
tgs
: structure that holds information about TGS exchange
tkt
: ticket to store in TGS.
Description:
Set the Ticket in the TGS exchange.
shishi_tgs_sendrecv_hint
Function:
int
shishi_tgs_sendrecv_hint
Shishi_tgs
tgs
Shishi_tkts_hint
hint
tgs
: structure that holds information about TGS exchange
hint
: additional parameters that modify connection behaviour, or
NULL
Description:
Send TGS-REQ and receive TGS-REP or KRB-ERROR. This is the
subsequent authentication, usually used to acquire server tickets.
The
hint
structure can be used to set, e.g., parameters for TLS
authentication.
Return value:
Returns SHISHI_OK iff successful.
shishi_tgs_sendrecv
Function:
int
shishi_tgs_sendrecv
Shishi_tgs
tgs
tgs
: structure that holds information about TGS exchange
Description:
Send TGS-REQ and receive TGS-REP or KRB-ERROR. This is the
subsequent authentication, usually used to acquire server tickets.
Return value:
Returns SHISHI_OK iff successful.
shishi_tgs_set_server
Function:
int
shishi_tgs_set_server
Shishi_tgs
tgs
, const char *
server
tgs
: structure that holds information about TGS exchange
server
: indicates the server to acquire ticket for.
Description:
Set the server in the TGS-REQ.
Return value:
Returns SHISHI_OK iff successful.
shishi_tgs_set_realm
Function:
int
shishi_tgs_set_realm
Shishi_tgs
tgs
, const char *
realm
tgs
: structure that holds information about TGS exchange
realm
: indicates the realm to acquire ticket for.
Description:
Set the server in the TGS-REQ.
Return value:
Returns SHISHI_OK iff successful.
shishi_tgs_set_realmserver
Function:
int
shishi_tgs_set_realmserver
Shishi_tgs
tgs
, const char *
realm
, const char *
server
tgs
: structure that holds information about TGS exchange
realm
: indicates the realm to acquire ticket for.
server
: indicates the server to acquire ticket for.
Description:
Set the realm and server in the TGS-REQ.
Return value:
Returns SHISHI_OK iff successful.
Next:
AS/TGS Functions
, Previous:
TGS Functions
, Up:
Programming Manual
Contents
][
Index
5.9 Ticket (ASN.1) Functions
See
Ticket Functions
, for an high-level overview of tickets. The
following illustrates the Ticket and EncTicketPart ASN.1 structures.
Ticket ::= [APPLICATION 1] SEQUENCE {
tkt-vno [0] INTEGER (5),
realm [1] Realm,
sname [2] PrincipalName,
enc-part [3] EncryptedData -- EncTicketPart
-- Encrypted part of ticket
EncTicketPart ::= [APPLICATION 3] SEQUENCE {
flags [0] TicketFlags,
key [1] EncryptionKey,
crealm [2] Realm,
cname [3] PrincipalName,
transited [4] TransitedEncoding,
authtime [5] KerberosTime,
starttime [6] KerberosTime OPTIONAL,
endtime [7] KerberosTime,
renew-till [8] KerberosTime OPTIONAL,
caddr [9] HostAddresses OPTIONAL,
authorization-data [10] AuthorizationData OPTIONAL
shishi_ticket
Function:
Shishi_asn1
shishi_ticket
(Shishi *
handle
handle
: shishi handle as allocated by
shishi_init()
Description:
This function creates a new ASN.1 Ticket, populated with some
default values.
Return value:
Returns the ticket or NULL on failure.
shishi_ticket_realm_get
Function:
int
shishi_ticket_realm_get
(Shishi *
handle
Shishi_asn1
ticket
, char **
realm
size_t
realmlen
handle
: shishi handle as allocated by
shishi_init()
ticket
: input variable with ticket info.
realm
: output array with newly allocated name of realm in ticket.
realmlen
: size of output array.
Description:
Extract realm from ticket.
Return value:
Returns SHISHI_OK iff successful.
shishi_ticket_realm_set
Function:
int
shishi_ticket_realm_set
(Shishi *
handle
Shishi_asn1
ticket
, const char *
realm
handle
: shishi handle as allocated by
shishi_init()
ticket
: input variable with ticket info.
realm
: input array with name of realm.
Description:
Set the realm field in the Ticket.
Return value:
Returns SHISHI_OK iff successful.
shishi_ticket_server
Function:
int
shishi_ticket_server
(Shishi *
handle
Shishi_asn1
ticket
, char **
server
size_t
serverlen
handle
: Shishi library handle create by
shishi_init()
ticket
: ASN.1 Ticket variable to get server name from.
server
: pointer to newly allocated zero terminated string containing
principal name. May be
NULL
(to only populate
serverlen
).
serverlen
: pointer to length of
server
on output, excluding terminating
zero. May be
NULL
(to only populate
server
).
Description:
Represent server principal name in Ticket as zero-terminated
string. The string is allocate by this function, and it is the
responsibility of the caller to deallocate it. Note that the
output length
serverlen
does not include the terminating zero.
Return value:
Returns SHISHI_OK iff successful.
shishi_ticket_sname_set
Function:
int
shishi_ticket_sname_set
(Shishi *
handle
Shishi_asn1
ticket
Shishi_name_type
name_type
, char *
sname
[]
handle
: shishi handle as allocated by
shishi_init()
ticket
: Ticket variable to set server name field in.
name_type
: type of principial, see Shishi_name_type, usually
SHISHI_NT_UNKNOWN.
sname
: input array with principal name.
Description:
Set the server name field in the Ticket.
Return value:
Returns SHISHI_OK iff successful.
shishi_ticket_get_enc_part_etype
Function:
int
shishi_ticket_get_enc_part_etype
(Shishi *
handle
Shishi_asn1
ticket
int32_t
etype
handle
: shishi handle as allocated by
shishi_init()
ticket
: Ticket variable to get value from.
etype
: output variable that holds the value.
Description:
Extract Ticket.enc-part.etype.
Return value:
Returns SHISHI_OK iff successful.
shishi_ticket_set_enc_part
Function:
int
shishi_ticket_set_enc_part
(Shishi *
handle
Shishi_asn1
ticket
int32_t
etype
uint32_t
kvno
, const char *
buf
size_t
buflen
handle
: shishi handle as allocated by
shishi_init()
ticket
: Ticket to add enc-part field to.
etype
: encryption type used to encrypt enc-part.
kvno
: key version number.
buf
: input array with encrypted enc-part.
buflen
: size of input array with encrypted enc-part.
Description:
Set the encrypted enc-part field in the Ticket. The encrypted data
is usually created by calling
shishi_encrypt()
on the DER encoded
enc-part. To save time, you may want to use
shishi_ticket_add_enc_part()
instead, which calculates the
encrypted data and calls this function in one step.
Return value:
Returns SHISHI_OK iff successful.
shishi_ticket_add_enc_part
Function:
int
shishi_ticket_add_enc_part
(Shishi *
handle
Shishi_asn1
ticket
Shishi_key
key
Shishi_asn1
encticketpart
handle
: shishi handle as allocated by
shishi_init()
ticket
: Ticket to add enc-part field to.
key
: key used to encrypt enc-part.
encticketpart
: EncTicketPart to add.
Description:
Encrypts DER encoded EncTicketPart using key and stores it in the
Ticket.
Return value:
Returns SHISHI_OK iff successful.
shishi_encticketpart_get_key
Function:
int
shishi_encticketpart_get_key
(Shishi *
handle
Shishi_asn1
encticketpart
Shishi_key
**
key
handle
: shishi handle as allocated by
shishi_init()
encticketpart
: input EncTicketPart variable.
key
: newly allocated key.
Description:
Extract the session key in the Ticket.
Return value:
Returns
SHISHI_OK
iff successful.
shishi_encticketpart_key_set
Function:
int
shishi_encticketpart_key_set
(Shishi *
handle
Shishi_asn1
encticketpart
Shishi_key
key
handle
: shishi handle as allocated by
shishi_init()
encticketpart
: input EncTicketPart variable.
key
: key handle with information to store in encticketpart.
Description:
Set the EncTicketPart.key field to key type and value of supplied
key.
Return value:
Returns
SHISHI_OK
iff successful.
shishi_encticketpart_flags_set
Function:
int
shishi_encticketpart_flags_set
(Shishi *
handle
Shishi_asn1
encticketpart
, int
flags
handle
: shishi handle as allocated by
shishi_init()
encticketpart
: input EncTicketPart variable.
flags
: flags to set in encticketpart.
Description:
Set the EncTicketPart.flags to supplied value.
Return value:
Returns
SHISHI_OK
iff successful.
shishi_encticketpart_crealm_set
Function:
int
shishi_encticketpart_crealm_set
(Shishi *
handle
Shishi_asn1
encticketpart
, const char *
realm
handle
: shishi handle as allocated by
shishi_init()
encticketpart
: input EncTicketPart variable.
realm
: input array with name of realm.
Description:
Set the realm field in the KDC-REQ.
Return value:
Returns SHISHI_OK iff successful.
shishi_encticketpart_cname_set
Function:
int
shishi_encticketpart_cname_set
(Shishi *
handle
Shishi_asn1
encticketpart
Shishi_name_type
name_type
, const char *
principal
handle
: shishi handle as allocated by
shishi_init()
encticketpart
: input EncTicketPart variable.
name_type
: type of principial, see Shishi_name_type, usually
SHISHI_NT_UNKNOWN.
principal
: input array with principal name.
Description:
Set the client name field in the EncTicketPart.
Return value:
Returns SHISHI_OK iff successful.
shishi_encticketpart_transited_set
Function:
int
shishi_encticketpart_transited_set
(Shishi *
handle
Shishi_asn1
encticketpart
int32_t
trtype
, const char *
trdata
size_t
trdatalen
handle
: shishi handle as allocated by
shishi_init()
encticketpart
: input EncTicketPart variable.
trtype
: transitedencoding type, e.g. SHISHI_TR_DOMAIN_X500_COMPRESS.
trdata
: actual transited realm data.
trdatalen
: length of actual transited realm data.
Description:
Set the EncTicketPart.transited field to supplied value.
Return value:
Returns
SHISHI_OK
iff successful.
shishi_encticketpart_authtime_set
Function:
int
shishi_encticketpart_authtime_set
(Shishi *
handle
Shishi_asn1
encticketpart
, const char *
authtime
handle
: shishi handle as allocated by
shishi_init()
encticketpart
: input EncTicketPart variable.
authtime
: character buffer containing a generalized time string.
Description:
Set the EncTicketPart.authtime to supplied value.
Return value:
Returns
SHISHI_OK
iff successful.
shishi_encticketpart_endtime_set
Function:
int
shishi_encticketpart_endtime_set
(Shishi *
handle
Shishi_asn1
encticketpart
, const char *
endtime
handle
: shishi handle as allocated by
shishi_init()
encticketpart
: input EncTicketPart variable.
endtime
: character buffer containing a generalized time string.
Description:
Set the EncTicketPart.endtime to supplied value.
Return value:
Returns
SHISHI_OK
iff successful.
shishi_encticketpart_client
Function:
int
shishi_encticketpart_client
(Shishi *
handle
Shishi_asn1
encticketpart
, char **
client
size_t
clientlen
handle
: Shishi library handle create by
shishi_init()
encticketpart
: EncTicketPart variable to get client name from.
client
: pointer to newly allocated zero terminated string containing
principal name. May be
NULL
(to only populate
clientlen
).
clientlen
: pointer to length of
client
on output, excluding terminating
zero. May be
NULL
(to only populate
client
).
Description:
Represent client principal name in EncTicketPart as zero-terminated
string. The string is allocate by this function, and it is the
responsibility of the caller to deallocate it. Note that the
output length
clientlen
does not include the terminating zero.
Return value:
Returns SHISHI_OK iff successful.
shishi_encticketpart_clientrealm
Function:
int
shishi_encticketpart_clientrealm
(Shishi *
handle
Shishi_asn1
encticketpart
, char **
client
size_t
clientlen
handle
: Shishi library handle create by
shishi_init()
encticketpart
: EncTicketPart variable to get client name and realm from.
client
: pointer to newly allocated zero terminated string containing
principal name and realm. May be
NULL
(to only populate
clientlen
).
clientlen
: pointer to length of
client
on output, excluding terminating
zero. May be
NULL
(to only populate
client
).
Description:
Convert cname and realm fields from EncTicketPart to printable
principal name format. The string is allocate by this function,
and it is the responsibility of the caller to deallocate it. Note
that the output length
clientlen
does not include the terminating
zero.
Return value:
Returns SHISHI_OK iff successful.
Next:
Authenticator Functions
, Previous:
Ticket (ASN.1) Functions
, Up:
Programming Manual
Contents
][
Index
5.10 AS/TGS Functions
The Authentication Service (AS) is used to get an initial ticket using
e.g. your password. The Ticket Granting Service (TGS) is used to get
subsequent tickets using other tickets. Protocol wise the procedures
are very similar, which is the reason they are described together.
The following illustrates the AS-REQ, TGS-REQ and AS-REP, TGS-REP
ASN.1 structures. Most of the functions use the mnemonic “KDC”
instead of either AS or TGS, which means the function operates on both
AS and TGS types. Only where the distinction between AS and TGS is
important are the AS and TGS names used. Remember, these are
low-level functions, and normal applications will likely be satisfied
with the AS (see
AS Functions
) and TGS (see
TGS Functions
interfaces, or the even more high-level Ticket Set (see
Ticket Set Functions
) interface.
-- Request --
AS-REQ ::= KDC-REQ {10}
TGS-REQ ::= KDC-REQ {12}
KDC-REQ {INTEGER:tagnum} ::= [APPLICATION tagnum] SEQUENCE {
pvno [1] INTEGER (5) -- first tag is [1], not [0] --,
msg-type [2] INTEGER (tagnum),
padata [3] SEQUENCE OF PA-DATA OPTIONAL,
req-body [4] KDC-REQ-BODY
KDC-REQ-BODY ::= SEQUENCE {
kdc-options [0] KDCOptions,
cname [1] PrincipalName OPTIONAL
-- Used only in AS-REQ --,
realm [2] Realm
-- Server's realm
-- Also client's in AS-REQ --,
sname [3] PrincipalName OPTIONAL,
from [4] KerberosTime OPTIONAL,
till [5] KerberosTime,
rtime [6] KerberosTime OPTIONAL,
nonce [7] UInt32,
etype [8] SEQUENCE OF Int32 -- EncryptionType
-- in preference order --,
addresses [9] HostAddresses OPTIONAL,
enc-authorization-data [10] EncryptedData {
AuthorizationData,
{ keyuse-TGSReqAuthData-sesskey
| keyuse-TGSReqAuthData-subkey }
} OPTIONAL,
additional-tickets [11] SEQUENCE OF Ticket OPTIONAL
-- Reply --
AS-REP ::= KDC-REP {11, EncASRepPart, {keyuse-EncASRepPart}}
TGS-REP ::= KDC-REP {13, EncTGSRepPart,
{ keyuse-EncTGSRepPart-sesskey
| keyuse-EncTGSRepPart-subkey }}
KDC-REP {INTEGER:tagnum,
TypeToEncrypt,
UInt32:KeyUsages} ::= [APPLICATION tagnum] SEQUENCE {
pvno [0] INTEGER (5),
msg-type [1] INTEGER (tagnum),
padata [2] SEQUENCE OF PA-DATA OPTIONAL,
crealm [3] Realm,
cname [4] PrincipalName,
ticket [5] Ticket,
enc-part [6] EncryptedData {TypeToEncrypt, KeyUsages}
EncASRepPart ::= [APPLICATION 25] EncKDCRepPart
EncTGSRepPart ::= [APPLICATION 26] EncKDCRepPart
EncKDCRepPart ::= SEQUENCE {
key [0] EncryptionKey,
last-req [1] LastReq,
nonce [2] UInt32,
key-expiration [3] KerberosTime OPTIONAL,
flags [4] TicketFlags,
authtime [5] KerberosTime,
starttime [6] KerberosTime OPTIONAL,
endtime [7] KerberosTime,
renew-till [8] KerberosTime OPTIONAL,
srealm [9] Realm,
sname [10] PrincipalName,
caddr [11] HostAddresses OPTIONAL
shishi_as_derive_salt
Function:
int
shishi_as_derive_salt
(Shishi *
handle
Shishi_asn1
asreq
Shishi_asn1
asrep
, char **
salt
size_t
saltlen
handle
: Shishi handle as allocated by
shishi_init()
asreq
: Input AS-REQ variable.
asrep
: Input AS-REP variable.
salt
: Returned pointer to newly allocated output array.
saltlen
: Pointer to integer, returning size of output array.
Description:
Computes the salt that should be used when deriving a key via
shishi_string_to_key()
for an AS exchange. Currently this
searches for PA-DATA of type
SHISHI_PA_PW_SALT
in the AS-REP
provided by
asrep
, and if present returns it. Otherwise the
salt is composed from the client name and the realm, both are
extracted from the request
asreq
Return value:
Returns
SHISHI_OK
if successful.
Failure conditions include various ASN.1 issues.
shishi_kdcreq_sendrecv_hint
Function:
int
shishi_kdcreq_sendrecv_hint
(Shishi *
handle
Shishi_asn1
kdcreq
Shishi_asn1
kdcrep
Shishi_tkts_hint
hint
handle
: Shishi library handle created by
shishi_init()
kdcreq
: Input variable with a prepared AS-REQ.
kdcrep
: Output pointer variable for decoded AS-REP.
hint
: Input
Shishi_tkts_hint
structure with flags.
Description:
Sends a request to KDC, and receives the response.
The provided request
kdcreq
and the hints structure
hint
together determine transmitted data. On reception the reply
is decoded as AS-REP into
kdcrep
Return value:
Return code is
SHISHI_OK
on success,
SHISHI_KDC_TIMEOUT
on timeouts,
SHISHI_ASN1_ERROR
on
translation errors, and
SHISHI_GOT_KRBERROR
for other
corruptions.
shishi_kdcreq_sendrecv
Function:
int
shishi_kdcreq_sendrecv
(Shishi *
handle
Shishi_asn1
kdcreq
Shishi_asn1
kdcrep
handle
: Shishi library handle created by
shishi_init()
kdcreq
: Input variable with a prepared AS-REQ.
kdcrep
: Output pointer variable returning received AS-REP.
Description:
Sends a request to KDC, and receives the response.
The provided AS-REQ, in
kdcreq
, sets all data for the
request. On reception the reply is decoded as AS-REP
into
kdcrep
Return value:
Return code is
SHISHI_OK
on success,
SHISHI_KDC_TIMEOUT
on timeouts,
SHISHI_ASN1_ERROR
on
translation errors, and
SHISHI_GOT_KRBERROR
for other
corruptions.
shishi_kdc_copy_crealm
Function:
int
shishi_kdc_copy_crealm
(Shishi *
handle
Shishi_asn1
kdcrep
Shishi_asn1
encticketpart
handle
: Shishi handle as allocated by
shishi_init()
kdcrep
: KDC-REP where the field "crealm" is updated.
encticketpart
: EncTicketPart providing "crealm" field.
Description:
Reads the field "crealm" from the ticket
encticketpart
and copies the value into the reply
kdcrep
Return value:
Returns
SHISHI_OK
if successful, and ASN.1
failures otherwise.
shishi_as_check_crealm
Function:
int
shishi_as_check_crealm
(Shishi *
handle
Shishi_asn1
asreq
Shishi_asn1
asrep
handle
: Shishi handle as allocated by
shishi_init()
asreq
: Request of type AS-REQ.
asrep
: Reply structure of type AS-REP.
Description:
Verifies that the fields
asreq
.req-body.realm and
asrep
.crealm
contain identical realm names. This is one of the steps that
has to be performed when processing an exchange of AS-REQ and
AS-REP; see
shishi_kdc_process()
for more details.
Return value:
Returns
SHISHI_OK
if successful,
SHISHI_REALM_MISMATCH
whenever the realm names differ,
and an error code otherwise.
shishi_kdc_copy_cname
Function:
int
shishi_kdc_copy_cname
(Shishi *
handle
Shishi_asn1
kdcrep
Shishi_asn1
encticketpart
handle
: Shishi handle as allocated by
shishi_init()
kdcrep
: KDC-REP where the field "cname" is updated.
encticketpart
: EncTicketPart providing "cname" field.
Description:
Reads the field "cname" from the ticket
encticketpart
and copies the value into the reply
kdcrep
Return value:
Returns
SHISHI_OK
if successful, and ASN.1
failures otherwise.
shishi_as_check_cname
Function:
int
shishi_as_check_cname
(Shishi *
handle
Shishi_asn1
asreq
Shishi_asn1
asrep
handle
: Shishi handle as allocated by
shishi_init()
asreq
: Request of type AS-REQ.
asrep
: Reply structure of type AS-REP.
Description:
Verifies that the fields
asreq
.req-body.cname and
asrep
.cname
contain identical names. This is one of the steps that has to
be performed when processing an exchange of AS-REQ and AS-REP;
see
shishi_kdc_process()
for more details.
Return value:
Returns
SHISHI_OK
if successful,
SHISHI_CNAME_MISMATCH
if the names differ,
and an error code otherwise.
shishi_kdc_copy_nonce
Function:
int
shishi_kdc_copy_nonce
(Shishi *
handle
Shishi_asn1
kdcreq
Shishi_asn1
enckdcreppart
handle
: Shishi handle as allocated by
shishi_init()
kdcreq
: KDC-REQ providing "nonce" field.
enckdcreppart
: EncKDCRepPart where "nonce" field is updated.
Description:
Sets the field "nonce" in
enckdcreppart
to a value retreived
from the corresponding field in
kdcreq
Return value:
Returns
SHISHI_OK
if successful.
shishi_kdc_check_nonce
Function:
int
shishi_kdc_check_nonce
(Shishi *
handle
Shishi_asn1
kdcreq
Shishi_asn1
enckdcreppart
handle
: Shishi handle as allocated by
shishi_init()
kdcreq
: Request of type KDC-REQ.
enckdcreppart
: Encrypted KDC-REP part.
Description:
Verifies that
kdcreq
.req-body.nonce and
enckdcreppart
.nonce
contain matching values. This is one of the steps that has to
be performed when processing an exchange of KDC-REQ and KDC-REP.
Return value:
Returns
SHISHI_OK
if successful,
SHISHI_NONCE_MISMATCH
whenever the nonces are of
differing lengths (usually a sign that a buggy server
truncates the nonce to 4 bytes) and the same code if the
nonce values differ, or an error code otherwise.
shishi_tgs_process
Function:
int
shishi_tgs_process
(Shishi *
handle
Shishi_asn1
tgsreq
Shishi_asn1
tgsrep
Shishi_asn1
authenticator
Shishi_asn1
oldenckdcreppart
Shishi_asn1
enckdcreppart
handle
: Shishi handle as allocated by
shishi_init()
tgsreq
: Input variable holding the transmitted KDC-REQ.
tgsrep
: Input variable holding the received KDC-REP.
authenticator
: Input variable with an authenticator extracted
from the AP-REQ part of
tgsreq
oldenckdcreppart
: Input variable with EncKDCRepPart used
in the request.
enckdcreppart
: Output variable holding the new EncKDCRepPart.
Description:
Processes a TGS client exchange and outputs the decrypted
EncKDCRepPart, holding details about the received ticket.
This function simply derives the encryption key from the
ticket used to construct the original TGS request, and then
calls
shishi_kdc_process()
Return value:
Returns
SHISHI_OK
if the TGS client exchange
was successful. Failures include ASN.1 and TGS conditions.
shishi_as_process
Function:
int
shishi_as_process
(Shishi *
handle
Shishi_asn1
asreq
Shishi_asn1
asrep
, const char *
string
Shishi_asn1
enckdcreppart
handle
: Shishi handle as allocated by
shishi_init()
asreq
: Input variable holding the transmitted KDC-REQ.
asrep
: Input variable holding the received KDC-REP.
string
: Input variable with a null terminated password.
enckdcreppart
: Output variable returning a new EncKDCRepPart.
Description:
Processes an AS client exchange and returns the decrypted
EncKDCRepPart, holding details about the received ticket.
This function simply derives the encryption key from the
password, and then calls
shishi_kdc_process()
Return value:
Returns
SHISHI_OK
if the AS client exchange was
successful. Multiple failure conditions are possible.
shishi_kdc_process
Function:
int
shishi_kdc_process
(Shishi *
handle
Shishi_asn1
kdcreq
Shishi_asn1
kdcrep
Shishi_key
key
, int
keyusage
Shishi_asn1
enckdcreppart
handle
: Shishi handle as allocated by
shishi_init()
kdcreq
: Input variable holding the transmitted KDC-REQ.
kdcrep
: Input variable holding the received KDC-REP.
key
: Input pointet to key for decrypting parts of
kdcrep
keyusage
: Kerberos key usage code.
enckdcreppart
: Output pointer for the extracted EncKDCRepPart.
Description:
Processes a KDC client exchange and extracts a decrypted
EncKDCRepPart, holding details about the received ticket.
Use
shishi_kdcrep_get_ticket()
to extract the ticket itself.
This function verifies the various conditions that must hold
if the response is to be considered valid. In particular,
it compares nonces (using
shishi_kdc_check_nonce()
), and if
the exchange was an AS exchange, it also checks cname and
crealm (using
shishi_as_check_cname()
shishi_as_check_crealm()
).
Usually
shishi_as_process()
and
shishi_tgs_process()
should be
used instead of this call, since they simplify computation of
the decryption key.
Return value:
Returns
SHISHI_OK
if the KDC client exchange was
successful. Multiple failure conditions are possible.
shishi_asreq
Function:
Shishi_asn1
shishi_asreq
(Shishi *
handle
handle
: shishi handle as allocated by
shishi_init()
Description:
This function creates a new AS-REQ, populated with some default
values.
Return value:
Returns the AS-REQ or NULL on failure.
shishi_tgsreq
Function:
Shishi_asn1
shishi_tgsreq
(Shishi *
handle
handle
: shishi handle as allocated by
shishi_init()
Description:
This function creates a new TGS-REQ, populated with some default
values.
Return value:
Returns the TGS-REQ or NULL on failure.
shishi_kdcreq_print
Function:
int
shishi_kdcreq_print
(Shishi *
handle
, FILE *
fh
Shishi_asn1
kdcreq
handle
: shishi handle as allocated by
shishi_init()
fh
: file handle open for writing.
kdcreq
: KDC-REQ to print.
Description:
Print ASCII armored DER encoding of KDC-REQ to file.
Return value:
Returns SHISHI_OK iff successful.
shishi_kdcreq_save
Function:
int
shishi_kdcreq_save
(Shishi *
handle
, FILE *
fh
Shishi_asn1
kdcreq
handle
: shishi handle as allocated by
shishi_init()
fh
: file handle open for writing.
kdcreq
: KDC-REQ to save.
Description:
Print DER encoding of KDC-REQ to file.
Return value:
Returns SHISHI_OK iff successful.
shishi_kdcreq_to_file
Function:
int
shishi_kdcreq_to_file
(Shishi *
handle
Shishi_asn1
kdcreq
, int
filetype
, const char *
filename
handle
: shishi handle as allocated by
shishi_init()
kdcreq
: KDC-REQ to save.
filetype
: input variable specifying type of file to be written,
see Shishi_filetype.
filename
: input variable with filename to write to.
Description:
Write KDC-REQ to file in specified TYPE. The file will be truncated
if it exists.
Return value:
Returns SHISHI_OK iff successful.
shishi_kdcreq_parse
Function:
int
shishi_kdcreq_parse
(Shishi *
handle
, FILE *
fh
Shishi_asn1
kdcreq
handle
: shishi handle as allocated by
shishi_init()
fh
: file handle open for reading.
kdcreq
: output variable with newly allocated KDC-REQ.
Description:
Read ASCII armored DER encoded KDC-REQ from file and populate given
variable.
Return value:
Returns SHISHI_OK iff successful.
shishi_kdcreq_read
Function:
int
shishi_kdcreq_read
(Shishi *
handle
, FILE *
fh
Shishi_asn1
kdcreq
handle
: shishi handle as allocated by
shishi_init()
fh
: file handle open for reading.
kdcreq
: output variable with newly allocated KDC-REQ.
Description:
Read DER encoded KDC-REQ from file and populate given variable.
Return value:
Returns SHISHI_OK iff successful.
shishi_kdcreq_from_file
Function:
int
shishi_kdcreq_from_file
(Shishi *
handle
Shishi_asn1
kdcreq
, int
filetype
, const char *
filename
handle
: shishi handle as allocated by
shishi_init()
kdcreq
: output variable with newly allocated KDC-REQ.
filetype
: input variable specifying type of file to be read,
see Shishi_filetype.
filename
: input variable with filename to read from.
Description:
Read KDC-REQ from file in specified TYPE.
Return value:
Returns SHISHI_OK iff successful.
shishi_kdcreq_nonce_set
Function:
int
shishi_kdcreq_nonce_set
(Shishi *
handle
Shishi_asn1
kdcreq
uint32_t
nonce
handle
: shishi handle as allocated by
shishi_init()
kdcreq
: KDC-REQ variable to set client name field in.
nonce
: integer nonce to store in KDC-REQ.
Description:
Store nonce number field in KDC-REQ.
Return value:
Returns
SHISHI_OK
iff successful.
shishi_kdcreq_set_cname
Function:
int
shishi_kdcreq_set_cname
(Shishi *
handle
Shishi_asn1
kdcreq
Shishi_name_type
name_type
, const char *
principal
handle
: shishi handle as allocated by
shishi_init()
kdcreq
: KDC-REQ variable to set client name field in.
name_type
: type of principial, see Shishi_name_type, usually
SHISHI_NT_UNKNOWN.
principal
: input array with principal name.
Description:
Set the client name field in the KDC-REQ.
Return value:
Returns SHISHI_OK iff successful.
shishi_kdcreq_client
Function:
int
shishi_kdcreq_client
(Shishi *
handle
Shishi_asn1
kdcreq
, char **
client
size_t
clientlen
handle
: Shishi library handle create by
shishi_init()
kdcreq
: KDC-REQ variable to get client name from.
client
: pointer to newly allocated zero terminated string containing
principal name. May be
NULL
(to only populate
clientlen
).
clientlen
: pointer to length of
client
on output, excluding terminating
zero. May be
NULL
(to only populate
client
).
Description:
Represent client principal name in KDC-REQ as zero-terminated
string. The string is allocate by this function, and it is the
responsibility of the caller to deallocate it. Note that the
output length
clientlen
does not include the terminating zero.
Return value:
Returns SHISHI_OK iff successful.
shishi_asreq_clientrealm
Function:
int
shishi_asreq_clientrealm
(Shishi *
handle
Shishi_asn1
asreq
, char **
client
size_t
clientlen
handle
: Shishi library handle create by
shishi_init()
asreq
: AS-REQ variable to get client name and realm from.
client
: pointer to newly allocated zero terminated string containing
principal name and realm. May be
NULL
(to only populate
clientlen
).
clientlen
: pointer to length of
client
on output, excluding terminating
zero. May be
NULL
(to only populate
client
).
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_kdcreq_realm
Function:
int
shishi_kdcreq_realm
(Shishi *
handle
Shishi_asn1
kdcreq
, char **
realm
size_t
realmlen
handle
: Shishi library handle create by
shishi_init()
kdcreq
: KDC-REQ variable to get client name from.
realm
: pointer to newly allocated zero terminated string containing
realm. May be
NULL
(to only populate
realmlen
).
realmlen
: pointer to length of
realm
on output, excluding terminating
zero. May be
NULL
(to only populate
realmlen
).
Description:
Get realm field in KDC-REQ as zero-terminated string. The string
is allocate by this function, and it is the responsibility of the
caller to deallocate it. Note that the output length
realmlen
does not include the terminating zero.
Return value:
Returns SHISHI_OK iff successful.
shishi_kdcreq_set_realm
Function:
int
shishi_kdcreq_set_realm
(Shishi *
handle
Shishi_asn1
kdcreq
, const char *
realm
handle
: shishi handle as allocated by
shishi_init()
kdcreq
: KDC-REQ variable to set realm field in.
realm
: input array with name of realm.
Description:
Set the realm field in the KDC-REQ.
Return value:
Returns SHISHI_OK iff successful.
shishi_kdcreq_server
Function:
int
shishi_kdcreq_server
(Shishi *
handle
Shishi_asn1
kdcreq
, char **
server
size_t
serverlen
handle
: Shishi library handle create by
shishi_init()
kdcreq
: KDC-REQ variable to get server name from.
server
: pointer to newly allocated zero terminated string containing
principal name. May be
NULL
(to only populate
serverlen
).
serverlen
: pointer to length of
server
on output, excluding terminating
zero. May be
NULL
(to only populate
server
).
Description:
Represent server principal name in KDC-REQ as zero-terminated
string. The string is allocate by this function, and it is the
responsibility of the caller to deallocate it. Note that the
output length
serverlen
does not include the terminating zero.
Return value:
Returns SHISHI_OK iff successful.
shishi_kdcreq_set_sname
Function:
int
shishi_kdcreq_set_sname
(Shishi *
handle
Shishi_asn1
kdcreq
Shishi_name_type
name_type
, const char *
sname
[]
handle
: shishi handle as allocated by
shishi_init()
kdcreq
: KDC-REQ variable to set server name field in.
name_type
: type of principial, see Shishi_name_type, usually
SHISHI_NT_UNKNOWN.
sname
: input array with principal name.
Description:
Set the server name field in the KDC-REQ.
Return value:
Returns SHISHI_OK iff successful.
shishi_kdcreq_till
Function:
int
shishi_kdcreq_till
(Shishi *
handle
Shishi_asn1
kdcreq
, char **
till
size_t
tilllen
handle
: Shishi library handle created by
shishi_init()
kdcreq
: KDC-REQ variable to get endtime from.
till
: pointer to newly allocated null terminated string containing
"till" field with generalized time. May be passed as
NULL
to only populate
tilllen
tilllen
: pointer to length of
till
for output, excluding the
terminating null. Set to
NULL
, only
till
is populated.
Description:
Get "till" field, i.e., "endtime", in KDC-REQ as a null-terminated
string. The string is typically 15 characters long and is
allocated by this function. It is the responsibility of the
caller to deallocate it. Note that the output length
tilllen
does not include the terminating zero.
Return value:
Returns SHISHI_OK iff successful.
shishi_kdcreq_tillc
Function:
time_t
shishi_kdcreq_tillc
(Shishi *
handle
Shishi_asn1
kdcreq
handle
: Shishi library handle created by
shishi_init()
kdcreq
: KDC-REQ variable to get "till" field from.
Description:
Extract C time corresponding to the "till" field.
Return value:
Returns the C time interpretation of the "till"
field in KDC-REQ.
shishi_kdcreq_etype
Function:
int
shishi_kdcreq_etype
(Shishi *
handle
Shishi_asn1
kdcreq
int32_t
etype
, int
netype
handle
: shishi handle as allocated by
shishi_init()
kdcreq
: KDC-REQ variable to get etype field from.
etype
: output encryption type.
netype
: element number to return.
Return the netype:
th encryption type from KDC-REQ. The first etype
is number 1.
Return value:
Returns SHISHI_OK iff etype successful set.
shishi_kdcreq_set_etype
Function:
int
shishi_kdcreq_set_etype
(Shishi *
handle
Shishi_asn1
kdcreq
int32_t
etype
, int
netype
handle
: shishi handle as allocated by
shishi_init()
kdcreq
: KDC-REQ variable to set etype field in.
etype
: input array with encryption types.
netype
: number of elements in input array with encryption types.
Description:
Set the list of supported or wanted encryption types in the
request. The list should be sorted in priority order.
Return value:
Returns SHISHI_OK iff successful.
shishi_kdcreq_options
Function:
int
shishi_kdcreq_options
(Shishi *
handle
Shishi_asn1
kdcreq
uint32_t
flags
handle
: shishi handle as allocated by
shishi_init()
kdcreq
: KDC-REQ variable to get kdc-options field from.
flags
: pointer to output integer with flags.
Description:
Extract KDC-Options from KDC-REQ.
Return value:
Returns SHISHI_OK iff successful.
shishi_kdcreq_forwardable_p
Function:
int
shishi_kdcreq_forwardable_p
(Shishi *
handle
Shishi_asn1
kdcreq
handle
: shishi handle as allocated by
shishi_init()
kdcreq
: KDC-REQ variable to get kdc-options field from.
Description:
Determine if KDC-Option forwardable flag is set.
The FORWARDABLE option indicates that the ticket to be issued is to
have its forwardable flag set. It may only be set on the initial
request, or in a subsequent request if the ticket-granting ticket
on which it is based is also forwardable.
Return value:
Returns non-0 iff forwardable flag is set in KDC-REQ.
shishi_kdcreq_forwarded_p
Function:
int
shishi_kdcreq_forwarded_p
(Shishi *
handle
Shishi_asn1
kdcreq
handle
: shishi handle as allocated by
shishi_init()
kdcreq
: KDC-REQ variable to get kdc-options field from.
Description:
Determine if KDC-Option forwarded flag is set.
The FORWARDED option is only specified in a request to the
ticket-granting server and will only be honored if the
ticket-granting ticket in the request has its FORWARDABLE bit
set. This option indicates that this is a request for
forwarding. The address(es) of the host from which the resulting
ticket is to be valid are included in the addresses field of the
request.
Return value:
Returns non-0 iff forwarded flag is set in KDC-REQ.
shishi_kdcreq_proxiable_p
Function:
int
shishi_kdcreq_proxiable_p
(Shishi *
handle
Shishi_asn1
kdcreq
handle
: shishi handle as allocated by
shishi_init()
kdcreq
: KDC-REQ variable to get kdc-options field from.
Description:
Determine if KDC-Option proxiable flag is set.
The PROXIABLE option indicates that the ticket to be issued is to
have its proxiable flag set. It may only be set on the initial
request, or in a subsequent request if the ticket-granting ticket
on which it is based is also proxiable.
Return value:
Returns non-0 iff proxiable flag is set in KDC-REQ.
shishi_kdcreq_proxy_p
Function:
int
shishi_kdcreq_proxy_p
(Shishi *
handle
Shishi_asn1
kdcreq
handle
: shishi handle as allocated by
shishi_init()
kdcreq
: KDC-REQ variable to get kdc-options field from.
Description:
Determine if KDC-Option proxy flag is set.
The PROXY option indicates that this is a request for a proxy. This
option will only be honored if the ticket-granting ticket in the
request has its PROXIABLE bit set. The address(es) of the host
from which the resulting ticket is to be valid are included in the
addresses field of the request.
Return value:
Returns non-0 iff proxy flag is set in KDC-REQ.
shishi_kdcreq_allow_postdate_p
Function:
int
shishi_kdcreq_allow_postdate_p
(Shishi *
handle
Shishi_asn1
kdcreq
handle
: shishi handle as allocated by
shishi_init()
kdcreq
: KDC-REQ variable to get kdc-options field from.
Description:
Determine if KDC-Option allow-postdate flag is set.
The ALLOW-POSTDATE option indicates that the ticket to be issued is
to have its MAY-POSTDATE flag set. It may only be set on the
initial request, or in a subsequent request if the ticket-granting
ticket on which it is based also has its MAY-POSTDATE flag set.
Return value:
Returns non-0 iff allow-postdate flag is set in KDC-REQ.
shishi_kdcreq_postdated_p
Function:
int
shishi_kdcreq_postdated_p
(Shishi *
handle
Shishi_asn1
kdcreq
handle
: shishi handle as allocated by
shishi_init()
kdcreq
: KDC-REQ variable to get kdc-options field from.
Description:
Determine if KDC-Option postdated flag is set.
The POSTDATED option indicates that this is a request for a
postdated ticket. This option will only be honored if the
ticket-granting ticket on which it is based has its MAY-POSTDATE
flag set. The resulting ticket will also have its INVALID flag set,
and that flag may be reset by a subsequent request to the KDC after
the starttime in the ticket has been reached.
Return value:
Returns non-0 iff postdated flag is set in KDC-REQ.
shishi_kdcreq_renewable_p
Function:
int
shishi_kdcreq_renewable_p
(Shishi *
handle
Shishi_asn1
kdcreq
handle
: shishi handle as allocated by
shishi_init()
kdcreq
: KDC-REQ variable to get kdc-options field from.
Description:
Determine if KDC-Option renewable flag is set.
The RENEWABLE option indicates that the ticket to be issued is to
have its RENEWABLE flag set. It may only be set on the initial
request, or when the ticket-granting ticket on which the request is
based is also renewable. If this option is requested, then the
rtime field in the request contains the desired absolute expiration
time for the ticket.
Return value:
Returns non-0 iff renewable flag is set in KDC-REQ.
shishi_kdcreq_disable_transited_check_p
Function:
int
shishi_kdcreq_disable_transited_check_p
(Shishi *
handle
Shishi_asn1
kdcreq
handle
: shishi handle as allocated by
shishi_init()
kdcreq
: KDC-REQ variable to get kdc-options field from.
Description:
Determine if KDC-Option disable-transited-check flag is set.
By default the KDC will check the transited field of a
ticket-granting-ticket against the policy of the local realm before
it will issue derivative tickets based on the ticket-granting
ticket. If this flag is set in the request, checking of the
transited field is disabled. Tickets issued without the performance
of this check will be noted by the reset (0) value of the
TRANSITED-POLICY-CHECKED flag, indicating to the application server
that the tranisted field must be checked locally. KDCs are
encouraged but not required to honor the DISABLE-TRANSITED-CHECK
option.
This flag is new since RFC 1510
Return value:
Returns non-0 iff disable-transited-check flag is set
in KDC-REQ.
shishi_kdcreq_renewable_ok_p
Function:
int
shishi_kdcreq_renewable_ok_p
(Shishi *
handle
Shishi_asn1
kdcreq
handle
: shishi handle as allocated by
shishi_init()
kdcreq
: KDC-REQ variable to get kdc-options field from.
Description:
Determine if KDC-Option renewable-ok flag is set.
The RENEWABLE-OK option indicates that a renewable ticket will be
acceptable if a ticket with the requested life cannot otherwise be
provided. If a ticket with the requested life cannot be provided,
then a renewable ticket may be issued with a renew-till equal to
the requested endtime. The value of the renew-till field may still
be limited by local limits, or limits selected by the individual
principal or server.
Return value:
Returns non-0 iff renewable-ok flag is set in KDC-REQ.
shishi_kdcreq_enc_tkt_in_skey_p
Function:
int
shishi_kdcreq_enc_tkt_in_skey_p
(Shishi *
handle
Shishi_asn1
kdcreq
handle
: shishi handle as allocated by
shishi_init()
kdcreq
: KDC-REQ variable to get kdc-options field from.
Description:
Determine if KDC-Option enc-tkt-in-skey flag is set.
This option is used only by the ticket-granting service. The
ENC-TKT-IN-SKEY option indicates that the ticket for the end server
is to be encrypted in the session key from the additional
ticket-granting ticket provided.
Return value:
Returns non-0 iff enc-tkt-in-skey flag is set in KDC-REQ.
shishi_kdcreq_renew_p
Function:
int
shishi_kdcreq_renew_p
(Shishi *
handle
Shishi_asn1
kdcreq
handle
: shishi handle as allocated by
shishi_init()
kdcreq
: KDC-REQ variable to get kdc-options field from.
Description:
Determine if KDC-Option renew flag is set.
This option is used only by the ticket-granting service. The RENEW
option indicates that the present request is for a renewal. The
ticket provided is encrypted in the secret key for the server on
which it is valid. This option will only be honored if the ticket
to be renewed has its RENEWABLE flag set and if the time in its
renew-till field has not passed. The ticket to be renewed is passed
in the padata field as part of the authentication header.
Return value:
Returns non-0 iff renew flag is set in KDC-REQ.
shishi_kdcreq_validate_p
Function:
int
shishi_kdcreq_validate_p
(Shishi *
handle
Shishi_asn1
kdcreq
handle
: shishi handle as allocated by
shishi_init()
kdcreq
: KDC-REQ variable to get kdc-options field from.
Description:
Determine if KDC-Option validate flag is set.
This option is used only by the ticket-granting service. The
VALIDATE option indicates that the request is to validate a
postdated ticket. It will only be honored if the ticket presented
is postdated, presently has its INVALID flag set, and would be
otherwise usable at this time. A ticket cannot be validated before
its starttime. The ticket presented for validation is encrypted in
the key of the server for which it is valid and is passed in the
padata field as part of the authentication header.
Return value:
Returns non-0 iff validate flag is set in KDC-REQ.
shishi_kdcreq_options_set
Function:
int
shishi_kdcreq_options_set
(Shishi *
handle
Shishi_asn1
kdcreq
uint32_t
options
handle
: shishi handle as allocated by
shishi_init()
kdcreq
: KDC-REQ variable to set etype field in.
options
: integer with flags to store in KDC-REQ.
Description:
Set options in KDC-REQ. Note that this reset any already existing
flags.
Return value:
Returns SHISHI_OK iff successful.
shishi_kdcreq_options_add
Function:
int
shishi_kdcreq_options_add
(Shishi *
handle
Shishi_asn1
kdcreq
uint32_t
option
handle
: shishi handle as allocated by
shishi_init()
kdcreq
: KDC-REQ variable to set etype field in.
option
: integer with options to add in KDC-REQ.
Description:
Add KDC-Option to KDC-REQ. This preserves all existing options.
Return value:
Returns SHISHI_OK iff successful.
shishi_kdcreq_clear_padata
Function:
int
shishi_kdcreq_clear_padata
(Shishi *
handle
Shishi_asn1
kdcreq
handle
: shishi handle as allocated by
shishi_init()
kdcreq
: KDC-REQ to remove PA-DATA from.
Description:
Remove the padata field from KDC-REQ.
Return value:
Returns SHISHI_OK iff successful.
shishi_kdcreq_get_padata
Function:
int
shishi_kdcreq_get_padata
(Shishi *
handle
Shishi_asn1
kdcreq
Shishi_padata_type
padatatype
, char **
out
size_t
outlen
handle
: shishi handle as allocated by
shishi_init()
kdcreq
: KDC-REQ to get PA-DATA from.
padatatype
: type of PA-DATA, see Shishi_padata_type.
out
: output array with newly allocated PA-DATA value.
outlen
: size of output array with PA-DATA value.
Description:
Get pre authentication data (PA-DATA) from KDC-REQ. Pre
authentication data is used to pass various information to KDC,
such as in case of a SHISHI_PA_TGS_REQ padatatype the AP-REQ that
authenticates the user to get the ticket.
Return value:
Returns SHISHI_OK iff successful.
shishi_kdcreq_get_padata_tgs
Function:
int
shishi_kdcreq_get_padata_tgs
(Shishi *
handle
Shishi_asn1
kdcreq
Shishi_asn1
apreq
handle
: shishi handle as allocated by
shishi_init()
kdcreq
: KDC-REQ to get PA-TGS-REQ from.
apreq
: Output variable with newly allocated AP-REQ.
Description:
Extract TGS pre-authentication data from KDC-REQ. The data is an
AP-REQ that authenticates the request. This function call
shishi_kdcreq_get_padata()
with a SHISHI_PA_TGS_REQ padatatype and
DER decode the result (if any).
Return value:
Returns SHISHI_OK iff successful.
shishi_kdcreq_add_padata
Function:
int
shishi_kdcreq_add_padata
(Shishi *
handle
Shishi_asn1
kdcreq
, int
padatatype
, const char *
data
size_t
datalen
handle
: shishi handle as allocated by
shishi_init()
kdcreq
: KDC-REQ to add PA-DATA to.
padatatype
: type of PA-DATA, see Shishi_padata_type.
data
: input array with PA-DATA value.
datalen
: size of input array with PA-DATA value.
Description:
Add new pre authentication data (PA-DATA) to KDC-REQ. This is used
to pass various information to KDC, such as in case of a
SHISHI_PA_TGS_REQ padatatype the AP-REQ that authenticates the user
to get the ticket. (But also see
shishi_kdcreq_add_padata_tgs()
which takes an AP-REQ directly.)
Return value:
Returns SHISHI_OK iff successful.
shishi_kdcreq_add_padata_tgs
Function:
int
shishi_kdcreq_add_padata_tgs
(Shishi *
handle
Shishi_asn1
kdcreq
Shishi_asn1
apreq
handle
: shishi handle as allocated by
shishi_init()
kdcreq
: KDC-REQ to add PA-DATA to.
apreq
: AP-REQ to add as PA-DATA.
Description:
Add TGS pre-authentication data to KDC-REQ. The data is an AP-REQ
that authenticates the request. This functions simply DER encodes
the AP-REQ and calls
shishi_kdcreq_add_padata()
with a
SHISHI_PA_TGS_REQ padatatype.
Return value:
Returns SHISHI_OK iff successful.
shishi_kdcreq_add_padata_preauth
Function:
int
shishi_kdcreq_add_padata_preauth
(Shishi *
handle
Shishi_asn1
kdcreq
Shishi_key
key
handle
: shishi handle as allocated by
shishi_init()
kdcreq
: KDC-REQ to add pre-authentication data to.
key
: Key used to encrypt pre-auth data.
Description:
Add pre-authentication data to KDC-REQ.
Return value:
Returns SHISHI_OK iff successful.
shishi_asrep
Function:
Shishi_asn1
shishi_asrep
(Shishi *
handle
handle
: shishi handle as allocated by
shishi_init()
Description:
This function creates a new AS-REP, populated with some default
values.
Return value:
Returns the AS-REP or NULL on failure.
shishi_tgsrep
Function:
Shishi_asn1
shishi_tgsrep
(Shishi *
handle
handle
: shishi handle as allocated by
shishi_init()
Description:
This function creates a new TGS-REP, populated with some default
values.
Return value:
Returns the TGS-REP or NULL on failure.
shishi_kdcrep_print
Function:
int
shishi_kdcrep_print
(Shishi *
handle
, FILE *
fh
Shishi_asn1
kdcrep
handle
: shishi handle as allocated by
shishi_init()
fh
: file handle open for writing.
kdcrep
: KDC-REP to print.
Description:
Print ASCII armored DER encoding of KDC-REP to file.
Return value:
Returns SHISHI_OK iff successful.
shishi_kdcrep_save
Function:
int
shishi_kdcrep_save
(Shishi *
handle
, FILE *
fh
Shishi_asn1
kdcrep
handle
: shishi handle as allocated by
shishi_init()
fh
: file handle open for writing.
kdcrep
: KDC-REP to save.
Description:
Print DER encoding of KDC-REP to file.
Return value:
Returns SHISHI_OK iff successful.
shishi_kdcrep_to_file
Function:
int
shishi_kdcrep_to_file
(Shishi *
handle
Shishi_asn1
kdcrep
, int
filetype
, const char *
filename
handle
: shishi handle as allocated by
shishi_init()
kdcrep
: KDC-REP to save.
filetype
: input variable specifying type of file to be written,
see Shishi_filetype.
filename
: input variable with filename to write to.
Description:
Write KDC-REP to file in specified TYPE. The file will be truncated
if it exists.
Return value:
Returns SHISHI_OK iff successful.
shishi_kdcrep_parse
Function:
int
shishi_kdcrep_parse
(Shishi *
handle
, FILE *
fh
Shishi_asn1
kdcrep
handle
: shishi handle as allocated by
shishi_init()
fh
: file handle open for reading.
kdcrep
: output variable with newly allocated KDC-REP.
Description:
Read ASCII armored DER encoded KDC-REP from file and populate given
variable.
Return value:
Returns SHISHI_OK iff successful.
shishi_kdcrep_read
Function:
int
shishi_kdcrep_read
(Shishi *
handle
, FILE *
fh
Shishi_asn1
kdcrep
handle
: shishi handle as allocated by
shishi_init()
fh
: file handle open for reading.
kdcrep
: output variable with newly allocated KDC-REP.
Description:
Read DER encoded KDC-REP from file and populate given variable.
Return value:
Returns SHISHI_OK iff successful.
shishi_kdcrep_from_file
Function:
int
shishi_kdcrep_from_file
(Shishi *
handle
Shishi_asn1
kdcrep
, int
filetype
, const char *
filename
handle
: shishi handle as allocated by
shishi_init()
kdcrep
: output variable with newly allocated KDC-REP.
filetype
: input variable specifying type of file to be read,
see Shishi_filetype.
filename
: input variable with filename to read from.
Description:
Read KDC-REP from file in specified TYPE.
Return value:
Returns SHISHI_OK iff successful.
shishi_kdcrep_crealm_set
Function:
int
shishi_kdcrep_crealm_set
(Shishi *
handle
Shishi_asn1
kdcrep
, const char *
crealm
handle
: shishi handle as allocated by
shishi_init()
kdcrep
: Kdcrep variable to set realm field in.
crealm
: input array with name of realm.
Description:
Set the client realm field in the KDC-REP.
Return value:
Returns SHISHI_OK iff successful.
shishi_kdcrep_cname_set
Function:
int
shishi_kdcrep_cname_set
(Shishi *
handle
Shishi_asn1
kdcrep
Shishi_name_type
name_type
, const char *
cname
[]
handle
: shishi handle as allocated by
shishi_init()
kdcrep
: Kdcrep variable to set server name field in.
name_type
: type of principial, see Shishi_name_type, usually
SHISHI_NT_UNKNOWN.
cname
: input array with principal name.
Description:
Set the client name field in the KDC-REP.
Return value:
Returns SHISHI_OK iff successful.
shishi_kdcrep_client_set
Function:
int
shishi_kdcrep_client_set
(Shishi *
handle
Shishi_asn1
kdcrep
, const char *
client
handle
: shishi handle as allocated by
shishi_init()
kdcrep
: Kdcrep variable to set server name field in.
client
: zero-terminated string with principal name on RFC 1964 form.
Description:
Set the client name field in the KDC-REP.
Return value:
Returns SHISHI_OK iff successful.
shishi_kdcrep_get_enc_part_etype
Function:
int
shishi_kdcrep_get_enc_part_etype
(Shishi *
handle
Shishi_asn1
kdcrep
int32_t
etype
handle
: shishi handle as allocated by
shishi_init()
kdcrep
: KDC-REP variable to get value from.
etype
: output variable that holds the value.
Description:
Extract KDC-REP.enc-part.etype.
Return value:
Returns SHISHI_OK iff successful.
shishi_kdcrep_get_ticket
Function:
int
shishi_kdcrep_get_ticket
(Shishi *
handle
Shishi_asn1
kdcrep
Shishi_asn1
ticket
handle
: shishi handle as allocated by
shishi_init()
kdcrep
: KDC-REP variable to get ticket from.
ticket
: output variable to hold extracted ticket.
Description:
Extract ticket from KDC-REP.
Return value:
Returns SHISHI_OK iff successful.
shishi_kdcrep_set_ticket
Function:
int
shishi_kdcrep_set_ticket
(Shishi *
handle
Shishi_asn1
kdcrep
Shishi_asn1
ticket
handle
: shishi handle as allocated by
shishi_init()
kdcrep
: KDC-REP to add ticket field to.
ticket
: input ticket to copy into KDC-REP ticket field.
Description:
Copy ticket into KDC-REP.
Return value:
Returns SHISHI_OK iff successful.
shishi_kdcrep_set_enc_part
Function:
int
shishi_kdcrep_set_enc_part
(Shishi *
handle
Shishi_asn1
kdcrep
int32_t
etype
uint32_t
kvno
, const char *
buf
size_t
buflen
handle
: shishi handle as allocated by
shishi_init()
kdcrep
: KDC-REP to add enc-part field to.
etype
: encryption type used to encrypt enc-part.
kvno
: key version number.
buf
: input array with encrypted enc-part.
buflen
: size of input array with encrypted enc-part.
Description:
Set the encrypted enc-part field in the KDC-REP. The encrypted
data is usually created by calling
shishi_encrypt()
on the DER
encoded enc-part. To save time, you may want to use
shishi_kdcrep_add_enc_part()
instead, which calculates the
encrypted data and calls this function in one step.
Return value:
Returns SHISHI_OK iff successful.
shishi_kdcrep_add_enc_part
Function:
int
shishi_kdcrep_add_enc_part
(Shishi *
handle
Shishi_asn1
kdcrep
Shishi_key
key
, int
keyusage
Shishi_asn1
enckdcreppart
handle
: shishi handle as allocated by
shishi_init()
kdcrep
: KDC-REP to add enc-part field to.
key
: key used to encrypt enc-part.
keyusage
: key usage to use, normally SHISHI_KEYUSAGE_ENCASREPPART,
SHISHI_KEYUSAGE_ENCTGSREPPART_SESSION_KEY or
SHISHI_KEYUSAGE_ENCTGSREPPART_AUTHENTICATOR_KEY.
enckdcreppart
: EncKDCRepPart to add.
Description:
Encrypts DER encoded EncKDCRepPart using key and stores it in the
KDC-REP.
Return value:
Returns SHISHI_OK iff successful.
shishi_kdcrep_clear_padata
Function:
int
shishi_kdcrep_clear_padata
(Shishi *
handle
Shishi_asn1
kdcrep
handle
: shishi handle as allocated by
shishi_init()
kdcrep
: KDC-REP to remove PA-DATA from.
Description:
Remove the padata field from KDC-REP.
Return value:
Returns SHISHI_OK iff successful.
shishi_enckdcreppart_get_key
Function:
int
shishi_enckdcreppart_get_key
(Shishi *
handle
Shishi_asn1
enckdcreppart
Shishi_key
**
key
handle
: shishi handle as allocated by
shishi_init()
enckdcreppart
: input EncKDCRepPart variable.
key
: newly allocated encryption key handle.
Description:
Extract the key to use with the ticket sent in the KDC-REP
associated with the EncKDCRepPart input variable.
Return value:
Returns
SHISHI_OK
iff successful.
shishi_enckdcreppart_key_set
Function:
int
shishi_enckdcreppart_key_set
(Shishi *
handle
Shishi_asn1
enckdcreppart
Shishi_key
key
handle
: shishi handle as allocated by
shishi_init()
enckdcreppart
: input EncKDCRepPart variable.
key
: key handle with information to store in enckdcreppart.
Description:
Set the EncKDCRepPart.key field to key type and value of supplied
key.
Return value:
Returns
SHISHI_OK
iff successful.
shishi_enckdcreppart_nonce_set
Function:
int
shishi_enckdcreppart_nonce_set
(Shishi *
handle
Shishi_asn1
enckdcreppart
uint32_t
nonce
handle
: shishi handle as allocated by
shishi_init()
enckdcreppart
: input EncKDCRepPart variable.
nonce
: nonce to set in EncKDCRepPart.
Description:
Set the EncKDCRepPart.nonce field.
Return value:
Returns
SHISHI_OK
iff successful.
shishi_enckdcreppart_flags_set
Function:
int
shishi_enckdcreppart_flags_set
(Shishi *
handle
Shishi_asn1
enckdcreppart
, int
flags
handle
: shishi handle as allocated by
shishi_init()
enckdcreppart
: input EncKDCRepPart variable.
flags
: flags to set in EncKDCRepPart.
Description:
Set the EncKDCRepPart.flags field.
Return value:
Returns
SHISHI_OK
iff successful.
shishi_enckdcreppart_authtime_set
Function:
int
shishi_enckdcreppart_authtime_set
(Shishi *
handle
Shishi_asn1
enckdcreppart
, const char *
authtime
handle
: shishi handle as allocated by
shishi_init()
enckdcreppart
: input EncKDCRepPart variable.
authtime
: character buffer containing a generalized time string.
Description:
Set the EncTicketPart.authtime to supplied value.
Return value:
Returns
SHISHI_OK
iff successful.
shishi_enckdcreppart_starttime_set
Function:
int
shishi_enckdcreppart_starttime_set
(Shishi *
handle
Shishi_asn1
enckdcreppart
, const char *
starttime
handle
: shishi handle as allocated by
shishi_init()
enckdcreppart
: input EncKDCRepPart variable.
starttime
: character buffer containing a generalized time string.
Description:
Set the EncTicketPart.starttime to supplied value. Use a NULL
value for
starttime
to remove the field.
Return value:
Returns
SHISHI_OK
iff successful.
shishi_enckdcreppart_endtime_set
Function:
int
shishi_enckdcreppart_endtime_set
(Shishi *
handle
Shishi_asn1
enckdcreppart
, const char *
endtime
handle
: shishi handle as allocated by
shishi_init()
enckdcreppart
: input EncKDCRepPart variable.
endtime
: character buffer containing a generalized time string.
Description:
Set the EncTicketPart.endtime to supplied value.
Return value:
Returns
SHISHI_OK
iff successful.
shishi_enckdcreppart_renew_till_set
Function:
int
shishi_enckdcreppart_renew_till_set
(Shishi *
handle
Shishi_asn1
enckdcreppart
, const char *
renew_till
handle
: shishi handle as allocated by
shishi_init()
enckdcreppart
: input EncKDCRepPart variable.
renew_till
: character buffer containing a generalized time string.
Description:
Set the EncTicketPart.renew-till to supplied value. Use a NULL
value for
renew_till
to remove the field.
Return value:
Returns
SHISHI_OK
iff successful.
shishi_enckdcreppart_srealm_set
Function:
int
shishi_enckdcreppart_srealm_set
(Shishi *
handle
Shishi_asn1
enckdcreppart
, const char *
srealm
handle
: shishi handle as allocated by
shishi_init()
enckdcreppart
: EncKDCRepPart variable to set realm field in.
srealm
: input array with name of realm.
Description:
Set the server realm field in the EncKDCRepPart.
Return value:
Returns SHISHI_OK iff successful.
shishi_enckdcreppart_sname_set
Function:
int
shishi_enckdcreppart_sname_set
(Shishi *
handle
Shishi_asn1
enckdcreppart
Shishi_name_type
name_type
, char *
sname
[]
handle
: shishi handle as allocated by
shishi_init()
enckdcreppart
: EncKDCRepPart variable to set server name field in.
name_type
: type of principial, see Shishi_name_type, usually
SHISHI_NT_UNKNOWN.
sname
: input array with principal name.
Description:
Set the server name field in the EncKDCRepPart.
Return value:
Returns SHISHI_OK iff successful.
shishi_enckdcreppart_populate_encticketpart
Function:
int
shishi_enckdcreppart_populate_encticketpart
(Shishi *
handle
Shishi_asn1
enckdcreppart
Shishi_asn1
encticketpart
handle
: shishi handle as allocated by
shishi_init()
enckdcreppart
: input EncKDCRepPart variable.
encticketpart
: input EncTicketPart variable.
Description:
Set the flags, authtime, starttime, endtime, renew-till and caddr
fields of the EncKDCRepPart to the corresponding values in the
EncTicketPart.
Return value:
Returns
SHISHI_OK
iff successful.
Next:
KRB-ERROR Functions
, Previous:
AS/TGS Functions
, Up:
Programming Manual
Contents
][
Index
5.11 Authenticator Functions
An “Authenticator” is an ASN.1 structure that work as a proof that
an entity owns a ticket. It is usually embedded in the AP-REQ
structure (see
AP-REQ and AP-REP Functions
), and you most likely
want to use an AP-REQ instead of a Authenticator in normal
applications. The following illustrates the Authenticator ASN.1
structure.
Authenticator ::= [APPLICATION 2] SEQUENCE {
authenticator-vno [0] INTEGER (5),
crealm [1] Realm,
cname [2] PrincipalName,
cksum [3] Checksum OPTIONAL,
cusec [4] Microseconds,
ctime [5] KerberosTime,
subkey [6] EncryptionKey OPTIONAL,
seq-number [7] UInt32 OPTIONAL,
authorization-data [8] AuthorizationData OPTIONAL
shishi_authenticator
Function:
Shishi_asn1
shishi_authenticator
(Shishi *
handle
handle
: shishi handle as allocated by
shishi_init()
Description:
This function creates a new Authenticator, populated with some
default values. It uses the current time as returned by the system
for the ctime and cusec fields.
Return value:
Returns the authenticator or NULL on
failure.
shishi_authenticator_subkey
Function:
Shishi_asn1
shishi_authenticator_subkey
(Shishi *
handle
handle
: shishi handle as allocated by
shishi_init()
Description:
This function creates a new Authenticator, populated with some
default values. It uses the current time as returned by the system
for the ctime and cusec fields. It adds a random subkey.
Return value:
Returns the authenticator or NULL on
failure.
shishi_authenticator_print
Function:
int
shishi_authenticator_print
(Shishi *
handle
, FILE *
fh
Shishi_asn1
authenticator
handle
: shishi handle as allocated by
shishi_init()
fh
: file handle open for writing.
authenticator
: authenticator as allocated by
shishi_authenticator()
Description:
Print ASCII armored DER encoding of authenticator to file.
Return value:
Returns SHISHI_OK iff successful.
shishi_authenticator_save
Function:
int
shishi_authenticator_save
(Shishi *
handle
, FILE *
fh
Shishi_asn1
authenticator
handle
: shishi handle as allocated by
shishi_init()
fh
: file handle open for writing.
authenticator
: authenticator as allocated by
shishi_authenticator()
Description:
Save DER encoding of authenticator to file.
Return value:
Returns SHISHI_OK iff successful.
shishi_authenticator_to_file
Function:
int
shishi_authenticator_to_file
(Shishi *
handle
Shishi_asn1
authenticator
, int
filetype
, const char *
filename
handle
: shishi handle as allocated by
shishi_init()
authenticator
: Authenticator to save.
filetype
: input variable specifying type of file to be written,
see Shishi_filetype.
filename
: input variable with filename to write to.
Description:
Write Authenticator to file in specified TYPE. The file will be
truncated if it exists.
Return value:
Returns SHISHI_OK iff successful.
shishi_authenticator_parse
Function:
int
shishi_authenticator_parse
(Shishi *
handle
, FILE *
fh
Shishi_asn1
authenticator
handle
: shishi handle as allocated by
shishi_init()
fh
: file handle open for reading.
authenticator
: output variable with newly allocated authenticator.
Description:
Read ASCII armored DER encoded authenticator from file and populate
given authenticator variable.
Return value:
Returns SHISHI_OK iff successful.
shishi_authenticator_read
Function:
int
shishi_authenticator_read
(Shishi *
handle
, FILE *
fh
Shishi_asn1
authenticator
handle
: shishi handle as allocated by
shishi_init()
fh
: file handle open for reading.
authenticator
: output variable with newly allocated authenticator.
Description:
Read DER encoded authenticator from file and populate given
authenticator variable.
Return value:
Returns SHISHI_OK iff successful.
shishi_authenticator_from_file
Function:
int
shishi_authenticator_from_file
(Shishi *
handle
Shishi_asn1
authenticator
, int
filetype
, const char *
filename
handle
: shishi handle as allocated by
shishi_init()
authenticator
: output variable with newly allocated Authenticator.
filetype
: input variable specifying type of file to be read,
see Shishi_filetype.
filename
: input variable with filename to read from.
Description:
Read Authenticator from file in specified TYPE.
Return value:
Returns SHISHI_OK iff successful.
shishi_authenticator_set_crealm
Function:
int
shishi_authenticator_set_crealm
(Shishi *
handle
Shishi_asn1
authenticator
, const char *
crealm
handle
: shishi handle as allocated by
shishi_init()
authenticator
: authenticator as allocated by
shishi_authenticator()
crealm
: input array with realm.
Description:
Set realm field in authenticator to specified value.
Return value:
Returns SHISHI_OK iff successful.
shishi_authenticator_set_cname
Function:
int
shishi_authenticator_set_cname
(Shishi *
handle
Shishi_asn1
authenticator
Shishi_name_type
name_type
, const char *
cname
[]
handle
: shishi handle as allocated by
shishi_init()
authenticator
: authenticator as allocated by
shishi_authenticator()
name_type
: type of principial, see Shishi_name_type, usually
SHISHI_NT_UNKNOWN.
cname
: input array with principal name.
Description:
Set principal field in authenticator to specified value.
Return value:
Returns SHISHI_OK iff successful.
shishi_authenticator_client_set
Function:
int
shishi_authenticator_client_set
(Shishi *
handle
Shishi_asn1
authenticator
, const char *
client
handle
: shishi handle as allocated by
shishi_init()
authenticator
: Authenticator to set client name field in.
client
: zero-terminated string with principal name on RFC 1964 form.
Description:
Set the client name field in the Authenticator.
Return value:
Returns SHISHI_OK iff successful.
shishi_authenticator_ctime
Function:
int
shishi_authenticator_ctime
(Shishi *
handle
Shishi_asn1
authenticator
, char **
handle
: shishi handle as allocated by
shishi_init()
authenticator
: Authenticator as allocated by
shishi_authenticator()
: newly allocated zero-terminated character array with client time.
Description:
Extract client time from Authenticator.
Return value:
Returns SHISHI_OK iff successful.
shishi_authenticator_ctime_set
Function:
int
shishi_authenticator_ctime_set
(Shishi *
handle
Shishi_asn1
authenticator
, const char *
handle
: shishi handle as allocated by
shishi_init()
authenticator
: Authenticator as allocated by
shishi_authenticator()
: string with generalized time value to store in Authenticator.
Description:
Store client time in Authenticator.
Return value:
Returns SHISHI_OK iff successful.
shishi_authenticator_cusec_get
Function:
int
shishi_authenticator_cusec_get
(Shishi *
handle
Shishi_asn1
authenticator
uint32_t
cusec
handle
: shishi handle as allocated by
shishi_init()
authenticator
: Authenticator as allocated by
shishi_authenticator()
cusec
: output integer with client microseconds field.
Description:
Extract client microseconds field from Authenticator.
Return value:
Returns SHISHI_OK iff successful.
shishi_authenticator_cusec_set
Function:
int
shishi_authenticator_cusec_set
(Shishi *
handle
Shishi_asn1
authenticator
uint32_t
cusec
handle
: shishi handle as allocated by
shishi_init()
authenticator
: authenticator as allocated by
shishi_authenticator()
cusec
: client microseconds to set in authenticator, 0-999999.
Description:
Set the cusec field in the Authenticator.
Return value:
Returns SHISHI_OK iff successful.
shishi_authenticator_seqnumber_get
Function:
int
shishi_authenticator_seqnumber_get
(Shishi *
handle
Shishi_asn1
authenticator
uint32_t
seqnumber
handle
: shishi handle as allocated by
shishi_init()
authenticator
: authenticator as allocated by
shishi_authenticator()
seqnumber
: output integer with sequence number field.
Description:
Extract sequence number field from Authenticator.
Return value:
Returns
SHISHI_OK
iff successful.
shishi_authenticator_seqnumber_remove
Function:
int
shishi_authenticator_seqnumber_remove
(Shishi *
handle
Shishi_asn1
authenticator
handle
: shishi handle as allocated by
shishi_init()
authenticator
: authenticator as allocated by
shishi_authenticator()
Description:
Remove sequence number field in Authenticator.
Return value:
Returns
SHISHI_OK
iff successful.
shishi_authenticator_seqnumber_set
Function:
int
shishi_authenticator_seqnumber_set
(Shishi *
handle
Shishi_asn1
authenticator
uint32_t
seqnumber
handle
: shishi handle as allocated by
shishi_init()
authenticator
: authenticator as allocated by
shishi_authenticator()
seqnumber
: integer with sequence number field to store in Authenticator.
Description:
Store sequence number field in Authenticator.
Return value:
Returns
SHISHI_OK
iff successful.
shishi_authenticator_client
Function:
int
shishi_authenticator_client
(Shishi *
handle
Shishi_asn1
authenticator
, char **
client
size_t
clientlen
handle
: Shishi library handle create by
shishi_init()
authenticator
: Authenticator variable to get client name from.
client
: pointer to newly allocated zero terminated string containing
principal name. May be
NULL
(to only populate
clientlen
).
clientlen
: pointer to length of
client
on output, excluding terminating
zero. May be
NULL
(to only populate
client
).
Description:
Represent client principal name in Authenticator as zero-terminated
string. The string is allocate by this function, and it is the
responsibility of the caller to deallocate it. Note that the
output length
clientlen
does not include the terminating zero.
Return value:
Returns SHISHI_OK iff successful.
shishi_authenticator_clientrealm
Function:
int
shishi_authenticator_clientrealm
(Shishi *
handle
Shishi_asn1
authenticator
, char **
client
size_t
clientlen
handle
: Shishi library handle create by
shishi_init()
authenticator
: Authenticator variable to get client name and realm from.
client
: pointer to newly allocated zero terminated string containing
principal name and realm. May be
NULL
(to only populate
clientlen
).
clientlen
: pointer to length of
client
on output, excluding terminating
zero. May be
NULL
(to only populate
client
).
Description:
Convert cname and realm fields from Authenticator to printable
principal name format. The string is allocate by this function,
and it is the responsibility of the caller to deallocate it. Note
that the output length
clientlen
does not include the terminating
zero.
Return value:
Returns SHISHI_OK iff successful.
shishi_authenticator_cksum
Function:
int
shishi_authenticator_cksum
(Shishi *
handle
Shishi_asn1
authenticator
int32_t
cksumtype
, char **
cksum
size_t
cksumlen
handle
: shishi handle as allocated by
shishi_init()
authenticator
: authenticator as allocated by
shishi_authenticator()
cksumtype
: output checksum type.
cksum
: newly allocated output checksum data from authenticator.
cksumlen
: on output, actual size of allocated output checksum data buffer.
Description:
Read checksum value from authenticator.
cksum
is allocated by
this function, and it is the responsibility of caller to deallocate
it.
Return value:
Returns SHISHI_OK iff successful.
shishi_authenticator_set_cksum
Function:
int
shishi_authenticator_set_cksum
(Shishi *
handle
Shishi_asn1
authenticator
int32_t
cksumtype
, char *
cksum
size_t
cksumlen
handle
: shishi handle as allocated by
shishi_init()
authenticator
: authenticator as allocated by
shishi_authenticator()
cksumtype
: input checksum type to store in authenticator.
cksum
: input checksum data to store in authenticator.
cksumlen
: size of input checksum data to store in authenticator.
Description:
Store checksum value in authenticator. A checksum is usually created
by calling
shishi_checksum()
on some application specific data using
the key from the ticket that is being used. To save time, you may
want to use
shishi_authenticator_add_cksum()
instead, which calculates
the checksum and calls this function in one step.
Return value:
Returns SHISHI_OK iff successful.
shishi_authenticator_add_cksum
Function:
int
shishi_authenticator_add_cksum
(Shishi *
handle
Shishi_asn1
authenticator
Shishi_key
key
, int
keyusage
, char *
data
size_t
datalen
handle
: shishi handle as allocated by
shishi_init()
authenticator
: authenticator as allocated by
shishi_authenticator()
key
: key to to use for encryption.
keyusage
: cryptographic key usage value to use in encryption.
data
: input array with data to calculate checksum on.
datalen
: size of input array with data to calculate checksum on.
Description:
Calculate checksum for data and store it in the authenticator.
Return value:
Returns SHISHI_OK iff successful.
shishi_authenticator_add_cksum_type
Function:
int
shishi_authenticator_add_cksum_type
(Shishi *
handle
Shishi_asn1
authenticator
Shishi_key
key
, int
keyusage
, int
cksumtype
, char *
data
size_t
datalen
handle
: shishi handle as allocated by
shishi_init()
authenticator
: authenticator as allocated by
shishi_authenticator()
key
: key to to use for encryption.
keyusage
: cryptographic key usage value to use in encryption.
cksumtype
: checksum to type to calculate checksum.
data
: input array with data to calculate checksum on.
datalen
: size of input array with data to calculate checksum on.
Description:
Calculate checksum for data and store it in the authenticator.
Return value:
Returns SHISHI_OK iff successful.
shishi_authenticator_clear_authorizationdata
Function:
int
shishi_authenticator_clear_authorizationdata
(Shishi *
handle
Shishi_asn1
authenticator
handle
: shishi handle as allocated by
shishi_init()
authenticator
: Authenticator as allocated by
shishi_authenticator()
Description:
Remove the authorization-data field from Authenticator.
Return value:
Returns SHISHI_OK iff successful.
shishi_authenticator_add_authorizationdata
Function:
int
shishi_authenticator_add_authorizationdata
(Shishi *
handle
Shishi_asn1
authenticator
int32_t
adtype
, const char *
addata
size_t
addatalen
handle
: shishi handle as allocated by
shishi_init()
authenticator
: authenticator as allocated by
shishi_authenticator()
adtype
: input authorization data type to add.
addata
: input authorization data to add.
addatalen
: size of input authorization data to add.
Description:
Add authorization data to authenticator.
Return value:
Returns SHISHI_OK iff successful.
shishi_authenticator_authorizationdata
Function:
int
shishi_authenticator_authorizationdata
(Shishi *
handle
Shishi_asn1
authenticator
int32_t
adtype
, char **
addata
size_t
addatalen
size_t
nth
handle
: shishi handle as allocated by
shishi_init()
authenticator
: authenticator as allocated by
shishi_authenticator()
adtype
: output authorization data type.
addata
: newly allocated output authorization data.
addatalen
: on output, actual size of newly allocated authorization data.
nth
: element number of authorization-data to extract.
Extract n:
th authorization data from authenticator. The first
field is 1.
Return value:
Returns SHISHI_OK iff successful.
shishi_authenticator_remove_subkey
Function:
int
shishi_authenticator_remove_subkey
(Shishi *
handle
Shishi_asn1
authenticator
handle
: shishi handle as allocated by
shishi_init()
authenticator
: authenticator as allocated by
shishi_authenticator()
Description:
Remove subkey from the authenticator.
Return value:
Returns SHISHI_OK iff successful.
shishi_authenticator_get_subkey
Function:
int
shishi_authenticator_get_subkey
(Shishi *
handle
Shishi_asn1
authenticator
Shishi_key
**
subkey
handle
: shishi handle as allocated by
shishi_init()
authenticator
: authenticator as allocated by
shishi_authenticator()
subkey
: output newly allocated subkey from authenticator.
Description:
Read subkey value from authenticator.
Return value:
Returns SHISHI_OK if successful or SHISHI_ASN1_NO_ELEMENT
if subkey is not present.
shishi_authenticator_set_subkey
Function:
int
shishi_authenticator_set_subkey
(Shishi *
handle
Shishi_asn1
authenticator
int32_t
subkeytype
, const char *
subkey
size_t
subkeylen
handle
: shishi handle as allocated by
shishi_init()
authenticator
: authenticator as allocated by
shishi_authenticator()
subkeytype
: input subkey type to store in authenticator.
subkey
: input subkey data to store in authenticator.
subkeylen
: size of input subkey data to store in authenticator.
Description:
Store subkey value in authenticator. A subkey is usually created
by calling
shishi_key_random()
using the default encryption type of
the key from the ticket that is being used. To save time, you may
want to use
shishi_authenticator_add_subkey()
instead, which calculates
the subkey and calls this function in one step.
Return value:
Returns SHISHI_OK iff successful.
shishi_authenticator_add_random_subkey
Function:
int
shishi_authenticator_add_random_subkey
(Shishi *
handle
Shishi_asn1
authenticator
handle
: shishi handle as allocated by
shishi_init()
authenticator
: authenticator as allocated by
shishi_authenticator()
Description:
Generate random subkey, of the default encryption type from
configuration, and store it in the authenticator.
Return value:
Returns SHISHI_OK iff successful.
shishi_authenticator_add_random_subkey_etype
Function:
int
shishi_authenticator_add_random_subkey_etype
(Shishi *
handle
Shishi_asn1
authenticator
, int
etype
handle
: shishi handle as allocated by
shishi_init()
authenticator
: authenticator as allocated by
shishi_authenticator()
etype
: encryption type of random key to generate.
Description:
Generate random subkey of indicated encryption type, and store it
in the authenticator.
Return value:
Returns SHISHI_OK iff successful.
shishi_authenticator_add_subkey
Function:
int
shishi_authenticator_add_subkey
(Shishi *
handle
Shishi_asn1
authenticator
Shishi_key
subkey
handle
: shishi handle as allocated by
shishi_init()
authenticator
: authenticator as allocated by
shishi_authenticator()
subkey
: subkey to add to authenticator.
Description:
Store subkey in the authenticator.
Return value:
Returns SHISHI_OK iff successful.
Next:
Cryptographic Functions
, Previous:
Authenticator Functions
, Up:
Programming Manual
Contents
][
Index
5.12 KRB-ERROR Functions
The “KRB-ERROR” is an ASN.1 structure that can be returned, instead
of, e.g., KDC-REP or AP-REP, to indicate various error conditions.
Unfortunately, the semantics of several of the fields are ill
specified, so the typically procedure is to extract “e-text” and/or
“e-data” and show it to the user. The following illustrates the
KRB-ERROR ASN.1 structure.
KRB-ERROR ::= [APPLICATION 30] SEQUENCE {
pvno [0] INTEGER (5),
msg-type [1] INTEGER (30),
ctime [2] KerberosTime OPTIONAL,
cusec [3] Microseconds OPTIONAL,
stime [4] KerberosTime,
susec [5] Microseconds,
error-code [6] Int32,
crealm [7] Realm OPTIONAL,
cname [8] PrincipalName OPTIONAL,
realm [9] Realm -- service realm --,
sname [10] PrincipalName -- service name --,
e-text [11] KerberosString OPTIONAL,
e-data [12] OCTET STRING OPTIONAL
shishi_krberror
Function:
Shishi_asn1
shishi_krberror
(Shishi *
handle
handle
: shishi handle as allocated by
shishi_init()
Description:
This function creates a new KRB-ERROR, populated with some default
values.
Return value:
Returns the KRB-ERROR or NULL on failure.
shishi_krberror_print
Function:
int
shishi_krberror_print
(Shishi *
handle
, FILE *
fh
Shishi_asn1
krberror
handle
: shishi handle as allocated by
shishi_init()
fh
: file handle open for writing.
krberror
: KRB-ERROR to print.
Description:
Print ASCII armored DER encoding of KRB-ERROR to file.
Return value:
Returns SHISHI_OK iff successful.
shishi_krberror_save
Function:
int
shishi_krberror_save
(Shishi *
handle
, FILE *
fh
Shishi_asn1
krberror
handle
: shishi handle as allocated by
shishi_init()
fh
: file handle open for writing.
krberror
: KRB-ERROR to save.
Description:
Save DER encoding of KRB-ERROR to file.
Return value:
Returns SHISHI_OK iff successful.
shishi_krberror_to_file
Function:
int
shishi_krberror_to_file
(Shishi *
handle
Shishi_asn1
krberror
, int
filetype
, const char *
filename
handle
: shishi handle as allocated by
shishi_init()
krberror
: KRB-ERROR to save.
filetype
: input variable specifying type of file to be written,
see Shishi_filetype.
filename
: input variable with filename to write to.
Description:
Write KRB-ERROR to file in specified TYPE. The file will be
truncated if it exists.
Return value:
Returns SHISHI_OK iff successful.
shishi_krberror_parse
Function:
int
shishi_krberror_parse
(Shishi *
handle
, FILE *
fh
Shishi_asn1
krberror
handle
: shishi handle as allocated by
shishi_init()
fh
: file handle open for reading.
krberror
: output variable with newly allocated KRB-ERROR.
Description:
Read ASCII armored DER encoded KRB-ERROR from file and populate given
variable.
Return value:
Returns SHISHI_OK iff successful.
shishi_krberror_read
Function:
int
shishi_krberror_read
(Shishi *
handle
, FILE *
fh
Shishi_asn1
krberror
handle
: shishi handle as allocated by
shishi_init()
fh
: file handle open for reading.
krberror
: output variable with newly allocated KRB-ERROR.
Description:
Read DER encoded KRB-ERROR from file and populate given variable.
Return value:
Returns SHISHI_OK iff successful.
shishi_krberror_from_file
Function:
int
shishi_krberror_from_file
(Shishi *
handle
Shishi_asn1
krberror
, int
filetype
, const char *
filename
handle
: shishi handle as allocated by
shishi_init()
krberror
: output variable with newly allocated KRB-ERROR.
filetype
: input variable specifying type of file to be read,
see Shishi_filetype.
filename
: input variable with filename to read from.
Description:
Read KRB-ERROR from file in specified TYPE.
Return value:
Returns SHISHI_OK iff successful.
shishi_krberror_build
Function:
int
shishi_krberror_build
(Shishi *
handle
Shishi_asn1
krberror
handle
: shishi handle as allocated by
shishi_init()
krberror
: krberror as allocated by
shishi_krberror()
Description:
Finish KRB-ERROR, called before e.g. shishi_krberror_der. This
function removes empty but OPTIONAL fields (such as cname), and
Return value:
Returns SHISHI_OK iff successful.
shishi_krberror_der
Function:
int
shishi_krberror_der
(Shishi *
handle
Shishi_asn1
krberror
, char **
out
size_t
outlen
handle
: shishi handle as allocated by
shishi_init()
krberror
: krberror as allocated by
shishi_krberror()
out
: output array with newly allocated DER encoding of KRB-ERROR.
outlen
: length of output array with DER encoding of KRB-ERROR.
Description:
DER encode KRB-ERROR. The caller must deallocate the OUT buffer.
Return value:
Returns SHISHI_OK iff successful.
shishi_krberror_crealm
Function:
int
shishi_krberror_crealm
(Shishi *
handle
Shishi_asn1
krberror
, char **
realm
size_t
realmlen
handle
: shishi handle as allocated by
shishi_init()
krberror
: krberror as allocated by
shishi_krberror()
realm
: output array with newly allocated name of realm in KRB-ERROR.
realmlen
: size of output array.
Description:
Extract client realm from KRB-ERROR.
Return value:
Returns SHISHI_OK iff successful.
shishi_krberror_remove_crealm
Function:
int
shishi_krberror_remove_crealm
(Shishi *
handle
Shishi_asn1
krberror
handle
: shishi handle as allocated by
shishi_init()
krberror
: krberror as allocated by
shishi_krberror()
Description:
Remove client realm field in KRB-ERROR.
Return value:
Returns SHISHI_OK iff successful.
shishi_krberror_set_crealm
Function:
int
shishi_krberror_set_crealm
(Shishi *
handle
Shishi_asn1
krberror
, const char *
crealm
handle
: shishi handle as allocated by
shishi_init()
krberror
: krberror as allocated by
shishi_krberror()
crealm
: input array with realm.
Description:
Set realm field in krberror to specified value.
Return value:
Returns SHISHI_OK iff successful.
shishi_krberror_client
Function:
int
shishi_krberror_client
(Shishi *
handle
Shishi_asn1
krberror
, char **
client
size_t
clientlen
handle
: shishi handle as allocated by
shishi_init()
krberror
: krberror as allocated by
shishi_krberror()
client
: pointer to newly allocated zero terminated string containing
principal name. May be
NULL
(to only populate
clientlen
).
clientlen
: pointer to length of
client
on output, excluding terminating
zero. May be
NULL
(to only populate
client
).
Description:
Return client principal name in KRB-ERROR.
Return value:
Returns SHISHI_OK iff successful.
shishi_krberror_set_cname
Function:
int
shishi_krberror_set_cname
(Shishi *
handle
Shishi_asn1
krberror
Shishi_name_type
name_type
, const char *
cname
[]
handle
: shishi handle as allocated by
shishi_init()
krberror
: krberror as allocated by
shishi_krberror()
name_type
: type of principial, see Shishi_name_type, usually
SHISHI_NT_UNKNOWN.
cname
: input array with principal name.
Description:
Set principal field in krberror to specified value.
Return value:
Returns SHISHI_OK iff successful.
shishi_krberror_remove_cname
Function:
int
shishi_krberror_remove_cname
(Shishi *
handle
Shishi_asn1
krberror
handle
: shishi handle as allocated by
shishi_init()
krberror
: krberror as allocated by
shishi_krberror()
Description:
Remove client realm field in KRB-ERROR.
Return value:
Returns SHISHI_OK iff successful.
shishi_krberror_client_set
Function:
int
shishi_krberror_client_set
(Shishi *
handle
Shishi_asn1
krberror
, const char *
client
handle
: shishi handle as allocated by
shishi_init()
krberror
: Krberror to set client name field in.
client
: zero-terminated string with principal name on RFC 1964 form.
Description:
Set the client name field in the Krberror.
Return value:
Returns SHISHI_OK iff successful.
shishi_krberror_realm
Function:
int
shishi_krberror_realm
(Shishi *
handle
Shishi_asn1
krberror
, char **
realm
size_t
realmlen
handle
: shishi handle as allocated by
shishi_init()
krberror
: krberror as allocated by
shishi_krberror()
realm
: output array with newly allocated name of realm in KRB-ERROR.
realmlen
: size of output array.
Description:
Extract (server) realm from KRB-ERROR.
Return value:
Returns SHISHI_OK iff successful.
shishi_krberror_set_realm
Function:
int
shishi_krberror_set_realm
(Shishi *
handle
Shishi_asn1
krberror
, const char *
realm
handle
: shishi handle as allocated by
shishi_init()
krberror
: krberror as allocated by
shishi_krberror()
realm
: input array with (server) realm.
Description:
Set (server) realm field in krberror to specified value.
Return value:
Returns SHISHI_OK iff successful.
shishi_krberror_server
Function:
int
shishi_krberror_server
(Shishi *
handle
Shishi_asn1
krberror
, char **
server
size_t
serverlen
handle
: shishi handle as allocated by
shishi_init()
krberror
: krberror as allocated by
shishi_krberror()
server
: pointer to newly allocated zero terminated string containing
server name. May be
NULL
(to only populate
serverlen
).
serverlen
: pointer to length of
server
on output, excluding terminating
zero. May be
NULL
(to only populate
server
).
Description:
Return server principal name in KRB-ERROR.
Return value:
Returns SHISHI_OK iff successful.
shishi_krberror_remove_sname
Function:
int
shishi_krberror_remove_sname
(Shishi *
handle
Shishi_asn1
krberror
handle
: shishi handle as allocated by
shishi_init()
krberror
: Krberror to set server name field in.
Description:
Remove server name field in KRB-ERROR. (Since it is not marked
OPTIONAL in the ASN.1 profile, what is done is to set the name-type
to UNKNOWN and make sure the name-string sequence is empty.)
Return value:
Returns SHISHI_OK iff successful.
shishi_krberror_set_sname
Function:
int
shishi_krberror_set_sname
(Shishi *
handle
Shishi_asn1
krberror
Shishi_name_type
name_type
, const char *
sname
[]
handle
: shishi handle as allocated by
shishi_init()
krberror
: krberror as allocated by
shishi_krberror()
name_type
: type of principial, see Shishi_name_type, usually
SHISHI_NT_UNKNOWN.
sname
: input array with principal name.
Description:
Set principal field in krberror to specified value.
Return value:
Returns SHISHI_OK iff successful.
shishi_krberror_server_set
Function:
int
shishi_krberror_server_set
(Shishi *
handle
Shishi_asn1
krberror
, const char *
server
handle
: shishi handle as allocated by
shishi_init()
krberror
: Krberror to set server name field in.
server
: zero-terminated string with principal name on RFC 1964 form.
Description:
Set the server name field in the Krberror.
Return value:
Returns SHISHI_OK iff successful.
shishi_krberror_ctime
Function:
int
shishi_krberror_ctime
(Shishi *
handle
Shishi_asn1
krberror
, char **
handle
: shishi handle as allocated by
shishi_init()
krberror
: Krberror to set client name field in.
: newly allocated zero-terminated output array with client time.
Description:
Extract client time from KRB-ERROR.
Return value:
Returns SHISHI_OK iff successful.
shishi_krberror_ctime_set
Function:
int
shishi_krberror_ctime_set
(Shishi *
handle
Shishi_asn1
krberror
, const char *
handle
: shishi handle as allocated by
shishi_init()
krberror
: Krberror as allocated by
shishi_krberror()
: string with generalized time value to store in Krberror.
Description:
Store client time in Krberror.
Return value:
Returns SHISHI_OK iff successful.
shishi_krberror_remove_ctime
Function:
int
shishi_krberror_remove_ctime
(Shishi *
handle
Shishi_asn1
krberror
handle
: shishi handle as allocated by
shishi_init()
krberror
: Krberror as allocated by
shishi_krberror()
Description:
Remove client time field in Krberror.
Return value:
Returns SHISHI_OK iff successful.
shishi_krberror_cusec
Function:
int
shishi_krberror_cusec
(Shishi *
handle
Shishi_asn1
krberror
uint32_t
cusec
handle
: shishi handle as allocated by
shishi_init()
krberror
: Krberror as allocated by
shishi_krberror()
cusec
: output integer with client microseconds field.
Description:
Extract client microseconds field from Krberror.
Return value:
Returns SHISHI_OK iff successful.
shishi_krberror_cusec_set
Function:
int
shishi_krberror_cusec_set
(Shishi *
handle
Shishi_asn1
krberror
uint32_t
cusec
handle
: shishi handle as allocated by
shishi_init()
krberror
: krberror as allocated by
shishi_krberror()
cusec
: client microseconds to set in krberror, 0-999999.
Description:
Set the cusec field in the Krberror.
Return value:
Returns SHISHI_OK iff successful.
shishi_krberror_remove_cusec
Function:
int
shishi_krberror_remove_cusec
(Shishi *
handle
Shishi_asn1
krberror
handle
: shishi handle as allocated by
shishi_init()
krberror
: Krberror as allocated by
shishi_krberror()
Description:
Remove client usec field in Krberror.
Return value:
Returns SHISHI_OK iff successful.
shishi_krberror_stime
Function:
int
shishi_krberror_stime
(Shishi *
handle
Shishi_asn1
krberror
, char **
handle
: shishi handle as allocated by
shishi_init()
krberror
: Krberror to set client name field in.
: newly allocated zero-terminated output array with server time.
Description:
Extract server time from KRB-ERROR.
Return value:
Returns SHISHI_OK iff successful.
shishi_krberror_stime_set
Function:
int
shishi_krberror_stime_set
(Shishi *
handle
Shishi_asn1
krberror
, const char *
handle
: shishi handle as allocated by
shishi_init()
krberror
: Krberror as allocated by
shishi_krberror()
: string with generalized time value to store in Krberror.
Description:
Store server time in Krberror.
Return value:
Returns SHISHI_OK iff successful.
shishi_krberror_susec
Function:
int
shishi_krberror_susec
(Shishi *
handle
Shishi_asn1
krberror
uint32_t
susec
handle
: shishi handle as allocated by
shishi_init()
krberror
: Krberror as allocated by
shishi_krberror()
susec
: output integer with server microseconds field.
Description:
Extract server microseconds field from Krberror.
Return value:
Returns SHISHI_OK iff successful.
shishi_krberror_susec_set
Function:
int
shishi_krberror_susec_set
(Shishi *
handle
Shishi_asn1
krberror
uint32_t
susec
handle
: shishi handle as allocated by
shishi_init()
krberror
: krberror as allocated by
shishi_krberror()
susec
: server microseconds to set in krberror, 0-999999.
Description:
Set the susec field in the Krberror.
Return value:
Returns SHISHI_OK iff successful.
shishi_krberror_errorcode
Function:
int
shishi_krberror_errorcode
(Shishi *
handle
Shishi_asn1
krberror
int32_t
errorcode
handle
: shishi handle as allocated by
shishi_init()
krberror
: KRB-ERROR structure with error code.
errorcode
: output integer KRB-ERROR error code.
Description:
Extract error code from KRB-ERROR.
Return value:
Returns SHISHI_OK iff successful.
shishi_krberror_errorcode_fast
Function:
int
shishi_krberror_errorcode_fast
(Shishi *
handle
Shishi_asn1
krberror
handle
: shishi handle as allocated by
shishi_init()
krberror
: KRB-ERROR structure with error code.
Description:
Get error code from KRB-ERROR, without error checking.
Return value:
Return error code (see
shishi_krberror_errorcode()
directly, or -1 on error.
shishi_krberror_errorcode_set
Function:
int
shishi_krberror_errorcode_set
(Shishi *
handle
Shishi_asn1
krberror
, int
errorcode
handle
: shishi handle as allocated by
shishi_init()
krberror
: KRB-ERROR structure with error code to set.
errorcode
: new error code to set in krberror.
Description:
Set the error-code field to a new error code.
Return value:
Returns SHISHI_OK iff successful.
shishi_krberror_etext
Function:
int
shishi_krberror_etext
(Shishi *
handle
Shishi_asn1
krberror
, char **
etext
size_t
etextlen
handle
: shishi handle as allocated by
shishi_init()
krberror
: KRB-ERROR structure with error code.
etext
: output array with newly allocated error text.
etextlen
: output length of error text.
Description:
Extract additional error text from server (possibly empty).
Return value:
Returns SHISHI_OK iff successful.
shishi_krberror_set_etext
Function:
int
shishi_krberror_set_etext
(Shishi *
handle
Shishi_asn1
krberror
, const char *
etext
handle
: shishi handle as allocated by
shishi_init()
krberror
: krberror as allocated by
shishi_krberror()
etext
: input array with error text to set.
Description:
Set error text (e-text) field in KRB-ERROR to specified value.
Return value:
Returns SHISHI_OK iff successful.
shishi_krberror_remove_etext
Function:
int
shishi_krberror_remove_etext
(Shishi *
handle
Shishi_asn1
krberror
handle
: shishi handle as allocated by
shishi_init()
krberror
: krberror as allocated by
shishi_krberror()
Description:
Remove error text (e-text) field in KRB-ERROR.
Return value:
Returns SHISHI_OK iff successful.
shishi_krberror_edata
Function:
int
shishi_krberror_edata
(Shishi *
handle
Shishi_asn1
krberror
, char **
edata
size_t
edatalen
handle
: shishi handle as allocated by
shishi_init()
krberror
: KRB-ERROR structure with error code.
edata
: output array with newly allocated error data.
edatalen
: output length of error data.
Description:
Extract additional error data from server (possibly empty).
Return value:
Returns SHISHI_OK iff successful.
shishi_krberror_methoddata
Function:
int
shishi_krberror_methoddata
(Shishi *
handle
Shishi_asn1
krberror
Shishi_asn1
methoddata
handle
: shishi handle as allocated by
shishi_init()
krberror
: KRB-ERROR structure with error code.
methoddata
: output ASN.1 METHOD-DATA.
Description:
Extract METHOD-DATA ASN.1 object from the e-data field. The e-data
field will only contain a METHOD-DATA if the krberror error code is
SHISHI_KDC_ERR_PREAUTH_REQUIRED
Return value:
Returns SHISHI_OK iff successful.
shishi_krberror_set_edata
Function:
int
shishi_krberror_set_edata
(Shishi *
handle
Shishi_asn1
krberror
, const char *
edata
handle
: shishi handle as allocated by
shishi_init()
krberror
: krberror as allocated by
shishi_krberror()
edata
: input array with error text to set.
Description:
Set error text (e-data) field in KRB-ERROR to specified value.
Return value:
Returns SHISHI_OK iff successful.
shishi_krberror_remove_edata
Function:
int
shishi_krberror_remove_edata
(Shishi *
handle
Shishi_asn1
krberror
handle
: shishi handle as allocated by
shishi_init()
krberror
: krberror as allocated by
shishi_krberror()
Description:
Remove error text (e-data) field in KRB-ERROR.
Return value:
Returns SHISHI_OK iff successful.
shishi_krberror_pretty_print
Function:
int
shishi_krberror_pretty_print
(Shishi *
handle
, FILE *
fh
Shishi_asn1
krberror
handle
: shishi handle as allocated by
shishi_init()
fh
: file handle opened for writing.
krberror
: KRB-ERROR structure with error code.
Description:
Print KRB-ERROR error condition and some explanatory text to file
descriptor.
Return value:
Returns SHISHI_OK iff successful.
shishi_krberror_errorcode_message
Function:
const char *
shishi_krberror_errorcode_message
(Shishi *
handle
, int
errorcode
handle
: shishi handle as allocated by
shishi_init()
errorcode
: integer KRB-ERROR error code.
Description:
Get human readable string describing KRB-ERROR code.
Return value:
Return a string describing error code. This function
will always return a string even if the error code
isn’t known.
shishi_krberror_message
Function:
const char *
shishi_krberror_message
(Shishi *
handle
Shishi_asn1
krberror
handle
: shishi handle as allocated by
shishi_init()
krberror
: KRB-ERROR structure with error code.
Description:
Extract error code (see
shishi_krberror_errorcode_fast()
) and
return error message (see
shishi_krberror_errorcode_message()
).
Return value:
Return a string describing error code. This function
will always return a string even if the error code
isn’t known.
Next:
X.509 Functions
, Previous:
KRB-ERROR Functions
, Up:
Programming Manual
Contents
][
Index
5.13 Cryptographic Functions
Underneath the high-level functions described earlier, cryptographic
operations are happening. If you need to access these cryptographic
primitives directly, this section describes the functions available.
Most cryptographic operations need keying material, and cryptographic
keys have been isolated into it’s own data structure
Shishi_key
. The following illustrates it’s contents, but note
that you cannot access it’s elements directly but must use the
accessor functions described below.
struct Shishi_key
int type; /* RFC 1510 encryption integer type */
char *value; /* Cryptographic key data */
int version; /* RFC 1510 ``kvno'' */
};
All functions that operate on this data structure are described now.
shishi_key_principal
Function:
const char *
shishi_key_principal
(const
Shishi_key
key
key
: structure that holds key information
Description:
Get the principal part of the key owner principal name, i.e.,
except the realm.
Return value:
Returns the principal owning the key. (Not a copy of
it, so don’t modify or deallocate it.)
shishi_key_principal_set
Function:
void
shishi_key_principal_set
Shishi_key
key
, const char *
principal
key
: structure that holds key information
principal
: string with new principal name.
Description:
Set the principal owning the key. The string is copied into the
key, so you can dispose of the variable immediately after calling
this function.
shishi_key_realm
Function:
const char *
shishi_key_realm
(const
Shishi_key
key
key
: structure that holds key information
Description:
Get the realm part of the key owner principal name.
Return value:
Returns the realm for the principal owning the key.
(Not a copy of it, so don’t modify or deallocate it.)
shishi_key_realm_set
Function:
void
shishi_key_realm_set
Shishi_key
key
, const char *
realm
key
: structure that holds key information
realm
: string with new realm name.
Description:
Set the realm for the principal owning the key. The string is
copied into the key, so you can dispose of the variable immediately
after calling this function.
shishi_key_type
Function:
int
shishi_key_type
(const
Shishi_key
key
key
: structure that holds key information
Description:
Get key type.
Return value:
Returns the type of key as an integer as described in
the standard.
shishi_key_type_set
Function:
void
shishi_key_type_set
Shishi_key
key
int32_t
type
key
: structure that holds key information
type
: type to set in key.
Description:
Set the type of key in key structure.
shishi_key_value
Function:
const char *
shishi_key_value
(const
Shishi_key
key
key
: structure that holds key information
Description:
Get the raw key bytes.
Return value:
Returns the key value as a pointer which is valid
throughout the lifetime of the key structure.
shishi_key_value_set
Function:
void
shishi_key_value_set
Shishi_key
key
, const char *
value
key
: structure that holds key information
value
: input array with key data.
Description:
Set the key value and length in key structure. The value is copied
into the key (in other words, you can deallocate
value
right after
calling this function without modifying the value inside the key).
shishi_key_version
Function:
uint32_t
shishi_key_version
(const
Shishi_key
key
key
: structure that holds key information
Description:
Get the "kvno" (key version) of key. It will be UINT32_MAX if the
key is not long-lived.
Return value:
Returns the version of key ("kvno").
shishi_key_version_set
Function:
void
shishi_key_version_set
Shishi_key
key
uint32_t
kvno
key
: structure that holds key information
kvno
: new version integer.
Description:
Set the version of key ("kvno") in key structure. Use UINT32_MAX
for non-ptermanent keys.
shishi_key_timestamp
Function:
time_t
shishi_key_timestamp
(const
Shishi_key
key
key
: structure that holds key information
Description:
Get the time the key was established. Typically only present when
the key was imported from a keytab format.
Return value:
Returns the time the key was established, or
(time_t)-1 if not available.
Since:
0.0.42
shishi_key_timestamp_set
Function:
void
shishi_key_timestamp_set
Shishi_key
key
time_t
timestamp
key
: structure that holds key information
timestamp
: new timestamp.
Description:
Set the time the key was established. Typically only relevant when
exporting the key to keytab format.
Since:
0.0.42
shishi_key_name
Function:
const char *
shishi_key_name
Shishi_key
key
key
: structure that holds key information
Description:
Calls shishi_cipher_name for key type.
Return value:
Return name of key.
shishi_key_length
Function:
size_t
shishi_key_length
(const
Shishi_key
key
key
: structure that holds key information
Description:
Calls shishi_cipher_keylen for key type.
Return value:
Returns the length of the key value.
shishi_key
Function:
int
shishi_key
(Shishi *
handle
Shishi_key
**
key
handle
: Shishi library handle create by
shishi_init()
key
: pointer to structure that will hold newly created key information
Description:
Create a new Key information structure.
Return value:
Returns SHISHI_OK iff successful.
shishi_key_done
Function:
void
shishi_key_done
Shishi_key
key
key
: pointer to structure that holds key information.
Description:
Deallocates key information structure.
shishi_key_copy
Function:
void
shishi_key_copy
Shishi_key
dstkey
Shishi_key
srckey
dstkey
: structure that holds destination key information
srckey
: structure that holds source key information
Description:
Copies source key into existing allocated destination key.
shishi_key_from_value
Function:
int
shishi_key_from_value
(Shishi *
handle
int32_t
type
, const char *
value
Shishi_key
**
key
handle
: Shishi library handle create by
shishi_init()
type
: type of key.
value
: input array with key value, or NULL.
key
: pointer to structure that will hold newly created key information
Description:
Create a new Key information structure, and set the key type and
key value. KEY contains a newly allocated structure only if this
function is successful.
Return value:
Returns SHISHI_OK iff successful.
shishi_key_from_base64
Function:
int
shishi_key_from_base64
(Shishi *
handle
int32_t
type
, const char *
value
Shishi_key
**
key
handle
: Shishi library handle create by
shishi_init()
type
: type of key.
value
: input string with base64 encoded key value, or NULL.
key
: pointer to structure that will hold newly created key information
Description:
Create a new Key information structure, and set the key type and
key value. KEY contains a newly allocated structure only if this
function is successful.
Return value:
Returns SHISHI_INVALID_KEY if the base64 encoded key
length doesn’t match the key type, and SHISHI_OK on
success.
shishi_key_random
Function:
int
shishi_key_random
(Shishi *
handle
int32_t
type
Shishi_key
**
key
handle
: Shishi library handle create by
shishi_init()
type
: type of key.
key
: pointer to structure that will hold newly created key information
Description:
Create a new Key information structure for the key type and some
random data. KEY contains a newly allocated structure only if this
function is successful.
Return value:
Returns SHISHI_OK iff successful.
shishi_key_from_random
Function:
int
shishi_key_from_random
(Shishi *
handle
int32_t
type
, const char *
rnd
size_t
rndlen
Shishi_key
**
outkey
handle
: Shishi library handle create by
shishi_init()
type
: type of key.
rnd
: random data.
rndlen
: length of random data.
outkey
: pointer to structure that will hold newly created key information
Description:
Create a new Key information structure, and set the key type and
key value using
shishi_random_to_key()
. KEY contains a newly
allocated structure only if this function is successful.
Return value:
Returns SHISHI_OK iff successful.
shishi_key_from_string
Function:
int
shishi_key_from_string
(Shishi *
handle
int32_t
type
, const char *
password
size_t
passwordlen
, const char *
salt
size_t
saltlen
, const char *
parameter
Shishi_key
**
outkey
handle
: Shishi library handle create by
shishi_init()
type
: type of key.
password
: input array containing password.
passwordlen
: length of input array containing password.
salt
: input array containing salt.
saltlen
: length of input array containing salt.
parameter
: input array with opaque encryption type specific information.
outkey
: pointer to structure that will hold newly created key information
Description:
Create a new Key information structure, and set the key type and
key value using
shishi_string_to_key()
. KEY contains a newly
allocated structure only if this function is successful.
Return value:
Returns SHISHI_OK iff successful.
shishi_key_from_name
Function:
int
shishi_key_from_name
(Shishi *
handle
int32_t
type
, const char *
name
, const char *
password
size_t
passwordlen
, const char *
parameter
Shishi_key
**
outkey
handle
: Shishi library handle create by
shishi_init()
type
: type of key.
name
: principal name of user.
password
: input array containing password.
passwordlen
: length of input array containing password.
parameter
: input array with opaque encryption type specific information.
outkey
: pointer to structure that will hold newly created key information
Description:
Create a new Key information structure, and derive the key from
principal name and password using
shishi_key_from_name()
. The salt
is derived from the principal name by concatenating the decoded
realm and principal.
Return value:
Returns SHISHI_OK iff successful.
Applications that run uninteractively may need keying material. In
these cases, the keys are stored in a file, a file that is normally
stored on the local host. The file should be protected from
unauthorized access. The file is in ASCII format and contains keys as
outputed by
shishi_key_print
. All functions that handle these
keys sets are described now.
shishi_keys
Function:
int
shishi_keys
(Shishi *
handle
Shishi_keys
**
keys
handle
: shishi handle as allocated by
shishi_init()
keys
: output pointer to newly allocated keys handle.
Description:
Get a new key set handle.
Return value:
Returns
SHISHI_OK
iff successful.
shishi_keys_done
Function:
void
shishi_keys_done
Shishi_keys
**
keys
keys
: key set handle as allocated by
shishi_keys()
Description:
Deallocates all resources associated with key set. The key set
handle must not be used in calls to other shishi_keys_*() functions
after this.
shishi_keys_size
Function:
int
shishi_keys_size
Shishi_keys
keys
keys
: key set handle as allocated by
shishi_keys()
Description:
Get size of key set.
Return value:
Returns number of keys stored in key set.
shishi_keys_nth
Function:
const Shishi_key *
shishi_keys_nth
Shishi_keys
keys
, int
keyno
keys
: key set handle as allocated by
shishi_keys()
keyno
: integer indicating requested key in key set.
Get the n:
th ticket in key set.
Return value:
Returns a key handle to the keyno:th key in the key
set, or NULL if
keys
is invalid or
keyno
is out of bounds. The
first key is
keyno
0, the second key
keyno
1, and so on.
shishi_keys_remove
Function:
void
shishi_keys_remove
Shishi_keys
keys
, int
keyno
keys
: key set handle as allocated by
shishi_keys()
keyno
: key number of key in the set to remove. The first
key is key number 0.
Description:
Remove a key, indexed by
keyno
, in given key set.
shishi_keys_add
Function:
int
shishi_keys_add
Shishi_keys
keys
Shishi_key
key
keys
: key set handle as allocated by
shishi_keys()
key
: key to be added to key set.
Description:
Add a key to the key set. A deep copy of the key is stored, so
changing
key
, or deallocating it, will not modify the value stored
in the key set.
Return value:
Returns
SHISHI_OK
iff successful.
shishi_keys_print
Function:
int
shishi_keys_print
Shishi_keys
keys
, FILE *
fh
keys
: key set to print.
fh
: file handle, open for writing, to print keys to.
Description:
Print all keys in set using shishi_key_print.
Returns:
Returns
SHISHI_OK
on success.
shishi_keys_to_file
Function:
int
shishi_keys_to_file
(Shishi *
handle
, const char *
filename
Shishi_keys
keys
handle
: shishi handle as allocated by
shishi_init()
filename
: filename to append key to.
keys
: set of keys to print.
Description:
Print an ASCII representation of a key structure to a file, for
each key in the key set. The file is appended to if it exists.
See
shishi_key_print()
for the format of the output.
Return value:
Returns
SHISHI_OK
iff successful.
shishi_keys_from_file
Function:
int
shishi_keys_from_file
Shishi_keys
keys
, const char *
filename
keys
: key set handle as allocated by
shishi_keys()
filename
: filename to read keys from.
Description:
Read zero or more keys from file
filename
and append them to the
keyset
keys
. See
shishi_key_print()
for the format of the input.
Return value:
Returns
SHISHI_OK
iff successful.
Since:
0.0.42
shishi_keys_for_serverrealm_in_file
Function:
Shishi_key *
shishi_keys_for_serverrealm_in_file
(Shishi *
handle
, const char *
filename
, const char *
server
, const char *
realm
handle
: Shishi library handle create by
shishi_init()
filename
: file to read keys from.
server
: server name to get key for.
realm
: realm of server to get key for.
Description:
Get keys that match specified
server
and
realm
from the key set
file
filename
Return value:
Returns the key for specific server and realm, read
from the indicated file, or NULL if no key could be found or an
error encountered.
shishi_keys_for_server_in_file
Function:
Shishi_key *
shishi_keys_for_server_in_file
(Shishi *
handle
, const char *
filename
, const char *
server
handle
: Shishi library handle create by
shishi_init()
filename
: file to read keys from.
server
: server name to get key for.
Description:
Get key for specified
server
from
filename
Return value:
Returns the key for specific server, read from the
indicated file, or NULL if no key could be found or an error
encountered.
shishi_keys_for_localservicerealm_in_file
Function:
Shishi_key *
shishi_keys_for_localservicerealm_in_file
(Shishi *
handle
, const char *
filename
, const char *
service
, const char *
realm
handle
: Shishi library handle create by
shishi_init()
filename
: file to read keys from.
service
: service to get key for.
realm
: realm of server to get key for, or NULL for default realm.
Description:
Get key for specified
service
and
realm
from
filename
Return value:
Returns the key for the server
"SERVICE/HOSTNAME@REALM" (where HOSTNAME is the current system’s
hostname), read from the default host keys file (see
shishi_hostkeys_default_file()
), or NULL if no key could be found
or an error encountered.
The previous functions require that the filename is known. For some
applications, servers, it makes sense to provide a system default.
These key sets used by server applications are known as “hostkeys”.
Here are the functions that operate on hostkeys (they are mostly
wrappers around generic key sets).
shishi_hostkeys_default_file
Function:
const char *
shishi_hostkeys_default_file
(Shishi *
handle
handle
: Shishi library handle create by
shishi_init()
Description:
Get file name of default host key file.
Return value:
Returns the default host key filename used in the
library. (Not a copy of it, so don’t modify or deallocate it.)
shishi_hostkeys_default_file_set
Function:
void
shishi_hostkeys_default_file_set
(Shishi *
handle
, const char *
hostkeysfile
handle
: Shishi library handle create by
shishi_init()
hostkeysfile
: string with new default hostkeys file name, or
NULL to reset to default.
Description:
Set the default host key filename used in the library. The
string is copied into the library, so you can dispose of the
variable immediately after calling this function.
shishi_hostkeys_for_server
Function:
Shishi_key *
shishi_hostkeys_for_server
(Shishi *
handle
, const char *
server
handle
: Shishi library handle create by
shishi_init()
server
: server name to get key for
Description:
Get host key for
server
Return value:
Returns the key for specific server, read from the
default host keys file (see
shishi_hostkeys_default_file()
), or
NULL if no key could be found or an error encountered.
shishi_hostkeys_for_serverrealm
Function:
Shishi_key *
shishi_hostkeys_for_serverrealm
(Shishi *
handle
, const char *
server
, const char *
realm
handle
: Shishi library handle create by
shishi_init()
server
: server name to get key for
realm
: realm of server to get key for.
Description:
Get host key for
server
in
realm
Return value:
Returns the key for specific server and realm, read
from the default host keys file (see
shishi_hostkeys_default_file()
), or NULL if no key could be found
or an error encountered.
shishi_hostkeys_for_localservicerealm
Function:
Shishi_key *
shishi_hostkeys_for_localservicerealm
(Shishi *
handle
, const char *
service
, const char *
realm
handle
: Shishi library handle create by
shishi_init()
service
: service to get key for.
realm
: realm of server to get key for, or NULL for default realm.
Description:
Get host key for
service
on current host in
realm
Return value:
Returns the key for the server
"SERVICE/HOSTNAME@REALM" (where HOSTNAME is the current system’s
hostname), read from the default host keys file (see
shishi_hostkeys_default_file()
), or NULL if no key could be found
or an error encountered.
shishi_hostkeys_for_localservice
Function:
Shishi_key *
shishi_hostkeys_for_localservice
(Shishi *
handle
, const char *
service
handle
: Shishi library handle create by
shishi_init()
service
: service to get key for.
Description:
Get host key for
service
on current host in default realm.
Return value:
Returns the key for the server "SERVICE/HOSTNAME"
(where HOSTNAME is the current system’s hostname), read from the
default host keys file (see
shishi_hostkeys_default_file()
), or
NULL if no key could be found or an error encountered.
After creating the key structure, it can be used to encrypt and
decrypt data, calculate checksum on data etc. All available functions
are described now.
shishi_cipher_supported_p
Function:
int
shishi_cipher_supported_p
int32_t
type
type
: encryption type, see Shishi_etype.
Description:
Find out if cipher is supported.
Return value:
Return 0 iff cipher is unsupported.
shishi_cipher_name
Function:
const char *
shishi_cipher_name
int32_t
type
type
: encryption type, see Shishi_etype.
Description:
Read humanly readable string for cipher.
Return value:
Return name of encryption type,
e.g. "des3-cbc-sha1-kd", as defined in the standards.
shishi_cipher_blocksize
Function:
int
shishi_cipher_blocksize
int32_t
type
type
: encryption type, see Shishi_etype.
Description:
Get block size for cipher.
Return value:
Return block size for encryption type, as defined in
the standards.
shishi_cipher_confoundersize
Function:
int
shishi_cipher_confoundersize
int32_t
type
type
: encryption type, see Shishi_etype.
Description:
Get length of confounder for cipher.
Return value:
Returns the size of the confounder (random data) for
encryption type, as defined in the standards, or (size_t)-1 on
error (e.g., unsupported encryption type).
shishi_cipher_keylen
Function:
size_t
shishi_cipher_keylen
int32_t
type
type
: encryption type, see Shishi_etype.
Description:
Get key length for cipher.
Return value:
Return length of key used for the encryption type, as
defined in the standards.
shishi_cipher_randomlen
Function:
size_t
shishi_cipher_randomlen
int32_t
type
type
: encryption type, see Shishi_etype.
Description:
Get length of random data for cipher.
Return value:
Return length of random used for the encryption type,
as defined in the standards, or (size_t)-1 on error (e.g.,
unsupported encryption type).
shishi_cipher_defaultcksumtype
Function:
int
shishi_cipher_defaultcksumtype
int32_t
type
type
: encryption type, see Shishi_etype.
Description:
Get the default checksum associated with cipher.
Return value:
Return associated checksum mechanism for the
encryption type, as defined in the standards.
shishi_cipher_parse
Function:
int
shishi_cipher_parse
(const char *
cipher
cipher
: name of encryption type, e.g. "des3-cbc-sha1-kd".
Description:
Get cipher number by parsing string.
Return value:
Return encryption type corresponding to a string.
shishi_checksum_supported_p
Function:
int
shishi_checksum_supported_p
int32_t
type
type
: checksum type, see Shishi_cksumtype.
Description:
Find out whether checksum is supported.
Return value:
Return 0 iff checksum is unsupported.
shishi_checksum_name
Function:
const char *
shishi_checksum_name
int32_t
type
type
: checksum type, see Shishi_cksumtype.
Description:
Get name of checksum.
Return value:
Return name of checksum type,
e.g. "hmac-sha1-96-aes256", as defined in the standards.
shishi_checksum_cksumlen
Function:
size_t
shishi_checksum_cksumlen
int32_t
type
type
: checksum type, see Shishi_cksumtype.
Description:
Get length of checksum output.
Return value:
Return length of checksum used for the checksum type,
as defined in the standards.
shishi_checksum_parse
Function:
int
shishi_checksum_parse
(const char *
checksum
checksum
: name of checksum type, e.g. "hmac-sha1-96-aes256".
Description:
Get checksum number by parsing a string.
Return value:
Return checksum type, see Shishi_cksumtype,
corresponding to a string.
shishi_string_to_key
Function:
int
shishi_string_to_key
(Shishi *
handle
int32_t
keytype
, const char *
password
size_t
passwordlen
, const char *
salt
size_t
saltlen
, const char *
parameter
Shishi_key
outkey
handle
: shishi handle as allocated by
shishi_init()
keytype
: cryptographic encryption type, see Shishi_etype.
password
: input array with password.
passwordlen
: length of input array with password.
salt
: input array with salt.
saltlen
: length of input array with salt.
parameter
: input array with opaque encryption type specific information.
outkey
: allocated key handle that will contain new key.
Description:
Derive key from a string (password) and salt (commonly
concatenation of realm and principal) for specified key type, and
set the type and value in the given key to the computed values.
The parameter value is specific for each keytype, and can be set if
the parameter information is not available.
Return value:
Returns
SHISHI_OK
iff successful.
shishi_random_to_key
Function:
int
shishi_random_to_key
(Shishi *
handle
int32_t
keytype
, const char *
rnd
size_t
rndlen
Shishi_key
outkey
handle
: shishi handle as allocated by
shishi_init()
keytype
: cryptographic encryption type, see Shishi_etype.
rnd
: input array with random data.
rndlen
: length of input array with random data.
outkey
: allocated key handle that will contain new key.
Description:
Derive key from random data for specified key type, and set the
type and value in the given key to the computed values.
Return value:
Returns
SHISHI_OK
iff successful.
shishi_checksum
Function:
int
shishi_checksum
(Shishi *
handle
Shishi_key
key
, int
keyusage
, int
cksumtype
, const char *
in
size_t
inlen
, char **
out
size_t
outlen
handle
: shishi handle as allocated by
shishi_init()
key
: key to compute checksum with.
keyusage
: integer specifying what this key is used for.
cksumtype
: the checksum algorithm to use.
in
: input array with data to integrity protect.
inlen
: size of input array with data to integrity protect.
out
: output array with newly allocated integrity protected data.
outlen
: output variable with length of output array with checksum.
Description:
Integrity protect data using key, possibly altered by supplied key
usage. If key usage is 0, no key derivation is used. The OUT
buffer must be deallocated by the caller.
Return value:
Returns
SHISHI_OK
iff successful.
shishi_verify
Function:
int
shishi_verify
(Shishi *
handle
Shishi_key
key
, int
keyusage
, int
cksumtype
, const char *
in
size_t
inlen
, const char *
cksum
size_t
cksumlen
handle
: shishi handle as allocated by
shishi_init()
key
: key to verify checksum with.
keyusage
: integer specifying what this key is used for.
cksumtype
: the checksum algorithm to use.
in
: input array with data that was integrity protected.
inlen
: size of input array with data that was integrity protected.
cksum
: input array with alleged checksum of data.
cksumlen
: size of input array with alleged checksum of data.
Description:
Verify checksum of data using key, possibly altered by supplied key
usage. If key usage is 0, no key derivation is used.
Return value:
Returns
SHISHI_OK
iff successful.
shishi_encrypt_ivupdate_etype
Function:
int
shishi_encrypt_ivupdate_etype
(Shishi *
handle
Shishi_key
key
, int
keyusage
int32_t
etype
, const char *
iv
size_t
ivlen
, char **
ivout
size_t
ivoutlen
, const char *
in
size_t
inlen
, char **
out
size_t
outlen
handle
: shishi handle as allocated by
shishi_init()
key
: key to encrypt with.
keyusage
: integer specifying what this key is encrypting.
etype
: integer specifying what cipher to use.
iv
: input array with initialization vector
ivlen
: size of input array with initialization vector.
ivout
: output array with newly allocated updated initialization vector.
ivoutlen
: size of output array with updated initialization vector.
in
: input array with data to encrypt.
inlen
: size of input array with data to encrypt.
out
: output array with newly allocated encrypted data.
outlen
: output variable with size of newly allocated output array.
Description:
Encrypts data as per encryption method using specified
initialization vector and key. The key actually used is derived
using the key usage. If key usage is 0, no key derivation is used.
The OUT buffer must be deallocated by the caller. If IVOUT or
IVOUTLEN is NULL, the updated IV is not saved anywhere.
Note that DECRYPT(ENCRYPT(data)) does not necessarily yield data
exactly. Some encryption types add pad to make the data fit into
the block size of the encryption algorithm. Furthermore, the pad
is not guaranteed to look in any special way, although existing
implementations often pad with the zero byte. This means that you
may have to "frame" data, so it is possible to infer the original
length after decryption. Compare ASN.1 DER which contains such
information.
Return value:
Returns
SHISHI_OK
iff successful.
shishi_encrypt_iv_etype
Function:
int
shishi_encrypt_iv_etype
(Shishi *
handle
Shishi_key
key
, int
keyusage
int32_t
etype
, const char *
iv
size_t
ivlen
, const char *
in
size_t
inlen
, char **
out
size_t
outlen
handle
: shishi handle as allocated by
shishi_init()
key
: key to encrypt with.
keyusage
: integer specifying what this key is encrypting.
etype
: integer specifying what cipher to use.
iv
: input array with initialization vector
ivlen
: size of input array with initialization vector.
in
: input array with data to encrypt.
inlen
: size of input array with data to encrypt.
out
: output array with newly allocated encrypted data.
outlen
: output variable with size of newly allocated output array.
Description:
Encrypts data as per encryption method using specified
initialization vector and key. The key actually used is derived
using the key usage. If key usage is 0, no key derivation is used.
The OUT buffer must be deallocated by the caller. The next IV is
lost, see shishi_encrypt_ivupdate_etype if you need it.
Note that DECRYPT(ENCRYPT(data)) does not necessarily yield data
exactly. Some encryption types add pad to make the data fit into
the block size of the encryption algorithm. Furthermore, the pad
is not guaranteed to look in any special way, although existing
implementations often pad with the zero byte. This means that you
may have to "frame" data, so it is possible to infer the original
length after decryption. Compare ASN.1 DER which contains such
information.
Return value:
Returns
SHISHI_OK
iff successful.
shishi_encrypt_etype
Function:
int
shishi_encrypt_etype
(Shishi *
handle
Shishi_key
key
, int
keyusage
int32_t
etype
, const char *
in
size_t
inlen
, char **
out
size_t
outlen
handle
: shishi handle as allocated by
shishi_init()
key
: key to encrypt with.
keyusage
: integer specifying what this key is encrypting.
etype
: integer specifying what cipher to use.
in
: input array with data to encrypt.
inlen
: size of input array with data to encrypt.
out
: output array with newly allocated encrypted data.
outlen
: output variable with size of newly allocated output array.
Description:
Encrypts data as per encryption method using specified
initialization vector and key. The key actually used is derived
using the key usage. If key usage is 0, no key derivation is used.
The OUT buffer must be deallocated by the caller. The default IV
is used, see shishi_encrypt_iv_etype if you need to alter it. The
next IV is lost, see shishi_encrypt_ivupdate_etype if you need it.
Note that DECRYPT(ENCRYPT(data)) does not necessarily yield data
exactly. Some encryption types add pad to make the data fit into
the block size of the encryption algorithm. Furthermore, the pad
is not guaranteed to look in any special way, although existing
implementations often pad with the zero byte. This means that you
may have to "frame" data, so it is possible to infer the original
length after decryption. Compare ASN.1 DER which contains such
information.
Return value:
Returns
SHISHI_OK
iff successful.
shishi_encrypt_ivupdate
Function:
int
shishi_encrypt_ivupdate
(Shishi *
handle
Shishi_key
key
, int
keyusage
, const char *
iv
size_t
ivlen
, char **
ivout
size_t
ivoutlen
, const char *
in
size_t
inlen
, char **
out
size_t
outlen
handle
: shishi handle as allocated by
shishi_init()
key
: key to encrypt with.
keyusage
: integer specifying what this key is encrypting.
iv
: input array with initialization vector
ivlen
: size of input array with initialization vector.
ivout
: output array with newly allocated updated initialization vector.
ivoutlen
: size of output array with updated initialization vector.
in
: input array with data to encrypt.
inlen
: size of input array with data to encrypt.
out
: output array with newly allocated encrypted data.
outlen
: output variable with size of newly allocated output array.
Description:
Encrypts data using specified initialization vector and key. The
key actually used is derived using the key usage. If key usage is
0, no key derivation is used. The OUT buffer must be deallocated
by the caller. If IVOUT or IVOUTLEN is NULL, the updated IV is not
saved anywhere.
Note that DECRYPT(ENCRYPT(data)) does not necessarily yield data
exactly. Some encryption types add pad to make the data fit into
the block size of the encryption algorithm. Furthermore, the pad
is not guaranteed to look in any special way, although existing
implementations often pad with the zero byte. This means that you
may have to "frame" data, so it is possible to infer the original
length after decryption. Compare ASN.1 DER which contains such
information.
Return value:
Returns
SHISHI_OK
iff successful.
shishi_encrypt_iv
Function:
int
shishi_encrypt_iv
(Shishi *
handle
Shishi_key
key
, int
keyusage
, const char *
iv
size_t
ivlen
, const char *
in
size_t
inlen
, char **
out
size_t
outlen
handle
: shishi handle as allocated by
shishi_init()
key
: key to encrypt with.
keyusage
: integer specifying what this key is encrypting.
iv
: input array with initialization vector
ivlen
: size of input array with initialization vector.
in
: input array with data to encrypt.
inlen
: size of input array with data to encrypt.
out
: output array with newly allocated encrypted data.
outlen
: output variable with size of newly allocated output array.
Description:
Encrypts data using specified initialization vector and key. The
key actually used is derived using the key usage. If key usage is
0, no key derivation is used. The OUT buffer must be deallocated
by the caller. The next IV is lost, see shishi_encrypt_ivupdate if
you need it.
Note that DECRYPT(ENCRYPT(data)) does not necessarily yield data
exactly. Some encryption types add pad to make the data fit into
the block size of the encryption algorithm. Furthermore, the pad
is not guaranteed to look in any special way, although existing
implementations often pad with the zero byte. This means that you
may have to "frame" data, so it is possible to infer the original
length after decryption. Compare ASN.1 DER which contains such
information.
Return value:
Returns
SHISHI_OK
iff successful.
shishi_encrypt
Function:
int
shishi_encrypt
(Shishi *
handle
Shishi_key
key
, int
keyusage
, char *
in
size_t
inlen
, char **
out
size_t
outlen
handle
: shishi handle as allocated by
shishi_init()
key
: key to encrypt with.
keyusage
: integer specifying what this key is encrypting.
in
: input array with data to encrypt.
inlen
: size of input array with data to encrypt.
out
: output array with newly allocated encrypted data.
outlen
: output variable with size of newly allocated output array.
Description:
Encrypts data using specified key. The key actually used is
derived using the key usage. If key usage is 0, no key derivation
is used. The OUT buffer must be deallocated by the caller. The
default IV is used, see shishi_encrypt_iv if you need to alter it.
The next IV is lost, see shishi_encrypt_ivupdate if you need it.
Note that DECRYPT(ENCRYPT(data)) does not necessarily yield data
exactly. Some encryption types add pad to make the data fit into
the block size of the encryption algorithm. Furthermore, the pad
is not guaranteed to look in any special way, although existing
implementations often pad with the zero byte. This means that you
may have to "frame" data, so it is possible to infer the original
length after decryption. Compare ASN.1 DER which contains such
information.
Return value:
Returns
SHISHI_OK
iff successful.
shishi_decrypt_ivupdate_etype
Function:
int
shishi_decrypt_ivupdate_etype
(Shishi *
handle
Shishi_key
key
, int
keyusage
int32_t
etype
, const char *
iv
size_t
ivlen
, char **
ivout
size_t
ivoutlen
, const char *
in
size_t
inlen
, char **
out
size_t
outlen
handle
: shishi handle as allocated by
shishi_init()
key
: key to decrypt with.
keyusage
: integer specifying what this key is decrypting.
etype
: integer specifying what cipher to use.
iv
: input array with initialization vector
ivlen
: size of input array with initialization vector.
ivout
: output array with newly allocated updated initialization vector.
ivoutlen
: size of output array with updated initialization vector.
in
: input array with data to decrypt.
inlen
: size of input array with data to decrypt.
out
: output array with newly allocated decrypted data.
outlen
: output variable with size of newly allocated output array.
Description:
Decrypts data as per encryption method using specified
initialization vector and key. The key actually used is derived
using the key usage. If key usage is 0, no key derivation is used.
The OUT buffer must be deallocated by the caller. If IVOUT or
IVOUTLEN is NULL, the updated IV is not saved anywhere.
Note that DECRYPT(ENCRYPT(data)) does not necessarily yield data
exactly. Some encryption types add pad to make the data fit into
the block size of the encryption algorithm. Furthermore, the pad
is not guaranteed to look in any special way, although existing
implementations often pad with the zero byte. This means that you
may have to "frame" data, so it is possible to infer the original
length after decryption. Compare ASN.1 DER which contains such
information.
Return value:
Returns
SHISHI_OK
iff successful.
shishi_decrypt_iv_etype
Function:
int
shishi_decrypt_iv_etype
(Shishi *
handle
Shishi_key
key
, int
keyusage
int32_t
etype
, const char *
iv
size_t
ivlen
, const char *
in
size_t
inlen
, char **
out
size_t
outlen
handle
: shishi handle as allocated by
shishi_init()
key
: key to decrypt with.
keyusage
: integer specifying what this key is decrypting.
etype
: integer specifying what cipher to use.
iv
: input array with initialization vector
ivlen
: size of input array with initialization vector.
in
: input array with data to decrypt.
inlen
: size of input array with data to decrypt.
out
: output array with newly allocated decrypted data.
outlen
: output variable with size of newly allocated output array.
Description:
Decrypts data as per encryption method using specified
initialization vector and key. The key actually used is derived
using the key usage. If key usage is 0, no key derivation is used.
The OUT buffer must be deallocated by the caller. The next IV is
lost, see shishi_decrypt_ivupdate_etype if you need it.
Note that DECRYPT(ENCRYPT(data)) does not necessarily yield data
exactly. Some encryption types add pad to make the data fit into
the block size of the encryption algorithm. Furthermore, the pad
is not guaranteed to look in any special way, although existing
implementations often pad with the zero byte. This means that you
may have to "frame" data, so it is possible to infer the original
length after decryption. Compare ASN.1 DER which contains such
information.
Return value:
Returns
SHISHI_OK
iff successful.
shishi_decrypt_etype
Function:
int
shishi_decrypt_etype
(Shishi *
handle
Shishi_key
key
, int
keyusage
int32_t
etype
, const char *
in
size_t
inlen
, char **
out
size_t
outlen
handle
: shishi handle as allocated by
shishi_init()
key
: key to decrypt with.
keyusage
: integer specifying what this key is decrypting.
etype
: integer specifying what cipher to use.
in
: input array with data to decrypt.
inlen
: size of input array with data to decrypt.
out
: output array with newly allocated decrypted data.
outlen
: output variable with size of newly allocated output array.
Description:
Decrypts data as per encryption method using specified key. The
key actually used is derived using the key usage. If key usage is
0, no key derivation is used. The OUT buffer must be deallocated
by the caller. The default IV is used, see shishi_decrypt_iv_etype
if you need to alter it. The next IV is lost, see
shishi_decrypt_ivupdate_etype if you need it.
Note that DECRYPT(ENCRYPT(data)) does not necessarily yield data
exactly. Some encryption types add pad to make the data fit into
the block size of the encryption algorithm. Furthermore, the pad
is not guaranteed to look in any special way, although existing
implementations often pad with the zero byte. This means that you
may have to "frame" data, so it is possible to infer the original
length after decryption. Compare ASN.1 DER which contains such
information.
Return value:
Returns
SHISHI_OK
iff successful.
shishi_decrypt_ivupdate
Function:
int
shishi_decrypt_ivupdate
(Shishi *
handle
Shishi_key
key
, int
keyusage
, const char *
iv
size_t
ivlen
, char **
ivout
size_t
ivoutlen
, const char *
in
size_t
inlen
, char **
out
size_t
outlen
handle
: shishi handle as allocated by
shishi_init()
key
: key to decrypt with.
keyusage
: integer specifying what this key is decrypting.
iv
: input array with initialization vector
ivlen
: size of input array with initialization vector.
ivout
: output array with newly allocated updated initialization vector.
ivoutlen
: size of output array with updated initialization vector.
in
: input array with data to decrypt.
inlen
: size of input array with data to decrypt.
out
: output array with newly allocated decrypted data.
outlen
: output variable with size of newly allocated output array.
Description:
Decrypts data using specified initialization vector and key. The
key actually used is derived using the key usage. If key usage is
0, no key derivation is used. The OUT buffer must be deallocated
by the caller. If IVOUT or IVOUTLEN is NULL, the updated IV is not
saved anywhere.
Note that DECRYPT(ENCRYPT(data)) does not necessarily yield data
exactly. Some encryption types add pad to make the data fit into
the block size of the encryption algorithm. Furthermore, the pad
is not guaranteed to look in any special way, although existing
implementations often pad with the zero byte. This means that you
may have to "frame" data, so it is possible to infer the original
length after decryption. Compare ASN.1 DER which contains such
information.
Return value:
Returns
SHISHI_OK
iff successful.
shishi_decrypt_iv
Function:
int
shishi_decrypt_iv
(Shishi *
handle
Shishi_key
key
, int
keyusage
, const char *
iv
size_t
ivlen
, const char *
in
size_t
inlen
, char **
out
size_t
outlen
handle
: shishi handle as allocated by
shishi_init()
key
: key to decrypt with.
keyusage
: integer specifying what this key is decrypting.
iv
: input array with initialization vector
ivlen
: size of input array with initialization vector.
in
: input array with data to decrypt.
inlen
: size of input array with data to decrypt.
out
: output array with newly allocated decrypted data.
outlen
: output variable with size of newly allocated output array.
Description:
Decrypts data using specified initialization vector and key. The
key actually used is derived using the key usage. If key usage is
0, no key derivation is used. The OUT buffer must be deallocated
by the caller. The next IV is lost, see
shishi_decrypt_ivupdate_etype if you need it.
Note that DECRYPT(ENCRYPT(data)) does not necessarily yield data
exactly. Some encryption types add pad to make the data fit into
the block size of the encryption algorithm. Furthermore, the pad
is not guaranteed to look in any special way, although existing
implementations often pad with the zero byte. This means that you
may have to "frame" data, so it is possible to infer the original
length after decryption. Compare ASN.1 DER which contains such
information.
Return value:
Returns
SHISHI_OK
iff successful.
shishi_decrypt
Function:
int
shishi_decrypt
(Shishi *
handle
Shishi_key
key
, int
keyusage
, const char *
in
size_t
inlen
, char **
out
size_t
outlen
handle
: shishi handle as allocated by
shishi_init()
key
: key to decrypt with.
keyusage
: integer specifying what this key is decrypting.
in
: input array with data to decrypt.
inlen
: size of input array with data to decrypt.
out
: output array with newly allocated decrypted data.
outlen
: output variable with size of newly allocated output array.
Description:
Decrypts data specified key. The key actually used is derived
using the key usage. If key usage is 0, no key derivation is used.
The OUT buffer must be deallocated by the caller. The default IV
is used, see shishi_decrypt_iv if you need to alter it. The next
IV is lost, see shishi_decrypt_ivupdate if you need it.
Note that DECRYPT(ENCRYPT(data)) does not necessarily yield data
exactly. Some encryption types add pad to make the data fit into
the block size of the encryption algorithm. Furthermore, the pad
is not guaranteed to look in any special way, although existing
implementations often pad with the zero byte. This means that you
may have to "frame" data, so it is possible to infer the original
length after decryption. Compare ASN.1 DER which contains such
information.
Return value:
Returns
SHISHI_OK
iff successful.
shishi_n_fold
Function:
int
shishi_n_fold
(Shishi *
handle
, const char *
in
size_t
inlen
, char *
out
size_t
outlen
handle
: shishi handle as allocated by
shishi_init()
in
: input array with data to decrypt.
inlen
: size of input array with data to decrypt ("M").
out
: output array with decrypted data.
outlen
: size of output array ("N").
Description:
Fold data into a fixed length output array, with the intent to give
each input bit approximately equal weight in determining the value
of each output bit.
The algorithm is from "A Better Key Schedule For DES-like Ciphers"
by Uri Blumenthal and Steven M. Bellovin,
sample vectors provided by the paper are incorrect.
Return value:
Returns
SHISHI_OK
iff successful.
shishi_dr
Function:
int
shishi_dr
(Shishi *
handle
Shishi_key
key
, const char *
prfconstant
size_t
prfconstantlen
, char *
derivedrandom
size_t
derivedrandomlen
handle
: shishi handle as allocated by
shishi_init()
key
: input array with cryptographic key to use.
prfconstant
: input array with the constant string.
prfconstantlen
: size of input array with the constant string.
derivedrandom
: output array with derived random data.
derivedrandomlen
: size of output array with derived random data.
Description:
Derive "random" data from a key and a constant thusly:
DR(KEY, PRFCONSTANT) = TRUNCATE(DERIVEDRANDOMLEN,
SHISHI_ENCRYPT(KEY, PRFCONSTANT)).
Return value:
Returns
SHISHI_OK
iff successful.
shishi_dk
Function:
int
shishi_dk
(Shishi *
handle
Shishi_key
key
, const char *
prfconstant
size_t
prfconstantlen
Shishi_key
derivedkey
handle
: shishi handle as allocated by
shishi_init()
key
: input cryptographic key to use.
prfconstant
: input array with the constant string.
prfconstantlen
: size of input array with the constant string.
derivedkey
: pointer to derived key (allocated by caller).
Derive a key from a key and a constant thusly:
DK(KEY, PRFCONSTANT) = SHISHI_RANDOM-TO-KEY(SHISHI_DR(KEY, PRFCONSTANT)).
Return value:
Returns
SHISHI_OK
iff successful.
An easier way to use encryption and decryption if your application
repeatedly calls, e.g.,
shishi_encrypt_ivupdate
, is to use the
following functions. They store the key, initialization vector, etc,
in a context, and the encryption and decryption operations update the
IV within the context automatically.
shishi_crypto
Function:
Shishi_crypto *
shishi_crypto
(Shishi *
handle
Shishi_key
key
, int
keyusage
int32_t
etype
, const char *
iv
size_t
ivlen
handle
: shishi handle as allocated by
shishi_init()
key
: key to encrypt with.
keyusage
: integer specifying what this key will encrypt/decrypt.
etype
: integer specifying what cipher to use.
iv
: input array with initialization vector
ivlen
: size of input array with initialization vector.
Description:
Initialize a crypto context. This store a key, keyusage,
encryption type and initialization vector in a "context", and the
caller can then use this context to perform encryption via
shishi_crypto_encrypt()
and decryption via
shishi_crypto_encrypt()
without supplying all those details again. The functions also
takes care of propagating the IV between calls.
When the application no longer need to use the context, it should
deallocate resources associated with it by calling
shishi_crypto_close()
Return value:
Return a newly allocated crypto context.
shishi_crypto_encrypt
Function:
int
shishi_crypto_encrypt
Shishi_crypto
ctx
, const char *
in
size_t
inlen
, char **
out
size_t
outlen
ctx
: crypto context as returned by
shishi_crypto()
in
: input array with data to encrypt.
inlen
: size of input array with data to encrypt.
out
: output array with newly allocated encrypted data.
outlen
: output variable with size of newly allocated output array.
Description:
Encrypt data, using information (e.g., key and initialization
vector) from context. The IV is updated inside the context after
this call.
When the application no longer need to use the context, it should
deallocate resources associated with it by calling
shishi_crypto_close()
Return value:
Returns
SHISHI_OK
iff successful.
shishi_crypto_decrypt
Function:
int
shishi_crypto_decrypt
Shishi_crypto
ctx
, const char *
in
size_t
inlen
, char **
out
size_t
outlen
ctx
: crypto context as returned by
shishi_crypto()
in
: input array with data to decrypt.
inlen
: size of input array with data to decrypt.
out
: output array with newly allocated decrypted data.
outlen
: output variable with size of newly allocated output array.
Description:
Decrypt data, using information (e.g., key and initialization
vector) from context. The IV is updated inside the context after
this call.
When the application no longer need to use the context, it should
deallocate resources associated with it by calling
shishi_crypto_close()
Return value:
Returns
SHISHI_OK
iff successful.
shishi_crypto_close
Function:
void
shishi_crypto_close
Shishi_crypto
ctx
ctx
: crypto context as returned by
shishi_crypto()
Description:
Deallocate resources associated with the crypto context.
Also included in Shishi is an interface to the really low-level
cryptographic primitives. They map directly on the underlying
cryptographic library used (i.e., Gnulib or Libgcrypt) and is used
internally by Shishi.
shishi_randomize
Function:
int
shishi_randomize
(Shishi *
handle
, int
strong
, void *
data
size_t
datalen
handle
: shishi handle as allocated by
shishi_init()
strong
: 0 iff operation should not block, non-0 for very strong randomness.
data
: output array to be filled with random data.
datalen
: size of output array.
Description:
Store cryptographically random data of given size in the provided
buffer.
Return value:
Returns
SHISHI_OK
iff successful.
shishi_crc
Function:
int
shishi_crc
(Shishi *
handle
, const char *
in
size_t
inlen
, char *
out
[4]
handle
: shishi handle as allocated by
shishi_init()
in
: input character array of data to checksum.
inlen
: length of input character array of data to checksum.
out
: newly allocated character array with checksum of data.
Description:
Compute checksum of data using CRC32 modified according to RFC
1510. The
out
buffer must be deallocated by the caller.
The modifications compared to standard CRC32 is that no initial and
final XOR is performed, and that the output is returned in
LSB-first order.
Return value:
Returns SHISHI_OK iff successful.
shishi_md4
Function:
int
shishi_md4
(Shishi *
handle
, const char *
in
size_t
inlen
, char *
out
[16]
handle
: shishi handle as allocated by
shishi_init()
in
: input character array of data to hash.
inlen
: length of input character array of data to hash.
out
: newly allocated character array with hash of data.
Description:
Compute hash of data using MD4. The
out
buffer must be
deallocated by the caller.
Return value:
Returns SHISHI_OK iff successful.
shishi_md5
Function:
int
shishi_md5
(Shishi *
handle
, const char *
in
size_t
inlen
, char *
out
[16]
handle
: shishi handle as allocated by
shishi_init()
in
: input character array of data to hash.
inlen
: length of input character array of data to hash.
out
: newly allocated character array with hash of data.
Description:
Compute hash of data using MD5. The
out
buffer must be
deallocated by the caller.
Return value:
Returns SHISHI_OK iff successful.
shishi_hmac_md5
Function:
int
shishi_hmac_md5
(Shishi *
handle
, const char *
key
size_t
keylen
, const char *
in
size_t
inlen
, char *
outhash
[16]
handle
: shishi handle as allocated by
shishi_init()
key
: input character array with key to use.
keylen
: length of input character array with key to use.
in
: input character array of data to hash.
inlen
: length of input character array of data to hash.
outhash
: newly allocated character array with keyed hash of data.
Description:
Compute keyed checksum of data using HMAC-MD5. The
outhash
buffer
must be deallocated by the caller.
Return value:
Returns SHISHI_OK iff successful.
shishi_hmac_sha1
Function:
int
shishi_hmac_sha1
(Shishi *
handle
, const char *
key
size_t
keylen
, const char *
in
size_t
inlen
, char *
outhash
[20]
handle
: shishi handle as allocated by
shishi_init()
key
: input character array with key to use.
keylen
: length of input character array with key to use.
in
: input character array of data to hash.
inlen
: length of input character array of data to hash.
outhash
: newly allocated character array with keyed hash of data.
Description:
Compute keyed checksum of data using HMAC-SHA1. The
outhash
buffer must be deallocated by the caller.
Return value:
Returns SHISHI_OK iff successful.
shishi_des_cbc_mac
Function:
int
shishi_des_cbc_mac
(Shishi *
handle
, const char
key
[8]
, const char
iv
[8]
, const char *
in
size_t
inlen
, char *
out
[8]
handle
: shishi handle as allocated by
shishi_init()
key
: input character array with key to use.
iv
: input character array with initialization vector to use, can be NULL.
in
: input character array of data to hash.
inlen
: length of input character array of data to hash.
out
: newly allocated character array with keyed hash of data.
Description:
Computed keyed checksum of data using DES-CBC-MAC. The
out
buffer
must be deallocated by the caller.
Return value:
Returns SHISHI_OK iff successful.
shishi_arcfour
Function:
int
shishi_arcfour
(Shishi *
handle
, int
decryptp
, const char *
key
size_t
keylen
, const char
iv
[258]
, char *
ivout
[258]
, const char *
in
size_t
inlen
, char **
out
handle
: shishi handle as allocated by
shishi_init()
decryptp
: 0 to indicate encryption, non-0 to indicate decryption.
key
: input character array with key to use.
keylen
: length of input key array.
iv
: input character array with initialization vector to use, or NULL.
ivout
: output character array with updated initialization vector, or NULL.
in
: input character array of data to encrypt/decrypt.
inlen
: length of input character array of data to encrypt/decrypt.
out
: newly allocated character array with encrypted/decrypted data.
Description:
Encrypt or decrypt data (depending on
decryptp
) using ARCFOUR.
The
out
buffer must be deallocated by the caller.
The "initialization vector" used here is the concatenation of the
sbox and i and j, and is thus always of size 256 + 1 + 1. This is
a slight abuse of terminology, and assumes you know what you are
doing. Don’t use it if you can avoid to.
Return value:
Returns SHISHI_OK iff successful.
shishi_des
Function:
int
shishi_des
(Shishi *
handle
, int
decryptp
, const char
key
[8]
, const char
iv
[8]
, char *
ivout
[8]
, const char *
in
size_t
inlen
, char **
out
handle
: shishi handle as allocated by
shishi_init()
decryptp
: 0 to indicate encryption, non-0 to indicate decryption.
key
: input character array with key to use.
iv
: input character array with initialization vector to use, or NULL.
ivout
: output character array with updated initialization vector, or NULL.
in
: input character array of data to encrypt/decrypt.
inlen
: length of input character array of data to encrypt/decrypt.
out
: newly allocated character array with encrypted/decrypted data.
Description:
Encrypt or decrypt data (depending on
decryptp
) using DES in CBC
mode. The
out
buffer must be deallocated by the caller.
Return value:
Returns SHISHI_OK iff successful.
shishi_3des
Function:
int
shishi_3des
(Shishi *
handle
, int
decryptp
, const char
key
[8]
, const char
iv
[8]
, char *
ivout
[8]
, const char *
in
size_t
inlen
, char **
out
handle
: shishi handle as allocated by
shishi_init()
decryptp
: 0 to indicate encryption, non-0 to indicate decryption.
key
: input character array with key to use.
iv
: input character array with initialization vector to use, or NULL.
ivout
: output character array with updated initialization vector, or NULL.
in
: input character array of data to encrypt/decrypt.
inlen
: length of input character array of data to encrypt/decrypt.
out
: newly allocated character array with encrypted/decrypted data.
Description:
Encrypt or decrypt data (depending on
decryptp
) using 3DES in CBC
mode. The
out
buffer must be deallocated by the caller.
Return value:
Returns SHISHI_OK iff successful.
shishi_aes_cts
Function:
int
shishi_aes_cts
(Shishi *
handle
, int
decryptp
, const char *
key
size_t
keylen
, const char
iv
[16]
, char *
ivout
[16]
, const char *
in
size_t
inlen
, char **
out
handle
: shishi handle as allocated by
shishi_init()
decryptp
: 0 to indicate encryption, non-0 to indicate decryption.
key
: input character array with key to use.
keylen
: length of input character array with key to use.
iv
: input character array with initialization vector to use, or NULL.
ivout
: output character array with updated initialization vector, or NULL.
in
: input character array of data to encrypt/decrypt.
inlen
: length of input character array of data to encrypt/decrypt.
out
: newly allocated character array with encrypted/decrypted data.
Description:
Encrypt or decrypt data (depending on
decryptp
) using AES in
CBC-CTS mode. The length of the key,
keylen
, decide if AES 128 or
AES 256 should be used. The
out
buffer must be deallocated by the
caller.
Return value:
Returns SHISHI_OK iff successful.
shishi_pbkdf2_sha1
Function:
int
shishi_pbkdf2_sha1
(Shishi *
handle
, const char *
size_t
Plen
, const char *
size_t
Slen
, unsigned int
, unsigned int
dkLen
, char *
DK
handle
: shishi handle as allocated by
shishi_init()
: input password, an octet string
Plen
: length of password, an octet string
: input salt, an octet string
Slen
: length of salt, an octet string
: iteration count, a positive integer
dkLen
: intended length in octets of the derived key, a positive integer,
at most (2^32 - 1) * hLen. The DK array must have room for this many
characters.
DK
: output derived key, a dkLen-octet string
Description:
Derive key using the PBKDF2 defined in PKCS5. PBKDF2 applies a
pseudorandom function to derive keys. The length of the derived key
is essentially unbounded. (However, the maximum effective search
space for the derived key may be limited by the structure of the
underlying pseudorandom function, which is this function is always
SHA1.)
Return value:
Returns SHISHI_OK iff successful.
Next:
Utility Functions
, Previous:
Cryptographic Functions
, Up:
Programming Manual
Contents
][
Index
5.14 X.509 Functions
The functions described in this section are used by the STARTTLS
functionality, see
Kerberos via TLS
shishi_x509ca_default_file_guess
Function:
char *
shishi_x509ca_default_file_guess
(Shishi *
handle
handle
: Shishi library handle create by
shishi_init()
Description:
Guesses the default X.509 CA certificate filename; it is
/.shishi/client.ca.
Return value:
Returns default X.509 client certificate filename as
a string that has to be deallocated with
free()
by the caller.
shishi_x509ca_default_file_set
Function:
void
shishi_x509ca_default_file_set
(Shishi *
handle
, const char *
x509cafile
handle
: Shishi library handle create by
shishi_init()
x509cafile
: string with new default x509 client certificate file name,
or NULL to reset to default.
Description:
Set the default X.509 CA certificate filename used in the library.
The certificate is used during TLS connections with the KDC to
authenticate the KDC. The string is copied into the library, so
you can dispose of the variable immediately after calling this
function.
shishi_x509ca_default_file
Function:
const char *
shishi_x509ca_default_file
(Shishi *
handle
handle
: Shishi library handle create by
shishi_init()
Description:
Get filename for default X.509 CA certificate.
Return value:
Returns the default X.509 CA certificate filename
used in the library. The certificate is used during TLS
connections with the KDC to authenticate the KDC. The string is
not a copy, so don’t modify or deallocate it.
shishi_x509cert_default_file_guess
Function:
char *
shishi_x509cert_default_file_guess
(Shishi *
handle
handle
: Shishi library handle create by
shishi_init()
Description:
Guesses the default X.509 client certificate filename; it is
/.shishi/client.certs.
Return value:
Returns default X.509 client certificate filename as
a string that has to be deallocated with
free()
by the caller.
shishi_x509cert_default_file_set
Function:
void
shishi_x509cert_default_file_set
(Shishi *
handle
, const char *
x509certfile
handle
: Shishi library handle create by
shishi_init()
x509certfile
: string with new default x509 client certificate file name,
or NULL to reset to default.
Description:
Set the default X.509 client certificate filename used in the
library. The certificate is used during TLS connections with the
KDC to authenticate the client. The string is copied into the
library, so you can dispose of the variable immediately after
calling this function.
shishi_x509cert_default_file
Function:
const char *
shishi_x509cert_default_file
(Shishi *
handle
handle
: Shishi library handle create by
shishi_init()
Description:
Get filename for default X.509 certificate.
Return value:
Returns the default X.509 client certificate filename
used in the library. The certificate is used during TLS
connections with the KDC to authenticate the client. The string is
not a copy, so don’t modify or deallocate it.
shishi_x509key_default_file_guess
Function:
char *
shishi_x509key_default_file_guess
(Shishi *
handle
handle
: Shishi library handle create by
shishi_init()
Description:
Guesses the default X.509 client key filename; it is
/.shishi/client.key.
Return value:
Returns default X.509 client key filename as
a string that has to be deallocated with
free()
by the caller.
shishi_x509key_default_file_set
Function:
void
shishi_x509key_default_file_set
(Shishi *
handle
, const char *
x509keyfile
handle
: Shishi library handle create by
shishi_init()
x509keyfile
: string with new default x509 client key file name, or
NULL to reset to default.
Description:
Set the default X.509 client key filename used in the library. The
key is used during TLS connections with the KDC to authenticate the
client. The string is copied into the library, so you can dispose
of the variable immediately after calling this function.
shishi_x509key_default_file
Function:
const char *
shishi_x509key_default_file
(Shishi *
handle
handle
: Shishi library handle create by
shishi_init()
Description:
Get filename for default X.509 key.
Return value:
Returns the default X.509 client key filename
used in the library. The key is used during TLS
connections with the KDC to authenticate the client. The string is
not a copy, so don’t modify or deallocate it.
Next:
ASN.1 Functions
, Previous:
X.509 Functions
, Up:
Programming Manual
Contents
][
Index
5.15 Utility Functions
shishi_realm_default_guess
Function:
char *
shishi_realm_default_guess
()
Description:
Guesses a realm based on
getdomainname()
, which really responds
with a NIS/YP domain, but if set properly, it might be a good
first guess. If this NIS query fails, call
gethostname()
and on its failure, fall back to returning the artificial
string "could-not-guess-default-realm".
Note that the hostname is not trimmed off of the string returned
by
gethostname()
, thus pretending the local host name is a valid
realm name. The resulting corner case could merit a check that
the suggested realm is distinct from the fully qualifies host,
and if not, simply strip the host name from the returned string
before it is used in an application. One reason for sticking
with the present behaviour, is that some systems respond with
a non-qualified host name as reply from
gethostname()
Return value:
Returns a guessed realm for the running host,
containing a string that has to be deallocated with
free()
by the caller.
shishi_realm_default
Function:
const char *
shishi_realm_default
(Shishi *
handle
handle
: Shishi library handle created by
shishi_init()
Description:
Determines name of default realm, i.e., the name of whatever
realm the library will use whenever an explicit realm is not
stated during a library call.
Return value:
Returns the default realm in use by the library.
Not a copy, so do not modify or deallocate the returned string.
shishi_realm_default_set
Function:
void
shishi_realm_default_set
(Shishi *
handle
, const char *
realm
handle
: Shishi library handle created by
shishi_init()
realm
: String stating a new default realm name, or
NULL
Description:
Sets the default realm used by the library; or, with
realm
set to
NULL
, resets the library realm setting to that name
selected by configuration for default value.
The string is copied into the library, so you can dispose of
the content in
realm
immediately after calling this function.
shishi_realm_for_server_file
Function:
char *
shishi_realm_for_server_file
(Shishi *
handle
, char *
server
handle
: Shishi library handle created by
shishi_init()
server
: Hostname to determine realm for.
Description:
Finds the realm applicable to a host
server
, using the
standard configuration file.
Return value:
Returns realm for host, or
NULL
if not known.
shishi_realm_for_server_dns
Function:
char *
shishi_realm_for_server_dns
(Shishi *
handle
, char *
server
handle
: Shishi library handle created by
shishi_init()
server
: Hostname to find realm for.
Description:
Finds the realm for a host
server
using DNS lookup, as is
prescribed in "draft-ietf-krb-wg-krb-dns-locate-03.txt".
Since DNS lookup can be spoofed, relying on the realm information
may result in a redirection attack. In a single-realm scenario,
this only achieves a denial of service, but with trust across
multiple realms the attack may redirect you to a compromised realm.
For this reason, Shishi prints a warning, suggesting that the user
should instead add a proper ’server-realm’ configuration token.
To illustrate the DNS information used, here is an extract from a
zone file for the domain ASDF.COM:
_kerberos.asdf.com. IN TXT "ASDF.COM"
_kerberos.mrkserver.asdf.com. IN TXT "MARKETING.ASDF.COM"
_kerberos.salesserver.asdf.com. IN TXT "SALES.ASDF.COM"
Let us suppose that in this case, a client wishes to use a service
on the host "foo.asdf.com". It would first query for
_kerberos.foo.asdf.com. IN TXT
Finding no match, it would then query for
_kerberos.asdf.com. IN TXT
With the resource records stated above, the latter query returns
a positive answer.
Return value:
Returns realm for the indicated host, or
NULL
if no relevant TXT record could be found.
shishi_realm_for_server
Function:
char *
shishi_realm_for_server
(Shishi *
handle
, char *
server
handle
: Shishi library handle created by
shishi_init()
server
: Hostname to find realm for.
Description:
Finds a realm for the host
server
, using various methods.
Currently this includes static configuration files, using
the library call
shishi_realm_for_server_file()
, and DNS
lookup using
shishi_realm_for_server_dns()
. They are
attempted in the stated order. See the documentation of
either function for more information.
Return value:
Returns realm for the indicated host, or
NULL
if nothing is known about
server
shishi_principal_default_guess
Function:
char *
shishi_principal_default_guess
()
Description:
Guesses the principal name for the user, looking at environment
variables SHISHI_USER, USER and LOGNAME, or if that fails, returns
the string "user".
Return value:
Returns guessed default principal for user as a
string that has to be deallocated by the caller with
free()
shishi_principal_default
Function:
const char *
shishi_principal_default
(Shishi *
handle
handle
: Shishi library handle created by
shishi_init()
Description:
The default principal name is the name in the environment variable
USER, or LOGNAME for some systems, but it can be overridden by
specifying the environment variable SHISHI_USER.
Return value:
Returns the default principal name used by the
library. (Not a copy of it, so don’t modify or deallocate it.)
shishi_principal_default_set
Function:
void
shishi_principal_default_set
(Shishi *
handle
, const char *
principal
handle
: Shishi library handle created by
shishi_init()
principal
: string with new default principal name, or NULL to
reset to default.
Description:
Set the default principal used by the library. The string is copied
into the library, so you can dispose of the variable immediately
after calling this function.
shishi_parse_name
Function:
int
shishi_parse_name
(Shishi *
handle
, const char *
name
, char **
principal
, char **
realm
handle
: Shishi library handle created by
shishi_init()
name
: input principal name string, e.g. imap/mail.gnu.org\
GNU
.ORG.
principal
: newly allocated output string with principal name.
realm
: newly allocated output string with realm name.
Description:
Split principal name (e.g., "simon\
JOSEFSSON
.ORG") into two
newly allocated strings, the
principal
("simon"), and the
realm
("JOSEFSSON.ORG"). If there is no realm part in
name
realm
is set
to NULL.
Return value:
Returns SHISHI_INVALID_PRINCIPAL_NAME if
name
is NULL
or ends with the escape character "\", and SHISHI_OK if
successful.
shishi_principal_name
Function:
int
shishi_principal_name
(Shishi *
handle
Shishi_asn1
namenode
, const char *
namefield
, char **
out
size_t
outlen
handle
: Shishi library handle created by
shishi_init()
namenode
: ASN.1 structure with principal in
namefield
namefield
: name of field in
namenode
containing principal name.
out
: pointer to newly allocated, null terminated, string containing
principal name. May be
NULL
(to only populate
outlen
).
outlen
: pointer to length of
out
on output, excluding terminating
null. May be
NULL
(to only populate
out
).
Description:
Represent principal name in ASN.1 structure as null-terminated
string. The string is allocated by this function, and it is the
responsibility of the caller to deallocate it. Note that the
output length
outlen
does not include the terminating null.
Return value:
Returns SHISHI_OK if successful.
shishi_principal_name_realm
Function:
int
shishi_principal_name_realm
(Shishi *
handle
Shishi_asn1
namenode
, const char *
namefield
Shishi_asn1
realmnode
, const char *
realmfield
, char **
out
size_t
outlen
handle
: Shishi library handle created by
shishi_init()
namenode
: ASN.1 structure with principal name in
namefield
namefield
: name of field in
namenode
containing principal name.
realmnode
: ASN.1 structure with principal realm in
realmfield
realmfield
: name of field in
realmnode
containing principal realm.
out
: pointer to newly allocated null terminated string containing
principal name. May be
NULL
(to only populate
outlen
).
outlen
: pointer to length of
out
on output, excluding terminating
null. May be
NULL
(to only populate
out
).
Description:
Represent principal name and realm in ASN.1 structure as
null-terminated string. The string is allocated by this function.
It is the responsibility of the caller to deallocate it. Note
that the output length
outlen
does not include the terminating
null character.
Return value:
Returns SHISHI_OK if successful.
shishi_principal_name_set
Function:
int
shishi_principal_name_set
(Shishi *
handle
Shishi_asn1
namenode
, const char *
namefield
Shishi_name_type
name_type
, const char *
name
[]
handle
: shishi handle as allocated by
shishi_init()
namenode
: ASN.1 structure with principal in
namefield
namefield
: name of field in
namenode
containing principal name.
name_type
: type of principal, see Shishi_name_type, usually
SHISHI_NT_UNKNOWN.
name
: null-terminated input array with principal name.
Description:
Set the given principal name field to the given name.
Return value:
Returns SHISHI_OK if successful.
shishi_principal_set
Function:
int
shishi_principal_set
(Shishi *
handle
Shishi_asn1
namenode
, const char *
namefield
, const char *
name
handle
: shishi handle as allocated by
shishi_init()
namenode
: ASN.1 structure with principal in
namefield
namefield
: name of field in
namenode
containing principal name.
name
: null-terminated string with principal name in RFC 1964 form.
Description:
Set principal name field in an ASN.1 structure to the given name.
Return value:
Returns SHISHI_OK if successful.
shishi_derive_default_salt
Function:
int
shishi_derive_default_salt
(Shishi *
handle
, const char *
name
, char **
salt
handle
: shishi handle as allocated by
shishi_init()
name
: principal name of user.
salt
: output variable with newly allocated salt string.
Description:
Derive the default salt from a principal. The default salt is the
concatenation of the decoded realm and the principal.
Return value:
Return SHISHI_OK if successful.
shishi_server_for_local_service
Function:
char *
shishi_server_for_local_service
(Shishi *
handle
, const char *
service
handle
: shishi handle as allocated by
shishi_init()
service
: null terminated string with name of service, e.g., "host".
Description:
Construct a service principal (e.g., "imap/yxa.extuno.com") based
on supplied service name (i.e., "imap") and the system’s hostname as
returned by
hostname()
(i.e., "yxa.extundo.com"). The string must
be deallocated by the caller.
Return value:
Return newly allocated service name string.
shishi_authorize_strcmp
Function:
int
shishi_authorize_strcmp
(Shishi *
handle
, const char *
principal
, const char *
authzname
handle
: shishi handle allocated by
shishi_init()
principal
: string with desired principal name.
authzname
: authorization name.
Description:
Authorization of
authzname
against desired
principal
according to "basic" authentication, i.e., testing for
identical strings.
Return value:
Returns 1 if
authzname
is authorized for services
by the encrypted principal, and 0 otherwise.
shishi_authorize_k5login
Function:
int
shishi_authorize_k5login
(Shishi *
handle
, const char *
principal
, const char *
authzname
handle
: shishi handle allocated by
shishi_init()
principal
: string with desired principal name and realm.
authzname
: authorization name.
Description:
Authorization of
authzname
against desired
principal
in accordance with the MIT/Heimdal authorization method.
Return value:
Returns 1 if
authzname
is authorized for services
by
principal
, and returns 0 otherwise.
shishi_authorization_parse
Function:
int
shishi_authorization_parse
(const char *
authorization
authorization
: name of authorization type, "basic" or "k5login".
Description:
Parse authorization type name.
Return value:
Returns authorization type corresponding to a string.
shishi_authorized_p
Function:
int
shishi_authorized_p
(Shishi *
handle
Shishi_tkt
tkt
, const char *
authzname
handle
: shishi handle allocated by
shishi_init()
tkt
: input variable with ticket info.
authzname
: authorization name.
Description:
Simplistic authorization of
authzname
against encrypted client
principal name inside ticket. For "basic" authentication type,
the principal name must coincide with
authzname
. The "k5login"
authentication type attempts the MIT/Heimdal method of parsing
the file "~/.k5login" for additional equivalence names.
Return value:
Returns 1 if
authzname
is authorized for services
by the encrypted principal, and 0 otherwise.
shishi_generalize_time
Function:
const char *
shishi_generalize_time
(Shishi *
handle
time_t
handle
: Shishi handle as allocated by
shishi_init()
: C time to convert.
Description:
Converts C time
to a KerberosTime string representation.
The returned string must not be deallocated by the caller.
Return value:
Returns a KerberosTime formatted string
corresponding to the input parameter.
shishi_generalize_now
Function:
const char *
shishi_generalize_now
(Shishi *
handle
handle
: Shishi handle as allocated by
shishi_init()
Description:
Converts the current time to a KerberosTime string.
The returned string must not be deallocated by the caller.
Return value:
Returns a KerberosTime formatted string
corresponding to the current time.
shishi_generalize_ctime
Function:
time_t
shishi_generalize_ctime
(Shishi *
handle
, const char *
handle
: Shishi handle as allocated by
shishi_init()
: KerberosTime string to convert.
Description:
Converts a KerberosTime formatted string in
to
integral C time representation.
Return value:
Returns the C time corresponding to the input
argument.
shishi_time
Function:
int
shishi_time
(Shishi *
handle
Shishi_asn1
node
, const char *
field
, char **
handle
: Shishi handle as allocated by
shishi_init()
node
: ASN.1 structure to get time from.
field
: Name of the field in the ASN.1 node carrying time.
: Returned pointer to an allocated char array containing
a null-terminated time string.
Description:
Extracts time information from an ASN.1 structure,
and to be precise, does so from the named field
field
within the structure
node
Return value:
Returns
SHISHI_OK
if successful, or an error.
shishi_ctime
Function:
int
shishi_ctime
(Shishi *
handle
Shishi_asn1
node
, const char *
field
time_t
handle
: Shishi handle as allocated by
shishi_init()
node
: ASN.1 structure to read field from.
field
: Name of field in
node
to read.
: Pointer to a C-time valued integer, being updated with
the time value to be extracted.
Description:
Extracts time information from an ASN.1 structure
node
and from an arbitrary element
field
of that structure.
Return value:
Returns
SHISHI_OK
if successful,
SHISHI_ASN1_NO_ELEMENT
if the element does not exist,
SHISHI_ASN1_NO_VALUE
if the field has no value.
In all other cases,
SHISHI_ASN1_ERROR
is returned.
shishi_prompt_password_callback_set
Function:
void
shishi_prompt_password_callback_set
(Shishi *
handle
shishi_prompt_password_func
cb
handle
: shishi handle as allocated by
shishi_init()
cb
: function pointer to application password callback, a
shishi_prompt_password_func
type.
Description:
Set a callback function that will be used by
shishi_prompt_password()
to query the user for a password. The
function pointer can be retrieved using
shishi_prompt_password_callback_get()
The
cb
function should follow the
shishi_prompt_password_func
prototype:
int prompt_password (Shishi *
handle
, char **
const char *
format
, va_list
ap
);
If the function returns 0, the
variable should contain a newly
allocated string with the password read from the user.
shishi_prompt_password_callback_get
Function:
shishi_prompt_password_func
shishi_prompt_password_callback_get
(Shishi *
handle
handle
: shishi handle as allocated by
shishi_init()
Description:
Get the application password prompt function callback as set by
shishi_prompt_password_callback_set()
Returns:
Returns the callback, a
shishi_prompt_password_func
type,
or
NULL
shishi_prompt_password
Function:
int
shishi_prompt_password
(Shishi *
handle
, char **
, const char *
format
...
handle
: shishi handle as allocated by
shishi_init()
: pointer to newly allocated output string with read password.
format
: printf(3) style format string.
...
: printf(3) style arguments.
Description:
Format and print a prompt, and read a password from user. The
password is possibly converted (e.g., converted from Latin-1 to
UTF-8, or processed using Stringprep profile) following any
"stringprocess" keywords in configuration files.
Return value:
Returns SHISHI_OK iff successful.
shishi_resolv
Function:
Shishi_dns
shishi_resolv
(const char *
zone
uint16_t
querytype
zone
: Domain name of authentication zone, e.g. "EXAMPLE.ORG"
querytype
: Type of domain data to query for.
Description:
Queries the DNS resolver for data of type
querytype
about
the domain name
zone
. Currently, the types
SHISHI_DNS_TXT
and
SHISHI_DNS_SRV
are the only supported kinds.
After its use, the returned list should be deallocated by
a call to
shishi_resolv_free()
Return value:
Returns a linked list of DNS resource records,
or
NULL
if the query failed.
shishi_resolv_free
Function:
void
shishi_resolv_free
Shishi_dns
rrs
rrs
: List of DNS RRs as returned by
shishi_resolv()
Description:
Deallocates a list of DNS resource records returned by
a call to
shishi_resolv()
Next:
Error Handling
, Previous:
Utility Functions
, Up:
Programming Manual
Contents
][
Index
5.16 ASN.1 Functions
shishi_asn1_read_inline
Function:
int
shishi_asn1_read_inline
(Shishi *
handle
Shishi_asn1
node
, const char *
field
, char *
data
size_t
datalen
handle
: shishi handle as allocated by
shishi_init()
node
: ASN.1 variable to read field from.
field
: name of field in
node
to read.
data
: pre-allocated output buffer that will hold ASN.1 field data.
datalen
: on input, maximum size of output buffer,
on output, actual size of output buffer.
Description:
Extract data stored in a ASN.1 field into a fixed size buffer
allocated by caller.
Note that since it is difficult to predict the length of the field,
it is often better to use
shishi_asn1_read()
instead.
Return value:
Returns SHISHI_OK if successful,
SHISHI_ASN1_NO_ELEMENT if the element do not exist,
SHISHI_ASN1_NO_VALUE if the field has no value, ot
SHISHI_ASN1_ERROR otherwise.
shishi_asn1_read
Function:
int
shishi_asn1_read
(Shishi *
handle
Shishi_asn1
node
, const char *
field
, char **
data
size_t
datalen
handle
: shishi handle as allocated by
shishi_init()
node
: ASN.1 variable to read field from.
field
: name of field in
node
to read.
data
: newly allocated output buffer that will hold ASN.1 field data.
datalen
: actual size of output buffer.
Description:
Extract data stored in a ASN.1 field into a newly allocated buffer.
The buffer will always be zero terminated, even though
datalen
will not include the added zero.
Return value:
Returns SHISHI_OK if successful,
SHISHI_ASN1_NO_ELEMENT if the element do not exist,
SHISHI_ASN1_NO_VALUE if the field has no value, ot
SHISHI_ASN1_ERROR otherwise.
shishi_asn1_read_optional
Function:
int
shishi_asn1_read_optional
(Shishi *
handle
Shishi_asn1
node
, const char *
field
, char **
data
size_t
datalen
handle
: shishi handle as allocated by
shishi_init()
node
: ASN.1 variable to read field from.
field
: name of field in
node
to read.
data
: newly allocated output buffer that will hold ASN.1 field data.
datalen
: actual size of output buffer.
Description:
Extract data stored in a ASN.1 field into a newly allocated buffer.
If the field does not exist (i.e., SHISHI_ASN1_NO_ELEMENT), this
function set datalen to 0 and succeeds. Can be useful to read
ASN.1 fields which are marked OPTIONAL in the grammar, if you want
to avoid special error handling in your code.
Return value:
Returns SHISHI_OK if successful,
SHISHI_ASN1_NO_VALUE if the field has no value, ot
SHISHI_ASN1_ERROR otherwise.
shishi_asn1_done
Function:
void
shishi_asn1_done
(Shishi *
handle
Shishi_asn1
node
handle
: shishi handle as allocated by
shishi_init()
node
: ASN.1 node to deallocate.
Description:
Deallocate resources associated with ASN.1 structure. Note that
the node must not be used after this call.
shishi_asn1_pa_enc_ts_enc
Function:
Shishi_asn1
shishi_asn1_pa_enc_ts_enc
(Shishi *
handle
handle
: shishi handle as allocated by
shishi_init()
Description:
Create new ASN.1 structure for PA-ENC-TS-ENC.
Return value:
Returns ASN.1 structure.
shishi_asn1_encrypteddata
Function:
Shishi_asn1
shishi_asn1_encrypteddata
(Shishi *
handle
handle
: shishi handle as allocated by
shishi_init()
Description:
Create new ASN.1 structure for EncryptedData
Return value:
Returns ASN.1 structure.
shishi_asn1_padata
Function:
Shishi_asn1
shishi_asn1_padata
(Shishi *
handle
handle
: shishi handle as allocated by
shishi_init()
Description:
Create new ASN.1 structure for PA-DATA.
Return value:
Returns ASN.1 structure.
shishi_asn1_methoddata
Function:
Shishi_asn1
shishi_asn1_methoddata
(Shishi *
handle
handle
: shishi handle as allocated by
shishi_init()
Description:
Create new ASN.1 structure for METHOD-DATA.
Return value:
Returns ASN.1 structure.
shishi_asn1_etype_info
Function:
Shishi_asn1
shishi_asn1_etype_info
(Shishi *
handle
handle
: shishi handle as allocated by
shishi_init()
Description:
Create new ASN.1 structure for ETYPE-INFO.
Return value:
Returns ASN.1 structure.
shishi_asn1_etype_info2
Function:
Shishi_asn1
shishi_asn1_etype_info2
(Shishi *
handle
handle
: shishi handle as allocated by
shishi_init()
Description:
Create new ASN.1 structure for ETYPE-INFO2.
Return value:
Returns ASN.1 structure.
shishi_asn1_asreq
Function:
Shishi_asn1
shishi_asn1_asreq
(Shishi *
handle
handle
: shishi handle as allocated by
shishi_init()
Description:
Create new ASN.1 structure for AS-REQ.
Return value:
Returns ASN.1 structure.
shishi_asn1_asrep
Function:
Shishi_asn1
shishi_asn1_asrep
(Shishi *
handle
handle
: shishi handle as allocated by
shishi_init()
Description:
Create new ASN.1 structure for AS-REP.
Return value:
Returns ASN.1 structure.
shishi_asn1_tgsreq
Function:
Shishi_asn1
shishi_asn1_tgsreq
(Shishi *
handle
handle
: shishi handle as allocated by
shishi_init()
Description:
Create new ASN.1 structure for TGS-REQ.
Return value:
Returns ASN.1 structure.
shishi_asn1_tgsrep
Function:
Shishi_asn1
shishi_asn1_tgsrep
(Shishi *
handle
handle
: shishi handle as allocated by
shishi_init()
Description:
Create new ASN.1 structure for TGS-REP.
Return value:
Returns ASN.1 structure.
shishi_asn1_apreq
Function:
Shishi_asn1
shishi_asn1_apreq
(Shishi *
handle
handle
: shishi handle as allocated by
shishi_init()
Description:
Create new ASN.1 structure for AP-REQ.
Return value:
Returns ASN.1 structure.
shishi_asn1_aprep
Function:
Shishi_asn1
shishi_asn1_aprep
(Shishi *
handle
handle
: shishi handle as allocated by
shishi_init()
Description:
Create new ASN.1 structure for AP-REP.
Return value:
Returns ASN.1 structure.
shishi_asn1_encapreppart
Function:
Shishi_asn1
shishi_asn1_encapreppart
(Shishi *
handle
handle
: shishi handle as allocated by
shishi_init()
Description:
Create new ASN.1 structure for AP-REP.
Return value:
Returns ASN.1 structure.
shishi_asn1_ticket
Function:
Shishi_asn1
shishi_asn1_ticket
(Shishi *
handle
handle
: shishi handle as allocated by
shishi_init()
Description:
Create new ASN.1 structure for Ticket.
Return value:
Returns ASN.1 structure.
shishi_asn1_encticketpart
Function:
Shishi_asn1
shishi_asn1_encticketpart
(Shishi *
handle
handle
: shishi handle as allocated by
shishi_init()
Description:
Create new ASN.1 structure for EncTicketPart.
Return value:
Returns ASN.1 structure.
shishi_asn1_authenticator
Function:
Shishi_asn1
shishi_asn1_authenticator
(Shishi *
handle
handle
: shishi handle as allocated by
shishi_init()
Description:
Create new ASN.1 structure for Authenticator.
Return value:
Returns ASN.1 structure.
shishi_asn1_enckdcreppart
Function:
Shishi_asn1
shishi_asn1_enckdcreppart
(Shishi *
handle
handle
: shishi handle as allocated by
shishi_init()
Description:
Create new ASN.1 structure for EncKDCRepPart.
Return value:
Returns ASN.1 structure.
shishi_asn1_encasreppart
Function:
Shishi_asn1
shishi_asn1_encasreppart
(Shishi *
handle
handle
: shishi handle as allocated by
shishi_init()
Description:
Create new ASN.1 structure for EncASRepPart.
Return value:
Returns ASN.1 structure.
shishi_asn1_krberror
Function:
Shishi_asn1
shishi_asn1_krberror
(Shishi *
handle
handle
: shishi handle as allocated by
shishi_init()
Description:
Create new ASN.1 structure for KRB-ERROR.
Return value:
Returns ASN.1 structure.
shishi_asn1_krbsafe
Function:
Shishi_asn1
shishi_asn1_krbsafe
(Shishi *
handle
handle
: shishi handle as allocated by
shishi_init()
Description:
Create new ASN.1 structure for KRB-SAFE.
Return value:
Returns ASN.1 structure.
shishi_asn1_priv
Function:
Shishi_asn1
shishi_asn1_priv
(Shishi *
handle
handle
: shishi handle as allocated by
shishi_init()
Description:
Create new ASN.1 structure for KRB-PRIV.
Return value:
Returns ASN.1 structure.
shishi_asn1_encprivpart
Function:
Shishi_asn1
shishi_asn1_encprivpart
(Shishi *
handle
handle
: shishi handle as allocated by
shishi_init()
Description:
Create new ASN.1 structure for EncKrbPrivPart.
Return value:
Returns ASN.1 structure.
shishi_asn1_to_der_field
Function:
int
shishi_asn1_to_der_field
(Shishi *
handle
Shishi_asn1
node
, const char *
field
, char **
der
size_t
len
handle
: shishi handle as allocated by
shishi_init()
node
: ASN.1 data that have field to extract.
field
: name of field in
node
to extract.
der
: output array that holds DER encoding of
field
in
node
len
: output variable with length of
der
output array.
Description:
Extract newly allocated DER representation of specified ASN.1 field.
Return value:
Returns SHISHI_OK if successful, or SHISHI_ASN1_ERROR
if DER encoding fails (common reasons for this is that the ASN.1
is missing required values).
shishi_asn1_to_der
Function:
int
shishi_asn1_to_der
(Shishi *
handle
Shishi_asn1
node
, char **
der
size_t
len
handle
: shishi handle as allocated by
shishi_init()
node
: ASN.1 data to convert to DER.
der
: output array that holds DER encoding of
node
len
: output variable with length of
der
output array.
Description:
Extract newly allocated DER representation of specified ASN.1 data.
Return value:
Returns SHISHI_OK if successful, or SHISHI_ASN1_ERROR
if DER encoding fails (common reasons for this is that the ASN.1
is missing required values).
shishi_asn1_msgtype
Function:
Shishi_msgtype
shishi_asn1_msgtype
(Shishi *
handle
Shishi_asn1
node
handle
: shishi handle as allocated by
shishi_init()
node
: ASN.1 type to get msg type for.
Description:
Determine msg-type of ASN.1 type of a packet. Currently this uses
the msg-type field instead of the APPLICATION tag, but this may be
changed in the future.
Return value:
Returns msg-type of ASN.1 type, 0 on failure.
shishi_der_msgtype
Function:
Shishi_msgtype
shishi_der_msgtype
(Shishi *
handle
, const char *
der
size_t
derlen
handle
: shishi handle as allocated by
shishi_init()
der
: input character array with DER encoding.
derlen
: length of input character array with DER encoding.
Description:
Determine msg-type of DER coded data of a packet.
Return value:
Returns msg-type of DER data, 0 on failure.
shishi_der2asn1
Function:
Shishi_asn1
shishi_der2asn1
(Shishi *
handle
, const char *
der
size_t
derlen
handle
: shishi handle as allocated by
shishi_init()
der
: input character array with DER encoding.
derlen
: length of input character array with DER encoding.
Description:
Convert arbitrary DER data of a packet to a ASN.1 type.
Return value:
Returns newly allocate ASN.1 corresponding to DER
data, or
NULL
on failure.
shishi_der2asn1_padata
Function:
Shishi_asn1
shishi_der2asn1_padata
(Shishi *
handle
, const char *
der
size_t
derlen
handle
: shishi handle as allocated by
shishi_init()
der
: input character array with DER encoding.
derlen
: length of input character array with DER encoding.
Description:
Decode DER encoding of PA-DATA and create a ASN.1 structure.
Return value:
Returns ASN.1 structure corresponding to DER data.
shishi_der2asn1_methoddata
Function:
Shishi_asn1
shishi_der2asn1_methoddata
(Shishi *
handle
, const char *
der
size_t
derlen
handle
: shishi handle as allocated by
shishi_init()
der
: input character array with DER encoding.
derlen
: length of input character array with DER encoding.
Description:
Decode DER encoding of METHOD-DATA and create a ASN.1 structure.
Return value:
Returns ASN.1 structure corresponding to DER data.
shishi_der2asn1_etype_info
Function:
Shishi_asn1
shishi_der2asn1_etype_info
(Shishi *
handle
, const char *
der
size_t
derlen
handle
: shishi handle as allocated by
shishi_init()
der
: input character array with DER encoding.
derlen
: length of input character array with DER encoding.
Description:
Decode DER encoding of ETYPE-INFO and create a ASN.1 structure.
Return value:
Returns ASN.1 structure corresponding to DER data.
shishi_der2asn1_etype_info2
Function:
Shishi_asn1
shishi_der2asn1_etype_info2
(Shishi *
handle
, const char *
der
size_t
derlen
handle
: shishi handle as allocated by
shishi_init()
der
: input character array with DER encoding.
derlen
: length of input character array with DER encoding.
Description:
Decode DER encoding of ETYPE-INFO2 and create a ASN.1 structure.
Return value:
Returns ASN.1 structure corresponding to DER data.
shishi_der2asn1_ticket
Function:
Shishi_asn1
shishi_der2asn1_ticket
(Shishi *
handle
, const char *
der
size_t
derlen
handle
: shishi handle as allocated by
shishi_init()
der
: input character array with DER encoding.
derlen
: length of input character array with DER encoding.
Description:
Decode DER encoding of Ticket and create a ASN.1 structure.
Return value:
Returns ASN.1 structure corresponding to DER data.
shishi_der2asn1_encticketpart
Function:
Shishi_asn1
shishi_der2asn1_encticketpart
(Shishi *
handle
, const char *
der
size_t
derlen
handle
: shishi handle as allocated by
shishi_init()
der
: input character array with DER encoding.
derlen
: length of input character array with DER encoding.
Description:
Decode DER encoding of EncTicketPart and create a ASN.1 structure.
Return value:
Returns ASN.1 structure corresponding to DER data.
shishi_der2asn1_asreq
Function:
Shishi_asn1
shishi_der2asn1_asreq
(Shishi *
handle
, const char *
der
size_t
derlen
handle
: shishi handle as allocated by
shishi_init()
der
: input character array with DER encoding.
derlen
: length of input character array with DER encoding.
Description:
Decode DER encoding of AS-REQ and create a ASN.1 structure.
Return value:
Returns ASN.1 structure corresponding to DER data.
shishi_der2asn1_tgsreq
Function:
Shishi_asn1
shishi_der2asn1_tgsreq
(Shishi *
handle
, const char *
der
size_t
derlen
handle
: shishi handle as allocated by
shishi_init()
der
: input character array with DER encoding.
derlen
: length of input character array with DER encoding.
Description:
Decode DER encoding of TGS-REQ and create a ASN.1 structure.
Return value:
Returns ASN.1 structure corresponding to DER data.
shishi_der2asn1_asrep
Function:
Shishi_asn1
shishi_der2asn1_asrep
(Shishi *
handle
, const char *
der
size_t
derlen
handle
: shishi handle as allocated by
shishi_init()
der
: input character array with DER encoding.
derlen
: length of input character array with DER encoding.
Description:
Decode DER encoding of AS-REP and create a ASN.1 structure.
Return value:
Returns ASN.1 structure corresponding to DER data.
shishi_der2asn1_tgsrep
Function:
Shishi_asn1
shishi_der2asn1_tgsrep
(Shishi *
handle
, const char *
der
size_t
derlen
handle
: shishi handle as allocated by
shishi_init()
der
: input character array with DER encoding.
derlen
: length of input character array with DER encoding.
Description:
Decode DER encoding of TGS-REP and create a ASN.1 structure.
Return value:
Returns ASN.1 structure corresponding to DER data.
shishi_der2asn1_kdcrep
Function:
Shishi_asn1
shishi_der2asn1_kdcrep
(Shishi *
handle
, const char *
der
size_t
derlen
handle
: shishi handle as allocated by
shishi_init()
der
: input character array with DER encoding.
derlen
: length of input character array with DER encoding.
Description:
Decode DER encoding of KDC-REP and create a ASN.1 structure.
Return value:
Returns ASN.1 structure corresponding to DER data.
shishi_der2asn1_encasreppart
Function:
Shishi_asn1
shishi_der2asn1_encasreppart
(Shishi *
handle
, const char *
der
size_t
derlen
handle
: shishi handle as allocated by
shishi_init()
der
: input character array with DER encoding.
derlen
: length of input character array with DER encoding.
Description:
Decode DER encoding of EncASRepPart and create a ASN.1 structure.
Return value:
Returns ASN.1 structure corresponding to DER data.
shishi_der2asn1_enctgsreppart
Function:
Shishi_asn1
shishi_der2asn1_enctgsreppart
(Shishi *
handle
, const char *
der
size_t
derlen
handle
: shishi handle as allocated by
shishi_init()
der
: input character array with DER encoding.
derlen
: length of input character array with DER encoding.
Description:
Decode DER encoding of EncTGSRepPart and create a ASN.1 structure.
Return value:
Returns ASN.1 structure corresponding to DER data.
shishi_der2asn1_enckdcreppart
Function:
Shishi_asn1
shishi_der2asn1_enckdcreppart
(Shishi *
handle
, const char *
der
size_t
derlen
handle
: shishi handle as allocated by
shishi_init()
der
: input character array with DER encoding.
derlen
: length of input character array with DER encoding.
Description:
Decode DER encoding of EncKDCRepPart and create a ASN.1 structure.
Return value:
Returns ASN.1 structure corresponding to DER data.
shishi_der2asn1_authenticator
Function:
Shishi_asn1
shishi_der2asn1_authenticator
(Shishi *
handle
, const char *
der
size_t
derlen
handle
: shishi handle as allocated by
shishi_init()
der
: input character array with DER encoding.
derlen
: length of input character array with DER encoding.
Description:
Decode DER encoding of Authenticator and create a ASN.1 structure.
Return value:
Returns ASN.1 structure corresponding to DER data.
shishi_der2asn1_krberror
Function:
Shishi_asn1
shishi_der2asn1_krberror
(Shishi *
handle
, const char *
der
size_t
derlen
handle
: shishi handle as allocated by
shishi_init()
der
: input character array with DER encoding.
derlen
: length of input character array with DER encoding.
Description:
Decode DER encoding of KRB-ERROR and create a ASN.1 structure.
Return value:
Returns ASN.1 structure corresponding to DER data.
shishi_der2asn1_krbsafe
Function:
Shishi_asn1
shishi_der2asn1_krbsafe
(Shishi *
handle
, const char *
der
size_t
derlen
handle
: shishi handle as allocated by
shishi_init()
der
: input character array with DER encoding.
derlen
: length of input character array with DER encoding.
Description:
Decode DER encoding of KRB-SAFE and create a ASN.1 structure.
Return value:
Returns ASN.1 structure corresponding to DER data.
shishi_der2asn1_priv
Function:
Shishi_asn1
shishi_der2asn1_priv
(Shishi *
handle
, const char *
der
size_t
derlen
handle
: shishi handle as allocated by
shishi_init()
der
: input character array with DER encoding.
derlen
: length of input character array with DER encoding.
Description:
Decode DER encoding of KRB-PRIV and create a ASN.1 structure.
Return value:
Returns ASN.1 structure corresponding to DER data.
shishi_der2asn1_encprivpart
Function:
Shishi_asn1
shishi_der2asn1_encprivpart
(Shishi *
handle
, const char *
der
size_t
derlen
handle
: shishi handle as allocated by
shishi_init()
der
: input character array with DER encoding.
derlen
: length of input character array with DER encoding.
Description:
Decode DER encoding of EncKrbPrivPart and create a ASN.1 structure.
Return value:
Returns ASN.1 structure corresponding to DER data.
shishi_der2asn1_apreq
Function:
Shishi_asn1
shishi_der2asn1_apreq
(Shishi *
handle
, const char *
der
size_t
derlen
handle
: shishi handle as allocated by
shishi_init()
der
: input character array with DER encoding.
derlen
: length of input character array with DER encoding.
Description:
Decode DER encoding of AP-REQ and create a ASN.1 structure.
Return value:
Returns ASN.1 structure corresponding to DER data.
shishi_der2asn1_aprep
Function:
Shishi_asn1
shishi_der2asn1_aprep
(Shishi *
handle
, const char *
der
size_t
derlen
handle
: shishi handle as allocated by
shishi_init()
der
: input character array with DER encoding.
derlen
: length of input character array with DER encoding.
Description:
Decode DER encoding of AP-REP and create a ASN.1 structure.
Return value:
Returns ASN.1 structure corresponding to DER data.
shishi_der2asn1_encapreppart
Function:
Shishi_asn1
shishi_der2asn1_encapreppart
(Shishi *
handle
, const char *
der
size_t
derlen
handle
: shishi handle as allocated by
shishi_init()
der
: input character array with DER encoding.
derlen
: length of input character array with DER encoding.
Description:
Decode DER encoding of EncAPRepPart and create a ASN.1 structure.
Return value:
Returns ASN.1 structure corresponding to DER data.
shishi_der2asn1_kdcreq
Function:
Shishi_asn1
shishi_der2asn1_kdcreq
(Shishi *
handle
, const char *
der
size_t
derlen
handle
: shishi handle as allocated by
shishi_init()
der
: input character array with DER encoding.
derlen
: length of input character array with DER encoding.
Description:
Decode DER encoding of AS-REQ, TGS-REQ or KDC-REQ and create a
ASN.1 structure.
Return value:
Returns ASN.1 structure corresponding to DER data.
shishi_asn1_print
Function:
void
shishi_asn1_print
(Shishi *
handle
Shishi_asn1
node
, FILE *
fh
handle
: shishi handle as allocated by
shishi_init()
node
: ASN.1 data that have field to extract.
fh
: file descriptor to print to, e.g. stdout.
Description:
Print ASN.1 structure in human readable form, typically for
debugging purposes.
Next:
Examples
, Previous:
ASN.1 Functions
, Up:
Programming Manual
Contents
][
Index
5.17 Error Handling
Most functions in ‘Libshishi’ are returning an error if they fail.
For this reason, the application should always catch the error
condition and take appropriate measures, for example by releasing the
resources and passing the error up to the caller, or by displaying a
descriptive message to the user and cancelling the operation.
Some error values do not indicate a system error or an error in the
operation, but the result of an operation that failed properly.
Error Values
A list of all error values used.
Error Functions
Error handling related functions.
Next:
Error Functions
, Up:
Error Handling
Contents
][
Index
5.17.1 Error Values
Errors are returned as an
int
. Except for the SHISHI_OK case,
an application should always use the constants instead of their
numeric value. Applications are encouraged to use the constants even
for SHISHI_OK as it improves readability. Possible values are:
SHISHI_OK
This value indicates success. The value of this error is guaranteed
to always be
so you may use it in boolean constructs.
SHISHI_ASN1_ERROR
Error in ASN.1 function. (corrupt data?)
SHISHI_FOPEN_ERROR
Could not open file.
SHISHI_IO_ERROR
File input/output error.
SHISHI_MALLOC_ERROR
Memory allocation error in shishi library.
SHISHI_BASE64_ERROR
Base64 encoding or decoding failed. Data corrupt?
SHISHI_REALM_MISMATCH
Client realm value differ between request and reply.
SHISHI_CNAME_MISMATCH
Client name value differ between request and reply.
SHISHI_NONCE_MISMATCH
Replay protection value (nonce) differ between request and reply.
SHISHI_TGSREP_BAD_KEYTYPE
Incorrect key type used in TGS reply.
SHISHI_KDCREP_BAD_KEYTYPE
Incorrect key type used in reply from KDC.
SHISHI_APREP_BAD_KEYTYPE
Incorrect key type used in AP reply.
SHISHI_APREP_VERIFY_FAILED
Failed verification of AP reply.
SHISHI_APREQ_BAD_KEYTYPE
Incorrect key type used in AP request.
SHISHI_TOO_SMALL_BUFFER
Provided buffer was too small.
SHISHI_DERIVEDKEY_TOO_SMALL
Derived key material is too short to be applicable.
SHISHI_KEY_TOO_LARGE
The key is too large to be usable.
SHISHI_CRYPTO_ERROR
Low-level cryptographic primitive failed. This usually indicates bad password or data corruption.
SHISHI_CRYPTO_INTERNAL_ERROR
Internal error in low-level crypto routines.
SHISHI_SOCKET_ERROR
The system call socket() failed. This usually indicates that your system does not support the socket type.
SHISHI_BIND_ERROR
The system call bind() failed. This usually indicates insufficient permissions.
SHISHI_SENDTO_ERROR
The system call sendto() failed.
SHISHI_RECVFROM_ERROR
Error receiving data from server.
SHISHI_CLOSE_ERROR
The system call close() failed.
SHISHI_KDC_TIMEOUT
Timed out talking to KDC. This usually indicates a network or KDC address problem.
SHISHI_KDC_NOT_KNOWN_FOR_REALM
No KDC known for given realm.
SHISHI_TTY_ERROR
No TTY assigned to process.
SHISHI_GOT_KRBERROR
Server replied to the request with an error message.
SHISHI_HANDLE_ERROR
Failure to use handle. Missing handle, or misconfigured.
SHISHI_INVALID_TKTS
Ticket set not initialized. This usually indicates an internal application error.
SHISHI_TICKET_BAD_KEYTYPE
Key type used to encrypt ticket doesn’t match provided key. This usually indicates an internal application error.
SHISHI_INVALID_KEY
Reference to invalid encryption key.
SHISHI_APREQ_DECRYPT_FAILED
Could not decrypt AP-REQ using provided key. This usually indicates an internal application error.
SHISHI_TICKET_DECRYPT_FAILED
Could not decrypt Ticket using provided key. This usually indicates an internal application error.
SHISHI_INVALID_TICKET
Invalid ticked passed in call.
SHISHI_OUT_OF_RANGE
Argument lies outside of valid range.
SHISHI_ASN1_NO_ELEMENT
The ASN.1 structure does not contain the indicated element.
SHISHI_SAFE_BAD_KEYTYPE
Attempted access to non-existent key type.
SHISHI_SAFE_VERIFY_FAILED
Verification failed on either side.
SHISHI_PKCS5_INVALID_PRF
Invalid PKCS5 descriptor.
SHISHI_PKCS5_INVALID_ITERATION_COUNT
Invalid claim of iteration count in PKCS5 descriptor.
SHISHI_PKCS5_INVALID_DERIVED_KEY_LENGTH
Derived key length is incorrect for PKCS5 descriptor.
SHISHI_PKCS5_DERIVED_KEY_TOO_LONG
Derived key is too long for PKCS5 descriptor.
SHISHI_INVALID_PRINCIPAL_NAME
Principal name syntax error.
SHISHI_INVALID_ARGUMENT
Invalid argument passed in call. Wrong or unknown value.
SHISHI_ASN1_NO_VALUE
The indicated ASN.1 element does not carry a value.
SHISHI_CONNECT_ERROR
Connection attempt failed. Try again, or check availability.
SHISHI_VERIFY_FAILED
Verification failed on either side.
SHISHI_PRIV_BAD_KEYTYPE
The private key uses an incompatible encryption type.
SHISHI_FILE_ERROR
The desired file could not be accessed. Check permissions.
SHISHI_ENCAPREPPART_BAD_KEYTYPE
The present AP reply specifies an inpermissible key type.
SHISHI_GETTIMEOFDAY_ERROR
A request for present time of day has failed. This is usually internal, but a valid time is imperative for us.
SHISHI_KEYTAB_ERROR
Failed to parse keytab file.
SHISHI_CCACHE_ERROR
Failed to parse credential cache file.
Previous:
Error Values
, Up:
Error Handling
Contents
][
Index
5.17.2 Error Functions
shishi_strerror
Function:
const char *
shishi_strerror
(int
err
err
: shishi error code.
Description:
Converts the return code in
err
to a human readable string.
Return value:
Returns a pointer to a statically allocated string
containing a description of the error with code
err
This string can be used to output a diagnostic message to the user.
shishi_error
Function:
const char *
shishi_error
(Shishi *
handle
handle
: shishi handle as allocated by
shishi_init()
Description:
Extracts detailed information on the most recently occurred
error condition. Note that memory is managed by the Shishi
library, so the returned string must not be deallocated.
Return value:
Returns a pointer to a string describing an error.
The string must not be deallocated by the caller.
shishi_error_clear
Function:
void
shishi_error_clear
(Shishi *
handle
handle
: shishi handle as allocated by
shishi_init()
Description:
Clears the internal error description. See
shishi_error()
on how to access the error string, and
shishi_error_set()
as well
as
shishi_error_printf()
on how to set the error string.
This function is mostly for Shishi’s internal use, but if you develop
an extension of Shishi, it may be useful to support the same error
handling infrastructure.
shishi_error_set
Function:
void
shishi_error_set
(Shishi *
handle
, const char *
errstr
handle
: shishi handle as allocated by
shishi_init()
errstr
: A null-terminated character string holding a description,
or
NULL
to clear the internal error string.
Description:
Sets the error description to the content of
errstr
. The
string is copied into the Shishi internal structure, so you can
deallocate any string passed to this function.
This function is mostly for Shishi’s internal use, but if you develop
an extension of Shishi, it may be useful to support the same error
handling infrastructure.
shishi_error_printf
Function:
void
shishi_error_printf
(Shishi *
handle
, const char *
format
...
handle
: shishi handle as allocated by
shishi_init()
format
: printf style format string.
...
: printf style arguments.
Description:
Sets the internal error description to a printf(3) formatted
string. This function is mostly for Shishi’s internal use, but if
you develop an extension of Shishi, it may be useful to support the
same infrastructure for error handling.
shishi_error_outputtype
Function:
int
shishi_error_outputtype
(Shishi *
handle
handle
: shishi handle as allocated by
shishi_init()
Description:
Reports the current output type used in message logging.
Return value:
Returns the output type.
SHISHI_OUTPUTTYPE_NULL
means no output.
SHISHI_OUTPUTTYPE_STDERR
and
SHISHI_OUTPUTTYPE_SYSLOG
direct text to the console, or to the
syslog system.
shishi_error_set_outputtype
Function:
void
shishi_error_set_outputtype
(Shishi *
handle
, int
type
handle
: shishi handle as allocated by
shishi_init()
type
: output type, of enum type
Shishi_outputtype
Description:
Sets the output type (
NULL
stderr
or
syslog
) used for information
and warning messages. Intended values are
SHISHI_OUTPUTTYPE_NULL
for no output at all,
SHISHI_OUTPUTTYPE_STDERR
for output to the
console, and
SHISHI_OUTPUTTYPE_SYSLOG
for syslog messaging.
The first value covers everything different from the latter two values.
shishi_info
Function:
void
shishi_info
(Shishi *
handle
, const char *
format
...
handle
: shishi handle as allocated by
shishi_init()
format
: printf style format string.
...
: printf style arguments.
Description:
Prints an informational message, composed from the arguments,
to the output stream set in
handle
shishi_warn
Function:
void
shishi_warn
(Shishi *
handle
, const char *
format
...
handle
: shishi handle as allocated by
shishi_init()
format
: printf style format string.
...
: printf style arguments.
Description:
Prints a warning, composed from the arguments, to the output
stream set in
handle
shishi_verbose
Function:
void
shishi_verbose
(Shishi *
handle
, const char *
format
...
handle
: shishi handle as allocated by
shishi_init()
format
: printf style format string.
...
: printf style arguments.
Description:
Prints a diagnostic message, composed from the arguments,
to the output stream set in
handle
. The current verbosity
setting determines whether the message is actually printed,
or is suppressed due to low significance.
Next:
Kerberos Database Functions
, Previous:
Error Handling
, Up:
Programming Manual
Contents
][
Index
5.18 Examples
This section will be extended to contain walk-throughs of example code
that demonstrate how ‘Shishi’ is used to write your own applications
that support Kerberos 5. The rest of the current section consists of
some crude hints for the example client/server applications that is
part of Shishi, taken from an email but saved here for lack of a
better place to put it.
There are two programs: ’client’ and ’server’ in src/.
The client output an AP-REQ, waits for an AP-REP, and then simply
reads data from stdin.
The server waits for an AP-REQ, parses it and prints an AP-REP, and
then read data from stdin.
Both programs accept a Kerberos server name as the first command line
argument. Your KDC must know this server, since the client tries to
get a ticket for it (first it gets a ticket granting ticket for the
default username), and you must write the key for the server into
/usr/local/etc/shishi.keys on the Shishi format, e.g.:
-----BEGIN SHISHI KEY-----
Keytype: 16 (des3-cbc-sha1-kd)
Principal: sample/latte.josefsson.org
Realm: JOSEFSSON.ORG
8W0VrQQBpxlACPQEqN91EHxbvFFo2ltt
-----END SHISHI KEY-----
You must extract the proper encryption key from the KDC in some way.
(This part will be easier when Shishi include a KDC, a basic one isn’t
far away, give me a week or to.)
The intention is that the data read, after the authentication phase,
should be protected using KRB_SAFE (see RFC) but I haven’t added this
yet.
Next:
Generic Security Service
, Previous:
Examples
, Up:
Programming Manual
Contents
][
Index
5.19 Kerberos Database Functions
Shisa is a separate and standalone library from Shishi
(see
Introduction to Shisa
). If you only wish to manipulate the
information stored in the Kerberos user database used by Shishi, you
do not need to link or use the Shishi library at all. However, you
may find it useful to combine the two libraries.
For two real world examples on using the Shisa library, refer to
src/shisa.c
(Shisa command line tool) and
src/kdc.c
(part of Shishid server).
Shisa uses two ‘
struct
’s to carry information. The first,
Shisa_principal
, is used to hold information about principals.
The struct does not contain pointers to strings etc, so the library
assumes the caller is responsible for allocating and deallocating the
struct itself. Each such struct is (uniquely) identified by the
combination of principal name and realm name.
struct Shisa_principal
int isdisabled;
uint32_t kvno;
time_t notusedbefore;
time_t lastinitialtgt; /* time of last initial request for a TGT */
time_t lastinitialrequest; /* time of last initial request */
time_t lasttgt; /* time of issue for the newest TGT used */
time_t lastrenewal; /* time of the last renewal */
time_t passwordexpire; /* time when the password will expire */
time_t accountexpire; /* time when the account will expire. */
};
typedef struct Shisa_principal Shisa_principal;
The second structure is called
Shisa_key
and hold information
about cryptographic keys. Because the struct contain pointers, and
the caller cannot know how many keys a principal have, the Shisa
library manages memory for the struct. The library allocate the
structs, and the pointers within them. The caller may deallocate
them, but it is recommended to use
shisa_key_free
or
shisa_keys_free
instead. Note that each principal may have
multiple keys.
struct Shisa_key
uint32_t kvno;
int32_t etype;
int priority;
char *key;
size_t keylen;
char *salt;
size_t saltlen;
char *str2keyparam;
size_t str2keyparamlen;
char *password;
};
typedef struct Shisa_key Shisa_key;
Shisa is typically initialized by calling
shisa_init
, and
deinitialized (when the application no longer need to use Shisa,
typically when it shuts down) by calling
shisa_done
, but here
are the complete (de)initialization interface functions.
shisa
Function:
Shisa *
shisa
()
Description:
Initializes the Shisa library. If this function fails, it may
print diagnostic errors to standard error.
Return value:
Returns a Shisa library handle, or
NULL
on error.
shisa_done
Function:
void
shisa_done
(Shisa *
dbh
dbh
: Shisa handle as allocated by
shisa()
Description:
Deallocates the shisa library handle. The handle must not be used
in calls to any shisa function after the completion of this call.
shisa_init
Function:
int
shisa_init
(Shisa **
dbh
dbh
: Returned pointer to a created Shisa library handle.
Description:
Creates a Shisa library handle, using
shisa()
, reading the system
configuration file from its default location. The path to the
default system configuration file is decided at compile time
sysconfdir
/shisa.conf).
The handle is allocated regardless of return value, the only
exception being
SHISA_INIT_ERROR
, which indicates a problem
in allocating the handle. Other error conditions arise while
reading a file.
Return value:
Returns
SHISA_OK
, or an error code. The value
SHISA_INIT_ERROR
indicates a failure to create the handle.
shisa_init_with_paths
Function:
int
shisa_init_with_paths
(Shisa **
dbh
, const char *
file
dbh
: Returned pointer to a created Shisa library handle.
file
: Filename of system configuration, or
NULL
Description:
Creates a Shisa library handle, using
shisa()
, but reading
the system configuration file at the location
file
, or at
the default location, should
file
be
NULL
. The path to
the default system configuration file is decided at compile
time (
sysconfdir
/shisa.conf).
The handle is allocated regardless of return value, the only
exception being
SHISA_INIT_ERROR
, which indicates a problem
in allocating the handle. Other error conditions arise while
reading a file.
Return value:
Returns
SHISA_OK
, or an error code. The value
SHISA_INIT_ERROR
indicates a failure to create the handle.
The default configuration file is typically read automatically by
calling
shisa_init
, but if you wish to manually access the
Shisa configuration file functions, here is the complete interface.
shisa_cfg_db
Function:
int
shisa_cfg_db
(Shisa *
dbh
, const char *
value
dbh
: Shisa library handle created by
shisa()
value
: String containing database definition.
Description:
Sets up and opens a new database. The syntax of the parameter
value
is "TYPE[ LOCATION[ PARAMETER]]", where TYPE is one of
the supported database types, typically "file".
The above substrings LOCATION and PARAMETER are optional strings
passed on verbatim to the database during initialization.
Neither TYPE nor LOCATION may contain embedded spaces,
but PARAMETER may do so.
Return value:
Returns
SHISA_OK
if a database was parsed and opened
successfully.
shisa_cfg
Function:
int
shisa_cfg
(Shisa *
dbh
, const char *
option
dbh
: Shisa library handle created by
shisa()
option
: String with options to prime the Shisa library.
Description:
Configures the Shisa library from the specification
option
This call expects a string declaration of the form "db=VALUE",
or "db VALUE". Here VALUE is the same declaration as used by
shisa_cfg_db()
, i.e., of the form "TYPE[ LOCATION[ PARAMETER]]".
The prefix "db", mandatory in
option
, makes
shisa_cfg()
suited
to a syntax with key-value pairs also in PARAMETER.
Return value:
Returns
SHISA_OK
if
option
is valid.
shisa_cfg_from_file
Function:
int
shisa_cfg_from_file
(Shisa *
dbh
, const char *
cfg
dbh
: Shisa library handle created by
shisa()
cfg
: File name where to read configuration.
Description:
Configures the Shisa library using a configuration file
located at
cfg
Return value:
Returns
SHISA_OK
if successful. Typically
returns
SHISA_CFG_NO_FILE
in response to a misnamed file.
shisa_cfg_default_systemfile
Function:
const char *
shisa_cfg_default_systemfile
(Shisa *
dbh
dbh
: Shisa library handle created by
shisa()
Description:
Fetches information on the installed configuration.
Return value:
Returns file name of the active
system configuration.
The core part of the Shisa interface follows. The typical procedure
is to use
shisa_principal_find
to verify that a specific
principal exists, and to extract some information about it, and then
use
shisa_keys_find
to get the cryptographic keys for the
principal, usually suppliying some hints as to which of all keys you
are interested in (e.g., key version number and encryption algorithm
number).
shisa_enumerate_realms
Function:
int
shisa_enumerate_realms
(Shisa *
dbh
, char ***
realms
size_t
nrealms
dbh
: Shisa library handle created by
shisa()
realms
: Returned pointer to a newly allocated array of also
allocated and null-terminated UTF-8 strings with realm names.
nrealms
: Pointer to a number which is updated with the number
of just allocated and returned realm strings.
Description:
Extracts a list of all realm names in backend, as null-terminated
UTF-8 strings. The caller is responsible for deallocating all
strings as well as the array *
realms
Return value:
Returns
SHISA_OK
on success, or an error code.
shisa_enumerate_principals
Function:
int
shisa_enumerate_principals
(Shisa *
dbh
, const char *
realm
, char ***
principals
size_t
nprincipals
dbh
: Shisa library handle created by
shisa()
realm
: Name of realm, as null-terminated UTF-8 string.
principals
: Returned pointer to newly allocated array of just
allocated null-terminated UTF-8 strings with principal names.
nprincipals
: Pointer to an integer updated with the number of just
allocated and returned principal names.
Description:
Extracts a list of all principal names in backend belonging to
the realm
realm
, as null-terminated UTF-8 strings. The caller
is responsible for deallocating all strings and the array
principals
Return value:
Returns
SHISA_OK
on success,
SHISA_NO_REALM
if the
specified realm does not exist, or an error code otherwise.
shisa_principal_find
Function:
int
shisa_principal_find
(Shisa *
dbh
, const char *
realm
, const char *
principal
Shisa_principal
ph
dbh
: Shisa library handle created by
shisa()
realm
: Name of the realm the principal belongs to.
principal
: Name of principal to get information about.
ph
: Pointer to a previously allocated principal structure
where information about the principal is to be stored.
Description:
Extracts information about given the PRINCIPAL@REALM pair
selected by
principal
and
realm
Return value:
Returns
SHISA_OK
if successful,
SHISA_NO_REALM
if
the indicated realm does not exist,
SHISA_NO_PRINCIPAL
if the
indicated principal does not exist, or an error code otherwise.
shisa_principal_update
Function:
int
shisa_principal_update
(Shisa *
dbh
, const char *
realm
, const char *
principal
, const
Shisa_principal
ph
dbh
: Shisa library handle created by
shisa()
realm
: Name of the realm the principal belongs to.
principal
: Name of principal to get information about.
ph
: Pointer to an existing principal structure containing
information to store in the database.
Description:
Modifies information stored about the given principal
PRINCIPAL@REALM. Note that it is usually a good idea to set
in
ph
only the fields that are to be updated.
It is generally suggested to first call
shisa_principal_find()
to get the current information, then to modify one field and
call
shisa_principal_update()
Modifying several values is not recommended in general,
as this will 1) overwrite any modifications made to other
fields between the two calls (by other processes) and
2) will cause all values to be written again, which may
generate more overhead.
Return value:
Returns
SHISA_OK
if successful,
SHISA_NO_REALM
if
the indicated realm does not exist,
SHISA_NO_PRINCIPAL
if the
indicated principal does not exist, or an error code otherwise.
shisa_principal_add
Function:
int
shisa_principal_add
(Shisa *
dbh
, const char *
realm
, const char *
principal
, const
Shisa_principal
ph
, const
Shisa_key
key
dbh
: Shisa library handle created by
shisa()
realm
: Name of the realm the principal belongs to.
principal
: Name of principal to add. When set to
NULL
only the realm
realm
is created.
ph
: Pointer to a principal structure with information to store
in the database.
key
: Pointer to a key structure with information to store in
the database.
Description:
Inserts the given information into the database for the
principal PRINCIPAL@REALM. In case
principal
is
NULL
the parameters
ph
and
key
are not used, so only the realm
is added to the database.
Return value:
Returns
SHISA_OK
if the information was
successfully added, or an error code otherwise.
shisa_principal_remove
Function:
int
shisa_principal_remove
(Shisa *
dbh
, const char *
realm
, const char *
principal
dbh
: Shisa library handle created by
shisa()
realm
: Name of the realm the principal belongs to.
principal
: Name of the principal to remove. Set to
NULL
only the realm
realm
is removed.
Description:
Removes all information stored in the database for the given
principal PRINCIPAL@REALM. When
principal
is
NULL
, then the
realm
realm
is itself removed, but this can only succeed if
the realm is already empty of principals.
Return value:
Returns
SHISA_OK
if successful, or an error code.
shisa_keys_find
Function:
int
shisa_keys_find
(Shisa *
dbh
, const char *
realm
, const char *
principal
, const
Shisa_key
hint
Shisa_key
***
keys
size_t
nkeys
dbh
: Shisa library handle created by
shisa()
realm
: Name of the realm the principal belongs to.
principal
: Name of the principal whose keys are examined.
hint
: Pointer to a Shisa key structure with hints on matching
criteria for relevant keys.
NULL
matches all keys.
keys
: Returned pointer to a newly allocated array of Shisa
key structures.
nkeys
: Pointer to an integer updated with the number of
allocated Shisa key structures in *
keys
Description:
Iterates through the set of keys belonging to PRINCIPAL@REALM,
as selected by
principal
and
realm
. Then extracts any keys
that match the criteria in
hint
Not all elements of
hint
need to be filled in. Set only
the fields you are interested in. For example, if you want
to extract all keys of etype 3, i.e., DES-CBC-MD5, then set
the field
key
->etype to 3, and all other fields to zero.
Return value:
Returns
SHISA_OK
if successful, or an error code.
shisa_key_add
Function:
int
shisa_key_add
(Shisa *
dbh
, const char *
realm
, const char *
principal
, const
Shisa_key
key
dbh
: Shisa library handle created by
shisa()
realm
: Name of the realm the principal belongs to.
principal
: Name of the principal to add a new key for.
key
: Pointer to a Shisa key structure with the new key.
Description:
Adds a complete key
key
to the database entry belonging
to the principal PRINCIPAL@REALM, as set by
principal
and
realm
Return value:
Returns
SHISA_OK
if successful, or an error code.
shisa_key_update
Function:
int
shisa_key_update
(Shisa *
dbh
, const char *
realm
, const char *
principal
, const
Shisa_key
oldkey
, const
Shisa_key
newkey
dbh
: Shisa library handle created by
shisa()
realm
: Name of the realm the principal belongs to.
principal
: Name of the principal needing an updated key.
oldkey
: Pointer to a Shisa key structure giving matching
criteria for locating the key to be updated.
newkey
: Pointer to a complete Shisa key structure, in which
all fields are used for the new key. Note that
oldkey
normally has far fewer fields filled-in.
Description:
Modifies data about a key stored in the database, a key
belonging to the principal selected by
principal
and
realm
First
oldkey
is used to locate the key to update, as does
shisa_keys_find()
. Then the found key is modified to carry
whatever information is stored in
newkey
Not all elements of
oldkey
need to be filled out, only
sufficiently many so as to uniquely identify the desired key.
For example, if you want to modify the information stored about
a unique key of etype 3, i.e., DES-CBC-MD5, then set the field
key
->etype to 3, leaving all other fields as zero.
Return value:
Returns
SHISA_OK
on success,
SHISA_NO_KEY
if no
key could be located,
SHISA_MULTIPLE_KEY_MATCH
if more
than a single key matched the given criteria, or an error code
otherwise.
shisa_key_remove
Function:
int
shisa_key_remove
(Shisa *
dbh
, const char *
realm
, const char *
principal
, const
Shisa_key
key
dbh
: Shisa library handle created by
shisa()
realm
: Name of the realm the principal belongs to.
principal
: Name of the principal whose key is to be removed.
key
: Pointer to a Shisa key structure with hints on matching
criteria for the key to select.
Description:
Removes from the Shisa database a key, matching the hints in
key
for the user PRINCIPAL@REALM. Not all elements of
key
need to be
filled in, only those relevant to locate the key uniquely.
For example, if you want to remove the only key of etype 3,
i.e., DES-CBC-MD5, then set the field
key
->etype to 3, and
all other fields to zero.
Return value:
Returns
SHISA_OK
on success,
SHISA_NO_KEY
if no key
could be located,
SHISA_MULTIPLE_KEY_MATCH
if more than one
key matched the given criteria, or an error code otherwise.
shisa_key_free
Function:
void
shisa_key_free
(Shisa *
dbh
Shisa_key
key
dbh
: Shisa library handle created by
shisa()
key
: Pointer to a Shisa key structure to deallocate.
Description:
Deallocates the fields of a Shisa key structure, as well as
the structure itself.
shisa_keys_free
Function:
void
shisa_keys_free
(Shisa *
dbh
Shisa_key
**
keys
size_t
nkeys
dbh
: Shisa library handle created by
shisa()
keys
: Pointer to an array of Shisa key structures.
nkeys
: Number of key elements in the array
keys
Description:
Deallocates each key element in the array
keys
of Shisa
database keys, using repeated calls to
shisa_key_free()
Error handling is similar to that for Shishi in general (see
Error Handling
), i.e., you invoke
shisa_strerror
on the integer
return value received by some function, if the return value is
non-zero. Below is the complete interface.
shisa_strerror
Function:
const char *
shisa_strerror
(int
err
err
: Shisa error code.
Description:
Explains verbally an error status
err
. The returned string
can be used to compose a diagnostic message of benefit to a user.
Return value:
Returns a pointer to a statically allocated string,
containing a description of the error given as input argument.
shisa_info
Function:
void
shisa_info
(Shisa *
dbh
, const char *
format
...
dbh
: Shisa library handle created by
shisa()
format
: printf style format string.
...
: printf style arguments.
Description:
Prints an informational message to standard error.
The text is composed from the arguments, like printf(3).
Previous:
Kerberos Database Functions
, Up:
Programming Manual
Contents
][
Index
5.20 Generic Security Service
As an alternative to the native Shishi programming API, it is possible
to program Shishi through the Generic Security Services (GSS) API.
The advantage of using GSS-API in your security application, instead
of the native Shishi API, is that it will be easier to port your
application between different Kerberos 5 implementations, and even
beyond Kerberos 5 to different security systems, that support GSS-API.
In the free software world, however, almost the only widely used
security system that supports GSS-API is Kerberos 5, so the last
advantage is somewhat academic. But if you are porting applications
using GSS-API for other Kerberos 5 implementations, or want a more
mature and stable API than the native Shishi API, you may find using
Shishi’s GSS-API interface compelling. Note that GSS-API only offer
basic services, for more advanced uses you must use the native API.
Since the GSS-API is not specific to Shishi, it is distributed
independently from Shishi. Further information on the GSS project can
be found at
Next:
Criticism of Kerberos
, Previous:
Programming Manual
, Up:
Top
Contents
][
Index
6 Acknowledgements
Shishi uses Libtasn1 by Fabio Fiorina, Libgcrypt and Libgpg-error by
Werner Koch, Libidn by Simon Josefsson, cvs2cl by Karl Fogel, and gdoc
by Michael Zucchi.
Several GNU packages simplified development considerably, those
packages include Autoconf, Automake, Libtool, Gnulib, Gettext, Indent,
CVS, Texinfo, Help2man and Emacs.
Several people reported bugs, sent patches or suggested improvements,
see the file THANKS.
Nicolas Pouvesle wrote the section about the Kerberos rsh/rlogin
protocol.
This manual borrows text from the Kerberos 5 specification.
Next:
Protocol Extensions
, Previous:
Acknowledgements
, Up:
Top
Contents
][
Index
Appendix A Criticism of Kerberos
The intention with this section is to discuss various problems with
Kerberos 5, so you can form a conscious decision how to deploy and use
Shishi correctly in your organization. Currently the issues below are
condensed, and mostly serve as a reminder for the author to elaborate
on them.
No encryption scheme with security proof.
No standardized API, and GSS mechanism lack important functionality.
Lack of authorization system. (krb5_kuserok())
Host to realm mapping relies on insecure DNS or static configuration
files.
Informational model and user database administration.
Non-formal specification. Unclear on the etype to use for session
keys (etype in request or database?). Unclear on how to populate some
“evident” fields (e.g., cname in tickets for AS-REQ, or crealm,
cname, realm, sname, ctime and cusec in KRB-ERROR). Unclear error
code semantics (e.g., logic for when to use S_PRINCIPAL_UNKNOWN
absent). Some KRB-ERROR fields are required, but can’t be usefully
populated in some situations, and no guidance is given on what they
should contain.
RFC 1510/1510bis incompatibilities. NULL enctype removed without
discussion, and it is still used by some 1964 GSSAPI implementations.
KRB_SAFE text (3.4.1) says the checksum is generated using the session
or sub-session key, which contradicts itself (compare section 3.2.6)
and also RFC 1510, which both allow the application to define the key.
Verification of KRB_SAFE now require the key to be compatible with the
(sub-)session key, in 1510 the only requirement was that it was
collision proof.
Problems with RFC 1510bis. Uses bignum INTEGER for TYPED-DATA and
AD-AND-OR.
Problems with crypto specification. It uses the word “random” many
times, but there is no discussion on the randomness requirements.
Practical experience indicate it is impossible to use true randomness
for all “random” fields, and no implementation does this. A post by
Don Davis on the ietf-krb-wg list tried to provide insight, but the
information was never added to the specification.
Next:
Copying Information
, Previous:
Criticism of Kerberos
, Up:
Top
Contents
][
Index
Appendix B Protocol Extensions
This appendix specifies the non-standard protocol elements implemented
by Shishi. By nature of being non-standard, everything described here
is experimental. Comments and feedback is appreciated.
STARTTLS protected KDC exchanges
How Shishi talks to KDC protected by TLS.
Telnet encryption with AES-CCM
Integrity and privacy protected telnet.
Kerberized rsh and rlogin
Description of KCMD protocol.
Key as initialization vector
Some cryptography discussion.
The Keytab Binary File Format
Format of keytab files.
The Credential Cache Binary File Format
Format of ccache files.
Next:
Telnet encryption with AES-CCM
, Up:
Protocol Extensions
Contents
][
Index
B.1 STARTTLS protected KDC exchanges
Shishi is able to “upgrade” TCP communications with the KDC to use
the Transport Layer Security (TLS) protocol. The TLS protocol offers
integrity and privacy protected exchanges. TLS also offers
authentication using username and passwords, X.509 certificates, or
OpenPGP certificates. Kerberos 5 claims to offer some of these
features, although it is not as rich as the TLS protocol. An
inconclusive list of the motivation for using TLS is given below.
Server authentication of the KDC to the client.
In traditional Kerberos 5, KDC authentication is only proved as a side
effect that the KDC knows your encryption key (i.e., your password).
Client authentication against KDC.
Kerberos 5 assume the user knows a key (usually in the form of a
password). Sometimes external factors make this hard to fulfill. In
some situations, users are equipped with smart cards with a RSA
authentication key. In others, users have a OpenPGP client on their
desktop, with a public OpenPGP key known to the server. In some
situations, the policy may be that password authentication may only be
done through SRP.
Kerberos exchanges are privacy protected.
Part of many Kerberos packets are transfered without privacy
protection (i.e., encryption). That part contains information, such
as the client principal name, the server principal name, the
encryption types supported by the client, the lifetime of tickets,
etc. Revealing such information is, in some threat models, considered
a problem. Thus, this enables “anonymity”.
Prevents downgrade attacks affecting encryption types.
The encryption type of the ticket in KDC-REQ are sent in the clear in
Kerberos 5. This allows an attacker to replace the encryption type
with a compromised mechanisms, e.g. 56-bit DES. Since clients in
general cannot know the encryption types other servers support, it is
difficult for the client to detect if there was a man-in-the-middle or
if the remote server simply did not support a stronger mechanism.
Clients may chose to refuse 56-bit DES altogether, but in some
environments this leads to operational difficulties.
TLS is well-proved and the protocol is studied by many parties.
This is an advantage in network design, where TLS is often already
assumed as part of the solution since it is used to protect HTTP,
IMAP, SMTP etc. In some threat models, the designer prefer to reduce
the number of protocols that can hurt the overall system security if
they are compromised.
Other reasons for using TLS exists.
B.1.1 TCP/IP transport with TLS upgrade (STARTTLS)
RFC 1510bis requires Kerberos servers (KDCs) to accept TCP requests.
Each request and response is prefixed by a 4 octet integer in network
byte order, indicating the length of the packet. The high bit of the
length was reserved for future expansion, and servers that do not
understand how to interpret a set high bit must return a
KRB-ERROR
with a
KRB_ERR_FIELD_TOOLONG
and close the TCP
stream.
The TCP/IP transport with TLS upgrade (STARTTLS) uses this reserved
bit as follows. First we define a new extensible typed hole for
Kerberos 5 messages, because we used the only reserved bit. It is
thus prudent to offer future extensions on our proposal. Secondly we
reserve two values in this new typed hole, and described how they are
used to implement STARTTLS.
B.1.2 Extensible typed hole based on reserved high bit
When the high bit is set, the remaining 31 bits of the 4 octets are
treated as an extensible typed hole, and thus form a 31 bit integer
enumerating various extensions. Each of the values indicate a
specific extended operation mode, two of which are used and defined
here, and the rest are left for others to use. If the KDC do not
understand a requested extension, it MUST return a
KRB-ERROR
with a
KRB_ERR_FIELD_TOOLONG
value (prefixed by the 4 octet
length integer, with the high bit clear, as usual) and close the TCP
stream.
Meaning of the 31 lower bits in the 4 octet field, when the high bit
is set:
0 RESERVED.
1 STARTTLS requested by client.
2 STARTTLS request accepted by server.
3...2147483647 AVAILABLE for registration (via bug-shishi@josefsson.org).
2147483648 RESERVED.
B.1.3 STARTTLS requested by client (extension mode 1)
When this is sent by the client, the client is requesting the server
to start TLS negotiation on the TCP stream. The client MUST NOT start
TLS negotiation immediately. Instead, the client wait for either a
KRB-ERROR (sent normally, prefixed by a 4 octet length integer)
indicating the server do not understand the set high bit, or 4 octet
which is to interpreted as an integer in network byte order, where the
high bit is set and the remaining 31 bit are interpreted as an integer
specifying the “STARTTLS request accepted by server”. In the first
case, the client infer that the server do not understand (or wish to
support) STARTTLS, and can re-try using normal TCP, if unprotected
Kerberos 5 exchanges are acceptable to the client policy. In the
latter case, it should invoke TLS negotiation on the stream. If any
other data is received, the client MUST close the TCP stream.
B.1.4 STARTTLS request accepted by server (extension mode 2)
This 4 octet message should be sent by the server when it has received
the previous 4 octet message. The message is an acknowledgment of the
client’s request to initiate STARTTLS on the channel. The server MUST
then invoke a TLS negotiation.
B.1.5 Proceeding after successful TLS negotiation
If the TLS negotiation ended successfully, possibly also considering
client or server policies, the exchange within the TLS protected
stream is performed like normal UDP Kerberos 5 exchanges, i.e., there
is no TCP 4 octet length field before each packet. Instead each
Kerberos packet MUST be sent within one TLS record, so the application
can use the TLS record length as the Kerberos 5 packet length.
B.1.6 Proceeding after failed TLS negotiation
If the TLS negotiation fails, possibly due to client or server policy
(e.g., inadequate support of encryption types in TLS, or lack of
client or server authentication) the entity that detect the failure
MUST disconnected the connection. It is expected that any error
messages that explain the error condition is transfered by TLS.
B.1.7 Interaction with KDC addresses in DNS
Administrators for a KDC may announce the KDC address by placing SRV
records in DNS for the realm, as described in
draft-ietf-krb-wg-krb-dns-locate-03.txt
. That document mention
TLS, but do not reference any work that describe how KDCs uses TLS.
Until further clarified, consider the TLS field in that document to
refer to implementation supporting this STARTTLS protocol.
B.1.8 Using TLS authentication logic in Kerberos
The server MAY consider the authentication performed by the TLS
exchange as sufficient to issue Kerberos 5 tickets to the client,
without requiring, e.g., pre-authentication. However, it is not an
error to require or use pre-authentication as well.
The client may also indicate that it wishes to use TLS both for
authentication and data protection by using the ‘
NULL
’ encryption
type in its request. The server can decide from its local policy
whether or not issuing tickets based solely on TLS authentication, and
whether ‘
NULL
’ encryption within TLS, is acceptable or not. This
mode is currently under investigation.
B.1.9 Security considerations
Because the initial token is not protected, it is possible for an
active attacker to make it appear to the client that the server do not
support this extension. It is up to client configuration to disallow
non-TLS connections, if this vulnerability is deemed unacceptable.
For interoperability, we suggest the default behaviour should be to
allow automatic fallback to TCP or UDP.
The security considerations of both TLS and Kerberos 5 are inherited.
Using TLS for authentication and/or data protection together with
Kerberos alter the authentication logic fundamentally. Thus, it may
be that even if the TLS and Kerberos 5 protocols and implementations
were secure, the combination of TLS and Kerberos 5 described here
could be insecure.
No channel bindings are provided in the Kerberos messages. It is an
open question whether, and how, this should be fixed.
Next:
Kerberized rsh and rlogin
, Previous:
STARTTLS protected KDC exchanges
, Up:
Protocol Extensions
Contents
][
Index
B.2 Telnet encryption with AES-CCM
This appendix describe how Shishi use the Advanced Encryption Standard
(AES) encryption algorithm in Counter with CBC-MAC mode (RFC 3610)
with the telnet encryption option (RFC 2946).
B.2.1 Command Names and Codes
Encryption Type
AES_CCM 12
Suboption Commands
AES_CCM_INFO 1
AES_CCM_INFO_OK 2
AES_CCM_INFO_BAD 3
B.2.2 Command Meanings
IAC SB ENCRYPT IS AES_CCM AES_CCM_INFO
The sender of this command selects desired
and
parameters,
and
nonce
, as described in RFC 3610, and sends it to
the other side of the connection.
The parameters and the
nonce
are sent in clear text.
Only the side of the connection that is WILL ENCRYPT may send the
AES_CCM_INFO command.
IAC SB ENCRYPT REPLY AES_CCM AES_CCM_INFO_BAD IAC SE
The sender of this command rejects the parameters received in the
AES_CCM_INFO command. Only the side of the connection that is
DO ENCRYPT may send the AES_CCM_INFO_BAD command.
The command MUST be sent if the
nonce
field length does not
match the selected value of
The command MAY be sent if the receiver does not accept the
parameters for a reason such as policy. No capability is provided
for negotiating these parameters.
IAC SB ENCRYPT REPLY AES_CCM AES_CCM_INFO_OK IAC SE
The sender of this command accepts the parameters received in the
AES_CCM_INFO command. Only the side of the connection that is
DO ENCRYPT may send the AES_CCM_INFO_BAD command.
The command MUST NOT be sent if the
nonce
field length
does not match the selected value of
B.2.3 Implementation Rules
Once an AES_CCM_INFO_OK command has been received, the WILL ENCRYPT
side of the connection should do keyid negotiation using the ENC_KEYID
command. Once the keyid negotiation has successfully identified a
common keyid, then START and END commands may be sent by the side of
the connection that is WILL ENCRYPT.
Data will be encrypted using the AES-CCM algorithm, with the negotiated
nonce
and parameters
and
After each successful encryption and decryption, the
nonce
is
treated as an integer in network byte order, and is incremented by one.
If encryption (decryption) is turned off and back on again, and the
same keyid is used when re-starting the encryption (decryption),
then the intervening clear text must not change the state of
the encryption (decryption) machine.
In particular, the AES-CCM
nonce
must not have been re-set.
If a START command is sent (received) with a different keyid, the
encryption (decryption) machine must be re-initialized immediately
following the end of the START command with the new key and the
parameters sent (received) in the last AES_CCM_INFO command.
If a new AES_CCM_INFO command is sent (received), and encryption
(decryption) is enabled, the encryption (decryption) machine must be
re-initialized immediately following the end of the AES_CCM_INFO
command with the new
nonce
and parameters, and the keyid sent
(received) in the last START command.
If encryption (decryption) is not enabled when an AES_CCM_INFO command
is sent (received), the encryption (decryption) machine must be re-
initialized after the next START command, with the keyid sent
(received) in that START command, and the
nonce
and parameters
sent (received) in this AES_CCM_INFO command.
At all times each peer MUST make sure that an AES-CCM
nonce
is not used twice with the same encryption key.
The rules above help accomplish this in an interoperable way.
B.2.4 Integration with the AUTHENTICATION telnet option
As noted in the telnet ENCRYPTION option specifications, a keyid value
of zero indicates the default encryption key, as might be derived from
the telnet AUTHENTICATION option. If the default encryption key
negotiated as a result of the telnet AUTHENTICATION option contains
less than 32 bytes (corresponding to two 128 bit keys), then the
AES_CCM option MUST NOT be offered or used as a valid telnet
encryption option. Furthermore, depending on policy for key lengths,
the AES_CCM option MAY be disabled if the default encryption key
contain less than 48 bytes (for two 192 bit keys), or less than 64
bytes (for two 256 bit keys), as well.
The available encrypt key data is divided on two halves, where the
first half is used to encrypt data sent from the server (decrypt data
received by the client), and the second half is used to encrypt data
sent from the client (decrypt data received by the server).
Note that the above algorithm assumes that the AUTHENTICATION
mechanism generate keying material suitable for AES-CCM as used in
this specification. This is not necessarily true in general, but we
specify this behaviour as the default since it is true for most
authentication systems in popular use today. New telnet
AUTHENTICATION mechanisms may specify alternative methods for
determining the keys to be used for this cipher suite in their
specification, if the session key negotiated by that authentication
mechanism is not a DES key and where this algorithm may not be
safely used.
Kerberos 5 authentication clarification: The key used to encrypt data
from the client to the server is taken from the sub-session key in the
AP-REQ. The key used to decrypt data from the server to the client is
taken from the sub-session key in the AP-REP. If mutual
authentication is not negotiated, the key used to encrypt data from
the client to the server is taken from the session key in the ticket,
and the key used to decrypt data from the server to the client is
taken from the sub-session key in the AP-REQ. Leaving the AP-REQ
sub-key field empty MUST disable the AES_CCM option.
B.2.5 Security Considerations
The protocol must be properly and securely implemented. For example,
an implementation should not be vulnerable to various
implementation-specific attacks such as buffer overflows or
side-channel analysis.
We wish to repeat the suggestion from RFC 2946, to investigate
a STARTTLS approach for Telnet encryption (and also authentication),
when the security level provided by this specification is not
adequate.
B.2.5.1 Telnet Encryption Protocol Security Considerations
The security consideration of the Telnet encryption protocol are
inherited.
It should be noted that it is up to the authentication protocol used,
if any, to bind the authenticity of the peers to a specific session.
The Telnet encryption protocol does not, in general, protect against
possibly malicious downgrading to any mutually acceptable, but not
preferred, encryption type. This places a requirement on each peer to
only accept encryption types it trust fully. In other words, the
Telnet encryption protocol do not guarantee that the strongest
mutually acceptable encryption type is always selected.
B.2.5.2 AES-CCM Security Considerations
The integrity and privacy claims are inherited from AES-CCM. In
particular, the implementation must make sure a
nonce
is not used more than once together with a single key.
Furthermore, the encryption key is assumed to be random, i.e., it
should not be possible to guess it with probability of success higher
than guessing any uniformly selected random key. RFC 1750 gives an
overview of issues and recommendations related to randomness.
B.2.6 Acknowledgments
This document is based on the various Telnet Encryption RFCs (RFC
2946, RFC 2947, RFC 2948, RFC 2952 and RFC 2953).
Next:
Key as initialization vector
, Previous:
Telnet encryption with AES-CCM
, Up:
Protocol Extensions
Contents
][
Index
B.3 Kerberized rsh and rlogin
This appendix describes the KCMDV0.2 protocol used in versions of
inetutils patched for shishi. The KCMD protocol was developed by
the MIT Kerberos team for the kerberized
rsh
and
rlogin
programs.
The differences between
rlogin
and
rsh
are explained below, as are differences between protocol versions v0.1
and v0.2. Both remain in use resons of compatibility.
It is possible that some parts of this document are not in conformity
with the original KCMD protocol, because there is no official
specification of it. However, it seems that shishi’s implementation
is compatible with MIT’s protocol.
Warning:
If you are seriously considering using Kerberized
rsh
or
rlogin
, instead of more robust remote
access protocols, such as
SSH
, you may first want to explore
or the full paper
at
B.3.1 Establish connection
Initially the client establishs a TCP connection to the server.
Default ports are 543 (‘
klogin
’), 544 (‘
kshell
’),
and 2105 (‘
eklogin
’).
Here ‘
eklogin
’ is the same as ‘
klogin
’, but with encryption.
There is no longer a separate ‘
ekshell
’ port, because encrypted
and normal connection now use the same port ‘
kshell
’.
Normally ‘
kshell
’ needs a second connection for
stderr
The client should send a null terminated string containing an ascii
encoding of the port number to be used for this second connection.
Since ‘
klogin
’ and ‘
eklogin
’ do not use a second connection
for
stderr
, the client just sends an additional null byte
to the server, which can be thought of as an empty string.
Contrary to classic
rsh
and
rlogin
, the server
need not check if the client’s port lies in the range 0-1023.
B.3.2 Kerberos identification
When a connection is being established, the first thing to do is
to indicate that Kerberos authentication is desired.
The client will send a string to indicate it will use Kerberos 5.
Let us say “length-string” of
strl
, and mean the couple
(length of the string strl, null-terminated string strl).
when
strl
itself is given.
The string length is encoded as an
int32
(32-bit integer)
in MSB order, i.e., network byte order.
So the client first sends an authentication message,
the length-string of
KRB5_SENDAUTH_V1.0
After that, the client must tell which version of the
protocol it uses by sending a version message, consisting of
a second length-string. This time based on
KCMDV0.2
or on “KCMDV0.1”, for the older version.
If the client’s indentification is acceptable, the server will respond
with a null byte (
0x00
).
Otherwise, if the authentication message was incorrect, then the server
responds with the single byte
0x01
, while if the protocol version
message was unacceptable, then the response is a single
0x02
B.3.3 Kerberos authentication
When the client is indentified, Kerberos authentication can begin.
The client must send an AP-REQ to the server; an AP-REQ authenticator
must contain a subkey (only for KCMDV0.2) and a checksum.
The authenticator checksum is calculated from the following string.
"serverport":"terminaltype""remoteusername"
Observe the mandatory colon, serving as a delimiter
to the terminal type.
Here
remoteusername
is whatever identity the client desires
to use at the remote end.
The simple example
543:linux/38400user
demonstrates that the terminal type expects a terminfo
name and a speed as decimal number.
Once the AP-REQ has been updated with the checksum, it is ready for
transmission to the server.
Its length (as
int32
) is first sent in network order (MSB),
followed by the DER encoded AP-REQ itself.
If all is acceptable, the server reponds with an
int32
of
value null.
(In MSB order, but as it is null, order is irrelevant!).
The KCMD protocol uses mutual authentication, so the server must
also send an AP-REP back:
(int32-length in MSB of DER encoded AP-REP)
(DER encoded AP-REP)
Now server and client are provisionally authenticated.
B.3.4 Extended authentication
The client next sends three different null terminated strings,
without length :
remote user name (user identity on remote machine)
terminal type for
rlogin
or command for
rsh
local user name (user identity on client machine)
An example for
rsh
"rname\0"
"cat /usr/local/etc/shishi.conf"
"lname\0"
The server must next verify that the checksum delivered in the
AP-REQ authenticator is correct, by computing a new hash like
the client has previously done.
The server must also verify that the requesting principal
(found in AP-REQ) has the right to log in to the remote user account.
In the ‘
basic
’ authorization, this is done by checking
whether the remote user name is identical to the principal’s name.
The alternative is ‘
k5login
’ mode, which is discussed in
kerberos authorization
If all is correct, the server sends a null byte, i.e., an empty string,
or else an error message string (null terminated).
The remote client reads the first byte.
If it is equal to zero, authentication is successful and the user
is logged in at the remote host.
In any other case, the client has the error message available,
as sent by the server, to help the user understand the failure.
B.3.5 Window size
In the
rlogin
protocol, when authentication completes,
the server can optionally send a message asking for terminal window
size suitable for the user.
The client can respond, but it is not obliged to do so.
Under KCMDV0.1, the server sends a single byte, an urgent TCP message
MSG_OOB
) :
TIOCPKT_WINDOW = 0x80
With KCMDV0.2, the server does not send an urgent message at all,
but writes five bytes to the socket :
'\377', '\377', 'o', 'o', TIOCPKT_WINDOW
If encryption is enabled (‘
eklogin
’) the server must send those
five bytes in encrypted form.
The client answers alike in both protocol versions :
'\377', '\377', 's', 's', "struct winsize"
The winsize structure is filled in with the settings from
the client’s terminal.
With encryption enabled, this answer must be sent encrypted.
B.3.6 End of authentication
The legacy exchange supported by
rsh
and
rlogin
continues from this point onwards.
B.3.7 Encryption
Encryption mode is always used when connecting via the port ‘
eklogin
’.
The port ‘
kshell
’ also supports encryption.
Previously, there was a specific port ‘
ekshell
’ for that purpose,
a use which is now extinct.
Instead, whenever an encrypted exchange is desired via the port
kshell
’, client must prefix the string “-x ” to the
command string, when it is sent inbetween the remote user name
and the local user name.
In contrast, when the client computes the checksum for the AP-REQ
authenticator, the string “-x ” must not be included.
Encryption porcedure under version KCMDV0.2 differs from that in the
older protocol version.
Under version KCMDV0.1, the ticket session key is put to use
as encryption key, and only standard Kerberos encryption functions
are usable.
Thus it supports only ‘
des-cbc-crc
’, ‘
des-cbc-md4
’,
des-cbc-md5
’, and does not allow use of initialisation vectors.
As an example of encryption/decryption calls, the following
Kerberos function prototype should be used :
kerberos_encrypt (key, keyusage, in, out) (or kerberos_decrypt)
To contrast, KCMDV0.2 can be used with all Kerberos encryption modes,
i.e., ‘
des
’, ‘
3des
’, ‘
aes
’, ‘
arcfour
’,
and it uses an AP-REQ authenticator subkey. In opposition to KCMDV0.1,
initialisation vectors are used.
All encryption and descryption must be made using a cryptographic context.
A typical coding example updates the context with an
iv
then executes an encryption call :
kerberos_init(ctx, iv, key, keyusage)
kerberos_encrypt (ctx, in, out)
For both protocols, default keyusage identity allowing ‘
des-cbc-md5
’,
des-cbc-md4
’, ‘
des-cbc-crc
’, and ‘
des3-cbc-sha1
(the latter applicable only to KCMDV0.2) is identical :
keyusage = 1026
KCMDV0.2 encryption modes, other than the four named above,
specify distinct values for
keyusage
unique to each encryption/decryption mode.
In conclusion, ‘
eklogin
’ uses a single socket.
It encrypts data “output 1” prior to sending,
and it decrypts “input 1” received data.
kshell
’ uses two sockets: one for transmitting data,
and one for a side channel carrying
stderr
Thus there are four streams available :
transmit : input 1
output 1
stderr : input 2
output 2
There is a key usage set for each mode.
The values of each
keyusage
must be compatible between
client and server side.
An example with ‘
klogin
’, shows the client’s “input 1”
key usage to be identical to the server’s “output 1” usage.
I/O
Client
Server
input 1
1028
1030
output 1
1030
1028
input 2
1032
1034
output 2
1034
1032
The stated key usages are for AES and ARCFOUR modes.
KCMDV0.2 uses an IV (initialisation vector) with AES.
Like for key usage, the client IV must correspond to the server IV.
The IV size is equal to the blocksize of the chosen key type.
All bytes of IV must be initialised too :
I/O
Client
Server
input 1
output 1
input 2
output 2
ARCFOUR mode does not use an IV.
However, like mentioned before, a context must be used to keep
the updating the sbox.
A normal message for ‘
klogin
’ or ‘
kshell
’ is set up like this :
(int32-length of message in MSB order)
(message)
In encrypted mode, the format is only slightly different :
(int32-length of unencrypted message in MSB order)
(encrypted message)
Under KCMDV0.2, the encrypted message is create like this :
encrypt (
(int32-length of message in MSB order)
(message)
A check on message size can be made in second version of the protocol.
B.3.8 KCMDV0.3
This part only gives possible ways to extend the KCMD protocol.
They should not be understood as some kind of “must have”
in a future KCMD implementation.
Extensions to KCMV0.2 can be imagined.
For example, ‘
kshell
’ assumes there are no files of names
like “-x *”.
I think the same thing can be assumed of terminal names for ‘
klogin
’.
So the client could add “-x ” to the terminal type it transmits
to the server, in order to indicate the desire to use encryption.
Under this provision, there need only be one port shared by
klogin
’ and ‘
eklogin
’, namely the IANA defined port
number 543.
Before encryption begins, ‘
kshell
’ passes the intended
commands in the clear through the network.
This could be considered insecure, once the user has decided
to use encryption.
It is not really a problem with ‘
klogin
’, because it just
tells which terminal type to target.
One could imagine, when the client intends to use encrypted mode,
that the client side initially transmits a mundane “-x” and
nothing else to either of ‘
klogin
’ and ‘
kshell
’,
in place of either a command or a terminal type, respectively.
Once encryption is in place, the client could send terminal
type or command in a second, now encrypted exchange.
The server could respond with a single null byte, saying that all
is well, or respond with an error message, which already enjoys the
added benefit of being encrypted.
B.3.9 MIT/Heimdal authorization
This short part describes how MIT/Heimdal versions of Kerberos 5
check authorization of any user seeking to log in to a remote machine.
The authorization stage begins by testing whether the file
.k5login
exists in the home directory of the remote user.
If this file does not exist, then a valid authorization demands that
the remote user’s name must be the same as the name of the principal
contained in the request AP-REQ.
(This is the legacy ‘
basic
’ authorization.)
Else, if the file is present, the serve first verifies that the remote
user, or root, is the owner of
.k5login
, then goes on to verify
that the file is not readable by group, nor by world.
If either fails, then the check fails entirely.
If all is good so far, then each line of that file is examined,
and each name read in is compared to the principal.
If the principal is found listed somewhere in
.k5login
then authorization is successful.
In the contrary case, the user is not admitted to the remote host as
the requested remote user, a name that could have been derived to be
the very same as in the principal itself.
So someone, “user1” say, can remotely log in to the account
of “user2”, if the file
.k5login
is present in the home
directory of “user2”, and it is owned by “user2” or by root,
and at the same time the name “user1” is listed in this file.
Next:
The Keytab Binary File Format
, Previous:
Kerberized rsh and rlogin
, Up:
Protocol Extensions
Contents
][
Index
B.4 Key as initialization vector
The
des-cbc-crc
algorithm (see
Cryptographic Overview
) uses
the DES key as the initialization vector. This is problematic in
general (see below
), but
may be mitigated in Kerberos by the CRC checksum that is also
included.
From daw@espresso.CS.Berkeley.EDU Fri Mar 1 13:32:34 PST 1996
Article: 50440 of sci.crypt
Path: agate!daw
From: daw@espresso.CS.Berkeley.EDU (David A Wagner)
Newsgroups: sci.crypt
Subject: Re: DES-CBC and Initialization Vectors
Date: 29 Feb 1996 21:48:16 GMT
Organization: University of California, Berkeley
Lines: 31
Message-ID: <4h56v0$3no@agate.berkeley.edu>
References: <4h39li$33o@gaia.ns.utk.edu>
NNTP-Posting-Host: espresso.cs.berkeley.edu
In article <4h39li$33o@gaia.ns.utk.edu>,
Nair Venugopal
> Is there anything wrong in using the key as the I.V. in DES-CBC mode?
Yes, you're open to a chosen-ciphertext attack which recovers the key.
Alice is sending stuff DES-CBC encrypted with key K to Bob. Mary is an
active adversary in the middle. Suppose Alice encrypts some plaintext
blocks P_1, P_2, P_3, ... in DES-CBC mode with K as the IV, and sends off
the resulting ciphertext
A->B: C_1, C_2, C_3, ...
where each C_j is a 8-byte DES ciphertext block. Mary wants to discover
the key K, but doesn't even know any of the P_j's. She replaces the above
message by
M->B: C_1, 0, C_1
where 0 is the 8-byte all-zeros block. Bob will decrypt under DES-CBC,
recovering the blocks
Q_1, Q_2, Q_3
where
Q_1 = DES-decrypt(K, C_1) xor K = P_1
Q_2 = DES-decrypt(K, C_2) xor C_1 = (some unimportant junk)
Q_3 = DES-decrypt(K, C_1) xor 0 = P_1 xor K
Bob gets this garbage-looking message Q_1,Q_2,Q_3 which Mary recovers
(under the chosen-ciphertext assumption: this is like a known-plaintext
attack, which isn't too implausible). Notice that Mary can recover K by
K = Q_1 xor Q_3;
so after this one simple active attack, Mary gets the key back!
So, if you must use a fixed IV, don't use the key-- use 0 or something
like that. Even better, don't use a fixed IV-- use the DES encryption
of a counter, or something like that.
Next:
The Credential Cache Binary File Format
, Previous:
Key as initialization vector
, Up:
Protocol Extensions
Contents
][
Index
B.5 The Keytab Binary File Format
The keytab file format is described in the file
keytab.txt
here included verbatim.
The Kerberos Keytab Binary File Format
Copyright (C) 2006 Michael B Allen
The MIT keytab binary format is not a standard format, nor is it
documented anywhere in detail. The format has evolved and may continue
to. It is however understood by several Kerberos implementations including
Heimdal and of course MIT and keytab files are created by the ktpass.exe
utility from Windows. So it has established itself as the defacto format
for storing Kerberos keys.
The following C-like structure definitions illustrate the MIT keytab
file format. All values are in network byte order. All text is ASCII.
keytab {
uint16_t file_format_version; /* 0x502 */
keytab_entry entries[*];
};
keytab_entry {
int32_t size;
uint16_t num_components; /* sub 1 if version 0x501 */
counted_octet_string realm;
counted_octet_string components[num_components];
uint32_t name_type; /* not present if version 0x501 */
uint32_t timestamp;
uint8_t vno8;
keyblock key;
uint32_t vno; /* only present if >= 4 bytes left in entry */
};
counted_octet_string {
uint16_t length;
uint8_t data[length];
};
keyblock {
uint16_t type;
counted_octet_string;
};
The keytab file format begins with the 16 bit file_format_version which
at the time this document was authored is 0x502. The format of older
keytabs is described at the end of this document.
The file_format_version is immediately followed by an array of
keytab_entry structures which are prefixed with a 32 bit size indicating
the number of bytes that follow in the entry. Note that the size should be
evaluated as signed. This is because a negative value indicates that the
entry is in fact empty (e.g. it has been deleted) and that the negative
value of that negative value (which is of course a positive value) is
the offset to the next keytab_entry. Based on these size values alone
the entire keytab file can be traversed.
The size is followed by a 16 bit num_components field indicating the
number of counted_octet_string components in the components array.
The num_components field is followed by a counted_octet_string
representing the realm of the principal.
A counted_octet_string is simply an array of bytes prefixed with a 16
bit length. For the realm and name components, the counted_octet_string
bytes are ASCII encoded text with no zero terminator.
Following the realm is the components array that represents the name of
the principal. The text of these components may be joined with slashs
to construct the typical SPN representation. For example, the service
principal HTTP/www.foo.net@FOO.NET would consist of name components
"HTTP" followed by "www.foo.net".
Following the components array is the 32 bit name_type (e.g. 1 is
KRB5_NT_PRINCIPAL, 2 is KRB5_NT_SRV_INST, 5 is KRB5_NT_UID, etc). In
practice the name_type is almost certainly 1 meaning KRB5_NT_PRINCIPAL.
The 32 bit timestamp indicates the time the key was established for that
principal. The value represents the number of seconds since Jan 1, 1970.
The 8 bit vno8 field is the version number of the key. This value is
overridden by the 32 bit vno field if it is present.
The keyblock structure consists of a 16 bit value indicating the keytype
(e.g. 3 is des-cbc-md5, 23 is arcfour-hmac-md5, 16 is des3-cbc-sha1,
etc). This is followed by a counted_octet_string containing the key.
The last field of the keytab_entry structure is optional. If the size of
the keytab_entry indicates that there are at least 4 bytes remaining,
a 32 bit value representing the key version number is present. This
value supersedes the 8 bit vno8 value preceeding the keyblock.
Older keytabs with a file_format_version of 0x501 are different in
three ways:
1) All integers are in host byte order [1].
2) The num_components field is 1 too large (i.e. after decoding,
decrement by 1).
3) The 32 bit name_type field is not present.
[1] The file_format_version field should really be treated as two
separate 8 bit quantities representing the major and minor version
number respectively.
Permission to copy, modify, and distribute this document, with or
without modification, for any purpose and without fee or royalty is
hereby granted, provided that you include this copyright notice in ALL
copies of the document or portions thereof, including modifications.
Previous:
The Keytab Binary File Format
, Up:
Protocol Extensions
Contents
][
Index
B.6 The Credential Cache Binary File Format
The credential cache file format is described in the file
keytab.txt
, included verbatim.
The Kerberos Credential Cache Binary File Format
Copyright (C) 2006-2022 Simon Josefsson
Like the MIT keytab binary format (see Michael B Allen's reverse
engineered description in keytab.txt), the credential cache format is
not standard nor documented anywhere.
In C style notation, the MIT credential cache file format is as
follows. All values are in network byte order. All text is ASCII.
ccache {
uint16_t file_format_version; /* 0x0504 */
uint16_t headerlen; /* only if version is 0x0504 */
header headers[]; /* only if version is 0x0504 */
principal primary_principal;
credential credentials[*];
};
header {
uint16_t tag; /* 1 = DeltaTime */
uint16_t taglen;
uint8_t tagdata[taglen]
};
The ccache.taglen and ccache.tags fields are only present in 0x0504
versions, not in earlier. Both MIT and Heimdal appear to correctly
ignore unknown tags, so it appears safe to add them (although there is
no central place to "register" tags).
Currently only one tag is widely implemented, DeltaTime (0x0001). Its
taglen is always 8, and tagdata will contain:
DeltaTime {
uint32_t time_offset;
uint32_t usec_offset;
};
After reading the file_format_version, header tags, and default
principal, a list of credentials follow. You deduce from the file
length when there are no more credentials.
credential {
principal client;
principal server;
keyblock key;
times time;
uint8_t is_skey; /* 1 if skey, 0 otherwise */
uint32_t tktflags; /* stored in reversed byte order */
uint32_t num_address;
address addrs[num_address];
uint32_t num_authdata;
authdata authdata[num_authdata];
countet_octet_string ticket;
countet_octet_string second_ticket;
};
keyblock {
uint16_t keytype;
uint16_t etype; /* only present if version 0x0503 */
uint16_t keylen;
uint8_t keyvalue[keylen];
};
times {
uint32_t authtime;
uint32_t starttime;
uint32_t endtime;
uint32_t renew_till;
};
address {
uint16_t addrtype;
counted_octet_string addrdata;
};
authdata {
uint16_t authtype;
counted_octet_string authdata;
};
principal {
uint32_t name_type; /* not present if version 0x0501 */
uint32_t num_components; /* sub 1 if version 0x501 */
counted_octet_string realm;
counted_octet_string components[num_components];
};
counted_octet_string {
uint32_t length;
uint8_t data[length];
};
Permission to copy, modify, and distribute this document, with or
without modification, for any purpose and without fee or royalty is
hereby granted, provided that you include this copyright notice in ALL
copies of the document or portions thereof, including modifications.
Next:
Function and Data Index
, Previous:
Protocol Extensions
, Up:
Top
Contents
][
Index
Appendix C Copying Information
GNU Free Documentation License
License for copying this manual.
Up:
Copying Information
Contents
][
Index
C.1 GNU Free Documentation License
Version 1.3, 3 November 2008
Copyright © 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
PREAMBLE
The purpose of this License is to make a manual, textbook, or other
functional and useful document
free
in the sense of freedom: to
assure everyone the effective freedom to copy and redistribute it,
with or without modifying it, either commercially or noncommercially.
Secondarily, this License preserves for the author and publisher a way
to get credit for their work, while not being considered responsible
for modifications made by others.
This License is a kind of “copyleft”, which means that derivative
works of the document must themselves be free in the same sense. It
complements the GNU General Public License, which is a copyleft
license designed for free software.
We have designed this License in order to use it for manuals for free
software, because free software needs free documentation: a free
program should come with manuals providing the same freedoms that the
software does. But this License is not limited to software manuals;
it can be used for any textual work, regardless of subject matter or
whether it is published as a printed book. We recommend this License
principally for works whose purpose is instruction or reference.
APPLICABILITY AND DEFINITIONS
This License applies to any manual or other work, in any medium, that
contains a notice placed by the copyright holder saying it can be
distributed under the terms of this License. Such a notice grants a
world-wide, royalty-free license, unlimited in duration, to use that
work under the conditions stated herein. The “Document”, below,
refers to any such manual or work. Any member of the public is a
licensee, and is addressed as “you”. You accept the license if you
copy, modify or distribute the work in a way requiring permission
under copyright law.
A “Modified Version” of the Document means any work containing the
Document or a portion of it, either copied verbatim, or with
modifications and/or translated into another language.
A “Secondary Section” is a named appendix or a front-matter section
of the Document that deals exclusively with the relationship of the
publishers or authors of the Document to the Document’s overall
subject (or to related matters) and contains nothing that could fall
directly within that overall subject. (Thus, if the Document is in
part a textbook of mathematics, a Secondary Section may not explain
any mathematics.) The relationship could be a matter of historical
connection with the subject or with related matters, or of legal,
commercial, philosophical, ethical or political position regarding
them.
The “Invariant Sections” are certain Secondary Sections whose titles
are designated, as being those of Invariant Sections, in the notice
that says that the Document is released under this License. If a
section does not fit the above definition of Secondary then it is not
allowed to be designated as Invariant. The Document may contain zero
Invariant Sections. If the Document does not identify any Invariant
Sections then there are none.
The “Cover Texts” are certain short passages of text that are listed,
as Front-Cover Texts or Back-Cover Texts, in the notice that says that
the Document is released under this License. A Front-Cover Text may
be at most 5 words, and a Back-Cover Text may be at most 25 words.
A “Transparent” copy of the Document means a machine-readable copy,
represented in a format whose specification is available to the
general public, that is suitable for revising the document
straightforwardly with generic text editors or (for images composed of
pixels) generic paint programs or (for drawings) some widely available
drawing editor, and that is suitable for input to text formatters or
for automatic translation to a variety of formats suitable for input
to text formatters. A copy made in an otherwise Transparent file
format whose markup, or absence of markup, has been arranged to thwart
or discourage subsequent modification by readers is not Transparent.
An image format is not Transparent if used for any substantial amount
of text. A copy that is not “Transparent” is called “Opaque”.
Examples of suitable formats for Transparent copies include plain
ASCII without markup, Texinfo input format, LaTeX input
format, SGML or XML using a publicly available
DTD, and standard-conforming simple HTML,
PostScript or PDF designed for human modification. Examples
of transparent image formats include PNG, XCF and
JPG. Opaque formats include proprietary formats that can be
read and edited only by proprietary word processors, SGML or
XML for which the DTD and/or processing tools are
not generally available, and the machine-generated HTML,
PostScript or PDF produced by some word processors for
output purposes only.
The “Title Page” means, for a printed book, the title page itself,
plus such following pages as are needed to hold, legibly, the material
this License requires to appear in the title page. For works in
formats which do not have any title page as such, “Title Page” means
the text near the most prominent appearance of the work’s title,
preceding the beginning of the body of the text.
The “publisher” means any person or entity that distributes copies
of the Document to the public.
A section “Entitled XYZ” means a named subunit of the Document whose
title either is precisely XYZ or contains XYZ in parentheses following
text that translates XYZ in another language. (Here XYZ stands for a
specific section name mentioned below, such as “Acknowledgements”,
“Dedications”, “Endorsements”, or “History”.) To “Preserve the Title”
of such a section when you modify the Document means that it remains a
section “Entitled XYZ” according to this definition.
The Document may include Warranty Disclaimers next to the notice which
states that this License applies to the Document. These Warranty
Disclaimers are considered to be included by reference in this
License, but only as regards disclaiming warranties: any other
implication that these Warranty Disclaimers may have is void and has
no effect on the meaning of this License.
VERBATIM COPYING
You may copy and distribute the Document in any medium, either
commercially or noncommercially, provided that this License, the
copyright notices, and the license notice saying this License applies
to the Document are reproduced in all copies, and that you add no other
conditions whatsoever to those of this License. You may not use
technical measures to obstruct or control the reading or further
copying of the copies you make or distribute. However, you may accept
compensation in exchange for copies. If you distribute a large enough
number of copies you must also follow the conditions in section 3.
You may also lend copies, under the same conditions stated above, and
you may publicly display copies.
COPYING IN QUANTITY
If you publish printed copies (or copies in media that commonly have
printed covers) of the Document, numbering more than 100, and the
Document’s license notice requires Cover Texts, you must enclose the
copies in covers that carry, clearly and legibly, all these Cover
Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
the back cover. Both covers must also clearly and legibly identify
you as the publisher of these copies. The front cover must present
the full title with all words of the title equally prominent and
visible. You may add other material on the covers in addition.
Copying with changes limited to the covers, as long as they preserve
the title of the Document and satisfy these conditions, can be treated
as verbatim copying in other respects.
If the required texts for either cover are too voluminous to fit
legibly, you should put the first ones listed (as many as fit
reasonably) on the actual cover, and continue the rest onto adjacent
pages.
If you publish or distribute Opaque copies of the Document numbering
more than 100, you must either include a machine-readable Transparent
copy along with each Opaque copy, or state in or with each Opaque copy
a computer-network location from which the general network-using
public has access to download using public-standard network protocols
a complete Transparent copy of the Document, free of added material.
If you use the latter option, you must take reasonably prudent steps,
when you begin distribution of Opaque copies in quantity, to ensure
that this Transparent copy will remain thus accessible at the stated
location until at least one year after the last time you distribute an
Opaque copy (directly or through your agents or retailers) of that
edition to the public.
It is requested, but not required, that you contact the authors of the
Document well before redistributing any large number of copies, to give
them a chance to provide you with an updated version of the Document.
MODIFICATIONS
You may copy and distribute a Modified Version of the Document under
the conditions of sections 2 and 3 above, provided that you release
the Modified Version under precisely this License, with the Modified
Version filling the role of the Document, thus licensing distribution
and modification of the Modified Version to whoever possesses a copy
of it. In addition, you must do these things in the Modified Version:
Use in the Title Page (and on the covers, if any) a title distinct
from that of the Document, and from those of previous versions
(which should, if there were any, be listed in the History section
of the Document). You may use the same title as a previous version
if the original publisher of that version gives permission.
List on the Title Page, as authors, one or more persons or entities
responsible for authorship of the modifications in the Modified
Version, together with at least five of the principal authors of the
Document (all of its principal authors, if it has fewer than five),
unless they release you from this requirement.
State on the Title page the name of the publisher of the
Modified Version, as the publisher.
Preserve all the copyright notices of the Document.
Add an appropriate copyright notice for your modifications
adjacent to the other copyright notices.
Include, immediately after the copyright notices, a license notice
giving the public permission to use the Modified Version under the
terms of this License, in the form shown in the Addendum below.
Preserve in that license notice the full lists of Invariant Sections
and required Cover Texts given in the Document’s license notice.
Include an unaltered copy of this License.
Preserve the section Entitled “History”, Preserve its Title, and add
to it an item stating at least the title, year, new authors, and
publisher of the Modified Version as given on the Title Page. If
there is no section Entitled “History” in the Document, create one
stating the title, year, authors, and publisher of the Document as
given on its Title Page, then add an item describing the Modified
Version as stated in the previous sentence.
Preserve the network location, if any, given in the Document for
public access to a Transparent copy of the Document, and likewise
the network locations given in the Document for previous versions
it was based on. These may be placed in the “History” section.
You may omit a network location for a work that was published at
least four years before the Document itself, or if the original
publisher of the version it refers to gives permission.
For any section Entitled “Acknowledgements” or “Dedications”, Preserve
the Title of the section, and preserve in the section all the
substance and tone of each of the contributor acknowledgements and/or
dedications given therein.
Preserve all the Invariant Sections of the Document,
unaltered in their text and in their titles. Section numbers
or the equivalent are not considered part of the section titles.
Delete any section Entitled “Endorsements”. Such a section
may not be included in the Modified Version.
Do not retitle any existing section to be Entitled “Endorsements” or
to conflict in title with any Invariant Section.
Preserve any Warranty Disclaimers.
If the Modified Version includes new front-matter sections or
appendices that qualify as Secondary Sections and contain no material
copied from the Document, you may at your option designate some or all
of these sections as invariant. To do this, add their titles to the
list of Invariant Sections in the Modified Version’s license notice.
These titles must be distinct from any other section titles.
You may add a section Entitled “Endorsements”, provided it contains
nothing but endorsements of your Modified Version by various
parties—for example, statements of peer review or that the text has
been approved by an organization as the authoritative definition of a
standard.
You may add a passage of up to five words as a Front-Cover Text, and a
passage of up to 25 words as a Back-Cover Text, to the end of the list
of Cover Texts in the Modified Version. Only one passage of
Front-Cover Text and one of Back-Cover Text may be added by (or
through arrangements made by) any one entity. If the Document already
includes a cover text for the same cover, previously added by you or
by arrangement made by the same entity you are acting on behalf of,
you may not add another; but you may replace the old one, on explicit
permission from the previous publisher that added the old one.
The author(s) and publisher(s) of the Document do not by this License
give permission to use their names for publicity for or to assert or
imply endorsement of any Modified Version.
COMBINING DOCUMENTS
You may combine the Document with other documents released under this
License, under the terms defined in section 4 above for modified
versions, provided that you include in the combination all of the
Invariant Sections of all of the original documents, unmodified, and
list them all as Invariant Sections of your combined work in its
license notice, and that you preserve all their Warranty Disclaimers.
The combined work need only contain one copy of this License, and
multiple identical Invariant Sections may be replaced with a single
copy. If there are multiple Invariant Sections with the same name but
different contents, make the title of each such section unique by
adding at the end of it, in parentheses, the name of the original
author or publisher of that section if known, or else a unique number.
Make the same adjustment to the section titles in the list of
Invariant Sections in the license notice of the combined work.
In the combination, you must combine any sections Entitled “History”
in the various original documents, forming one section Entitled
“History”; likewise combine any sections Entitled “Acknowledgements”,
and any sections Entitled “Dedications”. You must delete all
sections Entitled “Endorsements.”
COLLECTIONS OF DOCUMENTS
You may make a collection consisting of the Document and other documents
released under this License, and replace the individual copies of this
License in the various documents with a single copy that is included in
the collection, provided that you follow the rules of this License for
verbatim copying of each of the documents in all other respects.
You may extract a single document from such a collection, and distribute
it individually under this License, provided you insert a copy of this
License into the extracted document, and follow this License in all
other respects regarding verbatim copying of that document.
AGGREGATION WITH INDEPENDENT WORKS
A compilation of the Document or its derivatives with other separate
and independent documents or works, in or on a volume of a storage or
distribution medium, is called an “aggregate” if the copyright
resulting from the compilation is not used to limit the legal rights
of the compilation’s users beyond what the individual works permit.
When the Document is included in an aggregate, this License does not
apply to the other works in the aggregate which are not themselves
derivative works of the Document.
If the Cover Text requirement of section 3 is applicable to these
copies of the Document, then if the Document is less than one half of
the entire aggregate, the Document’s Cover Texts may be placed on
covers that bracket the Document within the aggregate, or the
electronic equivalent of covers if the Document is in electronic form.
Otherwise they must appear on printed covers that bracket the whole
aggregate.
TRANSLATION
Translation is considered a kind of modification, so you may
distribute translations of the Document under the terms of section 4.
Replacing Invariant Sections with translations requires special
permission from their copyright holders, but you may include
translations of some or all Invariant Sections in addition to the
original versions of these Invariant Sections. You may include a
translation of this License, and all the license notices in the
Document, and any Warranty Disclaimers, provided that you also include
the original English version of this License and the original versions
of those notices and disclaimers. In case of a disagreement between
the translation and the original version of this License or a notice
or disclaimer, the original version will prevail.
If a section in the Document is Entitled “Acknowledgements”,
“Dedications”, or “History”, the requirement (section 4) to Preserve
its Title (section 1) will typically require changing the actual
title.
TERMINATION
You may not copy, modify, sublicense, or distribute the Document
except as expressly provided under this License. Any attempt
otherwise to copy, modify, sublicense, or distribute it is void, and
will automatically terminate your rights under this License.
However, if you cease all violation of this License, then your license
from a particular copyright holder is reinstated (a) provisionally,
unless and until the copyright holder explicitly and finally
terminates your license, and (b) permanently, if the copyright holder
fails to notify you of the violation by some reasonable means prior to
60 days after the cessation.
Moreover, your license from a particular copyright holder is
reinstated permanently if the copyright holder notifies you of the
violation by some reasonable means, this is the first time you have
received notice of violation of this License (for any work) from that
copyright holder, and you cure the violation prior to 30 days after
your receipt of the notice.
Termination of your rights under this section does not terminate the
licenses of parties who have received copies or rights from you under
this License. If your rights have been terminated and not permanently
reinstated, receipt of a copy of some or all of the same material does
not give you any rights to use it.
FUTURE REVISIONS OF THIS LICENSE
The Free Software Foundation may publish new, revised versions
of the GNU Free Documentation License from time to time. Such new
versions will be similar in spirit to the present version, but may
differ in detail to address new problems or concerns. See
Each version of the License is given a distinguishing version number.
If the Document specifies that a particular numbered version of this
License “or any later version” applies to it, you have the option of
following the terms and conditions either of that specified version or
of any later version that has been published (not as a draft) by the
Free Software Foundation. If the Document does not specify a version
number of this License, you may choose any version ever published (not
as a draft) by the Free Software Foundation. If the Document
specifies that a proxy can decide which future versions of this
License can be used, that proxy’s public statement of acceptance of a
version permanently authorizes you to choose that version for the
Document.
RELICENSING
“Massive Multiauthor Collaboration Site” (or “MMC Site”) means any
World Wide Web server that publishes copyrightable works and also
provides prominent facilities for anybody to edit those works. A
public wiki that anybody can edit is an example of such a server. A
“Massive Multiauthor Collaboration” (or “MMC”) contained in the
site means any set of copyrightable works thus published on the MMC
site.
“CC-BY-SA” means the Creative Commons Attribution-Share Alike 3.0
license published by Creative Commons Corporation, a not-for-profit
corporation with a principal place of business in San Francisco,
California, as well as future copyleft versions of that license
published by that same organization.
“Incorporate” means to publish or republish a Document, in whole or
in part, as part of another Document.
An MMC is “eligible for relicensing” if it is licensed under this
License, and if all works that were first published under this License
somewhere other than this MMC, and subsequently incorporated in whole
or in part into the MMC, (1) had no cover texts or invariant sections,
and (2) were thus incorporated prior to November 1, 2008.
The operator of an MMC Site may republish an MMC contained in the site
under CC-BY-SA on the same site at any time before August 1, 2009,
provided the MMC is eligible for relicensing.
ADDENDUM: How to use this License for your documents
To use this License in a document you have written, include a copy of
the License in the document and put the following copyright and
license notices just after the title page:
Copyright (C)
year
your name
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
Texts. A copy of the license is included in the section entitled ``GNU
Free Documentation License''.
If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
replace the “with…Texts.” line with this:
with the Invariant Sections being
list their titles
, with
the Front-Cover Texts being
list
, and with the Back-Cover Texts
being
list
If you have Invariant Sections without Cover Texts, or some other
combination of the three, merge those two alternatives to suit the
situation.
If your document contains nontrivial examples of program code, we
recommend releasing these examples in parallel under your choice of
free software license, such as the GNU General Public License,
to permit their use in free software.
Next:
Concept Index
, Previous:
Copying Information
, Up:
Top
Contents
][
Index
Function and Data Index
Jump to:
Index Entry
Section
ago
in date strings
Relative items in date strings
am
in date strings
Time of day items
day
in date strings
Relative items in date strings
day
in date strings
Relative items in date strings
first
in date strings
General date syntax
fortnight
in date strings
Relative items in date strings
hour
in date strings
Relative items in date strings
last
day
Day of week items
last
in date strings
General date syntax
midnight
in date strings
Time of day items
minute
in date strings
Relative items in date strings
month
in date strings
Relative items in date strings
next
day
Day of week items
next
in date strings
General date syntax
noon
in date strings
Time of day items
now
in date strings
Relative items in date strings
parse_datetime
Date input formats
pm
in date strings
Time of day items
shisa
Kerberos Database Functions
shisa_cfg
Kerberos Database Functions
shisa_cfg_db
Kerberos Database Functions
shisa_cfg_default_systemfile
Kerberos Database Functions
shisa_cfg_from_file
Kerberos Database Functions
shisa_done
Kerberos Database Functions
shisa_enumerate_principals
Kerberos Database Functions
shisa_enumerate_realms
Kerberos Database Functions
shisa_info
Kerberos Database Functions
shisa_init
Kerberos Database Functions
shisa_init_with_paths
Kerberos Database Functions
shisa_keys_find
Kerberos Database Functions
shisa_keys_free
Kerberos Database Functions
shisa_key_add
Kerberos Database Functions
shisa_key_free
Kerberos Database Functions
shisa_key_remove
Kerberos Database Functions
shisa_key_update
Kerberos Database Functions
shisa_principal_add
Kerberos Database Functions
shisa_principal_find
Kerberos Database Functions
shisa_principal_remove
Kerberos Database Functions
shisa_principal_update
Kerberos Database Functions
shisa_strerror
Kerberos Database Functions
shishi
Initialization Functions
shishi_3des
Cryptographic Functions
shishi_aes_cts
Cryptographic Functions
shishi_ap
AP-REQ and AP-REP Functions
shishi_aprep
AP-REQ and AP-REP Functions
shishi_aprep_from_file
AP-REQ and AP-REP Functions
shishi_aprep_get_enc_part_etype
AP-REQ and AP-REP Functions
shishi_aprep_parse
AP-REQ and AP-REP Functions
shishi_aprep_print
AP-REQ and AP-REP Functions
shishi_aprep_read
AP-REQ and AP-REP Functions
shishi_aprep_save
AP-REQ and AP-REP Functions
shishi_aprep_to_file
AP-REQ and AP-REP Functions
shishi_apreq
AP-REQ and AP-REP Functions
shishi_apreq_add_authenticator
AP-REQ and AP-REP Functions
shishi_apreq_from_file
AP-REQ and AP-REP Functions
shishi_apreq_get_authenticator_etype
AP-REQ and AP-REP Functions
shishi_apreq_get_ticket
AP-REQ and AP-REP Functions
shishi_apreq_mutual_required_p
AP-REQ and AP-REP Functions
shishi_apreq_options
AP-REQ and AP-REP Functions
shishi_apreq_options_add
AP-REQ and AP-REP Functions
shishi_apreq_options_remove
AP-REQ and AP-REP Functions
shishi_apreq_options_set
AP-REQ and AP-REP Functions
shishi_apreq_parse
AP-REQ and AP-REP Functions
shishi_apreq_print
AP-REQ and AP-REP Functions
shishi_apreq_read
AP-REQ and AP-REP Functions
shishi_apreq_save
AP-REQ and AP-REP Functions
shishi_apreq_set_authenticator
AP-REQ and AP-REP Functions
shishi_apreq_set_ticket
AP-REQ and AP-REP Functions
shishi_apreq_to_file
AP-REQ and AP-REP Functions
shishi_apreq_use_session_key_p
AP-REQ and AP-REP Functions
shishi_ap_authenticator
AP-REQ and AP-REP Functions
shishi_ap_authenticator_cksumdata
AP-REQ and AP-REP Functions
shishi_ap_authenticator_cksumdata_set
AP-REQ and AP-REP Functions
shishi_ap_authenticator_cksumraw_set
AP-REQ and AP-REP Functions
shishi_ap_authenticator_cksumtype
AP-REQ and AP-REP Functions
shishi_ap_authenticator_cksumtype_set
AP-REQ and AP-REP Functions
shishi_ap_authenticator_set
AP-REQ and AP-REP Functions
shishi_ap_done
AP-REQ and AP-REP Functions
shishi_ap_encapreppart
AP-REQ and AP-REP Functions
shishi_ap_encapreppart_set
AP-REQ and AP-REP Functions
shishi_ap_etype
AP-REQ and AP-REP Functions
shishi_ap_etype_tktoptionsdata
AP-REQ and AP-REP Functions
shishi_ap_key
AP-REQ and AP-REP Functions
shishi_ap_nosubkey
AP-REQ and AP-REP Functions
shishi_ap_option2string
AP-REQ and AP-REP Functions
shishi_ap_rep
AP-REQ and AP-REP Functions
shishi_ap_rep_asn1
AP-REQ and AP-REP Functions
shishi_ap_rep_build
AP-REQ and AP-REP Functions
shishi_ap_rep_der
AP-REQ and AP-REP Functions
shishi_ap_rep_der_set
AP-REQ and AP-REP Functions
shishi_ap_rep_set
AP-REQ and AP-REP Functions
shishi_ap_rep_verify
AP-REQ and AP-REP Functions
shishi_ap_rep_verify_asn1
AP-REQ and AP-REP Functions
shishi_ap_rep_verify_der
AP-REQ and AP-REP Functions
shishi_ap_req
AP-REQ and AP-REP Functions
shishi_ap_req_asn1
AP-REQ and AP-REP Functions
shishi_ap_req_build
AP-REQ and AP-REP Functions
shishi_ap_req_decode
AP-REQ and AP-REP Functions
shishi_ap_req_der
AP-REQ and AP-REP Functions
shishi_ap_req_der_set
AP-REQ and AP-REP Functions
shishi_ap_req_process
AP-REQ and AP-REP Functions
shishi_ap_req_process_keyusage
AP-REQ and AP-REP Functions
shishi_ap_req_set
AP-REQ and AP-REP Functions
shishi_ap_set_tktoptions
AP-REQ and AP-REP Functions
shishi_ap_set_tktoptionsasn1usage
AP-REQ and AP-REP Functions
shishi_ap_set_tktoptionsdata
AP-REQ and AP-REP Functions
shishi_ap_set_tktoptionsraw
AP-REQ and AP-REP Functions
shishi_ap_string2option
AP-REQ and AP-REP Functions
shishi_ap_tkt
AP-REQ and AP-REP Functions
shishi_ap_tktoptions
AP-REQ and AP-REP Functions
shishi_ap_tktoptionsasn1usage
AP-REQ and AP-REP Functions
shishi_ap_tktoptionsdata
AP-REQ and AP-REP Functions
shishi_ap_tktoptionsraw
AP-REQ and AP-REP Functions
shishi_ap_tkt_set
AP-REQ and AP-REP Functions
shishi_arcfour
Cryptographic Functions
shishi_as
AS Functions
shishi_asn1_aprep
ASN.1 Functions
shishi_asn1_apreq
ASN.1 Functions
shishi_asn1_asrep
ASN.1 Functions
shishi_asn1_asreq
ASN.1 Functions
shishi_asn1_authenticator
ASN.1 Functions
shishi_asn1_done
ASN.1 Functions
shishi_asn1_encapreppart
ASN.1 Functions
shishi_asn1_encasreppart
ASN.1 Functions
shishi_asn1_enckdcreppart
ASN.1 Functions
shishi_asn1_encprivpart
ASN.1 Functions
shishi_asn1_encrypteddata
ASN.1 Functions
shishi_asn1_encticketpart
ASN.1 Functions
shishi_asn1_etype_info
ASN.1 Functions
shishi_asn1_etype_info2
ASN.1 Functions
shishi_asn1_krberror
ASN.1 Functions
shishi_asn1_krbsafe
ASN.1 Functions
shishi_asn1_methoddata
ASN.1 Functions
shishi_asn1_msgtype
ASN.1 Functions
shishi_asn1_padata
ASN.1 Functions
shishi_asn1_pa_enc_ts_enc
ASN.1 Functions
shishi_asn1_print
ASN.1 Functions
shishi_asn1_priv
ASN.1 Functions
shishi_asn1_read
ASN.1 Functions
shishi_asn1_read_inline
ASN.1 Functions
shishi_asn1_read_optional
ASN.1 Functions
shishi_asn1_tgsrep
ASN.1 Functions
shishi_asn1_tgsreq
ASN.1 Functions
shishi_asn1_ticket
ASN.1 Functions
shishi_asn1_to_der
ASN.1 Functions
shishi_asn1_to_der_field
ASN.1 Functions
shishi_asrep
AS/TGS Functions
shishi_asreq
AS/TGS Functions
shishi_asreq_clientrealm
AS/TGS Functions
shishi_as_check_cname
AS/TGS Functions
shishi_as_check_crealm
AS/TGS Functions
shishi_as_derive_salt
AS/TGS Functions
shishi_as_done
AS Functions
shishi_as_krberror
AS Functions
shishi_as_krberror_der
AS Functions
shishi_as_krberror_set
AS Functions
shishi_as_process
AS/TGS Functions
shishi_as_rep
AS Functions
shishi_as_rep_build
AS Functions
shishi_as_rep_der
AS Functions
shishi_as_rep_der_set
AS Functions
shishi_as_rep_process
AS Functions
shishi_as_rep_set
AS Functions
shishi_as_req
AS Functions
shishi_as_req_build
AS Functions
shishi_as_req_der
AS Functions
shishi_as_req_der_set
AS Functions
shishi_as_req_set
AS Functions
shishi_as_sendrecv
AS Functions
shishi_as_sendrecv_hint
AS Functions
shishi_as_tkt
AS Functions
shishi_as_tkt_set
AS Functions
shishi_authenticator
Authenticator Functions
shishi_authenticator_add_authorizationdata
Authenticator Functions
shishi_authenticator_add_cksum
Authenticator Functions
shishi_authenticator_add_cksum_type
Authenticator Functions
shishi_authenticator_add_random_subkey
Authenticator Functions
shishi_authenticator_add_random_subkey_etype
Authenticator Functions
shishi_authenticator_add_subkey
Authenticator Functions
shishi_authenticator_authorizationdata
Authenticator Functions
shishi_authenticator_cksum
Authenticator Functions
shishi_authenticator_clear_authorizationdata
Authenticator Functions
shishi_authenticator_client
Authenticator Functions
shishi_authenticator_clientrealm
Authenticator Functions
shishi_authenticator_client_set
Authenticator Functions
shishi_authenticator_ctime
Authenticator Functions
shishi_authenticator_ctime_set
Authenticator Functions
shishi_authenticator_cusec_get
Authenticator Functions
shishi_authenticator_cusec_set
Authenticator Functions
shishi_authenticator_from_file
Authenticator Functions
shishi_authenticator_get_subkey
Authenticator Functions
shishi_authenticator_parse
Authenticator Functions
shishi_authenticator_print
Authenticator Functions
shishi_authenticator_read
Authenticator Functions
shishi_authenticator_remove_subkey
Authenticator Functions
shishi_authenticator_save
Authenticator Functions
shishi_authenticator_seqnumber_get
Authenticator Functions
shishi_authenticator_seqnumber_remove
Authenticator Functions
shishi_authenticator_seqnumber_set
Authenticator Functions
shishi_authenticator_set_cksum
Authenticator Functions
shishi_authenticator_set_cname
Authenticator Functions
shishi_authenticator_set_crealm
Authenticator Functions
shishi_authenticator_set_subkey
Authenticator Functions
shishi_authenticator_subkey
Authenticator Functions
shishi_authenticator_to_file
Authenticator Functions
shishi_authorization_parse
Utility Functions
shishi_authorized_p
Utility Functions
shishi_authorize_k5login
Utility Functions
shishi_authorize_strcmp
Utility Functions
shishi_cfg
Initialization Functions
shishi_cfg_authorizationtype_set
Initialization Functions
shishi_cfg_clientkdcetype
Initialization Functions
shishi_cfg_clientkdcetype_fast
Initialization Functions
shishi_cfg_clientkdcetype_set
Initialization Functions
shishi_cfg_default_systemfile
Initialization Functions
shishi_cfg_default_userdirectory
Initialization Functions
shishi_cfg_default_userfile
Initialization Functions
shishi_cfg_from_file
Initialization Functions
shishi_cfg_print
Initialization Functions
shishi_cfg_userdirectory_file
Initialization Functions
shishi_checksum
Cryptographic Functions
shishi_checksum_cksumlen
Cryptographic Functions
shishi_checksum_name
Cryptographic Functions
shishi_checksum_parse
Cryptographic Functions
shishi_checksum_supported_p
Cryptographic Functions
shishi_check_version
Version Check
shishi_cipher_blocksize
Cryptographic Functions
shishi_cipher_confoundersize
Cryptographic Functions
shishi_cipher_defaultcksumtype
Cryptographic Functions
shishi_cipher_keylen
Cryptographic Functions
shishi_cipher_name
Cryptographic Functions
shishi_cipher_parse
Cryptographic Functions
shishi_cipher_randomlen
Cryptographic Functions
shishi_cipher_supported_p
Cryptographic Functions
shishi_crc
Cryptographic Functions
shishi_crypto
Cryptographic Functions
shishi_crypto_close
Cryptographic Functions
shishi_crypto_decrypt
Cryptographic Functions
shishi_crypto_encrypt
Cryptographic Functions
shishi_ctime
Utility Functions
shishi_decrypt
Cryptographic Functions
shishi_decrypt_etype
Cryptographic Functions
shishi_decrypt_iv
Cryptographic Functions
shishi_decrypt_ivupdate
Cryptographic Functions
shishi_decrypt_ivupdate_etype
Cryptographic Functions
shishi_decrypt_iv_etype
Cryptographic Functions
shishi_der2asn1
ASN.1 Functions
shishi_der2asn1_aprep
ASN.1 Functions
shishi_der2asn1_apreq
ASN.1 Functions
shishi_der2asn1_asrep
ASN.1 Functions
shishi_der2asn1_asreq
ASN.1 Functions
shishi_der2asn1_authenticator
ASN.1 Functions
shishi_der2asn1_encapreppart
ASN.1 Functions
shishi_der2asn1_encasreppart
ASN.1 Functions
shishi_der2asn1_enckdcreppart
ASN.1 Functions
shishi_der2asn1_encprivpart
ASN.1 Functions
shishi_der2asn1_enctgsreppart
ASN.1 Functions
shishi_der2asn1_encticketpart
ASN.1 Functions
shishi_der2asn1_etype_info
ASN.1 Functions
shishi_der2asn1_etype_info2
ASN.1 Functions
shishi_der2asn1_kdcrep
ASN.1 Functions
shishi_der2asn1_kdcreq
ASN.1 Functions
shishi_der2asn1_krberror
ASN.1 Functions
shishi_der2asn1_krbsafe
ASN.1 Functions
shishi_der2asn1_methoddata
ASN.1 Functions
shishi_der2asn1_padata
ASN.1 Functions
shishi_der2asn1_priv
ASN.1 Functions
shishi_der2asn1_tgsrep
ASN.1 Functions
shishi_der2asn1_tgsreq
ASN.1 Functions
shishi_der2asn1_ticket
ASN.1 Functions
shishi_derive_default_salt
Utility Functions
shishi_der_msgtype
ASN.1 Functions
shishi_des
Cryptographic Functions
shishi_des_cbc_mac
Cryptographic Functions
shishi_dk
Cryptographic Functions
shishi_done
Initialization Functions
shishi_dr
Cryptographic Functions
shishi_encapreppart
AP-REQ and AP-REP Functions
shishi_encapreppart_ctime
AP-REQ and AP-REP Functions
shishi_encapreppart_ctime_set
AP-REQ and AP-REP Functions
shishi_encapreppart_cusec_get
AP-REQ and AP-REP Functions
shishi_encapreppart_cusec_set
AP-REQ and AP-REP Functions
shishi_encapreppart_from_file
AP-REQ and AP-REP Functions
shishi_encapreppart_get_key
AP-REQ and AP-REP Functions
shishi_encapreppart_parse
AP-REQ and AP-REP Functions
shishi_encapreppart_print
AP-REQ and AP-REP Functions
shishi_encapreppart_read
AP-REQ and AP-REP Functions
shishi_encapreppart_save
AP-REQ and AP-REP Functions
shishi_encapreppart_seqnumber_get
AP-REQ and AP-REP Functions
shishi_encapreppart_seqnumber_remove
AP-REQ and AP-REP Functions
shishi_encapreppart_seqnumber_set
AP-REQ and AP-REP Functions
shishi_encapreppart_time_copy
AP-REQ and AP-REP Functions
shishi_encapreppart_to_file
AP-REQ and AP-REP Functions
shishi_enckdcreppart_authtime_set
AS/TGS Functions
shishi_enckdcreppart_endtime_set
AS/TGS Functions
shishi_enckdcreppart_flags_set
AS/TGS Functions
shishi_enckdcreppart_get_key
AS/TGS Functions
shishi_enckdcreppart_key_set
AS/TGS Functions
shishi_enckdcreppart_nonce_set
AS/TGS Functions
shishi_enckdcreppart_populate_encticketpart
AS/TGS Functions
shishi_enckdcreppart_renew_till_set
AS/TGS Functions
shishi_enckdcreppart_sname_set
AS/TGS Functions
shishi_enckdcreppart_srealm_set
AS/TGS Functions
shishi_enckdcreppart_starttime_set
AS/TGS Functions
shishi_encprivpart_set_user_data
SAFE and PRIV Functions
shishi_encprivpart_user_data
SAFE and PRIV Functions
shishi_encrypt
Cryptographic Functions
shishi_encrypt_etype
Cryptographic Functions
shishi_encrypt_iv
Cryptographic Functions
shishi_encrypt_ivupdate
Cryptographic Functions
shishi_encrypt_ivupdate_etype
Cryptographic Functions
shishi_encrypt_iv_etype
Cryptographic Functions
shishi_encticketpart_authtime_set
Ticket (ASN.1) Functions
shishi_encticketpart_client
Ticket (ASN.1) Functions
shishi_encticketpart_clientrealm
Ticket (ASN.1) Functions
shishi_encticketpart_cname_set
Ticket (ASN.1) Functions
shishi_encticketpart_crealm_set
Ticket (ASN.1) Functions
shishi_encticketpart_endtime_set
Ticket (ASN.1) Functions
shishi_encticketpart_flags_set
Ticket (ASN.1) Functions
shishi_encticketpart_get_key
Ticket (ASN.1) Functions
shishi_encticketpart_key_set
Ticket (ASN.1) Functions
shishi_encticketpart_transited_set
Ticket (ASN.1) Functions
shishi_error
Error Functions
shishi_error_clear
Error Functions
shishi_error_outputtype
Error Functions
shishi_error_printf
Error Functions
shishi_error_set
Error Functions
shishi_error_set_outputtype
Error Functions
shishi_generalize_ctime
Utility Functions
shishi_generalize_now
Utility Functions
shishi_generalize_time
Utility Functions
shishi_hmac_md5
Cryptographic Functions
shishi_hmac_sha1
Cryptographic Functions
shishi_hostkeys_default_file
Cryptographic Functions
shishi_hostkeys_default_file_set
Cryptographic Functions
shishi_hostkeys_for_localservice
Cryptographic Functions
shishi_hostkeys_for_localservicerealm
Cryptographic Functions
shishi_hostkeys_for_server
Cryptographic Functions
shishi_hostkeys_for_serverrealm
Cryptographic Functions
shishi_info
Error Functions
shishi_init
Initialization Functions
shishi_init_server
Initialization Functions
shishi_init_server_with_paths
Initialization Functions
shishi_init_with_paths
Initialization Functions
shishi_kdcrep_add_enc_part
AS/TGS Functions
shishi_kdcrep_clear_padata
AS/TGS Functions
shishi_kdcrep_client_set
AS/TGS Functions
shishi_kdcrep_cname_set
AS/TGS Functions
shishi_kdcrep_crealm_set
AS/TGS Functions
shishi_kdcrep_from_file
AS/TGS Functions
shishi_kdcrep_get_enc_part_etype
AS/TGS Functions
shishi_kdcrep_get_ticket
AS/TGS Functions
shishi_kdcrep_parse
AS/TGS Functions
shishi_kdcrep_print
AS/TGS Functions
shishi_kdcrep_read
AS/TGS Functions
shishi_kdcrep_save
AS/TGS Functions
shishi_kdcrep_set_enc_part
AS/TGS Functions
shishi_kdcrep_set_ticket
AS/TGS Functions
shishi_kdcrep_to_file
AS/TGS Functions
shishi_kdcreq_add_padata
AS/TGS Functions
shishi_kdcreq_add_padata_preauth
AS/TGS Functions
shishi_kdcreq_add_padata_tgs
AS/TGS Functions
shishi_kdcreq_allow_postdate_p
AS/TGS Functions
shishi_kdcreq_clear_padata
AS/TGS Functions
shishi_kdcreq_client
AS/TGS Functions
shishi_kdcreq_disable_transited_check_p
AS/TGS Functions
shishi_kdcreq_enc_tkt_in_skey_p
AS/TGS Functions
shishi_kdcreq_etype
AS/TGS Functions
shishi_kdcreq_forwardable_p
AS/TGS Functions
shishi_kdcreq_forwarded_p
AS/TGS Functions
shishi_kdcreq_from_file
AS/TGS Functions
shishi_kdcreq_get_padata
AS/TGS Functions
shishi_kdcreq_get_padata_tgs
AS/TGS Functions
shishi_kdcreq_nonce_set
AS/TGS Functions
shishi_kdcreq_options
AS/TGS Functions
shishi_kdcreq_options_add
AS/TGS Functions
shishi_kdcreq_options_set
AS/TGS Functions
shishi_kdcreq_parse
AS/TGS Functions
shishi_kdcreq_postdated_p
AS/TGS Functions
shishi_kdcreq_print
AS/TGS Functions
shishi_kdcreq_proxiable_p
AS/TGS Functions
shishi_kdcreq_proxy_p
AS/TGS Functions
shishi_kdcreq_read
AS/TGS Functions
shishi_kdcreq_realm
AS/TGS Functions
shishi_kdcreq_renewable_ok_p
AS/TGS Functions
shishi_kdcreq_renewable_p
AS/TGS Functions
shishi_kdcreq_renew_p
AS/TGS Functions
shishi_kdcreq_save
AS/TGS Functions
shishi_kdcreq_sendrecv
AS/TGS Functions
shishi_kdcreq_sendrecv_hint
AS/TGS Functions
shishi_kdcreq_server
AS/TGS Functions
shishi_kdcreq_set_cname
AS/TGS Functions
shishi_kdcreq_set_etype
AS/TGS Functions
shishi_kdcreq_set_realm
AS/TGS Functions
shishi_kdcreq_set_sname
AS/TGS Functions
shishi_kdcreq_till
AS/TGS Functions
shishi_kdcreq_tillc
AS/TGS Functions
shishi_kdcreq_to_file
AS/TGS Functions
shishi_kdcreq_validate_p
AS/TGS Functions
shishi_kdc_check_nonce
AS/TGS Functions
shishi_kdc_copy_cname
AS/TGS Functions
shishi_kdc_copy_crealm
AS/TGS Functions
shishi_kdc_copy_nonce
AS/TGS Functions
shishi_kdc_process
AS/TGS Functions
shishi_key
Cryptographic Functions
shishi_keys
Cryptographic Functions
shishi_keys_add
Cryptographic Functions
shishi_keys_done
Cryptographic Functions
shishi_keys_for_localservicerealm_in_file
Cryptographic Functions
shishi_keys_for_serverrealm_in_file
Cryptographic Functions
shishi_keys_for_server_in_file
Cryptographic Functions
shishi_keys_from_file
Cryptographic Functions
shishi_keys_nth
Cryptographic Functions
shishi_keys_print
Cryptographic Functions
shishi_keys_remove
Cryptographic Functions
shishi_keys_size
Cryptographic Functions
shishi_keys_to_file
Cryptographic Functions
shishi_key_copy
Cryptographic Functions
shishi_key_done
Cryptographic Functions
shishi_key_from_base64
Cryptographic Functions
shishi_key_from_name
Cryptographic Functions
shishi_key_from_random
Cryptographic Functions
shishi_key_from_string
Cryptographic Functions
shishi_key_from_value
Cryptographic Functions
shishi_key_length
Cryptographic Functions
shishi_key_name
Cryptographic Functions
shishi_key_principal
Cryptographic Functions
shishi_key_principal_set
Cryptographic Functions
shishi_key_random
Cryptographic Functions
shishi_key_realm
Cryptographic Functions
shishi_key_realm_set
Cryptographic Functions
shishi_key_timestamp
Cryptographic Functions
shishi_key_timestamp_set
Cryptographic Functions
shishi_key_type
Cryptographic Functions
shishi_key_type_set
Cryptographic Functions
shishi_key_value
Cryptographic Functions
shishi_key_value_set
Cryptographic Functions
shishi_key_version
Cryptographic Functions
shishi_key_version_set
Cryptographic Functions
shishi_krberror
KRB-ERROR Functions
shishi_krberror_build
KRB-ERROR Functions
shishi_krberror_client
KRB-ERROR Functions
shishi_krberror_client_set
KRB-ERROR Functions
shishi_krberror_crealm
KRB-ERROR Functions
shishi_krberror_ctime
KRB-ERROR Functions
shishi_krberror_ctime_set
KRB-ERROR Functions
shishi_krberror_cusec
KRB-ERROR Functions
shishi_krberror_cusec_set
KRB-ERROR Functions
shishi_krberror_der
KRB-ERROR Functions
shishi_krberror_edata
KRB-ERROR Functions
shishi_krberror_errorcode
KRB-ERROR Functions
shishi_krberror_errorcode_fast
KRB-ERROR Functions
shishi_krberror_errorcode_message
KRB-ERROR Functions
shishi_krberror_errorcode_set
KRB-ERROR Functions
shishi_krberror_etext
KRB-ERROR Functions
shishi_krberror_from_file
KRB-ERROR Functions
shishi_krberror_message
KRB-ERROR Functions
shishi_krberror_methoddata
KRB-ERROR Functions
shishi_krberror_parse
KRB-ERROR Functions
shishi_krberror_pretty_print
KRB-ERROR Functions
shishi_krberror_print
KRB-ERROR Functions
shishi_krberror_read
KRB-ERROR Functions
shishi_krberror_realm
KRB-ERROR Functions
shishi_krberror_remove_cname
KRB-ERROR Functions
shishi_krberror_remove_crealm
KRB-ERROR Functions
shishi_krberror_remove_ctime
KRB-ERROR Functions
shishi_krberror_remove_cusec
KRB-ERROR Functions
shishi_krberror_remove_edata
KRB-ERROR Functions
shishi_krberror_remove_etext
KRB-ERROR Functions
shishi_krberror_remove_sname
KRB-ERROR Functions
shishi_krberror_save
KRB-ERROR Functions
shishi_krberror_server
KRB-ERROR Functions
shishi_krberror_server_set
KRB-ERROR Functions
shishi_krberror_set_cname
KRB-ERROR Functions
shishi_krberror_set_crealm
KRB-ERROR Functions
shishi_krberror_set_edata
KRB-ERROR Functions
shishi_krberror_set_etext
KRB-ERROR Functions
shishi_krberror_set_realm
KRB-ERROR Functions
shishi_krberror_set_sname
KRB-ERROR Functions
shishi_krberror_stime
KRB-ERROR Functions
shishi_krberror_stime_set
KRB-ERROR Functions
shishi_krberror_susec
KRB-ERROR Functions
shishi_krberror_susec_set
KRB-ERROR Functions
shishi_krberror_to_file
KRB-ERROR Functions
shishi_md4
Cryptographic Functions
shishi_md5
Cryptographic Functions
shishi_n_fold
Cryptographic Functions
shishi_parse_name
Utility Functions
shishi_pbkdf2_sha1
Cryptographic Functions
shishi_principal_default
Utility Functions
shishi_principal_default_guess
Utility Functions
shishi_principal_default_set
Utility Functions
shishi_principal_name
Utility Functions
shishi_principal_name_realm
Utility Functions
shishi_principal_name_set
Utility Functions
shishi_principal_set
Utility Functions
shishi_priv
SAFE and PRIV Functions
shishi_priv_build
SAFE and PRIV Functions
shishi_priv_done
SAFE and PRIV Functions
shishi_priv_encprivpart
SAFE and PRIV Functions
shishi_priv_encprivpart_der
SAFE and PRIV Functions
shishi_priv_encprivpart_der_set
SAFE and PRIV Functions
shishi_priv_encprivpart_set
SAFE and PRIV Functions
shishi_priv_enc_part_etype
SAFE and PRIV Functions
shishi_priv_from_file
SAFE and PRIV Functions
shishi_priv_key
SAFE and PRIV Functions
shishi_priv_key_set
SAFE and PRIV Functions
shishi_priv_parse
SAFE and PRIV Functions
shishi_priv_print
SAFE and PRIV Functions
shishi_priv_priv
SAFE and PRIV Functions
shishi_priv_priv_der
SAFE and PRIV Functions
shishi_priv_priv_der_set
SAFE and PRIV Functions
shishi_priv_priv_set
SAFE and PRIV Functions
shishi_priv_process
SAFE and PRIV Functions
shishi_priv_read
SAFE and PRIV Functions
shishi_priv_save
SAFE and PRIV Functions
shishi_priv_set_enc_part
SAFE and PRIV Functions
shishi_priv_to_file
SAFE and PRIV Functions
shishi_prompt_password
Utility Functions
shishi_prompt_password_callback_get
Utility Functions
shishi_prompt_password_callback_set
Utility Functions
shishi_randomize
Cryptographic Functions
shishi_random_to_key
Cryptographic Functions
shishi_realm_default
Utility Functions
shishi_realm_default_guess
Utility Functions
shishi_realm_default_set
Utility Functions
shishi_realm_for_server
Utility Functions
shishi_realm_for_server_dns
Utility Functions
shishi_realm_for_server_file
Utility Functions
shishi_resolv
Utility Functions
shishi_resolv_free
Utility Functions
shishi_safe
SAFE and PRIV Functions
shishi_safe_build
SAFE and PRIV Functions
shishi_safe_cksum
SAFE and PRIV Functions
shishi_safe_done
SAFE and PRIV Functions
shishi_safe_from_file
SAFE and PRIV Functions
shishi_safe_key
SAFE and PRIV Functions
shishi_safe_key_set
SAFE and PRIV Functions
shishi_safe_parse
SAFE and PRIV Functions
shishi_safe_print
SAFE and PRIV Functions
shishi_safe_read
SAFE and PRIV Functions
shishi_safe_safe
SAFE and PRIV Functions
shishi_safe_safe_der
SAFE and PRIV Functions
shishi_safe_safe_der_set
SAFE and PRIV Functions
shishi_safe_safe_set
SAFE and PRIV Functions
shishi_safe_save
SAFE and PRIV Functions
shishi_safe_set_cksum
SAFE and PRIV Functions
shishi_safe_set_user_data
SAFE and PRIV Functions
shishi_safe_to_file
SAFE and PRIV Functions
shishi_safe_user_data
SAFE and PRIV Functions
shishi_safe_verify
SAFE and PRIV Functions
shishi_server
Initialization Functions
shishi_server_for_local_service
Utility Functions
shishi_strerror
Error Functions
shishi_string_to_key
Cryptographic Functions
shishi_tgs
TGS Functions
shishi_tgsrep
AS/TGS Functions
shishi_tgsreq
AS/TGS Functions
shishi_tgs_ap
TGS Functions
shishi_tgs_done
TGS Functions
shishi_tgs_krberror
TGS Functions
shishi_tgs_krberror_der
TGS Functions
shishi_tgs_krberror_set
TGS Functions
shishi_tgs_process
AS/TGS Functions
shishi_tgs_rep
TGS Functions
shishi_tgs_rep_build
TGS Functions
shishi_tgs_rep_der
TGS Functions
shishi_tgs_rep_process
TGS Functions
shishi_tgs_req
TGS Functions
shishi_tgs_req_build
TGS Functions
shishi_tgs_req_der
TGS Functions
shishi_tgs_req_der_set
TGS Functions
shishi_tgs_req_process
TGS Functions
shishi_tgs_req_set
TGS Functions
shishi_tgs_sendrecv
TGS Functions
shishi_tgs_sendrecv_hint
TGS Functions
shishi_tgs_set_realm
TGS Functions
shishi_tgs_set_realmserver
TGS Functions
shishi_tgs_set_server
TGS Functions
shishi_tgs_tgtkt
TGS Functions
shishi_tgs_tgtkt_set
TGS Functions
shishi_tgs_tkt
TGS Functions
shishi_tgs_tkt_set
TGS Functions
shishi_ticket
Ticket (ASN.1) Functions
shishi_ticket_add_enc_part
Ticket (ASN.1) Functions
shishi_ticket_get_enc_part_etype
Ticket (ASN.1) Functions
shishi_ticket_realm_get
Ticket (ASN.1) Functions
shishi_ticket_realm_set
Ticket (ASN.1) Functions
shishi_ticket_server
Ticket (ASN.1) Functions
shishi_ticket_set_enc_part
Ticket (ASN.1) Functions
shishi_ticket_sname_set
Ticket (ASN.1) Functions
shishi_time
Utility Functions
shishi_tkt
Ticket Functions
shishi_tkt2
Ticket Functions
shishi_tkts
Ticket Set Functions
shishi_tkts_add
Ticket Set Functions
shishi_tkts_default
Ticket Set Functions
shishi_tkts_default_file
Ticket Set Functions
shishi_tkts_default_file_guess
Ticket Set Functions
shishi_tkts_default_file_set
Ticket Set Functions
shishi_tkts_done
Ticket Set Functions
shishi_tkts_expire
Ticket Set Functions
shishi_tkts_find
Ticket Set Functions
shishi_tkts_find_for_clientserver
Ticket Set Functions
shishi_tkts_find_for_server
Ticket Set Functions
shishi_tkts_from_file
Ticket Set Functions
shishi_tkts_get
Ticket Set Functions
shishi_tkts_get_for_clientserver
Ticket Set Functions
shishi_tkts_get_for_localservicepasswd
Ticket Set Functions
shishi_tkts_get_for_server
Ticket Set Functions
shishi_tkts_get_tgs
Ticket Set Functions
shishi_tkts_get_tgt
Ticket Set Functions
shishi_tkts_new
Ticket Set Functions
shishi_tkts_nth
Ticket Set Functions
shishi_tkts_print
Ticket Set Functions
shishi_tkts_print_for_service
Ticket Set Functions
shishi_tkts_read
Ticket Set Functions
shishi_tkts_remove
Ticket Set Functions
shishi_tkts_size
Ticket Set Functions
shishi_tkts_to_file
Ticket Set Functions
shishi_tkts_write
Ticket Set Functions
shishi_tkt_authctime
Ticket Functions
shishi_tkt_client
Ticket Functions
shishi_tkt_clientrealm
Ticket Functions
shishi_tkt_clientrealm_p
Ticket Functions
shishi_tkt_client_p
Ticket Functions
shishi_tkt_done
Ticket Functions
shishi_tkt_enckdcreppart
Ticket Functions
shishi_tkt_enckdcreppart_set
Ticket Functions
shishi_tkt_encticketpart
Ticket Functions
shishi_tkt_encticketpart_set
Ticket Functions
shishi_tkt_endctime
Ticket Functions
shishi_tkt_expired_p
Ticket Functions
shishi_tkt_flags
Ticket Functions
shishi_tkt_flags_add
Ticket Functions
shishi_tkt_flags_set
Ticket Functions
shishi_tkt_forwardable_p
Ticket Functions
shishi_tkt_forwarded_p
Ticket Functions
shishi_tkt_hw_authent_p
Ticket Functions
shishi_tkt_initial_p
Ticket Functions
shishi_tkt_invalid_p
Ticket Functions
shishi_tkt_kdcrep
Ticket Functions
shishi_tkt_key
Ticket Functions
shishi_tkt_keytype
Ticket Functions
shishi_tkt_keytype_fast
Ticket Functions
shishi_tkt_keytype_p
Ticket Functions
shishi_tkt_key_set
Ticket Functions
shishi_tkt_lastreqc
Ticket Functions
shishi_tkt_lastreq_pretty_print
Ticket Functions
shishi_tkt_match_p
Ticket Set Functions
shishi_tkt_may_postdate_p
Ticket Functions
shishi_tkt_ok_as_delegate_p
Ticket Functions
shishi_tkt_postdated_p
Ticket Functions
shishi_tkt_pretty_print
Ticket Functions
shishi_tkt_pre_authent_p
Ticket Functions
shishi_tkt_proxiable_p
Ticket Functions
shishi_tkt_proxy_p
Ticket Functions
shishi_tkt_realm
Ticket Functions
shishi_tkt_renewable_p
Ticket Functions
shishi_tkt_renew_tillc
Ticket Functions
shishi_tkt_server
Ticket Functions
shishi_tkt_server_p
Ticket Functions
shishi_tkt_startctime
Ticket Functions
shishi_tkt_ticket
Ticket Functions
shishi_tkt_ticket_set
Ticket Functions
shishi_tkt_transited_policy_checked_p
Ticket Functions
shishi_tkt_valid_at_time_p
Ticket Functions
shishi_tkt_valid_now_p
Ticket Functions
shishi_verbose
Error Functions
shishi_verify
Cryptographic Functions
shishi_warn
Error Functions
shishi_x509ca_default_file
X.509 Functions
shishi_x509ca_default_file_guess
X.509 Functions
shishi_x509ca_default_file_set
X.509 Functions
shishi_x509cert_default_file
X.509 Functions
shishi_x509cert_default_file_guess
X.509 Functions
shishi_x509cert_default_file_set
X.509 Functions
shishi_x509key_default_file
X.509 Functions
shishi_x509key_default_file_guess
X.509 Functions
shishi_x509key_default_file_set
X.509 Functions
this
in date strings
Relative items in date strings
today
in date strings
Relative items in date strings
tomorrow
in date strings
Relative items in date strings
week
in date strings
Relative items in date strings
year
in date strings
Relative items in date strings
yesterday
in date strings
Relative items in date strings
Jump to:
Previous:
Function and Data Index
, Up:
Top
Contents
][
Index
Concept Index
Jump to:
Index Entry
Section
3DES
Cryptographic Overview
abbreviations for months
Calendar date items
AES
Cryptographic Overview
AES-CCM
Telnet encryption with AES-CCM
AIX
Supported Platforms
anonymous tls
Kerberos via TLS
Application Programming Interface (API)
Programming Manual
ARCFOUR
Cryptographic Overview
authenticated tls
Kerberos via TLS
Authentication
Glossary of terms
Authentication header
Glossary of terms
Authentication path
Glossary of terms
Authenticator
Glossary of terms
Authorization
Glossary of terms
authors of
parse_datetime
Authors of parse_datetime
Autoconf tests
Autoconf tests
basic authorization
Kerberized rsh and rlogin
beginning of time, for POSIX
Seconds since the Epoch
Bellovin, Steven M.
Authors of parse_datetime
Berets, Jim
Authors of parse_datetime
Berry, K.
Authors of parse_datetime
calendar date item
Calendar date items
Capability
Glossary of terms
case, ignored in dates
General date syntax
certificate authority (CA)
Kerberos via TLS
Ciphertext
Glossary of terms
Client
Glossary of terms
client authentication
Kerberos via TLS
combined date and time of day item
Combined date and time of day items
comments, in dates
General date syntax
Compiling your application
Building the source
concurrent writers
Multiple servers
configuration file
Shishi Configuration
Configure tests
Autoconf tests
Contributing
Contributing
copying information
Copying Information
credential cache, file format of
The Credential Cache Binary File Format
Credentials
Glossary of terms
database definition
Shisa Configuration
Database interface
Kerberos Database Functions
date and time of day format, ISO 8601
Combined date and time of day items
date format, ISO 8601
Calendar date items
date input formats
Date input formats
day of week item
Day of week items
Debian
Supported Platforms
Debian
Supported Platforms
DES
Cryptographic Overview
Diffie Hellman key exchange
Kerberos via TLS
displacement of dates
Relative items in date strings
Downloading and Installing
Eggert, Paul
Authors of parse_datetime
eklogin
Kerberized rsh and rlogin
Encryption Type (etype)
Glossary of terms
End-user Shishi usage
User Manual
Epoch, for POSIX
Seconds since the Epoch
Error Handling
Error Handling
Examples
Examples
fail over
Multiple servers
FDL, GNU Free Documentation License
GNU Free Documentation License
FreeBSD
Supported Platforms
general date syntax
General date syntax
Generic Security Service
Generic Security Service
GNUTLS
Kerberos via TLS
GSS-API
Generic Security Service
GSSLib
Generic Security Service
Hacking
Contributing
High Availability
Multiple servers
HP-UX
Supported Platforms
Installation
Downloading and Installing
IPSEC
Multiple servers
IRIX
Supported Platforms
ISO 8601 date and time of day format
Combined date and time of day items
ISO 8601 date format
Calendar date items
items in date strings
General date syntax
k5login authorization
Kerberized rsh and rlogin
KCMDV0.2
Kerberized rsh and rlogin
KCMDV0.3
Kerberized rsh and rlogin
KDC
Glossary of terms
Kerberos
Glossary of terms
Kerberos Ticket
Glossary of terms
Key Version Number (kvno)
Glossary of terms
keytab, file format of
The Keytab Binary File Format
language, in dates
General date syntax
language, in dates
General date syntax
LDAP
Multiple servers
leap seconds
General date syntax
leap seconds
Time of day items
leap seconds
Seconds since the Epoch
MacKenzie, David
Authors of parse_datetime
MacOS X
Supported Platforms
Mandrake
Supported Platforms
master server
Multiple servers
Meyering, Jim
Authors of parse_datetime
minutes, time zone correction by
Time of day items
month names in date strings
Calendar date items
months, written-out
General date syntax
Motorola Coldfire
Supported Platforms
NetBSD
Supported Platforms
NFS
Multiple servers
numbers, written-out
General date syntax
OpenBSD
Supported Platforms
ordinal numbers
General date syntax
Pinard, F.
Authors of parse_datetime
Plaintext
Glossary of terms
Principal
Glossary of terms
Principal identifier
Glossary of terms
Protocol Extensions
Protocol Extensions
pure numbers in date strings
Pure numbers in date strings
RedHat
Supported Platforms
RedHat
Supported Platforms
RedHat
Supported Platforms
RedHat Advanced Server
Supported Platforms
relative items in date strings
Relative items in date strings
remote databases
Multiple servers
Reporting Bugs
Bug Reports
rsh and rlogin
Kerberized rsh and rlogin
rsync
Multiple servers
Salz, Rich
Authors of parse_datetime
Seal
Glossary of terms
secondary server
Multiple servers
Secret key
Glossary of terms
Server
Glossary of terms
server authentication
Kerberos via TLS
Service
Glossary of terms
Session key
Glossary of terms
Shisa API
Kerberos Database Functions
Solaris
Supported Platforms
specifying user database
Shisa Configuration
SQL
Multiple servers
STARTTLS
Kerberos via TLS
Sub-session key
Glossary of terms
SuSE
Supported Platforms
SuSE Linux
Supported Platforms
SuSE Linux
Supported Platforms
Telnet encryption
Telnet encryption with AES-CCM
Ticket
Glossary of terms
time of day item
Time of day items
time zone correction
Time of day items
time zone item
General date syntax
time zone item
Time zone items
TLS
Kerberos via TLS
tls resume
Kerberos via TLS
Tru64
Supported Platforms
uClibc
Supported Platforms
uClinux
Supported Platforms
user database definition
Shisa Configuration
X.509 authentication
Kerberos via TLS
Jump to:
Short Table of Contents
1 Introduction
2 User Manual
3 Administration Manual
4 Reference Manual
5 Programming Manual
6 Acknowledgements
Appendix A Criticism of Kerberos
Appendix B Protocol Extensions
Appendix C Copying Information
Function and Data Index
Concept Index
Table of Contents
1 Introduction
1.1 Getting Started
1.2 Features and Status
1.3 Overview
1.4 Cryptographic Overview
1.5 Supported Platforms
1.6 Getting help
1.7 Downloading and Installing
1.8 Bug Reports
1.9 Contributing
2 User Manual
2.1 Proxiable and Proxy Tickets
2.2 Forwardable and Forwarded Tickets
3 Administration Manual
3.1 Introduction to Shisa
3.2 Configuring Shisa
3.3 Using Shisa
3.4 Starting Shishid
3.5 Configuring DNS for KDC
3.5.1 DNS vs. Kerberos - Case Sensitivity of Realm Names
3.5.2 Overview - KDC location information
3.5.3 Example - KDC location information
3.5.4 Security considerations
3.6 Kerberos via TLS
3.6.1 Setting up TLS resume
3.6.2 Setting up Anonymous TLS
3.6.3 Setting up X.509 authenticated TLS
3.6.3.1 Create a Kerberos Certificate Authority
3.6.3.2 Create a Kerberos KDC Certificate
3.6.3.3 Create a Kerberos Client Certificate
3.6.3.4 Starting KDC with X.509 authentication support
3.7 Multiple servers
3.8 Developer information
4 Reference Manual
4.1 Environmental Assumptions
4.2 Glossary of terms
4.3 Realm and Principal Naming
4.3.1 Realm Names
4.3.2 Principal Names
4.3.2.1 Name of server principals
4.3.2.2 Name of the TGS
4.3.3 Choosing a principal with which to communicate
4.3.4 Principal Name Form
4.4 Shishi Configuration
4.4.1 ‘
default-realm
4.4.2 ‘
default-principal
4.4.3 ‘
client-kdc-etypes
4.4.4 ‘
verbose
’, ‘
verbose-asn1
’, ‘
verbose-noise
’, ‘
verbose-crypto
’, ‘
verbose-crypto-noise
4.4.5 ‘
realm-kdc
4.4.6 ‘
server-realm
4.4.7 ‘
kdc-timeout
’, ‘
kdc-retries
4.4.8 ‘
stringprocess
4.4.9 ‘
ticket-life
4.4.10 ‘
renew-life
4.5 Shisa Configuration
4.5.1 ‘
db
4.6 Parameters for shishi
4.7 Parameters for shishid
4.8 Parameters for shisa
4.9 Environment variables
4.10 Date input formats
4.10.1 General date syntax
4.10.2 Calendar date items
4.10.3 Time of day items
4.10.4 Time zone items
4.10.5 Combined date and time of day items
4.10.6 Day of week items
4.10.7 Relative items in date strings
4.10.8 Pure numbers in date strings
4.10.9 Seconds since the Epoch
4.10.10 Specifying time zone rules
4.10.11 Authors of
parse_datetime
5 Programming Manual
5.1 Preparation
5.1.1 Header
5.1.2 Initialization
5.1.3 Version Check
5.1.4 Building the source
5.1.5 Autoconf tests
5.1.5.1 Autoconf test via ‘
pkg-config
5.1.5.2 Standalone Autoconf test using Libtool
5.1.5.3 Standalone Autoconf test
5.2 Initialization Functions
5.3 Ticket Set Functions
5.4 AP-REQ and AP-REP Functions
5.5 SAFE and PRIV Functions
5.6 Ticket Functions
5.7 AS Functions
5.8 TGS Functions
5.9 Ticket (ASN.1) Functions
5.10 AS/TGS Functions
5.11 Authenticator Functions
5.12 KRB-ERROR Functions
5.13 Cryptographic Functions
5.14 X.509 Functions
5.15 Utility Functions
5.16 ASN.1 Functions
5.17 Error Handling
5.17.1 Error Values
5.17.2 Error Functions
5.18 Examples
5.19 Kerberos Database Functions
5.20 Generic Security Service
6 Acknowledgements
Appendix A Criticism of Kerberos
Appendix B Protocol Extensions
B.1 STARTTLS protected KDC exchanges
B.1.1 TCP/IP transport with TLS upgrade (STARTTLS)
B.1.2 Extensible typed hole based on reserved high bit
B.1.3 STARTTLS requested by client (extension mode 1)
B.1.4 STARTTLS request accepted by server (extension mode 2)
B.1.5 Proceeding after successful TLS negotiation
B.1.6 Proceeding after failed TLS negotiation
B.1.7 Interaction with KDC addresses in DNS
B.1.8 Using TLS authentication logic in Kerberos
B.1.9 Security considerations
B.2 Telnet encryption with AES-CCM
B.2.1 Command Names and Codes
B.2.2 Command Meanings
B.2.3 Implementation Rules
B.2.4 Integration with the AUTHENTICATION telnet option
B.2.5 Security Considerations
B.2.5.1 Telnet Encryption Protocol Security Considerations
B.2.5.2 AES-CCM Security Considerations
B.2.6 Acknowledgments
B.3 Kerberized rsh and rlogin
B.3.1 Establish connection
B.3.2 Kerberos identification
B.3.3 Kerberos authentication
B.3.4 Extended authentication
B.3.5 Window size
B.3.6 End of authentication
B.3.7 Encryption
B.3.8 KCMDV0.3
B.3.9 MIT/Heimdal authorization
B.4 Key as initialization vector
B.5 The Keytab Binary File Format
B.6 The Credential Cache Binary File Format
Appendix C Copying Information
C.1 GNU Free Documentation License
Function and Data Index
Concept Index
Footnotes
(1)
The text is a lightly adapted version of the
introduction section from RFC 1510 by J. Kohl and C. Neuman, September
1993, copyright likely owned by the RFC 1510 authors or some
contributor.
(2)
(3)
(4)
And besides, Shishi is
intended to work on non-Unix platforms as well.
(5)
The post is copyrighted by David Wagner,
included here with permission, the canonical location is