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)
This commit is contained in:
erbsland-dev 2024-08-28 21:54:12 +02:00 committed by Tomas Mraz
parent d52e92f835
commit 26521fdcf4

View File

@ -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