THRIFT-2512 lib/${language}/README.md
Client: cpp
merge README_WINDOWS.md and README.SSL.md into README.md
diff --git a/lib/cpp/README.SSL.md b/lib/cpp/README.SSL.md
deleted file mode 100644
index a928057..0000000
--- a/lib/cpp/README.SSL.md
+++ /dev/null
@@ -1,135 +0,0 @@
-Notes on Thrift/SSL
-
-Author: Ping Li <pingli@facebook.com>
-
-1. Scope
-
- This SSL only supports blocking mode socket I/O. It can only be used with
- TSimpleServer, TThreadedServer, and TThreadPoolServer.
-
-2. Implementation
-
- There're two main classes TSSLSocketFactory and TSSLSocket. Instances of
- TSSLSocket are always created from TSSLSocketFactory.
-
- 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.
-
-3. How to use SSL APIs
-
- // This is for demo. In real code, typically only one TSSLSocketFactory
- // instance is needed.
- shared_ptr<TSSLSocketFactory> getSSLSocketFactory() {
- shared_ptr<TSSLSocketFactory> factory(new TSSLSocketFactory());
- // client: load trusted certificates
- factory->loadTrustedCertificates("my-trusted-ca-certificates.pem");
- // client: optionally set your own access manager, otherwise,
- // the default client access manager will be loaded.
-
- factory->loadCertificate("my-certificate-signed-by-ca.pem");
- factory->loadPrivateKey("my-private-key.pem");
- // server: optionally setup access manager
- // shared_ptr<AccessManager> accessManager(new MyAccessManager);
- // factory->access(accessManager);
- ...
- }
-
- // client code sample
- shared_ptr<TSSLSocketFactory> factory = getSSLSocketFactory();
- shared_ptr<TSocket> socket = factory.createSocket(host, port);
- shared_ptr<TBufferedTransport> transport(new TBufferedTransport(socket));
- ...
-
- // server code sample
- shared_ptr<TSSLSocketFactory> factory = getSSLSocketFactory();
- shared_ptr<TSSLServerSocket> socket(new TSSLServerSocket(port, factory));
- shared_ptr<TTransportFactory> transportFactory(new TBufferedTransportFactory));
- ...
-
-4. AccessManager
-
- AccessManager defines a callback interface. It has three callback methods:
-
- (a) Decision verify(const sockaddr_storage& sa);
- (b) Decision verify(const string& host, const char* name, int size);
- (c) Decision verify(const sockaddr_storage& sa, const char* data, int size);
-
- 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.
-
- 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.
-
- First, (a) is called with the remote IP. It is called once at the beginning.
- "sa" is the IP address of the remote peer.
-
- 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.
-
- 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.
-
- 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.
-
- If any of the above "verify" methods returned a decision ALLOW or DENY, the
- verification process would be stopped.
-
- 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.
-
- Thread safety, an access manager should not store state information if it's
- to be used by many SSL sockets.
-
-5. SIGPIPE signal
-
- 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.
-
-6. How to run test client/server in SSL mode
-
- The server expects the followings from the current working directory,
- - "server-certificate.pem"
- - "server-private-key.pem"
-
- The client loads "trusted-ca-certificate.pem" from current directory.
-
- 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 "server-certificate.pem",
- - subjectAltName, DNS localhost
- - subjectAltName, IP 127.0.0.1
- - common name, localhost
-
- Run,
- - "./test_server --ssl" to start server
- - "./test_client --ssl" to run client
-
- 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.
-
-7. TSSLSocketFactory::randomize()
-
- The default implementation of OpenSSLSocketFactory::randomize() simply calls
- OpenSSL's RAND_poll() when OpenSSL library is first initialized.
-
- The PRNG seed is key to the application security. This method should be
- overridden if it's not strong enough for you.
diff --git a/lib/cpp/README.md b/lib/cpp/README.md
old mode 100644
new mode 100755
index 576d017..e57fdd4
--- a/lib/cpp/README.md
+++ b/lib/cpp/README.md
@@ -1,7 +1,6 @@
Thrift C++ Software Library
-License
-=======
+# License
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
@@ -20,31 +19,28 @@
specific language governing permissions and limitations
under the License.
-Using Thrift with C++
-=====================
+
+# Using Thrift with C++
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.
+in the top-level README.md
-In case you do not want to open another README file, do this:
- ./bootstrap.sh
- ./configure (--with-boost=/usr/local)
- make
- sudo make install
+In case you do not want to open another README.md file, do this thrift src:
+
+ ./bootstrap.sh
+ ./configure (--with-boost=/usr/local)
+ make
+ sudo make install
Thrift is divided into two libraries.
-libthrift
- The core Thrift library contains all the core Thrift code. It requires
+* libthrift - The core Thrift library contains all the core Thrift code. It requires
boost shared pointers, pthreads, and librt.
-libthriftnb
- This library contains the Thrift nonblocking server, which uses libevent.
+* libthriftnb - This library contains the Thrift nonblocking server, which uses libevent.
To link this library you will also need to link libevent.
-Linking Against Thrift
-======================
+## Linking Against Thrift
After you build and install Thrift the libraries are installed to
/usr/local/lib by default. Make sure this is in your LDPATH.
@@ -57,11 +53,212 @@
libraries when linking against thrift, such as librt and/or libpthread. If
you are using libthriftnb you will also need libevent.
-Dependencies
-============
+## Dependencies
boost shared pointers
http://www.boost.org/libs/smart_ptr/smart_ptr.htm
libevent (for libthriftnb only)
http://monkey.org/~provos/libevent/
+
+# Using Thrift with C++ on Windows
+
+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.
+
+e.g. $(THIRD_PARTY)/boost/boost_1_47_0/
+
+Thrift is divided into two libraries.
+
+* libthrift - The core Thrift library contains all the core Thrift code. It requires
+ boost shared pointers, pthreads, and librt.
+
+* libthriftnb - This library contains the Thrift nonblocking server, which uses libevent.
+ To link this library you will also need to link libevent.
+
+## Linking Against Thrift
+
+You need to link your project that uses thrift against all the thrift
+dependancies; in the case of libthrift, boost and for
+libthriftnb, libevent.
+
+In the project properties you must also set HAVE_CONFIG_H as force include
+the config header: "windows/confg.h"
+
+## Dependencies
+
+boost shared pointers
+http://www.boost.org/libs/smart_ptr/smart_ptr.htm
+
+boost thread
+http://www.boost.org/doc/libs/release/doc/html/thread.html
+
+libevent (for libthriftnb only)
+http://monkey.org/~provos/libevent/
+
+## Notes on boost thread (static vs shared):
+
+By default lib/cpp/windows/force_inc.h defines:
+
+ #define BOOST_ALL_NO_LIB 1
+ #define BOOST_THREAD_NO_LIB 1
+
+This has for effect to have the host application linking against Thrift
+to have to link with boost thread as a static library.
+
+If you wanted instead to link with boost thread as a shared library,
+you'll need to uncomment those two lines, and recompile.
+
+## Windows version compatibility
+
+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
+
+ #define TARGET_WIN_XP.
+
+## Named Pipes
+
+Named Pipe transport has been added in the TPipe and TPipeServer classes. This
+is currently Windows-only. Named pipe transport for *NIX has not been
+implemented. Domain sockets are a better choice for local IPC under non-Windows
+OS's. *NIX named pipes only support 1:1 client-server connection.
+
+# Thrift/SSL
+
+1. Scope
+
+ This SSL only supports blocking mode socket I/O. It can only be used with
+ TSimpleServer, TThreadedServer, and TThreadPoolServer.
+
+2. Implementation
+
+ There're two main classes TSSLSocketFactory and TSSLSocket. Instances of
+ TSSLSocket are always created from TSSLSocketFactory.
+
+ 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.
+
+3. How to use SSL APIs
+
+ // This is for demo. In real code, typically only one TSSLSocketFactory
+ // instance is needed.
+ shared_ptr<TSSLSocketFactory> getSSLSocketFactory() {
+ shared_ptr<TSSLSocketFactory> factory(new TSSLSocketFactory());
+ // client: load trusted certificates
+ factory->loadTrustedCertificates("my-trusted-ca-certificates.pem");
+ // client: optionally set your own access manager, otherwise,
+ // the default client access manager will be loaded.
+
+ factory->loadCertificate("my-certificate-signed-by-ca.pem");
+ factory->loadPrivateKey("my-private-key.pem");
+ // server: optionally setup access manager
+ // shared_ptr<AccessManager> accessManager(new MyAccessManager);
+ // factory->access(accessManager);
+ ...
+ }
+
+
+ // client code sample
+ shared_ptr<TSSLSocketFactory> factory = getSSLSocketFactory();
+ shared_ptr<TSocket> socket = factory.createSocket(host, port);
+ shared_ptr<TBufferedTransport> transport(new TBufferedTransport(socket));
+ ...
+
+
+ // server code sample
+ shared_ptr<TSSLSocketFactory> factory = getSSLSocketFactory();
+ shared_ptr<TSSLServerSocket> socket(new TSSLServerSocket(port, factory));
+ shared_ptr<TTransportFactory> transportFactory(new TBufferedTransportFactory));
+ ...
+
+4. AccessManager
+
+ AccessManager defines a callback interface. It has three callback methods:
+
+ (a) Decision verify(const sockaddr_storage& sa);
+ (b) Decision verify(const string& host, const char* name, int size);
+ (c) Decision verify(const sockaddr_storage& sa, const char* data, int size);
+
+ 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.
+
+ 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.
+
+ First, (a) is called with the remote IP. It is called once at the beginning.
+ "sa" is the IP address of the remote peer.
+
+ 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.
+
+ 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.
+
+ 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.
+
+ If any of the above "verify" methods returned a decision ALLOW or DENY, the
+ verification process would be stopped.
+
+ 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.
+
+ Thread safety, an access manager should not store state information if it's
+ to be used by many SSL sockets.
+
+5. SIGPIPE signal
+
+ 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.
+
+6. How to run test client/server in SSL mode
+
+ The server and client expects the followings from the directory /test/
+
+ - keys/server.crt
+ - keys/server.key
+ - keys/CA.pem
+
+ 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",
+
+ - subjectAltName, DNS localhost
+ - subjectAltName, IP 127.0.0.1
+ - common name, localhost
+
+ Run within /test/ folder,
+
+ ./cpp/TestServer --ssl &
+ ./cpp/TestClient --ssl
+
+ 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.
+
+7. TSSLSocketFactory::randomize()
+
+ The default implementation of OpenSSLSocketFactory::randomize() simply calls
+ OpenSSL's RAND_poll() when OpenSSL library is first initialized.
+
+ The PRNG seed is key to the application security. This method should be
+ overridden if it's not strong enough for you.
diff --git a/lib/cpp/README_WINDOWS.md b/lib/cpp/README_WINDOWS.md
deleted file mode 100644
index f4c887c..0000000
--- a/lib/cpp/README_WINDOWS.md
+++ /dev/null
@@ -1,107 +0,0 @@
-Thrift C++ Software Library
-
-License
-=======
-
-Licensed to the Apache Software Foundation (ASF) under one
-or more contributor license agreements. See the NOTICE file
-distributed with this work for additional information
-regarding copyright ownership. The ASF licenses this file
-to you under the Apache License, Version 2.0 (the
-"License"); you may not use this file except in compliance
-with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing,
-software distributed under the License is distributed on an
-"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-KIND, either express or implied. See the License for the
-specific language governing permissions and limitations
-under the License.
-
-Using Thrift with C++
-=====================
-
-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.
-
-e.g. $(THIRD_PARTY)/boost/boost_1_47_0/
-
-Thrift is divided into two libraries.
-
-libthrift
- The core Thrift library contains all the core Thrift code. It requires
- boost shared pointers and boost thread.
-
-libthriftnb
- This library contains the Thrift nonblocking server, which uses libevent.
- To link this library you will also need to link libevent.
-
-Linking Against Thrift
-======================
-
-You need to link your project that uses thrift against all the thrift
-dependancies; in the case of libthrift, boost and for
-libthriftnb, libevent.
-
-In the project properties you must also set HAVE_CONFIG_H as force include
-the config header: "windows/confg.h"
-
-Dependencies
-============
-
-boost shared pointers
-http://www.boost.org/libs/smart_ptr/smart_ptr.htm
-
-boost thread
-http://www.boost.org/doc/libs/release/doc/html/thread.html
-
-libevent (for libthriftnb only)
-http://monkey.org/~provos/libevent/
-
-Notes on boost thread (static vs shared):
-=========================================
-
-By default lib/cpp/windows/force_inc.h defines:
-
-#define BOOST_ALL_NO_LIB 1
-#define BOOST_THREAD_NO_LIB 1
-
-This has for effect to have the host application linking against Thrift
-to have to link with boost thread as a static library.
-
-If you wanted instead to link with boost thread as a shared library,
-you'll need to uncomment those two lines, and recompile.
-
-Windows version compatibility
-=============================
-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
-#define TARGET_WIN_XP.
-
-Named Pipes
-===========
-- Named Pipe transport has been added in the TPipe and TPipeServer classes.
- This is currently Windows-only (see below).
-
-Known issues
-============
-
-- Named pipe transport for *NIX has not been implemented. Domain sockets are
- a better choice for local IPC under non-Windows OS's. *NIX named pipes
- only support 1:1 client-server connection.
-
-TODO
-====
-
-- Port remaining classes in libthrift:
- - TSSLSocket
-
-- Port test cases. (Not even started this. Run test cases in release mode?)
-
-- Autolink libraries depending on debug\release build.
-
-- Auto versioning.