deps: add docs to upgrade openssl
This document is intended to describe the procedure to upgrade openssl from 1.0.1m to 1.0.2a in io.js. Fixes: https://github.com/iojs/io.js/issues/589 PR-URL: https://github.com/iojs/io.js/pull/1389 Reviewed-By: Fedor Indutny <fedor@indutny.com> Reviewed-By: Ben Noordhuis <info@bnoordhuis.nl>
This commit is contained in:
Shigeki Ohtsu
Родитель
deb9d23d7b
Коммит
4830b4bce8
|
|
@ -0,0 +1,191 @@
|
|||
## How to upgrade openssl library in io.js
|
||||
|
||||
This document describes the procedure to upgrade openssl from 1.0.1m
|
||||
to 1.0.2a in io.js.
|
||||
|
||||
|
||||
### Build System and Upgrading Overview
|
||||
The openssl build system is based on the `Configure` perl script in
|
||||
`deps/openssl/openssl`. For example, running `Configure linux_x86-64`
|
||||
in the openssl repository generates `Makefile` and `opensslconf.h` for
|
||||
the linux_x86_64 target architecture.
|
||||
|
||||
The `Makefile` contains the list of asm files which are generated by
|
||||
perl scripts during build so that we can get the most of use of the
|
||||
hardware performance according to the type of cpus.
|
||||
|
||||
`Configure TABLE` shows various build parameters that depend on each
|
||||
os and arch.
|
||||
|
||||
In io.js, build target is defined as `--dest-os` and `--dest-cpu` in
|
||||
configure options which are different from the one that is defined in
|
||||
openssl and it's build system is gyp that is based on python,
|
||||
therefore we cannot use the openssl build system directly.
|
||||
|
||||
In order to build openssl with gyp in iojs, files of opensslconf.h and
|
||||
asm are generated in advance for several supported platforms.
|
||||
|
||||
Here is a map table to show conf(opensslconf.h) and asm between
|
||||
the openssl target and configuration parameters of os and cpu in iojs.
|
||||
The tested platform in CI are also listed.
|
||||
|
||||
| --dest-os | --dest-cpu | conf | asm | openssl target | CI |
|
||||
|---------- |----------- |----- |----- |------------------- |--- |
|
||||
| linux | ia32 | o | o |linux-elf | o |
|
||||
| linux | x32 | o | x(*2)|linux-x32 | x |
|
||||
| linux | x64 | o | o |linux-x86_64 | o |
|
||||
| linux | arm | o | o |linux-arm | o |
|
||||
| linux | arm64 | o | o |linux-aarch64 | o |
|
||||
| mac | ia32 | o | o |darwin-i386-cc | - |
|
||||
| mac | x64 | o | o |darwin64-x86_64-cc | o |
|
||||
| win | ia32 | o | o(*3)|VC-WIN32 | x |
|
||||
| win | x64 | o | o |VC-WIN64A | o |
|
||||
| solaris | ia32 | o | o |solaris-x86-gcc | o |
|
||||
| solaris | x64 | o | o |solaris64-x86_64-gcc| o |
|
||||
| freebsd | ia32 | o | o |BSD-x86 | o |
|
||||
| freebsd | x64 | o | o |BSD-x86_64 | o |
|
||||
| openbsd | ia32 | o | o |BSD-x86 | x |
|
||||
| openbsd | x64 | o | o |BSD-x86_64 | x |
|
||||
| others | ia32 | x(*1)| o | - | x |
|
||||
| others | x64 | x(*1)| o | - | x |
|
||||
| others | arm | x(*1)| o | - | x |
|
||||
| others | arm64 | x(*1)| o | - | x |
|
||||
| others | others | x(*1)| x(*2)| - | x |
|
||||
|
||||
- (*1) use linux-elf as a fallback configuration
|
||||
- (*2) no-asm used
|
||||
- (*3) currently masm (Microsoft Macro Assembler) is used but it's no
|
||||
longer supported in openssl. We need to move to use nasm or yasm.
|
||||
|
||||
All parameters such as sources, defines, cflags and others generated
|
||||
in openssl Makefile are written down into `deps/openssl/openssl.gypi`.
|
||||
|
||||
The header file of `deps/openssl/openssl/crypto/opensslconf.h` are
|
||||
generated by `Configure` and varies on each os and arch so that we
|
||||
made a new `deps/openssl/config/opensslconf.h`, where it includes each
|
||||
conf file from `deps/openssl/config/archs/*/opensslconf.h` by using
|
||||
pre-defined compiler macros. This procedure can be processed
|
||||
automatically with `deps/openssl/config/Makefile`
|
||||
|
||||
Assembler support is one of the key features in openssl, but asm files
|
||||
are dynamically generated with
|
||||
`deps/openssl/openssl/crypto/*/asm/*.pl` by perl during
|
||||
build. Furthermore, these perl scripts check the version of assembler
|
||||
and generate asm files according to the supported instructions in each
|
||||
compiler.
|
||||
|
||||
Since perl is not a build requirement in iojs, they all should be
|
||||
generated in advance and statically stored in the repository. We
|
||||
provide two sets of asm files, one is asm_latest(avx2 and addx
|
||||
supported) in `deps/openssl/asm` and the other asm_obsolete(without
|
||||
avx1/2 and addx) in `deps/openssl/asm_obsolute`, which depends on
|
||||
supported features in assemblers. Each directory has a `Makefile`
|
||||
to generate asm files with perl scripts in openssl sources.
|
||||
|
||||
`configure` and gyp check the version of assemblers such as gnu
|
||||
as(gas), llvm and Visual Studio. `deps/openssl/openssl.gypi`
|
||||
determines what asm files should be used, in which the asm_latest
|
||||
needs the version of gas >= 2.23, llvm >= 3.3 or MSVS_VERSION>='2012'
|
||||
(ml64 >= 12) as defined in
|
||||
https://github.com/openssl/openssl/blob/OpenSSL_1_0_2-stable/crypto/sha/asm/sha512-x86_64.pl#L112-L129,
|
||||
otherwise asm_obsolete are used.
|
||||
|
||||
The following is the detail instruction steps how to upgrade openssl
|
||||
version from 1.0.1m to 1.0.2a in iojs.
|
||||
|
||||
### 1. Replace openssl source in `deps/openssl/openssl`
|
||||
Remove old openssl sources in `deps/openssl/openssl` .
|
||||
Get original openssl sources from
|
||||
https://www.openssl.org/source/openssl-1.0.2a.tar.gz and extract all
|
||||
files into `deps/openssl/openssl` .
|
||||
|
||||
### 2. Apply private patches
|
||||
There are three kinds of private patches to be applied in openssl-1.0.2a.
|
||||
|
||||
- The two fixes of assembly error on ia32 win32. masm is no longer
|
||||
supported in openssl. We should move to use nasm or yasm in future
|
||||
version of iojs.
|
||||
|
||||
- The fix of openssl-cli built on win. Key press requirement of
|
||||
openssl-cli in win causes timeout failures of several tests.
|
||||
|
||||
- Backport patches for alt cert feature from openssl-1.1.x. Root certs
|
||||
of 1024bit RSA key length were deprecated in io.js. When a tls
|
||||
server has a cross root cert, io.js client leads CERT_UNTRUSTED
|
||||
error because openssl does not find alternate cert chains. This fix
|
||||
supports its feature but was made the current master which is
|
||||
openssl-1.1.x. We backported them privately into openssl-1.0.2 on
|
||||
iojs.
|
||||
|
||||
### 3. Replace openssl header files in `deps/openssl/openssl/include/openssl`
|
||||
all header files in `deps/openssl/openssl/include/openssl/*.h` are
|
||||
symbolic links in the distributed release tar.gz. They cause issues in
|
||||
Windows. They are replaced into the files to include a real header
|
||||
file such as
|
||||
````
|
||||
#include "../../crypto/aes/aes.h"
|
||||
````
|
||||
### 4. Change `opensslconf.h` so as to fit each platform.
|
||||
The opensslconf.h in each target was created in advance by typing
|
||||
`deps/openssl/openssl/Configure {target}` and copied
|
||||
into `deps/openssl/conf/archs/{target}/opensslconf.h`.
|
||||
`deps/openssl/conf/openssconf.h` includes each file according to its
|
||||
target by checking pre-defined compiler macros. These can be generated
|
||||
by using `deps/openssl/conf/Makefile`
|
||||
|
||||
We should remove OPENSSL_CPUID_OBJ define in opensslconf.h because it
|
||||
causes build error when --openss-no-asm option is specified. Instead,
|
||||
the OPENSSL_CPUID_OBJ is defined in `deps/openssl/openssl.gypi`
|
||||
according to the configure options.
|
||||
|
||||
One fix of opensslconf.h is needed in 64-bit MacOS.
|
||||
The current openssl release does not use RC4 asm since it explicitly
|
||||
specified as `$asm=~s/rc4\-[^:]+//;` in
|
||||
https://github.com/openssl/openssl/blob/OpenSSL_1_0_1-stable/Configure#L584
|
||||
But iojs has used RC4 asm on MacOS for long time. Fix type of RC4_INT
|
||||
into `unsigned int` in opensslconf.h of darwin64-x86_64-cc to work on
|
||||
the RC4 asm.
|
||||
|
||||
### 5. Update openssl.gyp and openssl.gypi
|
||||
Sources, cflags and define parameters that depends on each target can
|
||||
be obtained via `Configure TABLE`. Its list is put in the table of
|
||||
[define and cflags changes in openssl-1.0.2a](openssl_define_list.pdf)
|
||||
|
||||
There is no way to verify all necessary sources automatically. We can
|
||||
only carefully look at the source list and compiled objects in
|
||||
Makefile of openssl and compare the compiled objects that stored
|
||||
stored under `out/Release/obj.target/openssl/deps/openssl/' in iojs.
|
||||
|
||||
### 6. ASM files for openssl
|
||||
We provide two sets of asm files. One is for the latest assembler
|
||||
and the other is the older one.
|
||||
|
||||
### 6.1. asm files for the latest compiler
|
||||
This was made in `deps/openssl/asm/Makefile`
|
||||
- Updated asm files for each platforms which are required in
|
||||
openssl-1.0.2a.
|
||||
- Some perl files need CC and ASM envs. Added a check if these envs
|
||||
exist. Followed asm files are to be generated with CC=gcc and
|
||||
ASM=nasm on Linux. See
|
||||
`deps/openssl/openssl/crypto/sha/asm/sha512-x86_64.pl`
|
||||
- Added new 32bit targets/rules with a sse2 flag (OPENSSL_IA32_SSE2)
|
||||
to generate asm for use SSE2.
|
||||
- Generating sha512 asm files in x86_64 need output filename which
|
||||
has 512. Added new rules so as not to use stdout for outputs.
|
||||
- PERLASM_SCHEME of linux-armv4 is `void` as defined in openssl
|
||||
Configure. Changed its target/rule and all directories are moved
|
||||
from arm-elf-gas to arm-void-gas.
|
||||
- add a new rule for armv8 asm generation
|
||||
|
||||
With export environments of CC=gcc and ASM=nasm, then type make
|
||||
command and check if new asm files are generated.
|
||||
|
||||
### 6.2.asm files for the older compiler
|
||||
For older assembler, the version check of CC and ASM should be
|
||||
skipped in generating asm file with perl scripts.
|
||||
Copy files from `deps/openssl/asm` into
|
||||
`deps/openssl/asm/asm_obsolete` and change rules to generate asm files
|
||||
into this directories and remove the check of CC and ASM envs.
|
||||
|
||||
Without environments of CC and ASM, then type make command and check
|
||||
if new asm files for older compilers are generated.
|
||||
Двоичный файл не отображается.
Загрузка…
Ссылка в новой задаче