[PATCH] Docs/security: update cmdline keyword usage

[PATCH] Docs/security: update cmdline keyword usage

[Randy Dunlap]

Use "lsm=name,..." instead "security=name,..." since the latter is
deprecated.

Fixes: 89a9684ea158 ("LSM: Ignore "security=" when "lsm=" is specified")
Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: Kees Cook <kees@kernel.org>
Cc: Paul Moore <paul@paul-moore.com>
Cc: James Morris <jmorris@namei.org>
Cc: "Serge E. Hallyn" <sergeh@kernel.org>
Cc: linux-security-module@vger.kernel.org
Cc: Kentaro Takeda <takedakn@nttdata.co.jp>
Cc: Tetsuo Handa <penguin-kernel@I-love.SAKURA.ne.jp>
Cc: John Johansen <john.johansen@canonical.com>
Cc: John Johansen <john@apparmor.net>
Cc: Jonathan Corbet <corbet@lwn.net>
---
 Documentation/admin-guide/LSM/apparmor.rst |    4 ++--
 Documentation/admin-guide/LSM/index.rst    |    2 +-
 Documentation/admin-guide/LSM/tomoyo.rst   |    2 +-
 3 files changed, 4 insertions(+), 4 deletions(-)

--- linux-next-20250113.orig/Documentation/admin-guide/LSM/apparmor.rst
+++ linux-next-20250113/Documentation/admin-guide/LSM/apparmor.rst
@@ -27,10 +27,10 @@ in the list.
 Build the kernel
 
 If AppArmor is not the default security module it can be enabled by passing
-``security=apparmor`` on the kernel's command line.
+``lsm=apparmor`` on the kernel's command line.
 
 If AppArmor is the default security module it can be disabled by passing
-``apparmor=0, security=XXXX`` (where ``XXXX`` is valid security module), on the
+``apparmor=0, lsm=XXXX`` (where ``XXXX`` is valid security module), on the
 kernel's command line.
 
 For AppArmor to enforce any restrictions beyond standard Linux DAC permissions
--- linux-next-20250113.orig/Documentation/admin-guide/LSM/index.rst
+++ linux-next-20250113/Documentation/admin-guide/LSM/index.rst
@@ -7,7 +7,7 @@ various security checks to be hooked by
 "module" is a bit of a misnomer since these extensions are not actually
 loadable kernel modules. Instead, they are selectable at build-time via
 CONFIG_DEFAULT_SECURITY and can be overridden at boot-time via the
-``"security=..."`` kernel command line argument, in the case where multiple
+``"lsm=..."`` kernel command line argument, in the case where multiple
 LSMs were built into a given kernel.
 
 The primary users of the LSM interface are Mandatory Access Control
--- linux-next-20250113.orig/Documentation/admin-guide/LSM/tomoyo.rst
+++ linux-next-20250113/Documentation/admin-guide/LSM/tomoyo.rst
@@ -18,7 +18,7 @@ to know what TOMOYO is.
 How to enable TOMOYO?
 =====================
 
-Build the kernel with ``CONFIG_SECURITY_TOMOYO=y`` and pass ``security=tomoyo`` on
+Build the kernel with ``CONFIG_SECURITY_TOMOYO=y`` and pass ``lsm=tomoyo`` on
 kernel's command line.
 
 Please see https://tomoyo.sourceforge.net/2.6/ for details.

Re: [PATCH] Docs/security: update cmdline keyword usage

[Tetsuo Handa]

On 2025/01/15 7:51, Randy Dunlap wrote:
> Use "lsm=name,..." instead "security=name,..." since the latter is
> deprecated.

Sorry, but security= is for specifying only one of exclusive LSM modules
whereas lsm= is for specifying both one of exclusive LSM modules and
all of non-exclusive LSM modules. That is, you can't deprecate
security= using s/security=/lsm=/g .

Re: [PATCH] Docs/security: update cmdline keyword usage

[Randy Dunlap]

On 1/14/25 2:59 PM, Tetsuo Handa wrote:
> On 2025/01/15 7:51, Randy Dunlap wrote:
>> Use "lsm=name,..." instead "security=name,..." since the latter is
>> deprecated.
> 
> Sorry, but security= is for specifying only one of exclusive LSM modules
> whereas lsm= is for specifying both one of exclusive LSM modules and
> all of non-exclusive LSM modules. That is, you can't deprecate
> security= using s/security=/lsm=/g .
> 

OK, thanks for the feedback.

I am still confused by this part though, in Documentation/doc-guide/kernel-parameters.txt:

	security=	[SECURITY] Choose a legacy "major" security module to
			enable at boot. This has been deprecated by the
			"lsm=" parameter.

-- 
~Randy

Re: [PATCH] Docs/security: update cmdline keyword usage

[Paul Moore]

On Tue, Jan 14, 2025 at 6:17 PM Randy Dunlap <rdunlap@infradead.org> wrote:
> On 1/14/25 2:59 PM, Tetsuo Handa wrote:
> > On 2025/01/15 7:51, Randy Dunlap wrote:
> >> Use "lsm=name,..." instead "security=name,..." since the latter is
> >> deprecated.
> >
> > Sorry, but security= is for specifying only one of exclusive LSM modules
> > whereas lsm= is for specifying both one of exclusive LSM modules and
> > all of non-exclusive LSM modules. That is, you can't deprecate
> > security= using s/security=/lsm=/g .
> >
>
> OK, thanks for the feedback.
>
> I am still confused by this part though, in Documentation/doc-guide/kernel-parameters.txt:
>
>         security=       [SECURITY] Choose a legacy "major" security module to
>                         enable at boot. This has been deprecated by the
>                         "lsm=" parameter.

That wording is correct, look at the ordered_lsm_init() and
ordered_lsm_parse() functions in security/security.c.  The legacy
"security=" parameter is from a point in time where we didn't support
running multiple major LSMs and for various reasons when we did add
support for multiple LSMs we moved to the "lsm=" parameter, with
continuing support for the "security=" parameter for backwards
compatibility with existing installs.  If present, the "lsm="
parameter overrides "security=".

Looking at Randy's patch and Tetsuo's comment, I think there was a
minor misunderstanding which has led to some confusion.  Tetsuo made
the comment that you can't simply do a search and replace on the
kernel command line substituting "lsm=" for "security=" as the
"security=" parameter will ensure that only one major LSM is activated
while "lsm=" would permit multiple major LSMs if they were configured
at kernel build time.

Looking at Randy's original patch, I've got a couple of comments ...

On Tue, Jan 14, 2025 at 5:52 PM Randy Dunlap <rdunlap@infradead.org> wrote:
>
> Use "lsm=name,..." instead "security=name,..." since the latter is
> deprecated.

The "security=" parameter only supports a single LSM name, not a comma
delimited list like the "lsm=" parameter.

> Fixes: 89a9684ea158 ("LSM: Ignore "security=" when "lsm=" is specified")
> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
> Cc: Kees Cook <kees@kernel.org>
> Cc: Paul Moore <paul@paul-moore.com>
> Cc: James Morris <jmorris@namei.org>
> Cc: "Serge E. Hallyn" <sergeh@kernel.org>
> Cc: linux-security-module@vger.kernel.org
> Cc: Kentaro Takeda <takedakn@nttdata.co.jp>
> Cc: Tetsuo Handa <penguin-kernel@I-love.SAKURA.ne.jp>
> Cc: John Johansen <john.johansen@canonical.com>
> Cc: John Johansen <john@apparmor.net>
> Cc: Jonathan Corbet <corbet@lwn.net>
> ---
>  Documentation/admin-guide/LSM/apparmor.rst |    4 ++--
>  Documentation/admin-guide/LSM/index.rst    |    2 +-
>  Documentation/admin-guide/LSM/tomoyo.rst   |    2 +-
>  3 files changed, 4 insertions(+), 4 deletions(-)
>
> --- linux-next-20250113.orig/Documentation/admin-guide/LSM/apparmor.rst
> +++ linux-next-20250113/Documentation/admin-guide/LSM/apparmor.rst
> @@ -27,10 +27,10 @@ in the list.
>  Build the kernel
>
>  If AppArmor is not the default security module it can be enabled by passing
> -``security=apparmor`` on the kernel's command line.
> +``lsm=apparmor`` on the kernel's command line.
>
>  If AppArmor is the default security module it can be disabled by passing
> -``apparmor=0, security=XXXX`` (where ``XXXX`` is valid security module), on the
> +``apparmor=0, lsm=XXXX`` (where ``XXXX`` is valid security module), on the
>  kernel's command line.

The problem with the /security=/lsm=/ conversion that you've done
here, and elsewhere in the patch, is that when you use the "security="
parameter the non-major LSMs that are built into the kernel (see the
CONFIG_LSM Kconfig knob) are still enabled whereas if you use the
"lsm=" parameter you must explicitly list *all* of the LSMs you want
to enable.  As an example, "security=apparmor" might enable both
AppArmor and Yama, where "lsm=apparmor" only enabled AppArmor, leaving
Yama disabled.

-- 
paul-moore.com

Re: [PATCH] Docs/security: update cmdline keyword usage

[Randy Dunlap]

Hi Paul,

On 1/14/25 7:08 PM, Paul Moore wrote:
> On Tue, Jan 14, 2025 at 6:17 PM Randy Dunlap <rdunlap@infradead.org> wrote:
>> On 1/14/25 2:59 PM, Tetsuo Handa wrote:
>>> On 2025/01/15 7:51, Randy Dunlap wrote:
>>>> Use "lsm=name,..." instead "security=name,..." since the latter is
>>>> deprecated.
>>>
>>> Sorry, but security= is for specifying only one of exclusive LSM modules
>>> whereas lsm= is for specifying both one of exclusive LSM modules and
>>> all of non-exclusive LSM modules. That is, you can't deprecate
>>> security= using s/security=/lsm=/g .
>>>
>>
>> OK, thanks for the feedback.
>>
>> I am still confused by this part though, in Documentation/doc-guide/kernel-parameters.txt:
>>
>>         security=       [SECURITY] Choose a legacy "major" security module to
>>                         enable at boot. This has been deprecated by the
>>                         "lsm=" parameter.
> 
> That wording is correct, look at the ordered_lsm_init() and
> ordered_lsm_parse() functions in security/security.c.  The legacy
> "security=" parameter is from a point in time where we didn't support
> running multiple major LSMs and for various reasons when we did add
> support for multiple LSMs we moved to the "lsm=" parameter, with
> continuing support for the "security=" parameter for backwards
> compatibility with existing installs.  If present, the "lsm="
> parameter overrides "security=".
> 
> Looking at Randy's patch and Tetsuo's comment, I think there was a
> minor misunderstanding which has led to some confusion.  Tetsuo made
> the comment that you can't simply do a search and replace on the
> kernel command line substituting "lsm=" for "security=" as the
> "security=" parameter will ensure that only one major LSM is activated
> while "lsm=" would permit multiple major LSMs if they were configured
> at kernel build time.

Yes, there are some subtle parts there that I overlooked.

> Looking at Randy's original patch, I've got a couple of comments ...
> 
> On Tue, Jan 14, 2025 at 5:52 PM Randy Dunlap <rdunlap@infradead.org> wrote:
>>
>> Use "lsm=name,..." instead "security=name,..." since the latter is
>> deprecated.
> 
> The "security=" parameter only supports a single LSM name, not a comma
> delimited list like the "lsm=" parameter.
> 
>> Fixes: 89a9684ea158 ("LSM: Ignore "security=" when "lsm=" is specified")
>> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
>> Cc: Kees Cook <kees@kernel.org>
>> Cc: Paul Moore <paul@paul-moore.com>
>> Cc: James Morris <jmorris@namei.org>
>> Cc: "Serge E. Hallyn" <sergeh@kernel.org>
>> Cc: linux-security-module@vger.kernel.org
>> Cc: Kentaro Takeda <takedakn@nttdata.co.jp>
>> Cc: Tetsuo Handa <penguin-kernel@I-love.SAKURA.ne.jp>
>> Cc: John Johansen <john.johansen@canonical.com>
>> Cc: John Johansen <john@apparmor.net>
>> Cc: Jonathan Corbet <corbet@lwn.net>
>> ---
>>  Documentation/admin-guide/LSM/apparmor.rst |    4 ++--
>>  Documentation/admin-guide/LSM/index.rst    |    2 +-
>>  Documentation/admin-guide/LSM/tomoyo.rst   |    2 +-
>>  3 files changed, 4 insertions(+), 4 deletions(-)
>>
>> --- linux-next-20250113.orig/Documentation/admin-guide/LSM/apparmor.rst
>> +++ linux-next-20250113/Documentation/admin-guide/LSM/apparmor.rst
>> @@ -27,10 +27,10 @@ in the list.
>>  Build the kernel
>>
>>  If AppArmor is not the default security module it can be enabled by passing
>> -``security=apparmor`` on the kernel's command line.
>> +``lsm=apparmor`` on the kernel's command line.
>>
>>  If AppArmor is the default security module it can be disabled by passing
>> -``apparmor=0, security=XXXX`` (where ``XXXX`` is valid security module), on the
>> +``apparmor=0, lsm=XXXX`` (where ``XXXX`` is valid security module), on the
>>  kernel's command line.
> 
> The problem with the /security=/lsm=/ conversion that you've done
> here, and elsewhere in the patch, is that when you use the "security="
> parameter the non-major LSMs that are built into the kernel (see the
> CONFIG_LSM Kconfig knob) are still enabled whereas if you use the
> "lsm=" parameter you must explicitly list *all* of the LSMs you want
> to enable.  As an example, "security=apparmor" might enable both
> AppArmor and Yama, where "lsm=apparmor" only enabled AppArmor, leaving
> Yama disabled.
> 

I see. Thanks for the explanations.

-- 
~Randy