You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@thrift.apache.org by bu...@apache.org on 2014/05/04 22:37:37 UTC
svn commit: r908028 - in /websites/staging/thrift/trunk/content: ./
lib/cpp.html
Author: buildbot
Date: Sun May 4 20:37:37 2014
New Revision: 908028
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:37:37 2014
@@ -1 +1 @@
-1592416
+1592417
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:37:37 2014
@@ -163,105 +163,95 @@ is currently Windows-only. Named pipe tr
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>
+<h2 id="scope">Scope</h2>
<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>
+TSimpleServer, TThreadedServer, and TThreadPoolServer.</p>
+<h2 id="implementation">Implementation</h2>
<p>There're two main classes TSSLSocketFactory and TSSLSocket. Instances of
- TSSLSocket are always created from TSSLSocketFactory.</p>
+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>
+PthreadThread type is that it cleanups OpenSSL error queue upon exiting
+the thread. Ideally, OpenSSL APIs should only be called from PosixSSLThread.</p>
+<h2 id="how-to-use-ssl-apis">How to use SSL APIs</h2>
+<p>This is for demo. In real code, typically only one TSSLSocketFactory
+instance is needed.</p>
+<div class="codehilite"><pre><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="n">new</span> <span class="n">TSSLSocketFactory</span><span class="p">());</span>
+ <span class="o">//</span> <span class="n">client</span><span class="p">:</span> <span class="n">load</span> <span class="n">trusted</span> <span class="n">certificates</span>
+ <span class="n">factory</span><span class="o">-></span><span class="n">loadTrustedCertificates</span><span class="p">(</span>"<span class="n">my</span><span class="o">-</span><span class="n">trusted</span><span class="o">-</span><span class="n">ca</span><span class="o">-</span><span class="n">certificates</span><span class="p">.</span><span class="n">pem</span>"<span class="p">);</span>
+ <span class="o">//</span> <span class="n">client</span><span class="p">:</span> <span class="n">optionally</span> <span class="n">set</span> <span class="n">your</span> <span class="n">own</span> <span class="n">access</span> <span class="n">manager</span><span class="p">,</span> <span class="k">otherwise</span><span class="p">,</span>
+ <span class="o">//</span> <span class="n">the</span> <span class="n">default</span> <span class="n">client</span> <span class="n">access</span> <span class="n">manager</span> <span class="n">will</span> <span class="n">be</span> <span class="n">loaded</span><span class="p">.</span>
+
+ <span class="n">factory</span><span class="o">-></span><span class="n">loadCertificate</span><span class="p">(</span>"<span class="n">my</span><span class="o">-</span><span class="n">certificate</span><span class="o">-</span><span class="n">signed</span><span class="o">-</span><span class="n">by</span><span class="o">-</span><span class="n">ca</span><span class="p">.</span><span class="n">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="n">my</span><span class="o">-</span><span class="n">private</span><span class="o">-</span><span class="n">key</span><span class="p">.</span><span class="n">pem</span>"<span class="p">);</span>
+ <span class="o">//</span> <span class="n">server</span><span class="p">:</span> <span class="n">optionally</span> <span class="n">setup</span> <span class="n">access</span> <span class="n">manager</span>
+ <span class="o">//</span> <span class="n">shared_ptr</span><span class="o"><</span><span class="n">AccessManager</span><span class="o">></span> <span class="n">accessManager</span><span class="p">(</span><span class="n">new</span> <span class="n">MyAccessManager</span><span class="p">);</span>
+ <span class="o">//</span> <span class="n">factory</span><span class="o">-></span><span class="n">access</span><span class="p">(</span><span class="n">accessManager</span><span class="p">);</span>
<span class="p">...</span>
<span class="p">}</span>
+</pre></div>
+
-<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>
+<p>client code sample</p>
+<div class="codehilite"><pre><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="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="p">=</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="n">new</span> <span class="n">TBufferedTransport</span><span class="p">(</span><span class="n">socket</span><span class="p">));</span>
<span class="p">...</span>
+</pre></div>
+
-<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>
+<p>server code sample</p>
+<div class="codehilite"><pre><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="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="n">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="n">new</span> <span class="n">TBufferedTransportFactory</span><span class="p">));</span>
<span class="p">...</span>
</pre></div>
-</li>
-<li>
-<p>AccessManager</p>
-</li>
-</ol>
+<h2 id="accessmanager">AccessManager</h2>
<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>(a) Decision verify(const sockaddr_storage& sa);</p>
+<p>(b) Decision verify(const string& host, const char* name, int size);</p>
+<p>(c) Decision verify(const sockaddr_storage& sa, const char* 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>
+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>
+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>
+"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>
+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>
+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>
+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>
+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>
+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>
+to be used by many SSL sockets.</p>
+<h2 id="sigpipe-signal">SIGPIPE signal</h2>
<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>
+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>
+<h2 id="how-to-run-test-clientserver-in-ssl-mode">How to run test client/server in SSL mode</h2>
<p>The server and client expects the followings from the directory /test/</p>
<ul>
<li>keys/server.crt</li>
@@ -269,28 +259,26 @@ OS's. </em>NIX named pipes only support
<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>
+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>
+<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>
+keys/server.crt has to be replaced with that host name.</p>
+<h2 id="tsslsocketfactoryrandomize">TSSLSocketFactory::randomize()</h2>
<p>The default implementation of OpenSSLSocketFactory::randomize() simply calls
- OpenSSL's RAND_poll() when OpenSSL library is first initialized.</p>
+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.
+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>