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_GSS_EXPORT_NAME
  66         @abstract       is a gss exported name
  67         @discussion     is the data in gss_buffer_t as returned from gss_export_name.
  68 */
  69 #define ID_TYPE_GSS_EXPORT_NAME 10
  70
  71 /*!
  72         @defined    ID_TYPE_X509_DN
  73         @abstract       is a NULL terminated string representation of the X.509 certificate identity
  74         @discussion     is a NULL terminated string with the format of:
  75
  76                                 <I>DN of the Certificate authority<S>DN of the holder
  77
  78                                 Example:
  79
  80                                 <I>DC=com,DC=example,CN=CertificatAuthority<S>DC=com,DC=example,CN=username
  81 */
  82 #define ID_TYPE_X509_DN                 11
  83
  84 /*!
  85         @defined    ID_TYPE_KERBEROS
  86         @abstract       is a NULL terminated string representation of a Kerberos principal
  87         @discussion     is a NULL terminated string in the form of user\@REALM representing a typical
  88                                 Kerberos principal.
  89 */
  90 #define ID_TYPE_KERBEROS                12
  91
  92 __BEGIN_DECLS
  93
  94 /*!
  95         @function   mbr_uid_to_uuid
  96         @abstract       convert a UID to a corresponding UUID
  97         @discussion     will convert a UID of a user to a corresponding UUID value.
  98                                 This call will always succeed and may return a synthesized
  99                                 UUID with the prefix FFFFEEEE-DDDD-CCCC-BBBB-AAAAxxxxxxxx,
 100                                 where 'xxxxxxxx' is a hex conversion of the UID. The returned
 101                                 UUID can be used for any operation including ACL and SACL
 102                                 memberships, even if a UUID is later assigned to the user
 103                                 record.
 104         @param          uid the uid_t to be converted
 105         @param          uu is the UUID found for the provided UID
 106         @result         returns 0 on success or appropriate errno code.
 107 */
 108 int mbr_uid_to_uuid(uid_t uid, uuid_t uu);
 109
 110 /*!
 111         @function   mbr_gid_to_uuid
 112         @abstract   convert a GID to a corresponding UUID
 113         @discussion will convert a GID of a group to a corresponding UUID value.
 114                                 This call will always succeed and may return a synthesized
 115                                 UUID with the prefix AAAABBBB-CCCC-DDDD-EEEE-FFFFxxxxxxxx,
 116                                 where 'xxxxxxxx' is a hex conversion of the UID. The returned
 117                                 UUID can be used for any operation including ACL and SACL
 118                                 memberships, even if a UUID is later assigned to the group
 119                                 record.
 120         @param          gid the gid_t to be converted
 121         @param          uu is the UUID found for the provided GID
 122         @result         returns 0 on success or appropriate errno code.
 123 */
 124 int mbr_gid_to_uuid(gid_t gid, uuid_t uu);
 125
 126 /*!
 127         @function   mbr_sid_to_uuid
 128         @abstract       convert a SID to a corresponding UUID
 129         @discussion will convert a SID to a corresponding UUID value. This call
 130                                 can fail for records that do not have a valid SID or RID.
 131         @param          sid the nt_sid_t to be converted
 132         @param          uu is the UUID found for the provided GID
 133         @result         returns 0 on success or appropriate errno code.
 134 */
 135 int mbr_sid_to_uuid(const nt_sid_t* sid, uuid_t uu);
 136
 137 /*!
 138         @function       mbr_identifier_to_uuid
 139         @abstract       resolves various identifiers to corresponding UUID
 140         @discussion     will resolve various identifiers such as X.509 Distinguished
 141                                 Names, Kerberos ID or other forms of security identifiers to a
 142                                 corresponding UUID.
 143         @param          id_type is one of the defined types
 144         @param          identifier is a generic pointer as defined by the type
 145         @param          identifier_size is the size of the data pointed to in identifier
 146         @param          uu is the UUID found for the identifier
 147         @result         returns 0 on success or appropriate errno code.
 148 */
 149 int mbr_identifier_to_uuid(int id_type, const void *identifier, size_t identifier_size,
 150                                                    uuid_t uu);
 151
 152 /*!
 153         @function       mbr_uuid_to_id
 154         @abstract       resolves a UUID to a corresponding ID and type
 155         @discussion     will resolve a UUID to a corresponding GID or UID and return
 156                                 the type of ID (ID_TYPE_UID or ID_TYPE_GID).  Synthesized
 157                                 UUID values will be directly translated to corresponding ID.
 158                                 A UID will always be returned even if the UUID is not found.
 159                                 The returned ID is not persistant, but can be used to map back
 160                                 to the UUID during runtime.
 161         @param          uu is the UUID to be resolved
 162         @param          uid_or_gid is the UID or GID found for the UUID
 163         @param          id_type is the type of ID
 164         @result         returns 0 on success or appropriate errno code.
 165 */
 166 int mbr_uuid_to_id(const uuid_t uu, id_t* uid_or_gid, int* id_type);
 167
 168 /*!
 169         @function       mbr_uuid_to_sid
 170         @abstract       resolves a UUID to a corresponding SID
 171         @discussion will resolve a UUID to a corresponding SID.
 172         @param          uu is the UUID to be resolved
 173         @param          sid is the SID found for the UUID
 174         @result         returns 0 on success or appropriate errno code.
 175 */
 176 int mbr_uuid_to_sid(const uuid_t uu, nt_sid_t* sid);
 177
 178 /*!
 179         @function       mbr_check_membership
 180         @abstract       checks if a user is a member of a group
 181         @discussion     will check if a user is a member of a group either through
 182                                 direct membership or via nested group membership.
 183         @param          user is the UUID of the user in question
 184         @param          group is the UUID of the group to be checked
 185         @param          ismember is set to 1 if user is a member of the group,
 186                                 otherwise 0 is returned
 187         @result         returns 0 on success or appropriate errno code.
 188 */
 189 int mbr_check_membership(uuid_t user, uuid_t group, int* ismember);
 190
 191 /*!
 192         @function       mbr_check_service_membership
 193         @abstract   checks if a user is part of a service group
 194         @discussion will check if a user is a member of a service access group.
 195                                 The servicename provided will be automatically prefixed with
 196                                 "com.apple.access_" (e.g., "afp" becomes "com.apple.access_afp").
 197                                 In addition a special service group "com.apple.access_all_services"
 198                                 will be checked in addition to the specific service.
 199         @param          user is the UUID of the user in question
 200         @param          servicename is the service type (e.g., "afp", "ftp", etc.)
 201         @param          ismember is set to 1 if user is a member of the group,
 202                                 otherwise 0 is returned
 203         @result         returns 0 on success or appropriate errno code.
 204 */
 205 int mbr_check_service_membership(const uuid_t user, const char *servicename,
 206                                                                  int *ismember);
 207
 208 __END_DECLS
 209
 210 #endif /* !_MEMBERSHIP_H_ */