documentation incomplete?

[Nikos Mavrogiannopoulos]

On 05/24/2012 08:07 PM, Michal Suchanek wrote:

Hello Michal,
 Thank you for the comments.

 
> There is not much in the way of explanation of most return values that
> contain any complex information,


Could you pinpoint those?

> and the examples are grossly incomplete.

Do your comments below show the parts of the examples you consider
incomplete or you had other issues as well?  Note, however, that
examples are just that and cannot be complete applications.

> 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.


I've added some text in the Anonymous authentication chapter to make
this more clear.

> Second comes x509 client which should work in normal environments.
> This somewhat differs for version 2 and 3 of the docs.


The documentation is continuously updated based on comments and new
library features.

> 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.


What does it mean reject in an example application? I'd expect that
someone would customize it to his needs, but you may have a point for
someone who blindly copies it. I'll make it return an error.

> 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?


GNUTLS_CERT_INVALID is always set on a verification error. I've
committed an update in the documentation to make that explicit.

> 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.


The comment is a mistake. It is leftover from a previous version of this
function. Thanks for pointing out.

> 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.


I don't understand the issue. Could you explain further?
If you are referring to gnutls_certificate_set_x509_trust_file(), it
can read PEM or DER formatted files.

> 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.

That's an omission. I've added some small text on that.

> Is there some other documentation I am missing?

Unfortunately none that I know of.


regards,
Nikos