nixos: add release notes for conversion to types.secretFile

NixOS · Jun 6, 2022 · 775864b · 775864b
1 parent 2caf44d
commit 775864b
Show file tree

Hide file tree

Showing 3 changed files with 89 additions and 0 deletions.
diff --git a/nixos/doc/manual/from_md/development/option-types.section.xml b/nixos/doc/manual/from_md/development/option-types.section.xml
@@ -37,6 +37,46 @@
           </para>
         </listitem>
       </varlistentry>
+      <varlistentry>
+        <term>
+          <literal>types.secretFile</literal>
+        </term>
+        <listitem>
+          <para>
+            A string representing a filesystem path (starting with
+            <quote>/</quote>) to a file which is supposed to remain
+            secret. Depending on how the module is implemented, setting
+            an option of type <literal>types.path</literal> to the
+            literal value <literal>/etc/secret_file</literal> can make
+            nix copy the secret file at <literal>nixos-rebuild</literal>
+            time to the store and thus make it world readable. To avoid
+            this behavior, it is enough to quote the path:
+            <literal>&quot;/etc/secret_file&quot;</literal>. This
+            solution is simple, but it is easy to forget about it.
+            <literal>types.secretFile</literal> is design to prevent
+            such mistakes. Compared to <literal>types.path</literal>,
+            this type adds further restrictions:
+          </para>
+          <itemizedlist spacing="compact">
+            <listitem>
+              <para>
+                only strings (as opposed to unquoted paths) are accepted
+                as input.
+              </para>
+            </listitem>
+            <listitem>
+              <para>
+                the string must not start by
+                <literal>/nix/store/</literal>. To bypass these
+                restrictions you can pass the value to the function
+                <literal>types.secretFile.makeWorldReadable</literal>.
+                This can be useful when writing NixOS tests, as in this
+                case the secret file is only an example value.
+              </para>
+            </listitem>
+          </itemizedlist>
+        </listitem>
+      </varlistentry>
       <varlistentry>
         <term>
           <literal>types.package</literal>

diff --git a/nixos/doc/manual/from_md/release-notes/rl-2211.section.xml b/nixos/doc/manual/from_md/release-notes/rl-2211.section.xml
@@ -36,6 +36,36 @@
           PHP now defaults to PHP 8.1, updated from 8.0.
         </para>
       </listitem>
+      <listitem>
+        <para>
+          The NixOS module system now has a type
+          <literal>secretFile</literal> for options which contain the
+          path to a file that should remain secret. This is to avoid
+          mistakes where one writes
+          <literal>services.miniflux.adminCredentialsFile = /etc/secret</literal>
+          instead of
+          <literal>services.miniflux.adminCredentialsFile = &quot;/etc/secret&quot;;</literal>
+          which makes nix copy <literal>/etc/secret</literal> to the
+          store where everyone could read it. A number of modules have
+          been converted to use it. This is a breaking change visible by
+          an error message like this:
+        </para>
+        <programlisting>
+error: A definition for option `services.miniflux.adminCredentialsFile' is not of type `quoted path to a secret file'. Definition values:
+     - In `nixos/lib/build-vms.nix': /etc/secret
+</programlisting>
+        <para>
+          To fix the issue you must assess whether leaking
+          <literal>/etc/secret</literal> to the store and thus all local
+          users is a problem. If it is the case, then add quotes:
+          <literal>services.miniflux.adminCredentialsFile = &quot;/etc/secrets&quot;</literal>.
+          If you notice this during upgrade, your secret probably has
+          already leaked and it may be a good time to change it. If
+          leaking this file is acceptable (for example in a NixOS test),
+          you can keep the old behavior like this:
+          <literal>services.miniflux.adminCredentialsFile = lib.types.secretFile.makeWorldReadable /etc/secret</literal>.
+        </para>
+      </listitem>
     </itemizedlist>
   </section>
   <section xml:id="sec-release-22.11-new-services">

diff --git a/nixos/doc/manual/release-notes/rl-2211.section.md b/nixos/doc/manual/release-notes/rl-2211.section.md
@@ -19,6 +19,25 @@ In addition to numerous new and upgraded packages, this release has the followin
 
 - PHP now defaults to PHP 8.1, updated from 8.0.
 
+- The NixOS module system now has a type `secretFile` for options which contain
+  the path to a file that should remain secret. This is to avoid mistakes where
+  one writes `services.miniflux.adminCredentialsFile = /etc/secret` instead of
+  `services.miniflux.adminCredentialsFile = "/etc/secret";` which makes nix
+  copy `/etc/secret` to the store where everyone could read it. A number of
+  modules have been converted to use it. This is a breaking change visible by
+  an error message like this:
+  ```
+  error: A definition for option `services.miniflux.adminCredentialsFile' is not of type `quoted path to a secret file'. Definition values:
+       - In `nixos/lib/build-vms.nix': /etc/secret
+  ```
+  To fix the issue you must assess whether leaking `/etc/secret` to the store
+  and thus all local users is a problem. If it is the case, then add quotes:
+  `services.miniflux.adminCredentialsFile = "/etc/secrets"`. If you notice this
+  during upgrade, your secret probably has already leaked and it may be a good
+  time to change it. If leaking this file is acceptable (for example in a NixOS
+  test), you can keep the old behavior like this:
+  `services.miniflux.adminCredentialsFile = lib.types.secretFile.makeWorldReadable /etc/secret`.
+
 <!-- To avoid merge conflicts, consider adding your item at an arbitrary place in the list instead. -->
 
 ## New Services {#sec-release-22.11-new-services}