CSIdentity

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 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

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.

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.

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

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

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

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.

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

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.

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.).

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.

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.

Returns the identity authority of an identity

extern CSIdentityAuthorityRef CSIdentityGetAuthority( 
    CSIdentityRef identity );  

Parameters

identity

The identity object to access

Return Value

A CSIdentityAuthorityRef object

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.

Returns an identity's class

extern CSIdentityClass CSIdentityGetClass( 
    CSIdentityRef identity );  

Parameters

identity

The identity object to access

Return Value

The CSIdentityClass of an identity

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.

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.

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.

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.

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.

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).

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.

Returns the CSIdentity type identifier

extern CFTypeID CSIdentityGetTypeID(
    void );  

Return Value

The CFTypeID of the CSIdentity Core Foundation type

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.

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

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.

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

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

typedef opaque CSIdentityQueryRef;  

Discussion

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

typedef opaque CSIdentityRef;  

Discussion

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

Structs and Unions

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

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

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

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

enum { 
    kCSIdentityCommitCompleted = 1 
};  

Constants

kCSIdentityCommitCompleted

The identity has been committed to the authority database

Discussion

values