x509: clarify the calling convention of AIA callbacks

This updates the documentation of
gnutls_x509_trust_list_set_getissuer_function to explicitly mention
that the callback shall initialize the output arguments upon
successful call, even if the result is empty.

Signed-off-by: Daiki Ueno <ueno@gnu.org>

diff --git a/lib/cert-cred.c b/lib/cert-cred.c
index 49ba04eb4c89e2f37eecae9b11dda859f175ec02..eab0c947f77f73d30b8918376d151689717c5ee9 100644 (file)
--- a/lib/cert-cred.c
+++ b/lib/cert-cred.c
@@ -889,14 +889,17 @@ void gnutls_certificate_set_verify_function(
  * gnutls_x509_crt_get_authority_info_access() to get a URI from which
  * to attempt to download the missing issuer certificate, if available.
  *
- * On a successful call, the callback shall allocate the 'issuers' array with
- * gnutls_x509_crt_list_import2(). The ownership of both the array and the
- * elements is transferred to the caller and thus the application does not need
- * to maintain the memory after the call.
- *
- * The callback function should return 0 if the missing issuer certificate
- * for 'crt' was properly populated and added to the 'issuers', or non-zero
- * to continue the certificate list verification but with issuer as %NULL.
+ * On a successful call, the callback shall set '*issuers' and '*issuers_size'
+ * even if the result is empty; in that case '*issuers' will point to %NULL and
+ * '*issuers_size' will be 0.  Otherwise, the '*issuers' array shall be
+ * allocated using gnutls_x509_crt_list_import2(). The ownership of both the
+ * array and the elements is transferred to the caller and thus the application
+ * does not need to maintain the memory after the call.
+ *
+ * The callback function should return 0 if the attempt to retrieve the issuer
+ * certificates for 'crt' succeeded, or non-zero to indicate any error occurred
+ * during the attempt. In the latter case, '*issuers' and '*issuers_size' are
+ * not set.
  *
  * Since: 3.7.0
  **/