src/include/utils/acl.h

   1 /*-------------------------------------------------------------------------
   2  *
   3  * acl.h
   4  *        Definition of (and support for) access control list data structures.
   5  *
   6  *
   7  * Portions Copyright (c) 1996-2023, PostgreSQL Global Development Group
   8  * Portions Copyright (c) 1994, Regents of the University of California
   9  *
  10  * src/include/utils/acl.h
  11  *
  12  * NOTES
  13  *        An ACL array is simply an array of AclItems, representing the union
  14  *        of the privileges represented by the individual items.  A zero-length
  15  *        array represents "no privileges".
  16  *
  17  *        The order of items in the array is important as client utilities (in
  18  *        particular, pg_dump, though possibly other clients) expect to be able
  19  *        to issue GRANTs in the ordering of the items in the array.  The reason
  20  *        this matters is that GRANTs WITH GRANT OPTION must be before any GRANTs
  21  *        which depend on it.  This happens naturally in the backend during
  22  *        operations as we update ACLs in-place, new items are appended, and
  23  *        existing entries are only removed if there's no dependency on them (no
  24  *        GRANT can been based on it, or, if there was, those GRANTs are also
  25  *        removed).
  26  *
  27  *        For backward-compatibility purposes we have to allow null ACL entries
  28  *        in system catalogs.  A null ACL will be treated as meaning "default
  29  *        protection" (i.e., whatever acldefault() returns).
  30  *-------------------------------------------------------------------------
  31  */
  32 #ifndef ACL_H
  33 #define ACL_H
  34
  35 #include "access/htup.h"
  36 #include "nodes/parsenodes.h"
  37 #include "parser/parse_node.h"
  38 #include "utils/snapshot.h"
  39
  40
  41 /*
  42  * typedef AclMode is declared in parsenodes.h, also the individual privilege
  43  * bit meanings are defined there
  44  */
  45
  46 #define ACL_ID_PUBLIC   0               /* placeholder for id in a PUBLIC acl item */
  47
  48 /*
  49  * AclItem
  50  *
  51  * Note: must be same size on all platforms, because the size is hardcoded
  52  * in the pg_type.h entry for aclitem.
  53  */
  54 typedef struct AclItem
  55 {
  56         Oid                     ai_grantee;             /* ID that this item grants privs to */
  57         Oid                     ai_grantor;             /* grantor of privs */
  58         AclMode         ai_privs;               /* privilege bits */
  59 } AclItem;
  60
  61 /*
  62  * The upper 32 bits of the ai_privs field of an AclItem are the grant option
  63  * bits, and the lower 32 bits are the actual privileges.  We use "rights"
  64  * to mean the combined grant option and privilege bits fields.
  65  */
  66 #define ACLITEM_GET_PRIVS(item)    ((item).ai_privs & 0xFFFFFFFF)
  67 #define ACLITEM_GET_GOPTIONS(item) (((item).ai_privs >> 32) & 0xFFFFFFFF)
  68 #define ACLITEM_GET_RIGHTS(item)   ((item).ai_privs)
  69
  70 #define ACL_GRANT_OPTION_FOR(privs) (((AclMode) (privs) & 0xFFFFFFFF) << 32)
  71 #define ACL_OPTION_TO_PRIVS(privs)      (((AclMode) (privs) >> 32) & 0xFFFFFFFF)
  72
  73 #define ACLITEM_SET_PRIVS(item,privs) \
  74   ((item).ai_privs = ((item).ai_privs & ~((AclMode) 0xFFFFFFFF)) | \
  75                                          ((AclMode) (privs) & 0xFFFFFFFF))
  76 #define ACLITEM_SET_GOPTIONS(item,goptions) \
  77   ((item).ai_privs = ((item).ai_privs & ~(((AclMode) 0xFFFFFFFF) << 32)) | \
  78                                          (((AclMode) (goptions) & 0xFFFFFFFF) << 32))
  79 #define ACLITEM_SET_RIGHTS(item,rights) \
  80   ((item).ai_privs = (AclMode) (rights))
  81
  82 #define ACLITEM_SET_PRIVS_GOPTIONS(item,privs,goptions) \
  83   ((item).ai_privs = ((AclMode) (privs) & 0xFFFFFFFF) | \
  84                                          (((AclMode) (goptions) & 0xFFFFFFFF) << 32))
  85
  86
  87 #define ACLITEM_ALL_PRIV_BITS           ((AclMode) 0xFFFFFFFF)
  88 #define ACLITEM_ALL_GOPTION_BITS        ((AclMode) 0xFFFFFFFF << 32)
  89
  90 /*
  91  * Definitions for convenient access to Acl (array of AclItem).
  92  * These are standard PostgreSQL arrays, but are restricted to have one
  93  * dimension and no nulls.  We also ignore the lower bound when reading,
  94  * and set it to one when writing.
  95  *
  96  * CAUTION: as of PostgreSQL 7.1, these arrays are toastable (just like all
  97  * other array types).  Therefore, be careful to detoast them with the
  98  * macros provided, unless you know for certain that a particular array
  99  * can't have been toasted.
 100  */
 101
 102
 103 /*
 104  * Acl                  a one-dimensional array of AclItem
 105  */
 106 typedef struct ArrayType Acl;
 107
 108 #define ACL_NUM(ACL)                    (ARR_DIMS(ACL)[0])
 109 #define ACL_DAT(ACL)                    ((AclItem *) ARR_DATA_PTR(ACL))
 110 #define ACL_N_SIZE(N)                   (ARR_OVERHEAD_NONULLS(1) + ((N) * sizeof(AclItem)))
 111 #define ACL_SIZE(ACL)                   ARR_SIZE(ACL)
 112
 113 /*
 114  * fmgr macros for these types
 115  */
 116 #define DatumGetAclItemP(X)                ((AclItem *) DatumGetPointer(X))
 117 #define PG_GETARG_ACLITEM_P(n)     DatumGetAclItemP(PG_GETARG_DATUM(n))
 118 #define PG_RETURN_ACLITEM_P(x)     PG_RETURN_POINTER(x)
 119
 120 #define DatumGetAclP(X)                    ((Acl *) PG_DETOAST_DATUM(X))
 121 #define DatumGetAclPCopy(X)                ((Acl *) PG_DETOAST_DATUM_COPY(X))
 122 #define PG_GETARG_ACL_P(n)                 DatumGetAclP(PG_GETARG_DATUM(n))
 123 #define PG_GETARG_ACL_P_COPY(n)    DatumGetAclPCopy(PG_GETARG_DATUM(n))
 124 #define PG_RETURN_ACL_P(x)                 PG_RETURN_POINTER(x)
 125
 126 /*
 127  * ACL modification opcodes for aclupdate
 128  */
 129 #define ACL_MODECHG_ADD                 1
 130 #define ACL_MODECHG_DEL                 2
 131 #define ACL_MODECHG_EQL                 3
 132
 133 /*
 134  * External representations of the privilege bits --- aclitemin/aclitemout
 135  * represent each possible privilege bit with a distinct 1-character code
 136  */
 137 #define ACL_INSERT_CHR                  'a' /* formerly known as "append" */
 138 #define ACL_SELECT_CHR                  'r' /* formerly known as "read" */
 139 #define ACL_UPDATE_CHR                  'w' /* formerly known as "write" */
 140 #define ACL_DELETE_CHR                  'd'
 141 #define ACL_TRUNCATE_CHR                'D' /* super-delete, as it were */
 142 #define ACL_REFERENCES_CHR              'x'
 143 #define ACL_TRIGGER_CHR                 't'
 144 #define ACL_EXECUTE_CHR                 'X'
 145 #define ACL_USAGE_CHR                   'U'
 146 #define ACL_CREATE_CHR                  'C'
 147 #define ACL_CREATE_TEMP_CHR             'T'
 148 #define ACL_CONNECT_CHR                 'c'
 149 #define ACL_SET_CHR                             's'
 150 #define ACL_ALTER_SYSTEM_CHR    'A'
 151
 152 /* string holding all privilege code chars, in order by bitmask position */
 153 #define ACL_ALL_RIGHTS_STR      "arwdDxtXUCTcsA"
 154
 155 /*
 156  * Bitmasks defining "all rights" for each supported object type
 157  */
 158 #define ACL_ALL_RIGHTS_COLUMN           (ACL_INSERT|ACL_SELECT|ACL_UPDATE|ACL_REFERENCES)
 159 #define ACL_ALL_RIGHTS_RELATION         (ACL_INSERT|ACL_SELECT|ACL_UPDATE|ACL_DELETE|ACL_TRUNCATE|ACL_REFERENCES|ACL_TRIGGER)
 160 #define ACL_ALL_RIGHTS_SEQUENCE         (ACL_USAGE|ACL_SELECT|ACL_UPDATE)
 161 #define ACL_ALL_RIGHTS_DATABASE         (ACL_CREATE|ACL_CREATE_TEMP|ACL_CONNECT)
 162 #define ACL_ALL_RIGHTS_FDW                      (ACL_USAGE)
 163 #define ACL_ALL_RIGHTS_FOREIGN_SERVER (ACL_USAGE)
 164 #define ACL_ALL_RIGHTS_FUNCTION         (ACL_EXECUTE)
 165 #define ACL_ALL_RIGHTS_LANGUAGE         (ACL_USAGE)
 166 #define ACL_ALL_RIGHTS_LARGEOBJECT      (ACL_SELECT|ACL_UPDATE)
 167 #define ACL_ALL_RIGHTS_PARAMETER_ACL (ACL_SET|ACL_ALTER_SYSTEM)
 168 #define ACL_ALL_RIGHTS_SCHEMA           (ACL_USAGE|ACL_CREATE)
 169 #define ACL_ALL_RIGHTS_TABLESPACE       (ACL_CREATE)
 170 #define ACL_ALL_RIGHTS_TYPE                     (ACL_USAGE)
 171
 172 /* operation codes for pg_*_aclmask */
 173 typedef enum
 174 {
 175         ACLMASK_ALL,                            /* normal case: compute all bits */
 176         ACLMASK_ANY                                     /* return when result is known nonzero */
 177 } AclMaskHow;
 178
 179 /* result codes for pg_*_aclcheck */
 180 typedef enum
 181 {
 182         ACLCHECK_OK = 0,
 183         ACLCHECK_NO_PRIV,
 184         ACLCHECK_NOT_OWNER
 185 } AclResult;
 186
 187
 188 /*
 189  * routines used internally
 190  */
 191 extern Acl *acldefault(ObjectType objtype, Oid ownerId);
 192 extern Acl *get_user_default_acl(ObjectType objtype, Oid ownerId,
 193                                                                  Oid nsp_oid);
 194 extern void recordDependencyOnNewAcl(Oid classId, Oid objectId, int32 objsubId,
 195                                                                          Oid ownerId, Acl *acl);
 196
 197 extern Acl *aclupdate(const Acl *old_acl, const AclItem *mod_aip,
 198                                           int modechg, Oid ownerId, DropBehavior behavior);
 199 extern Acl *aclnewowner(const Acl *old_acl, Oid oldOwnerId, Oid newOwnerId);
 200 extern Acl *make_empty_acl(void);
 201 extern Acl *aclcopy(const Acl *orig_acl);
 202 extern Acl *aclconcat(const Acl *left_acl, const Acl *right_acl);
 203 extern Acl *aclmerge(const Acl *left_acl, const Acl *right_acl, Oid ownerId);
 204 extern void aclitemsort(Acl *acl);
 205 extern bool aclequal(const Acl *left_acl, const Acl *right_acl);
 206
 207 extern AclMode aclmask(const Acl *acl, Oid roleid, Oid ownerId,
 208                                            AclMode mask, AclMaskHow how);
 209 extern int      aclmembers(const Acl *acl, Oid **roleids);
 210
 211 extern bool has_privs_of_role(Oid member, Oid role);
 212 extern bool member_can_set_role(Oid member, Oid role);
 213 extern void check_can_set_role(Oid member, Oid role);
 214 extern bool is_member_of_role(Oid member, Oid role);
 215 extern bool is_member_of_role_nosuper(Oid member, Oid role);
 216 extern bool is_admin_of_role(Oid member, Oid role);
 217 extern Oid      select_best_admin(Oid member, Oid role);
 218 extern Oid      get_role_oid(const char *rolname, bool missing_ok);
 219 extern Oid      get_role_oid_or_public(const char *rolname);
 220 extern Oid      get_rolespec_oid(const RoleSpec *role, bool missing_ok);
 221 extern void check_rolespec_name(const RoleSpec *role, const char *detail_msg);
 222 extern HeapTuple get_rolespec_tuple(const RoleSpec *role);
 223 extern char *get_rolespec_name(const RoleSpec *role);
 224
 225 extern void select_best_grantor(Oid roleId, AclMode privileges,
 226                                                                 const Acl *acl, Oid ownerId,
 227                                                                 Oid *grantorId, AclMode *grantOptions);
 228
 229 extern void initialize_acl(void);
 230
 231 /*
 232  * prototypes for functions in aclchk.c
 233  */
 234 extern void ExecuteGrantStmt(GrantStmt *stmt);
 235 extern void ExecAlterDefaultPrivilegesStmt(ParseState *pstate, AlterDefaultPrivilegesStmt *stmt);
 236
 237 extern void RemoveRoleFromObjectACL(Oid roleid, Oid classid, Oid objid);
 238
 239 extern AclMode pg_class_aclmask(Oid table_oid, Oid roleid,
 240                                                                 AclMode mask, AclMaskHow how);
 241
 242 /* generic function */
 243 extern AclResult object_aclcheck(Oid classid, Oid objectid, Oid roleid, AclMode mode);
 244
 245 /* special cases */
 246 extern AclResult pg_attribute_aclcheck(Oid table_oid, AttrNumber attnum,
 247                                                                            Oid roleid, AclMode mode);
 248 extern AclResult pg_attribute_aclcheck_ext(Oid table_oid, AttrNumber attnum,
 249                                                                                    Oid roleid, AclMode mode,
 250                                                                                    bool *is_missing);
 251 extern AclResult pg_attribute_aclcheck_all(Oid table_oid, Oid roleid,
 252                                                                                    AclMode mode, AclMaskHow how);
 253 extern AclResult pg_class_aclcheck(Oid table_oid, Oid roleid, AclMode mode);
 254 extern AclResult pg_class_aclcheck_ext(Oid table_oid, Oid roleid,
 255                                                                            AclMode mode, bool *is_missing);
 256 extern AclResult pg_parameter_aclcheck(const char *name, Oid roleid,
 257                                                                            AclMode mode);
 258 extern AclResult pg_largeobject_aclcheck_snapshot(Oid lobj_oid, Oid roleid,
 259                                                                                                   AclMode mode, Snapshot snapshot);
 260
 261 extern void aclcheck_error(AclResult aclerr, ObjectType objtype,
 262                                                    const char *objectname);
 263
 264 extern void aclcheck_error_col(AclResult aclerr, ObjectType objtype,
 265                                                            const char *objectname, const char *colname);
 266
 267 extern void aclcheck_error_type(AclResult aclerr, Oid typeOid);
 268
 269 extern void recordExtObjInitPriv(Oid objoid, Oid classoid);
 270 extern void removeExtObjInitPriv(Oid objoid, Oid classoid);
 271
 272
 273 /* ownercheck routines just return true (owner) or false (not) */
 274 extern bool object_ownercheck(Oid classid, Oid objectid, Oid roleid);
 275 extern bool has_createrole_privilege(Oid roleid);
 276 extern bool has_bypassrls_privilege(Oid roleid);
 277
 278 #endif                                                  /* ACL_H */