security/landlock/object.h

   1 /* SPDX-License-Identifier: GPL-2.0-only */
   2 /*
   3  * Landlock LSM - Object management
   4  *
   5  * Copyright © 2016-2020 Mickaël Salaün <mic@digikod.net>
   6  * Copyright © 2018-2020 ANSSI
   7  */
   8
   9 #ifndef _SECURITY_LANDLOCK_OBJECT_H
  10 #define _SECURITY_LANDLOCK_OBJECT_H
  11
  12 #include <linux/compiler_types.h>
  13 #include <linux/refcount.h>
  14 #include <linux/spinlock.h>
  15
  16 struct landlock_object;
  17
  18 /**
  19  * struct landlock_object_underops - Operations on an underlying object
  20  */
  21 struct landlock_object_underops {
  22         /**
  23          * @release: Releases the underlying object (e.g. iput() for an inode).
  24          */
  25         void (*release)(struct landlock_object *const object)
  26                 __releases(object->lock);
  27 };
  28
  29 /**
  30  * struct landlock_object - Security blob tied to a kernel object
  31  *
  32  * The goal of this structure is to enable to tie a set of ephemeral access
  33  * rights (pertaining to different domains) to a kernel object (e.g an inode)
  34  * in a safe way.  This implies to handle concurrent use and modification.
  35  *
  36  * The lifetime of a &struct landlock_object depends on the rules referring to
  37  * it.
  38  */
  39 struct landlock_object {
  40         /**
  41          * @usage: This counter is used to tie an object to the rules matching
  42          * it or to keep it alive while adding a new rule.  If this counter
  43          * reaches zero, this struct must not be modified, but this counter can
  44          * still be read from within an RCU read-side critical section.  When
  45          * adding a new rule to an object with a usage counter of zero, we must
  46          * wait until the pointer to this object is set to NULL (or recycled).
  47          */
  48         refcount_t usage;
  49         /**
  50          * @lock: Protects against concurrent modifications.  This lock must be
  51          * held from the time @usage drops to zero until any weak references
  52          * from @underobj to this object have been cleaned up.
  53          *
  54          * Lock ordering: inode->i_lock nests inside this.
  55          */
  56         spinlock_t lock;
  57         /**
  58          * @underobj: Used when cleaning up an object and to mark an object as
  59          * tied to its underlying kernel structure.  This pointer is protected
  60          * by @lock.  Cf. landlock_release_inodes() and release_inode().
  61          */
  62         void *underobj;
  63         union {
  64                 /**
  65                  * @rcu_free: Enables lockless use of @usage, @lock and
  66                  * @underobj from within an RCU read-side critical section.
  67                  * @rcu_free and @underops are only used by
  68                  * landlock_put_object().
  69                  */
  70                 struct rcu_head rcu_free;
  71                 /**
  72                  * @underops: Enables landlock_put_object() to release the
  73                  * underlying object (e.g. inode).
  74                  */
  75                 const struct landlock_object_underops *underops;
  76         };
  77 };
  78
  79 struct landlock_object *
  80 landlock_create_object(const struct landlock_object_underops *const underops,
  81                        void *const underobj);
  82
  83 void landlock_put_object(struct landlock_object *const object);
  84
  85 static inline void landlock_get_object(struct landlock_object *const object)
  86 {
  87         if (object)
  88                 refcount_inc(&object->usage);
  89 }
  90
  91 #endif /* _SECURITY_LANDLOCK_OBJECT_H */