README.chromium - chromium/deps/openssl - Git at Google

 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.

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

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