membership.subproj/membership.h

   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 */
 129 int 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 */
 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
 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
 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 */
 231 int 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 */
 247 int mbr_check_service_membership(const uuid_t user, const char *servicename,
 248                                                                  int *ismember);
 249
 250 __END_DECLS
 251
 252 #endif /* !_MEMBERSHIP_H_ */