From: Roger Meier Date: Sun, 4 May 2014 20:21:58 +0000 (+0200) Subject: THRIFT-2512 lib/${language}/README.md X-Git-Url: https://source.supwisdom.com/gerrit/gitweb?a=commitdiff_plain;h=6370cfdd7a84fbece58fd1bf6547570d3c8880db;p=common%2Fthrift.git 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 a928057d..00000000 --- a/lib/cpp/README.SSL.md +++ /dev/null @@ -1,135 +0,0 @@ -Notes on Thrift/SSL - -Author: Ping Li - -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 getSSLSocketFactory() { - shared_ptr 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(new MyAccessManager); - // factory->access(accessManager); - ... - } - - // client code sample - shared_ptr factory = getSSLSocketFactory(); - shared_ptr socket = factory.createSocket(host, port); - shared_ptr transport(new TBufferedTransport(socket)); - ... - - // server code sample - shared_ptr factory = getSSLSocketFactory(); - shared_ptr socket(new TSSLServerSocket(port, factory)); - shared_ptr 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 " 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 576d0170..e57fdd44 --- 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 @@ KIND, either express or implied. See the License for the 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.md file, do this thrift src: -In case you do not want to open another README file, do this: - ./bootstrap.sh - ./configure (--with-boost=/usr/local) - make - sudo make install + ./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 @@ 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. -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 getSSLSocketFactory() { + shared_ptr 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(new MyAccessManager); + // factory->access(accessManager); + ... + } + + + // client code sample + shared_ptr factory = getSSLSocketFactory(); + shared_ptr socket = factory.createSocket(host, port); + shared_ptr transport(new TBufferedTransport(socket)); + ... + + + // server code sample + shared_ptr factory = getSSLSocketFactory(); + shared_ptr socket(new TSSLServerSocket(port, factory)); + shared_ptr 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 " 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 f4c887ce..00000000 --- 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.