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_prioritity_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
50       included as a fallback only.  The ciphers are sorted by  security  mar‐
51       gin.
52
53       "PFS"  means  all  "secure"  ciphersuites  that support perfect forward
54       secrecy.  The 256-bit ciphers are included as  a  fallback  only.   The
55       ciphers are sorted by security margin.
56
57       "SECURE128"  means  all "secure" ciphersuites of security level 128-bit
58       or more.
59
60       "SECURE192" means all "secure" ciphersuites of security  level  192-bit
61       or more.
62
63       "SUITEB128"  means  all the NSA SuiteB ciphersuites with security level
64       of 128.
65
66       "SUITEB192" means all the NSA SuiteB ciphersuites with  security  level
67       of 192.
68
69       "NONE"  means  nothing is enabled.  This disables everything, including
70       protocols.
71
72       "@KEYWORD1,KEYWORD2,..." The  system  administrator  imposed  settings.
73       The provided keyword(s) will be expanded from a configuration-time pro‐
74       vided file - default is: /etc/gnutls/config.  Any attributes that  fol‐
75       low  it,  will be appended to the expanded string. If multiple keywords
76       are provided, separated by commas, then the first keyword  that  exists
77       in  the  configuration  file will be used. At least one of the keywords
78       must exist, or this function will return an error. Typical usage  would
79       be to specify an application specified keyword first, followed by "SYS‐
80       TEM" as a default fallback. e.g., " LIBVIRT ,SYSTEM:!-VERS-SSL3.0" will
81       first  try  to find a config file entry matching "LIBVIRT", but if that
82       does not exist will use the entry for "SYSTEM". If  "SYSTEM"  does  not
83       exist  either, an error will be returned. In all cases, the SSL3.0 pro‐
84       tocol will be disabled. The system priority file entries should be for‐
85       matted as "KEYWORD=VALUE", e.g., "SYSTEM=NORMAL:+ARCFOUR-128".
86
87       Special  keywords  are  "!",  "-" and "+".  "!" or "-" appended with an
88       algorithm will remove this algorithm.  "+" appended with  an  algorithm
89       will add this algorithm.
90
91       Check  the GnuTLS manual section "Priority strings" for detailed infor‐
92       mation.
93

EXAMPLES

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

RETURNS

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

SINCE

118       3.6.3
119

REPORTING BUGS

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

COPYRIGHT

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