2 * Copyright (c) 2005 Massachusetts Institute of Technology
4 * Permission is hereby granted, free of charge, to any person
5 * obtaining a copy of this software and associated documentation
6 * files (the "Software"), to deal in the Software without
7 * restriction, including without limitation the rights to use, copy,
8 * modify, merge, publish, distribute, sublicense, and/or sell copies
9 * of the Software, and to permit persons to whom the Software is
10 * furnished to do so, subject to the following conditions:
12 * The above copyright notice and this permission notice shall be
13 * included in all copies or substantial portions of the Software.
15 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
16 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
17 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
18 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
19 * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
20 * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
21 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
27 #ifndef __KHIMAIRA_KCREDDB_H__
28 #define __KHIMAIRA_KCREDDB_H__
34 /*! \defgroup kcdb NetIDMgr Credentials Database */
37 /*! \brief Maximum length in characters of short description
39 The length includes the terminating \a NULL character.
41 #define KCDB_MAXCCH_SHORT_DESC 256
43 /*! \brief Maximum length in bytes of short description
45 The length includes the terminating \a NULL character.
47 #define KCDB_MAXCB_SHORT_DESC (sizeof(wchar_t) * KCDB_MAXCCH_SHORT_DESC)
49 /*! \brief Maximum length in characters of long description
51 The length includes the terminating \a NULL character.
53 #define KCDB_MAXCCH_LONG_DESC 8192
55 /*! \brief Maximum length in characters of long description
57 The length includes the terminating \a NULL character.
59 #define KCDB_MAXCB_LONG_DESC (sizeof(wchar_t) * KCDB_MAXCCH_LONG_DESC)
61 /*! \brief Maximum length in characters of name
63 The length includes the terminating \a NULL character.
65 #define KCDB_MAXCCH_NAME 256
67 /*! \brief Maximum length in bytes of short description
69 The length includes the terminating \a NULL character.
71 #define KCDB_MAXCB_NAME (sizeof(wchar_t) * KCDB_MAXCCH_NAME)
73 /*! \brief Automatically determine the number of bytes required
75 Can be used in most places where a count of bytes is required.
76 For many objects, the number of bytes that are required can be
77 determined through context and may be ommited. In such cases you
78 can use the \a KCDB_CBSIZE_AUTO value to specify that the function
79 is to determine the size automatically.
81 \note Not all functions that take a count of bytes support the \a
82 KCDB_CBSIZE_AUTO value.
84 #define KCDB_CBSIZE_AUTO (-1)
87 \defgroup kcdb_ident Identities
89 Functions, macros etc. for manipulating identities.
94 /*! \brief The maximum number of characters (including terminator) that can
95 be specified as an identity name */
96 #define KCDB_IDENT_MAXCCH_NAME 256
98 /*! \brief The maximum number of bytes that can be specified as an identity
100 #define KCDB_IDENT_MAXCB_NAME (sizeof(wchar_t) * KCDB_IDENT_MAXCCH_NAME)
102 /*! \brief Valid characters in an identity name */
103 #define KCDB_IDENT_VALID_CHARS L"0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ._@-/"
106 \name Flags for identities */
109 /*! \brief Create the identity if it doesn't already exist.
110 \note Only to be used with kcdb_identity_create() */
111 #define KCDB_IDENT_FLAG_CREATE 0x10000000L
113 /*! \brief Has configuration information
115 Indicates that the identity has persistent configuration
116 information associated with it.
118 #define KCDB_IDENT_FLAG_CONFIG 0x00800000L
120 /*! \brief Marks the identity as active.
122 An active identity is one that is in active use within NetIDMgr.
124 \note This flag is readonly and cannot be specified when creating
125 or modifying an identity. Once an identity is deleted, it will
126 no longer have this flag. */
127 #define KCDB_IDENT_FLAG_ACTIVE 0x02000000L
130 /*! \brief The identity has custom attributes assigned
132 #define KCDB_IDENT_FLAG_ATTRIBS 0x08000000L
134 /*! \brief This is the default identity.
136 At most one identity will have this flag set at any given time.
137 To set or reset the flag, use kcdb_identity_set_default() */
138 #define KCDB_IDENT_FLAG_DEFAULT 0x00000001L
140 /*! \brief This identity can be searched.
142 The meaning of this flag is left to be interpreted by individual
144 #define KCDB_IDENT_FLAG_SEARCHABLE 0x00000002L
146 /*! \brief Hidden identity.
148 The identity will not show up in the identity list window. Once
149 the hidden is switched off, the identity (and all associated
150 credentials) will re-appear in the window */
151 #define KCDB_IDENT_FLAG_HIDDEN 0x00000004L
153 /*! \brief Invalid identity
155 For one reason or another, this identity is invalid. This flag
156 can be set by an identity provider to indicate that this identity
157 does not correspond to an actual identity because an external
158 entity (such as a KDC) has denied it's existence.
160 The absence of this flag does not imply that the identity is
161 valid. The ::KCDB_IDENT_FLAG_VALID bit must be set for that to be
162 the case. If neither flag is set, then the status of the identity
165 #define KCDB_IDENT_FLAG_INVALID 0x00000008L
167 /*! \brief Valid identity
169 The identity has been validated through an external entity, or
170 it's validity implied through the existence of credentials for the
173 The absence of this flag does not imply that the identity is
174 invalid. The ::KCDB_IDENT_FLAG_INVALID bit must be set for that
175 to be the case. If neither flag is set, then the status of the
176 identity is not known.
178 #define KCDB_IDENT_FLAG_VALID 0x00000010L
180 /*! \brief Expired identity
182 This identity has expired and can not be actively used to obtain
183 credentials. This determination is made based on the input of
184 some external entity. This flag may only be set by an identity
187 #define KCDB_IDENT_FLAG_EXPIRED 0x00000020L
189 /*! \brief Empty identity
191 The identity does not have actual credentials associated with it.
193 #define KCDB_IDENT_FLAG_EMPTY 0x00000040L
195 /*! \brief Renewable identity
197 The initial credentials associated with this identity are
198 renewable. Thus making the whole identity renewable.
200 #define KCDB_IDENT_FLAG_RENEWABLE 0x00000080L
202 /*! \brief Required user interaction
204 The identity is in a state which requires user interaction to
205 activate. Currently, the identity may not be in a state where it
206 can be used to obtain credentials.
208 A typical example of this is when the primary password for an
209 identity has expired.
211 #define KCDB_IDENT_FLAG_INTERACT 0x00000100L
213 /*! \brief Has expired credentials
215 The identity has expired credentials associated with it.
217 #define KCDB_IDENT_FLAG_CRED_EXP 0x00000200L
219 /*! \brief Has renewable credentials
221 The identity has renewable credentials associated with it. If the
222 initial credentials of the identity are renewable, then identity
223 is renewable. Hence the ::KCDB_IDENT_FLAG_RENEWABLE should also
226 #define KCDB_IDENT_FLAG_CRED_RENEW 0x00000400L
228 /*! \brief Sticky identity
230 Sticky identities are identities that are always visible in the
231 credentials display even if no credentials are associated with it.
233 #define KCDB_IDENT_FLAG_STICKY 0x00000800L
235 /*! \brief Read/write flags mask.
237 A bitmask that correspond to all the read/write flags in the mask.
239 #define KCDB_IDENT_FLAGMASK_RDWR 0x00000fffL
243 /*! \name Identity Provider Data Structures
246 /*! \brief Name transfer structure
248 Used when the KCDB is communicating with the identity provider to
249 exchange string names of identities. See individual ::KMSG_IDENT
250 message subtypes for the usage of this structure.
252 typedef struct tag_kcdb_ident_name_xfer {
253 const wchar_t * name_src; /*!< An identity name. Does not
254 exceed KCDB_IDENT_MAXCCH_NAME
255 characters including terminating
257 const wchar_t * name_alt; /*!< An identity name. Does not
258 exceed KCDB_IDENT_MAXCCH_NAME
259 characters including terminating
261 wchar_t * name_dest; /*!< Pointer to a buffer that is to
262 receive a response string. The
263 size of the buffer in bytes is
264 specified in \a cb_name_dest. */
265 khm_size cb_name_dest; /*!< Size of buffer pointed to by \a
266 name_dest in bytes. */
267 khm_int32 result; /*!< Receives a result value, which is
268 usually an error code defined in
269 kherror.h, though it is not
271 } kcdb_ident_name_xfer;
273 typedef struct tag_kcdb_ident_info {
282 /*! \name Identity provider interface functions
284 These functions encapsulate safe calls to the current identity
285 provider. While these functions are exported, applications should
286 not call these functions directly. They are provided for use by
287 the NetIDMgr core application.
290 /*! \brief Validate an identity name
292 The name that is provided will be passed through sets of
293 validations. One set, which doesn't depend on the identity
294 provider checks whether the length of the identity name and
295 whether there are any invalid characters in the identity name. If
296 the name passes those tests, then the name is passed down to the
297 identity provider's name validation handler.
299 \retval KHM_ERROR_SUCCESS The name is valid
300 \retval KHM_ERROR_TOO_LONG Too many characters in name
301 \retval KHM_ERROR_INVALID_NAME There were invalid characters in the name.
302 \retval KHM_ERROR_NO_PROVIDER There is no identity provider;
303 however the name passed the length and character tests.
304 \retval KHM_ERROR_NOT_IMPLEMENTED The identity provider doesn't
305 implement a name validation handler; however the name passed
306 the length and character tests.
308 \see ::KMSG_IDENT_VALIDATE_NAME
310 KHMEXP khm_int32 KHMAPI
311 kcdb_identpro_validate_name(const wchar_t * name);
313 /*! \brief Validate an identity
315 The identity itself needs to be validated. This may involve
316 communicating with an external entity.
318 \see ::KMSG_IDENT_VALIDATE_IDENTITY
320 KHMEXP khm_int32 KHMAPI
321 kcdb_identpro_validate_identity(khm_handle identity);
323 /*! \brief Canonicalize the name
326 \see ::KMSG_IDENT_CANON_NAME
328 KHMEXP khm_int32 KHMAPI
329 kcdb_identpro_canon_name(const wchar_t * name_in,
331 khm_size * cb_name_out);
333 /*! \brief Compare two identity names
335 \see ::KMSG_IDENT_COMPARE_NAME
337 KHMEXP khm_int32 KHMAPI
338 kcdb_identpro_compare_name(const wchar_t * name1,
339 const wchar_t * name2);
341 /*! \brief Set the specified identity as the default
343 \see ::KMSG_IDENT_SET_DEFAULT
345 KHMEXP khm_int32 KHMAPI
346 kcdb_identpro_set_default(khm_handle identity);
348 /*! \brief Set the specified identity as searchable
350 \see ::KMSG_IDENT_SET_SEARCHABLE
352 KHMEXP khm_int32 KHMAPI
353 kcdb_identpro_set_searchable(khm_handle identity,
354 khm_boolean searchable);
356 /*! \brief Update the specified identity
358 \see ::KMSG_IDENT_UPDATE
360 KHMEXP khm_int32 KHMAPI
361 kcdb_identpro_update(khm_handle identity);
363 /*! \brief Obtain the UI callback
365 \a rock is actually a pointer to a ::khui_ident_new_creds_cb which
366 is to receive the callback.
368 \see ::KMSG_IDENT_GET_UI_CALLBACK
370 KHMEXP khm_int32 KHMAPI
371 kcdb_identpro_get_ui_cb(void * rock);
373 /*! \brief Notify an identity provider of the creation of a new identity
375 \see ::KMSG_IDENT_NOTIFY_CREATE
377 KHMEXP khm_int32 KHMAPI
378 kcdb_identpro_notify_create(khm_handle identity);
382 /*! \brief Check if the given name is a valid identity name
384 \return TRUE or FALSE to the question, is this valid?
386 KHMEXP khm_boolean KHMAPI
387 kcdb_identity_is_valid_name(const wchar_t * name);
389 /*! \brief Create or open an identity.
391 If the KCDB_IDENT_FLAG_CREATE flag is specified in the flags
392 parameter a new identity will be created if one does not already
393 exist with the given name. If an identity by that name already
394 exists, then the existing identity will be opened. The result
395 parameter will receive a held reference to the opened identity.
396 Use kcdb_identity_release() to release the handle.
398 \param[in] name Name of identity to create
399 \param[in] flags If KCDB_IDENT_FLAG_CREATE is specified, then the
400 identity will be created if it doesn't already exist.
401 Additional flags can be set here which will be assigned to the
402 identity if it is created. Additional flags have no effect if
403 an existing identity is opened.
404 \param[out] result If the call is successful, this receives a held
405 reference to the identity. The caller should call
406 kcdb_identity_release() to release the identity once it is no
409 KHMEXP khm_int32 KHMAPI
410 kcdb_identity_create(const wchar_t *name,
412 khm_handle * result);
414 /*! \brief Mark an identity for deletion.
416 The identity will be marked for deletion. The
417 KCDB_IDENT_FLAG_ACTIVE will no longer be present for this
418 identity. Once all references to the identity are released, it
419 will be removed from memory. All associated credentials will also
421 KHMEXP khm_int32 KHMAPI
422 kcdb_identity_delete(khm_handle id);
424 /*! \brief Set or unset the specified flags in the specified identity.
426 Only flags that are in KCDB_IDENT_FLAGMASK_RDWR can be specifed in
427 the \a flags parameter or the \a mask parameter. The flags set in
428 the \a mask parameter of the identity will be set to the
429 corresponding values in the \a flags parameter.
431 If ::KCDB_IDENT_FLAG_INVALID is set using this function, then the
432 ::KCDB_IDENT_FLAG_VALID will be automatically reset, and vice
433 versa. Resetting either bit does not undo this change, and will
434 leave the identity's validity unspecified.
436 Note that setting or resetting certain flags have other semantic
439 - ::KCDB_IDENT_FLAG_DEFAULT : Setting this is equivalent to
440 calling kcdb_identity_set_default() with \a id. Resetting this
441 is equivalent to calling kcdb_identity_set_default() with NULL.
443 - ::KCDB_IDENT_FLAG_SEARCHABLE : Setting this will result in the
444 identity provider getting notified of the change. If the
445 identity provider indicates that searchable flag should not be
446 set or reset on the identity, then kcdb_identity_set_flags()
447 will return an error.
449 \note kcdb_identity_set_flags() is not atomic. Even if the
450 function returns a failure code, some flags in the identity may
451 have been set. When calling kcdb_identity_set_flags() always
452 check the flags in the identity using kcdb_identity_get_flags() to
453 check which flags have been set and which have failed.
455 KHMEXP khm_int32 KHMAPI
456 kcdb_identity_set_flags(khm_handle id,
460 /*! \brief Return all the flags for the identity
462 The returned flags may include internal flags.
464 KHMEXP khm_int32 KHMAPI
465 kcdb_identity_get_flags(khm_handle id,
468 /*! \brief Return the name of the identity
470 \param[out] buffer Buffer to copy the identity name into. The
471 maximum size of an identity name is \a KCDB_IDENT_MAXCB_NAME.
472 If \a buffer is \a NULL, then the required size of the buffer
473 is returned in \a pcbsize.
475 \param[in,out] pcbsize Size of buffer in bytes. */
476 KHMEXP khm_int32 KHMAPI
477 kcdb_identity_get_name(khm_handle id,
481 /*! \brief Set the specified identity as the default.
483 Specifying NULL effectively makes none of the identities the
486 \see kcdb_identity_set_flags()
488 KHMEXP khm_int32 KHMAPI
489 kcdb_identity_set_default(khm_handle id);
491 /*! \brief Mark the specified identity as the default.
493 This API is reserved for use by identity providers as a means of
494 specifying which identity is default. The difference between
495 kcdb_identity_set_default() and kcdb_identity_set_default_int() is
498 - kcdb_identity_set_default() is used to request the KCDB to
499 designate the specified identity as the default. When
500 processing the request, the KCDB invokes the identity provider
501 to do the necessary work to make the identity the default.
503 - kcdb_identity_set_default_int() is used by the identity provider
504 to notify the KCDB that the specified identity is the default.
505 This does not result in the invocation of any other semantics to
506 make the identity the default other than releasing the previous
507 defualt identity and making the specified one the default. As
508 an additional side effect, the notification <::KMSG_KCDB,
509 ::KMSG_KCDB_IDENT, ::KCDB_OP_NEW_DEFAULT> will also not be sent.
511 KHMEXP khm_int32 KHMAPI
512 kcdb_identity_set_default_int(khm_handle id);
514 /*! \brief Get the default identity
516 Obtain a held handle to the default identity if there is one. The
517 handle must be freed using kcdb_identity_release().
519 If there is no default identity, then the handle pointed to by \a
520 pvid is set to \a NULL and the function returns
521 KHM_ERROR_NOT_FOUND. */
522 KHMEXP khm_int32 KHMAPI
523 kcdb_identity_get_default(khm_handle * pvid);
525 /*! \brief Get the configuration space for the identity.
527 If the configuration space for the identity does not exist and the
528 flags parameter does not specify ::KHM_FLAG_CREATE, then the
529 function will return a failure code as specified in
530 ::khc_open_space(). Depending on whether or not a configuration
531 space was found, the ::KCDB_IDENT_FLAG_CONFIG flag will be set or
532 reset for the identity.
534 \param[in] id Identity for which the configuraiton space is requested
536 \param[in] flags Flags used when calling khc_open_space(). If \a
537 flags specifies KHM_FLAG_CREATE, then the configuration space
540 \param[out] result The resulting handle. If the call is
541 successful, this receives a handle to the configuration space.
542 Use khc_close_space() to close the handle.
544 KHMEXP khm_int32 KHMAPI
545 kcdb_identity_get_config(khm_handle id,
547 khm_handle * result);
549 /*! \brief Hold a reference to an identity.
551 A reference to an identity (a handle) is only valid while it is
552 held. \note Once the handle is released, it can not be
553 revalidated by calling kcdb_identity_hold(). Doing so would lead
554 to unpredictable consequences. */
555 KHMEXP khm_int32 KHMAPI
556 kcdb_identity_hold(khm_handle id);
558 /*! \brief Release a reference to an identity.
559 \see kcdb_identity_hold() */
560 KHMEXP khm_int32 KHMAPI
561 kcdb_identity_release(khm_handle id);
563 /*! \brief Set the identity provider subscription
565 If there was a previous subscription, that subscription will be
566 automatically deleted.
568 \param[in] sub New identity provider subscription
570 KHMEXP khm_int32 KHMAPI
571 kcdb_identity_set_provider(khm_handle sub);
573 /*! \brief Set the primary credentials type
575 The primary credentials type is designated by the identity
576 provider. As such, this function should only be called by an
579 KHMEXP khm_int32 KHMAPI
580 kcdb_identity_set_type(khm_int32 cred_type);
582 /*! \brief Retrieve the identity provider subscription
584 \param[out] sub Receives the current identity provider
585 subscription. Set to NULL if only the existence of an
586 identity provider needs to be checked.
588 \retval KHM_ERROR_SUCCESS An identity provider exists. If \a sub
589 was not NULL, the subscription has been copied there.
591 \retval KHM_ERROR_NOT_FOUND There is currently no registered
592 identity provider. If \a sub was not NULL, the handle it
593 points to has been set to NULL.
595 KHMEXP khm_int32 KHMAPI
596 kcdb_identity_get_provider(khm_handle * sub);
598 /*! \brief Retrieve the identity provider credentials type
600 This is the credentials type that the identity provider has
601 designated as the primary credentials type.
603 KHMEXP khm_int32 KHMAPI
604 kcdb_identity_get_type(khm_int32 * ptype);
606 /*! \brief Returns TRUE if the two identities are equal
608 Also returns TRUE if both identities are NULL.
610 KHMEXP khm_boolean KHMAPI
611 kcdb_identity_is_equal(khm_handle identity1,
612 khm_handle identity2);
614 /*! \brief Set an attribute in an identity by attribute id
616 \param[in] buffer A pointer to a buffer containing the data to
617 assign to the attribute. Setting \a buffer to NULL has the
618 effect of removing any data that is already assigned to the
619 attribute. If \a buffer is non-NULL, then \a cbbuf should
620 specify the number of bytes in \a buffer.
622 \param[in] cbbuf Number of bytes of data in \a buffer. The
623 individual data type handlers may copy in less than this many
624 bytes in to the credential.
626 KHMEXP khm_int32 KHMAPI
627 kcdb_identity_set_attr(khm_handle identity,
632 /*! \brief Set an attribute in an identity by name
634 The attribute name has to be a KCDB registered attribute or
637 \param[in] cbbuf Number of bytes of data in \a buffer. The
638 individual data type handlers may copy in less than this many
639 bytes in to the credential.
641 KHMEXP khm_int32 KHMAPI
642 kcdb_identity_set_attrib(khm_handle identity,
647 /*! \brief Get an attribute from an identity by attribute id.
649 \param[in] buffer The buffer that is to receive the attribute
650 value. Set this to NULL if only the required buffer size is
653 \param[in,out] cbbuf The number of bytes available in \a buffer.
654 If \a buffer is not sufficient, returns KHM_ERROR_TOO_LONG and
655 sets this to the required buffer size.
657 \param[out] attr_type Receives the data type of the attribute.
658 Set this to NULL if the type is not required.
660 \note Set both \a buffer and \a cbbuf to NULL if only the
661 existence of the attribute is to be checked. If the attribute
662 exists in this identity then the function will return
663 KHM_ERROR_SUCCESS, otherwise it returns KHM_ERROR_NOT_FOUND.
665 KHMEXP khm_int32 KHMAPI
666 kcdb_identity_get_attr(khm_handle identity,
668 khm_int32 * attr_type,
672 /*! \brief Get an attribute from an identity by name.
674 \param[in] buffer The buffer that is to receive the attribute
675 value. Set this to NULL if only the required buffer size is
678 \param[in,out] cbbuf The number of bytes available in \a buffer.
679 If \a buffer is not sufficient, returns KHM_ERROR_TOO_LONG and
680 sets this to the required buffer size.
682 \note Set both \a buffer and \a cbbuf to NULL if only the
683 existence of the attribute is to be checked. If the attribute
684 exists in this identity then the function will return
685 KHM_ERROR_SUCCESS, otherwise it returns KHM_ERROR_NOT_FOUND.
687 KHMEXP khm_int32 KHMAPI
688 kcdb_identity_get_attrib(khm_handle identity,
690 khm_int32 * attr_type,
694 /*! \brief Get the string representation of an identity attribute.
696 A shortcut function which generates the string representation of
697 an identity attribute directly.
699 \param[in] identity A handle to an identity
701 \param[in] attr_id The attribute to retrieve
703 \param[out] buffer A pointer to a string buffer which receives the
704 string form of the attribute. Set this to NULL if you only
705 want to determine the size of the required buffer.
707 \param[in,out] pcbbuf A pointer to a #khm_int32 that, on entry,
708 holds the size of the buffer pointed to by \a buffer, and on
709 exit, receives the actual number of bytes that were copied.
711 \param[in] flags Flags for the string conversion. Can be set to
712 one of KCDB_TS_LONG or KCDB_TS_SHORT. The default is
715 \retval KHM_ERROR_SUCCESS Success
716 \retval KHM_ERROR_NOT_FOUND The given attribute was either invalid
717 or was not defined for this identity
718 \retval KHM_ERROR_INVALID_PARAM One or more parameters were invalid
719 \retval KHM_ERROR_TOO_LONG Either \a buffer was NULL or the
720 supplied buffer was insufficient
722 KHMEXP khm_int32 KHMAPI
723 kcdb_identity_get_attr_string(khm_handle identity,
729 /*! \brief Get the string representation of an identity attribute by name.
731 A shortcut function which generates the string representation of
732 an identity attribute directly.
734 \param[in] identity A handle to an identity
736 \param[in] attrib The name of the attribute to retrieve
738 \param[out] buffer A pointer to a string buffer which receives the
739 string form of the attribute. Set this to NULL if you only
740 want to determine the size of the required buffer.
742 \param[in,out] pcbbuf A pointer to a #khm_int32 that, on entry,
743 holds the size of the buffer pointed to by \a buffer, and on
744 exit, receives the actual number of bytes that were copied.
746 \param[in] flags Flags for the string conversion. Can be set to
747 one of KCDB_TS_LONG or KCDB_TS_SHORT. The default is
750 \see kcdb_identity_get_attr_string()
752 KHMEXP khm_int32 KHMAPI
753 kcdb_identity_get_attrib_string(khm_handle identity,
759 /*! \brief Enumerate identities
761 Enumerates all the active identities that match the criteria
762 specified using \a and_flags and \a eq_flags. The condition is
763 applied to all active identities as follows:
766 (identity->flags & and_flags) == (eq_flags & and_flags)
769 Essentially, if a flag is set in \a and_flags, then that flag in
770 the identity should equal the setting in \a eq_flags.
772 \param[in] and_flags See above
774 \param[in] eq_flags See above
776 \param[out] name_buf Buffer to receive the list of identity names.
777 Can be NULL if only the required size of the buffer or the
778 number of matching identities is required. The list is
779 returned as a multi string.
781 \param[in,out] pcb_buf Number of bytes in buffer pointed to by \a
782 name_buf on entry. On exit, will receive the number of bytes
783 copied. Can be NULL only if \a name_buf is also NULL. If \a
784 name_buf is NULL or if \a pcb_buf indicates that the buffer is
785 insufficient, this will receive the number of bytes required
786 and the return value of the function will be
789 \param[out] pn_idents Receives the number of identities that match
792 \retval KHM_ERROR_SUCCESS If \a name_buf was valid, the buffer now
793 contains a multi string of identities that matched. If \a
794 pn_idents was valid, it contains the number of identities
797 \retval KHM_ERROR_TOO_LONG No buffer was supplied or the supplied
798 buffer was insufficient. If \a pn_idents was valid, it
799 contains the number of identities.
801 \retval KHM_ERROR_INVALID_PARAM None of the parameters \a name_buf,
802 \a pcb_buf and \a pn_idents were supplied, or \a pcb_buf was
803 NULL when \a name_buf was not.
805 \note Calling this function to obtain the required size of the
806 buffer and then calling it with a that sized buffer is not
807 guaranteed to work since the list of identities may change
808 between the two calls.
810 KHMEXP khm_int32 KHMAPI
811 kcdb_identity_enum(khm_int32 and_flags,
815 khm_size * pn_idents);
817 /*! \brief Refresh identity attributes based on root credential set
819 Several flags in an identity are dependent on the credentials that
820 are associated with it in the root credential set. In addition,
821 other flags in an identity depend on external factors that need to
822 be verfied once in a while. This API goes through the root
823 credential set as well as consulting the identity provider to
826 \see kcdb_identity_refresh()
828 KHMEXP khm_int32 KHMAPI
829 kcdb_identity_refresh(khm_handle vid);
831 /*! \brief Refresh all identities
833 Equivalent to calling kcdb_identity_refresh() for all active
836 \see kcdb_identityt_refresh()
838 KHMEXP khm_int32 KHMAPI
839 kcdb_identity_refresh_all(void);
841 /* KSMG_KCDB_IDENT notifications are structured as follows:
843 subtype=KMSG_KCDB_IDENT
844 uparam=one of KCDB_OP_*
845 blob=handle to identity in question */
850 /*********************************************************************/
854 \defgroup kcdb_creds Credential sets and individual credentials
860 /*! \brief Credentials process function
862 This function is called for each credential in a credential set
863 when supplied to kcdb_credset_apply(). It should return
864 KHM_ERROR_SUCCESS to continue the operation, or any other value to
865 terminate the processing.
867 \see kcdb_credset_apply()
870 (KHMAPI *kcdb_cred_apply_func)(khm_handle cred,
873 /*! \brief Credentials filter function.
875 Should return non-zero if the credential passed as \a cred is to
876 be "accepted". The precise consequence of a non-zero return value
877 is determined by the individual function that this call back is
880 This function should not call any other function which may modify
883 \see kcdb_credset_collect_filtered()
884 \see kcdb_credset_extract_filtered()
887 (KHMAPI *kcdb_cred_filter_func)(khm_handle cred,
891 /*! \brief Credentials compare function.
893 Asserts a weak ordering on the credentials that are passed in as
894 \a cred1 and \a cred2. It should return:
896 - a negative value if \a cred1 < \a cred2
897 - zero if \a cred1 == \a cred2
898 - a postive value if \a cred1 > \a cred2
899 \see kcdb_credset_sort()
903 (KHMAPI *kcdb_cred_comp_func)(khm_handle cred1,
907 /*! \defgroup kcdb_credset Credential sets */
910 /*! \brief Create a credential set.
912 Credential sets are temporary containers for credentials. These
913 can be used by plug-ins to store credentials while they are being
914 enumerated from an external source. Once all the credentials have
915 been collected into the credential set, the plug-in may call
916 kcdb_credset_collect() to collect the credentials into the root
919 The user interface will only display credentials that are in the
920 root credential store. No notifications are generated for changes
921 to a non-root credential set.
923 Use kcdb_credset_delete() to delete the credential set once it is
926 \see kcdb_credset_delete()
927 \see kcdb_credset_collect()
929 KHMEXP khm_int32 KHMAPI
930 kcdb_credset_create(khm_handle * result);
932 /** \brief Delete a credential set
934 \see kcdb_credset_create()
936 KHMEXP khm_int32 KHMAPI
937 kcdb_credset_delete(khm_handle credset);
939 /** \brief Collect credentials from a credential set to another credential set.
941 Collecting a subset of credentials from credential set \a cs_src
942 into credential set \a cs_dest involves the following steps:
944 - Select all credentials from \a cs_src that matches the \a
945 identity and \a type specified in the function call and add them
946 to the \a cs_dest credential set if they are not there already.
947 Note that if neither credential set is not the root credential
948 store, then the credentials will be added by reference, while if
949 it is the root credential store, the credentials will be
950 duplicated, and the copies will be added to \a cs_dest.
952 - If a selected credential in \a cs_src already exists in \a
953 cs_dest, then update the credential in \a cs_dest with the
954 credential fields in \a cs_src. In other words, once a
955 credential is found to exist in both \a cs_src and \a cs_dest,
956 all the non-null fields from the credential in \a cs_src will be
957 copied to the credential in \a cs_dest. Fields which are null
958 (undefined) in \a cs_src and are non-null in \a cs_dest will be
959 left unmodified in \a cs_dest.
961 One notable exception is the credentials' flags. All flags in
962 \a cs_src which are not included in
963 ::KCDB_CRED_FLAGMASK_ADDITIVE will be copied to the
964 corresponding bits in the flags of \a cs_dest. However, flags
965 that are included in ::KCDB_CRED_FLAGMASK_ADDITIVE will be added
966 to the corresponding bits in \a cs_dest.
970 - Remove all credentials from \a cs_dest that match the \a
971 identity and \a type that do not appear in \a cs_src. (see notes
974 For performance reasons, plugins should use kcdb_credset_collect()
975 to update the root credentials store instead of adding and
976 removing individual credentials from the root store.
978 Only credentials that are associated with active identities are
979 affected by kcdb_credset_collect().
981 \param[in] cs_dest A handle to the destination credential set. If
982 this is \a NULL, then it is assumed to refer to the root
985 \param[in] cs_src A handle to the source credential set. If this
986 is NULL, then it is assumed to refer to the root credential
989 \param[in] identity A handle to an identity. Setting this to NULL
990 collects all identities in the credential set.
992 \param[in] type A credentials type. Setting this to
993 KCDB_CREDTYPE_ALL collects all credential types in the set.
995 \param[out] delta A bit mask that indicates the modifications that
996 were made to \a cs_dest as a result of the collect operation.
997 This is a combination of KCDB_DELTA_* values. This parameter
998 can be \a NULL if the value is not required.
1000 \warning If \a identity and \a type is set to a wildcard, all
1001 credentials in the root store that are not in this credentials
1002 set will be deleted.
1004 \note Two credentials \a A and \a B are considered equal if:
1005 - They refer to the same identity
1006 - Both have the same credential type
1007 - Both have the same name
1009 \note This is the only supported way of modifying the root
1012 \note \a cs_src and \a cs_dest can not refer to the same
1015 \note The destination credential set cannot be sealed.
1017 KHMEXP khm_int32 KHMAPI
1018 kcdb_credset_collect(khm_handle cs_dest,
1020 khm_handle identity,
1024 /*! \brief Credentials were added
1025 \see kcdb_credset_collect() */
1026 #define KCDB_DELTA_ADD 1
1028 /*! \brief Credentials were deleted
1029 \see kcdb_credset_collect() */
1030 #define KCDB_DELTA_DEL 2
1032 /*! \brief Credentials were modified
1033 \see kcdb_credset_collect() */
1034 #define KCDB_DELTA_MODIFY 4
1036 /*! \brief Indicates that the credential to be filtered is from the root store.
1038 \see kcdb_credset_collect_filtered()
1040 #define KCDB_CREDCOLL_FILTER_ROOT 1
1042 /*! \brief Indicates that the credential to be filtered is from the source
1045 \see kcdb_credset_collect_filtered() */
1046 #define KCDB_CREDCOLL_FILTER_SRC 2
1048 /*! \brief Indicates that the credential to be filtered is from the destination
1051 \see kcdb_credset_collect_filtered() */
1052 #define KCDB_CREDCOLL_FILTER_DEST 4
1054 /*! \brief Collect credentials from one credential set to another using a filter.
1056 Similar to kcdb_credset_collect() except instead of selecting
1057 credentials by matching against an identity and/or type, a filter
1058 function is called. If the filter function returns non-zero for a
1059 credential, that credential is selected.
1061 Credentials in the source and destination credential sets are
1062 passed into the filter function. Depending on whether the
1063 credential is in the source credential set or destination
1064 credential set, the \a flag parameter may have either \a
1065 KCDB_CREDCOLL_FILTER_SRC or \a KCDB_CREDCOLL_FILTER_DEST bits set.
1066 Also, if either one of the credential sets is the root credential
1067 store, then additionally \a KCDB_CREDCOLL_FILTER_ROOT would also
1070 See the kcdb_credset_collect() documentation for explanations of
1071 the \a cs_src, \a cs_dest and \a delta parameters which perform
1072 identical functions.
1074 \param[in] filter The filter of type ::kcdb_cred_filter_func
1075 \param[in] rock A custom argument to be passed to the filter function.
1077 \see kcdb_credset_collect()
1079 KHMEXP khm_int32 KHMAPI
1080 kcdb_credset_collect_filtered(khm_handle cs_dest,
1082 kcdb_cred_filter_func filter,
1086 /*! \brief Flush all credentials from a credential set
1088 Deletes all the crednetials from the credential set.
1090 \param[in] credset A handle to a credential set. Cannot be NULL.
1092 \note The credential set cannot be sealed
1094 KHMEXP khm_int32 KHMAPI
1095 kcdb_credset_flush(khm_handle credset);
1097 /*! \brief Extract credentials from one credential set to another
1099 Credentials from the source credential set are selected based on
1100 the \a identity and \a type arguements. If a credential is
1101 matched, then it is added to the \a destcredset.
1103 If the \a sourcecredset is the root credential set, the added
1104 credentials are copies of the actual credentials in the root
1105 credential set. Otherwise the credentials are references to the
1106 original credentials in the \a sourcecredset .
1108 \param[in] destcredset Destination credential set. Must be valid.
1110 \param[in] sourcecredset The source credential set. If set to
1111 NULL, extracts from the root credential set.
1113 \param[in] identity The identity to match in the source credential
1114 set. If set to NULL, matches all identities.
1116 \param[in] type The credential type to match in the source credential set.
1117 If set to KCDB_CREDTYPE_INVALID, matches all types.
1119 \note This function does not check for duplicate credentials.
1121 \note The destination credential set cannot be sealed.
1123 KHMEXP khm_int32 KHMAPI
1124 kcdb_credset_extract(khm_handle destcredset,
1125 khm_handle sourcecredset,
1126 khm_handle identity,
1129 /*! \brief Extract credentials from one credential set to another using a filter.
1131 Similar to kcdb_credset_extract() except a filter function is used
1132 to determine which credentials should be selected.
1134 \param[in] rock A custom argument to be passed in to the filter function.
1136 \note The destination credential set cannot be sealed.
1138 KHMEXP khm_int32 KHMAPI
1139 kcdb_credset_extract_filtered(khm_handle destcredset,
1140 khm_handle sourcecredset,
1141 kcdb_cred_filter_func filter,
1144 /*! \brief Retrieve a held reference to a credential in a credential set based on index.
1146 \param[in] idx The index of the credential to retrieve. This is a
1147 zero based index which goes from 0 ... (size of credset - 1).
1149 \param[out] cred The held reference to a credential. Call
1150 kcdb_cred_release() to release the credential.
1152 \retval KHM_ERROR_SUCCESS Success. \a cred has a held reference to the credential.
1153 \retval KHM_ERROR_OUT_OF_BOUNDS The index specified in \a idx is out of bounds.
1154 \retval KHM_ERROR_DELETED The credential at index \a idx has been marked as deleted.
1156 \see kcdb_cred_release()
1158 KHMEXP khm_int32 KHMAPI
1159 kcdb_credset_get_cred(khm_handle credset,
1163 /*! \brief Search a credential set for a specific credential
1165 The credential set indicated by \a credset is searched for a
1166 credential that satisfies the predicate function \a f. Each
1167 credential starting at \a idx_start is passed into the predicate
1168 function until it returns a non-zero value. At this point, that
1169 credential is passed in to the \a cred parameter, and the index of
1170 the credential is passed into the \a idx parameter.
1172 \param[in] credset The credential set to search on. Specify NULL
1173 if you want to search teh root credential set.
1175 \param[in] idx_start The index at which to start the search after.
1176 The first credential passed to the predicate function will be
1177 at \a idx_start + 1. Specify -1 to start from the beginning
1178 of the credential set.
1180 \param[in] f The predicate function. The \a flags parameter of
1181 the predicate function will always receive 0.
1183 \param[in] rock An opaque parameter to be passed to the predicate
1186 \param[out] cred A held reference to the credential that satisfied
1187 the predicate function or NULL if no such credential was
1188 found. Note that if a valid credential is returned, the
1189 calling function must release the credential using
1190 kcdb_cred_release().
1192 \param[out] idx The index of the credential passed in \a cred.
1193 Specify NULL if the index is not required.
1195 \retval KHM_ERROR_SUCCESS A credential that satisfied the
1196 predicate function was found and was assigned to \a cred.
1198 \retval KHM_ERROR_NOT_FOUND No credential was found that matched
1199 the predicate function.
1201 \note When querying credential sets that are shared between
1202 threads, it is possible that another thread modifies the
1203 credential set between successive calls to
1204 kcdb_credset_find_filtered(). Therefore a continued sequences of
1205 searches are not guaranteed to exhastively cover the
1206 credential set nor to not return duplicate matches. Duplicate
1207 matches are possible if the order of the credentials in the
1210 KHMEXP khm_int32 KHMAPI
1211 kcdb_credset_find_filtered(khm_handle credset,
1212 khm_int32 idx_start,
1213 kcdb_cred_filter_func f,
1218 /*! \brief Find matching credential
1220 Searches a credential set for a credential that matches the
1221 specified credential. For a credential to be a match, it must
1222 have the same identity, credential type and name.
1224 \param[in] credset Credential set to search
1226 \param[in] cred_src Credetial to search on
1228 \param[out] cred_dest receieves the matching credential if the
1229 search is successful. If a handle is returend, the
1230 kcdb_cred_release() must be used to release the handle. If
1231 the matching credential is not required, you can pass in NULL.
1233 \retval KHM_ERROR_SUCCESS The search was successful. A credential
1234 was assigned to \a cred_dest
1236 \retval KHM_ERROR_NOT_FOUND A matching credential was not found.
1238 KHMEXP khm_int32 KHMAPI
1239 kcdb_credset_find_cred(khm_handle credset,
1240 khm_handle cred_src,
1241 khm_handle *cred_dest);
1244 /*! \brief Delete a credential from a credential set.
1246 The credential at index \a idx will be deleted. All the
1247 credentials that are at indices \a idx + 1 and above will be moved
1248 down to fill the gap and the size of the credential set will
1251 Use kcdb_credset_del_cred_ref() to delete a credential by
1252 reference. Using kcdb_credset_del_cred() is faster than
1253 kcdb_credset_del_cred_ref().
1255 If you call kcdb_credset_del_cred() or kcdb_credset_del_cred_ref()
1256 from within kcdb_credset_apply(), the credential will only be
1257 marked as deleted. They will not be removed. This means that the
1258 size of the credential set will not decrease. To purge the
1259 deleted credentials from the set, call kcdb_credset_purge() after
1260 kcdb_credset_apply() completes.
1262 \note The credential set cannot be sealed.
1264 \see kcdb_credset_del_cred_ref()
1266 KHMEXP khm_int32 KHMAPI
1267 kcdb_credset_del_cred(khm_handle credset,
1270 /*! \brief Delete a credential from a credential set by reference.
1272 See kcdb_credset_del_cred() for description of what happens when a
1273 credential is deleted from a credential set.
1275 \note The credential set cannot be sealed.
1277 \see kcdb_credset_del_cred()
1279 KHMEXP khm_int32 KHMAPI
1280 kcdb_credset_del_cred_ref(khm_handle credset,
1283 /*! \brief Add a credential to a credential set.
1285 The credential is added by reference. In other words, no copy of
1286 the credential is made.
1288 \param[in] idx Index of the new credential. This must be a value
1289 in the range 0..(previous size of credential set) or -1. If
1290 -1 is specifed, then the credential is appended at the end of
1293 \note The credential set cannot be sealed.
1295 KHMEXP khm_int32 KHMAPI
1296 kcdb_credset_add_cred(khm_handle credset,
1300 /*! \brief Get the number of credentials in a credential set.
1302 Credentials in a credential set may be volatile. When
1303 kcdb_credeset_get_size() is called, the credential set is
1304 compacted to only include credentials that are active at the time.
1305 However, when you are iterating through the credential set, it
1306 might be the case that some credentials would get marked as
1307 deleted. These credentials will remain in the credential set
1308 until the credential set is discarded or another call to
1309 kcdb_credset_get_size() or kdcb_credset_purge() is made.
1311 If the credential set is sealed, then it will not be compacted and
1312 will include deleted credentials as well.
1314 \see kcdb_credset_purge()
1315 \see kcdb_credset_get_cred()
1317 KHMEXP khm_int32 KHMAPI
1318 kcdb_credset_get_size(khm_handle credset,
1321 /*! \brief Removes credentials that have been marked as deleted from a credential set.
1323 See description of \a kcdb_credset_purge() for a description of
1324 what happens when credntials that are contained in a credential
1325 set are deleted by an external entity.
1327 \note The credential set cannot be sealed.
1329 \see kcdb_credset_get_size()
1330 \see kcdb_credset_get_cred()
1332 KHMEXP khm_int32 KHMAPI
1333 kcdb_credset_purge(khm_handle credset);
1335 /*! \brief Applies a function to all the credentials in a credentials set
1337 The given function is called for each credential in a credential
1338 set. With each iteration, the function is called with a handle to
1339 the credential and the user defined parameter \a rock. If the
1340 function returns anything other than KHM_ERROR_SUCCESS, the
1343 \param[in] credset The credential set to apply the function to, or
1344 NULL if you want to apply this to the root credential set.
1346 \param[in] f Function to call for each credential
1348 \param[in] rock An opaque parameter which is to be passed to 'f'
1349 as the second argument.
1351 \retval KHM_ERROR_SUCCESS All the credentials were processed.
1353 \retval KHM_ERROR_EXIT The supplied function signalled the
1354 processing to be aborted.
1356 \retval KHM_ERROR_INVALID_PARAM One or more parameters were invalid.
1358 KHMEXP khm_int32 KHMAPI
1359 kcdb_credset_apply(khm_handle credset,
1360 kcdb_cred_apply_func f,
1363 /*! \brief Sort the contents of a credential set.
1365 \param[in] rock A custom argument to be passed in to the \a comp function.
1367 \note The credential set cannot be sealed.
1369 \see kcdb_cred_comp_generic()
1371 KHMEXP khm_int32 KHMAPI
1372 kcdb_credset_sort(khm_handle credset,
1373 kcdb_cred_comp_func comp,
1376 /*! \brief Seal a credential set
1378 Sealing a credential set makes it read-only. To unseal a
1379 credential set, call kcdb_credset_unseal().
1381 Sealing is an additive operation. kcdb_credset_seal() can be
1382 called muliple times. However, for every call to
1383 kcdb_credset_seal() a call to kcdb_credset_unseal() must be made
1384 to undo the seal. The credential set will become unsealed when
1385 all the seals are released.
1387 Once sealed, the credential set will not allow any operation that
1388 might change its contents. However, a selaed credential set can
1391 \see kcdb_credset_unseal()
1393 KHMEXP khm_int32 KHMAPI
1394 kcdb_credset_seal(khm_handle credset);
1396 /*! \brief Unseal a credential set
1398 Undoes what kcdb_credset_seal() did. This does not guarantee that
1399 the credential set is unsealed since there may be other seals.
1401 \see kcdb_credset_seal()
1403 KHMEXP khm_int32 KHMAPI
1404 kcdb_credset_unseal(khm_handle credset);
1406 /*! \brief Defines a sort criterion for kcdb_cred_comp_generic()
1408 \see kcdb_cred_comp_generic()
1410 typedef struct tag_kcdb_cred_comp_field {
1411 khm_int32 attrib; /*!< a valid attribute ID */
1412 khm_int32 order; /*!< one of KCDB_CRED_COMP_INCREASING or
1413 KCDB_CRED_COMP_DECREASING. Optionally,
1414 KCDB_CRED_COMP_INITIAL_FIRST may be combined
1416 } kcdb_cred_comp_field;
1418 /*! \brief Defines the sort order for a field in ::kcdb_cred_comp_field
1420 Sorts lexicographically ascending by string representation of field.
1422 #define KCDB_CRED_COMP_INCREASING 0
1424 /*! \brief Defines the sort order for a field in ::kcdb_cred_comp_field
1426 Sorts lexicographically descending by string representation of
1429 #define KCDB_CRED_COMP_DECREASING 1
1431 /*! \brief Defines the sort order for a field in ::kcdb_cred_comp_field
1433 Any credentials which have the ::KCDB_CRED_FLAG_INITIAL will be
1434 grouped above any that don't.
1436 If that does not apply, then credentials from the primary
1437 credentials type will be sorted before others.
1439 #define KCDB_CRED_COMP_INITIAL_FIRST 2
1441 /*! \brief Defines the sort criteria for kcdb_cred_comp_generic()
1443 \see kcdb_cred_comp_generic()
1445 typedef struct tag_kcdb_cred_comp_order {
1447 kcdb_cred_comp_field * fields;
1448 } kcdb_cred_comp_order;
1450 /*! \brief A generic compare function for comparing credentials.
1452 This function can be passed as a parameter to kcdb_credset_sort().
1454 The \a rock parameter to this function should be a pointer to a
1455 ::kcdb_cred_comp_order object. The \a fields member of the
1456 ::kcdb_cred_comp_order object should point to an array of
1457 ::kcdb_cred_comp_field objects, each of which specifies the sort
1458 order in decreasing order of priority. The number of
1459 ::kcdb_cred_comp_field objects in the array should correspond to
1460 the \a nFields member in the ::kcdb_cred_comp_order object.
1462 The array of ::kcdb_cred_comp_field objects define the sort
1463 criteria, in order. The \a attrib member should be a valid
1464 attribute ID, while the \a order member determines whether the
1465 sort order is increasing or decreasing. The exact meaning or
1466 increasing or decreasing depends on the data type of the
1469 \param[in] rock a pointer to a ::kcdb_cred_comp_order object
1471 KHMEXP khm_int32 KHMAPI
1472 kcdb_cred_comp_generic(khm_handle cred1,
1478 /*! \defgroup kcdb_cred Credentials */
1481 /*! \brief Maximum number of characters in a credential name */
1482 #define KCDB_CRED_MAXCCH_NAME 256
1484 /*! \brief Maximum number of bytes in a credential name */
1485 #define KCDB_CRED_MAXCB_NAME (sizeof(wchar_t) * KCDB_CRED_MAXCCH_NAME)
1487 /*! \brief Marked as deleted */
1488 #define KCDB_CRED_FLAG_DELETED 0x00000008
1490 /*! \brief Renewable */
1491 #define KCDB_CRED_FLAG_RENEWABLE 0x00000010
1495 Initial credentials form the basis of an identity. Some
1496 properties of an initial credential, such as being renewable, are
1497 directly inherited by the identity. An identity is also
1498 automatically considered valid if it contains a valid initial
1501 #define KCDB_CRED_FLAG_INITIAL 0x00000020
1505 The credential's lifetime has ended.
1507 #define KCDB_CRED_FLAG_EXPIRED 0x00000040
1511 The credential can no longer serve its intended function. This
1512 may be because it is expired and is not renewable, or its
1513 renewable time period has also expired, or for some other reason.
1515 #define KCDB_CRED_FLAG_INVALID 0x00000080
1517 /*! \brief Credential is selected
1519 Indicates that the credential is selected. Note that using this
1520 flag may be subject to race conditions.
1522 #define KCDB_CRED_FLAG_SELECTED 0x00000100
1524 /*! \brief Bitmask indicating all known credential flags
1526 #define KCDB_CRED_FLAGMASK_ALL 0x0000ffff
1528 /*! \brief External flags
1530 These are flags that are provided by the credentials providers.
1531 The other flags are internal to KCDB and should not be modified.
1533 #define KCDB_CRED_FLAGMASK_EXT (KCDB_CRED_FLAG_INITIAL | KCDB_CRED_FLAG_EXPIRED | KCDB_CRED_FLAG_INVALID | KCDB_CRED_FLAG_RENEWABLE)
1535 /*! \brief Bitmask indicating dditive flags
1537 Additive flags are special flags which are added to exiting
1538 credentials based on new credentials when doing a collect
1539 operation. See details on kcdb_credset_collect()
1541 \see kcdb_credset_collect()
1543 #define KCDB_CRED_FLAGMASK_ADDITIVE KCDB_CRED_FLAG_SELECTED
1545 /*! \brief Generic credentials request
1547 This data structure is used as the format for a generic
1548 credentials reqeust for a ::KMSG_KCDB_REQUEST message. A plugin
1549 typically publishes this message so that a credentials provider
1550 may handle it and in response, obtain the specified credential.
1552 While the \a identity, \a type and \a name members of the
1553 structure are all optional, typically one would specify all three
1554 or at least two for a credential provider to be able to provide
1555 the credential unambigously.
1557 Credential providers do not need to respond to ::KMSG_KCDB_REQUEST
1558 messages. However, if they do, they should make sure that they
1559 are the only credential provider that is responding by setting the
1560 \a semaphore member to a non-zero value. The \a semaphore is set
1561 to zero when a request is initially sent out. When incrementing
1562 the semaphore, the plugin should use a thread safe mechanism to
1563 ensure that there are no race conditions that would allow more
1564 than one provider to respond to the message.
1566 typedef struct tag_kcdb_cred_request {
1567 khm_handle identity; /*!< Identity of the credential. Set
1568 to NULL if not specified. */
1569 khm_int32 type; /*!< Type of the credential. Set to
1570 KCDB_CREDTYPE_INVALID if not
1572 wchar_t * name; /*!< Name of the credential. Set to
1573 NULL if not specified. */
1575 khm_handle dest_credset; /*!< If non-NULL, instructs whoever is
1576 handling the request that the
1577 credential thus obtained be placed
1578 in this credential set in addition
1579 to whereever it may place newly
1580 acquired credentials. Note that
1581 while this can be NULL if the new
1582 credential does not need to be
1583 placed in a credential set, it can
1584 not equal the root credential
1587 void * vparam; /*!< An unspecified
1588 parameter. Specific credential types
1589 may specify how this field is to be
1592 long semaphore; /*!< Incremented by one when this
1593 request is answered. Only one
1594 credential provider is allowed to
1595 answer a ::KMSG_KCDB_REQUEST
1596 message. Initially, when the
1597 message is sent out, this member
1598 should be set to zero. */
1599 } kcdb_cred_request;
1601 /*! \brief Create a new credential
1603 \param[in] name Name of credential. \a name cannot be NULL and cannot
1604 exceed \a KCDB_CRED_MAXCCH_NAME unicode characters including the
1606 \param[in] identity A reference to an identity.
1607 \param[in] cred_type A credentials type identifier for the credential.
1608 \param[out] result Gets a held reference to the newly created credential.
1609 Call kcdb_cred_release() or kcdb_cred_delete() to release the
1611 \see kcdb_cred_release()
1613 KHMEXP khm_int32 KHMAPI
1614 kcdb_cred_create(wchar_t * name,
1615 khm_handle identity,
1616 khm_int32 cred_type,
1617 khm_handle * result);
1619 /*! \brief Duplicate an existing credential.
1621 \param[out] newcred A held reference to the new credential if the call
1624 KHMEXP khm_int32 KHMAPI
1625 kcdb_cred_dup(khm_handle cred,
1626 khm_handle * newcred);
1628 /*! \brief Updates one credential using field values from another
1630 All fields that exist in \a vsrc will get copied to \a vdest and will
1631 overwrite any values that are already there in \a vdest. However any
1632 values that exist in \a vdest taht do not exist in \a vsrc will not be
1635 \retval KHM_ERROR_SUCCESS vdest was successfully updated
1636 \retval KHM_ERROR_EQUIVALENT all fields in vsrc were present and equivalent in vdest
1638 KHMEXP khm_int32 KHMAPI
1639 kcdb_cred_update(khm_handle vdest,
1642 /*! \brief Set an attribute in a credential by name
1644 \param[in] cbbuf Number of bytes of data in \a buffer. The
1645 individual data type handlers may copy in less than this many
1646 bytes in to the credential.
1648 KHMEXP khm_int32 KHMAPI
1649 kcdb_cred_set_attrib(khm_handle cred,
1654 /*! \brief Set an attribute in a credential by attribute id
1656 \param[in] buffer A pointer to a buffer containing the data to
1657 assign to the attribute. Setting this to NULL has the effect
1658 of removing any data that is already assigned to the
1659 attribute. If \a buffer is non-NULL, then \a cbbuf should
1660 specify the number of bytes in \a buffer.
1662 \param[in] cbbuf Number of bytes of data in \a buffer. The
1663 individual data type handlers may copy in less than this many
1664 bytes in to the credential.
1666 KHMEXP khm_int32 KHMAPI
1667 kcdb_cred_set_attr(khm_handle cred,
1672 /*! \brief Get an attribute from a credential by name.
1674 \param[in] buffer The buffer that is to receive the attribute
1675 value. Set this to NULL if only the required buffer size is
1678 \param[in,out] cbbuf The number of bytes available in \a buffer.
1679 If \a buffer is not sufficient, returns KHM_ERROR_TOO_LONG and
1680 sets this to the required buffer size.
1682 \note Set both \a buffer and \a cbbuf to NULL if only the
1683 existence of the attribute is to be checked. If the attribute
1684 exists in this credential then the function will return
1685 KHM_ERROR_SUCCESS, otherwise it returns KHM_ERROR_NOT_FOUND.
1687 KHMEXP khm_int32 KHMAPI
1688 kcdb_cred_get_attrib(khm_handle cred,
1690 khm_int32 * attr_type,
1694 /*! \brief Get an attribute from a credential by attribute id.
1696 \param[in] buffer The buffer that is to receive the attribute
1697 value. Set this to NULL if only the required buffer size is
1700 \param[in,out] cbbuf The number of bytes available in \a buffer.
1701 If \a buffer is not sufficient, returns KHM_ERROR_TOO_LONG and
1702 sets this to the required buffer size.
1704 \param[out] attr_type Receives the data type of the attribute.
1705 Set this to NULL if the type is not required.
1707 \note Set both \a buffer and \a cbbuf to NULL if only the
1708 existence of the attribute is to be checked. If the attribute
1709 exists in this credential then the function will return
1710 KHM_ERROR_SUCCESS, otherwise it returns KHM_ERROR_NOT_FOUND.
1712 KHMEXP khm_int32 KHMAPI
1713 kcdb_cred_get_attr(khm_handle cred,
1715 khm_int32 * attr_type,
1719 /*! \brief Get the name of a credential.
1721 \param[in] buffer The buffer that is to receive the credential
1722 name. Set this to NULL if only the required buffer size is to
1725 \param[in,out] cbbuf The number of bytes available in \a buffer.
1726 If \a buffer is not sufficient, returns KHM_ERROR_TOO_LONG and
1727 sets this to the required buffer size.
1729 KHMEXP khm_int32 KHMAPI
1730 kcdb_cred_get_name(khm_handle cred,
1734 /*! \brief Get the string representation of a credential attribute.
1736 A shortcut function which generates the string representation of a
1737 credential attribute directly.
1739 \param[in] vcred A handle to a credential
1741 \param[in] attr_id The attribute to retrieve
1743 \param[out] buffer A pointer to a string buffer which receives the
1744 string form of the attribute. Set this to NULL if you only
1745 want to determine the size of the required buffer.
1747 \param[in,out] pcbbuf A pointer to a #khm_int32 that, on entry,
1748 holds the size of the buffer pointed to by \a buffer, and on
1749 exit, receives the actual number of bytes that were copied.
1751 \param[in] flags Flags for the string conversion. Can be set to
1752 one of KCDB_TS_LONG or KCDB_TS_SHORT. The default is
1755 \retval KHM_ERROR_SUCCESS Success
1756 \retval KHM_ERROR_NOT_FOUND The given attribute was either invalid
1757 or was not defined for this credential
1758 \retval KHM_ERROR_INVALID_PARAM One or more parameters were invalid
1759 \retval KHM_ERROR_TOO_LONG Either \a buffer was NULL or the
1760 supplied buffer was insufficient
1762 KHMEXP khm_int32 KHMAPI
1763 kcdb_cred_get_attr_string(khm_handle vcred,
1769 /*! \brief Get the string representation of a credential attribute by name.
1771 A shortcut function which generates the string representation of a
1772 credential attribute directly.
1774 \param[in] vcred A handle to a credential
1776 \param[in] attrib The name of the attribute to retrieve
1778 \param[out] buffer A pointer to a string buffer which receives the
1779 string form of the attribute. Set this to NULL if you only
1780 want to determine the size of the required buffer.
1782 \param[in,out] pcbbuf A pointer to a #khm_int32 that, on entry,
1783 holds the size of the buffer pointed to by \a buffer, and on
1784 exit, receives the actual number of bytes that were copied.
1786 \param[in] flags Flags for the string conversion. Can be set to
1787 one of KCDB_TS_LONG or KCDB_TS_SHORT. The default is
1790 \see kcdb_cred_get_attr_string()
1792 KHMEXP khm_int32 KHMAPI
1793 kcdb_cred_get_attrib_string(khm_handle cred,
1800 /*! \brief Get a held reference to the identity associated with a credential
1802 Use kcdb_identity_release() to release the reference that is
1805 \see kcdb_identity_relase()
1807 KHMEXP khm_int32 KHMAPI
1808 kcdb_cred_get_identity(khm_handle cred,
1809 khm_handle * identity);
1811 /*! \brief Set the identity of a credential
1813 While it is ill-advised to change the identity of a credential
1814 that has been placed in one or more credential sets, there can be
1815 legitimate reasons for doing so. Only change the identity of a
1816 credential that is not placed in a credential set or placed in a
1817 credential set that is only used by a single entity.
1819 KHMEXP khm_int32 KHMAPI
1820 kcdb_cred_set_identity(khm_handle vcred,
1823 /*! \brief Get the serial number for the credential.
1825 Each credential gets assigned a serial number at the time it is
1826 created. This will stay with the credential for its lifetime.
1828 \param[out] pserial Receives the serial number. Cannot be NULL.
1830 KHMEXP khm_int32 KHMAPI
1831 kcdb_cred_get_serial(khm_handle cred,
1832 khm_ui_8 * pserial);
1834 /*! \brief Get the type of the credential.
1836 The returned type is a credential type. Doh.
1838 \param[out] type Receives the type. Cannot be NULL.
1840 KHMEXP khm_int32 KHMAPI
1841 kcdb_cred_get_type(khm_handle cred,
1844 /*! \brief Retrieve flags from a credential
1846 The flags returned will be place in the location pointed to by \a
1847 flags. Note that the specified credential must be an active
1848 credential for the operation to succeed. This means the
1849 ::KCDB_CRED_FLAG_DELETED will never be retured by this function.
1851 KHMEXP khm_int32 KHMAPI
1852 kcdb_cred_get_flags(khm_handle cred,
1855 /*! \brief Set the flags of a credential
1857 The flags specified in the \a mask parameter will be set to the
1858 values specified in the \a flags parameter. The flags that are
1859 not included in \a mask will not be modified.
1861 This function can not be used to set the ::KCDB_CRED_FLAG_DELETED
1862 flag. If this bit is specified in either \a flags or \a mask, it
1865 \see ::KCDB_CRED_FLAGMASK_ALL
1867 KHMEXP khm_int32 KHMAPI
1868 kcdb_cred_set_flags(khm_handle cred,
1872 /*! \brief Hold a reference to a credential.
1874 Use kcdb_cred_release() to release the reference.
1876 \see kcdb_cred_release()
1878 KHMEXP khm_int32 KHMAPI
1879 kcdb_cred_hold(khm_handle cred);
1881 /*! \brief Release a held reference to a credential.
1883 KHMEXP khm_int32 KHMAPI
1884 kcdb_cred_release(khm_handle cred);
1886 /*! \brief Delete a credential.
1888 The credential will be marked for deletion and will continue to
1889 exist until all held references are released. If the credential
1890 is bound to a credential set or the root credential store, it will
1891 be removed from the respective container.
1893 KHMEXP khm_int32 KHMAPI
1894 kcdb_cred_delete(khm_handle cred);
1896 /*! \brief Compare an attribute of two credentials by name.
1898 \return The return value is dependent on the type of the attribute
1899 and indicate a weak ordering of the attribute values of the two
1900 credentials. If one or both credentials do not contain the
1901 attribute, the return value is 0, which signifies that no ordering
1904 KHMEXP khm_int32 KHMAPI
1905 kcdb_creds_comp_attrib(khm_handle cred1,
1909 /*! \brief Compare an attribute of two credentials by attribute id.
1911 \return The return value is dependent on the type of the attribute
1912 and indicate a weak ordering of the attribute values of the two
1913 credentials. If one or both credentials do not contain the
1914 attribute, the return value is 0, which signifies that no ordering
1917 KHMEXP khm_int32 KHMAPI
1918 kcdb_creds_comp_attr(khm_handle cred1,
1922 /*! \brief Compare two credentials for equivalence
1924 \return Non-zero if the two credentials are equal. Zero otherwise.
1925 \note Two credentials are considered equal if all the following hold:
1926 - Both refer to the same identity.
1927 - Both have the same name.
1928 - Both have the same type.
1930 KHMEXP khm_int32 KHMAPI
1931 kcdb_creds_is_equal(khm_handle cred1,
1937 /********************************************************************/
1939 /*! \defgroup kcdb_type Credential attribute types
1943 /*! \brief Convert a field to a string
1945 Provides a string representation of a field in a credential. The
1946 data buffer can be assumed to be valid.
1948 On entry, \a s_buf can be NULL if only the required size of the
1949 buffer is to be returned. \a pcb_s_buf should be non-NULL and
1950 should point to a valid variable of type ::khm_size that will, on
1951 entry, contain the size of the buffer pointed to by \a s_buf if \a
1952 s_buf is not \a NULL, and on exit will contain the number of bytes
1953 consumed in \a s_buf, or the required size of the buffer if \a
1954 s_buf was NULL or the size of the buffer was insufficient.
1956 The implementation should verify the parameters that are passed in
1959 The data pointed to by \a data should not be modified in any way.
1961 \param[in] data Valid pointer to a block of data
1963 \param[in] cb_data Number of bytes in data block pointed to by \a
1966 \param[out] s_buf Buffer to receive the string representation of
1967 data. If the data type flags has KCDB_TYPE_FLAG_CB_AUTO, then
1968 this parameter could be set to KCDB_CBSIZE_AUTO. In this
1969 case, the function should compute the size of the input buffer
1970 assuming that the input buffer is valid.
1972 \param[in,out] pcb_s_buf On entry, contains the size of the buffer
1973 pointed to by \a s_buf, and on exit, contains the number of
1974 bytes used by the string representation of the data including
1977 \param[in] flags Flags for formatting the string
1979 \retval KHM_ERROR_SUCCESS The string representation of the data
1980 field was successfully copied to \a s_buf and the size of the
1981 buffer used was copied to \a pcb_s_buf.
1983 \retval KHM_ERROR_INVALID_PARAM One or more parameters were invalid
1985 \retval KHM_ERROR_TOO_LONG Either \a s_buf was \a NULL or the size
1986 indicated by \a pcb_s_buf was too small to contain the string
1987 representation of the value. The required size of the buffer
1990 \note This documents the expected behavior of this prototype function
1995 (KHMAPI *kcdb_dtf_toString)(const void * data,
1998 khm_size * pcb_s_buf,
2001 /*! \brief Verifies whetehr the given buffer contains valid data
2003 The function should examine the buffer and the size of the buffer
2004 and determine whether or not the buffer contains valid data for
2007 The data field pointed to by \a data should not be modified in any
2010 \param[in] data A pointer to a data buffer
2012 \param[in] cb_data The number of bytes in the data buffer. If the
2013 data type flags has KCDB_TYPE_FLAG_CB_AUTO, then this
2014 parameter could be set to KCDB_CBSIZE_AUTO. In this case, the
2015 function should compute the size of the input buffer assuming
2016 that the input buffer is valid.
2018 \return TRUE if the data is valid, FALSE otherwise.
2020 \note This documents the expected behavior of this prototype function
2025 (KHMAPI *kcdb_dtf_isValid)(const void * data,
2028 /*! \brief Compare two fields
2030 Compare the two data fields and return a value indicating their
2031 relative ordering. The return value follows the same
2032 specification as strcmp().
2034 Both data buffers that are passed in can be assumed to be valid.
2036 None of the data buffers should be modified in any way.
2038 \param[in] data_l Valid pointer to first data buffer
2040 \param[in] cb_data_l Number of bytes in \a data_l. If the data
2041 type flags has KCDB_TYPE_FLAG_CB_AUTO, then this parameter
2042 could be set to KCDB_CBSIZE_AUTO. In this case, the function
2043 should compute the size of the input buffer assuming that the
2044 input buffer is valid.
2046 \param[in] data_r Valid pointer to second data buffer
2048 \param[in] cb_data_r Number of bytes in \a data_r. If the data
2049 type flags has KCDB_TYPE_FLAG_CB_AUTO, then this parameter
2050 could be set to KCDB_CBSIZE_AUTO. In this case, the function
2051 should compute the size of the input buffer assuming that the
2052 input buffer is valid.
2054 \return The return value should be
2055 - Less than zero if \a data_l < \a data_r
2056 - Equal to zero if \a data_l == \a data_r or if this data type can not be compared
2057 - Greater than zero if \a data_l > \a data_r
2059 \note This documents the expected behavior of this prototype function
2064 (KHMAPI *kcdb_dtf_comp)(const void * data_l,
2066 const void * data_r,
2067 khm_size cb_data_r);
2069 /*! \brief Duplicate a data field
2071 Duplicates a data field. The buffer pointed to by \a data_src
2072 contains a valid field. The function should copy the field with
2073 appropriate adjustments to \a data_dst.
2075 The \a data_dst parameter can be NULL if only the required size of
2076 the buffer is needed. In this case, teh function should set \a
2077 pcb_data_dst to the number of bytes required and then return
2080 \param[in] data_src Pointer to a valid data buffer
2082 \param[in] cb_data_src Number of bytes in \a data_src. If the data
2083 type flags has KCDB_TYPE_FLAG_CB_AUTO, then this parameter
2084 could be set to KCDB_CBSIZE_AUTO. In this case, the function
2085 should compute the size of the input buffer assuming that the
2086 input buffer is valid.
2088 \param[out] data_dst Poitner to destination buffer. Could be NULL
2089 if only the required size of the destination buffer is to be
2092 \param[in,out] pcb_data_dst On entry specifies the number of bytes
2093 in \a data_dst, and on exit should contain the number of bytes
2096 \retval KHM_ERROR_SUCCESS The data was successfully copied. The
2097 number of bytes copied is in \a pcb_data_dst
2099 \retval KHM_ERROR_INVALID_PARAM One or more parameters is incorrect.
2101 \retval KHM_ERROR_TOO_LONG Either \a data_dst was NULL or the size
2102 of the buffer was insufficient. The required size is in \a
2105 \note This documents the expected behavior of this prototype function
2110 (KHMAPI *kcdb_dtf_dup)(const void * data_src,
2111 khm_size cb_data_src,
2113 khm_size * pcb_data_dst);
2115 /*! \brief A data type descriptor.
2117 Handles basic operation for a specific data type.
2119 \see \ref cred_data_types
2121 typedef struct tag_kcdb_type {
2129 kcdb_dtf_toString toString;
2130 /*!< Provides a string representation for a value. */
2132 kcdb_dtf_isValid isValid;
2133 /*!< Returns true of the value is valid for this data type */
2136 /*!< Compare two values and return \a strcmp style return value */
2139 /*!< Duplicate a value into a secondary buffer */
2142 /*! \name Flags for kcdb_type::toString
2144 /*! \brief Specify that the short form of the string representation should be returned.
2146 Flags for #kcdb_type::toString. The flag specifies how long the
2147 string representation should be. The specific length of a short
2148 or long description is not restricted and it is up to the
2149 implementation to choose how to interpret the flags.
2151 Usually, KCDB_TS_SHORT is specified when the amount of space that
2152 is available to display the string is very restricted. It may be
2153 the case that the string is truncated to facilitate displaying in
2154 a constrainted space.
2156 #define KCDB_TS_SHORT 1
2158 /*! \brief Specify that the long form of the string representation should be returned
2160 Flags for #kcdb_type::toString. The flag specifies how long the
2161 string representation should be. The specific length of a short
2162 or long description is not restricted and it is up to the
2163 implementation to choose how to interpret the flags.
2166 #define KCDB_TS_LONG 0
2169 /*! \brief The maximum number of bytes allowed for a value of any type */
2170 #define KCDB_TYPE_MAXCB 16384
2172 /*! \name Flags for kcdb_type
2175 /*! \brief The type supports KCDB_CBSIZE_AUTO.
2177 Used for types where the size of the object can be determined
2178 through context or by the object content. Such as for objects
2179 that have a fixed size or unicode strings that have a terminator.
2181 This implies that ALL the object manipulation callbacks that are
2182 defined in this type definition support the KCDB_CBSIZE_AUTO
2185 #define KCDB_TYPE_FLAG_CB_AUTO 16
2187 /*! \brief The \a cb_min member is valid.
2189 The \a cb_min member defines the minimum number of bytes that an
2190 object of this type will consume.
2192 \note If this flag is used in conjunction with \a
2193 KCDB_TYPE_FLAG_CB_MAX then, \a cb_min must be less than or equal
2196 #define KCDB_TYPE_FLAG_CB_MIN 128
2198 /*! \brief The \a cb_max member is valid.
2200 The \a cb_max member defines the maximum number of bytes that an
2201 object of this type will consume.
2203 \note If this flag is used in conjunction with \a
2204 KCDB_TYPE_FLAG_CB_MIN then, \a cb_min must be less than or
2205 equal to \a cb_max. */
2206 #define KCDB_TYPE_FLAG_CB_MAX 256
2208 /*! \brief Denotes that objects of this type have a fixed size.
2210 If this flags is specified, then the type definition must also
2211 specify cb_min and cb_max, which must both be the same value.
2213 \note Implies \a KCDB_TYPE_FLAG_CB_AUTO, \a KCDB_TYPE_FLAG_CB_MIN
2214 and \a KCDB_TYPE_FLAG_CB_MAX. Pay special attention to the
2215 implication of \a KCDB_TYPE_FLAG_AUTO.
2217 #define KCDB_TYPE_FLAG_CB_FIXED (KCDB_TYPE_FLAG_CB_AUTO|KCDB_TYPE_FLAG_CB_MIN|KCDB_TYPE_FLAG_CB_MAX)
2221 KHMEXP khm_int32 KHMAPI
2222 kcdb_type_get_id(wchar_t *name, khm_int32 * id);
2224 /*! \brief Return the type descriptor for a given type id
2226 \param[out] info Receives a held reference to a type descriptor.
2227 Use kcdb_type_release_info() to release the handle. If the \a
2228 info parameter is NULL, the function returns KHM_ERROR_SUCCESS
2229 if \a id is a valid type id, and returns KHM_ERROR_NOT_FOUND
2232 \see kcdb_type_release_info()
2234 KHMEXP khm_int32 KHMAPI
2235 kcdb_type_get_info(khm_int32 id, kcdb_type ** info);
2237 /*! \brief Release a reference to a type info structure
2239 Releases the reference to the type information obtained with a
2240 prior call to kcdb_type_get_info().
2242 KHMEXP khm_int32 KHMAPI
2243 kcdb_type_release_info(kcdb_type * info);
2245 /*! \brief Get the name of a type
2247 Retrieves the non-localized name of the specified type.
2249 KHMEXP khm_int32 KHMAPI
2250 kcdb_type_get_name(khm_int32 id,
2254 /*! \brief Register a credentials attribute type
2256 The credentials type record pointed to by \a type defines a new
2257 credential attribute type. The \a id member of \a type may be set
2258 to KCDB_TYPE_INVALID to indicate that an attribute ID is to be
2259 generated automatically.
2261 \param[in] type The type descriptor
2262 \param[out] new_id Receives the identifier for the credential attribute type.
2264 KHMEXP khm_int32 KHMAPI
2265 kcdb_type_register(kcdb_type * type,
2266 khm_int32 * new_id);
2268 /*! \brief Unregister a credential attribute type
2270 Removes the registration for the specified credentials attribute
2273 KHMEXP khm_int32 KHMAPI
2274 kcdb_type_unregister(khm_int32 id);
2276 KHMEXP khm_int32 KHMAPI
2277 kcdb_type_get_next_free(khm_int32 * id);
2279 /*! \name Conversion functions
2281 /*! \brief Convert a time_t value to FILETIME
2284 TimetToFileTime( time_t t, LPFILETIME pft );
2286 /*! \brief Convert a time_t interval to a FILETIME interval
2289 TimetToFileTimeInterval(time_t t, LPFILETIME pft);
2291 /*! \brief Convert a FILETIME interval to seconds
2294 FtIntervalToSeconds(LPFILETIME pft);
2296 /*! \brief Convert a FILETIME interval to milliseconds
2299 FtIntervalToMilliseconds(LPFILETIME pft);
2301 /*! \brief Compare two FILETIME values
2303 The return value is similar to the return value of strcmp(), based
2304 on the comparison of the two FILETIME values.
2307 FtCompare(LPFILETIME pft1, LPFILETIME pft2);
2309 /*! \brief Convert a FILETIME to a 64 bit int
2311 KHMEXP khm_int64 KHMAPI FtToInt(LPFILETIME pft);
2313 /*! \brief Convert a 64 bit int to a FILETIME
2315 KHMEXP FILETIME KHMAPI IntToFt(khm_int64 i);
2317 /*! \brief Calculate the difference between two FILETIMEs
2319 Returns the value of ft1 - ft2
2321 KHMEXP FILETIME KHMAPI FtSub(LPFILETIME ft1, LPFILETIME ft2);
2323 /*! \brief Calculate the sum of two FILETIMEs
2325 Return the value of ft1 + ft2
2327 KHMEXP FILETIME KHMAPI FtAdd(LPFILETIME ft1, LPFILETIME ft2);
2329 /*! \brief Convert a FILETIME inverval to a string
2331 KHMEXP khm_int32 KHMAPI
2332 FtIntervalToString(LPFILETIME data,
2336 /*! \brief Parse a string representing an interval into a FILETIME interval
2338 The string is a localized string which should look like the
2342 [number unit] [number unit]...
2345 where \a number is an integer while \a unit is a localized
2346 (possibly abbreviated) unit specification. The value of the
2347 described interval is calculated as the sum of each \a number in
2348 \a units. For example :
2354 would result in an interval specification that's equivalent to 1
2355 hour and 36 minutes. Of course there is no restriction on the
2356 order in which the \a number \a unit specifications are given and
2357 the same unit may be repeated multiple times.
2359 \retval KHM_ERROR_INVALID_PARAM The given string was invalid or had
2360 a token that could not be parsed. It can also mean that \a
2361 pft was NULL or \a str was NULL.
2363 \retval KHM_ERROR_SUCCESS The string was successfully parsed and
2364 the result was placed in \a pft.
2366 KHMEXP khm_int32 KHMAPI
2367 IntervalStringToFt(FILETIME * pft, wchar_t * str);
2369 /*! \brief Return number of milliseconds till next representation change
2371 Returns the number of milliseconds that must elapse away from the
2372 interval specified in pft \a for the representation of pft to change
2373 from whatever it is right now.
2375 Returns 0 if the representation is not expected to change.
2378 FtIntervalMsToRepChange(LPFILETIME pft);
2380 /*! \brief Convert a safe ANSI string to a Unicode string
2382 The resulting string is guaranteed to be NULL terminated and
2383 within the size limit set by \a cbwstr.
2385 If the whole string cannot be converted, \a wstr is set to an
2388 \return the number of characters converted. This is always either
2389 the length of the string \a astr or 0.
2392 AnsiStrToUnicode( wchar_t * wstr, size_t cbwstr, const char * astr);
2394 /*! \brief Convert a Unicode string to ANSI
2396 The resulting string is guaranteed to be NULL terminated and
2397 within the size limit set by \a cbdest.
2399 \return the number of characters converted. This is always either
2400 the length of the string \a src or 0.
2403 UnicodeStrToAnsi( char * dest, size_t cbdest, const wchar_t * src);
2406 /*! \name Standard type identifiers and names
2409 /*! Maximum identifier number */
2410 #define KCDB_TYPE_MAX_ID 255
2412 /*! \brief Invalid type
2414 Used by functions that return a type identifier to indicate that
2415 the returned type identifier is invalid. Also used to indicate
2416 that a type identifier is not available */
2417 #define KCDB_TYPE_INVALID (-1)
2419 /*! \brief All types
2421 Used by filters to indicate that all types are allowed.
2423 #define KCDB_TYPE_ALL KCDB_TYPE_INVALID
2425 #define KCDB_TYPE_VOID 0
2426 #define KCDB_TYPE_STRING 1
2427 #define KCDB_TYPE_DATE 2
2428 #define KCDB_TYPE_INTERVAL 3
2429 #define KCDB_TYPE_INT32 4
2430 #define KCDB_TYPE_INT64 5
2431 #define KCDB_TYPE_DATA 6
2433 #define KCDB_TYPENAME_VOID L"Void"
2434 #define KCDB_TYPENAME_STRING L"String"
2435 #define KCDB_TYPENAME_DATE L"Date"
2436 #define KCDB_TYPENAME_INTERVAL L"Interval"
2437 #define KCDB_TYPENAME_INT32 L"Int32"
2438 #define KCDB_TYPENAME_INT64 L"Int64"
2439 #define KCDB_TYPENAME_DATA L"Data"
2443 /********************************************************************/
2445 /*! \defgroup kcdb_credattr Credential attributes */
2448 /*! \brief Prototype callback function for computed data types.
2450 If the flags for a particular attribute specifies that the value
2451 is computed, then a callback function should be specified. The
2452 callback function will be called with a handle to a credential
2453 along with the attribute ID for the requested attribute. The
2454 function should place the computed value in \a buffer. The size
2455 of the buffer in bytes is specifed in \a cbsize. However, if \a
2456 buffer is \a NULL, then the required buffer size should be placed
2460 (KHMAPI *kcdb_attrib_compute_cb)(khm_handle cred,
2465 /*! \brief Credential attribute descriptor
2467 \see kcdb_attrib_register()
2469 typedef struct tag_kcdb_attrib {
2470 wchar_t * name; /*!< Name. (Not localized,
2472 khm_int32 id; /*!< Identifier. When registering,
2474 ::KCDB_ATTR_INVALID if a unique
2475 identifier is to be generated. */
2476 khm_int32 alt_id; /*!< Alternate identifier. If the \a
2478 ::KCDB_ATTR_FLAG_ALTVIEW, then this
2479 field should specify the identifier
2480 of the canonical attribute from
2481 which this attribute is derived. */
2482 khm_int32 flags; /*!< Flags. Combination of \ref
2483 kcdb_credattr_flags "attribute
2486 khm_int32 type; /*!< Type of the attribute. Must be valid. */
2488 wchar_t * short_desc; /*!< Short description. (Localized,
2491 wchar_t * long_desc; /*!< Long description. (Localized,
2494 kcdb_attrib_compute_cb compute_cb;
2495 /*!< Callback. Required if \a flags
2496 specify ::KCDB_ATTR_FLAG_COMPUTED. */
2498 khm_size compute_min_cbsize;
2499 /*!< Minimum number of bytes required
2500 to store this attribute. Required
2501 if ::KCDB_ATTR_FLAG_COMPUTED is
2503 khm_size compute_max_cbsize;
2504 /*!< Maximum number of bytes required
2505 to store this attribute. Required
2506 if ::KCDB_ATTR_FLAG_COMPUTED is
2510 /*! \brief Retrieve the ID of a named attribute */
2511 KHMEXP khm_int32 KHMAPI
2512 kcdb_attrib_get_id(wchar_t *name,
2515 /*! \brief Register an attribute
2517 \param[out] new_id Receives the ID of the newly registered
2518 attribute. If the \a id member of the ::kcdb_attrib object is
2519 set to KCDB_ATTR_INVALID, then a unique ID is generated. */
2520 KHMEXP khm_int32 KHMAPI
2521 kcdb_attrib_register(kcdb_attrib * attrib,
2522 khm_int32 * new_id);
2524 /*! \brief Retrieve the attribute descriptor for an attribute
2526 The descriptor that is returned must be released through a call to
2527 kcdb_attrib_release_info()
2529 If only the validity of the attribute identifier needs to be
2530 checked, you can pass in NULL for \a attrib. In this case, if the
2531 identifier is valid, then the funciton will return
2532 KHM_ERROR_SUCCESS, otherwise it will return KHM_ERROR_NOT_FOUND.
2534 \see kcdb_attrib_release_info()
2536 KHMEXP khm_int32 KHMAPI
2537 kcdb_attrib_get_info(khm_int32 id,
2538 kcdb_attrib ** attrib);
2540 /*! \brief Release an attribute descriptor
2542 \see kcdb_attrib_get_info()
2544 KHMEXP khm_int32 KHMAPI
2545 kcdb_attrib_release_info(kcdb_attrib * attrib);
2547 /*! \brief Unregister an attribute
2549 Once an attribute ID has been unregistered, it may be reclaimed by
2550 a subsequent call to kcdb_attrib_register().
2552 KHMEXP khm_int32 KHMAPI
2553 kcdb_attrib_unregister(khm_int32 id);
2555 /*! \brief Retrieve the description of an attribute
2557 \param[in] flags Specify \a KCDB_TS_SHORT to retrieve the short description. */
2558 KHMEXP khm_int32 KHMAPI
2559 kcdb_attrib_describe(khm_int32 id,
2564 /*! \brief Count attributes
2566 Counts the number of attributes that match the given criteria.
2567 The criteria is specified against the flags of the attribute. An
2568 attribute is a match if its flags satisfy the condition below:
2571 (attrib.flags & and_flags) == (eq_flags & and_flags)
2574 The number of attributes that match are returned in \a pcount.
2576 KHMEXP khm_int32 KHMAPI
2577 kcdb_attrib_get_count(khm_int32 and_flags,
2581 /*! \brief List attribute identifiers
2583 Lists the identifiers of the attributes that match the given
2584 criteria. The criteria is specified against the flags of the
2585 attribute. An attribute is a match if the following condition is
2589 (attrib.flags & and_flags) == (eq_flags & and_flags)
2592 The list of attributes found are copied to the \a khm_int32 array
2593 specified in \a plist. The number of elements available in the
2594 buffer \a plist is specified in \a pcsize. On exit, \a pcsize
2595 will hold the actual number of attribute identifiers copied to the
2598 \param[in] and_flags See above
2599 \param[in] eq_flags See above
2600 \param[in] plist A khm_int32 array
2601 \param[in,out] pcsize On entry, holds the number of elements
2602 available in the array pointed to by \a plist. On exit, holds
2603 the number of elements copied to the array.
2605 \retval KHM_ERROR_SUCCESS The list of attribute identifiers have
2607 \retval KHM_ERROR_TOO_LONG The list was too long to fit in the
2608 supplied buffer. As many elements as possible have been
2609 copied to the \a plist array and the required number of
2610 elements has been written to \a pcsize.
2612 \note The \a pcsize parameter specifies the number of khm_int32
2613 elements in the array and not the number of bytes in the
2614 array. This is different from the usual size parameters used
2615 in the NetIDMgr API.
2617 KHMEXP khm_int32 KHMAPI
2618 kcdb_attrib_get_ids(khm_int32 and_flags,
2623 /*! \defgroup kcdb_credattr_flags Attribute flags */
2625 /*! \brief The attribute is required */
2626 #define KCDB_ATTR_FLAG_REQUIRED 0x00000008
2628 /*! \brief The attribute is computed.
2630 If this flag is set, the \a compute_cb, \a compute_min_cbsize and
2631 \a compute_max_cbsize members of the ::kcdb_attrib attribute
2632 descriptor must be assigned valid values.
2634 #define KCDB_ATTR_FLAG_COMPUTED 0x00000010
2636 /*! \brief System attribute.
2638 This cannot be specified for a custom attribute. Implies that the
2639 value of the attribute is given by the credentials database
2642 #define KCDB_ATTR_FLAG_SYSTEM 0x00000020
2646 The attribute is not meant to be displayed to the user. Setting
2647 this flag prevents this attribute from being listed in the list of
2648 available data fields in the UI.
2650 #define KCDB_ATTR_FLAG_HIDDEN 0x00000040
2654 The attribute is a property. The main difference between regular
2655 attributes and properties are that properties are not allocated
2656 off the credentials record. Hence, a property can not be used as
2657 a credentials field. Other objects such as identities can hold
2658 property sets. A property set can hold both regular attributes as
2661 #define KCDB_ATTR_FLAG_PROPERTY 0x00000080
2665 A volatile property is one whose value changes often, such as
2666 ::KCDB_ATTR_TIMELEFT. Some controls will make use of additional
2667 logic to deal with such values, or not display them at all.
2669 #define KCDB_ATTR_FLAG_VOLATILE 0x00000100
2671 /*! \brief Alternate view
2673 The attribute is actually an alternate representation of another
2674 attribute. The Canonical attribute name is specified in \a
2677 Sometimes a certain attribute may need to be represented in
2678 different ways. You can register multiple attributes for each
2679 view. However, you should also provide a canonical attribute for
2680 whenever the canonical set of attributes of the credential is
2683 #define KCDB_ATTR_FLAG_ALTVIEW 0x00000200
2685 /*! \brief Transient attribute
2687 A transient attribute is one whose absence is meaningful. When
2688 updating one record using another, if a transient attribute is
2689 absent in the source but present in the destination, then the
2690 attribute is removed from the destination.
2692 #define KCDB_ATTR_FLAG_TRANSIENT 0x00000400
2696 /*! \defgroup kcdb_credattr_idnames Standard attribute IDs and names */
2699 /*! \name Attribute related constants */
2701 /*! \brief Maximum valid attribute ID */
2702 #define KCDB_ATTR_MAX_ID 255
2704 /*! \brief Minimum valid property ID */
2705 #define KCDB_ATTR_MIN_PROP_ID 4096
2707 /*! \brief Maximum number of properties */
2708 #define KCDB_ATTR_MAX_PROPS 128
2710 /*! \brief Maximum valid property ID */
2711 #define KCDB_ATTR_MAX_PROP_ID (KCDB_ATTR_MIN_PROP_ID + KCDB_ATTR_MAX_PROPS - 1)
2713 /*! \brief Invalid ID */
2714 #define KCDB_ATTR_INVALID (-1)
2716 /*! \brief First custom attribute ID */
2717 #define KCDB_ATTRID_USER 20
2721 /*!\name Attribute identifiers */
2723 /*! \brief Name of the credential
2726 - \b Flags: REQUIRED, COMPUTED, SYSTEM
2728 #define KCDB_ATTR_NAME 0
2730 /*! \brief The identity handle for the credential
2733 - \b Flags: REQUIRED, COMPUTED, SYSTEM, HIDDEN
2735 \note The handle returned in by specifying this attribute to
2736 kcdb_cred_get_attr() or kcdb_cred_get_attrib() is not held.
2737 While the identity is implicitly held for the duration that
2738 the credential is held, it is not recommended to obtain a
2739 handle to the identity using this method. Use
2740 kcdb_cred_get_identity() instead.
2742 #define KCDB_ATTR_ID 1
2744 /*! \brief The name of the identity
2747 - \b Flags: REQUIRED, COMPUTED, SYSTEM
2749 #define KCDB_ATTR_ID_NAME 2
2751 /*! \brief The type of the credential
2754 - \b Flags: REQUIRED, COMPUTED, SYSTEM, HIDDEN
2756 #define KCDB_ATTR_TYPE 3
2758 /*! \brief Type name for the credential
2761 - \b Flags: REQUIRED, COMPUTED, SYSTEM
2763 #define KCDB_ATTR_TYPE_NAME 4
2765 /*! \brief Name of the parent credential
2770 #define KCDB_ATTR_PARENT_NAME 5
2777 #define KCDB_ATTR_ISSUE 6
2779 /*! \brief Expires on
2784 #define KCDB_ATTR_EXPIRE 7
2786 /*! \brief Renewable period expires on
2791 #define KCDB_ATTR_RENEW_EXPIRE 8
2793 /*! \brief Time left till expiration
2796 - \b Flags: SYSTEM, COMPUTED, VOLATILE
2798 #define KCDB_ATTR_TIMELEFT 9
2800 #define KCDB_ATTR_RENEW_TIMELEFT 10
2802 /*! \brief Location of the credential
2807 #define KCDB_ATTR_LOCATION 11
2809 /*! \brief Lifetime of the credential
2814 #define KCDB_ATTR_LIFETIME 12
2816 #define KCDB_ATTR_RENEW_LIFETIME 13
2818 /*! \brief Flags for the credential
2821 - \b Flags: REQUIRED, COMPUTED, SYSTEM, HIDDEN
2823 #define KCDB_ATTR_FLAGS 14
2827 /*!\name Attribute names */
2830 #define KCDB_ATTRNAME_NAME L"Name"
2831 #define KCDB_ATTRNAME_ID L"Identity"
2832 #define KCDB_ATTRNAME_ID_NAME L"IdentityName"
2833 #define KCDB_ATTRNAME_TYPE L"TypeId"
2834 #define KCDB_ATTRNAME_TYPE_NAME L"TypeName"
2835 #define KCDB_ATTRNAME_FLAGS L"Flags"
2837 #define KCDB_ATTRNAME_PARENT_NAME L"Parent"
2838 #define KCDB_ATTRNAME_ISSUE L"Issued"
2839 #define KCDB_ATTRNAME_EXPIRE L"Expires"
2840 #define KCDB_ATTRNAME_RENEW_EXPIRE L"RenewExpires"
2841 #define KCDB_ATTRNAME_TIMELEFT L"TimeLeft"
2842 #define KCDB_ATTRNAME_RENEW_TIMELEFT L"RenewTimeLeft"
2843 #define KCDB_ATTRNAME_LOCATION L"Location"
2844 #define KCDB_ATTRNAME_LIFETIME L"Lifetime"
2845 #define KCDB_ATTRNAME_RENEW_LIFETIME L"RenewLifetime"
2853 /*****************************************************************************/
2855 /*! \defgroup kcdb_credtype Credential types */
2858 /*! \brief Credential type descriptor */
2859 typedef struct tag_kcdb_credtype {
2860 wchar_t * name; /*!< name (less than KCDB_MAXCB_NAME bytes) */
2862 wchar_t * short_desc; /*!< short localized description (less
2863 than KCDB_MAXCB_SHORT_DESC bytes) */
2864 wchar_t * long_desc; /*!< long localized descriptionn (less
2865 than KCDB_MAXCB_LONG_DESC bytes) */
2866 khm_handle sub; /*!< Subscription for credentials type
2867 hander. This should be a valid
2868 subscription constructed through a
2869 call to kmq_create_subscription()
2870 and must handle KMSG_CRED messages
2871 that are marked as being sent to
2872 type specific subscriptions.
2874 The subscription will be
2875 automatically deleted with a call to
2876 kmq_delete_subscription() when the
2877 credentials type is unregistered.*/
2879 kcdb_cred_comp_func is_equal; /*!< Used to as an additional clause
2880 when comparing two credentials for
2881 equality. The function this is
2882 actually a comparison function, it
2883 should return zero if the two
2884 credentials are equal and non-zero
2885 if they are not. The addtional \a
2886 rock parameter is always zero.
2888 It can be assumed that the identity,
2889 name and credentials have already
2890 been found to be equal among the
2891 credentials and the credential type
2892 is the type that is being
2900 /*! \brief Maximum value of a credential type identifier
2902 Credential type identifiers are assigned serially unless the
2903 process registering the credential type sets a specific identity.
2904 The maximum identifier number places a hard limit to the number of
2905 credential types that can be registered at one time, which is
2906 KCDB_CREDTYPE_MAX_ID + 1.
2908 #define KCDB_CREDTYPE_MAX_ID 31
2910 /*! \brief Specify all credential types
2912 This value is used by functions which filter credentials based on
2913 credential types. Specifying this value tells the filter to
2914 accept all credential types.
2916 #define KCDB_CREDTYPE_ALL (-1)
2918 /*! \brief Automatically determine a credential type identifier
2920 Used with kcdb_credtype_register() to specify that the credential
2921 type identifier should be automatically determined to avoid
2924 #define KCDB_CREDTYPE_AUTO (-2)
2926 /*! \brief An invalid credential type
2928 Even though any non positive credential type ID is invalid
2929 anywhere where a specific credential type ID is required, this
2930 value is provided for explicit indication that the credential type
2931 is invalid. Also it makes code more readable to have a constant
2932 that shouts out INVALID.
2935 #define KCDB_CREDTYPE_INVALID (-3)
2937 /*! \brief Macro predicate for testing whether a credtype is valid
2939 Returns TRUE if the given credtype is valid. This is a safe
2942 #define KCDB_CREDTYPE_IS_VALID(t) ((t) >= 0)
2944 /*! \brief Register a credentials type.
2946 The information given in the \a type parameter is used to register
2947 a new credential type. Note that the \a name member of the \a
2948 type should be unique among all credential types.
2950 You can specify ::KCDB_CREDTYPE_AUTO as the \a id member of \a
2951 type to let kcdb_credtype_register() determine a suitable
2952 credential type identifier. You can subsequently call
2953 kcdb_credtype_get_id() to retrieve the generated id or pass a
2954 valid pointer to a khm_int32 type variable as \a new_id.
2956 \param[in] type Credential type descriptor
2958 \param[out] new_id The credential type identifier that this type
2961 \retval KHM_ERROR_SUCCESS The credential type was successfully registered.
2963 \retval KHM_ERROR_INVALID_PARAM One or more of the parameters were invalid
2965 \retval KHM_ERROR_TOO_LONG One or more of the string fields in \a
2966 type exceeded the character limit for that field.
2968 \retval KHM_ERROR_NO_RESOURCES When autogenerating credential type
2969 identifiers, this value indicates that the maximum number of
2970 credential types have been registered. No more registrations
2971 can be accepted unless some credentials type is unregisred.
2973 \retval KHM_ERROR_DUPLICATE The \a name or \a id that was
2974 specified is already in use.
2976 KHMEXP khm_int32 KHMAPI
2977 kcdb_credtype_register(kcdb_credtype * type,
2978 khm_int32 * new_id);
2980 /*! \brief Return a held reference to a \a kcdb_credtype object describing the credential type.
2982 The reference points to a static internal object of type \a
2983 kcdb_credtype. Use the kcdb_credtype_release_info() function to
2984 release the reference.
2986 Also, the structure passed in as the \a type argument to
2987 kcdb_credtype_register() is not valid as a credential type
2988 descriptor. Use kcdb_credtype_get_info() to obtain the actual
2989 credential type descriptor.
2991 \param[in] id Credentials type identifier.
2993 \param[out] type Receives the credentials descriptor handle. If
2994 \a type is NULL, then no handle is returned. However, the
2995 function will still return \a KHM_ERROR_SUCCESS if the \a id
2996 parameter passed in is a valid credentials type identifier.
2998 \see kcdb_credtype_release_info()
2999 \see kcdb_credtype_register()
3001 KHMEXP khm_int32 KHMAPI
3002 kcdb_credtype_get_info(khm_int32 id,
3003 kcdb_credtype ** type);
3005 /*! \brief Release a reference to a \a kcdb_credtype object
3007 Undoes the hold obtained on a \a kcdb_credtype object from a
3008 previous call to kcdb_credtype_get_info().
3010 \see kcdb_credtype_get_info()
3012 KHMEXP khm_int32 KHMAPI
3013 kcdb_credtype_release_info(kcdb_credtype * type);
3015 /*! \brief Unregister a credentials type
3017 Undoes the registration performed by kcdb_credtype_register().
3019 This should only be done when the credentials provider is being
3022 KHMEXP khm_int32 KHMAPI
3023 kcdb_credtype_unregister(khm_int32 id);
3025 /*! \brief Retrieve the name of a credentials type
3027 Given a credentials type identifier, retrieves the name. The name
3028 is not localized and serves as a persistent identifier of the
3031 \param[out] buf The buffer to receive the name. Could be \a NULL
3032 if only the length of the buffer is required.
3034 \param[in,out] cbbuf On entry, specifies the size of the buffer
3035 pointed to by \a buf if \a buf is not NULL. On exit, contains
3036 the number of bytes copied to \a buf or the required size of
3039 \retval KHM_ERROR_SUCCESS The call succeeded.
3041 \retval KHM_ERROR_TOO_LONG Either \a buf was NULL or the supplied
3042 buffer was not large enough. The required size is in \a cbbuf.
3044 \retval KHM_ERROR_INVALID_PARAM Invalid parameter.
3046 KHMEXP khm_int32 KHMAPI
3047 kcdb_credtype_get_name(khm_int32 id,
3051 /*! \brief Retrieve the type specific subscription for a type
3053 Given a credentials type, this function returns the credentials
3054 type specific subcription. It may return NULL if the subscription
3057 KHMEXP khm_handle KHMAPI
3058 kcdb_credtype_get_sub(khm_int32 id);
3060 /*! \brief Get the description of a credentials type
3062 Unlike the name of a credential type, the description is localized.
3064 \param[in] id Credentials type identifier
3066 \param[out] buf Receives the description. Can bet set to NULL if
3067 only the size of the buffer is required.
3069 \param[in,out] cbbuf On entry, specifies the size of the buffer
3070 pointed to by \a buf. On exit, specifies the required size of
3071 the buffer or the number of bytes copied, depending on whether
3072 the call succeeded or not.
3074 \param[in] flags Specify ::KCDB_TS_SHORT if the short version of
3075 the description is desired if there is more than one.
3077 \retval KHM_ERROR_SUCCESS The call succeeded
3078 \retval KHM_ERROR_TOO_LONG Either \a buf was NULL or the supplied buffer was insufficient. The required size is specified in \a cbbuf.
3079 \retval KHM_ERROR_INVALID_PARAM One or more parameters were invalid.
3081 KHMEXP khm_int32 KHMAPI
3082 kcdb_credtype_describe(khm_int32 id,
3087 /*! \brief Look up the identifier of a credentials type by name
3089 Given a name, looks up the identifier.
3091 \param[in] name Name of the credentials type
3092 \param[out] id Receives the identifier if the call succeeds
3095 KHMEXP khm_int32 KHMAPI
3096 kcdb_credtype_get_id(wchar_t * name,
3101 /*********************************************************************/
3103 /*! \defgroup kcdb_buf Generic access to buffer
3105 Currently, credentials and identities both hold record data types.
3106 This set of API's allow an application to access fields in the
3107 records using a single interface. Note that credentials only
3108 accept regular attributes while identities can hold both
3109 attributes and properties.
3111 Handles to credentials and identities are implicitly also handles
3112 to records. Thus they can be directly used as such.
3116 /*! \brief Get an attribute from a record by attribute id.
3118 \param[in] buffer The buffer that is to receive the attribute
3119 value. Set this to NULL if only the required buffer size is
3122 \param[in,out] cbbuf The number of bytes available in \a buffer.
3123 If \a buffer is not sufficient, returns KHM_ERROR_TOO_LONG and
3124 sets this to the required buffer size.
3126 \param[out] attr_type Receives the data type of the attribute.
3127 Set this to NULL if the type is not required.
3129 \note Set both \a buffer and \a cbbuf to NULL if only the
3130 existence of the attribute is to be checked. If the attribute
3131 exists in this record then the function will return
3132 KHM_ERROR_SUCCESS, otherwise it returns KHM_ERROR_NOT_FOUND.
3134 KHMEXP khm_int32 KHMAPI
3135 kcdb_buf_get_attr(khm_handle record,
3137 khm_int32 * attr_type,
3139 khm_size * pcb_buf);
3141 /*! \brief Get an attribute from a record by name.
3143 \param[in] buffer The buffer that is to receive the attribute
3144 value. Set this to NULL if only the required buffer size is
3147 \param[in,out] cbbuf The number of bytes available in \a buffer.
3148 If \a buffer is not sufficient, returns KHM_ERROR_TOO_LONG and
3149 sets this to the required buffer size.
3151 \note Set both \a buffer and \a cbbuf to NULL if only the
3152 existence of the attribute is to be checked. If the attribute
3153 exists in this record then the function will return
3154 KHM_ERROR_SUCCESS, otherwise it returns KHM_ERROR_NOT_FOUND.
3156 KHMEXP khm_int32 KHMAPI
3157 kcdb_buf_get_attrib(khm_handle record,
3158 wchar_t * attr_name,
3159 khm_int32 * attr_type,
3161 khm_size * pcb_buf);
3163 /*! \brief Get the string representation of a record attribute.
3165 A shortcut function which generates the string representation of a
3166 record attribute directly.
3168 \param[in] record A handle to a record
3170 \param[in] attr_id The attribute to retrieve
3172 \param[out] buffer A pointer to a string buffer which receives the
3173 string form of the attribute. Set this to NULL if you only
3174 want to determine the size of the required buffer.
3176 \param[in,out] pcbbuf A pointer to a #khm_int32 that, on entry,
3177 holds the size of the buffer pointed to by \a buffer, and on
3178 exit, receives the actual number of bytes that were copied.
3180 \param[in] flags Flags for the string conversion. Can be set to
3181 one of KCDB_TS_LONG or KCDB_TS_SHORT. The default is
3184 \retval KHM_ERROR_SUCCESS Success
3185 \retval KHM_ERROR_NOT_FOUND The given attribute was either invalid
3186 or was not defined for this record
3187 \retval KHM_ERROR_INVALID_PARAM One or more parameters were invalid
3188 \retval KHM_ERROR_TOO_LONG Either \a buffer was NULL or the
3189 supplied buffer was insufficient
3191 KHMEXP khm_int32 KHMAPI
3192 kcdb_buf_get_attr_string(khm_handle record,
3198 /*! \brief Get the string representation of a record attribute by name.
3200 A shortcut function which generates the string representation of a
3201 record attribute directly.
3203 \param[in] record A handle to a record
3205 \param[in] attrib The name of the attribute to retrieve
3207 \param[out] buffer A pointer to a string buffer which receives the
3208 string form of the attribute. Set this to NULL if you only
3209 want to determine the size of the required buffer.
3211 \param[in,out] pcbbuf A pointer to a #khm_int32 that, on entry,
3212 holds the size of the buffer pointed to by \a buffer, and on
3213 exit, receives the actual number of bytes that were copied.
3215 \param[in] flags Flags for the string conversion. Can be set to
3216 one of KCDB_TS_LONG or KCDB_TS_SHORT. The default is
3219 \see kcdb_cred_get_attr_string()
3221 KHMEXP khm_int32 KHMAPI
3222 kcdb_buf_get_attrib_string(khm_handle record,
3223 wchar_t * attr_name,
3228 /*! \brief Set an attribute in a record by attribute id
3230 \param[in] cbbuf Number of bytes of data in \a buffer. The
3231 individual data type handlers may copy in less than this many
3232 bytes in to the record.
3234 KHMEXP khm_int32 KHMAPI
3235 kcdb_buf_set_attr(khm_handle record,
3240 /*! \brief Set an attribute in a record by name
3242 \param[in] cbbuf Number of bytes of data in \a buffer. The
3243 individual data type handlers may copy in less than this many
3244 bytes in to the record.
3246 KHMEXP khm_int32 KHMAPI
3247 kcdb_buf_set_attrib(khm_handle record,
3248 wchar_t * attr_name,
3252 KHMEXP khm_int32 KHMAPI
3253 kcdb_buf_hold(khm_handle record);
3255 KHMEXP khm_int32 KHMAPI
3256 kcdb_buf_release(khm_handle record);
3260 /********************************************************************/
3262 /* Notification operation constants */
3264 #define KCDB_OP_INSERT 1
3265 #define KCDB_OP_DELETE 2
3266 #define KCDB_OP_MODIFY 3
3267 #define KCDB_OP_ACTIVATE 4
3268 #define KCDB_OP_DEACTIVATE 5
3269 #define KCDB_OP_HIDE 6
3270 #define KCDB_OP_UNHIDE 7
3271 #define KCDB_OP_SETSEARCH 8
3272 #define KCDB_OP_UNSETSEARCH 9
3273 #define KCDB_OP_NEW_DEFAULT 10