docs: SSH host verification is done at connect time

Connection reuse is done more "casually" once verified.

Closes #21173

diff --git a/docs/libcurl/opts/CURLOPT_SSH_HOST_PUBLIC_KEY_MD5.md b/docs/libcurl/opts/CURLOPT_SSH_HOST_PUBLIC_KEY_MD5.md
index 0f66f31f12ab067b19dbbb17db572db84c7228d9..777b25c4a1ba24cb3160443b69ea4ad8cfad1b3e 100644 (file)
--- a/docs/libcurl/opts/CURLOPT_SSH_HOST_PUBLIC_KEY_MD5.md
+++ b/docs/libcurl/opts/CURLOPT_SSH_HOST_PUBLIC_KEY_MD5.md
@@ -43,6 +43,20 @@ option.
 Using this option multiple times makes the last set string override the
 previous ones. Set it to NULL to disable its use again.
 
+This option is only applied when libcurl creates a new SSH connection. Once a
+connection has been created and successfully verified with this MD5 check, it
+is deemed vetted and may be reused by libcurl without performing the MD5
+verification again, even if you later change or disable this option or switch
+to other verification mechanisms such as CURLOPT_SSH_KNOWNHOSTS(3) or
+CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256(3). Any such changes only affect future new
+connections, not already established ones.
+
+When MD5 verification is enabled for a connection via this option, libcurl
+uses that MD5-based check instead of the known hosts/host key callback
+verification path for that connection, so you must not assume that both the
+MD5 check and the known hosts/host key callback verification are performed for
+the same connection.
+
 # DEFAULT
 
 NULL

diff --git a/docs/libcurl/opts/CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256.md b/docs/libcurl/opts/CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256.md
index e83bf918d79b5dc8e78d1dd63ce7febcbdf809b5..43a6d9e708e5734b9832f0d764316a5dafeda0ba 100644 (file)
--- a/docs/libcurl/opts/CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256.md
+++ b/docs/libcurl/opts/CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256.md
@@ -39,6 +39,17 @@ option.
 Using this option multiple times makes the last set string override the
 previous ones. Set it to NULL to disable its use again.
 
+This option is used to verify a new connection only. The SHA256 hash check is
+performed when libcurl establishes a new SSH connection; once that connection
+has been successfully verified, it is deemed vetted and may be reused without
+performing the SHA256 (or any other host key) verification again, even if you
+subsequently change SSH verification-related options. When this SHA256-based
+verification is enabled for a new connection, libcurl does not additionally
+consult CURLOPT_SSH_KNOWNHOSTS(3) or SSH host key callbacks (including
+CURLOPT_SSH_HOST_PUBLIC_KEY_MD5(3)) for that connection, so you should not
+expect multiple host verification methods to be applied to the same new
+connection.
+
 # DEFAULT
 
 NULL

diff --git a/docs/libcurl/opts/CURLOPT_SSH_KNOWNHOSTS.md b/docs/libcurl/opts/CURLOPT_SSH_KNOWNHOSTS.md
index cdd45110afbb83ec3565c0d0de9406097068d44e..fc7e60777147811afa193a1fd77cb84fbf3ee059 100644 (file)
--- a/docs/libcurl/opts/CURLOPT_SSH_KNOWNHOSTS.md
+++ b/docs/libcurl/opts/CURLOPT_SSH_KNOWNHOSTS.md
@@ -45,6 +45,18 @@ option.
 Using this option multiple times makes the last set string override the
 previous ones. Set it to NULL to disable its use again.
 
+This option is only consulted when libcurl establishes a new connection. Once
+a connection has been created and its host key verified against the known
+hosts file, it is deemed vetted and may be reused by libcurl without
+re-running the known hosts check, even if you later change SSH host
+verification options (including setting this option to NULL or using
+CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256(3) or CURLOPT_SSH_HOST_PUBLIC_KEY_MD5(3)).
+Such changes only affect subsequently created connections; existing cached
+connections can continue to be reused with the verification that was in effect
+when they were first established. If you need to force re-verification with
+the new settings, use CURLOPT_FRESH_CONNECT(3) or CURLOPT_FORBID_REUSE(3) to
+avoid reusing the old connection.
+
 # DEFAULT
 
 NULL