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@
21 */
22
23#ifndef _MEMBERSHIP_H_
24#define _MEMBERSHIP_H_
25
26#include <uuid/uuid.h>
27#include <ntsid.h>
28
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
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
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
112
113__BEGIN_DECLS
114
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*/
129int mbr_uid_to_uuid(uid_t uid, uuid_t uu);
130
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*/
145int 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*/
156int 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*/
170int 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*/
187int 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*/
197int mbr_uuid_to_sid(const uuid_t uu, nt_sid_t* sid);
198
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 */
208int 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 */
218int mbr_string_to_sid(const char *string, nt_sid_t *sid);
219
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*/
231int mbr_check_membership(const uuid_t user, const uuid_t group, int* ismember);
232
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*/
247int mbr_check_service_membership(const uuid_t user, const char *servicename,
248								 int *ismember);
249
250__END_DECLS
251
252#endif /* !_MEMBERSHIP_H_ */
253