xref: /external/chromium_org/third_party/openssl

Name: openssl
URL: http://openssl.org/source/
Version: 1.0.1e
License: BSDish
License File: openssl/NOTICE
License Android Compatible: yes
Security Critical: yes

Description:
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:

     https://groups.google.com/a/chromium.org/d/msg/chromium-dev/gmO3U9HLY3Y/RPGNiQ-NL-YJ

 - To implement net/tools/flip_server, a host-side tool. Read more about
   it at the following page:

     http://dev.chromium.org/spdy/running_flipinmemserver   

This means that the library must be built for these systems:

  Android/ARM
  Android/x86
  Linux/x86
  Linux/x86_64
  Darwin/x86
  Darwin/x86_64

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:

  ./import_from_android.sh

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:

      openssl/openssl.version
          Configuration file telling which upstream version of
          OpenSSL sources to use.

      openssl/patches/
          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.

      openssl/openssl.config
          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.

      openssl/import_openssl.sh
          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_openssl.sh 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:

    openssl-chromium.config
        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.

    patches.chromium/
        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_ import_openssl.sh is run to
        re-generate the final set of sources. This allows modifying the
        content of any Android configuration file easily.

    openssl.gyp
        A gyp build file for the library. Manually maintained, this file
        includes openssl.gypi below.

    openssl.gypi
        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.

    config/x64/openssl/opensslconf.h
        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.

    import_from_android.sh
        The top-level script that will automatically perform the full
        Chromium download + patching + import + auto-generation process.


More specifically, calling 'import_from_android.sh' 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 'import_openssl.sh' 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:

  x509_hash_name_algorithm_change.patch
    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. http://crbug.com/111045 is used
    to track this issue.

  enable-dtls1.patch:
    Enable DTLSv1, which is disabled by default in the Android platform
    configuration.

  x86_64_source_excludes.patch
    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.

  z_reduce_client_hello_size.patch
    Advertise support of only the NIST curves P-521, P-384, and P-256,
    as well as only uncompressed points, to keep ClientHello small.

  channelid.patch
    Add API so that channel ID private key can be set only after verifying the
    remote server supports channel IDs.

  fix_lhash_iteration.patch
    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 http://crbug.com/298606

  chacha.patch
    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
procedure:

  1) Use the --temp-dir option to download everything to a known directory
     (by default, import_from_android.sh downloads everything into a
     temporary directory that is erased when the script exits, even in
     case of error).

       ./import_from_android.sh --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 'import_openssl.sh'

  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:

      ./import_from_android.sh

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 openssl-chromium.org and remove your local patch in
one new CL.