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)

1 files changed, 67 insertions, 7 deletions

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