security/landlock/ruleset.h

   1 /* SPDX-License-Identifier: GPL-2.0-only */
   2 /*
   3  * Landlock LSM - Ruleset management
   4  *
   5  * Copyright © 2016-2020 Mickaël Salaün <mic@digikod.net>
   6  * Copyright © 2018-2020 ANSSI
   7  */
   8
   9 #ifndef _SECURITY_LANDLOCK_RULESET_H
  10 #define _SECURITY_LANDLOCK_RULESET_H
  11
  12 #include <linux/cleanup.h>
  13 #include <linux/err.h>
  14 #include <linux/mutex.h>
  15 #include <linux/rbtree.h>
  16 #include <linux/refcount.h>
  17 #include <linux/workqueue.h>
  18
  19 #include "access.h"
  20 #include "limits.h"
  21 #include "object.h"
  22
  23 /**
  24  * struct landlock_layer - Access rights for a given layer
  25  */
  26 struct landlock_layer {
  27         /**
  28          * @level: Position of this layer in the layer stack.
  29          */
  30         u16 level;
  31         /**
  32          * @access: Bitfield of allowed actions on the kernel object.  They are
  33          * relative to the object type (e.g. %LANDLOCK_ACTION_FS_READ).
  34          */
  35         access_mask_t access;
  36 };
  37
  38 /**
  39  * union landlock_key - Key of a ruleset's red-black tree
  40  */
  41 union landlock_key {
  42         /**
  43          * @object: Pointer to identify a kernel object (e.g. an inode).
  44          */
  45         struct landlock_object *object;
  46         /**
  47          * @data: Raw data to identify an arbitrary 32-bit value
  48          * (e.g. a TCP port).
  49          */
  50         uintptr_t data;
  51 };
  52
  53 /**
  54  * enum landlock_key_type - Type of &union landlock_key
  55  */
  56 enum landlock_key_type {
  57         /**
  58          * @LANDLOCK_KEY_INODE: Type of &landlock_ruleset.root_inode's node
  59          * keys.
  60          */
  61         LANDLOCK_KEY_INODE = 1,
  62         /**
  63          * @LANDLOCK_KEY_NET_PORT: Type of &landlock_ruleset.root_net_port's
  64          * node keys.
  65          */
  66         LANDLOCK_KEY_NET_PORT,
  67 };
  68
  69 /**
  70  * struct landlock_id - Unique rule identifier for a ruleset
  71  */
  72 struct landlock_id {
  73         /**
  74          * @key: Identifies either a kernel object (e.g. an inode) or
  75          * a raw value (e.g. a TCP port).
  76          */
  77         union landlock_key key;
  78         /**
  79          * @type: Type of a landlock_ruleset's root tree.
  80          */
  81         const enum landlock_key_type type;
  82 };
  83
  84 /**
  85  * struct landlock_rule - Access rights tied to an object
  86  */
  87 struct landlock_rule {
  88         /**
  89          * @node: Node in the ruleset's red-black tree.
  90          */
  91         struct rb_node node;
  92         /**
  93          * @key: A union to identify either a kernel object (e.g. an inode) or
  94          * a raw data value (e.g. a network socket port). This is used as a key
  95          * for this ruleset element.  The pointer is set once and never
  96          * modified.  It always points to an allocated object because each rule
  97          * increments the refcount of its object.
  98          */
  99         union landlock_key key;
 100         /**
 101          * @num_layers: Number of entries in @layers.
 102          */
 103         u32 num_layers;
 104         /**
 105          * @layers: Stack of layers, from the latest to the newest, implemented
 106          * as a flexible array member (FAM).
 107          */
 108         struct landlock_layer layers[] __counted_by(num_layers);
 109 };
 110
 111 /**
 112  * struct landlock_hierarchy - Node in a ruleset hierarchy
 113  */
 114 struct landlock_hierarchy {
 115         /**
 116          * @parent: Pointer to the parent node, or NULL if it is a root
 117          * Landlock domain.
 118          */
 119         struct landlock_hierarchy *parent;
 120         /**
 121          * @usage: Number of potential children domains plus their parent
 122          * domain.
 123          */
 124         refcount_t usage;
 125 };
 126
 127 /**
 128  * struct landlock_ruleset - Landlock ruleset
 129  *
 130  * This data structure must contain unique entries, be updatable, and quick to
 131  * match an object.
 132  */
 133 struct landlock_ruleset {
 134         /**
 135          * @root_inode: Root of a red-black tree containing &struct
 136          * landlock_rule nodes with inode object.  Once a ruleset is tied to a
 137          * process (i.e. as a domain), this tree is immutable until @usage
 138          * reaches zero.
 139          */
 140         struct rb_root root_inode;
 141
 142 #if IS_ENABLED(CONFIG_INET)
 143         /**
 144          * @root_net_port: Root of a red-black tree containing &struct
 145          * landlock_rule nodes with network port. Once a ruleset is tied to a
 146          * process (i.e. as a domain), this tree is immutable until @usage
 147          * reaches zero.
 148          */
 149         struct rb_root root_net_port;
 150 #endif /* IS_ENABLED(CONFIG_INET) */
 151
 152         /**
 153          * @hierarchy: Enables hierarchy identification even when a parent
 154          * domain vanishes.  This is needed for the ptrace protection.
 155          */
 156         struct landlock_hierarchy *hierarchy;
 157         union {
 158                 /**
 159                  * @work_free: Enables to free a ruleset within a lockless
 160                  * section.  This is only used by
 161                  * landlock_put_ruleset_deferred() when @usage reaches zero.
 162                  * The fields @lock, @usage, @num_rules, @num_layers and
 163                  * @access_masks are then unused.
 164                  */
 165                 struct work_struct work_free;
 166                 struct {
 167                         /**
 168                          * @lock: Protects against concurrent modifications of
 169                          * @root, if @usage is greater than zero.
 170                          */
 171                         struct mutex lock;
 172                         /**
 173                          * @usage: Number of processes (i.e. domains) or file
 174                          * descriptors referencing this ruleset.
 175                          */
 176                         refcount_t usage;
 177                         /**
 178                          * @num_rules: Number of non-overlapping (i.e. not for
 179                          * the same object) rules in this ruleset.
 180                          */
 181                         u32 num_rules;
 182                         /**
 183                          * @num_layers: Number of layers that are used in this
 184                          * ruleset.  This enables to check that all the layers
 185                          * allow an access request.  A value of 0 identifies a
 186                          * non-merged ruleset (i.e. not a domain).
 187                          */
 188                         u32 num_layers;
 189                         /**
 190                          * @access_masks: Contains the subset of filesystem and
 191                          * network actions that are restricted by a ruleset.
 192                          * A domain saves all layers of merged rulesets in a
 193                          * stack (FAM), starting from the first layer to the
 194                          * last one.  These layers are used when merging
 195                          * rulesets, for user space backward compatibility
 196                          * (i.e. future-proof), and to properly handle merged
 197                          * rulesets without overlapping access rights.  These
 198                          * layers are set once and never changed for the
 199                          * lifetime of the ruleset.
 200                          */
 201                         struct access_masks access_masks[];
 202                 };
 203         };
 204 };
 205
 206 struct landlock_ruleset *
 207 landlock_create_ruleset(const access_mask_t access_mask_fs,
 208                         const access_mask_t access_mask_net,
 209                         const access_mask_t scope_mask);
 210
 211 void landlock_put_ruleset(struct landlock_ruleset *const ruleset);
 212 void landlock_put_ruleset_deferred(struct landlock_ruleset *const ruleset);
 213
 214 DEFINE_FREE(landlock_put_ruleset, struct landlock_ruleset *,
 215             if (!IS_ERR_OR_NULL(_T)) landlock_put_ruleset(_T))
 216
 217 int landlock_insert_rule(struct landlock_ruleset *const ruleset,
 218                          const struct landlock_id id,
 219                          const access_mask_t access);
 220
 221 struct landlock_ruleset *
 222 landlock_merge_ruleset(struct landlock_ruleset *const parent,
 223                        struct landlock_ruleset *const ruleset);
 224
 225 const struct landlock_rule *
 226 landlock_find_rule(const struct landlock_ruleset *const ruleset,
 227                    const struct landlock_id id);
 228
 229 static inline void landlock_get_ruleset(struct landlock_ruleset *const ruleset)
 230 {
 231         if (ruleset)
 232                 refcount_inc(&ruleset->usage);
 233 }
 234
 235 /**
 236  * landlock_union_access_masks - Return all access rights handled in the
 237  *                               domain
 238  *
 239  * @domain: Landlock ruleset (used as a domain)
 240  *
 241  * Returns: an access_masks result of the OR of all the domain's access masks.
 242  */
 243 static inline struct access_masks
 244 landlock_union_access_masks(const struct landlock_ruleset *const domain)
 245 {
 246         union access_masks_all matches = {};
 247         size_t layer_level;
 248
 249         for (layer_level = 0; layer_level < domain->num_layers; layer_level++) {
 250                 union access_masks_all layer = {
 251                         .masks = domain->access_masks[layer_level],
 252                 };
 253
 254                 matches.all |= layer.all;
 255         }
 256
 257         return matches.masks;
 258 }
 259
 260 /**
 261  * landlock_get_applicable_domain - Return @domain if it applies to (handles)
 262  *                                  at least one of the access rights specified
 263  *                                  in @masks
 264  *
 265  * @domain: Landlock ruleset (used as a domain)
 266  * @masks: access masks
 267  *
 268  * Returns: @domain if any access rights specified in @masks is handled, or
 269  * NULL otherwise.
 270  */
 271 static inline const struct landlock_ruleset *
 272 landlock_get_applicable_domain(const struct landlock_ruleset *const domain,
 273                                const struct access_masks masks)
 274 {
 275         const union access_masks_all masks_all = {
 276                 .masks = masks,
 277         };
 278         union access_masks_all merge = {};
 279
 280         if (!domain)
 281                 return NULL;
 282
 283         merge.masks = landlock_union_access_masks(domain);
 284         if (merge.all & masks_all.all)
 285                 return domain;
 286
 287         return NULL;
 288 }
 289
 290 static inline void
 291 landlock_add_fs_access_mask(struct landlock_ruleset *const ruleset,
 292                             const access_mask_t fs_access_mask,
 293                             const u16 layer_level)
 294 {
 295         access_mask_t fs_mask = fs_access_mask & LANDLOCK_MASK_ACCESS_FS;
 296
 297         /* Should already be checked in sys_landlock_create_ruleset(). */
 298         WARN_ON_ONCE(fs_access_mask != fs_mask);
 299         ruleset->access_masks[layer_level].fs |= fs_mask;
 300 }
 301
 302 static inline void
 303 landlock_add_net_access_mask(struct landlock_ruleset *const ruleset,
 304                              const access_mask_t net_access_mask,
 305                              const u16 layer_level)
 306 {
 307         access_mask_t net_mask = net_access_mask & LANDLOCK_MASK_ACCESS_NET;
 308
 309         /* Should already be checked in sys_landlock_create_ruleset(). */
 310         WARN_ON_ONCE(net_access_mask != net_mask);
 311         ruleset->access_masks[layer_level].net |= net_mask;
 312 }
 313
 314 static inline void
 315 landlock_add_scope_mask(struct landlock_ruleset *const ruleset,
 316                         const access_mask_t scope_mask, const u16 layer_level)
 317 {
 318         access_mask_t mask = scope_mask & LANDLOCK_MASK_SCOPE;
 319
 320         /* Should already be checked in sys_landlock_create_ruleset(). */
 321         WARN_ON_ONCE(scope_mask != mask);
 322         ruleset->access_masks[layer_level].scope |= mask;
 323 }
 324
 325 static inline access_mask_t
 326 landlock_get_fs_access_mask(const struct landlock_ruleset *const ruleset,
 327                             const u16 layer_level)
 328 {
 329         /* Handles all initially denied by default access rights. */
 330         return ruleset->access_masks[layer_level].fs |
 331                _LANDLOCK_ACCESS_FS_INITIALLY_DENIED;
 332 }
 333
 334 static inline access_mask_t
 335 landlock_get_net_access_mask(const struct landlock_ruleset *const ruleset,
 336                              const u16 layer_level)
 337 {
 338         return ruleset->access_masks[layer_level].net;
 339 }
 340
 341 static inline access_mask_t
 342 landlock_get_scope_mask(const struct landlock_ruleset *const ruleset,
 343                         const u16 layer_level)
 344 {
 345         return ruleset->access_masks[layer_level].scope;
 346 }
 347
 348 bool landlock_unmask_layers(const struct landlock_rule *const rule,
 349                             const access_mask_t access_request,
 350                             layer_mask_t (*const layer_masks)[],
 351                             const size_t masks_array_size);
 352
 353 access_mask_t
 354 landlock_init_layer_masks(const struct landlock_ruleset *const domain,
 355                           const access_mask_t access_request,
 356                           layer_mask_t (*const layer_masks)[],
 357                           const enum landlock_key_type key_type);
 358
 359 #endif /* _SECURITY_LANDLOCK_RULESET_H */