Documentation: security/credentials.rst: explain need to sort group_list

This patch updates the documentation with the observations that led
to commit bdcf0a423e ("kernel: make groups_sort calling a
responsibility group_info allocators") and the new behaviour required.
Specifically that groups_sort() should be called on a new group_list
before set_groups() or set_current_groups() is called.

Signed-off-by: NeilBrown <neilb@suse.com>
[jc: use proper :c:func: references]
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
This commit is contained in:
NeilBrown 2018-01-03 08:01:15 +11:00 committed by Jonathan Corbet
parent 536ec30477
commit 0b345d722e

View File

@ -451,6 +451,13 @@ checks and hooks done. Both the current and the proposed sets of credentials
are available for this purpose as current_cred() will return the current set
still at this point.
When replacing the group list, the new list must be sorted before it
is added to the credential, as a binary search is used to test for
membership. In practice, this means :c:func:`groups_sort` should be
called before :c:func:`set_groups` or :c:func:`set_current_groups`.
:c:func:`groups_sort)` must not be called on a ``struct group_list`` which
is shared as it may permute elements as part of the sorting process
even if the array is already sorted.
When the credential set is ready, it should be committed to the current process
by calling::