From 90b07e2c18ba3a36ce842c4828407f72fb390c55 Mon Sep 17 00:00:00 2001 From: Francesco Rollo Date: Tue, 17 Feb 2026 15:31:29 +0100 Subject: [PATCH] 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 Reviewed-by: Jakub Jelen --- include/libssh/server.h | 17 +++++++++++++++++ src/bind_config.c | 7 +++++++ src/options.c | 9 +++++++++ 3 files changed, 33 insertions(+) diff --git a/include/libssh/server.h b/include/libssh/server.h index fb420bf7..7b72ebd8 100644 --- a/include/libssh/server.h +++ b/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); diff --git a/src/bind_config.c b/src/bind_config.c index 77fe8bc4..ea0b41fd 100644 --- a/src/bind_config.c +++ b/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 */ diff --git a/src/options.c b/src/options.c index cfaa4c8e..78a48f8e 100644 --- a/src/options.c +++ b/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,