Hi Kristaps,
Kristaps Dzonsons BSD.LV wrote on Fri, Apr 06, 2018 at 09:57:09PM +0700:
> Short: what do you recommend for documenting an external library's
> pledge(2) requirements?
That is an interesting question indeed. I never considered it
before, so i will think about it in some detail.
For a bit of context, let me first explain how documentation of
pledge(2) requirements inside the OpenBSD C library itself works,
and why the documentation was designed that way.
On first sight, it might seem most user-friendly if each and every
section 3 manual page for the C library would state the pledge(2)
requirements for each individual library function.
But that would have three important downsides:
(1) It would be hard to do. There are very many manual pages,
so it would require much work for initial setup.
(2) It would be unmaintainable, in particular while pledge(2)
is still in very active development. Pledge evolved through
incremental tweaking. Usage patterns were studied and modeled,
the resulting pledge promises applied across the whole three,
and the resulting experience allowed to refine the analysis
and improve the way pledge(2) itself worked, based on real-world
usage. Rinse and repeat, literally dozens of times, over years
of careful work. Keeping many hundred manual pages in sync
with that gradual evolution would have been flat-out impossible.
(3) It would have put the focus in the wrong place.
One among the chief ideas of pledge(2) is to avoid the splintered
character of traditional syscall filters, where you are forced
to filter each syscall, or even worse each of the arguments
of each syscall, individually, and consequently completely lose
the overview of what you are really doing before you even get
started. Instead, pleadge promises enable high-level logical
feature groups. The essential job of pledge(2) documentation
is not to say that the FOO promise enables the BAR argument
of the BAZ syscall, but that pledging FOO is required when you
want to do operations of the BAR kind, no matter with which
calls or arguments.
Of course, once pledge(2) is completely stable, there would
be nothing wrong with *also* documenting the effect in individual
library functions manuals for user convenience, even though
that would imply some redundancy. But given that pledge(2)
is still quite actively worked on, i doubt it will happen soon,
if ever at all.
That said, for external libraries, putting your stuff directly into
the pledge(2) manual is obviously not an option. Also, i agree
that documenting pledge(2) requirements for external libraries
is very useful, because these requirements are often quite
non-obvious and hard to guess by just looking at the pledge(2)
manual page itself, because many library manuals intentionally,
and sensibly, do not document how exactly the library operates
internally.
Note that for external libraries, the above arguments do not
apply:
(1) Well-designed external libraries have small numbers of
functions, so problem (1) is not a concern.
(2) The logical functionality of functions in external libraries
is hopefully mostly stable, and the required promises will
rarely be affected by changes in pledge(2) itself. Also,
pledge(2) has already stabilized considerably, so problem (2)
is no longer a major concern - though a bit of maintenace
may be required now and then if you put such information
into your manual pages.
(3) The pledge(2) manual explains the high-level logic, your
manuals add the specifics for your library, without
duplication of information. That is a clean division
of tasks, so problem (3) is not a concern.
> 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.
Absolutely agreed. "Complete functional description in one
canonical place, do not scatter reference-manual-type information
across multiple sources" is among the most important requirements
for good documentation.
> .Sh SANDBOXING
> On
> .Ox ,
> the
> .Fn khttp_parse
> function requires the
> .Qq stdio proc
> promises to
> .Xr pledge 2 .
As long as it is only a single sentence, that could easily go right
after the description of the individual function in the DESCRIPTION,
or alternatively at the end of the DESCRIPTION section. Custom
sections are not very nice, in particular when they are so short
that they hardly justify opening a new section in the first place.
If you really want to describe multiple different sandboxing
systems, then i guess ".Sh SANDBOXING" after the DESCRIPTION
might make sense. I'm not all that sure that describing any other
system will be possible without going overboard; they are typically
much too complicated to be summarized without excessive verbosity.
But you shall no doubt see whether or not it works...
The text itself reads fine to me.
> 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.
No, mdoc(7) says
.\" .Sh SECURITY CONSIDERATIONS
.\" Not used in OpenBSD.
for a reason: security ought to be an integral part of interface
design and description, not an afterthought. Besides, that section
is intended to be used a bit like CAVEATS, i.e. to explain dubious
design decisions that set up traps for the user. If there are
any such traps, describing them below CAVEATS is just fine, as that
section is rarely overcrowded.
On the other hand, to promote coding idioms that are good for
correctness, robustness, security, and simplicity, we typically use
the EXAMPLES section.
Yours,
Ingo
