1/* 2 * $Header$ 3 * 4 * Copyright 1998-2006 Massachusetts Institute of Technology. 5 * All Rights Reserved. 6 * 7 * Export of this software from the United States of America may 8 * require a specific license from the United States Government. 9 * It is the responsibility of any person or organization contemplating 10 * export to obtain such a license before exporting. 11 * 12 * WITHIN THAT CONSTRAINT, permission to use, copy, modify, and 13 * distribute this software and its documentation for any purpose and 14 * without fee is hereby granted, provided that the above copyright 15 * notice appear in all copies and that both that copyright notice and 16 * this permission notice appear in supporting documentation, and that 17 * the name of M.I.T. not be used in advertising or publicity pertaining 18 * to distribution of the software without specific, written prior 19 * permission. Furthermore if you modify this software you must label 20 * your software as modified software and not distribute it in such a 21 * fashion that it might be confused with the original M.I.T. software. 22 * M.I.T. makes no representations about the suitability of 23 * this software for any purpose. It is provided "as is" without express 24 * or implied warranty. 25 */ 26 27#ifndef __CREDENTIALSCACHE__ 28#define __CREDENTIALSCACHE__ 29 30#if defined(macintosh) || (defined(__MACH__) && defined(__APPLE__)) 31#include <TargetConditionals.h> 32 33/* Notifications which are sent when the ccache collection or a ccache change. 34 * Notifications are sent to the distributed notification center. 35 * The object for kCCAPICacheCollectionChangedNotification is NULL. 36 * The object for kCCAPICCacheChangedNotification is a CFString containing the 37 * name of the ccache. 38 * 39 * Note: Notifications are not sent if the CCacheServer crashes. */ 40#define kCCAPICacheCollectionChangedNotification CFSTR ("CCAPICacheCollectionChangedNotification") 41#define kCCAPICCacheChangedNotification CFSTR ("CCAPICCacheChangedNotification") 42#endif 43 44#if defined(_WIN32) 45#include <winsock.h> 46#include "win-mac.h" 47#else 48#include <stdint.h> 49#endif 50 51#ifdef __cplusplus 52extern "C" { 53#endif /* __cplusplus */ 54 55#if TARGET_OS_MAC 56#pragma pack(push,2) 57#endif 58 59#if defined(_WIN32) 60#define CCACHE_API __declspec(dllexport) 61 62#if _INTEGRAL_MAX_BITS >= 64 && _MSC_VER >= 1500 && !defined(_WIN64) && !defined(_USE_32BIT_TIME_T) 63#if defined(_TIME_T_DEFINED) || defined(_INC_IO) || defined(_INC_TIME) || defined(_INC_WCHAR) 64#error time_t has been defined as a 64-bit integer which is incompatible with Kerberos on this platform. 65#endif /* _TIME_T_DEFINED */ 66#define _USE_32BIT_TIME_T 67#endif 68#else 69#define CCACHE_API 70#endif 71 72#ifndef __has_extension 73#define __has_extension(x) 0 74#endif 75 76#ifndef cc_deprecated 77#if __has_extension(attribute_deprecated_with_message) 78#define cc_deprecated(x) __attribute__((deprecated(x))); 79#else 80#define cc_deprecated(x) __attribute__((deprecated)); 81#endif 82#endif /* cc_deprecated */ 83 84 85/*! 86 * \mainpage Credentials Cache API (CCAPI) Documentation 87 * 88 * \section toc Table of Contents 89 * 90 * \li \ref introduction 91 * \li \ref error_handling 92 * \li \ref synchronization_atomicity 93 * \li \ref memory_management 94 * \li \ref opaque_types 95 * 96 * \li \ref ccapi_constants_reference 97 * \li \ref ccapi_types_reference 98 * 99 * \li \ref cc_context_reference 100 * \li \ref cc_context_f "cc_context_t Functions" 101 * 102 * \li \ref cc_ccache_reference 103 * \li \ref cc_ccache_f "cc_ccache_t Functions" 104 * 105 * \li \ref cc_credentials_reference 106 * \li \ref cc_credentials_f "cc_credentials_t Functions" 107 * 108 * \li \ref cc_ccache_iterator_reference 109 * \li \ref cc_ccache_iterator_f "cc_ccache_iterator_t Functions" 110 * 111 * \li \ref cc_credentials_iterator_reference 112 * \li \ref cc_credentials_iterator_f "cc_credentials_iterator_t Functions" 113 * 114 * \li \ref cc_string_reference 115 * \li \ref cc_string_f "cc_string_t Functions" 116 * 117 * \section introduction Introduction 118 * 119 * This is the specification for an API which provides Credentials Cache 120 * services for both Kerberos v5 and v4. The idea behind this API is that 121 * multiple Kerberos implementations can share a single collection of 122 * credentials caches, mediated by this API specification. On the Mac OS 123 * and Microsoft Windows platforms this will allow single-login, even when 124 * more than one Kerberos shared library is in use on a particular system. 125 * 126 * Abstractly, a credentials cache collection contains one or more credentials 127 * caches, or ccaches. A ccache is uniquely identified by its name, which is 128 * a string internal to the API and not intended to be presented to users. 129 * The user presentable identifier of a ccache is its principal. 130 * 131 * Unlike the previous versions of the API, version 3 of the API stores both 132 * Kerberos v4 and v5 credentials in the same ccache. 133 * 134 * At any given time, one ccache is the "default" ccache. The exact meaning 135 * of a default ccache is OS-specific; refer to implementation requirements 136 * for details. 137 * 138 * \section error_handling Error Handling 139 * 140 * All functions of the API return some of the error constants listed FIXME; 141 * the exact list of error constants returned by any API function is provided 142 * in the function descriptions below. 143 * 144 * When returning an error constant other than ccNoError or ccIteratorEnd, API 145 * functions never modify any of the values passed in by reference. 146 * 147 * \section synchronization_atomicity Synchronization and Atomicity 148 * 149 * Every function in the API is atomic. In order to make a series of calls 150 * atomic, callers should lock the ccache or cache collection they are working 151 * with to advise other callers not to modify that container. Note that 152 * advisory locks are per container so even if you have a read lock on the cache 153 * collection other callers can obtain write locks on ccaches in that cache 154 * collection. 155 * 156 * Note that iterators do not iterate over ccaches and credentials atomically 157 * because locking ccaches and the cache collection over every iteration would 158 * degrade performance considerably under high load. However, iterators do 159 * guarantee a consistent view of items they are iterating over. Iterators 160 * will never return duplicate entries or skip entries when items are removed 161 * or added to the container they are iterating over. 162 * 163 * An application can always lock a ccache or the cache collection to guarantee 164 * that other callers participating in the advisory locking system do not 165 * modify the ccache or cache collection. 166 * 167 * Implementations should not use copy-on-write techniques to implement locks 168 * because those techniques imply that same parts of the ccache collection 169 * remain visible to some callers even though they are not present in the 170 * collection, which is a potential security risk. For example, a copy-on-write 171 * technique might make a copy of the entire collection when a read lock is 172 * acquired, so as to allow the owner of the lock to access the collection in 173 * an apparently unmodified state, while also allowing others to make 174 * modifications to the collection. However, this would also enable the owner 175 * of the lock to indefinitely (until the expiration time) use credentials that 176 * have actually been deleted from the collection. 177 * 178 * \section memory_management Object Memory Management 179 * 180 * The lifetime of an object returned by the API is until release() is called 181 * for it. Releasing one object has no effect on existence of any other object. 182 * For example, a ccache obtained within a context continue to exist when the 183 * context is released. 184 * 185 * Every object returned by the API (cc_context_t, cc_ccache_t, cc_ccache_iterator_t, 186 * cc_credentials_t, cc_credentials_iterator_t, cc_string_t) is owned by the 187 * caller of the API, and it is the responsibility of the caller to call release() 188 * for every object to prevent memory leaks. 189 * 190 * \section opaque_types Opaque Types 191 * 192 * All of the opaque high-level types in CCache API are implemented as structures 193 * of function pointers and private data. To perform some operation on a type, the 194 * caller of the API has to first obtain an instance of that type, and then call the 195 * appropriate function pointer from that instance. For example, to call 196 * get_change_time() on a cc_context_t, one would call cc_initialize() which creates 197 * a new cc_context_t and then call its get_change_time(), like this: 198 * 199 * \code 200 * cc_context_t context; 201 * cc_int32 err = cc_initialize (&context, ccapi_version_3, nil, nil); 202 * if (err == ccNoError) 203 * time = context->functions->get_change_time (context) 204 * \endcode 205 * 206 * All API functions also have convenience preprocessor macros, which make the API 207 * seem completely function-based. For example, cc_context_get_change_time 208 * (context, time) is equivalent to context->functions->get_change_time 209 * (context, time). The convenience macros follow the following naming convention: 210 * 211 * The API function some_function() 212 * \code 213 * cc_type_t an_object; 214 * result = an_object->functions->some_function (opaque_pointer, args) 215 * \endcode 216 * 217 * has an equivalent convenience macro of the form cc_type_some_function(): 218 * \code 219 * cc_type_t an_object; 220 * result = cc_type_some_function (an_object, args) 221 * \endcode 222 * 223 * The specifications below include the names for both the functions and the 224 * convenience macros, in that order. For clarity, it is recommended that clients 225 * using the API use the convenience macros, but that is merely a stylistic choice. 226 * 227 * Implementing the API in this manner allows us to extend and change the interface 228 * in the future, while preserving compatibility with older clients. 229 * 230 * For example, consider the case when the signature or the semantics of a cc_ccache_t 231 * function is changed. The API version number is incremented. The library 232 * implementation contains both a function with the old signature and semantics and 233 * a function with the new signature and semantics. When a context is created, the API 234 * version number used in that context is stored in the context, and therefore it can 235 * be used whenever a ccache is created in that context. When a ccache is created in a 236 * context with the old API version number, the function pointer structure for the 237 * ccache is filled with pointers to functions implementing the old semantics; when a 238 * ccache is created in a context with the new API version number, the function pointer 239 * structure for the ccache is filled with poitners to functions implementing the new 240 * semantics. 241 * 242 * Similarly, if a function is added to the API, the version number in the context can 243 * be used to decide whether to include the implementation of the new function in the 244 * appropriate function pointer structure or not. 245 */ 246 247/*! 248 * \defgroup ccapi_constants_reference Constants 249 * @{ 250 */ 251 252/*! 253 * API version numbers 254 * 255 * These constants are passed into cc_initialize() to indicate the version 256 * of the API the caller wants to use. 257 * 258 * CCAPI v1 and v2 are deprecated and should not be used. 259 */ 260enum { 261 ccapi_version_2 = 2, 262 ccapi_version_3 = 3, 263 ccapi_version_4 = 4, 264 ccapi_version_5 = 5, 265 ccapi_version_6 = 6, 266 ccapi_version_7 = 7, 267 ccapi_version_max = ccapi_version_7 268}; 269 270/*! 271 * Error codes 272 */ 273enum { 274 275 ccNoError = 0, /*!< Success. */ 276 277 ccIteratorEnd = 201, /*!< Iterator is done iterating. */ 278 ccErrBadParam, /*!< Bad parameter (NULL or invalid pointer where valid pointer expected). */ 279 ccErrNoMem, /*!< Not enough memory to complete the operation. */ 280 ccErrInvalidContext, /*!< Context is invalid (e.g., it was released). */ 281 ccErrInvalidCCache, /*!< CCache is invalid (e.g., it was released or destroyed). */ 282 283 /* 206 */ 284 ccErrInvalidString, /*!< String is invalid (e.g., it was released). */ 285 ccErrInvalidCredentials, /*!< Credentials are invalid (e.g., they were released), or they have a bad version. */ 286 ccErrInvalidCCacheIterator, /*!< CCache iterator is invalid (e.g., it was released). */ 287 ccErrInvalidCredentialsIterator, /*!< Credentials iterator is invalid (e.g., it was released). */ 288 ccErrInvalidLock, /*!< Lock is invalid (e.g., it was released). */ 289 290 /* 211 */ 291 ccErrBadName, /*!< Bad credential cache name format. */ 292 ccErrBadCredentialsVersion, /*!< Credentials version is invalid. */ 293 ccErrBadAPIVersion, /*!< Unsupported API version. */ 294 ccErrContextLocked, /*!< Context is already locked. */ 295 ccErrContextUnlocked, /*!< Context is not locked by the caller. */ 296 297 /* 216 */ 298 ccErrCCacheLocked, /*!< CCache is already locked. */ 299 ccErrCCacheUnlocked, /*!< CCache is not locked by the caller. */ 300 ccErrBadLockType, /*!< Bad lock type. */ 301 ccErrNeverDefault, /*!< CCache was never default. */ 302 ccErrCredentialsNotFound, /*!< Matching credentials not found in the ccache. */ 303 304 /* 221 */ 305 ccErrCCacheNotFound, /*!< Matching ccache not found in the collection. */ 306 ccErrContextNotFound, /*!< Matching cache collection not found. */ 307 ccErrServerUnavailable, /*!< CCacheServer is unavailable. */ 308 ccErrServerInsecure, /*!< CCacheServer has detected that it is running as the wrong user. */ 309 ccErrServerCantBecomeUID, /*!< CCacheServer failed to start running as the user. */ 310 311 /* 226 */ 312 ccErrTimeOffsetNotSet, /*!< KDC time offset not set for this ccache. */ 313 ccErrBadInternalMessage, /*!< The client and CCacheServer can't communicate (e.g., a version mismatch). */ 314 ccErrNotImplemented, /*!< API function not supported by this implementation. */ 315 ccErrClientNotFound /*!< CCacheServer has no record of the caller's process (e.g., the server crashed). */ 316}; 317 318/*! 319 * Credentials versions 320 * 321 * These constants are used in several places in the API to discern 322 * between Kerberos v4 and Kerberos v5. Not all values are valid 323 * inputs and outputs for all functions; function specifications 324 * below detail the allowed values. 325 * 326 * Kerberos version constants will always be a bit-field, and can be 327 * tested as such; for example the following test will tell you if 328 * a ccacheVersion includes v5 credentials: 329 * 330 * if ((ccacheVersion & cc_credentials_v5) != 0) 331 */ 332enum cc_credential_versions { 333 cc_credentials_v4 = 1, 334 cc_credentials_v5 = 2, 335 cc_credentials_v4_v5 = 3 336}; 337 338/*! 339 * Lock types 340 * 341 * These constants are used in the locking functions to describe the 342 * type of lock requested. Note that all CCAPI locks are advisory 343 * so only callers using the lock calls will be blocked by each other. 344 * This is because locking functions were introduced after the CCAPI 345 * came into common use and we did not want to break existing callers. 346 */ 347enum cc_lock_types { 348 cc_lock_read = 0, 349 cc_lock_write = 1, 350 cc_lock_upgrade = 2, 351 cc_lock_downgrade = 3 352}; 353 354/*! 355 * Locking Modes 356 * 357 * These constants are used in the advisory locking functions to 358 * describe whether or not the lock function should block waiting for 359 * a lock or return an error immediately. For example, attempting to 360 * acquire a lock with a non-blocking call will result in an error if the 361 * lock cannot be acquired; otherwise, the call will block until the lock 362 * can be acquired. 363 */ 364enum cc_lock_modes { 365 cc_lock_noblock = 0, 366 cc_lock_block = 1 367}; 368 369/*! 370 * Sizes of fields in cc_credentials_v4_t. 371 */ 372enum { 373 /* Make sure all of these are multiples of four (for alignment sanity) */ 374 cc_v4_name_size = 40, 375 cc_v4_instance_size = 40, 376 cc_v4_realm_size = 40, 377 cc_v4_ticket_size = 1254, 378 cc_v4_key_size = 8 379}; 380 381/*! 382 * String to key type (Kerberos v4 only) 383 */ 384enum cc_string_to_key_type { 385 cc_v4_stk_afs = 0, 386 cc_v4_stk_des = 1, 387 cc_v4_stk_columbia_special = 2, 388 cc_v4_stk_krb5 = 3, 389 cc_v4_stk_unknown = 4 390}; 391 392/*!@}*/ 393 394/*! 395 * \defgroup ccapi_types_reference Basic Types 396 * @{ 397 */ 398 399/*! Unsigned 32-bit integer type */ 400typedef uint32_t cc_uint32; 401/*! Signed 32-bit integer type */ 402typedef int32_t cc_int32; 403#if defined (WIN32) 404typedef __int64 cc_int64; 405typedef unsigned __int64 cc_uint64; 406#else 407/*! Unsigned 64-bit integer type */ 408typedef int64_t cc_int64; 409/*! Signed 64-bit integer type */ 410typedef uint64_t cc_uint64; 411#endif 412/*! 413 * The cc_time_t type is used to represent a time in seconds. The time must 414 * be stored as the number of seconds since midnight GMT on January 1, 1970. 415 */ 416typedef cc_uint32 cc_time_t; 417 418/*!@}*/ 419 420/*! 421 * \defgroup cc_context_reference cc_context_t Overview 422 * @{ 423 * 424 * The cc_context_t type gives the caller access to a ccache collection. 425 * Before being able to call any functions in the CCache API, the caller 426 * needs to acquire an instance of cc_context_t by calling cc_initialize(). 427 * 428 * For API function documentation see \ref cc_context_f. 429 */ 430struct cc_context_f; 431typedef struct cc_context_f cc_context_f; 432 433struct cc_context_d { 434 const cc_context_f *functions; 435#if TARGET_OS_MAC 436 const cc_context_f *vector_functions; 437#endif 438}; 439typedef struct cc_context_d cc_context_d; 440typedef cc_context_d *cc_context_t; 441 442/*!@}*/ 443 444/*! 445 * \defgroup cc_ccache_reference cc_ccache_t Overview 446 * @{ 447 * 448 * The cc_ccache_t type represents a reference to a ccache. 449 * Callers can access a ccache and the credentials stored in it 450 * via a cc_ccache_t. A cc_ccache_t can be acquired via 451 * cc_context_open_ccache(), cc_context_open_default_ccache(), or 452 * cc_ccache_iterator_next(). 453 * 454 * For API function documentation see \ref cc_ccache_f. 455 */ 456struct cc_ccache_f; 457typedef struct cc_ccache_f cc_ccache_f; 458 459struct cc_ccache_d { 460 const cc_ccache_f *functions; 461#if TARGET_OS_MAC 462 const cc_ccache_f *vector_functions; 463#endif 464}; 465typedef struct cc_ccache_d cc_ccache_d; 466typedef cc_ccache_d *cc_ccache_t; 467 468/*!@}*/ 469 470/*! 471 * \defgroup cc_ccache_iterator_reference cc_ccache_iterator_t Overview 472 * @{ 473 * 474 * The cc_ccache_iterator_t type represents an iterator that 475 * iterates over a set of ccaches and returns them in all in some 476 * order. A new instance of this type can be obtained by calling 477 * cc_context_new_ccache_iterator(). 478 * 479 * For API function documentation see \ref cc_ccache_iterator_f. 480 */ 481struct cc_ccache_iterator_f; 482typedef struct cc_ccache_iterator_f cc_ccache_iterator_f; 483 484struct cc_ccache_iterator_d { 485 const cc_ccache_iterator_f *functions; 486#if TARGET_OS_MAC 487 const cc_ccache_iterator_f *vector_functions; 488#endif 489}; 490typedef struct cc_ccache_iterator_d cc_ccache_iterator_d; 491typedef cc_ccache_iterator_d *cc_ccache_iterator_t; 492/*!@}*/ 493 494/*! 495 * \defgroup cc_credentials_reference cc_credentials_t Overview 496 * @{ 497 * 498 * The cc_credentials_t type is used to store a single set of 499 * credentials for either Kerberos v4 or Kerberos v5. In addition 500 * to its only function, release(), it contains a pointer to a 501 * cc_credentials_union structure. A cc_credentials_union 502 * structure contains an integer of the enumerator type 503 * cc_credentials_version, which is either #cc_credentials_v4 or 504 * #cc_credentials_v5, and a pointer union, which contains either a 505 * cc_credentials_v4_t pointer or a cc_credentials_v5_t pointer, 506 * depending on the value in version. 507 * 508 * Variables of the type cc_credentials_t are allocated by the CCAPI 509 * implementation, and should be released with their release() 510 * function. API functions which receive credentials structures 511 * from the caller always accept cc_credentials_union, which is 512 * allocated by the caller, and accordingly disposed by the caller. 513 * 514 * For API functions see \ref cc_credentials_f. 515 */ 516 517/*! 518 * If a cc_credentials_t variable is used to store Kerberos v4 519 * credentials, then credentials.credentials_v4 points to a v4 520 * credentials structure. This structure is similar to a 521 * krb4 API CREDENTIALS structure. 522 */ 523struct cc_credentials_v4_t { 524 cc_uint32 version; 525 /*! A properly quoted string representation of the first component of the client principal */ 526 char principal [cc_v4_name_size]; 527 /*! A properly quoted string representation of the second component of the client principal */ 528 char principal_instance [cc_v4_instance_size]; 529 /*! A properly quoted string representation of the first component of the service principal */ 530 char service [cc_v4_name_size]; 531 /*! A properly quoted string representation of the second component of the service principal */ 532 char service_instance [cc_v4_instance_size]; 533 /*! A properly quoted string representation of the realm */ 534 char realm [cc_v4_realm_size]; 535 /*! Ticket session key */ 536 unsigned char session_key [cc_v4_key_size]; 537 /*! Key version number */ 538 cc_int32 kvno; 539 /*! String to key type used. See cc_string_to_key_type for valid values */ 540 cc_int32 string_to_key_type; 541 /*! Time when the ticket was issued */ 542 cc_time_t issue_date; 543 /*! Ticket lifetime in 5 minute units */ 544 cc_int32 lifetime; 545 /*! IPv4 address of the client the ticket was issued for */ 546 cc_uint32 address; 547 /*! Ticket size (no greater than cc_v4_ticket_size) */ 548 cc_int32 ticket_size; 549 /*! Ticket data */ 550 unsigned char ticket [cc_v4_ticket_size]; 551}; 552typedef struct cc_credentials_v4_t cc_credentials_v4_t; 553 554/*! 555 * The CCAPI data structure. This structure is similar to a krb5_data structure. 556 * In a v5 credentials structure, cc_data structures are used 557 * to store tagged variable-length binary data. Specifically, 558 * for cc_credentials_v5.ticket and 559 * cc_credentials_v5.second_ticket, the cc_data.type field must 560 * be zero. For the cc_credentials_v5.addresses, 561 * cc_credentials_v5.authdata, and cc_credentials_v5.keyblock, 562 * the cc_data.type field should be the address type, 563 * authorization data type, and encryption type, as defined by 564 * the Kerberos v5 protocol definition. 565 */ 566struct cc_data { 567 /*! The type of the data as defined by the krb5_data structure. */ 568 cc_uint32 type; 569 /*! The length of \a data. */ 570 cc_uint32 length; 571 /*! The data buffer. */ 572 void* data; 573}; 574typedef struct cc_data cc_data; 575 576/*! 577 * If a cc_credentials_t variable is used to store Kerberos v5 c 578 * redentials, and then credentials.credentials_v5 points to a 579 * v5 credentials structure. This structure is similar to a 580 * krb5_creds structure. 581 */ 582struct cc_credentials_v5_t { 583 /*! A properly quoted string representation of the client principal. */ 584 char* client; 585 /*! A properly quoted string representation of the service principal. */ 586 char* server; 587 /*! Session encryption key info. */ 588 cc_data keyblock; 589 /*! The time when the ticket was issued. */ 590 cc_time_t authtime; 591 /*! The time when the ticket becomes valid. */ 592 cc_time_t starttime; 593 /*! The time when the ticket expires. */ 594 cc_time_t endtime; 595 /*! The time when the ticket becomes no longer renewable (if renewable). */ 596 cc_time_t renew_till; 597 /*! 1 if the ticket is encrypted in another ticket's key, or 0 otherwise. */ 598 cc_uint32 is_skey; 599 /*! Ticket flags, as defined by the Kerberos 5 API. */ 600 cc_uint32 ticket_flags; 601 /*! The the list of network addresses of hosts that are allowed to authenticate 602 * using this ticket. */ 603 cc_data** addresses; 604 /*! Ticket data. */ 605 cc_data ticket; 606 /*! Second ticket data. */ 607 cc_data second_ticket; 608 /*! Authorization data. */ 609 cc_data** authdata; 610}; 611typedef struct cc_credentials_v5_t cc_credentials_v5_t; 612 613struct cc_credentials_union { 614 /*! The credentials version of this credentials object. */ 615 cc_uint32 version; 616 /*! The credentials. */ 617 union { 618 /*! If \a version is #cc_credentials_v4, a pointer to a cc_credentials_v4_t. */ 619 cc_credentials_v4_t* credentials_v4; 620 /*! If \a version is #cc_credentials_v5, a pointer to a cc_credentials_v5_t. */ 621 cc_credentials_v5_t* credentials_v5; 622 } credentials; 623}; 624typedef struct cc_credentials_union cc_credentials_union; 625 626struct cc_credentials_f; 627typedef struct cc_credentials_f cc_credentials_f; 628 629struct cc_credentials_d { 630 const cc_credentials_union *data; 631 const cc_credentials_f *functions; 632#if TARGET_OS_MAC 633 const cc_credentials_f *otherFunctions; 634#endif 635}; 636typedef struct cc_credentials_d cc_credentials_d; 637typedef cc_credentials_d *cc_credentials_t; 638/*!@}*/ 639 640/*! 641 * \defgroup cc_credentials_iterator_reference cc_credentials_iterator_t 642 * @{ 643 * The cc_credentials_iterator_t type represents an iterator that 644 * iterates over a set of credentials. A new instance of this type 645 * can be obtained by calling cc_ccache_new_credentials_iterator(). 646 * 647 * For API function documentation see \ref cc_credentials_iterator_f. 648 */ 649struct cc_credentials_iterator_f; 650typedef struct cc_credentials_iterator_f cc_credentials_iterator_f; 651 652struct cc_credentials_iterator_d { 653 const cc_credentials_iterator_f *functions; 654#if TARGET_OS_MAC 655 const cc_credentials_iterator_f *vector_functions; 656#endif 657}; 658typedef struct cc_credentials_iterator_d cc_credentials_iterator_d; 659typedef cc_credentials_iterator_d *cc_credentials_iterator_t; 660/*!@}*/ 661 662/*! 663 * \defgroup cc_string_reference cc_string_t Overview 664 * @{ 665 * The cc_string_t represents a C string returned by the API. 666 * It has a pointer to the string data and a release() function. 667 * This type is used for both principal names and ccache names 668 * returned by the API. Principal names may contain UTF-8 encoded 669 * strings for internationalization purposes. 670 * 671 * For API function documentation see \ref cc_string_f. 672 */ 673struct cc_string_f; 674typedef struct cc_string_f cc_string_f; 675 676struct cc_string_d { 677 const char *data; 678 const cc_string_f *functions; 679#if TARGET_OS_MAC 680 const cc_string_f *vector_functions; 681#endif 682}; 683typedef struct cc_string_d cc_string_d; 684typedef cc_string_d *cc_string_t; 685/*!@}*/ 686 687/*! 688 * Function pointer table for cc_context_t. For more information see 689 * \ref cc_context_reference. 690 */ 691struct cc_context_f { 692 /*! 693 * \param io_context the context object to free. 694 * \return On success, #ccNoError. On failure, an error code representing the failure. 695 * \brief \b cc_context_release(): Release memory associated with a cc_context_t. 696 */ 697 cc_int32 (*release) (cc_context_t io_context); 698 699 /*! 700 * \param in_context the context object for the cache collection to examine. 701 * \param out_time on exit, the time of the most recent change for the entire ccache collection. 702 * \return On success, #ccNoError. On failure, an error code representing the failure. 703 * \brief \b cc_context_get_change_time(): Get the last time the cache collection changed. 704 * 705 * This function returns the time of the most recent change for the entire ccache collection. 706 * By maintaining a local copy the caller can deduce whether or not the ccache collection has 707 * been modified since the previous call to cc_context_get_change_time(). 708 * 709 * The time returned by cc_context_get_changed_time() increases whenever: 710 * 711 * \li a ccache is created 712 * \li a ccache is destroyed 713 * \li a credential is stored 714 * \li a credential is removed 715 * \li a ccache principal is changed 716 * \li the default ccache is changed 717 * 718 * \note In order to be able to compare two values returned by cc_context_get_change_time(), 719 * the caller must use the same context to acquire them. Callers should maintain a single 720 * context in memory for cc_context_get_change_time() calls rather than creating a new 721 * context for every call. 722 * 723 * \sa wait_for_change 724 */ 725 cc_int32 (*get_change_time) (cc_context_t in_context, 726 cc_time_t *out_time); 727 728 /*! 729 * \param in_context the context object for the cache collection. 730 * \param out_name on exit, the name of the default ccache. 731 * \return On success, #ccNoError. On failure, an error code representing the failure. 732 * \brief \b cc_context_get_default_ccache_name(): Get the name of the default ccache. 733 * 734 * This function returns the name of the default ccache. When the default ccache 735 * exists, its name is returned. If there are no ccaches in the collection, and 736 * thus there is no default ccache, the name that the default ccache should have 737 * is returned. The ccache with that name will be used as the default ccache by 738 * all processes which initialized Kerberos libraries before the ccache was created. 739 * 740 * If there is no default ccache, and the client is creating a new ccache, it 741 * should be created with the default name. If there already is a default ccache, 742 * and the client wants to create a new ccache (as opposed to reusing an existing 743 * ccache), it should be created with any unique name; #create_new_ccache() 744 * can be used to accomplish that more easily. 745 * 746 * If the first ccache is created with a name other than the default name, then 747 * the processes already running will not notice the credentials stored in the 748 * new ccache, which is normally undesirable. 749 */ 750 cc_int32 (*get_default_ccache_name) (cc_context_t in_context, 751 cc_string_t *out_name); 752 753 /*! 754 * \param in_context the context object for the cache collection. 755 * \param in_name the name of the ccache to open. 756 * \param out_ccache on exit, a ccache object for the ccache 757 * \return On success, #ccNoError. If no ccache named \a in_name exists, 758 * #ccErrCCacheNotFound. On failure, an error code representing the failure. 759 * \brief \b cc_context_open_ccache(): Open a ccache. 760 * 761 * Opens an already existing ccache identified by its name. It returns a reference 762 * to the ccache in \a out_ccache. 763 * 764 * The list of all ccache names, principals, and credentials versions may be retrieved 765 * by calling cc_context_new_cache_iterator(), cc_ccache_get_name(), 766 * cc_ccache_get_principal(), and cc_ccache_get_cred_version(). 767 */ 768 cc_int32 (*open_ccache) (cc_context_t in_context, 769 const char *in_name, 770 cc_ccache_t *out_ccache); 771 772 /*! 773 * \param in_context the context object for the cache collection. 774 * \param out_ccache on exit, a ccache object for the default ccache 775 * \return On success, #ccNoError. If no default ccache exists, 776 * #ccErrCCacheNotFound. On failure, an error code representing the failure. 777 * \brief \b cc_context_open_default_ccache(): Open the default ccache. 778 * 779 * Opens the default ccache. It returns a reference to the ccache in *ccache. 780 * 781 * This function performs the same function as calling 782 * cc_context_get_default_ccache_name followed by cc_context_open_ccache, 783 * but it performs it atomically. 784 */ 785 cc_int32 (*open_default_ccache) (cc_context_t in_context, 786 cc_ccache_t *out_ccache); 787 788 /*! 789 * \param in_context the context object for the cache collection. 790 * \param in_name the name of the new ccache to create 791 * \param in_cred_vers the version of the credentials the new ccache will hold 792 * \param in_principal the client principal of the credentials the new ccache will hold 793 * \param out_ccache on exit, a ccache object for the newly created ccache 794 * \return On success, #ccNoError. On failure, an error code representing the failure. 795 * \brief \b cc_context_create_ccache(): Create a new ccache. 796 * 797 * Create a new credentials cache. The ccache is uniquely identified by its name. 798 * The principal given is also associated with the ccache and the credentials 799 * version specified. A NULL name is not allowed (and ccErrBadName is returned 800 * if one is passed in). Only cc_credentials_v4 and cc_credentials_v5 are valid 801 * input values for cred_vers. If you want to create a new ccache that will hold 802 * both versions of credentials, call cc_context_create_ccache() with one version, 803 * and then cc_ccache_set_principal() with the other version. 804 * 805 * If you want to create a new ccache (with a unique name), you should use 806 * cc_context_create_new_ccache() instead. If you want to create or reinitialize 807 * the default cache, you should use cc_context_create_default_ccache(). 808 * 809 * If name is non-NULL and there is already a ccache named name: 810 * 811 * \li the credentials in the ccache whose version is cred_vers are removed 812 * \li the principal (of the existing ccache) associated with cred_vers is set to principal 813 * \li a handle for the existing ccache is returned and all existing handles for the ccache remain valid 814 * 815 * If no ccache named name already exists: 816 * 817 * \li a new empty ccache is created 818 * \li the principal of the new ccache associated with cred_vers is set to principal 819 * \li a handle for the new ccache is returned 820 * 821 * For a new ccache, the name should be any unique string. The name is not 822 * intended to be presented to users. 823 * 824 * If the created ccache is the first ccache in the collection, it is made 825 * the default ccache. Note that normally it is undesirable to create the first 826 * ccache with a name different from the default ccache name (as returned by 827 * cc_context_get_default_ccache_name()); see the description of 828 * cc_context_get_default_ccache_name() for details. 829 * 830 * The principal should be a C string containing an unparsed Kerberos principal 831 * in the format of the appropriate Kerberos version, i.e. \verbatim foo.bar/@BAZ 832 * \endverbatim for Kerberos v4 and \verbatim foo/bar/@BAZ \endverbatim 833 * for Kerberos v5. 834 */ 835 cc_int32 (*create_ccache) (cc_context_t in_context, 836 const char *in_name, 837 cc_uint32 in_cred_vers, 838 const char *in_principal, 839 cc_ccache_t *out_ccache); 840 841 /*! 842 * \param in_context the context object for the cache collection. 843 * \param in_cred_vers the version of the credentials the new default ccache will hold 844 * \param in_principal the client principal of the credentials the new default ccache will hold 845 * \param out_ccache on exit, a ccache object for the newly created default ccache 846 * \return On success, #ccNoError. On failure, an error code representing the failure. 847 * \brief \b cc_context_create_default_ccache(): Create a new default ccache. 848 * 849 * Create the default credentials cache. The behavior of this function is 850 * similar to that of cc_create_ccache(). If there is a default ccache 851 * (which is always the case except when there are no ccaches at all in 852 * the collection), it is initialized with the specified credentials version 853 * and principal, as per cc_create_ccache(); otherwise, a new ccache is 854 * created, and its name is the name returned by 855 * cc_context_get_default_ccache_name(). 856 */ 857 cc_int32 (*create_default_ccache) (cc_context_t in_context, 858 cc_uint32 in_cred_vers, 859 const char *in_principal, 860 cc_ccache_t *out_ccache); 861 862 /*! 863 * \param in_context the context object for the cache collection. 864 * \param in_cred_vers the version of the credentials the new ccache will hold 865 * \param in_principal the client principal of the credentials the new ccache will hold 866 * \param out_ccache on exit, a ccache object for the newly created ccache 867 * \return On success, #ccNoError. On failure, an error code representing the failure. 868 * \brief \b cc_context_create_new_ccache(): Create a new uniquely named ccache. 869 * 870 * Create a new unique credentials cache. The behavior of this function 871 * is similar to that of cc_create_ccache(). If there are no ccaches, and 872 * therefore no default ccache, the new ccache is created with the default 873 * ccache name as would be returned by get_default_ccache_name(). If there 874 * are some ccaches, and therefore there is a default ccache, the new ccache 875 * is created with a new unique name. Clearly, this function never reinitializes 876 * a ccache, since it always uses a unique name. 877 */ 878 cc_int32 (*create_new_ccache) (cc_context_t in_context, 879 cc_uint32 in_cred_vers, 880 const char *in_principal, 881 cc_ccache_t *out_ccache); 882 883 /*! 884 * \param in_context the context object for the cache collection. 885 * \param out_iterator on exit, a ccache iterator object for the ccache collection. 886 * \return On success, #ccNoError. On failure, an error code representing the failure. 887 * \brief \b cc_context_new_ccache_iterator(): Get an iterator for the cache collection. 888 * 889 * Used to allocate memory and initialize iterator. Successive calls to iterator's 890 * next() function will return ccaches in the collection. 891 * 892 * If changes are made to the collection while an iterator is being used 893 * on it, the iterator must return at least the intersection, and at most 894 * the union, of the set of ccaches that were present when the iteration 895 * began and the set of ccaches that are present when it ends. 896 */ 897 cc_int32 (*new_ccache_iterator) (cc_context_t in_context, 898 cc_ccache_iterator_t *out_iterator); 899 900 /*! 901 * \param in_context the context object for the cache collection. 902 * \param in_lock_type the type of lock to obtain. 903 * \param in_block whether or not the function should block if the lock cannot be obtained immediately. 904 * \return On success, #ccNoError. On failure, an error code representing the failure. 905 * \brief \b cc_context_lock(): Lock the cache collection. 906 * 907 * Attempts to acquire an advisory lock for the ccache collection. Allowed values 908 * for lock_type are: 909 * 910 * \li cc_lock_read: a read lock. 911 * \li cc_lock_write: a write lock 912 * \li cc_lock_upgrade: upgrade an already-obtained read lock to a write lock 913 * \li cc_lock_downgrade: downgrade an already-obtained write lock to a read lock 914 * 915 * If block is cc_lock_block, lock() will not return until the lock is acquired. 916 * If block is cc_lock_noblock, lock() will return immediately, either acquiring 917 * the lock and returning ccNoError, or failing to acquire the lock and returning 918 * an error explaining why. 919 * 920 * Locks apply only to the list of ccaches, not the contents of those ccaches. To 921 * prevent callers participating in the advisory locking from changing the credentials 922 * in a cache you must also lock that ccache with cc_ccache_lock(). This is so 923 * that you can get the list of ccaches without preventing applications from 924 * simultaneously obtaining service tickets. 925 * 926 * To avoid having to deal with differences between thread semantics on different 927 * platforms, locks are granted per context, rather than per thread or per process. 928 * That means that different threads of execution have to acquire separate contexts 929 * in order to be able to synchronize with each other. 930 * 931 * The lock should be unlocked by using cc_context_unlock(). 932 * 933 * \note All locks are advisory. For example, callers which do not call 934 * cc_context_lock() and cc_context_unlock() will not be prevented from writing 935 * to the cache collection when you have a read lock. This is because the CCAPI 936 * locking was added after the first release and thus adding mandatory locks would 937 * have changed the user experience and performance of existing applications. 938 */ 939 cc_int32 (*lock) (cc_context_t in_context, 940 cc_uint32 in_lock_type, 941 cc_uint32 in_block); 942 943 /*! 944 * \param in_context the context object for the cache collection. 945 * \return On success, #ccNoError. On failure, an error code representing the failure. 946 * \brief \b cc_context_unlock(): Unlock the cache collection. 947 */ 948 cc_int32 (*unlock) (cc_context_t in_cc_context); 949 950 /*! 951 * \param in_context a context object. 952 * \param in_compare_to_context a context object to compare with \a in_context. 953 * \param out_equal on exit, whether or not the two contexts refer to the same cache collection. 954 * \return On success, #ccNoError. On failure, an error code representing the failure. 955 * \brief \b cc_context_compare(): Compare two context objects. 956 */ 957 cc_int32 (*compare) (cc_context_t in_cc_context, 958 cc_context_t in_compare_to_context, 959 cc_uint32 *out_equal); 960 961 /*! 962 * \param in_context a context object. 963 * \return On success, #ccNoError. On failure, an error code representing the failure. 964 * \brief \b cc_context_wait_for_change(): Wait for the next change in the cache collection. 965 * 966 * This function blocks until the next change is made to the cache collection 967 * ccache collection. By repeatedly calling cc_context_wait_for_change() from 968 * a worker thread the caller can effectively receive callbacks whenever the 969 * cache collection changes. This is considerably more efficient than polling 970 * with cc_context_get_change_time(). 971 * 972 * cc_context_wait_for_change() will return whenever: 973 * 974 * \li a ccache is created 975 * \li a ccache is destroyed 976 * \li a credential is stored 977 * \li a credential is removed 978 * \li a ccache principal is changed 979 * \li the default ccache is changed 980 * 981 * \note In order to make sure that the caller doesn't miss any changes, 982 * cc_context_wait_for_change() always returns immediately after the first time it 983 * is called on a new context object. Callers must use the same context object 984 * for successive calls to cc_context_wait_for_change() rather than creating a new 985 * context for every call. 986 * 987 * \sa get_change_time 988 */ 989 cc_int32 (*wait_for_change) (cc_context_t in_cc_context); 990}; 991 992/*! 993 * Function pointer table for cc_ccache_t. For more information see 994 * \ref cc_ccache_reference. 995 */ 996struct cc_ccache_f { 997 /*! 998 * \param io_ccache the ccache object to release. 999 * \return On success, #ccNoError. On failure, an error code representing the failure. 1000 * \brief \b cc_ccache_release(): Release memory associated with a cc_ccache_t object. 1001 * \note Does not modify the ccache. If you wish to remove the ccache see cc_ccache_destroy(). 1002 */ 1003 cc_int32 (*release) (cc_ccache_t io_ccache); 1004 1005 /*! 1006 * \param io_ccache the ccache object to destroy and release. 1007 * \return On success, #ccNoError. On failure, an error code representing the failure. 1008 * \brief \b cc_ccache_destroy(): Destroy a ccache. 1009 * 1010 * Destroy the ccache referred to by \a io_ccache and releases memory associated with 1011 * the \a io_ccache object. After this call \a io_ccache becomes invalid. If 1012 * \a io_ccache was the default ccache, the next ccache in the cache collection (if any) 1013 * becomes the new default. 1014 */ 1015 cc_int32 (*destroy) (cc_ccache_t io_ccache); 1016 1017 /*! 1018 * \param io_ccache a ccache object to make the new default ccache. 1019 * \return On success, #ccNoError. On failure, an error code representing the failure. 1020 * \brief \b cc_ccache_set_default(): Make a ccache the default ccache. 1021 */ 1022 cc_int32 (*set_default) (cc_ccache_t io_ccache); 1023 1024 /*! 1025 * \param in_ccache a ccache object. 1026 * \param out_credentials_version on exit, the credentials version of \a in_ccache. 1027 * \return On success, #ccNoError. On failure, an error code representing the failure. 1028 * \brief \b cc_ccache_get_credentials_version(): Get the credentials version of a ccache. 1029 * 1030 * cc_ccache_get_credentials_version() returns one value of the enumerated type 1031 * cc_credentials_vers. The possible return values are #cc_credentials_v4 1032 * (if ccache's v4 principal has been set), #cc_credentials_v5 1033 * (if ccache's v5 principal has been set), or #cc_credentials_v4_v5 1034 * (if both ccache's v4 and v5 principals have been set). A ccache's 1035 * principal is set with one of cc_context_create_ccache(), 1036 * cc_context_create_new_ccache(), cc_context_create_default_ccache(), or 1037 * cc_ccache_set_principal(). 1038 */ 1039 cc_int32 (*get_credentials_version) (cc_ccache_t in_ccache, 1040 cc_uint32 *out_credentials_version); 1041 1042 /*! 1043 * \param in_ccache a ccache object. 1044 * \param out_name on exit, a cc_string_t representing the name of \a in_ccache. 1045 * \a out_name must be released with cc_string_release(). 1046 * \return On success, #ccNoError. On failure, an error code representing the failure. 1047 * \brief \b cc_ccache_get_name(): Get the name of a ccache. 1048 */ 1049 cc_int32 (*get_name) (cc_ccache_t in_ccache, 1050 cc_string_t *out_name); 1051 1052 /*! 1053 * \param in_ccache a ccache object. 1054 * \param in_credentials_version the credentials version to get the principal for. 1055 * \param out_principal on exit, a cc_string_t representing the principal of \a in_ccache. 1056 * \a out_principal must be released with cc_string_release(). 1057 * \return On success, #ccNoError. On failure, an error code representing the failure. 1058 * \brief \b cc_ccache_get_principal(): Get the principal of a ccache. 1059 * 1060 * Return the principal for the ccache that was set via cc_context_create_ccache(), 1061 * cc_context_create_default_ccache(), cc_context_create_new_ccache(), or 1062 * cc_ccache_set_principal(). Principals for v4 and v5 are separate, but 1063 * should be kept synchronized for each ccache; they can be retrieved by 1064 * passing cc_credentials_v4 or cc_credentials_v5 in cred_vers. Passing 1065 * cc_credentials_v4_v5 will result in the error ccErrBadCredentialsVersion. 1066 */ 1067 cc_int32 (*get_principal) (cc_ccache_t in_ccache, 1068 cc_uint32 in_credentials_version, 1069 cc_string_t *out_principal); 1070 1071 1072 /*! 1073 * \param in_ccache a ccache object. 1074 * \param in_credentials_version the credentials version to set the principal for. 1075 * \param in_principal a C string representing the new principal of \a in_ccache. 1076 * \return On success, #ccNoError. On failure, an error code representing the failure. 1077 * \brief \b cc_ccache_set_principal(): Set the principal of a ccache. 1078 * 1079 * Set the a principal for ccache. The v4 and v5 principals can be set 1080 * independently, but they should always be kept equal, up to differences in 1081 * string representation between v4 and v5. Passing cc_credentials_v4_v5 in 1082 * cred_vers will result in the error ccErrBadCredentialsVersion. 1083 */ 1084 cc_int32 (*set_principal) (cc_ccache_t io_ccache, 1085 cc_uint32 in_credentials_version, 1086 const char *in_principal); 1087 1088 /*! 1089 * \param io_ccache a ccache object. 1090 * \param in_credentials_union the credentials to store in \a io_ccache. 1091 * \return On success, #ccNoError. On failure, an error code representing the failure. 1092 * \brief \b cc_ccache_store_credentials(): Store credentials in a ccache. 1093 * 1094 * Store a copy of credentials in the ccache. 1095 * 1096 * See the description of the credentials types for the meaning of 1097 * cc_credentials_union fields. 1098 * 1099 * Before credentials of a specific credential type can be stored in a ccache, 1100 * the corresponding principal version has to be set. For example, before you can 1101 * store Kerberos v4 credentials in a ccache, the Kerberos v4 principal has to be set 1102 * either by cc_context_create_ccache(), cc_context_create_default_ccache(), 1103 * cc_context_create_new_ccache(), or cc_ccache_set_principal(); likewise for 1104 * Kerberos v5. Otherwise, ccErrBadCredentialsVersion is returned. 1105 */ 1106 cc_int32 (*store_credentials) (cc_ccache_t io_ccache, 1107 const cc_credentials_union *in_credentials_union); 1108 1109 /*! 1110 * \param io_ccache a ccache object. 1111 * \param in_credentials the credentials to remove from \a io_ccache. 1112 * \return On success, #ccNoError. On failure, an error code representing the failure. 1113 * \brief \b cc_ccache_remove_credentials(): Remove credentials from a ccache. 1114 * 1115 * Removes credentials from a ccache. Note that credentials must be previously 1116 * acquired from the CCache API; only exactly matching credentials will be 1117 * removed. (This places the burden of determining exactly which credentials 1118 * to remove on the caller, but ensures there is no ambigity about which 1119 * credentials will be removed.) cc_credentials_t objects can be obtained by 1120 * iterating over the ccache's credentials with cc_ccache_new_credentials_iterator(). 1121 * 1122 * If found, the credentials are removed from the ccache. The credentials 1123 * parameter is not modified and should be freed by the caller. It is 1124 * legitimate to call this function while an iterator is traversing the 1125 * ccache, and the deletion of a credential already returned by 1126 * cc_credentials_iterator_next() will not disturb sequence of credentials 1127 * returned by cc_credentials_iterator_next(). 1128 */ 1129 cc_int32 (*remove_credentials) (cc_ccache_t io_ccache, 1130 cc_credentials_t in_credentials); 1131 1132 /*! 1133 * \param in_ccache a ccache object. 1134 * \param out_credentials_iterator a credentials iterator for \a io_ccache. 1135 * \return On success, #ccNoError. On failure, an error code representing the failure. 1136 * \brief \b cc_ccache_new_credentials_iterator(): Iterate over credentials in a ccache. 1137 * 1138 * Allocates memory for iterator and initializes it. Successive calls to 1139 * cc_credentials_iterator_next() will return credentials from the ccache. 1140 * 1141 * If changes are made to the ccache while an iterator is being used on it, 1142 * the iterator must return at least the intersection, and at most the union, 1143 * of the set of credentials that were in the ccache when the iteration began 1144 * and the set of credentials that are in the ccache when it ends. 1145 */ 1146 cc_int32 (*new_credentials_iterator) (cc_ccache_t in_ccache, 1147 cc_credentials_iterator_t *out_credentials_iterator); 1148 1149 /*! 1150 * \param io_source_ccache a ccache object to move. 1151 * \param io_destination_ccache a ccache object replace with the contents of \a io_source_ccache. 1152 * \return On success, #ccNoError. On failure, an error code representing the failure. 1153 * \brief \b cc_ccache_move(): Move the contents of one ccache into another, destroying the source. 1154 * 1155 * cc_ccache_move() atomically copies the credentials, credential versions and principals 1156 * from one ccache to another. On successful completion \a io_source_ccache will be 1157 * released and the ccache it points to will be destroyed. Any credentials previously 1158 * in \a io_destination_ccache will be replaced with credentials from \a io_source_ccache. 1159 * The only part of \a io_destination_ccache which remains constant is the name. Any other 1160 * callers referring to \a io_destination_ccache will suddenly see new data in it. 1161 * 1162 * Typically cc_ccache_move() is used when the caller wishes to safely overwrite the 1163 * contents of a ccache with new data which requires several steps to generate. 1164 * cc_ccache_move() allows the caller to create a temporary ccache 1165 * (which can be destroyed if any intermediate step fails) and the atomically copy 1166 * the temporary cache into the destination. 1167 */ 1168 cc_int32 (*move) (cc_ccache_t io_source_ccache, 1169 cc_ccache_t io_destination_ccache); 1170 1171 /*! 1172 * \param io_ccache the ccache object for the ccache you wish to lock. 1173 * \param in_lock_type the type of lock to obtain. 1174 * \param in_block whether or not the function should block if the lock cannot be obtained immediately. 1175 * \return On success, #ccNoError. On failure, an error code representing the failure. 1176 * \brief \b cc_ccache_lock(): Lock a ccache. 1177 * 1178 * Attempts to acquire an advisory lock for a ccache. Allowed values for lock_type are: 1179 * 1180 * \li cc_lock_read: a read lock. 1181 * \li cc_lock_write: a write lock 1182 * \li cc_lock_upgrade: upgrade an already-obtained read lock to a write lock 1183 * \li cc_lock_downgrade: downgrade an already-obtained write lock to a read lock 1184 * 1185 * If block is cc_lock_block, lock() will not return until the lock is acquired. 1186 * If block is cc_lock_noblock, lock() will return immediately, either acquiring 1187 * the lock and returning ccNoError, or failing to acquire the lock and returning 1188 * an error explaining why. 1189 * 1190 * To avoid having to deal with differences between thread semantics on different 1191 * platforms, locks are granted per ccache, rather than per thread or per process. 1192 * That means that different threads of execution have to acquire separate contexts 1193 * in order to be able to synchronize with each other. 1194 * 1195 * The lock should be unlocked by using cc_ccache_unlock(). 1196 * 1197 * \note All locks are advisory. For example, callers which do not call 1198 * cc_ccache_lock() and cc_ccache_unlock() will not be prevented from writing 1199 * to the ccache when you have a read lock. This is because the CCAPI 1200 * locking was added after the first release and thus adding mandatory locks would 1201 * have changed the user experience and performance of existing applications. 1202 */ 1203 cc_int32 (*lock) (cc_ccache_t io_ccache, 1204 cc_uint32 in_lock_type, 1205 cc_uint32 in_block); 1206 1207 /*! 1208 * \param io_ccache a ccache object. 1209 * \return On success, #ccNoError. On failure, an error code representing the failure. 1210 * \brief \b cc_ccache_unlock(): Unlock a ccache. 1211 */ 1212 cc_int32 (*unlock) (cc_ccache_t io_ccache); 1213 1214 /*! 1215 * \param in_ccache a cache object. 1216 * \param out_last_default_time on exit, the last time the ccache was default. 1217 * \return On success, #ccNoError. On failure, an error code representing the failure. 1218 * \brief \b cc_ccache_get_change_time(): Get the last time a ccache was the default ccache. 1219 * 1220 * This function returns the last time when the ccache was made the default ccache. 1221 * This allows clients to sort the ccaches by how recently they were default, which 1222 * is useful for user listing of ccaches. If the ccache was never default, 1223 * ccErrNeverDefault is returned. 1224 */ 1225 cc_int32 (*get_last_default_time) (cc_ccache_t in_ccache, 1226 cc_time_t *out_last_default_time); 1227 1228 /*! 1229 * \param in_ccache a cache object. 1230 * \param out_change_time on exit, the last time the ccache changed. 1231 * \return On success, #ccNoError. If the ccache was never the default ccache, 1232 * #ccErrNeverDefault. Otherwise, an error code representing the failure. 1233 * \brief \b cc_ccache_get_change_time(): Get the last time a ccache changed. 1234 * 1235 * This function returns the time of the most recent change made to a ccache. 1236 * By maintaining a local copy the caller can deduce whether or not the ccache has 1237 * been modified since the previous call to cc_ccache_get_change_time(). 1238 * 1239 * The time returned by cc_ccache_get_change_time() increases whenever: 1240 * 1241 * \li a credential is stored 1242 * \li a credential is removed 1243 * \li a ccache principal is changed 1244 * \li the ccache becomes the default ccache 1245 * \li the ccache is no longer the default ccache 1246 * 1247 * \note In order to be able to compare two values returned by cc_ccache_get_change_time(), 1248 * the caller must use the same ccache object to acquire them. Callers should maintain a 1249 * single ccache object in memory for cc_ccache_get_change_time() calls rather than 1250 * creating a new ccache object for every call. 1251 * 1252 * \sa wait_for_change 1253 */ 1254 cc_int32 (*get_change_time) (cc_ccache_t in_ccache, 1255 cc_time_t *out_change_time); 1256 1257 /*! 1258 * \param in_ccache a ccache object. 1259 * \param in_compare_to_ccache a ccache object to compare with \a in_ccache. 1260 * \param out_equal on exit, whether or not the two ccaches refer to the same ccache. 1261 * \return On success, #ccNoError. On failure, an error code representing the failure. 1262 * \brief \b cc_ccache_compare(): Compare two ccache objects. 1263 */ 1264 cc_int32 (*compare) (cc_ccache_t in_ccache, 1265 cc_ccache_t in_compare_to_ccache, 1266 cc_uint32 *out_equal); 1267 1268 /*! 1269 * \param in_ccache a ccache object. 1270 * \param in_credentials_version the credentials version to get the time offset for. 1271 * \param out_time_offset on exit, the KDC time offset for \a in_ccache for credentials version 1272 * \a in_credentials_version. 1273 * \return On success, #ccNoError if a time offset was obtained or #ccErrTimeOffsetNotSet 1274 * if a time offset has not been set. On failure, an error code representing the failure. 1275 * \brief \b cc_ccache_get_kdc_time_offset(): Get the KDC time offset for credentials in a ccache. 1276 * \sa set_kdc_time_offset, clear_kdc_time_offset 1277 * 1278 * Sometimes the KDC and client's clocks get out of sync. cc_ccache_get_kdc_time_offset() 1279 * returns the difference between the KDC and client's clocks at the time credentials were 1280 * acquired. This offset allows callers to figure out how much time is left on a given 1281 * credential even though the end_time is based on the KDC's clock not the client's clock. 1282 */ 1283 cc_int32 (*get_kdc_time_offset) (cc_ccache_t in_ccache, 1284 cc_uint32 in_credentials_version, 1285 cc_time_t *out_time_offset); 1286 1287 /*! 1288 * \param in_ccache a ccache object. 1289 * \param in_credentials_version the credentials version to get the time offset for. 1290 * \param in_time_offset the new KDC time offset for \a in_ccache for credentials version 1291 * \a in_credentials_version. 1292 * \return On success, #ccNoError. On failure, an error code representing the failure. 1293 * \brief \b cc_ccache_set_kdc_time_offset(): Set the KDC time offset for credentials in a ccache. 1294 * \sa get_kdc_time_offset, clear_kdc_time_offset 1295 * 1296 * Sometimes the KDC and client's clocks get out of sync. cc_ccache_set_kdc_time_offset() 1297 * sets the difference between the KDC and client's clocks at the time credentials were 1298 * acquired. This offset allows callers to figure out how much time is left on a given 1299 * credential even though the end_time is based on the KDC's clock not the client's clock. 1300 */ 1301 cc_int32 (*set_kdc_time_offset) (cc_ccache_t io_ccache, 1302 cc_uint32 in_credentials_version, 1303 cc_time_t in_time_offset); 1304 1305 /*! 1306 * \param in_ccache a ccache object. 1307 * \param in_credentials_version the credentials version to get the time offset for. 1308 * \return On success, #ccNoError. On failure, an error code representing the failure. 1309 * \brief \b cc_ccache_clear_kdc_time_offset(): Clear the KDC time offset for credentials in a ccache. 1310 * \sa get_kdc_time_offset, set_kdc_time_offset 1311 * 1312 * Sometimes the KDC and client's clocks get out of sync. cc_ccache_clear_kdc_time_offset() 1313 * clears the difference between the KDC and client's clocks at the time credentials were 1314 * acquired. This offset allows callers to figure out how much time is left on a given 1315 * credential even though the end_time is based on the KDC's clock not the client's clock. 1316 */ 1317 cc_int32 (*clear_kdc_time_offset) (cc_ccache_t io_ccache, 1318 cc_uint32 in_credentials_version); 1319 1320 /*! 1321 * \param in_ccache a ccache object. 1322 * \return On success, #ccNoError. On failure, an error code representing the failure. 1323 * \brief \b cc_ccache_wait_for_change(): Wait for the next change to a ccache. 1324 * 1325 * This function blocks until the next change is made to the ccache referenced by 1326 * \a in_ccache. By repeatedly calling cc_ccache_wait_for_change() from 1327 * a worker thread the caller can effectively receive callbacks whenever the 1328 * ccache changes. This is considerably more efficient than polling 1329 * with cc_ccache_get_change_time(). 1330 * 1331 * cc_ccache_wait_for_change() will return whenever: 1332 * 1333 * \li a credential is stored 1334 * \li a credential is removed 1335 * \li the ccache principal is changed 1336 * \li the ccache becomes the default ccache 1337 * \li the ccache is no longer the default ccache 1338 * 1339 * \note In order to make sure that the caller doesn't miss any changes, 1340 * cc_ccache_wait_for_change() always returns immediately after the first time it 1341 * is called on a new ccache object. Callers must use the same ccache object 1342 * for successive calls to cc_ccache_wait_for_change() rather than creating a new 1343 * ccache object for every call. 1344 * 1345 * \sa get_change_time 1346 */ 1347 cc_int32 (*wait_for_change) (cc_ccache_t in_ccache); 1348}; 1349 1350/*! 1351 * Function pointer table for cc_string_t. For more information see 1352 * \ref cc_string_reference. 1353 */ 1354struct cc_string_f { 1355 /*! 1356 * \param io_string the string object to release. 1357 * \return On success, #ccNoError. On failure, an error code representing the failure. 1358 * \brief \b cc_string_release(): Release memory associated with a cc_string_t object. 1359 */ 1360 cc_int32 (*release) (cc_string_t io_string); 1361}; 1362 1363/*! 1364 * Function pointer table for cc_credentials_t. For more information see 1365 * \ref cc_credentials_reference. 1366 */ 1367struct cc_credentials_f { 1368 /*! 1369 * \param io_credentials the credentials object to release. 1370 * \return On success, #ccNoError. On failure, an error code representing the failure. 1371 * \brief \b cc_credentials_release(): Release memory associated with a cc_credentials_t object. 1372 */ 1373 cc_int32 (*release) (cc_credentials_t io_credentials); 1374 1375 /*! 1376 * \param in_credentials a credentials object. 1377 * \param in_compare_to_credentials a credentials object to compare with \a in_credentials. 1378 * \param out_equal on exit, whether or not the two credentials objects refer to the 1379 * same credentials in the cache collection. 1380 * \return On success, #ccNoError. On failure, an error code representing the failure. 1381 * \brief \b cc_credentials_compare(): Compare two credentials objects. 1382 */ 1383 cc_int32 (*compare) (cc_credentials_t in_credentials, 1384 cc_credentials_t in_compare_to_credentials, 1385 cc_uint32 *out_equal); 1386}; 1387 1388/*! 1389 * Function pointer table for cc_ccache_iterator_t. For more information see 1390 * \ref cc_ccache_iterator_reference. 1391 */ 1392struct cc_ccache_iterator_f { 1393 /*! 1394 * \param io_ccache_iterator the ccache iterator object to release. 1395 * \return On success, #ccNoError. On failure, an error code representing the failure. 1396 * \brief \b cc_ccache_iterator_release(): Release memory associated with a cc_ccache_iterator_t object. 1397 */ 1398 cc_int32 (*release) (cc_ccache_iterator_t io_ccache_iterator); 1399 1400 /*! 1401 * \param in_ccache_iterator a ccache iterator object. 1402 * \param out_ccache on exit, the next ccache in the cache collection. 1403 * \return On success, #ccNoError if the next ccache in the cache collection was 1404 * obtained or #ccIteratorEnd if there are no more ccaches. 1405 * On failure, an error code representing the failure. 1406 * \brief \b cc_ccache_iterator_next(): Get the next ccache in the cache collection. 1407 */ 1408 cc_int32 (*next) (cc_ccache_iterator_t in_ccache_iterator, 1409 cc_ccache_t *out_ccache); 1410 1411 /*! 1412 * \param in_ccache_iterator a ccache iterator object. 1413 * \param out_ccache_iterator on exit, a copy of \a in_ccache_iterator. 1414 * \return On success, #ccNoError. On failure, an error code representing the failure. 1415 * \brief \b cc_ccache_iterator_clone(): Make a copy of a ccache iterator. 1416 */ 1417 cc_int32 (*clone) (cc_ccache_iterator_t in_ccache_iterator, 1418 cc_ccache_iterator_t *out_ccache_iterator); 1419}; 1420 1421/*! 1422 * Function pointer table for cc_credentials_iterator_t. For more information see 1423 * \ref cc_credentials_iterator_reference. 1424 */ 1425struct cc_credentials_iterator_f { 1426 /*! 1427 * \param io_credentials_iterator the credentials iterator object to release. 1428 * \return On success, #ccNoError. On failure, an error code representing the failure. 1429 * \brief \b cc_credentials_iterator_release(): Release memory associated with a cc_credentials_iterator_t object. 1430 */ 1431 cc_int32 (*release) (cc_credentials_iterator_t io_credentials_iterator); 1432 1433 /*! 1434 * \param in_credentials_iterator a credentials iterator object. 1435 * \param out_credentials on exit, the next credentials in the ccache. 1436 * \return On success, #ccNoError if the next credential in the ccache was obtained 1437 * or #ccIteratorEnd if there are no more credentials. 1438 * On failure, an error code representing the failure. 1439 * \brief \b cc_credentials_iterator_next(): Get the next credentials in the ccache. 1440 */ 1441 cc_int32 (*next) (cc_credentials_iterator_t in_credentials_iterator, 1442 cc_credentials_t *out_credentials); 1443 1444 /*! 1445 * \ingroup cc_credentials_iterator_reference 1446 * \param in_credentials_iterator a credentials iterator object. 1447 * \param out_credentials_iterator on exit, a copy of \a in_credentials_iterator. 1448 * \return On success, #ccNoError. On failure, an error code representing the failure. 1449 * \brief \b cc_credentials_iterator_clone(): Make a copy of a credentials iterator. 1450 */ 1451 cc_int32 (*clone) (cc_credentials_iterator_t in_credentials_iterator, 1452 cc_credentials_iterator_t *out_credentials_iterator); 1453}; 1454 1455/*! 1456 * \ingroup cc_context_reference 1457 * \param out_context on exit, a new context object. Must be free with cc_context_release(). 1458 * \param in_version the requested API version. This should be the maximum version the 1459 * application supports. 1460 * \param out_supported_version if non-NULL, on exit contains the maximum API version 1461 * supported by the implementation. 1462 * \param out_vendor if non-NULL, on exit contains a pointer to a read-only C string which 1463 * contains a string describing the vendor which implemented the credentials cache API. 1464 * \return On success, #ccNoError. On failure, an error code representing the failure. 1465 * May return CCAPI v2 error CC_BAD_API_VERSION if #ccapi_version_2 is passed in. 1466 * \brief Initialize a new cc_context. 1467 */ 1468CCACHE_API cc_int32 cc_initialize (cc_context_t *out_context, 1469 cc_int32 in_version, 1470 cc_int32 *out_supported_version, 1471 char const **out_vendor) 1472 cc_deprecated("use gss_iter_creds instead"); 1473 1474 1475/*! \defgroup helper_macros CCAPI Function Helper Macros 1476 * @{ */ 1477 1478/*! Helper macro for cc_context_f release() */ 1479#define cc_context_release(context) \ 1480 ((context) -> functions -> release (context)) 1481/*! Helper macro for cc_context_f get_change_time() */ 1482#define cc_context_get_change_time(context, change_time) \ 1483 ((context) -> functions -> get_change_time (context, change_time)) 1484/*! Helper macro for cc_context_f get_default_ccache_name() */ 1485#define cc_context_get_default_ccache_name(context, name) \ 1486 ((context) -> functions -> get_default_ccache_name (context, name)) 1487/*! Helper macro for cc_context_f open_ccache() */ 1488#define cc_context_open_ccache(context, name, ccache) \ 1489 ((context) -> functions -> open_ccache (context, name, ccache)) 1490/*! Helper macro for cc_context_f open_default_ccache() */ 1491#define cc_context_open_default_ccache(context, ccache) \ 1492 ((context) -> functions -> open_default_ccache (context, ccache)) 1493/*! Helper macro for cc_context_f create_ccache() */ 1494#define cc_context_create_ccache(context, name, version, principal, ccache) \ 1495 ((context) -> functions -> create_ccache (context, name, version, principal, ccache)) 1496/*! Helper macro for cc_context_f create_default_ccache() */ 1497#define cc_context_create_default_ccache(context, version, principal, ccache) \ 1498 ((context) -> functions -> create_default_ccache (context, version, principal, ccache)) 1499/*! Helper macro for cc_context_f create_new_ccache() */ 1500#define cc_context_create_new_ccache(context, version, principal, ccache) \ 1501 ((context) -> functions -> create_new_ccache (context, version, principal, ccache)) 1502/*! Helper macro for cc_context_f new_ccache_iterator() */ 1503#define cc_context_new_ccache_iterator(context, iterator) \ 1504 ((context) -> functions -> new_ccache_iterator (context, iterator)) 1505/*! Helper macro for cc_context_f lock() */ 1506#define cc_context_lock(context, type, block) \ 1507 ((context) -> functions -> lock (context, type, block)) 1508/*! Helper macro for cc_context_f unlock() */ 1509#define cc_context_unlock(context) \ 1510 ((context) -> functions -> unlock (context)) 1511/*! Helper macro for cc_context_f compare() */ 1512#define cc_context_compare(context, compare_to, equal) \ 1513 ((context) -> functions -> compare (context, compare_to, equal)) 1514/*! Helper macro for cc_context_f wait_for_change() */ 1515#define cc_context_wait_for_change(context) \ 1516 ((context) -> functions -> wait_for_change (context)) 1517 1518/*! Helper macro for cc_ccache_f release() */ 1519#define cc_ccache_release(ccache) \ 1520 ((ccache) -> functions -> release (ccache)) 1521/*! Helper macro for cc_ccache_f destroy() */ 1522#define cc_ccache_destroy(ccache) \ 1523 ((ccache) -> functions -> destroy (ccache)) 1524/*! Helper macro for cc_ccache_f set_default() */ 1525#define cc_ccache_set_default(ccache) \ 1526 ((ccache) -> functions -> set_default (ccache)) 1527/*! Helper macro for cc_ccache_f get_credentials_version() */ 1528#define cc_ccache_get_credentials_version(ccache, version) \ 1529 ((ccache) -> functions -> get_credentials_version (ccache, version)) 1530/*! Helper macro for cc_ccache_f get_name() */ 1531#define cc_ccache_get_name(ccache, name) \ 1532 ((ccache) -> functions -> get_name (ccache, name)) 1533/*! Helper macro for cc_ccache_f get_principal() */ 1534#define cc_ccache_get_principal(ccache, version, principal) \ 1535 ((ccache) -> functions -> get_principal (ccache, version, principal)) 1536/*! Helper macro for cc_ccache_f set_principal() */ 1537#define cc_ccache_set_principal(ccache, version, principal) \ 1538 ((ccache) -> functions -> set_principal (ccache, version, principal)) 1539/*! Helper macro for cc_ccache_f store_credentials() */ 1540#define cc_ccache_store_credentials(ccache, credentials) \ 1541 ((ccache) -> functions -> store_credentials (ccache, credentials)) 1542/*! Helper macro for cc_ccache_f remove_credentials() */ 1543#define cc_ccache_remove_credentials(ccache, credentials) \ 1544 ((ccache) -> functions -> remove_credentials (ccache, credentials)) 1545/*! Helper macro for cc_ccache_f new_credentials_iterator() */ 1546#define cc_ccache_new_credentials_iterator(ccache, iterator) \ 1547 ((ccache) -> functions -> new_credentials_iterator (ccache, iterator)) 1548/*! Helper macro for cc_ccache_f lock() */ 1549#define cc_ccache_lock(ccache, type, block) \ 1550 ((ccache) -> functions -> lock (ccache, type, block)) 1551/*! Helper macro for cc_ccache_f unlock() */ 1552#define cc_ccache_unlock(ccache) \ 1553 ((ccache) -> functions -> unlock (ccache)) 1554/*! Helper macro for cc_ccache_f get_last_default_time() */ 1555#define cc_ccache_get_last_default_time(ccache, last_default_time) \ 1556 ((ccache) -> functions -> get_last_default_time (ccache, last_default_time)) 1557/*! Helper macro for cc_ccache_f get_change_time() */ 1558#define cc_ccache_get_change_time(ccache, change_time) \ 1559 ((ccache) -> functions -> get_change_time (ccache, change_time)) 1560/*! Helper macro for cc_ccache_f move() */ 1561#define cc_ccache_move(source, destination) \ 1562 ((source) -> functions -> move (source, destination)) 1563/*! Helper macro for cc_ccache_f compare() */ 1564#define cc_ccache_compare(ccache, compare_to, equal) \ 1565 ((ccache) -> functions -> compare (ccache, compare_to, equal)) 1566/*! Helper macro for cc_ccache_f get_kdc_time_offset() */ 1567#define cc_ccache_get_kdc_time_offset(ccache, version, time_offset) \ 1568 ((ccache) -> functions -> get_kdc_time_offset (ccache, version, time_offset)) 1569/*! Helper macro for cc_ccache_f set_kdc_time_offset() */ 1570#define cc_ccache_set_kdc_time_offset(ccache, version, time_offset) \ 1571 ((ccache) -> functions -> set_kdc_time_offset (ccache, version, time_offset)) 1572/*! Helper macro for cc_ccache_f clear_kdc_time_offset() */ 1573#define cc_ccache_clear_kdc_time_offset(ccache, version) \ 1574 ((ccache) -> functions -> clear_kdc_time_offset (ccache, version)) 1575/*! Helper macro for cc_ccache_f wait_for_change() */ 1576#define cc_ccache_wait_for_change(ccache) \ 1577 ((ccache) -> functions -> wait_for_change (ccache)) 1578 1579/*! Helper macro for cc_string_f release() */ 1580#define cc_string_release(string) \ 1581 ((string) -> functions -> release (string)) 1582 1583/*! Helper macro for cc_credentials_f release() */ 1584#define cc_credentials_release(credentials) \ 1585 ((credentials) -> functions -> release (credentials)) 1586/*! Helper macro for cc_credentials_f compare() */ 1587#define cc_credentials_compare(credentials, compare_to, equal) \ 1588 ((credentials) -> functions -> compare (credentials, compare_to, equal)) 1589 1590/*! Helper macro for cc_ccache_iterator_f release() */ 1591#define cc_ccache_iterator_release(iterator) \ 1592 ((iterator) -> functions -> release (iterator)) 1593/*! Helper macro for cc_ccache_iterator_f next() */ 1594#define cc_ccache_iterator_next(iterator, ccache) \ 1595 ((iterator) -> functions -> next (iterator, ccache)) 1596/*! Helper macro for cc_ccache_iterator_f clone() */ 1597#define cc_ccache_iterator_clone(iterator, new_iterator) \ 1598 ((iterator) -> functions -> clone (iterator, new_iterator)) 1599 1600/*! Helper macro for cc_credentials_iterator_f release() */ 1601#define cc_credentials_iterator_release(iterator) \ 1602 ((iterator) -> functions -> release (iterator)) 1603/*! Helper macro for cc_credentials_iterator_f next() */ 1604#define cc_credentials_iterator_next(iterator, credentials) \ 1605 ((iterator) -> functions -> next (iterator, credentials)) 1606/*! Helper macro for cc_credentials_iterator_f clone() */ 1607#define cc_credentials_iterator_clone(iterator, new_iterator) \ 1608 ((iterator) -> functions -> clone (iterator, new_iterator)) 1609/*!@}*/ 1610 1611#if TARGET_OS_MAC 1612#pragma pack(pop) 1613#endif 1614 1615#ifdef __cplusplus 1616} 1617#endif /* __cplusplus */ 1618 1619#endif /* __CREDENTIALSCACHE__ */ 1620