gnutls_priority_init2(3)

1gnutls_priority_init2(3)            gnutls            gnutls_priority_init2(3)
2
3
4

NAME

6       gnutls_priority_init2 - API function
7

SYNOPSIS

9       #include <gnutls/gnutls.h>
10
11       int  gnutls_priority_init2(gnutls_priority_t  *  priority_cache,  const
12       char * priorities, const char ** err_pos, unsigned flags);
13

ARGUMENTS

15       gnutls_priority_t * priority_cache
16                   is a gnutls_priority_t type.
17
18       const char * priorities
19                   is a string describing priorities (may be NULL)
20
21       const char ** err_pos
22                   In case of an error this will  have  the  position  in  the
23                   string the error occurred
24
25       unsigned flags
26                   zero or GNUTLS_PRIORITY_INIT_DEF_APPEND
27

DESCRIPTION

29       Sets  priorities  for the ciphers, key exchange methods, and macs.  The
30       priority_cache should be deinitialized using gnutls_priority_deinit().
31
32       The priorities option allows you to specify a colon separated  list  of
33       the  cipher priorities to enable.  Some keywords are defined to provide
34       quick access to common preferences.
35
36       When  flags is set to GNUTLS_PRIORITY_INIT_DEF_APPEND then the  priori‐
37       ties specified will be appended to the default options.
38
39       Unless  there  is  a  special need, use the "NORMAL" keyword to apply a
40       reasonable security level, or "NORMAL:%COMPAT" for compatibility.
41
42       "PERFORMANCE" means all the "secure" ciphersuites are enabled,  limited
43       to 128 bit ciphers and sorted by terms of speed performance.
44
45       "LEGACY"  the  NORMAL settings for GnuTLS 3.2.x or earlier. There is no
46       verification profile set, and the allowed DH primes are considered weak
47       today.
48
49       "NORMAL"  means  all "secure" ciphersuites. The 256-bit ciphers are in‐
50       cluded as a fallback only.  The ciphers are sorted by security margin.
51
52       "PFS" means all "secure" ciphersuites that support perfect forward  se‐
53       crecy.   The  256-bit ciphers are included as a fallback only.  The ci‐
54       phers are sorted by security margin.
55
56       "SECURE128" means all "secure" ciphersuites of security  level  128-bit
57       or more.
58
59       "SECURE192"  means  all "secure" ciphersuites of security level 192-bit
60       or more.
61
62       "SUITEB128" means all the NSA SuiteB ciphersuites with  security  level
63       of 128.
64
65       "SUITEB192"  means  all the NSA SuiteB ciphersuites with security level
66       of 192.
67
68       "NONE" means nothing is enabled.  This disables  everything,  including
69       protocols.
70
71       "@KEYWORD1,KEYWORD2,..."  The  system  administrator  imposed settings.
72       The provided keyword(s) will be expanded from a configuration-time pro‐
73       vided  file - default is: /etc/gnutls/config.  Any attributes that fol‐
74       low it, will be appended to the expanded string. If  multiple  keywords
75       are  provided,  separated by commas, then the first keyword that exists
76       in the configuration file will be used. At least one  of  the  keywords
77       must  exist, or this function will return an error. Typical usage would
78       be to specify an application specified keyword first, followed by "SYS‐
79       TEM" as a default fallback. e.g., " LIBVIRT ,SYSTEM:!-VERS-SSL3.0" will
80       first try to find a config file entry matching "LIBVIRT", but  if  that
81       does  not  exist  will use the entry for "SYSTEM". If "SYSTEM" does not
82       exist either, an error will be returned. In all cases, the SSL3.0  pro‐
83       tocol will be disabled. The system priority file entries should be for‐
84       matted as "KEYWORD=VALUE", e.g., "SYSTEM=NORMAL:+ARCFOUR-128".
85
86       Special keywords are "!", "-" and "+".  "!" or "-" appended with an al‐
87       gorithm  will  remove  this  algorithm.  "+" appended with an algorithm
88       will add this algorithm.
89
90       Check the GnuTLS manual section "Priority strings" for detailed  infor‐
91       mation.
92

EXAMPLES

94       "NONE:+VERS-TLS-ALL:+MAC-ALL:+RSA:+AES-128-CBC:+SIGN-ALL:+COMP-NULL"
95
96       "NORMAL:+ARCFOUR-128" means normal ciphers plus ARCFOUR-128.
97
98       "SECURE128:-VERS-SSL3.0"  means  that  only  secure ciphers are and en‐
99       abled, SSL3.0 is disabled.
100
101       "NONE:+VERS-TLS-ALL:+AES-128-CBC:+RSA:+SHA1:+COMP-NULL:+SIGN-RSA-SHA1",
102
103       "NONE:+VERS-TLS-ALL:+AES-128-CBC:+ECDHE-RSA:+SHA1:+COMP-NULL:+SIGN-RSA-SHA1:+CURVE-SECP256R1",
104
105       "SECURE256:+SECURE128",
106
107       Note that "NORMAL:%COMPAT" is the most compatible mode.
108
109       A  NULL   priorities string indicates the default priorities to be used
110       (this is available since GnuTLS 3.3.0).
111

RETURNS

113       On syntax error GNUTLS_E_INVALID_REQUEST is returned,  GNUTLS_E_SUCCESS
114       on success, or an error code.
115

SINCE

117       3.6.3
118

REPORTING BUGS

120       Report bugs to <bugs@gnutls.org>.
121       Home page: https://www.gnutls.org
122
123

COPYRIGHT

125       Copyright © 2001-2023 Free Software Foundation, Inc., and others.
126       Copying  and  distribution  of this file, with or without modification,
127       are permitted in any medium without royalty provided the copyright  no‐
128       tice and this notice are preserved.
129