Back to index

courier  0.68.2
maildiraclt.h
Go to the documentation of this file.
00001 #ifndef       maildiraclt_h
00002 #define       maildiraclt_h
00003 
00004 #ifdef  __cplusplus
00005 extern "C" {
00006 #endif
00007 
00008 
00009 /*
00010 ** Copyright 2003-2004 Double Precision, Inc.
00011 ** See COPYING for distribution information.
00012 */
00013 
00014 #if    HAVE_CONFIG_H
00015 #include      "config.h"
00016 #endif
00017 
00018 
00019 /*
00020 ** A basic ACL entity.  Be generic, it's just a character string.
00021 ** However, we do keep it in collating order.
00022 **
00023 ** These functions return 0 on success, <0 on error.
00024 */
00025 
00026 typedef char *maildir_aclt;
00027 
00028 
00029 /*
00030 ** Initialize an aclt.  The second or third args specify its initial value.
00031 ** Both may be NULL.  Only one can be non-NULL.
00032 */
00033 
00034 int maildir_aclt_init(maildir_aclt *aclt,
00035                     const char *initvalue_cstr,
00036                     const maildir_aclt *initvalue_cpy);
00037 
00038 /* Destroy an aclt after it is no longer used. */
00039 
00040 void maildir_aclt_destroy(maildir_aclt *aclt);
00041 
00042 
00043 /* Add or remove access chars. */
00044 
00045 int maildir_aclt_add(maildir_aclt *aclt,
00046                     const char *add_strs,
00047                     const maildir_aclt *add_aclt);
00048 
00049 int maildir_aclt_del(maildir_aclt *aclt,
00050                    const char *del_strs,
00051                    const maildir_aclt *del_aclt);
00052 
00053 /* return a const char * that contains the acl */
00054 
00055 #define maildir_aclt_ascstr(t) (*(t) ? (const char *)*(t):"")
00056 
00057 
00058 /* Next level up, a list of <identifier,acl>s */
00059 
00060 struct maildir_aclt_node {
00061        struct maildir_aclt_node *prev;
00062        struct maildir_aclt_node *next;
00063        char *identifier;
00064        maildir_aclt acl;
00065 };
00066 
00067 typedef struct {
00068        struct maildir_aclt_node *head;
00069        struct maildir_aclt_node *tail;
00070 } maildir_aclt_list;
00071 
00072 
00073 /* Initialize and destroy the list */
00074 
00075 void maildir_aclt_list_init(maildir_aclt_list *aclt_list);
00076 void maildir_aclt_list_destroy(maildir_aclt_list *aclt_list);
00077 
00078 /* Add an <identifier,acl> pair.  Returns 0 on success, -1 on failure */
00079 
00080 int maildir_aclt_list_add(maildir_aclt_list *aclt_list,
00081                        const char *identifier,
00082                        const char *aclt_str,
00083                        maildir_aclt *aclt_cpy);
00084 
00085 /* Remove an identifier */
00086 
00087 int maildir_aclt_list_del(maildir_aclt_list *aclt_list,
00088                        const char *identifier);
00089 
00090 /*
00091 ** Enumerate the ACL list.  The callback function, cb_func, gets
00092 ** invoked for each ACL list entry.  The callback function receives:
00093 ** identifier+rights pair; as well as the transparent pass-through
00094 ** argument.  A nonzero return from the callback function terminates
00095 ** the enumeration, and maildir_aclt_list_enum itself returns
00096 ** non-zero.  A zero return continues the enumeration.  After the
00097 ** entire list is enumerated maildir_aclt_list_enum returns 0.
00098 */
00099 
00100 int maildir_aclt_list_enum(maildir_aclt_list *aclt_list,
00101                         int (*cb_func)(const char *identifier,
00102                                      const maildir_aclt *acl,
00103                                      void *cb_arg),
00104                         void *cb_arg);
00105 
00106 /* Find an identifier */
00107  
00108 const maildir_aclt *maildir_aclt_list_find(maildir_aclt_list *aclt_list,
00109                                       const char *identifier);
00110 
00111 /* maildir-level acl ops */
00112 
00113 #define ACL_LOOKUP "l"
00114 #define ACL_READ "r"
00115 #define ACL_SEEN "s"
00116 #define ACL_WRITE "w"
00117 #define ACL_INSERT "i"
00118 #define ACL_POST "p"
00119 #define ACL_CREATE "c"
00120 #define ACL_DELETEFOLDER "x"
00121 #define ACL_DELETEMSGS "t"
00122 #define ACL_EXPUNGE "e"
00123 #define ACL_ADMINISTER "a"
00124 
00125 #define ACL_ALL \
00126        ACL_ADMINISTER \
00127        ACL_CREATE \
00128        ACL_EXPUNGE \
00129        ACL_INSERT \
00130        ACL_LOOKUP \
00131        ACL_READ \
00132        ACL_SEEN \
00133        ACL_DELETEMSGS \
00134        ACL_WRITE \
00135        ACL_DELETEFOLDER
00136 
00137 #define ACL_DELETE_SPECIAL "d"
00138 
00139 #define ACLFILE "courierimapacl"
00140 #define ACLHIERDIR "courierimaphieracl"
00141 
00142 
00143 #define MAILDIR_ACL_ANYONE(s) \
00144        (strcmp( (s), "anonymous") == 0 || \
00145         strcmp( (s), "anyone") == 0)
00146 
00147 
00148 /*
00149 ** Set maildir_acl_disabled to 1 to effectively disable ACL support, and its
00150 ** overhead.
00151 **
00152 ** If maildir_acl_disabled is set, maildir_acl_read never goes to disk to
00153 ** read the ACL file, instead it returns a fixed ACL list which only contains
00154 ** an entry for "owner", and gives "owner" all ACL rights, except the
00155 ** ADMINISTER right, relying on higher level code to refuse to set new
00156 ** ACLs unless the existing ACL gives administer right.
00157 **
00158 ** Additionally, maildir_acl_disabled turns off the hook in maildir_acl_compute
00159 ** that grants ADMINISTER to "owner" irrespective of what the ACLs actually
00160 ** say.
00161 */
00162 
00163 extern int maildir_acl_disabled;
00164 
00165 /*
00166 ** Read ACLs for maildir maildir.path.
00167 **
00168 ** maildir: Path to the main maildir.
00169 **
00170 ** path: ".folder.subfolder".
00171 **
00172 ** aclt_list is an uninitialized maildir_aclt_list
00173 **
00174 ** Returns 0 for success, <0 for failure.
00175 */
00176 
00177 int maildir_acl_read(maildir_aclt_list *aclt_list,
00178                    const char *maildir,
00179                    const char *path);
00180 
00181 /*
00182 ** Write ACLs for maildir maildir.path.
00183 **
00184 ** Returns 0 for success, <0 for failure.
00185 **
00186 ** Additional parameters:
00187 **
00188 ** owner: the owner entity of the folder represented by 'path'.
00189 **
00190 ** err_failedrights: if not NULL, *err_failedrights will be initialized to
00191 ** a non-null identifier string if maildir_acl_set fails because aclt_list
00192 ** illegally revokes minimum rights from the identifier (admin/lookup).
00193 **
00194 */
00195 
00196 int maildir_acl_write(maildir_aclt_list *aclt_list,
00197                     const char *maildir,
00198                     const char *path,
00199                     const char *owner,
00200                     const char **err_failedrights);
00201 
00202 /* Remove stale ACL entries */
00203 
00204 int maildir_acl_reset(const char *maildir);
00205 
00206 /* Remove a particular ACL entry */
00207 
00208 int maildir_acl_delete(const char *maildir,
00209                      const char *path);   /* .folder.subfolder */
00210 
00211 /*
00212 ** Compute my access rights.  Initializes 'aclt'. 'aclt_list' is the ACL.
00213 **
00214 ** The callback function should return >0 if identifier refers to the entity
00215 ** whose access rights are to be computed; 0 if it does not, <0 if an error
00216 ** occured.
00217 **
00218 ** As a special case, maildir_acl_compute() handles "anonymous" and "anyone"
00219 ** identifiers on its own.
00220 **
00221 ** As a special case, if the callback function returns >0 for the identifier
00222 ** "owner", the computed access rights will always include the ADMIN right.
00223 **
00224 ** maildir_aclt_compute() uses ACL2=UNION; the computed access rights
00225 ** consist of the union of all rights granted to all identifiers that include
00226 ** the entity, minus the union of all reights revoked from all identifiers
00227 ** that include the entity.
00228 */
00229 int maildir_acl_compute(maildir_aclt *aclt, maildir_aclt_list *aclt_list,
00230                      int (*cb_func)(const char *identifier,
00231                                    void *void_arg), void *void_arg);
00232 
00233 /*
00234 ** A wrapper for maildir_acl_compute that compares against a
00235 ** const char * array.
00236 */
00237 
00238 int maildir_acl_compute_array(maildir_aclt *aclt,
00239                            maildir_aclt_list *aclt_list,
00240                            const char * const *identifiers);
00241 
00242 /*
00243 ** A wrapper for maildir_acl_compute.
00244 **
00245 ** Compute 'rights' - my rights on the mailbox.
00246 **
00247 ** acl_list: the mailbox's ACL.
00248 **
00249 ** me: my login identifier.
00250 **
00251 ** folder_owner: the owner of the mailbox folder whose rights are computed
00252 **
00253 ** OTHER: The "OPTIONS" environment variable is parsed to obtain a list of
00254 ** account groups 'me' belongs to.
00255 **
00256 ** Returns 0 upon success, after placing the computed access rights in
00257 ** 'rights'.
00258 */
00259 
00260 int maildir_acl_computerights(maildir_aclt *rights,
00261                            maildir_aclt_list *acl_list,
00262                            const char *me,
00263                            const char *folder_owner);
00264 
00265 /*
00266 ** Convenience functions:
00267 **
00268 ** maildir_acl_canlistrights: return true if the given rights indicate that
00269 ** the rights themselves can be viewed (one of the following must be present:
00270 ** ACL_LOOKUP, ACL_READ, ACL_INSERT[0], ACL_CREATE[0], ACL_DELETEFOLDER,
00271 ** ACL_EXPUNGE[0], or ACL_ADMINISTER).
00272 */
00273 
00274 int maildir_acl_canlistrights(const char *myrights);
00275 
00276 #ifdef  __cplusplus
00277 }
00278 #endif
00279 
00280 #endif