[00/10] LSM documentation update
mbox series

Message ID cover.1549540487.git.efremov@ispras.ru
Headers show
Series
  • LSM documentation update
Related show

Message

Denis Efremov Feb. 7, 2019, 12:44 p.m. UTC
Recent "New LSM Hooks" discussion has led me to the
thought that it might be a good idea to slightly
update the current documentation. The patchset adds
nothing new to the documentation, only fixes the old
description of hooks to reflect their current state.

Denis Efremov (10):
  security: fix documentation for the sb_copy_data hook
  security: fix documentation for the syslog hook
  security: fix documentation for the socket_post_create hook
  security: fix documentation for the task_setscheduler hook
  security: fix documentation for the socket_getpeersec_dgram hook
  security: fix documentation for the path_chmod hook
  security: fix documentation for the audit_* hooks
  security: fix documentation for the msg_queue_* hooks
  security: fix documentation for the sem_* hooks
  security: fix documentation for the shm_* hooks

 include/linux/lsm_hooks.h | 127 ++++++++++++++++++--------------------
 1 file changed, 61 insertions(+), 66 deletions(-)

Comments

Kees Cook Feb. 11, 2019, 7:28 p.m. UTC | #1
On Thu, Feb 7, 2019 at 4:45 AM Denis Efremov <efremov@ispras.ru> wrote:
>
> Recent "New LSM Hooks" discussion has led me to the
> thought that it might be a good idea to slightly
> update the current documentation. The patchset adds
> nothing new to the documentation, only fixes the old
> description of hooks to reflect their current state.

Do these fixes silence any warnings during the documentation build?
(i.e. how did you verify the results beyond eyeballing the changes)

-Kees

>
> Denis Efremov (10):
>   security: fix documentation for the sb_copy_data hook
>   security: fix documentation for the syslog hook
>   security: fix documentation for the socket_post_create hook
>   security: fix documentation for the task_setscheduler hook
>   security: fix documentation for the socket_getpeersec_dgram hook
>   security: fix documentation for the path_chmod hook
>   security: fix documentation for the audit_* hooks
>   security: fix documentation for the msg_queue_* hooks
>   security: fix documentation for the sem_* hooks
>   security: fix documentation for the shm_* hooks
>
>  include/linux/lsm_hooks.h | 127 ++++++++++++++++++--------------------
>  1 file changed, 61 insertions(+), 66 deletions(-)
>
> --
> 2.17.2
>
Denis Efremov Feb. 17, 2019, 6:04 p.m. UTC | #2
Kees Cook писал 2019-02-11 22:28:
> On Thu, Feb 7, 2019 at 4:45 AM Denis Efremov <efremov@ispras.ru> wrote:
>> 
>> Recent "New LSM Hooks" discussion has led me to the
>> thought that it might be a good idea to slightly
>> update the current documentation. The patchset adds
>> nothing new to the documentation, only fixes the old
>> description of hooks to reflect their current state.

> 
> Do these fixes silence any warnings during the documentation build?
> (i.e. how did you verify the results beyond eyeballing the changes)
> 
> -Kees

This LSM documentation is not used during the documentation build.
At least I can't find it in the resulting build directory and at
the online documentation on the kernel. Most of the fixes are pretty
obvious and can be checked by comparing an lsm hook declaration and
its description in the LSM comment from lsm_hooks.h I tried to be
exhaustive in the commits description and in every case to reference
the original commit where the interface was changed without
documentation update.

> 
>> 
>> Denis Efremov (10):
>>   security: fix documentation for the sb_copy_data hook
>>   security: fix documentation for the syslog hook
>>   security: fix documentation for the socket_post_create hook
>>   security: fix documentation for the task_setscheduler hook
>>   security: fix documentation for the socket_getpeersec_dgram hook
>>   security: fix documentation for the path_chmod hook
>>   security: fix documentation for the audit_* hooks
>>   security: fix documentation for the msg_queue_* hooks
>>   security: fix documentation for the sem_* hooks
>>   security: fix documentation for the shm_* hooks
>> 
>>  include/linux/lsm_hooks.h | 127 
>> ++++++++++++++++++--------------------
>>  1 file changed, 61 insertions(+), 66 deletions(-)
>> 
>> --
>> 2.17.2
>>
Kees Cook Feb. 17, 2019, 10:15 p.m. UTC | #3
On Sun, Feb 17, 2019 at 10:04 AM efremov <efremov@ispras.ru> wrote:
>
> Kees Cook писал 2019-02-11 22:28:
> > On Thu, Feb 7, 2019 at 4:45 AM Denis Efremov <efremov@ispras.ru> wrote:
> >>
> >> Recent "New LSM Hooks" discussion has led me to the
> >> thought that it might be a good idea to slightly
> >> update the current documentation. The patchset adds
> >> nothing new to the documentation, only fixes the old
> >> description of hooks to reflect their current state.
>
> >
> > Do these fixes silence any warnings during the documentation build?
> > (i.e. how did you verify the results beyond eyeballing the changes)
> >
> > -Kees
>
> This LSM documentation is not used during the documentation build.
> At least I can't find it in the resulting build directory and at
> the online documentation on the kernel. Most of the fixes are pretty
> obvious and can be checked by comparing an lsm hook declaration and
> its description in the LSM comment from lsm_hooks.h I tried to be
> exhaustive in the commits description and in every case to reference
> the original commit where the interface was changed without
> documentation update.

I'll send an official patch that'll hook this up. I've been meaning to
do it for a while, but there were several things that needed cleaning
up (and you've snagged most of them). So with this patch, you'll be
able to check the output for "make htmldocs" for lsm_hooks.h errors:

diff --git a/Documentation/security/LSM.rst b/Documentation/security/LSM.rst
index 8b9ee597e9d0..31d92bc5fdd2 100644
--- a/Documentation/security/LSM.rst
+++ b/Documentation/security/LSM.rst
@@ -11,4 +11,7 @@ that end users and distros can make a more informed
decision about which
 LSMs suit their requirements.

 For extensive documentation on the available LSM hook interfaces, please
-see ``include/linux/lsm_hooks.h``.
+see ``include/linux/lsm_hooks.h`` and associated structures:
+
+.. kernel-doc:: include/linux/lsm_hooks.h
+   :internal: