linux-kernel - Re: [PATCH 2/2] docs: fault-injection: Add requirements of error injectable functions

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives
Hash Suite: Windows password security audit tool. GUI, reports in PDF.
[<prev] [next>] [<thread-prev] [day] [month] [year] [list]
Message-Id: <20221213231122.7ae94229bdd6e9e232a4c32c@kernel.org>
Date:   Tue, 13 Dec 2022 23:11:22 +0900
From:   Masami Hiramatsu (Google) <mhiramat@...nel.org>
To:     Randy Dunlap <rdunlap@...radead.org>
Cc:     LKML <linux-kernel@...r.kernel.org>, bpf@...r.kernel.org,
        Borislav Petkov <bp@...en8.de>,
        Alexei Starovoitov <alexei.starovoitov@...il.com>,
        Steven Rostedt <rostedt@...dmis.org>,
        Linus Torvalds <torvalds@...ux-foundation.org>,
        Andrew Morton <akpm@...ux-foundation.org>,
        Peter Zijlstra <peterz@...radead.org>,
        Kees Cook <keescook@...omium.org>,
        Josh Poimboeuf <jpoimboe@...hat.com>,
        KP Singh <kpsingh@...nel.org>,
        Mark Rutland <mark.rutland@....com>,
        Florent Revest <revest@...omium.org>,
        Greg Kroah-Hartman <gregkh@...uxfoundation.org>,
        Christoph Hellwig <hch@...radead.org>,
        Chris Mason <clm@...a.com>, Jonathan Corbet <corbet@....net>,
        linux-doc@...r.kernel.org
Subject: Re: [PATCH 2/2] docs: fault-injection: Add requirements of error
 injectable functions

Hi Randy,

Thank you very much for the review!
OK, I'll fix those typos and misses.

Thanks!

On Mon, 12 Dec 2022 22:54:08 -0800
Randy Dunlap <rdunlap@...radead.org> wrote:

> Hi--
> 
> On 12/11/22 18:46, Masami Hiramatsu (Google) wrote:
> > From: Masami Hiramatsu (Google) <mhiramat@...nel.org>
> > 
> > Add a section about the requirements of the error injectable functions
> > and the type of errors.
> > Since this section must be read before using ALLOW_ERROR_INJECTION()
> > macro, that section is referred from the comment of the macro too.
> > 
> > Signed-off-by: Masami Hiramatsu (Google) <mhiramat@...nel.org>
> > Link: https://lore.kernel.org/all/20221211115218.2e6e289bb85f8cf53c11aa97@kernel.org/T/#u
> > ---
> >  Documentation/fault-injection/fault-injection.rst |   65 +++++++++++++++++++++
> >  include/asm-generic/error-injection.h             |    6 +-
> >  2 files changed, 69 insertions(+), 2 deletions(-)
> > 
> > diff --git a/Documentation/fault-injection/fault-injection.rst b/Documentation/fault-injection/fault-injection.rst
> > index 17779a2772e5..da6c5796b1f8 100644
> > --- a/Documentation/fault-injection/fault-injection.rst
> > +++ b/Documentation/fault-injection/fault-injection.rst
> > @@ -233,6 +233,71 @@ proc entries
> >  	This feature is intended for systematic testing of faults in a single
> >  	system call. See an example below.
> >  
> > +
> > +Error Injectable Functions
> > +--------------------------
> > +
> > +This part is for the kenrel developers considering to add a function to
> 
>                         kernel developers considering adding a function
> 
> > +ALLOW_ERROR_INJECTION() macro.
> 
>    using the ALLOW_ERROR_INJECTION() macro.
> 
> > +
> > +Requirements for the Error Injectable Functions
> > +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> > +
> > +Since the function-level error injection forcibly changes the code path
> > +and returns an error even if the input and conditions are proper, this can
> > +cause unexpected kernel crash if you allow error injection on the function
> > +which is NOT error injectable. Thus, you (and reviewers) must ensure;
> > +
> > +- The function returns an error code if it fails, and the callers must check
> > +  it correctly (need to recover from it).
> > +
> > +- The function does not execute any code which can change any state before
> > +  the first error return. The state includes global or local, or input
> > +  variable. For example, clear output address storage (e.g. `*ret = NULL`),
> > +  increments/decrements counter, set a flag, preempt/irq disable or get
> 
>      increment/decrement a counter,
> 
> > +  a lock (if those are recovered before returning error, that will be OK.)
> > +
> > +The first requirement is important, and it will result in that the release
> > +(free objects) functions are usually harder to inject errors than allocate
> > +functions. If errors of such release functions are not correctly handled
> > +it will cause a memory leak easily (the caller will confuse that the object
> > +has been released or corrupted.)
> > +
> > +The second one is for the caller which expects the function should always
> > +does something. Thus if the function error injection skips whole of the
> 
>    do something.                                        skips all of the
> 
> > +function, the expectation is betrayed and causes an unexpected error.
> > +
> > +Type of the Error Injectable Functions
> > +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> > +
> > +Each error injectable functions will have the error type specified by the
> 
>                          function
> 
> > +ALLOW_ERROR_INJECTION() macro. You have to choose it carefully if you add
> > +a new error injectable function. If the wrong error type is chosen, the
> > +kernel may crash because it may not be able to handle the error.
> > +There are 4 types of errors defined in include/asm-generic/error-injection.h
> > +
> > +EI_ETYPE_NULL
> > +  This function will return `NULL` if it fails. e.g. return an allocateed
> 
>                                                                   allocated
> 
> > +  object address.
> > +
> > +EI_ETYPE_ERRNO
> > +  This function will return an `-errno` error code if it fails. e.g. return
> > +  -EINVAL if the input is wrong. This will include the functions which will
> > +  return an address which encodes `-errno` by ERR_PTR() macro.
> > +
> > +EI_ETYPE_ERRNO_NULL
> > +  This function will return an `-errno` or `NULL` if it fails. If the caller
> > +  of this function checks the return value with IS_ERR_OR_NULL() macro, this
> > +  type will be appropriate.
> > +
> > +EI_ETYPE_TRUE
> > +  This function will return `true` (non-zero positive value) if it fails.
> > +
> > +If you specifies a wrong type, for example, EI_TYPE_ERRNO for the function
> 
>           specify
> 
> > +which returns an allocated object, it may cause a problem because the returned
> > +value is not an object address and the caller can not access to the address.
> > +
> > +
> >  How to add new fault injection capability
> >  -----------------------------------------
> >  
> > diff --git a/include/asm-generic/error-injection.h b/include/asm-generic/error-injection.h
> > index c0b9d3217ed9..b05253f68eaa 100644
> > --- a/include/asm-generic/error-injection.h
> > +++ b/include/asm-generic/error-injection.h
> > @@ -19,8 +19,10 @@ struct pt_regs;
> >  
> >  #ifdef CONFIG_FUNCTION_ERROR_INJECTION
> >  /*
> > - * Whitelist generating macro. Specify functions which can be
> > - * error-injectable using this macro.
> > + * Whitelist generating macro. Specify functions which can be error-injectable
> > + * using this macro. If you unsure what is required for the error-injectable
> 
>                         If you are unsure ...
> 
> > + * functions, please read Documentation/fault-injection/fault-injection.rst
> > + * 'Error Injectable Functions' section.
> >   */
> >  #define ALLOW_ERROR_INJECTION(fname, _etype)				\
> >  static struct error_injection_entry __used				\
> > 
> 
> -- 
> ~Randy


-- 
Masami Hiramatsu (Google) <mhiramat@...nel.org>