|
Packit |
fd8b60 |
/* -*- mode: c; c-basic-offset: 4; indent-tabs-mode: nil -*- */
|
|
Packit |
fd8b60 |
/* include/CredentialsCache.h */
|
|
Packit |
fd8b60 |
/*
|
|
Packit |
fd8b60 |
* Copyright 1998-2006 Massachusetts Institute of Technology.
|
|
Packit |
fd8b60 |
* All Rights Reserved.
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* Export of this software from the United States of America may
|
|
Packit |
fd8b60 |
* require a specific license from the United States Government.
|
|
Packit |
fd8b60 |
* It is the responsibility of any person or organization contemplating
|
|
Packit |
fd8b60 |
* export to obtain such a license before exporting.
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* WITHIN THAT CONSTRAINT, permission to use, copy, modify, and
|
|
Packit |
fd8b60 |
* distribute this software and its documentation for any purpose and
|
|
Packit |
fd8b60 |
* without fee is hereby granted, provided that the above copyright
|
|
Packit |
fd8b60 |
* notice appear in all copies and that both that copyright notice and
|
|
Packit |
fd8b60 |
* this permission notice appear in supporting documentation, and that
|
|
Packit |
fd8b60 |
* the name of M.I.T. not be used in advertising or publicity pertaining
|
|
Packit |
fd8b60 |
* to distribution of the software without specific, written prior
|
|
Packit |
fd8b60 |
* permission. Furthermore if you modify this software you must label
|
|
Packit |
fd8b60 |
* your software as modified software and not distribute it in such a
|
|
Packit |
fd8b60 |
* fashion that it might be confused with the original M.I.T. software.
|
|
Packit |
fd8b60 |
* M.I.T. makes no representations about the suitability of
|
|
Packit |
fd8b60 |
* this software for any purpose. It is provided "as is" without express
|
|
Packit |
fd8b60 |
* or implied warranty.
|
|
Packit |
fd8b60 |
*/
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
#ifndef __CREDENTIALSCACHE__
|
|
Packit |
fd8b60 |
#define __CREDENTIALSCACHE__
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
#if defined(macintosh) || (defined(__MACH__) && defined(__APPLE__))
|
|
Packit |
fd8b60 |
#include <TargetConditionals.h>
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
/* Notifications which are sent when the ccache collection or a ccache change.
|
|
Packit |
fd8b60 |
* Notifications are sent to the distributed notification center.
|
|
Packit |
fd8b60 |
* The object for kCCAPICacheCollectionChangedNotification is NULL.
|
|
Packit |
fd8b60 |
* The object for kCCAPICCacheChangedNotification is a CFString containing the
|
|
Packit |
fd8b60 |
* name of the ccache.
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* Note: Notifications are not sent if the CCacheServer crashes. */
|
|
Packit |
fd8b60 |
#define kCCAPICacheCollectionChangedNotification CFSTR ("CCAPICacheCollectionChangedNotification")
|
|
Packit |
fd8b60 |
#define kCCAPICCacheChangedNotification CFSTR ("CCAPICCacheChangedNotification")
|
|
Packit |
fd8b60 |
#endif
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
#if defined(_WIN32)
|
|
Packit |
fd8b60 |
#include <winsock.h>
|
|
Packit |
fd8b60 |
#include "win-mac.h"
|
|
Packit |
fd8b60 |
#else
|
|
Packit |
fd8b60 |
#include <stdint.h>
|
|
Packit |
fd8b60 |
#endif
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
#ifdef __cplusplus
|
|
Packit |
fd8b60 |
extern "C" {
|
|
Packit |
fd8b60 |
#endif /* __cplusplus */
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
#if TARGET_OS_MAC
|
|
Packit |
fd8b60 |
#pragma pack(push,2)
|
|
Packit |
fd8b60 |
#endif
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
#if defined(_WIN32)
|
|
Packit |
fd8b60 |
#define CCACHE_API __declspec(dllexport)
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
#if _INTEGRAL_MAX_BITS >= 64 && _MSC_VER >= 1500 && !defined(_WIN64) && !defined(_USE_32BIT_TIME_T)
|
|
Packit |
fd8b60 |
#if defined(_TIME_T_DEFINED) || defined(_INC_IO) || defined(_INC_TIME) || defined(_INC_WCHAR)
|
|
Packit |
fd8b60 |
#error time_t has been defined as a 64-bit integer which is incompatible with Kerberos on this platform.
|
|
Packit |
fd8b60 |
#endif /* _TIME_T_DEFINED */
|
|
Packit |
fd8b60 |
#define _USE_32BIT_TIME_T
|
|
Packit |
fd8b60 |
#endif
|
|
Packit |
fd8b60 |
#else
|
|
Packit |
fd8b60 |
#define CCACHE_API
|
|
Packit |
fd8b60 |
#endif
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
/*!
|
|
Packit |
fd8b60 |
* \mainpage Credentials Cache API (CCAPI) Documentation
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* \section toc Table of Contents
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* \li \ref introduction
|
|
Packit |
fd8b60 |
* \li \ref error_handling
|
|
Packit |
fd8b60 |
* \li \ref synchronization_atomicity
|
|
Packit |
fd8b60 |
* \li \ref memory_management
|
|
Packit |
fd8b60 |
* \li \ref opaque_types
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* \li \ref ccapi_constants_reference
|
|
Packit |
fd8b60 |
* \li \ref ccapi_types_reference
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* \li \ref cc_context_reference
|
|
Packit |
fd8b60 |
* \li \ref cc_context_f "cc_context_t Functions"
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* \li \ref cc_ccache_reference
|
|
Packit |
fd8b60 |
* \li \ref cc_ccache_f "cc_ccache_t Functions"
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* \li \ref cc_credentials_reference
|
|
Packit |
fd8b60 |
* \li \ref cc_credentials_f "cc_credentials_t Functions"
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* \li \ref cc_ccache_iterator_reference
|
|
Packit |
fd8b60 |
* \li \ref cc_ccache_iterator_f "cc_ccache_iterator_t Functions"
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* \li \ref cc_credentials_iterator_reference
|
|
Packit |
fd8b60 |
* \li \ref cc_credentials_iterator_f "cc_credentials_iterator_t Functions"
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* \li \ref cc_string_reference
|
|
Packit |
fd8b60 |
* \li \ref cc_string_f "cc_string_t Functions"
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* \section introduction Introduction
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* This is the specification for an API which provides Credentials Cache
|
|
Packit |
fd8b60 |
* services for Kerberos v5 (and previously v4). The idea behind this API is
|
|
Packit |
fd8b60 |
* that multiple Kerberos implementations can share a single collection of
|
|
Packit |
fd8b60 |
* credentials caches, mediated by this API specification. On the Mac OS and
|
|
Packit |
fd8b60 |
* Microsoft Windows platforms this will allow single-login, even when more
|
|
Packit |
fd8b60 |
* than one Kerberos shared library is in use on a particular system.
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* Abstractly, a credentials cache collection contains one or more credentials
|
|
Packit |
fd8b60 |
* caches, or ccaches. A ccache is uniquely identified by its name, which is
|
|
Packit |
fd8b60 |
* a string internal to the API and not intended to be presented to users.
|
|
Packit |
fd8b60 |
* The user presentable identifier of a ccache is its principal.
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* Unlike the previous versions of the API, version 3 of the API could store
|
|
Packit |
fd8b60 |
* credentials for multiple Kerberos versions in the same ccache.
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* At any given time, one ccache is the "default" ccache. The exact meaning
|
|
Packit |
fd8b60 |
* of a default ccache is OS-specific; refer to implementation requirements
|
|
Packit |
fd8b60 |
* for details.
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* \section error_handling Error Handling
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* All functions of the API return some of the error constants listed FIXME;
|
|
Packit |
fd8b60 |
* the exact list of error constants returned by any API function is provided
|
|
Packit |
fd8b60 |
* in the function descriptions below.
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* When returning an error constant other than ccNoError or ccIteratorEnd, API
|
|
Packit |
fd8b60 |
* functions never modify any of the values passed in by reference.
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* \section synchronization_atomicity Synchronization and Atomicity
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* Every function in the API is atomic. In order to make a series of calls
|
|
Packit |
fd8b60 |
* atomic, callers should lock the ccache or cache collection they are working
|
|
Packit |
fd8b60 |
* with to advise other callers not to modify that container. Note that
|
|
Packit |
fd8b60 |
* advisory locks are per container so even if you have a read lock on the cache
|
|
Packit |
fd8b60 |
* collection other callers can obtain write locks on ccaches in that cache
|
|
Packit |
fd8b60 |
* collection.
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* Note that iterators do not iterate over ccaches and credentials atomically
|
|
Packit |
fd8b60 |
* because locking ccaches and the cache collection over every iteration would
|
|
Packit |
fd8b60 |
* degrade performance considerably under high load. However, iterators do
|
|
Packit |
fd8b60 |
* guarantee a consistent view of items they are iterating over. Iterators
|
|
Packit |
fd8b60 |
* will never return duplicate entries or skip entries when items are removed
|
|
Packit |
fd8b60 |
* or added to the container they are iterating over.
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* An application can always lock a ccache or the cache collection to guarantee
|
|
Packit |
fd8b60 |
* that other callers participating in the advisory locking system do not
|
|
Packit |
fd8b60 |
* modify the ccache or cache collection.
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* Implementations should not use copy-on-write techniques to implement locks
|
|
Packit |
fd8b60 |
* because those techniques imply that same parts of the ccache collection
|
|
Packit |
fd8b60 |
* remain visible to some callers even though they are not present in the
|
|
Packit |
fd8b60 |
* collection, which is a potential security risk. For example, a copy-on-write
|
|
Packit |
fd8b60 |
* technique might make a copy of the entire collection when a read lock is
|
|
Packit |
fd8b60 |
* acquired, so as to allow the owner of the lock to access the collection in
|
|
Packit |
fd8b60 |
* an apparently unmodified state, while also allowing others to make
|
|
Packit |
fd8b60 |
* modifications to the collection. However, this would also enable the owner
|
|
Packit |
fd8b60 |
* of the lock to indefinitely (until the expiration time) use credentials that
|
|
Packit |
fd8b60 |
* have actually been deleted from the collection.
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* \section memory_management Object Memory Management
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* The lifetime of an object returned by the API is until release() is called
|
|
Packit |
fd8b60 |
* for it. Releasing one object has no effect on existence of any other object.
|
|
Packit |
fd8b60 |
* For example, a ccache obtained within a context continue to exist when the
|
|
Packit |
fd8b60 |
* context is released.
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* Every object returned by the API (cc_context_t, cc_ccache_t, cc_ccache_iterator_t,
|
|
Packit |
fd8b60 |
* cc_credentials_t, cc_credentials_iterator_t, cc_string_t) is owned by the
|
|
Packit |
fd8b60 |
* caller of the API, and it is the responsibility of the caller to call release()
|
|
Packit |
fd8b60 |
* for every object to prevent memory leaks.
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* \section opaque_types Opaque Types
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* All of the opaque high-level types in CCache API are implemented as structures
|
|
Packit |
fd8b60 |
* of function pointers and private data. To perform some operation on a type, the
|
|
Packit |
fd8b60 |
* caller of the API has to first obtain an instance of that type, and then call the
|
|
Packit |
fd8b60 |
* appropriate function pointer from that instance. For example, to call
|
|
Packit |
fd8b60 |
* get_change_time() on a cc_context_t, one would call cc_initialize() which creates
|
|
Packit |
fd8b60 |
* a new cc_context_t and then call its get_change_time(), like this:
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* \code
|
|
Packit |
fd8b60 |
* cc_context_t context;
|
|
Packit |
fd8b60 |
* cc_int32 err = cc_initialize (&context, ccapi_version_3, nil, nil);
|
|
Packit |
fd8b60 |
* if (err == ccNoError)
|
|
Packit |
fd8b60 |
* time = context->functions->get_change_time (context)
|
|
Packit |
fd8b60 |
* \endcode
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* All API functions also have convenience preprocessor macros, which make the API
|
|
Packit |
fd8b60 |
* seem completely function-based. For example, cc_context_get_change_time
|
|
Packit |
fd8b60 |
* (context, time) is equivalent to context->functions->get_change_time
|
|
Packit |
fd8b60 |
* (context, time). The convenience macros follow the following naming convention:
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* The API function some_function()
|
|
Packit |
fd8b60 |
* \code
|
|
Packit |
fd8b60 |
* cc_type_t an_object;
|
|
Packit |
fd8b60 |
* result = an_object->functions->some_function (opaque_pointer, args)
|
|
Packit |
fd8b60 |
* \endcode
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* has an equivalent convenience macro of the form cc_type_some_function():
|
|
Packit |
fd8b60 |
* \code
|
|
Packit |
fd8b60 |
* cc_type_t an_object;
|
|
Packit |
fd8b60 |
* result = cc_type_some_function (an_object, args)
|
|
Packit |
fd8b60 |
* \endcode
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* The specifications below include the names for both the functions and the
|
|
Packit |
fd8b60 |
* convenience macros, in that order. For clarity, it is recommended that clients
|
|
Packit |
fd8b60 |
* using the API use the convenience macros, but that is merely a stylistic choice.
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* Implementing the API in this manner allows us to extend and change the interface
|
|
Packit |
fd8b60 |
* in the future, while preserving compatibility with older clients.
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* For example, consider the case when the signature or the semantics of a cc_ccache_t
|
|
Packit |
fd8b60 |
* function is changed. The API version number is incremented. The library
|
|
Packit |
fd8b60 |
* implementation contains both a function with the old signature and semantics and
|
|
Packit |
fd8b60 |
* a function with the new signature and semantics. When a context is created, the API
|
|
Packit |
fd8b60 |
* version number used in that context is stored in the context, and therefore it can
|
|
Packit |
fd8b60 |
* be used whenever a ccache is created in that context. When a ccache is created in a
|
|
Packit |
fd8b60 |
* context with the old API version number, the function pointer structure for the
|
|
Packit |
fd8b60 |
* ccache is filled with pointers to functions implementing the old semantics; when a
|
|
Packit |
fd8b60 |
* ccache is created in a context with the new API version number, the function pointer
|
|
Packit |
fd8b60 |
* structure for the ccache is filled with poitners to functions implementing the new
|
|
Packit |
fd8b60 |
* semantics.
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* Similarly, if a function is added to the API, the version number in the context can
|
|
Packit |
fd8b60 |
* be used to decide whether to include the implementation of the new function in the
|
|
Packit |
fd8b60 |
* appropriate function pointer structure or not.
|
|
Packit |
fd8b60 |
*/
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
/*!
|
|
Packit |
fd8b60 |
* \defgroup ccapi_constants_reference Constants
|
|
Packit |
fd8b60 |
* @{
|
|
Packit |
fd8b60 |
*/
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
/*!
|
|
Packit |
fd8b60 |
* API version numbers
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* These constants are passed into cc_initialize() to indicate the version
|
|
Packit |
fd8b60 |
* of the API the caller wants to use.
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* CCAPI v1 and v2 are deprecated and should not be used.
|
|
Packit |
fd8b60 |
*/
|
|
Packit |
fd8b60 |
enum {
|
|
Packit |
fd8b60 |
ccapi_version_2 = 2,
|
|
Packit |
fd8b60 |
ccapi_version_3 = 3,
|
|
Packit |
fd8b60 |
ccapi_version_4 = 4,
|
|
Packit |
fd8b60 |
ccapi_version_5 = 5,
|
|
Packit |
fd8b60 |
ccapi_version_6 = 6,
|
|
Packit |
fd8b60 |
ccapi_version_7 = 7,
|
|
Packit |
fd8b60 |
ccapi_version_max = ccapi_version_7
|
|
Packit |
fd8b60 |
};
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
/*!
|
|
Packit |
fd8b60 |
* Error codes
|
|
Packit |
fd8b60 |
*/
|
|
Packit |
fd8b60 |
enum {
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
ccNoError = 0, /*!< Success. */
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
ccIteratorEnd = 201, /*!< Iterator is done iterating. */
|
|
Packit |
fd8b60 |
ccErrBadParam, /*!< Bad parameter (NULL or invalid pointer where valid pointer expected). */
|
|
Packit |
fd8b60 |
ccErrNoMem, /*!< Not enough memory to complete the operation. */
|
|
Packit |
fd8b60 |
ccErrInvalidContext, /*!< Context is invalid (e.g., it was released). */
|
|
Packit |
fd8b60 |
ccErrInvalidCCache, /*!< CCache is invalid (e.g., it was released or destroyed). */
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
/* 206 */
|
|
Packit |
fd8b60 |
ccErrInvalidString, /*!< String is invalid (e.g., it was released). */
|
|
Packit |
fd8b60 |
ccErrInvalidCredentials, /*!< Credentials are invalid (e.g., they were released), or they have a bad version. */
|
|
Packit |
fd8b60 |
ccErrInvalidCCacheIterator, /*!< CCache iterator is invalid (e.g., it was released). */
|
|
Packit |
fd8b60 |
ccErrInvalidCredentialsIterator, /*!< Credentials iterator is invalid (e.g., it was released). */
|
|
Packit |
fd8b60 |
ccErrInvalidLock, /*!< Lock is invalid (e.g., it was released). */
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
/* 211 */
|
|
Packit |
fd8b60 |
ccErrBadName, /*!< Bad credential cache name format. */
|
|
Packit |
fd8b60 |
ccErrBadCredentialsVersion, /*!< Credentials version is invalid. */
|
|
Packit |
fd8b60 |
ccErrBadAPIVersion, /*!< Unsupported API version. */
|
|
Packit |
fd8b60 |
ccErrContextLocked, /*!< Context is already locked. */
|
|
Packit |
fd8b60 |
ccErrContextUnlocked, /*!< Context is not locked by the caller. */
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
/* 216 */
|
|
Packit |
fd8b60 |
ccErrCCacheLocked, /*!< CCache is already locked. */
|
|
Packit |
fd8b60 |
ccErrCCacheUnlocked, /*!< CCache is not locked by the caller. */
|
|
Packit |
fd8b60 |
ccErrBadLockType, /*!< Bad lock type. */
|
|
Packit |
fd8b60 |
ccErrNeverDefault, /*!< CCache was never default. */
|
|
Packit |
fd8b60 |
ccErrCredentialsNotFound, /*!< Matching credentials not found in the ccache. */
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
/* 221 */
|
|
Packit |
fd8b60 |
ccErrCCacheNotFound, /*!< Matching ccache not found in the collection. */
|
|
Packit |
fd8b60 |
ccErrContextNotFound, /*!< Matching cache collection not found. */
|
|
Packit |
fd8b60 |
ccErrServerUnavailable, /*!< CCacheServer is unavailable. */
|
|
Packit |
fd8b60 |
ccErrServerInsecure, /*!< CCacheServer has detected that it is running as the wrong user. */
|
|
Packit |
fd8b60 |
ccErrServerCantBecomeUID, /*!< CCacheServer failed to start running as the user. */
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
/* 226 */
|
|
Packit |
fd8b60 |
ccErrTimeOffsetNotSet, /*!< KDC time offset not set for this ccache. */
|
|
Packit |
fd8b60 |
ccErrBadInternalMessage, /*!< The client and CCacheServer can't communicate (e.g., a version mismatch). */
|
|
Packit |
fd8b60 |
ccErrNotImplemented, /*!< API function not supported by this implementation. */
|
|
Packit |
fd8b60 |
ccErrClientNotFound /*!< CCacheServer has no record of the caller's process (e.g., the server crashed). */
|
|
Packit |
fd8b60 |
};
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
/*!
|
|
Packit |
fd8b60 |
* Credentials versions
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* These constants are used in several places in the API to discern Kerberos
|
|
Packit |
fd8b60 |
* versions. Not all values are valid inputs and outputs for all functions;
|
|
Packit |
fd8b60 |
* function specifications below detail the allowed values.
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* Kerberos version constants will always be a bit-field, and can be
|
|
Packit |
fd8b60 |
* tested as such; for example the following test will tell you if
|
|
Packit |
fd8b60 |
* a ccacheVersion includes v5 credentials:
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* if ((ccacheVersion & cc_credentials_v5) != 0)
|
|
Packit |
fd8b60 |
*/
|
|
Packit |
fd8b60 |
enum cc_credential_versions {
|
|
Packit |
fd8b60 |
/* cc_credentials_v4 = 1, */
|
|
Packit |
fd8b60 |
cc_credentials_v5 = 2,
|
|
Packit |
fd8b60 |
/* cc_credentials_v4_v5 = 3 */
|
|
Packit |
fd8b60 |
};
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
/*!
|
|
Packit |
fd8b60 |
* Lock types
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* These constants are used in the locking functions to describe the
|
|
Packit |
fd8b60 |
* type of lock requested. Note that all CCAPI locks are advisory
|
|
Packit |
fd8b60 |
* so only callers using the lock calls will be blocked by each other.
|
|
Packit |
fd8b60 |
* This is because locking functions were introduced after the CCAPI
|
|
Packit |
fd8b60 |
* came into common use and we did not want to break existing callers.
|
|
Packit |
fd8b60 |
*/
|
|
Packit |
fd8b60 |
enum cc_lock_types {
|
|
Packit |
fd8b60 |
cc_lock_read = 0,
|
|
Packit |
fd8b60 |
cc_lock_write = 1,
|
|
Packit |
fd8b60 |
cc_lock_upgrade = 2,
|
|
Packit |
fd8b60 |
cc_lock_downgrade = 3
|
|
Packit |
fd8b60 |
};
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
/*!
|
|
Packit |
fd8b60 |
* Locking Modes
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* These constants are used in the advisory locking functions to
|
|
Packit |
fd8b60 |
* describe whether or not the lock function should block waiting for
|
|
Packit |
fd8b60 |
* a lock or return an error immediately. For example, attempting to
|
|
Packit |
fd8b60 |
* acquire a lock with a non-blocking call will result in an error if the
|
|
Packit |
fd8b60 |
* lock cannot be acquired; otherwise, the call will block until the lock
|
|
Packit |
fd8b60 |
* can be acquired.
|
|
Packit |
fd8b60 |
*/
|
|
Packit |
fd8b60 |
enum cc_lock_modes {
|
|
Packit |
fd8b60 |
cc_lock_noblock = 0,
|
|
Packit |
fd8b60 |
cc_lock_block = 1
|
|
Packit |
fd8b60 |
};
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
/*!@}*/
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
/*!
|
|
Packit |
fd8b60 |
* \defgroup ccapi_types_reference Basic Types
|
|
Packit |
fd8b60 |
* @{
|
|
Packit |
fd8b60 |
*/
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
/*! Unsigned 32-bit integer type */
|
|
Packit |
fd8b60 |
typedef uint32_t cc_uint32;
|
|
Packit |
fd8b60 |
/*! Signed 32-bit integer type */
|
|
Packit |
fd8b60 |
typedef int32_t cc_int32;
|
|
Packit |
fd8b60 |
#if defined (WIN32)
|
|
Packit |
fd8b60 |
typedef __int64 cc_int64;
|
|
Packit |
fd8b60 |
typedef unsigned __int64 cc_uint64;
|
|
Packit |
fd8b60 |
#else
|
|
Packit |
fd8b60 |
/*! Unsigned 64-bit integer type */
|
|
Packit |
fd8b60 |
typedef int64_t cc_int64;
|
|
Packit |
fd8b60 |
/*! Signed 64-bit integer type */
|
|
Packit |
fd8b60 |
typedef uint64_t cc_uint64;
|
|
Packit |
fd8b60 |
#endif
|
|
Packit |
fd8b60 |
/*!
|
|
Packit |
fd8b60 |
* The cc_time_t type is used to represent a time in seconds. The time must
|
|
Packit |
fd8b60 |
* be stored as the number of seconds since midnight GMT on January 1, 1970.
|
|
Packit |
fd8b60 |
*/
|
|
Packit |
fd8b60 |
typedef cc_uint32 cc_time_t;
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
/*!@}*/
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
/*!
|
|
Packit |
fd8b60 |
* \defgroup cc_context_reference cc_context_t Overview
|
|
Packit |
fd8b60 |
* @{
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* The cc_context_t type gives the caller access to a ccache collection.
|
|
Packit |
fd8b60 |
* Before being able to call any functions in the CCache API, the caller
|
|
Packit |
fd8b60 |
* needs to acquire an instance of cc_context_t by calling cc_initialize().
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* For API function documentation see \ref cc_context_f.
|
|
Packit |
fd8b60 |
*/
|
|
Packit |
fd8b60 |
struct cc_context_f;
|
|
Packit |
fd8b60 |
typedef struct cc_context_f cc_context_f;
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
struct cc_context_d {
|
|
Packit |
fd8b60 |
const cc_context_f *functions;
|
|
Packit |
fd8b60 |
#if TARGET_OS_MAC
|
|
Packit |
fd8b60 |
const cc_context_f *vector_functions;
|
|
Packit |
fd8b60 |
#endif
|
|
Packit |
fd8b60 |
};
|
|
Packit |
fd8b60 |
typedef struct cc_context_d cc_context_d;
|
|
Packit |
fd8b60 |
typedef cc_context_d *cc_context_t;
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
/*!@}*/
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
/*!
|
|
Packit |
fd8b60 |
* \defgroup cc_ccache_reference cc_ccache_t Overview
|
|
Packit |
fd8b60 |
* @{
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* The cc_ccache_t type represents a reference to a ccache.
|
|
Packit |
fd8b60 |
* Callers can access a ccache and the credentials stored in it
|
|
Packit |
fd8b60 |
* via a cc_ccache_t. A cc_ccache_t can be acquired via
|
|
Packit |
fd8b60 |
* cc_context_open_ccache(), cc_context_open_default_ccache(), or
|
|
Packit |
fd8b60 |
* cc_ccache_iterator_next().
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* For API function documentation see \ref cc_ccache_f.
|
|
Packit |
fd8b60 |
*/
|
|
Packit |
fd8b60 |
struct cc_ccache_f;
|
|
Packit |
fd8b60 |
typedef struct cc_ccache_f cc_ccache_f;
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
struct cc_ccache_d {
|
|
Packit |
fd8b60 |
const cc_ccache_f *functions;
|
|
Packit |
fd8b60 |
#if TARGET_OS_MAC
|
|
Packit |
fd8b60 |
const cc_ccache_f *vector_functions;
|
|
Packit |
fd8b60 |
#endif
|
|
Packit |
fd8b60 |
};
|
|
Packit |
fd8b60 |
typedef struct cc_ccache_d cc_ccache_d;
|
|
Packit |
fd8b60 |
typedef cc_ccache_d *cc_ccache_t;
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
/*!@}*/
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
/*!
|
|
Packit |
fd8b60 |
* \defgroup cc_ccache_iterator_reference cc_ccache_iterator_t Overview
|
|
Packit |
fd8b60 |
* @{
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* The cc_ccache_iterator_t type represents an iterator that
|
|
Packit |
fd8b60 |
* iterates over a set of ccaches and returns them in all in some
|
|
Packit |
fd8b60 |
* order. A new instance of this type can be obtained by calling
|
|
Packit |
fd8b60 |
* cc_context_new_ccache_iterator().
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* For API function documentation see \ref cc_ccache_iterator_f.
|
|
Packit |
fd8b60 |
*/
|
|
Packit |
fd8b60 |
struct cc_ccache_iterator_f;
|
|
Packit |
fd8b60 |
typedef struct cc_ccache_iterator_f cc_ccache_iterator_f;
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
struct cc_ccache_iterator_d {
|
|
Packit |
fd8b60 |
const cc_ccache_iterator_f *functions;
|
|
Packit |
fd8b60 |
#if TARGET_OS_MAC
|
|
Packit |
fd8b60 |
const cc_ccache_iterator_f *vector_functions;
|
|
Packit |
fd8b60 |
#endif
|
|
Packit |
fd8b60 |
};
|
|
Packit |
fd8b60 |
typedef struct cc_ccache_iterator_d cc_ccache_iterator_d;
|
|
Packit |
fd8b60 |
typedef cc_ccache_iterator_d *cc_ccache_iterator_t;
|
|
Packit |
fd8b60 |
/*!@}*/
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
/*!
|
|
Packit |
fd8b60 |
* \defgroup cc_credentials_reference cc_credentials_t Overview
|
|
Packit |
fd8b60 |
* @{
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* The cc_credentials_t type is used to store a single set of credentials for
|
|
Packit |
fd8b60 |
* Kerberos v5. In addition to its only function, release(), it contains a
|
|
Packit |
fd8b60 |
* pointer to a cc_credentials_union structure. A cc_credentials_union
|
|
Packit |
fd8b60 |
* structure contains an integer of the enumerator type
|
|
Packit |
fd8b60 |
* cc_credentials_version, which is #cc_credentials_v5, and a pointer union,
|
|
Packit |
fd8b60 |
* which contains a cc_credentials_v5_t pointer, depending on the value in
|
|
Packit |
fd8b60 |
* version.
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* Variables of the type cc_credentials_t are allocated by the CCAPI
|
|
Packit |
fd8b60 |
* implementation, and should be released with their release()
|
|
Packit |
fd8b60 |
* function. API functions which receive credentials structures
|
|
Packit |
fd8b60 |
* from the caller always accept cc_credentials_union, which is
|
|
Packit |
fd8b60 |
* allocated by the caller, and accordingly disposed by the caller.
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* For API functions see \ref cc_credentials_f.
|
|
Packit |
fd8b60 |
*/
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
/*!
|
|
Packit |
fd8b60 |
* The CCAPI data structure. This structure is similar to a krb5_data structure.
|
|
Packit |
fd8b60 |
* In a v5 credentials structure, cc_data structures are used
|
|
Packit |
fd8b60 |
* to store tagged variable-length binary data. Specifically,
|
|
Packit |
fd8b60 |
* for cc_credentials_v5.ticket and
|
|
Packit |
fd8b60 |
* cc_credentials_v5.second_ticket, the cc_data.type field must
|
|
Packit |
fd8b60 |
* be zero. For the cc_credentials_v5.addresses,
|
|
Packit |
fd8b60 |
* cc_credentials_v5.authdata, and cc_credentials_v5.keyblock,
|
|
Packit |
fd8b60 |
* the cc_data.type field should be the address type,
|
|
Packit |
fd8b60 |
* authorization data type, and encryption type, as defined by
|
|
Packit |
fd8b60 |
* the Kerberos v5 protocol definition.
|
|
Packit |
fd8b60 |
*/
|
|
Packit |
fd8b60 |
struct cc_data {
|
|
Packit |
fd8b60 |
/*! The type of the data as defined by the krb5_data structure. */
|
|
Packit |
fd8b60 |
cc_uint32 type;
|
|
Packit |
fd8b60 |
/*! The length of \a data. */
|
|
Packit |
fd8b60 |
cc_uint32 length;
|
|
Packit |
fd8b60 |
/*! The data buffer. */
|
|
Packit |
fd8b60 |
void* data;
|
|
Packit |
fd8b60 |
};
|
|
Packit |
fd8b60 |
typedef struct cc_data cc_data;
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
/*!
|
|
Packit |
fd8b60 |
* If a cc_credentials_t variable is used to store Kerberos v5 c
|
|
Packit |
fd8b60 |
* redentials, and then credentials.credentials_v5 points to a
|
|
Packit |
fd8b60 |
* v5 credentials structure. This structure is similar to a
|
|
Packit |
fd8b60 |
* krb5_creds structure.
|
|
Packit |
fd8b60 |
*/
|
|
Packit |
fd8b60 |
struct cc_credentials_v5_t {
|
|
Packit |
fd8b60 |
/*! A properly quoted string representation of the client principal. */
|
|
Packit |
fd8b60 |
char* client;
|
|
Packit |
fd8b60 |
/*! A properly quoted string representation of the service principal. */
|
|
Packit |
fd8b60 |
char* server;
|
|
Packit |
fd8b60 |
/*! Session encryption key info. */
|
|
Packit |
fd8b60 |
cc_data keyblock;
|
|
Packit |
fd8b60 |
/*! The time when the ticket was issued. */
|
|
Packit |
fd8b60 |
cc_time_t authtime;
|
|
Packit |
fd8b60 |
/*! The time when the ticket becomes valid. */
|
|
Packit |
fd8b60 |
cc_time_t starttime;
|
|
Packit |
fd8b60 |
/*! The time when the ticket expires. */
|
|
Packit |
fd8b60 |
cc_time_t endtime;
|
|
Packit |
fd8b60 |
/*! The time when the ticket becomes no longer renewable (if renewable). */
|
|
Packit |
fd8b60 |
cc_time_t renew_till;
|
|
Packit |
fd8b60 |
/*! 1 if the ticket is encrypted in another ticket's key, or 0 otherwise. */
|
|
Packit |
fd8b60 |
cc_uint32 is_skey;
|
|
Packit |
fd8b60 |
/*! Ticket flags, as defined by the Kerberos 5 API. */
|
|
Packit |
fd8b60 |
cc_uint32 ticket_flags;
|
|
Packit |
fd8b60 |
/*! The the list of network addresses of hosts that are allowed to authenticate
|
|
Packit |
fd8b60 |
* using this ticket. */
|
|
Packit |
fd8b60 |
cc_data** addresses;
|
|
Packit |
fd8b60 |
/*! Ticket data. */
|
|
Packit |
fd8b60 |
cc_data ticket;
|
|
Packit |
fd8b60 |
/*! Second ticket data. */
|
|
Packit |
fd8b60 |
cc_data second_ticket;
|
|
Packit |
fd8b60 |
/*! Authorization data. */
|
|
Packit |
fd8b60 |
cc_data** authdata;
|
|
Packit |
fd8b60 |
};
|
|
Packit |
fd8b60 |
typedef struct cc_credentials_v5_t cc_credentials_v5_t;
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
struct cc_credentials_union {
|
|
Packit |
fd8b60 |
/*! The credentials version of this credentials object. */
|
|
Packit |
fd8b60 |
cc_uint32 version;
|
|
Packit |
fd8b60 |
/*! The credentials. */
|
|
Packit |
fd8b60 |
union {
|
|
Packit |
fd8b60 |
/*! If \a version is #cc_credentials_v5, a pointer to a cc_credentials_v5_t. */
|
|
Packit |
fd8b60 |
cc_credentials_v5_t* credentials_v5;
|
|
Packit |
fd8b60 |
} credentials;
|
|
Packit |
fd8b60 |
};
|
|
Packit |
fd8b60 |
typedef struct cc_credentials_union cc_credentials_union;
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
struct cc_credentials_f;
|
|
Packit |
fd8b60 |
typedef struct cc_credentials_f cc_credentials_f;
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
struct cc_credentials_d {
|
|
Packit |
fd8b60 |
const cc_credentials_union *data;
|
|
Packit |
fd8b60 |
const cc_credentials_f *functions;
|
|
Packit |
fd8b60 |
#if TARGET_OS_MAC
|
|
Packit |
fd8b60 |
const cc_credentials_f *otherFunctions;
|
|
Packit |
fd8b60 |
#endif
|
|
Packit |
fd8b60 |
};
|
|
Packit |
fd8b60 |
typedef struct cc_credentials_d cc_credentials_d;
|
|
Packit |
fd8b60 |
typedef cc_credentials_d *cc_credentials_t;
|
|
Packit |
fd8b60 |
/*!@}*/
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
/*!
|
|
Packit |
fd8b60 |
* \defgroup cc_credentials_iterator_reference cc_credentials_iterator_t
|
|
Packit |
fd8b60 |
* @{
|
|
Packit |
fd8b60 |
* The cc_credentials_iterator_t type represents an iterator that
|
|
Packit |
fd8b60 |
* iterates over a set of credentials. A new instance of this type
|
|
Packit |
fd8b60 |
* can be obtained by calling cc_ccache_new_credentials_iterator().
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* For API function documentation see \ref cc_credentials_iterator_f.
|
|
Packit |
fd8b60 |
*/
|
|
Packit |
fd8b60 |
struct cc_credentials_iterator_f;
|
|
Packit |
fd8b60 |
typedef struct cc_credentials_iterator_f cc_credentials_iterator_f;
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
struct cc_credentials_iterator_d {
|
|
Packit |
fd8b60 |
const cc_credentials_iterator_f *functions;
|
|
Packit |
fd8b60 |
#if TARGET_OS_MAC
|
|
Packit |
fd8b60 |
const cc_credentials_iterator_f *vector_functions;
|
|
Packit |
fd8b60 |
#endif
|
|
Packit |
fd8b60 |
};
|
|
Packit |
fd8b60 |
typedef struct cc_credentials_iterator_d cc_credentials_iterator_d;
|
|
Packit |
fd8b60 |
typedef cc_credentials_iterator_d *cc_credentials_iterator_t;
|
|
Packit |
fd8b60 |
/*!@}*/
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
/*!
|
|
Packit |
fd8b60 |
* \defgroup cc_string_reference cc_string_t Overview
|
|
Packit |
fd8b60 |
* @{
|
|
Packit |
fd8b60 |
* The cc_string_t represents a C string returned by the API.
|
|
Packit |
fd8b60 |
* It has a pointer to the string data and a release() function.
|
|
Packit |
fd8b60 |
* This type is used for both principal names and ccache names
|
|
Packit |
fd8b60 |
* returned by the API. Principal names may contain UTF-8 encoded
|
|
Packit |
fd8b60 |
* strings for internationalization purposes.
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* For API function documentation see \ref cc_string_f.
|
|
Packit |
fd8b60 |
*/
|
|
Packit |
fd8b60 |
struct cc_string_f;
|
|
Packit |
fd8b60 |
typedef struct cc_string_f cc_string_f;
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
struct cc_string_d {
|
|
Packit |
fd8b60 |
const char *data;
|
|
Packit |
fd8b60 |
const cc_string_f *functions;
|
|
Packit |
fd8b60 |
#if TARGET_OS_MAC
|
|
Packit |
fd8b60 |
const cc_string_f *vector_functions;
|
|
Packit |
fd8b60 |
#endif
|
|
Packit |
fd8b60 |
};
|
|
Packit |
fd8b60 |
typedef struct cc_string_d cc_string_d;
|
|
Packit |
fd8b60 |
typedef cc_string_d *cc_string_t;
|
|
Packit |
fd8b60 |
/*!@}*/
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
/*!
|
|
Packit |
fd8b60 |
* Function pointer table for cc_context_t. For more information see
|
|
Packit |
fd8b60 |
* \ref cc_context_reference.
|
|
Packit |
fd8b60 |
*/
|
|
Packit |
fd8b60 |
struct cc_context_f {
|
|
Packit |
fd8b60 |
/*!
|
|
Packit |
fd8b60 |
* \param io_context the context object to free.
|
|
Packit |
fd8b60 |
* \return On success, #ccNoError. On failure, an error code representing the failure.
|
|
Packit |
fd8b60 |
* \brief \b cc_context_release(): Release memory associated with a cc_context_t.
|
|
Packit |
fd8b60 |
*/
|
|
Packit |
fd8b60 |
cc_int32 (*release) (cc_context_t io_context);
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
/*!
|
|
Packit |
fd8b60 |
* \param in_context the context object for the cache collection to examine.
|
|
Packit |
fd8b60 |
* \param out_time on exit, the time of the most recent change for the entire ccache collection.
|
|
Packit |
fd8b60 |
* \return On success, #ccNoError. On failure, an error code representing the failure.
|
|
Packit |
fd8b60 |
* \brief \b cc_context_get_change_time(): Get the last time the cache collection changed.
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* This function returns the time of the most recent change for the entire ccache collection.
|
|
Packit |
fd8b60 |
* By maintaining a local copy the caller can deduce whether or not the ccache collection has
|
|
Packit |
fd8b60 |
* been modified since the previous call to cc_context_get_change_time().
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* The time returned by cc_context_get_changed_time() increases whenever:
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* \li a ccache is created
|
|
Packit |
fd8b60 |
* \li a ccache is destroyed
|
|
Packit |
fd8b60 |
* \li a credential is stored
|
|
Packit |
fd8b60 |
* \li a credential is removed
|
|
Packit |
fd8b60 |
* \li a ccache principal is changed
|
|
Packit |
fd8b60 |
* \li the default ccache is changed
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* \note In order to be able to compare two values returned by cc_context_get_change_time(),
|
|
Packit |
fd8b60 |
* the caller must use the same context to acquire them. Callers should maintain a single
|
|
Packit |
fd8b60 |
* context in memory for cc_context_get_change_time() calls rather than creating a new
|
|
Packit |
fd8b60 |
* context for every call.
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* \sa wait_for_change
|
|
Packit |
fd8b60 |
*/
|
|
Packit |
fd8b60 |
cc_int32 (*get_change_time) (cc_context_t in_context,
|
|
Packit |
fd8b60 |
cc_time_t *out_time);
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
/*!
|
|
Packit |
fd8b60 |
* \param in_context the context object for the cache collection.
|
|
Packit |
fd8b60 |
* \param out_name on exit, the name of the default ccache.
|
|
Packit |
fd8b60 |
* \return On success, #ccNoError. On failure, an error code representing the failure.
|
|
Packit |
fd8b60 |
* \brief \b cc_context_get_default_ccache_name(): Get the name of the default ccache.
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* This function returns the name of the default ccache. When the default ccache
|
|
Packit |
fd8b60 |
* exists, its name is returned. If there are no ccaches in the collection, and
|
|
Packit |
fd8b60 |
* thus there is no default ccache, the name that the default ccache should have
|
|
Packit |
fd8b60 |
* is returned. The ccache with that name will be used as the default ccache by
|
|
Packit |
fd8b60 |
* all processes which initialized Kerberos libraries before the ccache was created.
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* If there is no default ccache, and the client is creating a new ccache, it
|
|
Packit |
fd8b60 |
* should be created with the default name. If there already is a default ccache,
|
|
Packit |
fd8b60 |
* and the client wants to create a new ccache (as opposed to reusing an existing
|
|
Packit |
fd8b60 |
* ccache), it should be created with any unique name; #create_new_ccache()
|
|
Packit |
fd8b60 |
* can be used to accomplish that more easily.
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* If the first ccache is created with a name other than the default name, then
|
|
Packit |
fd8b60 |
* the processes already running will not notice the credentials stored in the
|
|
Packit |
fd8b60 |
* new ccache, which is normally undesirable.
|
|
Packit |
fd8b60 |
*/
|
|
Packit |
fd8b60 |
cc_int32 (*get_default_ccache_name) (cc_context_t in_context,
|
|
Packit |
fd8b60 |
cc_string_t *out_name);
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
/*!
|
|
Packit |
fd8b60 |
* \param in_context the context object for the cache collection.
|
|
Packit |
fd8b60 |
* \param in_name the name of the ccache to open.
|
|
Packit |
fd8b60 |
* \param out_ccache on exit, a ccache object for the ccache
|
|
Packit |
fd8b60 |
* \return On success, #ccNoError. If no ccache named \a in_name exists,
|
|
Packit |
fd8b60 |
* #ccErrCCacheNotFound. On failure, an error code representing the failure.
|
|
Packit |
fd8b60 |
* \brief \b cc_context_open_ccache(): Open a ccache.
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* Opens an already existing ccache identified by its name. It returns a reference
|
|
Packit |
fd8b60 |
* to the ccache in \a out_ccache.
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* The list of all ccache names, principals, and credentials versions may be retrieved
|
|
Packit |
fd8b60 |
* by calling cc_context_new_cache_iterator(), cc_ccache_get_name(),
|
|
Packit |
fd8b60 |
* cc_ccache_get_principal(), and cc_ccache_get_cred_version().
|
|
Packit |
fd8b60 |
*/
|
|
Packit |
fd8b60 |
cc_int32 (*open_ccache) (cc_context_t in_context,
|
|
Packit |
fd8b60 |
const char *in_name,
|
|
Packit |
fd8b60 |
cc_ccache_t *out_ccache);
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
/*!
|
|
Packit |
fd8b60 |
* \param in_context the context object for the cache collection.
|
|
Packit |
fd8b60 |
* \param out_ccache on exit, a ccache object for the default ccache
|
|
Packit |
fd8b60 |
* \return On success, #ccNoError. If no default ccache exists,
|
|
Packit |
fd8b60 |
* #ccErrCCacheNotFound. On failure, an error code representing the failure.
|
|
Packit |
fd8b60 |
* \brief \b cc_context_open_default_ccache(): Open the default ccache.
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* Opens the default ccache. It returns a reference to the ccache in *ccache.
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* This function performs the same function as calling
|
|
Packit |
fd8b60 |
* cc_context_get_default_ccache_name followed by cc_context_open_ccache,
|
|
Packit |
fd8b60 |
* but it performs it atomically.
|
|
Packit |
fd8b60 |
*/
|
|
Packit |
fd8b60 |
cc_int32 (*open_default_ccache) (cc_context_t in_context,
|
|
Packit |
fd8b60 |
cc_ccache_t *out_ccache);
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
/*!
|
|
Packit |
fd8b60 |
* \param in_context the context object for the cache collection.
|
|
Packit |
fd8b60 |
* \param in_name the name of the new ccache to create
|
|
Packit |
fd8b60 |
* \param in_cred_vers the version of the credentials the new ccache will hold
|
|
Packit |
fd8b60 |
* \param in_principal the client principal of the credentials the new ccache will hold
|
|
Packit |
fd8b60 |
* \param out_ccache on exit, a ccache object for the newly created ccache
|
|
Packit |
fd8b60 |
* \return On success, #ccNoError. On failure, an error code representing the failure.
|
|
Packit |
fd8b60 |
* \brief \b cc_context_create_ccache(): Create a new ccache.
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* Create a new credentials cache. The ccache is uniquely identified by
|
|
Packit |
fd8b60 |
* its name. The principal given is also associated with the ccache and
|
|
Packit |
fd8b60 |
* the credentials version specified. A NULL name is not allowed (and
|
|
Packit |
fd8b60 |
* ccErrBadName is returned if one is passed in). Only cc_credentials_v5
|
|
Packit |
fd8b60 |
* can be an input value for cred_vers.
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* If you want to create a new ccache (with a unique name), you should use
|
|
Packit |
fd8b60 |
* cc_context_create_new_ccache() instead. If you want to create or reinitialize
|
|
Packit |
fd8b60 |
* the default cache, you should use cc_context_create_default_ccache().
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* If name is non-NULL and there is already a ccache named name:
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* \li the credentials in the ccache whose version is cred_vers are removed
|
|
Packit |
fd8b60 |
* \li the principal (of the existing ccache) associated with cred_vers is set to principal
|
|
Packit |
fd8b60 |
* \li a handle for the existing ccache is returned and all existing handles for the ccache remain valid
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* If no ccache named name already exists:
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* \li a new empty ccache is created
|
|
Packit |
fd8b60 |
* \li the principal of the new ccache associated with cred_vers is set to principal
|
|
Packit |
fd8b60 |
* \li a handle for the new ccache is returned
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* For a new ccache, the name should be any unique string. The name is not
|
|
Packit |
fd8b60 |
* intended to be presented to users.
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* If the created ccache is the first ccache in the collection, it is made
|
|
Packit |
fd8b60 |
* the default ccache. Note that normally it is undesirable to create the first
|
|
Packit |
fd8b60 |
* ccache with a name different from the default ccache name (as returned by
|
|
Packit |
fd8b60 |
* cc_context_get_default_ccache_name()); see the description of
|
|
Packit |
fd8b60 |
* cc_context_get_default_ccache_name() for details.
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* The principal should be a C string containing an unparsed Kerberos
|
|
Packit |
fd8b60 |
* principal in the format of the appropriate Kerberos version,
|
|
Packit |
fd8b60 |
* i.e. \verbatim foo/bar/@BAZ \endverbatim for Kerberos v5.
|
|
Packit |
fd8b60 |
*/
|
|
Packit |
fd8b60 |
cc_int32 (*create_ccache) (cc_context_t in_context,
|
|
Packit |
fd8b60 |
const char *in_name,
|
|
Packit |
fd8b60 |
cc_uint32 in_cred_vers,
|
|
Packit |
fd8b60 |
const char *in_principal,
|
|
Packit |
fd8b60 |
cc_ccache_t *out_ccache);
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
/*!
|
|
Packit |
fd8b60 |
* \param in_context the context object for the cache collection.
|
|
Packit |
fd8b60 |
* \param in_cred_vers the version of the credentials the new default ccache will hold
|
|
Packit |
fd8b60 |
* \param in_principal the client principal of the credentials the new default ccache will hold
|
|
Packit |
fd8b60 |
* \param out_ccache on exit, a ccache object for the newly created default ccache
|
|
Packit |
fd8b60 |
* \return On success, #ccNoError. On failure, an error code representing the failure.
|
|
Packit |
fd8b60 |
* \brief \b cc_context_create_default_ccache(): Create a new default ccache.
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* Create the default credentials cache. The behavior of this function is
|
|
Packit |
fd8b60 |
* similar to that of cc_create_ccache(). If there is a default ccache
|
|
Packit |
fd8b60 |
* (which is always the case except when there are no ccaches at all in
|
|
Packit |
fd8b60 |
* the collection), it is initialized with the specified credentials version
|
|
Packit |
fd8b60 |
* and principal, as per cc_create_ccache(); otherwise, a new ccache is
|
|
Packit |
fd8b60 |
* created, and its name is the name returned by
|
|
Packit |
fd8b60 |
* cc_context_get_default_ccache_name().
|
|
Packit |
fd8b60 |
*/
|
|
Packit |
fd8b60 |
cc_int32 (*create_default_ccache) (cc_context_t in_context,
|
|
Packit |
fd8b60 |
cc_uint32 in_cred_vers,
|
|
Packit |
fd8b60 |
const char *in_principal,
|
|
Packit |
fd8b60 |
cc_ccache_t *out_ccache);
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
/*!
|
|
Packit |
fd8b60 |
* \param in_context the context object for the cache collection.
|
|
Packit |
fd8b60 |
* \param in_cred_vers the version of the credentials the new ccache will hold
|
|
Packit |
fd8b60 |
* \param in_principal the client principal of the credentials the new ccache will hold
|
|
Packit |
fd8b60 |
* \param out_ccache on exit, a ccache object for the newly created ccache
|
|
Packit |
fd8b60 |
* \return On success, #ccNoError. On failure, an error code representing the failure.
|
|
Packit |
fd8b60 |
* \brief \b cc_context_create_new_ccache(): Create a new uniquely named ccache.
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* Create a new unique credentials cache. The behavior of this function
|
|
Packit |
fd8b60 |
* is similar to that of cc_create_ccache(). If there are no ccaches, and
|
|
Packit |
fd8b60 |
* therefore no default ccache, the new ccache is created with the default
|
|
Packit |
fd8b60 |
* ccache name as would be returned by get_default_ccache_name(). If there
|
|
Packit |
fd8b60 |
* are some ccaches, and therefore there is a default ccache, the new ccache
|
|
Packit |
fd8b60 |
* is created with a new unique name. Clearly, this function never reinitializes
|
|
Packit |
fd8b60 |
* a ccache, since it always uses a unique name.
|
|
Packit |
fd8b60 |
*/
|
|
Packit |
fd8b60 |
cc_int32 (*create_new_ccache) (cc_context_t in_context,
|
|
Packit |
fd8b60 |
cc_uint32 in_cred_vers,
|
|
Packit |
fd8b60 |
const char *in_principal,
|
|
Packit |
fd8b60 |
cc_ccache_t *out_ccache);
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
/*!
|
|
Packit |
fd8b60 |
* \param in_context the context object for the cache collection.
|
|
Packit |
fd8b60 |
* \param out_iterator on exit, a ccache iterator object for the ccache collection.
|
|
Packit |
fd8b60 |
* \return On success, #ccNoError. On failure, an error code representing the failure.
|
|
Packit |
fd8b60 |
* \brief \b cc_context_new_ccache_iterator(): Get an iterator for the cache collection.
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* Used to allocate memory and initialize iterator. Successive calls to iterator's
|
|
Packit |
fd8b60 |
* next() function will return ccaches in the collection.
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* If changes are made to the collection while an iterator is being used
|
|
Packit |
fd8b60 |
* on it, the iterator must return at least the intersection, and at most
|
|
Packit |
fd8b60 |
* the union, of the set of ccaches that were present when the iteration
|
|
Packit |
fd8b60 |
* began and the set of ccaches that are present when it ends.
|
|
Packit |
fd8b60 |
*/
|
|
Packit |
fd8b60 |
cc_int32 (*new_ccache_iterator) (cc_context_t in_context,
|
|
Packit |
fd8b60 |
cc_ccache_iterator_t *out_iterator);
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
/*!
|
|
Packit |
fd8b60 |
* \param in_context the context object for the cache collection.
|
|
Packit |
fd8b60 |
* \param in_lock_type the type of lock to obtain.
|
|
Packit |
fd8b60 |
* \param in_block whether or not the function should block if the lock cannot be obtained immediately.
|
|
Packit |
fd8b60 |
* \return On success, #ccNoError. On failure, an error code representing the failure.
|
|
Packit |
fd8b60 |
* \brief \b cc_context_lock(): Lock the cache collection.
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* Attempts to acquire an advisory lock for the ccache collection. Allowed values
|
|
Packit |
fd8b60 |
* for lock_type are:
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* \li cc_lock_read: a read lock.
|
|
Packit |
fd8b60 |
* \li cc_lock_write: a write lock
|
|
Packit |
fd8b60 |
* \li cc_lock_upgrade: upgrade an already-obtained read lock to a write lock
|
|
Packit |
fd8b60 |
* \li cc_lock_downgrade: downgrade an already-obtained write lock to a read lock
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* If block is cc_lock_block, lock() will not return until the lock is acquired.
|
|
Packit |
fd8b60 |
* If block is cc_lock_noblock, lock() will return immediately, either acquiring
|
|
Packit |
fd8b60 |
* the lock and returning ccNoError, or failing to acquire the lock and returning
|
|
Packit |
fd8b60 |
* an error explaining why.
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* Locks apply only to the list of ccaches, not the contents of those ccaches. To
|
|
Packit |
fd8b60 |
* prevent callers participating in the advisory locking from changing the credentials
|
|
Packit |
fd8b60 |
* in a cache you must also lock that ccache with cc_ccache_lock(). This is so
|
|
Packit |
fd8b60 |
* that you can get the list of ccaches without preventing applications from
|
|
Packit |
fd8b60 |
* simultaneously obtaining service tickets.
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* To avoid having to deal with differences between thread semantics on different
|
|
Packit |
fd8b60 |
* platforms, locks are granted per context, rather than per thread or per process.
|
|
Packit |
fd8b60 |
* That means that different threads of execution have to acquire separate contexts
|
|
Packit |
fd8b60 |
* in order to be able to synchronize with each other.
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* The lock should be unlocked by using cc_context_unlock().
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* \note All locks are advisory. For example, callers which do not call
|
|
Packit |
fd8b60 |
* cc_context_lock() and cc_context_unlock() will not be prevented from writing
|
|
Packit |
fd8b60 |
* to the cache collection when you have a read lock. This is because the CCAPI
|
|
Packit |
fd8b60 |
* locking was added after the first release and thus adding mandatory locks would
|
|
Packit |
fd8b60 |
* have changed the user experience and performance of existing applications.
|
|
Packit |
fd8b60 |
*/
|
|
Packit |
fd8b60 |
cc_int32 (*lock) (cc_context_t in_context,
|
|
Packit |
fd8b60 |
cc_uint32 in_lock_type,
|
|
Packit |
fd8b60 |
cc_uint32 in_block);
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
/*!
|
|
Packit |
fd8b60 |
* \param in_context the context object for the cache collection.
|
|
Packit |
fd8b60 |
* \return On success, #ccNoError. On failure, an error code representing the failure.
|
|
Packit |
fd8b60 |
* \brief \b cc_context_unlock(): Unlock the cache collection.
|
|
Packit |
fd8b60 |
*/
|
|
Packit |
fd8b60 |
cc_int32 (*unlock) (cc_context_t in_cc_context);
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
/*!
|
|
Packit |
fd8b60 |
* \param in_context a context object.
|
|
Packit |
fd8b60 |
* \param in_compare_to_context a context object to compare with \a in_context.
|
|
Packit |
fd8b60 |
* \param out_equal on exit, whether or not the two contexts refer to the same cache collection.
|
|
Packit |
fd8b60 |
* \return On success, #ccNoError. On failure, an error code representing the failure.
|
|
Packit |
fd8b60 |
* \brief \b cc_context_compare(): Compare two context objects.
|
|
Packit |
fd8b60 |
*/
|
|
Packit |
fd8b60 |
cc_int32 (*compare) (cc_context_t in_cc_context,
|
|
Packit |
fd8b60 |
cc_context_t in_compare_to_context,
|
|
Packit |
fd8b60 |
cc_uint32 *out_equal);
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
/*!
|
|
Packit |
fd8b60 |
* \param in_context a context object.
|
|
Packit |
fd8b60 |
* \return On success, #ccNoError. On failure, an error code representing the failure.
|
|
Packit |
fd8b60 |
* \brief \b cc_context_wait_for_change(): Wait for the next change in the cache collection.
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* This function blocks until the next change is made to the cache collection
|
|
Packit |
fd8b60 |
* ccache collection. By repeatedly calling cc_context_wait_for_change() from
|
|
Packit |
fd8b60 |
* a worker thread the caller can effectively receive callbacks whenever the
|
|
Packit |
fd8b60 |
* cache collection changes. This is considerably more efficient than polling
|
|
Packit |
fd8b60 |
* with cc_context_get_change_time().
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* cc_context_wait_for_change() will return whenever:
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* \li a ccache is created
|
|
Packit |
fd8b60 |
* \li a ccache is destroyed
|
|
Packit |
fd8b60 |
* \li a credential is stored
|
|
Packit |
fd8b60 |
* \li a credential is removed
|
|
Packit |
fd8b60 |
* \li a ccache principal is changed
|
|
Packit |
fd8b60 |
* \li the default ccache is changed
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* \note In order to make sure that the caller doesn't miss any changes,
|
|
Packit |
fd8b60 |
* cc_context_wait_for_change() always returns immediately after the first time it
|
|
Packit |
fd8b60 |
* is called on a new context object. Callers must use the same context object
|
|
Packit |
fd8b60 |
* for successive calls to cc_context_wait_for_change() rather than creating a new
|
|
Packit |
fd8b60 |
* context for every call.
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* \sa get_change_time
|
|
Packit |
fd8b60 |
*/
|
|
Packit |
fd8b60 |
cc_int32 (*wait_for_change) (cc_context_t in_cc_context);
|
|
Packit |
fd8b60 |
};
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
/*!
|
|
Packit |
fd8b60 |
* Function pointer table for cc_ccache_t. For more information see
|
|
Packit |
fd8b60 |
* \ref cc_ccache_reference.
|
|
Packit |
fd8b60 |
*/
|
|
Packit |
fd8b60 |
struct cc_ccache_f {
|
|
Packit |
fd8b60 |
/*!
|
|
Packit |
fd8b60 |
* \param io_ccache the ccache object to release.
|
|
Packit |
fd8b60 |
* \return On success, #ccNoError. On failure, an error code representing the failure.
|
|
Packit |
fd8b60 |
* \brief \b cc_ccache_release(): Release memory associated with a cc_ccache_t object.
|
|
Packit |
fd8b60 |
* \note Does not modify the ccache. If you wish to remove the ccache see cc_ccache_destroy().
|
|
Packit |
fd8b60 |
*/
|
|
Packit |
fd8b60 |
cc_int32 (*release) (cc_ccache_t io_ccache);
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
/*!
|
|
Packit |
fd8b60 |
* \param io_ccache the ccache object to destroy and release.
|
|
Packit |
fd8b60 |
* \return On success, #ccNoError. On failure, an error code representing the failure.
|
|
Packit |
fd8b60 |
* \brief \b cc_ccache_destroy(): Destroy a ccache.
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* Destroy the ccache referred to by \a io_ccache and releases memory associated with
|
|
Packit |
fd8b60 |
* the \a io_ccache object. After this call \a io_ccache becomes invalid. If
|
|
Packit |
fd8b60 |
* \a io_ccache was the default ccache, the next ccache in the cache collection (if any)
|
|
Packit |
fd8b60 |
* becomes the new default.
|
|
Packit |
fd8b60 |
*/
|
|
Packit |
fd8b60 |
cc_int32 (*destroy) (cc_ccache_t io_ccache);
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
/*!
|
|
Packit |
fd8b60 |
* \param io_ccache a ccache object to make the new default ccache.
|
|
Packit |
fd8b60 |
* \return On success, #ccNoError. On failure, an error code representing the failure.
|
|
Packit |
fd8b60 |
* \brief \b cc_ccache_set_default(): Make a ccache the default ccache.
|
|
Packit |
fd8b60 |
*/
|
|
Packit |
fd8b60 |
cc_int32 (*set_default) (cc_ccache_t io_ccache);
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
/*!
|
|
Packit |
fd8b60 |
* \param in_ccache a ccache object.
|
|
Packit |
fd8b60 |
* \param out_credentials_version on exit, the credentials version of \a in_ccache.
|
|
Packit |
fd8b60 |
* \return On success, #ccNoError. On failure, an error code representing the failure.
|
|
Packit |
fd8b60 |
* \brief \b cc_ccache_get_credentials_version(): Get the credentials version of a ccache.
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* cc_ccache_get_credentials_version() returns one value of the enumerated
|
|
Packit |
fd8b60 |
* type cc_credentials_vers. The return value is #cc_credentials_v5 (if
|
|
Packit |
fd8b60 |
* ccache's v5 principal has been set). A ccache's principal is set with
|
|
Packit |
fd8b60 |
* one of cc_context_create_ccache(), cc_context_create_new_ccache(),
|
|
Packit |
fd8b60 |
* cc_context_create_default_ccache(), or cc_ccache_set_principal().
|
|
Packit |
fd8b60 |
*/
|
|
Packit |
fd8b60 |
cc_int32 (*get_credentials_version) (cc_ccache_t in_ccache,
|
|
Packit |
fd8b60 |
cc_uint32 *out_credentials_version);
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
/*!
|
|
Packit |
fd8b60 |
* \param in_ccache a ccache object.
|
|
Packit |
fd8b60 |
* \param out_name on exit, a cc_string_t representing the name of \a in_ccache.
|
|
Packit |
fd8b60 |
* \a out_name must be released with cc_string_release().
|
|
Packit |
fd8b60 |
* \return On success, #ccNoError. On failure, an error code representing the failure.
|
|
Packit |
fd8b60 |
* \brief \b cc_ccache_get_name(): Get the name of a ccache.
|
|
Packit |
fd8b60 |
*/
|
|
Packit |
fd8b60 |
cc_int32 (*get_name) (cc_ccache_t in_ccache,
|
|
Packit |
fd8b60 |
cc_string_t *out_name);
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
/*!
|
|
Packit |
fd8b60 |
* \param in_ccache a ccache object.
|
|
Packit |
fd8b60 |
* \param in_credentials_version the credentials version to get the principal for.
|
|
Packit |
fd8b60 |
* \param out_principal on exit, a cc_string_t representing the principal of \a in_ccache.
|
|
Packit |
fd8b60 |
* \a out_principal must be released with cc_string_release().
|
|
Packit |
fd8b60 |
* \return On success, #ccNoError. On failure, an error code representing the failure.
|
|
Packit |
fd8b60 |
* \brief \b cc_ccache_get_principal(): Get the principal of a ccache.
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* Return the principal for the ccache that was set via cc_context_create_ccache(),
|
|
Packit |
fd8b60 |
* cc_context_create_default_ccache(), cc_context_create_new_ccache(), or
|
|
Packit |
fd8b60 |
* cc_ccache_set_principal().
|
|
Packit |
fd8b60 |
*/
|
|
Packit |
fd8b60 |
cc_int32 (*get_principal) (cc_ccache_t in_ccache,
|
|
Packit |
fd8b60 |
cc_uint32 in_credentials_version,
|
|
Packit |
fd8b60 |
cc_string_t *out_principal);
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
/*!
|
|
Packit |
fd8b60 |
* \param in_ccache a ccache object.
|
|
Packit |
fd8b60 |
* \param in_credentials_version the credentials version to set the principal for.
|
|
Packit |
fd8b60 |
* \param in_principal a C string representing the new principal of \a in_ccache.
|
|
Packit |
fd8b60 |
* \return On success, #ccNoError. On failure, an error code representing the failure.
|
|
Packit |
fd8b60 |
* \brief \b cc_ccache_set_principal(): Set the principal of a ccache.
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* Set the a principal for ccache.
|
|
Packit |
fd8b60 |
*/
|
|
Packit |
fd8b60 |
cc_int32 (*set_principal) (cc_ccache_t io_ccache,
|
|
Packit |
fd8b60 |
cc_uint32 in_credentials_version,
|
|
Packit |
fd8b60 |
const char *in_principal);
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
/*!
|
|
Packit |
fd8b60 |
* \param io_ccache a ccache object.
|
|
Packit |
fd8b60 |
* \param in_credentials_union the credentials to store in \a io_ccache.
|
|
Packit |
fd8b60 |
* \return On success, #ccNoError. On failure, an error code representing the failure.
|
|
Packit |
fd8b60 |
* \brief \b cc_ccache_store_credentials(): Store credentials in a ccache.
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* Store a copy of credentials in the ccache.
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* See the description of the credentials types for the meaning of
|
|
Packit |
fd8b60 |
* cc_credentials_union fields.
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* Before credentials of a specific credential type can be stored in a
|
|
Packit |
fd8b60 |
* ccache, the corresponding principal version has to be set. That is,
|
|
Packit |
fd8b60 |
* before you can store Kerberos v5 credentials in a ccache, the Kerberos
|
|
Packit |
fd8b60 |
* v5 principal has to be set either by cc_context_create_ccache(),
|
|
Packit |
fd8b60 |
* cc_context_create_default_ccache(), cc_context_create_new_ccache(), or
|
|
Packit |
fd8b60 |
* cc_ccache_set_principal(); otherwise, ccErrBadCredentialsVersion is
|
|
Packit |
fd8b60 |
* returned.
|
|
Packit |
fd8b60 |
*/
|
|
Packit |
fd8b60 |
cc_int32 (*store_credentials) (cc_ccache_t io_ccache,
|
|
Packit |
fd8b60 |
const cc_credentials_union *in_credentials_union);
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
/*!
|
|
Packit |
fd8b60 |
* \param io_ccache a ccache object.
|
|
Packit |
fd8b60 |
* \param in_credentials the credentials to remove from \a io_ccache.
|
|
Packit |
fd8b60 |
* \return On success, #ccNoError. On failure, an error code representing the failure.
|
|
Packit |
fd8b60 |
* \brief \b cc_ccache_remove_credentials(): Remove credentials from a ccache.
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* Removes credentials from a ccache. Note that credentials must be previously
|
|
Packit |
fd8b60 |
* acquired from the CCache API; only exactly matching credentials will be
|
|
Packit |
fd8b60 |
* removed. (This places the burden of determining exactly which credentials
|
|
Packit |
fd8b60 |
* to remove on the caller, but ensures there is no ambigity about which
|
|
Packit |
fd8b60 |
* credentials will be removed.) cc_credentials_t objects can be obtained by
|
|
Packit |
fd8b60 |
* iterating over the ccache's credentials with cc_ccache_new_credentials_iterator().
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* If found, the credentials are removed from the ccache. The credentials
|
|
Packit |
fd8b60 |
* parameter is not modified and should be freed by the caller. It is
|
|
Packit |
fd8b60 |
* legitimate to call this function while an iterator is traversing the
|
|
Packit |
fd8b60 |
* ccache, and the deletion of a credential already returned by
|
|
Packit |
fd8b60 |
* cc_credentials_iterator_next() will not disturb sequence of credentials
|
|
Packit |
fd8b60 |
* returned by cc_credentials_iterator_next().
|
|
Packit |
fd8b60 |
*/
|
|
Packit |
fd8b60 |
cc_int32 (*remove_credentials) (cc_ccache_t io_ccache,
|
|
Packit |
fd8b60 |
cc_credentials_t in_credentials);
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
/*!
|
|
Packit |
fd8b60 |
* \param in_ccache a ccache object.
|
|
Packit |
fd8b60 |
* \param out_credentials_iterator a credentials iterator for \a io_ccache.
|
|
Packit |
fd8b60 |
* \return On success, #ccNoError. On failure, an error code representing the failure.
|
|
Packit |
fd8b60 |
* \brief \b cc_ccache_new_credentials_iterator(): Iterate over credentials in a ccache.
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* Allocates memory for iterator and initializes it. Successive calls to
|
|
Packit |
fd8b60 |
* cc_credentials_iterator_next() will return credentials from the ccache.
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* If changes are made to the ccache while an iterator is being used on it,
|
|
Packit |
fd8b60 |
* the iterator must return at least the intersection, and at most the union,
|
|
Packit |
fd8b60 |
* of the set of credentials that were in the ccache when the iteration began
|
|
Packit |
fd8b60 |
* and the set of credentials that are in the ccache when it ends.
|
|
Packit |
fd8b60 |
*/
|
|
Packit |
fd8b60 |
cc_int32 (*new_credentials_iterator) (cc_ccache_t in_ccache,
|
|
Packit |
fd8b60 |
cc_credentials_iterator_t *out_credentials_iterator);
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
/*!
|
|
Packit |
fd8b60 |
* \param io_source_ccache a ccache object to move.
|
|
Packit |
fd8b60 |
* \param io_destination_ccache a ccache object replace with the contents of \a io_source_ccache.
|
|
Packit |
fd8b60 |
* \return On success, #ccNoError. On failure, an error code representing the failure.
|
|
Packit |
fd8b60 |
* \brief \b cc_ccache_move(): Move the contents of one ccache into another, destroying the source.
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* cc_ccache_move() atomically copies the credentials, credential versions and principals
|
|
Packit |
fd8b60 |
* from one ccache to another. On successful completion \a io_source_ccache will be
|
|
Packit |
fd8b60 |
* released and the ccache it points to will be destroyed. Any credentials previously
|
|
Packit |
fd8b60 |
* in \a io_destination_ccache will be replaced with credentials from \a io_source_ccache.
|
|
Packit |
fd8b60 |
* The only part of \a io_destination_ccache which remains constant is the name. Any other
|
|
Packit |
fd8b60 |
* callers referring to \a io_destination_ccache will suddenly see new data in it.
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* Typically cc_ccache_move() is used when the caller wishes to safely overwrite the
|
|
Packit |
fd8b60 |
* contents of a ccache with new data which requires several steps to generate.
|
|
Packit |
fd8b60 |
* cc_ccache_move() allows the caller to create a temporary ccache
|
|
Packit |
fd8b60 |
* (which can be destroyed if any intermediate step fails) and the atomically copy
|
|
Packit |
fd8b60 |
* the temporary cache into the destination.
|
|
Packit |
fd8b60 |
*/
|
|
Packit |
fd8b60 |
cc_int32 (*move) (cc_ccache_t io_source_ccache,
|
|
Packit |
fd8b60 |
cc_ccache_t io_destination_ccache);
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
/*!
|
|
Packit |
fd8b60 |
* \param io_ccache the ccache object for the ccache you wish to lock.
|
|
Packit |
fd8b60 |
* \param in_lock_type the type of lock to obtain.
|
|
Packit |
fd8b60 |
* \param in_block whether or not the function should block if the lock cannot be obtained immediately.
|
|
Packit |
fd8b60 |
* \return On success, #ccNoError. On failure, an error code representing the failure.
|
|
Packit |
fd8b60 |
* \brief \b cc_ccache_lock(): Lock a ccache.
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* Attempts to acquire an advisory lock for a ccache. Allowed values for lock_type are:
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* \li cc_lock_read: a read lock.
|
|
Packit |
fd8b60 |
* \li cc_lock_write: a write lock
|
|
Packit |
fd8b60 |
* \li cc_lock_upgrade: upgrade an already-obtained read lock to a write lock
|
|
Packit |
fd8b60 |
* \li cc_lock_downgrade: downgrade an already-obtained write lock to a read lock
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* If block is cc_lock_block, lock() will not return until the lock is acquired.
|
|
Packit |
fd8b60 |
* If block is cc_lock_noblock, lock() will return immediately, either acquiring
|
|
Packit |
fd8b60 |
* the lock and returning ccNoError, or failing to acquire the lock and returning
|
|
Packit |
fd8b60 |
* an error explaining why.
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* To avoid having to deal with differences between thread semantics on different
|
|
Packit |
fd8b60 |
* platforms, locks are granted per ccache, rather than per thread or per process.
|
|
Packit |
fd8b60 |
* That means that different threads of execution have to acquire separate contexts
|
|
Packit |
fd8b60 |
* in order to be able to synchronize with each other.
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* The lock should be unlocked by using cc_ccache_unlock().
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* \note All locks are advisory. For example, callers which do not call
|
|
Packit |
fd8b60 |
* cc_ccache_lock() and cc_ccache_unlock() will not be prevented from writing
|
|
Packit |
fd8b60 |
* to the ccache when you have a read lock. This is because the CCAPI
|
|
Packit |
fd8b60 |
* locking was added after the first release and thus adding mandatory locks would
|
|
Packit |
fd8b60 |
* have changed the user experience and performance of existing applications.
|
|
Packit |
fd8b60 |
*/
|
|
Packit |
fd8b60 |
cc_int32 (*lock) (cc_ccache_t io_ccache,
|
|
Packit |
fd8b60 |
cc_uint32 in_lock_type,
|
|
Packit |
fd8b60 |
cc_uint32 in_block);
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
/*!
|
|
Packit |
fd8b60 |
* \param io_ccache a ccache object.
|
|
Packit |
fd8b60 |
* \return On success, #ccNoError. On failure, an error code representing the failure.
|
|
Packit |
fd8b60 |
* \brief \b cc_ccache_unlock(): Unlock a ccache.
|
|
Packit |
fd8b60 |
*/
|
|
Packit |
fd8b60 |
cc_int32 (*unlock) (cc_ccache_t io_ccache);
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
/*!
|
|
Packit |
fd8b60 |
* \param in_ccache a cache object.
|
|
Packit |
fd8b60 |
* \param out_last_default_time on exit, the last time the ccache was default.
|
|
Packit |
fd8b60 |
* \return On success, #ccNoError. On failure, an error code representing the failure.
|
|
Packit |
fd8b60 |
* \brief \b cc_ccache_get_change_time(): Get the last time a ccache was the default ccache.
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* This function returns the last time when the ccache was made the default ccache.
|
|
Packit |
fd8b60 |
* This allows clients to sort the ccaches by how recently they were default, which
|
|
Packit |
fd8b60 |
* is useful for user listing of ccaches. If the ccache was never default,
|
|
Packit |
fd8b60 |
* ccErrNeverDefault is returned.
|
|
Packit |
fd8b60 |
*/
|
|
Packit |
fd8b60 |
cc_int32 (*get_last_default_time) (cc_ccache_t in_ccache,
|
|
Packit |
fd8b60 |
cc_time_t *out_last_default_time);
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
/*!
|
|
Packit |
fd8b60 |
* \param in_ccache a cache object.
|
|
Packit |
fd8b60 |
* \param out_change_time on exit, the last time the ccache changed.
|
|
Packit |
fd8b60 |
* \return On success, #ccNoError. If the ccache was never the default ccache,
|
|
Packit |
fd8b60 |
* #ccErrNeverDefault. Otherwise, an error code representing the failure.
|
|
Packit |
fd8b60 |
* \brief \b cc_ccache_get_change_time(): Get the last time a ccache changed.
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* This function returns the time of the most recent change made to a ccache.
|
|
Packit |
fd8b60 |
* By maintaining a local copy the caller can deduce whether or not the ccache has
|
|
Packit |
fd8b60 |
* been modified since the previous call to cc_ccache_get_change_time().
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* The time returned by cc_ccache_get_change_time() increases whenever:
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* \li a credential is stored
|
|
Packit |
fd8b60 |
* \li a credential is removed
|
|
Packit |
fd8b60 |
* \li a ccache principal is changed
|
|
Packit |
fd8b60 |
* \li the ccache becomes the default ccache
|
|
Packit |
fd8b60 |
* \li the ccache is no longer the default ccache
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* \note In order to be able to compare two values returned by cc_ccache_get_change_time(),
|
|
Packit |
fd8b60 |
* the caller must use the same ccache object to acquire them. Callers should maintain a
|
|
Packit |
fd8b60 |
* single ccache object in memory for cc_ccache_get_change_time() calls rather than
|
|
Packit |
fd8b60 |
* creating a new ccache object for every call.
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* \sa wait_for_change
|
|
Packit |
fd8b60 |
*/
|
|
Packit |
fd8b60 |
cc_int32 (*get_change_time) (cc_ccache_t in_ccache,
|
|
Packit |
fd8b60 |
cc_time_t *out_change_time);
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
/*!
|
|
Packit |
fd8b60 |
* \param in_ccache a ccache object.
|
|
Packit |
fd8b60 |
* \param in_compare_to_ccache a ccache object to compare with \a in_ccache.
|
|
Packit |
fd8b60 |
* \param out_equal on exit, whether or not the two ccaches refer to the same ccache.
|
|
Packit |
fd8b60 |
* \return On success, #ccNoError. On failure, an error code representing the failure.
|
|
Packit |
fd8b60 |
* \brief \b cc_ccache_compare(): Compare two ccache objects.
|
|
Packit |
fd8b60 |
*/
|
|
Packit |
fd8b60 |
cc_int32 (*compare) (cc_ccache_t in_ccache,
|
|
Packit |
fd8b60 |
cc_ccache_t in_compare_to_ccache,
|
|
Packit |
fd8b60 |
cc_uint32 *out_equal);
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
/*!
|
|
Packit |
fd8b60 |
* \param in_ccache a ccache object.
|
|
Packit |
fd8b60 |
* \param in_credentials_version the credentials version to get the time offset for.
|
|
Packit |
fd8b60 |
* \param out_time_offset on exit, the KDC time offset for \a in_ccache for credentials version
|
|
Packit |
fd8b60 |
* \a in_credentials_version.
|
|
Packit |
fd8b60 |
* \return On success, #ccNoError if a time offset was obtained or #ccErrTimeOffsetNotSet
|
|
Packit |
fd8b60 |
* if a time offset has not been set. On failure, an error code representing the failure.
|
|
Packit |
fd8b60 |
* \brief \b cc_ccache_get_kdc_time_offset(): Get the KDC time offset for credentials in a ccache.
|
|
Packit |
fd8b60 |
* \sa set_kdc_time_offset, clear_kdc_time_offset
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* Sometimes the KDC and client's clocks get out of sync. cc_ccache_get_kdc_time_offset()
|
|
Packit |
fd8b60 |
* returns the difference between the KDC and client's clocks at the time credentials were
|
|
Packit |
fd8b60 |
* acquired. This offset allows callers to figure out how much time is left on a given
|
|
Packit |
fd8b60 |
* credential even though the end_time is based on the KDC's clock not the client's clock.
|
|
Packit |
fd8b60 |
*/
|
|
Packit |
fd8b60 |
cc_int32 (*get_kdc_time_offset) (cc_ccache_t in_ccache,
|
|
Packit |
fd8b60 |
cc_uint32 in_credentials_version,
|
|
Packit |
fd8b60 |
cc_time_t *out_time_offset);
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
/*!
|
|
Packit |
fd8b60 |
* \param in_ccache a ccache object.
|
|
Packit |
fd8b60 |
* \param in_credentials_version the credentials version to get the time offset for.
|
|
Packit |
fd8b60 |
* \param in_time_offset the new KDC time offset for \a in_ccache for credentials version
|
|
Packit |
fd8b60 |
* \a in_credentials_version.
|
|
Packit |
fd8b60 |
* \return On success, #ccNoError. On failure, an error code representing the failure.
|
|
Packit |
fd8b60 |
* \brief \b cc_ccache_set_kdc_time_offset(): Set the KDC time offset for credentials in a ccache.
|
|
Packit |
fd8b60 |
* \sa get_kdc_time_offset, clear_kdc_time_offset
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* Sometimes the KDC and client's clocks get out of sync. cc_ccache_set_kdc_time_offset()
|
|
Packit |
fd8b60 |
* sets the difference between the KDC and client's clocks at the time credentials were
|
|
Packit |
fd8b60 |
* acquired. This offset allows callers to figure out how much time is left on a given
|
|
Packit |
fd8b60 |
* credential even though the end_time is based on the KDC's clock not the client's clock.
|
|
Packit |
fd8b60 |
*/
|
|
Packit |
fd8b60 |
cc_int32 (*set_kdc_time_offset) (cc_ccache_t io_ccache,
|
|
Packit |
fd8b60 |
cc_uint32 in_credentials_version,
|
|
Packit |
fd8b60 |
cc_time_t in_time_offset);
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
/*!
|
|
Packit |
fd8b60 |
* \param in_ccache a ccache object.
|
|
Packit |
fd8b60 |
* \param in_credentials_version the credentials version to get the time offset for.
|
|
Packit |
fd8b60 |
* \return On success, #ccNoError. On failure, an error code representing the failure.
|
|
Packit |
fd8b60 |
* \brief \b cc_ccache_clear_kdc_time_offset(): Clear the KDC time offset for credentials in a ccache.
|
|
Packit |
fd8b60 |
* \sa get_kdc_time_offset, set_kdc_time_offset
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* Sometimes the KDC and client's clocks get out of sync. cc_ccache_clear_kdc_time_offset()
|
|
Packit |
fd8b60 |
* clears the difference between the KDC and client's clocks at the time credentials were
|
|
Packit |
fd8b60 |
* acquired. This offset allows callers to figure out how much time is left on a given
|
|
Packit |
fd8b60 |
* credential even though the end_time is based on the KDC's clock not the client's clock.
|
|
Packit |
fd8b60 |
*/
|
|
Packit |
fd8b60 |
cc_int32 (*clear_kdc_time_offset) (cc_ccache_t io_ccache,
|
|
Packit |
fd8b60 |
cc_uint32 in_credentials_version);
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
/*!
|
|
Packit |
fd8b60 |
* \param in_ccache a ccache object.
|
|
Packit |
fd8b60 |
* \return On success, #ccNoError. On failure, an error code representing the failure.
|
|
Packit |
fd8b60 |
* \brief \b cc_ccache_wait_for_change(): Wait for the next change to a ccache.
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* This function blocks until the next change is made to the ccache referenced by
|
|
Packit |
fd8b60 |
* \a in_ccache. By repeatedly calling cc_ccache_wait_for_change() from
|
|
Packit |
fd8b60 |
* a worker thread the caller can effectively receive callbacks whenever the
|
|
Packit |
fd8b60 |
* ccache changes. This is considerably more efficient than polling
|
|
Packit |
fd8b60 |
* with cc_ccache_get_change_time().
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* cc_ccache_wait_for_change() will return whenever:
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* \li a credential is stored
|
|
Packit |
fd8b60 |
* \li a credential is removed
|
|
Packit |
fd8b60 |
* \li the ccache principal is changed
|
|
Packit |
fd8b60 |
* \li the ccache becomes the default ccache
|
|
Packit |
fd8b60 |
* \li the ccache is no longer the default ccache
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* \note In order to make sure that the caller doesn't miss any changes,
|
|
Packit |
fd8b60 |
* cc_ccache_wait_for_change() always returns immediately after the first time it
|
|
Packit |
fd8b60 |
* is called on a new ccache object. Callers must use the same ccache object
|
|
Packit |
fd8b60 |
* for successive calls to cc_ccache_wait_for_change() rather than creating a new
|
|
Packit |
fd8b60 |
* ccache object for every call.
|
|
Packit |
fd8b60 |
*
|
|
Packit |
fd8b60 |
* \sa get_change_time
|
|
Packit |
fd8b60 |
*/
|
|
Packit |
fd8b60 |
cc_int32 (*wait_for_change) (cc_ccache_t in_ccache);
|
|
Packit |
fd8b60 |
};
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
/*!
|
|
Packit |
fd8b60 |
* Function pointer table for cc_string_t. For more information see
|
|
Packit |
fd8b60 |
* \ref cc_string_reference.
|
|
Packit |
fd8b60 |
*/
|
|
Packit |
fd8b60 |
struct cc_string_f {
|
|
Packit |
fd8b60 |
/*!
|
|
Packit |
fd8b60 |
* \param io_string the string object to release.
|
|
Packit |
fd8b60 |
* \return On success, #ccNoError. On failure, an error code representing the failure.
|
|
Packit |
fd8b60 |
* \brief \b cc_string_release(): Release memory associated with a cc_string_t object.
|
|
Packit |
fd8b60 |
*/
|
|
Packit |
fd8b60 |
cc_int32 (*release) (cc_string_t io_string);
|
|
Packit |
fd8b60 |
};
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
/*!
|
|
Packit |
fd8b60 |
* Function pointer table for cc_credentials_t. For more information see
|
|
Packit |
fd8b60 |
* \ref cc_credentials_reference.
|
|
Packit |
fd8b60 |
*/
|
|
Packit |
fd8b60 |
struct cc_credentials_f {
|
|
Packit |
fd8b60 |
/*!
|
|
Packit |
fd8b60 |
* \param io_credentials the credentials object to release.
|
|
Packit |
fd8b60 |
* \return On success, #ccNoError. On failure, an error code representing the failure.
|
|
Packit |
fd8b60 |
* \brief \b cc_credentials_release(): Release memory associated with a cc_credentials_t object.
|
|
Packit |
fd8b60 |
*/
|
|
Packit |
fd8b60 |
cc_int32 (*release) (cc_credentials_t io_credentials);
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
/*!
|
|
Packit |
fd8b60 |
* \param in_credentials a credentials object.
|
|
Packit |
fd8b60 |
* \param in_compare_to_credentials a credentials object to compare with \a in_credentials.
|
|
Packit |
fd8b60 |
* \param out_equal on exit, whether or not the two credentials objects refer to the
|
|
Packit |
fd8b60 |
* same credentials in the cache collection.
|
|
Packit |
fd8b60 |
* \return On success, #ccNoError. On failure, an error code representing the failure.
|
|
Packit |
fd8b60 |
* \brief \b cc_credentials_compare(): Compare two credentials objects.
|
|
Packit |
fd8b60 |
*/
|
|
Packit |
fd8b60 |
cc_int32 (*compare) (cc_credentials_t in_credentials,
|
|
Packit |
fd8b60 |
cc_credentials_t in_compare_to_credentials,
|
|
Packit |
fd8b60 |
cc_uint32 *out_equal);
|
|
Packit |
fd8b60 |
};
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
/*!
|
|
Packit |
fd8b60 |
* Function pointer table for cc_ccache_iterator_t. For more information see
|
|
Packit |
fd8b60 |
* \ref cc_ccache_iterator_reference.
|
|
Packit |
fd8b60 |
*/
|
|
Packit |
fd8b60 |
struct cc_ccache_iterator_f {
|
|
Packit |
fd8b60 |
/*!
|
|
Packit |
fd8b60 |
* \param io_ccache_iterator the ccache iterator object to release.
|
|
Packit |
fd8b60 |
* \return On success, #ccNoError. On failure, an error code representing the failure.
|
|
Packit |
fd8b60 |
* \brief \b cc_ccache_iterator_release(): Release memory associated with a cc_ccache_iterator_t object.
|
|
Packit |
fd8b60 |
*/
|
|
Packit |
fd8b60 |
cc_int32 (*release) (cc_ccache_iterator_t io_ccache_iterator);
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
/*!
|
|
Packit |
fd8b60 |
* \param in_ccache_iterator a ccache iterator object.
|
|
Packit |
fd8b60 |
* \param out_ccache on exit, the next ccache in the cache collection.
|
|
Packit |
fd8b60 |
* \return On success, #ccNoError if the next ccache in the cache collection was
|
|
Packit |
fd8b60 |
* obtained or #ccIteratorEnd if there are no more ccaches.
|
|
Packit |
fd8b60 |
* On failure, an error code representing the failure.
|
|
Packit |
fd8b60 |
* \brief \b cc_ccache_iterator_next(): Get the next ccache in the cache collection.
|
|
Packit |
fd8b60 |
*/
|
|
Packit |
fd8b60 |
cc_int32 (*next) (cc_ccache_iterator_t in_ccache_iterator,
|
|
Packit |
fd8b60 |
cc_ccache_t *out_ccache);
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
/*!
|
|
Packit |
fd8b60 |
* \param in_ccache_iterator a ccache iterator object.
|
|
Packit |
fd8b60 |
* \param out_ccache_iterator on exit, a copy of \a in_ccache_iterator.
|
|
Packit |
fd8b60 |
* \return On success, #ccNoError. On failure, an error code representing the failure.
|
|
Packit |
fd8b60 |
* \brief \b cc_ccache_iterator_clone(): Make a copy of a ccache iterator.
|
|
Packit |
fd8b60 |
*/
|
|
Packit |
fd8b60 |
cc_int32 (*clone) (cc_ccache_iterator_t in_ccache_iterator,
|
|
Packit |
fd8b60 |
cc_ccache_iterator_t *out_ccache_iterator);
|
|
Packit |
fd8b60 |
};
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
/*!
|
|
Packit |
fd8b60 |
* Function pointer table for cc_credentials_iterator_t. For more information see
|
|
Packit |
fd8b60 |
* \ref cc_credentials_iterator_reference.
|
|
Packit |
fd8b60 |
*/
|
|
Packit |
fd8b60 |
struct cc_credentials_iterator_f {
|
|
Packit |
fd8b60 |
/*!
|
|
Packit |
fd8b60 |
* \param io_credentials_iterator the credentials iterator object to release.
|
|
Packit |
fd8b60 |
* \return On success, #ccNoError. On failure, an error code representing the failure.
|
|
Packit |
fd8b60 |
* \brief \b cc_credentials_iterator_release(): Release memory associated with a cc_credentials_iterator_t object.
|
|
Packit |
fd8b60 |
*/
|
|
Packit |
fd8b60 |
cc_int32 (*release) (cc_credentials_iterator_t io_credentials_iterator);
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
/*!
|
|
Packit |
fd8b60 |
* \param in_credentials_iterator a credentials iterator object.
|
|
Packit |
fd8b60 |
* \param out_credentials on exit, the next credentials in the ccache.
|
|
Packit |
fd8b60 |
* \return On success, #ccNoError if the next credential in the ccache was obtained
|
|
Packit |
fd8b60 |
* or #ccIteratorEnd if there are no more credentials.
|
|
Packit |
fd8b60 |
* On failure, an error code representing the failure.
|
|
Packit |
fd8b60 |
* \brief \b cc_credentials_iterator_next(): Get the next credentials in the ccache.
|
|
Packit |
fd8b60 |
*/
|
|
Packit |
fd8b60 |
cc_int32 (*next) (cc_credentials_iterator_t in_credentials_iterator,
|
|
Packit |
fd8b60 |
cc_credentials_t *out_credentials);
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
/*!
|
|
Packit |
fd8b60 |
* \ingroup cc_credentials_iterator_reference
|
|
Packit |
fd8b60 |
* \param in_credentials_iterator a credentials iterator object.
|
|
Packit |
fd8b60 |
* \param out_credentials_iterator on exit, a copy of \a in_credentials_iterator.
|
|
Packit |
fd8b60 |
* \return On success, #ccNoError. On failure, an error code representing the failure.
|
|
Packit |
fd8b60 |
* \brief \b cc_credentials_iterator_clone(): Make a copy of a credentials iterator.
|
|
Packit |
fd8b60 |
*/
|
|
Packit |
fd8b60 |
cc_int32 (*clone) (cc_credentials_iterator_t in_credentials_iterator,
|
|
Packit |
fd8b60 |
cc_credentials_iterator_t *out_credentials_iterator);
|
|
Packit |
fd8b60 |
};
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
/*!
|
|
Packit |
fd8b60 |
* \ingroup cc_context_reference
|
|
Packit |
fd8b60 |
* \param out_context on exit, a new context object. Must be free with cc_context_release().
|
|
Packit |
fd8b60 |
* \param in_version the requested API version. This should be the maximum version the
|
|
Packit |
fd8b60 |
* application supports.
|
|
Packit |
fd8b60 |
* \param out_supported_version if non-NULL, on exit contains the maximum API version
|
|
Packit |
fd8b60 |
* supported by the implementation.
|
|
Packit |
fd8b60 |
* \param out_vendor if non-NULL, on exit contains a pointer to a read-only C string which
|
|
Packit |
fd8b60 |
* contains a string describing the vendor which implemented the credentials cache API.
|
|
Packit |
fd8b60 |
* \return On success, #ccNoError. On failure, an error code representing the failure.
|
|
Packit |
fd8b60 |
* May return CCAPI v2 error CC_BAD_API_VERSION if #ccapi_version_2 is passed in.
|
|
Packit |
fd8b60 |
* \brief Initialize a new cc_context.
|
|
Packit |
fd8b60 |
*/
|
|
Packit |
fd8b60 |
CCACHE_API cc_int32 cc_initialize (cc_context_t *out_context,
|
|
Packit |
fd8b60 |
cc_int32 in_version,
|
|
Packit |
fd8b60 |
cc_int32 *out_supported_version,
|
|
Packit |
fd8b60 |
char const **out_vendor);
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
/*! \defgroup helper_macros CCAPI Function Helper Macros
|
|
Packit |
fd8b60 |
* @{ */
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
/*! Helper macro for cc_context_f release() */
|
|
Packit |
fd8b60 |
#define cc_context_release(context) \
|
|
Packit |
fd8b60 |
((context) -> functions -> release (context))
|
|
Packit |
fd8b60 |
/*! Helper macro for cc_context_f get_change_time() */
|
|
Packit |
fd8b60 |
#define cc_context_get_change_time(context, change_time) \
|
|
Packit |
fd8b60 |
((context) -> functions -> get_change_time (context, change_time))
|
|
Packit |
fd8b60 |
/*! Helper macro for cc_context_f get_default_ccache_name() */
|
|
Packit |
fd8b60 |
#define cc_context_get_default_ccache_name(context, name) \
|
|
Packit |
fd8b60 |
((context) -> functions -> get_default_ccache_name (context, name))
|
|
Packit |
fd8b60 |
/*! Helper macro for cc_context_f open_ccache() */
|
|
Packit |
fd8b60 |
#define cc_context_open_ccache(context, name, ccache) \
|
|
Packit |
fd8b60 |
((context) -> functions -> open_ccache (context, name, ccache))
|
|
Packit |
fd8b60 |
/*! Helper macro for cc_context_f open_default_ccache() */
|
|
Packit |
fd8b60 |
#define cc_context_open_default_ccache(context, ccache) \
|
|
Packit |
fd8b60 |
((context) -> functions -> open_default_ccache (context, ccache))
|
|
Packit |
fd8b60 |
/*! Helper macro for cc_context_f create_ccache() */
|
|
Packit |
fd8b60 |
#define cc_context_create_ccache(context, name, version, principal, ccache) \
|
|
Packit |
fd8b60 |
((context) -> functions -> create_ccache (context, name, version, principal, ccache))
|
|
Packit |
fd8b60 |
/*! Helper macro for cc_context_f create_default_ccache() */
|
|
Packit |
fd8b60 |
#define cc_context_create_default_ccache(context, version, principal, ccache) \
|
|
Packit |
fd8b60 |
((context) -> functions -> create_default_ccache (context, version, principal, ccache))
|
|
Packit |
fd8b60 |
/*! Helper macro for cc_context_f create_new_ccache() */
|
|
Packit |
fd8b60 |
#define cc_context_create_new_ccache(context, version, principal, ccache) \
|
|
Packit |
fd8b60 |
((context) -> functions -> create_new_ccache (context, version, principal, ccache))
|
|
Packit |
fd8b60 |
/*! Helper macro for cc_context_f new_ccache_iterator() */
|
|
Packit |
fd8b60 |
#define cc_context_new_ccache_iterator(context, iterator) \
|
|
Packit |
fd8b60 |
((context) -> functions -> new_ccache_iterator (context, iterator))
|
|
Packit |
fd8b60 |
/*! Helper macro for cc_context_f lock() */
|
|
Packit |
fd8b60 |
#define cc_context_lock(context, type, block) \
|
|
Packit |
fd8b60 |
((context) -> functions -> lock (context, type, block))
|
|
Packit |
fd8b60 |
/*! Helper macro for cc_context_f unlock() */
|
|
Packit |
fd8b60 |
#define cc_context_unlock(context) \
|
|
Packit |
fd8b60 |
((context) -> functions -> unlock (context))
|
|
Packit |
fd8b60 |
/*! Helper macro for cc_context_f compare() */
|
|
Packit |
fd8b60 |
#define cc_context_compare(context, compare_to, equal) \
|
|
Packit |
fd8b60 |
((context) -> functions -> compare (context, compare_to, equal))
|
|
Packit |
fd8b60 |
/*! Helper macro for cc_context_f wait_for_change() */
|
|
Packit |
fd8b60 |
#define cc_context_wait_for_change(context) \
|
|
Packit |
fd8b60 |
((context) -> functions -> wait_for_change (context))
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
/*! Helper macro for cc_ccache_f release() */
|
|
Packit |
fd8b60 |
#define cc_ccache_release(ccache) \
|
|
Packit |
fd8b60 |
((ccache) -> functions -> release (ccache))
|
|
Packit |
fd8b60 |
/*! Helper macro for cc_ccache_f destroy() */
|
|
Packit |
fd8b60 |
#define cc_ccache_destroy(ccache) \
|
|
Packit |
fd8b60 |
((ccache) -> functions -> destroy (ccache))
|
|
Packit |
fd8b60 |
/*! Helper macro for cc_ccache_f set_default() */
|
|
Packit |
fd8b60 |
#define cc_ccache_set_default(ccache) \
|
|
Packit |
fd8b60 |
((ccache) -> functions -> set_default (ccache))
|
|
Packit |
fd8b60 |
/*! Helper macro for cc_ccache_f get_credentials_version() */
|
|
Packit |
fd8b60 |
#define cc_ccache_get_credentials_version(ccache, version) \
|
|
Packit |
fd8b60 |
((ccache) -> functions -> get_credentials_version (ccache, version))
|
|
Packit |
fd8b60 |
/*! Helper macro for cc_ccache_f get_name() */
|
|
Packit |
fd8b60 |
#define cc_ccache_get_name(ccache, name) \
|
|
Packit |
fd8b60 |
((ccache) -> functions -> get_name (ccache, name))
|
|
Packit |
fd8b60 |
/*! Helper macro for cc_ccache_f get_principal() */
|
|
Packit |
fd8b60 |
#define cc_ccache_get_principal(ccache, version, principal) \
|
|
Packit |
fd8b60 |
((ccache) -> functions -> get_principal (ccache, version, principal))
|
|
Packit |
fd8b60 |
/*! Helper macro for cc_ccache_f set_principal() */
|
|
Packit |
fd8b60 |
#define cc_ccache_set_principal(ccache, version, principal) \
|
|
Packit |
fd8b60 |
((ccache) -> functions -> set_principal (ccache, version, principal))
|
|
Packit |
fd8b60 |
/*! Helper macro for cc_ccache_f store_credentials() */
|
|
Packit |
fd8b60 |
#define cc_ccache_store_credentials(ccache, credentials) \
|
|
Packit |
fd8b60 |
((ccache) -> functions -> store_credentials (ccache, credentials))
|
|
Packit |
fd8b60 |
/*! Helper macro for cc_ccache_f remove_credentials() */
|
|
Packit |
fd8b60 |
#define cc_ccache_remove_credentials(ccache, credentials) \
|
|
Packit |
fd8b60 |
((ccache) -> functions -> remove_credentials (ccache, credentials))
|
|
Packit |
fd8b60 |
/*! Helper macro for cc_ccache_f new_credentials_iterator() */
|
|
Packit |
fd8b60 |
#define cc_ccache_new_credentials_iterator(ccache, iterator) \
|
|
Packit |
fd8b60 |
((ccache) -> functions -> new_credentials_iterator (ccache, iterator))
|
|
Packit |
fd8b60 |
/*! Helper macro for cc_ccache_f lock() */
|
|
Packit |
fd8b60 |
#define cc_ccache_lock(ccache, type, block) \
|
|
Packit |
fd8b60 |
((ccache) -> functions -> lock (ccache, type, block))
|
|
Packit |
fd8b60 |
/*! Helper macro for cc_ccache_f unlock() */
|
|
Packit |
fd8b60 |
#define cc_ccache_unlock(ccache) \
|
|
Packit |
fd8b60 |
((ccache) -> functions -> unlock (ccache))
|
|
Packit |
fd8b60 |
/*! Helper macro for cc_ccache_f get_last_default_time() */
|
|
Packit |
fd8b60 |
#define cc_ccache_get_last_default_time(ccache, last_default_time) \
|
|
Packit |
fd8b60 |
((ccache) -> functions -> get_last_default_time (ccache, last_default_time))
|
|
Packit |
fd8b60 |
/*! Helper macro for cc_ccache_f get_change_time() */
|
|
Packit |
fd8b60 |
#define cc_ccache_get_change_time(ccache, change_time) \
|
|
Packit |
fd8b60 |
((ccache) -> functions -> get_change_time (ccache, change_time))
|
|
Packit |
fd8b60 |
/*! Helper macro for cc_ccache_f move() */
|
|
Packit |
fd8b60 |
#define cc_ccache_move(source, destination) \
|
|
Packit |
fd8b60 |
((source) -> functions -> move (source, destination))
|
|
Packit |
fd8b60 |
/*! Helper macro for cc_ccache_f compare() */
|
|
Packit |
fd8b60 |
#define cc_ccache_compare(ccache, compare_to, equal) \
|
|
Packit |
fd8b60 |
((ccache) -> functions -> compare (ccache, compare_to, equal))
|
|
Packit |
fd8b60 |
/*! Helper macro for cc_ccache_f get_kdc_time_offset() */
|
|
Packit |
fd8b60 |
#define cc_ccache_get_kdc_time_offset(ccache, version, time_offset) \
|
|
Packit |
fd8b60 |
((ccache) -> functions -> get_kdc_time_offset (ccache, version, time_offset))
|
|
Packit |
fd8b60 |
/*! Helper macro for cc_ccache_f set_kdc_time_offset() */
|
|
Packit |
fd8b60 |
#define cc_ccache_set_kdc_time_offset(ccache, version, time_offset) \
|
|
Packit |
fd8b60 |
((ccache) -> functions -> set_kdc_time_offset (ccache, version, time_offset))
|
|
Packit |
fd8b60 |
/*! Helper macro for cc_ccache_f clear_kdc_time_offset() */
|
|
Packit |
fd8b60 |
#define cc_ccache_clear_kdc_time_offset(ccache, version) \
|
|
Packit |
fd8b60 |
((ccache) -> functions -> clear_kdc_time_offset (ccache, version))
|
|
Packit |
fd8b60 |
/*! Helper macro for cc_ccache_f wait_for_change() */
|
|
Packit |
fd8b60 |
#define cc_ccache_wait_for_change(ccache) \
|
|
Packit |
fd8b60 |
((ccache) -> functions -> wait_for_change (ccache))
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
/*! Helper macro for cc_string_f release() */
|
|
Packit |
fd8b60 |
#define cc_string_release(string) \
|
|
Packit |
fd8b60 |
((string) -> functions -> release (string))
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
/*! Helper macro for cc_credentials_f release() */
|
|
Packit |
fd8b60 |
#define cc_credentials_release(credentials) \
|
|
Packit |
fd8b60 |
((credentials) -> functions -> release (credentials))
|
|
Packit |
fd8b60 |
/*! Helper macro for cc_credentials_f compare() */
|
|
Packit |
fd8b60 |
#define cc_credentials_compare(credentials, compare_to, equal) \
|
|
Packit |
fd8b60 |
((credentials) -> functions -> compare (credentials, compare_to, equal))
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
/*! Helper macro for cc_ccache_iterator_f release() */
|
|
Packit |
fd8b60 |
#define cc_ccache_iterator_release(iterator) \
|
|
Packit |
fd8b60 |
((iterator) -> functions -> release (iterator))
|
|
Packit |
fd8b60 |
/*! Helper macro for cc_ccache_iterator_f next() */
|
|
Packit |
fd8b60 |
#define cc_ccache_iterator_next(iterator, ccache) \
|
|
Packit |
fd8b60 |
((iterator) -> functions -> next (iterator, ccache))
|
|
Packit |
fd8b60 |
/*! Helper macro for cc_ccache_iterator_f clone() */
|
|
Packit |
fd8b60 |
#define cc_ccache_iterator_clone(iterator, new_iterator) \
|
|
Packit |
fd8b60 |
((iterator) -> functions -> clone (iterator, new_iterator))
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
/*! Helper macro for cc_credentials_iterator_f release() */
|
|
Packit |
fd8b60 |
#define cc_credentials_iterator_release(iterator) \
|
|
Packit |
fd8b60 |
((iterator) -> functions -> release (iterator))
|
|
Packit |
fd8b60 |
/*! Helper macro for cc_credentials_iterator_f next() */
|
|
Packit |
fd8b60 |
#define cc_credentials_iterator_next(iterator, credentials) \
|
|
Packit |
fd8b60 |
((iterator) -> functions -> next (iterator, credentials))
|
|
Packit |
fd8b60 |
/*! Helper macro for cc_credentials_iterator_f clone() */
|
|
Packit |
fd8b60 |
#define cc_credentials_iterator_clone(iterator, new_iterator) \
|
|
Packit |
fd8b60 |
((iterator) -> functions -> clone (iterator, new_iterator))
|
|
Packit |
fd8b60 |
/*!@}*/
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
#if TARGET_OS_MAC
|
|
Packit |
fd8b60 |
#pragma pack(pop)
|
|
Packit |
fd8b60 |
#endif
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
#ifdef __cplusplus
|
|
Packit |
fd8b60 |
}
|
|
Packit |
fd8b60 |
#endif /* __cplusplus */
|
|
Packit |
fd8b60 |
|
|
Packit |
fd8b60 |
#endif /* __CREDENTIALSCACHE__ */
|