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 14 For convenience, BoringSSL defines upstream's `OPENSSL_NO_*` feature macros 15 corresponding to removed features. These may also be used to disable code which 16 uses a removed feature. 17 18 Note: BoringSSL does *not* have a stable API or ABI. It must be updated with its 19 consumers. It is not suitable for, say, a system library in a traditional Linux 20 distribution. For instance, Chromium statically links the specific revision of 21 BoringSSL it was built against. Likewise, Android's system-internal copy of 22 BoringSSL is not exposed by the NDK and must not be used by third-party 23 applications. 24 25 26 ## Major API changes 27 28 ### Integer types 29 30 Some APIs have been converted to use `size_t` for consistency and to avoid 31 integer overflows at the API boundary. (Existing logic uses a mismash of `int`, 32 `long`, and `unsigned`.) For the most part, implicit casts mean that existing 33 code continues to compile. In some cases, this may require BoringSSL-specific 34 code, particularly to avoid compiler warnings. 35 36 Most notably, the `STACK_OF(T)` types have all been converted to use `size_t` 37 instead of `int` for indices and lengths. 38 39 ### Reference counts 40 41 Some external consumers increment reference counts directly by calling 42 `CRYPTO_add` with the corresponding `CRYPTO_LOCK_*` value. 43 44 These APIs no longer exist in BoringSSL. Instead, code which increments 45 reference counts should call the corresponding `FOO_up_ref` function, such as 46 `EVP_PKEY_up_ref`. Note that not all of these APIs are present in OpenSSL and 47 may require `#ifdef`s. 48 49 ### Error codes 50 51 OpenSSL's errors are extremely specific, leaking internals of the library, 52 including even a function code for the function which emitted the error! As some 53 logic in BoringSSL has been rewritten, code which conditions on the error may 54 break (grep for `ERR_GET_REASON` and `ERR_GET_FUNC`). This danger also exists 55 when upgrading OpenSSL versions. 56 57 Where possible, avoid conditioning on the exact error reason. Otherwise, a 58 BoringSSL `#ifdef` may be necessary. Exactly how best to resolve this issue is 59 still being determined. It's possible some new APIs will be added in the future. 60 61 Function codes have been completely removed. Remove code which conditions on 62 these as it will break with the slightest change in the library, OpenSSL or 63 BoringSSL. 64 65 ### `*_ctrl` functions 66 67 Some OpenSSL APIs are implemented with `ioctl`-style functions such as 68 `SSL_ctrl` and `EVP_PKEY_CTX_ctrl`, combined with convenience macros, such as 69 70 # define SSL_CTX_set_mode(ctx,op) \ 71 SSL_CTX_ctrl((ctx),SSL_CTRL_MODE,(op),NULL) 72 73 In BoringSSL, these macros have been replaced with proper functions. The 74 underlying `_ctrl` functions have been removed. 75 76 For convenience, `SSL_CTRL_*` values are retained as macros to `doesnt_exist` so 77 existing code which uses them (or the wrapper macros) in `#ifdef` expressions 78 will continue to function. However, the macros themselves will not work. 79 80 Switch any `*_ctrl` callers to the macro/function versions. This works in both 81 OpenSSL and BoringSSL. Note that BoringSSL's function versions will be 82 type-checked and may require more care with types. 83 84 ### HMAC `EVP_PKEY`s 85 86 `EVP_PKEY_HMAC` is removed. Use the `HMAC_*` functions in `hmac.h` instead. This 87 is compatible with OpenSSL. 88 89 ### DSA `EVP_PKEY`s 90 91 `EVP_PKEY_DSA` is deprecated. It is currently still possible to parse DER into a 92 DSA `EVP_PKEY`, but signing or verifying with those objects will not work. 93 94 ### DES 95 96 The `DES_cblock` type has been switched from an array to a struct to avoid the 97 pitfalls around array types in C. Where features which require DES cannot be 98 disabled, BoringSSL-specific codepaths may be necessary. 99 100 ### TLS renegotiation 101 102 OpenSSL enables TLS renegotiation by default and accepts renegotiation requests 103 from the peer transparently. Renegotiation is an extremely problematic protocol 104 feature, so BoringSSL rejects peer renegotiations by default. 105 106 To enable renegotiation, call `SSL_set_renegotiate_mode` and set it to 107 `ssl_renegotiate_once` or `ssl_renegotiate_freely`. Renegotiation is only 108 supported as a client in SSL3/TLS and the HelloRequest must be received at a 109 quiet point in the application protocol. This is sufficient to support the 110 common use of requesting a new client certificate between an HTTP request and 111 response in (unpipelined) HTTP/1.1. 112 113 Things which do not work: 114 115 * There is no support for renegotiation as a server. 116 117 * There is no support for renegotiation in DTLS. 118 119 * There is no support for initiating renegotiation; `SSL_renegotiate` always 120 fails and `SSL_set_state` does nothing. 121 122 * Interleaving application data with the new handshake is forbidden. 123 124 * If a HelloRequest is received while `SSL_write` has unsent application data, 125 the renegotiation is rejected. 126 127 ### Lowercase hexadecimal 128 129 BoringSSL's `BN_bn2hex` function uses lowercase hexadecimal digits instead of 130 uppercase. Some code may require changes to avoid being sensitive to this 131 difference. 132 133 134 ## Optional BoringSSL-specific simplifications 135 136 BoringSSL makes some changes to OpenSSL which simplify the API but remain 137 compatible with OpenSSL consumers. In general, consult the BoringSSL 138 documentation for any functions in new BoringSSL-only code. 139 140 ### Return values 141 142 Most OpenSSL APIs return 1 on success and either 0 or -1 on failure. BoringSSL 143 has narrowed most of these to 1 on success and 0 on failure. BoringSSL-specific 144 code may take advantage of the less error-prone APIs and use `!` to check for 145 errors. 146 147 ### Initialization 148 149 OpenSSL has a number of different initialization functions for setting up error 150 strings and loading algorithms, etc. All of these functions still exist in 151 BoringSSL for convenience, but they do nothing and are not necessary. 152 153 The one exception is `CRYPTO_library_init`. In `BORINGSSL_NO_STATIC_INITIALIZER` 154 builds, it must be called to query CPU capabitilies before the rest of the 155 library. In the default configuration, this is done with a static initializer 156 and is also unnecessary. 157 158 ### Threading 159 160 OpenSSL provides a number of APIs to configure threading callbacks and set up 161 locks. Without initializing these, the library is not thread-safe. Configuring 162 these does nothing in BoringSSL. Instead, BoringSSL calls pthreads and the 163 corresponding Windows APIs internally and is always thread-safe where the API 164 guarantees it. 165
