libs/beast/doc/html/beast/using_io/writing_composed_operations/detect_ssl.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>Detect SSL &#128161;</title>
   5 <link rel="stylesheet" href="../../../../../../../doc/src/boostbook.css" type="text/css">
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
   7 <link rel="home" href="../../../index.html" title="Chapter&#160;1.&#160;Boost.Beast">
   8 <link rel="up" href="../writing_composed_operations.html" title="Writing Composed Operations">
   9 <link rel="prev" href="echo.html" title="Echo &#128161;">
  10 <link rel="next" href="../../using_http.html" title="HTTP">
  11 </head>
  12 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  13 <table cellpadding="2" width="100%"><tr>
  14 <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
  15 <td align="center"><a href="../../../../../../../index.html">Home</a></td>
  16 <td align="center"><a href="../../../../../../../libs/libraries.htm">Libraries</a></td>
  17 <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
  18 <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
  19 <td align="center"><a href="../../../../../../../more/index.htm">More</a></td>
  20 </tr></table>
  21 <hr>
  22 <div class="spirit-nav">
  23 <a accesskey="p" href="echo.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../writing_composed_operations.html"><img src="../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="../../using_http.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
  24 </div>
  25 <div class="section">
  26 <div class="titlepage"><div><div><h4 class="title">
  27 <a name="beast.using_io.writing_composed_operations.detect_ssl"></a><a class="link" href="detect_ssl.html" title="Detect SSL &#128161;">Detect
  28         SSL &#128161;</a>
  29 </h4></div></div></div>
  30 <p>
  31           In this example we will build a simple function to detect the presence
  32           of the <a href="https://tools.ietf.org/html/rfc2246#section-7.4" target="_top">TLS
  33           client handshake</a> given an input buffer sequence. Then we build
  34           on the example by adding a synchronous stream algorithm. Finally, we implement
  35           an asynchronous detection function using a composed operation. This SSL
  36           detector may be used to allow a server to accept both TLS and plain (unencrypted)
  37           connections at the same port.
  38         </p>
  39 <p>
  40           Here is the declaration for a function template to detect the SSL client
  41           handshake. The function accepts any object whose type meets the requirements
  42           of <a href="../../../../../../../doc/html/boost_asio/reference/ConstBufferSequence.html" target="_top"><span class="emphasis"><em>ConstBufferSequence</em></span></a>.
  43           This gives callers flexibility to use a buffer object whose behavior is
  44           appropriate to the task.
  45         </p>
  46 <pre class="programlisting"><span class="comment">// By convention, the "detail" namespace means "not-public."</span>
  47 <span class="comment">// Identifiers in a detail namespace are not visible in the documentation,</span>
  48 <span class="comment">// and users should not directly use those identifiers in programs, otherwise</span>
  49 <span class="comment">// their program may break in the future.</span>
  50 <span class="comment">//</span>
  51 <span class="comment">// Using a detail namespace gives the library writer the freedom to change</span>
  52 <span class="comment">// the interface or behavior later, and maintain backward-compatibility.</span>
  53
  54 <span class="keyword">namespace</span> <span class="identifier">detail</span> <span class="special">{</span>
  55
  56 <span class="comment">/** Return `true` if the buffer contains a TLS Protocol client_hello message.
  57
  58     This function analyzes the bytes at the beginning of the buffer
  59     and compares it to a valid client_hello message. This is the
  60     message required to be sent by a client at the beginning of
  61     any TLS (encrypted communication) session, including when
  62     resuming a session.
  63
  64     The return value will be:
  65
  66     @li `true` if the contents of the buffer unambiguously define
  67     contain a client_hello message,
  68
  69     @li `false` if the contents of the buffer cannot possibly
  70     be a valid client_hello message, or
  71
  72     @li `boost::indeterminate` if the buffer contains an
  73     insufficient number of bytes to determine the result. In
  74     this case the caller should read more data from the relevant
  75     stream, append it to the buffers, and call this function again.
  76
  77     @param buffers The buffer sequence to inspect.
  78     This type must meet the requirements of &lt;em&gt;ConstBufferSequence&lt;/em&gt;.
  79
  80     @return `boost::tribool` indicating whether the buffer contains
  81     a TLS client handshake, does not contain a handshake, or needs
  82     additional bytes to determine an outcome.
  83
  84     @see
  85
  86     &lt;a href="https://tools.ietf.org/html/rfc2246#section-7.4"&gt;7.4. Handshake protocol&lt;/a&gt;
  87     (RFC2246: The TLS Protocol)
  88 */</span>
  89 <span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">ConstBufferSequence</span><span class="special">&gt;</span>
  90 <span class="identifier">boost</span><span class="special">::</span><span class="identifier">tribool</span>
  91 <span class="identifier">is_tls_client_hello</span> <span class="special">(</span><span class="identifier">ConstBufferSequence</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">buffers</span><span class="special">);</span>
  92
  93 <span class="special">}</span> <span class="comment">// detail</span>
  94 </pre>
  95 <p>
  96           The algorithm examines the buffer starting from the beginning, and performs
  97           a series of qualifying checks against the TLS specification. When not enough
  98           data exists to be certain, the returned value of <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">indeterminate</span></code>
  99           informs the caller to read more data into the buffer. The function definition
 100           for the declaration above follows:
 101         </p>
 102 <pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">detail</span> <span class="special">{</span>
 103
 104 <span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">ConstBufferSequence</span><span class="special">&gt;</span>
 105 <span class="identifier">boost</span><span class="special">::</span><span class="identifier">tribool</span>
 106 <span class="identifier">is_tls_client_hello</span> <span class="special">(</span><span class="identifier">ConstBufferSequence</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">buffers</span><span class="special">)</span>
 107 <span class="special">{</span>
 108     <span class="comment">// Make sure buffers meets the requirements</span>
 109     <span class="keyword">static_assert</span><span class="special">(</span>
 110         <span class="identifier">net</span><span class="special">::</span><span class="identifier">is_const_buffer_sequence</span><span class="special">&lt;</span><span class="identifier">ConstBufferSequence</span><span class="special">&gt;::</span><span class="identifier">value</span><span class="special">,</span>
 111         <span class="string">"ConstBufferSequence type requirements not met"</span><span class="special">);</span>
 112
 113 <span class="comment">/*
 114     The first message on a TLS connection must be the client_hello,
 115     which is a type of handshake record, and it cannot be compressed
 116     or encrypted. A plaintext record has this format:
 117
 118          0      byte    record_type      // 0x16 = handshake
 119          1      byte    major            // major protocol version
 120          2      byte    minor            // minor protocol version
 121        3-4      uint16  length           // size of the payload
 122          5      byte    handshake_type   // 0x01 = client_hello
 123          6      uint24  length           // size of the ClientHello
 124          9      byte    major            // major protocol version
 125         10      byte    minor            // minor protocol version
 126         11      uint32  gmt_unix_time
 127         15      byte    random_bytes[28]
 128                 ...
 129 */</span>
 130
 131     <span class="comment">// Flatten the input buffers into a single contiguous range</span>
 132     <span class="comment">// of bytes on the stack to make it easier to work with the data.</span>
 133     <span class="keyword">unsigned</span> <span class="keyword">char</span> <span class="identifier">buf</span><span class="special">[</span><span class="number">9</span><span class="special">];</span>
 134     <span class="keyword">auto</span> <span class="keyword">const</span> <span class="identifier">n</span> <span class="special">=</span> <span class="identifier">net</span><span class="special">::</span><span class="identifier">buffer_copy</span><span class="special">(</span>
 135         <span class="identifier">net</span><span class="special">::</span><span class="identifier">mutable_buffer</span><span class="special">(</span><span class="identifier">buf</span><span class="special">,</span> <span class="keyword">sizeof</span><span class="special">(</span><span class="identifier">buf</span><span class="special">)),</span> <span class="identifier">buffers</span><span class="special">);</span>
 136
 137     <span class="comment">// Can't do much without any bytes</span>
 138     <span class="keyword">if</span><span class="special">(</span><span class="identifier">n</span> <span class="special">&lt;</span> <span class="number">1</span><span class="special">)</span>
 139         <span class="keyword">return</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">indeterminate</span><span class="special">;</span>
 140
 141     <span class="comment">// Require the first byte to be 0x16, indicating a TLS handshake record</span>
 142     <span class="keyword">if</span><span class="special">(</span><span class="identifier">buf</span><span class="special">[</span><span class="number">0</span><span class="special">]</span> <span class="special">!=</span> <span class="number">0x16</span><span class="special">)</span>
 143         <span class="keyword">return</span> <span class="keyword">false</span><span class="special">;</span>
 144
 145     <span class="comment">// We need at least 5 bytes to know the record payload size</span>
 146     <span class="keyword">if</span><span class="special">(</span><span class="identifier">n</span> <span class="special">&lt;</span> <span class="number">5</span><span class="special">)</span>
 147         <span class="keyword">return</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">indeterminate</span><span class="special">;</span>
 148
 149     <span class="comment">// Calculate the record payload size</span>
 150     <span class="identifier">std</span><span class="special">::</span><span class="identifier">uint32_t</span> <span class="keyword">const</span> <span class="identifier">length</span> <span class="special">=</span> <span class="special">(</span><span class="identifier">buf</span><span class="special">[</span><span class="number">3</span><span class="special">]</span> <span class="special">&lt;&lt;</span> <span class="number">8</span><span class="special">)</span> <span class="special">+</span> <span class="identifier">buf</span><span class="special">[</span><span class="number">4</span><span class="special">];</span>
 151
 152     <span class="comment">// A ClientHello message payload is at least 34 bytes.</span>
 153     <span class="comment">// There can be multiple handshake messages in the same record.</span>
 154     <span class="keyword">if</span><span class="special">(</span><span class="identifier">length</span> <span class="special">&lt;</span> <span class="number">34</span><span class="special">)</span>
 155         <span class="keyword">return</span> <span class="keyword">false</span><span class="special">;</span>
 156
 157     <span class="comment">// We need at least 6 bytes to know the handshake type</span>
 158     <span class="keyword">if</span><span class="special">(</span><span class="identifier">n</span> <span class="special">&lt;</span> <span class="number">6</span><span class="special">)</span>
 159         <span class="keyword">return</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">indeterminate</span><span class="special">;</span>
 160
 161     <span class="comment">// The handshake_type must be 0x01 == client_hello</span>
 162     <span class="keyword">if</span><span class="special">(</span><span class="identifier">buf</span><span class="special">[</span><span class="number">5</span><span class="special">]</span> <span class="special">!=</span> <span class="number">0x01</span><span class="special">)</span>
 163         <span class="keyword">return</span> <span class="keyword">false</span><span class="special">;</span>
 164
 165     <span class="comment">// We need at least 9 bytes to know the payload size</span>
 166     <span class="keyword">if</span><span class="special">(</span><span class="identifier">n</span> <span class="special">&lt;</span> <span class="number">9</span><span class="special">)</span>
 167         <span class="keyword">return</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">indeterminate</span><span class="special">;</span>
 168
 169     <span class="comment">// Calculate the message payload size</span>
 170     <span class="identifier">std</span><span class="special">::</span><span class="identifier">uint32_t</span> <span class="keyword">const</span> <span class="identifier">size</span> <span class="special">=</span>
 171         <span class="special">(</span><span class="identifier">buf</span><span class="special">[</span><span class="number">6</span><span class="special">]</span> <span class="special">&lt;&lt;</span> <span class="number">16</span><span class="special">)</span> <span class="special">+</span> <span class="special">(</span><span class="identifier">buf</span><span class="special">[</span><span class="number">7</span><span class="special">]</span> <span class="special">&lt;&lt;</span> <span class="number">8</span><span class="special">)</span> <span class="special">+</span> <span class="identifier">buf</span><span class="special">[</span><span class="number">8</span><span class="special">];</span>
 172
 173     <span class="comment">// The message payload can't be bigger than the enclosing record</span>
 174     <span class="keyword">if</span><span class="special">(</span><span class="identifier">size</span> <span class="special">+</span> <span class="number">4</span> <span class="special">&gt;</span> <span class="identifier">length</span><span class="special">)</span>
 175         <span class="keyword">return</span> <span class="keyword">false</span><span class="special">;</span>
 176
 177     <span class="comment">// This can only be a TLS client_hello message</span>
 178     <span class="keyword">return</span> <span class="keyword">true</span><span class="special">;</span>
 179 <span class="special">}</span>
 180
 181 <span class="special">}</span> <span class="comment">// detail</span>
 182 </pre>
 183 <p>
 184           The detection function above is suitably generic and targeted in focus
 185           that it may be used as a building block to create higher level abstractions.
 186           Our goal is to create a <span class="emphasis"><em>stream algorithm</em></span>: a function
 187           which is invoked with a stream, that reads or writes (or both) to achieve
 188           a purpose. In this case, to detect the TLS client handshake. Stream algorithms
 189           may be synchronous or asynchronous. Because synchronous algorithms are
 190           easier to write, we start there. Then we build the asynchronous version,
 191           trying to model it similarly to make reasoning about it easier.
 192         </p>
 193 <p>
 194           The synchronous version is implemented thusly:
 195         </p>
 196 <pre class="programlisting"><span class="comment">/** Detect a TLS client handshake on a stream.
 197
 198     This function reads from a stream to determine if a client
 199     handshake message is being received.
 200
 201     The call blocks until one of the following is true:
 202
 203     @li A TLS client opening handshake is detected,
 204
 205     @li The received data is invalid for a TLS client handshake, or
 206
 207     @li An error occurs.
 208
 209     The algorithm, known as a &lt;em&gt;composed operation&lt;/em&gt;, is implemented
 210     in terms of calls to the next layer's `read_some` function.
 211
 212     Bytes read from the stream will be stored in the passed dynamic
 213     buffer, which may be used to perform the TLS handshake if the
 214     detector returns true, or be otherwise consumed by the caller based
 215     on the expected protocol.
 216
 217     @param stream The stream to read from. This type must meet the
 218     requirements of &lt;em&gt;SyncReadStream&lt;/em&gt;.
 219
 220     @param buffer The dynamic buffer to use. This type must meet the
 221     requirements of &lt;em&gt;DynamicBuffer&lt;/em&gt;.
 222
 223     @param ec Set to the error if any occurred.
 224
 225     @return `true` if the buffer contains a TLS client handshake and
 226     no error occurred, otherwise `false`.
 227 */</span>
 228 <span class="keyword">template</span><span class="special">&lt;</span>
 229     <span class="keyword">class</span> <span class="identifier">SyncReadStream</span><span class="special">,</span>
 230     <span class="keyword">class</span> <span class="identifier">DynamicBuffer</span><span class="special">&gt;</span>
 231 <span class="keyword">bool</span>
 232 <span class="identifier">detect_ssl</span><span class="special">(</span>
 233     <span class="identifier">SyncReadStream</span><span class="special">&amp;</span> <span class="identifier">stream</span><span class="special">,</span>
 234     <span class="identifier">DynamicBuffer</span><span class="special">&amp;</span> <span class="identifier">buffer</span><span class="special">,</span>
 235     <span class="identifier">error_code</span><span class="special">&amp;</span> <span class="identifier">ec</span><span class="special">)</span>
 236 <span class="special">{</span>
 237     <span class="keyword">namespace</span> <span class="identifier">beast</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">beast</span><span class="special">;</span>
 238
 239     <span class="comment">// Make sure arguments meet the requirements</span>
 240
 241     <span class="keyword">static_assert</span><span class="special">(</span>
 242         <span class="identifier">is_sync_read_stream</span><span class="special">&lt;</span><span class="identifier">SyncReadStream</span><span class="special">&gt;::</span><span class="identifier">value</span><span class="special">,</span>
 243         <span class="string">"SyncReadStream type requirements not met"</span><span class="special">);</span>
 244
 245     <span class="keyword">static_assert</span><span class="special">(</span>
 246         <span class="identifier">net</span><span class="special">::</span><span class="identifier">is_dynamic_buffer</span><span class="special">&lt;</span><span class="identifier">DynamicBuffer</span><span class="special">&gt;::</span><span class="identifier">value</span><span class="special">,</span>
 247         <span class="string">"DynamicBuffer type requirements not met"</span><span class="special">);</span>
 248
 249     <span class="comment">// Loop until an error occurs or we get a definitive answer</span>
 250     <span class="keyword">for</span><span class="special">(;;)</span>
 251     <span class="special">{</span>
 252         <span class="comment">// There could already be data in the buffer</span>
 253         <span class="comment">// so we do this first, before reading from the stream.</span>
 254         <span class="keyword">auto</span> <span class="keyword">const</span> <span class="identifier">result</span> <span class="special">=</span> <span class="identifier">detail</span><span class="special">::</span><span class="identifier">is_tls_client_hello</span><span class="special">(</span><span class="identifier">buffer</span><span class="special">.</span><span class="identifier">data</span><span class="special">());</span>
 255
 256         <span class="comment">// If we got an answer, return it</span>
 257         <span class="keyword">if</span><span class="special">(!</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">indeterminate</span><span class="special">(</span><span class="identifier">result</span><span class="special">))</span>
 258         <span class="special">{</span>
 259             <span class="comment">// A definite answer is a success</span>
 260             <span class="identifier">ec</span> <span class="special">=</span> <span class="special">{};</span>
 261             <span class="keyword">return</span> <span class="keyword">static_cast</span><span class="special">&lt;</span><span class="keyword">bool</span><span class="special">&gt;(</span><span class="identifier">result</span><span class="special">);</span>
 262         <span class="special">}</span>
 263
 264         <span class="comment">// Try to fill our buffer by reading from the stream.</span>
 265         <span class="comment">// The function read_size calculates a reasonable size for the</span>
 266         <span class="comment">// amount to read next, using existing capacity if possible to</span>
 267         <span class="comment">// avoid allocating memory, up to the limit of 1536 bytes which</span>
 268         <span class="comment">// is the size of a normal TCP frame.</span>
 269
 270         <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="keyword">const</span> <span class="identifier">bytes_transferred</span> <span class="special">=</span> <span class="identifier">stream</span><span class="special">.</span><span class="identifier">read_some</span><span class="special">(</span>
 271             <span class="identifier">buffer</span><span class="special">.</span><span class="identifier">prepare</span><span class="special">(</span><span class="identifier">beast</span><span class="special">::</span><span class="identifier">read_size</span><span class="special">(</span><span class="identifier">buffer</span><span class="special">,</span> <span class="number">1536</span><span class="special">)),</span> <span class="identifier">ec</span><span class="special">);</span>
 272
 273         <span class="comment">// Commit what we read into the buffer's input area.</span>
 274         <span class="identifier">buffer</span><span class="special">.</span><span class="identifier">commit</span><span class="special">(</span><span class="identifier">bytes_transferred</span><span class="special">);</span>
 275
 276         <span class="comment">// Check for an error</span>
 277         <span class="keyword">if</span><span class="special">(</span><span class="identifier">ec</span><span class="special">)</span>
 278             <span class="keyword">break</span><span class="special">;</span>
 279     <span class="special">}</span>
 280
 281     <span class="comment">// error</span>
 282     <span class="keyword">return</span> <span class="keyword">false</span><span class="special">;</span>
 283 <span class="special">}</span>
 284 </pre>
 285 <p>
 286           Now that we have the synchronous version, we can attempt to model the asynchronous
 287           version similarly. A function which launches an asynchronous operation
 288           is called an <span class="emphasis"><em>initiating function</em></span>. While the synchronous
 289           version above produces an error code through an output parameter, the asynchronous
 290           version delivers the error code to a completion handler or other custom
 291           mechanism defined by the completion token. The signature of the initiating
 292           function reflects these differences.
 293         </p>
 294 <p>
 295           First we declare the initiating function and document the requirements,
 296           parameters, preconditions, and effects:
 297         </p>
 298 <pre class="programlisting"><span class="comment">/** Detect a TLS/SSL handshake asynchronously on a stream.
 299
 300     This function reads asynchronously from a stream to determine
 301     if a client handshake message is being received.
 302
 303     This call always returns immediately. The asynchronous operation
 304     will continue until one of the following conditions is true:
 305
 306     @li A TLS client opening handshake is detected,
 307
 308     @li The received data is invalid for a TLS client handshake, or
 309
 310     @li An error occurs.
 311
 312     The algorithm, known as a &lt;em&gt;composed asynchronous operation&lt;/em&gt;,
 313     is implemented in terms of calls to the next layer's `async_read_some`
 314     function. The program must ensure that no other calls to
 315     `async_read_some` are performed until this operation completes.
 316
 317     Bytes read from the stream will be stored in the passed dynamic
 318     buffer, which may be used to perform the TLS handshake if the
 319     detector returns true, or be otherwise consumed by the caller based
 320     on the expected protocol.
 321
 322     @param stream The stream to read from. This type must meet the
 323     requirements of &lt;em&gt;AsyncReadStream&lt;/em&gt;.
 324
 325     @param buffer The dynamic buffer to use. This type must meet the
 326     requirements of &lt;em&gt;DynamicBuffer&lt;/em&gt;.
 327
 328     @param token The completion token used to determine the method
 329     used to provide the result of the asynchronous operation. If
 330     this is a completion handler, the implementation takes ownership
 331     of the handler by performing a decay-copy, and the equivalent
 332     function signature of the handler must be:
 333     @code
 334     void handler(
 335         error_code const&amp; error,    // Set to the error, if any
 336         bool result                 // The result of the detector
 337     );
 338     @endcode
 339     Regardless of whether the asynchronous operation completes
 340     immediately or not, the handler will not be invoked from within
 341     this function. Invocation of the handler will be performed in a
 342     manner equivalent to using `net::post`.
 343 */</span>
 344 <span class="keyword">template</span><span class="special">&lt;</span>
 345     <span class="keyword">class</span> <span class="identifier">AsyncReadStream</span><span class="special">,</span>
 346     <span class="keyword">class</span> <span class="identifier">DynamicBuffer</span><span class="special">,</span>
 347     <span class="keyword">class</span> <span class="identifier">CompletionToken</span> <span class="special">=</span>
 348         <span class="identifier">net</span><span class="special">::</span><span class="identifier">default_completion_token_t</span><span class="special">&lt;</span><span class="identifier">beast</span><span class="special">::</span><span class="identifier">executor_type</span><span class="special">&lt;</span><span class="identifier">AsyncReadStream</span><span class="special">&gt;&gt;</span>
 349 <span class="special">&gt;</span>
 350 <span class="preprocessor">#if</span> <span class="identifier">BOOST_BEAST_DOXYGEN</span>
 351 <span class="identifier">BOOST_ASIO_INITFN_RESULT_TYPE</span><span class="special">(</span><span class="identifier">CompletionToken</span><span class="special">,</span> <span class="keyword">void</span><span class="special">(</span><span class="identifier">error_code</span><span class="special">,</span> <span class="keyword">bool</span><span class="special">))</span>
 352 <span class="preprocessor">#else</span>
 353 <span class="keyword">auto</span>
 354 <span class="preprocessor">#endif</span>
 355 <span class="identifier">async_detect_ssl</span><span class="special">(</span>
 356     <span class="identifier">AsyncReadStream</span><span class="special">&amp;</span> <span class="identifier">stream</span><span class="special">,</span>
 357     <span class="identifier">DynamicBuffer</span><span class="special">&amp;</span> <span class="identifier">buffer</span><span class="special">,</span>
 358     <span class="identifier">CompletionToken</span><span class="special">&amp;&amp;</span> <span class="identifier">token</span> <span class="special">=</span> <span class="identifier">net</span><span class="special">::</span><span class="identifier">default_completion_token_t</span><span class="special">&lt;</span>
 359             <span class="identifier">beast</span><span class="special">::</span><span class="identifier">executor_type</span><span class="special">&lt;</span><span class="identifier">AsyncReadStream</span><span class="special">&gt;&gt;{})</span> <span class="special">-&gt;</span>
 360         <span class="keyword">typename</span> <span class="identifier">net</span><span class="special">::</span><span class="identifier">async_result</span><span class="special">&lt;</span>
 361             <span class="keyword">typename</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">decay</span><span class="special">&lt;</span><span class="identifier">CompletionToken</span><span class="special">&gt;::</span><span class="identifier">type</span><span class="special">,</span> <a class="co" name="beast.using_io.writing_composed_operations.detect_ssl.c0" href="detect_ssl.html#beast.using_io.writing_composed_operations.detect_ssl.c1"><img src="../../../../../../../doc/src/images/callouts/1.png" alt="1" border="0"></a>
 362             <span class="keyword">void</span><span class="special">(</span><span class="identifier">error_code</span><span class="special">,</span> <span class="keyword">bool</span><span class="special">)&gt;::</span><span class="identifier">return_type</span><span class="special">;</span> <a class="co" name="beast.using_io.writing_composed_operations.detect_ssl.c2" href="detect_ssl.html#beast.using_io.writing_composed_operations.detect_ssl.c3"><img src="../../../../../../../doc/src/images/callouts/2.png" alt="2" border="0"></a>
 363 </pre>
 364 <div class="calloutlist"><table border="0" summary="Callout list">
 365 <tr>
 366 <td width="5%" valign="top" align="left"><p><a name="beast.using_io.writing_composed_operations.detect_ssl.c1"></a><a href="#beast.using_io.writing_composed_operations.detect_ssl.c0"><img src="../../../../../../../doc/src/images/callouts/1.png" alt="1" border="0"></a> </p></td>
 367 <td valign="top" align="left"><p>
 368               <code class="computeroutput"><span class="identifier">async_result</span></code> customizes
 369               the return value based on the completion token
 370             </p></td>
 371 </tr>
 372 <tr>
 373 <td width="5%" valign="top" align="left"><p><a name="beast.using_io.writing_composed_operations.detect_ssl.c3"></a><a href="#beast.using_io.writing_composed_operations.detect_ssl.c2"><img src="../../../../../../../doc/src/images/callouts/2.png" alt="2" border="0"></a> </p></td>
 374 <td valign="top" align="left"><p>
 375               This is the signature for the completion handler
 376             </p></td>
 377 </tr>
 378 </table></div>
 379 <p>
 380           There are two additional components required to implement the initiating
 381           function:
 382         </p>
 383 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 384 <li class="listitem">
 385               An intermediate completion handler, called the "composed operation"
 386               object, which holds the state of the operation while it is in progress,
 387               and also holds the user's completion handler to be invoked when the
 388               opeartion completes, and
 389             </li>
 390 <li class="listitem">
 391               An "initiation" function object which when invoked with parameters
 392               captured at the call site of the initiating function, constructs the
 393               composed operation with the captured arguments and launches it.
 394             </li>
 395 </ul></div>
 396 <p>
 397           Here we forward declare the composed operation type, and provide the definition
 398           of the initiation function object. They are placed in the <code class="computeroutput"><span class="identifier">detail</span></code> namespace since they should not
 399           be public:
 400         </p>
 401 <pre class="programlisting"><span class="comment">// These implementation details don't need to be public</span>
 402
 403 <span class="keyword">namespace</span> <span class="identifier">detail</span> <span class="special">{</span>
 404
 405 <span class="comment">// The composed operation object</span>
 406 <span class="keyword">template</span><span class="special">&lt;</span>
 407     <span class="keyword">class</span> <span class="identifier">DetectHandler</span><span class="special">,</span>
 408     <span class="keyword">class</span> <span class="identifier">AsyncReadStream</span><span class="special">,</span>
 409     <span class="keyword">class</span> <span class="identifier">DynamicBuffer</span><span class="special">&gt;</span>
 410 <span class="keyword">class</span> <span class="identifier">detect_ssl_op</span><span class="special">;</span>
 411
 412 <span class="comment">// This is a function object which `net::async_initiate` can use to launch</span>
 413 <span class="comment">// our composed operation. This is a relatively new feature in networking</span>
 414 <span class="comment">// which allows the asynchronous operation to be "lazily" executed (meaning</span>
 415 <span class="comment">// that it is launched later). Users don't need to worry about this, but</span>
 416 <span class="comment">// authors of composed operations need to write it this way to get the</span>
 417 <span class="comment">// very best performance, for example when using Coroutines TS (`co_await`).</span>
 418
 419 <span class="keyword">struct</span> <span class="identifier">run_detect_ssl_op</span>
 420 <span class="special">{</span>
 421     <span class="comment">// The implementation of `net::async_initiate` captures the</span>
 422     <span class="comment">// arguments of the initiating function, and then calls this</span>
 423     <span class="comment">// function object later with the captured arguments in order</span>
 424     <span class="comment">// to launch the composed operation. All we need to do here</span>
 425     <span class="comment">// is take those arguments and construct our composed operation</span>
 426     <span class="comment">// object.</span>
 427     <span class="comment">//</span>
 428     <span class="comment">// `async_initiate` takes care of transforming the completion</span>
 429     <span class="comment">// token into the "real handler" which must have the correct</span>
 430     <span class="comment">// signature, in this case `void(error_code, boost::tri_bool)`.</span>
 431
 432     <span class="keyword">template</span><span class="special">&lt;</span>
 433         <span class="keyword">class</span> <span class="identifier">DetectHandler</span><span class="special">,</span>
 434         <span class="keyword">class</span> <span class="identifier">AsyncReadStream</span><span class="special">,</span>
 435         <span class="keyword">class</span> <span class="identifier">DynamicBuffer</span><span class="special">&gt;</span>
 436     <span class="keyword">void</span> <span class="keyword">operator</span><span class="special">()(</span>
 437         <span class="identifier">DetectHandler</span><span class="special">&amp;&amp;</span> <span class="identifier">h</span><span class="special">,</span>
 438         <span class="identifier">AsyncReadStream</span><span class="special">*</span> <span class="identifier">s</span><span class="special">,</span> <span class="comment">// references are passed as pointers</span>
 439         <span class="identifier">DynamicBuffer</span><span class="special">&amp;</span> <span class="identifier">b</span><span class="special">)</span>
 440     <span class="special">{</span>
 441         <span class="identifier">detect_ssl_op</span><span class="special">&lt;</span>
 442             <span class="keyword">typename</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">decay</span><span class="special">&lt;</span><span class="identifier">DetectHandler</span><span class="special">&gt;::</span><span class="identifier">type</span><span class="special">,</span>
 443             <span class="identifier">AsyncReadStream</span><span class="special">,</span>
 444             <span class="identifier">DynamicBuffer</span><span class="special">&gt;(</span>
 445                 <span class="identifier">std</span><span class="special">::</span><span class="identifier">forward</span><span class="special">&lt;</span><span class="identifier">DetectHandler</span><span class="special">&gt;(</span><span class="identifier">h</span><span class="special">),</span> <span class="special">*</span><span class="identifier">s</span><span class="special">,</span> <span class="identifier">b</span><span class="special">);</span>
 446     <span class="special">}</span>
 447 <span class="special">};</span>
 448
 449 <span class="special">}</span> <span class="comment">// detail</span>
 450 </pre>
 451 <p>
 452           The initiating function definition itself is straightforward. We perform
 453           type checking on the parameters, and then let <code class="computeroutput"><span class="identifier">net</span><span class="special">::</span><span class="identifier">async_initiate</span></code>
 454           capture the parameter list along with a copy of our initiation function
 455           object. Depending on the specialization of <code class="computeroutput"><span class="identifier">async_result</span></code>
 456           for the type of <code class="computeroutput"><span class="identifier">CompletionToken</span></code>,
 457           the initiation function may be invoked immediately. Alternatively, it may
 458           be invoked later, after the initiating function returns. This is known
 459           as "lazy execution," and allows efficient and expressive abstractions
 460           to be written.
 461         </p>
 462 <pre class="programlisting"><span class="comment">// Here is the implementation of the asynchronous initiation function</span>
 463 <span class="keyword">template</span><span class="special">&lt;</span>
 464     <span class="keyword">class</span> <span class="identifier">AsyncReadStream</span><span class="special">,</span>
 465     <span class="keyword">class</span> <span class="identifier">DynamicBuffer</span><span class="special">,</span>
 466     <span class="keyword">class</span> <span class="identifier">CompletionToken</span><span class="special">&gt;</span>
 467 <span class="preprocessor">#if</span> <span class="identifier">BOOST_BEAST_DOXYGEN</span>
 468 <span class="identifier">BOOST_ASIO_INITFN_RESULT_TYPE</span><span class="special">(</span><span class="identifier">CompletionToken</span><span class="special">,</span> <span class="keyword">void</span><span class="special">(</span><span class="identifier">error_code</span><span class="special">,</span> <span class="keyword">bool</span><span class="special">))</span>
 469 <span class="preprocessor">#else</span>
 470 <span class="keyword">auto</span>
 471 <span class="preprocessor">#endif</span>
 472 <span class="identifier">async_detect_ssl</span><span class="special">(</span>
 473     <span class="identifier">AsyncReadStream</span><span class="special">&amp;</span> <span class="identifier">stream</span><span class="special">,</span>
 474     <span class="identifier">DynamicBuffer</span><span class="special">&amp;</span> <span class="identifier">buffer</span><span class="special">,</span>
 475     <span class="identifier">CompletionToken</span><span class="special">&amp;&amp;</span> <span class="identifier">token</span><span class="special">)</span>
 476         <span class="special">-&gt;</span> <span class="keyword">typename</span> <span class="identifier">net</span><span class="special">::</span><span class="identifier">async_result</span><span class="special">&lt;</span>
 477             <span class="keyword">typename</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">decay</span><span class="special">&lt;</span><span class="identifier">CompletionToken</span><span class="special">&gt;::</span><span class="identifier">type</span><span class="special">,</span>
 478             <span class="keyword">void</span><span class="special">(</span><span class="identifier">error_code</span><span class="special">,</span> <span class="keyword">bool</span><span class="special">)&gt;::</span><span class="identifier">return_type</span>
 479 <span class="special">{</span>
 480     <span class="comment">// Make sure arguments meet the type requirements</span>
 481
 482     <span class="keyword">static_assert</span><span class="special">(</span>
 483         <span class="identifier">is_async_read_stream</span><span class="special">&lt;</span><span class="identifier">AsyncReadStream</span><span class="special">&gt;::</span><span class="identifier">value</span><span class="special">,</span>
 484         <span class="string">"SyncReadStream type requirements not met"</span><span class="special">);</span>
 485
 486     <span class="keyword">static_assert</span><span class="special">(</span>
 487         <span class="identifier">net</span><span class="special">::</span><span class="identifier">is_dynamic_buffer</span><span class="special">&lt;</span><span class="identifier">DynamicBuffer</span><span class="special">&gt;::</span><span class="identifier">value</span><span class="special">,</span>
 488         <span class="string">"DynamicBuffer type requirements not met"</span><span class="special">);</span>
 489
 490     <span class="comment">// The function `net::async_initate` uses customization points</span>
 491     <span class="comment">// to allow one asynchronous initiating function to work with</span>
 492     <span class="comment">// all sorts of notification systems, such as callbacks but also</span>
 493     <span class="comment">// fibers, futures, coroutines, and user-defined types.</span>
 494     <span class="comment">//</span>
 495     <span class="comment">// It works by capturing all of the arguments using perfect</span>
 496     <span class="comment">// forwarding, and then depending on the specialization of</span>
 497     <span class="comment">// `net::async_result` for the type of `CompletionToken`,</span>
 498     <span class="comment">// the `initiation` object will be invoked with the saved</span>
 499     <span class="comment">// parameters and the actual completion handler. Our</span>
 500     <span class="comment">// initiating object is `run_detect_ssl_op`.</span>
 501     <span class="comment">//</span>
 502     <span class="comment">// Non-const references need to be passed as pointers,</span>
 503     <span class="comment">// since we don't want a decay-copy.</span>
 504
 505     <span class="keyword">return</span> <span class="identifier">net</span><span class="special">::</span><span class="identifier">async_initiate</span><span class="special">&lt;</span>
 506         <span class="identifier">CompletionToken</span><span class="special">,</span>
 507         <span class="keyword">void</span><span class="special">(</span><span class="identifier">error_code</span><span class="special">,</span> <span class="keyword">bool</span><span class="special">)&gt;(</span>
 508             <span class="identifier">detail</span><span class="special">::</span><span class="identifier">run_detect_ssl_op</span><span class="special">{},</span>
 509             <span class="identifier">token</span><span class="special">,</span>
 510             <span class="special">&amp;</span><span class="identifier">stream</span><span class="special">,</span> <span class="comment">// pass the reference by pointer</span>
 511             <span class="identifier">buffer</span><span class="special">);</span>
 512 <span class="special">}</span>
 513 </pre>
 514 <p>
 515           Now we will declare our composed operation. There is a considerable amount
 516           of necessary boilerplate to get this right, but the result is worth the
 517           effort.
 518         </p>
 519 <pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">detail</span> <span class="special">{</span>
 520
 521 <span class="comment">// Read from a stream, calling is_tls_client_hello on the data</span>
 522 <span class="comment">// data to determine if the TLS client handshake is present.</span>
 523 <span class="comment">//</span>
 524 <span class="comment">// This will be implemented using Asio's "stackless coroutines"</span>
 525 <span class="comment">// which are based on macros forming a switch statement. The</span>
 526 <span class="comment">// operation is derived from `coroutine` for this reason.</span>
 527 <span class="comment">//</span>
 528 <span class="comment">// The library type `async_base` takes care of all of the</span>
 529 <span class="comment">// boilerplate for writing composed operations, including:</span>
 530 <span class="comment">//</span>
 531 <span class="comment">//  * Storing the user's completion handler</span>
 532 <span class="comment">//  * Maintaining the work guard for the handler's associated executor</span>
 533 <span class="comment">//  * Propagating the associated allocator of the handler</span>
 534 <span class="comment">//  * Propagating the associated executor of the handler</span>
 535 <span class="comment">//  * Deallocating temporary storage before invoking the handler</span>
 536 <span class="comment">//  * Posting the handler to the executor on an immediate completion</span>
 537 <span class="comment">//</span>
 538 <span class="comment">// `async_base` needs to know the type of the handler, as well</span>
 539 <span class="comment">// as the executor of the I/O object being used. The metafunction</span>
 540 <span class="comment">// `executor_type` returns the type of executor used by an</span>
 541 <span class="comment">// I/O object.</span>
 542 <span class="comment">//</span>
 543 <span class="keyword">template</span><span class="special">&lt;</span>
 544     <span class="keyword">class</span> <span class="identifier">DetectHandler</span><span class="special">,</span>
 545     <span class="keyword">class</span> <span class="identifier">AsyncReadStream</span><span class="special">,</span>
 546     <span class="keyword">class</span> <span class="identifier">DynamicBuffer</span><span class="special">&gt;</span>
 547 <span class="keyword">class</span> <span class="identifier">detect_ssl_op</span>
 548     <span class="special">:</span> <span class="keyword">public</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">coroutine</span>
 549     <span class="special">,</span> <span class="keyword">public</span> <span class="identifier">async_base</span><span class="special">&lt;</span>
 550         <span class="identifier">DetectHandler</span><span class="special">,</span> <span class="identifier">executor_type</span><span class="special">&lt;</span><span class="identifier">AsyncReadStream</span><span class="special">&gt;&gt;</span>
 551 <span class="special">{</span>
 552     <span class="comment">// This composed operation has trivial state,</span>
 553     <span class="comment">// so it is just kept inside the class and can</span>
 554     <span class="comment">// be cheaply copied as needed by the implementation.</span>
 555
 556     <span class="identifier">AsyncReadStream</span><span class="special">&amp;</span> <span class="identifier">stream_</span><span class="special">;</span>
 557
 558     <span class="comment">// The callers buffer is used to hold all received data</span>
 559     <span class="identifier">DynamicBuffer</span><span class="special">&amp;</span> <span class="identifier">buffer_</span><span class="special">;</span>
 560
 561     <span class="comment">// We're going to need this in case we have to post the handler</span>
 562     <span class="identifier">error_code</span> <span class="identifier">ec_</span><span class="special">;</span>
 563
 564     <span class="identifier">boost</span><span class="special">::</span><span class="identifier">tribool</span> <span class="identifier">result_</span> <span class="special">=</span> <span class="keyword">false</span><span class="special">;</span>
 565
 566 <span class="keyword">public</span><span class="special">:</span>
 567     <span class="comment">// Completion handlers must be MoveConstructible.</span>
 568     <span class="identifier">detect_ssl_op</span><span class="special">(</span><span class="identifier">detect_ssl_op</span><span class="special">&amp;&amp;)</span> <span class="special">=</span> <span class="keyword">default</span><span class="special">;</span>
 569
 570     <span class="comment">// Construct the operation. The handler is deduced through</span>
 571     <span class="comment">// the template type `DetectHandler_`, this lets the same constructor</span>
 572     <span class="comment">// work properly for both lvalues and rvalues.</span>
 573     <span class="comment">//</span>
 574     <span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">DetectHandler_</span><span class="special">&gt;</span>
 575     <span class="identifier">detect_ssl_op</span><span class="special">(</span>
 576         <span class="identifier">DetectHandler_</span><span class="special">&amp;&amp;</span> <span class="identifier">handler</span><span class="special">,</span>
 577         <span class="identifier">AsyncReadStream</span><span class="special">&amp;</span> <span class="identifier">stream</span><span class="special">,</span>
 578         <span class="identifier">DynamicBuffer</span><span class="special">&amp;</span> <span class="identifier">buffer</span><span class="special">)</span>
 579         <span class="special">:</span> <span class="identifier">beast</span><span class="special">::</span><span class="identifier">async_base</span><span class="special">&lt;</span>
 580             <span class="identifier">DetectHandler</span><span class="special">,</span>
 581             <span class="identifier">beast</span><span class="special">::</span><span class="identifier">executor_type</span><span class="special">&lt;</span><span class="identifier">AsyncReadStream</span><span class="special">&gt;&gt;(</span>
 582                 <span class="identifier">std</span><span class="special">::</span><span class="identifier">forward</span><span class="special">&lt;</span><span class="identifier">DetectHandler_</span><span class="special">&gt;(</span><span class="identifier">handler</span><span class="special">),</span>
 583                 <span class="identifier">stream</span><span class="special">.</span><span class="identifier">get_executor</span><span class="special">())</span>
 584         <span class="special">,</span> <span class="identifier">stream_</span><span class="special">(</span><span class="identifier">stream</span><span class="special">)</span>
 585         <span class="special">,</span> <span class="identifier">buffer_</span><span class="special">(</span><span class="identifier">buffer</span><span class="special">)</span>
 586     <span class="special">{</span>
 587         <span class="comment">// This starts the operation. We pass `false` to tell the</span>
 588         <span class="comment">// algorithm that it needs to use net::post if it wants to</span>
 589         <span class="comment">// complete immediately. This is required by Networking,</span>
 590         <span class="comment">// as initiating functions are not allowed to invoke the</span>
 591         <span class="comment">// completion handler on the caller's thread before</span>
 592         <span class="comment">// returning.</span>
 593         <span class="special">(*</span><span class="keyword">this</span><span class="special">)({},</span> <span class="number">0</span><span class="special">,</span> <span class="keyword">false</span><span class="special">);</span>
 594     <span class="special">}</span>
 595
 596     <span class="comment">// Our main entry point. This will get called as our</span>
 597     <span class="comment">// intermediate operations complete. Definition below.</span>
 598     <span class="comment">//</span>
 599     <span class="comment">// The parameter `cont` indicates if we are being called subsequently</span>
 600     <span class="comment">// from the original invocation</span>
 601     <span class="comment">//</span>
 602     <span class="keyword">void</span> <span class="keyword">operator</span><span class="special">()(</span>
 603         <span class="identifier">error_code</span> <span class="identifier">ec</span><span class="special">,</span>
 604         <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">bytes_transferred</span><span class="special">,</span>
 605         <span class="keyword">bool</span> <span class="identifier">cont</span> <span class="special">=</span> <span class="keyword">true</span><span class="special">);</span>
 606 <span class="special">};</span>
 607
 608 <span class="special">}</span> <span class="comment">// detail</span>
 609 </pre>
 610 <p>
 611           The boilerplate is all done, and now we need to implement the function
 612           call operator that turns this composed operation a completion handler with
 613           the signature <code class="computeroutput"><span class="keyword">void</span><span class="special">(</span><span class="identifier">error_code</span><span class="special">,</span>
 614           <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span><span class="special">)</span></code>
 615           which is exactly the signature needed when performing asynchronous reads.
 616           This function is a transformation of the synchronous version of <code class="computeroutput"><span class="identifier">detect_ssl</span></code> above, but with the inversion
 617           of flow that characterizes code written in the callback style:
 618         </p>
 619 <pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">detail</span> <span class="special">{</span>
 620
 621 <span class="comment">// This example uses the Asio's stackless "fauxroutines", implemented</span>
 622 <span class="comment">// using a macro-based solution. It makes the code easier to write and</span>
 623 <span class="comment">// easier to read. This include file defines the necessary macros and types.</span>
 624 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">asio</span><span class="special">/</span><span class="identifier">yield</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
 625
 626 <span class="comment">// detect_ssl_op is callable with the signature void(error_code, bytes_transferred),</span>
 627 <span class="comment">// allowing `*this` to be used as a ReadHandler</span>
 628 <span class="comment">//</span>
 629 <span class="keyword">template</span><span class="special">&lt;</span>
 630     <span class="keyword">class</span> <span class="identifier">AsyncStream</span><span class="special">,</span>
 631     <span class="keyword">class</span> <span class="identifier">DynamicBuffer</span><span class="special">,</span>
 632     <span class="keyword">class</span> <span class="identifier">Handler</span><span class="special">&gt;</span>
 633 <span class="keyword">void</span>
 634 <span class="identifier">detect_ssl_op</span><span class="special">&lt;</span><span class="identifier">AsyncStream</span><span class="special">,</span> <span class="identifier">DynamicBuffer</span><span class="special">,</span> <span class="identifier">Handler</span><span class="special">&gt;::</span>
 635 <span class="keyword">operator</span><span class="special">()(</span><span class="identifier">error_code</span> <span class="identifier">ec</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">bytes_transferred</span><span class="special">,</span> <span class="keyword">bool</span> <span class="identifier">cont</span><span class="special">)</span>
 636 <span class="special">{</span>
 637     <span class="keyword">namespace</span> <span class="identifier">beast</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">beast</span><span class="special">;</span>
 638
 639     <span class="comment">// This introduces the scope of the stackless coroutine</span>
 640     <span class="identifier">reenter</span><span class="special">(*</span><span class="keyword">this</span><span class="special">)</span>
 641     <span class="special">{</span>
 642         <span class="comment">// Loop until an error occurs or we get a definitive answer</span>
 643         <span class="keyword">for</span><span class="special">(;;)</span>
 644         <span class="special">{</span>
 645             <span class="comment">// There could already be a hello in the buffer so check first</span>
 646             <span class="identifier">result_</span> <span class="special">=</span> <span class="identifier">is_tls_client_hello</span><span class="special">(</span><span class="identifier">buffer_</span><span class="special">.</span><span class="identifier">data</span><span class="special">());</span>
 647
 648             <span class="comment">// If we got an answer, then the operation is complete</span>
 649             <span class="keyword">if</span><span class="special">(!</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">indeterminate</span><span class="special">(</span><span class="identifier">result_</span><span class="special">))</span>
 650                 <span class="keyword">break</span><span class="special">;</span>
 651
 652             <span class="comment">// Try to fill our buffer by reading from the stream.</span>
 653             <span class="comment">// The function read_size calculates a reasonable size for the</span>
 654             <span class="comment">// amount to read next, using existing capacity if possible to</span>
 655             <span class="comment">// avoid allocating memory, up to the limit of 1536 bytes which</span>
 656             <span class="comment">// is the size of a normal TCP frame.</span>
 657             <span class="comment">//</span>
 658             <span class="comment">// `async_read_some` expects a ReadHandler as the completion</span>
 659             <span class="comment">// handler. The signature of a read handler is void(error_code, size_t),</span>
 660             <span class="comment">// and this function matches that signature (the `cont` parameter has</span>
 661             <span class="comment">// a default of true). We pass `std::move(*this)` as the completion</span>
 662             <span class="comment">// handler for the read operation. This transfers ownership of this</span>
 663             <span class="comment">// entire state machine back into the `async_read_some` operation.</span>
 664             <span class="comment">// Care must be taken with this idiom, to ensure that parameters</span>
 665             <span class="comment">// passed to the initiating function which could be invalidated</span>
 666             <span class="comment">// by the move, are first moved to the stack before calling the</span>
 667             <span class="comment">// initiating function.</span>
 668
 669             <span class="identifier">yield</span> <span class="identifier">stream_</span><span class="special">.</span><span class="identifier">async_read_some</span><span class="special">(</span><span class="identifier">buffer_</span><span class="special">.</span><span class="identifier">prepare</span><span class="special">(</span>
 670                 <span class="identifier">read_size</span><span class="special">(</span><span class="identifier">buffer_</span><span class="special">,</span> <span class="number">1536</span><span class="special">)),</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">move</span><span class="special">(*</span><span class="keyword">this</span><span class="special">));</span>
 671
 672             <span class="comment">// Commit what we read into the buffer's input area.</span>
 673             <span class="identifier">buffer_</span><span class="special">.</span><span class="identifier">commit</span><span class="special">(</span><span class="identifier">bytes_transferred</span><span class="special">);</span>
 674
 675             <span class="comment">// Check for an error</span>
 676             <span class="keyword">if</span><span class="special">(</span><span class="identifier">ec</span><span class="special">)</span>
 677                 <span class="keyword">break</span><span class="special">;</span>
 678         <span class="special">}</span>
 679
 680         <span class="comment">// If `cont` is true, the handler will be invoked directly.</span>
 681         <span class="comment">//</span>
 682         <span class="comment">// Otherwise, the handler cannot be invoked directly, because</span>
 683         <span class="comment">// initiating functions are not allowed to call the handler</span>
 684         <span class="comment">// before returning. Instead, the handler must be posted to</span>
 685         <span class="comment">// the I/O context. We issue a zero-byte read using the same</span>
 686         <span class="comment">// type of buffers used in the ordinary read above, to prevent</span>
 687         <span class="comment">// the compiler from creating an extra instantiation of the</span>
 688         <span class="comment">// function template. This reduces compile times and the size</span>
 689         <span class="comment">// of the program executable.</span>
 690
 691         <span class="keyword">if</span><span class="special">(!</span> <span class="identifier">cont</span><span class="special">)</span>
 692         <span class="special">{</span>
 693             <span class="comment">// Save the error, otherwise it will be overwritten with</span>
 694             <span class="comment">// a successful error code when this read completes</span>
 695             <span class="comment">// immediately.</span>
 696             <span class="identifier">ec_</span> <span class="special">=</span> <span class="identifier">ec</span><span class="special">;</span>
 697
 698             <span class="comment">// Zero-byte reads and writes are guaranteed to complete</span>
 699             <span class="comment">// immediately with succcess. The type of buffers and the</span>
 700             <span class="comment">// type of handler passed here need to exactly match the types</span>
 701             <span class="comment">// used in the call to async_read_some above, to avoid</span>
 702             <span class="comment">// instantiating another version of the function template.</span>
 703
 704             <span class="identifier">yield</span> <span class="identifier">stream_</span><span class="special">.</span><span class="identifier">async_read_some</span><span class="special">(</span><span class="identifier">buffer_</span><span class="special">.</span><span class="identifier">prepare</span><span class="special">(</span><span class="number">0</span><span class="special">),</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">move</span><span class="special">(*</span><span class="keyword">this</span><span class="special">));</span>
 705
 706             <span class="comment">// Restore the saved error code</span>
 707             <span class="identifier">ec</span> <span class="special">=</span> <span class="identifier">ec_</span><span class="special">;</span>
 708         <span class="special">}</span>
 709
 710         <span class="comment">// Invoke the final handler.</span>
 711         <span class="comment">// At this point, we are guaranteed that the original initiating</span>
 712         <span class="comment">// function is no longer on our stack frame.</span>
 713
 714         <span class="keyword">this</span><span class="special">-&gt;</span><span class="identifier">complete_now</span><span class="special">(</span><span class="identifier">ec</span><span class="special">,</span> <span class="keyword">static_cast</span><span class="special">&lt;</span><span class="keyword">bool</span><span class="special">&gt;(</span><span class="identifier">result_</span><span class="special">));</span>
 715     <span class="special">}</span>
 716 <span class="special">}</span>
 717
 718 <span class="comment">// Including this file undefines the macros used by the stackless fauxroutines.</span>
 719 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">asio</span><span class="special">/</span><span class="identifier">unyield</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
 720
 721 <span class="special">}</span> <span class="comment">// detail</span>
 722 </pre>
 723 <p>
 724           The examples <a href="../../../../../example/advanced/server/advanced_server.cpp" target="_top">advanced-server</a> and
 725           <a href="../../../../../example/advanced/server-flex/advanced_server_flex.cpp" target="_top">advanced-server-flex</a>
 726 use
 727           this SSL detection function.
 728         </p>
 729 </div>
 730 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 731 <td align="left"></td>
 732 <td align="right"><div class="copyright-footer">Copyright &#169; 2016-2019 Vinnie
 733       Falco<p>
 734         Distributed under the Boost Software License, Version 1.0. (See accompanying
 735         file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
 736       </p>
 737 </div></td>
 738 </tr></table>
 739 <hr>
 740 <div class="spirit-nav">
 741 <a accesskey="p" href="echo.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../writing_composed_operations.html"><img src="../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="../../using_http.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
 742 </div>
 743 </body>
 744 </html>