1 # Porting from OpenSSL to BoringSSL 2 3 BoringSSL is an OpenSSL derivative and is mostly source-compatible, for the 4 subset of OpenSSL retained. Libraries ideally need little to no changes for 5 BoringSSL support, provided they do not use removed APIs. In general, see if the 6 library compiles and, on failure, consult the documentation in the header files 7 and see if problematic features can be removed. 8 9 BoringSSL's `OPENSSL_VERSION_NUMBER` matches the OpenSSL version it targets. 10 Version checks for OpenSSL should ideally work as-is in BoringSSL. BoringSSL 11 also defines upstream's `OPENSSL_NO_*` feature macros corresponding to removed 12 features. If the preprocessor is needed, use these version checks or feature 13 macros where possible, especially when patching third-party projects. Such 14 patches are more generally useful to OpenSSL consumers and thus more 15 appropriate to send upstream. 16 17 In some cases, BoringSSL-specific code may be necessary. Use the 18 `OPENSSL_IS_BORINGSSL` preprocessor macro in `#ifdef`s. However, first contact 19 the BoringSSL maintainers about the missing APIs. We will typically add 20 compatibility functions for convenience. In particular, *contact BoringSSL 21 maintainers before working around missing OpenSSL 1.1.0 accessors*. BoringSSL 22 was originally derived from OpenSSL 1.0.2 but now targets OpenSSL 1.1.0. Some 23 newer APIs may be missing but can be added on request. (Not all projects have 24 been ported to OpenSSL 1.1.0, so BoringSSL also remains largely compatible with 25 OpenSSL 1.0.2.) 26 27 The `OPENSSL_IS_BORINGSSL` macro may also be used to distinguish OpenSSL from 28 BoringSSL in configure scripts. Do not use the presence or absence of particular 29 symbols to detect BoringSSL. 30 31 Note: BoringSSL does *not* have a stable API or ABI. It must be updated with its 32 consumers. It is not suitable for, say, a system library in a traditional Linux 33 distribution. For instance, Chromium statically links the specific revision of 34 BoringSSL it was built against. Likewise, Android's system-internal copy of 35 BoringSSL is not exposed by the NDK and must not be used by third-party 36 applications. 37 38 39 ## Major API changes 40 41 ### Integer types 42 43 Some APIs have been converted to use `size_t` for consistency and to avoid 44 integer overflows at the API boundary. (Existing logic uses a mismash of `int`, 45 `long`, and `unsigned`.) For the most part, implicit casts mean that existing 46 code continues to compile. In some cases, this may require BoringSSL-specific 47 code, particularly to avoid compiler warnings. 48 49 Most notably, the `STACK_OF(T)` types have all been converted to use `size_t` 50 instead of `int` for indices and lengths. 51 52 ### Reference counts and opaque types 53 54 Some external consumers increment reference counts directly by calling 55 `CRYPTO_add` with the corresponding `CRYPTO_LOCK_*` value. These APIs no longer 56 exist in BoringSSL. Instead, code which increments reference counts should call 57 the corresponding `FOO_up_ref` function, such as `EVP_PKEY_up_ref`. 58 59 BoringSSL also hides some structs which were previously exposed in OpenSSL 60 1.0.2, particularly in libssl. Use the relevant accessors instead. 61 62 Note that some of these APIs were added in OpenSSL 1.1.0, so projects which do 63 not yet support 1.1.0 may need additional `#ifdef`s. Projects supporting OpenSSL 64 1.1.0 should not require modification. 65 66 ### Error codes 67 68 OpenSSL's errors are extremely specific, leaking internals of the library, 69 including even a function code for the function which emitted the error! As some 70 logic in BoringSSL has been rewritten, code which conditions on the error may 71 break (grep for `ERR_GET_REASON` and `ERR_GET_FUNC`). This danger also exists 72 when upgrading OpenSSL versions. 73 74 Where possible, avoid conditioning on the exact error reason. Otherwise, a 75 BoringSSL `#ifdef` may be necessary. Exactly how best to resolve this issue is 76 still being determined. It's possible some new APIs will be added in the future. 77 78 Function codes have been completely removed. Remove code which conditions on 79 these as it will break with the slightest change in the library, OpenSSL or 80 BoringSSL. 81 82 ### `*_ctrl` functions 83 84 Some OpenSSL APIs are implemented with `ioctl`-style functions such as 85 `SSL_ctrl` and `EVP_PKEY_CTX_ctrl`, combined with convenience macros, such as 86 87 # define SSL_CTX_set_mode(ctx,op) \ 88 SSL_CTX_ctrl((ctx),SSL_CTRL_MODE,(op),NULL) 89 90 In BoringSSL, these macros have been replaced with proper functions. The 91 underlying `_ctrl` functions have been removed. 92 93 For convenience, `SSL_CTRL_*` values are retained as macros to `doesnt_exist` so 94 existing code which uses them (or the wrapper macros) in `#ifdef` expressions 95 will continue to function. However, the macros themselves will not work. 96 97 Switch any `*_ctrl` callers to the macro/function versions. This works in both 98 OpenSSL and BoringSSL. Note that BoringSSL's function versions will be 99 type-checked and may require more care with types. See the end of this 100 document for a table of functions to use. 101 102 ### HMAC `EVP_PKEY`s 103 104 `EVP_PKEY_HMAC` is removed. Use the `HMAC_*` functions in `hmac.h` instead. This 105 is compatible with OpenSSL. 106 107 ### DSA `EVP_PKEY`s 108 109 `EVP_PKEY_DSA` is deprecated. It is currently still possible to parse DER into a 110 DSA `EVP_PKEY`, but signing or verifying with those objects will not work. 111 112 ### DES 113 114 The `DES_cblock` type has been switched from an array to a struct to avoid the 115 pitfalls around array types in C. Where features which require DES cannot be 116 disabled, BoringSSL-specific codepaths may be necessary. 117 118 ### TLS renegotiation 119 120 OpenSSL enables TLS renegotiation by default and accepts renegotiation requests 121 from the peer transparently. Renegotiation is an extremely problematic protocol 122 feature, so BoringSSL rejects peer renegotiations by default. 123 124 To enable renegotiation, call `SSL_set_renegotiate_mode` and set it to 125 `ssl_renegotiate_once` or `ssl_renegotiate_freely`. Renegotiation is only 126 supported as a client in TLS and the HelloRequest must be received at a 127 quiet point in the application protocol. This is sufficient to support the 128 common use of requesting a new client certificate between an HTTP request and 129 response in (unpipelined) HTTP/1.1. 130 131 Things which do not work: 132 133 * There is no support for renegotiation as a server. (Attempts by clients will 134 result in a fatal alert so that ClientHello messages cannot be used to flood 135 a server and escape higher-level limits.) 136 137 * There is no support for renegotiation in DTLS. 138 139 * There is no support for initiating renegotiation; `SSL_renegotiate` always 140 fails and `SSL_set_state` does nothing. 141 142 * Interleaving application data with the new handshake is forbidden. 143 144 * If a HelloRequest is received while `SSL_write` has unsent application data, 145 the renegotiation is rejected. 146 147 * Renegotiation does not participate in session resumption. The client will 148 not offer a session on renegotiation or resume any session established by a 149 renegotiation handshake. 150 151 * The server may not change its certificate in the renegotiation. This mitigates 152 the [triple handshake attack](https://mitls.org/pages/attacks/3SHAKE). Any new 153 stapled OCSP response and SCT list will be ignored. As no authentication state 154 may change, BoringSSL will not re-verify the certificate on a renegotiation. 155 Callbacks such as `SSL_CTX_set_custom_verify` will only run on the initial 156 handshake. 157 158 ### Lowercase hexadecimal 159 160 BoringSSL's `BN_bn2hex` function uses lowercase hexadecimal digits instead of 161 uppercase. Some code may require changes to avoid being sensitive to this 162 difference. 163 164 ### Legacy ASN.1 functions 165 166 OpenSSL's ASN.1 stack uses `d2i` functions for parsing. They have the form: 167 168 RSA *d2i_RSAPrivateKey(RSA **out, const uint8_t **inp, long len); 169 170 In addition to returning the result, OpenSSL places it in `*out` if `out` is 171 not `NULL`. On input, if `*out` is not `NULL`, OpenSSL will usually (but not 172 always) reuse that object rather than allocating a new one. In BoringSSL, these 173 functions are compatibility wrappers over a newer ASN.1 stack. Even if `*out` 174 is not `NULL`, these wrappers will always allocate a new object and free the 175 previous one. 176 177 Ensure that callers do not rely on this object reuse behavior. It is 178 recommended to avoid the `out` parameter completely and always pass in `NULL`. 179 Note that less error-prone APIs are available for BoringSSL-specific code (see 180 below). 181 182 ### Memory allocation 183 184 OpenSSL provides wrappers `OPENSSL_malloc` and `OPENSSL_free` over the standard 185 `malloc` and `free`. Memory allocated by OpenSSL should be released with 186 `OPENSSL_free`, not the standard `free`. However, by default, they are 187 implemented directly using `malloc` and `free`, so code which mixes them up 188 usually works. 189 190 In BoringSSL, these functions maintain additional book-keeping to zero memory 191 on `OPENSSL_free`, so any mixups must be fixed. 192 193 ## Optional BoringSSL-specific simplifications 194 195 BoringSSL makes some changes to OpenSSL which simplify the API but remain 196 compatible with OpenSSL consumers. In general, consult the BoringSSL 197 documentation for any functions in new BoringSSL-only code. 198 199 ### Return values 200 201 Most OpenSSL APIs return 1 on success and either 0 or -1 on failure. BoringSSL 202 has narrowed most of these to 1 on success and 0 on failure. BoringSSL-specific 203 code may take advantage of the less error-prone APIs and use `!` to check for 204 errors. 205 206 ### Initialization 207 208 OpenSSL has a number of different initialization functions for setting up error 209 strings and loading algorithms, etc. All of these functions still exist in 210 BoringSSL for convenience, but they do nothing and are not necessary. 211 212 The one exception is `CRYPTO_library_init`. In `BORINGSSL_NO_STATIC_INITIALIZER` 213 builds, it must be called to query CPU capabilities before the rest of the 214 library. In the default configuration, this is done with a static initializer 215 and is also unnecessary. 216 217 ### Threading 218 219 OpenSSL provides a number of APIs to configure threading callbacks and set up 220 locks. Without initializing these, the library is not thread-safe. Configuring 221 these does nothing in BoringSSL. Instead, BoringSSL calls pthreads and the 222 corresponding Windows APIs internally and is always thread-safe where the API 223 guarantees it. 224 225 ### ASN.1 226 227 BoringSSL is in the process of deprecating OpenSSL's `d2i` and `i2d` in favor of 228 new functions using the much less error-prone `CBS` and `CBB` types. 229 BoringSSL-only code should use those functions where available. 230 231 232 ## Replacements for `CTRL` values 233 234 When porting code which uses `SSL_CTX_ctrl` or `SSL_ctrl`, use the replacement 235 functions below. If a function has both `SSL_CTX` and `SSL` variants, only the 236 `SSL_CTX` version is listed. 237 238 Note some values correspond to multiple functions depending on the `larg` 239 parameter. 240 241 `CTRL` value | Replacement function(s) 242 -------------|------------------------- 243 `DTLS_CTRL_GET_TIMEOUT` | `DTLSv1_get_timeout` 244 `DTLS_CTRL_HANDLE_TIMEOUT` | `DTLSv1_handle_timeout` 245 `SSL_CTRL_CHAIN` | `SSL_CTX_set0_chain` or `SSL_CTX_set1_chain` 246 `SSL_CTRL_CHAIN_CERT` | `SSL_add0_chain_cert` or `SSL_add1_chain_cert` 247 `SSL_CTRL_CLEAR_EXTRA_CHAIN_CERTS` | `SSL_CTX_clear_extra_chain_certs` 248 `SSL_CTRL_CLEAR_MODE` | `SSL_CTX_clear_mode` 249 `SSL_CTRL_CLEAR_OPTIONS` | `SSL_CTX_clear_options` 250 `SSL_CTRL_EXTRA_CHAIN_CERT` | `SSL_CTX_add_extra_chain_cert` 251 `SSL_CTRL_GET_CHAIN_CERTS` | `SSL_CTX_get0_chain_certs` 252 `SSL_CTRL_GET_CLIENT_CERT_TYPES` | `SSL_get0_certificate_types` 253 `SSL_CTRL_GET_EXTRA_CHAIN_CERTS` | `SSL_CTX_get_extra_chain_certs` or `SSL_CTX_get_extra_chain_certs_only` 254 `SSL_CTRL_GET_MAX_CERT_LIST` | `SSL_CTX_get_max_cert_list` 255 `SSL_CTRL_GET_NUM_RENEGOTIATIONS` | `SSL_num_renegotiations` 256 `SSL_CTRL_GET_READ_AHEAD` | `SSL_CTX_get_read_ahead` 257 `SSL_CTRL_GET_RI_SUPPORT` | `SSL_get_secure_renegotiation_support` 258 `SSL_CTRL_GET_SESSION_REUSED` | `SSL_session_reused` 259 `SSL_CTRL_GET_SESS_CACHE_MODE` | `SSL_CTX_get_session_cache_mode` 260 `SSL_CTRL_GET_SESS_CACHE_SIZE` | `SSL_CTX_sess_get_cache_size` 261 `SSL_CTRL_GET_TLSEXT_TICKET_KEYS` | `SSL_CTX_get_tlsext_ticket_keys` 262 `SSL_CTRL_GET_TOTAL_RENEGOTIATIONS` | `SSL_total_renegotiations` 263 `SSL_CTRL_MODE` | `SSL_CTX_get_mode` or `SSL_CTX_set_mode` 264 `SSL_CTRL_NEED_TMP_RSA` | `SSL_CTX_need_tmp_RSA` is equivalent, but [*do not use this function*](https://freakattack.com/). (It is a no-op in BoringSSL.) 265 `SSL_CTRL_OPTIONS` | `SSL_CTX_get_options` or `SSL_CTX_set_options` 266 `SSL_CTRL_SESS_NUMBER` | `SSL_CTX_sess_number` 267 `SSL_CTRL_SET_CURVES` | `SSL_CTX_set1_curves` 268 `SSL_CTRL_SET_ECDH_AUTO` | `SSL_CTX_set_ecdh_auto` 269 `SSL_CTRL_SET_MAX_CERT_LIST` | `SSL_CTX_set_max_cert_list` 270 `SSL_CTRL_SET_MAX_SEND_FRAGMENT` | `SSL_CTX_set_max_send_fragment` 271 `SSL_CTRL_SET_MSG_CALLBACK` | `SSL_set_msg_callback` 272 `SSL_CTRL_SET_MSG_CALLBACK_ARG` | `SSL_set_msg_callback_arg` 273 `SSL_CTRL_SET_MTU` | `SSL_set_mtu` 274 `SSL_CTRL_SET_READ_AHEAD` | `SSL_CTX_set_read_ahead` 275 `SSL_CTRL_SET_SESS_CACHE_MODE` | `SSL_CTX_set_session_cache_mode` 276 `SSL_CTRL_SET_SESS_CACHE_SIZE` | `SSL_CTX_sess_set_cache_size` 277 `SSL_CTRL_SET_TLSEXT_HOSTNAME` | `SSL_set_tlsext_host_name` 278 `SSL_CTRL_SET_TLSEXT_SERVERNAME_ARG` | `SSL_CTX_set_tlsext_servername_arg` 279 `SSL_CTRL_SET_TLSEXT_SERVERNAME_CB` | `SSL_CTX_set_tlsext_servername_callback` 280 `SSL_CTRL_SET_TLSEXT_TICKET_KEYS` | `SSL_CTX_set_tlsext_ticket_keys` 281 `SSL_CTRL_SET_TLSEXT_TICKET_KEY_CB` | `SSL_CTX_set_tlsext_ticket_key_cb` 282 `SSL_CTRL_SET_TMP_DH` | `SSL_CTX_set_tmp_dh` 283 `SSL_CTRL_SET_TMP_DH_CB` | `SSL_CTX_set_tmp_dh_callback` 284 `SSL_CTRL_SET_TMP_ECDH` | `SSL_CTX_set_tmp_ecdh` 285 `SSL_CTRL_SET_TMP_ECDH_CB` | `SSL_CTX_set_tmp_ecdh_callback` 286 `SSL_CTRL_SET_TMP_RSA` | `SSL_CTX_set_tmp_rsa` is equivalent, but [*do not use this function*](https://freakattack.com/). (It is a no-op in BoringSSL.) 287 `SSL_CTRL_SET_TMP_RSA_CB` | `SSL_CTX_set_tmp_rsa_callback` is equivalent, but [*do not use this function*](https://freakattack.com/). (It is a no-op in BoringSSL.) 288 289 ## Significant API additions 290 291 In some places, BoringSSL has added significant APIs. Use of these APIs goes beyound porting and means giving up on OpenSSL compatibility. 292 293 One example of this has already been mentioned: the [CBS and CBB](https://commondatastorage.googleapis.com/chromium-boringssl-docs/bytestring.h.html) functions should be used whenever parsing or serialising data. 294 295 ### CRYPTO\_BUFFER 296 297 With the standard OpenSSL APIs, when making many TLS connections, the certificate data for each connection is retained in memory in an expensive `X509` structure. Additionally, common certificates often appear in the chains for multiple connections and are needlessly duplicated in memory. 298 299 A [`CRYPTO_BUFFER`](https://commondatastorage.googleapis.com/chromium-boringssl-docs/pool.h.html) is just an opaque byte string. A `CRYPTO_BUFFER_POOL` is an intern table for these buffers, i.e. it ensures that only a single copy of any given byte string is kept for each pool. 300 301 The function `TLS_with_buffers_method` returns an `SSL_METHOD` that avoids creating `X509` objects for certificates. Additionally, `SSL_CTX_set0_buffer_pool` can be used to install a pool on an `SSL_CTX` so that certificates can be deduplicated across connections and across `SSL_CTX`s. 302 303 When using these functions, the application also needs to ensure that it doesn't call other functions that deal with `X509` or `X509_NAME` objects. For example, `SSL_get_peer_certificate` or `SSL_get_peer_cert_chain`. Doing so will trigger an assert in debug mode and will result in NULLs in release mode. Instead, call the buffer-based alternatives such as `SSL_get0_peer_certificates`. (See [ssl.h](https://commondatastorage.googleapis.com/chromium-boringssl-docs/ssl.h.html) for functions taking or returning `CRYPTO_BUFFER`.) The buffer-based alternative functions will work even when not using `TLS_with_buffers_method`, thus application code can transition gradually. 304 305 In order to use buffers, the application code also needs to implement its own certificate verification using `SSL_[CTX_]set_custom_verify`. Otherwise all connections will fail with a verification error. Auto-chaining is also disabled when using buffers. 306 307 Once those changes have been completed, the whole of the OpenSSL X.509 and ASN.1 code should be eliminated by the linker if BoringSSL is linked statically. 308 309 ### Asynchronous and opaque private keys 310 311 OpenSSL offers the ENGINE API for implementing opaque private keys (i.e. private keys where software only has oracle access because the secrets are held in special hardware or on another machine). While the ENGINE API has been mostly removed from BoringSSL, it is still possible to support opaque keys in this way. However, when using such keys with TLS and BoringSSL, you should strongly prefer using `SSL_PRIVATE_KEY_METHOD` via `SSL[_CTX]_set_private_key_method`. This allows a handshake to be suspended while the private operation is in progress. It also supports more forms of opaque key as it exposes higher-level information about the operation to be performed. 312
