1# Porting from OpenSSL to BoringSSL
2
3BoringSSL is an OpenSSL derivative and is mostly source-compatible, for the
4subset of OpenSSL retained. Libraries ideally need little to no changes for
5BoringSSL support, provided they do not use removed APIs. In general, see if the
6library compiles and, on failure, consult the documentation in the header files
7and see if problematic features can be removed.
8
9In 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
11should also be used in lieu of the presence of any particular function to detect
12OpenSSL vs BoringSSL in configure scripts, etc., where those are necessary.
13
14For convenience, BoringSSL defines upstream's `OPENSSL_NO_*` feature macros
15corresponding to removed features. These may also be used to disable code which
16uses a removed feature.
17
18Note: BoringSSL does *not* have a stable API or ABI. It must be updated with its
19consumers. It is not suitable for, say, a system library in a traditional Linux
20distribution. For instance, Chromium statically links the specific revision of
21BoringSSL it was built against. Likewise, Android's system-internal copy of
22BoringSSL is not exposed by the NDK and must not be used by third-party
23applications.
24
25
26## Major API changes
27
28### Integer types
29
30Some APIs have been converted to use `size_t` for consistency and to avoid
31integer 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
33code continues to compile. In some cases, this may require BoringSSL-specific
34code, particularly to avoid compiler warnings.
35
36Most notably, the `STACK_OF(T)` types have all been converted to use `size_t`
37instead of `int` for indices and lengths.
38
39### Reference counts
40
41Some external consumers increment reference counts directly by calling
42`CRYPTO_add` with the corresponding `CRYPTO_LOCK_*` value.
43
44These APIs no longer exist in BoringSSL. Instead, code which increments
45reference 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
47may require `#ifdef`s.
48
49### Error codes
50
51OpenSSL's errors are extremely specific, leaking internals of the library,
52including even a function code for the function which emitted the error! As some
53logic in BoringSSL has been rewritten, code which conditions on the error may
54break (grep for `ERR_GET_REASON` and `ERR_GET_FUNC`). This danger also exists
55when upgrading OpenSSL versions.
56
57Where possible, avoid conditioning on the exact error reason. Otherwise, a
58BoringSSL `#ifdef` may be necessary. Exactly how best to resolve this issue is
59still being determined. It's possible some new APIs will be added in the future.
60
61Function codes have been completely removed. Remove code which conditions on
62these as it will break with the slightest change in the library, OpenSSL or
63BoringSSL.
64
65### `*_ctrl` functions
66
67Some 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
73In BoringSSL, these macros have been replaced with proper functions. The
74underlying `_ctrl` functions have been removed.
75
76For convenience, `SSL_CTRL_*` values are retained as macros to `doesnt_exist` so
77existing code which uses them (or the wrapper macros) in `#ifdef` expressions
78will continue to function. However, the macros themselves will not work.
79
80Switch any `*_ctrl` callers to the macro/function versions. This works in both
81OpenSSL and BoringSSL. Note that BoringSSL's function versions will be
82type-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
87is 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
92DSA `EVP_PKEY`, but signing or verifying with those objects will not work.
93
94### DES
95
96The `DES_cblock` type has been switched from an array to a struct to avoid the
97pitfalls around array types in C. Where features which require DES cannot be
98disabled, BoringSSL-specific codepaths may be necessary.
99
100### TLS renegotiation
101
102OpenSSL enables TLS renegotiation by default and accepts renegotiation requests
103from the peer transparently. Renegotiation is an extremely problematic protocol
104feature, so BoringSSL rejects peer renegotiations by default.
105
106To enable renegotiation, call `SSL_set_renegotiate_mode` and set it to
107`ssl_renegotiate_once` or `ssl_renegotiate_freely`. Renegotiation is only
108supported as a client in SSL3/TLS and the HelloRequest must be received at a
109quiet point in the application protocol. This is sufficient to support the
110common use of requesting a new client certificate between an HTTP request and
111response in (unpipelined) HTTP/1.1.
112
113Things 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
129BoringSSL's `BN_bn2hex` function uses lowercase hexadecimal digits instead of
130uppercase. Some code may require changes to avoid being sensitive to this
131difference.
132
133
134## Optional BoringSSL-specific simplifications
135
136BoringSSL makes some changes to OpenSSL which simplify the API but remain
137compatible with OpenSSL consumers. In general, consult the BoringSSL
138documentation for any functions in new BoringSSL-only code.
139
140### Return values
141
142Most OpenSSL APIs return 1 on success and either 0 or -1 on failure. BoringSSL
143has narrowed most of these to 1 on success and 0 on failure. BoringSSL-specific
144code may take advantage of the less error-prone APIs and use `!` to check for
145errors.
146
147### Initialization
148
149OpenSSL has a number of different initialization functions for setting up error
150strings and loading algorithms, etc. All of these functions still exist in
151BoringSSL for convenience, but they do nothing and are not necessary.
152
153The one exception is `CRYPTO_library_init`. In `BORINGSSL_NO_STATIC_INITIALIZER`
154builds, it must be called to query CPU capabitilies before the rest of the
155library. In the default configuration, this is done with a static initializer
156and is also unnecessary.
157
158### Threading
159
160OpenSSL provides a number of APIs to configure threading callbacks and set up
161locks. Without initializing these, the library is not thread-safe. Configuring
162these does nothing in BoringSSL. Instead, BoringSSL calls pthreads and the
163corresponding Windows APIs internally and is always thread-safe where the API
164guarantees it.
165