Kernel Protections/refcount t - Revision history

KeesCook: /* Reference Counting API */

2017-08-04T05:20:11Z

Reference Counting API

← Older revision		Revision as of 05:20, 4 August 2017
Line 5:		Line 5:
	= Reference Counting API =		= Reference Counting API =

	~~HARDENED_ATOMIC introduces~~ a new data type: <code>refcount_t</code>. This type is to be used for all kernel reference counters.		Instead of the traditional <code>atomic_t</code>, reference counting uses a new data type: <code>refcount_t</code>. This type is to be used for all kernel reference counters.

	The following is the kernel reference counting API.		The following is the kernel reference counting API.

KeesCook: /* Summary */

2017-08-04T05:19:12Z

Summary

← Older revision		Revision as of 05:19, 4 August 2017
Line 1:		Line 1:
	= Summary =		= Summary =

	~~HARDENED_ATOMIC~~ is a kernel self-protection mechanism that greatly helps with the prevention of [[Bug Classes/Use after free\|use-after-free]] bugs. It is based off of work done by the [https://pax.grsecurity.net PaX Team], originally called [https://forums.grsecurity.net/viewtopic.php?f=7&t=4173 PAX_REFCOUNT].		The refcount_t API is a kernel self-protection mechanism that greatly helps with the prevention of [[Bug Classes/Use after free\|use-after-free]] bugs. It is based off of work done by the [https://pax.grsecurity.net PaX Team], originally called [https://forums.grsecurity.net/viewtopic.php?f=7&t=4173 PAX_REFCOUNT].

	= Reference Counting API =		= Reference Counting API =

KeesCook: KeesCook moved page Kernel Protections/HARDENED ATOMIC to Kernel Protections/refcount t

2017-08-04T05:18:41Z

KeesCook moved page Kernel Protections/HARDENED ATOMIC to Kernel Protections/refcount t

← Older revision	Revision as of 05:18, 4 August 2017
(No difference)

DavidWindsor: Minor language change in Reference Counting API

2017-02-06T14:54:25Z

Minor language change in Reference Counting API

← Older revision		Revision as of 14:54, 6 February 2017
Line 7:		Line 7:
	HARDENED_ATOMIC introduces a new data type: <code>refcount_t</code>. This type is to be used for all kernel reference counters.		HARDENED_ATOMIC introduces a new data type: <code>refcount_t</code>. This type is to be used for all kernel reference counters.

	The following is the kernel reference counting API~~. Please note that all operations are atomic, unless otherwise specified~~.		The following is the kernel reference counting API.

	;'''<code>REFCOUNT_INIT(unsigned int)</code>'''		;'''<code>REFCOUNT_INIT(unsigned int)</code>'''
Line 47:		Line 47:
	;'''<code>bool refcount_dec_and_lock(refcount_t r, spinlock_t s)</code>'''		;'''<code>bool refcount_dec_and_lock(refcount_t r, spinlock_t s)</code>'''
	: Decrement <code>r</code> and lock spinlock if <code>r</code> becomes 0. Will <code>WARN</code> on underflow and fail to decrement if <code>r</code> is saturated at <code>UINT_MAX</code>. Returns <code>true</code> if <code>r</code> is 0 and spinlock is held, <code>false</code> otherwise.		: Decrement <code>r</code> and lock spinlock if <code>r</code> becomes 0. Will <code>WARN</code> on underflow and fail to decrement if <code>r</code> is saturated at <code>UINT_MAX</code>. Returns <code>true</code> if <code>r</code> is 0 and spinlock is held, <code>false</code> otherwise.


	= Examples =		= Examples =

DavidWindsor: Minor language change in Summary

2017-02-06T14:53:47Z

Minor language change in Summary

← Older revision		Revision as of 14:53, 6 February 2017
Line 1:		Line 1:
	= Summary =		= Summary =

	HARDENED_ATOMIC is a kernel self-protection mechanism that greatly helps with the ~~mitigation~~ of [[Bug Classes/Use after free\|use-after-free]] bugs. It is based off of work done by the [https://pax.grsecurity.net PaX Team], originally called [https://forums.grsecurity.net/viewtopic.php?f=7&t=4173 PAX_REFCOUNT].		HARDENED_ATOMIC is a kernel self-protection mechanism that greatly helps with the prevention of [[Bug Classes/Use after free\|use-after-free]] bugs. It is based off of work done by the [https://pax.grsecurity.net PaX Team], originally called [https://forums.grsecurity.net/viewtopic.php?f=7&t=4173 PAX_REFCOUNT].

	= Reference Counting API =		= Reference Counting API =

DavidWindsor: Add Examples section

2017-02-06T14:45:47Z

Add Examples section

← Older revision		Revision as of 14:45, 6 February 2017
Line 47:		Line 47:
	;'''<code>bool refcount_dec_and_lock(refcount_t r, spinlock_t s)</code>'''		;'''<code>bool refcount_dec_and_lock(refcount_t r, spinlock_t s)</code>'''
	: Decrement <code>r</code> and lock spinlock if <code>r</code> becomes 0. Will <code>WARN</code> on underflow and fail to decrement if <code>r</code> is saturated at <code>UINT_MAX</code>. Returns <code>true</code> if <code>r</code> is 0 and spinlock is held, <code>false</code> otherwise.		: Decrement <code>r</code> and lock spinlock if <code>r</code> becomes 0. Will <code>WARN</code> on underflow and fail to decrement if <code>r</code> is saturated at <code>UINT_MAX</code>. Returns <code>true</code> if <code>r</code> is 0 and spinlock is held, <code>false</code> otherwise.


			= Examples =

			The following use case is an instance of correct usage of the <code>refcount_t</code> API. The object being counted is <code>struct super_block</code>, which represents a virtual filesystem superblock, an object containing a particular filesystem's metadata such as block size, the root inode, etc.

			==== Member Definition ====

			This is the definition of the reference counter field in the <code>struct super_block</code> object. If the object being counted is a structure, the reference counter is typically defined as a field of the counted structure, as we see in <code>struct super_block</code> below.

			From <code>[http://lxr.free-electrons.com/source/include/linux/fs.h include/linux/fs.h]</code>:

			<code>
			struct super_block {
			...
			refcount_t s_active;
			...
			};
			</code>

			==== Object Initialization ====

			When a counted object is created, its reference counter must be initialized to something sane, typically 1 (since, by virtue of being called in an "allocation" method, a user of the object already exists).

			From <code>[http://lxr.free-electrons.com/source/fs/super.c fs/super.c]</code>:

			<code>
			static struct super_block alloc_super(struct file_system_type type, int flags, struct user_namespace *user_ns)
			{
			struct super_block *s = kzalloc(sizeof(struct super_block), GFP_USER);
			...
			refcount_set(&s->s_active, 1);
			...
			}
			</code>

			==== Getting a New Reference ====
			This code is executed when a user wishes to obtain a new reference to a <code>struct super_block</code> object. The following code corresponds to the traditional reference counting "get" method.

			From <code>[http://lxr.free-electrons.com/source/fs/super.c fs/super.c]</code>:

			<code>
			static int grab_super(struct super_block *s) __releases(sb_lock)
			{
			s->s_count++;
			spin_unlock(&sb_lock);
			down_write(&s->s_umount);
			if ((s->s_flags & MS_BORN) && refcount_inc_not_zero(&s->s_active)) {
			put_super(s);
			return 1;
			}
			up_write(&s->s_umount);
			put_super(s);
			return 0;
			}
			</code>

			==== Releasing an Existing Reference ====
			This code is executed when a user currently holding a reference to a <code>struct super_block</code> object no longer needs the object and wants to release it. The following code corresponds to the traditional reference counting "put" method.

			From <code>[http://lxr.free-electrons.com/source/fs/super.c fs/super.c]</code>:

			<code>
			void deactivate_locked_super(struct super_block *s) {
			...
			if (refcount_dec_and_test(&s->s_active)) {
			...
			put_super(s);
			}
			}

			void deactivate_super(struct super_block *s)
			{
			if (!refcount_dec_not_one(&s->s_active)) {
			down_write(&s->s_umount);nnNnnn
			deactivate_locked_super(s);
			}
			}
			</code>

DavidWindsor: Change `tags to`

2017-02-06T12:19:19Z Change <tt> tags to <code> ← Older revision Revision as of 12:19, 6 February 2017 Line 5: Line 5: = Reference Counting API = = Reference Counting API = HARDENED_ATOMIC introduces a new data type: <tt>refcount_t</tt>. This type is to be used for all kernel reference counters. HARDENED_ATOMIC introduces a new data type: <code>refcount_t</code>. This type is to be used for all kernel reference counters. The following is the kernel reference counting API. Please note that all operations are atomic, unless otherwise specified. The following is the kernel reference counting API. Please note that all operations are atomic, unless otherwise specified. ;'''<tt>REFCOUNT_INIT(unsigned int)</tt>''' ;'''<code>REFCOUNT_INIT(unsigned int)</code>''' : Initialize a <tt>refcount_t</tt> object. : Initialize a <code>refcount_t</code> object. ;'''<tt>void refcount_set(refcount_t *, unsigned int)</tt>''' ;'''<code>void refcount_set(refcount_t *, unsigned int)</code>''' : Set a <tt>refcount_t</tt> object's internal value. : Set a <code>refcount_t</code> object's internal value. ;'''<tt>unsigned int refcount_read(refcount_t *)</tt>''' ;'''<code>unsigned int refcount_read(refcount_t *)</code>''' : Returns the <tt>refcount_t</tt> object's internal value. : Returns the <code>refcount_t</code> object's internal value. ;'''<tt>bool refcount_add_not_zero(unsigned int v, refcount_t *r)</tt>''' ;'''<code>bool refcount_add_not_zero(unsigned int v, refcount_t *r)</code>''' : Add <tt>v</tt> to <tt>r</tt>. If <tt>r + v</tt> causes an overflow, the result of the addition operation is not saved to <tt>r</tt>. Returns <tt>true</tt> if the resulting value of <tt>r</tt> is non-zero, <tt>false</tt> otherwise. : Add <code>v</code> to <code>r</code>. If <code>r + v</code> causes an overflow, the result of the addition operation is not saved to <code>r</code>. Returns <code>true</code> if the resulting value of <code>r</code> is non-zero, <code>false</code> otherwise. ;'''<tt>void refcount_add(unsigned int v, refcount_t *r)</tt>''' ;'''<code>void refcount_add(unsigned int v, refcount_t *r)</code>''' : Adds <tt>v</tt> to <tt>r</tt> and stores the value in <tt>r</tt>. : Adds <code>v</code> to <code>r</code> and stores the value in <code>r</code>. ;'''<tt>bool refcount_inc_not_zero(refcount_t *r)</tt>''' ;'''<code>bool refcount_inc_not_zero(refcount_t *r)</code>''' : Increments <tt>r</tt> and tests whether <tt>r + 1</tt> causes an overflow. If an overflow does occur, the result of the increment operation is not saved to <tt>r</tt>. Will saturate at <tt>UINT_MAX</tt> and <tt>WARN</tt>. Returns <tt>true</tt> if the resulting value of <tt>r</tt> is non-zero, <tt>false</tt> otherwise. : Increments <code>r</code> and tests whether <code>r + 1</code> causes an overflow. If an overflow does occur, the result of the increment operation is not saved to <code>r</code>. Will saturate at <code>UINT_MAX</code> and <code>WARN</code>. Returns <code>true</code> if the resulting value of <code>r</code> is non-zero, <code>false</code> otherwise. ;'''<tt>void refcount_inc(refcount_t *r)</tt>''' ;'''<code>void refcount_inc(refcount_t *r)</code>''' : Increment <tt>r</tt>. Will saturate at <tt>UINT_MAX</tt> and <tt>WARN</tt>. : Increment <code>r</code>. Will saturate at <code>UINT_MAX</code> and <code>WARN</code>. ;'''<tt>bool refcount_sub_and_test(unsigned int v, refcount_t *r)</tt>''' ;'''<code>bool refcount_sub_and_test(unsigned int v, refcount_t *r)</code>''' : Subtract <tt>v</tt> from <tt>r</tt> and tests whether <tt>r - v</tt> causes an underflow. If an underflow does occur, the result of the decrement operation is not saved to <tt>r</tt>. Will fail to decrement when saturated at <tt>UINT_MAX</tt>. Returns <tt>true</tt> if the resulting value of <tt>r</tt> is non-zero, <tt>false</tt> otherwise. : Subtract <code>v</code> from <code>r</code> and tests whether <code>r - v</code> causes an underflow. If an underflow does occur, the result of the decrement operation is not saved to <code>r</code>. Will fail to decrement when saturated at <code>UINT_MAX</code>. Returns <code>true</code> if the resulting value of <code>r</code> is non-zero, <code>false</code> otherwise. ;'''<tt>void refcount_dec(refcount_t *r)</tt>''' ;'''<code>void refcount_dec(refcount_t *r)</code>''' : Decrement <tt>r</tt>. If <tt>r - 1</tt> causes an underflow, the result of the decrement operation is not saved to <tt>r</tt>. Will fail to decrement when saturated at <tt>UINT_MAX</tt>. : Decrement <code>r</code>. If <code>r - 1</code> causes an underflow, the result of the decrement operation is not saved to <code>r</code>. Will fail to decrement when saturated at <code>UINT_MAX</code>. ;'''<tt>bool refcount_dec_if_one(refcount_t *r)</tt>''' ;'''<code>bool refcount_dec_if_one(refcount_t *r)</code>''' : Attempts to transition <tt>r</tt> from 1 to 0. If <tt>r</tt> is 1, decrement it to 0. Returns <tt>true</tt> if <tt>r</tt> was decremented, <tt>false</tt> otherwise. : Attempts to transition <code>r</code> from 1 to 0. If <code>r</code> is 1, decrement it to 0. Returns <code>true</code> if <code>r</code> was decremented, <code>false</code> otherwise. ;'''<tt>bool refcount_dec_not_one(refcount_t *r)</tt>''' ;'''<code>bool refcount_dec_not_one(refcount_t *r)</code>''' : Decrement <tt>r</tt> unless the value of <tt>r</tt> is 1. Returns <tt>true</tt> if <tt>r</tt> was decremented, </tt>false</tt> otherwise. : Decrement <code>r</code> unless the value of <code>r</code> is 1. Returns <code>true</code> if <code>r</code> was decremented, </code>false</code> otherwise. ;'''<tt>bool refcount_dec_and_mutex_lock(refcount_t *r, struct mutex *lock)</tt>''' ;'''<code>bool refcount_dec_and_mutex_lock(refcount_t *r, struct mutex *lock)</code>''' : Decrement <tt>r</tt> and lock mutex if <tt>r</tt> becomes 0. Will <tt>WARN</tt> on underflow and fail to decrement if <tt>r</tt> is saturated at <tt>UINT_MAX</tt>. Returns <tt>true</tt> if <tt>r</tt> is 0 and mutex is held, <tt>false</tt> otherwise. : Decrement <code>r</code> and lock mutex if <code>r</code> becomes 0. Will <code>WARN</code> on underflow and fail to decrement if <code>r</code> is saturated at <code>UINT_MAX</code>. Returns <code>true</code> if <code>r</code> is 0 and mutex is held, <code>false</code> otherwise. ;'''<tt>bool refcount_dec_and_lock(refcount_t *r, spinlock_t *s)</tt>''' ;'''<code>bool refcount_dec_and_lock(refcount_t *r, spinlock_t *s)</code>''' : Decrement <tt>r</tt> and lock spinlock if <tt>r</tt> becomes 0. Will <tt>WARN</tt> on underflow and fail to decrement if <tt>r</tt> is saturated at <tt>UINT_MAX</tt>. Returns <tt>true</tt> if <tt>r</tt> is 0 and spinlock is held, <tt>false</tt> otherwise. : Decrement <code>r</code> and lock spinlock if <code>r</code> becomes 0. Will <code>WARN</code> on underflow and fail to decrement if <code>r</code> is saturated at <code>UINT_MAX</code>. Returns <code>true</code> if <code>r</code> is 0 and spinlock is held, <code>false</code> otherwise.

DavidWindsor: Minor language change in Reference Counting API 2017-02-04T11:20:47Z Minor language change in Reference Counting API ← Older revision Revision as of 11:20, 4 February 2017 Line 7: Line 7: HARDENED_ATOMIC introduces a new data type: <tt>refcount_t</tt>. This type is to be used for all kernel reference counters. HARDENED_ATOMIC introduces a new data type: <tt>refcount_t</tt>. This type is to be used for all kernel reference counters. The following operations are the kernel reference counting API. Please note that all operations are atomic, unless otherwise specified. The following is the kernel reference counting API. Please note that all operations are atomic, unless otherwise specified. ;'''<tt>REFCOUNT_INIT(unsigned int)</tt>''' ;'''<tt>REFCOUNT_INIT(unsigned int)</tt>''' DavidWindsor: Minor language change in Summary 2017-02-04T11:19:13Z Minor language change in Summary ← Older revision Revision as of 11:19, 4 February 2017 Line 1: Line 1: = Summary = = Summary = HARDENED_ATOMIC is a kernel self-protection feature that greatly helps with the mitigation of [[Bug Classes/Use after free|use-after-free]] bugs. It is based off of work done by the [https://pax.grsecurity.net PaX Team], originally called [https://forums.grsecurity.net/viewtopic.php?f=7&t=4173 PAX_REFCOUNT]. HARDENED_ATOMIC is a kernel self-protection mechanism that greatly helps with the mitigation of [[Bug Classes/Use after free|use-after-free]] bugs. It is based off of work done by the [https://pax.grsecurity.net PaX Team], originally called [https://forums.grsecurity.net/viewtopic.php?f=7&t=4173 PAX_REFCOUNT]. = Reference Counting API = = Reference Counting API = DavidWindsor: Add refcount_t API 2017-02-04T06:42:17Z Add refcount_t API New page = Summary = HARDENED_ATOMIC is a kernel self-protection feature that greatly helps with the mitigation of [[Bug Classes/Use after free|use-after-free]] bugs. It is based off of work done by the [https://pax.grsecurity.net PaX Team], originally called [https://forums.grsecurity.net/viewtopic.php?f=7&t=4173 PAX_REFCOUNT]. = Reference Counting API = HARDENED_ATOMIC introduces a new data type: <tt>refcount_t</tt>. This type is to be used for all kernel reference counters. The following operations are the kernel reference counting API. Please note that all operations are atomic, unless otherwise specified. ;'''<tt>REFCOUNT_INIT(unsigned int)</tt>''' : Initialize a <tt>refcount_t</tt> object. ;'''<tt>void refcount_set(refcount_t *, unsigned int)</tt>''' : Set a <tt>refcount_t</tt> object's internal value. ;'''<tt>unsigned int refcount_read(refcount_t *)</tt>''' : Returns the <tt>refcount_t</tt> object's internal value. ;'''<tt>bool refcount_add_not_zero(unsigned int v, refcount_t *r)</tt>''' : Add <tt>v</tt> to <tt>r</tt>. If <tt>r + v</tt> causes an overflow, the result of the addition operation is not saved to <tt>r</tt>. Returns <tt>true</tt> if the resulting value of <tt>r</tt> is non-zero, <tt>false</tt> otherwise. ;'''<tt>void refcount_add(unsigned int v, refcount_t *r)</tt>''' : Adds <tt>v</tt> to <tt>r</tt> and stores the value in <tt>r</tt>. ;'''<tt>bool refcount_inc_not_zero(refcount_t *r)</tt>''' : Increments <tt>r</tt> and tests whether <tt>r + 1</tt> causes an overflow. If an overflow does occur, the result of the increment operation is not saved to <tt>r</tt>. Will saturate at <tt>UINT_MAX</tt> and <tt>WARN</tt>. Returns <tt>true</tt> if the resulting value of <tt>r</tt> is non-zero, <tt>false</tt> otherwise. ;'''<tt>void refcount_inc(refcount_t *r)</tt>''' : Increment <tt>r</tt>. Will saturate at <tt>UINT_MAX</tt> and <tt>WARN</tt>. ;'''<tt>bool refcount_sub_and_test(unsigned int v, refcount_t *r)</tt>''' : Subtract <tt>v</tt> from <tt>r</tt> and tests whether <tt>r - v</tt> causes an underflow. If an underflow does occur, the result of the decrement operation is not saved to <tt>r</tt>. Will fail to decrement when saturated at <tt>UINT_MAX</tt>. Returns <tt>true</tt> if the resulting value of <tt>r</tt> is non-zero, <tt>false</tt> otherwise. ;'''<tt>void refcount_dec(refcount_t *r)</tt>''' : Decrement <tt>r</tt>. If <tt>r - 1</tt> causes an underflow, the result of the decrement operation is not saved to <tt>r</tt>. Will fail to decrement when saturated at <tt>UINT_MAX</tt>. ;'''<tt>bool refcount_dec_if_one(refcount_t *r)</tt>''' : Attempts to transition <tt>r</tt> from 1 to 0. If <tt>r</tt> is 1, decrement it to 0. Returns <tt>true</tt> if <tt>r</tt> was decremented, <tt>false</tt> otherwise. ;'''<tt>bool refcount_dec_not_one(refcount_t *r)</tt>''' : Decrement <tt>r</tt> unless the value of <tt>r</tt> is 1. Returns <tt>true</tt> if <tt>r</tt> was decremented, </tt>false</tt> otherwise. ;'''<tt>bool refcount_dec_and_mutex_lock(refcount_t *r, struct mutex *lock)</tt>''' : Decrement <tt>r</tt> and lock mutex if <tt>r</tt> becomes 0. Will <tt>WARN</tt> on underflow and fail to decrement if <tt>r</tt> is saturated at <tt>UINT_MAX</tt>. Returns <tt>true</tt> if <tt>r</tt> is 0 and mutex is held, <tt>false</tt> otherwise. ;'''<tt>bool refcount_dec_and_lock(refcount_t *r, spinlock_t *s)</tt>''' : Decrement <tt>r</tt> and lock spinlock if <tt>r</tt> becomes 0. Will <tt>WARN</tt> on underflow and fail to decrement if <tt>r</tt> is saturated at <tt>UINT_MAX</tt>. Returns <tt>true</tt> if <tt>r</tt> is 0 and spinlock is held, <tt>false</tt> otherwise.

← Older revision		Revision as of 12:19, 6 February 2017
Line 5:		Line 5:
	= Reference Counting API =		= Reference Counting API =

	HARDENED_ATOMIC introduces a new data type: <tt>refcount_t</tt>. This type is to be used for all kernel reference counters.		HARDENED_ATOMIC introduces a new data type: <code>refcount_t</code>. This type is to be used for all kernel reference counters.

	The following is the kernel reference counting API. Please note that all operations are atomic, unless otherwise specified.		The following is the kernel reference counting API. Please note that all operations are atomic, unless otherwise specified.

	;'''<tt>REFCOUNT_INIT(unsigned int)</tt>'''		;'''<code>REFCOUNT_INIT(unsigned int)</code>'''
	: Initialize a <tt>refcount_t</tt> object.		: Initialize a <code>refcount_t</code> object.

	;'''<tt>void refcount_set(refcount_t *, unsigned int)</tt>'''		;'''<code>void refcount_set(refcount_t *, unsigned int)</code>'''
	: Set a <tt>refcount_t</tt> object's internal value.		: Set a <code>refcount_t</code> object's internal value.

	;'''<tt>unsigned int refcount_read(refcount_t *)</tt>'''		;'''<code>unsigned int refcount_read(refcount_t *)</code>'''
	: Returns the <tt>refcount_t</tt> object's internal value.		: Returns the <code>refcount_t</code> object's internal value.

	;'''<tt>bool refcount_add_not_zero(unsigned int v, refcount_t *r)</tt>'''		;'''<code>bool refcount_add_not_zero(unsigned int v, refcount_t *r)</code>'''
	: Add <tt>v</tt> to <tt>r</tt>. If <tt>r + v</tt> causes an overflow, the result of the addition operation is not saved to <tt>r</tt>. Returns <tt>true</tt> if the resulting value of <tt>r</tt> is non-zero, <tt>false</tt> otherwise.		: Add <code>v</code> to <code>r</code>. If <code>r + v</code> causes an overflow, the result of the addition operation is not saved to <code>r</code>. Returns <code>true</code> if the resulting value of <code>r</code> is non-zero, <code>false</code> otherwise.

	;'''<tt>void refcount_add(unsigned int v, refcount_t *r)</tt>'''		;'''<code>void refcount_add(unsigned int v, refcount_t *r)</code>'''
	: Adds <tt>v</tt> to <tt>r</tt> and stores the value in <tt>r</tt>.		: Adds <code>v</code> to <code>r</code> and stores the value in <code>r</code>.

	;'''<tt>bool refcount_inc_not_zero(refcount_t *r)</tt>'''		;'''<code>bool refcount_inc_not_zero(refcount_t *r)</code>'''
	: Increments <tt>r</tt> and tests whether <tt>r + 1</tt> causes an overflow. If an overflow does occur, the result of the increment operation is not saved to <tt>r</tt>. Will saturate at <tt>UINT_MAX</tt> and <tt>WARN</tt>. Returns <tt>true</tt> if the resulting value of <tt>r</tt> is non-zero, <tt>false</tt> otherwise.		: Increments <code>r</code> and tests whether <code>r + 1</code> causes an overflow. If an overflow does occur, the result of the increment operation is not saved to <code>r</code>. Will saturate at <code>UINT_MAX</code> and <code>WARN</code>. Returns <code>true</code> if the resulting value of <code>r</code> is non-zero, <code>false</code> otherwise.

	;'''<tt>void refcount_inc(refcount_t *r)</tt>'''		;'''<code>void refcount_inc(refcount_t *r)</code>'''
	: Increment <tt>r</tt>. Will saturate at <tt>UINT_MAX</tt> and <tt>WARN</tt>.		: Increment <code>r</code>. Will saturate at <code>UINT_MAX</code> and <code>WARN</code>.

	;'''<tt>bool refcount_sub_and_test(unsigned int v, refcount_t *r)</tt>'''		;'''<code>bool refcount_sub_and_test(unsigned int v, refcount_t *r)</code>'''
	: Subtract <tt>v</tt> from <tt>r</tt> and tests whether <tt>r - v</tt> causes an underflow. If an underflow does occur, the result of the decrement operation is not saved to <tt>r</tt>. Will fail to decrement when saturated at <tt>UINT_MAX</tt>. Returns <tt>true</tt> if the resulting value of <tt>r</tt> is non-zero, <tt>false</tt> otherwise.		: Subtract <code>v</code> from <code>r</code> and tests whether <code>r - v</code> causes an underflow. If an underflow does occur, the result of the decrement operation is not saved to <code>r</code>. Will fail to decrement when saturated at <code>UINT_MAX</code>. Returns <code>true</code> if the resulting value of <code>r</code> is non-zero, <code>false</code> otherwise.

	;'''<tt>void refcount_dec(refcount_t *r)</tt>'''		;'''<code>void refcount_dec(refcount_t *r)</code>'''
	: Decrement <tt>r</tt>. If <tt>r - 1</tt> causes an underflow, the result of the decrement operation is not saved to <tt>r</tt>. Will fail to decrement when saturated at <tt>UINT_MAX</tt>.		: Decrement <code>r</code>. If <code>r - 1</code> causes an underflow, the result of the decrement operation is not saved to <code>r</code>. Will fail to decrement when saturated at <code>UINT_MAX</code>.

	;'''<tt>bool refcount_dec_if_one(refcount_t *r)</tt>'''		;'''<code>bool refcount_dec_if_one(refcount_t *r)</code>'''
	: Attempts to transition <tt>r</tt> from 1 to 0. If <tt>r</tt> is 1, decrement it to 0. Returns <tt>true</tt> if <tt>r</tt> was decremented, <tt>false</tt> otherwise.		: Attempts to transition <code>r</code> from 1 to 0. If <code>r</code> is 1, decrement it to 0. Returns <code>true</code> if <code>r</code> was decremented, <code>false</code> otherwise.

	;'''<tt>bool refcount_dec_not_one(refcount_t *r)</tt>'''		;'''<code>bool refcount_dec_not_one(refcount_t *r)</code>'''
	: Decrement <tt>r</tt> unless the value of <tt>r</tt> is 1. Returns <tt>true</tt> if <tt>r</tt> was decremented, </tt>false</tt> otherwise.		: Decrement <code>r</code> unless the value of <code>r</code> is 1. Returns <code>true</code> if <code>r</code> was decremented, </code>false</code> otherwise.

	;'''<tt>bool refcount_dec_and_mutex_lock(refcount_t r, struct mutex lock)</tt>'''		;'''<code>bool refcount_dec_and_mutex_lock(refcount_t r, struct mutex lock)</code>'''
	: Decrement <tt>r</tt> and lock mutex if <tt>r</tt> becomes 0. Will <tt>WARN</tt> on underflow and fail to decrement if <tt>r</tt> is saturated at <tt>UINT_MAX</tt>. Returns <tt>true</tt> if <tt>r</tt> is 0 and mutex is held, <tt>false</tt> otherwise.		: Decrement <code>r</code> and lock mutex if <code>r</code> becomes 0. Will <code>WARN</code> on underflow and fail to decrement if <code>r</code> is saturated at <code>UINT_MAX</code>. Returns <code>true</code> if <code>r</code> is 0 and mutex is held, <code>false</code> otherwise.

	;'''<tt>bool refcount_dec_and_lock(refcount_t r, spinlock_t s)</tt>'''		;'''<code>bool refcount_dec_and_lock(refcount_t r, spinlock_t s)</code>'''
	: Decrement <tt>r</tt> and lock spinlock if <tt>r</tt> becomes 0. Will <tt>WARN</tt> on underflow and fail to decrement if <tt>r</tt> is saturated at <tt>UINT_MAX</tt>. Returns <tt>true</tt> if <tt>r</tt> is 0 and spinlock is held, <tt>false</tt> otherwise.		: Decrement <code>r</code> and lock spinlock if <code>r</code> becomes 0. Will <code>WARN</code> on underflow and fail to decrement if <code>r</code> is saturated at <code>UINT_MAX</code>. Returns <code>true</code> if <code>r</code> is 0 and spinlock is held, <code>false</code> otherwise.

← Older revision		Revision as of 11:20, 4 February 2017
Line 7:		Line 7:
	HARDENED_ATOMIC introduces a new data type: <tt>refcount_t</tt>. This type is to be used for all kernel reference counters.		HARDENED_ATOMIC introduces a new data type: <tt>refcount_t</tt>. This type is to be used for all kernel reference counters.

	The following ~~operations are~~ the kernel reference counting API. Please note that all operations are atomic, unless otherwise specified.		The following is the kernel reference counting API. Please note that all operations are atomic, unless otherwise specified.

	;'''<tt>REFCOUNT_INIT(unsigned int)</tt>'''		;'''<tt>REFCOUNT_INIT(unsigned int)</tt>'''

← Older revision		Revision as of 11:19, 4 February 2017
Line 1:		Line 1:
	= Summary =		= Summary =

	HARDENED_ATOMIC is a kernel self-protection ~~feature~~ that greatly helps with the mitigation of [[Bug Classes/Use after free\|use-after-free]] bugs. It is based off of work done by the [https://pax.grsecurity.net PaX Team], originally called [https://forums.grsecurity.net/viewtopic.php?f=7&t=4173 PAX_REFCOUNT].		HARDENED_ATOMIC is a kernel self-protection mechanism that greatly helps with the mitigation of [[Bug Classes/Use after free\|use-after-free]] bugs. It is based off of work done by the [https://pax.grsecurity.net PaX Team], originally called [https://forums.grsecurity.net/viewtopic.php?f=7&t=4173 PAX_REFCOUNT].

	= Reference Counting API =		= Reference Counting API =

Kernel Protections/refcount t - Revision history

KeesCook: /* Reference Counting API */

KeesCook: /* Summary */

KeesCook: KeesCook moved page Kernel Protections/HARDENED ATOMIC to Kernel Protections/refcount t

DavidWindsor: Minor language change in Reference Counting API

DavidWindsor: Minor language change in Summary

DavidWindsor: Add Examples section

DavidWindsor: Change tags to

DavidWindsor: Minor language change in Reference Counting API

DavidWindsor: Minor language change in Summary

DavidWindsor: Add refcount_t API

DavidWindsor: Change `tags to`