Author: buildbot
Date: Sun May 4 20:26:51 2014
New Revision: 908027
Log:
Staging update by buildbot for thrift
Modified:
websites/staging/thrift/trunk/content/ (props changed)
websites/staging/thrift/trunk/content/lib/cpp.html
Propchange: websites/staging/thrift/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Sun May 4 20:26:51 2014
@@ -1 +1 @@
-1592231
+1592416
Modified: websites/staging/thrift/trunk/content/lib/cpp.html
==============================================================================
--- websites/staging/thrift/trunk/content/lib/cpp.html (original)
+++ websites/staging/thrift/trunk/content/lib/cpp.html Sun May 4 20:26:51 2014
@@ -75,21 +75,27 @@
<div class="container">
<h1 id="using-thrift-with-c">Using Thrift with C++</h1>
<p>The Thrift C++ libraries are built using the GNU tools. Follow the
instructions
-in the top-level README, or run bootstrap.sh in this folder to generate the
-Makefiles.</p>
-<p>In case you do not want to open another README file, do this:
- ./bootstrap.sh
- ./configure (--with-boost=/usr/local)
- make
- sudo make install</p>
+in the top-level README.md</p>
+<p>In case you do not want to open another README.md file, do this thrift
src:</p>
+<div class="codehilite"><pre><span class="o">./</span><span
class="n">bootstrap</span><span class="p">.</span><span class="n">sh</span>
+<span class="o">./</span><span class="n">configure</span> <span
class="p">(</span><span class="o">--</span><span class="n">with</span><span
class="o">-</span><span class="n">boost</span><span class="p">=</span><span
class="o">/</span><span class="n">usr</span><span class="o">/</span><span
class="n">local</span><span class="p">)</span>
+<span class="n">make</span>
+<span class="n">sudo</span> <span class="n">make</span> <span
class="n">install</span>
+</pre></div>
+
+
<p>Thrift is divided into two libraries.</p>
-<p>libthrift
- The core Thrift library contains all the core Thrift code. It requires
+<ul>
+<li>
+<p>libthrift - The core Thrift library contains all the core Thrift code. It
requires
boost shared pointers, pthreads, and librt.</p>
-<p>libthriftnb
- This library contains the Thrift nonblocking server, which uses libevent.
+</li>
+<li>
+<p>libthriftnb - This library contains the Thrift nonblocking server, which
uses libevent.
To link this library you will also need to link libevent.</p>
-<h1 id="linking-against-thrift">Linking Against Thrift</h1>
+</li>
+</ul>
+<h2 id="linking-against-thrift">Linking Against Thrift</h2>
<p>After you build and install Thrift the libraries are installed to
/usr/local/lib by default. Make sure this is in your LDPATH.</p>
<p>On Linux, the best way to do this is to ensure that /usr/local/lib is in
@@ -98,11 +104,193 @@ your /etc/ld.so.conf and then run /sbin/
your build environment it set up, you may need to include additional
libraries when linking against thrift, such as librt and/or libpthread. If
you are using libthriftnb you will also need libevent.</p>
-<h1 id="dependencies">Dependencies</h1>
+<h2 id="dependencies">Dependencies</h2>
+<p>boost shared pointers
+http://www.boost.org/libs/smart_ptr/smart_ptr.htm</p>
+<p>libevent (for libthriftnb only)
+http://monkey.org/~provos/libevent/</p>
+<h1 id="using-thrift-with-c-on-windows">Using Thrift with C++ on Windows</h1>
+<p>You need to define an enviroment variable called THIRD_PARTY. The project
+assumes that you have extracted the dependancies into their default structure
+into the path defined by THIRD_PARTY.</p>
+<p>e.g. $(THIRD_PARTY)/boost/boost_1_47_0/</p>
+<p>Thrift is divided into two libraries.</p>
+<ul>
+<li>
+<p>libthrift - The core Thrift library contains all the core Thrift code. It
requires
+ boost shared pointers, pthreads, and librt.</p>
+</li>
+<li>
+<p>libthriftnb - This library contains the Thrift nonblocking server, which
uses libevent.
+ To link this library you will also need to link libevent.</p>
+</li>
+</ul>
+<h2 id="linking-against-thrift_1">Linking Against Thrift</h2>
+<p>You need to link your project that uses thrift against all the thrift
+dependancies; in the case of libthrift, boost and for
+libthriftnb, libevent.</p>
+<p>In the project properties you must also set HAVE_CONFIG_H as force include
+the config header: "windows/confg.h"</p>
+<h2 id="dependencies_1">Dependencies</h2>
<p>boost shared pointers
http://www.boost.org/libs/smart_ptr/smart_ptr.htm</p>
+<p>boost thread
+http://www.boost.org/doc/libs/release/doc/html/thread.html</p>
<p>libevent (for libthriftnb only)
-http://monkey.org/~provos/libevent/
+http://monkey.org/~provos/libevent/</p>
+<h2 id="notes-on-boost-thread-static-vs-shared">Notes on boost thread (static
vs shared):</h2>
+<p>By default lib/cpp/windows/force_inc.h defines:</p>
+<div class="codehilite"><pre><span class="c">#define BOOST_ALL_NO_LIB 1</span>
+<span class="c">#define BOOST_THREAD_NO_LIB 1</span>
+</pre></div>
+
+
+<p>This has for effect to have the host application linking against Thrift
+to have to link with boost thread as a static library.</p>
+<p>If you wanted instead to link with boost thread as a shared library,
+you'll need to uncomment those two lines, and recompile.</p>
+<h2 id="windows-version-compatibility">Windows version compatibility</h2>
+<p>The Thrift library targets Windows XP for broadest compatbility. A notable
+difference is in the Windows-specific implementation of the socket poll
+function. To target Vista, Win7 or other versions, comment out the line</p>
+<div class="codehilite"><pre><span class="c">#define TARGET_WIN_XP.</span>
+</pre></div>
+
+
+<h2 id="named-pipes">Named Pipes</h2>
+<p>Named Pipe transport has been added in the TPipe and TPipeServer classes.
This
+is currently Windows-only. Named pipe transport for <em>NIX has not been
+implemented. Domain sockets are a better choice for local IPC under non-Windows
+OS's. </em>NIX named pipes only support 1:1 client-server connection.</p>
+<h1 id="thriftssl">Thrift/SSL</h1>
+<ol>
+<li>Scope</li>
+</ol>
+<p>This SSL only supports blocking mode socket I/O. It can only be used with
+ TSimpleServer, TThreadedServer, and TThreadPoolServer.</p>
+<ol>
+<li>Implementation</li>
+</ol>
+<p>There're two main classes TSSLSocketFactory and TSSLSocket. Instances of
+ TSSLSocket are always created from TSSLSocketFactory.</p>
+<p>PosixSSLThreadFactory creates PosixSSLThread. The only difference from the
+ PthreadThread type is that it cleanups OpenSSL error queue upon exiting
+ the thread. Ideally, OpenSSL APIs should only be called from
PosixSSLThread.</p>
+<ol>
+<li>
+<p>How to use SSL APIs</p>
+<div class="codehilite"><pre><span class="c1">// This is for demo. In real
code, typically only one TSSLSocketFactory</span>
+<span class="c1">// instance is needed.</span>
+<span class="n">shared_ptr</span><span class="o"><</span><span
class="n">TSSLSocketFactory</span><span class="o">></span> <span
class="n">getSSLSocketFactory</span><span class="p">()</span> <span
class="p">{</span>
+ <span class="n">shared_ptr</span><span class="o"><</span><span
class="n">TSSLSocketFactory</span><span class="o">></span> <span
class="n">factory</span><span class="p">(</span><span class="k">new</span>
<span class="n">TSSLSocketFactory</span><span class="p">());</span>
+ <span class="c1">// client: load trusted certificates</span>
+ <span class="n">factory</span><span class="o">-></span><span
class="n">loadTrustedCertificates</span><span class="p">(</span><span
class="s">"my-trusted-ca-certificates.pem"</span><span
class="p">);</span>
+ <span class="c1">// client: optionally set your own access manager,
otherwise,</span>
+ <span class="c1">// the default client access manager will be
loaded.</span>
+
+ <span class="n">factory</span><span class="o">-></span><span
class="n">loadCertificate</span><span class="p">(</span><span
class="s">"my-certificate-signed-by-ca.pem"</span><span
class="p">);</span>
+ <span class="n">factory</span><span class="o">-></span><span
class="n">loadPrivateKey</span><span class="p">(</span><span
class="s">"my-private-key.pem"</span><span class="p">);</span>
+ <span class="c1">// server: optionally setup access manager</span>
+ <span class="c1">// shared_ptr<AccessManager> accessManager(new
MyAccessManager);</span>
+ <span class="c1">// factory->access(accessManager);</span>
+ <span class="p">...</span>
+<span class="p">}</span>
+
+<span class="c1">// client code sample</span>
+<span class="n">shared_ptr</span><span class="o"><</span><span
class="n">TSSLSocketFactory</span><span class="o">></span> <span
class="n">factory</span> <span class="o">=</span> <span
class="n">getSSLSocketFactory</span><span class="p">();</span>
+<span class="n">shared_ptr</span><span class="o"><</span><span
class="n">TSocket</span><span class="o">></span> <span
class="n">socket</span> <span class="o">=</span> <span
class="n">factory</span><span class="p">.</span><span
class="n">createSocket</span><span class="p">(</span><span
class="n">host</span><span class="p">,</span> <span class="n">port</span><span
class="p">);</span>
+<span class="n">shared_ptr</span><span class="o"><</span><span
class="n">TBufferedTransport</span><span class="o">></span> <span
class="n">transport</span><span class="p">(</span><span class="k">new</span>
<span class="n">TBufferedTransport</span><span class="p">(</span><span
class="n">socket</span><span class="p">));</span>
+<span class="p">...</span>
+
+<span class="c1">// server code sample</span>
+<span class="n">shared_ptr</span><span class="o"><</span><span
class="n">TSSLSocketFactory</span><span class="o">></span> <span
class="n">factory</span> <span class="o">=</span> <span
class="n">getSSLSocketFactory</span><span class="p">();</span>
+<span class="n">shared_ptr</span><span class="o"><</span><span
class="n">TSSLServerSocket</span><span class="o">></span> <span
class="n">socket</span><span class="p">(</span><span class="k">new</span> <span
class="n">TSSLServerSocket</span><span class="p">(</span><span
class="n">port</span><span class="p">,</span> <span
class="n">factory</span><span class="p">));</span>
+<span class="n">shared_ptr</span><span class="o"><</span><span
class="n">TTransportFactory</span><span class="o">></span> <span
class="n">transportFactory</span><span class="p">(</span><span
class="k">new</span> <span class="n">TBufferedTransportFactory</span><span
class="p">));</span>
+<span class="p">...</span>
+</pre></div>
+
+
+</li>
+<li>
+<p>AccessManager</p>
+</li>
+</ol>
+<p>AccessManager defines a callback interface. It has three callback
methods:</p>
+<p>(a) Decision verify(const sockaddr_storage& sa);
+ (b) Decision verify(const string& host, const char<em> name, int size);
+ (c) Decision verify(const sockaddr_storage& sa, const char</em> data,
int size);</p>
+<p>After SSL handshake completes, additional checks are conducted. Application
+ is given the chance to decide whether or not to continue the conversation
+ with the remote. Application is queried through the above three "verify"
+ method. They are called at different points of the verification process.</p>
+<p>Decisions can be one of ALLOW, DENY, and SKIP. ALLOW and DENY means the
+ conversation should be continued or disconnected, respectively. ALLOW and
+ DENY decision stops the verification process. SKIP means there's no decision
+ based on the given input, continue the verification process.</p>
+<p>First, (a) is called with the remote IP. It is called once at the beginning.
+ "sa" is the IP address of the remote peer.</p>
+<p>Then, the certificate of remote peer is loaded. SubjectAltName extensions
+ are extracted and sent to application for verification. When a DNS
+ subjectAltName field is extracted, (b) is called. When an IP subjectAltName
+ field is extracted, (c) is called.</p>
+<p>The "host" in (b) is the value from TSocket::getHost() if this is a client
+ side socket, or TSocket::getPeerHost() if this is a server side socket. The
+ reason is client side socket initiates the connection. TSocket::getHost()
+ is the remote host name. On server side, the remote host name is unknown
+ unless it's retrieved through TSocket::getPeerHost(). Either way, "host"
+ should be the remote host name. Keep in mind, if TSocket::getPeerHost()
+ failed, it would return the remote host name in numeric format.</p>
+<p>If all subjectAltName extensions were "skipped", the common name field would
+ be checked. It is sent to application through (c), where "sa" is the remote
+ IP address. "data" is the IP address extracted from subjectAltName IP
+ extension, and "size" is the length of the extension data.</p>
+<p>If any of the above "verify" methods returned a decision ALLOW or DENY, the
+ verification process would be stopped.</p>
+<p>If any of the above "verify" methods returned SKIP, that decision would be
+ ignored and the verification process would move on till the last item is
+ examined. At that point, if there's still no decision, the connection is
+ terminated.</p>
+<p>Thread safety, an access manager should not store state information if it's
+ to be used by many SSL sockets.</p>
+<ol>
+<li>SIGPIPE signal</li>
+</ol>
+<p>Applications running OpenSSL over network connections may crash if SIGPIPE
+ is not ignored. This happens when they receive a connection reset by remote
+ peer exception, which somehow triggers a SIGPIPE signal. If not handled,
+ this signal would kill the application.</p>
+<ol>
+<li>How to run test client/server in SSL mode</li>
+</ol>
+<p>The server and client expects the followings from the directory /test/</p>
+<ul>
+<li>keys/server.crt</li>
+<li>keys/server.key</li>
+<li>keys/CA.pem</li>
+</ul>
+<p>The file names are hard coded in the source code. You need to create these
+ certificates before you can run the test code in SSL mode. Make sure at
least
+ one of the followings is included in "keys/server.crt",</p>
+<ul>
+<li>subjectAltName, DNS localhost</li>
+<li>subjectAltName, IP 127.0.0.1</li>
+<li>common name, localhost</li>
+</ul>
+<p>Run within /test/ folder,</p>
+<div class="codehilite"><pre> <span class="o">./</span><span
class="n">cpp</span><span class="o">/</span><span class="n">TestServer</span>
<span class="o">--</span><span class="n">ssl</span> <span class="o">&</span>
+ <span class="o">./</span><span class="n">cpp</span><span
class="o">/</span><span class="n">TestClient</span> <span
class="o">--</span><span class="n">ssl</span>
+</pre></div>
+
+
+<p>If "-h <host>" is used to run client, the above "localhost" in the above
+ server-certificate.pem has to be replaced with that host name.</p>
+<ol>
+<li>TSSLSocketFactory::randomize()</li>
+</ol>
+<p>The default implementation of OpenSSLSocketFactory::randomize() simply calls
+ OpenSSL's RAND_poll() when OpenSSL library is first initialized.</p>
+<p>The PRNG seed is key to the application security. This method should be
+ overridden if it's not strong enough for you.
<p class='snippet_footer'>
This page was generated by Apache Thrift's <strong>source tree docs</strong>:
<a
href="http://git-wip-us.apache.org/repos/asf?p=thrift.git;a=blob;f=lib/cpp/README.md;hb=HEAD";</a>lib/cpp/README.md</a>
