Op 04/06/18 om 16:57 schreef Kristaps Dzonsons:
Hi folks,
Short: what do you recommend for documenting an external library's
pledge(2) requirements?
Longer: https://bsd.network/@florian/99802355448571943
The question raised in this... um... toot?... is which promises are
required by an external library call, in this case khttp_parse(3) in
kcgi. Sure, we can always just run the program, look in
/var/log/messages for failure, and edit our promises. But just... no.
In this particular case, I've documented this function's requirements
unofficially here and there---tutorials and such. But it's not
canonical. What I'd like is to put these directly into the manpages.
Something like:
.Sh SANDBOXING
On
.Ox ,
the
.Fn khttp_parse
function requires the
.Qq stdio proc
promises to
.Xr pledge 2 .
This encourages developers to use the tightest possible promises. And
as mdoc(7) is meant not to be system-specific, this might also include
information on, say, .Fx's Capsicum, or maybe whatever Linux uses this
week. It already has "SECURITY CONSIDERATIONS", but that just doesn't
seem quite right.
Thoughts?
Kristaps
What about having some sort of function yourlib_pledge_set_promises()
that sets up these requirements ? I think this also has the advantage of
automatically separating pledge specific code (and a man page) from
generic code as well as lessening the chance of users of your library
setting up incorrect promises for your library. Or in light of updates
to your library, users may not need to change their program's pledges
since the updated yourlib_pledge_set_promises function will hopefully be
sufficient to take care of that.
