From 26521fdcf4047d6b6c5a7cf14ac34323a6197266 Mon Sep 17 00:00:00 2001
From: erbsland-dev <github@erbsland.dev>
Date: Wed, 28 Aug 2024 21:54:12 +0200
Subject: [PATCH] Add note for non-interactive use of `s_client`

Fixes #8018

Documented the potential issue of premature connection closure in
non-interactive environments, such as cron jobs, when using `s_client`.

Added guidance on using the `-ign_eof` option and input redirection to
ensure proper handling of `stdin` and completion of TLS session data exchange.

Highlight potential issues with the `-ign_eof` flag and provide solutions for
graceful disconnection in SMTP and HTTP/1.1 scenarios to avoid indefinite hangs.

Reviewed-by: Paul Dale <ppzgs1@gmail.com>
Reviewed-by: Viktor Dukhovni <viktor@openssl.org>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/25311)
---
 doc/man1/openssl-s_client.pod.in | 45 ++++++++++++++++++++++++++++++++
 1 file changed, 45 insertions(+)

diff --git a/doc/man1/openssl-s_client.pod.in b/doc/man1/openssl-s_client.pod.in
index a9280b8e6f..2479026536 100644
--- a/doc/man1/openssl-s_client.pod.in
+++ b/doc/man1/openssl-s_client.pod.in
@@ -1007,6 +1007,51 @@ option: any verify errors are then returned aborting the handshake.
 The B<-bind> option may be useful if the server or a firewall requires
 connections to come from some particular address and or port.
 
+=head2 Note on Non-Interactive Use
+
+When B<s_client> is run in a non-interactive environment (e.g., a cron job or
+a script without a valid I<stdin>), it may close the connection prematurely,
+especially with TLS 1.3. To prevent this, you can use the B<-ign_eof> flag,
+which keeps B<s_client> running even after reaching EOF from I<stdin>.
+
+For example:
+
+ openssl s_client -connect <server address>:443 -tls1_3
+                  -sess_out /path/to/tls_session_params_file
+                  -ign_eof </dev/null
+
+However, relying solely on B<-ign_eof> can lead to issues if the server keeps
+the connection open, expecting the client to close first. In such cases, the
+client may hang indefinitely. This behavior is not uncommon, particularly with
+protocols where the server waits for a graceful disconnect from the client.
+
+For example, when connecting to an SMTP server, the session may pause if the
+server expects a QUIT command before closing:
+
+ $ openssl s_client -brief -ign_eof -starttls smtp
+                    -connect <server address>:25 </dev/null
+ CONNECTION ESTABLISHED
+ Protocol version: TLSv1.3
+ Ciphersuite: TLS_AES_256_GCM_SHA384
+ ...
+ 250 CHUNKING
+ [long pause]
+
+To avoid such hangs, it's better to use an application-level command to
+initiate a clean disconnect. For SMTP, you can send a QUIT command:
+
+ printf 'QUIT\r\n' | openssl s_client -connect <server address>:25
+                                      -starttls smtp -brief -ign_eof
+
+Similarly, for HTTP/1.1 connections, including a `Connection: close` header
+ensures the server closes the connection after responding:
+
+ printf 'GET / HTTP/1.1\r\nHost: <server address>\r\nConnection: close\r\n\r\n'
+     | openssl s_client -connect <server address>:443 -brief
+
+These approaches help manage the connection closure gracefully and prevent
+hangs caused by the server waiting for the client to initiate the disconnect.
+
 =head1 BUGS
 
 Because this program has a lot of options and also because some of the