1 /* 2 * matrixsslConfig.h 3 * Release $Name: MATRIXSSL-3-3-0-OPEN $ 4 * 5 * Configuration settings for building the MatrixSSL library. 6 */ 7 /* 8 * Copyright (c) AuthenTec, Inc. 2011-2012 9 * Copyright (c) PeerSec Networks, 2002-2011 10 * All Rights Reserved 11 * 12 * The latest version of this code is available at http://www.matrixssl.org 13 * 14 * This software is open source; you can redistribute it and/or modify 15 * it under the terms of the GNU General Public License as published by 16 * the Free Software Foundation; either version 2 of the License, or 17 * (at your option) any later version. 18 * 19 * This General Public License does NOT permit incorporating this software 20 * into proprietary programs. If you are unable to comply with the GPL, a 21 * commercial license for this software may be purchased from AuthenTec at 22 * http://www.authentec.com/Products/EmbeddedSecurity/SecurityToolkits.aspx 23 * 24 * This program is distributed in WITHOUT ANY WARRANTY; without even the 25 * implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. 26 * See the GNU General Public License for more details. 27 * 28 * You should have received a copy of the GNU General Public License 29 * along with this program; if not, write to the Free Software 30 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 31 * http://www.gnu.org/copyleft/gpl.html 32 */ 33 /******************************************************************************/ 34 35 #ifndef _h_MATRIXSSLCONFIG 36 #define _h_MATRIXSSLCONFIG 37 38 39 #ifdef __cplusplus 40 extern "C" { 41 #endif 42 43 /******************************************************************************/ 44 /* 45 Recommended cipher suites: 46 47 Define the following to enable various cipher suites 48 At least one of these must be defined. If multiple are defined, 49 the handshake will determine which is best for the connection. 50 */ 51 #define USE_TLS_RSA_WITH_AES_128_CBC_SHA 52 #define USE_TLS_RSA_WITH_AES_256_CBC_SHA 53 /* #define USE_SSL_RSA_WITH_3DES_EDE_CBC_SHA */ 54 /* #define USE_SSL_RSA_WITH_RC4_128_SHA */ 55 /* #define USE_SSL_RSA_WITH_RC4_128_MD5 */ 56 57 /******************************************************************************/ 58 /* 59 These cipher suites do not combine authentication and encryption and 60 are not recommended for use-cases that require strong security 61 */ 62 /* #define USE_SSL_RSA_WITH_NULL_SHA */ 63 /* #define USE_SSL_RSA_WITH_NULL_MD5 */ 64 65 /******************************************************************************/ 66 /* 67 Support for TLS protocols. 68 69 - SSLv3 is always on unless disabled below 70 - TLS versions must 'stack' 71 - must enable TLS if enabling TLS 1.1 72 - must enable TLS 1.1 if enabling TLS 1.2 73 */ 74 #define USE_TLS /* TLS 1.0 aka SSL 3.1 */ 75 #define USE_TLS_1_1 76 77 /* #define DISABLE_SSLV3 */ /* Disable SSL 3.0 */ 78 79 80 /******************************************************************************/ 81 /* 82 Compile time support for server or client side SSL 83 */ 84 #define USE_CLIENT_SIDE_SSL 85 #define USE_SERVER_SIDE_SSL 86 87 88 89 /******************************************************************************/ 90 /* 91 The initial buffer sizes for send and receive buffers in each ssl_t session. 92 Buffers are internally grown if more incoming or outgoing data storage is 93 needed, up to a maximum of SSL_MAX_BUF_SIZE. Once the memory used by the 94 buffer again drops below SSL_DEFAULT_X_BUF_SIZE, the buffer will be reduced 95 to this size. Most standard SSL handshakes require on the order of 1024 B. 96 97 SSL_DEFAULT_X_BUF_SIZE value in bytes, maximum SSL_MAX_BUF_SIZE 98 */ 99 #define SSL_DEFAULT_IN_BUF_SIZE 1500 /* Baseline recv buf size */ 100 #define SSL_DEFAULT_OUT_BUF_SIZE 1500 /* Baseline send buf size */ 101 102 /******************************************************************************/ 103 /* 104 If SERVER you may define the number of sessions to cache and how 105 long a session will remain valid in the cache from first access. 106 107 Session caching enables very fast "session resumption handshakes". Session 108 caching can effectively by disabled by setting SSL_SESSION_ENTRY_LIFE to 0 109 110 SSL_SESSION_TABLE_SIZE minimum value is 1 111 SSL_SESSION_ENTRY_LIFE is in milliseconds, minimum 0 112 113 */ 114 #define SSL_SESSION_TABLE_SIZE 32 115 #define SSL_SESSION_ENTRY_LIFE 86400 * 1000 /* one day */ 116 117 118 119 /******************************************************************************/ 120 /* 121 REHANDSHAKING SUPPORT 122 In late 2009 An "authentication gap" exploit was discovered in the 123 SSL re-handshaking protocol. The fix to the exploit was introduced 124 in RFC 5746 and is referred to here as SECURE_REHANDSHAKES. 125 126 ENABLE_SECURE_REHANDSHAKES implements RFC 5746 and will securely 127 renegotiate with any implementations that support it. It is 128 recommended to leave this enabled. 129 130 By enabling REQUIRE_SECURE_REHANDSHAKES, the library will test that each 131 communicating peer has implemented RFC 5746 and will terminate handshakes 132 with any that have not. 133 134 If working with SSL peers that have not implemented RFC 5746 and 135 rehandshakes are required, you may enable ENABLE_INSECURE_REHANDSHAKES 136 but it is NOT RECOMMENDED 137 138 It is a conflict to enable both ENABLE_INSECURE_REHANDSHAKES and 139 REQUIRE_SECURE_REHANDSHAKES and a compile error will occur 140 141 To completely disable rehandshaking comment out all three of these defines 142 */ 143 #define ENABLE_SECURE_REHANDSHAKES 144 /* #define REQUIRE_SECURE_REHANDSHAKES */ 145 /* #define ENABLE_INSECURE_REHANDSHAKES */ /* NOT RECOMMENDED */ 146 147 /******************************************************************************/ 148 /* 149 Google has an implementation of HTTPS client (Chrome) that sends application 150 data immedately after the client FINISHED message, and before the server 151 has responded with a CHANGE_CIPHER_SPEC and FINISHED message. This saves 152 a round trip when sending the HTTP request, since it is sent with the 153 FINISHED message in a single IP packet, and does not wait for the server 154 handshake response. 155 156 A similar technique is used and supported by MatrixSSL for including 157 application data at the end of a finished message that does not require 158 a response (a standard server Finished message for example). However, 159 this implementation in Chrome is subtly and importantly different. 160 161 MatrixSSL was written to explicitly ignore any data after any handshake 162 message that requires a response, because in all cases, this response 163 changes the state of the client. 164 165 Chrome cannot be assured that the final handshake hash matches (and that 166 the handshake was not tampered with) before it sends the potentially 167 sensitive HTTP request. 168 169 Apparently most other SSL implementations do allow this "trick" to 170 succeed, and so we have added support as well using a conditional compile. 171 Enabling this allows Chrome browsers to connect to HTTPS servers running 172 MatrixSSL. Sending app data with a client finished message from MatrixSSL 173 is still NOT SUPPORTED for the security reasons above. 174 175 For more information: 176 http://tools.ietf.org/html/draft-bmoeller-tls-falsestart-00 177 */ 178 #define ENABLE_FALSE_START 179 180 /******************************************************************************/ 181 /* 182 In Sept. 2011 security researchers demonstrated how a previously known 183 CBC encryption weakness could be used to decrypt HTTP data over SSL. 184 The attack was named BEAST (Browser Exploit Against SSL/TLS). 185 186 This issue only effects TLS 1.0 (and SSL) and only if the cipher suite 187 is using a symmetric CBC block cipher. Enable USE_TLS_1_1 above to 188 completely negate this workaround if TLS 1.1 is also supported by peers. 189 190 As with previous SSL vulnerabilities, the attack is generally considered 191 a very low risk for individual browsers as it requires the attacker 192 to have control over the network to become a MITM. They will also have 193 to have knowledge of the first couple blocks of underlying plaintext 194 in order to mount the attack. 195 196 A zero length record proceeding a data record has been a known fix to this 197 problem for years and MatrixSSL has always supported the handling of empty 198 records. So alternatively, an implementation could always encode a zero 199 length record before each record encode. Some old SSL implementations do 200 not handle decoding zero length records, however. 201 202 This BEAST fix is on the client side and moves the implementation down to 203 the SSL library level so users do not need to manually send zero length 204 records. This fix uses the same IV obfuscation logic as a zero length 205 record by breaking up each application data record in two. Because some 206 implementations don't handle zero-length records, the the first record 207 is the first byte of the plaintext message, and the second record 208 contains the remainder of the message. 209 210 This fix is based on the workaround implemented in Google Chrome: 211 http://src.chromium.org/viewvc/chrome?view=rev&revision=97269 212 213 This workaround adds approximagely 53 bytes to the encoded length of each 214 SSL record that is encoded, due to the additional header, padding and MAC 215 of the second record. 216 */ 217 #define USE_BEAST_WORKAROUND 218 219 /******************************************************************************/ 220 /* 221 Enable certificate chain message "stream" parsing. This allows single 222 certificates to be parsed on-the-fly without having to wait for the entire 223 certificate chain to be recieved in the buffer. This is a memory saving 224 feature for the application buffer but will add a small amount of code 225 size for the parsing and structure overhead. 226 227 This feature will only save memory if the CERTIFICATE message is the 228 only message in the record, and multiple certs are present in the chain. 229 */ 230 /* #define USE_CERT_CHAIN_PARSING */ 231 232 /******************************************************************************/ 233 /* 234 Show which SSL messages are created and parsed 235 */ 236 /* #define USE_SSL_HANDSHAKE_MSG_TRACE */ 237 238 /******************************************************************************/ 239 /* 240 Informational trace that could help pinpoint problems with SSL connections 241 */ 242 /* #define USE_SSL_INFORMATIONAL_TRACE */ 243 244 /******************************************************************************/ 245 #ifdef __cplusplus 246 } 247 #endif 248 249 #endif /* _h_MATRIXCONFIG */ 250 /******************************************************************************/ 251 252