diff options
Diffstat (limited to 'src/PORTING.md')
| -rw-r--r-- | src/PORTING.md | 157 |
1 files changed, 0 insertions, 157 deletions
diff --git a/src/PORTING.md b/src/PORTING.md deleted file mode 100644 index 70b67cc..0000000 --- a/src/PORTING.md +++ /dev/null @@ -1,157 +0,0 @@ -# Porting from OpenSSL to BoringSSL - -BoringSSL is an OpenSSL derivative and is mostly source-compatible, for the -subset of OpenSSL retained. Libraries ideally need little to no changes for -BoringSSL support, provided they do not use removed APIs. In general, see if the -library compiles and, on failure, consult the documentation in the header files -and see if problematic features can be removed. - -In some cases, BoringSSL-specific code may be necessary. In that case, the -`OPENSSL_IS_BORINGSSL` preprocessor macro may be used in `#ifdef`s. This macro -should also be used in lieu of the presence of any particular function to detect -OpenSSL vs BoringSSL in configure scripts, etc., where those are necessary. - -For convenience, BoringSSL defines upstream's `OPENSSL_NO_*` feature macros -corresponding to removed features. These may also be used to disable code which -uses a removed feature. - -Note: BoringSSL does *not* have a stable API or ABI. It must be updated with its -consumers. It is not suitable for, say, a system library in a traditional Linux -distribution. For instance, Chromium statically links the specific revision of -BoringSSL it was built against. Likewise, Android's system-internal copy of -BoringSSL is not exposed by the NDK and must not be used by third-party -applications. - - -## Major API changes - -### Integer types - -Some APIs have been converted to use `size_t` for consistency and to avoid -integer overflows at the API boundary. (Existing logic uses a mismash of `int`, -`long`, and `unsigned`.) For the most part, implicit casts mean that existing -code continues to compile. In some cases, this may require BoringSSL-specific -code, particularly to avoid compiler warnings. - -Most notably, the `STACK_OF(T)` types have all been converted to use `size_t` -instead of `int` for indices and lengths. - -### Reference counts - -Some external consumers increment reference counts directly by calling -`CRYPTO_add` with the corresponding `CRYPTO_LOCK_*` value. - -These APIs no longer exist in BoringSSL. Instead, code which increments -reference counts should call the corresponding `FOO_up_ref` function, such as -`EVP_PKEY_up_ref`. Note that not all of these APIs are present in OpenSSL and -may require `#ifdef`s. - -### Error codes - -OpenSSL's errors are extremely specific, leaking internals of the library, -including even a function code for the function which emitted the error! As some -logic in BoringSSL has been rewritten, code which conditions on the error may -break (grep for `ERR_GET_REASON` and `ERR_GET_FUNC`). This danger also exists -when upgrading OpenSSL versions. - -Where possible, avoid conditioning on the exact error reason. Otherwise, a -BoringSSL `#ifdef` may be necessary. Exactly how best to resolve this issue is -still being determined. It's possible some new APIs will be added in the future. - -Function codes have been completely removed. Remove code which conditions on -these as it will break with the slightest change in the library, OpenSSL or -BoringSSL. - -### `*_ctrl` functions - -Some OpenSSL APIs are implemented with `ioctl`-style functions such as -`SSL_ctrl` and `EVP_PKEY_CTX_ctrl`, combined with convenience macros, such as - - # define SSL_CTX_set_mode(ctx,op) \ - SSL_CTX_ctrl((ctx),SSL_CTRL_MODE,(op),NULL) - -In BoringSSL, these macros have been replaced with proper functions. The -underlying `_ctrl` functions have been removed. - -For convenience, `SSL_CTRL_*` values are retained as macros to `doesnt_exist` so -existing code which uses them (or the wrapper macros) in `#ifdef` expressions -will continue to function. However, the macros themselves will not work. - -Switch any `*_ctrl` callers to the macro/function versions. This works in both -OpenSSL and BoringSSL. Note that BoringSSL's function versions will be -type-checked and may require more care with types. - -### HMAC `EVP_PKEY`s - -`EVP_PKEY_HMAC` is removed. Use the `HMAC_*` functions in `hmac.h` instead. This -is compatible with OpenSSL. - -### DSA `EVP_PKEY`s - -`EVP_PKEY_DSA` is deprecated. It is currently still possible to parse DER into a -DSA `EVP_PKEY`, but signing or verifying with those objects will not work. - -### DES - -The `DES_cblock` type has been switched from an array to a struct to avoid the -pitfalls around array types in C. Where features which require DES cannot be -disabled, BoringSSL-specific codepaths may be necessary. - -### TLS renegotiation - -OpenSSL enables TLS renegotiation by default and accepts renegotiation requests -from the peer transparently. Renegotiation is an extremely problematic protocol -feature, so BoringSSL rejects peer renegotiations by default. - -To enable renegotiation, call `SSL_set_reject_peer_renegotiations` and set it to -off. Renegotiation is only supported as a client in SSL3/TLS and the -HelloRequest must be received at a quiet point in the application protocol. This -is sufficient to support the common use of requesting a new client certificate -between an HTTP request and response in (unpipelined) HTTP/1.1. - -Things which do not work: - -* There is no support for renegotiation as a server. - -* There is no support for renegotiation in DTLS. - -* There is no support for initiating renegotiation; `SSL_renegotiate` always - fails and `SSL_set_state` does nothing. - -* Interleaving application data with the new handshake is forbidden. - -* If a HelloRequest is received while `SSL_write` has unsent application data, - the renegotiation is rejected. - - -## Optional BoringSSL-specific simplifications - -BoringSSL makes some changes to OpenSSL which simplify the API but remain -compatible with OpenSSL consumers. In general, consult the BoringSSL -documentation for any functions in new BoringSSL-only code. - -### Return values - -Most OpenSSL APIs return 1 on success and either 0 or -1 on failure. BoringSSL -has narrowed most of these to 1 on success and 0 on failure. BoringSSL-specific -code may take advantage of the less error-prone APIs and use `!` to check for -errors. - -### Initialization - -OpenSSL has a number of different initialization functions for setting up error -strings and loading algorithms, etc. All of these functions still exist in -BoringSSL for convenience, but they do nothing and are not necessary. - -The one exception is `CRYPTO_library_init` (and `SSL_library_init` which merely -calls it). In `BORINGSSL_NO_STATIC_INITIALIZER` builds, it must be called to -query CPU capabitilies before the rest of the library. In the default -configuration, this is done with a static initializer and is also unnecessary. - -### Threading - -OpenSSL provides a number of APIs to configure threading callbacks and set up -locks. Without initializing these, the library is not thread-safe. Configuring -these does nothing in BoringSSL. Instead, BoringSSL calls pthreads and the -corresponding Windows APIs internally and is always thread-safe where the API -guarantees it. |