Switch branches/tags
Find file History
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


OpenSSL 1.x illumos-extra Integration Notes

There are several changes made to OpenSSL that are worth highlighting for
the benefit of anyone wishing to upgrade or further modify the installation.
Generally, they are:

- The addition of a "hw_pk11" engine, written by Sun for 0.9.x, that
  supports various HW accelerators that have KCF drivers.  It is highly
  unlikely at this point that anyone actually cares about this.  There are a
  few minor changes to hook this into the library, as well as the various
  files themselves that implement the engine and are simply copied in.
  There are no changes required to the build system in order to make this

- New smartos-* build targets.  These are patched into Configure as
  templates.  These templates are later filled in by trivial sed rules in
  the build system to generate a configure (lower-case) that we then use to
  actually set up the links.  This allows us to control variables such as CC
  and CFLAGS in the usual way, and to treat the OpenSSL configuration system
  as if it were autoconf even though it's nothing of the sort.

- Changes to Configure, the assembly generators/translators, and the
  addition of a header file to effect prefixing of globally visible function
  symbol names.

- Changes to opensslconf.h.in, which is transformed into opensshconf.h
  and delivered.  This header defines data types used in the
  implementations of algorithms along with which algorithms have been
  built and several other pieces of metadata.  Because OpenSSL does not
  include proper multilib support and instead assumes that the libraries
  and headers that are generated will be used on the build system, this
  doesn't work well in our multilib environment.  Rather than patching the
  header after it's generated (which is basically impossible, since there
  are so many differences between 32-bit and 64-bit), we instead modify it
  in advance to support both.  We then remove Configure's ability to
  modify those portions of the header during the build.  The introduction
  of new algorithms whose preprocessor definitions or parameters differ
  between 32-bit and 64-bit implementation will require further changes in
  this area.

- Minor changes to eliminate warnings so that we can build with -Wall
  -Werror.  Fixes for these should be accumulated if required, and sent
  upstream where possible.

If you are upgrading, it is likely that simply replacing the tarball and
modifying VER in the makefile will suffice.  The changes to most of the
above are targeted at areas of the code that are unlikely to be changed,
especially to fix security bugs.  One other thing to be aware of is that if
the library numbering (the portion of the filename after '.so') changes, you
will also need to change LIBVER.  There is also a possibility that changes
to the library may break the hw_pk11 engine.  For example, from 0.9.x to
1.x, the aes-ctr NIDs were added, making some of the code redundant.
Porting this code should not be a great deal of work, but if it becomes so,
it is probably best to delete it.

When upgrading, you will need to be sure that no new symbols have been
introduced.  If any have been, it will be necessary to add them to
sunw_prefix.h.  Unfortunately, the public interface to OpenSSL is not really
defined anywhere, so making a proper mapfile is difficult and every new
symbol, even those that are not intended for public use, must be added
there.  A tool is included that can generate an appropriate header from an
OpenSSL library built from unmodified code; however, it will then be
necessary to append the Sun pk11 engine symbols to that.

Also, the prefixing of symbol names can confuse foreign software that
makes assumptions about the names of symbols in the libraries.  The most
common culprit here is GNU autoconf (and configure scripts that use it);
there are several macros that are designed to check for symbols in a
library without bothering to include any of the headers necessary to
actually use the library.  These will need to be fixed up in any
software that consumes OpenSSL in illumos-extra.  This does not affect
ON, nor any other software that simply consumes OpenSSL in the
documented manner.

The libraries as delivered are not, and are not intended to be,
compatible with consumers built against 0.9.8.  In addition to the
inherent changes to OpenSSL itself, the symbol prefixing and our
simplification of algorithm selection (namely, the adoption of the
standard implementations the OpenSSL Configure script would choose based
on our hardware architecture) have altered the binary interfaces.  The
use of the bootstrap proto area allows arbitrary incompatible changes
here -- the libraries we deliver are used only by software in the


This software is absolutely critical to the security of our customers'
information.  Do not upgrade this package on a whim.  If a security fix
necessitates an upgrade, take the time to understand what has changed
and how it will interact with our build environment and consumers.  It
may be preferable to apply a patch rather than do a wholesale upgrade if
that avoids complex interactions with our changes.   While these changes
have been designed to avoid conflict with likely changes in OpenSSL,
there are several classes of change that would inherently necessitate
minor additional integration work in order for them to work correctly.
It is not sufficient that updating the tarball and bumping VERSION
builds successfully; despite the checks that are in place to prevent
errors, it is still important that you read the release notes, change
logs, and diffs to ensure proper integration.  The "unique" build
environment we have here is unfortunately more costly than usual to
maintain, but this software also has unusual importance both in the
number of consumers and the critical nature of the functionality it
provides.  If there is anywhere to spend the time getting it right, it
is here.  Don't take shortcuts.