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: |
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.
Deletion
- CSIdentityDelete
- Permanently delete an identity from the identity database
changes
- 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
Methods
- CSIdentityAuthenticateUsingPassword
- Attempt to autenticate a password for a user identity
- CSIdentityGetCertificate
- Get a user's authentication certificate
- CSIdentityIsEnabled
- Determine if a user is enabled
Methods
- CSIdentityCreateGroupMembershipQuery
- Creates a query to find a group's members
Identity Attributes
- 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
group membership
- 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
Identities
- CSIdentityCreate
- Creates a new identity
- CSIdentityCreateCopy
- Creates a copy of an identity
- CSIdentitySetIsEnabled
- Enable or disable a user
CSIdentityAddAlias |
Add a name alias to an identity
extern void CSIdentityAddAlias( CSIdentityRef identity, CFStringRef alias );
identity
alias
This change must be committed.
CSIdentityAddMember |
Add an identity to a group
extern void CSIdentityAddMember( CSIdentityRef group, CSIdentityRef member );
group
member
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 );
user
password
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 );
identity
authorization
error
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 );
identity
clientContext
runLoop
runLoopMode
authorization
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 );
allocator
identityClass
fullName
posixName
flags
authority
The CSIdentityRef of the newly created identity object. Returns NULL only if allocation fails.
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 );
allocator
identity
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 );
allocator
group
The CSIdentityQueryRef of the newly created object. The query is ready to be executed.
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 );
allocator
identity
Returns a new persistent reference for the identity
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 );
identity
Sets an identity to deleted state. This change must be committed.
CSIdentityGetAliases |
Retrieve the aliases of an identity.
extern CFArrayRef CSIdentityGetAliases( CSIdentityRef identity );
identity
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.
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 );
identity
A CSIdentityAuthorityRef object
CSIdentityGetCertificate |
Get a user's authentication certificate
extern SecCertificateRef CSIdentityGetCertificate( CSIdentityRef user );
user
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.
The authentication certificate can be used in PKI-based protocols to authenticate users.
CSIdentityGetClass |
Returns an identity's class
extern CSIdentityClass CSIdentityGetClass( CSIdentityRef identity );
identity
The CSIdentityClass of an identity
CSIdentityGetEmailAddress |
Retrieve the email address of a user identity
extern CFStringRef CSIdentityGetEmailAddress( CSIdentityRef identity );
identity
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 );
identity
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.
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 );
identity
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 );
identity
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 );
identity
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 );
identity
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 );
identity
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.
The POSIX name cannot be changed after an identity has been created.
CSIdentityGetTypeID |
Returns the CSIdentity type identifier
extern CFTypeID CSIdentityGetTypeID( void );
The CFTypeID of the CSIdentity Core Foundation type
CSIdentityGetUUID |
Returns an identity's UUID.
extern CFUUIDRef CSIdentityGetUUID( CSIdentityRef identity );
identity
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 );
identity
Returns true if a commit operation is in progress
CSIdentityIsEnabled |
Determine if a user is enabled
extern Boolean CSIdentityIsEnabled( CSIdentityRef user );
user
Returns true if the user is enabled. A user that is not enabled cannot authenticate.
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 );
identity
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 );
identity
group
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 );
identity
alias
This change must be committed.
CSIdentityRemoveClient |
Invalidate an identity's client structure to stop client callbacks
extern void CSIdentityRemoveClient( CSIdentityRef identity );
identity
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 );
group
member
This change to the group must be committed.
CSIdentitySetCertificate |
Set a user's authentication certificate
extern void CSIdentitySetCertificate( CSIdentityRef user, SecCertificateRef certificate );
user
certificate
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 );
identity
emailAddress
This change must be committed.
CSIdentitySetFullName |
Sets an identity's full name.
extern void CSIdentitySetFullName( CSIdentityRef identity, CFStringRef fullName );
identity
fullName
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 );
identity
imageData
imageDataType
This change must be committed.
CSIdentitySetImageURL |
Set the URL of an identity's external image storage
extern void CSIdentitySetImageURL( CSIdentityRef identity, CFURLRef url );
identity
url
This change must be committed.
CSIdentitySetIsEnabled |
Enable or disable a user
extern void CSIdentitySetIsEnabled( CSIdentityRef user, Boolean isEnabled );
user
isEnabled
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 );
user
password
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.
CSIdentityQueryRef |
typedef opaque CSIdentityQueryRef;
A reference to an identity query object, used to lookup identities in an identity authority's database.
CSIdentityRef |
typedef opaque CSIdentityRef;
A reference to an identity object. Can be either a user or group.
CSIdentityClientContext |
struct CSIdentityClientContext { CFIndex version; void *info; CFAllocatorRetainCallBack retain; CFAllocatorReleaseCallBack release; CFAllocatorCopyDescriptionCallBack copyDescription; CSIdentityStatusUpdatedCallback statusUpdated; };
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
Structure containing the user-defined data and callbacks used during asynchronous commits
CSIdentity error codes |
enum { kCSIdentityUnknownAuthorityErr = -1, kCSIdentityAuthorityNotAccessibleErr = -2, kCSIdentityPermissionErr = -3, kCSIdentityDeletedErr = -4, kCSIdentityInvalidFullNameErr = -5, kCSIdentityDuplicateFullNameErr = -6, kCSIdentityInvalidPosixNameErr = -7, kCSIdentityDuplicatePosixNameErr = -8 };
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
Error codes in the CSIdentity error domain
CSIdentityClass |
enum { kCSIdentityClassUser = 1, kCSIdentityClassGroup = 2 };
kCSIdentityClassUser
- The class value for user identities
kCSIdentityClassGroup
- The class value for group identities
Enum specifying an identity class
CSIdentityFlags |
enum { kCSIdentityFlagNone = 0, kCSIdentityFlagHidden = 1 };
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.
Flags used when creating new identities
Status |
enum { kCSIdentityCommitCompleted = 1 };
kCSIdentityCommitCompleted
- The identity has been committed to the authority database
values