[v9,10/10] docs: Include modules.builtin.alias

  Update the documentation to include the presense and use case of
modules.builtin.alias.

Signed-off-by: Allen Webb <allenwebb@google.com>
---
 Documentation/kbuild/kbuild.rst | 6 ++++++
 1 file changed, 6 insertions(+)
  

Please disregard this patch. I updated the commit message and this was
hanging around in my outgoing directory afterward.

On Mon, Dec 19, 2022 at 2:46 PM Allen Webb <allenwebb@google.com> wrote:
>
> Update the documentation to include the presense and use case of
> modules.builtin.alias.
>
> Signed-off-by: Allen Webb <allenwebb@google.com>
> ---
>  Documentation/kbuild/kbuild.rst | 6 ++++++
>  1 file changed, 6 insertions(+)
>
> diff --git a/Documentation/kbuild/kbuild.rst b/Documentation/kbuild/kbuild.rst
> index 08f575e6236c..1c7c02040a54 100644
> --- a/Documentation/kbuild/kbuild.rst
> +++ b/Documentation/kbuild/kbuild.rst
> @@ -17,6 +17,12 @@ modules.builtin
>  This file lists all modules that are built into the kernel. This is used
>  by modprobe to not fail when trying to load something builtin.
>
> +modules.builtin.alias
> +---------------------
> +This file lists all match-id based aliases for modules built into the kernel.
> +These are intended to enable userspace to make authorization decisions based
> +on which modules are likely to be bound to a device after it is authorized.
> +
>  modules.builtin.modinfo
>  -----------------------
>  This file contains modinfo from all modules that are built into the kernel.
> --
> 2.37.3
>
  

On Mon, Dec 19, 2022 at 02:46:18PM -0600, Allen Webb wrote:
> Update the documentation to include the presense and use case of
> modules.builtin.alias.
> 
> Signed-off-by: Allen Webb <allenwebb@google.com>
> ---
>  Documentation/kbuild/kbuild.rst | 6 ++++++
>  1 file changed, 6 insertions(+)
> 
> diff --git a/Documentation/kbuild/kbuild.rst b/Documentation/kbuild/kbuild.rst
> index 08f575e6236c..1c7c02040a54 100644
> --- a/Documentation/kbuild/kbuild.rst
> +++ b/Documentation/kbuild/kbuild.rst
> @@ -17,6 +17,12 @@ modules.builtin
>  This file lists all modules that are built into the kernel. This is used
>  by modprobe to not fail when trying to load something builtin.
>  
> +modules.builtin.alias
> +---------------------
> +This file lists all match-id based aliases for modules built into the kernel.
> +These are intended to enable userspace to make authorization decisions based
> +on which modules are likely to be bound to a device after it is authorized.

What is an example? This sounds obscure.

  Luis
  

On Mon, Dec 19, 2022 at 3:23 PM Luis Chamberlain <mcgrof@kernel.org> wrote:
>
> On Mon, Dec 19, 2022 at 02:46:18PM -0600, Allen Webb wrote:
> > Update the documentation to include the presense and use case of
> > modules.builtin.alias.
> >
> > Signed-off-by: Allen Webb <allenwebb@google.com>
> > ---
> >  Documentation/kbuild/kbuild.rst | 6 ++++++
> >  1 file changed, 6 insertions(+)
> >
> > diff --git a/Documentation/kbuild/kbuild.rst b/Documentation/kbuild/kbuild.rst
> > index 08f575e6236c..1c7c02040a54 100644
> > --- a/Documentation/kbuild/kbuild.rst
> > +++ b/Documentation/kbuild/kbuild.rst
> > @@ -17,6 +17,12 @@ modules.builtin
> >  This file lists all modules that are built into the kernel. This is used
> >  by modprobe to not fail when trying to load something builtin.
> >
> > +modules.builtin.alias
> > +---------------------
> > +This file lists all match-id based aliases for modules built into the kernel.
> > +These are intended to enable userspace to make authorization decisions based
> > +on which modules are likely to be bound to a device after it is authorized.
>
> What is an example? This sounds obscure.

Many of the devices that match the usb_storage driver only specify the
vendor id, product id, and device id (VID:PID:D) and do not match
against device class, interface class, etc. Here are some examples
from modules.alias: A grep for wildcards in these fields yields 6136
matches:
grep 'dc\*dsc\*dp\*ic\*isc\*ip\*in\*'
/lib/modules/5.19.11-1rodete1-amd64/modules.alias | wc -l
6136

To write USBGuard policy that only authorizes devices that bind to a
particular module the policy needs to be aware of all these VID:PID:D
which can change between kernel versions.

This is done at runtime rather than excluding modules from the build
because some devices are not needed at or before login or when a
device is locked. By not authorizing new devices that would bind to a
set of modules, these modules become unreachable to an attacker who
seeks to exploit kernel bugs in those modules.

I could add this detail to the documentation file, but I was trying to
keep the description to about the same length as the others around it.

>
>   Luis
  

On Mon, Dec 19, 2022 at 03:40:42PM -0600, Allen Webb wrote:
> On Mon, Dec 19, 2022 at 3:23 PM Luis Chamberlain <mcgrof@kernel.org> wrote:
> >
> > On Mon, Dec 19, 2022 at 02:46:18PM -0600, Allen Webb wrote:
> > > Update the documentation to include the presense and use case of
> > > modules.builtin.alias.
> > >
> > > Signed-off-by: Allen Webb <allenwebb@google.com>
> > > ---
> > >  Documentation/kbuild/kbuild.rst | 6 ++++++
> > >  1 file changed, 6 insertions(+)
> > >
> > > diff --git a/Documentation/kbuild/kbuild.rst b/Documentation/kbuild/kbuild.rst
> > > index 08f575e6236c..1c7c02040a54 100644
> > > --- a/Documentation/kbuild/kbuild.rst
> > > +++ b/Documentation/kbuild/kbuild.rst
> > > @@ -17,6 +17,12 @@ modules.builtin
> > >  This file lists all modules that are built into the kernel. This is used
> > >  by modprobe to not fail when trying to load something builtin.
> > >
> > > +modules.builtin.alias
> > > +---------------------
> > > +This file lists all match-id based aliases for modules built into the kernel.
> > > +These are intended to enable userspace to make authorization decisions based
> > > +on which modules are likely to be bound to a device after it is authorized.
> >
> > What is an example? This sounds obscure.
> 
> Many of the devices that match the usb_storage driver only specify the
> vendor id, product id, and device id (VID:PID:D) and do not match
> against device class, interface class, etc. Here are some examples
> from modules.alias: A grep for wildcards in these fields yields 6136
> matches:
> grep 'dc\*dsc\*dp\*ic\*isc\*ip\*in\*'
> /lib/modules/5.19.11-1rodete1-amd64/modules.alias | wc -l
> 6136
> 
> To write USBGuard policy that only authorizes devices that bind to a
> particular module the policy needs to be aware of all these VID:PID:D
> which can change between kernel versions.
> 
> This is done at runtime rather than excluding modules from the build
> because some devices are not needed at or before login or when a
> device is locked. By not authorizing new devices that would bind to a
> set of modules, these modules become unreachable to an attacker who
> seeks to exploit kernel bugs in those modules.
> 
> I could add this detail to the documentation file, but I was trying to
> keep the description to about the same length as the others around it.

How about the second sentence you wrote say something like:

An example usage of the built-in aliases is to enable software such as
USBGuard to enable / disable specific devices outside of just the
vendor, product and device ID. This allows more flexible security policies
in userspace.

  Luis
  

On Mon, Dec 19, 2022 at 4:07 PM Luis Chamberlain <mcgrof@kernel.org> wrote:
>
> On Mon, Dec 19, 2022 at 03:40:42PM -0600, Allen Webb wrote:
> > On Mon, Dec 19, 2022 at 3:23 PM Luis Chamberlain <mcgrof@kernel.org> wrote:
> > >
> > > On Mon, Dec 19, 2022 at 02:46:18PM -0600, Allen Webb wrote:
> > > > Update the documentation to include the presense and use case of
> > > > modules.builtin.alias.
> > > >
> > > > Signed-off-by: Allen Webb <allenwebb@google.com>
> > > > ---
> > > >  Documentation/kbuild/kbuild.rst | 6 ++++++
> > > >  1 file changed, 6 insertions(+)
> > > >
> > > > diff --git a/Documentation/kbuild/kbuild.rst b/Documentation/kbuild/kbuild.rst
> > > > index 08f575e6236c..1c7c02040a54 100644
> > > > --- a/Documentation/kbuild/kbuild.rst
> > > > +++ b/Documentation/kbuild/kbuild.rst
> > > > @@ -17,6 +17,12 @@ modules.builtin
> > > >  This file lists all modules that are built into the kernel. This is used
> > > >  by modprobe to not fail when trying to load something builtin.
> > > >
> > > > +modules.builtin.alias
> > > > +---------------------
> > > > +This file lists all match-id based aliases for modules built into the kernel.
> > > > +These are intended to enable userspace to make authorization decisions based
> > > > +on which modules are likely to be bound to a device after it is authorized.
> > >
> > > What is an example? This sounds obscure.
> >
> > Many of the devices that match the usb_storage driver only specify the
> > vendor id, product id, and device id (VID:PID:D) and do not match
> > against device class, interface class, etc. Here are some examples
> > from modules.alias: A grep for wildcards in these fields yields 6136
> > matches:
> > grep 'dc\*dsc\*dp\*ic\*isc\*ip\*in\*'
> > /lib/modules/5.19.11-1rodete1-amd64/modules.alias | wc -l
> > 6136
> >
> > To write USBGuard policy that only authorizes devices that bind to a
> > particular module the policy needs to be aware of all these VID:PID:D
> > which can change between kernel versions.
> >
> > This is done at runtime rather than excluding modules from the build
> > because some devices are not needed at or before login or when a
> > device is locked. By not authorizing new devices that would bind to a
> > set of modules, these modules become unreachable to an attacker who
> > seeks to exploit kernel bugs in those modules.
> >
> > I could add this detail to the documentation file, but I was trying to
> > keep the description to about the same length as the others around it.
>
> How about the second sentence you wrote say something like:
>
> An example usage of the built-in aliases is to enable software such as
> USBGuard to enable / disable specific devices outside of just the
> vendor, product and device ID. This allows more flexible security policies
> in userspace.

I tweaked it a tiny bit, but that makes the whole description:

This file lists all match-id based aliases for modules built into the kernel.
An example usage of the built-in aliases is to enable software such as
USBGuard to allow or block devices outside of just the vendor, product, and
device ID. This enables more flexible security policies in userspace.

>
>   Luis
  

On Mon, Dec 19, 2022 at 04:20:41PM -0600, Allen Webb wrote:
> On Mon, Dec 19, 2022 at 4:07 PM Luis Chamberlain <mcgrof@kernel.org> wrote:
> >
> > On Mon, Dec 19, 2022 at 03:40:42PM -0600, Allen Webb wrote:
> > > On Mon, Dec 19, 2022 at 3:23 PM Luis Chamberlain <mcgrof@kernel.org> wrote:
> > > >
> > > > On Mon, Dec 19, 2022 at 02:46:18PM -0600, Allen Webb wrote:
> > > > > Update the documentation to include the presense and use case of
> > > > > modules.builtin.alias.
> > > > >
> > > > > Signed-off-by: Allen Webb <allenwebb@google.com>
> > > > > ---
> > > > >  Documentation/kbuild/kbuild.rst | 6 ++++++
> > > > >  1 file changed, 6 insertions(+)
> > > > >
> > > > > diff --git a/Documentation/kbuild/kbuild.rst b/Documentation/kbuild/kbuild.rst
> > > > > index 08f575e6236c..1c7c02040a54 100644
> > > > > --- a/Documentation/kbuild/kbuild.rst
> > > > > +++ b/Documentation/kbuild/kbuild.rst
> > > > > @@ -17,6 +17,12 @@ modules.builtin
> > > > >  This file lists all modules that are built into the kernel. This is used
> > > > >  by modprobe to not fail when trying to load something builtin.
> > > > >
> > > > > +modules.builtin.alias
> > > > > +---------------------
> > > > > +This file lists all match-id based aliases for modules built into the kernel.
> > > > > +These are intended to enable userspace to make authorization decisions based
> > > > > +on which modules are likely to be bound to a device after it is authorized.
> > > >
> > > > What is an example? This sounds obscure.
> > >
> > > Many of the devices that match the usb_storage driver only specify the
> > > vendor id, product id, and device id (VID:PID:D) and do not match
> > > against device class, interface class, etc. Here are some examples
> > > from modules.alias: A grep for wildcards in these fields yields 6136
> > > matches:
> > > grep 'dc\*dsc\*dp\*ic\*isc\*ip\*in\*'
> > > /lib/modules/5.19.11-1rodete1-amd64/modules.alias | wc -l
> > > 6136
> > >
> > > To write USBGuard policy that only authorizes devices that bind to a
> > > particular module the policy needs to be aware of all these VID:PID:D
> > > which can change between kernel versions.
> > >
> > > This is done at runtime rather than excluding modules from the build
> > > because some devices are not needed at or before login or when a
> > > device is locked. By not authorizing new devices that would bind to a
> > > set of modules, these modules become unreachable to an attacker who
> > > seeks to exploit kernel bugs in those modules.
> > >
> > > I could add this detail to the documentation file, but I was trying to
> > > keep the description to about the same length as the others around it.
> >
> > How about the second sentence you wrote say something like:
> >
> > An example usage of the built-in aliases is to enable software such as
> > USBGuard to enable / disable specific devices outside of just the
> > vendor, product and device ID. This allows more flexible security policies
> > in userspace.
> 
> I tweaked it a tiny bit, but that makes the whole description:
> 
> This file lists all match-id based aliases for modules built into the kernel.
> An example usage of the built-in aliases is to enable software such as
> USBGuard to allow or block devices outside of just the vendor, product, and
> device ID. This enables more flexible security policies in userspace.

Now, without ever readng your patchset and intentions I can easily grasp
what your goals are. Looks good. Feel free to add my Reviewed-by tags
for this patch.

  Luis