custom subpolicy: added example

xml/security_cryptopolicy.xml

@@ -156,7 +156,7 @@
       <step>
         <para>
           After switching to a different policy level restart the system to
-          apply the changes.
+          apply the changes to the applications.
         </para>
       </step>
     </procedure>
@@ -169,19 +169,74 @@
       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 example ????.
+      line to one of the predefined policies. For details, see
+      <xref linkend="ex-crypto-policy-subpolicy"></xref>.
     </para>
 
     <para>
-      Subpolicies need to be stored in
-      <filename>/usr/share/crypto-policies/policies/modules/</filename>. You
-      can also find example subpolicies in this directory. The name of the
-      subpolicy file must be <replaceable>MODULE</replaceable>.pmod, where
-      <replaceable>MODULE</replaceable> is the name of the modifier in
-      uppercase and without spaces.
+      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) . The name of the subpolicy file must be
+      <replaceable>MODULE</replaceable>.pmod, where
+      <replaceable>MODULE</replaceable> is the name of the subpolicy. It needs
+      to be spelled in uppercase letters and without spaces.
     </para>
 
-    <!--todo: add example and how to apply it, e.g. with update-crypto-policies -/-set DEFAULT:NO-SHA1-->
+    <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>
+        </step>
+        <step>
+          <para>
+            Add the following line and save the file 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>:
+            command:
+          </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><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.
+          </para>
+        </step>
+      </procedure>
+    </example>
+
     <!--todo: add another section how to create a new policy from scratch-->
   </sect1>
 </chapter>