Merge pull request #6334 from zmstone/refactor-psk-better-name

refactor: give psk auth a better namespace

apps/emqx_dashboard/src/emqx_dashboard_swagger.erl

@@ -337,19 +337,28 @@ components(Refs) ->
 components([], SpecAcc, []) -> SpecAcc;
 components([], SpecAcc, SubRefAcc) -> components(SubRefAcc, SpecAcc, []);
 components([{Module, Field} | Refs], SpecAcc, SubRefsAcc) ->
-    Props = apply(Module, fields, [Field]),
+    Props = hocon_schema_fields(Module, Field),
     Namespace = namespace(Module),
     {Object, SubRefs} = parse_object(Props, Module),
     NewSpecAcc = SpecAcc#{?TO_REF(Namespace, Field) => Object},
     components(Refs, NewSpecAcc, SubRefs ++ SubRefsAcc);
 %% parameters in ref only have one value, not array
 components([{Module, Field, parameter} | Refs], SpecAcc, SubRefsAcc) ->
-    Props = apply(Module, fields, [Field]),
+    Props = hocon_schema_fields(Module, Field),
     {[Param], SubRefs} = parameters(Props, Module),
     Namespace = namespace(Module),
     NewSpecAcc = SpecAcc#{?TO_REF(Namespace, Field) => Param},
     components(Refs, NewSpecAcc, SubRefs ++ SubRefsAcc).
 
+hocon_schema_fields(Module, StructName) ->
+    case apply(Module, fields, [StructName]) of
+        #{fields := Fields, desc := _} ->
+            %% evil here, as it's match hocon_schema's internal representation
+            Fields; %% TODO: make use of desc ?
+        Other ->
+            Other
+    end.
+
 %% Semantic error at components.schemas.xxx:xx:xx
 %% Component names can only contain the characters A-Z a-z 0-9 - . _
 %% So replace ':' by '-'.

apps/emqx_psk/etc/emqx_psk.conf

@@ -2,11 +2,11 @@
 ## EMQ X PSK
 ##--------------------------------------------------------------------
 
-psk {
+psk_authentication {
     ## Whether to enable the PSK feature.
     enable = false
 
-    ## If init file is specified, emqx will import PSKs from the file 
+    ## If init file is specified, emqx will import PSKs from the file
     ## into the built-in database at startup for use by the runtime.
     ##
     ## The file has to be structured line-by-line, each line must be in

apps/emqx_psk/src/emqx_psk.erl

@@ -142,13 +142,13 @@ code_change(_OldVsn, State, _Extra) ->
 %%------------------------------------------------------------------------------
 
 get_config(enable) ->
-    emqx_conf:get([psk, enable]);
+    emqx_conf:get([psk_authentication, enable]);
 get_config(init_file) ->
-    emqx_conf:get([psk, init_file], undefined);
+    emqx_conf:get([psk_authentication, init_file], undefined);
 get_config(separator) ->
-    emqx_conf:get([psk, separator], ?DEFAULT_DELIMITER);
+    emqx_conf:get([psk_authentication, separator], ?DEFAULT_DELIMITER);
 get_config(chunk_size) ->
-    emqx_conf:get([psk, chunk_size]).
+    emqx_conf:get([psk_authentication, chunk_size]).
 
 import_psks(SrcFile) ->
     case file:open(SrcFile, [read, raw, binary, read_ahead]) of

apps/emqx_psk/src/emqx_psk_schema.erl

@@ -24,9 +24,24 @@
         , fields/1
         ]).
 
-roots() -> ["psk"].
+roots() -> ["psk_authentication"].
 
-fields("psk") ->
+fields("psk_authentication") ->
+    #{fields => fields(),
+      desc => """PSK stands for 'Pre-Shared Keys'.
+This config to enable TLS-PSK authentication.
+
+<strong>Important!</strong> Make sure the SSL listener with
+only <code>tlsv1.2</code> enabled, and also PSK cipher suites
+configured, such as <code>RSA-PSK-AES256-GCM-SHA384</code>.
+See listener SSL options config for more details.
+
+The IDs and secrets can be provided from a file the path
+to which is configurable by the <code>init_file</code> field.
+"""
+     }.
+
+fields() ->
     [ {enable,     fun enable/1}
     , {init_file,  fun init_file/1}
     , {separator,  fun separator/1}
@@ -43,7 +58,7 @@ init_file(desc) ->
     <<"If init_file is specified, emqx will import PSKs from the file ",
       "into the built-in database at startup for use by the runtime. ",
       "The file has to be structured line-by-line, each line must be in ",
-      "the format: <PSKIdentity>:<SharedSecret>">>;
+      "the format of 'PSKIdentity:SharedSecret' for example: mydevice1:c2VjcmV0">>;
 init_file(nullable) -> true;
 init_file(_) -> undefined.
 

apps/emqx_psk/test/emqx_psk_SUITE.erl

@@ -26,13 +26,13 @@ all() ->
 
 init_per_suite(Config) ->
     meck:new(emqx_config, [non_strict, passthrough, no_history, no_link]),
-    meck:expect(emqx_config, get, fun([psk, enable]) -> true;
-                                     ([psk, chunk_size]) -> 50;
+    meck:expect(emqx_config, get, fun([psk_authentication, enable]) -> true;
+                                     ([psk_authentication, chunk_size]) -> 50;
                                      (KeyPath) -> meck:passthrough([KeyPath])
                                   end),
-    meck:expect(emqx_config, get, fun([psk, init_file], _) ->
+    meck:expect(emqx_config, get, fun([psk_authentication, init_file], _) ->
                                          filename:join([code:lib_dir(emqx_psk, test), "data/init.psk"]);
-                                     ([psk, separator], _) -> <<":">>;
+                                     ([psk_authentication, separator], _) -> <<":">>;
                                      (KeyPath, Default) -> meck:passthrough([KeyPath, Default])
                                   end),
     emqx_common_test_helpers:start_apps([emqx_psk]),