blob: 9abfa8d42080d1f46c2e54988159046aa5d51cce [file] [log] [blame]
Name: openssl
Version: 1.0.1e
License: BSDish
License File: openssl/NOTICE
License Android Compatible: yes
Security Critical: yes
This is OpenSSL, the standard SSL/TLS library, which is used *only* in
the following cases:
- For Chrome/Chromium, only on Android to implement SSL/TLS support
(while certificate validation is performed through the platform APIs),
instead of using NSS as on other Linux-based operating systems.
Note that there is no plans to support OpenSSL in Chromium on other
platforms. For more context, please read:
- To implement net/tools/flip_server, a host-side tool. Read more about
it at the following page:
This means that the library must be built for these systems:
Whenever you change it, try to rebuild Chromium for all these systems.
Automatic generation of source tree.
Most of the sources in this directory are auto-generated and come from
the Android version of the OpenSSL sources, with a few Chromium-specific
patches applied.
Said Android sources are themselves a patched subset of the official
OpenSSL release sources, generated by a special import script.
To update the sources for Chromium, one has to modify
openssl-chromium.config or the content of patches.chromium/ then run:
Before doing that, you should understand how everything works:
1) Android-specific files are taken from a given commit from the
AOSP git servers. See how 'openssl-chromium.config' defines the
following variables:
ANDROID_OPENSSL_GIT_SOURCE -> point to source git server.
ANDROID_OPENSSL_GIT_COMMIT -> point to git commit
2) All downloaded Android-specific files are placed under the openssl/
sub-directory. The most important files are the following:
Configuration file telling which upstream version of
OpenSSL sources to use.
Directory containing several Android-specific patches to
apply to the official OpenSSL sources to create the
Android ones. See openssl/patches/README for a description
of what each of these patches do.
Configuration file describing which build-time options
to enable, what patches to apply, which source files to compile
(including CPU architecture-specific variants), and which
sources to keep in the final source directory.
Import script used to regenerate all other Android-specific
source files, based on the configuration files above
and a tarball of the official OpenSSL source release.
For example, to rebuild the full Android source tree (without any
Chromium patches), one would do something like:
cd openssl/
./ import /path/to/openssl-<version>.tar.gz
where <version> matches the definition found in 'openssl.version'.
3) Chromium adds a few of its own files:
Configuration file which indicates:
- The reference Android OpenSSL git repository and commit.
- The download location of official OpenSSL source tarballs.
- The corresponding SHA-1 sum, for sanity checking.
A set of additional patches to apply to the openssl/ tree
after it has been downloaded from the Android git repository.
These patches are applied _before_ is run to
re-generate the final set of sources. This allows modifying the
content of any Android configuration file easily.
A gyp build file for the library. Manually maintained, this file
includes openssl.gypi below.
An *auto-generated* gyp include file that contains the required
definitions used to describe the library's sources to the
Chromium build system. Its content mirrors openssl/openssl.config
in a gyp-compatible way.
Another *auto-generated* file used for 64-bit builds of the library
only. This is required for correctness because the Android sources
only come with a single generic header which is tailored for
32-bit builds. Using the latter results either in a broken build,
or even worse, in a library that doesn't work correctly.
The content of this file is a simple copy of
openssl/include/openssl/opensslconf.h, with a few lines
altered to reflect that the target has 64-bit types.
The top-level script that will automatically perform the full
Chromium download + patching + import + auto-generation process.
More specifically, calling '' will do the following:
1) Download a specific Android commit from AOSP git servers to openssl/
2) Download the corresponding official OpenSSL release tarball.
3) Sainty check its SHA-1 against a hard-coded value.
4) Apply chromium-specific patches.
5) Re-run the Android '' script.
6) Auto-generate config/x64/openssl/opensslconf.h
7) Auto-generate openssl.gypi
Once the script is done, all you need to do is launch gyp again, rebuild
and run unit tests. Use the --verbose option to see what the script does,
or --help to see a detailed scription and a list of valid options.
Chromium-specific patches:
The list of Chromium-specific patches to apply to the Android tree is
located in patches.chromium/. Currently this consists of:
Ensure the library can find the right files under /etc/ssl/certs when
running on older systems.
There are many symbolic links under /etc/ssl/certs created by using
hash of the PEM certificates in order for OpenSSL to find those
certificates. Openssl has a tool to help you create hash symbolic
links (tools/c_rehash). However newer versions of the library changed
the hash algorithm, which makes it unable to run properly on systems
that use the old /etc/ssl/certs layout (e.g. Ubuntu Lucid).
This patch gives a way to find a certificate according to its hash by
using both the old and new algorithms. is used
to track this issue.
Enable DTLSv1, which is disabled by default in the Android platform
Exclude the source files bn_asm.c and rc4_skey.c for x86_64 because
they are replaced by x86_64-gcc.c and rc4-x86_64.S.
Advertise support of only the NIST curves P-521, P-384, and P-256,
as well as only uncompressed points, to keep ClientHello small.
Add API so that channel ID private key can be set only after verifying the
remote server supports channel IDs.
Fix a crash that happens when OpenSSL tries to delete items from a lhash
table that is being iterated over. This happens in certain rare cases
when SSL_CTX_flush_sessions() is called. See
Add support for ChaCha20+Poly1305 cipher suites.
Adding new Chromium patches:
In the event you need to add a new Chromium-specific patch, follow this
1) Use the --temp-dir option to download everything to a known directory
(by default, downloads everything into a
temporary directory that is erased when the script exits, even in
case of error).
./ --temp-dir=/tmp/aaa
2) Save the "original" Android sources:
cp -rp /tmp/aaa/build/android-openssl /tmp/aaa/build/android-openssl.orig
3) Modify the content of /tmp/aaa/build/android-openssl appropriately.
You do *not* have to run ''
4) Create new patch:
(cd /tmp/aaa/build && diff -burN android-openssl.orig android-openssl) > patches.chromium/my-new-change.patch
5) Re-run the script:
Generally speaking, consider sending your patch directly to the Android
open-source review servers too. Once submitted there, you can update
the git commit in and remove your local patch in
one new CL.