3/1/03 Version 0.8 Binary distributions of the OpenSAML code are available as part of the Shibboleth project. Information on obtaining and installing binaries can be found at http://shibboleth.internet2.edu/ JAVA There are a fairly large number of dependent Java class libraries required to build the opensaml.jar file, but all the needed jars are currently included in CVS. A Java source distribution is not currently available, but the binaries can be built easily by checking out the code from CVS and running Ant. You can obtain Ant from http://jakarta.apache.org/ant/ The following commands will check out and build this release of OpenSAML: $ cvs -d:pserver:anoncvs@cvs.internet2.edu:/home/cvs/shibboleth login $ cvs -d:pserver:anoncvs@cvs.internet2.edu:/home/cvs/shibboleth co -r Rel_0_8 opensaml $ cd opensaml/java $ ant dist The JavaDocs can be generated with the following command: $ ant javadocs Make sure that opensaml.jar and all the jars in the lib folder are in your classpath when using the classes. Some of the classes also depend on a Servlet 2.2 environment and should work in any compliant J2EE server. C++ Building and using the C++ version requires a fair bit of effort because of numerous dependent libraries and the need to use a version of gcc/g++ that does not ship with most older Linux or Unix versions. Also note that C++ lacks a stable binary interface, which means that in almost all cases, the same compiler must be used to build all the libraries that will eventually be linked to OpenSAML. Any version of gcc 3.0-3.2 will work, but the same version must be used throughout, and the corresponding version of libstdc++ must be present on any machine where the code will be used. The astute observer will note that every release of gcc since 3.0 contains a new version of libstdc++.so with a new version number on the end. This means you can generally install package updates to libstdc++ without overwriting any earlier releases. On the other hand, installing gcc updates can be much more destructive, since they often overwrite your system compiler and sometimes even libc. You may wish to build on one machine you can update the compiler on, and simply install libgcc and libstd++ packages on other hosts. What follows is a non-exhaustive, probably less than complete or 100% correct example of how to obtain and build versions of all the needed libraries and OpenSAML. This is merely a guide, and does not capture all the potential problems one might encounter. One must also be prepared to adapt to pre-existing software or machine quirks, and as with all open source software, "go with the flow". Don't just start asking questions when something fails, until you've explored the error and tinkered a bit. Also try and refer to the particular package's web site and support vehicles before assuming it's a problem specific to OpenSAML. We have not modified any code of any dependent package! We have in one case provided a custom tarball that contains a corrected configure script because the default distribution is broken, but the package's code itself is unmodified. In another case, a patch exists to fix a bug in Xerces 2.1, but it's only really needed for Shibboleth to work, not OpenSAML. Platforms The code is tested on Red Hat Linux 7.2 and 7.3 and Solaris 2.6, 8, and 9. Other Solaris and Linux versions probably work. Other Unix systems might work with some porting effort. Feedback and code or build changes are welcome but may not be immediately incorporated. To port, start with ./configure as described below, and see what happens! Windows will eventually be supported. The code currently is buildable with Visual C++ 6.0, but it's not an official part of the project yet. You'll see workspace and project files in the CVS that should provide a starting point. None of the dependencies are dealt with, so you'll have to change the paths and all that stuff manually in the IDE. When you see an OS in parentheses below (eg. (Linux)) that's a note that applies only to that platform. Compilers Currently, only gcc/g++ are used in our development and testing on Unix. Visual C++ 6.0 is used on Windows. We have done some work with other compilers (notably Sun/Forte Workshop on Solaris), but issues remain. One common issue is that even with the very new version of libtool we include in the distribution, it's often necessary to set the LD environment variable to your C++ compiler's link command, to make linking work properly when building any of the C++ packages. OK, ready? Dive in...each piece is headed by a ****** title block so you can scan for those. The following assumptions are made in the configure commands, and should be modified to suit your needs: The components are to be built and installed to /opt/shibboleth to avoid interference from preinstalled, older versions of libraries. This is very crucial on Linux, where some of these libraries will almost certainly exist in /usr/lib (and will be too old). ******* gcc/g++ ******* You must use version 3.0 or newer. (RH Linux 7.2/7.3) The easiest way to get a new gcc without destroying your existing gcc, which is very likely 2.96 or thereabouts, is to update to 3.04 via the Red Hat 7.2 update RPMs for gcc, g++, libgcc, and libstdc++, and all the related development packages. The reason is that the 3.04 RPMs install gcc and g++ as gcc3 and g++3 alongside your old compilers. Newer versions like 3.1 and 3.2 install over top of your system's gcc, which you may not like. To get these RPMs, look in ftp://ftp.rpmfind.net/linux/redhat/updates/7.2/en/os/i386/ Note that when you're building with that 3.04 package, you should set your CC and CXX environment variables to gcc3 and g++3 respectively or you will get errors while building the C++ code. Do not mix compilers, ever! (Solaris) Since Solaris doesn't come with gcc at all, you could build it from source or download a binary package from www.sunfreeware.com. Packages for 3.2 that use the Sun linker are available, and are highly recommended. If you build from source, you probably will have to direct it at Sun's linker and not use GNU ld. ******* OpenSSL ******* Aside from the information below, the thing you need to keep in mind here is that a lot of packages below, and other important packages in the open source world, use OpenSSL. If you're going to run them in the same process with one another, then you have to build consistently against one version. For example, if you're using OpenSAML inside of, say, Apache+mod_ssl, you will need to reconfigure and rebuild mod_ssl if you're using a binary version of OpenSAML built with a newer version of OpenSSL. Many packages linked to OpenSSL will reveal the version they used if you run the ldd command on them, since OpenSSL's shared libraries are (incorrectly) stamped with a version suffix that matches the OpenSSL version. If you see 0.9.6 and you want to use 0.9.7 below, you'll need to rebuild. (RH Linux) OpenSSL is fairly core on Linux, and you should probably update via Red Hat's update RPMs, which technically aren't the most current, but they work and are patched. We've built against the standard 0.9.6 revision from Red Hat. Also note that Red Hat stamps a different version on their build, so you tend to get libssl.so.1 or libssl.so.2 instead of libssl.so.0.9.6, which means you have to be conscious of what you have on your system. Sadly, sometimes even renaming or symlinking them will work. (Solaris) We suggest version 0.9.7a or greater, because of a problem in the library we use for XML Signatures. http://www.openssl.org/source/openssl-0.9.7a.tar.gz $ tar xvzf openssl-0.9.7a.tar.gz $ cd openssl-0.9.7a $ ./config --prefix=/opt/shibboleth threads shared $ make $ make install ******* libcurl ******* We now prefer version 7.10.3, though some autoconf support exists to compile against older versions. (RH Linux) There are usually pretty recent RPMs available from the Curl web site, but you'll find you have to install both curl-devel and curl packages to avoid dependency problems. You might want to just build from source into your build tree and ignore the preinstalled version. To install the latest RPMs at time of writing: $ rpm -Uvh http://curl.haxx.se/download/curl-ssl-7.10.3-1.i386.rpm \ http://curl.haxx.se/download/curl-ssl-devel-7.10.3-1.i386.rpm To build from source, see Solaris below. (Solaris) The latest code is http://curl.haxx.se/download/curl-7.10.3.tar.gz To build: $ tar xvzf curl-7.10.3.tar.gz $ cd curl-7.10.3 $ ./configure --without-ca-bundle --enable-static=no --with-ssl= \ --prefix=/opt/shibboleth $ make $ make install ******************************** libuuid/e2fsprogs (Solaris only) ******************************** Most or all Linux distros come with Ted T'so's ext2 file system utilities, which includes a UUID-generating library. If you've got a libuuid from his package, you're fine. For others, you'll need to get this package and build at least that much of it. We're working on extracting the code out, but this is required for now. Note that OpenSAML won't build against libdce at this point. If any poor souls out there are still stuck with DCE, and would like to use that UUID code, let us know. Also, be warned, this is the most awkward part of the build. As far as I can tell, the latest e2fsprogs won't even build properly on Solaris. If you follow these directions, it will build "enough". Sorry, best I can say. http://osdn.dl.sourceforge.net/sourceforge/e2fsprogs/e2fsprogs-1.32.tar.gz $ tar xvzf e2fsprogs-1.32.tar.gz $ cd e2fsprogs-1.32 $ ./configure --prefix=/opt/shibboleth --enable-elf-shlibs $ make This will generate errors but libuuid will be built. Now install it manually: $ cd lib/uuid $ make install $ mkdir /opt/shibboleth/include/uuid $ cp uuid.h /opt/shibboleth/include/uuid ******* log4cpp ******* Your first C++ foray. Don't worry, it won't be too painful. This is the one where you'll need our tarball to get a Solaris build to work. Just use it for Linux as well. This project is not in a stable state. We're using a snapshot release. http://wayf.internet2.edu/shibboleth/log4cpp-0.3.4b.tar.gz $ tar xvzf log4cpp-0.3.4b.tar.gz $ cd log4cpp-0.3.4b $ ./configure --prefix=/opt/shibboleth --with-pthreads=yes --enable-static=no \ --enable-doxygen=no $ make $ make install ****** Xerces ****** We're on version 2.1 (and that's the only one you can use). This takes a while to build, so grab your coffee here once make is underway. Make sure you set XERCESCROOT as appropriate below (the sample shows a build in a home directory). Also set the -x and -c switches as needed to specify your compilers to runConfigure. http://xml.apache.org/dist/xerces-c/stable/xerces-c-src2_1_0.tar.gz $ tar xvzf xerces-c-src2_1_0.tar.gz $ cd xerces-c-src2_1_0/src/xercesc $ setenv XERCESCROOT ~/xerces-c-src2_1_0 There's a patch that needs to be applied to one source file to fix a bug in the regular expression parser. This bug is fixed in future versions of Xerces, which will be incoporated in time for the 1.0 release. The patch is described here: http://marc.theaimsgroup.com/?l=xerces-c-dev&m=103460586830158&w=2 The file to be modified is: xerces-c-src2_1_0/src/xercesc/util/regx/RegularExpression.cpp Two lines of code must be modified as shown in the patch message. You only need this patch to use Shibboleth. OpenSAML doesn't use any of the regular expression code directly. (Linux) $ ./runConfigure -p linux -c gcc3 -x g++3 -r pthread -b 32 -P /opt/shibboleth $ make $ make install $ ln -s /opt/shibboleth/lib/libxerces-c.so.21 /opt/shibboleth/lib/libxerces-c.so (Solaris) $ ./runConfigure -p solaris -c gcc -x g++ -r pthread -b 32 -P /opt/shibboleth $ make $ make install $ ln -s /opt/shibboleth/lib/libxerces-c.so.21.0 /opt/shibboleth/lib/libxerces-c.so ************************************ GNOME XML packages (libxml2/libxslt) ************************************ This is another XML parser suite that we hope to eliminate at a later date. On Solaris, you're probably not using these, but any GNOME installation on Linux is sitting on top of these, so chances are you'll want to build them in /opt/shibboleth and leave your system alone. The versions that come with Red Hat (even 8.0) are too old, unfortunately. ftp://ftp.gnome.org/pub/GNOME/sources/libxml2/2.4/libxml2-2.4.26.tar.gz ftp://ftp.gnome.org/pub/GNOME/sources/libxslt/1.0/libxslt-1.0.22.tar.gz $ tar xvzf libxml2-2.4.26.tar.gz $ cd libxml2-2.4.26 $ ./configure --prefix=/opt/shibboleth --with-threads --with-thread-alloc \ --without-iconv --enable-static=no $ make $ make install $ tar xvzf libxslt-1.0.22.tar.gz $ cd libxslt-1.0.22 $ ./configure --prefix=/opt/shibboleth --with-libxml-prefix=/opt/shibboleth \ --enable-static=no $ make $ make install ****** xmlsec ****** This is the only moderately stable open source XML signature library in C or C++. It sits on the GNOME parser. http://www.aleksey.com/xmlsec/download/xmlsec-0.0.10.tar.gz (Linux) There's a problem in the configure script that causes your build to pull in the wrong version of libxml2 when you don't update your system packages. It's caused by the presence of OpenSSL in the system lib folder. You'll need to make the following modifications to the configure script by hand to get it to do the right thing. Modify the configure script as follows, by wrapping the original lines below in a conditional: # if test $dir != "/usr/include"; then # OPENSSL_CFLAGS="-I$dir" <-- original line # else # OPENSSL_CFLAGS="-I." # fi # if test $dir != "/usr/lib"; then # OPENSSL_LIBS="-L$dir -lcrypto" <-- original line # else # OPENSSL_LIBS="-lcrypto" # fi (Solaris) Basic build is fine. If you're trying to get Sun's compiler to work, you'll have to edit src/Makefile.in and delete a pair of CFLAGS in the file (-Wall and -ansi) that are specific to gcc. $ tar xvzf xmlsec-0.0.10.tar.gz $ cd xmlsec-0.0.10 $ ./configure --prefix=/opt/shibboleth --with-libxml=/opt/shibboleth \ --with-libxslt=/opt/shibboleth --enable-static=no --enable-dynamic=yes $ make $ make install ******** OpenSAML ******** Umm, what were we doing? Oh, right. You're finally ready to build the bloody thing. You can do this a couple of different ways. The easiest is probably via the source distribution, at http://shibboleth.internet2.edu/ This is fairly simple: $ ./configure --prefix=/opt/shibboleth --with-xmlsec=/opt/shibboleth -C $ make $ make install On Linux, you may have a problem later linking against libsaml because of an error in the libtool archive, libsaml.la. To fix this, edit that file and remove the reference to /usr/lib/libstdc++.so.5 $ vi /opt/shibboleth/lib/libsaml.la (edit the dependency list to remove the non-existing libstdc++ in /usr/lib) If you want to build it raw out of CVS, you're going to find that any old versions of autoconf and automake (and libtool) you have lying around are not gonna work. Sorry. We include the libtool you need inside cvs, so you'll only need to update or at least install a new automake and autoconf. You can use packages or build them yourself, either is fine. To get the code and bootstrap the build: $ cvs -d:pserver:anoncvs@cvs.internet2.edu:/home/cvs/shibboleth login $ cvs -d:pserver:anoncvs@cvs.internet2.edu:/home/cvs/shibboleth co -r Rel_0_7 opensaml $ cd opensaml/c $ ./bootstrap Then go back up and build as above. To see if your build worked, your best bet is to proceed on to Shibboleth, but we'll eventually get some tests in place. It's possible for the OpenSAML link to appear successful but actually be missing symbols, and right now, only a full build of Shib's binaries will expose that. Now follow the flowchart: Did the build succeed? Yes? No? CONGRATULATIONS! Get beer. Condolences. Get beer.