nexmon – Blame information for rev 1

Subversion Repositories:
Rev:
Rev Author Line No. Line
1 office 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 ### Legacy ASN.1 functions
134  
135 OpenSSL's ASN.1 stack uses `d2i` functions for parsing. They have the form:
136  
137 RSA *d2i_RSAPrivateKey(RSA **out, const uint8_t **inp, long len);
138  
139 In addition to returning the result, OpenSSL places it in `*out` if `out` is
140 not `NULL`. On input, if `*out` is not `NULL`, OpenSSL will usually (but not
141 always) reuse that object rather than allocating a new one. In BoringSSL, these
142 functions are compatibility wrappers over a newer ASN.1 stack. Even if `*out`
143 is not `NULL`, these wrappers will always allocate a new object and free the
144 previous one.
145  
146 Ensure that callers do not rely on this object reuse behavior. It is
147 recommended to avoid the `out` parameter completely and always pass in `NULL`.
148 Note that less error-prone APIs are available for BoringSSL-specific code (see
149 below).
150  
151 ## Optional BoringSSL-specific simplifications
152  
153 BoringSSL makes some changes to OpenSSL which simplify the API but remain
154 compatible with OpenSSL consumers. In general, consult the BoringSSL
155 documentation for any functions in new BoringSSL-only code.
156  
157 ### Return values
158  
159 Most OpenSSL APIs return 1 on success and either 0 or -1 on failure. BoringSSL
160 has narrowed most of these to 1 on success and 0 on failure. BoringSSL-specific
161 code may take advantage of the less error-prone APIs and use `!` to check for
162 errors.
163  
164 ### Initialization
165  
166 OpenSSL has a number of different initialization functions for setting up error
167 strings and loading algorithms, etc. All of these functions still exist in
168 BoringSSL for convenience, but they do nothing and are not necessary.
169  
170 The one exception is `CRYPTO_library_init`. In `BORINGSSL_NO_STATIC_INITIALIZER`
171 builds, it must be called to query CPU capabitilies before the rest of the
172 library. In the default configuration, this is done with a static initializer
173 and is also unnecessary.
174  
175 ### Threading
176  
177 OpenSSL provides a number of APIs to configure threading callbacks and set up
178 locks. Without initializing these, the library is not thread-safe. Configuring
179 these does nothing in BoringSSL. Instead, BoringSSL calls pthreads and the
180 corresponding Windows APIs internally and is always thread-safe where the API
181 guarantees it.
182  
183 ### ASN.1
184  
185 BoringSSL is in the process of deprecating OpenSSL's `d2i` and `i2d` in favor of
186 new functions using the much less error-prone `CBS` and `CBB` types.
187 BoringSSL-only code should use those functions where available.