security/landlock/ruleset.h

0001 /* SPDX-License-Identifier: GPL-2.0-only */
0002 /*
0003  * Landlock LSM - Ruleset management
0004  *
0005  * Copyright © 2016-2020 Mickaël Salaün <mic@digikod.net>
0006  * Copyright © 2018-2020 ANSSI
0007  */
0008
0009 #ifndef _SECURITY_LANDLOCK_RULESET_H
0010 #define _SECURITY_LANDLOCK_RULESET_H
0011
0012 #include <linux/bitops.h>
0013 #include <linux/build_bug.h>
0014 #include <linux/mutex.h>
0015 #include <linux/rbtree.h>
0016 #include <linux/refcount.h>
0017 #include <linux/workqueue.h>
0018
0019 #include "limits.h"
0020 #include "object.h"
0021
0022 typedef u16 access_mask_t;
0023 /* Makes sure all filesystem access rights can be stored. */
0024 static_assert(BITS_PER_TYPE(access_mask_t) >= LANDLOCK_NUM_ACCESS_FS);
0025 /* Makes sure for_each_set_bit() and for_each_clear_bit() calls are OK. */
0026 static_assert(sizeof(unsigned long) >= sizeof(access_mask_t));
0027
0028 typedef u16 layer_mask_t;
0029 /* Makes sure all layers can be checked. */
0030 static_assert(BITS_PER_TYPE(layer_mask_t) >= LANDLOCK_MAX_NUM_LAYERS);
0031
0032 /**
0033  * struct landlock_layer - Access rights for a given layer
0034  */
0035 struct landlock_layer {
0036     /**
0037      * @level: Position of this layer in the layer stack.
0038      */
0039     u16 level;
0040     /**
0041      * @access: Bitfield of allowed actions on the kernel object.  They are
0042      * relative to the object type (e.g. %LANDLOCK_ACTION_FS_READ).
0043      */
0044     access_mask_t access;
0045 };
0046
0047 /**
0048  * struct landlock_rule - Access rights tied to an object
0049  */
0050 struct landlock_rule {
0051     /**
0052      * @node: Node in the ruleset's red-black tree.
0053      */
0054     struct rb_node node;
0055     /**
0056      * @object: Pointer to identify a kernel object (e.g. an inode).  This
0057      * is used as a key for this ruleset element.  This pointer is set once
0058      * and never modified.  It always points to an allocated object because
0059      * each rule increments the refcount of its object.
0060      */
0061     struct landlock_object *object;
0062     /**
0063      * @num_layers: Number of entries in @layers.
0064      */
0065     u32 num_layers;
0066     /**
0067      * @layers: Stack of layers, from the latest to the newest, implemented
0068      * as a flexible array member (FAM).
0069      */
0070     struct landlock_layer layers[];
0071 };
0072
0073 /**
0074  * struct landlock_hierarchy - Node in a ruleset hierarchy
0075  */
0076 struct landlock_hierarchy {
0077     /**
0078      * @parent: Pointer to the parent node, or NULL if it is a root
0079      * Landlock domain.
0080      */
0081     struct landlock_hierarchy *parent;
0082     /**
0083      * @usage: Number of potential children domains plus their parent
0084      * domain.
0085      */
0086     refcount_t usage;
0087 };
0088
0089 /**
0090  * struct landlock_ruleset - Landlock ruleset
0091  *
0092  * This data structure must contain unique entries, be updatable, and quick to
0093  * match an object.
0094  */
0095 struct landlock_ruleset {
0096     /**
0097      * @root: Root of a red-black tree containing &struct landlock_rule
0098      * nodes.  Once a ruleset is tied to a process (i.e. as a domain), this
0099      * tree is immutable until @usage reaches zero.
0100      */
0101     struct rb_root root;
0102     /**
0103      * @hierarchy: Enables hierarchy identification even when a parent
0104      * domain vanishes.  This is needed for the ptrace protection.
0105      */
0106     struct landlock_hierarchy *hierarchy;
0107     union {
0108         /**
0109          * @work_free: Enables to free a ruleset within a lockless
0110          * section.  This is only used by
0111          * landlock_put_ruleset_deferred() when @usage reaches zero.
0112          * The fields @lock, @usage, @num_rules, @num_layers and
0113          * @fs_access_masks are then unused.
0114          */
0115         struct work_struct work_free;
0116         struct {
0117             /**
0118              * @lock: Protects against concurrent modifications of
0119              * @root, if @usage is greater than zero.
0120              */
0121             struct mutex lock;
0122             /**
0123              * @usage: Number of processes (i.e. domains) or file
0124              * descriptors referencing this ruleset.
0125              */
0126             refcount_t usage;
0127             /**
0128              * @num_rules: Number of non-overlapping (i.e. not for
0129              * the same object) rules in this ruleset.
0130              */
0131             u32 num_rules;
0132             /**
0133              * @num_layers: Number of layers that are used in this
0134              * ruleset.  This enables to check that all the layers
0135              * allow an access request.  A value of 0 identifies a
0136              * non-merged ruleset (i.e. not a domain).
0137              */
0138             u32 num_layers;
0139             /**
0140              * @fs_access_masks: Contains the subset of filesystem
0141              * actions that are restricted by a ruleset.  A domain
0142              * saves all layers of merged rulesets in a stack
0143              * (FAM), starting from the first layer to the last
0144              * one.  These layers are used when merging rulesets,
0145              * for user space backward compatibility (i.e.
0146              * future-proof), and to properly handle merged
0147              * rulesets without overlapping access rights.  These
0148              * layers are set once and never changed for the
0149              * lifetime of the ruleset.
0150              */
0151             access_mask_t fs_access_masks[];
0152         };
0153     };
0154 };
0155
0156 struct landlock_ruleset *
0157 landlock_create_ruleset(const access_mask_t fs_access_mask);
0158
0159 void landlock_put_ruleset(struct landlock_ruleset *const ruleset);
0160 void landlock_put_ruleset_deferred(struct landlock_ruleset *const ruleset);
0161
0162 int landlock_insert_rule(struct landlock_ruleset *const ruleset,
0163              struct landlock_object *const object,
0164              const access_mask_t access);
0165
0166 struct landlock_ruleset *
0167 landlock_merge_ruleset(struct landlock_ruleset *const parent,
0168                struct landlock_ruleset *const ruleset);
0169
0170 const struct landlock_rule *
0171 landlock_find_rule(const struct landlock_ruleset *const ruleset,
0172            const struct landlock_object *const object);
0173
0174 static inline void landlock_get_ruleset(struct landlock_ruleset *const ruleset)
0175 {
0176     if (ruleset)
0177         refcount_inc(&ruleset->usage);
0178 }
0179
0180 #endif /* _SECURITY_LANDLOCK_RULESET_H */