doc/man1/openssl-s_time.pod.in - third_party/openssl - Git at Google

 =pod
 {- OpenSSL::safe::output_do_not_edit_headers(); -}

 =head1 NAME

 openssl-s_time - SSL/TLS performance timing program

 =head1 SYNOPSIS

 B<openssl> B<s_time>
 [B<-help>]
 [B<-connect> I<host>:I<port>]
 [B<-www> I<page>]
 [B<-cert> I<filename>]
 [B<-key> I<filename>]
 [B<-reuse>]
 [B<-new>]
 [B<-verify> I<depth>]
 [B<-time> I<seconds>]
 [B<-ssl3>]
 [B<-tls1>]
 [B<-tls1_1>]
 [B<-tls1_2>]
 [B<-tls1_3>]
 [B<-bugs>]
 [B<-cipher> I<cipherlist>]
 [B<-ciphersuites> I<val>]
 {- $OpenSSL::safe::opt_name_synopsis -}
 [B<-cafile> I<file>]
 {- $OpenSSL::safe::opt_trust_synopsis -}
 {- $OpenSSL::safe::opt_provider_synopsis -}

 =head1 DESCRIPTION

 This command implements a generic SSL/TLS client which
 connects to a remote host using SSL/TLS. It can request a page from the server
 and includes the time to transfer the payload data in its timing measurements.
 It measures the number of connections within a given timeframe, the amount of
 data transferred (if any), and calculates the average time spent for one
 connection.

 =head1 OPTIONS

 =over 4

 =item B<-help>

 Print out a usage message.

 =item B<-connect> I<host>:I<port>

 This specifies the host and optional port to connect to.

 =item B<-www> I<page>

 This specifies the page to GET from the server. A value of '/' gets the
 F<index.html> page. If this parameter is not specified, then this command
 will only perform the handshake to establish SSL connections but not transfer
 any payload data.

 =item B<-cert> I<certname>

 The certificate to use, if one is requested by the server. The default is
 not to use a certificate. The file is in PEM format.

 =item B<-key> I<keyfile>

 The private key to use. If not specified then the certificate file will
 be used. The file is in PEM format.

 =item B<-verify> I<depth>

 The verify depth to use. This specifies the maximum length of the
 server certificate chain and turns on server certificate verification.
 Currently the verify operation continues after errors so all the problems
 with a certificate chain can be seen. As a side effect the connection
 will never fail due to a server certificate verify failure.

 =item B<-new>

 Performs the timing test using a new session ID for each connection.
 If neither B<-new> nor B<-reuse> are specified, they are both on by default
 and executed in sequence.

 =item B<-reuse>

 Performs the timing test using the same session ID; this can be used as a test
 that session caching is working. If neither B<-new> nor B<-reuse> are
 specified, they are both on by default and executed in sequence.

 =item B<-bugs>

 There are several known bugs in SSL and TLS implementations. Adding this
 option enables various workarounds.

 =item B<-cipher> I<cipherlist>

 This allows the TLSv1.2 and below cipher list sent by the client to be modified.
 This list will be combined with any TLSv1.3 ciphersuites that have been
 configured. Although the server determines which cipher suite is used it should
 take the first supported cipher in the list sent by the client. See
 L<openssl-ciphers(1)> for more information.

 =item B<-ciphersuites> I<val>

 This allows the TLSv1.3 ciphersuites sent by the client to be modified. This
 list will be combined with any TLSv1.2 and below ciphersuites that have been
 configured. Although the server determines which cipher suite is used it should
 take the first supported cipher in the list sent by the client. See
 L<openssl-ciphers(1)> for more information. The format for this list is a
 simple colon (":") separated list of TLSv1.3 ciphersuite names.

 =item B<-time> I<length>

 Specifies how long (in seconds) this command should establish connections
 and optionally transfer payload data from a server. Server and client
 performance and the link speed determine how many connections it
 can establish.

 {- $OpenSSL::safe::opt_name_item -}

 {- $OpenSSL::safe::opt_trust_item -}

 {- $OpenSSL::safe::opt_provider_item -}

 =item B<-cafile> I<file>

 This is an obsolete synonym for B<-CAfile>.

 =item B<-ssl3>, B<-tls1>, B<-tls1_1>, B<-tls1_2>, B<-tls1_3>

 See L<openssl(1)/TLS Version Options>.

 =back

 =head1 NOTES

 This command can be used to measure the performance of an SSL connection.
 To connect to an SSL HTTP server and get the default page the command

  openssl s_time -connect servername:443 -www / -CApath yourdir -CAfile yourfile.pem -cipher commoncipher [-ssl3]

 would typically be used (https uses port 443). I<commoncipher> is a cipher to
 which both client and server can agree, see the L<openssl-ciphers(1)> command
 for details.

 If the handshake fails then there are several possible causes, if it is
 nothing obvious like no client certificate then the B<-bugs> and
 B<-ssl3> options can be tried
 in case it is a buggy server. In particular you should play with these
 options B<before> submitting a bug report to an OpenSSL mailing list.

 A frequent problem when attempting to get client certificates working
 is that a web client complains it has no certificates or gives an empty
 list to choose from. This is normally because the server is not sending
 the clients certificate authority in its "acceptable CA list" when it
 requests a certificate. By using L<openssl-s_client(1)> the CA list can be
 viewed and checked. However, some servers only request client authentication
 after a specific URL is requested. To obtain the list in this case it
 is necessary to use the B<-prexit> option of L<openssl-s_client(1)> and
 send an HTTP request for an appropriate page.

 If a certificate is specified on the command line using the B<-cert>
 option it will not be used unless the server specifically requests
 a client certificate. Therefore, merely including a client certificate
 on the command line is no guarantee that the certificate works.

 =head1 BUGS

 Because this program does not have all the options of the
 L<openssl-s_client(1)> program to turn protocols on and off, you may not
 be able to measure the performance of all protocols with all servers.

 The B<-verify> option should really exit if the server verification
 fails.

 =head1 HISTORY

 The B<-cafile> option was deprecated in OpenSSL 3.0.

 =head1 SEE ALSO

 L<openssl(1)>,
 L<openssl-s_client(1)>,
 L<openssl-s_server(1)>,
 L<openssl-ciphers(1)>,
 L<ossl_store-file(7)>

 =head1 COPYRIGHT

 Copyright 2004-2021 The OpenSSL Project Authors. All Rights Reserved.

 Licensed under the Apache License 2.0 (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy
 in the file LICENSE in the source distribution or at
 L<https://www.openssl.org/source/license.html>.

 =cut
	=pod
	{- OpenSSL::safe::output_do_not_edit_headers(); -}

	=head1 NAME

	openssl-s_time - SSL/TLS performance timing program

	=head1 SYNOPSIS

	B<openssl> B<s_time>
	[B<-help>]
	[B<-connect> I<host>:I<port>]
	[B<-www> I<page>]
	[B<-cert> I<filename>]
	[B<-key> I<filename>]
	[B<-reuse>]
	[B<-new>]
	[B<-verify> I<depth>]
	[B<-time> I<seconds>]
	[B<-ssl3>]
	[B<-tls1>]
	[B<-tls1_1>]
	[B<-tls1_2>]
	[B<-tls1_3>]
	[B<-bugs>]
	[B<-cipher> I<cipherlist>]
	[B<-ciphersuites> I<val>]
	{- $OpenSSL::safe::opt_name_synopsis -}
	[B<-cafile> I<file>]
	{- $OpenSSL::safe::opt_trust_synopsis -}
	{- $OpenSSL::safe::opt_provider_synopsis -}

	=head1 DESCRIPTION

	This command implements a generic SSL/TLS client which
	connects to a remote host using SSL/TLS. It can request a page from the server
	and includes the time to transfer the payload data in its timing measurements.
	It measures the number of connections within a given timeframe, the amount of
	data transferred (if any), and calculates the average time spent for one
	connection.

	=head1 OPTIONS

	=over 4

	=item B<-help>

	Print out a usage message.

	=item B<-connect> I<host>:I<port>

	This specifies the host and optional port to connect to.

	=item B<-www> I<page>

	This specifies the page to GET from the server. A value of '/' gets the
	F<index.html> page. If this parameter is not specified, then this command
	will only perform the handshake to establish SSL connections but not transfer
	any payload data.

	=item B<-cert> I<certname>

	The certificate to use, if one is requested by the server. The default is
	not to use a certificate. The file is in PEM format.

	=item B<-key> I<keyfile>

	The private key to use. If not specified then the certificate file will
	be used. The file is in PEM format.

	=item B<-verify> I<depth>

	The verify depth to use. This specifies the maximum length of the
	server certificate chain and turns on server certificate verification.
	Currently the verify operation continues after errors so all the problems
	with a certificate chain can be seen. As a side effect the connection
	will never fail due to a server certificate verify failure.

	=item B<-new>

	Performs the timing test using a new session ID for each connection.
	If neither B<-new> nor B<-reuse> are specified, they are both on by default
	and executed in sequence.

	=item B<-reuse>

	Performs the timing test using the same session ID; this can be used as a test
	that session caching is working. If neither B<-new> nor B<-reuse> are
	specified, they are both on by default and executed in sequence.

	=item B<-bugs>

	There are several known bugs in SSL and TLS implementations. Adding this
	option enables various workarounds.

	=item B<-cipher> I<cipherlist>

	This allows the TLSv1.2 and below cipher list sent by the client to be modified.
	This list will be combined with any TLSv1.3 ciphersuites that have been
	configured. Although the server determines which cipher suite is used it should
	take the first supported cipher in the list sent by the client. See
	L<openssl-ciphers(1)> for more information.

	=item B<-ciphersuites> I<val>

	This allows the TLSv1.3 ciphersuites sent by the client to be modified. This
	list will be combined with any TLSv1.2 and below ciphersuites that have been
	configured. Although the server determines which cipher suite is used it should
	take the first supported cipher in the list sent by the client. See
	L<openssl-ciphers(1)> for more information. The format for this list is a
	simple colon (":") separated list of TLSv1.3 ciphersuite names.

	=item B<-time> I<length>

	Specifies how long (in seconds) this command should establish connections
	and optionally transfer payload data from a server. Server and client
	performance and the link speed determine how many connections it
	can establish.

	{- $OpenSSL::safe::opt_name_item -}

	{- $OpenSSL::safe::opt_trust_item -}

	{- $OpenSSL::safe::opt_provider_item -}

	=item B<-cafile> I<file>

	This is an obsolete synonym for B<-CAfile>.

	=item B<-ssl3>, B<-tls1>, B<-tls1_1>, B<-tls1_2>, B<-tls1_3>

	See L<openssl(1)/TLS Version Options>.

	=back

	=head1 NOTES

	This command can be used to measure the performance of an SSL connection.
	To connect to an SSL HTTP server and get the default page the command

	openssl s_time -connect servername:443 -www / -CApath yourdir -CAfile yourfile.pem -cipher commoncipher [-ssl3]

	would typically be used (https uses port 443). I<commoncipher> is a cipher to
	which both client and server can agree, see the L<openssl-ciphers(1)> command
	for details.

	If the handshake fails then there are several possible causes, if it is
	nothing obvious like no client certificate then the B<-bugs> and
	B<-ssl3> options can be tried
	in case it is a buggy server. In particular you should play with these
	options B<before> submitting a bug report to an OpenSSL mailing list.

	A frequent problem when attempting to get client certificates working
	is that a web client complains it has no certificates or gives an empty
	list to choose from. This is normally because the server is not sending
	the clients certificate authority in its "acceptable CA list" when it
	requests a certificate. By using L<openssl-s_client(1)> the CA list can be
	viewed and checked. However, some servers only request client authentication
	after a specific URL is requested. To obtain the list in this case it
	is necessary to use the B<-prexit> option of L<openssl-s_client(1)> and
	send an HTTP request for an appropriate page.

	If a certificate is specified on the command line using the B<-cert>
	option it will not be used unless the server specifically requests
	a client certificate. Therefore, merely including a client certificate
	on the command line is no guarantee that the certificate works.

	=head1 BUGS

	Because this program does not have all the options of the
	L<openssl-s_client(1)> program to turn protocols on and off, you may not
	be able to measure the performance of all protocols with all servers.

	The B<-verify> option should really exit if the server verification
	fails.

	=head1 HISTORY

	The B<-cafile> option was deprecated in OpenSSL 3.0.

	=head1 SEE ALSO

	L<openssl(1)>,
	L<openssl-s_client(1)>,
	L<openssl-s_server(1)>,
	L<openssl-ciphers(1)>,
	L<ossl_store-file(7)>

	=head1 COPYRIGHT

	Copyright 2004-2021 The OpenSSL Project Authors. All Rights Reserved.

	Licensed under the Apache License 2.0 (the "License"). You may not use
	this file except in compliance with the License. You can obtain a copy
	in the file LICENSE in the source distribution or at
	L<https://www.openssl.org/source/license.html>.

	=cut