README.chromium
1Name: openssl
2URL: http://openssl.org/source/
3Version: 1.0.1e
4License: BSDish
5License File: openssl/NOTICE
6License Android Compatible: yes
7Security Critical: yes
8
9Description:
10This is OpenSSL, the standard SSL/TLS library, which is used *only* in
11the following cases:
12
13 - For Chrome/Chromium, only on Android to implement SSL/TLS support
14 (while certificate validation is performed through the platform APIs),
15 instead of using NSS as on other Linux-based operating systems.
16
17 Note that there is no plans to support OpenSSL in Chromium on other
18 platforms. For more context, please read:
19
20 https://groups.google.com/a/chromium.org/d/msg/chromium-dev/gmO3U9HLY3Y/RPGNiQ-NL-YJ
21
22 - To implement net/tools/flip_server, a host-side tool. Read more about
23 it at the following page:
24
25 http://dev.chromium.org/spdy/running_flipinmemserver
26
27This means that the library must be built for these systems:
28
29 Android/ARM
30 Android/x86
31 Linux/x86
32 Linux/x86_64
33 Darwin/x86
34 Darwin/x86_64
35
36Whenever you change it, try to rebuild Chromium for all these systems.
37
38**************************************************************************
39Automatic generation of source tree.
40
41Most of the sources in this directory are auto-generated and come from
42the Android version of the OpenSSL sources, with a few Chromium-specific
43patches applied.
44
45Said Android sources are themselves a patched subset of the official
46OpenSSL release sources, generated by a special import script.
47
48To update the sources for Chromium, one has to modify
49openssl-chromium.config or the content of patches.chromium/ then run:
50
51 ./import_from_android.sh
52
53Before doing that, you should understand how everything works:
54
55 1) Android-specific files are taken from a given commit from the
56 AOSP git servers. See how 'openssl-chromium.config' defines the
57 following variables:
58
59 ANDROID_OPENSSL_GIT_SOURCE -> point to source git server.
60 ANDROID_OPENSSL_GIT_COMMIT -> point to git commit
61
62 2) All downloaded Android-specific files are placed under the openssl/
63 sub-directory. The most important files are the following:
64
65 openssl/openssl.version
66 Configuration file telling which upstream version of
67 OpenSSL sources to use.
68
69 openssl/patches/
70 Directory containing several Android-specific patches to
71 apply to the official OpenSSL sources to create the
72 Android ones. See openssl/patches/README for a description
73 of what each of these patches do.
74
75 openssl/openssl.config
76 Configuration file describing which build-time options
77 to enable, what patches to apply, which source files to compile
78 (including CPU architecture-specific variants), and which
79 sources to keep in the final source directory.
80
81 openssl/import_openssl.sh
82 Import script used to regenerate all other Android-specific
83 source files, based on the configuration files above
84 and a tarball of the official OpenSSL source release.
85
86 For example, to rebuild the full Android source tree (without any
87 Chromium patches), one would do something like:
88
89 cd openssl/
90 ./import_openssl.sh import /path/to/openssl-<version>.tar.gz
91
92 where <version> matches the definition found in 'openssl.version'.
93
94 3) Chromium adds a few of its own files:
95
96 openssl-chromium.config
97 Configuration file which indicates:
98 - The reference Android OpenSSL git repository and commit.
99 - The download location of official OpenSSL source tarballs.
100 - The corresponding SHA-1 sum, for sanity checking.
101
102 patches.chromium/
103 A set of additional patches to apply to the openssl/ tree
104 after it has been downloaded from the Android git repository.
105
106 These patches are applied _before_ import_openssl.sh is run to
107 re-generate the final set of sources. This allows modifying the
108 content of any Android configuration file easily.
109
110 openssl.gyp
111 A gyp build file for the library. Manually maintained, this file
112 includes openssl.gypi below.
113
114 openssl.gypi
115 An *auto-generated* gyp include file that contains the required
116 definitions used to describe the library's sources to the
117 Chromium build system. Its content mirrors openssl/openssl.config
118 in a gyp-compatible way.
119
120 config/x64/openssl/opensslconf.h
121 Another *auto-generated* file used for 64-bit builds of the library
122 only. This is required for correctness because the Android sources
123 only come with a single generic header which is tailored for
124 32-bit builds. Using the latter results either in a broken build,
125 or even worse, in a library that doesn't work correctly.
126
127 The content of this file is a simple copy of
128 openssl/include/openssl/opensslconf.h, with a few lines
129 altered to reflect that the target has 64-bit types.
130
131 import_from_android.sh
132 The top-level script that will automatically perform the full
133 Chromium download + patching + import + auto-generation process.
134
135
136More specifically, calling 'import_from_android.sh' will do the following:
137
138 1) Download a specific Android commit from AOSP git servers to openssl/
139 2) Download the corresponding official OpenSSL release tarball.
140 3) Sainty check its SHA-1 against a hard-coded value.
141 4) Apply chromium-specific patches.
142 5) Re-run the Android 'import_openssl.sh' script.
143 6) Auto-generate config/x64/openssl/opensslconf.h
144 7) Auto-generate openssl.gypi
145
146Once the script is done, all you need to do is launch gyp again, rebuild
147and run unit tests. Use the --verbose option to see what the script does,
148or --help to see a detailed scription and a list of valid options.
149
150**************************************************************************
151Chromium-specific patches:
152
153The list of Chromium-specific patches to apply to the Android tree is
154located in patches.chromium/. Currently this consists of:
155
156 x509_hash_name_algorithm_change.patch
157 Ensure the library can find the right files under /etc/ssl/certs when
158 running on older systems.
159
160 There are many symbolic links under /etc/ssl/certs created by using
161 hash of the PEM certificates in order for OpenSSL to find those
162 certificates. Openssl has a tool to help you create hash symbolic
163 links (tools/c_rehash). However newer versions of the library changed
164 the hash algorithm, which makes it unable to run properly on systems
165 that use the old /etc/ssl/certs layout (e.g. Ubuntu Lucid).
166
167 This patch gives a way to find a certificate according to its hash by
168 using both the old and new algorithms. http://crbug.com/111045 is used
169 to track this issue.
170
171 enable-dtls1.patch:
172 Enable DTLSv1, which is disabled by default in the Android platform
173 configuration.
174
175 x86_64_source_excludes.patch
176 Exclude the source files bn_asm.c and rc4_skey.c for x86_64 because
177 they are replaced by x86_64-gcc.c and rc4-x86_64.S.
178
179 z_reduce_client_hello_size.patch
180 Advertise support of only the NIST curves P-521, P-384, and P-256,
181 as well as only uncompressed points, to keep ClientHello small.
182
183 channelid.patch
184 Add API so that channel ID private key can be set only after verifying the
185 remote server supports channel IDs.
186
187 fix_lhash_iteration.patch
188 Fix a crash that happens when OpenSSL tries to delete items from a lhash
189 table that is being iterated over. This happens in certain rare cases
190 when SSL_CTX_flush_sessions() is called. See http://crbug.com/298606
191
192 chacha.patch
193 Add support for ChaCha20+Poly1305 cipher suites.
194
195 paddingext.patch
196 paddingext2.patch
197 Add ClientHello padding to workaround bug in F5 terminators.
198
199 stricter_cutthrough.patch
200 Requires NPN and a PFS cipher suite to enable cut-through (false start) on
201 the client.
202
203 mac_osx32_assembly.patch
204 Add support for 32 bit OS X with assembly optimization.
205
206 fix_limit_checks.patch
207 Fix limit checks in writing extensions. BUF_MEM_grow allocates 4/3 the size
208 requested, so it doesn't overflow the actual allocation.
209
210 reorder_extensions.patch
211 Move the ECC extensions to the end of the ClientHello to work around a
212 server bug. Some servers are intolerant to the last extension being empty.
213 See https://crbug.com/363583
214
215 export_certificate_types.patch
216 Export the certificate_types field in CertificateRequest.
217
218 send_client_verify_cleanup.patch
219 Clean up ssl3_send_client_verify so the various cases (TLS 1.2, pre-TLS-1.2
220 cases for each cipher suite) are less intertwined.
221
222**************************************************************************
223Adding new Chromium patches:
224
225In the event you need to add a new Chromium-specific patch, follow this
226procedure:
227
228 1) Use the --temp-dir option to download everything to a known directory
229 (by default, import_from_android.sh downloads everything into a
230 temporary directory that is erased when the script exits, even in
231 case of error).
232
233 ./import_from_android.sh --temp-dir=/tmp/aaa
234
235 2) Save the "original" Android sources:
236
237 cp -rp /tmp/aaa/build/android-openssl /tmp/aaa/build/android-openssl.orig
238
239 3) Modify the content of /tmp/aaa/build/android-openssl appropriately.
240 You do *not* have to run 'import_openssl.sh'
241
242 4) Create new patch:
243
244 (cd /tmp/aaa/build && diff -burN android-openssl.orig android-openssl) > patches.chromium/my-new-change.patch
245
246 5) Re-run the script:
247
248 ./import_from_android.sh
249
250Generally speaking, consider sending your patch directly to the Android
251open-source review servers too. Once submitted there, you can update
252the git commit in openssl-chromium.org and remove your local patch in
253one new CL.
254