Merge pull request #39526 (improve dhparams)

This introduces an option that allows us to turn off stateful generation
of Diffie-Hellman parameters, which in some way is still "stateful" as
the generated DH params file is non-deterministic.

However what we can avoid with this is to have an increased surface for
failures during system startup, because generation of the parameters is
done during build-time.

Aside from adding a NixOS VM test it also restructures the type of the
security.dhparams.params option, so that it's a submodule.

A new defaultBitSize option is also there to allow users to set a
system-wide default.

I added a release notes entry that described what has changed and also
included a few notes for module developers using this module, as the
first usage already popped up in NixOS/nixpkgs#39507.

Thanks to @Ekleog and @abbradar for reviewing.

1 files changed, 52 insertions, 0 deletions

diff --git a/nixos/doc/manual/release-notes/rl-1809.xml b/nixos/doc/manual/release-notes/rl-1809.xml
index 7136f4540502..7259be4c904c 100644
--- a/nixos/doc/manual/release-notes/rl-1809.xml
+++ b/nixos/doc/manual/release-notes/rl-1809.xml
@@ -175,6 +175,58 @@ $ nix-instantiate -E '(import <nixpkgsunstable> {}).gitFull'
      for further reference.
     </para>
    </listitem>
+   <listitem>
+    <para>
+     The module for <option>security.dhparams</option> has two new options now:
+    </para>
+
+    <variablelist>
+     <varlistentry>
+      <term><option>security.dhparams.stateless</option></term>
+      <listitem><para>
+       Puts the generated Diffie-Hellman parameters into the Nix store instead
+       of managing them in a stateful manner in
+       <filename class="directory">/var/lib/dhparams</filename>.
+      </para></listitem>
+     </varlistentry>
+     <varlistentry>
+      <term><option>security.dhparams.defaultBitSize</option></term>
+      <listitem><para>
+       The default bit size to use for the generated Diffie-Hellman parameters.
+      </para></listitem>
+     </varlistentry>
+    </variablelist>
+
+    <note><para>
+     The path to the actual generated parameter files should now be queried
+     using
+     <literal>config.security.dhparams.params.<replaceable>name</replaceable>.path</literal>
+     because it might be either in the Nix store or in a directory configured
+     by <option>security.dhparams.path</option>.
+    </para></note>
+
+    <note>
+     <title>For developers:</title>
+     <para>
+      Module implementers should not set a specific bit size in order to let
+      users configure it by themselves if they want to have a different bit
+      size than the default (2048).
+     </para>
+     <para>
+      An example usage of this would be:
+<programlisting>
+{ config, ... }:
+
+{
+  security.dhparams.params.myservice = {};
+  environment.etc."myservice.conf".text = ''
+    dhparams = ${config.security.dhparams.params.myservice.path}
+  '';
+}
+</programlisting>
+     </para>
+    </note>
+   </listitem>
   </itemizedlist>
  </section>
 </section>