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.

   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.

   paddingext.patch
   paddingext2.patch
     Add ClientHello padding to workaround bug in F5 terminators.

   stricter_cutthrough.patch
     Requires NPN and a PFS cipher suite to enable cut-through (false start) on
     the client.

   mac_osx32_assembly.patch
     Add support for 32 bit OS X with assembly optimization.

   fix_limit_checks.patch
     Fix limit checks in writing extensions. BUF_MEM_grow allocates 4/3 the size
     requested, so it doesn't overflow the actual allocation.

   reorder_extensions.patch
     Move the ECC extensions to the end of the ClientHello to work around a
     server bug. Some servers are intolerant to the last extension being empty.
     See https://crbug.com/363583

   export_certificate_types.patch
     Export the certificate_types field in CertificateRequest.

   send_client_verify_cleanup.patch
     Clean up ssl3_send_client_verify so the various cases (TLS 1.2, pre-TLS-1.2
     cases for each cipher suite) are less intertwined.

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

	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.

	paddingext.patch
	paddingext2.patch
	Add ClientHello padding to workaround bug in F5 terminators.

	stricter_cutthrough.patch
	Requires NPN and a PFS cipher suite to enable cut-through (false start) on
	the client.

	mac_osx32_assembly.patch
	Add support for 32 bit OS X with assembly optimization.

	fix_limit_checks.patch
	Fix limit checks in writing extensions. BUF_MEM_grow allocates 4/3 the size
	requested, so it doesn't overflow the actual allocation.

	reorder_extensions.patch
	Move the ECC extensions to the end of the ClientHello to work around a
	server bug. Some servers are intolerant to the last extension being empty.
	See https://crbug.com/363583

	export_certificate_types.patch
	Export the certificate_types field in CertificateRequest.

	send_client_verify_cleanup.patch
	Clean up ssl3_send_client_verify so the various cases (TLS 1.2, pre-TLS-1.2
	cases for each cipher suite) are less intertwined.

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