#
# CDDL HEADER START
#
# The contents of this file are subject to the terms of the
# Common Development and Distribution License (the "License").
# You may not use this file except in compliance with the License.
#
# You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
# See the License for the specific language governing permissions
# and limitations under the License.
#
# When distributing Covered Code, include this CDDL HEADER in each
# file and include the License file at usr/src/OPENSOLARIS.LICENSE.
# If applicable, add the following below this CDDL HEADER, with the
# fields enclosed by brackets "[]" replaced with your own identifying
# information: Portions Copyright [yyyy] [name of copyright owner]
#
# CDDL HEADER END
#
# Copyright (c) 2009, 2015, Oracle and/or its affiliates. All rights reserved.
#
Build Layout
---
OpenSSL build is run four times. Once for regular dynamic non-fips, once
for static bits to link with standalone wanboot binary, once for fips-140,
and once for FIPS-140 canister (in the openssl-fips component)
needed to build FIPS-140 certified libraries. All builds apart from
static libraries for wanboot are done for 32 and 64 bits. So, in total, OpenSSL
is built seven times. OpenSSL for wanboot is only built on sparc.
See also comments in all the Makefiles for more information.
OpenSSL Version
--------------
The non-fips Build.
---
The non-fips build is the 'default' build of OpenSSL and includes the regular
binaries, libraries, man pages, and header files.
The fips Build
---
We are now shipping FIPS-140 certified OpenSSL with S11.2 and later.
The admin may choose to activate 'openssl-fips' implementation using 'pkg mediator'.
The wanboot Build
----
There are some significant differences when building OpenSSL for wanboot.
Some additional Configuration options are needed:
-DNO_CHMOD chmod not available in stand-alone environment
-DBOOT guard for wanboot specific patches
-DOPENSSL_NO_DTLS1 to avoid dtls1_min_mtu() - DTLS not used anyway
List of object files for wanboot-openssl.o
----
At this moment, object files for wanboot-openssl.o need to be listed explicitly.
This is cumbersome and relatively tedious with respect to upgrading to higher
version of openssl.
In future, it would be nice, if this could be performed automatically by the
linker. The required interface for wanboot is already defined in a mapfile and
linker option '-zdiscard-unused=sections,files' is already used to discard
unused code.
But sadly, at this moment when the linker is given all the object files, it
correctly discards some unused files, but references to undefined symbols from
the discarded files don't get discarded along. Later, these undefined references
cause wanboot linking failure.
In order to determine which openssl object files are required for wanboot,
first build static standalone openssl bits in Userland. As a site effect,
$ cd $USERLAND/components/openssl/openssl-default ; gmake build
Next, collect some information from linking wanboot static libraries in ON.
This can be done by the following hack.
$ touch wanboot.o
$ LD_OPTIONS="-Dfiles,symbols,output=ld.dbg \
WAN_OPENSSL=" -lwanboot -lssl -lcrypto" dmake all
The following sort of information ends up in ld.dbg (note that the debugging
output from the link-editor is not considered a 'stable interface' and may
change in the future):
debug: file=/builds/tkuthan/ul-wanboot-rebuilt/components/openssl/openssl-default/build/sparcv9-wanboot/libcrypto.a(sparcv9cap.o) [ ET_REL ]
debug:
debug: symbol table processing; file=/builds/tkuthan/ul-wanboot-rebuilt/components/openssl/openssl-default/build/sparcv9-wanboot/libcrypto.a(sparcv9cap.o) [ ET_REL ]
debug: symbol[1]=sparcv9cap.c
....
Now run the following script in Userland:
# set to workspace paths:
USERLAND=/builds/tkuthan/ul-wanboot-rebuilt
for i in `find $BUILD/crypto $BUILD/ssl -name '*.o'`
do
f=`basename $i`
if grep -q "^debug: file.*\<$f\>" $LD_DBG
then
echo $i | sed "s#$BUILD/##"
fi
done
to get the list of required object files.
Additionally, you can format the list for including to Makefile by:
sort | tr '\n' ' ' | fold -s -w74 | sed -e 's/^/ /' -e 's/$/\\/'
Linking with wanboot
----
When linking with wanboot please pay attention to following pitfalls.
Correct openssl header files need to be included. This is done in
Make sure CPPFLAGS point to the right directories.
EXTREME CAUTION needs to be employed, if WANBOOT GREW IN SIZE because of the
changes!
Wanboot is a statically linked standalone binary and it is loaded on a fixed
address before execution. This address is defined in
LOAD_SEGMENT text {
FLAGS = READ EXECUTE;
VADDR = 0x130000;
ASSIGN_SECTION {
TYPE = PROGBITS;
FLAGS = ALLOC !WRITE;
};
};
This address (VADDR) NEEDS TO BE GREATER THEN
size of wanboot binary + 0x4000
The reason for this is in how wanboot is loaded by OpenBoot Prom:
1) user initiates boot from network - "boot net"
2) obp loads wanboot binary at address 0x4000
3) obp parses ELF header, reads virtual address where to load wanboot to
4) obp mem-copies .text section to this address
5) obp copies .data section behind .text
6) obp starts executing wanboot at entry address
If the given address is too small, obp overwrites part of .data with
instructions from .text in step 4. resulting in .data being corrupted.
Initialized variables get bogus values and failure is inevitable.
This is very hard to troubleshoot.
Testing wanboot with new openssl
----
With every upgrade of OpenSSL, it is necessary to make sure wanboot builds and
works well with the new bits (post lullaby).
Provided you have a freshly built ON workspace, you can link wanboot with new
OpenSSL bits as follows:
# copy wanboot-openssl.o to ON build machine
# prepare to rebuild wanboot
cd $ON
# hack to force a rebuild
# modify Makefile and assign the WAN_OPENSSL macro to your binary
# something like
WAN_OPENSSL = /var/tmp/wanboot-openssl.o
# build a wanboot binary
build -i dmake all
Wanboot should build without warning.
If there is something like this in the output:
Undefined first referenced
symbol in file
CRYPTO_ccm128_setiv /var/tmp/wanboot-openssl.o
SSL_get_srtp_profiles /var/tmp/wanboot-openssl.o
ssl_parse_clienthello_use_srtp_ext /var/tmp/wanboot-openssl.o
CRYPTO_gcm128_setiv /var/tmp/wanboot-openssl.o
...
cmac_pkey_meth /var/tmp/wanboot-openssl.o
ld: fatal: symbol referencing errors. No output written to wanboot
*** Error code 1
dmake: Fatal error: Command failed for target `wanboot'
some additional work has to be done in OpenSSL to either satisfy the function
references listed in the linker error message, or to remove the calls to these
functions.
Finally, resulting wanboot binary shall be deployed on some install server and
wanbooting from this server shall be tested.
===============
Common Patches
===============
Common patch files are located in the components/openssl/common/patches dir,
and they are copied to both FIPS and non-FIPS 'patches' dir as soon as the
Makefile is parsed. The Common patch filename has prefix '0',
=========================
Non-FIPS specific Patches
=========================
Non-FIPS specific patch files are located in the
The Non-FIPS specific patch filename has prefix '1',
=========================
FIPS specific Patches
=========================
FIPS specific patch files are located in the
The FIPS specific patch filename has prefix '2',