[kernel-hardening] HARDENED_ATOMIC documentation

[kernel-hardening] HARDENED_ATOMIC documentation

[David Windsor]

[-- Attachment #1: Type: text/plain, Size: 590 bytes --]

Hi,

I've put together some preliminary documentation for HARDENED_ATOMIC.  This
will be in addition to the in-tree documentation earlier submitted for
review.  This documentation contains only an API definition and examples.
Justification and background info for HARDENED_ATOMIC are included in the
in-tree documentation, so I didn't recreate this info in the kernsec.org
documentation.  Thoughts about this?

You can find this documentation at
http://kernsec.org/wiki/index.php/Kernel_Protections/HARDENED_ATOMIC.

Please take a look and let me know your comments.

Thanks,
David Windsor

[-- Attachment #2: Type: text/html, Size: 827 bytes --]

[kernel-hardening] Re: HARDENED_ATOMIC documentation

[Greg KH]

On Mon, Feb 06, 2017 at 09:55:41AM -0500, David Windsor wrote:
> Hi,
> 
> I've put together some preliminary documentation for HARDENED_ATOMIC.  This
> will be in addition to the in-tree documentation earlier submitted for review. 
> This documentation contains only an API definition and examples.  Justification
> and background info for HARDENED_ATOMIC are included in the in-tree
> documentation, so I didn't recreate this info in the kernsec.org
> documentation.  Thoughts about this?
> 
> You can find this documentation at http://kernsec.org/wiki/index.php/
> Kernel_Protections/HARDENED_ATOMIC. 
> 
> Please take a look and let me know your comments.

Please just send it as a patch so that we can comment on it, as well as
don't send html email because the mailing lists reject it!

thanks,

greg k-h

[kernel-hardening] Re: HARDENED_ATOMIC documentation

[David Windsor]

[-- Attachment #1: Type: text/plain, Size: 1362 bytes --]

On Mon, Feb 6, 2017 at 10:13 AM, Greg KH <gregkh@linuxfoundation.org> wrote:

> On Mon, Feb 06, 2017 at 09:55:41AM -0500, David Windsor wrote:
> > Hi,
> >
> > I've put together some preliminary documentation for HARDENED_ATOMIC.
> This
> > will be in addition to the in-tree documentation earlier submitted for
> review.
> > This documentation contains only an API definition and examples.
> Justification
> > and background info for HARDENED_ATOMIC are included in the in-tree
> > documentation, so I didn't recreate this info in the kernsec.org
> > documentation.  Thoughts about this?
> >
> > You can find this documentation at http://kernsec.org/wiki/index.php/
> > Kernel_Protections/HARDENED_ATOMIC.
> >
> > Please take a look and let me know your comments.
>
> Please just send it as a patch so that we can comment on it, as well as
> don't send html email because the mailing lists reject it!
>
>
Sorry, I might not have been clear: this is just a request to review the
documentation I posted on kernsec.org for the HARDENED_ATOMIC portion of
KSPP.  We're going to use kernsec.org as a place to host additional
documentation for KSPP and its related sub-projects.  There isn't an
in-tree portion of this, so I'm not sure what I could submit a patch
against.  I probably shouldn't have directly CC'ed you on this; my
apologies!


> thanks,
>
> greg k-h
>

[-- Attachment #2: Type: text/html, Size: 2231 bytes --]

[kernel-hardening] Re: HARDENED_ATOMIC documentation

[Greg KH]

On Mon, Feb 06, 2017 at 10:19:14AM -0500, David Windsor wrote:
> On Mon, Feb 6, 2017 at 10:13 AM, Greg KH <gregkh@linuxfoundation.org> wrote:
> 
>     On Mon, Feb 06, 2017 at 09:55:41AM -0500, David Windsor wrote:
>     > Hi,
>     >
>     > I've put together some preliminary documentation for HARDENED_ATOMIC. 
>     This
>     > will be in addition to the in-tree documentation earlier submitted for
>     review. 
>     > This documentation contains only an API definition and examples. 
>     Justification
>     > and background info for HARDENED_ATOMIC are included in the in-tree
>     > documentation, so I didn't recreate this info in the kernsec.org
>     > documentation.  Thoughts about this?
>     >
>     > You can find this documentation at http://kernsec.org/wiki/index.php/
>     > Kernel_Protections/HARDENED_ATOMIC. 
>     >
>     > Please take a look and let me know your comments.
> 
>     Please just send it as a patch so that we can comment on it, as well as
>     don't send html email because the mailing lists reject it!
> 
> 
> 
> Sorry, I might not have been clear: this is just a request to review the
> documentation I posted on kernsec.org for the HARDENED_ATOMIC portion of KSPP. 
> We're going to use kernsec.org as a place to host additional documentation for
> KSPP and its related sub-projects.  There isn't an in-tree portion of this, so
> I'm not sure what I could submit a patch against.  I probably shouldn't have
> directly CC'ed you on this; my apologies!

Why not put the documentation right into the kernel tree?  That way it
is always up to date with the code (well, hopefully), it will get built
and hosted all over the internet at different sites (including
kernel.org) and is much easier to search and people can modify easier.

And again, you are sending html email which the mailing list rejects so
no one on it is seeing your messages :(

thanks,

greg k-h

[kernel-hardening] Re: HARDENED_ATOMIC documentation

[David Windsor]

> Why not put the documentation right into the kernel tree?  That way it
> is always up to date with the code (well, hopefully), it will get built
> and hosted all over the internet at different sites (including
> kernel.org) and is much easier to search and people can modify easier.
>

Fair enough, I'll re-submit as a patch against something in
Documentation/.  It doesn't appear that there's currently a good
landing spot for this, as Documentation/security/self-protection.txt
already looks fairly crowded.  Individual KSPP sub-project details
would impossibly complicate this file.  Maybe a kspp/ or
self-protection/ sub-directory with files for individual KSPP
features?

> And again, you are sending html email which the mailing list rejects so
> no one on it is seeing your messages :(
>

Sorry.  This should be fixed now.

>
> thanks,
>
> greg k-h

Re: [kernel-hardening] Re: HARDENED_ATOMIC documentation

[Mark Rutland]

On Mon, Feb 06, 2017 at 11:02:56AM -0500, David Windsor wrote:
> > Why not put the documentation right into the kernel tree?  That way it
> > is always up to date with the code (well, hopefully), it will get built
> > and hosted all over the internet at different sites (including
> > kernel.org) and is much easier to search and people can modify easier.
> >
> 
> Fair enough, I'll re-submit as a patch against something in
> Documentation/.  It doesn't appear that there's currently a good
> landing spot for this, as Documentation/security/self-protection.txt
> already looks fairly crowded.  Individual KSPP sub-project details
> would impossibly complicate this file.  Maybe a kspp/ or
> self-protection/ sub-directory with files for individual KSPP
> features?

It would be better to mirror our documentation of atomics; i.e. place
this in Documentation/core-api/refcount_ops.rst.

Developers don't care if this is part of KSPP, they care about the API.

Thanks,
Mark.

Re: [kernel-hardening] Re: HARDENED_ATOMIC documentation

[Kees Cook]

On Mon, Feb 6, 2017 at 8:09 AM, Mark Rutland <mark.rutland@arm.com> wrote:
> On Mon, Feb 06, 2017 at 11:02:56AM -0500, David Windsor wrote:
>> > Why not put the documentation right into the kernel tree?  That way it
>> > is always up to date with the code (well, hopefully), it will get built
>> > and hosted all over the internet at different sites (including
>> > kernel.org) and is much easier to search and people can modify easier.
>> >
>>
>> Fair enough, I'll re-submit as a patch against something in
>> Documentation/.  It doesn't appear that there's currently a good
>> landing spot for this, as Documentation/security/self-protection.txt
>> already looks fairly crowded.  Individual KSPP sub-project details
>> would impossibly complicate this file.  Maybe a kspp/ or
>> self-protection/ sub-directory with files for individual KSPP
>> features?
>
> It would be better to mirror our documentation of atomics; i.e. place
> this in Documentation/core-api/refcount_ops.rst.

Yeah, this is likely the best place. (And since it's not strictly
"hardened atomic" any more: it's just "safe refcounting".)

> Developers don't care if this is part of KSPP, they care about the API.

Right. I think changes could be made to
Documentation/security/self-protection.txt to point to the
refcount_ops.rst file, though, since security folks would like
pointers from that doc to the refcount API.

-Kees

-- 
Kees Cook
Pixel Security

Re: [kernel-hardening] Re: HARDENED_ATOMIC documentation

[David Windsor]

On Mon, Feb 6, 2017 at 3:08 PM, Kees Cook <keescook@chromium.org> wrote:
> On Mon, Feb 6, 2017 at 8:09 AM, Mark Rutland <mark.rutland@arm.com> wrote:
>> On Mon, Feb 06, 2017 at 11:02:56AM -0500, David Windsor wrote:
>>> > Why not put the documentation right into the kernel tree?  That way it
>>> > is always up to date with the code (well, hopefully), it will get built
>>> > and hosted all over the internet at different sites (including
>>> > kernel.org) and is much easier to search and people can modify easier.
>>> >
>>>
>>> Fair enough, I'll re-submit as a patch against something in
>>> Documentation/.  It doesn't appear that there's currently a good
>>> landing spot for this, as Documentation/security/self-protection.txt
>>> already looks fairly crowded.  Individual KSPP sub-project details
>>> would impossibly complicate this file.  Maybe a kspp/ or
>>> self-protection/ sub-directory with files for individual KSPP
>>> features?
>>
>> It would be better to mirror our documentation of atomics; i.e. place
>> this in Documentation/core-api/refcount_ops.rst.
>
> Yeah, this is likely the best place. (And since it's not strictly
> "hardened atomic" any more: it's just "safe refcounting".)
>
>> Developers don't care if this is part of KSPP, they care about the API.
>
> Right. I think changes could be made to
> Documentation/security/self-protection.txt to point to the
> refcount_ops.rst file, though, since security folks would like
> pointers from that doc to the refcount API.
>

Understood.  I'll take the API reference I just created on kernsec.org
and move its contents to Documentation/core-api/refcount_ops.rst.
Then, update Documentation/security/self-protection.txt with some
language about this feature's justification, etc. and point to
refcount_ops.rst.

Thanks!

> -Kees
>
> --
> Kees Cook
> Pixel Security

[kernel-hardening] Re: HARDENED_ATOMIC documentation

[Jonathan Corbet]

On Mon, 6 Feb 2017 15:36:10 -0500
David Windsor <dwindsor@gmail.com> wrote:

> Understood.  I'll take the API reference I just created on kernsec.org
> and move its contents to Documentation/core-api/refcount_ops.rst.
> Then, update Documentation/security/self-protection.txt with some
> language about this feature's justification, etc. and point to
> refcount_ops.rst.

This all sounds good, but the low-level API documentation is best done as
kerneldoc comments with the actual definitions of the functions.  You can
then use the appropriate directives to pull it into the RST documentation.

Details in Documentation/doc-guide/ if you need them.

Thanks,

jon

[kernel-hardening] Re: HARDENED_ATOMIC documentation

[David Windsor]

On Mon, Feb 6, 2017 at 3:51 PM, Jonathan Corbet <corbet@lwn.net> wrote:
> On Mon, 6 Feb 2017 15:36:10 -0500
> David Windsor <dwindsor@gmail.com> wrote:
>
>> Understood.  I'll take the API reference I just created on kernsec.org
>> and move its contents to Documentation/core-api/refcount_ops.rst.
>> Then, update Documentation/security/self-protection.txt with some
>> language about this feature's justification, etc. and point to
>> refcount_ops.rst.
>
> This all sounds good, but the low-level API documentation is best done as
> kerneldoc comments with the actual definitions of the functions.  You can
> then use the appropriate directives to pull it into the RST documentation.
>
> Details in Documentation/doc-guide/ if you need them.
>

Even better.

Objections, anyone?

> Thanks,
>
> jon