Credential sets
[Credential sets and individual credentials]

---

Detailed Description

Data Structures
struct	tag_kcdb_cred_comp_field
	Defines a sort criterion for kcdb_cred_comp_generic(). More...
struct	tag_kcdb_cred_comp_order
	Defines the sort criteria for kcdb_cred_comp_generic(). More...
Defines
#define	KCDB_DELTA_ADD   1
	Credentials were added.
#define	KCDB_DELTA_DEL   2
	Credentials were deleted.
#define	KCDB_DELTA_MODIFY   4
	Credentials were modified.
#define	KCDB_CREDCOLL_FILTER_ROOT   1
	Indicates that the credential to be filtered is from the root store.
#define	KCDB_CREDCOLL_FILTER_SRC   2
	Indicates that the credential to be filtered is from the source credential set.
#define	KCDB_CREDCOLL_FILTER_DEST   4
	Indicates that the credential to be filtered is from the destination credential set.
#define	KCDB_CRED_COMP_INCREASING   0
	Defines the sort order for a field in kcdb_cred_comp_field.
#define	KCDB_CRED_COMP_DECREASING   1
	Defines the sort order for a field in kcdb_cred_comp_field.
#define	KCDB_CRED_COMP_INITIAL_FIRST   2
	Defines the sort order for a field in kcdb_cred_comp_field.
Typedefs
typedef tag_kcdb_cred_comp_field	kcdb_cred_comp_field
	Defines a sort criterion for kcdb_cred_comp_generic().
typedef tag_kcdb_cred_comp_order	kcdb_cred_comp_order
	Defines the sort criteria for kcdb_cred_comp_generic().
Functions
KHMEXP khm_int32 KHMAPI	kcdb_credset_create (khm_handle *result)
	Create a credential set.
KHMEXP khm_int32 KHMAPI	kcdb_credset_delete (khm_handle credset)
	Delete a credential set.
KHMEXP khm_int32 KHMAPI	kcdb_credset_collect (khm_handle cs_dest, khm_handle cs_src, khm_handle identity, khm_int32 type, khm_int32 *delta)
	Collect credentials from a credential set to another credential set.
KHMEXP khm_int32 KHMAPI	kcdb_credset_collect_filtered (khm_handle cs_dest, khm_handle cs_src, kcdb_cred_filter_func filter, void *rock, khm_int32 *delta)
	Collect credentials from one credential set to another using a filter.
KHMEXP khm_int32 KHMAPI	kcdb_credset_flush (khm_handle credset)
	Flush all credentials from a credential set.
KHMEXP khm_int32 KHMAPI	kcdb_credset_extract (khm_handle destcredset, khm_handle sourcecredset, khm_handle identity, khm_int32 type)
	Extract credentials from one credential set to another.
KHMEXP khm_int32 KHMAPI	kcdb_credset_extract_filtered (khm_handle destcredset, khm_handle sourcecredset, kcdb_cred_filter_func filter, void *rock)
	Extract credentials from one credential set to another using a filter.
KHMEXP khm_int32 KHMAPI	kcdb_credset_get_cred (khm_handle credset, khm_int32 idx, khm_handle *cred)
	Retrieve a held reference to a credential in a credential set based on index.
KHMEXP khm_int32 KHMAPI	kcdb_credset_find_filtered (khm_handle credset, khm_int32 idx_start, kcdb_cred_filter_func f, void *rock, khm_handle *cred, khm_int32 *idx)
	Search a credential set for a specific credential.
KHMEXP khm_int32 KHMAPI	kcdb_credset_find_cred (khm_handle credset, khm_handle cred_src, khm_handle *cred_dest)
	Find matching credential.
KHMEXP khm_int32 KHMAPI	kcdb_credset_del_cred (khm_handle credset, khm_int32 idx)
	Delete a credential from a credential set.
KHMEXP khm_int32 KHMAPI	kcdb_credset_del_cred_ref (khm_handle credset, khm_handle cred)
	Delete a credential from a credential set by reference.
KHMEXP khm_int32 KHMAPI	kcdb_credset_add_cred (khm_handle credset, khm_handle cred, khm_int32 idx)
	Add a credential to a credential set.
KHMEXP khm_int32 KHMAPI	kcdb_credset_get_size (khm_handle credset, khm_size *size)
	Get the number of credentials in a credential set.
KHMEXP khm_int32 KHMAPI	kcdb_credset_purge (khm_handle credset)
	Removes credentials that have been marked as deleted from a credential set.
KHMEXP khm_int32 KHMAPI	kcdb_credset_apply (khm_handle credset, kcdb_cred_apply_func f, void *rock)
	Applies a function to all the credentials in a credentials set.
KHMEXP khm_int32 KHMAPI	kcdb_credset_sort (khm_handle credset, kcdb_cred_comp_func comp, void *rock)
	Sort the contents of a credential set.
KHMEXP khm_int32 KHMAPI	kcdb_credset_seal (khm_handle credset)
	Seal a credential set.
KHMEXP khm_int32 KHMAPI	kcdb_credset_unseal (khm_handle credset)
	Unseal a credential set.
KHMEXP khm_int32 KHMAPI	kcdb_cred_comp_generic (khm_handle cred1, khm_handle cred2, void *rock)
	A generic compare function for comparing credentials.

---

Define Documentation

#define KCDB_CRED_COMP_DECREASING   1

Defines the sort order for a field in kcdb_cred_comp_field.

Sorts lexicographically descending by string representation of field.

#define KCDB_CRED_COMP_INCREASING   0

Defines the sort order for a field in kcdb_cred_comp_field.

Sorts lexicographically ascending by string representation of field.

#define KCDB_CRED_COMP_INITIAL_FIRST   2

Defines the sort order for a field in kcdb_cred_comp_field.

Any credentials which have the KCDB_CRED_FLAG_INITIAL will be grouped above any that don't.

If that does not apply, then credentials from the primary credentials type will be sorted before others.

#define KCDB_CREDCOLL_FILTER_DEST   4

Indicates that the credential to be filtered is from the destination credential set.

See also:

kcdb_credset_collect_filtered()

#define KCDB_CREDCOLL_FILTER_ROOT   1

Indicates that the credential to be filtered is from the root store.

See also:

kcdb_credset_collect_filtered()

#define KCDB_CREDCOLL_FILTER_SRC   2

Indicates that the credential to be filtered is from the source credential set.

See also:

kcdb_credset_collect_filtered()

#define KCDB_DELTA_ADD   1

Credentials were added.

See also:

kcdb_credset_collect()

#define KCDB_DELTA_DEL   2

Credentials were deleted.

See also:

kcdb_credset_collect()

#define KCDB_DELTA_MODIFY   4

Credentials were modified.

See also:

kcdb_credset_collect()

---

Typedef Documentation

typedef struct tag_kcdb_cred_comp_field kcdb_cred_comp_field

Defines a sort criterion for kcdb_cred_comp_generic().

See also:

kcdb_cred_comp_generic()

typedef struct tag_kcdb_cred_comp_order kcdb_cred_comp_order

Defines the sort criteria for kcdb_cred_comp_generic().

See also:

kcdb_cred_comp_generic()

---

Function Documentation

KHMEXP khm_int32 KHMAPI kcdb_cred_comp_generic	(	khm_handle	cred1,
		khm_handle	cred2,
		void *	rock
	)

A generic compare function for comparing credentials.

This function can be passed as a parameter to kcdb_credset_sort().

The rock parameter to this function should be a pointer to a kcdb_cred_comp_order object. The fields member of the kcdb_cred_comp_order object should point to an array of kcdb_cred_comp_field objects, each of which specifies the sort order in decreasing order of priority. The number of kcdb_cred_comp_field objects in the array should correspond to the nFields member in the kcdb_cred_comp_order object.

The array of kcdb_cred_comp_field objects define the sort criteria, in order. The attrib member should be a valid attribute ID, while the order member determines whether the sort order is increasing or decreasing. The exact meaning or increasing or decreasing depends on the data type of the attribute.

Parameters:

[in]

rock

a pointer to a kcdb_cred_comp_order object

KHMEXP khm_int32 KHMAPI kcdb_credset_add_cred	(	khm_handle	credset,
		khm_handle	cred,
		khm_int32	idx
	)

Add a credential to a credential set.

The credential is added by reference. In other words, no copy of the credential is made.

Parameters:

[in]

idx

Index of the new credential. This must be a value in the range 0..(previous size of credential set) or -1. If -1 is specifed, then the credential is appended at the end of the set.

Note:

The credential set cannot be sealed.

KHMEXP khm_int32 KHMAPI kcdb_credset_apply	(	khm_handle	credset,
		kcdb_cred_apply_func	f,
		void *	rock
	)

Applies a function to all the credentials in a credentials set.

The given function is called for each credential in a credential set. With each iteration, the function is called with a handle to the credential and the user defined parameter rock. If the function returns anything other than KHM_ERROR_SUCCESS, the processing stops.

Parameters:

[in]	credset	The credential set to apply the function to, or NULL if you want to apply this to the root credential set.
[in]	f	Function to call for each credential
[in]	rock	An opaque parameter which is to be passed to 'f' as the second argument.

Return values:

	KHM_ERROR_SUCCESS	All the credentials were processed.
	KHM_ERROR_EXIT	The supplied function signalled the processing to be aborted.
	KHM_ERROR_INVALID_PARAM	One or more parameters were invalid.

KHMEXP khm_int32 KHMAPI kcdb_credset_collect	(	khm_handle	cs_dest,
		khm_handle	cs_src,
		khm_handle	identity,
		khm_int32	type,
		khm_int32 *	delta
	)

Collect credentials from a credential set to another credential set.

Collecting a subset of credentials from credential set cs_src into credential set cs_dest involves the following steps:

• Select all credentials from cs_src that matches the identity and type specified in the function call and add them to the cs_dest credential set if they are not there already. Note that if neither credential set is not the root credential store, then the credentials will be added by reference, while if it is the root credential store, the credentials will be duplicated, and the copies will be added to cs_dest.

• If a selected credential in cs_src already exists in cs_dest, then update the credential in cs_dest with the credential fields in cs_src. In other words, once a credential is found to exist in both cs_src and cs_dest, all the non-null fields from the credential in cs_src will be copied to the credential in cs_dest. Fields which are null (undefined) in cs_src and are non-null in cs_dest will be left unmodified in cs_dest.

One notable exception is the credentials' flags. All flags in cs_src which are not included in KCDB_CRED_FLAGMASK_ADDITIVE will be copied to the corresponding bits in the flags of cs_dest. However, flags that are included in KCDB_CRED_FLAGMASK_ADDITIVE will be added to the corresponding bits in cs_dest.

(See notes below)

• Remove all credentials from cs_dest that match the identity and type that do not appear in cs_src. (see notes below)

For performance reasons, plugins should use kcdb_credset_collect() to update the root credentials store instead of adding and removing individual credentials from the root store.

Only credentials that are associated with active identities are affected by kcdb_credset_collect().

Parameters:

[in]	cs_dest	A handle to the destination credential set. If this is NULL, then it is assumed to refer to the root credential store.
[in]	cs_src	A handle to the source credential set. If this is NULL, then it is assumed to refer to the root credential store.
[in]	identity	A handle to an identity. Setting this to NULL collects all identities in the credential set.
[in]	type	A credentials type. Setting this to KCDB_CREDTYPE_ALL collects all credential types in the set.
[out]	delta	A bit mask that indicates the modifications that were made to cs_dest as a result of the collect operation. This is a combination of KCDB_DELTA_* values. This parameter can be NULL if the value is not required.

Warning:

If identity and type is set to a wildcard, all credentials in the root store that are not in this credentials set will be deleted.

Note:

Two credentials A and B are considered equal if:

• They refer to the same identity
• Both have the same credential type
• Both have the same name

This is the only supported way of modifying the root credential store.

cs_src and cs_dest can not refer to the same credentials set.

The destination credential set cannot be sealed.

KHMEXP khm_int32 KHMAPI kcdb_credset_collect_filtered	(	khm_handle	cs_dest,
		khm_handle	cs_src,
		kcdb_cred_filter_func	filter,
		void *	rock,
		khm_int32 *	delta
	)

Collect credentials from one credential set to another using a filter.

Similar to kcdb_credset_collect() except instead of selecting credentials by matching against an identity and/or type, a filter function is called. If the filter function returns non-zero for a credential, that credential is selected.

Credentials in the source and destination credential sets are passed into the filter function. Depending on whether the credential is in the source credential set or destination credential set, the flag parameter may have either KCDB_CREDCOLL_FILTER_SRC or KCDB_CREDCOLL_FILTER_DEST bits set. Also, if either one of the credential sets is the root credential store, then additionally KCDB_CREDCOLL_FILTER_ROOT would also be set.

See the kcdb_credset_collect() documentation for explanations of the cs_src, cs_dest and delta parameters which perform identical functions.

Parameters:

[in]	filter	The filter of type kcdb_cred_filter_func
[in]	rock	A custom argument to be passed to the filter function.

See also:

kcdb_credset_collect()

KHMEXP khm_int32 KHMAPI kcdb_credset_create

(

khm_handle *

result

)

Create a credential set.

Credential sets are temporary containers for credentials. These can be used by plug-ins to store credentials while they are being enumerated from an external source. Once all the credentials have been collected into the credential set, the plug-in may call kcdb_credset_collect() to collect the credentials into the root credential store.

The user interface will only display credentials that are in the root credential store. No notifications are generated for changes to a non-root credential set.

Use kcdb_credset_delete() to delete the credential set once it is created.

See also:

kcdb_credset_delete()

kcdb_credset_collect()

KHMEXP khm_int32 KHMAPI kcdb_credset_del_cred	(	khm_handle	credset,
		khm_int32	idx
	)

Delete a credential from a credential set.

The credential at index idx will be deleted. All the credentials that are at indices idx + 1 and above will be moved down to fill the gap and the size of the credential set will decrease by one.

Use kcdb_credset_del_cred_ref() to delete a credential by reference. Using kcdb_credset_del_cred() is faster than kcdb_credset_del_cred_ref().

If you call kcdb_credset_del_cred() or kcdb_credset_del_cred_ref() from within kcdb_credset_apply(), the credential will only be marked as deleted. They will not be removed. This means that the size of the credential set will not decrease. To purge the deleted credentials from the set, call kcdb_credset_purge() after kcdb_credset_apply() completes.

Note:

The credential set cannot be sealed.

See also:

kcdb_credset_del_cred_ref()

KHMEXP khm_int32 KHMAPI kcdb_credset_del_cred_ref	(	khm_handle	credset,
		khm_handle	cred
	)

Delete a credential from a credential set by reference.

See kcdb_credset_del_cred() for description of what happens when a credential is deleted from a credential set.

Note:

The credential set cannot be sealed.

See also:

kcdb_credset_del_cred()

KHMEXP khm_int32 KHMAPI kcdb_credset_delete

(

khm_handle

credset

)

Delete a credential set.

See also:

kcdb_credset_create()

KHMEXP khm_int32 KHMAPI kcdb_credset_extract	(	khm_handle	destcredset,
		khm_handle	sourcecredset,
		khm_handle	identity,
		khm_int32	type
	)

Extract credentials from one credential set to another.

Credentials from the source credential set are selected based on the identity and type arguements. If a credential is matched, then it is added to the destcredset.

If the sourcecredset is the root credential set, the added credentials are copies of the actual credentials in the root credential set. Otherwise the credentials are references to the original credentials in the sourcecredset .

Parameters:

[in]	destcredset	Destination credential set. Must be valid.
[in]	sourcecredset	The source credential set. If set to NULL, extracts from the root credential set.
[in]	identity	The identity to match in the source credential set. If set to NULL, matches all identities.
[in]	type	The credential type to match in the source credential set. If set to KCDB_CREDTYPE_INVALID, matches all types.

Note:

This function does not check for duplicate credentials.

The destination credential set cannot be sealed.

KHMEXP khm_int32 KHMAPI kcdb_credset_extract_filtered	(	khm_handle	destcredset,
		khm_handle	sourcecredset,
		kcdb_cred_filter_func	filter,
		void *	rock
	)

Extract credentials from one credential set to another using a filter.

Similar to kcdb_credset_extract() except a filter function is used to determine which credentials should be selected.

Parameters:

[in]

rock

A custom argument to be passed in to the filter function.

Note:

The destination credential set cannot be sealed.

KHMEXP khm_int32 KHMAPI kcdb_credset_find_cred	(	khm_handle	credset,
		khm_handle	cred_src,
		khm_handle *	cred_dest
	)

Find matching credential.

Searches a credential set for a credential that matches the specified credential. For a credential to be a match, it must have the same identity, credential type and name.

Parameters:

[in]	credset	Credential set to search
[in]	cred_src	Credetial to search on
[out]	cred_dest	receieves the matching credential if the search is successful. If a handle is returend, the kcdb_cred_release() must be used to release the handle. If the matching credential is not required, you can pass in NULL.

Return values:

	KHM_ERROR_SUCCESS	The search was successful. A credential was assigned to cred_dest
	KHM_ERROR_NOT_FOUND	A matching credential was not found.

KHMEXP khm_int32 KHMAPI kcdb_credset_find_filtered	(	khm_handle	credset,
		khm_int32	idx_start,
		kcdb_cred_filter_func	f,
		void *	rock,
		khm_handle *	cred,
		khm_int32 *	idx
	)

Search a credential set for a specific credential.

The credential set indicated by credset is searched for a credential that satisfies the predicate function f. Each credential starting at idx_start is passed into the predicate function until it returns a non-zero value. At this point, that credential is passed in to the cred parameter, and the index of the credential is passed into the idx parameter.

Parameters:

[in]	credset	The credential set to search on. Specify NULL if you want to search teh root credential set.
[in]	idx_start	The index at which to start the search after. The first credential passed to the predicate function will be at idx_start + 1. Specify -1 to start from the beginning of the credential set.
[in]	f	The predicate function. The flags parameter of the predicate function will always receive 0.
[in]	rock	An opaque parameter to be passed to the predicate function f.
[out]	cred	A held reference to the credential that satisfied the predicate function or NULL if no such credential was found. Note that if a valid credential is returned, the calling function must release the credential using kcdb_cred_release().
[out]	idx	The index of the credential passed in cred. Specify NULL if the index is not required.

Return values:

	KHM_ERROR_SUCCESS	A credential that satisfied the predicate function was found and was assigned to cred.
	KHM_ERROR_NOT_FOUND	No credential was found that matched the predicate function.

Note:

When querying credential sets that are shared between threads, it is possible that another thread modifies the credential set between successive calls to kcdb_credset_find_filtered(). Therefore a continued sequences of searches are not guaranteed to exhastively cover the credential set nor to not return duplicate matches. Duplicate matches are possible if the order of the credentials in the set was changed.

KHMEXP khm_int32 KHMAPI kcdb_credset_flush

(

khm_handle

credset

)

Flush all credentials from a credential set.

Deletes all the crednetials from the credential set.

Parameters:

[in]

credset

A handle to a credential set. Cannot be NULL.

Note:

The credential set cannot be sealed

KHMEXP khm_int32 KHMAPI kcdb_credset_get_cred	(	khm_handle	credset,
		khm_int32	idx,
		khm_handle *	cred
	)

Retrieve a held reference to a credential in a credential set based on index.

Parameters:

[in]	idx	The index of the credential to retrieve. This is a zero based index which goes from 0 ... (size of credset - 1).
[out]	cred	The held reference to a credential. Call kcdb_cred_release() to release the credential.

Return values:

	KHM_ERROR_SUCCESS	Success. cred has a held reference to the credential.
	KHM_ERROR_OUT_OF_BOUNDS	The index specified in idx is out of bounds.
	KHM_ERROR_DELETED	The credential at index idx has been marked as deleted.

See also:

kcdb_cred_release()

KHMEXP khm_int32 KHMAPI kcdb_credset_get_size	(	khm_handle	credset,
		khm_size *	size
	)

Get the number of credentials in a credential set.

Credentials in a credential set may be volatile. When kcdb_credeset_get_size() is called, the credential set is compacted to only include credentials that are active at the time. However, when you are iterating through the credential set, it might be the case that some credentials would get marked as deleted. These credentials will remain in the credential set until the credential set is discarded or another call to kcdb_credset_get_size() or kdcb_credset_purge() is made.

If the credential set is sealed, then it will not be compacted and will include deleted credentials as well.

See also:

kcdb_credset_purge()

kcdb_credset_get_cred()

KHMEXP khm_int32 KHMAPI kcdb_credset_purge

(

khm_handle

credset

)

Removes credentials that have been marked as deleted from a credential set.

See description of kcdb_credset_purge() for a description of what happens when credntials that are contained in a credential set are deleted by an external entity.

Note:

The credential set cannot be sealed.

See also:

kcdb_credset_get_size()

kcdb_credset_get_cred()

KHMEXP khm_int32 KHMAPI kcdb_credset_seal

(

khm_handle

credset

)

Seal a credential set.

Sealing a credential set makes it read-only. To unseal a credential set, call kcdb_credset_unseal().

Sealing is an additive operation. kcdb_credset_seal() can be called muliple times. However, for every call to kcdb_credset_seal() a call to kcdb_credset_unseal() must be made to undo the seal. The credential set will become unsealed when all the seals are released.

Once sealed, the credential set will not allow any operation that might change its contents. However, a selaed credential set can still be delted.

See also:

kcdb_credset_unseal()

KHMEXP khm_int32 KHMAPI kcdb_credset_sort	(	khm_handle	credset,
		kcdb_cred_comp_func	comp,
		void *	rock
	)

Sort the contents of a credential set.

Parameters:

[in]

rock

A custom argument to be passed in to the comp function.

Note:

The credential set cannot be sealed.

See also:

kcdb_cred_comp_generic()

KHMEXP khm_int32 KHMAPI kcdb_credset_unseal

(

khm_handle

credset

)

Unseal a credential set.

Undoes what kcdb_credset_seal() did. This does not guarantee that the credential set is unsealed since there may be other seals.

See also:

kcdb_credset_seal()

---