1 Name: openssl 2 URL: http://openssl.org/source/ 3 Version: 1.0.1e 4 License: BSDish 5 License File: openssl/NOTICE 6 License Android Compatible: yes 7 Security Critical: yes 8 9 Description: 10 This is OpenSSL, the standard SSL/TLS library, which is used *only* in 11 the 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 27 This 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 36 Whenever you change it, try to rebuild Chromium for all these systems. 37 38 ************************************************************************** 39 Automatic generation of source tree. 40 41 Most of the sources in this directory are auto-generated and come from 42 the Android version of the OpenSSL sources, with a few Chromium-specific 43 patches applied. 44 45 Said Android sources are themselves a patched subset of the official 46 OpenSSL release sources, generated by a special import script. 47 48 To update the sources for Chromium, one has to modify 49 openssl-chromium.config or the content of patches.chromium/ then run: 50 51 ./import_from_android.sh 52 53 Before 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 136 More 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 146 Once the script is done, all you need to do is launch gyp again, rebuild 147 and run unit tests. Use the --verbose option to see what the script does, 148 or --help to see a detailed scription and a list of valid options. 149 150 ************************************************************************** 151 Chromium-specific patches: 152 153 The list of Chromium-specific patches to apply to the Android tree is 154 located 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 ************************************************************************** 184 Adding new Chromium patches: 185 186 In the event you need to add a new Chromium-specific patch, follow this 187 procedure: 188 189 1) Use the --temp-dir option to download everything to a known directory 190 (by default, import_from_android.sh downloads everything into a 191 temporary directory that is erased when the script exits, even in 192 case of error). 193 194 ./import_from_android.sh --temp-dir=/tmp/aaa 195 196 2) Save the "original" Android sources: 197 198 cp -rp /tmp/aaa/build/android-openssl /tmp/aaa/build/android-openssl.orig 199 200 3) Modify the content of /tmp/aaa/build/android-openssl appropriately. 201 You do *not* have to run 'import_openssl.sh' 202 203 4) Create new patch: 204 205 (cd /tmp/aaa/build && diff -burN android-openssl.orig android-openssl) > patches.chromium/my-new-change.patch 206 207 5) Re-run the script: 208 209 ./import_from_android.sh 210 211 Generally speaking, consider sending your patch directly to the Android 212 open-source review servers too. Once submitted there, you can update 213 the git commit in openssl-chromium.org and remove your local patch in 214 one new CL. 215
