Re: CVS commit: src/usr.bin/nbsvtool

[Dieter Baron <dillo%KD119105101110.ppp-bb.dion.ne.jp@localhost>]

[documenting nbsvtool, moved here from source-changes]

In article <20080714163517.GA4058%britannica.bec.de@localhost> Joerg wrote:
: On Mon, Jul 14, 2008 at 05:15:39PM +0100, Alistair Crooks wrote:
: > > People can't agree on what and what not should be described.
: > 
: > That wasn't my impression - various people have asked for
: > documentation, and policies backing this tool up, both before and
: > after the code was committed.
: > 
: > The only one who didn't agree with this was ...ummm... err... joerg.

: I objected including a full X509 manual in the manual page of nbsvntool.
: The only person to actually start to help hashing out policies and more
: specific issues with this was Thor in the context of pkg_install. Sadly
: Thor has been busy lately.

  This isn't so much an issue of policies and usage, as of basic
description of the tool's operation and inputs.  From reading the
manual page, at least the follwing information is missing:


  Mention that keys and signatures are in X509 format, and which
variants are supported.


  List and description of supported commands.


  Expected format of the various input files, with pointer to complete
description and ways/tools to create them (openssl man pages, relevant
RFCs, . . .):

- certificate_chain_file
- certificate_file
- private_key


  Description of the key usages mentioned (ssl-server, ssl-client,
code, smime), and when one is supposed to use which.  Pointer to more
detailed information and exhaustive list (if there are more
possibilities).


  Syntax of the trust anchor.


  Description of the examples, and what each is trying to acomplish.



  Joerg, it would be great if you could fill in this information.
Don't worry too much about wording or formatting; once the information
is there, it's much easier for others (less clued) to improve upon it.

                                        yours,
                                        dillo