mars_nwe/mars-matrixssl
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
Files
e05dfbf65050c13ae02ca41cd6cae575e5403a28
mars-matrixssl/doc/matrixssl_dev_guide.html
Arto Niemi 7c741e9005 MatrixSSL 3.9.0
2017-03-10 17:29:32 +02:00

2006 lines
206 KiB
HTML
Raw Blame History

This file contains invisible Unicode characters
This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>matrixssl_dev_guide</title>
<link rel="stylesheet" href="html/css/base.css" />
</head>
<body>
<h1 id="matrixssl-developers-guide">MatrixSSL Developer’s Guide</h1>
<p><img src="http://www.insidesecure.com/extension/isinside/design/front/images/logo.png" alt="INSIDE Secure" title=""></p>
<p><strong>Version 3.9</strong> <br>
<em>© INSIDE Secure - 2017 - All Rights Reserved</em></p>
<p><div class="toc">
<ul>
<li><a href="#matrixssl-developers-guide">MatrixSSL Developer’s Guide</a></li>
<li><a href="#1-overview">1 OVERVIEW </a><ul>
<li><a href="#11-nomenclature">1.1 Nomenclature </a></li>
<li><a href="#12-supported-rfcs">1.2 Supported RFCs </a></li>
<li><a href="#13-currently-unsupported-rfcs">1.3 Currently Unsupported RFCs</a></li>
<li><a href="#14-supported-cipher-suites">1.4 Supported Cipher Suites </a></li>
</ul>
</li>
<li><a href="#2-security-considerations">2 SECURITY CONSIDERATIONS </a><ul>
<li><a href="#21-ssltls-version-security">2.1 SSL/TLS Version Security </a></li>
<li><a href="#22-selecting-cipher-suites">2.2 Selecting Cipher Suites </a></li>
<li><a href="#23-authentication-mode">2.3 Authentication Mode</a></li>
<li><a href="#24-authentication-and-key-exchange">2.4 Authentication and Key Exchange </a><ul>
<li><a href="#241-server-and-client-authentication">2.4.1 Server and Client Authentication</a></li>
<li><a href="#242-certificate-validation-and-authentication">2.4.2 Certificate Validation and Authentication</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="#3-application-integration-flow">3 APPLICATION INTEGRATION FLOW </a><ul>
<li><a href="#31-sslt-structure">3.1 ssl_t Structure</a></li>
<li><a href="#32-initialization">3.2 Initialization</a></li>
<li><a href="#33-creating-a-session">3.3 Creating a Session</a></li>
<li><a href="#34-handshaking">3.4 Handshaking</a></li>
<li><a href="#35-communicating-securely-with-peers">3.5 Communicating Securely With Peers </a><ul>
<li><a href="#351-encrypting-data">3.5.1 Encrypting Data</a></li>
<li><a href="#352-decrypting-data">3.5.2 Decrypting Data</a></li>
</ul>
</li>
<li><a href="#36-ending-a-session">3.6 Ending a Session</a></li>
<li><a href="#37-closing-the-library">3.7 Closing the Library</a></li>
</ul>
</li>
<li><a href="#4-configurable-features">4 CONFIGURABLE FEATURES </a><ul>
<li><a href="#41-protocol-and-performance">4.1 Protocol and Performance </a></li>
<li><a href="#42-public-key-math-assembly-optimizations">4.2 Public Key Math Assembly Optimizations </a></li>
<li><a href="#43-debug-configuration">4.3 Debug Configuration </a></li>
<li><a href="#44-minimum-firmware-configuration">4.4 Minimum Firmware Configuration </a></li>
<li><a href="#45-example-configurations">4.5 Example configurations</a></li>
</ul>
</li>
<li><a href="#5-ssl-handshaking">5 SSL HANDSHAKING </a><ul>
<li><a href="#51-standard-handshake">5.1 Standard Handshake</a></li>
<li><a href="#52-client-authentication-handshake">5.2 Client Authentication Handshake</a></li>
<li><a href="#53-session-resumption-handshake">5.3 Session Resumption Handshake</a></li>
<li><a href="#54-other-handshakes">5.4 Other Handshakes</a></li>
<li><a href="#55-re-handshakes">5.5 Re-Handshakes</a><ul>
<li><a href="#551-disable-re-handshaking-at-runtime">5.5.1 Disable Re-Handshaking At Runtime</a></li>
<li><a href="#552-the-re-handshake-credit-mechanism">5.5.2 The Re-Handshake Credit Mechanism</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="#6-optional-features">6 OPTIONAL FEATURES </a><ul>
<li><a href="#61-stateless-session-ticket-resumption">6.1 Stateless Session Ticket Resumption</a></li>
<li><a href="#62-server-name-indication-extension">6.2 Server Name Indication Extension</a></li>
<li><a href="#63-extended-master-secret">6.3 Extended Master Secret</a></li>
<li><a href="#64-maximum-fragment-length">6.4 Maximum Fragment Length</a></li>
<li><a href="#65-truncated-hmac">6.5 Truncated HMAC</a></li>
<li><a href="#66-application-layer-protocol-negotiation-extension">6.6 Application Layer Protocol Negotiation Extension</a></li>
<li><a href="#67-tls-fallback-scsv">6.7 TLS Fallback SCSV</a></li>
<li><a href="#68-ocsp">6.8 OCSP</a><ul>
<li><a href="#configuring-ocsp-feature-for-use">Configuring OCSP Feature for Use</a></li>
<li><a href="#invoking-ocsp-manually">Invoking OCSP Manually</a><ul>
<li><a href="#ocsp-example-application">OCSP Example Application</a></li>
<li><a href="#creating-ocsp-request-data">Creating OCSP request data</a><ul>
<li><a href="#providing-nonce-extension">Providing Nonce Extension</a></li>
<li><a href="#providing-name-for-requestor-requestorname">Providing name for requestor (requestorName)</a></li>
<li><a href="#providing-list-of-requests-requestlist">Providing list of requests (requestList)</a></li>
</ul>
</li>
<li><a href="#interacting-with-ocsp-server">Interacting with OCSP server</a></li>
<li><a href="#working-with-ocsp-response">Working with OCSP response</a></li>
<li><a href="#obtaining-and-checking-issuer-certificate">Obtaining and checking issuer certificate</a></li>
<li><a href="#parsing-ocsp-response">Parsing OCSP response</a></li>
<li><a href="#checking-time-stamps">Checking time-stamps</a></li>
<li><a href="#validating-ocsp-response">Validating OCSP response</a><ul>
<li><a href="#revocation-status-and-reason">Revocation status and reason</a></li>
<li><a href="#nonce-validation">Nonce validation</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
<li><a href="#69-matrixssl-statistics-framework">6.9 MatrixSSL Statistics Framework</a></li>
<li><a href="#610-client-authentication-using-an-external-security-token">6.10 Client Authentication using an External Security Token</a></li>
</ul>
</li>
<li><a href="#7-deprecated-features">7 Deprecated Features </a><ul>
<li><a href="#71-eapfast-mode">7.1 EAP_FAST Mode</a></li>
<li><a href="#72-zlib-compression">7.2 ZLIB Compression</a></li>
</ul>
</li>
</ul>
</div>
</p>
<h1 id="1-overview">1 OVERVIEW <i class="icon-globe"></i></h1>
<p>This developer’s guide is a general SSL/TLS overview and a MatrixSSL specific integration reference for adding SSL security into an application. <br>
This document is primarily intended for the software developer performing MatrixSSL integration into their custom application but is also a useful reference for anybody wishing to learn more about MatrixSSL or the SSL/TLS protocol in general. <br>
For additional information on the APIs discussed here please see the <em>MatrixSSL API</em> document included in this package.</p>
<h2 id="11-nomenclature">1.1 Nomenclature <i class="icon-book"></i></h2>
<p>MatrixSSL supports both the TLS and SSL protocols. Despite the difference in acronym, TLS 1.0 is simply version 3.1 of SSL. There are no practical security differences between the protocols, and only minor differences in how they are implemented. It was felt that ‘Transport Layer Security’ was a more appropriate name than ‘Secure Sockets Layer’ going forward beyond SSL 3.0. In this documentation, the term SSL is used generically to mean SSL/TLS, and TLS is used to indicate specifically the TLS protocol. SSL 2.0 is deprecated and not supported. MatrixSSL supports SSL 3.0, TLS 1.0, TLS 1.1 and TLS 1.2 protocols. In addition, the DTLS protocol is based closely on TLS 1.1 and beyond.</p>
<h2 id="12-supported-rfcs">1.2 Supported RFCs <i class="icon-doc-text"></i></h2>
<p>The following TLS RFCs are implemented by MatrixSSL.</p>
<dl>
<dt><a href="https://tools.ietf.org/html/rfc3749">RFC 3749</a> Transport Layer Security Protocol Compression Methods</dt>
<dd>Supported. Disabled by default due to security issues. <a href="#21-ssltls-version-security">See CRIME below</a>.</dd>
<dt><a href="https://tools.ietf.org/html/rfc4162">RFC 4162</a> Addition of SEED Cipher Suites to Transport Layer Security (TLS)</dt>
<dd>Supported. Disabled by default at compile time.</dd>
<dt><a href="https://tools.ietf.org/html/rfc4279">RFC 4279</a> Pre-Shared Key Ciphersuites for Transport Layer Security (TLS)</dt>
<dd>Supported: <br>
<code>TLS_DHE_PSK_WITH_AES_256_CBC_SHA</code> <br>
<code>TLS_DHE_PSK_WITH_AES_128_CBC_SHA</code> <br>
<code>TLS_PSK_WITH_AES_256_CBC_SHA</code> <br>
<code>TLS_PSK_WITH_AES_128_CBC_SHA</code></dd>
<dt><a href="https://tools.ietf.org/html/rfc4492">RFC 4492</a> Elliptic Curve Cryptography (ECC) Cipher Suites for Transport Layer Security (TLS)</dt>
<dd>Supported: <br>
<code>TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA</code> <br>
<code>TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA</code> <br>
<code>TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA</code> <br>
<code>TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA</code> <br>
<code>TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA</code> <br>
<code>TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA</code> <br>
<code>TLS_ECDH_RSA_WITH_AES_256_CBC_SHA</code> <br>
<code>TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA</code> <br>
<code>TLS_ECDH_RSA_WITH_AES_128_CBC_SHA</code> <br>
Supported Elliptic Curves: <br>
<code>secp192r1</code>, <code>secp224r1</code>, <code>secp256r1</code>, <code>secp384r1</code>, <code>secp521r1</code> <br>
Supported Point Formats: <br>
<code>uncompressed</code></dd>
<dt><a href="https://tools.ietf.org/html/rfc5077">RFC5077</a> Transport Layer Security (TLS) Session Resumption without Server-Side State</dt>
<dd>Supported (Session Tickets).</dd>
<dt><a href="https://tools.ietf.org/html/rfc5081">RFC5246</a> The Transport Layer Security (TLS) Protocol Version 1.2.</dt>
<dd>Supported, including TLS 1.1 and 1.0.</dd>
<dt><a href="https://tools.ietf.org/html/rfc5288">RFC 5288</a> AES Galois Counter Mode (GCM) Cipher Suites for TLS</dt>
<dd>Supported: <br>
<code>TLS_RSA_WITH_AES_256_GCM_SHA384</code> <br>
<code>TLS_RSA_WITH_AES_128_GCM_SHA256</code></dd>
<dt><a href="https://tools.ietf.org/html/rfc5289">RFC 5289</a> TLS Elliptic Curve Cipher Suites with SHA-256/384 and AES Galois Counter Mode (GCM)</dt>
<dd>Supported: <br>
<code>TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384</code> <br>
<code>TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384</code> <br>
<code>TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384</code> <br>
<code>TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256</code> <br>
<code>TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256</code> <br>
<code>TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384</code> <br>
<code>TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384</code> <br>
<code>TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256</code> <br>
<code>TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256</code></dd>
<dt><a href="https://tools.ietf.org/html/rfc5430">RFC 5430</a> Suite B Profile for Transport Layer Security (TLS)</dt>
<dd>Supported via compile time configuration.</dd>
<dt><a href="https://tools.ietf.org/html/rfc5469">RFC 5469</a> DES and IDEA Cipher Suites for Transport Layer Security (TLS)</dt>
<dd>These ciphers are removed per spec:
<blockquote>
<i class="icon-quote-left"></i> …the single-DES cipher suites SHOULD NOT be implemented by TLS libraries …the IDEA cipher suite SHOULD NOT be implemented by TLS libraries and SHOULD be removed from existing implementations. <i class="icon-quote-right"></i>
</blockquote></dd>
<dt><a href="https://tools.ietf.org/html/rfc5487">RFC 5487</a> Pre-Shared Key Cipher Suites for TLS with SHA-256/384 and AES Galois Counter Mode</dt>
<dd>Supported: <br>
<code>TLS_PSK_WITH_AES_256_CBC_SHA384</code> <br>
<code>TLS_PSK_WITH_AES_128_CBC_SHA256</code></dd>
<dt><a href="https://tools.ietf.org/html/rfc5746">RFC 5746</a> Transport Layer Security (TLS) Renegotiation Indication Extension</dt>
<dd>Supported. Extension required by compile time default.</dd>
<dt><a href="https://tools.ietf.org/html/rfc6066">RFC 6066</a> Transport Layer Security (TLS) Extensions: Extension Definitions</dt>
<dd><code>server_name</code> Server Name Indication Supported <br>
<code>max_fragment_length</code> Supported <br>
<code>client_certificate_url</code> Unsupported (denial of service risk) <br>
<code>trusted_ca_keys</code> Unsupported <br>
<code>truncated_hmac</code> Supported <br>
<code>status_request</code> OCSP Supported</dd>
<dt><a href="https://tools.ietf.org/html/rfc6176">RFC 6176</a> Prohibiting Secure Sockets Layer (SSL) Version 2.0</dt>
<dd>Supported. SSL 2.0 (including ClientHello) deprecated.</dd>
<dt><a href="https://tools.ietf.org/html/rfc6347">RFC 6347</a> Datagram Transport Layer Security Version 1.2</dt>
<dd>Supported, including DTLS 1.0.</dd>
<dt><a href="https://tools.ietf.org/html/rfc7027">RFC 7027</a> Elliptic Curve Cryptography (ECC) Brainpool Curves for Transport Layer Security (TLS)</dt>
<dd>Supported Curves: <br>
<code>brainpoolP224r1</code>, <code>brainpoolP256r1</code>, <code>brainpoolP384r1</code>, <code>brainpoolP512r1</code></dd>
<dt><a href="https://tools.ietf.org/html/rfc7301">RFC 7301</a> Transport Layer Security (TLS) Application-Layer Protocol Negotiation Extension</dt>
<dd>Supported</dd>
<dt><a href="https://tools.ietf.org/html/rfc7457">RFC 7457</a> Summarizing Known Attacks on Transport Layer Security (TLS) and Datagram TLS (DTLS)</dt>
<dd>Supported. <a href="#2-security-considerations">See Security Considerations below</a>.</dd>
<dt><a href="https://tools.ietf.org/html/rfc7465">RFC 7465</a> Prohibiting RC4 Cipher Suites</dt>
<dd>Supported. RC4 ciphers are disabled by default at compile time.</dd>
<dt><a href="https://tools.ietf.org/html/rfc7507">RFC 7507</a> TLS Fallback Signaling Cipher Suite Value (SCSV) for Preventing Protocol Downgrade Attacks</dt>
<dd>Supported</dd>
<dt><a href="https://tools.ietf.org/html/rfc7525">RFC 7525</a> Recommendations for Secure Use of Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS)</dt>
<dd>Supported. <a href="#2-security-considerations">See Security Considerations below</a>.</dd>
<dt><a href="https://tools.ietf.org/html/rfc7568">RFC 7568</a> Deprecating Secure Sockets Layer Version 3.0</dt>
<dd>Supported. SSL 3.0 is disabled by default at compile time.</dd>
<dt><a href="https://tools.ietf.org/html/rfc7627">RFC 7627</a> Transport Layer Security (TLS) Session Hash and Extended Master Secret Extension</dt>
<dd>Supported</dd>
<dt><a href="https://datatracker.ietf.org/doc/draft-ietf-dice-profile/">draft-ietf-dice-profile-17</a> TLS/DTLS Profiles for the Internet of Things</dt>
<dd>Supported via compile time configuration.</dd>
<dt><a href="https://datatracker.ietf.org/doc/draft-ietf-tls-chacha20-poly1305/">draft-ietf-tls-chacha20-poly1305</a> ChaCha20-Poly1305 Cipher Suites for Transport Layer Security (TLS)</dt>
<dd>Supported: <br>
<code>TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256</code> <br>
<code>TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256</code></dd>
<dt><a href="https://datatracker.ietf.org/doc/draft-ietf-tls-falsestart/">draft-ietf-tls-falsestart</a> Transport Layer Security (TLS) False Start</dt>
<dd>Supported. Disabled by default due to security concerns. <a href="#21-ssltls-version-security">See False Start below</a>.</dd>
</dl>
<h2 id="13-currently-unsupported-rfcs">1.3 Currently Unsupported RFCs</h2>
<p>The following “Proposed Standard RFCs” for TLS are not currently supported. Numerous “Experimental” and “Informational” RFCs are not listed here. <br>
<a href="https://tools.ietf.org/html/rfc2712">RFC 2712</a> Addition of Kerberos Cipher Suites to Transport Layer Security (TLS) <br>
<a href="https://tools.ietf.org/html/rfc4785">RFC 4785</a> Pre-Shared Key (PSK) Ciphersuites with NULL Encryption for Transport Layer Security (TLS) <br>
<a href="https://tools.ietf.org/html/rfc5705">RFC 5705</a> Keying Material Exporters for Transport Layer Security (TLS) <br>
<a href="https://tools.ietf.org/html/rfc5929">RFC 5929</a> Channel Bindings for TLS <br>
<a href="https://tools.ietf.org/html/rfc5932">RFC 5932</a> Camellia Cipher Suites for TLS <br>
<a href="https://tools.ietf.org/html/rfc6520">RFC 6520</a> Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS) Heartbeat Extension <br>
<a href="https://tools.ietf.org/html/rfc6655">RFC 6655</a> AES-CCM Cipher Suites for Transport Layer Security (TLS) <br>
<a href="https://tools.ietf.org/html/rfc6961">RFC 6961</a> The Transport Layer Security (TLS) Multiple Certificate Status Request Extension <br>
<a href="https://tools.ietf.org/html/rfc7250">RFC 7250</a> Using Raw Public Keys in Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS) <br>
<a href="https://tools.ietf.org/html/rfc7366">RFC 7366</a> Encrypt-then-MAC for Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS) <br>
<a href="https://tools.ietf.org/html/rfc7685">RFC 7633</a> X.509v3 Transport Layer Security (TLS) Feature Extension <br>
<a href="https://tools.ietf.org/html/rfc7685">RFC 7685</a> A Transport Layer Security (TLS) ClientHello Padding Extension</p>
<h2 id="14-supported-cipher-suites">1.4 Supported Cipher Suites <i class="icon-puzzle"></i></h2>
<p>Supported suites in priority order (not all suites are enabled by default):</p>
<pre class="prettyprint"><code class=" hljs autohotkey">TLS_ECDHE_ECDS<span class="hljs-built_in">A_WITH</span>_AES_256_GCM_SHA384
TLS_ECDHE_RS<span class="hljs-built_in">A_WITH</span>_AES_256_GCM_SHA384
TLS_ECDHE_ECDS<span class="hljs-built_in">A_WITH</span>_CHACHA20_POLY1305_SHA256
TLS_ECDHE_RS<span class="hljs-built_in">A_WITH</span>_CHACHA20_POLY1305_SHA256
TLS_ECDHE_ECDS<span class="hljs-built_in">A_WITH</span>_AES_256_CBC_SHA384
TLS_ECDHE_RS<span class="hljs-built_in">A_WITH</span>_AES_256_CBC_SHA384
TLS_DHE_RS<span class="hljs-built_in">A_WITH</span>_AES_256_CBC_SHA256
TLS_DHE_RS<span class="hljs-built_in">A_WITH</span>_AES_128_CBC_SHA256
TLS_ECDHE_ECDS<span class="hljs-built_in">A_WITH</span>_AES_128_GCM_SHA256
TLS_ECDHE_RS<span class="hljs-built_in">A_WITH</span>_AES_128_GCM_SHA256
TLS_ECDHE_ECDS<span class="hljs-built_in">A_WITH</span>_AES_128_CBC_SHA256
TLS_ECDHE_RS<span class="hljs-built_in">A_WITH</span>_AES_128_CBC_SHA256
TLS_DHE_RS<span class="hljs-built_in">A_WITH</span>_AES_256_CBC_SHA
TLS_ECDHE_ECDS<span class="hljs-built_in">A_WITH</span>_AES_256_CBC_SHA
TLS_ECDHE_RS<span class="hljs-built_in">A_WITH</span>_AES_256_CBC_SHA
TLS_DHE_RS<span class="hljs-built_in">A_WITH</span>_AES_128_CBC_SHA
TLS_ECDHE_ECDS<span class="hljs-built_in">A_WITH</span>_AES_128_CBC_SHA
TLS_ECDHE_RS<span class="hljs-built_in">A_WITH</span>_AES_128_CBC_SHA
SSL_DHE_RS<span class="hljs-built_in">A_WITH</span>_3DES_EDE_CBC_SHA
TLS_ECDHE_RS<span class="hljs-built_in">A_WITH</span>_3DES_EDE_CBC_SHA
TLS_DHE_PSK_WITH_AES_256_CBC_SHA
TLS_DHE_PSK_WITH_AES_128_CBC_SHA
TLS_RS<span class="hljs-built_in">A_WITH</span>_AES_256_GCM_SHA384
TLS_ECDH_ECDS<span class="hljs-built_in">A_WITH</span>_AES_256_GCM_SHA384
TLS_ECDH_RS<span class="hljs-built_in">A_WITH</span>_AES_256_GCM_SHA384
TLS_ECDH_ECDS<span class="hljs-built_in">A_WITH</span>_AES_256_CBC_SHA384
TLS_ECDH_RS<span class="hljs-built_in">A_WITH</span>_AES_256_CBC_SHA384
TLS_RS<span class="hljs-built_in">A_WITH</span>_AES_256_CBC_SHA256
TLS_ECDH_ECDS<span class="hljs-built_in">A_WITH</span>_AES_128_GCM_SHA256
TLS_RS<span class="hljs-built_in">A_WITH</span>_AES_128_GCM_SHA256
TLS_ECDH_RS<span class="hljs-built_in">A_WITH</span>_AES_128_GCM_SHA256
TLS_ECDH_ECDS<span class="hljs-built_in">A_WITH</span>_AES_128_CBC_SHA256
TLS_RS<span class="hljs-built_in">A_WITH</span>_AES_128_CBC_SHA256
TLS_ECDH_RS<span class="hljs-built_in">A_WITH</span>_AES_128_CBC_SHA256
TLS_ECDH_ECDS<span class="hljs-built_in">A_WITH</span>_AES_256_CBC_SHA
TLS_RS<span class="hljs-built_in">A_WITH</span>_AES_256_CBC_SHA
TLS_ECDH_RS<span class="hljs-built_in">A_WITH</span>_AES_256_CBC_SHA
TLS_ECDH_ECDS<span class="hljs-built_in">A_WITH</span>_AES_128_CBC_SHA
TLS_RS<span class="hljs-built_in">A_WITH</span>_AES_128_CBC_SHA
TLS_ECDH_RS<span class="hljs-built_in">A_WITH</span>_AES_128_CBC_SHA
SSL_RS<span class="hljs-built_in">A_WITH</span>_3DES_EDE_CBC_SHA
TLS_PSK_WITH_AES_256_CBC_SHA384
TLS_PSK_WITH_AES_128_CBC_SHA256
TLS_PSK_WITH_AES_256_CBC_SHA
TLS_PSK_WITH_AES_128_CBC_SHA</code></pre>
<p>Deprecated, disabled by default:</p>
<pre class="prettyprint"><code class=" hljs autohotkey">SSL_RS<span class="hljs-built_in">A_WITH</span>_RC4_128_SHA
TLS_RS<span class="hljs-built_in">A_WITH</span>_SEED_CBC_SHA
TLS_RS<span class="hljs-built_in">A_WITH</span>_IDE<span class="hljs-built_in">A_CBC</span>_SHA
SSL_RS<span class="hljs-built_in">A_WITH</span>_RC4_128_MD5
SSL_RS<span class="hljs-built_in">A_WITH</span>_NULL_SHA
SSL_RS<span class="hljs-built_in">A_WITH</span>_NULL_MD5
TLS_DH_anon_WITH_AES_256_CBC_SHA
TLS_DH_anon_WITH_AES_128_CBC_SHA
SSL_DH_anon_WITH_3DES_EDE_CBC_SHA
SSL_DH_anon_WITH_RC4_128_MD5</code></pre>
<h1 id="2-security-considerations">2 SECURITY CONSIDERATIONS <i class="icon-lock"></i></h1>
<p>Prior to working directly with the MatrixSSL library there are some critical SSL security concepts that application integrators should be familiar with.</p>
<h2 id="21-ssltls-version-security">2.1 SSL/TLS Version Security <i class="icon-eye"></i></h2>
<p>Although TLS 1.0 and above can be considered secure if configured correctly, several weaknesses have been discovered in some versions and cipher combinations. For an overview, see: <br>
<a href="https://tools.ietf.org/html/rfc7457">RFC7457 Summarizing Known Attacks on Transport Layer Security (TLS) and Datagram TLS (DTLS)</a></p>
<blockquote>
<dl>
<dt>Timing and Power Attacks</dt>
<dd>While attempts are made for constant-time operation, the MatrixSSL crypto library is not explicitly designed to be resilient to every type of timing, cache and power attack. If these are a concern, MatrixSSL TLS protocol library has support for hardware crypto, DPA resistant tokens, and hardened software crypto implementations.</dd>
</dl>
</blockquote>
<p>All of the issues discovered below are mitigated by default in MatrixSSL. Additionally, SSL 3.0 and weak ciphers and key strengths are disabled by default in MatrixSSL to reduce version downgrade attacks and the padding oracle attack (POODLE). TLS 1.0 is also disabled by default at compile time in an effort to move protocol support forward.</p>
<dl>
<dt><a href="https://en.wikipedia.org/wiki/Transport_Layer_Security#BEAST_attack">BEAST</a></dt>
<dd><code>USE_BEAST_WORKAROUND</code> enabled by default for SSL 3.0 and TLS 1.0. Some implementations of TLS are not compatible with this workaround. <br>
TLS 1.1 and above are not vulnerable to this attack. By default TLS 1.1 is the minimum compiled-in version for MatrixSSL.</dd>
<dt><a href="https://en.wikipedia.org/wiki/Adaptive_chosen-ciphertext_attack">Bleichenbacher Type Attacks</a></dt>
<dd>Private RSA key information can be leaked if libraries aren’t careful in their implementation of RSA PKCS#1 padding. MatrixSSL has been analyzed as secure by internal and 3rd party security researchers. Additionally, the more secure RSA-PSS signatures are supported, however TLS 1.2 and below allows only PKCS#1v1.5 signatures.</dd>
<dt><a href="https://en.wikipedia.org/wiki/CRIME_%28security_exploit%29">CRIME</a>, <a href="https://en.wikipedia.org/wiki/BREACH_%28security_exploit%29">BREACH</a></dt>
<dd><code>USE_ZLIB_COMPRESSION</code> disabled and deprecated by default. <br>
Application code should not compress frequently used headers.</dd>
<dt><a href="https://drownattack.com/">DROWN</a></dt>
<dd>SSLv2 and export ciphers are not part of the MatrixSSL codebase so this attack cannot be applied.</dd>
<dt><a href="https://securityblog.redhat.com/2015/09/02/factoring-rsa-keys-with-tls-perfect-forward-secrecy/">Lenstra Type Attacks</a></dt>
<dd>Private RSA key information can be leaked if a hardware error or memory overrun occurs on the private key, or on intermediate results of the RSA signature operation. MatrixSSL verifies all RSA private key signatures before they are transmitted, so these rareerrors will be caught before they can be exploited.</dd>
<dt><a href="https://en.wikipedia.org/wiki/Lucky_Thirteen_attack">LUCKY13</a></dt>
<dd>Internal blinding for block cipher padding automatically applied. <br>
Stream and AEAD ciphers are not affected.</dd>
<dt><a href="https://en.wikipedia.org/wiki/POODLE">POODLE</a></dt>
<dd>SSL 3.0 disabled by default with <code>DISABLE_SSL3</code> since version 3.3.1 as per <a href="https://tools.ietf.org/html/rfc7568">RFC 7568</a> <br>
TLS 1.0 and above are not affected.</dd>
<dt><a href="https://en.wikipedia.org/wiki/FREAK">FREAK</a></dt>
<dd>MatrixSSL has never supported weak, export grade ciphers.</dd>
<dt><a href="https://en.wikipedia.org/wiki/Logjam_%28computer_security%29">Logjam</a></dt>
<dd><code>USE_DH</code> is disabled by default. In addition, <code>MIN_DH_BITS</code> can be increased from the default 1024 bits to reduce the feasibility of this attack. Custom Diffie-Hellman parameters are loaded by the API <code>pkcs3ParseDhParam</code>.</dd>
<dt><a href="https://en.wikipedia.org/wiki/Heartbleed">Heartbleed</a></dt>
<dd>MatrixSSL does not support the Heartbeat extension.</dd>
<dt><a href="http://www.intelsecurity.com/advanced-threat-research/berserk.html">BERserk</a></dt>
<dd>MatrixSSL was tested against this PKCS#1 v1.5 RSA parsing bug and is not vulnerable.</dd>
<dt><a href="https://www.mitls.org/pages/attacks/SMACK">SMACK</a></dt>
<dd>MatrixSSL was tested against state machine attacks where are messages are missing or out of order and is not vulnerable. MatrixSSL tracks both the current state and the expected state of the state machine against incoming handshake messages.</dd>
<dt><a href="https://en.wikipedia.org/wiki/Transport_Layer_Security#Renegotiation_attack">Renegotiation Attacks</a></dt>
<dd><code>REQUIRE_SECURE_REHANDSHAKES</code> enabled by default, as per <a href="https://tools.ietf.org/html/rfc5746">RFC 5746</a>.</dd>
<dd><code>TLS_FALLBACK_SCSV</code> always enabled as per <a href="https://tools.ietf.org/html/rfc7507">RFC7507</a>.</dd>
<dt><a href="https://en.wikipedia.org/wiki/Transport_Layer_Security#Version_rollback_attacks">False Start Weakness</a></dt>
<dd><code>ENABLE_FALSE_START</code> disabled and deprecated by default.</dd>
<dt><a href="https://en.wikipedia.org/wiki/Transport_Layer_Security#RC4_attacks">RC4 Weakness</a></dt>
<dd><code>USE_SSL_RSA_WITH_RC4_128</code> disabled and deprecated by default. If enabled, internal code limits the number of bytes RC4 will encode. <a href="https://tools.ietf.org/html/rfc7465">RFC 7465</a> proposes to remove these suites from TLS.</dd>
<dt>MD5 MAC Weakness, <a href="https://www.mitls.org/pages/attacks/SLOTH">SLOTH</a></dt>
<dd><code>USE_MD5</code> and <code>USE_SSL_RSA_WITH_RC4_128_MD5</code> cipher disabled by default. <br>
All other MD5 based ciphers disabled by default.</dd>
<dt>MD5 Certificate Weakness</dt>
<dd><code>ENABLE_MD5_SIGNED_CERTS</code> disabled by default.</dd>
<dt>SHA1 Certificate Weakness</dt>
<dd><code>ENABLE_SHA1_SIGNED_CERTS</code> can be disabled. Many certificates still use SHA1, so enabling may introduce compatibility issues with certain hosts.</dd>
</dl>
<h2 id="22-selecting-cipher-suites">2.2 Selecting Cipher Suites <i class="icon-ok-squared"></i></h2>
<p>The strength of the secure communications is primarily determined by the choice of cipher suites that will be supported. A cipher suite determines how two peers progress through an SSL handshake as well as how the final application data will be encrypted over the secure connection. The four components of any given cipher suite are key exchange, authentication, encryption and digest hash.</p>
<p>Key exchange mechanisms refer to how the peers agree upon a common symmetric key that will be used to encrypt data after handshaking is complete. The two common key exchange algorithms are RSA and Diffie-Hellman (DH or ECDH). Currently, when Diffie-Hellman is chosen it is used almost exclusively in ephemeral mode (DHE or ECDHE) in which new private key pairs are generated for each connection to allow perfect forward secrecy. The trade-off for DHE is a much slower SSL handshake as key generation is a relatively processor-intensive operation. Some older protocols also specify DH, as it was the first widely publicized key exchange algorithm. The elliptic curve variations on the Diffie-Hellman algorithms are denoted ECDH or ECDHE in the cipher suite name.</p>
<p>Authentication algorithms specify how the peers will prove their identities to each other. Authentication options within cipher suites are RSA, DSA, Elliptic Curve DSA (ECDSA), Pre-shared Key (PSK), or anonymous if no authentication is required. RSA has the unique property that it can be used for both key exchange and authentication. For this reason, RSA has become the most widely implemented cipher suite mechanism for SSL communications. RSA key strengths of between 1024 and 2048 bits are the most common.</p>
<p>The encryption component of the cipher suite identifies which symmetric cipher is to be used when exchanging data at the completion of the handshake. The AES block cipher is recommended for new implementations, and is the most likely to have hardware acceleration support.</p>
<p>Finally, the digest hash is the choice of checksum algorithm used to confirm the integrity of exchanged data, with SHA-1 being the most common and SHA256 recommended for new implementations. Here is a selection of cipher suites that illustrate how to identify the four components.</p>
<table>
<thead>
<tr>
<th>Cipher Suite</th>
<th>Key Exchange</th>
<th>Auth Type</th>
<th>Encryption</th>
<th>MAC</th>
</tr>
</thead>
<tbody><tr>
<td><code>SSL_RSA_WITH_3DES_EDE_CBC_SHA</code></td>
<td>RSA</td>
<td>RSA</td>
<td>3DES</td>
<td>SHA1</td>
</tr>
<tr>
<td><code>SSL_DH_anon_WITH_RC4_128_MD5</code></td>
<td>DH</td>
<td>Anon</td>
<td>RC4-128</td>
<td>MD5</td>
</tr>
<tr>
<td><code>TLS_RSA_WITH_AES_128_CBC_SHA</code></td>
<td>RSA</td>
<td>RSA</td>
<td>AES-CBC-128</td>
<td>SHA1</td>
</tr>
<tr>
<td><code>TLS_DHE_RSA_WITH_AES_256_CBC_SHA</code></td>
<td>DHE</td>
<td>RSA</td>
<td>AES-CBC-256</td>
<td>SHA1</td>
</tr>
<tr>
<td><code>TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA</code></td>
<td>ECDHE</td>
<td>RSA</td>
<td>AES-CBC-128</td>
<td>SHA1</td>
</tr>
<tr>
<td><code>TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA</code></td>
<td>ECDHE</td>
<td>ECDSA</td>
<td>AES-CBC-256</td>
<td>SHA1</td>
</tr>
<tr>
<td><code>TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384</code></td>
<td>ECDH</td>
<td>ECDSA</td>
<td>AES-GCM-256</td>
<td>GMAC</td>
</tr>
<tr>
<td><code>TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256</code></td>
<td>ECDH</td>
<td>ECDSA</td>
<td>ChaCha20</td>
<td>Poly1305</td>
</tr>
</tbody></table>
<p>The <code>AES_GCM</code> and <code>CHACHA20_POLY1305</code> are <a href="https://en.wikipedia.org/wiki/Authenticated_encryption">AEAD ciphers</a> that combine the encryption and digest hash components so a dedicated hash algorithm is not used in these suites. The hash algorithm that is specified is the hash to use for the handshake hash in TLS 1.2 and greater.</p>
<p><strong>Symmetric Algorithms Supported by MatrixSSL</strong></p>
<table>
<thead>
<tr>
<th>Algorithm</th>
<th>Ok?</th>
<th>Typical Risks</th>
</tr>
</thead>
<tbody><tr>
<td>RC4</td>
<td>No</td>
<td>Several known weaknesses. Can be OK for small amounts of data. All RC4 ciphersuites disabled by default.</td>
</tr>
<tr>
<td>3DES</td>
<td>No</td>
<td>Theoretical weaknesses due to key strength. AES typically a better candidate. 3DES ciphersuites disabled by default.</td>
</tr>
<tr>
<td>SEED</td>
<td>No</td>
<td>Standard usage only in Korea. AES is a better candidate. Disabled by default.</td>
</tr>
<tr>
<td>IDEA</td>
<td>No</td>
<td>Disabled by default.</td>
</tr>
<tr>
<td>AES-CBC</td>
<td>Yes</td>
<td>AES-256 preferred over AES-192 and AES-128. Lucky13 Attack mitigated internally, but all block ciphers are vulnerable.</td>
</tr>
<tr>
<td>AES-GCM</td>
<td>Yes</td>
<td>AES-256 preferred over AES-192 and AES-128. Not vulnerable to Lucky13 Attack. Without hardware acceleration, can be slower than AES-SHA. Risk that an as-yet undiscovered AES attack will compromise both encryption and record validation.</td>
</tr>
<tr>
<td>ChaCha20</td>
<td>Yes</td>
<td>Stream cipher with 256 bit equivalent security. Supported as per <a href="https://tools.ietf.org/html/draft-ietf-tls-chacha20-poly1305">IETF Draft</a></td>
</tr>
</tbody></table>
<p><strong>Hash Algorithms Supported by MatrixSSL</strong></p>
<table>
<thead>
<tr>
<th>Algorithm</th>
<th>Ok?</th>
<th>Typical Risks</th>
</tr>
</thead>
<tbody><tr>
<td>MD2</td>
<td>No</td>
<td>Known weak. Used only for legacy certificate signatures. <code>USE_MD2</code> disabled by default.</td>
</tr>
<tr>
<td>MD4</td>
<td>No</td>
<td>Known weak. Used only for legacy certificate signatures. <code>USE_MD4</code> disabled by default.</td>
</tr>
<tr>
<td>MD5</td>
<td>No</td>
<td>Proven attacks. SSL 3.0 through TLS 1.1 require MD5 in combination with SHA-1 for their internal protocol (and therefore are at least as strong as SHA-1). TLS 1.2 does not require MD5. All MD5 based cipher suites disabled by default. <code>ENABLE_MD5_SIGNED_CERTS</code> disabled by default.</td>
</tr>
<tr>
<td>SHA-1</td>
<td>Deprecate</td>
<td>SHA-1 is still widely deployed despite recent collision attacks. Only TLS 1.2 and newly issued certificates using SHA-2 are able to remove SHA-1 completely from the TLS protocol.</td>
</tr>
<tr>
<td>SHA-256</td>
<td>Yes</td>
<td>Assumed secure.</td>
</tr>
<tr>
<td>SHA-384</td>
<td>Yes</td>
<td>Assumed secure.</td>
</tr>
<tr>
<td>SHA-512</td>
<td>Yes</td>
<td>Assumed secure.</td>
</tr>
<tr>
<td>Poly1305</td>
<td>Yes</td>
<td>Supported as per <a href="https://tools.ietf.org/html/draft-ietf-tls-chacha20-poly1305">IETF Draft</a></td>
</tr>
</tbody></table>
<p><strong>Key Exchange Algorithms Supported by MatrixSSL</strong></p>
<table>
<thead>
<tr>
<th>Algorithm</th>
<th>Key Size</th>
<th>Ok?</th>
<th>Typical Risks</th>
</tr>
</thead>
<tbody><tr>
<td>RSA</td>
<td>&lt; 1024</td>
<td>No</td>
<td>Weak. Below MIN_RSA_SIZE connections will be refused.</td>
</tr>
<tr>
<td>RSA</td>
<td>1024</td>
<td>No</td>
<td>In wide usage. Recommended to not use going forward</td>
</tr>
<tr>
<td>RSA</td>
<td>&gt; 1024</td>
<td>Yes</td>
<td>Recommend at least 2048 bit keys, per NIST and FIPS.</td>
</tr>
<tr>
<td>DH</td>
<td>&lt; 1024</td>
<td>No</td>
<td>Weak. Below <code>MIN_DH_SIZE</code> connections will be refused.</td>
</tr>
<tr>
<td>DH</td>
<td>1024</td>
<td>No</td>
<td>In wide usage. Recommended to not use going forward</td>
</tr>
<tr>
<td>DH</td>
<td>&gt; 1024</td>
<td>Yes</td>
<td>Recommend at least 2048 bit DH group per NIST and FIPS.</td>
</tr>
<tr>
<td>DHE</td>
<td>&gt; 1024</td>
<td>Yes</td>
<td>See chart below. Ephemeral cipher suites provide perfect forward secrecy, and are generally the strongest available, although they are also the slowest performing for key exchange.</td>
</tr>
<tr>
<td>ECDHE</td>
<td>&gt;= 192</td>
<td>Yes</td>
<td>See chart below. Ephemeral cipher suites provide perfect forward secrecy, and are generally the strongest available, although they are also the slowest performing for key exchange. 224 and greater required by FIPS.</td>
</tr>
<tr>
<td>ECDH</td>
<td>&gt;= 192</td>
<td>Yes</td>
<td>192 bit DH group and above is currently assumed secure. Smaller groups are not supported in MatrixSSL. Below <code>MIN_ECC_SIZE</code> connections will be refused. 224 and greater required by FIPS.</td>
</tr>
<tr>
<td>PSK</td>
<td>&gt;= 128</td>
<td>Yes</td>
<td>Pre-shared Key ciphers rely on offline key agreement. They avoid any weaknesses of Key Exchange Algorithms, however, it is not easy to change keys once they are installed when used as session keys. When PSK is used only for authentication (<code>DHE_PSK</code> and <code>ECDHE_PSK</code> cipher suites), the session encryption keys are generated each connection.</td>
</tr>
</tbody></table>
<p><strong>Authentication Methods Supported by MatrixSSL</strong></p>
<table>
<thead>
<tr>
<th>Suite Type</th>
<th>Auth</th>
<th>Exchange</th>
<th>Ok?</th>
<th>Typical Risks</th>
</tr>
</thead>
<tbody><tr>
<td><code>RSA_WITH_NULL</code></td>
<td>RSA</td>
<td>none</td>
<td>No</td>
<td>No encryption. Authentication via RSA. Typically used for debugging connections only.</td>
</tr>
<tr>
<td><code>DH_anon</code></td>
<td>none</td>
<td>Diffie-Hellman</td>
<td>No</td>
<td>No Authentication. Key exchange only. If this ciphersuite is used, authentication MUST be done by direct comparison of remote DH key ID to trusted key ID, similar to SSH authentication. If DH key ID authentication is done, this is similar in strength to DHE_PSK ciphers, although the keys exchanged are not ephemeral. Authentication to a trusted key ID can mitigate many attacks related to X.509 PKI infrastructure.</td>
</tr>
<tr>
<td><code>PSK</code></td>
<td>Pre-shared Key</td>
<td>Pre-shared Key</td>
<td>Yes</td>
<td>Pre-shared Keys can be used for authentication, since the same secret must be shared between client and server. <code>DHE_PSK</code> suites use PSK only for authentication, while PSK suites use PSK for authentication and session keys. PSK keys are difficult to change in the field, however authentication with PSK can mitigate many attacks related to X.509 PKI infrastructure.</td>
</tr>
<tr>
<td><code>RSA</code></td>
<td>RSA</td>
<td>RSA</td>
<td>Yes</td>
<td>The most commonly used authentication method. Supported by X.509 PKI infrastructure. Additional security can be had by directly comparing <code>RSA</code> key IDs to trusted Key Ids (similar to Certificate Pinning). Usually faster than ECC based authentication.</td>
</tr>
<tr>
<td><code>DHE_RSA</code></td>
<td>RSA</td>
<td>Diffie-Hellman Ephemeral</td>
<td>Yes</td>
<td>RSA for authentication, Ephemeral DH for key exchange. Provides <a href="http://en.wikipedia.org/wiki/Forward_secrecy">perfect forward secrecy</a>.</td>
</tr>
<tr>
<td><code>DHE_PSK</code></td>
<td>PSK</td>
<td>Diffie-Hellman Ephemeral</td>
<td>Yes</td>
<td>PSK for authentication, Ephemeral DH for key exchange. Does not rely on X.509.</td>
</tr>
<tr>
<td><code>ECDH_ECDSA</code></td>
<td>ECC DSA</td>
<td>ECC Diffie-Hellman</td>
<td>Yes</td>
<td>ECC DSA for authentication, ECC for key exchange. Most commonly used in embedded devices supporting hardware based ECC support.</td>
</tr>
<tr>
<td><code>ECDH_RSA</code></td>
<td>RSA</td>
<td>ECC Diffie-Hellman</td>
<td>Yes</td>
<td>ECC key exchange, with RSA authentication. Uses widely deployed X.509 RSA certificate infrastructure, but ECC for key exchange. Not often deployed due to the implementation having to support ECC and RSA.</td>
</tr>
<tr>
<td><code>ECDHE_ECDSA</code></td>
<td>ECC DSA</td>
<td>ECC Diffie-Hellman Ephemeral</td>
<td>Yes</td>
<td>ECC key exchange with ephemeral keys, ECC DSA authentication. Most commonly used in embedded devices supporting hardware based ECC support.</td>
</tr>
<tr>
<td><code>ECDHE_RSA</code></td>
<td>RSA</td>
<td>ECC Diffie-Hellman Ephemeral</td>
<td>Yes</td>
<td>Ephemeral counterpart to ECDH_RSA.</td>
</tr>
</tbody></table>
<h2 id="23-authentication-mode">2.3 Authentication Mode</h2>
<p>By default in SSL, it is the server that is authenticated by a client. It is easiest to remember this when thinking about purchasing a product online with a credit card over an HTTPS (SSL) connection. The client Web browser must authenticate the server in order to be confident the credit card information is being sent to a trusted source. This is referred to as one-way authentication or server authentication and is performed as part of all standard SSL connections (unless, of course, a cipher suite with an authentication type of anonymous has been agreed upon).</p>
<p>However, in some use-case scenarios the user may require that both peers authenticate each other. This is referred to as mutual authentication or client authentication. If the project requires client authentication there is an additional set of key material that must be used to support it as described in the next section.</p>
<p>Client authentication is also done inherently in Pre-shared Key cipher suites, as both sides of a connection must have a common shared secret.</p>
<h2 id="24-authentication-and-key-exchange">2.4 Authentication and Key Exchange <i class="icon-certificate"></i></h2>
<h3 id="241-server-and-client-authentication">2.4.1 Server and Client Authentication</h3>
<p>With a cipher suite and authentication mode chosen, the user will need to obtain or generate the necessary key material for supporting the authentication and key exchange mechanisms. X.509 is the standard for how key material is stored in certificate files.</p>
<p>The peer that is being authenticated must have a private key and a public certificate. The peer performing the authentication must have the Certificate Authority (CA) certificate that was used to issue the public certificate. In the standard one-way authentication scenario this means the server will load a private key and certificate while the client will load the CA file.</p>
<p>If client authentication is needed the mirror image of CA, certificate, and private key files must also be used. This chart shows which files clients and server must load when using a standard RSA based cipher suite such as <code>TLS_RSA_WITH_AES_256_GCM_SHA384</code>.</p>
<table>
<thead>
<tr>
<th>Authentication Mode</th>
<th>Server Key Files</th>
<th>Client Key Files</th>
</tr>
</thead>
<tbody><tr>
<td>One-way server authentication</td>
<td>RSA server certificate file and corresponding RSA private key file.</td>
<td>Certificate Authority certificate file that issued the server certificate</td>
</tr>
<tr>
<td>Additions for client authentication</td>
<td>Certificate Authority certificate file that issued the client certificate</td>
<td>RSA client certificate file and corresopnding RSA private key file.</td>
</tr>
</tbody></table>
<h3 id="242-certificate-validation-and-authentication">2.4.2 Certificate Validation and Authentication</h3>
<p>Authentication in SSL is most often based on X.509 Certificate chain validation. <br>
Example <a href="https://www.geotrust.com/resources/root-certificates/">Equifax GeoTrust</a> trusted root certificate loaded by a MatrixSSL client with <code>matrixSslLoadRsaKeys</code>. </p>
<blockquote>
<p><strong>Subject: C=US, O=Equifax, OU=Equifax Secure Certificate Authority</strong> <br>
<em>Authority KeyId</em>:48:E6:68:F9:2B:D2:B2:95… [Valid, self-signed OK for root] <br>
<em>Subject KeyId</em>: 48:E6:68:F9:2B:D2:B2:95… <br>
<em>Basic Constraints</em>: critical CA:TRUE [Valid, this certificate can sign others] <br>
<em>Key Usage</em>: critical Certificate Sign, CRL Sign [Valid, able to sign certificates] <br>
<em>Validity</em>: (Aug 22 16:41:51 1998 GMT to Aug 22 16:41:51 2018 GMT) [Valid]</p>
</blockquote>
<p>Certificate chain sent to a MatrixSSL client during SSL handshake Certificate message by remote server <a href="https://www.google.com">https://www.google.com</a>.</p>
<blockquote>
<p><strong>C=US, O=GeoTrust Inc., CN=GeoTrust Global CA</strong> <br>
<em>Issuer</em>: C=US, O=Equifax, OU=Equifax Secure Certificate Authority [Valid, matches a loaded trusted root subject] <br>
<em>Authority KeyId</em>: 48:E6:68:F9:2B:D2:B2:95… [Valid, matches the Issuer Subject KeyId] <br>
<em>Subject KeyId</em>: C0:7A:98:68:8D:89:FB:AB… <br>
<em>Basic Constraints</em>: critical CA:TRUE [Valid, this certificate can sign others] <br>
<em>Key Usage</em>: critical Certificate Sign, CRL Sign [Valid, able to sign certificates] <br>
<em>Validity</em>: (May 21 04:00:00 2002 GMT to Aug 21 04:00:00 2018 GMT) [Valid]</p>
<blockquote>
<p><strong>C=US, O=Google Inc, CN=Google Internet Authority G2</strong> <br>
<em>Issuer</em>: C=US, O=GeoTrust Inc., CN=GeoTrust Global CA [Valid, matches parent subject] <br>
<em>Authority KeyId</em>: C0:7A:98:68:8D:89:FB:AB… [Valid, matches the Issuer Subject KeyId] <br>
<em>Subject KeyId</em>: 4A:DD:06:16:1B:BC:F6:68… <br>
<em>Validity</em>: (Apr 5 15:15:55 2013 GMT to Apr 4 15:15:55 2015 GMT) [Valid] <br>
<em>Basic Constraints</em>: critical CA:TRUE, pathlen:0 [Valid, this certificate can sign others and the signed certificate is not also a CA] <br>
<em>Key Usage</em>: critical Certificate Sign, CRL Sign [Valid, able to sign certificates] <br>
<em>Version</em>: 3 [Valid]</p>
<blockquote>
<p><strong>C=US, ST=California, L=Mountain View, O=Google Inc, CN=*.google.com</strong> <br>
<em>Issuer</em>: C=US, O=Google Inc, CN=Google Internet Authority G2 [Valid, matches parent subject] <br>
<em>X509v3 Basic Constraints</em>: critical CA:FALSE [Valid, this is a leaf cert] <br>
<em>Extended Key Usage</em>: TLS Web Server Authentication, TLS Web Client Authentication [Valid] <br>
<em>X509v3 Subject Alternative Name</em>: DNS:<em>.google.com, DNS:</em>.android.com… [Valid, matches expected DNS name] <br>
<em>Validity</em>: (Mar 12 09:53:40 2014 GMT to Jun 10 00:00:00 2014 GMT) [Valid]</p>
</blockquote>
</blockquote>
</blockquote>
<p><strong>Validity checks that are done on all certificates</strong></p>
<table>
<thead>
<tr>
<th>X.509 Field</th>
<th>Validation Performed</th>
</tr>
</thead>
<tbody><tr>
<td>Version</td>
<td>Must be a version 3 certificate.</td>
</tr>
<tr>
<td>Serial</td>
<td>Used for lookup in a CRL, if <code>USE_CRL</code> defined.</td>
</tr>
<tr>
<td>Signature Algorithm</td>
<td>RSA or ECDSA algorithms. Should be SHA256, SHA384 or SHA512. SHA1 enabled by default with <code>ENABLE_SHA1_SIGNED_CERTS</code>. MD2 and MD5 support for RSA signatures is disabled by default by <code>ENABLE_MD5_SIGNED_CERTS</code>.</td>
</tr>
<tr>
<td>Issuer</td>
<td>In a chain, issuer must match the subject of the immediate (following) parent certificate. Self-signed certificates (<code>Issuer</code> == <code>Subject</code>) are allowed as loaded root certificates, but not as part of a chain. Common name must contain only printable characters.</td>
</tr>
<tr>
<td>Validity</td>
<td>Current date must be within notBefore and notAfter range on all certs in the chain. Time is not currently validated. On platforms without a date function, the range check is always flagged as failed and must be handled by the <em>Certificate Validation Callback</em>. For platforms without a date API, validation must be done within the user <em>Certificate Validation Callback</em>.</td>
</tr>
<tr>
<td>Subject</td>
<td>Common name must contain only printable characters. Common name will be validated via full match to expectedName, if provided in <code>matrixSslNewClientSession</code>. Partial match not allowed. Wildcard match is allowed for the first segment of a DNS name. More complex validation must be done within the user <em>Certificate Validation Callback</em>.</td>
</tr>
<tr>
<td>Subject Public Key Info</td>
<td>RSA and ECC keys supported. RSA public key modulus must be at least <code>MIN_RSA_SIZE</code> bits. ECC public key must be at least <code>MIN_ECC_SIZE</code> bits.</td>
</tr>
<tr>
<td>Signature</td>
<td>The hash of the certificate contents must match the hash that is signed by the <code>Issuer Public Key</code>.</td>
</tr>
<tr>
<td>Basic Constraints</td>
<td>For Root or intermediate certs, must be marked <code>Critical</code> with <code>CA:TRUE</code>. Path Length constraints are validated.</td>
</tr>
<tr>
<td>Key Usage</td>
<td>For Root or intermediate certs, must be marked for use as <code>CertificateSign</code>. For CRL checks, <code>CrlSign</code> flag must be set.</td>
</tr>
<tr>
<td>Extended Key Usage</td>
<td>If marked Critical, must have <code>TLS Web Server Authentication</code> or <code>TLS Web Client Authentication</code> set in the leaf certificate.</td>
</tr>
<tr>
<td>Subject Alternative Name</td>
<td>If an expectedName is specified in <code>matrixSslNewClientSession</code> and does not match <code>Subject Common Name</code>, or any printable <code>Subject Alternative Name</code> of type <code>DNS</code>, <code>Email</code> or <code>IP</code>, validation will fail.</td>
</tr>
<tr>
<td>Authority Key Identifier</td>
<td>If specified, the direct Issuer of the certificate must have a defined, matching <code>Subject Key Identifier</code>.</td>
</tr>
<tr>
<td>Subject Key Identifier</td>
<td>If specified, any direct children of the Issuer must have a defined, matching <code>Authority Key Identifier</code>.</td>
</tr>
<tr>
<td>CRL Distribution Points</td>
<td>If USE_CRL is defined, <code>matrixSslGetCRL</code> will download the CRL files from each URI type distribution point provided for each trusted root certificate (Note: not intermediate certificates).</td>
</tr>
<tr>
<td>CRL Validation</td>
<td>CRL file must be signed by certificate with <code>CrlSign</code> Basic constraints. MD5 signatures not supported by default.</td>
</tr>
<tr>
<td>Unknown Extensions</td>
<td>Unknown extensions are ignored, unless flagged as <code>Critical</code>. Validation will fail for any Critical extension unrecognized by MatrixSSL.</td>
</tr>
</tbody></table>
<p>In <em>MatrixSSL Commercial Edition</em>, Certificate Authority root and child certificates can be created using the provided command-line tools and API. For more information, please consult the <em>Matrix Key and Cert Generation Utilities</em> and <em>MatrixSSL Certificates and Certificate Revocation Lists</em> documents.</p>
<h1 id="3-application-integration-flow">3 APPLICATION INTEGRATION FLOW <i class="icon-fork"></i></h1>
<p>MatrixSSL is a C code library that provides a security layer for client and server applications allowing them to securely communicate with other SSL enabled peers. MatrixSSL is transport agnostic and can just as easily integrate with an HTTP server as it could with a device communicating through a serial port. For simplicity, this developer’s guide will assume a socket-based implementation for all its examples unless otherwise noted.</p>
<p>The term application in this document refers to the peer (client or server) application the MatrixSSL library is being integrated into.</p>
<p>This section will detail the specific points in the application life cycle where MatrixSSL should be integrated. In general, MatrixSSL APIs are used for initialization/cleanup, when new secure connections are being established (handshaking), and when encrypting/decrypting messages exchanged with peers.</p>
<p>Refer to the MatrixSSL API document to get familiar with the interface to the library and with the example code to see how they are used at implementation. Follow the guidelines below when using these APIs to integrate MatrixSSL into an application.</p>
<h2 id="31-sslt-structure">3.1 <code>ssl_t</code> Structure</h2>
<p>The <code>ssl_t</code> structure holds the state and keys for each client or server connection as well as buffers for encoding and decoding SSL data. The buffers are dynamically managed internally to make the integration with existing non-secure software easier. SSL is a record based protocol, and the internal buffer management makes a better ‘impedance match’ with classic stream based protocols. For example, data may be read from a socket, but if a full SSL record has not been received, no data is available for the caller to process. This partial record is held within the <code>ssl_t</code> buffer. The MatrixSSL API is also designed so there are no buffer copies, and the caller is able to read and write network data directly into the SSL buffers, providing a very low memory overhead per session.</p>
<h2 id="32-initialization">3.2 Initialization</h2>
<p>MatrixSSL must be initialized as part of the application initialization with a call to <code>matrixSslOpen</code>. This function sets up the internal structures needed by the library.</p>
<p>In most cases, the application will subsequently load the key material from the file system. RSA or EC certificates, Diffie-Hellman parameters, and Pre-Shared Keys for the specific peer application must be parsed before creating a new SSL session. The <code>matrixSslNewKeys</code> function is used to allocate the key storage and <code>matrixSslLoadRsaKeys</code>, <code>matrixSslLoadEcKeys</code>, <code>matrixSslLoadDhParams</code>, and <code>matrixSslLoadPsk</code> are used to parse the key material into the <code>sslKeys_t</code> structure during initialization. The populated key structure will be used as an input parameter to <code>matrixSslNewClientSession</code> or <code>matrixSslNewServerSession</code>. <br>
The allocation and loading of the <code>sslKeys_t</code> structure is most commonly done a single time at start and the application uses those keys for each connection. Alternatively, a new <code>sslKeys_t</code> structure can be allocated once for each secure connection and freed immediately after the connection is closed. This should be done if the application has multiple certificate files depending on the identity of the connecting entity or if there is a security concern with keeping the RSA keys in memory for extended periods of time. <br>
Once the application is done with the keys, the associated memory is freed with a call to <code>matrixSslDeleteKeys</code>.</p>
<h2 id="33-creating-a-session">3.3 Creating a Session</h2>
<p>The next MatrixSSL integration point in the application is when a new session is starting. In the case of a client, this is whenever it chooses to begin one because SSL is a client-initiated protocol (like HTTP). In the case of a server, a new session should be started when the server accepts an incoming connection from a client on a secure port. In a socket based application, this would typically happen when the accept socket call returns with a valid incoming socket. The application sets up a new session with the API <code>matrixSslNewClientSession</code> or <code>matrixSslNewServerSession</code>. The returned <code>ssl_t</code> context will become the input parameter for all public APIs that act at a per-session level.</p>
<p>The required input parameters to the session creation APIs differ based on whether the application is assuming a server or client role. Both require a populated keys structure (discussed in the previous section) but a client can also nominate a specific cipher suite or session ID when starting a session. The ciphers that the server will accept are determined at compile time. <br>
The client should also always nominate a certificate callback function during <code>matrixSslNewClientSession</code>. This callback function will be invoked mid-handshake to allow the user to inspect the key material, date and other certificate information sent from the server. For detailed information on this callback function, see the API documentation for the <em>Certificate Validation Callback Function</em> section.</p>
<p>The server may also choose to nominate a certificate callback function if client authentication is desired. The MatrixSSL library must have been compiled with <code>USE_CLIENT_AUTH</code> defined in order to use this parameter in the <code>matrixSslNewServerSession</code> function.</p>
<p>For clients wishing to quickly (and securely) reconnect to a server that it has recently connected to, there is an optional sessonId parameter that may be used to initiate a faster resumed handshake (the cpu intensive public key exchange is omitted). To use the session parameter, a client should allocate a <code>sslSessionId_t</code> structure with <code>matrixSslNewSessionId</code> and pass it to <code>matrixSslNewClientSession</code> during the initial connection with the server. Over the course of the session negotiation, the MatrixSSL library will populate that structure behind-the-scenes so that during the next connection the same sessionId parameter address can be used to initiate the resumed session.</p>
<h2 id="34-handshaking">3.4 Handshaking</h2>
<p>During client session initialization with <code>matrixSslNewClientSession</code> the SSL handshake message <code>CLIENT_HELLO</code> is encoded to the internal outgoing buffer. The client now needs to send this message to the server over a communication channel. <br>
The sequence of events that should always be used to transmit pending handshake data is as follows:</p>
<ol>
<li>The user calls <code>matrixSslGetOutdata</code> to retrieve the encoded data and number of bytes to be sent</li>
<li>The user sends the number of bytes indicated from the out data buffer pointer to the peer</li>
<li>The user calls <code>matrixSslSentData</code> with the actual number of bytes that were sent</li>
<li>If more data remains (bytes sent &lt; bytes to be sent), repeat the above 3 steps when the transport layer is ready to send again</li>
</ol>
<p>When the server receives notice that a client is starting a new session the <code>matrixSslNewServerSession</code> API is invoked and the incoming data is retrieved and processed. <br>
The sequence of events that should always be used when expecting handshake data from a peer is as follows:</p>
<ol>
<li>The application calls <code>matrixSslGetReadbuf</code> to retrieve a pointer to available buffer space in the <code>ssl_t</code> structure.</li>
<li>The application reads (or copies) incoming data into that buffer</li>
<li>The application calls <code>matrixSslReceivedData</code> to process the data</li>
<li>The application examines the return code from <code>matrixSslReceivedData</code> to determine the next step</li>
</ol>
<p>All incoming messages should be copied into the provided buffer and passed to <code>matrixSslReceivedData</code>, which processes the message and drives the handshake through the built-in SSLv3 or TLS state machine. The parameters include the SSL context and the number of bytes that have been received. The return code from <code>matrixSslReceivedData</code> tells the application what the message was and how it is to be handled:</p>
<dl>
<dt><code>MATRIXSSL_REQUEST_SEND</code></dt>
<dd>Success. The processing of the received data resulted in an SSL response message that needs to be sent to the peer. If this return code is hit the user should call <code>matrixSslGetOutdata</code> to retrieve the encoded outgoing data.</dd>
<dt><code>MATRIXSSL_REQUEST_RECV</code></dt>
<dd>Success. More data must be received and this function must be called again. User must first call <code>matrixSslGetReadbuf</code> again to receive the updated buffer pointer and length to where the remaining data should be read into.</dd>
<dt><code>MATRIXSSL_HANDSHAKE_COMPLETE</code></dt>
<dd>Success. The SSL handshake is complete. This return code is returned to client side implementation during a full handshake after parsing the <code>FINISHED</code> message from the server. It is possible for a server to receive this value if a resumed handshake is being performed where the client sends the final <code>FINISHED</code> message.</dd>
<dt><code>MATRIXSSL_RECEIVED_ALERT</code></dt>
<dd>Success. The data that was processed was an SSL alert message. In this case, the ptbuf pointer will be two bytes (ptLen will be 2) in which the first byte will be the alert level and the second byte will be the alert description. After examining the alert, the user must call <code>matrixSslProcessedData</code> to indicate the alert was processed and the data may be internally discarded.</dd>
<dt><code>MATRIXSSL_APP_DATA</code></dt>
<dd>Success. The data that was processed was application data that the user should process. In this return code case the ptbuf and ptLen output parameters will be valid. The user may process the data directly from ptbuf or copy it aside for later processing. After handling the data the user must call <code>matrixSslProcessedData</code> to indicate the plain text data may be internally discarded</dd>
<dt><code>PS_SUCCESS</code></dt>
<dd>Success. This return code will be returned if the bytes parameter is 0 and there is no remaining internal data to process. This could be useful as a polling mechanism to confirm the internal buffer is empty. One real life use-case for this method of invocation is when dealing with a <em>Google Chrome</em> browser that uses <em>False Start</em>.</dd>
<dt><code>&lt; 0</code></dt>
<dd>Failure. See API documentation</dd>
</dl>
<h2 id="35-communicating-securely-with-peers">3.5 Communicating Securely With Peers <i class="icon-users"></i></h2>
<h3 id="351-encrypting-data">3.5.1 Encrypting Data</h3>
<p>Once the handshake is complete, the application wishing to encrypt data that will be sent to the peer has the choice between two encoding options.</p>
<p><strong>In-Situ Encryption</strong> <br>
An in-situ encryption occurs when the outputted cipher text overwrites the plain text during the encoding process. In this case, the user will retrieve an allocated buffer from the MatrixSSL library, populate the buffer with the desired plaintext, and then notify the library that the plaintext is ready to be encoded. The API steps for the in-situ method are as follows:</p>
<ol>
<li>The application first determines the length of the plaintext that needs to be sent </li>
<li>The application calls <code>matrixSslGetWritebuf</code> with that length to retrieve a pointer to an internally allocated buffer.</li>
<li>The application writes the plaintext into the buffer and then calls <code>matrixSslEncodeWritebuf</code> to encrypt the plaintext</li>
<li>The application calls <code>matrixSslGetOutdata</code> to retrieve the encoded data and length to be sent (SSL always adds some overhead to the message size)</li>
<li>The application sends the out data buffer contents to the peer.</li>
<li>The application calls <code>matrixSslSentData</code> with the number of bytes that were actually sent</li>
</ol>
<p><strong>User provided plaintext data location</strong> <br>
The alternative to in-situ encryption is to allow the user to provide the location and length of the plaintext data that needs to be encoded. In this case, the encrypted data is still written to the internal MatrixSSL out data buffer but the user provided plaintext data is left untouched. The API steps for this method are as follows:</p>
<ol>
<li>The user passes the plaintext and length to <code>matrixSslEncodeToOutdata</code></li>
<li>The application calls <code>matrixSslGetOutdata</code> to retrieve the encoded data and length to be sent (SSL always adds some overhead to the message size)</li>
<li>The application sends the out data buffer contents to the peer.</li>
<li>The application calls <code>matrixSslSentData</code> with the # of bytes that were actually sent</li>
</ol>
<h3 id="352-decrypting-data">3.5.2 Decrypting Data</h3>
<p>The sequence of events that should always be used when expecting application data from a peer is as follows:</p>
<ol>
<li>The application calls <code>matrixSslGetReadbuf</code> to retrieve an allocated buffer</li>
<li>The application copies the incoming data into that buffer</li>
<li>The application calls <code>matrixSslReceivedData</code> to process the data</li>
<li>The application confirms the return code from <code>matrixSslReceivedData</code> is <code>MATRIXSSL_APP_DATA</code> and parses <code>ptLen</code> bytes of the returned plain text </li>
<li>If the return code does not indicate application data, handle the return code as described in the handshaking section above.</li>
<li>The application calls <code>matrixSslProcessedData</code> to inform the library it is finished with the plaintext and checks to see if there are additional records in the buffer to process.</li>
</ol>
<h2 id="36-ending-a-session">3.6 Ending a Session</h2>
<p>When the application receives notice that the session is complete or has determined itself that the session is complete, it should notify the other side, close the socket and delete the session. Calling <code>matrixSslEncodeClosureAlert</code> and <code>matrixSslDeleteSession</code> will perform this step. </p>
<p>A call to <code>matrixSslEncodeClosureAlert</code> is an optional step that will encode an alert message to pass along to the other side to inform them to close the session cleanly. The closure alert buffer is retrieved and sent using the same <code>matrixSslGetOutdata</code> then <code>matrixSslSentData</code> mechanism that all outgoing data uses. Since the connection is being closed, the application shouldn’t block indefinitely on sending the closure alert.</p>
<h2 id="37-closing-the-library">3.7 Closing the Library</h2>
<p>At application exit the MatrixSSL library should be un-initialized with a call to <code>matrixSslClose</code>. If the application has called <code>matrixSsNewKeys</code> as part of the initialization process and kept its keys in memory it should call <code>matrixSslDeleteKeys</code> before calling <code>matrixSslClose</code>. Also, any existing SSL sessions should be freed by calling <code>matrixSslDeleteSession</code> before calling <code>matrixSslClose</code>. </p>
<p>Example implementations of MatrixSSL client and server applications integration can be found in the apps subdirectory of the distribution package. </p>
<h1 id="4-configurable-features">4 CONFIGURABLE FEATURES <i class="icon-wrench"></i></h1>
<p>MatrixSSL contains a set of optional features that are configurable at compile time. This allows the user to remove unneeded functionality to reduce code size footprint and disable potentially insecure features. Each of these options are pre-processor defines that can be disabled by simply commenting out the #define in the header files or by using the -D compile flag during build. APIs with dependencies on optional features are highlighted in the Define Dependencies sub-section in the API documentation for that function.</p>
<p><em>Not all configurable options are listed below. See comments directly in configuration header files for more fine-tuning.</em></p>
<h2 id="41-protocol-and-performance">4.1 Protocol and Performance <i class="icon-gauge"></i></h2>
<dl>
<dt><code>USE_CLIENT_SIDE_SSL</code></dt>
<dd>matrixsslConfig.h - Enables client side SSL support</dd>
<dt><code>USE_SERVER_SIDE_SSL</code></dt>
<dd>matrixsslConfig.h - Enables server side SSL support</dd>
<dt><code>USE_TLS_1_2_AND_ABOVE</code></dt>
<dt><code>USE_TLS_1_1_AND_ABOVE</code></dt>
<dt><code>USE_TLS_1_0_AND_ABOVE</code></dt>
<dd>Enable one of these settings to specify which versions are compiled in. Clients or servers can select between compiled in versions at runtime if desired. Defaults to TLS 1.1 and above.</dd>
<dt><code>USE_DTLS</code></dt>
<dd>Support DTLS connections (TLS over UDP) in addition to TLS. DTLS version support is based on the underlying level of TLS support.</dd>
<dt><code>SSL_SESSION_TABLE_SIZE</code></dt>
<dd>matrixsslConfig.h – Applicable to servers only. The size of the session resumption table for caching session identifiers. Old entries will be overwritten when size is reached</dd>
<dt><code>SSL_SESSION_ENTRY_LIFE</code></dt>
<dd>matrixsslConfig.h – Applicable to servers only. The time in seconds that a session identifier will be valid in the session table. A value of 0 will disable SSL resumption. Also applies to the lifetime of Stateless Session Tickets, below.</dd>
<dt><code>USE_STATELESS_SESSION_TICKETS</code></dt>
<dd>matrixsslConfig.h – Enable stateless session tickets as defined in RFC 5077</dd>
<dt><code>USE_REHANDSHAKING</code></dt>
<dd>matrixsslConfig.h - Enable secure rehandshaking as defined in RFC 5746.</dd>
<dd>Legacy (insecure) rehandshaking is no longer supported.</dd>
<dd>Disabled by default.</dd>
<dt><code>REQUESTED_MAX_PLAINTEXT_RECORD_LEN</code></dt>
<dd>matrixsslConfig.h – Enable the “max_fragment_length” TLS extension defined in RFC 4366. Value of #define determines fragment length (server may reject)</dd>
<dt><code>USE_CLIENT_AUTH</code></dt>
<dd>matrixsslConfig.h - Enables two-way(mutual) authentication</dd>
<dt><code>USE_EXT_CERTIFICATE_VERIFY_SIGNING</code></dt>
<dd>matrixsslConfig.h - Enables client authentication using an external module. See the <code>MatrixSSL External Module Integration</code> manual for details.</dd>
<dt><code>SERVER_CAN_SEND_EMPTY_CERT_REQUEST</code></dt>
<dd>matrixsslConfig.h – A client authentication feature. Allows the server to send an empty CertificateRequest message if no CA files have been loaded</dd>
<dt><code>SERVER_WILL_ACCEPT_EMPTY_CLIENT_CERT_MSG</code></dt>
<dd>matrixsslConfig.h – A client authentication feature. Allows the server to ‘downgrade’ a client authentication handshake to a standard handshake if client does not provide a certificate</dd>
<dt><code>USE_ALPN</code></dt>
<dd>matrixsslConfig.h - Enable Application Level Protocol Negotiation. Also must be enabled via runtime option for new client sessions.</dd>
<dt><code>USE_TRUSTED_CA_INDICATION</code></dt>
<dd>matrixsslConfig.h - Enable the Trusted CA Indication extension defined in RFC 6066.</dd>
<dt><code>USE_OCSP</code></dt>
<dt><code>USE_OCSP_MUST_STAPLE</code></dt>
<dd>cryptoConfig.h and matrixsslConfig.h respectively. Enable OCSP and require OCSP stapling.</dd>
<dt><code>USE_X509</code></dt>
<dd>cryptoConfig.h - Enables basic support for X.509 certificates.</dd>
<dt><code>USE_CERT_PARSE</code></dt>
<dd>cryptoConfig.h - Enables X.509 certificate parsing.</dd>
<dt><code>USE_FULL_CERT_PARSE</code></dt>
<dd>cryptoConfig.h - Enables the parsing of some additional certificate extensions, such as nameConstraints and authorityInfoAccess.</dd>
<dt><code>USE_CERT_GEN</code></dt>
<dd>cryptoConfig.h - <em>(MatrixSSL Commercial Edition only:)</em> Enables X.509 certificate generation.</dd>
<dt><code>ENABLE_MD5_SIGNED_CERTS</code></dt>
<dt><code>ENABLE_SHA1_SIGNED_CERTS</code></dt>
<dd>cryptoConfig.h – Support MD5 or SHA1 signature algorithm in X.509 certificates and Certificate Revocation Lists.</dd>
<dt><code>ALWAYS_KEEP_CERT_DER</code></dt>
<dd>cryptoConfig.h - When parsing certificates, always also retain the unparsed DER data in the psX509Cert_t structure.</dd>
<dt><code>USE_CRL</code></dt>
<dd>cryptoConfig.h - Enable Certificate Revocation List APIs.</dd>
<dt><code>ALLOW_CRL_ISSUERS_WITHOUT_KEYUSAGE</code></dt>
<dd>cryptoConfig.h - Compatibility option. Allows CRL authentication to succeed when signer CA’s cert does not have the keyUsage extension.</dd>
<dt><code>USE_FIPS_CRYPTO</code></dt>
<dt><code>USE_CL_CRYPTO</code></dt>
<dd>cryptoConfig.h - <em>(MatrixSSL FIPS Edition only:)</em> Enable using the FIPS 140-2 validated SafeZone CL/FIPSLib 1.1 as the cryptographic library in MatrixSSL. For more information on FIPS 140-2 specific configuration options, please consult the <em>MatrixSSL with CL Library</em> document, included with the <em>MatrixSSL FIPS Edition</em>.</dd>
<dt><code>USE_CMS</code></dt>
<dd>cryptoConfig.h - <em>(MatrixSSL Commercial Edition only:)</em> Enable support for Cryptographic Messaging Syntax (CMS).</dd>
<dt><code>USE_RSA</code></dt>
<dt><code>USE_ECC</code></dt>
<dt><code>USE_DH</code></dt>
<dd>cryptoConfig.h - Enable RSA, ECC and DH support, respectively.</dd>
<dt><code>USE_DSA_VERIFY</code></dt>
<dd>cryptoConfig.h - <em>(MatrixSSL FIPS Edition only:)</em> Enable verification of DSA signatures in certificate validation.</dd>
<dt><code>MIN_RSA_SIZE</code></dt>
<dt><code>MIN_DH_SIZE</code></dt>
<dt><code>MIN_ECC_SIZE</code></dt>
<dd>cryptoConfig.h – The minimum size in bits that MatrixSSL will accept for key exchange for each algorithm. Prevents weak keys from being used or downgraded to.</dd>
<dt><code>USE_PRIVATE_KEY_PARSING</code></dt>
<dd>cryptoConfig.h - Enables X.509 private key parsing</dd>
<dt><code>USE_PKCS5</code></dt>
<dd>cryptoConfig.h - Enables the parsing of password protected private keys</dd>
<dt><code>USE_PKCS8</code></dt>
<dd>cryptoConfig.h - Enables the parsing of PKCS#8 formatted private keys</dd>
<dt><code>USE_PKCS12</code></dt>
<dd>cryptoConfig.h - Enables the parsing of PKCS#12 formatted certificate and key material</dd>
<dt><code>USE_BEAST_WORKAROUND</code></dt>
<dd>matrixssllib.h – Enabled by default. See code comments in file.</dd>
<dt><code>ENABLE_FALSE_START</code></dt>
<dd>matrixsslConfig.h - Disabled by default. See code comments in file.</dd>
<dt><code>NO_ECC_EPHEMERAL_CACHE</code></dt>
<dd>matrixsslConfig.h - By default, MatrixSSL caches the ECDHE keys it generates and re-uses the cached keys for connections within a certain time frame and a certain usage count. This improves performance of ECDHE suites, and is in line with the configuration current web browsers. Enabling NO_ECC_EPHEMERAL_CACHE disables the key caching and forces new ECDHE keys to be created for every TLS connection. Note that caching ECDHE keys is against some standards such as NIST SP 800-56A, and disallowed in the FIPS 140-2 mode of operation. NO_ECC_EPHEMERAL_CACHE is disabled by default.</dd>
<dt><code>ECC_EPHEMERAL_CACHE_SECONDS</code></dt>
<dt><code>ECC_EPHEMERAL_CACHE_USAGE</code></dt>
<dd>matrixssllib.h - The maximum time period and usage count of a cached ECDHE key. After these limits have been exceeded, the key will be removed from the cache.</dd>
<dt><code>USE_1024_KEY_SPEED_OPTIMIZATIONS</code></dt>
<dt><code>USE_2048_KEY_SPEED_OPTIMIZATIONS</code></dt>
<dt><code>PS_PUBKEY_OPTIMIZE_FOR_SMALLER_RAM</code></dt>
<dt><code>PS_PUBKEY_OPTIMIZE_FOR_FASTER_SPEED</code></dt>
<dd>crypto/layer/layer.h - RSA and Diffie-Hellman speed vs. runtime memory tradeoff. By default these will be enabled if the compiler is invoked with optimization that is not for size (eg. <code>-O1 to -O3</code>). They will be disabled for <code>-O0</code> and <code>-Os</code>.</dd>
<dt><code>PS_AES_IMPROVE_PERF_INCREASE_CODESIZE</code></dt>
<dt><code>PS_3DES_IMPROVE_PERF_INCREASE_CODESIZE</code></dt>
<dt><code>PS_MD5_IMPROVE_PERF_INCREASE_CODESIZE</code></dt>
<dt><code>PS_SHA1_IMPROVE_PERF_INCREASE_CODESIZE</code></dt>
<dd>crypto/layer/layer.h - Optionally enable for selected algorithms to improve performance at the cost of increased binary code size. By default these will be enabled if the compiler is invoked with optimization that is not for size (eg. <code>-O1 to -O3</code>). They will be disabled for <code>-O0</code> and <code>-Os</code>.</dd>
<dt><code>MATRIX_USE_FILE_SYSTEM</code></dt>
<dd>Determined automatically in core/osdep.h. Enables keys to be read from a filesystem, in addition to in-memory keys.</dd>
<dt><code>USE_MULTITHREADING</code></dt>
<dd>coreConfig.h: Enable if using MatrixSSL with a multithreading client or server, where session cache may be shared between threads simultaneously.</dd>
</dl>
<h2 id="42-public-key-math-assembly-optimizations">4.2 Public Key Math Assembly Optimizations <i class="icon-fighter-jet"></i></h2>
<p>Optimizing assembly code for low level math operations is available for many common processor architectures. The files <em>pstm_montgomery_reduce.c</em>, <em>pstm_mul_comba.c</em>, and <em>pstm_sqr_comba.c</em> in the <em>crypto/math</em> directory implement the available assembly optimizations. These following defines are set in the <em>osdep.h</em> header file by detecting the platform. These should be set accordingly when porting to an unsupported platform.</p>
<dl>
<dt><code>PSTM_X86</code></dt>
<dd>32-bit x86 processor</dd>
<dt><code>PSTM_X86_64</code></dt>
<dd>64-bit x86 processor</dd>
<dt><code>PSTM_ARM</code></dt>
<dd>ARMv4 or greater processor</dd>
<dt><code>PSTM_MIPS</code></dt>
<dd>32 bit MIPS processor</dd>
<dt><code>PSTM_PPC</code></dt>
<dd>32 bit PowerPC processor</dd>
<dt><em>None of the above</em></dt>
<dd>Standard C code implementation</dd>
</dl>
<h2 id="43-debug-configuration">4.3 Debug Configuration <i class="icon-bug"></i></h2>
<p>MatrixSSL contains a set of optional debug features that are configurable at compile time. Each of these options are pre-processor defines that can be disabled by simply commenting out the <code>#define</code> in the specified header files.</p>
<dl>
<dt><code>HALT_ON_PS_ERROR</code></dt>
<dd>coreConfig.h - Enables the osdepBreak platform function whenever a psError trace function is called. Helpful in debug environments.</dd>
<dt><code>USE_CORE_ERROR</code></dt>
<dt><code>USE_CORE_ASSERT</code></dt>
<dt><code>USE_CORE_TRACE</code></dt>
<dd>coreConfig.h - Enables the psTraceCore family of APIs that display function-level messages in the core module. Disabling these can reduce static code size significantly, as the trace strings will not be included in the final binary.</dd>
<dt><code>USE_CRYPTO_TRACE</code></dt>
<dd>cryptoConfig.h - Enables the psTraceCrypto family of APIs that display function-level messages in the crypto module.</dd>
<dt><code>USE_SSL_HANDSHAKE_MSG_TRACE</code></dt>
<dd>matrixsslConfig.h - Enables SSL handshake level debug trace for troubleshooting connection problems.</dd>
<dt><code>USE_SSL_INFORMATIONAL_TRACE</code></dt>
<dd>matrixsslConfig.h - Enables SSL function level debug trace for troubleshooting connection problems.</dd>
<dt><code>USE_DTLS_DEBUG_TRACE</code></dt>
<dd>matrixsslConfig.h - Enables DTLS-specific trace messages for troubleshooting connection problems.</dd>
<dt><code>DTLS_SEND_RECORDS_INDIVIDUALLY</code></dt>
<dd>matrixsslConfig.h - If enabled, each DTLS handshake message will be returned individually when matrixDtlsGetOutdata is called. When left disabled, the default behaviour of matrixDtlsGetOutdata is to return as much data as possible that fits within the maximum PMTU.</dd>
</dl>
<h2 id="44-minimum-firmware-configuration">4.4 Minimum Firmware Configuration <i class="icon-leaf"></i></h2>
<p>MatrixSSL can be built to a minimum size using TLS 1.2, PSK cipher with AES128 and SHA256. If interoperability with <em>OpenSSL</em> is desired, then a few changes are necessary, since the USE_TLS_PSK_WITH_AES_128_CBC_SHA256 ciphersuite is not implemented by OpenSSL (as of 1.0.2d). In this case, <code>USE_SHA1</code> and <code>USE_HMAC_SHA1</code> must also be defined and the cipher suite changed to <br>
<code>USE_TLS_PSK_WITH_AES_256_CBC_SHA</code> or <br>
<code>USE_TLS_PSK_WITH_AES_128_CBC_SHA</code>.</p>
<p>To enable minimal configuration, all options in <em>core/coreConfig.h</em>, <em>crypto/cryptoConfig.h</em> and <em>matrixssl/matrixsslConfig.h</em> should be commented out, except for the following:</p>
<dl>
<dt><em>coreConfig.h</em></dt>
<dd>Optional: USE_MATRIX_MEMORY_MANAGEMENT <br>
Optional: Disable <code>USE_CORE_ERROR</code> and <code>USE_CORE_ASSERT</code></dd>
<dt><em>cryptoConfig.h</em></dt>
<dd><code>USE_AES_CBC</code>, <code>USE_SHA256</code>, <code>USE_HMAC</code>, <code>USE_HMAC_SHA256</code> <br>
Optional: <code>__AES__</code> block to enable <em>AESNI</em> on <em>Intel</em> platforms. <br>
Optional: For <em>OpenSSL</em> compatibility, also enable <code>USE_SHA1</code> and <code>USE_HMAC_SHA1</code></dd>
<dt><em>matrixsslConfig.h</em></dt>
<dd><code>USE_TLS_PSK_WITH_AES_128_CBC_SHA256</code> <br>
<code>USE_TLS_1_2_AND_ABOVE</code>, <code>USE_CLIENT_SIDE_SSL</code> and/or <code>USE_SERVER_SIDE_SSL</code> <br>
Optional: <code>SSL_DEFAULT_IN_BUF_SIZE</code>, <code>SSL_DEFAULT_OUT_BUF_SIZE</code> set to 1500 for reduced RAM footprint. <br>
Optional for Server: <code>SSL_SESSION_TABLE_SIZE</code> as low as 1 for reduced RAM footprint. <br>
Optional: <code>USE_DTLS</code> <br>
Optional: For <em>OpenSSL</em> compatibility, enable: <br>
<code>USE_TLS_PSK_WITH_AES_256_CBC_SHA</code> or <br>
<code>USE_TLS_PSK_WITH_AES_128_CBC_SHA</code></dd>
</dl>
<p><strong>Code + Data Size ARM Thumb 2 Results:</strong></p>
<table>
<thead>
<tr>
<th align="center"><code>PSK_AES128_SHA256</code></th>
<th align="center"><code>PSK_AES128_SHA1</code></th>
</tr>
</thead>
<tbody><tr>
<td align="center">24,108 B</td>
<td align="center">25,771 B</td>
</tr>
</tbody></table>
<h2 id="45-example-configurations">4.5 Example configurations</h2>
<p>MatrixSSL ships with a few example configurations, which are described here. <em>MatrixSSL FIPS edition</em> contains additional example configurations; these are described in the <em>MatrixCrypto CL</em> document included in that distribution.</p>
<table>
<thead>
<tr>
<th>Configuration</th>
<th>Comment</th>
</tr>
</thead>
<tbody><tr>
<td>default</td>
<td>The default configuration</td>
</tr>
<tr>
<td>nonfips</td>
<td>Same as default</td>
</tr>
<tr>
<td>noecc</td>
<td>Disables ECC support</td>
</tr>
<tr>
<td>rsaonly</td>
<td>Disables ECC and DH support</td>
</tr>
<tr>
<td>tls</td>
<td>The recommended configuration for TLS</td>
</tr>
<tr>
<td>nonfips-psk</td>
<td>The minimal PSK configuration described in the last subsection, except that both server- and client side support are enabled.</td>
</tr>
</tbody></table>
<p>These configurations can be applied with the commands <em>make all-nonfips</em>, <em>make all-noecc</em>, <em>make all-rsaonly</em>, <em>make all-tls</em>, <em>make all-nonfips-psk</em> respectively. Applying a new configuration will override the existing <em>./core/coreConfig.h</em>, <em>./crypto/cryptoConfig.h</em>, and <em>./matrixssl/matrixsslConfig.h</em> files. After applying the configuration, these files can be further adapted per specific needs and the MatrixSSL can be compiled as usual, via the make commands described in the <em>MatrixSSL Getting Started</em> document.</p>
<h1 id="5-ssl-handshaking">5 SSL HANDSHAKING <i class="icon-exchange"></i></h1>
<p>The core of SSL security is the handshake protocol that allows two peers to authenticate and negotiate symmetric encryption keys. A handshake is defined by the specific sequence of SSL messages that are exchanged between the client and server. A collection of messages being sent from one peer to another is called a flight.</p>
<h2 id="51-standard-handshake">5.1 Standard Handshake</h2>
<p>The standard handshake is the most common and allows a client to authenticate a server. There are four flights in the standard handshake. </p>
<div class="sequence-diagram"><svg height="770" version="1.1" width="274.5" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" style="overflow: hidden; position: relative; left: -0.25px; top: -0.765625px;"><desc>Created with Raphaël 2.1.2</desc><defs><path stroke-linecap="round" d="M5,0 0,2.5 5,5z" id="raphael-marker-block"></path><marker id="raphael-marker-endblock55-obj966" markerHeight="5" markerWidth="5" orient="auto" refX="2.5" refY="2.5"><use xlink:href="#raphael-marker-block" transform="rotate(180 2.5 2.5) scale(1,1)" stroke-width="1.0000" fill="#000" stroke="none"></use></marker><marker id="raphael-marker-endblock55-obj972" markerHeight="5" markerWidth="5" orient="auto" refX="2.5" refY="2.5"><use xlink:href="#raphael-marker-block" transform="rotate(180 2.5 2.5) scale(1,1)" stroke-width="1.0000" fill="#000" stroke="none"></use></marker><marker id="raphael-marker-endblock55-obj975" markerHeight="5" markerWidth="5" orient="auto" refX="2.5" refY="2.5"><use xlink:href="#raphael-marker-block" transform="rotate(180 2.5 2.5) scale(1,1)" stroke-width="1.0000" fill="#000" stroke="none"></use></marker><marker id="raphael-marker-endblock55-obj978" markerHeight="5" markerWidth="5" orient="auto" refX="2.5" refY="2.5"><use xlink:href="#raphael-marker-block" transform="rotate(180 2.5 2.5) scale(1,1)" stroke-width="1.0000" fill="#000" stroke="none"></use></marker><marker id="raphael-marker-endblock55-obj984" markerHeight="5" markerWidth="5" orient="auto" refX="2.5" refY="2.5"><use xlink:href="#raphael-marker-block" transform="rotate(180 2.5 2.5) scale(1,1)" stroke-width="1.0000" fill="#000" stroke="none"></use></marker><marker id="raphael-marker-endblock55-obj987" markerHeight="5" markerWidth="5" orient="auto" refX="2.5" refY="2.5"><use xlink:href="#raphael-marker-block" transform="rotate(180 2.5 2.5) scale(1,1)" stroke-width="1.0000" fill="#000" stroke="none"></use></marker><marker id="raphael-marker-endblock55-obj990" markerHeight="5" markerWidth="5" orient="auto" refX="2.5" refY="2.5"><use xlink:href="#raphael-marker-block" transform="rotate(180 2.5 2.5) scale(1,1)" stroke-width="1.0000" fill="#000" stroke="none"></use></marker><marker id="raphael-marker-endblock55-obj996" markerHeight="5" markerWidth="5" orient="auto" refX="2.5" refY="2.5"><use xlink:href="#raphael-marker-block" transform="rotate(180 2.5 2.5) scale(1,1)" stroke-width="1.0000" fill="#000" stroke="none"></use></marker><marker id="raphael-marker-endblock55-obj999" markerHeight="5" markerWidth="5" orient="auto" refX="2.5" refY="2.5"><use xlink:href="#raphael-marker-block" transform="rotate(180 2.5 2.5) scale(1,1)" stroke-width="1.0000" fill="#000" stroke="none"></use></marker><marker id="raphael-marker-endblock55-obj1011" markerHeight="5" markerWidth="5" orient="auto" refX="2.5" refY="2.5"><use xlink:href="#raphael-marker-block" transform="rotate(180 2.5 2.5) scale(1,1)" stroke-width="1.0000" fill="#000" stroke="none"></use></marker></defs><rect x="10" y="10" width="167" height="30" rx="0" ry="0" fill="none" stroke="#000000" style="" stroke-width="2"></rect><rect x="15" y="15" width="157" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="93.5" y="25" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">Standard TLS Handshake</tspan></text><rect x="10" y="50" width="57" height="40" rx="0" ry="0" fill="none" stroke="#000000" style="" stroke-width="2"></rect><rect x="20" y="60" width="37" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="38.5" y="70" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">Client</tspan></text><rect x="10" y="710" width="57" height="40" rx="0" ry="0" fill="none" stroke="#000000" style="" stroke-width="2"></rect><rect x="20" y="720" width="37" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="38.5" y="730" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">Client</tspan></text><path style="" fill="none" stroke="#000000" d="M38.5,90L38.5,710" stroke-width="2"></path><rect x="184.5" y="50" width="60" height="40" rx="0" ry="0" fill="none" stroke="#000000" style="" stroke-width="2"></rect><rect x="195" y="60" width="40" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="214.5" y="70" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">Server</tspan></text><rect x="184.5" y="710" width="60" height="40" rx="0" ry="0" fill="none" stroke="#000000" style="" stroke-width="2"></rect><rect x="195" y="720" width="40" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="214.5" y="730" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">Server</tspan></text><path style="" fill="none" stroke="#000000" d="M214.5,90L214.5,710" stroke-width="2"></path><rect x="78.5" y="105" width="96" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="126.5" y="115" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">CLIENT_HELLO</tspan></text><path style="" fill="none" stroke="#000000" d="M38.5,130C38.5,130,180.79715251922607,130,209.49281853018329,130" stroke-width="2" marker-end="url(#raphael-marker-endblock55-obj966)" stroke-dasharray="0"></path><rect x="204.5" y="150" width="-156" height="10" rx="0" ry="0" fill="none" stroke="#000000" style="" stroke-width="2"></rect><rect x="0" y="0" width="0" height="0" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="126.5" y="155" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="155"></tspan></text><rect x="76.5" y="175" width="100" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="126.5" y="185" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">SERVER_HELLO</tspan></text><path style="" fill="none" stroke="#000000" d="M214.5,200C214.5,200,72.20284748077393,200,43.507181469816715,200" stroke-width="2" marker-end="url(#raphael-marker-endblock55-obj972)" stroke-dasharray="0"></path><rect x="86" y="215" width="81" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="126.5" y="225" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">CERTIFICATE</tspan></text><path style="" fill="none" stroke="#000000" d="M214.5,240C214.5,240,72.20284748077393,240,43.507181469816715,240" stroke-width="2" marker-end="url(#raphael-marker-endblock55-obj975)" stroke-dasharray="0"></path><rect x="54" y="255" width="145" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="126.5" y="265" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">SERVER_HELLO_DONE</tspan></text><path style="" fill="none" stroke="#000000" d="M214.5,280C214.5,280,72.20284748077393,280,43.507181469816715,280" stroke-width="2" marker-end="url(#raphael-marker-endblock55-obj978)" stroke-dasharray="0"></path><rect x="204.5" y="300" width="-156" height="10" rx="0" ry="0" fill="none" stroke="#000000" style="" stroke-width="2"></rect><rect x="0" y="0" width="0" height="0" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="126.5" y="305" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="305"></tspan></text><rect x="48.5" y="325" width="156" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="126.5" y="335" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">CLIENT_KEY_EXCHANGE</tspan></text><path style="" fill="none" stroke="#000000" d="M38.5,350C38.5,350,180.79715251922607,350,209.49281853018329,350" stroke-width="2" marker-end="url(#raphael-marker-endblock55-obj984)" stroke-dasharray="0"></path><rect x="50" y="365" width="153" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="126.5" y="375" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">CHANGE_CIPHER_SPEC</tspan></text><path style="" fill="none" stroke="#000000" d="M38.5,390C38.5,390,180.79715251922607,390,209.49281853018329,390" stroke-width="2" marker-end="url(#raphael-marker-endblock55-obj987)" stroke-dasharray="0"></path><rect x="96.5" y="405" width="60" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="126.5" y="415" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">FINISHED</tspan></text><path style="" fill="none" stroke="#000000" d="M38.5,430C38.5,430,180.79715251922607,430,209.49281853018329,430" stroke-width="2" marker-end="url(#raphael-marker-endblock55-obj990)" stroke-dasharray="0"></path><rect x="204.5" y="450" width="-156" height="10" rx="0" ry="0" fill="none" stroke="#000000" style="" stroke-width="2"></rect><rect x="0" y="0" width="0" height="0" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="126.5" y="455" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="455"></tspan></text><rect x="50" y="475" width="153" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="126.5" y="485" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">CHANGE_CIPHER_SPEC</tspan></text><path style="" fill="none" stroke="#000000" d="M214.5,500C214.5,500,72.20284748077393,500,43.507181469816715,500" stroke-width="2" marker-end="url(#raphael-marker-endblock55-obj996)" stroke-dasharray="0"></path><rect x="96.5" y="515" width="60" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="126.5" y="525" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">FINISHED</tspan></text><path style="" fill="none" stroke="#000000" d="M214.5,540C214.5,540,72.20284748077393,540,43.507181469816715,540" stroke-width="2" marker-end="url(#raphael-marker-endblock55-obj999)" stroke-dasharray="0"></path><rect x="204.5" y="560" width="-156" height="10" rx="0" ry="0" fill="none" stroke="#000000" style="" stroke-width="2"></rect><rect x="0" y="0" width="0" height="0" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="126.5" y="565" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="565"></tspan></text><rect x="28.5" y="590" width="196" height="30" rx="0" ry="0" fill="none" stroke="#000000" style="" stroke-width="2"></rect><rect x="94" y="595" width="66" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="126.5" y="605" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">APP_DATA</tspan></text><rect x="204.5" y="640" width="-156" height="10" rx="0" ry="0" fill="none" stroke="#000000" style="" stroke-width="2"></rect><rect x="0" y="0" width="0" height="0" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="126.5" y="645" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="645"></tspan></text><rect x="72" y="665" width="109" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="126.5" y="675" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">CLOSURE_ALERT</tspan></text><path style="" fill="none" stroke="#000000" d="M214.5,690C214.5,690,72.20284748077393,690,43.507181469816715,690" stroke-width="2" marker-end="url(#raphael-marker-endblock55-obj1011)" stroke-dasharray="0"></path></svg></div>
<p><strong>Client Notes</strong> <br>
The client is the first to send and the last to receive. Therefore, a MatrixSSL implementation of a client must be testing for the <code>MATRIXSSL_HANDSHAKE_COMPLETE</code> return code from <code>matrixSslReceivedData</code> to determine when application data is ready to be encrypted and sent to the server. When a client wishes to begin a standard handshake, <code>matrixSslNewClientSession</code> will be called with an empty sessionId.</p>
<h2 id="52-client-authentication-handshake">5.2 Client Authentication Handshake</h2>
<p>The client authentication handshake allows a two-way authentication. There are four flights in the client authentication handshake.</p>
<div class="sequence-diagram"><svg height="850" version="1.1" width="274.5" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" style="overflow: hidden; position: relative; left: -0.25px; top: -0.382813px;"><desc>Created with Raphaël 2.1.2</desc><defs><marker id="raphael-marker-endblock55-obj1052" markerHeight="5" markerWidth="5" orient="auto" refX="2.5" refY="2.5"><use xlink:href="#raphael-marker-block" transform="rotate(180 2.5 2.5) scale(1,1)" stroke-width="1.0000" fill="#000" stroke="none"></use></marker><marker id="raphael-marker-endblock55-obj1058" markerHeight="5" markerWidth="5" orient="auto" refX="2.5" refY="2.5"><use xlink:href="#raphael-marker-block" transform="rotate(180 2.5 2.5) scale(1,1)" stroke-width="1.0000" fill="#000" stroke="none"></use></marker><marker id="raphael-marker-endblock55-obj1061" markerHeight="5" markerWidth="5" orient="auto" refX="2.5" refY="2.5"><use xlink:href="#raphael-marker-block" transform="rotate(180 2.5 2.5) scale(1,1)" stroke-width="1.0000" fill="#000" stroke="none"></use></marker><marker id="raphael-marker-endblock55-obj1064" markerHeight="5" markerWidth="5" orient="auto" refX="2.5" refY="2.5"><use xlink:href="#raphael-marker-block" transform="rotate(180 2.5 2.5) scale(1,1)" stroke-width="1.0000" fill="#000" stroke="none"></use></marker><marker id="raphael-marker-endblock55-obj1067" markerHeight="5" markerWidth="5" orient="auto" refX="2.5" refY="2.5"><use xlink:href="#raphael-marker-block" transform="rotate(180 2.5 2.5) scale(1,1)" stroke-width="1.0000" fill="#000" stroke="none"></use></marker><marker id="raphael-marker-endblock55-obj1073" markerHeight="5" markerWidth="5" orient="auto" refX="2.5" refY="2.5"><use xlink:href="#raphael-marker-block" transform="rotate(180 2.5 2.5) scale(1,1)" stroke-width="1.0000" fill="#000" stroke="none"></use></marker><marker id="raphael-marker-endblock55-obj1076" markerHeight="5" markerWidth="5" orient="auto" refX="2.5" refY="2.5"><use xlink:href="#raphael-marker-block" transform="rotate(180 2.5 2.5) scale(1,1)" stroke-width="1.0000" fill="#000" stroke="none"></use></marker><marker id="raphael-marker-endblock55-obj1079" markerHeight="5" markerWidth="5" orient="auto" refX="2.5" refY="2.5"><use xlink:href="#raphael-marker-block" transform="rotate(180 2.5 2.5) scale(1,1)" stroke-width="1.0000" fill="#000" stroke="none"></use></marker><marker id="raphael-marker-endblock55-obj1082" markerHeight="5" markerWidth="5" orient="auto" refX="2.5" refY="2.5"><use xlink:href="#raphael-marker-block" transform="rotate(180 2.5 2.5) scale(1,1)" stroke-width="1.0000" fill="#000" stroke="none"></use></marker><marker id="raphael-marker-endblock55-obj1088" markerHeight="5" markerWidth="5" orient="auto" refX="2.5" refY="2.5"><use xlink:href="#raphael-marker-block" transform="rotate(180 2.5 2.5) scale(1,1)" stroke-width="1.0000" fill="#000" stroke="none"></use></marker><marker id="raphael-marker-endblock55-obj1091" markerHeight="5" markerWidth="5" orient="auto" refX="2.5" refY="2.5"><use xlink:href="#raphael-marker-block" transform="rotate(180 2.5 2.5) scale(1,1)" stroke-width="1.0000" fill="#000" stroke="none"></use></marker><marker id="raphael-marker-endblock55-obj1103" markerHeight="5" markerWidth="5" orient="auto" refX="2.5" refY="2.5"><use xlink:href="#raphael-marker-block" transform="rotate(180 2.5 2.5) scale(1,1)" stroke-width="1.0000" fill="#000" stroke="none"></use></marker></defs><rect x="10" y="10" width="178" height="30" rx="0" ry="0" fill="none" stroke="#000000" style="" stroke-width="2"></rect><rect x="15" y="15" width="168" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="99" y="25" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">Client Auth TLS Handshake</tspan></text><rect x="10" y="50" width="57" height="40" rx="0" ry="0" fill="none" stroke="#000000" style="" stroke-width="2"></rect><rect x="20" y="60" width="37" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="38.5" y="70" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">Client</tspan></text><rect x="10" y="790" width="57" height="40" rx="0" ry="0" fill="none" stroke="#000000" style="" stroke-width="2"></rect><rect x="20" y="800" width="37" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="38.5" y="810" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">Client</tspan></text><path style="" fill="none" stroke="#000000" d="M38.5,90L38.5,790" stroke-width="2"></path><rect x="184.5" y="50" width="60" height="40" rx="0" ry="0" fill="none" stroke="#000000" style="" stroke-width="2"></rect><rect x="195" y="60" width="40" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="214.5" y="70" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">Server</tspan></text><rect x="184.5" y="790" width="60" height="40" rx="0" ry="0" fill="none" stroke="#000000" style="" stroke-width="2"></rect><rect x="195" y="800" width="40" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="214.5" y="810" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">Server</tspan></text><path style="" fill="none" stroke="#000000" d="M214.5,90L214.5,790" stroke-width="2"></path><rect x="78.5" y="105" width="96" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="126.5" y="115" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">CLIENT_HELLO</tspan></text><path style="" fill="none" stroke="#000000" d="M38.5,130C38.5,130,180.79715251922607,130,209.49281853018329,130" stroke-width="2" marker-end="url(#raphael-marker-endblock55-obj1052)" stroke-dasharray="0"></path><rect x="204.5" y="150" width="-156" height="10" rx="0" ry="0" fill="none" stroke="#000000" style="" stroke-width="2"></rect><rect x="0" y="0" width="0" height="0" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="126.5" y="155" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="155"></tspan></text><rect x="76.5" y="175" width="100" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="126.5" y="185" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">SERVER_HELLO</tspan></text><path style="" fill="none" stroke="#000000" d="M214.5,200C214.5,200,72.20284748077393,200,43.507181469816715,200" stroke-width="2" marker-end="url(#raphael-marker-endblock55-obj1058)" stroke-dasharray="0"></path><rect x="86" y="215" width="81" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="126.5" y="225" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">CERTIFICATE</tspan></text><path style="" fill="none" stroke="#000000" d="M214.5,240C214.5,240,72.20284748077393,240,43.507181469816715,240" stroke-width="2" marker-end="url(#raphael-marker-endblock55-obj1061)" stroke-dasharray="0"></path><rect x="51.5" y="255" width="150" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="126.5" y="265" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">CERTIFICATE_REQUEST</tspan></text><path style="" fill="none" stroke="#000000" d="M214.5,280C214.5,280,72.20284748077393,280,43.507181469816715,280" stroke-width="2" marker-end="url(#raphael-marker-endblock55-obj1064)" stroke-dasharray="0"></path><rect x="54" y="295" width="145" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="126.5" y="305" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">SERVER_HELLO_DONE</tspan></text><path style="" fill="none" stroke="#000000" d="M214.5,320C214.5,320,72.20284748077393,320,43.507181469816715,320" stroke-width="2" marker-end="url(#raphael-marker-endblock55-obj1067)" stroke-dasharray="0"></path><rect x="204.5" y="340" width="-156" height="10" rx="0" ry="0" fill="none" stroke="#000000" style="" stroke-width="2"></rect><rect x="0" y="0" width="0" height="0" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="126.5" y="345" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="345"></tspan></text><rect x="48.5" y="365" width="156" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="126.5" y="375" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">CLIENT_KEY_EXCHANGE</tspan></text><path style="" fill="none" stroke="#000000" d="M38.5,390C38.5,390,180.79715251922607,390,209.49281853018329,390" stroke-width="2" marker-end="url(#raphael-marker-endblock55-obj1073)" stroke-dasharray="0"></path><rect x="60.5" y="405" width="133" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="126.5" y="415" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">CERTIFICATE_VERIFY</tspan></text><path style="" fill="none" stroke="#000000" d="M38.5,430C38.5,430,180.79715251922607,430,209.49281853018329,430" stroke-width="2" marker-end="url(#raphael-marker-endblock55-obj1076)" stroke-dasharray="0"></path><rect x="50" y="445" width="153" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="126.5" y="455" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">CHANGE_CIPHER_SPEC</tspan></text><path style="" fill="none" stroke="#000000" d="M38.5,470C38.5,470,180.79715251922607,470,209.49281853018329,470" stroke-width="2" marker-end="url(#raphael-marker-endblock55-obj1079)" stroke-dasharray="0"></path><rect x="96.5" y="485" width="60" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="126.5" y="495" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">FINISHED</tspan></text><path style="" fill="none" stroke="#000000" d="M38.5,510C38.5,510,180.79715251922607,510,209.49281853018329,510" stroke-width="2" marker-end="url(#raphael-marker-endblock55-obj1082)" stroke-dasharray="0"></path><rect x="204.5" y="530" width="-156" height="10" rx="0" ry="0" fill="none" stroke="#000000" style="" stroke-width="2"></rect><rect x="0" y="0" width="0" height="0" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="126.5" y="535" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="535"></tspan></text><rect x="50" y="555" width="153" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="126.5" y="565" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">CHANGE_CIPHER_SPEC</tspan></text><path style="" fill="none" stroke="#000000" d="M214.5,580C214.5,580,72.20284748077393,580,43.507181469816715,580" stroke-width="2" marker-end="url(#raphael-marker-endblock55-obj1088)" stroke-dasharray="0"></path><rect x="96.5" y="595" width="60" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="126.5" y="605" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">FINISHED</tspan></text><path style="" fill="none" stroke="#000000" d="M214.5,620C214.5,620,72.20284748077393,620,43.507181469816715,620" stroke-width="2" marker-end="url(#raphael-marker-endblock55-obj1091)" stroke-dasharray="0"></path><rect x="204.5" y="640" width="-156" height="10" rx="0" ry="0" fill="none" stroke="#000000" style="" stroke-width="2"></rect><rect x="0" y="0" width="0" height="0" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="126.5" y="645" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="645"></tspan></text><rect x="28.5" y="670" width="196" height="30" rx="0" ry="0" fill="none" stroke="#000000" style="" stroke-width="2"></rect><rect x="94" y="675" width="66" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="126.5" y="685" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">APP_DATA</tspan></text><rect x="204.5" y="720" width="-156" height="10" rx="0" ry="0" fill="none" stroke="#000000" style="" stroke-width="2"></rect><rect x="0" y="0" width="0" height="0" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="126.5" y="725" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="725"></tspan></text><rect x="72" y="745" width="109" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="126.5" y="755" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">CLOSURE_ALERT</tspan></text><path style="" fill="none" stroke="#000000" d="M214.5,770C214.5,770,72.20284748077393,770,43.507181469816715,770" stroke-width="2" marker-end="url(#raphael-marker-endblock55-obj1103)" stroke-dasharray="0"></path></svg></div>
<p><strong>Client Notes</strong> <br>
The client is the first to send and the last to receive. Therefore, a MatrixSSL implementation of a client must be testing for the <code>MATRIXSSL_HANDSHAKE_COMPLETE</code> return code from <code>matrixSslReceivedData</code> to determine when application data is ready to be encrypted and sent to the server.</p>
<p>In order to participate in a client authentication handshake, the client must have loaded a Certificate Authority file during the call to <code>matrixSslLoadRsaKeys</code>.</p>
<p><strong>Server Notes</strong> <br>
To prepare for a client authentication handshake the server must nominate a certificate and private key during the call to <code>matrixSslLoadRsaKeys</code>. The actual determination of whether or not to perform a client authentication handshake is made when nominating a certificate callback parameter when invoking <code>matrixSslNewServerSession</code>. If the callback is provided, a client authentication handshake will be requested. <br>
 </p>
<h2 id="53-session-resumption-handshake">5.3 Session Resumption Handshake</h2>
<p>Session resumption enables a previously connected client to quickly resume a session with a server. Session resumption is much faster than other handshake types because public key authentication is not performed (authentication is implicit since both sides will be using secret information from the previous connection). This handshake types has three flights.</p>
<div class="sequence-diagram"><svg height="620" version="1.1" width="271.5" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" style="overflow: hidden; position: relative; left: -0.25px; top: -0.601563px;"><desc>Created with Raphaël 2.1.2</desc><defs><marker id="raphael-marker-endblock55-obj1138" markerHeight="5" markerWidth="5" orient="auto" refX="2.5" refY="2.5"><use xlink:href="#raphael-marker-block" transform="rotate(180 2.5 2.5) scale(1,1)" stroke-width="1.0000" fill="#000" stroke="none"></use></marker><marker id="raphael-marker-endblock55-obj1144" markerHeight="5" markerWidth="5" orient="auto" refX="2.5" refY="2.5"><use xlink:href="#raphael-marker-block" transform="rotate(180 2.5 2.5) scale(1,1)" stroke-width="1.0000" fill="#000" stroke="none"></use></marker><marker id="raphael-marker-endblock55-obj1147" markerHeight="5" markerWidth="5" orient="auto" refX="2.5" refY="2.5"><use xlink:href="#raphael-marker-block" transform="rotate(180 2.5 2.5) scale(1,1)" stroke-width="1.0000" fill="#000" stroke="none"></use></marker><marker id="raphael-marker-endblock55-obj1150" markerHeight="5" markerWidth="5" orient="auto" refX="2.5" refY="2.5"><use xlink:href="#raphael-marker-block" transform="rotate(180 2.5 2.5) scale(1,1)" stroke-width="1.0000" fill="#000" stroke="none"></use></marker><marker id="raphael-marker-endblock55-obj1156" markerHeight="5" markerWidth="5" orient="auto" refX="2.5" refY="2.5"><use xlink:href="#raphael-marker-block" transform="rotate(180 2.5 2.5) scale(1,1)" stroke-width="1.0000" fill="#000" stroke="none"></use></marker><marker id="raphael-marker-endblock55-obj1159" markerHeight="5" markerWidth="5" orient="auto" refX="2.5" refY="2.5"><use xlink:href="#raphael-marker-block" transform="rotate(180 2.5 2.5) scale(1,1)" stroke-width="1.0000" fill="#000" stroke="none"></use></marker><marker id="raphael-marker-endblock55-obj1171" markerHeight="5" markerWidth="5" orient="auto" refX="2.5" refY="2.5"><use xlink:href="#raphael-marker-block" transform="rotate(180 2.5 2.5) scale(1,1)" stroke-width="1.0000" fill="#000" stroke="none"></use></marker></defs><rect x="10" y="10" width="166" height="30" rx="0" ry="0" fill="none" stroke="#000000" style="" stroke-width="2"></rect><rect x="15" y="15" width="156" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="93" y="25" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">Resumed TLS Handshake</tspan></text><rect x="10" y="50" width="57" height="40" rx="0" ry="0" fill="none" stroke="#000000" style="" stroke-width="2"></rect><rect x="20" y="60" width="37" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="38.5" y="70" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">Client</tspan></text><rect x="10" y="560" width="57" height="40" rx="0" ry="0" fill="none" stroke="#000000" style="" stroke-width="2"></rect><rect x="20" y="570" width="37" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="38.5" y="580" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">Client</tspan></text><path style="" fill="none" stroke="#000000" d="M38.5,90L38.5,560" stroke-width="2"></path><rect x="181.5" y="50" width="60" height="40" rx="0" ry="0" fill="none" stroke="#000000" style="" stroke-width="2"></rect><rect x="192" y="60" width="40" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="211.5" y="70" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">Server</tspan></text><rect x="181.5" y="560" width="60" height="40" rx="0" ry="0" fill="none" stroke="#000000" style="" stroke-width="2"></rect><rect x="192" y="570" width="40" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="211.5" y="580" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">Server</tspan></text><path style="" fill="none" stroke="#000000" d="M211.5,90L211.5,560" stroke-width="2"></path><rect x="77" y="105" width="96" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="125" y="115" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">CLIENT_HELLO</tspan></text><path style="" fill="none" stroke="#000000" d="M38.5,130C38.5,130,178.14385986328125,130,206.50901889801025,130" stroke-width="2" marker-end="url(#raphael-marker-endblock55-obj1138)" stroke-dasharray="0"></path><rect x="201.5" y="150" width="-153" height="10" rx="0" ry="0" fill="none" stroke="#000000" style="" stroke-width="2"></rect><rect x="0" y="0" width="0" height="0" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="125" y="155" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="155"></tspan></text><rect x="75" y="175" width="100" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="125" y="185" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">SERVER_HELLO</tspan></text><path style="" fill="none" stroke="#000000" d="M211.5,200C211.5,200,71.85614013671875,200,43.490981101989746,200" stroke-width="2" marker-end="url(#raphael-marker-endblock55-obj1144)" stroke-dasharray="0"></path><rect x="48.5" y="215" width="153" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="125" y="225" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">CHANGE_CIPHER_SPEC</tspan></text><path style="" fill="none" stroke="#000000" d="M211.5,240C211.5,240,71.85614013671875,240,43.490981101989746,240" stroke-width="2" marker-end="url(#raphael-marker-endblock55-obj1147)" stroke-dasharray="0"></path><rect x="95" y="255" width="60" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="125" y="265" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">FINISHED</tspan></text><path style="" fill="none" stroke="#000000" d="M211.5,280C211.5,280,71.85614013671875,280,43.490981101989746,280" stroke-width="2" marker-end="url(#raphael-marker-endblock55-obj1150)" stroke-dasharray="0"></path><rect x="201.5" y="300" width="-153" height="10" rx="0" ry="0" fill="none" stroke="#000000" style="" stroke-width="2"></rect><rect x="0" y="0" width="0" height="0" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="125" y="305" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="305"></tspan></text><rect x="48.5" y="325" width="153" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="125" y="335" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">CHANGE_CIPHER_SPEC</tspan></text><path style="" fill="none" stroke="#000000" d="M38.5,350C38.5,350,178.14385986328125,350,206.50901889801025,350" stroke-width="2" marker-end="url(#raphael-marker-endblock55-obj1156)" stroke-dasharray="0"></path><rect x="95" y="365" width="60" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="125" y="375" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">FINISHED</tspan></text><path style="" fill="none" stroke="#000000" d="M38.5,390C38.5,390,178.14385986328125,390,206.50901889801025,390" stroke-width="2" marker-end="url(#raphael-marker-endblock55-obj1159)" stroke-dasharray="0"></path><rect x="201.5" y="410" width="-153" height="10" rx="0" ry="0" fill="none" stroke="#000000" style="" stroke-width="2"></rect><rect x="0" y="0" width="0" height="0" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="125" y="415" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="415"></tspan></text><rect x="28.5" y="440" width="193" height="30" rx="0" ry="0" fill="none" stroke="#000000" style="" stroke-width="2"></rect><rect x="92.5" y="445" width="66" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="125" y="455" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">APP_DATA</tspan></text><rect x="201.5" y="490" width="-153" height="10" rx="0" ry="0" fill="none" stroke="#000000" style="" stroke-width="2"></rect><rect x="0" y="0" width="0" height="0" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="125" y="495" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="495"></tspan></text><rect x="70.5" y="515" width="109" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="125" y="525" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">CLOSURE_ALERT</tspan></text><path style="" fill="none" stroke="#000000" d="M211.5,540C211.5,540,71.85614013671875,540,43.490981101989746,540" stroke-width="2" marker-end="url(#raphael-marker-endblock55-obj1171)" stroke-dasharray="0"></path></svg></div>
<p><strong>Client Notes</strong> <br>
The client is the first and the last to send data. Therefore, a MatrixSSL implementation of a client must be testing for the <code>MATRIXSSL_HANDSHAKE_COMPLETE</code> return code from <code>matrixSslSentData</code> to determine when application data is ready to be encrypted and sent to the server. <br>
The client initiates a session resumption handshake by reusing the same <code>sessionId_t</code> structure from a previously connected session when calling <code>matrixSslNewClientSession</code>.</p>
<p><strong>Server Notes</strong> <br>
The MatrixSSL server will cache a <code>SSL_SESSION_TABLE_SIZE</code> number of session IDs for resumption. The length of time a session ID will remain in the case is determined by <code>SSL_SESSION_ENTRY_LIFE</code>. Also, the server sends the <code>FINISHED</code> message first in this case, which is different from the standard handshake.</p>
<h2 id="54-other-handshakes">5.4 Other Handshakes</h2>
<p>Other cipher suites can require variations on the handshake flights. PSK cipher suites do not use any key exchange. DSA cipher suites do not use certificates, and DH/DHE/ECDH/ECDHE cipher suites may or may not use certificates for authentication.</p>
<h2 id="55-re-handshakes">5.5 Re-Handshakes</h2>
<p>A re-handshake is a handshake over a currently connected SSL session. A re-handshake may take the form of a standard handshake, a client authentication handshake, or a resumed handshake. Either the client or server may initiate a re-handshake.</p>
<blockquote>
<p>Re-handshaking is not often used and can be the source of cross protocol attacks and implementation bugs. MatrixSSL by default disables the <code>USE_REHANDSHAKING</code> option at compile time to reduce code size and complexity.</p>
</blockquote>
<p>The <code>matrixSslEncodeRehandshake</code> API is used to initiate a re-handshake. The three most common reasons for initiating re-handshakes are:</p>
<ol>
<li><em>Re-key the symmetric cryptographic material</em> <br>
Re-keying the symmetric keys adds an extra level of security for applications that require the connection be open for long periods of time or transferring large amounts of data. Periodic changes to the keys can discourage hackers who are mounting timing attacks on a connection.</li>
<li><em>Perform a client authentication handshake</em> <br>
A scenario may arise in which the server requires that the data being exchanged is only allowed for a client whose certificate has been authenticated, but the original negotiation took place without client authentication. In order to do a client authenticated re-handshake the server must call matrixSslEncodeRehandshake with a certificate callback parameter.</li>
<li><em>Change cipher spec</em> <br>
The cipher suite may be changed on a connected session using a re-handshake if needed. The client must call matrixSslEncodeRehandshake with the new cipherSpec. </li>
</ol>
<h3 id="551-disable-re-handshaking-at-runtime">5.5.1 Disable Re-Handshaking At Runtime</h3>
<p>Global disabling of re-handshakes can be controlled at compile time using the <code>USE_REHANDSHAKING</code> define but sometimes a per-session control of the feature is required. In these cases, the <code>matrixSslDisableRehandshakes</code> and <code>matrixSslReEnableRehandshakes</code> APIs are used.</p>
<h3 id="552-the-re-handshake-credit-mechanism">5.5.2 The Re-Handshake Credit Mechanism</h3>
<p>The re-handshake feature has been used at the entry point in a couple TLS attacks. In an effort to combat these attacks, MatrixSSL has incorporated a mechanism that prevents a peer from continually re-handshaking. This “re-handshake credit” mechanism is simply a count of how often the MatrixSSL-enabled application will allow a peer to request a re-handshake before sending the <code>NO_RENEGOTIATION</code> alert. The default number of credits is set using the <code>DEFAULT_RH_CREDITS</code> define in <em>matrixssllib.h</em>. The shipped default is 1. </p>
<p>In order to allow real-life conditions of re-handshakes, a single credit will be added after transmitting a given number of application data bytes. The default count of bytes that have to be sent before gaining a credit is set using the <code>BYTES_BEFORE_RH_CREDIT</code> define in <em>matrixssllib.h</em>. The shipped default is 20MB.</p>
<h1 id="6-optional-features">6 OPTIONAL FEATURES <i class="icon-cog-alt"></i></h1>
<p>This section describes some of the optional SSL handshake features. Additional details can be found in the API documentation for the specific functions that are referenced here.</p>
<h2 id="61-stateless-session-ticket-resumption">6.1 Stateless Session Ticket Resumption</h2>
<p><a href="https://tools.ietf.org/html/rfc5077">RFC 5077</a> defines an alternative method to the standard server-cached session ID mechanism. The stateless ticket mechanism allows the server to send an encrypted session ticket to the client that the client can use in a later connection to speed up the handshake process. The server does not have to store a large number of session ID entries when this stateless mechanism is used.</p>
<p><strong>Servers and Clients</strong> <br>
The feature is made available with the USE_STATELESS_SESSION_TICKETS define in <em>matrixsslConfig.h</em>. </p>
<p><strong>Clients</strong> <br>
Clients that wish to use the stateless session resumption mechanism must set the ticketResumption member of the <code>sslSessOpts_t</code> structure to 1 when calling <code>matrixSslNewClientSession</code>. <br>
With that session option set, the client only has to use the standard session resumption API, <code>matrixSslNewSessionId</code>, to complete the use of the feature. If a server does not support stateless session tickets, the standard resumption mechanism will still work.</p>
<p><strong>Servers</strong> <br>
The server must load at least one session ticket key using <code>matrixSslLoadSessionTicketKeys</code> to enable the feature. A user callback can optionally be registered that will be called each time a session ticket is received from a client. The callback will indicate to the user whether or not the server already has the correct ticket key cached. The callback can be used to locate a ticket key or to void the ticket and revert to a full handshake. The <code>matrixSslSetSessionTicketCallback</code> API is used to register this function. <br>
The MatrixSSL implementation for resumption does not renew the session ticket as described in section <a href="https://tools.ietf.org/html/rfc5077#section-3.1">3.1 of the RFC</a> (Figure 2). If the ticket is valid, the server progresses with the standard resumed handshake without a <code>NewSessionTicket</code> handshake message. If the server is unable to decrypt the session ticket, a full handshake will take place and a new session ticket will be issued. The MatrixSSL library also handles the expiration of a session ticket based on the value of the <code>SSL_SESSION_ENTRY_LIFE</code> in <em>matrixsslConfig.h</em>.</p>
<h2 id="62-server-name-indication-extension">6.2 Server Name Indication Extension</h2>
<p><a href="https://tools.ietf.org/html/rfc6066">RFC 6066</a> defines a TLS hello extension to allow the client to send the name of the server it is trying to securely connect to. This allows “virtual” servers to locate the correct server with the expected key material to complete the connection.</p>
<p><strong>Servers</strong> <br>
Server applications should register the SNI callback using <code>matrixSslRegisterSNICallback</code>. This function must be called immediately after <code>matrixSslNewServerSession</code> before the first incoming flight from the client is processed. The callback will be invoked during the processing of the <code>CLIENT_HELLO</code> message if the client has included the SNI extension. The callback will use the incoming hostname to locate the correct key material and return them in the <code>sslKeys_t</code> structure format.</p>
<p><strong>Clients</strong> <br>
Clients must include the SNI extension in the <code>CLIENT_HELLO</code> message. The utility function <code>matrixSslCreateSNIext</code> is provided to help format the extension given a hostname and hostname length. Once the extension format has been created it will be loaded into the <code>tlsExtension_t</code> structure with the <code>matrixSslLoadHelloExtension</code> API (<code>matrixSslNewHelloExtension</code> must first be called). The <code>tlsExtension_t</code> type is then passed to <code>matrixSslNewClientSession</code> to complete the client side SNI integration.</p>
<h2 id="63-extended-master-secret">6.3 Extended Master Secret</h2>
<p>The “extended master secret” as specified in <a href="https://tools.ietf.org/html/rfc7627">RFC 7627</a> is an important security feature for TLS implementations that use session resumption. The extended master secret feature associates the internal TLS master secret directly to the connection context to prevent man-in-the-middle attacks during session resumption. One such attack is a synchronizing triple handshake as described in <a href="https://mitls.org/pages/attacks/3SHAKE">Triple Handshakes and Cookie Cutters: Breaking and Fixing Authentication over TLS</a>.</p>
<p>This feature is always enabled by default in both MatrixSSL clients and servers. The peer agreement mechanism is the <code>CLIENT_HELLO</code> and <code>SERVER_HELLO</code> <code>extended_master_secret</code> extension.</p>
<p><strong>Clients</strong> <br>
A client will always include the <code>extended_master_secret</code> extension when creating the <code>CLIENT_HELLO</code> message. If the server replies with an <code>extended_master_secret</code>, the upgraded master secret generation will be used. If the server does not reply with an <code>extended_master_secret</code>, the standard master secret generation will be used for the connection.</p>
<p>A client may REQUIRE that a server support the <code>extended_master_secret</code> feature by setting the <code>extendedMasterSecret</code> member of <code>sslSessOpts_t</code> to 1. The <code>sslSessOpts_t</code> structure is passed to <code>matrixSslNewClientSession</code> when starting a TLS session. If <code>extendedMasterSecret</code> is set, the client will send a fatal <code>handshake_failure</code> alert to the server if the <code>extended_master_secret</code> extension is not included in the <code>SERVER_HELLO</code>. </p>
<p><strong>Servers</strong> <br>
A server will always reply with the <code>extended_master_secret</code> extension if the client includes it in the <code>CLIENT_HELLO</code> message.</p>
<p>A server may <strong>require</strong> that a client support the <code>extended_master_secret</code> feature by setting the <code>extendedMasterSecret</code> member of <code>sslSessOpts_t</code> to 1. The <code>sslSessOpts_t</code> structure is passed to <code>matrixSslNewServerSession</code> when starting a TLS session. If <code>extendedMasterSecret</code> is set, the server will send a fatal <code>handshake_failure</code> alert to the client if the <code>extended_master_secret</code> extension is not included in the <code>CLIENT_HELLO</code>. </p>
<p>When creating the session resumption information (either the standard session table or the stateless session ticket) the server will flag whether the extended master secret was used for the initial connection. When a client attempts session resumption, the <code>CLIENT_HELLO</code> must include the <code>extended_master_secret</code> extension if it was used in the initial connection. Likewise, if the initial connection did not use the <code>extended_master_secret</code> the session resumption <code>CLIENT_HELLO</code> must also exclude that extension. If there is a mismatch, the server will not allow the session resumption and a full handshake will occur instead.</p>
<h2 id="64-maximum-fragment-length">6.4 Maximum Fragment Length</h2>
<p><a href="https://tools.ietf.org/html/rfc6066">RFC 6066</a> defines a TLS extension for negotiating a smaller maximum message size. The default maximum is 16KB (and can’t be set larger). The only allowed sizes that may be negotiated are 512, 1024, 2048, or 4096 bytes. The client requests the feature in a <code>CLIENT_HELLO</code> extension and if the server agrees to the new maximum fragment length it will acknowledge that in the <code>SERVER_HELLO</code> reply.</p>
<p><strong>Clients</strong> <br>
To request a smaller maximum fragment length the user sets the maxFragLen member of the <code>sslSessOpts_t *</code> options parameter to 512, 1024, 2048, or 4096 when calling <code>matrixSslNewClientSession</code>. The server is free to deny the request.</p>
<p><strong>Servers</strong> <br>
Servers will agree to the maximum fragment length request by default. To disable the feature for a session, the user may set the <code>maxFragLen</code> member of the <code>sslSessOpts_t *</code> options parameter to -1 when calling <code>matrixSslNewServerSession</code>.</p>
<h2 id="65-truncated-hmac">6.5 Truncated HMAC</h2>
<p><a href="https://tools.ietf.org/html/rfc6066">RFC 6066</a> defines a TLS extension for negotiating an HMAC length of 10 bytes. The client requests the feature in a <code>CLIENT_HELLO</code> extension and if the server agrees to the truncation it will acknowledge that in the <code>SERVER_HELLO</code> reply.</p>
<p><strong>Clients</strong> <br>
To request a truncated HMAC session the user sets the <code>truncHmac</code> member of the <code>sslSessOpts_t *</code>options parameter to PS_TRUE when calling <code>matrixSslNewClientSession</code>. The server is free to deny the request.</p>
<p><strong>Servers</strong> <br>
Servers will agree to HMAC truncation by default. To disable the feature for a session, the user may set the <code>truncHmac</code> member of the <code>sslSessOpts_t *</code> options parameter to -1 when calling <code>matrixSslNewServerSession</code>.</p>
<h2 id="66-application-layer-protocol-negotiation-extension">6.6 Application Layer Protocol Negotiation Extension</h2>
<p><a href="https://tools.ietf.org/html/rfc7301">RFC 7301</a> defines a TLS hello extension that enables servers and client to agree on the protocol that will be used after the TLS handshake is complete. The idea is to embed the negotiation in the TLS handshake to save any round trips that might be needed to negotiate the protocol after the handshake. The extension works the same as any extension by the client sending a list of protocols it wishes to use in the <code>CLIENT_HELLO</code> and the server replying with an extension in the <code>SERVER_HELLO</code>. The trade-off for negotiating the protocol during the handshake is that both MatrixSSL servers and clients must be prepared to intervene in the middle of the handshake process via registered callback functions.</p>
<p><strong>Servers and Clients</strong> <br>
The ALPN extension APIs will be available only if the <code>USE_ALPN</code> define in <em>matrixsslConfig.h</em> is enabled at compile-time. The define <code>MAX_PROTO_EXT</code> is the maximum number of protocols that can be expected in the list of protocols. The default is 8 and can be found in <em>matrixssllib.h</em>.</p>
<p><strong>Servers</strong> <br>
Servers that wish to process ALPN extensions sent from a client must call the <code>matrixSslRegisterALPNCallback</code> function immediately after the session is created with <code>matrixSslNewServerSession</code>. The timing of the registration is important so that the callback can be associated with the proper session context before the first handshake message from the client is passed to <code>matrixSslReceivedData</code>.</p>
<p>The server ALPN callback that is registered with <code>matrixSslRegisterALPNCallback</code> must have a prototype of:</p>
<pre class="prettyprint"><code class="language-C hljs axapta"><span class="hljs-keyword">void</span> ALPN_callback(<span class="hljs-keyword">void</span> *ssl, <span class="hljs-keyword">short</span> protoCount, <span class="hljs-keyword">char</span> *proto[MAX_PROTO_EXT], int32_t protoLen[MAX_PROTO_EXT], int32_t *<span class="hljs-keyword">index</span>)</code></pre>
<dl>
<dt><code>ssl</code></dt>
<dd>parameter is the session context and may be typecast to an <code>ssl_t *</code> type if access is required.</dd>
<dt><code>protoCount</code></dt>
<dd>is the number of protocols that the client has sent in the <code>CLIENT_HELLO</code> extension. It is the count of the number of array entries in the <code>proto</code> and <code>protoLen</code> parameters to follow.</dd>
<dt><code>proto</code></dt>
<dd>parameter is the priority-ordered list of string protocol names the client wants to communicate with following the TLS handshake. The <code>protoLen</code> parameter holds the string lengths of the <code>proto</code> counterpart parameter for each protocol.</dd>
<dt><code>index</code></dt>
<dd>parameter is an output that the callback logic will assign based on the desired action:</dd>
</dl>
<ul>
<li>The index of the proto array member the server has agreed to use. The index is the zero-based index to the array so a return value of 0 will indicate the first protocol in the list. This selection will result in the server including its own ALPN extension in the <code>SERVER_HELLO</code> message with the chosen protocol.</li>
<li>A negative value assigned to index indicates the server is not willing to communicate using any of the protocols. A fatal “<code>no_application_protocol</code>” alert will be sent to the client and the handshake will terminate.</li>
<li>If the callback does not assign any value to the outgoing parameter, the server will not take any action. That is, neither a reply ALPN extension nor an alert will be sent to the client and the handshake will continue normally. </li>
</ul>
<p><strong>Clients</strong> <br>
To support this feature, clients must be able to generate the ALPN extension and also receive the server reply. </p>
<p>To generate the ALPN extension, the API <code>matrixSslCreateALPNext</code> is used in conjunction with the <code>matrixSslNewHelloExtension</code> or <code>matrixSslLoadHelloExtension</code> framework.</p>
<p>The <code>matrixSslCreateALPNext</code> API accepts an array of <code>unsigned char *</code> string values (array length of <code>MAX_PROTO_EXT</code>) along with a companion array that hold the string lengths for the protocol list. The function will format the protocols into the specified ALPN extension format and return that to the caller in the output parameters. Once the extension has been created the client must load the extension using the <code>matrixSslLoadHelloExtension</code> API (<code>matrixSslNewHelloExtension</code> must have been called as well). Finally, the extension must be passed to <code>matrixSslNewClientSession</code> in the extensions parameter. Here is what the ALPN extension creation and session start might look like:</p>
<pre class="prettyprint"><code class="language-C hljs cpp">tlsExtension_t * extension;
<span class="hljs-keyword">unsigned</span> <span class="hljs-keyword">char</span> *alpn[MAX_PROTO_EXT];
int32_t alpnLen[MAX_PROTO_EXT];
matrixSslNewHelloExtension(&amp;extension);
alpn[<span class="hljs-number">0</span>] = psMalloc(NULL, <span class="hljs-built_in">strlen</span>(<span class="hljs-string">"http/1.0"</span>));
<span class="hljs-built_in">memcpy</span>(alpn[<span class="hljs-number">0</span>], <span class="hljs-string">"http/1.0"</span>, <span class="hljs-built_in">strlen</span>(<span class="hljs-string">"http/1.0"</span>));
alpnLen[<span class="hljs-number">0</span>] = <span class="hljs-built_in">strlen</span>(<span class="hljs-string">"http/1.0"</span>);
alpn[<span class="hljs-number">1</span>] = psMalloc(NULL, <span class="hljs-built_in">strlen</span>(<span class="hljs-string">"http/1.1"</span>));
<span class="hljs-built_in">memcpy</span>(alpn[<span class="hljs-number">1</span>], <span class="hljs-string">"http/1.1"</span>, <span class="hljs-built_in">strlen</span>(<span class="hljs-string">"http/1.1"</span>));
alpnLen[<span class="hljs-number">1</span>] = <span class="hljs-built_in">strlen</span>(<span class="hljs-string">"http/1.1"</span>);
matrixSslCreateALPNext(NULL, <span class="hljs-number">2</span>, alpn, alpnLen, &amp;ext, &amp;extLen);
matrixSslLoadHelloExtension(extension, ext, extLen, EXT_ALPN);
psFree(alpn[<span class="hljs-number">0</span>]);
psFree(alpn[<span class="hljs-number">1</span>]);
matrixSslNewClientSession(&amp;ssl, keys, sid, g_cipher, g_ciphers, certCb, g_ip, extension, extensionCb, &amp;options);
matrixSslDeleteHelloExtension(extension);</code></pre>
<p>To receive the server reply to the ALPN extension the client must register an extension callback routine using the <code>extCb</code> parameter when calling <code>matrixSslNewClientSession</code>. The callback will be invoked with the ALPN extension ID of <code>EXT_ALPN</code> (16) with a format of a single byte length followed by the protocol string value the server has agreed to. <br>
See the example in <em>apps/ssl/client.c</em> for full implementation details.</p>
<h2 id="67-tls-fallback-scsv">6.7 TLS Fallback SCSV</h2>
<p><a href="https://tools.ietf.org/html/rfc7507">RFC 7507</a> defines a method to prevent protocol downgrade attacks. Such an attack is illustrated below:</p>
<div class="sequence-diagram"><svg height="778" version="1.1" width="511.5" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" style="overflow: hidden; position: relative; left: -0.25px; top: -0.617188px;"><desc>Created with Raphaël 2.1.2</desc><defs><marker id="raphael-marker-endblock55-obj1216" markerHeight="5" markerWidth="5" orient="auto" refX="2.5" refY="2.5"><use xlink:href="#raphael-marker-block" transform="rotate(180 2.5 2.5) scale(1,1)" stroke-width="1.0000" fill="#000" stroke="none"></use></marker><marker id="raphael-marker-endblock55-obj1219" markerHeight="5" markerWidth="5" orient="auto" refX="2.5" refY="2.5"><use xlink:href="#raphael-marker-block" transform="rotate(180 2.5 2.5) scale(1,1)" stroke-width="1.0000" fill="#000" stroke="none"></use></marker><marker id="raphael-marker-endblock55-obj1222" markerHeight="5" markerWidth="5" orient="auto" refX="2.5" refY="2.5"><use xlink:href="#raphael-marker-block" transform="rotate(180 2.5 2.5) scale(1,1)" stroke-width="1.0000" fill="#000" stroke="none"></use></marker><marker id="raphael-marker-endblock55-obj1225" markerHeight="5" markerWidth="5" orient="auto" refX="2.5" refY="2.5"><use xlink:href="#raphael-marker-block" transform="rotate(180 2.5 2.5) scale(1,1)" stroke-width="1.0000" fill="#000" stroke="none"></use></marker><marker id="raphael-marker-endblock55-obj1231" markerHeight="5" markerWidth="5" orient="auto" refX="2.5" refY="2.5"><use xlink:href="#raphael-marker-block" transform="rotate(180 2.5 2.5) scale(1,1)" stroke-width="1.0000" fill="#000" stroke="none"></use></marker><marker id="raphael-marker-endblock55-obj1237" markerHeight="5" markerWidth="5" orient="auto" refX="2.5" refY="2.5"><use xlink:href="#raphael-marker-block" transform="rotate(180 2.5 2.5) scale(1,1)" stroke-width="1.0000" fill="#000" stroke="none"></use></marker><marker id="raphael-marker-endblock55-obj1240" markerHeight="5" markerWidth="5" orient="auto" refX="2.5" refY="2.5"><use xlink:href="#raphael-marker-block" transform="rotate(180 2.5 2.5) scale(1,1)" stroke-width="1.0000" fill="#000" stroke="none"></use></marker><marker id="raphael-marker-endblock55-obj1243" markerHeight="5" markerWidth="5" orient="auto" refX="2.5" refY="2.5"><use xlink:href="#raphael-marker-block" transform="rotate(180 2.5 2.5) scale(1,1)" stroke-width="1.0000" fill="#000" stroke="none"></use></marker><marker id="raphael-marker-endblock55-obj1246" markerHeight="5" markerWidth="5" orient="auto" refX="2.5" refY="2.5"><use xlink:href="#raphael-marker-block" transform="rotate(180 2.5 2.5) scale(1,1)" stroke-width="1.0000" fill="#000" stroke="none"></use></marker><marker id="raphael-marker-endblock55-obj1249" markerHeight="5" markerWidth="5" orient="auto" refX="2.5" refY="2.5"><use xlink:href="#raphael-marker-block" transform="rotate(180 2.5 2.5) scale(1,1)" stroke-width="1.0000" fill="#000" stroke="none"></use></marker><marker id="raphael-marker-endblock55-obj1252" markerHeight="5" markerWidth="5" orient="auto" refX="2.5" refY="2.5"><use xlink:href="#raphael-marker-block" transform="rotate(180 2.5 2.5) scale(1,1)" stroke-width="1.0000" fill="#000" stroke="none"></use></marker></defs><rect x="10" y="10" width="183" height="30" rx="0" ry="0" fill="none" stroke="#000000" style="" stroke-width="2"></rect><rect x="15.5" y="15" width="173" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="101.5" y="25" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">Protocol Downgrade Attack</tspan></text><rect x="10" y="50" width="57" height="40" rx="0" ry="0" fill="none" stroke="#000000" style="" stroke-width="2"></rect><rect x="20" y="60" width="37" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="38.5" y="70" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">Client</tspan></text><rect x="10" y="718" width="57" height="40" rx="0" ry="0" fill="none" stroke="#000000" style="" stroke-width="2"></rect><rect x="20" y="728" width="37" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="38.5" y="738" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">Client</tspan></text><path style="" fill="none" stroke="#000000" d="M38.5,90L38.5,718" stroke-width="2"></path><rect x="238" y="50" width="73" height="40" rx="0" ry="0" fill="none" stroke="#000000" style="" stroke-width="2"></rect><rect x="248.5" y="60" width="53" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="274.5" y="70" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">Attacker</tspan></text><rect x="238" y="718" width="73" height="40" rx="0" ry="0" fill="none" stroke="#000000" style="" stroke-width="2"></rect><rect x="248.5" y="728" width="53" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="274.5" y="738" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">Attacker</tspan></text><path style="" fill="none" stroke="#000000" d="M274.5,90L274.5,718" stroke-width="2"></path><rect x="421.5" y="50" width="60" height="40" rx="0" ry="0" fill="none" stroke="#000000" style="" stroke-width="2"></rect><rect x="432" y="60" width="40" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="451.5" y="70" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">Server</tspan></text><rect x="421.5" y="718" width="60" height="40" rx="0" ry="0" fill="none" stroke="#000000" style="" stroke-width="2"></rect><rect x="432" y="728" width="40" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="451.5" y="738" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">Server</tspan></text><path style="" fill="none" stroke="#000000" d="M451.5,90L451.5,718" stroke-width="2"></path><rect x="168.5" y="105" width="153" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="245" y="115" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">CLIENT_HELLO (TLS 1.2)</tspan></text><path style="" fill="none" stroke="#000000" d="M38.5,130C38.5,130,399.6001789569855,130,446.50088579417206,130" stroke-width="2" marker-end="url(#raphael-marker-endblock55-obj1216)" stroke-dasharray="0"></path><rect x="284.5" y="145" width="157" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="363" y="155" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">SERVER_HELLO (TLS 1.2)</tspan></text><path style="" fill="none" stroke="#000000" d="M451.5,170C451.5,170,308.2777500003576,170,279.50042779583964,170" stroke-width="2" marker-end="url(#raphael-marker-endblock55-obj1219)" stroke-dasharray="0"></path><rect x="322.5" y="185" width="81" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="363" y="195" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">CERTIFICATE</tspan></text><path style="" fill="none" stroke="#000000" d="M451.5,210C451.5,210,308.2777500003576,210,279.50042779583964,210" stroke-width="2" marker-end="url(#raphael-marker-endblock55-obj1222)" stroke-dasharray="0"></path><rect x="290.5" y="225" width="145" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="363" y="235" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">SERVER_HELLO_DONE</tspan></text><path style="" fill="none" stroke="#000000" d="M451.5,250C451.5,250,308.2777500003576,250,279.50042779583964,250" stroke-width="2" marker-end="url(#raphael-marker-endblock55-obj1225)" stroke-dasharray="0"></path><rect x="441.5" y="270" width="-393" height="30" rx="0" ry="0" fill="none" stroke="#000000" style="" stroke-width="2"></rect><rect x="142.5" y="275" width="205" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="245" y="285" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">Attacker changes server response</tspan></text><rect x="48.5" y="306" width="216" height="38" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="156.5" y="325" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="-4">SSL_ALERT_PROTOCOL_VERSION</tspan><tspan dy="18" x="156.5">(1.2 unsupported)</tspan></text><path style="" fill="none" stroke="#000000" d="M274.5,358C274.5,358,77.58282071352005,358,43.49730310753512,358" stroke-width="2" marker-end="url(#raphael-marker-endblock55-obj1231)" stroke-dasharray="0"></path><rect x="441.5" y="378" width="-393" height="30" rx="0" ry="0" fill="none" stroke="#000000" style="" stroke-width="2"></rect><rect x="154.5" y="383" width="181" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="245" y="393" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">(Client retries lower versions)</tspan></text><rect x="168.5" y="423" width="153" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="245" y="433" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">CLIENT_HELLO (TLS 1.1)</tspan></text><path style="" fill="none" stroke="#000000" d="M38.5,448C38.5,448,399.6001789569855,448,446.50088579417206,448" stroke-width="2" marker-end="url(#raphael-marker-endblock55-obj1237)" stroke-dasharray="0"></path><rect x="48.5" y="463" width="216" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="156.5" y="473" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">SSL_ALERT_PROTOCOL_VERSION</tspan></text><path style="" fill="none" stroke="#000000" d="M274.5,488C274.5,488,77.58282071352005,488,43.49730310753512,488" stroke-width="2" marker-end="url(#raphael-marker-endblock55-obj1240)" stroke-dasharray="0"></path><rect x="168.5" y="503" width="153" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="245" y="513" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">CLIENT_HELLO (TLS 1.0)</tspan></text><path style="" fill="none" stroke="#000000" d="M38.5,528C38.5,528,399.6001789569855,528,446.50088579417206,528" stroke-width="2" marker-end="url(#raphael-marker-endblock55-obj1243)" stroke-dasharray="0"></path><rect x="48.5" y="543" width="216" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="156.5" y="553" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">SSL_ALERT_PROTOCOL_VERSION</tspan></text><path style="" fill="none" stroke="#000000" d="M274.5,568C274.5,568,77.58282071352005,568,43.49730310753512,568" stroke-width="2" marker-end="url(#raphael-marker-endblock55-obj1246)" stroke-dasharray="0"></path><rect x="168.5" y="583" width="153" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="245" y="593" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">CLIENT_HELLO (SSL 3.0)</tspan></text><path style="" fill="none" stroke="#000000" d="M38.5,608C38.5,608,399.6001789569855,608,446.50088579417206,608" stroke-width="2" marker-end="url(#raphael-marker-endblock55-obj1249)" stroke-dasharray="0"></path><rect x="166.5" y="623" width="157" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="245" y="633" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">SERVER_HELLO (SSL 3.0)</tspan></text><path style="" fill="none" stroke="#000000" d="M451.5,648C451.5,648,90.39982104301453,648,43.49911420582794,648" stroke-width="2" marker-end="url(#raphael-marker-endblock55-obj1252)" stroke-dasharray="0"></path><rect x="441.5" y="668" width="-393" height="30" rx="0" ry="0" fill="none" stroke="#000000" style="" stroke-width="2"></rect><rect x="124.5" y="673" width="241" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="245" y="683" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">Attacker exploits SSL3.0 Vulnerabilities</tspan></text></svg></div>
<p>MatrixSSL does not automatically do such version fallback, but client software using MatrixSSL may choose to do this for compatibility with unknown servers. In this case, the <code>TLS_FALLBACK_SCSV</code> option flag MUST be set for each connection attempt at a lower protocol version. This will mitigate the attack as follows:</p>
<div class="sequence-diagram"><svg height="654" version="1.1" width="480.5" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" style="overflow: hidden; position: relative; left: -0.25px; top: -0.167969px;"><desc>Created with Raphaël 2.1.2</desc><defs><marker id="raphael-marker-endblock55-obj1296" markerHeight="5" markerWidth="5" orient="auto" refX="2.5" refY="2.5"><use xlink:href="#raphael-marker-block" transform="rotate(180 2.5 2.5) scale(1,1)" stroke-width="1.0000" fill="#000" stroke="none"></use></marker><marker id="raphael-marker-endblock55-obj1299" markerHeight="5" markerWidth="5" orient="auto" refX="2.5" refY="2.5"><use xlink:href="#raphael-marker-block" transform="rotate(180 2.5 2.5) scale(1,1)" stroke-width="1.0000" fill="#000" stroke="none"></use></marker><marker id="raphael-marker-endblock55-obj1302" markerHeight="5" markerWidth="5" orient="auto" refX="2.5" refY="2.5"><use xlink:href="#raphael-marker-block" transform="rotate(180 2.5 2.5) scale(1,1)" stroke-width="1.0000" fill="#000" stroke="none"></use></marker><marker id="raphael-marker-endblock55-obj1305" markerHeight="5" markerWidth="5" orient="auto" refX="2.5" refY="2.5"><use xlink:href="#raphael-marker-block" transform="rotate(180 2.5 2.5) scale(1,1)" stroke-width="1.0000" fill="#000" stroke="none"></use></marker><marker id="raphael-marker-endblock55-obj1311" markerHeight="5" markerWidth="5" orient="auto" refX="2.5" refY="2.5"><use xlink:href="#raphael-marker-block" transform="rotate(180 2.5 2.5) scale(1,1)" stroke-width="1.0000" fill="#000" stroke="none"></use></marker><marker id="raphael-marker-endblock55-obj1317" markerHeight="5" markerWidth="5" orient="auto" refX="2.5" refY="2.5"><use xlink:href="#raphael-marker-block" transform="rotate(180 2.5 2.5) scale(1,1)" stroke-width="1.0000" fill="#000" stroke="none"></use></marker><marker id="raphael-marker-endblock55-obj1323" markerHeight="5" markerWidth="5" orient="auto" refX="2.5" refY="2.5"><use xlink:href="#raphael-marker-block" transform="rotate(180 2.5 2.5) scale(1,1)" stroke-width="1.0000" fill="#000" stroke="none"></use></marker></defs><rect x="10" y="10" width="210" height="30" rx="0" ry="0" fill="none" stroke="#000000" style="" stroke-width="2"></rect><rect x="15" y="15" width="200" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="115" y="25" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">Protocol Downgrade Prevention</tspan></text><rect x="10" y="50" width="57" height="40" rx="0" ry="0" fill="none" stroke="#000000" style="" stroke-width="2"></rect><rect x="20" y="60" width="37" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="38.5" y="70" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">Client</tspan></text><rect x="10" y="594" width="57" height="40" rx="0" ry="0" fill="none" stroke="#000000" style="" stroke-width="2"></rect><rect x="20" y="604" width="37" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="38.5" y="614" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">Client</tspan></text><path style="" fill="none" stroke="#000000" d="M38.5,90L38.5,594" stroke-width="2"></path><rect x="207" y="50" width="73" height="40" rx="0" ry="0" fill="none" stroke="#000000" style="" stroke-width="2"></rect><rect x="217.5" y="60" width="53" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="243.5" y="70" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">Attacker</tspan></text><rect x="207" y="594" width="73" height="40" rx="0" ry="0" fill="none" stroke="#000000" style="" stroke-width="2"></rect><rect x="217.5" y="604" width="53" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="243.5" y="614" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">Attacker</tspan></text><path style="" fill="none" stroke="#000000" d="M243.5,90L243.5,594" stroke-width="2"></path><rect x="390.5" y="50" width="60" height="40" rx="0" ry="0" fill="none" stroke="#000000" style="" stroke-width="2"></rect><rect x="401" y="60" width="40" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="420.5" y="70" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">Server</tspan></text><rect x="390.5" y="594" width="60" height="40" rx="0" ry="0" fill="none" stroke="#000000" style="" stroke-width="2"></rect><rect x="401" y="604" width="40" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="420.5" y="614" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">Server</tspan></text><path style="" fill="none" stroke="#000000" d="M420.5,90L420.5,594" stroke-width="2"></path><rect x="153" y="105" width="153" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="229.5" y="115" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">CLIENT_HELLO (TLS 1.2)</tspan></text><path style="" fill="none" stroke="#000000" d="M38.5,130C38.5,130,370.5800484418869,130,415.49517218134133,130" stroke-width="2" marker-end="url(#raphael-marker-endblock55-obj1296)" stroke-dasharray="0"></path><rect x="253.5" y="145" width="157" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="332" y="155" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">SERVER_HELLO (TLS 1.2)</tspan></text><path style="" fill="none" stroke="#000000" d="M420.5,170C420.5,170,277.2777500003576,170,248.50042779583964,170" stroke-width="2" marker-end="url(#raphael-marker-endblock55-obj1299)" stroke-dasharray="0"></path><rect x="291.5" y="185" width="81" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="332" y="195" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">CERTIFICATE</tspan></text><path style="" fill="none" stroke="#000000" d="M420.5,210C420.5,210,277.2777500003576,210,248.50042779583964,210" stroke-width="2" marker-end="url(#raphael-marker-endblock55-obj1302)" stroke-dasharray="0"></path><rect x="259.5" y="225" width="145" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="332" y="235" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">SERVER_HELLO_DONE</tspan></text><path style="" fill="none" stroke="#000000" d="M420.5,250C420.5,250,277.2777500003576,250,248.50042779583964,250" stroke-width="2" marker-end="url(#raphael-marker-endblock55-obj1305)" stroke-dasharray="0"></path><rect x="410.5" y="270" width="-362" height="30" rx="0" ry="0" fill="none" stroke="#000000" style="" stroke-width="2"></rect><rect x="127" y="275" width="205" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="229.5" y="285" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">Attacker changes server response</tspan></text><rect x="48.5" y="306" width="185" height="38" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="141" y="325" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="-4">ALERT_PROTOCOL_VERSION</tspan><tspan dy="18" x="141">(1.2 unsupported)</tspan></text><path style="" fill="none" stroke="#000000" d="M243.5,358C243.5,358,74.8634917140007,358,43.4911725455604,358" stroke-width="2" marker-end="url(#raphael-marker-endblock55-obj1311)" stroke-dasharray="0"></path><rect x="410.5" y="378" width="-362" height="30" rx="0" ry="0" fill="none" stroke="#000000" style="" stroke-width="2"></rect><rect x="139" y="383" width="181" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="229.5" y="393" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">(Client retries lower versions)</tspan></text><rect x="68.5" y="423" width="322" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="229.5" y="433" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">CLIENT_HELLO (TLS 1.1) with TLS_FALLBACK_SCSV</tspan></text><path style="" fill="none" stroke="#000000" d="M38.5,448C38.5,448,370.5800484418869,448,415.49517218134133,448" stroke-width="2" marker-end="url(#raphael-marker-endblock55-obj1317)" stroke-dasharray="0"></path><rect x="410.5" y="468" width="-157" height="66" rx="0" ry="0" fill="none" stroke="#000000" style="" stroke-width="2"></rect><rect x="271.5" y="473" width="121" height="56" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="332" y="501" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="-13">Server supports 1.2,</tspan><tspan dy="18" x="332">client should not</tspan><tspan dy="18" x="332">indicate fallback</tspan></text><rect x="118" y="549" width="223" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="229.5" y="559" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">ALERT_INAPPROPRIATE_FALLBACK</tspan></text><path style="" fill="none" stroke="#000000" d="M420.5,574C420.5,574,88.4199515581131,574,43.50482781865867,574" stroke-width="2" marker-end="url(#raphael-marker-endblock55-obj1323)" stroke-dasharray="0"></path></svg></div>
<p>The client indicates that the lower version being requested is due to a previous response from the server that it was not supported. If the server sees this flag, but supports a higher version, it will recognize that something is amiss and return an alert, rather than a valid <code>SERVER_HELLO</code>.</p>
<blockquote>
<p>Note that if the attacker attempted to remove the <code>TLS_FALLBACK_SCSV</code> indication from the message, the tampering would be detected by the server and client later, as part of the <code>FINISHED</code> message handshake hash validation. The indication is specified by the RFC as a special ciphersuite value, rather than a TLS extension for maximum compatibility.</p>
</blockquote>
<p><strong>Clients</strong> <br>
If the client connection is being made at a lower protocol level because the server indicated it did not support the desired level, the <code>fallbackScsv</code> member of the <code>sslSessOpts_t *</code>options parameter <em>must</em> be set to <code>PS_TRUE</code> when calling <code>matrixSslNewClientSession</code> to prevent this type of attack.</p>
<p><strong>Servers</strong> <br>
Servers will evaluate the FALLBACK_SCSV indication automatically as per RFC:</p>
<blockquote>
<p>If TLS_FALLBACK_SCSV appears in ClientHello.cipher_suites and the highest protocol version supported by the server is higher than the version indicated in ClientHello.client_version, the server MUST respond with a fatal inappropriate_fallback alert</p>
</blockquote>
<h2 id="68-ocsp">6.8 OCSP</h2>
<p>The Online Certificate Status Protocol (OCSP) is an alternative to the Certificate Revocation List (CRL) mechanism for performing certificate revocation tests on server keys. TLS integrates with OCSP in a mechanism known as <em>OCSP stapling</em>. This feature allows the client to request that the server provide a time-stamped OCSP response when presenting the X.509 certificate during the TLS handshake. The primary goal for this method is to allow resource constrained clients to perform certificate revocation tests without having to communicate with an OCSP Responder themselves. The general process is illustrated below. The MatrixSSL also <br>
supports OCSP request generation, to do revocation tests on certificates without <br>
TLS server supporting OCSP stapling.</p>
<p>OCSP stapling is specified in Section 8 (Certificate Status Request) of the TLS Extensions <a href="https://tools.ietf.org/html/rfc6066#section-8">RFC 6066</a>. The <code>USE_OCSP</code> define in cryptoConfig.h must be enabled for these features to be available.</p>
<div class="sequence-diagram"><svg height="600" version="1.1" width="492" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" style="overflow: hidden; position: relative; left: -0.25px; top: -0.183594px;"><desc>Created with Raphaël 2.1.2</desc><defs><marker id="raphael-marker-endblock55-obj1364" markerHeight="5" markerWidth="5" orient="auto" refX="2.5" refY="2.5"><use xlink:href="#raphael-marker-block" transform="rotate(180 2.5 2.5) scale(1,1)" stroke-width="1.0000" fill="#000" stroke="none"></use></marker><marker id="raphael-marker-endblock55-obj1367" markerHeight="5" markerWidth="5" orient="auto" refX="2.5" refY="2.5"><use xlink:href="#raphael-marker-block" transform="rotate(180 2.5 2.5) scale(1,1)" stroke-width="1.0000" fill="#000" stroke="none"></use></marker><marker id="raphael-marker-endblock55-obj1376" markerHeight="5" markerWidth="5" orient="auto" refX="2.5" refY="2.5"><use xlink:href="#raphael-marker-block" transform="rotate(180 2.5 2.5) scale(1,1)" stroke-width="1.0000" fill="#000" stroke="none"></use></marker><marker id="raphael-marker-endblock55-obj1379" markerHeight="5" markerWidth="5" orient="auto" refX="2.5" refY="2.5"><use xlink:href="#raphael-marker-block" transform="rotate(180 2.5 2.5) scale(1,1)" stroke-width="1.0000" fill="#000" stroke="none"></use></marker><marker id="raphael-marker-endblock55-obj1382" markerHeight="5" markerWidth="5" orient="auto" refX="2.5" refY="2.5"><use xlink:href="#raphael-marker-block" transform="rotate(180 2.5 2.5) scale(1,1)" stroke-width="1.0000" fill="#000" stroke="none"></use></marker><marker id="raphael-marker-endblock55-obj1385" markerHeight="5" markerWidth="5" orient="auto" refX="2.5" refY="2.5"><use xlink:href="#raphael-marker-block" transform="rotate(180 2.5 2.5) scale(1,1)" stroke-width="1.0000" fill="#000" stroke="none"></use></marker><marker id="raphael-marker-endblock55-obj1388" markerHeight="5" markerWidth="5" orient="auto" refX="2.5" refY="2.5"><use xlink:href="#raphael-marker-block" transform="rotate(180 2.5 2.5) scale(1,1)" stroke-width="1.0000" fill="#000" stroke="none"></use></marker></defs><rect x="10" y="10" width="102" height="30" rx="0" ry="0" fill="none" stroke="#000000" style="" stroke-width="2"></rect><rect x="15" y="15" width="92" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="61" y="25" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">OCSP Stapling</tspan></text><rect x="10" y="50" width="57" height="40" rx="0" ry="0" fill="none" stroke="#000000" style="" stroke-width="2"></rect><rect x="20" y="60" width="37" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="38.5" y="70" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">Client</tspan></text><rect x="10" y="540" width="57" height="40" rx="0" ry="0" fill="none" stroke="#000000" style="" stroke-width="2"></rect><rect x="20" y="550" width="37" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="38.5" y="560" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">Client</tspan></text><path style="" fill="none" stroke="#000000" d="M38.5,90L38.5,540" stroke-width="2"></path><rect x="273.5" y="50" width="60" height="40" rx="0" ry="0" fill="none" stroke="#000000" style="" stroke-width="2"></rect><rect x="284" y="60" width="40" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="303.5" y="70" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">Server</tspan></text><rect x="273.5" y="540" width="60" height="40" rx="0" ry="0" fill="none" stroke="#000000" style="" stroke-width="2"></rect><rect x="284" y="550" width="40" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="303.5" y="560" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">Server</tspan></text><path style="" fill="none" stroke="#000000" d="M303.5,90L303.5,540" stroke-width="2"></path><rect x="375" y="50" width="87" height="40" rx="0" ry="0" fill="none" stroke="#000000" style="" stroke-width="2"></rect><rect x="385.5" y="60" width="67" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="418.5" y="70" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">Responder</tspan></text><rect x="375" y="540" width="87" height="40" rx="0" ry="0" fill="none" stroke="#000000" style="" stroke-width="2"></rect><rect x="385.5" y="550" width="67" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="418.5" y="560" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">Responder</tspan></text><path style="" fill="none" stroke="#000000" d="M418.5,90L418.5,540" stroke-width="2"></path><rect x="318" y="105" width="86" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="361" y="115" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">OCSPRequest</tspan></text><path style="" fill="none" stroke="#000000" d="M303.5,130C303.5,130,391.3995367884636,130,413.50318007267197,130" stroke-width="2" marker-end="url(#raphael-marker-endblock55-obj1364)" stroke-dasharray="0"></path><rect x="313.5" y="145" width="95" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="361" y="155" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">OCSPResponse</tspan></text><path style="" fill="none" stroke="#000000" d="M418.5,170C418.5,170,330.6004632115364,170,308.49681992732803,170" stroke-width="2" marker-end="url(#raphael-marker-endblock55-obj1367)" stroke-dasharray="0"></path><rect x="201" y="190" width="205" height="30" rx="0" ry="0" fill="none" stroke="#000000" style="" stroke-width="2"></rect><rect x="206" y="195" width="195" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="303.5" y="205" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">matrixSslLoadOCSPResponse()</tspan></text><rect x="293.5" y="240" width="-245" height="30" rx="0" ry="0" fill="none" stroke="#000000" style="" stroke-width="2"></rect><rect x="165" y="245" width="12" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="171" y="255" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">...</tspan></text><rect x="67" y="285" width="208" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="171" y="295" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">CLIENT_HELLO (+status_request)</tspan></text><path style="" fill="none" stroke="#000000" d="M38.5,310C38.5,310,262.0442793369293,310,298.5012077053543,310" stroke-width="2" marker-end="url(#raphael-marker-endblock55-obj1376)" stroke-dasharray="0"></path><rect x="65" y="325" width="212" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="171" y="335" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">SERVER_HELLO (+status_request)</tspan></text><path style="" fill="none" stroke="#000000" d="M303.5,350C303.5,350,79.95572066307068,350,43.49879229464568,350" stroke-width="2" marker-end="url(#raphael-marker-endblock55-obj1379)" stroke-dasharray="0"></path><rect x="130.5" y="365" width="81" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="171" y="375" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">CERTIFICATE</tspan></text><path style="" fill="none" stroke="#000000" d="M303.5,390C303.5,390,79.95572066307068,390,43.49879229464568,390" stroke-width="2" marker-end="url(#raphael-marker-endblock55-obj1382)" stroke-dasharray="0"></path><rect x="48.5" y="405" width="245" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="171" y="415" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">CERTIFICATE_STATUS (OCSPResponse)</tspan></text><path style="" fill="none" stroke="#000000" d="M303.5,430C303.5,430,79.95572066307068,430,43.49879229464568,430" stroke-width="2" marker-end="url(#raphael-marker-endblock55-obj1385)" stroke-dasharray="0"></path><rect x="98.5" y="445" width="145" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="171" y="455" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">SERVER_HELLO_DONE</tspan></text><path style="" fill="none" stroke="#000000" d="M303.5,470C303.5,470,79.95572066307068,470,43.49879229464568,470" stroke-width="2" marker-end="url(#raphael-marker-endblock55-obj1388)" stroke-dasharray="0"></path><rect x="293.5" y="490" width="-245" height="30" rx="0" ry="0" fill="none" stroke="#000000" style="" stroke-width="2"></rect><rect x="165" y="495" width="12" height="20" rx="0" ry="0" fill="#ffffff" stroke="none" style=""></rect><text style="text-anchor: middle; font-family: Andale Mono,monospace; font-size: 16px;" x="171" y="505" text-anchor="middle" font-family="Andale Mono, monospace" font-size="16px" stroke="none" fill="#000000"><tspan dy="5">...</tspan></text></svg></div>
<p><strong>Clients</strong> <br>
A client application can request OCSP stapling by setting the OCSPstapling member of the <code>sslSessOpts_t</code> structure when invoking <code>matrixSslNewClientSession</code>. This flag will trigger the creation of the Certificate Status Request extension in the <code>CLIENT_HELLO</code> message. The resulting <code>status_request</code> extension will not specify any responder identification hints or request extensions. This indicates that the server is free to provide whatever OCSP response is relevant to its identity certificate.</p>
<p>In order to validate the signature of provided OCSP response, the client will have to verify the Certificate Authority of the OCSP responder. There are two places the MatrixSSL library will search for this CA file. The first place the library will look is in the CA material that is loaded in the standard <code>matrixSslLoadRsaKeys</code> (or <code>matrixSslLoadEcKeys</code>) API. If the CA file is not located in this pre-loaded key material, the library will next look to the server’s certificate chain. In practice, many TLS servers that implement OCSP stapling will create a certificate chain in which the parent certificate of the primary identity certificate also acts as the OCSP responder. At the time of the OCSP validation test, the <code>CERTIFICATE</code> message will have already been processed and validated. If the client has confirmed the server to have a valid chain of trust, it is appropriate to trust that same certificate chain to provide the OSCP response. If the client is unable to locate the CA file for the public key of the OCSP responder, the handshake will fail.</p>
<p>In order to validate the time stamp of the OCSP response the client library will invoke the <code>checkOCSPtimestamp</code> function in <em>crypto/keyformat/x509.c</em>. The default time window for accepting an OCSP response is 1 week and can be changed using the <code>OCSP_VALID_TIME_WINDOW</code> define in <em>cryptolib.h</em>.</p>
<p>The OCSP stapling specification does not have guidance on how a client should behave if a server does not provide a <code>CERTIFICATE_STATUS</code> message when requested. The <code>USE_OCSP_MUST_STAPLE</code> define in <em>matrixsslConfig.h</em> is included to allow the client application to require that the server provide the message. If <code>USE_OCSP_MUST_STAPLE</code> is enabled and the client has requested <code>CERTIFICATE_STATUS</code>, the handshake will abort if the server does not provide one.</p>
<p><strong>Servers</strong> <br>
A server application wishing to support OCSP stapling must communicate out of band with an OCSP responder to periodically update the signed OCSP response, as defined in <a href="https://tools.ietf.org/html/rfc6960">RFC 6960</a>. The response is loaded into MatrixSSL by calling <code>matrixSslLoadOCSPResponse</code>. This function takes a fully formed <code>OCSPResponse</code> ASN.1 buffer as defined in <a href="https://tools.ietf.org/html/rfc6960#section-4.2">RFC6960 section 4.2</a> and loads it into the provided <code>sslKeys_t</code> structure. Whenever the server application gets a new OCSP response, the same <code>matrixSslLoadOCSPResponse</code> API can be called to update the <code>sslKeys_t</code> structure.</p>
<p>When a client sends the <code>status_request</code> extension the server will look to see if an OCSP response is available in the <code>sslKeys_t</code> structure and reply with a <code>status_request</code> extension and the <code>CERTIFICATE_STATUS</code> message that holds the OCSP response for the client to validate.</p>
<h3 id="configuring-ocsp-feature-for-use">Configuring OCSP Feature for Use</h3>
<p>The OCSP functionality depends on definitions in <code>cryptoConfig.h</code>. Full read/write functionality and server features requires following defines:</p>
<pre class="c prettyprint"><code class=" hljs "><span class="hljs-preprocessor">#define USE_X509</span>
<span class="hljs-preprocessor">#define USE_CERT_PARSE</span>
<span class="hljs-preprocessor">#define USE_FULL_CERT_PARSE</span>
<span class="hljs-preprocessor">#define USE_CRL</span>
<span class="hljs-preprocessor">#define USE_OCSP</span>
<span class="hljs-preprocessor">#define USE_OCSP_MUST_STAPLE</span></code></pre>
<p>The standard configurations like <code>default</code> on <em>MatrixSSL</em> FIPS and Commercial releases have already neccessary features enabled.</p>
<h3 id="invoking-ocsp-manually">Invoking OCSP Manually</h3>
<h4 id="ocsp-example-application">OCSP Example Application</h4>
<p>OCSP use has example application <code>ocsp.c</code> in <code>apps/crypto</code> subdirectory of <em>MatrixSSL</em>. The compiled application will be known as <code>matrixOCSP</code>. <br>
This application can be used to create OCSP requests and get responses. The easiest way to study OCSP functionality is to use and examine this application. The application provides usage instructions when invoked without parameters. Some of most interesting options include <code>-request</code>and <code>-reply</code> which allow storing requests and responses for examination with various other tools supporting OCSP and/or ASN.1 DER/BER. <br>
The most MatrixSSL supported functions are used by this program.</p>
<p>The most of functionality of <code>ocsp.c</code> program is found in <code>OCSPRequestAndResponseTest()</code> function, and this function is most useful to study for creating OCSP requests and validating OCSP responses. </p>
<h4 id="creating-ocsp-request-data">Creating OCSP request data</h4>
<p>In MatrixSSL, function <code>matrixSslWriteOCSPRequestExt()</code> is used to create OCSP requests.</p>
<p>The function is invoked as follows:</p>
<pre class="c prettyprint"><code class=" hljs "><span class="hljs-keyword">if</span> (matrixSslWriteOCSPRequestExt(NULL,
subject,
issuer,
&amp;request,
&amp;requestLen,
&amp;info) != PS_SUCCESS) {
<span class="hljs-comment">/* Error handling */</span>
<span class="hljs-keyword">return</span> PS_FAILURE;
}</code></pre>
<p>The memory pool is usually passed in as NULL. The certificates <code>subject</code> (certificate to check) and <code>issuer</code> (for issuer of certificate to check needs to be provided). New memory will be allocated for request and the pointer of request will be written to <code>request</code>, and the amount of memory allocated will be written to <code>requestLen</code>.</p>
<p><code>info</code> is used to provide options for OCSP request. These options are discussed below. The memory allocated for OCSP request shall be freed after the request <br>
is no longer needed.</p>
<h5 id="providing-nonce-extension">Providing Nonce Extension</h5>
<p>The <em>MatrixSSL</em> provides nonce for OCSP nonce extension via <code>info.flags</code> flag <code>MATRIXSSL_WRITE_OCSP_REQUEST_FLAG_NONCE</code>. The OCSP nonce extension provide unique nonce value, which can be used to the request is replied with a new (rather than cached) OCSP response.</p>
<h5 id="providing-name-for-requestor-requestorname">Providing name for requestor (requestorName)</h5>
<p>The MatrixSSL allows providing name for OCSP requestor. The name is represented <br>
using X.509 GeneralName. matrixSslWriteOCSPRequestInfoSetRequestorId() function <br>
is provided to help encoding the OCSP requestor name in suitable format for <br>
OCSP request. Note: This option is relatively rarely used and some OCSP <br>
Responders will reject requests with RequestorName.</p>
<h5 id="providing-list-of-requests-requestlist">Providing list of requests (requestList)</h5>
<p>If <code>matrixSslWriteOCSPRequestInfo_t</code> flag <code>MATRIXSSL_WRITE_OCSP_REQUEST_FLAG_CERT_LIST</code> is specified, <br>
then OCSP request is made concerning a list of certificates linked <br>
(via <code>subject-&gt;next</code>). This is a convenient way to allow for less network <br>
traffic when working with the certificates from the same issuer. <br>
Note: Some OCSP responders only support single request, and will reject requests <br>
concerning multiple certificates.</p>
<h4 id="interacting-with-ocsp-server">Interacting with OCSP server</h4>
<p>The most OCSP servers use <strong>HTTP</strong> protocol. The <em>MatrixSSL</em> provides <code>psUrlInteract()</code> function, to create HTTP request and get HTTP response. When OCSP is used in SSL/TLS context, the most commonly <code>subject</code> certificate will contain AuthorityInfoAccess information regarding what server will provide OCSP information. It is accessed via <code>authorityInfoAccess</code> field of the Certificate structure <code>psX509Cert_t</code>.</p>
<p>You can see <code>getOCSPResponse()</code> function in <code>ocsp.c</code> for a concrete example on how to interact with the server.</p>
<p>To use HTTP protocol, it is necessary to know the correct URL. The URL is in practice commonly specified in AuthorityInfoAccess extensions of X.509 certificate. The following function will extract authority information from X.509 certificate. </p>
<pre class="prettyprint"><code class="language-{.c} hljs lasso">static char <span class="hljs-subst">*</span>getAuthorityInfoOCSP_URI(const psX509Cert_t <span class="hljs-subst">*</span>subject)
{
char <span class="hljs-subst">*</span>url <span class="hljs-subst">=</span> <span class="hljs-built_in">NULL</span>;
x509authorityInfoAccess_t <span class="hljs-subst">*</span>authInfo;
authInfo <span class="hljs-subst">=</span> subject<span class="hljs-subst">-&gt;</span>extensions<span class="hljs-built_in">.</span>authorityInfoAccess;
<span class="hljs-comment">/* Find the first AuthorityInfoAccess extension data with
OCSP information. */</span>
<span class="hljs-keyword">while</span>(authInfo <span class="hljs-subst">!=</span> <span class="hljs-built_in">NULL</span>) {
<span class="hljs-keyword">if</span> (authInfo<span class="hljs-subst">-&gt;</span>ocsp <span class="hljs-subst">&amp;&amp;</span> authInfo<span class="hljs-subst">-&gt;</span>ocspLen <span class="hljs-subst">&gt;</span> <span class="hljs-number">0</span>) {
url <span class="hljs-subst">=</span> calloc(<span class="hljs-number">1</span>, authInfo<span class="hljs-subst">-&gt;</span>ocspLen <span class="hljs-subst">+</span> <span class="hljs-number">1</span>);
<span class="hljs-keyword">if</span> (url) {
memcpy(url, authInfo<span class="hljs-subst">-&gt;</span>ocsp, authInfo<span class="hljs-subst">-&gt;</span>ocspLen);
}
break;
}
authInfo <span class="hljs-subst">=</span> authInfo<span class="hljs-subst">-&gt;</span>next;
}
<span class="hljs-keyword">return</span> url;
}</code></pre>
<p>The interaction will result in getting an HTTP error code or OCSP response. The OCSP response can be analyzed and verified using the functions described in the next chapter.</p>
<h4 id="working-with-ocsp-response">Working with OCSP response</h4>
<p>Working with OCSP response actually consists of four phases:</p>
<ul>
<li>Obtaining and checking issuer certificate</li>
<li>Parsing</li>
<li>Checking of time-stamps</li>
<li>Validation of response</li>
</ul>
<p>The functions support both OCSP responses just retrieved as response to a constructed OCSP request and cached OCSP requests. One type of cache OCSP response often used in SSL/TLS is the ones used in OCSP stapling.</p>
<h4 id="obtaining-and-checking-issuer-certificate">Obtaining and checking issuer certificate</h4>
<p>To validate OCSP response, an issuer certificate is used. Many organizations use the same certificates to sign OCSP responses than are used to validate certificates themselves. In this case, the issuer certificate has been obtained and validated already as part of X.509 certificate validation. In case, OCSP responses have been signed with other keys designated for that purpose, then they shall be validated just like any other X.509 intermediate certificate, e.g. using <code>psX509ParseCert()</code> and <code>psX509AuthenticateCert()</code>.</p>
<p>The certificate of keys intended to be used for OCSP may have been marked for that purpose. This can be checked e.g. with the following code: </p>
<pre class="prettyprint"><code class="language-{.c} hljs cs"><span class="hljs-keyword">bool</span> gotEKU_OCSP = <span class="hljs-keyword">false</span>;
<span class="hljs-keyword">bool</span> gotKU_OCSP = <span class="hljs-keyword">false</span>;
<span class="hljs-keyword">const</span> x509v3extensions_t *ext = &amp;issuer-&gt;extensions;
<span class="hljs-comment">/* Specific flag for OCSP. */</span>
<span class="hljs-keyword">if</span> ((ext-&gt;ekuFlags &amp; EXT_KEY_USAGE_OCSP_SIGNING) &gt; <span class="hljs-number">0</span>)
gotEKU_OCSP = <span class="hljs-keyword">true</span>;
<span class="hljs-comment">/* No OCSP specific flag, use generic digital signatures flag. */</span>
<span class="hljs-keyword">if</span> ((ext-&gt;keyUsageFlags &amp; KEY_USAGE_DIGITAL_SIGNATURE) &gt; <span class="hljs-number">0</span>)
gotKY_OCSP = <span class="hljs-keyword">true</span>;</code></pre>
<p>Only if both key usage and extended key usage flags are found in the certificate, the key can be considered to be marked for OCSP usage. However, many of the keys used for OCSP do not have this purpose marked in their certificate, and the most important validity check for OCSP signers remains ensuring that they have been signed by (one of) the CA root(s).</p>
<h4 id="parsing-ocsp-response">Parsing OCSP response</h4>
<p>OCSP response can be parsed using function <code>parseOCSPResponse()</code>. Parsing does not validate the response for correctness, but translates the response to internal form (<code>mOCSPResponse_t</code>), which allows easier working with the response.</p>
<h4 id="checking-time-stamps">Checking time-stamps</h4>
<p>The times in OCSP response are validated with <code>checkOCSPResponseDates()</code> function. The function will check the times in the OCSP response with respect to the current time and provide <code>struct tm</code> field representing various times (<em>ProducedAt</em>, <em>thisUpdate</em>, <em>nextUpdate</em>) within OCSP response. If OCSP response has timed out the function will return <code>PS_TIMEOUT_FAIL</code>.</p>
<p>The time validation function allows some clock skew between server and client. The default value is provided by <code>PS_OCSP_TIME_LINGER</code>, it is two minutes. It is possible to provide different values depending on how well the clocks are expected to be synchronized. </p>
<p>If OCSP response is found to be no longer valid or there is another issue in timestamps, then the application should not accept the OCSP response or process it further.</p>
<h4 id="validating-ocsp-response">Validating OCSP response</h4>
<p>The purpose of OCSP is to check if a certificate is revoked. <code>validateOCSPResponse_ex()</code> function is (finally) provided for this purpose. The function supports many different arguments. The options are used to pass in optional arguments.</p>
<pre class="c prettyprint"><code class=" hljs ">opts.knownFlag = &amp;known;
opts.revocationFlag = &amp;revocated;
opts.nonceMatch = &amp;nonceOk;
opts.revocationTime = &amp;revocationTime;
opts.revocationReason = &amp;revocationReason;
opts.request = request;
opts.requestLen = requestLen;
<span class="hljs-keyword">if</span> (validateOCSPResponse_ex(NULL,
issuer,
subject,
&amp;response,
&amp;opts) != PS_SUCCESS) {
<span class="hljs-comment">/* Error handling */</span>
<span class="hljs-keyword">return</span> PS_FAILURE;
}</code></pre>
<p>The memory pool is usually passed in as NULL. The certificates <code>subject</code> (certificate to check) and <code>issuer</code> (for expected issuer of certificate needs to be provided). <code>response</code> is the response to work with. This function returns <em>PS_SUCCESS</em> only when validation has been deemed success, and the certificate has not been found to be revoked.</p>
<p>In the simplest usage of this function, only the return code is checked. The <em>PS_SUCCESS</em> return code is only gotten if certificate is <strong>not revoked</strong> and the response has been successfully validated.</p>
<p><code>opts</code> is used to provide options for OCSP response parsing. These options will provide more information regarding successful and unsuccessful invocation of <code>validateOCSPResponse_ex()</code>. The options are discussed below.</p>
<h5 id="revocation-status-and-reason">Revocation status and reason</h5>
<p>Flag pointed by <code>opts.knownFlag</code> will be set to <em>true</em> (1) if OCSP response contained information regarding this certificate (<code>subject</code>). Responses not containing information regarding the certificate should be dismissed. <br>
If certificate has been revoked, flag pointed by <code>opts.revocationFlag</code> will be set to <em>true</em> (1). If available, variables pointed by <code>opts.revocationReason</code> and <code>opts.revocationTime</code> and will be set to indicate the revocation reason and time respectively. In OCSP protocol, revocation reasons are indicated by numbers between 1 and 10, the same codes used by CRL. (See function <code>mapRevocationReason()</code> in <code>ocsp.c</code> for mapping the numbers to various reasons). </p>
<h5 id="nonce-validation">Nonce validation</h5>
<p>For validating OCSP nonce, it is necessary to provide the OCSP request as pointer and length pair to <code>validateOCSPResponse_ex()</code> function, using <code>opts.request</code> and <code>opts.requestLen</code>. If the same nonce is found in OCSP request and response, that is considered a match and flag pointed to by <code>opts.nonceMatch</code> is set to <em>true</em> (1).</p>
<p>Currently, OCSP nonce is not supported by many of the OCSP servers deployed in practice, and therefore, it is recommended to not rely on OCSP nonce feature to be provided by third party OCSP servers.</p>
<h2 id="69-matrixssl-statistics-framework">6.9 MatrixSSL Statistics Framework</h2>
<p>Implementations that wish to capture counts of SSL events can tap into the <code>MATRIXSSL_STATS</code> framework by enabling <code>USE_MATRIXSSL_STATS</code> during the compile. The mechanism is a very simple callback that can be registered to record whatever specific SSL event the user wants. The default set of events capture the following:</p>
<ul>
<li><code>CLIENT_HELLO</code> count (sent for clients and received for servers)</li>
<li><code>SERVER_HELLO</code> count (sent for servers and received for clients)</li>
<li>Alerts sent</li>
<li>Resumed handshake count</li>
<li>Failed resumed handshake count</li>
<li>Number of application data bytes received</li>
<li>Number of application data bytes sent</li>
</ul>
<p>To add an event to the framework the user must:</p>
<ol>
<li>Add a unique ID to the list of existing stats in matrixsslApi.h</li>
<li>Add the call to <code>matrixsslUpdateStat</code> in the appropriate place in the MatrixSSL library</li>
</ol>
<h2 id="610-client-authentication-using-an-external-security-token">6.10 Client Authentication using an External Security Token</h2>
<p>MatrixSSL allows the TLS client to authenticate itself using an external security token. The external client authentication feature allows the client-side private key operation (i.e. the signing of the handshake_messages hash in the CertificateVerify handshake message) to be offloaded from MatrixSSL to an external module. Please consult the <code>External Client Authentication</code> section in MatrixSSL External Module Integration manual for details on how to use this feature.</p>
<h1 id="7-deprecated-features">7 Deprecated Features <i class="icon-down"></i></h1>
<p>The features in this section are minimally supported and should only be used in cases where they are explicitly required for compatibility. Please be aware of any security implications of these features before enabling them.</p>
<h2 id="71-eapfast-mode">7.1 EAP_FAST Mode</h2>
<p><a href="https://tools.ietf.org/html/rfc4851">EAP-FAST</a> is an aging, proprietary EAP method that uses TLS to bootstrap a higher level EAP authentication method. It is supported by MatrixSSL for the client (EAP Supplicant) side only. Unlike EAP-TLS or EAP-TTLS, EAP-FAST requires modifications to the TLS protocol and therefore must be explicitly enabled with both a compile time define <code>USE_EAP_FAST</code> and a client side API <code>matrixSslSetSessionIdEapFast</code> in <em>matrixssllib.h</em>.</p>
<p>EAP-FAST requires a <em>Protected Access Credential (PAC)</em> to be provisioned between the peers out-of-band (see <a href="https://tools.ietf.org/html/rfc5422">RFC5422</a> <em>Dynamic Provisioning Using Flexible Authentication via Secure Tunneling Extensible Authentication Protocol (EAP-FAST)</em>. Like the <code>TLS_PSK</code> cipher suites, this <em>PAC</em> consists of a secret key (pac-key) and a unique id associated with the key, both shared between the peers. However, the <code>TLS_PSK</code> ciphers are not used for this mechanism directly.</p>
<p>The <em>PAC</em> is exchanged between the peers by the client sending the <a href="#61-stateless-session-ticket-resumption">Stateless Session Ticket Resumption</a> specification: the <code>CLIENT_HELLO SessionTicket Extension</code>. However, a <em>PAC</em> explicitly cannot be received by a client in the corresponding <code>NewSessionTicket</code> handshake message from the server, and must be provisioned out-of-band. Unfortunately this requires alteration of the standard TLS state machine logic.</p>
<pre class="prettyprint"><code class="language-C hljs r">sslSessionId_t *sid;
ssl_t *ssl;
<span class="hljs-keyword">...</span>
rc = matrixSslNewSessionId(&amp;sid, <span class="hljs-literal">NULL</span>);
matrixSslSetSessionIdEapFast(sid, pac_key, pac_opaque, pac_opaque_len);
rc = matrixSslNewClientSession(&amp;ssl, keys, sid, <span class="hljs-keyword">...</span>);
<span class="hljs-keyword">...</span>
/* When TLS session is successfully negotiated */
rc = matrixSslGetEapFastSKS(ssl, session_key_seed);
<span class="hljs-keyword">...</span>
matrixSslDeleteSession(ssl);
matrixSslDeleteSessionId(sid);</code></pre>
<h2 id="72-zlib-compression">7.2 ZLIB Compression</h2>
<p>The TLS specification specifies a mechanism for peers to agree on an algorithm to compress data before being encrypted. Although the feature is not widely adopted and is deprecated due to the ‘CRIME’ attack, there is limited support in MatrixSSL for zlib compression for implementations that are sensitive to throughput.</p>
<p>To enable the feature, enable <code>USE_ZLIB_COMPRESSION</code> in <em>matrixssllib.h</em>. It will also be necessary to edit the development environment to link with a zlib library. For a standard <em>GCC</em> <em>POSIX</em> environment this should simply mean including <code>–lz</code> in the linker flags.</p>
<p>The built-in support for this feature is limited. The feature only supports the internal compression and decompression of the <code>FINISHED</code> handshake message for initial handshakes. This means re-handshaking is not supported and that the application MUST compress and decompress application data manually.</p>
<p><strong>On the application data sending side:</strong> <br>
After a successful handshake with <code>USE_ZLIB_COMPRESSION</code> enabled, the user should call <code>matrixSslIsSessionCompressionOn</code> to test whether that mode has been successfully negotiated. If <code>PS_TRUE</code>, the user must manually zlib deflate any application data before calling the Matrix encryption functions. Do not compress more plaintext data in a single record than the maximum allowed record size to remain compatible with 3rd party SSL implementations.</p>
<p><strong>On the application data receiving side:</strong> <br>
Applications must test for <code>MATRIXSSL_APP_DATA_COMPRESSED</code> as the return code from <code>matrixSslReceivedData</code>. If found, the data must be zlib inflated to obtain the plaintext data</p>
Reference in New Issue View Git Blame Copy Permalink