[Pkg-gnutls-maint] Bug#416717: libgcrypt11-doc: not happy with documentation

[Jason Dorje Short]

Package: libgcrypt11-doc
Version: 1.2.3-2
Severity: normal


I am, in general, rather dissatisfied with the library's documentation.

There is a one-line description of each function, but no description of how
things actually work or are intended to be used.

My immediate concern is with the random number functions.

* If I use gcry_randomize, do I need to use gcry_random_add_bytes within
  the same program?
* If I use gcry_randomize too much and run out of entropy, what happens? Will
  it block?  Or do I get sucky random numbers?
* How much less random are the values returned by gcry_create_nonce?  For
  what applications might I use them instead of gcry_randomize?  And if
  gcry_randomize never blocks, why shouldn't I always use it?

By testing a few things it appears as though gcry_randomize always accesses
/dev/urandom for its entropy.  Thus on my system it never blocks but may
sometimes give less-secure random numbers - even if GCRY_VERY_STRONG_RANDOM is
used!  But I don't know if this is only the case on my platform; maybe on
a different platform it might block until more entropy is available?  Without
documentation guaranteeing the behavior, how can I trust this function?

-- System Information:
Debian Release: 4.0
  APT prefers unstable
  APT policy: (500, 'unstable')
Architecture: i386 (i686)
Shell:  /bin/sh linked to /bin/bash
Kernel: Linux 2.6.18-4-686
Locale: LANG=C, LC_CTYPE=C (charmap=ANSI_X3.4-1968)

-- no debconf information