[apple/libinfo.git] / membership.subproj / membership.h

/*
 * Copyright (c) 2004 Apple Computer, Inc. All rights reserved.
 *
 * @APPLE_LICENSE_HEADER_START@
 *
 * The contents of this file constitute Original Code as defined in and
 * are subject to the Apple Public Source License Version 1.1 (the
 * "License").  You may not use this file except in compliance with the
 * License.  Please obtain a copy of the License at
 * http://www.apple.com/publicsource and read it before using this file.
 *
 * This Original Code and all software distributed under the License are
 * distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT.  Please see the
 * License for the specific language governing rights and limitations
 * under the License.
 *
 * @APPLE_LICENSE_HEADER_END@
 */

#ifndef _MEMBERSHIP_H_
#define _MEMBERSHIP_H_

#include <uuid/uuid.h>
#include <ntsid.h>

/*!
	@defined    ID_TYPE_UID
	@abstract   is of type uid_t
	@discussion is of type uid_t
*/
#define ID_TYPE_UID				0

/*!
	@defined    ID_TYPE_GID
	@abstract   is of type gid_t
	@discussion is of type gid_t
*/
#define ID_TYPE_GID				1

/*!
    @defined    ID_TYPE_SID
    @abstract   is of type ntsid_t
    @discussion is of type ntsid_t
*/
#define ID_TYPE_SID				3

/*!
    @defined    ID_TYPE_USERNAME
    @abstract   is a NULL terminated UTF8 string
    @discussion is a NULL terminated UTF8 string
*/
#define ID_TYPE_USERNAME		4

/*!
    @defined    ID_TYPE_GROUPNAME
    @abstract   is a NULL terminated UTF8 string
    @discussion is a NULL terminated UTF8 string
*/
#define ID_TYPE_GROUPNAME		5

/*!
	@defined	ID_TYPE_UUID
	@abstract	is of type uuid_t
	@discussion	is of type uuid_t
*/
#define ID_TYPE_UUID			6

/*!
    @defined    ID_TYPE_GROUP_NFS
    @abstract   is a NULL terminated UTF8 string
    @discussion is a NULL terminated UTF8 string
*/
#define ID_TYPE_GROUP_NFS	7

/*!
    @defined    ID_TYPE_USER_NFS
    @abstract   is a NULL terminated UTF8 string
    @discussion is a NULL terminated UTF8 string
*/
#define ID_TYPE_USER_NFS		8

/*!
	@defined    ID_TYPE_GSS_EXPORT_NAME
	@abstract	is a gss exported name
	@discussion	is the data in gss_buffer_t as returned from gss_export_name.
*/
#define ID_TYPE_GSS_EXPORT_NAME	10

/*!
	@defined    ID_TYPE_X509_DN
	@abstract	is a NULL terminated string representation of the X.509 certificate identity
	@discussion	is a NULL terminated string with the format of:
 
				<I>DN of the Certificate authority<S>DN of the holder
 
				Example:
 
				<I>DC=com,DC=example,CN=CertificatAuthority<S>DC=com,DC=example,CN=username
*/
#define ID_TYPE_X509_DN			11

/*!
	@defined    ID_TYPE_KERBEROS
	@abstract	is a NULL terminated string representation of a Kerberos principal
	@discussion	is a NULL terminated string in the form of user\@REALM representing a typical 
				Kerberos principal.
*/
#define ID_TYPE_KERBEROS		12

__BEGIN_DECLS

/*!
	@function   mbr_uid_to_uuid
	@abstract	convert a UID to a corresponding UUID
	@discussion	will convert a UID of a user to a corresponding UUID value.
				This call will always succeed and may return a synthesized
				UUID with the prefix FFFFEEEE-DDDD-CCCC-BBBB-AAAAxxxxxxxx,
				where 'xxxxxxxx' is a hex conversion of the UID. The returned
				UUID can be used for any operation including ACL and SACL
				memberships, even if a UUID is later assigned to the user
				record.
	@param		uid the uid_t to be converted
	@param		uu is the UUID found for the provided UID
	@result		returns 0 on success or appropriate errno code.
*/
int mbr_uid_to_uuid(uid_t uid, uuid_t uu);

/*!
	@function   mbr_gid_to_uuid
	@abstract   convert a GID to a corresponding UUID
	@discussion will convert a GID of a group to a corresponding UUID value.
				This call will always succeed and may return a synthesized
				UUID with the prefix AAAABBBB-CCCC-DDDD-EEEE-FFFFxxxxxxxx,
				where 'xxxxxxxx' is a hex conversion of the UID. The returned
				UUID can be used for any operation including ACL and SACL
				memberships, even if a UUID is later assigned to the group
				record.
	@param		gid the gid_t to be converted
	@param		uu is the UUID found for the provided GID
	@result		returns 0 on success or appropriate errno code.
*/
int mbr_gid_to_uuid(gid_t gid, uuid_t uu);

/*!
	@function   mbr_sid_to_uuid
	@abstract	convert a SID to a corresponding UUID
	@discussion will convert a SID to a corresponding UUID value. This call
				can fail for records that do not have a valid SID or RID.
	@param		sid the nt_sid_t to be converted
	@param		uu is the UUID found for the provided GID
	@result		returns 0 on success or appropriate errno code.
*/
int mbr_sid_to_uuid(const nt_sid_t* sid, uuid_t uu);

/*!
	@function	mbr_identifier_to_uuid
	@abstract	resolves various identifiers to corresponding UUID
	@discussion	will resolve various identifiers such as X.509 Distinguished 
				Names, Kerberos ID or other forms of security identifiers to a
				corresponding UUID.
	@param		id_type is one of the defined types
	@param		identifier is a generic pointer as defined by the type
	@param		identifier_size is the size of the data pointed to in identifier
	@param		uu is the UUID found for the identifier
	@result		returns 0 on success or appropriate errno code.
*/
int mbr_identifier_to_uuid(int id_type, const void *identifier, size_t identifier_size,
						   uuid_t uu);

/*!
	@function	mbr_uuid_to_id
	@abstract	resolves a UUID to a corresponding ID and type
	@discussion	will resolve a UUID to a corresponding GID or UID and return
				the type of ID (ID_TYPE_UID or ID_TYPE_GID).  Synthesized
				UUID values will be directly translated to corresponding ID.
				A UID will always be returned even if the UUID is not found.  
				The returned ID is not persistant, but can be used to map back
				to the UUID during runtime.
	@param		uu is the UUID to be resolved
	@param		uid_or_gid is the UID or GID found for the UUID
	@param		id_type is the type of ID
	@result		returns 0 on success or appropriate errno code.
*/
int mbr_uuid_to_id(const uuid_t uu, id_t* uid_or_gid, int* id_type);

/*!
	@function	mbr_uuid_to_sid
	@abstract	resolves a UUID to a corresponding SID
	@discussion will resolve a UUID to a corresponding SID.
	@param		uu is the UUID to be resolved
	@param		sid is the SID found for the UUID
	@result		returns 0 on success or appropriate errno code.
*/
int mbr_uuid_to_sid(const uuid_t uu, nt_sid_t* sid);

/*!
	@function	mbr_sid_to_string
	@abstract	convert a SID to a corresponding character string representation
	@discussion for use in situations where an external representation of a SID is required.
	@param		sid is the SID to be converted
	@param		string is a buffer that will be filled in with a nul-terminated string
				representation of the SID.  The buffer must be at least 194 characters in length.
	@result    returns 0 on success or appropriate errno code.
 */
int mbr_sid_to_string(const nt_sid_t *sid, char *string);

/*!
	@function	mbr_string_to_sid
	@abstract	convert a character string representation of a sid to an nt_sid_t value
	@discussion for converting an external representation of a sid.
	@param		string is a buffer containing a nul-terminated string representation of a SID
	@param		sid is the target of the conversion
	@result    returns 0 on success or appropriate errno code.
 */
int mbr_string_to_sid(const char *string, nt_sid_t *sid);

/*!
	@function	mbr_check_membership
	@abstract	checks if a user is a member of a group
	@discussion	will check if a user is a member of a group either through
				direct membership or via nested group membership.
	@param		user is the UUID of the user in question
	@param		group is the UUID of the group to be checked
	@param		ismember is set to 1 if user is a member of the group,
				otherwise 0 is returned
	@result		returns 0 on success or appropriate errno code.
*/
int mbr_check_membership(const uuid_t user, const uuid_t group, int* ismember);

/*!
	@function	mbr_check_service_membership
	@abstract   checks if a user is part of a service group
	@discussion will check if a user is a member of a service access group.
				The servicename provided will be automatically prefixed with
				"com.apple.access_" (e.g., "afp" becomes "com.apple.access_afp").
				In addition a special service group "com.apple.access_all_services"
				will be checked in addition to the specific service.
	@param		user is the UUID of the user in question
	@param		servicename is the service type (e.g., "afp", "ftp", etc.)
	@param		ismember is set to 1 if user is a member of the group,
				otherwise 0 is returned
	@result		returns 0 on success or appropriate errno code.
*/
int mbr_check_service_membership(const uuid_t user, const char *servicename, 
								 int *ismember);

__END_DECLS

#endif /* !_MEMBERSHIP_H_ */
Commit	Line	Data
c29f2fcc A	1	/*
	2	* Copyright (c) 2004 Apple Computer, Inc. All rights reserved.
	3	*
	4	* @APPLE_LICENSE_HEADER_START@
	5	*
	6	* The contents of this file constitute Original Code as defined in and
	7	* are subject to the Apple Public Source License Version 1.1 (the
	8	* "License"). You may not use this file except in compliance with the
	9	* License. Please obtain a copy of the License at
	10	* http://www.apple.com/publicsource and read it before using this file.
	11	*
	12	* This Original Code and all software distributed under the License are
	13	* distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
	14	* EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
	15	* INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
	16	* FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT. Please see the
	17	* License for the specific language governing rights and limitations
	18	* under the License.
	19	*
	20	* @APPLE_LICENSE_HEADER_END@
d49d4c81	21	*/
c29f2fcc A	22
	23	#ifndef _MEMBERSHIP_H_
	24	#define _MEMBERSHIP_H_
	25
	26	#include <uuid/uuid.h>
	27	#include <ntsid.h>
	28
d49d4c81 A	29	/*!
	30	@defined ID_TYPE_UID
	31	@abstract is of type uid_t
	32	@discussion is of type uid_t
	33	*/
	34	#define ID_TYPE_UID 0
	35
	36	/*!
	37	@defined ID_TYPE_GID
	38	@abstract is of type gid_t
	39	@discussion is of type gid_t
	40	*/
	41	#define ID_TYPE_GID 1
	42
	43	/*!
	44	@defined ID_TYPE_SID
	45	@abstract is of type ntsid_t
	46	@discussion is of type ntsid_t
	47	*/
	48	#define ID_TYPE_SID 3
	49
	50	/*!
	51	@defined ID_TYPE_USERNAME
	52	@abstract is a NULL terminated UTF8 string
	53	@discussion is a NULL terminated UTF8 string
	54	*/
	55	#define ID_TYPE_USERNAME 4
	56
	57	/*!
	58	@defined ID_TYPE_GROUPNAME
	59	@abstract is a NULL terminated UTF8 string
	60	@discussion is a NULL terminated UTF8 string
	61	*/
	62	#define ID_TYPE_GROUPNAME 5
	63
d31dd049 A	64	/*!
	65	@defined ID_TYPE_UUID
	66	@abstract is of type uuid_t
	67	@discussion is of type uuid_t
	68	*/
	69	#define ID_TYPE_UUID 6
	70
	71	/*!
	72	@defined ID_TYPE_GROUP_NFS
	73	@abstract is a NULL terminated UTF8 string
	74	@discussion is a NULL terminated UTF8 string
	75	*/
	76	#define ID_TYPE_GROUP_NFS 7
	77
	78	/*!
	79	@defined ID_TYPE_USER_NFS
	80	@abstract is a NULL terminated UTF8 string
	81	@discussion is a NULL terminated UTF8 string
	82	*/
	83	#define ID_TYPE_USER_NFS 8
	84
d49d4c81 A	85	/*!
	86	@defined ID_TYPE_GSS_EXPORT_NAME
	87	@abstract is a gss exported name
	88	@discussion is the data in gss_buffer_t as returned from gss_export_name.
	89	*/
	90	#define ID_TYPE_GSS_EXPORT_NAME 10
	91
	92	/*!
	93	@defined ID_TYPE_X509_DN
	94	@abstract is a NULL terminated string representation of the X.509 certificate identity
	95	@discussion is a NULL terminated string with the format of:
	96
	97	<I>DN of the Certificate authority<S>DN of the holder
	98
	99	Example:
	100
	101	<I>DC=com,DC=example,CN=CertificatAuthority<S>DC=com,DC=example,CN=username
	102	*/
	103	#define ID_TYPE_X509_DN 11
	104
	105	/*!
	106	@defined ID_TYPE_KERBEROS
	107	@abstract is a NULL terminated string representation of a Kerberos principal
	108	@discussion is a NULL terminated string in the form of user\@REALM representing a typical
	109	Kerberos principal.
	110	*/
	111	#define ID_TYPE_KERBEROS 12
c29f2fcc A	112
	113	__BEGIN_DECLS
	114
d49d4c81 A	115	/*!
	116	@function mbr_uid_to_uuid
	117	@abstract convert a UID to a corresponding UUID
	118	@discussion will convert a UID of a user to a corresponding UUID value.
	119	This call will always succeed and may return a synthesized
	120	UUID with the prefix FFFFEEEE-DDDD-CCCC-BBBB-AAAAxxxxxxxx,
	121	where 'xxxxxxxx' is a hex conversion of the UID. The returned
	122	UUID can be used for any operation including ACL and SACL
	123	memberships, even if a UUID is later assigned to the user
	124	record.
	125	@param uid the uid_t to be converted
	126	@param uu is the UUID found for the provided UID
	127	@result returns 0 on success or appropriate errno code.
	128	*/
	129	int mbr_uid_to_uuid(uid_t uid, uuid_t uu);
c29f2fcc	130
d49d4c81 A	131	/*!
	132	@function mbr_gid_to_uuid
	133	@abstract convert a GID to a corresponding UUID
	134	@discussion will convert a GID of a group to a corresponding UUID value.
	135	This call will always succeed and may return a synthesized
	136	UUID with the prefix AAAABBBB-CCCC-DDDD-EEEE-FFFFxxxxxxxx,
	137	where 'xxxxxxxx' is a hex conversion of the UID. The returned
	138	UUID can be used for any operation including ACL and SACL
	139	memberships, even if a UUID is later assigned to the group
	140	record.
	141	@param gid the gid_t to be converted
	142	@param uu is the UUID found for the provided GID
	143	@result returns 0 on success or appropriate errno code.
	144	*/
	145	int mbr_gid_to_uuid(gid_t gid, uuid_t uu);
	146
	147	/*!
	148	@function mbr_sid_to_uuid
	149	@abstract convert a SID to a corresponding UUID
	150	@discussion will convert a SID to a corresponding UUID value. This call
	151	can fail for records that do not have a valid SID or RID.
	152	@param sid the nt_sid_t to be converted
	153	@param uu is the UUID found for the provided GID
	154	@result returns 0 on success or appropriate errno code.
	155	*/
	156	int mbr_sid_to_uuid(const nt_sid_t* sid, uuid_t uu);
	157
	158	/*!
	159	@function mbr_identifier_to_uuid
	160	@abstract resolves various identifiers to corresponding UUID
	161	@discussion will resolve various identifiers such as X.509 Distinguished
	162	Names, Kerberos ID or other forms of security identifiers to a
	163	corresponding UUID.
	164	@param id_type is one of the defined types
	165	@param identifier is a generic pointer as defined by the type
	166	@param identifier_size is the size of the data pointed to in identifier
	167	@param uu is the UUID found for the identifier
	168	@result returns 0 on success or appropriate errno code.
	169	*/
	170	int mbr_identifier_to_uuid(int id_type, const void *identifier, size_t identifier_size,
	171	uuid_t uu);
	172
	173	/*!
	174	@function mbr_uuid_to_id
	175	@abstract resolves a UUID to a corresponding ID and type
	176	@discussion will resolve a UUID to a corresponding GID or UID and return
	177	the type of ID (ID_TYPE_UID or ID_TYPE_GID). Synthesized
	178	UUID values will be directly translated to corresponding ID.
	179	A UID will always be returned even if the UUID is not found.
	180	The returned ID is not persistant, but can be used to map back
	181	to the UUID during runtime.
	182	@param uu is the UUID to be resolved
	183	@param uid_or_gid is the UID or GID found for the UUID
	184	@param id_type is the type of ID
	185	@result returns 0 on success or appropriate errno code.
	186	*/
	187	int mbr_uuid_to_id(const uuid_t uu, id_t* uid_or_gid, int* id_type);
	188
	189	/*!
	190	@function mbr_uuid_to_sid
	191	@abstract resolves a UUID to a corresponding SID
	192	@discussion will resolve a UUID to a corresponding SID.
	193	@param uu is the UUID to be resolved
	194	@param sid is the SID found for the UUID
195	@result returns 0 on success or appropriate errno code.
196	*/
197	int mbr_uuid_to_sid(const uuid_t uu, nt_sid_t* sid);
198
e44d8d47 A	199	/*!
	200	@function mbr_sid_to_string
	201	@abstract convert a SID to a corresponding character string representation
	202	@discussion for use in situations where an external representation of a SID is required.
	203	@param sid is the SID to be converted
	204	@param string is a buffer that will be filled in with a nul-terminated string
	205	representation of the SID. The buffer must be at least 194 characters in length.
	206	@result returns 0 on success or appropriate errno code.
	207	*/
	208	int mbr_sid_to_string(const nt_sid_t sid, char string);
	209
	210	/*!
	211	@function mbr_string_to_sid
	212	@abstract convert a character string representation of a sid to an nt_sid_t value
	213	@discussion for converting an external representation of a sid.
	214	@param string is a buffer containing a nul-terminated string representation of a SID
	215	@param sid is the target of the conversion
	216	@result returns 0 on success or appropriate errno code.
	217	*/
	218	int mbr_string_to_sid(const char string, nt_sid_t sid);
	219
d49d4c81 A	220	/*!
	221	@function mbr_check_membership
	222	@abstract checks if a user is a member of a group
	223	@discussion will check if a user is a member of a group either through
	224	direct membership or via nested group membership.
	225	@param user is the UUID of the user in question
	226	@param group is the UUID of the group to be checked
	227	@param ismember is set to 1 if user is a member of the group,
	228	otherwise 0 is returned
	229	@result returns 0 on success or appropriate errno code.
	230	*/
e44d8d47	231	int mbr_check_membership(const uuid_t user, const uuid_t group, int* ismember);
c29f2fcc	232
d49d4c81 A	233	/*!
	234	@function mbr_check_service_membership
	235	@abstract checks if a user is part of a service group
	236	@discussion will check if a user is a member of a service access group.
	237	The servicename provided will be automatically prefixed with
	238	"com.apple.access_" (e.g., "afp" becomes "com.apple.access_afp").
	239	In addition a special service group "com.apple.access_all_services"
	240	will be checked in addition to the specific service.
	241	@param user is the UUID of the user in question
	242	@param servicename is the service type (e.g., "afp", "ftp", etc.)
	243	@param ismember is set to 1 if user is a member of the group,
	244	otherwise 0 is returned
	245	@result returns 0 on success or appropriate errno code.
	246	*/
	247	int mbr_check_service_membership(const uuid_t user, const char *servicename,
	248	int *ismember);
	249
c29f2fcc A	250	__END_DECLS
	251
	252	#endif /* !_MEMBERSHIP_H_ */