refactor(server): Warn about config override behavior in bind APIs

- Add a warning to ssh_bind_listen() clarifying that it implicitly
calls ssh_bind_options_parse_config(), which may override options
previously set via ssh_bind_options_set().

- Add a warning to ssh_bind_options_set() and ssh_bind_config_parse_string()
explaining that options may be overridden if configuration files are parsed
afterwards, either implicitly via ssh_bind_listen() or by an explicit call to
ssh_bind_options_parse_config().

Signed-off-by: Francesco <eferollo@gmail.com>
Reviewed-by: Jakub Jelen <jjelen@redhat.com>

include/libssh/server.h

@@ -110,6 +110,23 @@ LIBSSH_API int ssh_bind_config_parse_string(ssh_bind bind, const char *input);
  * @param  ssh_bind_o     The ssh server bind to use.
  *
  * @return 0 on success, < 0 on error.
+ *
+ * @warning This function implicitly calls ssh_bind_options_parse_config()
+ *          to process system-wide and user configuration files unless
+ *          configuration processing was already performed explicitly
+ *          by the caller.\n
+ *          As a result, any options previously set (e.g., manually via
+ *          ssh_bind_options_set() or ssh_bind_config_parse_string()) may be
+ *          overridden by values from the configuration files.\n
+ *          To guarantee that explicitly set options take precedence,
+ *          callers of this function should either:
+ *            - call ssh_bind_options_parse_config() themselves before
+ *              setting options, or
+ *            - disable automatic config processing via
+ *              SSH_BIND_OPTIONS_PROCESS_CONFIG (set to false).
+ *
+ * @see ssh_bind_options_parse_config()
+ * @see ssh_bind_options_set()
  */
 LIBSSH_API int ssh_bind_listen(ssh_bind ssh_bind_o);
 

src/bind_config.c

@@ -683,6 +683,13 @@ int ssh_bind_config_parse_file(ssh_bind bind, const char *filename)
  * @params[in] bind      The ssh bind session
  * @params[in] input     Null terminated string containing the configuration
  *
+ * @warning Options set via this function may be overridden if a configuration
+ *          file is parsed afterwards (e.g., by an implicit call to
+ *          ssh_bind_options_parse_config() inside ssh_bind_listen(), or by a
+ *          manual call to the same function) and contains the same options.\n
+ *          It is the caller’s responsibility to ensure the correct order of
+ *          API calls if explicit options must take precedence.
+ *
  * @returns    SSH_OK on successful parsing the configuration string,
  *             SSH_ERROR on error
  */

src/options.c

@@ -2401,6 +2401,15 @@ static int ssh_bind_set_algo(ssh_bind sshbind,
  *                      not a pointer when it should have been a pointer, or if
  *                      its a pointer to a pointer when it should have just been
  *                      a pointer), then the behaviour is undefined.
+ *
+ * @warning             Options set via this function may be overridden if a
+ *                      configuration file is parsed afterwards (e.g., by an
+ *                      implicit call to ssh_bind_options_parse_config() inside
+ *                      ssh_bind_listen(), or by a manual call to the same
+ *                      function) and contains the same options.\n
+ *                      It is the caller’s responsibility to ensure the correct
+ *                      order of API calls if explicit options must take
+ *                      precedence.
  */
 int
 ssh_bind_options_set(ssh_bind sshbind,