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/default-priorities.    Any
75       attributes  that follow it, will be appended to the expanded string. If
76       multiple keywords are provided, separated by  commas,  then  the  first
77       keyword  that  exists  in the configuration file will be used. At least
78       one of the keywords must exist, or this function will return an  error.
79       Typical  usage  would  be  to  specify an application specified keyword
80       first, followed by "SYSTEM" as a  default  fallback.  e.g.,  "  LIBVIRT
81       ,SYSTEM:!-VERS-SSL3.0"  will  first  try  to  find  a config file entry
82       matching "LIBVIRT", but if that does not exist will use the  entry  for
83       "SYSTEM". If "SYSTEM" does not exist either, an error will be returned.
84       In all cases, the SSL3.0 protocol will be disabled. The system priority
85       file entries should be formatted as "KEYWORD=VALUE", e.g., "SYSTEM=NOR‐
86       MAL:+ARCFOUR-128".
87
88       Special keywords are "!", "-" and "+".  "!" or  "-"  appended  with  an
89       algorithm  will  remove this algorithm.  "+" appended with an algorithm
90       will add this algorithm.
91
92       Check the GnuTLS manual section "Priority strings" for detailed  infor‐
93       mation.
94

EXAMPLES

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

RETURNS

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

SINCE

119       3.6.3
120

REPORTING BUGS

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

COPYRIGHT

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