SSL/TLS Client - Revision history

Jwalton: Make PREFERRED_CIPHERS a constant array.

2022-12-12T15:33:28Z

Make PREFERRED_CIPHERS a constant array.

Jwalton: Add info about demos/sslecho to introduction.

2022-04-24T23:58:59Z

Add info about demos/sslecho to introduction.

Philippe lhardy: demos/sslecho and Simple TLS Client

2022-04-24T20:13:06Z

demos/sslecho and Simple TLS Client

Jwalton: Add additional citation

2018-02-18T04:05:34Z

Add additional citation

Jwalton: Add additional information on 0-RTT risk.

2017-06-13T21:12:01Z

Add additional information on 0-RTT risk.

Jwalton: /* Session Tickets */

2017-06-13T21:05:49Z

Session Tickets

Jwalton: Add additional information.

2017-02-11T00:29:41Z

Add additional information.

Jwalton: /* Session Reuse */

2016-11-16T20:44:28Z

Session Reuse

Jwalton: Add ChaCha/Poly1305.

2016-10-15T10:32:48Z

Add ChaCha/Poly1305.

Jwalton: Add info on RFC 4158.

2016-10-14T04:57:22Z

Add info on RFC 4158.

@@ Line 55: / Line 55: @@
 if(!(ssl != NULL)) handleFailure();
-const char* const PREFERRED_CIPHERS = "HIGH:!aNULL:!kRSA:!PSK:!SRP:!MD5:!RC4";
+const char PREFERRED_CIPHERS[] = "HIGH:!aNULL:!kRSA:!PSK:!SRP:!MD5:!RC4";
 res = SSL_set_cipher_list(ssl, PREFERRED_CIPHERS);
 if(!(1 == res)) handleFailure();

@@ Line 7: / Line 7: @@
 The code below does '''not''' perform hostname verification. OpenSSL prior to 1.1.0 does not perform the check, and you must perform the check yourself. The OpenSSL [http://www.openssl.org/news/changelog.html Change Log] for OpenSSL 1.1.0 states you can use <tt>-verify_name</tt> option, and <tt>apps.c</tt> offers <tt>-verify_hostname</tt>. But <tt>s_client</tt> does not respond to either switch, so its unclear how hostname checking will be implemented or invoked for a client. '''Note (N.B.)''': hostname verification is marked as experimental, so switches, options, and implementations could change.
-Finally, if you are looking for guidance on which protocols and ciphers you should be using, then see Adam Langley's blog [http://www.imperialviolet.org/2014/12/08/poodleagain.html The POODLE bites again]. The short version: use only TLS 1.2, use only ephemeral key exchanges, and use only AEAD ciphers (like AES/GCM, Camellia/GCM, ChaCha/Poly1305).
+If you are looking for guidance on which protocols and ciphers you should be using, then see Adam Langley's blog [http://www.imperialviolet.org/2014/12/08/poodleagain.html The POODLE bites again]. The short version: use only TLS 1.2, use only ephemeral key exchanges, and use only AEAD ciphers (like AES/GCM, Camellia/GCM, ChaCha/Poly1305).
 == Implementation ==
 The code below demonstrates a basic client that uses BIOs and TLS to connect to <tt>www.random.org</tt>, and fetches 32 bytes of random data through an HTTP request. The sample code is available for download below.

← Older revision		Revision as of 20:13, 24 April 2022
Line 10:		Line 10:

	== Implementation ==		== Implementation ==
		+
		+	You may find an up to date example within repository demos/sslecho and [[Simple TLS Client]]

	The code below demonstrates a basic client that uses BIOs and TLS to connect to <tt>www.random.org</tt>, and fetches 32 bytes of random data through an HTTP request. The sample code is available for download below.		The code below demonstrates a basic client that uses BIOs and TLS to connect to <tt>www.random.org</tt>, and fetches 32 bytes of random data through an HTTP request. The sample code is available for download below.

@@ Line 332: / Line 332: @@
 -RTT is specified in XXX (TODO). 0-RTT allows an application to immediately resume a previous session at the expense of consuming unauthenticated data. You should avoid 0-RTT if possible. In fact, an organization's data security policy may not allow it for some higher data sensitivity levels.
-Care should be taken if enabling 0-RTT at the client because a number of protections must be enabled at the server. Additionally, some of the protections are required higher up in the stack, outside of the secure socket layer. Below is a list of potential problems from [http://www.ietf.org/mail-archive/web/tls/current/msg23561.html Closing on 0-RTT] on the IETF TLS working group mailing list.
+Care should be taken if enabling 0-RTT at the client because a number of protections must be enabled at the server. Additionally, some of the protections are required higher up in the stack, outside of the secure socket layer. Below is a list of potential problems from [http://www.ietf.org/mail-archive/web/tls/current/msg15594.html 0-RTT and Anti-Replay] and [http://www.ietf.org/mail-archive/web/tls/current/msg23561.html Closing on 0-RTT] on the IETF TLS working group mailing list.
 * 0-RTT without stateful anti-replay allows for very high number of replays, breaking rate limiting systems, even high-performance ones, resulting in an opening for DDoS attacks.

@@ Line 343: / Line 343: @@
 * 0-RTT allows easily reordering request with re-transmission from the client. This can lead to various unexpected application behavior if possibility of such reordering is not taken into account. "Eventually consistent" datastores are especially vulnerable.
 == Downloads ==
 [[Media:openssl-bio-fetch.tar.gz|openssl-bio-fetch.tar.gz]] - The program and Makefile used for this wiki page.

@@ Line 327: / Line 327: @@
 <pre>const long flags = SSL_OP_NO_SSLv3 | ... | SSL_OP_NO_TICKET;
 SSL_CTX_set_options(ctx, flags);</pre>
 == Downloads ==
 [[Media:openssl-bio-fetch.tar.gz|openssl-bio-fetch.tar.gz]] - The program and Makefile used for this wiki page.

← Older revision		Revision as of 00:29, 11 February 2017
Line 151:		Line 151:

	'''<tt>SSL_CTX_new</tt>''' uses the <tt>SSLv23_method</tt> method to create a new '''SSL/TLS context object'''. If you use, for example <tt>TLSv1_method</tt>, then you will only use TLS v1.0, and if you use <tt>TLSv1_1_method</tt> then you will only use TLS v1.1. Typically you should always use '''<tt>SSLv23_method</tt>''' in preference to the version specific methods.		'''<tt>SSL_CTX_new</tt>''' uses the <tt>SSLv23_method</tt> method to create a new '''SSL/TLS context object'''. If you use, for example <tt>TLSv1_method</tt>, then you will only use TLS v1.0, and if you use <tt>TLSv1_1_method</tt> then you will only use TLS v1.1. Typically you should always use '''<tt>SSLv23_method</tt>''' in preference to the version specific methods.
		+
		+	OpenSSL 1.1.0 improves protocol selection by providing <tt>SSL_CTX_set_max_proto_version()</tt> and <tt>SSL_CTX_set_min_proto_version()</tt>. You no longer need to subtract unwanted options with <tt>SSL_OP_NO_SSLv2</tt> and <tt>SSL_OP_NO_SSLv3</tt>. Also see the [http://www.openssl.org/docs/man1.1.0/ssl/SSL_CTX_set_max_proto_version.html <tt>SSL_CTX_set_max_proto_version()</tt> and <tt>SSL_CTX_set_min_proto_version()</tt> man pages].

	== Options (1) ==		== Options (1) ==

@@ Line 75: / Line 75: @@
 /* Step 2: verify the result of chain verification */
 res = SSL_get_verify_result(ssl);
 if(!(X509_V_OK == res)) handleFailure();
@@ Line 160: / Line 161: @@
 * <tt>SSL_CTX_load_verify_locations</tt>
-'''<tt>SSL_CTX_set_verify</tt>''' sets the <tt>SSL_VERIFY_PEER</tt> flag and the verify callback so certificate chain Issuer and Subject information can be printed. If you don't want to perform custom processing (such as printing or checking), then don't set the callback. OpenSSL's default checking should be sufficient, so pass <tt>NULL</tt> to <tt>SSL_CTX_set_verify</tt>.
+'''<tt>SSL_CTX_set_verify</tt>''' sets the <tt>SSL_VERIFY_PEER</tt> flag and the verify callback. This ensures the chain is verified according to [http://tools.ietf.org/html/rfc4158 RFC 4158] and Issuer and Subject information can be printed. If you don't want to perform custom processing (such as printing or checking), then don't set the callback. OpenSSL's default checking should be sufficient, so pass <tt>NULL</tt> to <tt>SSL_CTX_set_verify</tt>.
 There is also a <tt>SSL_VERIFY_FAIL_IF_NO_PEER_CERT</tt> flag, but it is used for servers and has no effect on clients. If you accidentally use <tt>SSL_VERIFY_FAIL_IF_NO_PEER_CERT</tt>, then you chain will always verify when call <tt>SSL_get_verify_result</tt> because the flag is ignored for clients (essentially, 0 is passed for the flag which performs no verification).