mirror of https://github.com/lukechilds/node.git
Browse Source
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>v1.8.0-commit
Shigeki Ohtsu
10 years ago
2 changed files with 191 additions and 0 deletions
@ -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. |
Binary file not shown.
Loading…
Reference in new issue