1CRYPTO-POLICIES(7)                                          CRYPTO-POLICIES(7)
2
3
4

NAME

6       crypto-policies - system-wide crypto policies overview
7

DESCRIPTION

9       The security of cryptographic components of the operating system does
10       not remain constant over time. Algorithms, such as cryptographic
11       hashing and encryption, typically have a lifetime, after which they are
12       considered either too risky to use or plain insecure. That means, we
13       need to phase out such algorithms from the default settings or
14       completely disable them if they could cause an irreparable problem.
15
16       While in the past the algorithms were not disabled in a consistent way
17       and different applications applied different policies, the system-wide
18       crypto-policies followed by the crypto core components allow
19       consistently deprecating and disabling algorithms system-wide.
20
21       Several preconfigured policies (DEFAULT, LEGACY, FUTURE, and FIPS) and
22       subpolicies are included in the crypto-policies(7) package. System
23       administrators or third-party vendors can define custom policies.
24
25       For rationale, see RFC 7457 for a list of attacks taking advantage of
26       legacy crypto algorithms.
27

COVERED APPLICATIONS

29       Crypto-policies apply to the configuration of the core cryptographic
30       subsystems, covering TLS, IKE, IPSec, DNSSec, and Kerberos protocols;
31       i.e., the supported secure communications protocols on the base
32       operating system.
33
34       Once an application runs in the operating system, it follows the
35       default or selected policy and refuses to fall back to algorithms and
36       protocols not within the policy, unless the user has explicitly
37       requested the application to do so. That is, the policy applies to the
38       default behavior of applications when running with the system-provided
39       configuration but the user can override it on an application-specific
40       basis.
41
42       The policies currently provide settings for these applications and
43       libraries:
44
45BIND DNS name server daemon (scopes: BIND, DNSSec)
46
47GnuTLS TLS library (scopes: GnuTLS, SSL, TLS)
48
49OpenJDK runtime environment (scopes: java-tls, SSL, TLS)
50
51Kerberos 5 library (scopes: krb5, Kerberos)
52
53Libreswan IPsec and IKE protocol implementation (scopes: libreswan,
54           IPSec, IKE)
55
56NSS TLS library (scopes: NSS, SSL, TLS)
57
58OpenSSH SSH2 protocol implementation (scopes: OpenSSH, SSH)
59
60OpenSSL TLS library (scopes: OpenSSL, SSL, TLS)
61
62libssh SSH2 protocol implementation (scopes: libssh, SSH)
63
64       Applications using the above libraries and tools are covered by the
65       cryptographic policies unless they are explicitly configured otherwise.
66

PROVIDED POLICIES

68       LEGACY
69           This policy ensures maximum compatibility with legacy systems; it
70           is less secure and it includes support for TLS 1.0, TLS 1.1, and
71           SSH2 protocols or later. The algorithms DSA and 3DES are allowed,
72           while RSA and Diffie-Hellman parameters are accepted if larger than
73           1024 bits. This policy provides at least 64-bit security.
74
75           •   MACs: all HMAC with SHA-1 or better + all modern MACs (Poly1305
76               etc.)
77
78           •   Curves: all prime >= 255 bits (including Bernstein curves)
79
80           •   Signature algorithms: with SHA1 hash or better (DSA allowed)
81
82TLS Ciphers: all available >= 112-bit key, >= 128-bit block
83               (including 3DES, excluding RC4)
84
85           •   Non-TLS Ciphers: same as TLS ciphers with added Camellia
86
87           •   Key exchange: ECDHE, RSA, DHE
88
89DH params size: >= 1024
90
91RSA keys size: >= 1024
92
93DSA params size: >= 1024
94
95TLS protocols: TLS >= 1.0, DTLS >= 1.0
96
97       DEFAULT
98           The DEFAULT policy is a reasonable default policy for today’s
99           standards. It allows the TLS 1.2, and TLS 1.3 protocols, as well as
100           IKEv2 and SSH2. The Diffie-Hellman parameters are accepted if they
101           are at least 2048 bits long. This policy provides at least 112-bit
102           security with the exception of allowing SHA-1 signatures in DNSSec
103           where they are still prevalent.
104
105           •   MACs: all HMAC with SHA-1 or better + all modern MACs (Poly1305
106               etc.)
107
108           •   Curves: all prime >= 255 bits (including Bernstein curves)
109
110           •   Signature algorithms: with SHA-224 hash or better (no DSA)
111
112TLS Ciphers: >= 128-bit key, >= 128-bit block (AES, ChaCha20,
113               including AES-CBC)
114
115           •   non-TLS Ciphers: as TLS Ciphers with added Camellia
116
117           •   key exchange: ECDHE, RSA, DHE (no DHE-DSS)
118
119DH params size: >= 2048
120
121RSA keys size: >= 2048
122
123TLS protocols: TLS >= 1.2, DTLS >= 1.2
124
125       NEXT
126           The NEXT policy is just an alias to the DEFAULT policy.
127
128       FUTURE
129           A conservative security policy that is believed to withstand any
130           near-term future attacks. This policy does not allow the use of
131           SHA-1 in signature algorithms. The policy also provides some (not
132           complete) preparation for post-quantum encryption support in form
133           of 256-bit symmetric encryption requirement. The RSA and
134           Diffie-Hellman parameters are accepted if larger than 3071 bits.
135           This policy provides at least 128-bit security.
136
137           •   MACs: all HMAC with SHA-256 or better + all modern MACs
138               (Poly1305 etc.)
139
140           •   Curves: all prime >= 255 bits (including Bernstein curves)
141
142           •   Signature algorithms: with SHA-256 hash or better (no DSA)
143
144TLS Ciphers: >= 256-bit key, >= 128-bit block, only
145               Authenticated Encryption (AE) ciphers
146
147           •   non-TLS Ciphers: same as TLS ciphers with added non AE ciphers
148               and Camellia
149
150           •   key exchange: ECDHE, DHE (no DHE-DSS, no RSA)
151
152DH params size: >= 3072
153
154RSA keys size: >= 3072
155
156TLS protocols: TLS >= 1.2, DTLS >= 1.2
157
158       FIPS
159           A policy to aid conformance to the FIPS 140-2 requirements. This
160           policy is used internally by the fips-mode-setup(8) tool which can
161           switch the system into the FIPS 140-2 mode. This policy provides at
162           least 112-bit security.
163
164           •   MACs: all HMAC with SHA1 or better
165
166           •   Curves: all prime >= 256 bits
167
168           •   Signature algorithms: with SHA-256 hash or better (no DSA)
169
170TLS Ciphers: >= 128-bit key, >= 128-bit block (AES, including
171               AES-CBC)
172
173           •   non-TLS Ciphers: same as TLS Ciphers
174
175           •   key exchange: ECDHE, DHE (no DHE-DSS, no RSA)
176
177DH params size: >= 2048
178
179RSA params size: >= 2048
180
181TLS protocols: TLS >= 1.2, DTLS >= 1.2
182
183       EMPTY
184           All cryptographic algorithms are disabled (used for debugging only,
185           do not use).
186

CRYPTO POLICY DEFINITION FORMAT

188       The crypto policy definition files have a simple syntax following an
189       INI file key = value syntax with these particular features:
190
191       •   Comments are indicated by # character. Everything on the line
192           following the character is ignored.
193
194       •   Backslash \ character followed immediately with the end-of-line
195           character indicates line continuation. The following line is
196           concatenated to the current line after the backslash and
197           end-of-line characters are removed.
198
199       •   Value types for integer options can be decimal integers (option =
200           1).
201
202       •   Multiple-choice options can be specified by setting them to a list
203           of values (option = value1 value2). This list can further be
204           altered by prepending/omitting/appending values (option = prepended
205           -omitted appended). A follow-up reassignment will reset the list.
206           The latter syntax cannot be combined with the former one in the
207           same directive. Setting an option to an empty list is possible with
208           option =.
209
210       •   Asterisk sign can be used for wildcard matching as a shortcut for
211           specifying multiple values when setting multiple-choice options.
212           Note that wildcard matching can lead to future updates implicitly
213           enabling algorithms not yet available in the current version. If
214           this is a concern, do not use wildcard-matching outside of
215           algorithm-omitting directives.
216
217       •   In order to limit the scope of the directive and make it affect
218           just some of the backends, the following extended syntax can be
219           used: option@scope = ..., option@{scope1,scope2,...} = ....
220           Negation of scopes is possible with option@!scope /
221           'option@{scope1,scope2,...}. Scope selectors are case-insensitive.
222
223       The available options are:
224
225mac: List of allowed MAC algorithms
226
227group: List of allowed groups or elliptic curves for key exchanges
228           for use with other protocols
229
230hash: List of allowed cryptographic hash (message digest)
231           algorithms
232
233sign: List of allowed signature algorithms
234
235cipher: List of allowed symmetric encryption algorithms (including
236           the modes) for use with other protocols
237
238key_exchange: List of allowed key exchange algorithms
239
240protocol: List of allowed TLS, DTLS and IKE protocol versions; mind
241           that some backends do not allow selectively disabling protocols
242           versions and only use the oldest version as the lower boundary.
243
244min_dh_size: Integer value of minimum number of bits of parameters
245           for DH key exchange
246
247min_dsa_size: Integer value of minimum number of bits for DSA keys
248
249min_rsa_size: Integer value of minimum number of bits for RSA keys
250
251sha1_in_certs: Value of 1 if SHA1 allowed in certificate
252           signatures, 0 otherwise (Applies to GnuTLS back end only.)
253
254arbitrary_dh_groups: Value of 1 if arbitrary group in
255           Diffie-Hellman is allowed, 0 otherwise
256
257ssh_certs: Value of 1 if OpenSSH certificate authentication is
258           allowed, 0 otherwise
259
260ssh_etm: Value of 1 if OpenSSH EtM (encrypt-then-mac) extension is
261           allowed, 0 otherwise
262
263       Full policy definition files have suffix .pol, subpolicy files have
264       suffix .pmod. Subpolicies do not have to have values set for all the
265       keys listed above.
266
267       The effective configuration of a policy with subpolicies applied is the
268       same as a configuration from a single policy obtained by concatenating
269       the policy and the subpolicies in question.
270
271       Policy file placement and naming:
272
273       The policy files shipped in packages are placed in
274       /usr/share/crypto-policies/policies and the subpolicies in
275       /usr/share/crypto-policies/policies/modules.
276
277       Locally configured policy files should be placed in
278       /etc/crypto-policies/policies and subpolicies in
279       /etc/crypto-policies/policies/modules.
280
281       The policy and subpolicy files must have names in upper-case except for
282       the .pol and .pmod suffix as the update-crypto-policies command always
283       converts the policy name to upper-case before searching for the policy
284       on the filesystem.
285

COMMANDS

287       update-crypto-policies(8)
288           This command manages the policies available to the various
289           cryptographic back ends and allows the system administrator to
290           change the active cryptographic policy.
291
292       fips-mode-setup(8)
293           This command allows the system administrator to enable, or disable
294           the system FIPS mode and also apply the FIPS cryptographic policy
295           which limits the allowed algorithms and protocols to these allowed
296           by the FIPS 140-2 requirements.
297

NOTES

299       Known notable exceptions
300
301Go-language applications do not yet follow the system-wide policy.
302
303GnuPG-2 application does not follow the system-wide policy.
304
305       In general only the data-in-transit is currently covered by the
306       system-wide policy.
307
308       If the system administrator changes the system-wide policy with the
309       update-crypto-policies(8) command it is advisable to restart the system
310       as the individual back-end libraries read the configuration files
311       usually during their initialization. The changes in the policy thus
312       take place in most cases only when the applications using the back-end
313       libraries are restarted.
314
315       Removed cipher suites and protocols
316
317       The following cipher suites and protocols are completely removed from
318       the core cryptographic libraries listed above:
319
320DES
321
322       •   All export grade cipher suites
323
324MD5 in signatures
325
326SSLv2
327
328SSLv3
329
330       •   All ECC curves smaller than 224 bits
331
332       •   All binary field ECC curves
333
334       Cipher suites and protocols disabled in all predefined policies
335
336       The following ciphersuites and protocols are available but disabled in
337       all predefined crypto policies:
338
339DH with parameters < 1024 bits
340
341RSA with key size < 1024 bits
342
343Camellia
344
345RC4
346
347ARIA
348
349SEED
350
351IDEA
352
353       •   Integrity only ciphersuites
354
355TLS CBC mode ciphersuites using SHA-384 HMAC
356
357AES-CCM8
358
359       •   all ECC curves incompatible with TLS 1.3, including secp256k1
360
361IKEv1
362
363       Notable irregularities in the individual configuration generators
364
365OpenSSL and NSS: Disabling all TLS and/or all DTLS versions isn’t
366           actually possible. Trying to do so will result in the library
367           defaults being applied instead.
368
369OpenSSL: The minimum length of the keys and some other parameters
370           are enforced by the @SECLEVEL value which does not provide a fine
371           granularity. The list of TLS ciphers is not generated as an exact
372           list but by subtracting from all the supported ciphers for the
373           enabled key exchange methods. For that reason there is no way to
374           disable a random cipher. In particular all AES-128 ciphers are
375           disabled if the AES-128-GCM is not present in the list; all AES-256
376           ciphers are disabled if the AES-256-GCM is not present. The CBC
377           ciphers are disabled if there isn’t HMAC-SHA1 in the hmac list and
378           AES-256-CBC in the cipher list. To disable the CCM ciphers both
379           AES-128-CCM and AES-256-CCM must not be present in the cipher list.
380
381GnuTLS: The minimum length of the keys and some other parameters
382           are enforced by min-verification-profile setting in the GnuTLS
383           configuration file which does not provide fine granularity.
384
385GnuTLS: PSK key exchanges have to be explicitly enabled by the
386           applications using them.
387
388GnuTLS: HMAC-SHA2-256 and HMAC-SHA2-384 MACs are disabled due to
389           concerns over the constant-timedness of the implementation.
390
391OpenSSH: DH group 1 is always disabled on server even if the policy
392           allows 1024 bit DH groups in general. The OpenSSH configuration
393           option HostKeyAlgorithms is set only for the SSH server as
394           otherwise the handling of the existing known hosts entries would be
395           broken on client.
396
397Libreswan: The key_exchange parameter does not affect the generated
398           configuration. The use of regular DH or ECDH can be limited with
399           appropriate setting of the group parameter.
400

HISTORY

402       The ECDHE-GSS and DHE-GSS algorithms are newly introduced and must be
403       specified in the base policy for the SSH GSSAPI key exchange methods to
404       be enabled. Previously the legacy SSH GSSAPI key exchange methods were
405       automatically enabled when the SHA1 hash and DH parameters of at least
406       2048 bits were enabled.
407
408       Before the introduction of the custom crypto policies support it was
409       possible to have an completely arbitrary crypto policy created as a set
410       of arbitrary back-end config files in
411       /usr/share/crypto-policies/<POLICYNAME> directory. With the
412       introduction of the custom crypto policies it is still possible but
413       there must be an empty (possibly with any comment lines)
414       <POLICYNAME>.pol file in /usr/share/crypto-policies/policies so the
415       update-crypto-policies command can recognize the arbitrary custom
416       policy. No subpolicies must be used with such an arbitrary custom
417       policy. Modifications from local.d will be appended to the files
418       provided by the policy.
419
420       The use of the following historaically available options is
421       discouraged:
422
423min_tls_version: Lowest allowed TLS protocol version (recommended
424           replacement: protocol@TLS)
425
426min_dtls_version: Lowest allowed DTLS protocol version (recommended
427           replacement: protocol@TLS)
428
429       The following options are deprecated, please rewrite your policies:
430
431ike_protocol: List of allowed IKE protocol versions (recommended
432           replacement: protocol@IKE, mind the relative position to other
433           protocol directives).
434
435tls_cipher: list of allowed symmetric encryption algorithms for use
436           with the TLS protocol (recommended replacement: cipher@TLS, mind
437           the relative position to other cipher directives).
438
439ssh_cipher: list of allowed symmetric encryption algorithms for use
440           with the SSH protocol (recommended replacement: cipher@SSH, mind
441           the relative position to other cipher directives).
442
443ssh_group: list of allowed groups or elliptic curves for key
444           exchanges for use with the SSH protocol (recommended replacement:
445           group@SSH, mind the relative position to other group directives).
446
447sha1_in_dnssec: Allow SHA1 usage in DNSSec protocol even if it is
448           not present in the hash and sign lists (recommended replacements:
449           hash@DNSSec, sign@DNSSec).
450

FILES

452       /etc/crypto-policies/back-ends
453           The individual cryptographical back-end configuration files.
454           Usually linked to the configuration shipped in the crypto-policies
455           package unless a configuration from local.d is added.
456
457       /etc/crypto-policies/config
458           A file containing the name of the active crypto-policy set on the
459           system.
460
461       /etc/crypto-policies/local.d
462           Additional configuration shipped by other packages or created by
463           the system administrator. The contents of the
464           <back-end>-file.config is appended to the configuration from the
465           policy back end as shipped in the crypto-policies package.
466
467       /usr/share/crypto-policies/policies
468           System policy definition files.
469
470       /usr/share/crypto-policies/policies/modules
471           System subpolicy definition files.
472
473       /etc/crypto-policies/policies
474           Custom policy definition files as configured by the system
475           administrator.
476
477       /etc/crypto-policies/policies/modules
478           Custom subpolicy definition files as configured by the system
479           administrator.
480
481       /usr/share/crypto-policies/<'POLICYNAME'>
482           Pre-generated back-end configurations for policy POLICYNAME.
483

SEE ALSO

485       update-crypto-policies(8), fips-mode-setup(8)
486

AUTHOR

488       Written by Tomáš Mráz.
489
490
491
492crypto-policies                   04/28/2022                CRYPTO-POLICIES(7)
Impressum