Credentials
[Credential sets and individual credentials]

Detailed Description


Data Structures

struct  tag_kcdb_cred_request
 Generic credentials request. More...

Defines

#define KCDB_CRED_MAXCCH_NAME   256
 Maximum number of characters in a credential name.
#define KCDB_CRED_MAXCB_NAME   (sizeof(wchar_t) * KCDB_CRED_MAXCCH_NAME)
 Maximum number of bytes in a credential name.
#define KCDB_CRED_FLAG_DELETED   0x00000008
 Marked as deleted.
#define KCDB_CRED_FLAG_RENEWABLE   0x00000010
 Renewable.
#define KCDB_CRED_FLAG_INITIAL   0x00000020
 Initial.
#define KCDB_CRED_FLAG_EXPIRED   0x00000040
 Expired.
#define KCDB_CRED_FLAG_INVALID   0x00000080
 Invalid.
#define KCDB_CRED_FLAG_SELECTED   0x00000100
 Credential is selected.
#define KCDB_CRED_FLAGMASK_ALL   0x0000ffff
 Bitmask indicating all known credential flags.
#define KCDB_CRED_FLAGMASK_EXT   (KCDB_CRED_FLAG_INITIAL | KCDB_CRED_FLAG_EXPIRED | KCDB_CRED_FLAG_INVALID | KCDB_CRED_FLAG_RENEWABLE)
 External flags.
#define KCDB_CRED_FLAGMASK_ADDITIVE   KCDB_CRED_FLAG_SELECTED
 Bitmask indicating dditive flags.

Typedefs

typedef tag_kcdb_cred_request kcdb_cred_request
 Generic credentials request.

Functions

KHMEXP khm_int32 KHMAPI kcdb_cred_create (const wchar_t *name, khm_handle identity, khm_int32 cred_type, khm_handle *result)
 Create a new credential.
KHMEXP khm_int32 KHMAPI kcdb_cred_dup (khm_handle cred, khm_handle *newcred)
 Duplicate an existing credential.
KHMEXP khm_int32 KHMAPI kcdb_cred_update (khm_handle vdest, khm_handle vsrc)
 Updates one credential using field values from another.
KHMEXP khm_int32 KHMAPI kcdb_cred_set_attrib (khm_handle cred, const wchar_t *name, void *buffer, khm_size cbbuf)
 Set an attribute in a credential by name.
KHMEXP khm_int32 KHMAPI kcdb_cred_set_attr (khm_handle cred, khm_int32 attr_id, void *buffer, khm_size cbbuf)
 Set an attribute in a credential by attribute id.
KHMEXP khm_int32 KHMAPI kcdb_cred_get_attrib (khm_handle cred, const wchar_t *name, khm_int32 *attr_type, void *buffer, khm_size *cbbuf)
 Get an attribute from a credential by name.
KHMEXP khm_int32 KHMAPI kcdb_cred_get_attr (khm_handle cred, khm_int32 attr_id, khm_int32 *attr_type, void *buffer, khm_size *cbbuf)
 Get an attribute from a credential by attribute id.
KHMEXP khm_int32 KHMAPI kcdb_cred_get_name (khm_handle cred, wchar_t *buffer, khm_size *cbbuf)
 Get the name of a credential.
KHMEXP khm_int32 KHMAPI kcdb_cred_get_attr_string (khm_handle vcred, khm_int32 attr_id, wchar_t *buffer, khm_size *pcbbuf, khm_int32 flags)
 Get the string representation of a credential attribute.
KHMEXP khm_int32 KHMAPI kcdb_cred_get_attrib_string (khm_handle cred, const wchar_t *name, wchar_t *buffer, khm_size *cbbuf, khm_int32 flags)
 Get the string representation of a credential attribute by name.
KHMEXP khm_int32 KHMAPI kcdb_cred_get_identity (khm_handle cred, khm_handle *identity)
 Get a held reference to the identity associated with a credential.
KHMEXP khm_int32 KHMAPI kcdb_cred_set_identity (khm_handle vcred, khm_handle id)
 Set the identity of a credential.
KHMEXP khm_int32 KHMAPI kcdb_cred_get_serial (khm_handle cred, khm_ui_8 *pserial)
 Get the serial number for the credential.
KHMEXP khm_int32 KHMAPI kcdb_cred_get_type (khm_handle cred, khm_int32 *type)
 Get the type of the credential.
KHMEXP khm_int32 KHMAPI kcdb_cred_get_flags (khm_handle cred, khm_int32 *flags)
 Retrieve flags from a credential.
KHMEXP khm_int32 KHMAPI kcdb_cred_set_flags (khm_handle cred, khm_int32 flags, khm_int32 mask)
 Set the flags of a credential.
KHMEXP khm_int32 KHMAPI kcdb_cred_hold (khm_handle cred)
 Hold a reference to a credential.
KHMEXP khm_int32 KHMAPI kcdb_cred_release (khm_handle cred)
 Release a held reference to a credential.
KHMEXP khm_int32 KHMAPI kcdb_cred_delete (khm_handle cred)
 Delete a credential.
KHMEXP khm_int32 KHMAPI kcdb_creds_comp_attrib (khm_handle cred1, khm_handle cred2, const wchar_t *name)
 Compare an attribute of two credentials by name.
KHMEXP khm_int32 KHMAPI kcdb_creds_comp_attr (khm_handle cred1, khm_handle cred2, khm_int32 attr_id)
 Compare an attribute of two credentials by attribute id.
KHMEXP khm_int32 KHMAPI kcdb_creds_is_equal (khm_handle cred1, khm_handle cred2)
 Compare two credentials for equivalence.

Define Documentation

#define KCDB_CRED_FLAG_EXPIRED   0x00000040

Expired.

The credential's lifetime has ended.

#define KCDB_CRED_FLAG_INITIAL   0x00000020

Initial.

Initial credentials form the basis of an identity. Some properties of an initial credential, such as being renewable, are directly inherited by the identity. An identity is also automatically considered valid if it contains a valid initial credential.

#define KCDB_CRED_FLAG_INVALID   0x00000080

Invalid.

The credential can no longer serve its intended function. This may be because it is expired and is not renewable, or its renewable time period has also expired, or for some other reason.

#define KCDB_CRED_FLAG_SELECTED   0x00000100

Credential is selected.

Indicates that the credential is selected. Note that using this flag may be subject to race conditions.

#define KCDB_CRED_FLAGMASK_ADDITIVE   KCDB_CRED_FLAG_SELECTED

Bitmask indicating dditive flags.

Additive flags are special flags which are added to exiting credentials based on new credentials when doing a collect operation. See details on kcdb_credset_collect()

See also:
kcdb_credset_collect()

#define KCDB_CRED_FLAGMASK_EXT   (KCDB_CRED_FLAG_INITIAL | KCDB_CRED_FLAG_EXPIRED | KCDB_CRED_FLAG_INVALID | KCDB_CRED_FLAG_RENEWABLE)

External flags.

These are flags that are provided by the credentials providers. The other flags are internal to KCDB and should not be modified.

Typedef Documentation

typedef struct tag_kcdb_cred_request kcdb_cred_request

Generic credentials request.

This data structure is used as the format for a generic credentials reqeust for a KMSG_KCDB_REQUEST message. A plugin typically publishes this message so that a credentials provider may handle it and in response, obtain the specified credential.

While the identity, type and name members of the structure are all optional, typically one would specify all three or at least two for a credential provider to be able to provide the credential unambigously.

Credential providers do not need to respond to KMSG_KCDB_REQUEST messages. However, if they do, they should make sure that they are the only credential provider that is responding by setting the semaphore member to a non-zero value. The semaphore is set to zero when a request is initially sent out. When incrementing the semaphore, the plugin should use a thread safe mechanism to ensure that there are no race conditions that would allow more than one provider to respond to the message.

Function Documentation

KHMEXP khm_int32 KHMAPI kcdb_cred_create ( const wchar_t *  name,
khm_handle  identity,
khm_int32  cred_type,
khm_handle *  result 
)

Create a new credential.

Parameters:
[in] name Name of credential. name cannot be NULL and cannot exceed KCDB_CRED_MAXCCH_NAME unicode characters including the NULL terminator.
[in] identity A reference to an identity.
[in] cred_type A credentials type identifier for the credential.
[out] result Gets a held reference to the newly created credential. Call kcdb_cred_release() or kcdb_cred_delete() to release the reference.
See also:
kcdb_cred_release()

KHMEXP khm_int32 KHMAPI kcdb_cred_delete ( khm_handle  cred  ) 

Delete a credential.

The credential will be marked for deletion and will continue to exist until all held references are released. If the credential is bound to a credential set or the root credential store, it will be removed from the respective container.

KHMEXP khm_int32 KHMAPI kcdb_cred_dup ( khm_handle  cred,
khm_handle *  newcred 
)

Duplicate an existing credential.

Parameters:
[out] newcred A held reference to the new credential if the call succeeds.

KHMEXP khm_int32 KHMAPI kcdb_cred_get_attr ( khm_handle  cred,
khm_int32  attr_id,
khm_int32 *  attr_type,
void *  buffer,
khm_size *  cbbuf 
)

Get an attribute from a credential 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 credential then the function will return KHM_ERROR_SUCCESS, otherwise it returns KHM_ERROR_NOT_FOUND.

KHMEXP khm_int32 KHMAPI kcdb_cred_get_attr_string ( khm_handle  vcred,
khm_int32  attr_id,
wchar_t *  buffer,
khm_size *  pcbbuf,
khm_int32  flags 
)

Get the string representation of a credential attribute.

A shortcut function which generates the string representation of a credential attribute directly.

Parameters:
[in] vcred A handle to a credential
[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 credential
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_cred_get_attrib ( khm_handle  cred,
const wchar_t *  name,
khm_int32 *  attr_type,
void *  buffer,
khm_size *  cbbuf 
)

Get an attribute from a credential 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 credential then the function will return KHM_ERROR_SUCCESS, otherwise it returns KHM_ERROR_NOT_FOUND.

KHMEXP khm_int32 KHMAPI kcdb_cred_get_attrib_string ( khm_handle  cred,
const wchar_t *  name,
wchar_t *  buffer,
khm_size *  cbbuf,
khm_int32  flags 
)

Get the string representation of a credential attribute by name.

A shortcut function which generates the string representation of a credential attribute directly.

Parameters:
[in] vcred A handle to a credential
[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_cred_get_attr_string()

KHMEXP khm_int32 KHMAPI kcdb_cred_get_flags ( khm_handle  cred,
khm_int32 *  flags 
)

Retrieve flags from a credential.

The flags returned will be place in the location pointed to by flags. Note that the specified credential must be an active credential for the operation to succeed. This means the KCDB_CRED_FLAG_DELETED will never be retured by this function.

KHMEXP khm_int32 KHMAPI kcdb_cred_get_identity ( khm_handle  cred,
khm_handle *  identity 
)

Get a held reference to the identity associated with a credential.

Use kcdb_identity_release() to release the reference that is returned.

See also:
kcdb_identity_relase()

KHMEXP khm_int32 KHMAPI kcdb_cred_get_name ( khm_handle  cred,
wchar_t *  buffer,
khm_size *  cbbuf 
)

Get the name of a credential.

Parameters:
[in] buffer The buffer that is to receive the credential name. 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.

KHMEXP khm_int32 KHMAPI kcdb_cred_get_serial ( khm_handle  cred,
khm_ui_8 *  pserial 
)

Get the serial number for the credential.

Each credential gets assigned a serial number at the time it is created. This will stay with the credential for its lifetime.

Parameters:
[out] pserial Receives the serial number. Cannot be NULL.

KHMEXP khm_int32 KHMAPI kcdb_cred_get_type ( khm_handle  cred,
khm_int32 *  type 
)

Get the type of the credential.

The returned type is a credential type. Doh.

Parameters:
[out] type Receives the type. Cannot be NULL.

KHMEXP khm_int32 KHMAPI kcdb_cred_hold ( khm_handle  cred  ) 

Hold a reference to a credential.

Use kcdb_cred_release() to release the reference.

See also:
kcdb_cred_release()

KHMEXP khm_int32 KHMAPI kcdb_cred_set_attr ( khm_handle  cred,
khm_int32  attr_id,
void *  buffer,
khm_size  cbbuf 
)

Set an attribute in a credential by attribute id.

Parameters:
[in] buffer A pointer to a buffer containing the data to assign to the attribute. Setting this 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_cred_set_attrib ( khm_handle  cred,
const wchar_t *  name,
void *  buffer,
khm_size  cbbuf 
)

Set an attribute in a credential by name.

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. For some data types where the size of the buffer is fixed or can be determined from its contents, you can specify KCDB_CBSIZE_AUTO for this parameter.

KHMEXP khm_int32 KHMAPI kcdb_cred_set_flags ( khm_handle  cred,
khm_int32  flags,
khm_int32  mask 
)

Set the flags of a credential.

The flags specified in the mask parameter will be set to the values specified in the flags parameter. The flags that are not included in mask will not be modified.

This function can not be used to set the KCDB_CRED_FLAG_DELETED flag. If this bit is specified in either flags or mask, it will be ignored.

See also:
KCDB_CRED_FLAGMASK_ALL

KHMEXP khm_int32 KHMAPI kcdb_cred_set_identity ( khm_handle  vcred,
khm_handle  id 
)

Set the identity of a credential.

While it is ill-advised to change the identity of a credential that has been placed in one or more credential sets, there can be legitimate reasons for doing so. Only change the identity of a credential that is not placed in a credential set or placed in a credential set that is only used by a single entity.

KHMEXP khm_int32 KHMAPI kcdb_cred_update ( khm_handle  vdest,
khm_handle  vsrc 
)

Updates one credential using field values from another.

All fields that exist in vsrc will get copied to vdest and will overwrite any values that are already there in vdest. However any values that exist in vdest taht do not exist in vsrc will not be modified.

Return values:
KHM_ERROR_SUCCESS vdest was successfully updated
KHM_ERROR_EQUIVALENT all fields in vsrc were present and equivalent in vdest

KHMEXP khm_int32 KHMAPI kcdb_creds_comp_attr ( khm_handle  cred1,
khm_handle  cred2,
khm_int32  attr_id 
)

Compare an attribute of two credentials by attribute id.

Returns:
The return value is dependent on the type of the attribute and indicate a weak ordering of the attribute values of the two credentials. If one or both credentials do not contain the attribute, the return value is 0, which signifies that no ordering can be determined.

KHMEXP khm_int32 KHMAPI kcdb_creds_comp_attrib ( khm_handle  cred1,
khm_handle  cred2,
const wchar_t *  name 
)

Compare an attribute of two credentials by name.

Returns:
The return value is dependent on the type of the attribute and indicate a weak ordering of the attribute values of the two credentials. If one or both credentials do not contain the attribute, the return value is 0, which signifies that no ordering can be determined.

KHMEXP khm_int32 KHMAPI kcdb_creds_is_equal ( khm_handle  cred1,
khm_handle  cred2 
)

Compare two credentials for equivalence.

Returns:
Non-zero if the two credentials are equal. Zero otherwise.
Note:
Two credentials are considered equal if all the following hold:
  • Both refer to the same identity.
  • Both have the same name.
  • Both have the same type.

Generated on Fri Aug 3 08:27:14 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