modified the gnutls_certificate_set_key* change

While the change was fully backwards compatible for applications that were
adding a single certificate, and applications that were checking for negative
errors codes, many applications do not. As this may cause incompatibility issues
with software properly utilizing the previously documented API, the change
is reverted, and applications need to explicitly enable a flag (GNUTLS_CERTIFICATE_API_V2)
in the credentials structure for the set_key functions to return an index.

2 files changed, 25 insertions, 6 deletions

diff --git a/doc/cha-gtls-app.texi b/doc/cha-gtls-app.texi
index 63843124c8..7ee6ce81ae 100644
--- a/doc/cha-gtls-app.texi
+++ b/doc/cha-gtls-app.texi
@@ -82,11 +82,23 @@ resumed one, and will share the same session ID with the previous one.
 @node Error handling
 @subsection Error handling
 
-There two types of @acronym{GnuTLS} functions. One type returns
-a boolean true (non-zero) or false (zero) value, which are set
-to return an unsigned integer type. The other type returns a
-signed integer type with zero indicating success and a negative
-value indicating failure. 
+There two types of @acronym{GnuTLS} functions. The first type returns
+a boolean value, true (non-zero) or false (zero) value; these functions
+are defined to return an unsigned integer type. The other type returns a
+signed integer type with zero (or a positive number) indicating
+success and a negative value indicating failure. For the latter
+type it is recommended to check for errors as following.
+@example
+    ret = gnutls_function();
+    if (ret < 0) @{
+        return -1;
+    @}
+@end example
+The above example checks for a failure condition rather than
+for explicit success (e.g., equality to zero). That has the advantage
+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}).
 
 For certain operations such as TLS handshake and TLS packet receive
 there is the notion of fatal and non-fatal error codes.
diff --git a/doc/examples/ex-serv-x509.c b/doc/examples/ex-serv-x509.c
index e67c9592b5..4bf1940b89 100644
--- a/doc/examples/ex-serv-x509.c
+++ b/doc/examples/ex-serv-x509.c
@@ -63,11 +63,16 @@ int main(void)
         CHECK(gnutls_certificate_set_x509_crl_file(x509_cred, CRLFILE,
                                                    GNUTLS_X509_FMT_PEM));
 
+        /* The following code sets the certificate key pair as well as, 
+         * an OCSP response which corresponds to it. It is possible
+         * to set multiple key-pairs and multiple OCSP status responses
+         * (the latter since 3.5.6). See the manual pages of the individual
+         * functions for more information.
+         */
         CHECK(gnutls_certificate_set_x509_key_file(x509_cred, CERTFILE,
                                                    KEYFILE,
                                                    GNUTLS_X509_FMT_PEM));
 
-        /* loads an OCSP status request if available */
         CHECK(gnutls_certificate_set_ocsp_status_request_file(x509_cred,
                                                               OCSP_STATUS_FILE,
                                                               0));
@@ -75,9 +80,11 @@ int main(void)
         CHECK(gnutls_priority_init(&priority_cache,
                                    "PERFORMANCE:%SERVER_PRECEDENCE", NULL));
 
+#if GNUTLS_VERSION_NUMBER >= 0x030506
         /* only available since GnuTLS 3.5.6, on previous versions see
          * gnutls_certificate_set_dh_params(). */
         gnutls_certificate_set_known_dh_params(x509_cred, GNUTLS_SEC_PARAM_MEDIUM);
+#endif
 
         /* Socket operations
          */