]>
Commit | Line | Data |
---|---|---|
f67539c2 TL |
1 | Thrift C++ Software Library |
2 | ||
3 | # License | |
4 | ||
5 | Licensed to the Apache Software Foundation (ASF) under one | |
6 | or more contributor license agreements. See the NOTICE file | |
7 | distributed with this work for additional information | |
8 | regarding copyright ownership. The ASF licenses this file | |
9 | to you under the Apache License, Version 2.0 (the | |
10 | "License"); you may not use this file except in compliance | |
11 | with the License. You may obtain a copy of the License at | |
12 | ||
13 | http://www.apache.org/licenses/LICENSE-2.0 | |
14 | ||
15 | Unless required by applicable law or agreed to in writing, | |
16 | software distributed under the License is distributed on an | |
17 | "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY | |
18 | KIND, either express or implied. See the License for the | |
19 | specific language governing permissions and limitations | |
20 | under the License. | |
21 | ||
22 | # Using Thrift with C++ | |
23 | ||
24 | The Thrift C++ libraries are built using the GNU tools. Follow the instructions | |
25 | in the top-level README.md | |
26 | ||
27 | In case you do not want to open another README.md file, do this thrift src: | |
28 | ||
29 | ./bootstrap.sh | |
30 | ./configure (--with-boost=/usr/local) | |
31 | make | |
32 | sudo make install | |
33 | ||
34 | Thrift is divided into two libraries. | |
35 | ||
36 | * libthrift - The core Thrift library contains all the core Thrift code. This requires | |
37 | openssl, pthreads, and librt. | |
38 | ||
39 | * libthriftnb - This library contains the Thrift nonblocking server, which uses libevent. | |
40 | To link this library you will also need to link libevent. | |
41 | ||
42 | ## Linking Against Thrift | |
43 | ||
44 | After you build and install Thrift the libraries are installed to | |
45 | /usr/local/lib by default. Make sure this is in your LDPATH. | |
46 | ||
47 | On Linux, the best way to do this is to ensure that /usr/local/lib is in | |
48 | your /etc/ld.so.conf and then run /sbin/ldconfig. | |
49 | ||
50 | Depending upon whether you are linking dynamically or statically and how | |
51 | your build environment it set up, you may need to include additional | |
52 | libraries when linking against thrift, such as librt and/or libpthread. If | |
53 | you are using libthriftnb you will also need libevent. | |
54 | ||
55 | ## Dependencies | |
56 | ||
57 | C++11 is required at a minimum. C++03/C++98 are not supported after version 0.12.0. | |
58 | ||
59 | Boost is required to run the C++ unit tests. It is not necessary to link against | |
60 | the runtime library. | |
61 | ||
62 | libevent (for libthriftnb only) - most linux distributions have dev packages for this: | |
63 | http://monkey.org/~provos/libevent/ | |
64 | ||
65 | # Using Thrift with C++ on Windows | |
66 | ||
67 | Both the autoconf and cmake build systems are able to automatically detect many | |
68 | system configurations without the need to specify library locations, however if | |
69 | you run into problems or want to redirect thrift to build and link against your | |
70 | own provided third party libraries: | |
71 | ||
72 | BOOST_ROOT : For boost, e.g. D:\boost_1_55_0 | |
73 | OPENSSL_ROOT_DIR : For OpenSSL, e.g. D:\OpenSSL-Win32 | |
74 | ||
75 | only required by libthriftnb: | |
76 | ||
77 | LIBEVENT_ROOT_DIR : For Libevent e.g. D:\libevent-2.0.21-stable | |
78 | ||
79 | See /3rdparty.user for more details. | |
80 | ||
81 | The same linking guidelines described above for libthriftnb apply to windows as well. | |
82 | ||
83 | ## Linking Against Thrift | |
84 | ||
85 | You need to link your project that uses thrift against all the thrift | |
86 | dependencies; in the case of libthrift, openssl, pthreads, and librt and for | |
87 | libthriftnb, libevent. | |
88 | ||
89 | In the project properties you must also set HAVE_CONFIG_H as force include | |
90 | the config header: "windows/config.h" | |
91 | ||
92 | ## Dependencies | |
93 | ||
94 | libevent (for libthriftnb only) | |
95 | http://monkey.org/~provos/libevent/ | |
96 | ||
97 | ## Windows version compatibility | |
98 | ||
99 | The Thrift library targets Windows 7 or latter versions. The supports for windows XP and Vista are avaiable until 0.12.0. | |
100 | ||
101 | ## Named Pipes | |
102 | ||
103 | Named Pipe transport has been added in the TPipe and TPipeServer classes. This | |
104 | is currently Windows-only. Named pipe transport for *NIX has not been | |
105 | implemented. Domain sockets are a better choice for local IPC under non-Windows | |
106 | OS's. *NIX named pipes only support 1:1 client-server connection. | |
107 | ||
108 | # Thrift/SSL | |
109 | ||
110 | ## Scope | |
111 | ||
112 | This SSL only supports blocking mode socket I/O. It can only be used with | |
113 | TSimpleServer, TThreadedServer, and TThreadPoolServer. | |
114 | ||
115 | ## Implementation | |
116 | ||
117 | There are two main classes TSSLSocketFactory and TSSLSocket. Instances of | |
118 | TSSLSocket are always created from TSSLSocketFactory. | |
119 | ||
120 | ## How to use SSL APIs | |
121 | ||
122 | See the TestClient.cpp and TestServer.cpp files for examples. | |
123 | ||
124 | ### AccessManager (certificate validation) | |
125 | ||
126 | An example of certificate validation can be found in TestServer.cpp. | |
127 | ||
128 | AccessManager defines a callback interface. It has three callback methods: | |
129 | ||
130 | (a) Decision verify(const sockaddr_storage& sa); | |
131 | ||
132 | (b) Decision verify(const string& host, const char* name, int size); | |
133 | ||
134 | (c) Decision verify(const sockaddr_storage& sa, const char* data, int size); | |
135 | ||
136 | After SSL handshake completes, additional checks are conducted. Application | |
137 | is given the chance to decide whether or not to continue the conversation | |
138 | with the remote. Application is queried through the above three "verify" | |
139 | method. They are called at different points of the verification process. | |
140 | ||
141 | Decisions can be one of ALLOW, DENY, and SKIP. ALLOW and DENY means the | |
142 | conversation should be continued or disconnected, respectively. ALLOW and | |
143 | DENY decision stops the verification process. SKIP means there's no decision | |
144 | based on the given input, continue the verification process. | |
145 | ||
146 | First, (a) is called with the remote IP. It is called once at the beginning. | |
147 | "sa" is the IP address of the remote peer. | |
148 | ||
149 | Then, the certificate of remote peer is loaded. SubjectAltName extensions | |
150 | are extracted and sent to application for verification. When a DNS | |
151 | subjectAltName field is extracted, (b) is called. When an IP subjectAltName | |
152 | field is extracted, (c) is called. | |
153 | ||
154 | The "host" in (b) is the value from TSocket::getHost() if this is a client | |
155 | side socket, or TSocket::getPeerHost() if this is a server side socket. The | |
156 | reason is client side socket initiates the connection. TSocket::getHost() | |
157 | is the remote host name. On server side, the remote host name is unknown | |
158 | unless it's retrieved through TSocket::getPeerHost(). Either way, "host" | |
159 | should be the remote host name. Keep in mind, if TSocket::getPeerHost() | |
160 | failed, it would return the remote host name in numeric format. | |
161 | ||
162 | If all subjectAltName extensions were "skipped", the common name field would | |
163 | be checked. It is sent to application through (c), where "sa" is the remote | |
164 | IP address. "data" is the IP address extracted from subjectAltName IP | |
165 | extension, and "size" is the length of the extension data. | |
166 | ||
167 | If any of the above "verify" methods returned a decision ALLOW or DENY, the | |
168 | verification process would be stopped. | |
169 | ||
170 | If any of the above "verify" methods returned SKIP, that decision would be | |
171 | ignored and the verification process would move on till the last item is | |
172 | examined. At that point, if there's still no decision, the connection is | |
173 | terminated. | |
174 | ||
175 | Thread safety, an access manager should not store state information if it's | |
176 | to be used by many SSL sockets. | |
177 | ||
178 | ## SIGPIPE signal | |
179 | ||
180 | Applications running OpenSSL over network connections may crash if SIGPIPE | |
181 | is not ignored. This happens when they receive a connection reset by remote | |
182 | peer exception, which somehow triggers a SIGPIPE signal. If not handled, | |
183 | this signal would kill the application. | |
184 | ||
185 | ## How to run test client/server in SSL mode | |
186 | ||
187 | The server and client expects the followings from the directory /test/ | |
188 | ||
189 | - keys/server.crt | |
190 | - keys/server.key | |
191 | - keys/CA.pem | |
192 | ||
193 | The file names are hard coded in the source code. You need to create these | |
194 | certificates before you can run the test code in SSL mode. Make sure at least | |
195 | one of the followings is included in "keys/server.crt", | |
196 | ||
197 | - subjectAltName, DNS localhost | |
198 | - subjectAltName, IP 127.0.0.1 | |
199 | - common name, localhost | |
200 | ||
201 | Run within /test/ folder, | |
202 | ||
203 | ./cpp/TestServer --ssl & | |
204 | ./cpp/TestClient --ssl | |
205 | ||
206 | If "-h <host>" is used to run client, the above "localhost" in the above | |
207 | keys/server.crt has to be replaced with that host name. | |
208 | ||
209 | ## TSSLSocketFactory::randomize() | |
210 | ||
211 | The default implementation of OpenSSLSocketFactory::randomize() simply calls | |
212 | OpenSSL's RAND_poll() when OpenSSL library is first initialized. | |
213 | ||
214 | The PRNG seed is key to the application security. This method should be | |
215 | overridden if it's not strong enough for you. | |
216 | ||
217 | # Deprecations | |
218 | ||
219 | ## 0.12.0 | |
220 | ||
221 | Support for C++03/C++98 was deprecated. | |
222 | Support for Boost at runtime was deprecated. | |
223 | ||
224 | # Breaking Changes | |
225 | ||
226 | ## 1.0.0 | |
227 | ||
228 | THRIFT-4720: | |
229 | The classes Monitor and TimerManager now use std::chrono::milliseconds for timeout, the methods and functions involving THRIFT_TIMESPEC and timeval have been removed, the related tests have been modified. | |
230 | ||
231 | Support for Windows XP/Vista has been dropped. | |
232 | ||
233 | Support for C++03/C++98 has been dropped. Use version 0.12.0 to support that | |
234 | language level. As a consequence, boost is no longer required as a runtime | |
235 | library depenedency, but is is still required to build the runtime library | |
236 | and to run the unit tests. We will work towards removing boost as a | |
237 | build dependency for folks who just want to build the runtime and not | |
238 | run the tests. This means the header thrift/stdcxx.h has been removed and | |
239 | anything that relied on it has been changed to directly use C++11 concepts. | |
240 | ||
241 | THRIFT-4730: | |
242 | The classes BoostThreadFactory, PosixThreadFactory, StdThreadFactory, and | |
243 | PlatformThreadFactory have been removed, and we will use a ThreadFactory | |
244 | based on C++11 (essentially StdThreadFactory was renamed ThreadFactory). | |
245 | ||
246 | THRIFT-4732: | |
247 | The CMake build options WITH_SHARED_LIBS and WITH_STATIC_LIBS are deprecated. | |
248 | The project no longer performs a side-by-side static and shared build; you | |
249 | tell CMake through BUILD_SHARED_LIBS whether to make shared or static | |
250 | libraries now. This is CMake standard behavior. | |
251 | ||
252 | THRIFT-4735: | |
253 | Qt4 support was removed. | |
254 | ||
255 | THRIFT-4762: | |
256 | Added `const` specifier to `TTransport::getOrigin()`. This changes its function signature. | |
257 | It's recommended to add the `override` specifier in implementations derived from `TTransport`. | |
258 | ||
259 | ## 0.11.0 | |
260 | ||
261 | Older versions of thrift depended on the <boost/smart_ptr.hpp> classes which | |
262 | were used in thrift headers to define interfaces. Thrift now detects C++11 | |
263 | at build time and will prefer to use <memory> classes from C++11 instead. | |
264 | You can force the library to build with boost memory classes by defining the | |
265 | preprocessor macro `FORCE_BOOST_SMART_PTR`. (THRIFT-2221) | |
266 | ||
267 | In the pthread mutex implementation, the contention profiling code was enabled | |
268 | by default in all builds. This changed to be disabled by default. (THRIFT-4151) | |
269 | ||
270 | In older releases, if a TSSLSocketFactory's lifetime was not at least as long | |
271 | as the TSSLSockets it created, we silently reverted openssl to unsafe multithread behavior | |
272 | and so the results were undefined. Changes were made in 0.11.0 that cause either an | |
273 | assertion or a core instead of undefined behavior. The lifetime of a TSSLSocketFactory | |
274 | *must* be longer than any TSSLSocket that it creates, otherwise openssl will be cleaned | |
275 | up too early. If the static boolean is set to disable openssl initialization and | |
276 | cleanup and leave it up to the consuming application, this requirement is not needed. | |
277 | (THRIFT-4164) | |
278 |