First attempt at supporting encrypted debug_info

lib/ex_doc/config.ex

@@ -22,6 +22,7 @@ defmodule ExDoc.Config do
             canonical: nil,
             cover: nil,
             deps: [],
+            debug_info_fn: nil,
             extra_section: nil,
             extras: [],
             filter_modules: &__MODULE__.filter_modules/2,
@@ -50,6 +51,10 @@ defmodule ExDoc.Config do
             title: nil,
             version: nil
 
+  @typep debug_info_fn_arg :: :init | :clear | {:debug_info, atom(), module(), :file.filename()}
+  @typep debug_info_fn :: (debug_info_fn_arg ->
+                             :ok | {:ok, (debug_info_fn_arg -> term())} | {:error, term()})
+
   @type t :: %__MODULE__{
           annotations_for_docs: (map() -> list()),
           api_reference: boolean(),
@@ -62,6 +67,7 @@ defmodule ExDoc.Config do
           canonical: nil | String.t(),
           cover: nil | Path.t(),
           deps: [{ebin_path :: String.t(), doc_url :: String.t()}],
+          debug_info_fn: nil | debug_info_fn(),
           extra_section: nil | String.t(),
           extras: list(),
           filter_modules: (module, map -> boolean),
@@ -120,6 +126,21 @@ defmodule ExDoc.Config do
         guess_url(options[:source_url], options[:source_ref] || @default_source_ref)
       end)
 
+    {debug_info_key, options} = Keyword.pop(options, :debug_info_key)
+
+    {debug_info_fn, options} =
+      case Keyword.pop(options, :debug_info_fn) do
+        {nil, options} -> Keyword.pop(options, :debug_info_fun)
+        {debug_info_fn, options} -> {debug_info_fn, options}
+      end
+
+    debug_info_fn =
+      cond do
+        debug_info_fn != nil -> debug_info_fn
+        debug_info_key != nil -> default_debug_info_fn(debug_info_key)
+        true -> nil
+      end
+
     preconfig = %__MODULE__{
       filter_modules: normalize_filter_modules(filter_modules),
       groups_for_modules: normalize_groups_for_modules(groups_for_modules),
@@ -133,7 +154,8 @@ defmodule ExDoc.Config do
         normalize_skip_list_function(skip_undefined_reference_warnings_on),
       skip_code_autolink_to: normalize_skip_list_function(skip_code_autolink_to),
       source_url_pattern: source_url_pattern,
-      version: vsn
+      version: vsn,
+      debug_info_fn: debug_info_fn
     }
 
     struct(preconfig, options)
@@ -224,4 +246,14 @@ defmodule ExDoc.Config do
   defp append_slash(url) do
     if :binary.last(url) == ?/, do: url, else: url <> "/"
   end
+
+  defp default_debug_info_fn(key) do
+    key = to_charlist(key)
+
+    fn
+      :init -> :ok
+      :clear -> :ok
+      {:debug_info, _mode, _module, _filename} -> key
+    end
+  end
 end

lib/ex_doc/retriever.ex

@@ -80,7 +80,7 @@ defmodule ExDoc.Retriever do
   end
 
   defp get_module(module, config) do
-    with {:docs_v1, _, language, _, _, _metadata, _} = docs_chunk <- docs_chunk(module),
+    with {:docs_v1, _, language, _, _, _metadata, _} = docs_chunk <- docs_chunk(module, config),
          {:ok, language} <- ExDoc.Language.get(language, module),
          %{} = module_data <- language.module_data(module, docs_chunk, config) do
       {:ok, generate_node(module, module_data, config)}
@@ -90,7 +90,11 @@ defmodule ExDoc.Retriever do
     end
   end
 
-  defp docs_chunk(module) do
+  defp docs_chunk(module, config) do
+    if debug_info_fn = config.debug_info_fn do
+      set_crypto_key_fn(debug_info_fn)
+    end
+
     result = Code.fetch_docs(module)
     Refs.insert_from_chunk(module, result)
 
@@ -496,4 +500,17 @@ defmodule ExDoc.Retriever do
   defp source_link(source, line) do
     Utils.source_url_pattern(source.url, source.path |> Path.relative_to(File.cwd!()), line)
   end
+
+  @doc false
+  def set_crypto_key_fn(crypto_key_fn) do
+    :beam_lib.clear_crypto_key_fun()
+
+    case :beam_lib.crypto_key_fun(crypto_key_fn) do
+      {:error, reason} ->
+        raise Error, "failed to set crypto_key_fun: #{inspect(reason)}"
+
+      other ->
+        other
+    end
+  end
 end

lib/mix/tasks/docs.ex

@@ -104,6 +104,17 @@ defmodule Mix.Tasks.Docs do
       ExDoc will by default include all dependencies and assume they are hosted on
       HexDocs. This can be overridden by your own values. Example: `[plug: "https://myserver/plug/"]`
 
+    * `:debug_info_key` - The key to be used to decrypt debug info that was encrypted during compilation. This option will be ignored if `:debug_info_fn` or `:debug_info_fun` is provided.
+    See [Encrypted debug info](`m:Mix.Tasks.Docs#module-encrypted-debug-info`).
+
+    * `:debug_info_fn` - A function that will be provided to `:beam_lib.crypto_key_fun/1` to decrypt debug info that was encrypted during compilation. If this option is provided,
+    `:debug_info_key` and `:debug_info_fun` will be ignored. See
+    [Encrypted debug info](`m:Mix.Tasks.Docs#module-encrypted-debug-info`).
+
+    * `:debug_info_fun` - Same as `:debug_info_fn`. This option will be ignored if `:debug_info_fn`
+    is already present. See
+    [Encrypted debug info](`m:Mix.Tasks.Docs#module-encrypted-debug-info`).
+
     * `:extra_section` - String that defines the section title of the additional
       Markdown and plain text pages; default: "PAGES". Example: "GUIDES"
 
@@ -200,6 +211,62 @@ defmodule Mix.Tasks.Docs do
       where path is either an relative path from the cwd, or an absolute path. The function
       must return the full URI as it should be placed in the documentation.
 
+  ## Encrypted debug info
+
+  If a module is compiled with [encrypted debug info](`:compile.file/2`), ExDoc will not be able to
+  extract its documentation without first setting a decryption function or utilizing a
+  `.erlang.crypt` file as prescribed by `m::beam_lib#module-encrypted-debug-information`. Two
+  convenience options are provided to avoid having to call `:beam_lib.crypto_key_fun/1` out-of-band
+  and/or to avoid using `.erlang.crypt`.
+
+  If you prefer to set set the key out-of-band, follow the instructions provided in the
+  `m::beam_lib#module-encrypted-debug-information` module documentation.
+
+  > ### Key exposure {: .warning}
+  >
+  > Avoid adding keys directly to your `mix.exs` file. Instead, use an environment variable, an
+  > external documentation config file, or a
+  > [closure](https://erlef.github.io/security-wg/secure_coding_and_deployment_hardening/sensitive_data#wrapping).
+
+  ### `:debug_info_key`
+
+  This option can be provided if you only have one key for all encrypted modules. A `t:charlist/0`, `t:String.t/0`, or tuple of `{:des3_cbc, charlist() | String.t()}` can be used.
+
+  ### `:debug_info_fn`/`:debug_info_fun`
+
+  This option can be provided if you have multiple keys, want more control over key retrieval, or
+  would like to wrap your key(s) in a closure. `:debug_info_key` will be ignored if this option is
+  also present. `:debug_info_fun` will be ignored if `:debug_info_fn` is already present.
+
+  A basic function that provides the decryption key `SECRET`:
+
+  <!-- tabs-open -->
+
+  ### Elixir
+
+  ⚠️ The key returned must be a `t:charlist/0`!
+
+  ```elixir
+  fn
+    :init -> :ok,
+    {:debug_info, _mode, _module, _filename} -> ~c"SECRET"
+    :clear -> :ok
+  end
+  ```
+
+  ### Erlang
+
+  ```erlang
+  fun
+    (init) -> ok;
+    ({debug_info, _Mode, _Module, _Filename}) -> "SECRET";
+    (clear) -> ok
+  end.
+  ```
+  <!-- tabs-close -->
+
+  See `:beam_lib.crypto_key_fun/1` for more information.
+
   ## Groups
 
   ExDoc content can be organized in groups. This is done via the `:groups_for_extras`

test/ex_doc/config_test.exs

@@ -74,4 +74,52 @@ defmodule ExDoc.ConfigTest do
     assert config.skip_code_autolink_to.("ConfigTest.Hidden.bar/1")
     refute config.skip_code_autolink_to.("ConfigTest.NotHidden")
   end
+
+  test "produces a function when a debug_info_key is provided" do
+    config = ExDoc.Config.build(@project, @version, debug_info_key: "Hunter2")
+
+    assert config.debug_info_fn.(:init) == :ok
+    assert config.debug_info_fn.(:clear) == :ok
+    assert config.debug_info_fn.({:debug_info, nil, nil, nil}) == ~c"Hunter2"
+  end
+
+  test "ignores debug_info_key when debug_info_fn or debug_info_fun is provided" do
+    config =
+      ExDoc.Config.build(@project, @version,
+        debug_info_key: "Hunter2",
+        debug_info_fn: debug_info_fn(~c"foxtrot")
+      )
+
+    assert config.debug_info_fn.({:debug_info, nil, nil, nil}) == ~c"foxtrot"
+
+    config =
+      ExDoc.Config.build(@project, @version,
+        debug_info_key: "Hunter2",
+        debug_info_fun: debug_info_fn(~c"tango")
+      )
+
+    assert config.debug_info_fn.({:debug_info, nil, nil, nil}) == ~c"tango"
+  end
+
+  test "handles either debug_info_fn or debug_info_fun, but debug_info_fn takes precedence" do
+    config =
+      ExDoc.Config.build(@project, @version,
+        debug_info_fun: debug_info_fn(~c"fun"),
+        debug_info_fn: debug_info_fn(~c"fn")
+      )
+
+    assert config.debug_info_fn.({:debug_info, nil, nil, nil}) == ~c"fn"
+
+    config = ExDoc.Config.build(@project, @version, debug_info_fun: debug_info_fn(~c"fun"))
+
+    assert config.debug_info_fn.({:debug_info, nil, nil, nil}) == ~c"fun"
+  end
+
+  defp debug_info_fn(key) do
+    fn
+      :init -> :ok
+      :clear -> :ok
+      {:debug_info, _mode, _module, _filename} -> key
+    end
+  end
 end

test/ex_doc/retriever/erlang_test.exs

@@ -111,6 +111,59 @@
                ~r'Equivalent to <a href="`function2/1`"><code[^>]+>function2\(\[\{test, args\}\]\).*\.'
     end
 
+    test "with encrypted debug_info", c do
+      erlc(
+        c,
+        :debug_info_mod,
+        ~S"""
+        -module(debug_info_mod).
+        -moduledoc("mod docs.").
+        -export([function1/0]).
+        -export_type([foo/0]).
+
+        -doc("foo/0 docs.").
+        -type foo() :: atom().
+
+        -doc("function1/0 docs.").
+        -spec function1() -> atom().
+        function1() -> ok.
+        """,
+        debug_info_key: ~c"SECRET"
+      )
+
+      # the emitted warning is expected
+      assert {[], []} == Retriever.docs_from_modules([:debug_info_mod], %ExDoc.Config{})
+
+      config = ExDoc.Config.build("debug_info_mod", 1, debug_info_key: ~c"SECRET")
+
+      {[mod], []} = Retriever.docs_from_modules([:debug_info_mod], config)
+
+      assert %ExDoc.ModuleNode{
+               deprecated: nil,
+               moduledoc_line: 2,
+               moduledoc_file: moduledoc_file,
+               docs: [function1],
+               docs_groups: [:Types, :Callbacks, :Functions],
+               group: nil,
+               id: "debug_info_mod",
+               language: ExDoc.Language.Erlang,
+               module: :debug_info_mod,
+               nested_context: nil,
+               nested_title: nil,
+               rendered_doc: nil,
+               source_path: _,
+               source_url: nil,
+               title: "debug_info_mod",
+               type: :module,
+               typespecs: [foo]
+             } = mod
+
+      assert DocAST.to_string(mod.doc) =~ "mod docs."
+      assert DocAST.to_string(function1.doc) =~ "function1/0 docs."
+      assert DocAST.to_string(foo.doc) =~ "foo/0 docs."
+      assert moduledoc_file =~ "debug_info_mod.erl"
+    end
+
     test "module included files", c do
       erlc(c, :mod, ~S"""
       -file("module.hrl", 1).
@@ -506,5 +559,59 @@
       assert type1.spec |> Erlang.autolink_spec(current_kfa: {:type, :type1, 0}) ==
                "type1() :: <a href=\"https://www.erlang.org/doc/apps/erts/erlang.html#t:atom/0\">atom</a>()."
     end
+
+    test "with encrypted debug_info", c do
+      erlc(
+        c,
+        :debug_info_mod2,
+        ~S"""
+        %% @doc mod docs.
+        -module(debug_info_mod2).
+        -export([function1/0]).
+        -export_type([foo/0]).
+
+        -type foo() :: atom().
+        %% foo/0 docs.
+
+        %% @doc
+        %% function1/0 docs.
+        -spec function1() -> foo().
+        function1() -> ok.
+        """,
+        debug_info_key: ~c"SECRET"
+      )
+
+      # this test only succeeds on the first run
+      refute {[], []} == Retriever.docs_from_modules([:debug_info_mod2], %ExDoc.Config{})
+
+      config = ExDoc.Config.build("debug_info_mod2", 1, debug_info_key: ~c"SECRET")
+
+      {[mod], []} = Retriever.docs_from_modules([:debug_info_mod2], config)
+
+      assert %ExDoc.ModuleNode{
+               deprecated: nil,
+               moduledoc_line: 2,
+               moduledoc_file: moduledoc_file,
+               docs: [function1],
+               docs_groups: [:Types, :Callbacks, :Functions],
+               group: nil,
+               id: "debug_info_mod2",
+               language: ExDoc.Language.Erlang,
+               module: :debug_info_mod2,
+               nested_context: nil,
+               nested_title: nil,
+               rendered_doc: nil,
+               source_path: _,
+               source_url: nil,
+               title: "debug_info_mod2",
+               type: :module,
+               typespecs: [foo]
+             } = mod
+
+      assert DocAST.to_string(mod.doc) =~ "mod docs."
+      assert DocAST.to_string(function1.doc) =~ "function1/0 docs."
+      assert DocAST.to_string(foo.doc) =~ "foo/0 docs."
+      assert moduledoc_file =~ "debug_info_mod2.erl"
+    end
   end
 end

test/ex_doc/retriever_test.exs

@@ -307,4 +307,14 @@ defmodule ExDoc.RetrieverTest do
     %{docs: [%{signature: signature}]} = module_node
     assert signature == "callback_name(arg1, integer, %Date{}, term, t)"
   end
+
+  test "set_crypto_key_fn/1 raises if it receives an error" do
+    assert_raise(
+      Retriever.Error,
+      "failed to set crypto_key_fun: :badfun",
+      fn ->
+        Retriever.set_crypto_key_fn(fn _ -> {:error, :badfun} end)
+      end
+    )
+  end
 end