gnutls_priority_init2,gnutls_set_default_priority_append: introduced

This allows enhancing the default priority with additional
options, allowing an application to introduce stricter (or weaker)
settings without requiring it to override all settings.

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

5 files changed, 40 insertions, 16 deletions

diff --git a/doc/cha-gtls-app.texi b/doc/cha-gtls-app.texi
index 59b448547c..f6710a0a16 100644
--- a/doc/cha-gtls-app.texi
+++ b/doc/cha-gtls-app.texi
@@ -1071,7 +1071,8 @@ algorithms and options in a compact, easy-to-use format. These
 strings are intended as a user-specified override of the library defaults.
 
 That is, we recommend applications using the default settings
-(c.f. @funcref{gnutls_set_default_priority}), and provide the user 
+(c.f. @funcref{gnutls_set_default_priority} or
+@funcref{gnutls_set_default_priority_append}), and provide the user 
 with access to priority strings for overriding the default behavior,
 on configuration files, or other UI. Following such a principle,
 makes the GnuTLS library as the default settings provider. That is
@@ -1079,7 +1080,7 @@ necessary and a good practice, because TLS protocol hardening and
 phasing out of legacy algorithms, is easier to co-ordinate when happens
 in a single library.
 
-@showfuncB{gnutls_set_default_priority,gnutls_priority_set_direct}
+@showfuncC{gnutls_set_default_priority,gnutls_set_default_priority_append,gnutls_priority_set_direct}
 
 The priority string translation to the internal GnuTLS form requires
 processing and the generated internal form also occupies some memory.
@@ -1088,7 +1089,7 @@ and share the generated data across sessions. The following functions
 allow the generation of a "priority cache" and the sharing of it across
 sessions.
 
-@showfuncC{gnutls_priority_init,gnutls_priority_set,gnutls_priority_deinit}
+@showfuncD{gnutls_priority_init2,gnutls_priority_init,gnutls_priority_set,gnutls_priority_deinit}
 
 @subheading Using Priority Strings
 
diff --git a/doc/examples/ex-client-psk.c b/doc/examples/ex-client-psk.c
index 5658cb0ce0..4b393d877f 100644
--- a/doc/examples/ex-client-psk.c
+++ b/doc/examples/ex-client-psk.c
@@ -34,6 +34,11 @@ int main(void)
         gnutls_psk_client_credentials_t pskcred;
         const gnutls_datum_t key = { (void *) "DEADBEEF", 8 };
 
+        if (gnutls_check_version("3.6.3") == NULL) {
+                fprintf(stderr, "GnuTLS 3.6.3 or later is required for this example\n");
+                exit(1);
+        }
+
         CHECK(gnutls_global_init());
 
         CHECK(gnutls_psk_allocate_client_credentials(&pskcred));
@@ -44,11 +49,14 @@ int main(void)
          */
         CHECK(gnutls_init(&session, GNUTLS_CLIENT));
 
-        /* Use default priorities */
         ret =
-            gnutls_priority_set_direct(session,
-                                       "PERFORMANCE:+ECDHE-PSK:+DHE-PSK:+PSK",
-                                       &err);
+            gnutls_set_default_priority_append(session,
+                                         "-KX-ALL:+ECDHE-PSK:+DHE-PSK:+PSK",
+                                         &err, 0);
+
+        /* Alternative for pre-3.6.3 versions:
+         * gnutls_priority_set_direct(session, "NORMAL:+ECDHE-PSK:+DHE-PSK:+PSK", &err)
+         */
         if (ret < 0) {
                 if (ret == GNUTLS_E_INVALID_REQUEST) {
                         fprintf(stderr, "Syntax error at: %s\n", err);
diff --git a/doc/examples/ex-serv-dtls.c b/doc/examples/ex-serv-dtls.c
index 23b51a1781..40b4f4728f 100644
--- a/doc/examples/ex-serv-dtls.c
+++ b/doc/examples/ex-serv-dtls.c
@@ -88,9 +88,14 @@ int main(void)
 
         gnutls_certificate_set_known_dh_params(x509_cred, GNUTLS_SEC_PARAM_MEDIUM);
 
-        gnutls_priority_init(&priority_cache,
-                             "PERFORMANCE:-VERS-TLS-ALL:+VERS-DTLS1.0:%SERVER_PRECEDENCE",
-                             NULL);
+        /* pre-3.6.3 equivalent:
+         * gnutls_priority_init(&priority_cache,
+         *                      "NORMAL:-VERS-TLS-ALL:+VERS-DTLS1.0:%SERVER_PRECEDENCE",
+         *                      NULL);
+         */
+        gnutls_priority_init2(&priority_cache,
+                              "%SERVER_PRECEDENCE",
+                              NULL, GNUTLS_PRIORITY_INIT_DEF_APPEND);
 
         gnutls_key_generate(&cookie_key, GNUTLS_COOKIE_KEY_SIZE);
 
diff --git a/doc/examples/ex-serv-psk.c b/doc/examples/ex-serv-psk.c
index 26aad02f47..4c469819be 100644
--- a/doc/examples/ex-serv-psk.c
+++ b/doc/examples/ex-serv-psk.c
@@ -79,9 +79,14 @@ int main(void)
         gnutls_psk_allocate_server_credentials(&psk_cred);
         gnutls_psk_set_server_credentials_function(psk_cred, pskfunc);
 
-        gnutls_priority_init(&priority_cache,
-                             "NORMAL:+PSK:+ECDHE-PSK:+DHE-PSK",
-                             NULL);
+        /* pre-3.6.3 equivalent:
+         * gnutls_priority_init(&priority_cache,
+         *                      "NORMAL:+PSK:+ECDHE-PSK:+DHE-PSK",
+         *                      NULL);
+         */
+        gnutls_priority_init2(&priority_cache,
+                              "+ECDHE-PSK:+DHE-PSK:+PSK",
+                              NULL, GNUTLS_PRIORITY_INIT_DEF_APPEND);
 
         gnutls_certificate_set_known_dh_params(x509_cred, GNUTLS_SEC_PARAM_MEDIUM);
 
diff --git a/doc/examples/ex-serv-x509.c b/doc/examples/ex-serv-x509.c
index caf2a0c120..c2545a6688 100644
--- a/doc/examples/ex-serv-x509.c
+++ b/doc/examples/ex-serv-x509.c
@@ -77,11 +77,16 @@ int main(void)
                                                               OCSP_STATUS_FILE,
                                                               0));
 
-        /* One could use specific priority strings such as "PERFORMANCE:%SERVER_PRECEDENCE"
-         * especially if they are read from a configuration file; otherwise, it
-         * is recommended to use the defaults as shown here. */
         CHECK(gnutls_priority_init(&priority_cache, NULL, NULL));
 
+        /* Instead of the default options as shown above one could specify
+         * additional options such as server precedence in ciphersuite selection
+         * as follows:
+         * gnutls_priority_init2(&priority_cache,
+         *                       "%SERVER_PRECEDENCE",
+         *                       NULL, GNUTLS_PRIORITY_INIT_DEF_APPEND);
+	 */
+
 #if GNUTLS_VERSION_NUMBER >= 0x030506
         /* only available since GnuTLS 3.5.6, on previous versions see
          * gnutls_certificate_set_dh_params(). */