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 In some cases, BoringSSL-specific code may be necessary. In that case, the 10 `OPENSSL_IS_BORINGSSL` preprocessor macro may be used in `#ifdef`s. This macro 11 should also be used in lieu of the presence of any particular function to detect 12 OpenSSL vs BoringSSL in configure scripts, etc., where those are necessary. 13 Before using the preprocessor, however, contact the BoringSSL maintainers about 14 the missing APIs. If not an intentionally removed feature, BoringSSL will 15 typically add compatibility functions for convenience. 16 17 For convenience, BoringSSL defines upstream's `OPENSSL_NO_*` feature macros 18 corresponding to removed features. These may also be used to disable code which 19 uses a removed feature. 20 21 Note: BoringSSL does *not* have a stable API or ABI. It must be updated with its 22 consumers. It is not suitable for, say, a system library in a traditional Linux 23 distribution. For instance, Chromium statically links the specific revision of 24 BoringSSL it was built against. Likewise, Android's system-internal copy of 25 BoringSSL is not exposed by the NDK and must not be used by third-party 26 applications. 27 28 29 ## Major API changes 30 31 ### Integer types 32 33 Some APIs have been converted to use `size_t` for consistency and to avoid 34 integer overflows at the API boundary. (Existing logic uses a mismash of `int`, 35 `long`, and `unsigned`.) For the most part, implicit casts mean that existing 36 code continues to compile. In some cases, this may require BoringSSL-specific 37 code, particularly to avoid compiler warnings. 38 39 Most notably, the `STACK_OF(T)` types have all been converted to use `size_t` 40 instead of `int` for indices and lengths. 41 42 ### Reference counts 43 44 Some external consumers increment reference counts directly by calling 45 `CRYPTO_add` with the corresponding `CRYPTO_LOCK_*` value. 46 47 These APIs no longer exist in BoringSSL. Instead, code which increments 48 reference counts should call the corresponding `FOO_up_ref` function, such as 49 `EVP_PKEY_up_ref`. Note that not all of these APIs are present in OpenSSL and 50 may require `#ifdef`s. 51 52 ### Error codes 53 54 OpenSSL's errors are extremely specific, leaking internals of the library, 55 including even a function code for the function which emitted the error! As some 56 logic in BoringSSL has been rewritten, code which conditions on the error may 57 break (grep for `ERR_GET_REASON` and `ERR_GET_FUNC`). This danger also exists 58 when upgrading OpenSSL versions. 59 60 Where possible, avoid conditioning on the exact error reason. Otherwise, a 61 BoringSSL `#ifdef` may be necessary. Exactly how best to resolve this issue is 62 still being determined. It's possible some new APIs will be added in the future. 63 64 Function codes have been completely removed. Remove code which conditions on 65 these as it will break with the slightest change in the library, OpenSSL or 66 BoringSSL. 67 68 ### `*_ctrl` functions 69 70 Some OpenSSL APIs are implemented with `ioctl`-style functions such as 71 `SSL_ctrl` and `EVP_PKEY_CTX_ctrl`, combined with convenience macros, such as 72 73 # define SSL_CTX_set_mode(ctx,op) \ 74 SSL_CTX_ctrl((ctx),SSL_CTRL_MODE,(op),NULL) 75 76 In BoringSSL, these macros have been replaced with proper functions. The 77 underlying `_ctrl` functions have been removed. 78 79 For convenience, `SSL_CTRL_*` values are retained as macros to `doesnt_exist` so 80 existing code which uses them (or the wrapper macros) in `#ifdef` expressions 81 will continue to function. However, the macros themselves will not work. 82 83 Switch any `*_ctrl` callers to the macro/function versions. This works in both 84 OpenSSL and BoringSSL. Note that BoringSSL's function versions will be 85 type-checked and may require more care with types. See the end of this 86 document for a table of functions to use. 87 88 ### HMAC `EVP_PKEY`s 89 90 `EVP_PKEY_HMAC` is removed. Use the `HMAC_*` functions in `hmac.h` instead. This 91 is compatible with OpenSSL. 92 93 ### DSA `EVP_PKEY`s 94 95 `EVP_PKEY_DSA` is deprecated. It is currently still possible to parse DER into a 96 DSA `EVP_PKEY`, but signing or verifying with those objects will not work. 97 98 ### DES 99 100 The `DES_cblock` type has been switched from an array to a struct to avoid the 101 pitfalls around array types in C. Where features which require DES cannot be 102 disabled, BoringSSL-specific codepaths may be necessary. 103 104 ### TLS renegotiation 105 106 OpenSSL enables TLS renegotiation by default and accepts renegotiation requests 107 from the peer transparently. Renegotiation is an extremely problematic protocol 108 feature, so BoringSSL rejects peer renegotiations by default. 109 110 To enable renegotiation, call `SSL_set_renegotiate_mode` and set it to 111 `ssl_renegotiate_once` or `ssl_renegotiate_freely`. Renegotiation is only 112 supported as a client in SSL3/TLS and the HelloRequest must be received at a 113 quiet point in the application protocol. This is sufficient to support the 114 common use of requesting a new client certificate between an HTTP request and 115 response in (unpipelined) HTTP/1.1. 116 117 Things which do not work: 118 119 * There is no support for renegotiation as a server. 120 121 * There is no support for renegotiation in DTLS. 122 123 * There is no support for initiating renegotiation; `SSL_renegotiate` always 124 fails and `SSL_set_state` does nothing. 125 126 * Interleaving application data with the new handshake is forbidden. 127 128 * If a HelloRequest is received while `SSL_write` has unsent application data, 129 the renegotiation is rejected. 130 131 * Renegotiation does not participate in session resumption. The client will 132 not offer a session on renegotiation or resume any session established by a 133 renegotiation handshake. 134 135 * The server may not change its certificate in the renegotiation. This mitigates 136 the [triple handshake attack](https://mitls.org/pages/attacks/3SHAKE). Any new 137 stapled OCSP response and SCT list will be ignored. As no authentication state 138 may change, BoringSSL will not re-verify the certificate on a renegotiation. 139 Callbacks such as `SSL_CTX_set_custom_verify` will only run on the initial 140 handshake. 141 142 ### Lowercase hexadecimal 143 144 BoringSSL's `BN_bn2hex` function uses lowercase hexadecimal digits instead of 145 uppercase. Some code may require changes to avoid being sensitive to this 146 difference. 147 148 ### Legacy ASN.1 functions 149 150 OpenSSL's ASN.1 stack uses `d2i` functions for parsing. They have the form: 151 152 RSA *d2i_RSAPrivateKey(RSA **out, const uint8_t **inp, long len); 153 154 In addition to returning the result, OpenSSL places it in `*out` if `out` is 155 not `NULL`. On input, if `*out` is not `NULL`, OpenSSL will usually (but not 156 always) reuse that object rather than allocating a new one. In BoringSSL, these 157 functions are compatibility wrappers over a newer ASN.1 stack. Even if `*out` 158 is not `NULL`, these wrappers will always allocate a new object and free the 159 previous one. 160 161 Ensure that callers do not rely on this object reuse behavior. It is 162 recommended to avoid the `out` parameter completely and always pass in `NULL`. 163 Note that less error-prone APIs are available for BoringSSL-specific code (see 164 below). 165 166 ## Optional BoringSSL-specific simplifications 167 168 BoringSSL makes some changes to OpenSSL which simplify the API but remain 169 compatible with OpenSSL consumers. In general, consult the BoringSSL 170 documentation for any functions in new BoringSSL-only code. 171 172 ### Return values 173 174 Most OpenSSL APIs return 1 on success and either 0 or -1 on failure. BoringSSL 175 has narrowed most of these to 1 on success and 0 on failure. BoringSSL-specific 176 code may take advantage of the less error-prone APIs and use `!` to check for 177 errors. 178 179 ### Initialization 180 181 OpenSSL has a number of different initialization functions for setting up error 182 strings and loading algorithms, etc. All of these functions still exist in 183 BoringSSL for convenience, but they do nothing and are not necessary. 184 185 The one exception is `CRYPTO_library_init`. In `BORINGSSL_NO_STATIC_INITIALIZER` 186 builds, it must be called to query CPU capabitilies before the rest of the 187 library. In the default configuration, this is done with a static initializer 188 and is also unnecessary. 189 190 ### Threading 191 192 OpenSSL provides a number of APIs to configure threading callbacks and set up 193 locks. Without initializing these, the library is not thread-safe. Configuring 194 these does nothing in BoringSSL. Instead, BoringSSL calls pthreads and the 195 corresponding Windows APIs internally and is always thread-safe where the API 196 guarantees it. 197 198 ### ASN.1 199 200 BoringSSL is in the process of deprecating OpenSSL's `d2i` and `i2d` in favor of 201 new functions using the much less error-prone `CBS` and `CBB` types. 202 BoringSSL-only code should use those functions where available. 203 204 205 ## Replacements for `CTRL` values 206 207 When porting code which uses `SSL_CTX_ctrl` or `SSL_ctrl`, use the replacement 208 functions below. If a function has both `SSL_CTX` and `SSL` variants, only the 209 `SSL_CTX` version is listed. 210 211 Note some values correspond to multiple functions depending on the `larg` 212 parameter. 213 214 `CTRL` value | Replacement function(s) 215 -------------|------------------------- 216 `DTLS_CTRL_GET_TIMEOUT` | `DTLSv1_get_timeout` 217 `DTLS_CTRL_HANDLE_TIMEOUT` | `DTLSv1_handle_timeout` 218 `SSL_CTRL_CHAIN` | `SSL_CTX_set0_chain` or `SSL_CTX_set1_chain` 219 `SSL_CTRL_CHAIN_CERT` | `SSL_add0_chain_cert` or `SSL_add1_chain_cert` 220 `SSL_CTRL_CLEAR_EXTRA_CHAIN_CERTS` | `SSL_CTX_clear_extra_chain_certs` 221 `SSL_CTRL_CLEAR_MODE` | `SSL_CTX_clear_mode` 222 `SSL_CTRL_CLEAR_OPTIONS` | `SSL_CTX_clear_options` 223 `SSL_CTRL_EXTRA_CHAIN_CERT` | `SSL_CTX_add_extra_chain_cert` 224 `SSL_CTRL_GET_CHAIN_CERTS` | `SSL_CTX_get0_chain_certs` 225 `SSL_CTRL_GET_CLIENT_CERT_TYPES` | `SSL_get0_certificate_types` 226 `SSL_CTRL_GET_EXTRA_CHAIN_CERTS` | `SSL_CTX_get_extra_chain_certs` or `SSL_CTX_get_extra_chain_certs_only` 227 `SSL_CTRL_GET_MAX_CERT_LIST` | `SSL_CTX_get_max_cert_list` 228 `SSL_CTRL_GET_NUM_RENEGOTIATIONS` | `SSL_num_renegotiations` 229 `SSL_CTRL_GET_READ_AHEAD` | `SSL_CTX_get_read_ahead` 230 `SSL_CTRL_GET_RI_SUPPORT` | `SSL_get_secure_renegotiation_support` 231 `SSL_CTRL_GET_SESSION_REUSED` | `SSL_session_reused` 232 `SSL_CTRL_GET_SESS_CACHE_MODE` | `SSL_CTX_get_session_cache_mode` 233 `SSL_CTRL_GET_SESS_CACHE_SIZE` | `SSL_CTX_sess_get_cache_size` 234 `SSL_CTRL_GET_TLSEXT_TICKET_KEYS` | `SSL_CTX_get_tlsext_ticket_keys` 235 `SSL_CTRL_GET_TOTAL_RENEGOTIATIONS` | `SSL_total_renegotiations` 236 `SSL_CTRL_MODE` | `SSL_CTX_get_mode` or `SSL_CTX_set_mode` 237 `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.) 238 `SSL_CTRL_OPTIONS` | `SSL_CTX_get_options` or `SSL_CTX_set_options` 239 `SSL_CTRL_SESS_NUMBER` | `SSL_CTX_sess_number` 240 `SSL_CTRL_SET_CURVES` | `SSL_CTX_set1_curves` 241 `SSL_CTRL_SET_ECDH_AUTO` | `SSL_CTX_set_ecdh_auto` 242 `SSL_CTRL_SET_MAX_CERT_LIST` | `SSL_CTX_set_max_cert_list` 243 `SSL_CTRL_SET_MAX_SEND_FRAGMENT` | `SSL_CTX_set_max_send_fragment` 244 `SSL_CTRL_SET_MSG_CALLBACK` | `SSL_set_msg_callback` 245 `SSL_CTRL_SET_MSG_CALLBACK_ARG` | `SSL_set_msg_callback_arg` 246 `SSL_CTRL_SET_MTU` | `SSL_set_mtu` 247 `SSL_CTRL_SET_READ_AHEAD` | `SSL_CTX_set_read_ahead` 248 `SSL_CTRL_SET_SESS_CACHE_MODE` | `SSL_CTX_set_session_cache_mode` 249 `SSL_CTRL_SET_SESS_CACHE_SIZE` | `SSL_CTX_sess_set_cache_size` 250 `SSL_CTRL_SET_TLSEXT_HOSTNAME` | `SSL_set_tlsext_host_name` 251 `SSL_CTRL_SET_TLSEXT_SERVERNAME_ARG` | `SSL_CTX_set_tlsext_servername_arg` 252 `SSL_CTRL_SET_TLSEXT_SERVERNAME_CB` | `SSL_CTX_set_tlsext_servername_callback` 253 `SSL_CTRL_SET_TLSEXT_TICKET_KEYS` | `SSL_CTX_set_tlsext_ticket_keys` 254 `SSL_CTRL_SET_TLSEXT_TICKET_KEY_CB` | `SSL_CTX_set_tlsext_ticket_key_cb` 255 `SSL_CTRL_SET_TMP_DH` | `SSL_CTX_set_tmp_dh` 256 `SSL_CTRL_SET_TMP_DH_CB` | `SSL_CTX_set_tmp_dh_callback` 257 `SSL_CTRL_SET_TMP_ECDH` | `SSL_CTX_set_tmp_ecdh` 258 `SSL_CTRL_SET_TMP_ECDH_CB` | `SSL_CTX_set_tmp_ecdh_callback` 259 `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.) 260 `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.) 261
