ADC Home > Reference Library > Reference > Networking > Core Foundation > Core Services Identity Reference

CSIdentity

Framework:	/System/Library/Frameworks/CoreServices.framework/Frameworks/OSServices.framework
See Also:	Identity Services Programming Guide
Includes:	<CoreFoundation.i> <SecBase.i> <Authorization.i> <CSIdentityAuthority.i>

Overview

A CSIdentity object represents a user or group entity known to the system. An identity object has the following required attributes: a class (user or group), a unique identitfier (UUID), a full name, a Posix ID (UID or GID), and a Posix name (a.k.a. "short" name). There are also a number of optional attributes such as email address, image data, etc.

Group identities have a membership which may include both users as well as other groups. An identity can be tested for membership in a specific group.

A CSIdentity object is a private copy of the identity information. It can be modified in memory, but requires authorization to commit changes back to the identity authority database. On Mac OS X version 10.5, only local identities can be created, modified or deleted, and only by users with Administrator credentials.

Changes may be committed synchronously or asynchronously. All data validation occurs at commit time.

Two identities are CFEqual if they have the same class and UUID.

Groups

Permanent

Deletion

Group members:

CSIdentityDelete

Permanently delete an identity from the identity database

Committing

changes

Group members:

CSIdentityCommit

Synchronously commit all pending changes to the identity authority database

CSIdentityCommitAsynchronously

Asychronously commit all pending changes to the identity authority's database

CSIdentityIsCommitting

Determine if a commit operation is in progress

CSIdentityRemoveClient

Invalidate an identity's client structure to stop client callbacks

User

Methods

Group members:

CSIdentityAuthenticateUsingPassword

Attempt to autenticate a password for a user identity

CSIdentityGetCertificate

Get a user's authentication certificate

CSIdentityIsEnabled

Determine if a user is enabled

Group

Methods

Group members:

CSIdentityCreateGroupMembershipQuery

Creates a query to find a group's members

Getting

Identity Attributes

Group members:

CSIdentityCreatePersistentReference

Create an opaque, persistent data reference to an identity

CSIdentityGetAliases

Retrieve the aliases of an identity.

CSIdentityGetAuthority

Returns the identity authority of an identity

CSIdentityGetClass

Returns an identity's class

CSIdentityGetEmailAddress

Retrieve the email address of a user identity

CSIdentityGetFullName

Retrieve the full name of an identity

CSIdentityGetImageData

Retrieve the image associated with a user identity

CSIdentityGetImageDataType

Retrieve the uniform type identifier (UTI) of an identity's image

CSIdentityGetImageURL

Retrieve the URL to an identity's image file

CSIdentityGetPosixID

Retrieve POSIX ID of an identity.

CSIdentityGetPosixName

Retrieve the POSIX name (short name) of an identity.

CSIdentityGetUUID

Returns an identity's UUID.

CSIdentityIsHidden

Determine if a identity's hidden attribute is enabled

CSIdentityIsMemberOfGroup

Check if an identity is a memeber of a group

Modifying

group membership

Group members:

CSIdentityAddAlias

Add a name alias to an identity

CSIdentityAddMember

Add an identity to a group

CSIdentityRemoveAlias

Remove an alias name from an identity

CSIdentityRemoveMember

Remove a member from a group

CSIdentitySetCertificate

Set a user's authentication certificate

CSIdentitySetEmailAddress

Set an identity's email address

CSIdentitySetFullName

Sets an identity's full name.

CSIdentitySetImageData

Set the internally-stored image data and data type for an identity

CSIdentitySetImageURL

Set the URL of an identity's external image storage

CSIdentitySetIsEnabled

Enable or disable a user

CSIdentitySetPassword

Set a user password

Creating

Identities

Group members:

CSIdentityCreate

Creates a new identity

CSIdentityCreateCopy

Creates a copy of an identity

Modifying user credentials

Group members:

CSIdentitySetIsEnabled

Enable or disable a user

Functions

CSIdentityAddAlias: Add a name alias to an identity
CSIdentityAddMember: Add an identity to a group
CSIdentityAuthenticateUsingPassword: Attempt to autenticate a password for a user identity
CSIdentityCommit: Synchronously commit all pending changes to the identity authority database
CSIdentityCommitAsynchronously: Asychronously commit all pending changes to the identity authority's database
CSIdentityCreate: Creates a new identity
CSIdentityCreateCopy: Creates a copy of an identity
CSIdentityCreateGroupMembershipQuery: Creates a query to find a group's members
CSIdentityCreatePersistentReference: Create an opaque, persistent data reference to an identity
CSIdentityDelete: Permanently delete an identity from the identity database
CSIdentityGetAliases: Retrieve the aliases of an identity.
CSIdentityGetAuthority: Returns the identity authority of an identity
CSIdentityGetCertificate: Get a user's authentication certificate
CSIdentityGetClass: Returns an identity's class
CSIdentityGetEmailAddress: Retrieve the email address of a user identity
CSIdentityGetFullName: Retrieve the full name of an identity
CSIdentityGetImageData: Retrieve the image associated with a user identity
CSIdentityGetImageDataType: Retrieve the uniform type identifier (UTI) of an identity's image
CSIdentityGetImageURL: Retrieve the URL to an identity's image file
CSIdentityGetPosixID: Retrieve POSIX ID of an identity.
CSIdentityGetPosixName: Retrieve the POSIX name (short name) of an identity.
CSIdentityGetTypeID: Returns the CSIdentity type identifier
CSIdentityGetUUID: Returns an identity's UUID.
CSIdentityIsCommitting: Determine if a commit operation is in progress
CSIdentityIsEnabled: Determine if a user is enabled
CSIdentityIsHidden: Determine if a identity's hidden attribute is enabled
CSIdentityIsMemberOfGroup: Check if an identity is a memeber of a group
CSIdentityRemoveAlias: Remove an alias name from an identity
CSIdentityRemoveClient: Invalidate an identity's client structure to stop client callbacks
CSIdentityRemoveMember: Remove a member from a group
CSIdentitySetCertificate: Set a user's authentication certificate
CSIdentitySetEmailAddress: Set an identity's email address
CSIdentitySetFullName: Sets an identity's full name.
CSIdentitySetImageData: Set the internally-stored image data and data type for an identity
CSIdentitySetImageURL: Set the URL of an identity's external image storage
CSIdentitySetIsEnabled: Enable or disable a user
CSIdentitySetPassword: Set a user password

CSIdentityAddAlias

Add a name alias to an identity

extern void CSIdentityAddAlias( 
    CSIdentityRef identity, 
    CFStringRef alias );

Parameters

identity: The identity to access
alias: The alias to add

Discussion

This change must be committed.

CSIdentityAddMember

Add an identity to a group

extern void CSIdentityAddMember( 
    CSIdentityRef group, 
    CSIdentityRef member );

Parameters

group: The group identity to access
member: The identity to add to the group. Can be a user or group identity.

Discussion

This change to the group must be committed.

CSIdentityAuthenticateUsingPassword

Attempt to autenticate a password for a user identity

extern Boolean CSIdentityAuthenticateUsingPassword( 
    CSIdentityRef user, 
    CFStringRef password );

Parameters

user: The user identity to access
password: The password to authenticate

Return Value

Returns true if the passord is correct for the specified user

CSIdentityCommit

Synchronously commit all pending changes to the identity authority database

extern Boolean CSIdentityCommit( 
    CSIdentityRef identity, 
    AuthorizationRef authorization, 
    CFErrorRef *error );

Parameters

identity: The identity to commit
authorization: The authorization object holding credentials necessary to allow modification to the identity database. As a convenience, callers may pass NULL for the authorization, and the implmentation will attempt to acquire the necessary credentials from Authorization Services.
error: Optional pointer to a CFErrorRef which will be set if this function returns false. When this occurs, the caller is responsible for releasing the error.

Return Value

Returns true if successful, false if an error occurred

CSIdentityCommitAsynchronously

Asychronously commit all pending changes to the identity authority's database

extern Boolean CSIdentityCommitAsynchronously( 
    CSIdentityRef identity, 
    const CSIdentityClientContext *clientContext, 
    CFRunLoopRef runLoop, 
    CFStringRef runLoopMode, 
    AuthorizationRef authorization );

Parameters

identity: The identity to commit
clientContext: The client structure specifying context and callbacks for the asynchronous operation
runLoop: The run loop on which to schedule the statusUpdated callback
runLoopMode: The run loop mode in which the callback can be scheduled
authorization: The authorization object holding credentials necessary to allow modification to the identity database. As a convenience, callers may pass NULL for the authorization, and the implmentation will attempt to acquire the necessary credentials from Authorization Services. Modifying the local system identity database requires Admin credentials.

Return Value

Returns true if the commit operation is started, indicated that an statusUpdated callback will follow. Returns false if the identity has no uncommitted changes or a commit is already in progress

CSIdentityCreate

Creates a new identity

extern CSIdentityRef CSIdentityCreate( 
    CFAllocatorRef allocator, 
    CSIdentityClass identityClass, 
    CFStringRef fullName, 
    CFStringRef posixName, 
    CSIdentityFlags flags, 
    CSIdentityAuthorityRef authority );

Parameters

allocator: The allocator to use when creating the object. NULL is equivalent to specifying kCFAllocatorDefault.
identityClass: The type of identity to be created. Specifying kCSIdentityClassUser creates a user, while kCSIdentityClassGroup creates a group.
fullName: The primary name of the new identity.
posixName: The POSIX name of the new identity. Specify kCSIdentityGeneratePosixName to have a name generated autmatically from the full name.
flags: A CSIdentityFlags mask defining attributes of the new identity
authority: The identity authority to host the identity. Caller must have write access to the identity authority or commit will fail. Currently, only local identities may be created, so callers must specify the local identity authority for this argument.

Return Value

The CSIdentityRef of the newly created identity object. Returns NULL only if allocation fails.

Discussion

The new identity is allocated but is not committed to the identity authority's database. It will become persistent and available to other clients after being committed using CSIdentityCommit or CSIdentityCommitAsynchronously.

CSIdentityCreateCopy

Creates a copy of an identity

extern CSIdentityRef CSIdentityCreateCopy( 
    CFAllocatorRef allocator, 
    CSIdentityRef identity );

Parameters

allocator: The allocator to use for the new identity. NULL is equivalent to specifying kCFAllocatorDefault.
identity: The identity to copy

Return Value

The CSIdentityRef of the newly created identity object

CSIdentityCreateGroupMembershipQuery

Creates a query to find a group's members

extern CSIdentityQueryRef CSIdentityCreateGroupMembershipQuery( 
    CFAllocatorRef allocator, 
    CSIdentityRef group );

Parameters

allocator: The allocator to use for the query
group: The group identity whose members are to be queried

Return Value

The CSIdentityQueryRef of the newly created object. The query is ready to be executed.

Discussion

Using a query to lookup group membership allows the caller to execute the query synchronously or asynchronously.

CSIdentityCreatePersistentReference

Create an opaque, persistent data reference to an identity

extern CFDataRef CSIdentityCreatePersistentReference( 
    CFAllocatorRef allocator, 
    CSIdentityRef identity );

Parameters

allocator: The allocator for the data
identity: The identity to reference

Return Value

Returns a new persistent reference for the identity

Discussion

A persistent identity reference is an opaque data object from which an identity object may queried the future (see CSIdentityQueryCreateForPersistentReference). A persistent reference is suitable for storage in an external data store, for example, as an entry in an application-specific access control list associated with a shared resource. Use of a persistent identity reference is preferred over a pure UUID-based identity reference because the persistent reference contains additional information needed to optimize the identity query and to improve the user experience when working in a distributed identity environment (LDAP, Active Directory, etc.).

CSIdentityDelete

Permanently delete an identity from the identity database

extern void CSIdentityDelete( 
    CSIdentityRef identity );

Parameters

identity: The identity to delete

Discussion

Sets an identity to deleted state. This change must be committed.

CSIdentityGetAliases

Retrieve the aliases of an identity.

extern CFArrayRef CSIdentityGetAliases( 
    CSIdentityRef identity );

Parameters

identity: The identity to access

Return Value

Returns an array containing the identity's name aliases as CFStringRefs. The array may be empty. The identity object may release its reference to the return value when the identity is modified.

Discussion

Aliases are alternate names for identities. As with all identity names, aliases must be unique within the entire namespace of of the identity authority.

CSIdentityGetAuthority

Returns the identity authority of an identity

extern CSIdentityAuthorityRef CSIdentityGetAuthority( 
    CSIdentityRef identity );

Parameters

identity: The identity object to access

Return Value

A CSIdentityAuthorityRef object

CSIdentityGetCertificate

Get a user's authentication certificate

extern SecCertificateRef CSIdentityGetCertificate( 
    CSIdentityRef user );

Parameters

user: The user identity to access

Return Value

The identity's certificate, or NULL if there is no certificate. The identity object may release its reference to the return value when the identity is modified.

Discussion

The authentication certificate can be used in PKI-based protocols to authenticate users.

CSIdentityGetClass

Returns an identity's class

extern CSIdentityClass CSIdentityGetClass( 
    CSIdentityRef identity );

Parameters

identity: The identity object to access

Return Value

The CSIdentityClass of an identity

CSIdentityGetEmailAddress

Retrieve the email address of a user identity

extern CFStringRef CSIdentityGetEmailAddress( 
    CSIdentityRef identity );

Parameters

identity: The identity to access

Return Value

Returns the email address of the identity or NULL if there is no email address. The identity object may release its reference to the return value when the identity is modified.

CSIdentityGetFullName

Retrieve the full name of an identity

extern CFStringRef CSIdentityGetFullName( 
    CSIdentityRef identity );

Parameters

identity: The identity object to access

Return Value

Returns an identity's full name as a CFStringRef. This attribute is always non-NULL. The identity object may release its reference to the return value when the identity is modified.

Discussion

The full name is the name that is displayed in the user interface.

CSIdentityGetImageData

Retrieve the image associated with a user identity

extern CFDataRef CSIdentityGetImageData( 
    CSIdentityRef identity );

Parameters

identity: The identity to access

Return Value

Returns the identity's image data as a CFDataRef or NULL if there is no image data. The identity object may release its reference to the return value when the identity is modified.

CSIdentityGetImageDataType

Retrieve the uniform type identifier (UTI) of an identity's image

extern CFStringRef CSIdentityGetImageDataType( 
    CSIdentityRef identity );

Parameters

identity: The identity to access

Return Value

Returns a UTI as a CFStringRef for this identity's image data or NULL if there is no image data. The identity object may release its reference to the return value when the identity is modified.

CSIdentityGetImageURL

Retrieve the URL to an identity's image file

extern CFURLRef CSIdentityGetImageURL( 
    CSIdentityRef identity );

Parameters

identity: The identity to access

Return Value

Returns a CFURLRef that contains the location of the user's image file, or NULL if there is no image URL. The identity object may release its reference to the return value when the identity is modified.

CSIdentityGetPosixID

Retrieve POSIX ID of an identity.

extern id_t CSIdentityGetPosixID( 
    CSIdentityRef identity );

Parameters

identity: The identity to access

Return Value

Returns an identity's POSIX identifier (a UID or GID).

CSIdentityGetPosixName

Retrieve the POSIX name (short name) of an identity.

extern CFStringRef CSIdentityGetPosixName( 
    CSIdentityRef identity );

Parameters

identity: The identity object to access.

Return Value

Returns an identity's POSIX name. This attribute is always non-NULL. The identity object may release its reference to the return value when the identity is modified.

Discussion

The POSIX name cannot be changed after an identity has been created.

CSIdentityGetTypeID

Returns the CSIdentity type identifier

extern CFTypeID CSIdentityGetTypeID(
    void );

Return Value

The CFTypeID of the CSIdentity Core Foundation type

CSIdentityGetUUID

Returns an identity's UUID.

extern CFUUIDRef CSIdentityGetUUID( 
    CSIdentityRef identity );

Parameters

identity: The identity object to access

Return Value

A CFUUID object containing identity's UUID. Will never return NULL.

CSIdentityIsCommitting

Determine if a commit operation is in progress

extern Boolean CSIdentityIsCommitting( 
    CSIdentityRef identity );

Parameters

identity: The identity to access

Return Value

Returns true if a commit operation is in progress

CSIdentityIsEnabled

Determine if a user is enabled

extern Boolean CSIdentityIsEnabled(
    CSIdentityRef user );

Parameters

user: The user identity to access

Return Value

Returns true if the user is enabled. A user that is not enabled cannot authenticate.

Discussion

A user that is not enabled cannot authenticate. This setting may be used to temporarily allow a user's access to all services and resources.

CSIdentityIsHidden

Determine if a identity's hidden attribute is enabled

extern Boolean CSIdentityIsHidden(
    CSIdentityRef identity );

Parameters

identity: The identity object to access

Return Value

Returns true if the identity was created with the hidden attribute

CSIdentityIsMemberOfGroup

Check if an identity is a memeber of a group

extern Boolean CSIdentityIsMemberOfGroup( 
    CSIdentityRef identity, 
    CSIdentityRef group );

Parameters

identity: The identity whose membership is in question
group: The group identity whose membership is to be checked

Return Value

Returns true if the identity is a member (directly or indirectly) of the specified group

CSIdentityRemoveAlias

Remove an alias name from an identity

extern void CSIdentityRemoveAlias( 
    CSIdentityRef identity, 
    CFStringRef alias );

Parameters

identity: The identity to access
alias: The alias name to remove

Discussion

This change must be committed.

CSIdentityRemoveClient

Invalidate an identity's client structure to stop client callbacks

extern void CSIdentityRemoveClient( 
    CSIdentityRef identity );

Parameters

identity: The identity to access

Discussion

After returning, this function guarantees that client callbacks will never be invoked again. Use this function when releasing an identity which may have an outstanding asynchronous request. This function does not cancel an outstanding commit operation because a commit cannot be interrupted.

CSIdentityRemoveMember

Remove a member from a group

extern void CSIdentityRemoveMember( 
    CSIdentityRef group, 
    CSIdentityRef member );

Parameters

group: The group identity to access
member: The member identity to remove

Discussion

This change to the group must be committed.

CSIdentitySetCertificate

Set a user's authentication certificate

extern void CSIdentitySetCertificate( 
    CSIdentityRef user, 
    SecCertificateRef certificate );

Parameters

user: The user identity to access
certificate: The user's certificate, or NULL to remove the current certificate

Discussion

The subject name in the certificate will function as an alias for the identity. As with all identity names, the subject name must be unique within the entire name space of the identity authority. This change must be submitted.

CSIdentitySetEmailAddress

Set an identity's email address

extern void CSIdentitySetEmailAddress( 
    CSIdentityRef identity, 
    CFStringRef emailAddress );

Parameters

identity: The user identity to access
emailAddress: The user's new email address value. Pass NULL to remove an email address.

Discussion

This change must be committed.

CSIdentitySetFullName

Sets an identity's full name.

extern void CSIdentitySetFullName( 
    CSIdentityRef identity, 
    CFStringRef fullName );

Parameters

identity: The identity object to access
fullName: The new full name of the identity

Discussion

This change must be committed.

CSIdentitySetImageData

Set the internally-stored image data and data type for an identity

extern void CSIdentitySetImageData( 
    CSIdentityRef identity, 
    CFDataRef imageData, 
    CFStringRef imageDataType );

Parameters

identity: The identity to access
imageData: The image data. Pass NULL to remove image data.
imageDataType: The uniform type identitier (UTI) of the image data. Currently, kUTTypeJPEG ("public.jpeg") is the only type supported.

Discussion

This change must be committed.

CSIdentitySetImageURL

Set the URL of an identity's external image storage

extern void CSIdentitySetImageURL( 
    CSIdentityRef identity, 
    CFURLRef url );

Parameters

identity: The identity to access
url: The URL file of the image. For local identities, this must be a file URL. Pass NULL to remove the image URL from the identity.

Discussion

This change must be committed.

CSIdentitySetIsEnabled

Enable or disable a user

 extern void CSIdentitySetIsEnabled(
    CSIdentityRef user,
    Boolean isEnabled );

Parameters

user: The identity object to access
isEnabled: The new value of the isEnabled attribute

Discussion

A disabled user account cannot authenticate. Credentials (password and certificate) are not affected. This change must be committed.

CSIdentitySetPassword

Set a user password

extern void CSIdentitySetPassword( 
    CSIdentityRef user, 
    CFStringRef password );

Parameters

user: The user identity to access
password: The new password, or NULL to remove the current password and disable password-based authentication

Discussion

Setting the password to NULL removes the current password and disables password authentication for the user. Setting the password to a zero-length string allows authentication with a blank password. This change must be committed.

Typedefs

CSIdentityQueryRef

typedef opaque CSIdentityQueryRef;

Discussion

A reference to an identity query object, used to lookup identities in an identity authority's database.

CSIdentityRef

typedef opaque CSIdentityRef;

Discussion

A reference to an identity object. Can be either a user or group.

Structs and Unions

CSIdentityClientContext

struct CSIdentityClientContext { 
    CFIndex version; 
    void *info; 
    CFAllocatorRetainCallBack retain; 
    CFAllocatorReleaseCallBack release; 
    CFAllocatorCopyDescriptionCallBack copyDescription; 
    CSIdentityStatusUpdatedCallback statusUpdated; 
};

Fields

version
The version number of the client structure type. The current version number is 0.

info
An arbitrary pointer to client-defined data, which can be associated with the client and is passed to the callbacks.

retain
The callback used to add a retain for the on the client object for the life of the asynchronous operation, and may be used for temporary references the identity needs to take. This callback returns the actual info pointer to be passed to the statusUpdated callback. May be NULL.

release
The callback used to remove a retain previously acquired for the client object. May be NULL.

copyDescription
The callback used to create a descriptive string representation of the client object for debugging purposes. This is used by the CFCopyDescription() function. May be NULL.

statusUpdated
The client callback invoked when the status of an asnchronous operation changes

Discussion

Structure containing the user-defined data and callbacks used during asynchronous commits

Enumerations

CSIdentity error codes

enum { 
    kCSIdentityUnknownAuthorityErr = -1, 
    kCSIdentityAuthorityNotAccessibleErr = -2, 
    kCSIdentityPermissionErr = -3, 
    kCSIdentityDeletedErr = -4, 
    kCSIdentityInvalidFullNameErr = -5, 
    kCSIdentityDuplicateFullNameErr = -6, 
    kCSIdentityInvalidPosixNameErr = -7, 
    kCSIdentityDuplicatePosixNameErr = -8 
};

Constants

kCSIdentityUnknownAuthorityErr
The specified authority is not recognized

kCSIdentityAuthorityNotAccessibleErr
The specified authority is currently not accessible

kCSIdentityPermissionErr
The caller does not have permission to perform the operation

kCSIdentityDeletedErr
The requested identity has been deteled

kCSIdentityInvalidFullNameErr
The full name is not valid (length: [1-255])

kCSIdentityDuplicateFullNameErr
The full name is aleady assigned to another identity

kCSIdentityInvalidPosixNameErr
The Posix name is not valid (char set: [a-zA-Z0-9_-] length: [1-255])

kCSIdentityDuplicatePosixNameErr
The Posix name is aleady assigned to another identity

Discussion

Error codes in the CSIdentity error domain

CSIdentityClass

enum { 
    kCSIdentityClassUser = 1, 
    kCSIdentityClassGroup = 2 
};

Constants

kCSIdentityClassUser
The class value for user identities

kCSIdentityClassGroup
The class value for group identities

Discussion

Enum specifying an identity class

CSIdentityFlags

enum { 
    kCSIdentityFlagNone = 0, 
    kCSIdentityFlagHidden = 1 
};

Constants

kCSIdentityFlagNone
Use this flag to set no optional attributes for a new identity

kCSIdentityFlagHidden
This flag causes the identity to be "hidden," that is, excluded from most user-visible identity lists. Hidden identities include administrative users and groups such as root, www, and mysql. System service access control groups should be created with the hidden flag.

Discussion

Flags used when creating new identities

Status

enum { 
    kCSIdentityCommitCompleted = 1 
};

Constants

kCSIdentityCommitCompleted
The identity has been committed to the authority database

Discussion

values

Did this document help you?

Yes: Tell us what works for you.

It’s good, but: Report typos, inaccuracies, and so forth.

It wasn’t helpful: Tell us what would have helped.

Last Updated: 2008-03-11