Identities
[NetIDMgr Credentials Database]

Detailed Description

Functions, macros etc. for manipulating identities.


Data Structures

struct  tag_kcdb_ident_name_xfer
 Name transfer structure. More...
struct  tag_kcdb_ident_info

Identity Provider Data Structures

typedef tag_kcdb_ident_name_xfer kcdb_ident_name_xfer
 Name transfer structure.
typedef tag_kcdb_ident_info kcdb_ident_info

Identity provider interface functions

These functions encapsulate safe calls to the current identity provider. While these functions are exported, applications should not call these functions directly. They are provided for use by the NetIDMgr core application.

KHMEXP khm_int32 KHMAPI kcdb_identpro_validate_name (const wchar_t *name)
 Validate an identity name.
KHMEXP khm_int32 KHMAPI kcdb_identpro_validate_identity (khm_handle identity)
 Validate an identity.
KHMEXP khm_int32 KHMAPI kcdb_identpro_canon_name (const wchar_t *name_in, wchar_t *name_out, khm_size *cb_name_out)
 Canonicalize the name.
KHMEXP khm_int32 KHMAPI kcdb_identpro_compare_name (const wchar_t *name1, const wchar_t *name2)
 Compare two identity names.
KHMEXP khm_int32 KHMAPI kcdb_identpro_set_default (khm_handle identity)
 Set the specified identity as the default.
KHMEXP khm_int32 KHMAPI kcdb_identpro_set_searchable (khm_handle identity, khm_boolean searchable)
 Set the specified identity as searchable.
KHMEXP khm_int32 KHMAPI kcdb_identpro_update (khm_handle identity)
 Update the specified identity.
KHMEXP khm_int32 KHMAPI kcdb_identpro_get_ui_cb (void *rock)
 Obtain the UI callback.
KHMEXP khm_int32 KHMAPI kcdb_identpro_notify_create (khm_handle identity)
 Notify an identity provider of the creation of a new identity.

Flags for identities

#define KCDB_IDENT_FLAG_CREATE   0x10000000L
 Create the identity if it doesn't already exist.
#define KCDB_IDENT_FLAG_CONFIG   0x00800000L
 Has configuration information.
#define KCDB_IDENT_FLAG_ACTIVE   0x02000000L
 Marks the identity as active.
#define KCDB_IDENT_FLAG_ATTRIBS   0x08000000L
 The identity has custom attributes assigned.
#define KCDB_IDENT_FLAG_DEFAULT   0x00000001L
 This is the default identity.
#define KCDB_IDENT_FLAG_SEARCHABLE   0x00000002L
 This identity can be searched.
#define KCDB_IDENT_FLAG_HIDDEN   0x00000004L
 Hidden identity.
#define KCDB_IDENT_FLAG_INVALID   0x00000008L
 Invalid identity.
#define KCDB_IDENT_FLAG_VALID   0x00000010L
 Valid identity.
#define KCDB_IDENT_FLAG_EXPIRED   0x00000020L
 Expired identity.
#define KCDB_IDENT_FLAG_EMPTY   0x00000040L
 Empty identity.
#define KCDB_IDENT_FLAG_RENEWABLE   0x00000080L
 Renewable identity.
#define KCDB_IDENT_FLAG_INTERACT   0x00000100L
 Required user interaction.
#define KCDB_IDENT_FLAG_CRED_EXP   0x00000200L
 Has expired credentials.
#define KCDB_IDENT_FLAG_CRED_RENEW   0x00000400L
 Has renewable credentials.
#define KCDB_IDENT_FLAG_STICKY   0x00000800L
 Sticky identity.
#define KCDB_IDENT_FLAG_UNKNOWN   0x00001000L
 Unknown state.
#define KCDB_IDENT_FLAGMASK_RDWR   0x00001fffL
 Read/write flags mask.

Defines

#define KCDB_IDENT_MAXCCH_NAME   256
 The maximum number of characters (including terminator) that can be specified as an identity name.
#define KCDB_IDENT_MAXCB_NAME   (sizeof(wchar_t) * KCDB_IDENT_MAXCCH_NAME)
 The maximum number of bytes that can be specified as an identity name.
#define KCDB_IDENT_VALID_CHARS   L"0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ._@-/"
 Valid characters in an identity name.

Functions

KHMEXP khm_boolean KHMAPI kcdb_identity_is_valid_name (const wchar_t *name)
 Check if the given name is a valid identity name.
KHMEXP khm_int32 KHMAPI kcdb_identity_create (const wchar_t *name, khm_int32 flags, khm_handle *result)
 Create or open an identity.
KHMEXP khm_int32 KHMAPI kcdb_identity_delete (khm_handle id)
 Mark an identity for deletion.
KHMEXP khm_int32 KHMAPI kcdb_identity_set_flags (khm_handle id, khm_int32 flags, khm_int32 mask)
 Set or unset the specified flags in the specified identity.
KHMEXP khm_int32 KHMAPI kcdb_identity_get_flags (khm_handle id, khm_int32 *flags)
 Return all the flags for the identity.
KHMEXP khm_int32 KHMAPI kcdb_identity_get_name (khm_handle id, wchar_t *buffer, khm_size *pcbsize)
 Return the name of the identity.
KHMEXP khm_int32 KHMAPI kcdb_identity_set_default (khm_handle id)
 Set the specified identity as the default.
KHMEXP khm_int32 KHMAPI kcdb_identity_set_default_int (khm_handle id)
 Mark the specified identity as the default.
KHMEXP khm_int32 KHMAPI kcdb_identity_get_default (khm_handle *pvid)
 Get the default identity.
KHMEXP khm_int32 KHMAPI kcdb_identity_get_config (khm_handle id, khm_int32 flags, khm_handle *result)
 Get the configuration space for the identity.
KHMEXP khm_int32 KHMAPI kcdb_identity_hold (khm_handle id)
 Hold a reference to an identity.
KHMEXP khm_int32 KHMAPI kcdb_identity_release (khm_handle id)
 Release a reference to an identity.
KHMEXP khm_int32 KHMAPI kcdb_identity_set_provider (khm_handle sub)
 Set the identity provider subscription.
KHMEXP khm_int32 KHMAPI kcdb_identity_set_type (khm_int32 cred_type)
 Set the primary credentials type.
KHMEXP khm_int32 KHMAPI kcdb_identity_get_provider (khm_handle *sub)
 Retrieve the identity provider subscription.
KHMEXP khm_int32 KHMAPI kcdb_identity_get_type (khm_int32 *ptype)
 Retrieve the identity provider credentials type.
KHMEXP khm_boolean KHMAPI kcdb_identity_is_equal (khm_handle identity1, khm_handle identity2)
 Returns TRUE if the two identities are equal.
KHMEXP khm_int32 KHMAPI kcdb_identity_set_attr (khm_handle identity, khm_int32 attr_id, void *buffer, khm_size cbbuf)
 Set an attribute in an identity by attribute id.
KHMEXP khm_int32 KHMAPI kcdb_identity_set_attrib (khm_handle identity, const wchar_t *attr_name, void *buffer, khm_size cbbuf)
 Set an attribute in an identity by name.
KHMEXP khm_int32 KHMAPI kcdb_identity_get_attr (khm_handle identity, khm_int32 attr_id, khm_int32 *attr_type, void *buffer, khm_size *pcbbuf)
 Get an attribute from an identity by attribute id.
KHMEXP khm_int32 KHMAPI kcdb_identity_get_attrib (khm_handle identity, const wchar_t *attr_name, khm_int32 *attr_type, void *buffer, khm_size *pcbbuf)
 Get an attribute from an identity by name.
KHMEXP khm_int32 KHMAPI kcdb_identity_get_attr_string (khm_handle identity, khm_int32 attr_id, wchar_t *buffer, khm_size *pcbbuf, khm_int32 flags)
 Get the string representation of an identity attribute.
KHMEXP khm_int32 KHMAPI kcdb_identity_get_attrib_string (khm_handle identity, const wchar_t *attr_name, wchar_t *buffer, khm_size *pcbbuf, khm_int32 flags)
 Get the string representation of an identity attribute by name.
KHMEXP khm_int32 KHMAPI kcdb_identity_enum (khm_int32 and_flags, khm_int32 eq_flags, wchar_t *name_buf, khm_size *pcb_buf, khm_size *pn_idents)
 Enumerate identities.
KHMEXP khm_int32 KHMAPI kcdb_identity_refresh (khm_handle vid)
 Refresh identity attributes based on root credential set.
KHMEXP khm_int32 KHMAPI kcdb_identity_refresh_all (void)
 Refresh all identities.

Define Documentation

#define KCDB_IDENT_FLAG_ACTIVE   0x02000000L

Marks the identity as active.

An active identity is one that is in active use within NetIDMgr.

Note:
This flag is readonly and cannot be specified when creating or modifying an identity. Once an identity is deleted, it will no longer have this flag.

#define KCDB_IDENT_FLAG_CONFIG   0x00800000L

Has configuration information.

Indicates that the identity has persistent configuration information associated with it.

#define KCDB_IDENT_FLAG_CREATE   0x10000000L

Create the identity if it doesn't already exist.

Note:
Only to be used with kcdb_identity_create()

#define KCDB_IDENT_FLAG_CRED_EXP   0x00000200L

Has expired credentials.

The identity has expired credentials associated with it.

#define KCDB_IDENT_FLAG_CRED_RENEW   0x00000400L

Has renewable credentials.

The identity has renewable credentials associated with it. If the initial credentials of the identity are renewable, then identity is renewable. Hence the KCDB_IDENT_FLAG_RENEWABLE should also be set.

#define KCDB_IDENT_FLAG_DEFAULT   0x00000001L

This is the default identity.

At most one identity will have this flag set at any given time. To set or reset the flag, use kcdb_identity_set_default()

#define KCDB_IDENT_FLAG_EMPTY   0x00000040L

Empty identity.

The identity does not have actual credentials associated with it.

#define KCDB_IDENT_FLAG_EXPIRED   0x00000020L

Expired identity.

This identity has expired and can not be actively used to obtain credentials. This determination is made based on the input of some external entity. This flag may only be set by an identity provider.

#define KCDB_IDENT_FLAG_HIDDEN   0x00000004L

Hidden identity.

The identity will not show up in the identity list window. Once the hidden is switched off, the identity (and all associated credentials) will re-appear in the window

#define KCDB_IDENT_FLAG_INTERACT   0x00000100L

Required user interaction.

The identity is in a state which requires user interaction to activate. Currently, the identity may not be in a state where it can be used to obtain credentials.

A typical example of this is when the primary password for an identity has expired.

#define KCDB_IDENT_FLAG_INVALID   0x00000008L

Invalid identity.

For one reason or another, this identity is invalid. This flag can be set by an identity provider to indicate that this identity does not correspond to an actual identity because an external entity (such as a KDC) has denied it's existence.

The absence of this flag does not imply that the identity is valid. The KCDB_IDENT_FLAG_VALID bit must be set for that to be the case. If neither flag is set, then the status of the identity is not known.

#define KCDB_IDENT_FLAG_RENEWABLE   0x00000080L

Renewable identity.

The initial credentials associated with this identity are renewable. Thus making the whole identity renewable.

#define KCDB_IDENT_FLAG_SEARCHABLE   0x00000002L

This identity can be searched.

The meaning of this flag is left to be interpreted by individual plugins.

#define KCDB_IDENT_FLAG_STICKY   0x00000800L

Sticky identity.

Sticky identities are identities that are always visible in the credentials display even if no credentials are associated with it.

#define KCDB_IDENT_FLAG_UNKNOWN   0x00001000L

Unknown state.

The validity of the identity cannot be determined. This usually means that an authority could not be contacted. This flag is to be treated as transient. If KCDB_IDENT_FLAG_INVALID or KCDB_IDENT_FLAG_VALID is set for the identity, this flag is to be ignored.

#define KCDB_IDENT_FLAG_VALID   0x00000010L

Valid identity.

The identity has been validated through an external entity, or it's validity implied through the existence of credentials for the identity.

The absence of this flag does not imply that the identity is invalid. The KCDB_IDENT_FLAG_INVALID bit must be set for that to be the case. If neither flag is set, then the status of the identity is not known.

#define KCDB_IDENT_FLAGMASK_RDWR   0x00001fffL

Read/write flags mask.

A bitmask that correspond to all the read/write flags in the mask.

Typedef Documentation

typedef struct tag_kcdb_ident_name_xfer kcdb_ident_name_xfer

Name transfer structure.

Used when the KCDB is communicating with the identity provider to exchange string names of identities. See individual KMSG_IDENT message subtypes for the usage of this structure.

Function Documentation

KHMEXP khm_int32 KHMAPI kcdb_identity_create ( const wchar_t *  name,
khm_int32  flags,
khm_handle *  result 
)

Create or open an identity.

If the KCDB_IDENT_FLAG_CREATE flag is specified in the flags parameter a new identity will be created if one does not already exist with the given name. If an identity by that name already exists, then the existing identity will be opened. The result parameter will receive a held reference to the opened identity. Use kcdb_identity_release() to release the handle.

Parameters:
[in] name Name of identity to create
[in] flags If KCDB_IDENT_FLAG_CREATE is specified, then the identity will be created if it doesn't already exist. Additional flags can be set here which will be assigned to the identity if it is created. Additional flags have no effect if an existing identity is opened.
[out] result If the call is successful, this receives a held reference to the identity. The caller should call kcdb_identity_release() to release the identity once it is no longer needed.

KHMEXP khm_int32 KHMAPI kcdb_identity_delete ( khm_handle  id  ) 

Mark an identity for deletion.

The identity will be marked for deletion. The KCDB_IDENT_FLAG_ACTIVE will no longer be present for this identity. Once all references to the identity are released, it will be removed from memory. All associated credentials will also be removed.

KHMEXP khm_int32 KHMAPI kcdb_identity_enum ( khm_int32  and_flags,
khm_int32  eq_flags,
wchar_t *  name_buf,
khm_size *  pcb_buf,
khm_size *  pn_idents 
)

Enumerate identities.

Enumerates all the active identities that match the criteria specified using and_flags and eq_flags. The condition is applied to all active identities as follows:

    (identity->flags & and_flags) == (eq_flags & and_flags)

Essentially, if a flag is set in and_flags, then that flag in the identity should equal the setting in eq_flags.

Parameters:
[in] and_flags See above
[in] eq_flags See above
[out] name_buf Buffer to receive the list of identity names. Can be NULL if only the required size of the buffer or the number of matching identities is required. The list is returned as a multi string.
[in,out] pcb_buf Number of bytes in buffer pointed to by name_buf on entry. On exit, will receive the number of bytes copied. Can be NULL only if name_buf is also NULL. If name_buf is NULL or if pcb_buf indicates that the buffer is insufficient, this will receive the number of bytes required and the return value of the function will be KHM_ERROR_TOO_LONG
[out] pn_idents Receives the number of identities that match the given criteria.
Return values:
KHM_ERROR_SUCCESS If name_buf was valid, the buffer now contains a multi string of identities that matched. If pn_idents was valid, it contains the number of identities matched.
KHM_ERROR_TOO_LONG No buffer was supplied or the supplied buffer was insufficient. If pn_idents was valid, it contains the number of identities.
KHM_ERROR_INVALID_PARAM None of the parameters name_buf, pcb_buf and pn_idents were supplied, or pcb_buf was NULL when name_buf was not.
Note:
Calling this function to obtain the required size of the buffer and then calling it with a that sized buffer is not guaranteed to work since the list of identities may change between the two calls.

KHMEXP khm_int32 KHMAPI kcdb_identity_get_attr ( khm_handle  identity,
khm_int32  attr_id,
khm_int32 *  attr_type,
void *  buffer,
khm_size *  pcbbuf 
)

Get an attribute from an identity by attribute id.

Parameters:
[in] buffer The buffer that is to receive the attribute value. Set this to NULL if only the required buffer size is to be returned.
[in,out] cbbuf The number of bytes available in buffer. If buffer is not sufficient, returns KHM_ERROR_TOO_LONG and sets this to the required buffer size.
[out] attr_type Receives the data type of the attribute. Set this to NULL if the type is not required.
Note:
Set both buffer and cbbuf to NULL if only the existence of the attribute is to be checked. If the attribute exists in this identity then the function will return KHM_ERROR_SUCCESS, otherwise it returns KHM_ERROR_NOT_FOUND.

KHMEXP khm_int32 KHMAPI kcdb_identity_get_attr_string ( khm_handle  identity,
khm_int32  attr_id,
wchar_t *  buffer,
khm_size *  pcbbuf,
khm_int32  flags 
)

Get the string representation of an identity attribute.

A shortcut function which generates the string representation of an identity attribute directly.

Parameters:
[in] identity A handle to an identity
[in] attr_id The attribute to retrieve
[out] buffer A pointer to a string buffer which receives the string form of the attribute. Set this to NULL if you only want to determine the size of the required buffer.
[in,out] pcbbuf A pointer to a khm_int32 that, on entry, holds the size of the buffer pointed to by buffer, and on exit, receives the actual number of bytes that were copied.
[in] flags Flags for the string conversion. Can be set to one of KCDB_TS_LONG or KCDB_TS_SHORT. The default is KCDB_TS_LONG.
Return values:
KHM_ERROR_SUCCESS Success
KHM_ERROR_NOT_FOUND The given attribute was either invalid or was not defined for this identity
KHM_ERROR_INVALID_PARAM One or more parameters were invalid
KHM_ERROR_TOO_LONG Either buffer was NULL or the supplied buffer was insufficient

KHMEXP khm_int32 KHMAPI kcdb_identity_get_attrib ( khm_handle  identity,
const wchar_t *  attr_name,
khm_int32 *  attr_type,
void *  buffer,
khm_size *  pcbbuf 
)

Get an attribute from an identity by name.

Parameters:
[in] buffer The buffer that is to receive the attribute value. Set this to NULL if only the required buffer size is to be returned.
[in,out] cbbuf The number of bytes available in buffer. If buffer is not sufficient, returns KHM_ERROR_TOO_LONG and sets this to the required buffer size.
Note:
Set both buffer and cbbuf to NULL if only the existence of the attribute is to be checked. If the attribute exists in this identity then the function will return KHM_ERROR_SUCCESS, otherwise it returns KHM_ERROR_NOT_FOUND.

KHMEXP khm_int32 KHMAPI kcdb_identity_get_attrib_string ( khm_handle  identity,
const wchar_t *  attr_name,
wchar_t *  buffer,
khm_size *  pcbbuf,
khm_int32  flags 
)

Get the string representation of an identity attribute by name.

A shortcut function which generates the string representation of an identity attribute directly.

Parameters:
[in] identity A handle to an identity
[in] attrib The name of the attribute to retrieve
[out] buffer A pointer to a string buffer which receives the string form of the attribute. Set this to NULL if you only want to determine the size of the required buffer.
[in,out] pcbbuf A pointer to a khm_int32 that, on entry, holds the size of the buffer pointed to by buffer, and on exit, receives the actual number of bytes that were copied.
[in] flags Flags for the string conversion. Can be set to one of KCDB_TS_LONG or KCDB_TS_SHORT. The default is KCDB_TS_LONG.
See also:
kcdb_identity_get_attr_string()

KHMEXP khm_int32 KHMAPI kcdb_identity_get_config ( khm_handle  id,
khm_int32  flags,
khm_handle *  result 
)

Get the configuration space for the identity.

If the configuration space for the identity does not exist and the flags parameter does not specify KHM_FLAG_CREATE, then the function will return a failure code as specified in khc_open_space(). Depending on whether or not a configuration space was found, the KCDB_IDENT_FLAG_CONFIG flag will be set or reset for the identity.

Parameters:
[in] id Identity for which the configuraiton space is requested
[in] flags Flags used when calling khc_open_space(). If flags specifies KHM_FLAG_CREATE, then the configuration space is created.
[out] result The resulting handle. If the call is successful, this receives a handle to the configuration space. Use khc_close_space() to close the handle.

KHMEXP khm_int32 KHMAPI kcdb_identity_get_default ( khm_handle *  pvid  ) 

Get the default identity.

Obtain a held handle to the default identity if there is one. The handle must be freed using kcdb_identity_release().

If there is no default identity, then the handle pointed to by pvid is set to NULL and the function returns KHM_ERROR_NOT_FOUND.

KHMEXP khm_int32 KHMAPI kcdb_identity_get_flags ( khm_handle  id,
khm_int32 *  flags 
)

Return all the flags for the identity.

The returned flags may include internal flags.

KHMEXP khm_int32 KHMAPI kcdb_identity_get_name ( khm_handle  id,
wchar_t *  buffer,
khm_size *  pcbsize 
)

Return the name of the identity.

Parameters:
[out] buffer Buffer to copy the identity name into. The maximum size of an identity name is KCDB_IDENT_MAXCB_NAME. If buffer is NULL, then the required size of the buffer is returned in pcbsize.
[in,out] pcbsize Size of buffer in bytes.

KHMEXP khm_int32 KHMAPI kcdb_identity_get_provider ( khm_handle *  sub  ) 

Retrieve the identity provider subscription.

Parameters:
[out] sub Receives the current identity provider subscription. Set to NULL if only the existence of an identity provider needs to be checked.
Return values:
KHM_ERROR_SUCCESS An identity provider exists. If sub was not NULL, the subscription has been copied there.
KHM_ERROR_NOT_FOUND There is currently no registered identity provider. If sub was not NULL, the handle it points to has been set to NULL.

KHMEXP khm_int32 KHMAPI kcdb_identity_get_type ( khm_int32 *  ptype  ) 

Retrieve the identity provider credentials type.

This is the credentials type that the identity provider has designated as the primary credentials type.

KHMEXP khm_int32 KHMAPI kcdb_identity_hold ( khm_handle  vid  ) 

Hold a reference to an identity.

Note:
cs_ident must be available.

KHMEXP khm_boolean KHMAPI kcdb_identity_is_equal ( khm_handle  identity1,
khm_handle  identity2 
)

Returns TRUE if the two identities are equal.

Also returns TRUE if both identities are NULL.

KHMEXP khm_boolean KHMAPI kcdb_identity_is_valid_name ( const wchar_t *  name  ) 

Check if the given name is a valid identity name.

Returns:
TRUE or FALSE to the question, is this valid?

KHMEXP khm_int32 KHMAPI kcdb_identity_refresh ( khm_handle  vid  ) 

Refresh identity attributes based on root credential set.

Several flags in an identity are dependent on the credentials that are associated with it in the root credential set. In addition, other flags in an identity depend on external factors that need to be verfied once in a while. This API goes through the root credential set as well as consulting the identity provider to update an identity.

See also:
kcdb_identity_refresh()

KHMEXP khm_int32 KHMAPI kcdb_identity_refresh_all ( void   ) 

Refresh all identities.

Equivalent to calling kcdb_identity_refresh() for all active identities.

See also:
kcdb_identityt_refresh()

KHMEXP khm_int32 KHMAPI kcdb_identity_release ( khm_handle  vid  ) 

Release a reference to an identity.

Note:
cs_ident must be available.

KHMEXP khm_int32 KHMAPI kcdb_identity_set_attr ( khm_handle  identity,
khm_int32  attr_id,
void *  buffer,
khm_size  cbbuf 
)

Set an attribute in an identity by attribute id.

Parameters:
[in] buffer A pointer to a buffer containing the data to assign to the attribute. Setting buffer to NULL has the effect of removing any data that is already assigned to the attribute. If buffer is non-NULL, then cbbuf should specify the number of bytes in buffer.
[in] cbbuf Number of bytes of data in buffer. The individual data type handlers may copy in less than this many bytes in to the credential.

KHMEXP khm_int32 KHMAPI kcdb_identity_set_attrib ( khm_handle  identity,
const wchar_t *  attr_name,
void *  buffer,
khm_size  cbbuf 
)

Set an attribute in an identity by name.

The attribute name has to be a KCDB registered attribute or property.

Parameters:
[in] cbbuf Number of bytes of data in buffer. The individual data type handlers may copy in less than this many bytes in to the credential.

KHMEXP khm_int32 KHMAPI kcdb_identity_set_default ( khm_handle  id  ) 

Set the specified identity as the default.

Specifying NULL effectively makes none of the identities the default.

See also:
kcdb_identity_set_flags()

KHMEXP khm_int32 KHMAPI kcdb_identity_set_default_int ( khm_handle  id  ) 

Mark the specified identity as the default.

This API is reserved for use by identity providers as a means of specifying which identity is default. The difference between kcdb_identity_set_default() and kcdb_identity_set_default_int() is in semantics.

KHMEXP khm_int32 KHMAPI kcdb_identity_set_flags ( khm_handle  id,
khm_int32  flags,
khm_int32  mask 
)

Set or unset the specified flags in the specified identity.

Only flags that are in KCDB_IDENT_FLAGMASK_RDWR can be specifed in the flags parameter or the mask parameter. The flags set in the mask parameter of the identity will be set to the corresponding values in the flags parameter.

If KCDB_IDENT_FLAG_INVALID is set using this function, then the KCDB_IDENT_FLAG_VALID will be automatically reset, and vice versa. Resetting either bit does not undo this change, and will leave the identity's validity unspecified. Setting either of KCDB_IDENT_FLAG_INVALID or KCDB_IDENT_FLAG_VALID will automatically reset KCDB_IDENT_FLAG_UNKNOWN.

Note that setting or resetting certain flags have other semantic side-effects:

Note:
kcdb_identity_set_flags() is not atomic. Even if the function returns a failure code, some flags in the identity may have been set. When calling kcdb_identity_set_flags() always check the flags in the identity using kcdb_identity_get_flags() to check which flags have been set and which have failed.

KHMEXP khm_int32 KHMAPI kcdb_identity_set_provider ( khm_handle  sub  ) 

Set the identity provider subscription.

If there was a previous subscription, that subscription will be automatically deleted.

Parameters:
[in] sub New identity provider subscription

KHMEXP khm_int32 KHMAPI kcdb_identity_set_type ( khm_int32  cred_type  ) 

Set the primary credentials type.

The primary credentials type is designated by the identity provider. As such, this function should only be called by an identity provider.

KHMEXP khm_int32 KHMAPI kcdb_identpro_canon_name ( const wchar_t *  name_in,
wchar_t *  name_out,
khm_size *  cb_name_out 
)

Canonicalize the name.

See also:
KMSG_IDENT_CANON_NAME

KHMEXP khm_int32 KHMAPI kcdb_identpro_compare_name ( const wchar_t *  name1,
const wchar_t *  name2 
)

Compare two identity names.

See also:
KMSG_IDENT_COMPARE_NAME

KHMEXP khm_int32 KHMAPI kcdb_identpro_get_ui_cb ( void *  rock  ) 

Obtain the UI callback.

rock is actually a pointer to a khui_ident_new_creds_cb which is to receive the callback.

See also:
KMSG_IDENT_GET_UI_CALLBACK

KHMEXP khm_int32 KHMAPI kcdb_identpro_notify_create ( khm_handle  identity  ) 

Notify an identity provider of the creation of a new identity.

See also:
KMSG_IDENT_NOTIFY_CREATE

KHMEXP khm_int32 KHMAPI kcdb_identpro_set_default ( khm_handle  identity  ) 

Set the specified identity as the default.

See also:
KMSG_IDENT_SET_DEFAULT

KHMEXP khm_int32 KHMAPI kcdb_identpro_set_searchable ( khm_handle  identity,
khm_boolean  searchable 
)

Set the specified identity as searchable.

See also:
KMSG_IDENT_SET_SEARCHABLE

KHMEXP khm_int32 KHMAPI kcdb_identpro_update ( khm_handle  identity  ) 

Update the specified identity.

See also:
KMSG_IDENT_UPDATE

KHMEXP khm_int32 KHMAPI kcdb_identpro_validate_identity ( khm_handle  identity  ) 

Validate an identity.

The identity itself needs to be validated. This may involve communicating with an external entity.

See also:
KMSG_IDENT_VALIDATE_IDENTITY

KHMEXP khm_int32 KHMAPI kcdb_identpro_validate_name ( const wchar_t *  name  ) 

Validate an identity name.

The name that is provided will be passed through sets of validations. One set, which doesn't depend on the identity provider checks whether the length of the identity name and whether there are any invalid characters in the identity name. If the name passes those tests, then the name is passed down to the identity provider's name validation handler.

Return values:
KHM_ERROR_SUCCESS The name is valid
KHM_ERROR_TOO_LONG Too many characters in name
KHM_ERROR_INVALID_NAME There were invalid characters in the name.
KHM_ERROR_NO_PROVIDER There is no identity provider; however the name passed the length and character tests.
KHM_ERROR_NOT_IMPLEMENTED The identity provider doesn't implement a name validation handler; however the name passed the length and character tests.
See also:
KMSG_IDENT_VALIDATE_NAME

Generated on Fri Aug 3 08:27:13 2007 for Network Identity Manager by Doxygen 1.5.2
© 2004-2007 Massachusetts Institute of Technology.
© 2005-2007 Secure Endpoints Inc.
Contact khimaira@mit.edu