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/bitops.h>
  13 #include <linux/build_bug.h>
  14 #include <linux/mutex.h>
  15 #include <linux/rbtree.h>
  16 #include <linux/refcount.h>
  17 #include <linux/workqueue.h>
  18
  19 #include "limits.h"
  20 #include "object.h"
  21
  22 typedef u16 access_mask_t;
  23 /* Makes sure all filesystem access rights can be stored. */
  24 static_assert(BITS_PER_TYPE(access_mask_t) >= LANDLOCK_NUM_ACCESS_FS);
  25
  26 typedef u16 layer_mask_t;
  27 /* Makes sure all layers can be checked. */
  28 static_assert(BITS_PER_TYPE(layer_mask_t) >= LANDLOCK_MAX_NUM_LAYERS);
  29
  30 /**
  31  * struct landlock_layer - Access rights for a given layer
  32  */
  33 struct landlock_layer {
  34         /**
  35          * @level: Position of this layer in the layer stack.
  36          */
  37         u16 level;
  38         /**
  39          * @access: Bitfield of allowed actions on the kernel object.  They are
  40          * relative to the object type (e.g. %LANDLOCK_ACTION_FS_READ).
  41          */
  42         access_mask_t access;
  43 };
  44
  45 /**
  46  * struct landlock_rule - Access rights tied to an object
  47  */
  48 struct landlock_rule {
  49         /**
  50          * @node: Node in the ruleset's red-black tree.
  51          */
  52         struct rb_node node;
  53         /**
  54          * @object: Pointer to identify a kernel object (e.g. an inode).  This
  55          * is used as a key for this ruleset element.  This pointer is set once
  56          * and never modified.  It always points to an allocated object because
  57          * each rule increments the refcount of its object.
  58          */
  59         struct landlock_object *object;
  60         /**
  61          * @num_layers: Number of entries in @layers.
  62          */
  63         u32 num_layers;
  64         /**
  65          * @layers: Stack of layers, from the latest to the newest, implemented
  66          * as a flexible array member (FAM).
  67          */
  68         struct landlock_layer layers[];
  69 };
  70
  71 /**
  72  * struct landlock_hierarchy - Node in a ruleset hierarchy
  73  */
  74 struct landlock_hierarchy {
  75         /**
  76          * @parent: Pointer to the parent node, or NULL if it is a root
  77          * Landlock domain.
  78          */
  79         struct landlock_hierarchy *parent;
  80         /**
  81          * @usage: Number of potential children domains plus their parent
  82          * domain.
  83          */
  84         refcount_t usage;
  85 };
  86
  87 /**
  88  * struct landlock_ruleset - Landlock ruleset
  89  *
  90  * This data structure must contain unique entries, be updatable, and quick to
  91  * match an object.
  92  */
  93 struct landlock_ruleset {
  94         /**
  95          * @root: Root of a red-black tree containing &struct landlock_rule
  96          * nodes.  Once a ruleset is tied to a process (i.e. as a domain), this
  97          * tree is immutable until @usage reaches zero.
  98          */
  99         struct rb_root root;
 100         /**
 101          * @hierarchy: Enables hierarchy identification even when a parent
 102          * domain vanishes.  This is needed for the ptrace protection.
 103          */
 104         struct landlock_hierarchy *hierarchy;
 105         union {
 106                 /**
 107                  * @work_free: Enables to free a ruleset within a lockless
 108                  * section.  This is only used by
 109                  * landlock_put_ruleset_deferred() when @usage reaches zero.
 110                  * The fields @lock, @usage, @num_rules, @num_layers and
 111                  * @fs_access_masks are then unused.
 112                  */
 113                 struct work_struct work_free;
 114                 struct {
 115                         /**
 116                          * @lock: Protects against concurrent modifications of
 117                          * @root, if @usage is greater than zero.
 118                          */
 119                         struct mutex lock;
 120                         /**
 121                          * @usage: Number of processes (i.e. domains) or file
 122                          * descriptors referencing this ruleset.
 123                          */
 124                         refcount_t usage;
 125                         /**
 126                          * @num_rules: Number of non-overlapping (i.e. not for
 127                          * the same object) rules in this ruleset.
 128                          */
 129                         u32 num_rules;
 130                         /**
 131                          * @num_layers: Number of layers that are used in this
 132                          * ruleset.  This enables to check that all the layers
 133                          * allow an access request.  A value of 0 identifies a
 134                          * non-merged ruleset (i.e. not a domain).
 135                          */
 136                         u32 num_layers;
 137                         /**
 138                          * @fs_access_masks: Contains the subset of filesystem
 139                          * actions that are restricted by a ruleset.  A domain
 140                          * saves all layers of merged rulesets in a stack
 141                          * (FAM), starting from the first layer to the last
 142                          * one.  These layers are used when merging rulesets,
 143                          * for user space backward compatibility (i.e.
 144                          * future-proof), and to properly handle merged
 145                          * rulesets without overlapping access rights.  These
 146                          * layers are set once and never changed for the
 147                          * lifetime of the ruleset.
 148                          */
 149                         access_mask_t fs_access_masks[];
 150                 };
 151         };
 152 };
 153
 154 struct landlock_ruleset *
 155 landlock_create_ruleset(const access_mask_t fs_access_mask);
 156
 157 void landlock_put_ruleset(struct landlock_ruleset *const ruleset);
 158 void landlock_put_ruleset_deferred(struct landlock_ruleset *const ruleset);
 159
 160 int landlock_insert_rule(struct landlock_ruleset *const ruleset,
 161                          struct landlock_object *const object,
 162                          const access_mask_t access);
 163
 164 struct landlock_ruleset *
 165 landlock_merge_ruleset(struct landlock_ruleset *const parent,
 166                        struct landlock_ruleset *const ruleset);
 167
 168 const struct landlock_rule *
 169 landlock_find_rule(const struct landlock_ruleset *const ruleset,
 170                    const struct landlock_object *const object);
 171
 172 static inline void landlock_get_ruleset(struct landlock_ruleset *const ruleset)
 173 {
 174         if (ruleset)
 175                 refcount_inc(&ruleset->usage);
 176 }
 177
 178 #endif /* _SECURITY_LANDLOCK_RULESET_H */