gnutls.h: introduced flag GNUTLS_EXT_FLAG_OVERRIDE_INTERNAL [ci skip]

This flag is expected to be used by applications which handle
custom extensions that are not currently supported in gnutls, but
support for them may be added in the future.

Signed-off-by: Nikos Mavrogiannopoulos <nmav@gnutls.org>

2 files changed, 23 insertions, 7 deletions

diff --git a/lib/extensions.c b/lib/extensions.c
index 3b20e02e29..a42c733615 100644
--- a/lib/extensions.c
+++ b/lib/extensions.c
@@ -850,11 +850,16 @@ gnutls_ext_register(const char *name, int type, gnutls_ext_parse_type_t parse_ty
  * @deinit_func: a function deinitialize any private data
  * @pack_func: a function which serializes the extension's private data (used on session packing for resumption)
  * @unpack_func: a function which will deserialize the extension's private data
- * @flags: must be zero
+ * @flags: must be zero or flags from %gnutls_ext_flags_t
  *
  * This function will register a new extension type. The extension will be
  * only usable within the registered session. If the extension type
- * is already registered then %GNUTLS_E_ALREADY_REGISTERED will be returned.
+ * is already registered then %GNUTLS_E_ALREADY_REGISTERED will be returned,
+ * unless the flag %GNUTLS_EXT_FLAG_OVERRIDE_INTERNAL is specified. The latter
+ * flag when specified can be used to override certain extensions introduced
+ * after 3.6.0. It is expected to be used by applications which handle
+ * custom extensions that are not currently supported in GnuTLS, but direct
+ * support for them may be added in the future.
  *
  * Each registered extension can store temporary data into the gnutls_session_t
  * structure using gnutls_ext_set_data(), and they can be retrieved using
@@ -875,6 +880,7 @@ gnutls_session_ext_register(gnutls_session_t session,
 	extension_entry_st *exts;
 	unsigned i;
 
+	/* FIXME: handle GNUTLS_EXT_FLAG_OVERRIDE_INTERNAL for new exts */
 	for (i = 0; extfunc[i] != NULL; i++) {
 		if (extfunc[i]->type == type)
 			return gnutls_assert_val(GNUTLS_E_ALREADY_REGISTERED);
diff --git a/lib/includes/gnutls/gnutls.h.in b/lib/includes/gnutls/gnutls.h.in
index 289be64fc0..d7eec43d31 100644
--- a/lib/includes/gnutls/gnutls.h.in
+++ b/lib/includes/gnutls/gnutls.h.in
@@ -2579,9 +2579,9 @@ typedef int (*gnutls_ext_unpack_func) (gnutls_buffer_t packed_data,
  * @GNUTLS_EXT_TLS: TLS-internal extension.
  * @GNUTLS_EXT_MANDATORY: Extension parsed even if resuming (or extensions are disabled).
  *
- * Enumeration of different TLS extension types.  This flag
- * indicates for an extension whether it is useful to application
- * level or TLS level only.  This is (only) used to parse the
+ * Enumeration of different TLS extension types.  This type is
+ * to indicate whether an extension is useful to application
+ * level or TLS level only.  This is used to parse the
  * application level extensions before the "client_hello" callback
  * is called.
  */
@@ -2593,8 +2593,18 @@ typedef enum {
   GNUTLS_EXT_NONE = 4
 } gnutls_ext_parse_type_t;
 
-	/* Register a custom tls extension
-	 */
+/**
+ * gnutls_ext_flags_t:
+ * @GNUTLS_EXT_FLAG_OVERRIDE_INTERNAL: If specified the extension registered will override the internal; this does not work with extensions existing prior to 3.6.0.
+ *
+ * Enumeration of different TLS extension registration flags.
+ */
+typedef enum {
+  GNUTLS_EXT_FLAG_OVERRIDE_INTERNAL = 1
+} gnutls_ext_flags_t;
+
+/* Register a custom tls extension
+ */
 int gnutls_ext_register(const char *name, int type, gnutls_ext_parse_type_t parse_type,
 				gnutls_ext_recv_func recv_func, gnutls_ext_send_func send_func, 
 				gnutls_ext_deinit_data_func deinit_func, gnutls_ext_pack_func pack_func,