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