[PATCH v2] Documentation: crypto: add info about "fips=" boot option

[PATCH v2] Documentation: crypto: add info about "fips=" boot option

[Randy Dunlap]

Having just seen a report of using "fips=1" on the kernel command line,
I could not find it documented anywhere, so add some help for it.

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: Dexuan Cui <decui@microsoft.com>
Cc: linux-crypto@vger.kernel.org
Cc: Eric Biggers <ebiggers@kernel.org>
Cc: Herbert Xu <herbert@gondor.apana.org.au>
Cc: "David S. Miller" <davem@davemloft.net>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org
---
Updates/corrections welcome.

v2: drop comment that "fips_enabled can cause some tests to be skipped".

 Documentation/admin-guide/kernel-parameters.txt |   14 ++++++++++++++
 1 file changed, 14 insertions(+)

--- linux-next-20210329.orig/Documentation/admin-guide/kernel-parameters.txt
+++ linux-next-20210329/Documentation/admin-guide/kernel-parameters.txt
@@ -1370,6 +1370,20 @@
 			See Documentation/admin-guide/sysctl/net.rst for
 			fb_tunnels_only_for_init_ns
 
+	fips=		Format: { 0 | 1}
+			Use to disable (0) or enable (1) FIPS mode.
+			If enabled, any process that is waiting on the
+			'fips_fail_notif_chain' will be notified of fips
+			failures.
+			This setting can also be modified via sysctl at
+			/proc/sysctl/crypto/fips_enabled, i.e.,
+			crypto.fips_enabled.
+			If fips_enabled = 1 and a test fails, it will cause a
+			kernel panic.
+			If fips_enabled = 1, RSA test requires a key size of
+			2K or larger.
+			It can also effect which ECC curve is used.
+
 	floppy=		[HW]
 			See Documentation/admin-guide/blockdev/floppy.rst.
 

Re: [PATCH v2] Documentation: crypto: add info about "fips=" boot option

[Eric Biggers]

On Mon, Mar 29, 2021 at 10:06:51PM -0700, Randy Dunlap wrote:
> Having just seen a report of using "fips=1" on the kernel command line,
> I could not find it documented anywhere, so add some help for it.
> 
> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
> Cc: Dexuan Cui <decui@microsoft.com>
> Cc: linux-crypto@vger.kernel.org
> Cc: Eric Biggers <ebiggers@kernel.org>
> Cc: Herbert Xu <herbert@gondor.apana.org.au>
> Cc: "David S. Miller" <davem@davemloft.net>
> Cc: Jonathan Corbet <corbet@lwn.net>
> Cc: linux-doc@vger.kernel.org
> ---
> Updates/corrections welcome.
> 
> v2: drop comment that "fips_enabled can cause some tests to be skipped".
> 
>  Documentation/admin-guide/kernel-parameters.txt |   14 ++++++++++++++
>  1 file changed, 14 insertions(+)
> 
> --- linux-next-20210329.orig/Documentation/admin-guide/kernel-parameters.txt
> +++ linux-next-20210329/Documentation/admin-guide/kernel-parameters.txt
> @@ -1370,6 +1370,20 @@
>  			See Documentation/admin-guide/sysctl/net.rst for
>  			fb_tunnels_only_for_init_ns
>  
> +	fips=		Format: { 0 | 1}
> +			Use to disable (0) or enable (1) FIPS mode.
> +			If enabled, any process that is waiting on the
> +			'fips_fail_notif_chain' will be notified of fips
> +			failures.
> +			This setting can also be modified via sysctl at
> +			/proc/sysctl/crypto/fips_enabled, i.e.,
> +			crypto.fips_enabled.
> +			If fips_enabled = 1 and a test fails, it will cause a
> +			kernel panic.
> +			If fips_enabled = 1, RSA test requires a key size of
> +			2K or larger.
> +			It can also effect which ECC curve is used.

This doesn't really explain why anyone would want to give this option.
What high-level thing is this option meant to be accomplishing?
That's what the documentation should explain.

- Eric

Re: [PATCH v2] Documentation: crypto: add info about "fips=" boot option

[Randy Dunlap]

On 3/29/21 10:29 PM, Eric Biggers wrote:
> On Mon, Mar 29, 2021 at 10:06:51PM -0700, Randy Dunlap wrote:
>> Having just seen a report of using "fips=1" on the kernel command line,
>> I could not find it documented anywhere, so add some help for it.
>>
>> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
>> Cc: Dexuan Cui <decui@microsoft.com>
>> Cc: linux-crypto@vger.kernel.org
>> Cc: Eric Biggers <ebiggers@kernel.org>
>> Cc: Herbert Xu <herbert@gondor.apana.org.au>
>> Cc: "David S. Miller" <davem@davemloft.net>
>> Cc: Jonathan Corbet <corbet@lwn.net>
>> Cc: linux-doc@vger.kernel.org
>> ---
>> Updates/corrections welcome.
>>
>> v2: drop comment that "fips_enabled can cause some tests to be skipped".
>>
>>  Documentation/admin-guide/kernel-parameters.txt |   14 ++++++++++++++
>>  1 file changed, 14 insertions(+)
>>
>> --- linux-next-20210329.orig/Documentation/admin-guide/kernel-parameters.txt
>> +++ linux-next-20210329/Documentation/admin-guide/kernel-parameters.txt
>> @@ -1370,6 +1370,20 @@
>>  			See Documentation/admin-guide/sysctl/net.rst for
>>  			fb_tunnels_only_for_init_ns
>>  
>> +	fips=		Format: { 0 | 1}
>> +			Use to disable (0) or enable (1) FIPS mode.
>> +			If enabled, any process that is waiting on the
>> +			'fips_fail_notif_chain' will be notified of fips
>> +			failures.
>> +			This setting can also be modified via sysctl at
>> +			/proc/sysctl/crypto/fips_enabled, i.e.,
>> +			crypto.fips_enabled.
>> +			If fips_enabled = 1 and a test fails, it will cause a
>> +			kernel panic.
>> +			If fips_enabled = 1, RSA test requires a key size of
>> +			2K or larger.
>> +			It can also effect which ECC curve is used.
> 
> This doesn't really explain why anyone would want to give this option.
> What high-level thing is this option meant to be accomplishing?
> That's what the documentation should explain.

Yes, clearly, even to me.

But I could not find anything in the kernel source tree that would help me
explain that.  So to repeat:

>> Updates/corrections welcome.

thanks.
-- 
~Randy

Re: [PATCH v2] Documentation: crypto: add info about "fips=" boot option

[Eric Biggers]

On Tue, Mar 30, 2021 at 09:38:55AM -0700, Randy Dunlap wrote:
> On 3/29/21 10:29 PM, Eric Biggers wrote:
> > On Mon, Mar 29, 2021 at 10:06:51PM -0700, Randy Dunlap wrote:
> >> Having just seen a report of using "fips=1" on the kernel command line,
> >> I could not find it documented anywhere, so add some help for it.
> >>
> >> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
> >> Cc: Dexuan Cui <decui@microsoft.com>
> >> Cc: linux-crypto@vger.kernel.org
> >> Cc: Eric Biggers <ebiggers@kernel.org>
> >> Cc: Herbert Xu <herbert@gondor.apana.org.au>
> >> Cc: "David S. Miller" <davem@davemloft.net>
> >> Cc: Jonathan Corbet <corbet@lwn.net>
> >> Cc: linux-doc@vger.kernel.org
> >> ---
> >> Updates/corrections welcome.
> >>
> >> v2: drop comment that "fips_enabled can cause some tests to be skipped".
> >>
> >>  Documentation/admin-guide/kernel-parameters.txt |   14 ++++++++++++++
> >>  1 file changed, 14 insertions(+)
> >>
> >> --- linux-next-20210329.orig/Documentation/admin-guide/kernel-parameters.txt
> >> +++ linux-next-20210329/Documentation/admin-guide/kernel-parameters.txt
> >> @@ -1370,6 +1370,20 @@
> >>  			See Documentation/admin-guide/sysctl/net.rst for
> >>  			fb_tunnels_only_for_init_ns
> >>  
> >> +	fips=		Format: { 0 | 1}
> >> +			Use to disable (0) or enable (1) FIPS mode.
> >> +			If enabled, any process that is waiting on the
> >> +			'fips_fail_notif_chain' will be notified of fips
> >> +			failures.
> >> +			This setting can also be modified via sysctl at
> >> +			/proc/sysctl/crypto/fips_enabled, i.e.,
> >> +			crypto.fips_enabled.
> >> +			If fips_enabled = 1 and a test fails, it will cause a
> >> +			kernel panic.
> >> +			If fips_enabled = 1, RSA test requires a key size of
> >> +			2K or larger.
> >> +			It can also effect which ECC curve is used.
> > 
> > This doesn't really explain why anyone would want to give this option.
> > What high-level thing is this option meant to be accomplishing?
> > That's what the documentation should explain.
> 
> Yes, clearly, even to me.
> 
> But I could not find anything in the kernel source tree that would help me
> explain that.  So to repeat:
> 
> >> Updates/corrections welcome.
> 
> thanks.
> -- 

I'm by no means an expert on this, but the main thing I have in mind is that
(IIUC) the "fips" option is only useful if your whole kernel binary is certified
as a "FIPS cryptographic module", *and* you actually need the FIPS compliance.
And the upstream kernel doesn't have a FIPS certification out of the box; that's
a task for specific Linux distributors like Red Hat, SUSE, Ubuntu, who get
specific kernel binaries certified.

So, compiling a kernel and using the "fips" option is useless by itself, as your
kernel image won't actually have a FIPS certification in that case anyway.

So, I would expect an explanation like that about under what circumstances the
"fips" option is actually useful and intended for.

The people who actually use this option should be able to explain it properly
though; the above is just my understanding...

- Eric

Re: [PATCH v2] Documentation: crypto: add info about "fips=" boot option

[Stephan Mueller]

Am Dienstag, dem 30.03.2021 um 15:44 -0700 schrieb Eric Biggers:
> On Tue, Mar 30, 2021 at 09:38:55AM -0700, Randy Dunlap wrote:
> > On 3/29/21 10:29 PM, Eric Biggers wrote:
> > > On Mon, Mar 29, 2021 at 10:06:51PM -0700, Randy Dunlap wrote:
> > > > Having just seen a report of using "fips=1" on the kernel command
> > > > line,
> > > > I could not find it documented anywhere, so add some help for it.
> > > > 
> > > > Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
> > > > Cc: Dexuan Cui <decui@microsoft.com>
> > > > Cc: linux-crypto@vger.kernel.org
> > > > Cc: Eric Biggers <ebiggers@kernel.org>
> > > > Cc: Herbert Xu <herbert@gondor.apana.org.au>
> > > > Cc: "David S. Miller" <davem@davemloft.net>
> > > > Cc: Jonathan Corbet <corbet@lwn.net>
> > > > Cc: linux-doc@vger.kernel.org
> > > > ---
> > > > Updates/corrections welcome.
> > > > 
> > > > v2: drop comment that "fips_enabled can cause some tests to be
> > > > skipped".
> > > > 
> > > >  Documentation/admin-guide/kernel-parameters.txt |   14 ++++++++++++++
> > > >  1 file changed, 14 insertions(+)
> > > > 
> > > > --- linux-next-20210329.orig/Documentation/admin-guide/kernel-
> > > > parameters.txt
> > > > +++ linux-next-20210329/Documentation/admin-guide/kernel-
> > > > parameters.txt
> > > > @@ -1370,6 +1370,20 @@
> > > >                         See Documentation/admin-guide/sysctl/net.rst
> > > > for
> > > >                         fb_tunnels_only_for_init_ns
> > > >  
> > > > +       fips=           Format: { 0 | 1}
> > > > +                       Use to disable (0) or enable (1) FIPS mode.
> > > > +                       If enabled, any process that is waiting on the
> > > > +                       'fips_fail_notif_chain' will be notified of
> > > > fips
> > > > +                       failures.
> > > > +                       This setting can also be modified via sysctl
> > > > at
> > > > +                       /proc/sysctl/crypto/fips_enabled, i.e.,
> > > > +                       crypto.fips_enabled.
> > > > +                       If fips_enabled = 1 and a test fails, it will
> > > > cause a
> > > > +                       kernel panic.
> > > > +                       If fips_enabled = 1, RSA test requires a key
> > > > size of
> > > > +                       2K or larger.
> > > > +                       It can also effect which ECC curve is used.
> > > 
> > > This doesn't really explain why anyone would want to give this option.
> > > What high-level thing is this option meant to be accomplishing?
> > > That's what the documentation should explain.
> > 
> > Yes, clearly, even to me.
> > 
> > But I could not find anything in the kernel source tree that would help me
> > explain that.  So to repeat:
> > 
> > > > Updates/corrections welcome.
> > 
> > thanks.
> > -- 
> 
> I'm by no means an expert on this, but the main thing I have in mind is that
> (IIUC) the "fips" option is only useful if your whole kernel binary is
> certified
> as a "FIPS cryptographic module", *and* you actually need the FIPS
> compliance.
> And the upstream kernel doesn't have a FIPS certification out of the box;
> that's
> a task for specific Linux distributors like Red Hat, SUSE, Ubuntu, who get
> specific kernel binaries certified.
> 
> So, compiling a kernel and using the "fips" option is useless by itself, as
> your
> kernel image won't actually have a FIPS certification in that case anyway.
> 
> So, I would expect an explanation like that about under what circumstances
> the
> "fips" option is actually useful and intended for.
> 
> The people who actually use this option should be able to explain it
> properly
> though; the above is just my understanding...


The fips=1 flag serves the following purposes:

In-kernel:

- it restricts crypto algos to those which are marked as .fips_allowed in the
testmgr.c

- it causes the panic() if the signature verification of a KO providing a
crypto algo implementation fails

- it causes a specific behavior in driver/char/random.c (which was correct
till 4.8 but then got modified - patches to correct it in current kernels were
ignored)

- elevates the priority of crypto/drbg.c to ensure that when using stdrng the
DRBG is invoked

- ensures that the Jitter RNG is allocated as one seed source for
crypto/drbg.c

In user space:

- Various crypto libraries (OpenSSL, GnuTLS, libgcrypt, NSS) use the flag as
the trigger point to enable their FIPS-compliance with the goal to have one
central "knob" that enables the FIPS mode system-wide

- The boot system (e.g. dracut) starts its FIPS work (see dracut-fips).

Ciao
Stephan
> 
> - Eric