lib: Consistenly return sane results for all *_init()

After looking at gnutls_init(), I went and audited all other
*_init(gnutls_*_t) functions, to see if Bug #1414 applies in more
situations.  We had an inconsistent mix: some functions that went out
of their way to leave the parameter uninitialized on failure (such as
gnutls_x509_crt_init()); many that always left the parameter
initialized on failure (such as gnutls_x509_ext_ct_scts_init()), often
by relying on the gnutls_free() macro that assigns the pointer to NULL
after using the gnutls_free_function() callback pointer (such as
gnutls_pkcs11_obj_init()); but a few others that left stale pointers
on certain failures (such as gnutls_priority_init2()) or even which
used the wrong deallocation function (such as
gnutls_pkcs11_privkey_init()).

As with gnutls_init(), portable programs should either pre-initialize
memory to zero before calling _init() if they plan to unconditionally
call _deinit() (safe for all but gnutls_pkcs11_privkey_init()), or
they should avoid calling _deinit() if _init() failed.  But since we
can't force all existing clients to change, it is safest if we
unconditionally and consistently initialize the client's memory before
ALL failure paths.

Rather than try to adjust documentation of each *_init() function
(including those not needing a change), I instead generalized
documentation into the manual.

Signed-off-by: Eric Blake <eblake@redhat.com>

1 files changed, 16 insertions, 0 deletions

diff --git a/doc/cha-gtls-app.texi b/doc/cha-gtls-app.texi
index e0e971aea0..3547544e75 100644
--- a/doc/cha-gtls-app.texi
+++ b/doc/cha-gtls-app.texi
@@ -100,6 +100,22 @@ that future extensions of the API can be extended to provide
 additional information via positive returned values (see for example
 @funcref{gnutls_certificate_set_x509_key_file}).
 
+In @acronym{GnuTLS}, many objects are represented as opaque types that
+are initialized by passing an address to storage of that type to a
+pointer parameter of a function name @code{gnutls_@var{obj}_init}, and
+which have a counterpart function @code{gnutls_@var{obj}_deinit}.  It
+is safe, but not mandatory, to pre-initialize the opaque storage to
+contain all zeroes (such as by using @code{calloc()} or
+@code{memset()}).  If the initializer succeeds, the storage must be
+passed to the counterpart deinitializer when the object is no longer
+in use to avoid memory leaks.  As of version 3.8.0, if the initializer
+function fails, it is safe, but not mandatory, to call the counterpart
+deinitializer, regardless of whether the storage was pre-initialized.
+However, this was not guaranteed in earlier versions; for maximum
+portability to older library versions, callers should either
+pre-initialize the storage to zero before initialization or refrain
+from calling the deinitializer if the initializer fails.
+
 For certain operations such as TLS handshake and TLS packet receive
 there is the notion of fatal and non-fatal error codes.
 Fatal errors terminate the TLS session immediately and further sends