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.

**************************************************************************
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.