Skip to content

Commit 2fff00c

Browse files
committed
landlock: Fix documentation style
It seems that all code should use double backquotes, which is also used to convert "%" defines. Let's use an homogeneous style and remove all use of simple backquotes (which should only be used for emphasis). Cc: Günther Noack <gnoack3000@gmail.com> Cc: Paul Moore <paul@paul-moore.com> Signed-off-by: Mickaël Salaün <mic@digikod.net> Link: https://lore.kernel.org/r/20220923154207.3311629-4-mic@digikod.net
1 parent 16023b0 commit 2fff00c

File tree

4 files changed

+40
-39
lines changed

4 files changed

+40
-39
lines changed

Documentation/security/landlock.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -54,8 +54,8 @@ content of a listed inode. Indeed, a file name is local to its parent
5454
directory, and an inode can be referenced by multiple file names thanks to
5555
(hard) links. Being able to unlink a file only has a direct impact on the
5656
directory, not the unlinked inode. This is the reason why
57-
`LANDLOCK_ACCESS_FS_REMOVE_FILE` or `LANDLOCK_ACCESS_FS_REFER` are not allowed
58-
to be tied to files but only to directories.
57+
``LANDLOCK_ACCESS_FS_REMOVE_FILE`` or ``LANDLOCK_ACCESS_FS_REFER`` are not
58+
allowed to be tied to files but only to directories.
5959

6060
Tests
6161
=====

Documentation/userspace-api/landlock.rst

Lines changed: 13 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -69,7 +69,7 @@ should try to protect users as much as possible whatever the kernel they are
6969
using. To avoid binary enforcement (i.e. either all security features or
7070
none), we can leverage a dedicated Landlock command to get the current version
7171
of the Landlock ABI and adapt the handled accesses. Let's check if we should
72-
remove the `LANDLOCK_ACCESS_FS_REFER` access right which is only supported
72+
remove the ``LANDLOCK_ACCESS_FS_REFER`` access right which is only supported
7373
starting with the second version of the ABI.
7474

7575
.. code-block:: c
@@ -128,7 +128,7 @@ descriptor.
128128
It may also be required to create rules following the same logic as explained
129129
for the ruleset creation, by filtering access rights according to the Landlock
130130
ABI version. In this example, this is not required because
131-
`LANDLOCK_ACCESS_FS_REFER` is not allowed by any rule.
131+
``LANDLOCK_ACCESS_FS_REFER`` is not allowed by any rule.
132132

133133
We now have a ruleset with one rule allowing read access to ``/usr`` while
134134
denying all other handled accesses for the filesystem. The next step is to
@@ -154,8 +154,8 @@ The current thread is now ready to sandbox itself with the ruleset.
154154
}
155155
close(ruleset_fd);
156156
157-
If the `landlock_restrict_self` system call succeeds, the current thread is now
158-
restricted and this policy will be enforced on all its subsequently created
157+
If the ``landlock_restrict_self`` system call succeeds, the current thread is
158+
now restricted and this policy will be enforced on all its subsequently created
159159
children as well. Once a thread is landlocked, there is no way to remove its
160160
security policy; only adding more restrictions is allowed. These threads are
161161
now in a new Landlock domain, merge of their parent one (if any) with the new
@@ -175,7 +175,8 @@ depend on their location (i.e. parent directories). This is particularly
175175
relevant when we want to allow linking or renaming. Indeed, having consistent
176176
access rights per directory enables to change the location of such directory
177177
without relying on the destination directory access rights (except those that
178-
are required for this operation, see `LANDLOCK_ACCESS_FS_REFER` documentation).
178+
are required for this operation, see ``LANDLOCK_ACCESS_FS_REFER``
179+
documentation).
179180
Having self-sufficient hierarchies also helps to tighten the required access
180181
rights to the minimal set of data. This also helps avoid sinkhole directories,
181182
i.e. directories where data can be linked to but not linked from. However,
@@ -259,7 +260,7 @@ Backward and forward compatibility
259260

260261
Landlock is designed to be compatible with past and future versions of the
261262
kernel. This is achieved thanks to the system call attributes and the
262-
associated bitflags, particularly the ruleset's `handled_access_fs`. Making
263+
associated bitflags, particularly the ruleset's ``handled_access_fs``. Making
263264
handled access right explicit enables the kernel and user space to have a clear
264265
contract with each other. This is required to make sure sandboxing will not
265266
get stricter with a system update, which could break applications.
@@ -394,7 +395,7 @@ according to the potentially lost constraints. To protect against privilege
394395
escalations through renaming or linking, and for the sake of simplicity,
395396
Landlock previously limited linking and renaming to the same directory.
396397
Starting with the Landlock ABI version 2, it is now possible to securely
397-
control renaming and linking thanks to the new `LANDLOCK_ACCESS_FS_REFER`
398+
control renaming and linking thanks to the new ``LANDLOCK_ACCESS_FS_REFER``
398399
access right.
399400

400401
.. _kernel_support:
@@ -403,14 +404,14 @@ Kernel support
403404
==============
404405

405406
Landlock was first introduced in Linux 5.13 but it must be configured at build
406-
time with `CONFIG_SECURITY_LANDLOCK=y`. Landlock must also be enabled at boot
407+
time with ``CONFIG_SECURITY_LANDLOCK=y``. Landlock must also be enabled at boot
407408
time as the other security modules. The list of security modules enabled by
408-
default is set with `CONFIG_LSM`. The kernel configuration should then
409-
contains `CONFIG_LSM=landlock,[...]` with `[...]` as the list of other
409+
default is set with ``CONFIG_LSM``. The kernel configuration should then
410+
contains ``CONFIG_LSM=landlock,[...]`` with ``[...]`` as the list of other
410411
potentially useful security modules for the running system (see the
411-
`CONFIG_LSM` help).
412+
``CONFIG_LSM`` help).
412413

413-
If the running kernel does not have `landlock` in `CONFIG_LSM`, then we can
414+
If the running kernel does not have ``landlock`` in ``CONFIG_LSM``, then we can
414415
still enable it by adding ``lsm=landlock,[...]`` to
415416
Documentation/admin-guide/kernel-parameters.rst thanks to the bootloader
416417
configuration.

include/uapi/linux/landlock.h

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ struct landlock_ruleset_attr {
2626
* Landlock filesystem access rights that are not part of
2727
* handled_access_fs are allowed. This is needed for backward
2828
* compatibility reasons. One exception is the
29-
* LANDLOCK_ACCESS_FS_REFER access right, which is always implicitly
29+
* %LANDLOCK_ACCESS_FS_REFER access right, which is always implicitly
3030
* handled, but must still be explicitly handled to add new rules with
3131
* this access right.
3232
*/
@@ -128,11 +128,11 @@ struct landlock_path_beneath_attr {
128128
* hierarchy must also always have the same or a superset of restrictions of
129129
* the source hierarchy. If it is not the case, or if the domain doesn't
130130
* handle this access right, such actions are denied by default with errno
131-
* set to EXDEV. Linking also requires a LANDLOCK_ACCESS_FS_MAKE_* access
132-
* right on the destination directory, and renaming also requires a
133-
* LANDLOCK_ACCESS_FS_REMOVE_* access right on the source's (file or
131+
* set to ``EXDEV``. Linking also requires a ``LANDLOCK_ACCESS_FS_MAKE_*``
132+
* access right on the destination directory, and renaming also requires a
133+
* ``LANDLOCK_ACCESS_FS_REMOVE_*`` access right on the source's (file or
134134
* directory) parent. Otherwise, such actions are denied with errno set to
135-
* EACCES. The EACCES errno prevails over EXDEV to let user space
135+
* ``EACCES``. The ``EACCES`` errno prevails over ``EXDEV`` to let user space
136136
* efficiently deal with an unrecoverable error.
137137
*
138138
* .. warning::

security/landlock/syscalls.c

Lines changed: 20 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -149,10 +149,10 @@ static const struct file_operations ruleset_fops = {
149149
*
150150
* Possible returned errors are:
151151
*
152-
* - EOPNOTSUPP: Landlock is supported by the kernel but disabled at boot time;
153-
* - EINVAL: unknown @flags, or unknown access, or too small @size;
154-
* - E2BIG or EFAULT: @attr or @size inconsistencies;
155-
* - ENOMSG: empty &landlock_ruleset_attr.handled_access_fs.
152+
* - %EOPNOTSUPP: Landlock is supported by the kernel but disabled at boot time;
153+
* - %EINVAL: unknown @flags, or unknown access, or too small @size;
154+
* - %E2BIG or %EFAULT: @attr or @size inconsistencies;
155+
* - %ENOMSG: empty &landlock_ruleset_attr.handled_access_fs.
156156
*/
157157
SYSCALL_DEFINE3(landlock_create_ruleset,
158158
const struct landlock_ruleset_attr __user *const, attr,
@@ -280,7 +280,7 @@ static int get_path_from_fd(const s32 fd, struct path *const path)
280280
* @ruleset_fd: File descriptor tied to the ruleset that should be extended
281281
* with the new rule.
282282
* @rule_type: Identify the structure type pointed to by @rule_attr (only
283-
* LANDLOCK_RULE_PATH_BENEATH for now).
283+
* %LANDLOCK_RULE_PATH_BENEATH for now).
284284
* @rule_attr: Pointer to a rule (only of type &struct
285285
* landlock_path_beneath_attr for now).
286286
* @flags: Must be 0.
@@ -290,17 +290,17 @@ static int get_path_from_fd(const s32 fd, struct path *const path)
290290
*
291291
* Possible returned errors are:
292292
*
293-
* - EOPNOTSUPP: Landlock is supported by the kernel but disabled at boot time;
294-
* - EINVAL: @flags is not 0, or inconsistent access in the rule (i.e.
293+
* - %EOPNOTSUPP: Landlock is supported by the kernel but disabled at boot time;
294+
* - %EINVAL: @flags is not 0, or inconsistent access in the rule (i.e.
295295
* &landlock_path_beneath_attr.allowed_access is not a subset of the
296296
* ruleset handled accesses);
297-
* - ENOMSG: Empty accesses (e.g. &landlock_path_beneath_attr.allowed_access);
298-
* - EBADF: @ruleset_fd is not a file descriptor for the current thread, or a
297+
* - %ENOMSG: Empty accesses (e.g. &landlock_path_beneath_attr.allowed_access);
298+
* - %EBADF: @ruleset_fd is not a file descriptor for the current thread, or a
299299
* member of @rule_attr is not a file descriptor as expected;
300-
* - EBADFD: @ruleset_fd is not a ruleset file descriptor, or a member of
300+
* - %EBADFD: @ruleset_fd is not a ruleset file descriptor, or a member of
301301
* @rule_attr is not the expected file descriptor type;
302-
* - EPERM: @ruleset_fd has no write access to the underlying ruleset;
303-
* - EFAULT: @rule_attr inconsistency.
302+
* - %EPERM: @ruleset_fd has no write access to the underlying ruleset;
303+
* - %EFAULT: @rule_attr inconsistency.
304304
*/
305305
SYSCALL_DEFINE4(landlock_add_rule, const int, ruleset_fd,
306306
const enum landlock_rule_type, rule_type,
@@ -378,20 +378,20 @@ SYSCALL_DEFINE4(landlock_add_rule, const int, ruleset_fd,
378378
* @flags: Must be 0.
379379
*
380380
* This system call enables to enforce a Landlock ruleset on the current
381-
* thread. Enforcing a ruleset requires that the task has CAP_SYS_ADMIN in its
381+
* thread. Enforcing a ruleset requires that the task has %CAP_SYS_ADMIN in its
382382
* namespace or is running with no_new_privs. This avoids scenarios where
383383
* unprivileged tasks can affect the behavior of privileged children.
384384
*
385385
* Possible returned errors are:
386386
*
387-
* - EOPNOTSUPP: Landlock is supported by the kernel but disabled at boot time;
388-
* - EINVAL: @flags is not 0.
389-
* - EBADF: @ruleset_fd is not a file descriptor for the current thread;
390-
* - EBADFD: @ruleset_fd is not a ruleset file descriptor;
391-
* - EPERM: @ruleset_fd has no read access to the underlying ruleset, or the
387+
* - %EOPNOTSUPP: Landlock is supported by the kernel but disabled at boot time;
388+
* - %EINVAL: @flags is not 0.
389+
* - %EBADF: @ruleset_fd is not a file descriptor for the current thread;
390+
* - %EBADFD: @ruleset_fd is not a ruleset file descriptor;
391+
* - %EPERM: @ruleset_fd has no read access to the underlying ruleset, or the
392392
* current thread is not running with no_new_privs, or it doesn't have
393-
* CAP_SYS_ADMIN in its namespace.
394-
* - E2BIG: The maximum number of stacked rulesets is reached for the current
393+
* %CAP_SYS_ADMIN in its namespace.
394+
* - %E2BIG: The maximum number of stacked rulesets is reached for the current
395395
* thread.
396396
*/
397397
SYSCALL_DEFINE2(landlock_restrict_self, const int, ruleset_fd, const __u32,

0 commit comments

Comments
 (0)