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

 


CSIdentity

Framework:
/System/Library/Frameworks/CoreServices.framework/Frameworks/OSServices.framework
See Also:
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 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

Last Updated: 2008-03-11