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 and
24       subpolicies.
25
26       The recommended way to modify the effective configuration is to apply a
27       custom subpolicy on top of a predefined policy. This allows
28       configuration to evolve with future updates of the predefined policies
29       keeping desired modification in place. Modifying effective
30       configuration by defining a fully custom policy prevents the
31       configuration from evolving with future updates of the predefined
32       policies. The syntax to define custom policies and subpolicies is
33       described in the CRYPTO POLICY DEFINITION FORMAT section below.
34
35       For rationale, see RFC 7457 for a list of attacks taking advantage of
36       legacy crypto algorithms.
37

COVERED APPLICATIONS

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

PROVIDED POLICIES

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

CRYPTO POLICY DEFINITION FORMAT

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

COMMANDS

297       update-crypto-policies(8)
298           This command manages the policies available to the various
299           cryptographic back ends and allows the system administrator to
300           change the active cryptographic policy.
301
302       fips-mode-setup(8)
303           This command allows the system administrator to enable, or disable
304           the system FIPS mode and also apply the FIPS cryptographic policy
305           which limits the allowed algorithms and protocols to these allowed
306           by the FIPS 140-2 requirements.
307

NOTES

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

HISTORY

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

FILES

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

SEE ALSO

495       update-crypto-policies(8), fips-mode-setup(8)
496

AUTHOR

498       Written by Tomáš Mráz.
499
500
501
502crypto-policies                   08/15/2022                CRYPTO-POLICIES(7)
Impressum