documentation incomplete?

[Michal Suchanek]

Hello,

Debian ships a GNUTLS pdf book in the package gnutls-doc.

In the foreword it says it aims to be self-contained.

I tried to implement gnutls in a program based on the manual (as
opposed to ripping a working code from another program as suggested in
some places on the net).

This was a terrible experience.

There is not much in the way of explanation of most return values that
contain any complex information, and the examples are grossly
incomplete.

First off I tried the example with anonymous authentication which of
course does not work. A notice that even services that do not require
client authentication (such as most https servers) typically don't
support anonymous authentication either would be quite helpful in the
manual. That client example is kind of useless because you need to
build a matching server to run it which is not included.

Second comes x509 client which should work in normal environments.

This somewhat differs for version 2 and 3 of the docs.

The v2 docs have a client with authentication and no verification and
a client with verification only, the v3 a client with both and a
separate verification function.

In the client samples the verification function helpfully prints out
some info on what is wrong with the certificate but does NOT reject it
when it is invalid.

The separate verification function is better in that regard and shows
that the INVALID flag means the cert is invalid and the rest is
informative, at least those used there. However, it does not show off
NOT_ACTIVATED or REVOKED, and there is no description of how these
flags fit together. Does REVOKED also imply invalid or should that be
checked separately?

Another issue is with checking hostname. The client samples note that
this is not real world example as hostname is checked only on the
first cert in chain yet the separate function happily does just that
as well.

Final problem is that I have a CA cert, not cert list. All the
examples deal with cert lists because it is easy, a function imports
all of it but fails to import a single cert. To import a single cert
it has to be loaded into memory, converted, and then loaded into the
credentials.

Sadly this has to be done using the undocumented gnutls_datum_t. The
structure is quite simple and examples using it abound yet I cannot
find its description and semantics when used as input or output in
gnutls.

Is there some other documentation I am missing?

Thanks

Michal