Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[WIP] Add global crypto policies #1545

Open
wants to merge 12 commits into
base: main
Choose a base branch
from
Open

[WIP] Add global crypto policies #1545

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
4abf915
Security Guide: add chapter skeleton
taroth21 Jun 30, 2023
08133b2
start adding basic info and ToDos
taroth21 Jun 30, 2023
9b0d761
add predefined policy levels
taroth21 Jun 30, 2023
559093b
adding minor info and skeleton for next section
taroth21 Jul 7, 2023
79cc543
switch crypto-policy level
taroth21 Aug 4, 2023
2240999
predefined policies are read-only
taroth21 Aug 4, 2023
3a14193
custom subpolicy (WIP)
taroth21 Aug 4, 2023
e559065
custom subpolicy: added example
taroth21 Aug 11, 2023
c79575b
create new policy
taroth21 Aug 11, 2023
f113ed2
corrections from checking output
taroth21 Aug 11, 2023
6d105c1
predefined policies: add BSI (PED-4933)
taroth21 Mar 8, 2024
93b170e
switch policy: mention FIPS enablement by script
taroth21 Mar 8, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions xml/book_security.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,6 +60,7 @@
<xi:include href="security_yast2_security.xml"/>
<xi:include href="security_polkit.xml"/>
<xi:include href="security_acls.xml"/>
<xi:include href="security_cryptopolicy.xml"/>
<!-- this is very outdated, removing until I can rewrite
it with updated information cschroder 12 Dec 2021
<xi:include href="security_certificatestore.xml"/>-->
Expand Down
328 changes: 328 additions & 0 deletions xml/security_cryptopolicy.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,328 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter
[
<!ENTITY % entities SYSTEM "generic-entities.ent">
%entities;
]>
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="cha-security-cryptopolicies">
<!--taroth 2023-04-28
Main ToDos (based on https://bugzilla.suse.com/show_bug.cgi?id=1209998#c7)
* add new chapter to Security Guide, describe also integration
* explain how we intend customers to use the crypto-policies
* explain what changed exactly and what impact this has,
e.g. if someone updates from SP3 (no active crypto-policies)
to SP4 (active crypto-policies)-->
<title>Using system-wide cryptographic policies</title>
<info>
<abstract>
<para>
TODO
</para>
</abstract>
<dm:docmanager xmlns:dm="urn:x-suse:ns:docmanager">
<dm:bugtracker></dm:bugtracker>
<dm:translation>yes</dm:translation>
</dm:docmanager>
</info>
<sect1 xml:id="sec-security-cryptopolicies-concept">
<title>The <command>crypto-policies</command> concept</title>

<para>
The <package>crypto-policies</package> RPM package provides predefined
configuration files with cryptographic policies for cryptographic
back-ends, such as SSL/TLS libraries. This package allows to set the
cryptographic security level for all applications that use a
cryptographic back-end supported by the policies.
</para>

<para>
Crypto-policies apply to the configuration of the core cryptographic
subsystems. They cover the supported secure communications protocols on
the base operating system, such as TLS, IKE, IPSec, DNSSec and Kerberos
protocols. Crypto-policies allow to handle the deprecation of algorithms
or protocols system-wide and in a transparent manner.
</para>
</sect1>
<sect1 xml:id="sec-security-cryptopolicies-predefined">
<title>Predefined cryptographic policies</title>

<para>
The <package>crypto-policies</package> package comes with the following
predefined policies that can be applied system-wide:
</para>

<variablelist>
<varlistentry>
<term>BSI</term>
<listitem>
<para>
A security policy based on recommendations by the German government
agency BSI (Bundesamt fuer Sicherheit in der Informationstechnik,
translated as <literal>agency for security in software
technology</literal>). The policy is based on the technical
recommendation ruleset <literal>TR 02102</literal>. The BSI TR
02102 standard is updated in regular intervals. This policy does
not allow the use of SHA-1 in signature algorithms (except DNSSEC
and RPM). The policy also provides some (not complete) preparation
for post-quantum encryption support in form of 256-bit symmetric
encryption requirement. The RSA parameters are accepted if larger
than 2047 bits, and Diffie-Hellman parameters are accepted if
larger than 3071 bits. This policy provides at least 128-bit
security, excepting the transition of RSA.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>DEFAULT</term>
<listitem>
<para>
A reasonable default policy for today's standards. It allows the
TLS 1.2, and TLS 1.3 protocols, as well as IKEv2 and SSH2. The
Diffie-Hellman parameters are accepted if they are at least 2048
bits long. The level provides at least 112-bit security with the
exception of allowing SHA-1 signatures in DNSSec where they are
still prevalent.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>FIPS</term>
<listitem>
<para>
A level that conforms to the FIPS 140-2 requirements. This policy
is used internally by the <command>fips-mode-setup</command> tool
which can switch the system into FIPS 140-2 compliance mode. The
level provides at least 112-bit security.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>FUTURE</term>
<listitem>
<para>
A conservative security level that is believed to withstand any
near-term future attacks. This level does not allow the use of
SHA-1 in signature algorithms. The level also provides some (not
complete) preparation for post-quantum encryption support in form
of 256-bit symmetric encryption requirement. The RSA and
Diffie-Hellman parameters are accepted if larger than 3071 bits.
The level provides at least 128-bit security.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>LEGACY</term>
<listitem>
<para>
This policy ensures maximum compatibility with legacy systems. It
is less secure and it includes support for TLS 1.0, TLS 1.1, and
SSH2 protocols or later. The algorithms DSA, 3DES, and RC4 are
allowed, while RSA and Diffie-Hellman parameters are accepted if
larger than 1023 bits. The level provides at least 64-bit security.
</para>
</listitem>
</varlistentry>
</variablelist>

<para>
Policies can change over time together with the security of the
cryptographic components. For the latest details on the individual
policies, therefore see the man page of
<command>crypto-policies</command>. All predefined policies are located
in
<filename>/usr/share/crypto-policies/policies/<replaceable>NAME</replaceable>.pol</filename>
and are read-only.
</para>
</sect1>
<sect1 xml:id="sec-security-cryptopolicies-switch">
<title>Switching to a different crypto-policy</title>

<para>
Use the <command>update-crypto-policies</command> command to view and set
the policy which is applied system-wide to the cryptographic back-ends.
The policy which has been set with this command is used by these
back-ends by default unless the application user configures them
otherwise.
</para>

<procedure>
<step>
<para>
To check the crypto-policy that is currently in use:
</para>
<screen>&prompt.root;<command>update-crypto-policies --show</command></screen>
</step>
<step>
<para>
To switch to a different policy level, use the <option>--set</option>
option:
</para>
<remark>taroth 2023-07-04: do we need a word of caution here for LEGACY and FIPS?
and can we tell that switching to 'LEGACY' enables compatibility with a specific
older SLE version, like SLE 12 SP5 or so?
</remark>
<important>
<title>LEGACY crypto-policy is less secure</title>
<para>
Switching to a LEGACY crypto-policy makes your system and
applications less secure.
</para>
</important>
</step>
<step>
<para>
After switching to a different policy reboot the machine to apply the
changes to the applications:
</para>
<screen>&prompt.root;<command>reboot</command></screen>
</step>
</procedure>
<tip os="sles">
<title>Enabling FIPS mode via script</title>
<para>
For the FIPS crypto-policy, &suse; also provides a script with which you
can comfortably enable the FIPS mode. See
<xref linkend="sec-how-to-fips-install"/> for details.
</para>
</tip>
</sect1>
<sect1 xml:id="sec-security-cryptopolicies-subpolicies">
<title>Customizing existing crypto-policies</title>

<para>
You can modify aspects of any predefined policy by removing or adding
algorithms or protocols. This way, you create a subpolicy (or policy
modifier module), stored in text files that include the modifications.
After creation, one or multiple subpolicies can be applied on the command
line to one of the predefined policies. For details, see
<xref linkend="ex-crypto-policy-subpolicy"></xref>.
</para>

<para>
You can find example subpolicies in
<filename>/usr/share/crypto-policies/policies/modules</filename>.
However, your own subpolicies need to be stored in
<filename>/etc/crypto-policies/policies/modules</filename> (unless they
are packaged). Name the subpolicy file
<filename><replaceable>MODULE</replaceable>.pmod</filename>, where
<replaceable>MODULE</replaceable> is the name of the subpolicy. The file
name needs to be spelled in uppercase letters and without spaces.
</para>

<example xml:id="ex-crypto-policy-subpolicy">
<title>Removing support for RSA and PSK key exchanges</title>
<para>
The following example shows you how to create a subpolicy which removes
support for RSA and PSK key exchanges from the
<literal>DEFAULT</literal> policy. Both key exchanges do not provide
forward secrecy, which means they cannot make sure that session keys
are not compromised in case long-term secrets used in the key exchange
session are compromised.
</para>
<procedure>
<step>
<para>
In <filename>/etc/crypto-policies/policies/modules/</filename>
create a new file, named <filename>NO-RSA-PSK.pmod</filename>.
</para>
<screen>&prompt.root;<command>touch</command> /etc/crypto-policies/policies/modules/NO-RSA-PSK.pmod</screen>
</step>
<step>
<para>
Add the following line to the file and save it afterwards:
</para>
<screen>key_exchange = -RSA -PSK</screen>
<para>
Now you can apply the newly created subpolicy to one of the
predefined policies.
</para>
</step>
<step>
<para>
Assuming the current system-wide policy is
<literal>DEFAULT</literal> and you want to apply the newly created
subpolicy to <literal>DEFAULT</literal>:
</para>
<screen>&prompt.root;<command>update-crypto-policies --set DEFAULT:NO-RSA-PSK</command></screen>
</step>
<step>
<para>
Double-check if the subpolicy has been added to
<literal>DEFAULT</literal>:
</para>
<screen>&prompt.root;<command>update-crypto-policies --show</command>
DEFAULT:NO-RSA-PSK</screen>
</step>
<step>
<para>
Reboot the machine to apply the system-wide policy adjustment to
the applications:
</para>
<screen>&prompt.root;<command>reboot</command></screen>
</step>
</procedure>
</example>
</sect1>
<sect1>
<title>Creating a new policy from scratch</title>

<para>
Instead of customizing an existing crypto-policy with a subpolicy you can
also decide to write a new policy from scratch. You can use any of the
predefined policies in
<filename>/usr/share/crypto-policies/policies/</filename> as a starting
point. However, your own policy file needs to be stored in
<filename>/etc/crypto-policies/policies/</filename>. Name your file
<filename><replaceable>MY_POLICY</replaceable>.pol</filename>, where
<replaceable>MY_POLICY</replaceable> is the name of the policy. Make sure
the policy file is owned by &rootuser; and is not writable by
non-privileged users.
</para>

<example xml:id="ex-crypto-policy-custom">
<title>Creating a new policy and applying it</title>
<para>
The following example shows you how to create a new policy based on the
<literal>DEFAULT</literal> policy.
</para>
<procedure>
<step>
<para>
Copy the <literal>DEFAULT</literal> policy to
<filename>/etc/crypto-policies/policies/</filename> and rename it:
</para>
<screen>&prompt.root;<command>cp</command> /usr/share/crypto-policies/policies/DEFAULT.pol /etc/crypto-policies/policies/<replaceable>MY_POLICY</replaceable>.pol</screen>
</step>
<step>
<para>
Edit the policy as desired and save it.
</para>
</step>
<step>
<para>
Switch the system to the new policy:
</para>
<screen>&prompt.root;<command>update-crypto-policies --set</command> MY_POLICY</screen>
</step>
<step>
<para>
Reboot the machine to apply the new policy to the applications and
running services:
</para>
<screen>&prompt.root;<command>reboot</command></screen>
</step>
<step>
<para>
Double-check if the policy is active:
</para>
<screen>&prompt.root;<command>update-crypto-policies --show</command>
MY_POLICY</screen>
</step>
</procedure>
</example>
</sect1>
</chapter>
Loading