Added a small example on how to use the certificate selection callback in client side.

5 files changed, 57 insertions, 2 deletions

diff --git a/doc/examples/Makefile.am b/doc/examples/Makefile.am
index b3597d023f..6fc8dcca04 100644
--- a/doc/examples/Makefile.am
+++ b/doc/examples/Makefile.am
@@ -1,3 +1,3 @@
 EXTRA_DIST = ex-alert.c ex-client-resume.c ex-client-srp.c ex-client1.c \
 	ex-client2.c ex-info.c ex-rfc2818.c ex-serv-export.c ex-serv-pgp.c \
-	ex-serv-srp.c ex-serv1.c ex-pgp-keyserver.c
+	ex-serv-srp.c ex-serv1.c ex-pgp-keyserver.c ex-cert-select.c
diff --git a/doc/tex/Makefile.am b/doc/tex/Makefile.am
index 813e49dacf..dec2a362aa 100644
--- a/doc/tex/Makefile.am
+++ b/doc/tex/Makefile.am
@@ -7,7 +7,7 @@ EXTRA_DIST = gnutls.tex gnutls.ps \
 EXAMPLE_OBJECTS = ex-alert.tex ex-client-srp.tex ex-serv-export.tex \
 	ex-client1.tex ex-client2.tex ex-info.tex ex-rfc2818.tex \
 	ex-serv1.tex ex-client-resume.tex ex-serv-srp.tex \
-	ex-serv-pgp.tex ex-pgp-keyserver.tex
+	ex-serv-pgp.tex ex-pgp-keyserver.tex ex-cert-select.tex
 
 TEX_OBJECTS = gnutls.tex ../../lib/gnutls-api.tex fdl.tex ../../lib/x509/x509-api.tex \
 	macros.tex cover.tex ciphersuites.tex handshake.tex translayer.tex \
diff --git a/doc/tex/ex-cert-select.tex b/doc/tex/ex-cert-select.tex
new file mode 100644
index 0000000000..3be546bde8
--- /dev/null
+++ b/doc/tex/ex-cert-select.tex
@@ -0,0 +1,45 @@
+\begin{verbatim}
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <gnutls/gnutls.h>
+#include <gnutls/x509.h>
+
+/* This callback should be associated with a session by calling
+ * gnutls_certificate_client_set_select_function( session, cert_callback),
+ * before a handshake.
+ */
+
+static int cert_callback(gnutls_session session,
+			 const gnutls_datum * client_certs, int client_certs_num,
+			 const gnutls_datum * req_ca_rdn, int nreqs)
+{
+   char issuer_dn[256];
+   int len, i, ret;
+
+   /* Print the server's trusted CAs
+    */
+   if (nreqs > 0)
+      printf("- Server's trusted authorities:\n");
+   else
+      printf("- Server did not send us any trusted authorities names.\n");
+
+   /* print the names (if any) */
+   for (i = 0; i < nreqs; i++) {
+      len = sizeof(issuer_dn);
+      ret = gnutls_x509_rdn_get(&req_ca_rdn[i], issuer_dn, &len);
+      if (ret >= 0) {
+	 printf("   [%d]: ", i);
+	 printf("%s\n", issuer_dn);
+      }
+   }
+
+   /* Select a certificate from the client_certs and return it's
+    * index.
+    */
+
+   return -1;
+
+}
+
+\end{verbatim}
diff --git a/doc/tex/ex-info.tex b/doc/tex/ex-info.tex
index 0616d22df4..1dcfb6508b 100644
--- a/doc/tex/ex-info.tex
+++ b/doc/tex/ex-info.tex
@@ -3,6 +3,7 @@
 #include <stdio.h>
 #include <stdlib.h>
 #include <gnutls/gnutls.h>
+#include <gnutls/x509.h>
 
 static void print_x509_certificate_info(gnutls_session);
 
diff --git a/doc/tex/examples.tex b/doc/tex/examples.tex
index 4adbdbe254..aca1cdbacf 100644
--- a/doc/tex/examples.tex
+++ b/doc/tex/examples.tex
@@ -35,6 +35,15 @@ This function should be called after a successful
 
 \input{ex-info}
 
+\subsection{Using a callback to select the certificate to use}
+There are cases where a client holds several certificate and key pairs,
+and may want to choose the appropriate to send in the current session.
+The following example demonstrates the use of the certificate selection callback
+to assist in this purpose.
+\par
+
+\input{ex-cert-select}
+
 
 \subsection{Client with Resume capability example}
 \label{resume-example}