libkrb5(3) libkrb5(3)
NAME [Toc] [Back]
libkrb5 - Kerberos client libraries (libkrb5, libk5crypto, libcom_err)
SYNOPSIS [Toc] [Back]
32-Bit Itanium(R)-based Libraries
/usr/lib/hpux32/libkrb5.so
/usr/lib/hpux32/libcom_err.so
/usr/lib/hpux32/libk5crypto.so
64-Bit Itanium-based Libraries
/usr/lib/hpux64/libkrb5.so
/usr/lib/hpux64/libcom_err.so
/usr/lib/hpux64/libk5crypto.so
32-Bit PA-RISC Libraries
/usr/lib/libkrb5.sl
/usr/lib/libcom_err.sl
/usr/lib/libk5crypto.sl
64-Bit PA-RISC Libraries
/usr/lib/pa20_64/libkrb5.sl
/usr/lib/pa20_64/libcom_err.sl
/usr/lib/pa20_64/libk5crypto.sl
DESCRIPTION [Toc] [Back]
Kerberos is a network authentication protocol developed at MIT. This
is now an IETF standard RFC 1510, the Kerberos Network Authentication
Service (V5). The shared libraries, libkrb5.so/libkrb5.sl,
libcom_err.so/libcom_err.sl and libk5crypto.so/libk5crypto.sl support
authentication, integrity and confidentiality services as per the
Kerberos V5 specification.
Kerberos performs authentication as a trusted third-party
authentication service by using conventional (shared secret key)
cryptography mechanism. It provides a means of verifying the
identities of principals, without relying on authentication by the
host operating system and without basing trust on host addresses.
This protocol works without requiring the physical security of all the
hosts on the network under the assumption that packets transmitting
over the network can be read, modified and inserted at will.
libkrb5.so/libkrb5.sl is the main Kerberos library, which provides
APIs for authentication, verifying tickets, creating authenticator,
Hewlett-Packard Company - 1 - HP-UX 11i Version 2: August 2003
libkrb5(3) libkrb5(3)
context management, cache and replay cache management, keytab file
management, memory management, principal name style mapping and
operating system specific calls. The <krb5.h> header file should be
included in the application that uses APIs from libkrb5.so/libkrb5.sl
library.
libk5crypto.so/libk5crypto.sl, which is linked to
libkrb5.so/libkrb5.sl, will provide the encryption and decryption
APIs. A user should not link this library directly with an
application. In order to add authentication, an application may need
to call one or more APIs of the Kerberos library, which results in the
transmission of the necessary messages to achieve authentication.
libcom_err.so/libcom_err.sl implements Kerberos library error code
tables. There are separate error code tables for database, magic
numbers and ASN.1 APIs. Based on the failure in the API, the user may
get an error from these tables using the appropriate com_err() API.
The <com_err.h> header file should be included in the application that
uses routines from the libcom_err.so/libcom_err.sl library.
Executable files must be linked with -lcom_err in order to cause the
com_err library to be included.
The functionalities of the APIs implemented in Kerberos client
libraries are given below.
krb5_context Management APIs
The context is designed to represent per process state. The Global
parameters which are "context" specific are stored in this structure.
The structure contains default realm, default encryption type, default
configuration files and the like. APIs will provide full access to
the data structure stored in the context and should not be accessed
directly by developers. Some of the common APIs are
krb5_init_context(), krb5_init6_context(), krb5_free_context(), and
krb5_set_default_in_tkt_etypes().
The encryption types which are retrieved from the context and stored
in the etypes should be freed by the caller.
Note: krb5_init6_context() is only available on Itanium-based
platform.
krb5_auth_context Management APIs
The auth_context is a per-connection context and is used by the
various APIs involved directly in client/server authentication. Some
of the data stored in this context include keyblocks, addresses,
sequence numbers, authenticator, checksum type and replay cache
pointer. Some of the common APIs are krb5_auth_con_init(),
krb5_auth_con_free(), krb5_auth_con_setaddrs(),
krb5_auth_con_setports, krb5_auth_con_setflags,
krb5_auth_con_getlocalsubkey(), and krb5_auth_con_genaddrs().
Hewlett-Packard Company - 2 - HP-UX 11i Version 2: August 2003
libkrb5(3) libkrb5(3)
The auth_context structure should be freed using krb5_auth_con_free().
It is the responsibility of the application developer to free the
memory allocated to the authenticator by using
krb5_free_authenticator(). The application developer must also free
the memory that was allocated to store the local sub keyblocks using
krb5_free_keyblock().
Principal Access APIs [Toc] [Back]
A Principal is a uniquely named client or server instance that
participates in a network communication. The APIs allow one to
create, modify and access portions of the Krb5_principal. Some of the
common APIs are krb5_parse_name(), krb5_unparse_name(),
krb5_free_principal(), krb5_princ_realm(), krb5_copy_principal(), etc.
Some of the APIs are internal functions, not intended for use by the
application programs, interface may change at any time. Even though
it is possible to directly access the data elements in the structure,
it is recommended that these APIs should be used. The returned
principal should be freed with krb5_free_principal().
Credential Cache Management APIs [Toc] [Back]
These APIs deal with storing credentials (tickets, session keys and
other identifying information) in a semi-permanent store for later use
by different programs. The credential storage can be a hard disk or a
memory storage. Some of the common APIs are krb5_cc_resolve(),
krb5_cc_default(), krb5_cc_initialize(), krb5_cc_destroy(),
krb5_cc_store_cred(), krb5_cc_retrieve_cred(), krb5_cc_remove_cred(),
and krb5_cc_set_flags().
The retrieved credentials should be freed using
krb5_free_credentials().
Replay Cache Management APIs [Toc] [Back]
These APIs deal with verifying that AP_REQ's do not contain duplicate
authenticators. The storage must be non-volatile for the sitedetermined
validity period of authenticators. Some of the common APIs
are krb5_auth_to_rep(), krb5_rc_register_type(), krb5_rc_default(),
krb5_rc_initialize(), krb5_rc_close(), krb5_rc_store(), and
krb5_rc_resolve().
krb5_rc_resolve() initializes the private data for a replay cache.
This API must be called before the other replay cache APIs. The
allocated memory should be freed using krb5_rc_close().
These APIs are not generally used by the applications.
KeyTab Management APIs [Toc] [Back]
These APIs deal with storing and retrieving service keys for use by
unattended services which participate in authentication exchanges.
Keytab routines are all atomic. All keytab types support multiple
concurrent sequential scans. Some of the common APIs are
Hewlett-Packard Company - 3 - HP-UX 11i Version 2: August 2003
libkrb5(3) libkrb5(3)
krb5_kt_register(), krb5_kt_resolve(), krb5_kt_default(),
krb5_kt_add_entry(), krb5_kt_close(), krb5_kt_free_entry(), and
krb5_kt_next_entry().
To free the resources, the user should use krb5_kt_free_entry().
Memory Management APIs [Toc] [Back]
These APIs deal with deallocation of memory that has been allocated by
various routines. It is recommended that the developer must use these
routines in order to free the data structures. All the APIs start
with krb5_free prefix. Some of the common APIs are
krb5_free_principal(), krb5_free_data(), krb5_free_authenticator(),
krb5_free_ticket(), krb5_free_cred(), krb5_free_pa_data(), and
krb5_free_tgt_creds().
Operating System-Specific APIs [Toc] [Back]
These APIs provide an interface between the other parts of the libkrb5
libraries and the operating system. These include APIs to allow
access to configuration specific information, disk based I/O
operations, network based operations and operating system specific
access APIs. Some of the common APIs are krb5_set_config_file(),
krb5_get_default_realm(), krb5_get_krbhst(), krb5_gen_portaddr(),
krb5_read_message(), krb5_kuserok(), krb5_timeofday(), and
krb5_read_passwd().
Application-Specific and Miscellaneous APIs [Toc] [Back]
These APIs deal with sending and receiving KRB5 protocol messages to
the Kerberos server, ticket management and miscellaneous calls. Some
of the common APIs are krb5_get_cred_from_kdc(),
krb5_get_credentials(), krb5_get_in_tkt_with_password(),
krb5_rd_rep(), krb5_mk_error(), krb5_sendauth(), and krb5_recvauth().
Itanium-based Systems [Toc] [Back]
The Kerberos APIs have support for IPv6-enablement of application in
Kerberos mode. For an application to be v6-enabled in Kerberos mode,
the application needs to obtain the v6-context by calling
krb5_init6_context(), and send that v6-context as an argument to other
Kerberos APIs. The API krb5_init6_context() will initialize a v6-
context on an IPv6-enabled system. If the local host is not IPv6-
enabled, it returns the error code KRB5KRB_INIT_ERR_V6 but initializes
a v4-context, which means the application will perform all the
Kerberos operations in v4-mode only. During compilation of an
application that includes <krb5.h>, the preprocessor macro,
_HAVE_KRB5_IPV6_ needs to be defined for the IPv6 enablement. The
address type to be used for IPv6 is ADDRTYPE_INET6, which is defined
in <krb5.h>.
WARNINGS [Toc] [Back]
It is strongly recommended to use GSS-API instead of Kerberos calls.
The Kerberos libraries are not thread safe.
Hewlett-Packard Company - 4 - HP-UX 11i Version 2: August 2003
libkrb5(3) libkrb5(3)
AUTHOR [Toc] [Back]
Kerberos client libraries were developed at Massachusetts Institute of
Technology. This version of the libraries are compatible with MIT1.0,
MIT1.1 and MIT1.1.1.
SEE ALSO [Toc] [Back]
kdestroy(1), kinit(1), klist(1), kpasswd(1), ktutil(1), kvno(1),
krb5.conf(4), gssapi(5), kerberos(5).
Hewlett-Packard Company - 5 - HP-UX 11i Version 2: August 2003 [ Back ] |
