New Groups support

.drone.jsonnet

@@ -285,9 +285,9 @@ local static_build(name,
         'echo "Building on ${DRONE_STAGE_MACHINE}"',
         apt_get_quiet + ' update',
         apt_get_quiet + ' install -y python3-requests rsync',
-        'npm i docsify-cli -g',
-        'npm i docsify -g',
+        'npm i docsify-cli docsify-themeable [email protected] katex marked@4',
         'cd docs/api/',
+        'export NODE_PATH=node_modules',
         'make',
         '../../utils/ci/drone-docs-upload.sh',
       ],

docs/api/api-to-markdown.py

@@ -47,6 +47,7 @@
 #
 # "Inputs: none."
 # "Outputs: none."
+# "Member variable."
 # "Inputs:" followed by markdown (typically an unordered list) until the next match from this list.
 # "Outputs:" followed by markdown
 # "Example input:" followed by a code block (i.e. containing json)
@@ -91,6 +92,7 @@
 DEV_RPC_START = re.compile(r"^Dev-API:\s*([\w/:]+)(.*)$")
 IN_NONE = re.compile(r"^Inputs?: *[nN]one\.?$")
 IN_SOME = re.compile(r"^Inputs?:\s*$")
+MEMBER_VAR = re.compile(r"^Member +[vV]ar(?:iable)?\.?$")
 DECL_SOME = re.compile(r"^Declaration?:\s*$")
 OUT_SOME = re.compile(r"^Outputs?:\s*$")
 EXAMPLE_IN = re.compile(r"^Example [iI]nputs?:\s*$")
@@ -159,6 +161,7 @@ class Parsing(Enum):
     description, decl, inputs, outputs = "", "", "", ""
     done_desc = False
     no_inputs = False
+    member_var = False
     examples = []
     cur_ex_in = None
     old_names = []
@@ -194,6 +197,9 @@ class Parsing(Enum):
                 error("found multiple Inputs:")
             inputs, no_inputs, mode = MD_NO_INPUT, True, Parsing.NONE
 
+        elif re.search(MEMBER_VAR, line):
+            member_var, no_inputs, mode = True, True, Parsing.DESC
+
         elif re.search(DECL_SOME, line):
             if inputs:
                 error("found multiple Syntax:")
@@ -285,7 +291,7 @@ class Parsing(Enum):
     # We hit the end of the commented section
     if not description or inputs.isspace():
         problems.append("endpoint has no description")
-    if not inputs or inputs.isspace():
+    if (not inputs or inputs.isspace()) and not member_var:
         problems.append(
             "endpoint has no inputs description; perhaps you need to add 'Inputs: none.'?"
         )
@@ -321,7 +327,9 @@ class Parsing(Enum):
 {MD_DECL_HEADER}
 
 {decl}
-
+"""
+    if not member_var:
+        md = md + f"""
 {MD_INPUT_HEADER}
 
 {inputs}

docs/api/static/sidebar.md

@@ -4,6 +4,7 @@
 - [Convo Info Volatile](convo_info_volatile.md)
 - [Encrypt](encrypt.md)
 - [Error](error.md)
+- [Groups](groups.md)
 - [User Groups](user_groups.md)
 - [User Profile](user_profile.md)
 - [Utils](util.md)

include/session/config.hpp

@@ -60,6 +60,11 @@ struct missing_signature : signature_error {
 struct config_parse_error : config_error {
     using config_error::config_error;
 };
+/// Type thrown for some bad value in a config (e.g. missing required key, or key with an
+/// unexpected/unhandled value).
+struct config_value_error : config_parse_error {
+    using config_parse_error::config_parse_error;
+};
 
 /// Class for a parsed, read-only config message; also serves as the base class of a
 /// MutableConfigMessage which allows setting values.
@@ -87,7 +92,7 @@ class ConfigMessage {
     /// (so that they can return a reference to it).
     seqno_hash_t seqno_hash_{0, {0}};
 
-    bool verified_signature_ = false;
+    std::optional<std::array<unsigned char, 64>> verified_signature_;
 
     // This will be set during construction from configs based on the merge result:
     // -1 means we had to merge one or more configs together into a new merged config
@@ -123,7 +128,7 @@ class ConfigMessage {
             verify_callable verifier = nullptr,
             sign_callable signer = nullptr,
             int lag = DEFAULT_DIFF_LAGS,
-            bool signature_optional = false);
+            bool trust_signature = false);
 
     /// Constructs a new ConfigMessage by loading and potentially merging multiple serialized
     /// ConfigMessages together, according to the config conflict resolution rules.  The result
@@ -147,10 +152,6 @@ class ConfigMessage {
     /// diffs that exceeding this lag value will have those early lagged diffs dropping during
     /// loading.
     ///
-    /// signature_optional - if true then accept a message with no signature even when a verifier is
-    /// set, thus allowing unsigned messages (though messages with an invalid signature are still
-    /// not allowed).  This option is ignored when verifier is not set.
-    ///
     /// error_handler - if set then any config message parsing error will be passed to this function
     /// for handling with the index of `configs` that failed and the error exception: the callback
     /// typically warns and, if the overall construction should abort, rethrows the error.  If this
@@ -163,7 +164,6 @@ class ConfigMessage {
             verify_callable verifier = nullptr,
             sign_callable signer = nullptr,
             int lag = DEFAULT_DIFF_LAGS,
-            bool signature_optional = false,
             std::function<void(size_t, const config_error&)> error_handler = nullptr);
 
     /// Returns a read-only reference to the contained data.  (To get a mutable config object use
@@ -211,10 +211,13 @@ class ConfigMessage {
     /// data), this will return -1.
     int unmerged_index() const { return unmerged_; }
 
-    /// Returns true if this message contained a valid, verified signature when it was parsed.
-    /// Returns false otherwise (e.g. not loaded from verification at all; loaded without a
-    /// verification function; or had no signature and a signature wasn't required).
-    bool verified_signature() const { return verified_signature_; }
+    /// Read-only access to the optional verified signature if this message contained a valid,
+    /// verified signature when it was parsed.  Returns nullopt otherwise (e.g. not loaded from
+    /// verification at all; loaded without a verification function; or had no signature and a
+    /// signature wasn't required).
+    const std::optional<std::array<unsigned char, 64>>& verified_signature() {
+        return verified_signature_;
+    }
 
     /// Constructs a new MutableConfigMessage from this config message with an incremented seqno.
     /// The new config message's diff will reflect changes made after this construction.
@@ -283,7 +286,6 @@ class MutableConfigMessage : public ConfigMessage {
             verify_callable verifier = nullptr,
             sign_callable signer = nullptr,
             int lag = DEFAULT_DIFF_LAGS,
-            bool signature_optional = false,
             std::function<void(size_t, const config_error&)> error_handler = nullptr);
 
     /// Wrapper around the above that takes a single string view to load a single message, doesn't
@@ -293,8 +295,7 @@ class MutableConfigMessage : public ConfigMessage {
             ustring_view config,
             verify_callable verifier = nullptr,
             sign_callable signer = nullptr,
-            int lag = DEFAULT_DIFF_LAGS,
-            bool signature_optional = false);
+            int lag = DEFAULT_DIFF_LAGS);
 
     /// Does the same as the base incrementing, but also records any diff info from the current
     /// MutableConfigMessage.  *this* object gets pruned and signed as part of this call.  If the
@@ -342,6 +343,48 @@ class MutableConfigMessage : public ConfigMessage {
     void increment_impl();
 };
 
+/// API: base/verify_config_sig
+///
+/// Verifies a config message signature, throwing a missing_signature or signature_error exception
+/// if the signature is missing or invalid.
+///
+/// A config message signature is always in the "~" key of a config message, which must be the
+/// very last key of the message, and signs the config value up to (but not including) the ~
+/// key-value pair in the serialized config message.
+///
+/// For instance, for a config message of:
+///
+///     d[...configdata...]1:~64:[sigdata]e
+///
+/// the signature signs the value `d[...configdata...]` (i.e. the `1:~64:[sigdata]` signature
+/// pair, and the final closing `e` of the config message, are not included).  No keys may
+/// follow the signature key/value.
+///
+/// Inputs:
+/// - `dict` -- a `bt_dict_consumer` positioned at or before the "~" key where the signature is
+///   expected.  (If the bt_dict_consumer has already consumed the "~" key then this call will fail
+///   as if the signature was missing).
+/// - `config_msg` -- the full config message; this must be a view of the same data in memory that
+///   `dict` is parsing (i.e. it cannot be a copy).
+/// - `verifier` -- a callback to invoke to verify the signature of the message.  If the callback is
+///   empty then the signature will be ignored (it is neither required nor verified).
+/// - `verified_signature` is a pointer to a std::optional array of signature data; if this is
+///   specified and not nullptr then the optional with be emplaced with the signature bytes if the
+///   signature successfully validates.
+/// - `trust_signature` bypasses the verification and signature requirements, blinding trusting a
+///   signature if present.  This is intended for use when restoring from a dump (along with a
+///   nullptr verifier).
+///
+/// Outputs:
+/// - returns with no value on success
+/// - throws on failure
+void verify_config_sig(
+        oxenc::bt_dict_consumer dict,
+        ustring_view config_msg,
+        const ConfigMessage::verify_callable& verifier,
+        std::optional<std::array<unsigned char, 64>>* verified_signature = nullptr,
+        bool trust_signature = false);
+
 }  // namespace session::config
 
 namespace oxenc::detail {

include/session/config/base.h

@@ -281,6 +281,27 @@ typedef struct config_string_list {
 /// - `config_string_list*` -- point to the list of hashes, pointer belongs to the caller
 LIBSESSION_EXPORT config_string_list* config_current_hashes(const config_object* conf);
 
+/// API: base/config_get_keys
+///
+/// Obtains the current group decryption keys.
+///
+/// Returns a buffer where each consecutive 32 bytes is an encryption key for the object, in
+/// priority order (i.e. the key at 0 is the encryption key, and the first decryption key).
+///
+/// This function is mainly for debugging/diagnostics purposes; most config types have one single
+/// key (based on the secret key), and multi-keyed configs such as groups have their own methods for
+/// encryption/decryption that are already aware of the multiple keys.
+///
+/// Inputs:
+/// - `conf` -- [in] Pointer to the config_object object
+/// - `len` -- [out] Pointer where the number of keys will be written (that is: the returned pointer
+///   will be to a buffer which has a size of of this value times 32).
+///
+/// Outputs:
+/// - `unsigned char*` -- pointer to newly malloced key data (a multiple of 32 bytes); the pointer
+///   belongs to the caller and must be `free()`d when done with it.
+LIBSESSION_EXPORT unsigned char* config_get_keys(const config_object* conf, size_t* len);
+
 /// Config key management; see the corresponding method docs in base.hpp.  All `key` arguments here
 /// are 32-byte binary buffers (and since fixed-length, there is no keylen argument).
 
@@ -446,6 +467,59 @@ LIBSESSION_EXPORT const unsigned char* config_key(const config_object* conf, siz
 /// - `char*` -- encryption domain C-str used to encrypt values
 LIBSESSION_EXPORT const char* config_encryption_domain(const config_object* conf);
 
+/// API: base/config_set_sig_keys
+///
+/// Sets an Ed25519 keypair pair for signing and verifying config messages.  When set, this adds an
+/// additional signature for verification into the config message (*after* decryption) that
+/// validates a config message.
+///
+/// This is used in config contexts where the encryption/decryption keys are insufficient for
+/// permission verification to produce new messages, such as in groups where non-admins need to be
+/// able to decrypt group data, but are not permitted to push new group data.  In such a case only
+/// the admins have the secret key with which messages can be signed; regular users can only read,
+/// but cannot write, config messages.
+///
+/// When a signature public key (with or without a secret key) is set the config object enters a
+/// "signing-required" mode, which has some implications worth noting:
+/// - incoming messages must contain a signature that verifies with the public key; messages
+///   without such a signature will be dropped as invalid.
+/// - because of the above, a config object cannot push config updates without the secret key:
+///   thus any attempt to modify the config message with a pubkey-only config object will raise
+///   an exception.
+///
+/// Inputs:
+/// - `secret` -- pointer to a 64-byte sodium-style Ed25519 "secret key" buffer (technically the
+///   seed+precomputed pubkey concatenated together) that sets both the secret key and public key.
+LIBSESSION_EXPORT void config_set_sig_keys(config_object* conf, const unsigned char* secret);
+
+/// API: base/config_set_sig_pubkey
+///
+/// Sets a Ed25519 signing pubkey which incoming messages must be signed by to be acceptable.  This
+/// is intended for use when the secret key is not known (see `config_set_sig_keys()` to set both
+/// secret and pubkey keys together).
+///
+/// Inputs:
+/// - `pubkey` -- pointer to the 32-byte Ed25519 pubkey that must have signed incoming messages.
+LIBSESSION_EXPORT void config_set_sig_pubkey(config_object* conf, const unsigned char* pubkey);
+
+/// API: base/config_get_sig_pubkey
+///
+/// Returns a pointer to the 32-byte Ed25519 signing pubkey, if set.  Returns nullptr if there is no
+/// current signing pubkey.
+///
+/// Inputs: none.
+///
+/// Outputs:
+/// - pointer to the 32-byte pubkey, or NULL if not set.
+LIBSESSION_EXPORT const unsigned char* config_get_sig_pubkey(const config_object* conf);
+
+/// API: base/config_clear_sig_keys
+///
+/// Drops the signature pubkey and/or secret key, if the object has them.
+///
+/// Inputs: none.
+LIBSESSION_EXPORT void config_clear_sig_keys(config_object* conf);
+
 #ifdef __cplusplus
 }  // extern "C"
 #endif