cifsidmap.h

   1 /*
   2  * ID Mapping Plugin interface for cifs-utils
   3  * Copyright (C) 2012 Jeff Layton (jlayton@samba.org)
   4  *
   5  * This program is free software; you can redistribute it and/or modify
   6  * it under the terms of the GNU General Public License as published by
   7  * the Free Software Foundation; either version 3 of the License, or
   8  * (at your option) any later version.
   9  *
  10  * This program is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13  * GNU General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU General Public License
  16  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  17  */
  18 #include <stdint.h>
  19
  20 #ifndef _CIFSIDMAP_H
  21 #define _CIFSIDMAP_H
  22
  23 #define NUM_AUTHS (6)                   /* number of authority fields */
  24 #define SID_MAX_SUB_AUTHORITIES (15)    /* max number of sub authority fields */
  25
  26 /*
  27  * Binary representation of a SID as presented to/from the kernel. Note that
  28  * the sub_auth field is always stored in little-endian here.
  29  */
  30 struct cifs_sid {
  31         uint8_t revision; /* revision level */
  32         uint8_t num_subauth;
  33         uint8_t authority[NUM_AUTHS];
  34         uint32_t sub_auth[SID_MAX_SUB_AUTHORITIES];
  35 } __attribute__((packed));
  36
  37
  38 /*
  39  * The type of the ID stored within cifs_uxid. UNKNOWN generally means that
  40  * the mapping failed for some reason. BOTH means that the ID is usable as
  41  * either a UID or a GID -- IOW, the UID and GID namespaces are unity-mapped.
  42  */
  43 #define CIFS_UXID_TYPE_UNKNOWN  (0)     /* mapping type is unknown */
  44 #define CIFS_UXID_TYPE_UID      (1)     /* mapping is a UID */
  45 #define CIFS_UXID_TYPE_GID      (2)     /* mapping is a GID */
  46 #define CIFS_UXID_TYPE_BOTH     (3)     /* usable as UID or GID */
  47
  48 /* This struct represents a uid or gid and its type */
  49 struct cifs_uxid {
  50         union {
  51                 uid_t uid;
  52                 gid_t gid;
  53         } id;
  54         unsigned char type;
  55 } __attribute__((packed));
  56
  57 /*
  58  * Plugins should implement the following functions:
  59  */
  60
  61 /**
  62  * cifs_idmap_init_plugin - Initialize the plugin interface
  63  * @handle - return pointer for an opaque handle
  64  * @errmsg - pointer to error message pointer
  65  *
  66  * This function should do whatever is required to establish a context
  67  * for later ID mapping operations. The "handle" is an opaque context
  68  * cookie that will be passed in on subsequent ID mapping operations.
  69  * The errmsg is used to pass back an error string both during the init
  70  * and in subsequent idmapping functions. On any error, the plugin
  71  * should point *errmsg at a string describing that error. Returns 0
  72  * on success and non-zero on error.
  73  */
  74 extern int cifs_idmap_init_plugin(void **handle, const char **errmsg);
  75
  76 /**
  77  * cifs_idmap_exit_plugin - Destroy an idmapping context
  78  * @handle - context handle that should be destroyed
  79  *
  80  * When programs are finished with the idmapping plugin, they'll call
  81  * this function to destroy any context that was created during the
  82  * init_plugin. The handle passed back in was the one given by the init
  83  * routine.
  84  */
  85 extern void cifs_idmap_exit_plugin(void *handle);
  86
  87 /**
  88  * cifs_idmap_sid_to_str - convert cifs_sid to a string
  89  * @handle - context handle
  90  * @sid    - pointer to a cifs_sid
  91  * @name   - return pointer for the name
  92  *
  93  * This function should convert the given cifs_sid to a string
  94  * representation or mapped name in a heap-allocated buffer. The caller
  95  * of this function is expected to free "name" on success. Returns 0 on
  96  * success and non-zero on error. On error, the errmsg pointer passed
  97  * in to the init_plugin function should point to an error string. The
  98  * caller will not free the error string.
  99  */
 100 extern int cifs_idmap_sid_to_str(void *handle, const struct cifs_sid *sid,
 101                                         char **name);
 102
 103 /**
 104  * cifs_idmap_str_to_sid - convert string to struct cifs_sid
 105  * @handle - context handle
 106  * @name   - pointer to name string to be converted
 107  * @sid    - pointer to struct cifs_sid where result should go
 108  *
 109  * This function converts a name string or string representation of
 110  * a SID to a struct cifs_sid. The cifs_sid should already be
 111  * allocated. Returns 0 on success and non-zero on error. On error, the
 112  * plugin should reset the errmsg pointer passed to the init_plugin
 113  * function to an error string. The caller will not free the error string.
 114  */
 115 extern int cifs_idmap_str_to_sid(void *handle, const char *name,
 116                                 struct cifs_sid *sid);
 117
 118 /**
 119  * cifs_idmap_sids_to_ids - convert struct cifs_sids to struct cifs_uxids
 120  * @handle - context handle
 121  * @sid    - pointer to array of struct cifs_sids to be converted
 122  * @num    - number of sids to be converted
 123  * @cuxid  - pointer to preallocated array of struct cifs_uxids for return
 124  *
 125  * This function should map an array of struct cifs_sids to an array of
 126  * struct cifs_uxids.
 127  *
 128  * Returns 0 if at least one conversion was successful and non-zero on error.
 129  * Any that were not successfully converted will have a cuxid->type of
 130  * CIFS_UXID_TYPE_UNKNOWN.
 131  *
 132  * On any error, the plugin should reset the errmsg pointer passed to the
 133  * init_plugin function to an error string. The caller will not free the error
 134  * string.
 135  */
 136 extern int cifs_idmap_sids_to_ids(void *handle, const struct cifs_sid *sid,
 137                                 const size_t num, struct cifs_uxid *cuxid);
 138
 139 /**
 140  * cifs_idmap_ids_to_sids - convert uid to struct cifs_sid
 141  * @handle - context handle
 142  * @cuxid  - pointer to array of struct cifs_uxid to be converted to SIDs
 143  * @num    - number of cifs_uxids to be converted to SIDs
 144  * @sid    - pointer to preallocated array of struct cifs_sid where results
 145  *           should be stored
 146  *
 147  * This function should map an array of cifs_uxids an array of struct cifs_sids.
 148  * Returns 0 if at least one conversion was successful and non-zero on error.
 149  * Any sids that were not successfully converted should have their revision
 150  * number set to 0.
 151  *
 152  * On any error, the plugin should reset the errmsg pointer passed to the
 153  * init_plugin function to an error string. The caller will not free the error
 154  * string.
 155  */
 156 extern int cifs_idmap_ids_to_sids(void *handle, const struct cifs_uxid *cuxid,
 157                                 const size_t num, struct cifs_sid *sid);
 158 #endif /* _CIFSIDMAP_H */