corrections from checking output

Author: taroth21

xml/security_cryptopolicy.xml

@@ -8,7 +8,7 @@
          xmlns:xi="http://www.w3.org/2001/XInclude"
          xmlns:xlink="http://www.w3.org/1999/xlink"
          version="5.0"
-         xml:id="cha-security-cryptopolicy">
+         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
@@ -20,19 +20,19 @@
   <info>
     <abstract>
       <para>
-        bla
+        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-cryptopolicy-oview">
-    <title>Conceptual overview</title>
+  <sect1 xml:id="sec-security-cryptopolicies-concept">
+    <title>The <command>crypto-policies</command> concept</title>
 
     <para>
-      The <package>crypto-policies</package> RPM package provides pre-built
+      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
@@ -43,16 +43,16 @@
       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. Having crypto-policies allows to easily handle the deprecation
-      of algorithms or protocols system-wide and in a transparent manner.
+      protocols. Crypto-policies allow to handle the deprecation of algorithms
+      or protocols system-wide and in a transparent manner.
     </para>
   </sect1>
-  <sect1>
-    <title>Predefined policy levels</title>
+  <sect1 xml:id="sec-security-cryptopolicies-predefined">
+    <title>Predefined cryptographic policies</title>
 
     <para>
       The <package>crypto-policies</package> package comes with the following
-      predefined policy levels:
+      predefined policies that can be applied system-wide:
     </para>
 
     <variablelist>
@@ -118,20 +118,21 @@
       and are read-only.
     </para>
   </sect1>
-  <sect1>
-    <title>Switching to a different crypto-policy level</title>
+  <sect1 xml:id="sec-security-cryptopolicies-switch">
+    <title>Switching to a different crypto-policy</title>
 
     <para>
-      Use the <command>update-crypto-policies</command> to set the policy level
-      which is applied to the cryptographic back-ends. It is the default policy
-      used by these back-ends unless the application user configures them
+      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 level that is currently in use:
+          To check the crypto-policy that is currently in use:
         </para>
 <screen>&prompt.root;<command>update-crypto-policies --show</command></screen>
       </step>
@@ -140,28 +141,28 @@
           To switch to a different policy level, use the <option>--set</option>
           option:
         </para>
-<screen>update-crypto-policies --set <replaceable>POLICY</replaceable></screen>
         <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 level is less secure</title>
+          <title>LEGACY crypto-policy is less secure</title>
           <para>
-            Switching to a LEGACY crypto-policy level makes your system and
+            Switching to a LEGACY crypto-policy makes your system and
             applications less secure.
           </para>
         </important>
       </step>
       <step>
         <para>
-          After switching to a different policy level restart the system to
-          apply the changes to the applications.
+          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>
   </sect1>
-  <sect1>
+  <sect1 xml:id="sec-security-cryptopolicies-subpolicies">
     <title>Customizing existing crypto-policies</title>
 
     <para>
@@ -178,10 +179,10 @@
       <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). The name of the subpolicy file must be
+      are packaged). Name the subpolicy file
       <filename><replaceable>MODULE</replaceable>.pmod</filename>, where
-      <replaceable>MODULE</replaceable> is the name of the subpolicy. It needs
-      to be spelled in uppercase letters and without spaces.
+      <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">
@@ -200,10 +201,11 @@
             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 and save the file afterwards:
+            Add the following line to the file and save it afterwards:
           </para>
 <screen>key_exchange = -RSA -PSK</screen>
           <para>
@@ -224,13 +226,13 @@
             Double-check if the subpolicy has been added to
             <literal>DEFAULT</literal>:
           </para>
-<screen><command>update-crypto-policies --show</command>
+<screen>&prompt.root;<command>update-crypto-policies --show</command>
 DEFAULT:NO-RSA-PSK</screen>
         </step>
         <step>
           <para>
-            Reboot the system to apply the system-wide policy adjustment to the
-            applications:
+            Reboot the machine to apply the system-wide policy adjustment to
+            the applications:
           </para>
 <screen>&prompt.root;<command>reboot</command></screen>
         </step>
@@ -249,7 +251,8 @@ DEFAULT:NO-RSA-PSK</screen>
       <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
-      it is owned by &rootuser; and is not writable by non-privileged users.
+      the policy file is owned by &rootuser; and is not writable by
+      non-privileged users.
     </para>
 
     <example xml:id="ex-crypto-policy-custom">
@@ -264,7 +267,7 @@ DEFAULT:NO-RSA-PSK</screen>
             Copy the <literal>DEFAULT</literal> policy to
             <filename>/etc/crypto-policies/policies/</filename> and rename it:
           </para>
-<screen>cp /usr/share/crypto-policies/policies/DEFAULT.pol /etc/crypto-policies/policies/<replaceable>MY_POLICY</replaceable>.pol</screen>
+<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>
@@ -275,28 +278,22 @@ DEFAULT:NO-RSA-PSK</screen>
           <para>
             Switch the system to the new policy:
           </para>
-<screen>&prompt.root;<command>update-crypto-policies --set MY_POLICY</command></screen>
+<screen>&prompt.root;<command>update-crypto-policies --set</command> MY_POLICY</screen>
         </step>
         <step>
           <para>
-            Reboot the system to apply the new policy to the
-            applications and running services:
+            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><command>update-crypto-policies --show</command>
+<screen>&prompt.root;<command>update-crypto-policies --show</command>
 MY_POLICY</screen>
         </step>
-        <step>
-          <para>
-            Reboot the system to apply the system-wide policy adjustment to the
-            applications.
-          </para>
-        </step>
       </procedure>
     </example>
   </sect1>