[gnutls-dev] External signing API

Simon Josefsson simon at josefsson.org
Sat Aug 11 15:01:21 CEST 2007 

"Alon Bar-Lev" <alon.barlev at gmail.com> writes:

> On 8/10/07, Simon Josefsson <simon at josefsson.org> wrote:
>> Hi!  The userdata is passed to the callback, see the prototype.  Do you
>> think another function is needed anyway?
>
> Yes.
> During cleanup the user data should be accessible in order to
> optionally free it.

Ah, makes sense.  Added.  I also added some new error codes, see patches
below.

I've git-push'ed the changes, so tomorrow's daily snapshot should
contain this stuff (I can't trigger generation of a new daily snapshot
right now).

/Simon

commit 3d5e85faf9d1dbb3cf2d58f9accfc8d2db917016
Author: Simon Josefsson <simon at josefsson.org>
Date:   Sat Aug 11 14:34:15 2007 +0200

    New errors GNUTLS_E_APPLICATION_ERROR_MIN..GNUTLS_E_APPLICATION_ERROR_MAX.

diff --git a/NEWS b/NEWS
index e31fcbf..f00212d 100644
--- a/NEWS
+++ b/NEWS
@@ -17,6 +17,16 @@ for comments and testing.
 See tests/x509self.c and tests/x509signself.c.  The latter also tests
 the new external signing callback interface.
 
+** New errors GNUTLS_E_APPLICATION_ERROR_MIN..GNUTLS_E_APPLICATION_ERROR_MAX.
+These two actually describe the outer limits of a range of error codes
+reserved to the application.  All of the errors are treated as fatal
+by the library (it has to since it doesn't know the semantics of the
+error codes).  This can be useful in callbacks, to signal some
+application-specific error condition, which will usually eventually
+cause some gnutls API to return the same error code as the callback,
+which then can be inspected by the application.  Note that error codes
+are negative.
+
 ** gnutls_set_default_priority now disable TLS 1.2 by default.
 The RFC is not released yet, and we're approaching a major release so
 let's not enable it just yet.
@@ -37,6 +47,8 @@ gnutls_sign_func: ADD, new type for sign callback.
 gnutls_sign_callback_set: ADD, new function to set sign callback.
 gnutls_sign_callback_get: ADD, new function to retrieve sign callback.
 gnutls_x509_privkey_sign_hash: ADD, new function useful in sign callback.
+GNUTLS_E_APPLICATION_ERROR_MIN,
+GNUTLS_E_APPLICATION_ERROR_MAX: ADD, new CPP #defines for error codes.
 
 * Version 1.7.16 (released 2007-08-07)
 
diff --git a/includes/gnutls/gnutls.h.in b/includes/gnutls/gnutls.h.in
index 9663092..61b0b4d 100644
--- a/includes/gnutls/gnutls.h.in
+++ b/includes/gnutls/gnutls.h.in
@@ -1262,6 +1262,9 @@ extern "C"
 
 #define GNUTLS_E_UNIMPLEMENTED_FEATURE -1250
 
+#define GNUTLS_E_APPLICATION_ERROR_MAX -65000
+#define GNUTLS_E_APPLICATION_ERROR_MIN -65500
+
 #ifdef __cplusplus
 }
 #endif

commit cfa77b1f37a94585bea9aea81db7545a9c4fa7eb
Author: Simon Josefsson <simon at josefsson.org>
Date:   Sat Aug 11 14:23:07 2007 +0200

    Add gnutls_sign_callback_get.
    
    	* includes/gnutls/gnutls.h.in (gnutls_sign_callback_get): Add.
    
    	* lib/gnutls_cert.c (gnutls_sign_callback_set): Move here from
    	gnutls_sig.c.  Doc fix.
    	(gnutls_sign_callback_get): New function.
    
    	* lib/gnutls_sig.c (gnutls_sign_callback_set): Removed.

diff --git a/NEWS b/NEWS
index 9f39fd1..e31fcbf 100644
--- a/NEWS
+++ b/NEWS
@@ -7,8 +7,11 @@ See the end for copying conditions.
 
 ** New functions to perform external signing.
 Set the signing callback function (of the gnutls_sign_func prototype)
-using gnutls_sign_callback_set.  In the callback, you may find the new
-function gnutls_x509_privkey_sign_hash useful.
+using the gnutls_sign_callback_set function.  In the callback, you may
+find the new function gnutls_x509_privkey_sign_hash useful.  A new
+function gnutls_sign_callback_get is also added, to retrieve the
+function pointer.  Thanks to "Alon Bar-Lev" <alon.barlev at gmail.com>
+for comments and testing.
 
 ** New self test of client and server authenticated X.509 TLS sessions.
 See tests/x509self.c and tests/x509signself.c.  The latter also tests
@@ -32,6 +35,7 @@ Thanks to Jakub Bogusz <qboosh at pld-linux.org> and Daniel Nylander
 ** API and ABI modifications:
 gnutls_sign_func: ADD, new type for sign callback.
 gnutls_sign_callback_set: ADD, new function to set sign callback.
+gnutls_sign_callback_get: ADD, new function to retrieve sign callback.
 gnutls_x509_privkey_sign_hash: ADD, new function useful in sign callback.
 
 * Version 1.7.16 (released 2007-08-07)
diff --git a/includes/gnutls/gnutls.h.in b/includes/gnutls/gnutls.h.in
index 8f1e364..9663092 100644
--- a/includes/gnutls/gnutls.h.in
+++ b/includes/gnutls/gnutls.h.in
@@ -1058,6 +1058,9 @@ extern "C"
   void gnutls_sign_callback_set (gnutls_session_t session,
 				 gnutls_sign_func sign_func,
 				 void *userdata);
+  gnutls_sign_func
+  gnutls_sign_callback_get (gnutls_session_t session,
+			    void **userdata);
 
   /* These are set on the credentials structure.
    */
diff --git a/lib/gnutls_cert.c b/lib/gnutls_cert.c
index cc97842..23a0f3d 100644
--- a/lib/gnutls_cert.c
+++ b/lib/gnutls_cert.c
@@ -868,3 +868,50 @@ _gnutls_gcert_deinit (gnutls_cert * cert)
 
   _gnutls_free_datum (&cert->raw);
 }
+
+/**
+ * gnutls_sign_callback_set:
+ * @session: is a gnutls session
+ * @sign_func: function pointer to application's sign callback.
+ * @userdata: void pointer that will be passed to sign callback.
+ *
+ * Set the callback function.  The function must have this prototype:
+ *
+ * typedef int (*gnutls_sign_func) (gnutls_session_t session,
+ *                                  void *userdata,
+ *                                  gnutls_certificate_type_t cert_type,
+ *                                  gnutls_datum_t cert,
+ *                                  const gnutls_datum_t hash,
+ *                                  gnutls_datum_t * signature);
+ *
+ * The @userdata parameter is passed to the @sign_func verbatim, and
+ * can be used to store application-specific data needed in the
+ * callback function.  See also gnutls_sign_callback_get().
+ **/
+void
+gnutls_sign_callback_set (gnutls_session_t session,
+			  gnutls_sign_func sign_func,
+			  void *userdata)
+{
+  session->internals.sign_func = sign_func;
+  session->internals.sign_func_userdata = userdata;
+}
+
+/**
+ * gnutls_sign_callback_get:
+ * @session: is a gnutls session
+ * @userdata: if non-%NULL, will be set to abstract callback pointer.
+ *
+ * Retrieve the callback function, and its userdata pointer.
+ *
+ * Return value: The function pointer set by
+ *   gnutls_sign_callback_set(), or if not set, %NULL.
+ **/
+gnutls_sign_func
+gnutls_sign_callback_get (gnutls_session_t session,
+			  void **userdata)
+{
+  if (userdata)
+    *userdata = session->internals.sign_func_userdata;
+  return session->internals.sign_func;
+}
diff --git a/lib/gnutls_sig.c b/lib/gnutls_sig.c
index 31db1cf..1358b76 100644
--- a/lib/gnutls_sig.c
+++ b/lib/gnutls_sig.c
@@ -291,34 +291,6 @@ _gnutls_tls_sign (gnutls_session_t session,
 		       pkey->params_size, hash_concat, signature);
 }
 
-/**
- * gnutls_sign_callback_set:
- * @session:
- * @sign_func:
- * @userdata:
- *
- * Set the callback function.  The function must have this prototype:
- *
- * typedef int (*gnutls_sign_func) (gnutls_session_t session,
- *                                  void *userdata,
- *                                  gnutls_certificate_type_t cert_type,
- *                                  gnutls_datum_t cert,
- *                                  const gnutls_datum_t hash,
- *                                  gnutls_datum_t * signature);
- *
- * The @userdata parameter is passed to the @sign_func verbatim, and
- * can be used to store application-specific data needed in the
- * callback function.
- **/
-void
-gnutls_sign_callback_set (gnutls_session_t session,
-			  gnutls_sign_func sign_func,
-			  void *userdata)
-{
-  session->internals.sign_func = sign_func;
-  session->internals.sign_func_userdata = userdata;
-}
-
 static int
 _gnutls_verify_sig (gnutls_cert * cert,
 		    const gnutls_datum_t * hash_concat,

More information about the Gnutls-devel mailing list