Compiling and Installing ZXID

Sampo Kellomäki (sampo@iki.fi)

ZXID.org Identity Management toolkit implements standalone SAML 2.0 and Liberty ID-WSF 2.0 stacks. This document explains how to compile ZXID from source code.

1 Introduction

ZXID is distributed in source code form, ready to be compiled with C development environment.

Depending on your skill level, you may want to see if a binary package is available for your distribution - installing them is similar to installing the versions compiled from source, except that you step the early steps of compilation.

Once you have compiled ZXID or found a package, you should proceed to install ZXID. This will depend heavily on your environment and some of the cases are explained in their own documents.

After installation, you should try to run a canned tutorial, in section <<see:>>, below, to learn the basics of the technology and to ascertain everything works.

When you are ready to deploy your own services, you should check configuration instructions in ZXID Configuration Reference.

1.1 Other documents

2 Installing

If you want to try ZXID out immediately, we recommend compiling the library and examples and installing one of the examples as a CGI script in an existing web server. See later chapters for more details. 

  tar xvzf zxid-0.15.tgz
  cd zxid-0.15
  # N.B.  There is no configure script. The Makefile works for all
  #       supported platforms by provision of correct TARGET option.
  # N.B2: We distribute some generated files. If they are missing, you need
  #       to regenerate them: make cleaner; make dep ENA_GEN=1
  # Standard place is /var/zxid. You can change this with
  #   make ZXID_PATH=/usr/local/var
  make                   # default Linux. Do `make TARGET=sol8' for Solaris
  make dir               # Creates /var/zxid hierarchy (may need to be root)
  
  make samlmod           # optional
  make samlmod_install   # optional: install Net::SAML perl module
  make phpzxid           # optional
  make phpzxid_install   # optional: install php_zxid.so PHP extension
  make javazxid          # optional

  cp zxid <webroot>/
  # configure your web server to recognize zxid a CGI, e.g.
  mini_httpd -p 8443 -c 'zxid*' -S -E zxid.pem

  # Edit your /etc/hosts to contain
  127.0.0.1       localhost sp1.zxidcommon.org sp1.zxidsp.org

  # Point your browser to (zxid_simple() API version)
  https://sp1.zxidsp.org:8443/zxidhlo?o=E
  https://sp1.zxidsp.org:8443/zxidhlo.pl?o=E       # Perl version
  https://sp1.zxidsp.org:8443/zxidhlo.php?o=E      # PHP version
  http://sp1.zxidsp.org:8080/zxidservlet/zxidHLO?o=E  # Java version

  # Point your browser to (full API version)
  https://sp1.zxidsp.org:8443/zxid?o=E
  https://sp1.zxidsp.org:8443/zxid.pl?o=E       # Perl version
  https://sp1.zxidsp.org:8443/zxid.php?o=E      # PHP version
  https://sp1.zxidsp.org:8443/zxid-java.sh?o=E  # Java version

  # Find an IdP to test with and configure it...

2.1 Prerequisites

This software depends on the following packages:

  1. zlib from zlib.net. Generally whatever comes with your distro is sufficient.

  2. openssl-0.9.8l (earlier versions contain a man-in-the-middle security vulnearability) or later. See www.openssl.org. Generally openssl libraries distributed with most Linux distros are sufficient. ((It is possible to compile without OpenSSL, e.g. for space constrained embedded system, but this has serious security implications.))

  3. libcurl from http://curl.haxx.se/. I used version 7.15.5, but probably whatever ships with your distribution is fine. libcurl is needed for SOAP bindings and for fetching metadata. It needs to be compiled to support HTTPS. ((Compilation without libcurl is possible with some loss of functionality.))

  4. HTTPS capable web server. For most trivial testing CGI support is needed. We recommend mini_httpd(8) available from http://www.acme.com/software/mini_httpd/

    • apache: A possible receipe for Apache compilation

  5. Perl, PHP, and Java interfaces depend on the respective development tools but should not need any additional modules or tools.

Following additional packages are needed by developers who wish to build from scratch, including the code generation (the standard distribution includes the output of the code generation, so most people do not need these).

  1. gperf from gnu.org (only for build process when generating code)

  2. swig from swig.org (only for build process and only if you want scripting interfaces)

  3. perl from cpan.org (only for build process and only if you want to generate code from .sg)

  4. plaindoc from http://mercnet.pt/plaindoc/pd.html (only for build process, for code generation from .sg, and for documentation)

Although technically not needed to build zxid, you will need an IdP to test against. We do not, at the time, supply one, so you will need to find a third party, perhaps a free download of one of the commercial ones like

2.2 Canned Tutorial: Running ZXID as CGI under mini_httpd

While zxid will run easily under Apache httpd (see recipe), for sake of simplicity we first illustrate running it with mini_httpd(8), a very simple SSL capable web server by Jef Poskanzer.

2.2.1 Getting and installing mini_httpd

You can download the source for mini_httpd from http://www.acme.com/software/mini_httpd/

You should already have installed OpenSSL, or quite probably OpenSSL shipped with your distribution. If it is not located at /usr/local/ssl, the you need to edit the mini_httpd Makefile to indicate where it is. At any rate you need to uncomment all lines that start by SSL_ in the Makefile. Then say 

  make

Now copy the mini_httpd binary somewhere in your path.

2.2.2 Running mini_httpd

After building zxid, cd to zxid directory and run 

  mini_httpd -p 8443 -c 'zxid*' -S -E zxid.pem

where 

  -p 8443      specifies the port to listen to
  -c 'zxid*'   specifies that URL paths with "zxid" are CGI scripts
  -S           specifies that https is to be used
  -E zxid.pem  specifies the SSL certificate to use

See Apache recipe for alternative that avoids mini_httpd, but is more complicated otherwise.

N.B. The zxid.pem certificate and private key combo is shipped with zxid for demonstration purposes. Obviously everybody who downloads zxid has that private key, so there is no real security what-so-ever. For production use, you must generate, or acquire, your own private key-certificate pair (and keep the private key secret). See Certificates chapter for further info.

2.2.3 Accessing ZXID

Edit your /etc/hosts file so that the definition of localhost also includes sp1.zxidcommon.org and sp1.zxidsp.org domain names, e.g: 

  127.0.0.1       localhost sp1.zxidcommon.org sp1.zxidsp.org

Point your browser to

https://sp1.zxidsp.org:8443/zxid

or if you do not want the common domain cookie check

https://sp1.zxidsp.org:8443/zxid?o=E

Dynamic linking problems

If accessing the URL (while running mini_httpd) you get no error message and no content - everything just mysteriously fails - you may be hitting a dynamic linking problem. If mini_httpd(8) fails to launch CGI script it will silently fail. This is unfortunate, but I guess that is what the "mini" in the name implies.

To make matters even worse, mini_httpd(8), probably in the interest of security, will ignore LD_LIBRARY_PATH variable. Apparently it has its fixed notion of the library paths that is set at compile time.

If you suspect this problem, try following:

  1. Create shell script called test.sh:

         #!/bin/sh
     echo Content-Type: text/plain
     echo
     echo Test $$
     echo lib_path is --$LD_LIBRARY_PATH--
     ldd zxid
     ./zxid -h 2>&1
     echo Exit value --$?--

  2. Restart mini_httpd(8) like this

         chmod a+x test.sh
     mini_httpd -p 8443 -c test.sh -S -E zxid.pem -l mini.out

  3. Access https://sp1.zxidsp.org:8443/test.sh - you may see something like 

         Test 1655
     lib_path is --/usr/local/lib:/usr/lib--
     ./zxid: error while loading shared libraries: libcurl.so.3: cannot
         open shared object file: No such file or directory

    Now you at least see why it's failing (in this case the directory where libcurl was installed is not in mini_httpd's notion of LD_LIBRARY_PATH). If the zxid binary runs fine from comman line, try `ldd zxid' to see where it is finding its libraries.

Easiest dirty fix is to copy the missing libraries to one of the hardwired directories of mini_httpd(8) (e.g. /usr/lib). More sophisticated fixes include using ldconfig(8), recompiling your mini_httpd(8), or statically linking the offending library into zxid binary.

2.2.4 Setting up an IdP

Currently zxid does not ship with an IdP (though the necessary protocol encoders and decoders are latently available in libzxid, should anyone wish to make an attempt to hack an IdP together). For you to test zxid, you will need to acquire an IdP from somewhere - any vendor whose product is SAML 2.0 certified will do. Possible sources are

If you do not want to install an IdP yourself (even for testing), find someone who already runs one and ask if they would be willing to load the metadata of your zxid SP. If you do this, you will need to get externally visible domain names. This canned tutorial uses /etc/hosts (see previous step) which is only visible on your own machine.

Once you get your IdP up and running, you need to make sure it accepts the zxid SP in its Circle of Trust (CoT). This is done by placing the metadata of the SP in right place in the IdP product configuration. If your IdP supports automatic CoT management, just turn it on and chances are you are done. ((On production IdP you should understand the trust implications (i.e. no trust) of flipping automatic CoT management on.))

If not, you can obtain the zxid SP metadata (which is slightly different for each install so you can't just copy it from existing install) from

https://sp1.zxidsp.org:8443/zxid?o=B

This URL is the well known location method metadata URL. It is also the SP Entity ID or Provider ID, should the IdP product ask for this in its configuration. If the IdP product needs you to supply the metadata manually as an xml file, just point your web browser to the above URL and save to file, or use curl(1) or wget(1).

zxid SP, by default, has automatic fetching of IdP metadata enabled so there is no manual configuration step needed, provided that the IdP supports the well known location method. All SAML 2.0 certified IdP implementations must support it (but you may still need to enable it in configuration). See [SAML2meta] section 4.1 "Publication and Resolution via Well-Known Location", p.29, for normative description of this method.

However, you will need the Entity ID (Provider ID) of the IdP. This is the URL that the IdP uses for well known location method of metadata sharing. You may need to dig the IdP documentation or GUI for a while to find it. If you already have the IdP metadata as an xml file, open it and look for EntityDescriptor/entityID. If you already have the file, you can also import it manually by running the following command 

  ./zxid -import file:///path/to/idp-meta.xml

But the preferred method still is: just let the automatic method do its job.

2.2.5 Your first SSO

  1. Start at

    https://sp1.zxidsp.org:8443/zxid

    or

    https://sp1.zxidsp.org:8443/zxid?o=E

    If you had common domain cookie already in place, and you are already logged in the IdP, the SSO may happen automatically (go to step 3). The automatic experience will be typical when you use SSO regularly for more than one web site (i.e. several SPs).

    However, if you get a screen titled "ZXID SP SSO", you need to paste the IdP's Entity ID to the supplied field and click "Login". If zxid SP already obtained the metadata for the IdP, you may also see a button specific for your IdP (and in this case there is no need to know the Entity ID anymore or paste anything).

  2. Next step depends on the IdP product you are using. Usually a login screen will appear asking for user name and password. Supply these and login. You will need an account at the IdP.

  3. For more slick IdPs, that's all you need to do and you will land right back at the zxid SP page titled "ZXID SP Management".

    Congratulations, you have made your first SSO!

    However, some IdPs will pester you with additional questions and you will have to jump through their hoops. A typical question is whether you want to accept a federation. You do.

    Sometimes the federation question does not appear automatically and you need to figure out a way to create a federation in their user interface and how to get them to send you back to the SP. Sometimes the word used is "account linking" instead of federation. ((Vendor products are constantly improving in this area. From protocol perspective all the additional gyrations are unnecessary. Be sure to provide feedback to the vendor so that simpler, easier to use, products will emerge in future.))

3 Compilation for Experts

  make cleaner
  make dep ENA_GEN=1
  make
  make all ENA_GEN=1

3.1 Build Process

The build process of ZXID relies heavily on code generation techniques that are not for the faint of heart. Some of these techniques, like xsd2sg.pl were innovated for this project, while others like SWIG and gperf are existing software. Here and there some additional perl(1) and sed(1) scripts are run to fix a thing or two.


Fig-1: ZXID Build Process

Carefully study the Makefile, and this should all start to make sense. Please note that there is no configuration script and GNU Auto-tools (GNU Autohell) are not used. This is because they have been evaluated to be unsuitable to this project (or to author's tastes). If the Makefile does not do what you want, you should first study if you can change necessary variables using localconf.mk, or if that does not work, then just edit the Makefile itself. You can temporarily customize the variables in the Makefile by providing new value on command line, e.g. 

  make CC=cc   # override the default of CC=gcc

3.2 Special or embedded compile (reduced functionality)

libzxid contains thousands of functions and any given application is unlikely to use them all. Thus the easiest, safest, no loss of functionality, way to reduce the footprint is to simply enable compiler and linker flags that support dead function elimination. ((Unfortunately the gnu ld does not support dead function elimination. You should file this as a bug to them. If they tell you to put every one of the 7000-some functions in a separate <tt>.c</tt> file, consider the scalability implications of this. Read the comments in <tt>pulverize.pl</tt> for a full scoop and an approach.))

On gcc you should investigate compilation with "-ffunction-sections -fdata-sections" and linking with "-Wl,--gc-sections".

If you need to squeeze zxid into as minimal space as possible, some functionality trade-offs are supported. I stress that you should only attempt these trade-offs once you are familiar with zxid and know what you are doing. The canned install instructions and tutorial walk thrus stop working if you omit significant functionality.

3.2.1 Compilation without OpenSSL

Comment out the -DUSE_OPENSSL flag from CFLAGS in Makefile and recompile.

This will cripple zxid from security perspective because it will no longer be able to verify or generate digital signatures. Unless your environment does not need trust and security, or you understand thoroughly how to provide trust and security by other means, it is a very bad idea to compile without OpenSSL.

N.B. Compiling, or not, zxid with OpenSSL does not affect whether your web server will use SSL or TLS. Unless you know what you are doing, you should be using SSL at web server layer. Given that SSL is used at web server layer, the memory footprint savings you would gain from compiling zxid without OpenSSL may be negligible if you use dynamic linking.

3.2.2 Compilation without libcurl

Comment out the -DUSE_CURL flag from CFLAGS in Makefile and recompile.

Disabling libcurl does not have adverse security implications: you only loose some functionality and depending on your situation you may well be able to live without it.

  1. Without libcurl, zxid can not act as a SOAP client. This has a few consequences

    1. Artifact profile for SSO is not supported because it needs SOAP to resolve the artifact. In most cases a perfectly viable alternative is to use POST profile for SSO.

    2. SOAP profiles for Single Logout and NameID management (aka defederation) are not supported. You can use the redirect profiles and get mostly the same functionality.

  2. Automatic CoT metadata fetching using well known location method is not supported without libcurl. You can fetch the metadata manually, e.g. using web browser, and place it in /var/zxid/cot directory.

    If you want to manually control your Circle of Trust relationships, you probably want to do this anyway so loss of automatic functionality may be a non-issue. ((If you compile with libcurl, but still want to disable automatic metadata fetching, investigate the ZXID_MD_FETCH and related configuration options.))

  3. Web Services Client (WSC) functionality is not supported without libcurl. Effectively this is just another case of "SOAP needed". If you have your own SOAP implementation, you may, at lesser automation, achieve much of the same functionality by calling the encoder and decoder functions manually.

3.2.3 Compiling without zlib (not supported)

zlib is used mainly in redirect profiles. Since zlib is widely avvailable and its foot print is small, we have made no supported provision to compile without it. If you hack something together, let us know.

3.3 Choosing Which Standards to Compile in (default: all)

WARNING: Only regularly tested configuration is to compile all standards in.

On space constrained systems you may shed additional weight by only compiling in the IdM standards you actually use. Of course, if you do not use them, the dead function elimination should take care of them, but sometimes you can gain additional savings in space and especially compile time.

Another reason could be, in the land of the free, if some modules are covered by a software patent, you may want to compile a binary without the contested functionality. ((Please do not ask me to add additional baggage to avoid patents. Software patents are a plague and your efforts are best spent in getting them overturned or changing laws so they go away.))

You can tweak the flags, shown in accompanying table, in the Makefile or by supplying new values in localconf.mk or on commend line. For example 

  make TARGET=sol8 ENA_SAML2=0

would disable SAML 2.0 (and trigger build for Sparc Solaris 8).

Table 1:Conditional inclusion of standards
Makefile flag Standard Comments
ENA_SSO=1 All SSO Must be enabled for any of SSO to work
ENA_SAML2=1 SAML 2.0  
ENA_FF12=1 ID-FF 1.2 Requires ENA_SAML11=1
ENA_SAML11=1 SAML 1.1  
ENA_WSF=1 All WSF Must be enabled for any of WSF to work
ENA_WSF2=1 ID-WSF 2.0  
ENA_WSF11=1 ID-WSF 1.1  

3.4 localconf.mk

You can use localconf.mk to remember your own make options, such as TARGET and different ENA flags, without editing the distributed Makefile.

One useful option to put in localconf.mk is ENA_GEN which will turn on the dependencies that will trigger generation of the files in zxid/c directory. For example 

  echo 'ENA_GEN=1' >>localconf.mk
  make
WARNING: If you are confused about compilation flags appearing "out of nowhere", despite not being mentioned in the Makefile, be sure you have not inadvertently created a localconf.mk (perhaps you rsynced the sources from another machine and forgot to remove localconf.mk). A similar problem can occur if you accidentally copied deps.dep from another machine. It will reference the dependencies with the paths of that machine. Just remove the deps.dep to solve this issue.

3.5 Tough Compilation Errors

ZXID was mostly developed on gcc 3.4.6 and explicitly has not been tested on 4.x series of gcc (due to deprecation of commonly useful features in that gcc series). If you hit compile time problems with 4.x gcc, try with 3.4.x series gcc first, before reporting bugs.

***

3.6 Tough Linking Errors

3.7 Overview of the xsd2sg.pl Tool

The xsd2sg.pl tool, distributed as part of Plaindoc (http://mercnet.pt/plaindoc/pd.html) system, is at the heart of the ZXID code generation. Unfortunately the tool is still in flux. What follows is general outline valid as of March 2007.

xsd2sg.pl can be invoked in three ways (see xsd2sg.pl --help), but the invocation of interest to use is the -S SG to XSD with Code generation mode. This mode takes as inputs all .sg files and names of decoding root elelment. It will generate one mega parser that is capable of decoding any root element (and since root elements contain other elements, then really all elements). The decoder works by recursive descent parser principle so there will be smaller decoder functions to call. Similarily the encoder is generated by creating many unit encoders for different elements. Then the parent elements will call the child element encoders.

3.7.1 Process .sg to create %dt hash (throw away XSD output)

xsd2sg.pl first processes the .sg files to XSD. As a side effect it populates %dt multidimentsional hash 

  $dt{'element'}{elemname}[array-of-sublemens-and-attrs]
  $dt{'attribute'}{attrname} = "";
  $dt{'complexType'}{typename}[array-of-sublemens-and-attrs]
  $dt{'group'}{groupname}[array-of-sublemens-and-attrs]
  $dt{'attributeGroup'}{agname}[array-of-attrs]

Where the array-of-subelems-and-attrs can contain tag or reference to fundamental or derived type, e.g. 

  "tag$sa:Assertion$min$max"
  "ref$xs:anyURI$"
  "ref$sa:Assertion$"
  "base$$0$1$base-type"
  "enum$n1$n2$n3$n4$n5"
  "any$$min$max$pc$ns"
  "anyAttribute$$min$1"
  "_d$$0$1$simplecontent"

3.7.2 The expanding element definitions in %dt

Since the concrete goal is to generate data structures for elements irrespective of how types were used to describe the data, we need to expand any type reference into element definition where it appears. This is done by expand_element() which will in its turn call expand_complex_type(), expand_group() and expand_attribute_group() to do the job.

3.7.3 Generation Phase

Once %dt is in expanded form, the get_element() is called for each XML namespace. It will generate the code for encoders and decoders for the elements in the XML namespace. Finally the root decoder is gnerated using gen_element(). Furing generation following template files are used 

  aux-templ.c      - Code generation template for auxiliary functions
  dec-templ.c      - Code generation template for decoders
  enc-templ.c      - Code generation template for encoders
  getput-templ.c   - Code generation template for accessor functions

A lot of the generated headers are simply hard coded in the xsd2sg.pl (i.e. no templates).

4 Integration with Existing Web Sites

Single Sign-On is used to protect some useful resources. ZXID does not have any means of serving these resources, rather a normal web server or application server should do it. ZXID should just concentrate on verifying that a user has valid session, and if not, establishing the session by way of SSO.

4.1 Brief Overview of Control Flow

The SAML 2.0 specifications mandate a wire protocol, and in order to speak the wire protocol, the SP application typically has to follow certain standard sequence of control flow.


Fig-2: Typical control flow of ZXID SP

First a user ((The user is often referred to as "Principal" in more technical jargon. Although the human user and web browser are distinct entities, we do not stress that separation here. Whatever user "does" really will, in protocol, appear as web browser sending requests.)) tries to access a web site that acts in SP role. This triggers following sequence of events

  1. User is redirected to URL in a common domain. This is so that we can read the Common Domain Cookie that indicates which IdP the user uses. Alternatively, if you started at https://sp1.zxidsp.org:8443/zxid?o=E, the CDC check is by-passed and flow 2b. happens.

  2. After the CDC check, a Authentication Request (AuthnReq) is generated. The IdP may have been chosen automatically using CDC (2a), or there may have been some user interface interaction (not show in the diagram) to choose the IdP.

  3. User is redirected to the IdP. The redirection carries as a query string a compressed and encoded form of the SAML 2.0 AuthnReq.

  4. Once the IdP has authenticated the user, or observed that there already is a valid IdP session (perhaps from a cookie), the IdP redirects the user back to the SP.

    The AuthnResponse may be carried in this redirection in a number of alternate ways

    1. The redirect contains a special token called artifact. The artifact is a reference to the AuthnResponse and the SP needs to get the actual AuthnResponse by using a SOAP call (the 4bis step).

    2. The "redirect" is actually a HTML page with a form and little JavaScript that causes the form to be automatically posted to the SP. The AuthnResponse is carried as a form field.

  5. After verifying that AuthnResponse indicated a success, the SP establishes a local session for the user (perhaps setting a cookie to indicate this).

    Depending on how the SP to web site integration is done the user is taken to the web site in one of the two ways

    1. Redirect to the content. This time the session is there, therefore the flow passes directly from check session to the web content.

    2. It is also possible to show the content directly without any intervening redirection.

4.2 Redirect Approach to Integration

4.3 Pass-thru Approach to Integration

4.3.1 mod_perl pass-thru

4.3.2 PHP pass-thru

4.3.3 mod_zxid pass-thru

4.4 Proxy Approach to Integration

5 Testing

ZXID test suite is still in tatters. Some things that should be tested

  1. Will generated HTTP redirect sig validate at IdP?

  2. Does IdP issued A7N validate?

  3. Validation of EncryptedAssertion?

  4. Will generated SOAP binding sig validate at IdP?

  5. Does IdP issued SOAP sig validate?

Metadata related

  1. IBM metadata (can we parse)

  2. Sun metadata (can we parse)

XML related

  1. Fully qualified XML parses?

  2. Unknown ns prefix that refers to known namespace URI

  3. Known ns prefix, referring to wrong URI

  4. Known prefix refers to aliased URI

  5. Use of default namespaces working?

  6. Unknown prefix and URI as long as it is never used

  7. Unknown prefix and URI, used

  8. Known NS (prefix or URI), unknown element

6 License

Copyright (c) 2006-2009 Symlabs (symlabs@symlabs.com), All Rights Reserved. Author: Sampo Kellomäki (sampo@iki.fi)

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

While the source distribution of ZXID does not contain SSLeay or OpenSSL code, if you use this code you will use OpenSSL library. Please give Eric Young and OpenSSL team credit (as required by their licenses).

Binary distribution of this product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit (http://www.openssl.org/). See LICENSE.openssl for further information.

Binary distribution of this product includes cryptographic software written by Eric Young (eay@cryptsoft.com). Binary distribution of this product includes software written by Tim Hudson (tjh@cryptsoft.com). See LICENSE.ssleay for further information.

And remember, you, and nobody else but you, are responsible for auditing ZXID and OpenSSL library for security problems, back-doors, and general suitability for your application.

6.1 Dependency Library Licenses

ZXID strives to maintain IPR hygiene and avoid both non-free and GPL license contamination. All the dependency libraries have BSD style licenses

Please see each library package for the exact details of their licenses.

6.2 Specification IPR

ZXID is based on open SAML and Liberty specifications. The parties that have developed these specifications, including Symlabs, have made Royalty Free (RF) licensing commitment. Please ask OASIS and Liberty Alliance for the specifics of their IPR policies and IPR disclosures.

Some protocols, such as WS-Trust and WS-Federation enjoy Microsoft's pledge ((If you have a reference to where this pledge can be found, please let me know so it can be included here.)) that they will not sue you even if you implement these specifications. You should evaluate yourself whether this is good enough for your situation.

6.3 Further Warranties

If you need the author or Symlabs to further disclaim IPR interest or make warranties of non-infringement, such declarations are available for a fee. Please contact sales@symlabs.com

Legal queries and clarifications will be answered at then-current Symlabs Professional Services rate, please contact sales@symlabs.com.

7 FAQ

7.1 Compilation Problems

7.1.1 OpenSSL not found: you need to create localconf.mk

ZXID does NOT have a configure script. It ships with a notion of "standard" locations for the three dependency libraries, but if these libraries are not where it expects to find them, then typically you see (n.b. lines were folded for presentation): 

  make
  If you get compilation errors, try: make help
  gcc -g -fpic -fmessage-length=0 -Wno-unused-label -Wno-unknown-pragmas
     -fno-strict-aliasing -D_REENTRANT -DDEBUG -DUSE_CURL -DUSE_OPENSSL
     -DLINUX -I/tmp/zxid-0.20 -I/usr/local/ssl/include -I/usr/local/include
     -c -o zxid.o zxid.c
  zxid.c:34:23: curl/curl.h: No such file or directory
  In file included from zxid.c:38:
  zx.h:26:25: openssl/rsa.h: No such file or directory
  ...

What happened is that OpenSSL for some reason is not in the location where standard OpenSSL distribution would install it (as indicated by -I/usr/local/ssl/include flag that ships with ZXID Makefile). You need to determine where OpenSSL is installed in your case. You can use 

  find / -name rsa.h -ls

to locate candidates.

For example, if it turns out that OpenSSL is installed in /opt/ssl, then you need to create a localconf.mk file that indicates this location: 

  echo OPENSSL_ROOT=/opt/ssl >localconf.mk

There are several other make variables you may need to tweak. In the above example, we also notice that libcurl was not found where expected. This would be fixed like this 

  echo CURL_ROOT=/opt/curl >>localconf.mk

Net result? ZXID does not try to guess where the libraries are. It makes you do the foot work of locating the correct libraries (some people have more than one instance installed) and prepare the localconf.mk. This may seem like a lot of work, but in my experience, fixing GNU autohell configure scripts that guess wrong is thousand times more frustrating. The system is dumb by design so you, as a human, do not have to try to second guess it - you are in control.

7.1.2 Missing gperf

  gcc -g -fpic -fmessage-length=0 -Wno-unused-label -Wno-unknown-pragmas -fno-strict-aliasing -D_REENTRANT -DDEBUG -DUSE_CURL -DUSE_OPENSSL -DLINUX -I/c/cvs/zxid_cvs -I/usr/local/ssl/include -I/usr//include   -c -o c/zx-a-aux.o c/zx-a-aux.c
  c/zx-a-aux.c: In function "zx_NEW_a_Action":
  c/zx-a-aux.c:80: error: "zx_a_Action_ELEM" undeclared (first use in this function)

This happens because c/zx-const.h was misgenerated (it should not happen at all if you do not supply ENA_GEN=1) and does not include the necessary defines. c/zx-const.h should have more than 1900 lines and look something like 

  /* generated file, do not edit! zx_ _ATTR */
  #ifndef _zx__ATTR
  #define _zx__ATTR
  #define zx_use_ATTR     0
  #define zx_used_ATTR    1
  #define zx_sequence_ATTR        2
  ...
  #define zx_wantDSEPR_ATTR       347
  #define zx_ZX_TOK_NOT_FOUND_ATTR        348
  #define zx__ATTR_MAX    349
  #endif
  /* generated file, do not edit! zx_ _ELEM */
  #ifndef _zx__ELEM
  #define _zx__ELEM
  #define zx_ds_Y_ELEM    0
  #define zx_gl_Y_ELEM    1
  #define zx_gl_esrd_ELEM 2
  ...
  #define zx_wst_OnBehalfOf_ELEM  1629
  #define zx_ZX_TOK_NOT_FOUND_ELEM        1630
  #define zx__ELEM_MAX    1631
  #endif

7.1.3 make samlmod gives "incompatible types in assignment"

Should not happen with version 0.21 or later. See zxidnoswig.h for explanation of the problem.

7.1.4 Perl compiled with different compiler than zxid

Perl modules generally want to be compiled with the same C compiler and options as were used to compile perl itself (see perl -V). If this happens to be different than the compiler you have defined in CC variable (gcc by default, near top of Makefile or in localconf.mk), you may get an error like: 

  cd Net; perl Makefile.PL && make
  Warning: -L.. changed to -L/home/sampo/zxid/Net/..
  Writing Makefile for Net::SAML
  make[1]: Entering directory `/home/sampo/zxid/Net'
  cc -c  -I.. -I/apps/openssl/std/include -I/apps/include -D_REENTRANT -D_GNU_SOURCE -DTHREADS_HAVE_PIDS -DDEBUGGING -fno-strict-aliasing -pipe -Wdeclaration-after-statement -D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64 -O2 -march=i586 -mtune=i686 -fmessage-length=0 -Wall -D_FORTIFY_SOURCE=2 -g -Wall -pipe   -DVERSION=\"\" -DXS_VERSION=\"\" -fPIC "-I/usr/lib/perl5/5.8.8/i586-linux-thread-multi/CORE"   SAML_wrap.c
  /bin/sh: cc: command not found
  make[1]: *** [SAML_wrap.o] Error 127
  make[1]: Leaving directory `/zxid/Net'
  make: *** [samlmod] Error 2

Solutions

  1. Compile zxid with compiler that was used for perl, e.g.

         make CC=the-compiler-that-perl-wants

  2. Recompile perl using the compiler that you want to use for zxid

  3. Tinker with PATH environment variable so that both C compilers are found. However, using two different compilers is not really supported.

In general these types of problems happen when you use perl installed by your distribution, but have later compiled a gcc of your own. It may even be that you never installed the distribution cc - in that case consider installing it and then trying approaches 1 or 3.

A similar situation can arise with incompatibility of the compiler and options used for dependency libraries, such as OpenSSL or libcurl, and those used for compiling zxid itself.

7.1.5 All files under zx missing

You need to symlink zx to zxid source directory, thus 

  ln -s . zx

If you do not have it, then you will get a lot of file inclusion errors for headers that are supposed to be in path starting by zx/

The symlink is there to keep all hand written source files on top level of directory for ease of development, yet allow inclusions to go through zx subdirectory. When zxid is installed, it goes to /usr/include/zx. Hence the symlink keeps the includes the same whether developing or using installed version.

7.1.6 Compiler Warnings

If you compile zxid with compiler warnings turned on (CFLAGS += -Wall), you will see quite a number of warnings, most of which are unwarranted. Since the warnings are unwarranted, I ship zxid Makefile with warnings turned off. If this bothers you, feel free to investigate the warnings and report to me any issues you uncover.

Following warnings in partuclar are unwarranted:

  1. Any unusued variable warnings, especially in generated code. Most common of these is se variable (see enc-templ.c).

  2. "Suggest parenthesis around assignment when used as truth value." I rely on C language operator precedence. Also, in most cases the assignment is the only expression in the truth test - there simply is no opportunity for ambiguity -- and no justified case for gcc to warn about this.

  3. "Suggest parenthesis around && when used in ||". I rely on C language operator precedence, hence the suggestion is redundant.

Some warnings you may want to worry about

  1. "int format, long int arg". On 32 bit platforms int and long are both 32 bits so this warning is not an issue. On 64 bit platforms, however, there may be cause for worry.

7.1.7 SWIG and Java Problems

javac -J-Xmx128m -g zxid.java zxidjava/*.java zxidjava/zxidjni.java:159: cannot find symbol symbol : class SWIGTYPE_p_p_void location: class zxidjava.zxidjni 

  public static zx_str zx_rsa_pub_enc(zx_ctx c, zx_str plain, SWIGTYPE_p_p_void rsa_pkey, int pad) {
                                                              ^

zxidjava/zxidjni.java:164: cannot find symbol symbol : class SWIGTYPE_p_p_void location: class zxidjava.zxidjni 

  public static zx_str zx_rsa_pub_dec(zx_ctx c, zx_str ciphered, SWIGTYPE_p_p_void rsa_pkey, int pad) {
                                                                 ^

zxidjava/zxidjni.java:169: cannot find symbol symbol : class SWIGTYPE_p_p_void location: class zxidjava.zxidjni 

  public static zx_str zx_rsa_priv_dec(zx_ctx c, zx_str ciphered, SWIGTYPE_p_p_void rsa_pkey, int pad) {
                                                                  ^

zxidjava/zxidjni.java:174: cannot find symbol symbol : class SWIGTYPE_p_p_void location: class zxidjava.zxidjni 

  public static zx_str zx_rsa_priv_enc(zx_ctx c, zx_str plain, SWIGTYPE_p_p_void rsa_pkey, int pad) {
                                                               ^

This was due to missing SWIG generated classes. Probably interrupted file transfer.

javac -J-Xmx128m -g zxid.java zxidjava/*.java zxid.java:24: cannot find symbol symbol : method new_conf(java.lang.String) location: class zxidjava.zxidjni 

      cf = zxidjni.new_conf("/var/zxid/");
                  ^

zxid.java:27: cannot find symbol symbol : method url_set(zxidjava.zxid_conf,java.lang.String) location: class zxidjava.zxidjni 

      zxidjni.url_set(cf, url);
             ^

zxid.java:28: cannot find symbol

jar cf zxidjava.jar .class jar cf /tmp/zxidjava.jar zxidjava/.class

javac -J-Xmx128m -g zxid.java zxid.java:187: cannot access zxid_conf bad class file: /Library/Java/Extensions/zxidjava.jar(zxid_conf.class) class file contains wrong class: zxidjava.zxid_conf Please remove or make sure it appears in the correct subdirectory of the classpath. 

  public static int mgmt_screen(zxid_conf cf, zxid_cgi cgi, zxid_ses ses, char op)
                                ^

1 error

Underscore in linking error

./zxid-java.sh Start... Exception in thread "main" java.lang.NoSuchMethodError: zxidjava.zxidjni.new_conf(Ljava/lang/String;)Lzxidjava/zxid_conf; 

        at zxid.main(zxid.java:24)

This was due to finding some old copies from system paths.

java -classpath .:zxidjava -Djava.library.path=zxidjava zxid Start... Exception in thread "main" java.lang.UnsatisfiedLinkError: _zxid_new_conf 

        at zxidjava.zxidjniJNI._zxid_new_conf(Native Method)
        at zxidjava.zxidjni.new_conf(zxidjni.java:586)
        at zxid.main(zxid.java:24)

7.2 Platform Specifics

If your Unix platform is not mentioned, you should try saying just 

  make

which will compile with Linux options. These options actually are pretty close to pure POSIX compile so you should get very close to working configuration.

7.2.1 Linux

Native development platform. Just say 

  make

Seems there are some "improvements" that distributions have made. ZXID adopts the policy of expecting dependency modules where the module author meant it to be installed by default - for example OpenSSL by default installs in /usr/local/ssl (naming is historic, but has stuck). Many distros tinker with these paths. This means you need to create a localconf.mk.

Redhat used to have an issue with Net::SAML (make samlmod). This has since been fixed, please see zxidnoswig.h for explanation.

No doubt, distros will eventually pick up ZXID and provide it as a package. Once that happens they will solve any path issues accoring to their disto policy and that is fine, just do not ask me to comply with any such policy.

7.2.2 FreeBSD

No target available on Makefile, but a port is available from http://www.freshports.org/security/zxid/

7.2.3 Solaris (Sparc)

  make TARGET=sol8
  make TARGET=xsol8    # Cross compile for Solaris (e.g. on Linux host)

7.2.4 MacOS X (PowerPC?)

  make TARGET=macosx

7.2.5 Windows Using MinGW

  make zxid.dll TARGET=xmingw    # Cross compile on Linux host (best supported)
  make zxid.dll TARGET=mingw     # Native compile for mingw target in Cygwin environment

Eitherway, the net result is native Windows DLL that does not have Cygwin library dependencies or GPL encumberation.

See Makefile for further mingw notes.

7.2.6 Windows Using Cygwin

  make TARGET=cygwin

Very experimental (as of Oct 2007) native build for Cygwin.

Cygwin appears to not have neither flock(2) nor lockf(2). This is strange because at least one of these is implemented on MinGW. Current workaround is to define flock() to be empty macro. This of course means there is no file locking. There are 3 known races where things can go wrong

  1. Audit logs can get garbled. This does not stop ZXID from working, but may make log analysis more complicated.

  2. Auto-CoT metadata writes can get garbled. This is very unprobable, but if it happens, the ZXID deployment will not work towards affected IdP. Nothing to worry about really.

  3. Locking is used to protect against updates of zxid.conf while zxid is running. Again any corruption is very unlikely. Nothing to worry about.

The results of Cygwin compile may be GPL encumbered due to libraries.

7.2.7 Windows Using MSVC

Never been done (as of Oct 2007), but probably this is not very difficult given that MinGW port already has addressed many Windows platform issues. Please send any success reports, and receipes, my way.

7.3 Deployment Planning

Here is a rudimentary decision tree for deployment planning

  1. List your applications

    1. Any provided by external partner?

    2. Non web apps

  2. Document your existing identity stores and approaches to

    1. User provisioning (when someone is employed)

    2. Application provisioning (when someone starts using app)

    3. Authorization: how do you know who is supposed to be doing what?

    4. Deprovisioning: what happens when someone is fired?

    5. Login? Per app? Harmonized user names? Enterprise SSO?

  3. Document your goal: federated SAML SSO über alles :-)

    1. Do you want to run IdP?

    2. Could you out-source IdP?

    3. Will your partners / customers be running their own IdPs?

    4. Will you participate (or run) single CoT or do you need to consider cross CoT inter-operation (e.g. IdP proxying)

To be continued...

8 Support

8.1 Mailing list and forums

Mail the author until we get the list set up. Or volunteer a list :-)

8.2 Bugs

Mail the author until we get bug tracking set up. Or volunteer.

8.3 Developer access

We use CVS, but access needs to be manually configured and is not anonymous. If you contribute significantly, I will bother. Others can send patches (good way to show you are worthy of CVS access) to me. I've heard some mixed experiences about open source sites like sourceforge. If you run such site and want to host ZXID Project, please contact me.

If you just always want the latest source: get the tar ball from the downloads section. Trust me, this is still so much in flux that only the tar ball snapshots are in any usable state. CVS access just to get latest source would be pointless.

8.4 Commercial Support

Following companies provide consultancy and support contracts for ZXID:

References

[SAML11core]
SAML 1.1 Core, OASIS, 2003
[SAML11bind]
"Bindings and Profiles for the OASIS Security Assertion Markup Language (SAML) V1.1", Oasis Standard, 2.9.2003, oasis-sstc-saml-bindings-1.1
[IDFF12]
http://www.projectliberty.org/resources/specifications.php
[IDFF12meta]
Peted Davis, Ed., "Liberty Metadata Description and Discovery Specification", version 1.1, Liberty Alliance Project, 2004. (liberty-metadata-v1.1.pdf)
[SAML2core]
"Assertions and Protocols for the OASIS Security Assertion Markup Language (SAML) V2.0", Oasis Standard, 15.3.2005, saml-core-2.0-os
[SAML2prof]
"Profiles for the OASIS Security Assertion Markup Language (SAML) V2.0", Oasis Standard, 15.3.2005, saml-profiles-2.0-os
[SAML2bind]
"Bindings for the OASIS Security Assertion Markup Language (SAML) V2.0", Oasis Standard, 15.3.2005, saml-bindings-2.0-os
[SAML2context]
"Authentication Context for the OASIS Security Assertion Markup Language (SAML) V2.0", Oasis Standard, 15.3.2005, saml-authn-context-2.0-os
[SAML2meta]
Cantor, Moreh, Phipott, Maler, eds., "Metadata for the OASIS Security Assertion Markup Language (SAML) V2.0", Oasis Standard, 15.3.2005, saml-metadata-2.0-os
[SAML2security]
"Security and Privacy Considerations for the OASIS Security Assertion Markup Language (SAML) V2.0", Oasis Standard, 15.3.2005, saml-sec-consider-2.0-os
[SAML2conf]
"Conformance Requirements for the OASIS Security Assertion Markup Language (SAML) V2.0", Oasis Standard, 15.3.2005, saml-conformance-2.0-os
[SAML2glossary]
"Glossary for the OASIS Security Assertion Markup Language (SAML) V2.0", Oasis Standard, 15.3.2005, saml-glossary-2.0-os
[XML-C14N]
XML Canonicalization (non-exclusive), http://www.w3.org/TR/2001/REC-xml-c14n-20010315; J. Boyer: "Canonical XML Version 1.0", W3C Recommendation, 15.3.2001, http://www.w3.org/TR/xml-c14n, RFC3076
[XML-EXC-C14N]
Exclusive XML Canonicalization, http://www.w3.org/TR/xml-exc-c14n/
[Shibboleth]
http://shibboleth.internet2.edu/shibboleth-documents.html
[Hardt09]
Dick Hardt and Yaron Goland: "Simple Web Token (SWT)", Version 0.9.5.1, Microsoft, Nov. 4, 2009 (SWT-v0.9.5.1.pdf)
[Tom09]
Allen Tom, et al.: "OAuth Web Resource Authorization Profiles (OAuth WRAP)", Version 0.9.7.2, Google, Microsoft, and Yahoo, Nov. 5, 2009 (WRAP-v0.9.7.2.pdf)
[XMLENC]
"XML Encryption Syntax and Processing", W3C Recommendation, 10.12.2002, http://www.w3.org/TR/xmlenc-core
[XMLDSIG]
"XML-Signature Syntax and Processing", W3C Recommendation, 12.2.2002, http://www.w3.org/TR/xmldsig-core, RFC3275
[Disco2]
Liberty ID-WSF Discovery service 2.0
[Disco12]
Liberty ID-WSF Discovery service 1.1 (liberty-idwsf-disco-svc-v1.2.pdf)
[SecMech2]
Liberty ID-WSF 2.0 Security Mechanisms
[SOAPAuthn2]
Liberty ID-WSF 2.0 Authentication Service
[SOAPBinding2]
Liberty ID-WSF 2.0 framework document that pulls together all aspects
[DST21]
Liberty Data Services Template 2.1
[DST20]
Liberty DST v2.0
[DST11]
Liberty DST v1.1
[IDDAP]
Liberty Identity based Directory Access Protocol
[IDPP]
Liberty Personal Profile specification.
[Interact11]
Liberty ID-WSF Interaction Service protocol 1.1
[FF12]
Liberty ID Federation Framework 1.2, Protocols and Schemas
[SUBS2]
Liberty Subscriptions and Notifications specification
[Schema1-2]
Henry S. Thompson et al. (eds): XML Schema Part 1: Structures, 2nd Ed., WSC Recommendation, 28. Oct. 2004, http://www.w3.org/2002/XMLSchema
[XML]
http://www.w3.org/TR/REC-xml
[RFC1950]
P. Deutcsh, J-L. Gailly: "ZLIB Compressed Data Format Specification version 3.3", Aladdin Enterprises, Info-ZIP, May 1996
[RFC1951]
P. Deutcsh: "DEFLATE Compressed Data Format Specification version 1.3", Aladdin Enterprises, May 1996
[RFC1952]
P. Deutcsh: "GZIP file format specification version 4.3", Aladdin Enterprises, May 1996
[RFC2246]
TLSv1
[RFC2251]
LDAP
[RFC3548]
S. Josefsson, ed.: "The Base16, Base32, and Base64 Data Encodings", July 2003. (Section 4 describes Safebase64)
[MS-MWBF]
Microsoft Web Browser Federated Sign-On Protocol Specification, 20080207, http://msdn2.microsoft.com/en-us/library/cc236471.aspx