grub-dev: Verifiers framework
13 Verifiers framework
**********************
To register your own verifier call 'grub_verifier_register' with a
structure pointing to your functions.
The interface is inspired by the hash interface with
'init'/'write'/'fini'.
There are essentially 2 ways of using it, hashing and whole-file
verification.
With the hashing approach: During 'init' you decide whether you want
to check the given file and init context. In 'write' you update your
hashing state. In 'fini' you check that the hash matches the expected
value/passes some check/...
With whole-file verification: During 'init' you decide whether you
want to check the given file and init context. In 'write' you verify
the file and return an error if it fails. You don't have 'fini'.
Additional 'verify_string' receives various strings like kernel
parameters to verify. Returning no error means successful verification
and an error stops the current action.
Detailed description of the API:
Every time a file is opened your 'init' function is called with file
descriptor and file type. Your function can have the following
outcomes:
* returning no error and setting '*flags' to
'GRUB_VERIFY_FLAGS_DEFER_AUTH'. In this case verification is
deferred to other active verifiers. Verification fails if nobody
cares or selected verifier fails.
* returning no error and setting '*flags' to
'GRUB_VERIFY_FLAGS_SKIP_VERIFICATION'. In this case your verifier
will not be called anymore and it is assumed to have skipped
verification.
* returning no error and not setting '*flags' to
'GRUB_VERIFY_FLAGS_SKIP_VERIFICATION' In this case verification is
done as described in the following section.
* returning an error. Then opening of the file will fail due to
failed verification.
In the third case your 'write' will be called with chunks of the
file. If you need the whole file in a single chunk then during 'init'
set the bit 'GRUB_VERIFY_FLAGS_SINGLE_CHUNK' in '*flags'. During 'init'
you may set '*context' if you need additional context. At every
iteration you may return an error and the file will be considered as
having failed the verification. If you return no error then
verification continues.
Optionally at the end of the file 'fini', if it exists, is called
with just the context. If you return no error during any of 'init',
'write' and 'fini' then the file is considered as having succeded
verification.