From c31fcf2decfbf1259cc1f3192f0cde9416189510 Mon Sep 17 00:00:00 2001
From: Daniel Stenberg <daniel@haxx.se>
Date: Tue, 31 Mar 2026 10:42:56 +0200
Subject: [PATCH] docs: SSH host verification is done at connect time

Connection reuse is done more "casually" once verified.

Closes #21173
---
 .../opts/CURLOPT_SSH_HOST_PUBLIC_KEY_MD5.md        | 14 ++++++++++++++
 .../opts/CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256.md     | 11 +++++++++++
 docs/libcurl/opts/CURLOPT_SSH_KNOWNHOSTS.md        | 12 ++++++++++++
 3 files changed, 37 insertions(+)

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 0f66f31f12..777b25c4a1 100644
--- 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 e83bf918d7..43a6d9e708 100644
--- 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 cdd45110af..fc7e607771 100644
--- 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