Skip to content
This repository has been archived by the owner on Apr 22, 2023. It is now read-only.

OpenSSL upgrade process

Jump to bottom
Julien Gilli edited this page Apr 13, 2015 · 30 revisions

Introduction

Node.js depends on the OpenSSL library to implement its crypto, TLS/SSL and HTTPS features.

However, Node.js doesn't use OpenSSL's standard build process. Instead, a custom build process based on GYP that uses OpenSSL's source is maintained in parallel of OpenSSL's original build process. In addition to that, because the state of OpenSSL's support for Node.js supported platforms varies over time, it is sometimes necessary to maintain additional patches that fix some important issues.

For these two reasons, upgrading the OpenSSL version used by Node.js is not trivial. Some knowledge of how OpenSSL is built and embedded within the node binary and of the existing floating patches is necessary. This document describes both of these aspects so that upgrading the OpenSSL version used by a given version of Node.js does not have to be done by the few people with such knowledge.

The information in this document is valid for Node.js versions v0.10.x and v0.12.x.

Floating patches

Following is the list of the current patches that are floated on top of OpenSSL's source:

  • 2b21c45f75043f8e5728650e24a4e972ade18cf1. deps: separate sha256/sha512-x86_64.pl for openssl. This change is needed because Node.js' GYP-based build system cannot use the same PERL script to generate different implementations by passing different command line parameters like the original OpenSSL build system does.
  • 7817fbd692120887619d07228882dd19461109b6. deps: fix openssl assembly error on ia32 win32.
  • c4b9be7c5a97b9cac99cd599dbd995da556a5a17. openssl: replace symlinks by #include shims. As stated by the commit message, Git for Windows cannot create symlinks, so symlink sources are replaced by headers that #include the symlinks' targets instead.
  • 6b97c2e98627b5189e01b871f9130b5efc41988d. openssl: fix keypress requirement in apps on win32. Node.js uses openssl's s_client program to run some of its tests. However, this program requires the user to press a key to continue, which makes Node.js' tests time out. This change makes it continue without needing any user interaction.

How Node.js builds its OpenSSL dependency

The OpenSSL dependency is present at deps/openssl. It does not only contain the vanilla OpenSSL source tree, but is instead a "wrapper" that uses a custom build system (openssl.gyp and buildinf.h), pre-built assembly files (in asm) and a centralized configuration header file (in config).

Following are more detailed informations about some of the important files and directories in deps/openssl:

  • openssl/: This directory is the vanilla OpenSSL directory. When upgrading, one overwrites this directory with the content of an OpenSSL release tarball. All the other files in deps/openssl that are not in deps/openssl/openssl are custom and modified in some way by the Node.js project.
  • asm/: This directory contains the assembly files generated by the custom Makefile in the same directory. This Makefile is basically a port of every Makefile found in every subdirectory of deps/openssl/openssl (the vanilla OpenSSL source tree) that contains a cipher implementation. The assembly files generated are created in subdirectories for each supported architecture.
  • buildinf.h and config/: config/opensslconf.h was added so that binary add-on developers could rely on one single header configuration file instead of having to include different configuration file depending on the current platform.
  • openssl.gyp: This file is included by Node.js' master build file and more or less replicates the behavior of OpenSSL's original build system.
Clone this wiki locally