[PATCH v2] landlock: Explain how to support Landlock

[PATCH v2] landlock: Explain how to support Landlock

[Mickaël Salaün]

Let's help users by documenting how to enable and check for Landlock in
the kernel and the running system.  The userspace-api section may not be
the best place for this but it still makes sense to put all the user
documentation at the same place.

Cc: Paul Moore <paul@paul-moore.com>
Signed-off-by: Mickaël Salaün <mic@digikod.net>
Link: https://lore.kernel.org/r/20220513112743.156414-1-mic@digikod.net
---

Changes since v1:
* Move the checking subsection at the beginning (suggested by Paul
  Moore) and merge the two configuration subsections.
* Use both dmesg and journalctl to handle cases where journald is not
  installed or when the kernel log buffer is full.
* Add reference to the syscall check (ABI section).
* Improve explanations.
* Update copyright date.
---
 Documentation/userspace-api/landlock.rst | 29 +++++++++++++++++++++++-
 1 file changed, 28 insertions(+), 1 deletion(-)

diff --git a/Documentation/userspace-api/landlock.rst b/Documentation/userspace-api/landlock.rst
index 7b4fe6218132..b8ea59493964 100644
--- a/Documentation/userspace-api/landlock.rst
+++ b/Documentation/userspace-api/landlock.rst
@@ -1,7 +1,7 @@
 .. SPDX-License-Identifier: GPL-2.0
 .. Copyright © 2017-2020 Mickaël Salaün <mic@digikod.net>
 .. Copyright © 2019-2020 ANSSI
-.. Copyright © 2021 Microsoft Corporation
+.. Copyright © 2021-2022 Microsoft Corporation
 
 =====================================
 Landlock: unprivileged access control
@@ -18,6 +18,13 @@ is expected to help mitigate the security impact of bugs or
 unexpected/malicious behaviors in user space applications.  Landlock empowers
 any process, including unprivileged ones, to securely restrict themselves.
 
+We can quickly make sure that Landlock is enabled in the running system by
+looking for "landlock: Up and running" in kernel logs (as root): ``dmesg | grep
+landlock || journalctl -kg landlock`` .  Developers can also easily check for
+Landlock support with a :ref:`related system call <landlock_abi_versions>`.  If
+Landlock is not currently supported, we need to :ref:`configure the kernel
+appropriately <kernel_support>`.
+
 Landlock rules
 ==============
 
@@ -264,6 +271,8 @@ users, and because they may use different kernel versions, it is strongly
 encouraged to follow a best-effort security approach by checking the Landlock
 ABI version at runtime and only enforcing the supported features.
 
+.. _landlock_abi_versions:
+
 Landlock ABI versions
 ---------------------
 
@@ -388,6 +397,24 @@ Starting with the Landlock ABI version 2, it is now possible to securely
 control renaming and linking thanks to the new `LANDLOCK_ACCESS_FS_REFER`
 access right.
 
+.. _kernel_support:
+
+Kernel support
+==============
+
+Landlock was first introduced in Linux 5.13 but it must be configured at build
+time with `CONFIG_SECURITY_LANDLOCK=y`.  Landlock must also be enabled at boot
+time as the other security modules.  The list of security modules enabled by
+default is set with `CONFIG_LSM`.  The kernel configuration should then
+contains `CONFIG_LSM=landlock,[...]` with `[...]`  as the list of other
+potentially useful security modules for the running system (see the
+`CONFIG_LSM` help).
+
+If the running kernel doesn't have `landlock` in `CONFIG_LSM`, then we can
+still enable it by adding ``lsm=landlock,[...]`` to
+Documentation/admin-guide/kernel-parameters.rst thanks to the bootloader
+configuration.
+
 Questions and answers
 =====================
 

base-commit: 67761d8181f0fb9dbd264caa5b6408dbc0d8e86a
-- 
2.36.0

Re: [PATCH v2] landlock: Explain how to support Landlock

[Paul Moore]

On Fri, May 13, 2022 at 7:27 AM Mickaël Salaün <mic@digikod.net> wrote:
>
> Let's help users by documenting how to enable and check for Landlock in
> the kernel and the running system.  The userspace-api section may not be
> the best place for this but it still makes sense to put all the user
> documentation at the same place.
>
> Cc: Paul Moore <paul@paul-moore.com>
> Signed-off-by: Mickaël Salaün <mic@digikod.net>
> Link: https://lore.kernel.org/r/20220513112743.156414-1-mic@digikod.net
> ---
>
> Changes since v1:
> * Move the checking subsection at the beginning (suggested by Paul
>   Moore) and merge the two configuration subsections.
> * Use both dmesg and journalctl to handle cases where journald is not
>   installed or when the kernel log buffer is full.
> * Add reference to the syscall check (ABI section).
> * Improve explanations.
> * Update copyright date.
> ---
>  Documentation/userspace-api/landlock.rst | 29 +++++++++++++++++++++++-
>  1 file changed, 28 insertions(+), 1 deletion(-)

Looks good to me.

Reviewed-by: Paul Moore <paul@paul-moore.com>

-- 
paul-moore.com

Re: [PATCH v2] landlock: Explain how to support Landlock

[Mickaël Salaün]

On 13/05/2022 14:57, Paul Moore wrote:
> On Fri, May 13, 2022 at 7:27 AM Mickaël Salaün <mic@digikod.net> wrote:
>>
>> Let's help users by documenting how to enable and check for Landlock in
>> the kernel and the running system.  The userspace-api section may not be
>> the best place for this but it still makes sense to put all the user
>> documentation at the same place.
>>
>> Cc: Paul Moore <paul@paul-moore.com>
>> Signed-off-by: Mickaël Salaün <mic@digikod.net>
>> Link: https://lore.kernel.org/r/20220513112743.156414-1-mic@digikod.net
>> ---
>>
>> Changes since v1:
>> * Move the checking subsection at the beginning (suggested by Paul
>>    Moore) and merge the two configuration subsections.
>> * Use both dmesg and journalctl to handle cases where journald is not
>>    installed or when the kernel log buffer is full.
>> * Add reference to the syscall check (ABI section).
>> * Improve explanations.
>> * Update copyright date.
>> ---
>>   Documentation/userspace-api/landlock.rst | 29 +++++++++++++++++++++++-
>>   1 file changed, 28 insertions(+), 1 deletion(-)
> 
> Looks good to me.
> 
> Reviewed-by: Paul Moore <paul@paul-moore.com>
> 

Thanks Paul!