Add some documentation for the new advanced s_client command mode

Reviewed-by: Tomas Mraz <tomas@openssl.org>
Reviewed-by: Paul Dale <pauli@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/20566)

2 files changed, 76 insertions, 7 deletions

diff --git a/CHANGES.md b/CHANGES.md
index 9fa63ea7f0..f1d204b2b4 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -25,6 +25,15 @@ OpenSSL 3.2
 
 ### Changes between 3.1 and 3.2 [xx XXX xxxx]
 
+ * Added an "advanced" command mode to s_client. Use this with the "-adv"
+   option. The old "basic" command mode recognises certain letters that must
+   always appear at the start of a line and cannot be escaped. The advanced
+   command mode enables commands to be entered anywhere and there is an
+   escaping mechanism. After starting s_client with "-adv" type "{help}"
+   to show a list of available commands.
+
+   *Matt Caswell*
+
  * Add Raw Public Key (RFC7250) support. Authentication is supported
    by matching keys against either local policy (TLSA records synthesised
    from the expected keys) or DANE (TLSA records obtained by the
diff --git a/doc/man1/openssl-s_client.pod.in b/doc/man1/openssl-s_client.pod.in
index aa785d8b2f..d05183737d 100644
--- a/doc/man1/openssl-s_client.pod.in
+++ b/doc/man1/openssl-s_client.pod.in
@@ -52,6 +52,7 @@ B<openssl> B<s_client>
 [B<-debug>]
 [B<-trace>]
 [B<-nocommands>]
+[B<-adv>]
 [B<-security_debug>]
 [B<-security_debug_verbose>]
 [B<-msg>]
@@ -442,6 +443,10 @@ Print extensive debugging information including a hex dump of all traffic.
 
 Do not use interactive command letters.
 
+=item B<-adv>
+
+Use advanced command mode.
+
 =item B<-security_debug>
 
 Enable security debug messages.
@@ -852,15 +857,18 @@ I<localhost> on port I<4433>.
 
 =back
 
-=head1 CONNECTED COMMANDS
+=head1 CONNECTED COMMANDS (BASIC)
 
-If a connection is established with an SSL server then any data received
+If a connection is established with an SSL/TLS server then any data received
 from the server is displayed and any key presses will be sent to the
-server. If end of file is reached then the connection will be closed down. When
-used interactively (which means neither B<-quiet> nor B<-ign_eof> have been
-given), then certain commands are also recognized which perform special
-operations. These commands are a letter which must appear at the start of a
-line. They are listed below.
+server. If end of file is reached then the connection will be closed down.
+
+When used interactively (which means neither B<-quiet> nor B<-ign_eof> have been
+given), and neither of B<-adv> or B<-nocommands> are given then "Basic" command
+mode is entered. In this mode certain commands are recognized which perform
+special operations. These commands are a letter which must appear at the start
+of a line. All further data after the initial letter on the line is ignored.
+The commands are listed below.
 
 =over 4
 
@@ -872,6 +880,10 @@ End the current SSL connection and exit.
 
 Renegotiate the SSL session (TLSv1.2 and below only).
 
+=item B<C>
+
+Attempt to reconnect to the server using a resumption handshake.
+
 =item B<k>
 
 Send a key update message to the server (TLSv1.3 only)
@@ -882,6 +894,54 @@ Send a key update message to the server and request one back (TLSv1.3 only)
 
 =back
 
+=head1 CONNECTED COMMANDS (ADVANCED)
+
+If B<-adv> has been given then "advanced" command mode is entered. As with basic
+mode, if a connection is established with an SSL/TLS server then any data
+received from the server is displayed and any key presses will be sent to the
+server. If end of file is reached then the connection will be closed down.
+
+Special commands can be supplied by enclosing them in braces, e.g. "{help}" or
+"{quit}". These commands can appear anywhere in the text entered into s_client,
+but they are not sent to the server. Some commands can take an argument by
+ending the command name with ":" and then providing the argument, e.g.
+"{keyup:req}". Some commands are only available when certain protocol versions
+have been negotiated.
+
+If a newline appears at the end of a line entered into s_client then this is
+also sent to the server. If a command appears on a line on its own with no other
+text on the same line, then the newline is suppressed and not sent to the
+server.
+
+The following commands are recognised.
+
+=over 4
+
+=item B<help>
+
+Prints out summary help text about the available commands.
+
+=item B<quit>
+
+Close the connection to the peer
+
+=item B<reconnect>
+
+Reconnect to the peer and attempt a resumption handshake
+
+=item B<keyup>
+
+Send a Key Update message. TLSv1.3 only. This command takes an optional
+argument. If the argument "req" is supplied then the peer is also requested to
+update its keys. Otherwise if "noreq" is supplied the the peer is not requested
+to update its keys. The default is "req".
+
+=item B<reneg>
+
+Initiate a renegotiation with the server. (D)TLSv1.2 or below only.
+
+=back
+
 =head1 NOTES
 
 This command can be used to debug SSL servers. To connect to an SSL HTTP