Switch branches/tags
OS-5093 OS-5434 OS-5447 OS-6082 OS-7320 dev-bhyve eu-ams-1 grr-TOOLS-1807 master ncurses-test ntp release-20110901 release-20120528 release-20120626 release-20120712 release-20120726 release-20120809 release-20120823 release-20120906 release-20120920 release-20121004 release-20121101 release-20121115 release-20121129 release-20121213 release-20121227 release-20130110 release-20130124 release-20130207 release-20130221 release-20130307 release-20130321 release-20130404 release-20130418 release-20130502 release-20130515 release-20130530 release-20130613 release-20130627 release-20130711 release-20130725 release-20130822 release-20130905 release-20130919 release-20131003 release-20131017 release-20131031 release-20131128 release-20131212 release-20140109 release-20140123 release-20140206 release-20140220 release-20140307 release-20140320 release-20140403 release-20140417 release-20140501 release-20140515 release-20140529 release-20140612 release-20140626 release-20140703 release-20140710 release-20140724 release-20140807 release-20140821 release-20140904 release-20140918 release-20141002 release-20141016 release-20141030 release-20141113 release-20141127 release-20141211 release-20141225 release-20150108 release-20150122 release-20150205 release-20150219 release-20150305 release-20150319 release-20150402 release-20150416 release-20150430 release-20150514 release-20150528 release-20150611 release-20150625 release-20150709 release-20150723 release-20150806 release-20150820 release-20150903 release-20150917 release-20151001 release-20151015 release-20151029 release-20151112 release-20151126 release-20151210 release-20151224 release-20160107 release-20160121 release-20160204 release-20160218 release-20160303 release-20160317 release-20160331 release-20160414 release-20160428 release-20160512 release-20160526 release-20160609 release-20160625 release-20160707 release-20160721 release-20160804 release-20160818 release-20160901 release-20160915 release-20160929 release-20161013 release-20161027 release-20161110 release-20161124 release-20161208 release-20161222 release-20170105 release-20170119 release-20170202 release-20170216 release-20170302 release-20170316 release-20170330 release-20170413 release-20170427 release-20170511 release-20170525 release-20170608 release-20170622 release-20170706 release-20170720 release-20170803 release-20170817 release-20170831 release-20170914 release-20170928 release-20171012 release-20171026 release-20171109 release-20171123 release-20171207 release-20171221 release-20180104 release-20180118 release-20180201 release-20180215 release-20180301 release-20180315 release-20180329 release-20180412 release-20180426 release-20180510 release-20180524 release-20180607 release-20180621 release-20180705 release-20180719 release-20180802 release-20180816 release-20180830 release-20180913 release-20180927 release-20181011 release-20181025 release-20181108 release-20181122 release-20181206 us-west-2
Nothing to show
Find file History
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
..
Failed to load latest commit information.
Patches
engine_pkcs11
tools
Makefile
README.integration
install-sfw
install-sfw-64
openssl-1.0.2n.tar.gz
sunw_prefix.h

README.integration

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

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

MOST IMPORTANT OF ALL:

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.
BE CERTAIN THAT YOU HAVE UNDERSTOOD THE RAMIFICATIONS OF ANY UPGRADE!
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.