README.zxid
###########
<<author: Sampo Kellomäki (sampo@iki.fi)>>
<<cvsid: $Id: README.zxid,v 1.121 2009-08-25 16:22:44 sampo Exp $>>
<<class: article!a4paper!!ZXID 23>>

<<abstract:

ZXID.org Identity Management toolkit implements standalone SAML 2.0 and
Liberty ID-WSF 2.0 stacks and aims at implementing all popular
federation and ID Web Services protocols.  It is a C implementation
with minimal external dependencies - OpenSSL, CURL, and zlib -
ensuring easy deployment (no DLLhell). Due to its small footprint and
efficient and accurate schema driven implementation, it is suitable
for embedded and high volume applications. Language bindings to all
popular highlevel languages such as PHP, Perl, and Java, are provided
via SWIG.  ZXID implements, as of July 07, SP, WSC, and WSP roles. IdP
role will follow as the project evolves.\\\\

ZXID.org ist eine C-Bibliothek, die den vollständigen SAML
2.0-Stack implementiert und alle populären
Identitätsverwaltungs-Protokolle wie Liberty ID-FF 1.2,
WS-Federation, WS-Trust und ID-Webservices wie Liberty ID-WSF 1.1 und
2.0 implementieren will. Sie beruht auf Schema-basierter
Code-Erzeugung, woraus eine genaue Implementation resultiert. SWIG
wird verwendet, um Schnittstellen zu Skriptsprachen wie Perl, PHP und
Python sowie zu Java bereitzustellen. Sie kann als SP, WSC und
WSP fungieren.\\\\

A biblioteca de gestão de identidades ZXID.org é uma
implementação, em C, das normas SAML 2.0 e Liberty ID-WSF 2.0 com
dependências externas mínimas - OpenSSL, CURL, e zlib - facilitando
uma implantação fácil sem "inferno dos DLL". Sendo económica em
consumo de recursos é indicada para aplicações embutidas ou
de grande volume e performance. A biblioteca é disponibilizada para
todos os linguagens de programação de alto nível como, p.ex.,
PHP, Perl, e Java, atravez de interfáces SWIG. ZXID de hoje (Jul
07) pode funcionar nos papeis SP (Provedor de Serviços), WSC
(Cliente de Serviços Web) e WSP (Provedor de Serviços Web),
sendo o papel IdP (Provedor de Identidade) suportado
na futura evolução do projecto.\\\\

La librería de gestión de identidades ZXID.org es una
implementación en C de las normas SAML 2.0 y Liberty ID-WSF 2.0,
con dependencias externas mínimas - OpenSSL, CURL, y zlib - que
elimina el "Infierno DLL" en su implantación. Como ZXID es muy económica,
es apta para aplicaciones embebidas o de gran volumen y
envergadura. Los lenguajes de programación de alto nivel, como Perl,
PHP, y Java, son soportados con generador de interfaces SWIG. Hoy (Feb
07) el ZXID soporta los roles SP (proveedor de servicios) y WSC
(cliente de los servicios web). Los roles IdP (proveedor de
identidades) y WSP (proveedor de servicios web) serán soportados
en fases futuras del proyecto.\\\\

ZXID.org on verkkohenkilöllisyyden ja -tunnisteiden
hallintakirjasto joka tukee SAML 2.0 (sisäänkirjaantuminen) ja
Liberty ID-WSF 2.0 (henkilöllisyyteen pohjautuvat webbipalvelut)
standardeja. ZXID vaatii vain OpenSSL, CURL ja zlib
kirjastot joten se välttää "DLL helvetti"-ongelman.
Skemapohjaisena C toteutuksena se on tarkka ja
taloudellinen ja kelpaa sulautettuihin ja erittäin kovaa
suorituskykyä vaativiin sovelluksiin. Se tukee korkeantason
kieliä - kuten Perliä, PHP:tä, ja Javaa - SWIG generoiduin
rajapinnoin. ZXID tukee (Heinäkuu 07) SP (palveluntarjoaja), WSC
(webbipalvelunkutsuja), ja WSP (webbipalveluntarjoaja) rooleja.  IdP
(henkilöllisyydenvarmentaja) rooli toteutetaan projektin tulevissa
vaiheissa.

>>

<<maketoc: 1>>

This README.zxid is in process of being rewritten and restructured.
A lot of the material has moved to specific files, which
you should read.

* <<link:mod_auth_saml/mod_auth_saml.html: mod_auth_saml>> Apache
  module documentation: SSO without programming.
* <<link:html/zxid-simple.html: zxid_simple()>> Easy API for SAML
* <<link:html/zxid-raw.html: ZXID Raw API>>: Program like
  the pros (and fix your own problems). See also <<link:ref/html/index.html:Function reference>>
* <<link:html/zxid-wsf.html: ZXID ID-WSF API>>: Make Identity Web Services Calls using ID-WSF
* <<link:html/zxid-install.html: ZXID Compilation and Installation>>: Compile
  and install from source.
* <<link:html/zxid-conf.html: ZXID Configuration Reference>>: Nitty gritty
  on all options.
* <<link:html/zxid-cot.html: ZXID Circle of Trust Reference>>: How to
  set up the Circle of Trust, i.e. the partners your web site works with.
* <<link:html/zxid-log.html: ZXID Logging Reference>>: ZXID digitally signed logging facility
* <<link:html/zxid-java.html: javazxid>>: Using ZXID from Java
* <<link:html/zxid-perl.html: Net::SAML>>: Using ZXID from Perl
* <<link:html/zxid-php.html: php_zxid>>: Using ZXID from PHP
* <<link:html/apache.html: apache>>: A possible receipe for Apache compilation

2 ZXID Project
==============

Immediate goal: build a SAML 2.0 SP and ID-WSF 2.0 WSC

Goals of ZXID project include

* SOAP 1.1 support (done)
* SAML 2.0 compliance
  - SP role (done)
  - IdP role
* Liberty ID-FF 1.2 support
  - SP
  - IdP
  - SAML 1.1
* Liberty ID-WSF 1.1 support
  - Discovery bootstrap
  - Discovery WSC
  - ID-DAP WSC
  - ID-DAP WSP
* Liberty ID-WSF 2.0 support
  - Discovery bootstrap (done)
  - Discovery WSC (done)
  - ID-DAP WSC (done)
  - ID-DAP WSP

<<table: ZXID Platform Support
Platform        Native     Cross Compile    Notes
=============== ========== ================ ================================
Linux-ix86      gcc-3.4.6  n/a              Development platform
Solaris 8-sparc gcc-3.4.6  Linux gcc-3.4.6  Fully functional
Windows 2000    -          Linux gcc-3.4.6  Poorly tested
xBSD/Unix       gcc-3.4.6  n/a              C core tested, language bindings not tested
>>

<<table: ZXID Feature and Language Support (version number indicates last testing)
Feature               C     mod_perl mod_php Python Java/Tomcat Apache Shell
===================== ===== ======== ======= ====== =========== ====== =====
Geo Location          Alpha
ID-MM7                Alpha
ID-DAP                Beta
ID-HR-XML             Beta
Contact Book          Alpha
People Service        Alpha
Discovery             Yes
Web Services (ID-WSF) Yes
SSO                   0.17  0.17     0.17    Plan   0.17        Plan   0.17
>>

<<table: ZXID Enabled Application Packages
Application    Language      Notes
============== ============= =====================================================
DokuWiki       PHP           Patch available, in process of submitting to DokuWiki authors
>>

<<ignore: table: ZXID Enabled Application Packages
Application    Language      Notes
============== ============= ==============================
MediaWiki      PHP           Planned
Cognito
zxbug          Perl          Planned
>>

2.1 Project Layout
------------------

Following directory layout is used by the project. Many of the specified
directories are used by intermediate outputs that are not distributed
in tarball releases, but may or may no be present in CVS checkouts.

  zxid-0.xx
   |
   +-- Net       The Net::SAML perl module (also mod_perl)
   +-- php       PHP / mod_php integration
   +-- zxidjava  The Java JNI interface to ZXID
   +-- servlet   Apache Tomcat integration
   +-- c         C code generated from the Schema Grammar descriptions
   +-- sg        Schema Grammar (.sg) descriptions of protocols
   +-- xsd       XML schema descriptions of protocols (not distributed)
   +-- tex       Temporary files for document generation using PlainDoc (not distributed)
   +-- html      HTML documentation generated using PlainDoc
   +-- review    Publicly released announcements and documents (not distributed)
   +-- t         Test scripts and expected test outputs
   `-- tmp       Temporary files, such as actual test outputs

The Manifest file, which follows, explains each file in more detail.

<<logoutput:
<<Manifest>>
>>

2.2 Protocol Encoders and Decoders
----------------------------------

The protocol encoders and decoders are generated automatically from
the schema grammar (.sg) descriptions. This ensures accurate protocol
implementation. While the output is strictly schema driven and correct,
the decoders have some provisions to accept some deviations from
strict spec (e.g. out of order elements are tolerated). However,
one should note that XMLDSIG does not tolerate very much deviation,
thus even if decoder accepts a slightly illformed message, it is likely
to fail in signature verification.

There are three outputs from generation

1. Data structures describing the data (xx.h)
2. Encoder that linearizes the data structure to wire protocol (xx-enc.c)
3. Decoder that converts wire protocol byte stream to a data structure (xx-dec.c)

2.3 Standards and Namespaces
----------------------------

ZXID uses consistently the same namespace prefixes throughout the project. The
generated encoders and decoders support following schemata

<<longtable: ZXID Namespace Convention
Prefix URI                                            Description
====== ============================================== =================================
sa     urn:oasis:names:tc:SAML:2.0:assertion          SAML 2.0
sp     urn:oasis:names:tc:SAML:2.0:protocol
md     urn:oasis:names:tc:SAML:2.0:metadata
ecp    urn:oasis:names:tc:SAML:2.0:profiles:SSO:ecp
paos   urn:liberty:paos:2006-08
sa11   urn:oasis:names:tc:SAML:1.0:assertion          SAML 1.1
sp11   urn:oasis:names:tc:SAML:1.0:protocol
ff12   urn:liberty:iff:2003-08                        ID-FF 1.2
m20    urn:liberty:metadata:2004-12                   v2.0 (almost same as 1.2)
ac     urn:liberty:ac:2004-12                         v2.0 (almost same as 1.2)
b12    urn:liberty:sb:2003-08                         ID-WSF 1.1 SOAP Binding
sec12  urn:liberty:sec:2003-08                        ID-WSF 1.1 Security Mechanisms
di12   urn:liberty:disco:2003-08                      ID-WSF 1.1 Discovery Service
is12   urn:liberty:is:2003-08                         ID-WSF 1.1 Interaction Service
lu     urn:liberty:util:2006-08                       ID-WSF 2.0 Utility Schema
sbf    urn:liberty:sb                                 Framework header
b      urn:liberty:sb:2006-08                         ID-WSF 2.0 SOAP Binding
sec    urn:liberty:security:2006-08                   ID-WSF 2.0 Security Mechanisms
di     urn:liberty:disco:2006-08                      ID-WSF 2.0 Discovery Service
is     urn:liberty:is:2006-08                         ID-WSF 2.0 Interaction Service
dap    urn:liberty:id-sis-dap:2006-08:dst-2.1         ID Directory Access Protocol
dst    urn:liberty:dst:2006-08                        Data Services Template 2.1
subs   urn:liberty:ssos:2006-08                       Subscription and Notification
ps     urn:liberty:ps:2006-08                         People Service
im     urn:liberty:ims:2006-08                        Identity Mapping svc (aka Token Map)
as     urn:liberty:sa:2006-08                         ID-WSF 2.0 Authentication Service
cb     urn:liberty:id-sis-cb:2004-10                  Contact Book Protocol (DST 2.0 based)
cdm    urn:liberty:cb:conceptual-data-model:2004-10   Contact Book Common Data Model
gl     urn:liberty:id-sis-gl:2005-07                  Geolocation Service

mm7
http://www.3gpp.org/ftp/Specs/archive/23_series/23.140/schema/REL-6-MM7-1-4
ID-MM7 (ID-SIS-CSM)
dp     urn:liberty:dp:2006-12                         ID-WSF 2.0 Design Patterns
idp    urn:liberty:idp:2006-12                        ID-WSF 2.0 IdP as web svc
pmm    urn:liberty:pmm:2006-12                        ID-WSF 2.0 Prov Mod Mgr
prov   urn:liberty:prov:2006-12                       ID-WSF 2.0 TM Provisioning
shps   urn:liberty:shps:2006-12                       ID-WSF 2.0 Svc Handling and Proxying
e      http://schemas.xmlsoap.org/soap/envelope/      SOAP 1.1, with SAML and WSF
xa     urn:oasis:names:tc:xacml:2.0:policy:schema:os  XACML 2.0
xac    urn:oasis:names:tc:xacml:2.0:context:schema:os
xasp   urn:oasis:xacml:2.0:saml:protocol:schema:os
xasa   urn:oasis:xacml:2.0:saml:assertion:schema:os

wst
http://docs.oasis-open.org/ws-sx/ws-trust/200512/
WS-Trust 1.3 CD-01
wsp    http://schemas.xmlsoap.org/ws/2004/09/policy   *** Newer version? http://www.w3.org/ns/ws-policy/

wsc
http://docs.oasis-open.org/ws-sx/ws-secureconversation/200512
WS-Secure Conversation CD-01
ds     http://www.w3.org/2000/09/xmldsig#             XML Signatures
xenc   http://www.w3.org/2001/04/xmlenc#              XML Encryption
exca   http://www.w3.org/2001/10/xml-exc-c14n#        Exclusive Canonicalization
a      http://www.w3.org/2005/08/addressing           WSA 1.0

wsse
http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd
WS Security SecExt 1.0

wsu
http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd
WS Security Utility 1.0
xml    http://www.w3.org/XML/1998/namespace           http://www.w3.org/2001/xml.xsd
xsi    http://www.w3.org/2001/XMLSchema-instance
xs     http://www.w3.org/2001/XMLSchema               Namespace only, no code

igf0   urn:LibertyAlliance:igf:0.3:core               Early draft 01, WIP
carml0 urn:LibertyAlliance:igf:0.3:carml              Early draft 03, WIP
>>


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

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

* OpenSSL under BSDish (with "advertising" clause)
* libcurl under BSDish
* zlib under BSDish
* libc available as part of the operating system

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

96.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<<footnote: 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.

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

20 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

14 Integration of Other Libraries with ZXID
===========================================

14.1 Conor Cahill's C++ Library for ID-WSF
------------------------------------------

Conor P. Cahill, of AOL and Intel fame, has developed and maintains a
C++ library for ID-WSF 2.0 Web Service Client functionality for
selected application protocols, including the ID-WSF 2.0 Discovery and
some application protcols. Conor also provides a server side package
that implements the corresponding WSP roles in Java. These libraries
are valuable resources and come with extensive test suites - in fact,
passing Conor's test suites has become the gold standard for validity
and interoperability of any ID-WSF implmentations (this is not to
detract from formal IOP events and the Liberty certification program,
but passing Conor's test suite is a good predictor of getting
certified).

*Install Recipe*

Conor's libraries have certain dependencies. Following is my best understanding
of how to get them installed.<<footnote: As of May 2007, Conor's packages
explode in the current working directory. I recommend creating a wrapper
directory first. Also, the client and server functionality can not be
unpacked in same directory without creating conflict and overwriting some files.>>

  mkdir conor
  cd conor
  tar xvf /t/LibertyIDWSFServices-v0.8.2.tgz 
  cd ..
  mkdir conor-cli
  cd conor-cli/
  tar xvf /t/LibertyClientToolkit-v1.0.1.tgz 

14.2 Pat Patterson's php module
-------------------------------

(*** This section also appears in zxid-php.pd)

Pat Patterson of Sun distributes a pure PHP module (not to be confused
with Sun's OpenSSO open source effort, with which Pat has some
contact) that implements some aspects of SAML 2.0. As of May 2007, his
library provides functionality that, by and large, parallels that of the
php_zxid module. A major advatage of his module is that it does not have
C shared library dependency, but beware that he still depends on XML
parsing and popular crypto libraries (openssl) to be available. These
assumptions are not onerous, but you should be aware of them in case
your system differs from main stream deployments.

Overall, Pat's PHP implementation, as of May 2007, is still lacking
in metadata generation and loading (it does not implement Auto-CoT
or Well Known Location) and has some rough edges around less frequently
used parts of the SAML specification. No doubt matters will improve
over the time.

Pat's library handles only SSO and not ID Web Services. It would be
possible to extract the discovery bootstrap from SSO using his library
after which you can use ZXID WSC API to actually call the services.

14.3 Sun OpenSSO
----------------

Sun Microsystems distributes an open source implementation of SAML 2.0.
Their implementation is of primary interest as it provides a freely available
IdP implementation (as of May 2007 IMNSHO the ZXID SP interface is
superior to the OpenSSO SP - and since both implement an open standard,
you can mix ZXID SP with OpenSSO IdP).

Thus, the ZXID to OpenSSO integration reduces to each one acting in its
role using standard wire protocol - SAML 2.0.

97 FAQ
======

97.1 Compilation Problems
-------------------------

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

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

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

97.1.4 Perl compiled with different compiler than zxid
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

(*** this section also appears in zxid-perl.pd)

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.

97.1.5 All files under zx missing
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

(*** this section also appears in zxid-java.pd and zxid-perl.pd)

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.

97.1.6 Compiler Warnings
~~~~~~~~~~~~~~~~~~~~~~~~

(*** this section also appears in zxid-java.pd and zxid-perl.pd)

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

A. "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.

97.1.7 SWIG and Java Problems
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

(*** this section also appears in zxid-java.pd)

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)


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

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

97.2.2 FreeBSD
~~~~~~~~~~~~~~

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

97.2.3 Solaris (Sparc)
~~~~~~~~~~~~~~~~~~~~~~

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

97.2.4 MacOS X (PowerPC?)
~~~~~~~~~~~~~~~~~~~~~~~~~

  make TARGET=macosx

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

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

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

97.3 Configuration Questions
----------------------------

(*** Some of these may be repeated in zxid-conf.pd)

1. Q: In mod_auth_saml, what is the relation between ZXIDConf and httpd.conf?

   A: httpd.conf can contain ZXIDConf directives. Those directives are
   processed as if they came from /var/zxid/zxid.conf file (which is
   processed first, before and ZXIDConf directives), except that if you
   specify ZXIDConf "PATH=/your/path", this triggers reporcessing of
   the zxid.conf (from the new path).

2. Q: In mod_auth_saml, what is the relation between the +port+ in ZXIDConf
   and the +port+ in the httpd.conf?

   A: The ports must agree. ZXID configuration must match the way the
   Apache layer is configured.

3. Q: Multiple roles of same entity, acting as SP, WSC, and WSP for
   different services

   Asa:
   > Part of what you are saying is that the service
   > registration is WSC.  This is rather confusing since the case is a WSP
   > acting as a WSC of the Discovery Service.   For the ClientLib thus far,
   > I have chosen to think of service registration as a WSP to WSP.  What is
   > the downside to this approach?

   Conor:
   > Service registrations can't be done WSP to WSP with any Liberty protocol
   > (in fact, we don't define any such method of invocation as the invoking
   > party is always  a WSC for the intent of that message - there's no
   > problem with a WSP in turn being a WSC of another service instance, just

   Right. You can don WSC role whenever convenient. There is nothing confusing
   about WSP of one service being WSC of another service. Perhaps the
   confusion would be avoided if everybody fully qualified their descriptions
   until common convention about less than fully qualified roles emerges.

   Entity E1, an ID-DAP WSP (primary role), will act as Discovery WSC
   (secondary role) to perform metadata registration. This same entity E1
   will also have SP interface (another secondary role) which allows
   the user to trigger discovery association, again E1 acting in secondary
   role of Discovery WSC.

   No confusion as far as I can see.

97.3 Common Mistakes
--------------------

1.  When I try accessing https://sp1.zxidsp.org:8443/zxidtest.sh nothing happens!

    Assuming you have the web server correctly running, the most common
    gotcha is that zxidhlo has dynamic linking problem.
    See <<see: ZXID-Installing-CannedTutorialRunningZXIDasCGIundermini_httpd-AccessingZXID>>
    subsection "Dynamic Linking Problems", for explanation and resolution.

2.  Single Logout does not end the IdP session (i.e. IdP does
    not force you to supply password when you do SSO next time).

    Usual cause is that the management form (the one with the SLO buttons)
    does not have correct or any session ID. Do a view source on the
    the page and look for field called "s". The session ID is
    supposed to be extracted from the Single Sign-On result. For
    zxid_simple() you need to parse the returned LDIF and
    take the sesid. Pass that to zxid_fed_mgmt() as second argument.

3.  Login buttons do nothing.

    A possible cause is that the entity ID is not passed from
    the IdP selection form. If the form is using POST method,
    you must make sure you actually read the HTTP body and
    pass its contents to the zxid_simple() as the ~qs~ argument.

4.  The SP Login, a.k.a. IdP selection, page shows, but SSO does not work

    a. Your configuration does not match actual URL used to
       access the zxid system. For the zxidhlo family of
       examples you MUST edit the configuration string
       to match your situation. Watch out for domain name
       and port number.

    b. Connectivity issue prevents IdP from fetching metadata.
       Make sure your domain name is resolvable at IdP (e.g.
       add it to /etc/hosts). See also next point.

    c. IdP is not configured to get your metadata automatically.
       You have to configure your metadata to the IdP manually.
       How to do this depends on IdP product. Do not ask us.

    d. You supplied IdP URL that, in fact, is not the well known
       location for fetching IdP metadata. Or the IdP does
       not have well known location enabled. In the latter
       case you will need to install the IdP metadata
       manually (*** procedure to be documented). See [SAML2meta]
       section 4.1 "Publication and Resolution via Well-Known Location",
       p.29, for normative description of this method.

    e. Connectivity issue at web browser level. Make sure your
       web browser can resolve both SP and IdP domain names.
       Edit /etc/hosts as needed on the machine where the browser runs.

    f. Personal firewall blocks access. Check firewall set up on
       * browser machine
       * SP machine
       * IdP machine

5.  The SP Login, a.k.a. IdP selection, page does not show at all

    a. Connectivity issue at web browser level. Make sure your
       web browser can resolve both SP and IdP domain names.
       Edit /etc/hosts as needed.

    b. Personal firewall blocks access. Check firewall set up on
       * browser machine
       * SP machine

    c. You deployed the zxid in some other URL than you thought.
       Double check your webserver or servlet container
       configuration and be sure you understand where
       zxid is supposed to appear. Be sure you are editing
       the right configuration - some people run multiple
       web servers in their machine and get confused about
       which one actually is active on which port and where
       the configuration files are located.

    d. ZXID lacks execute permissions, dynamic link libraries
       are missing (use "ldd zxid" to check), or CGI permission
       setup prevents it from running. See previous bullet.

6.  Mystery configuration problems. Double check /var/zxid/zxid.conf
    or consider removing it if you do not understand what it does.
    Double check the conf string if using zxid_simple() interface.

7.  Writes a user...

    > Once it has been compiled, I copied the files zxidhlo.php and zxid.php
    > to /var/www/zxid (my webroot). I accessed zxidhlo.php?o=E with my browser
    > and I saw a page asking for IDP metadata. But when I looked at
    > the /var/log/apache2/error.log, I found these: 
    > 
    >  tb77f96c0 zxidmeta.c:352 zxid_get_ent_by_sha1_name zxid d Trying 
    >    sha1_name(cot) open (vopen_fd_from_path): No such file or directory 

    Did you create the /var/zxid hierarchy (make dir) and make sure your
    web user (nobody?) has write permission to the ~log~ directory? Or did
    you configure it to use some other directory than /var/zxid?

8.  What is this /var/zxidcot directory?

    It is supposed to be /var/zxid/cot

    When configuring PATH, did you forget trailing slash? E.g.

      "PATH=/var/zxid&URL=..."    # WRONG!
      "PATH=/var/zxid/&URL=..."   # Right

9.  If configuration appears to be prematurely truncated, then
    see if you need to adjust ZXID_MAX_CONF (default 4KB) in
    zxidconf.h and recompile.


97.3.2 Doubts
~~~~~~~~~~~~~

How to decode auto_flags

  0x1d54   1 = debug; d = FORMT + FORMF + MGMTC; 5 = METAC + LOGINC; 4 = SOAPC

97.4 Consent
------------

A frequent concern among the business people and lawyer types is
whether the architecture provides for consent by the user. Usually
this is related to (avoidance of) liability. If the system can be
said to have gathered the consent of the user, we are safe.

Unfortunately the standards do not mandate an uniform user interface,
thus there is no single specific way how the consent is gathered or
determined: it depends from business situation and application to
another. Fortunately the Liberty and SAML 2.0 architectures provide
plenty of ways and hooks to gather and convey the consent. Consider the
following:

1. When arriving to SP, user chooses IdP for SSO. This act
   of course manifests user's intent to perform SSO.

2. IdP can ask the user whether he wants to perform SSO to
   the SP (IdP can make this question even if user is already
   logged in to the IdP, though most demos omit the question
   in the already logged in case).

   At this point the IdP may also ask whether the user
   wants to create a federation so that the SP can track
   the user. Creating federation is consenting to be
   tracked by the SP.

   If the federation already exists, the IdP can still
   offer a choice: should the federation be used
   this time, i.e. does the user consent to be tracked
   this time specifically.

   If user does not consent to federation and use of
   federation this time, but still consents to SSO,
   the SSO will be made using a temporary name ID.

3. If user gives any Personally Identifying Information
   to the SP (beyond the federated pseudonym), then
   the SP may be able to "connect the dots" and
   correlate user's actions on the SP with his actions
   in some other systems (technically this is called
   collusion).

   In a very technical sense users should be aware
   of this risk or the implication and therefore by
   providing such information they are effectively
   consenting to be correlated across systems.

   However, lawyers would probably say that if
   the SP intends to correlate, it should state
   so to the user at the time the information is
   asked so that the user can make an informed decision.
   If, after being informed, the user still supplies
   the information, then user is clearly
   consenting to the information being used for
   the stated purpose, i.e. correlation.

4. When user starts to use an ID web service, the user is
   consenting to this service being visible to at least
   some parties (why use the service if you did not
   intend this).

   To make this consent explicit, the user interface
   of the ID Web Service can ask.

   Also, the Discovery Service can ask consent using
   the Liberty Interaction Service. It is quite
   appropriate for the DS to ask this consent
   because it allows the ACL to be set correctly
   right from the beginning, when the service is
   registered.

5. When the user later accesses an SP that needs to
   contact an ID Web Service, it could be
   construed that the user, by using the SP
   at all, is effectively consenting that the SP
   may access the ID Web Services of the user.

   If this is not enough, the Discovery Service
   can use the Interaction Service on per service
   invocation basis to ask if the user consents
   to the specific request.

   Finally, the actual ID Web Service can also
   invoke the Interaction Service to ask the
   user to consent to the specific request,
   or otherwise enforce its policies.

6. When using People Service, the inviter (Alice)
   consents to the access by the invitee (Bob)
   by requesting an invitation string from the
   system.

   Once the invitation has been sent (and
   accepted by invitee) there is no easy way
   to collect consent from inviter on per
   request basis. For example Alice may not
   be online at the time when Bob accesses
   her resource.

   Alice can later revoke Bob's invitation,
   but in the window between Alice sending
   the invite and revoking it, Bob can access
   Alice's resource without Alice actively
   consenting to every access.

   Of course the resource can implement ACL
   policies, like only allowing Bob to access
   the resource a limited number of times,
   such as once.

7. When the invitee (Bob) uses inviter's (Alice's)
   ID Web Services (resources), Bob has
   consented to some form of tracking by
   Alice's resources by accepting the
   invite. Further consent may be obtained
   by Bob's own IdP, see bullet 2.

97.5 Deployment Planning
------------------------

Here is a rudimentary decision tree for deployment planning

1. List your applications
   a. Any provided by external partner?
   b. Non web apps
2. Document your existing identity stores and approaches to
   a. User provisioning (when someone is employed)
   b. Application provisioning (when someone starts using app)
   c. Authorization: how do you know who is supposed to be
      doing what?
   d. Deprovisioning: what happens when someone is fired?
   e. Login? Per app? Harmonized user names? Enterprise SSO?
3. Document your goal: federated SAML SSO über alles :-)
   a. Do you want to run IdP?
   b. Could you out-source IdP?
   c. Will your partners / customers be running their own IdPs?
   d. Will you participate (or run) single CoT or do you
      need to consider cross CoT inter-operation (e.g. IdP proxying)

To be continued...

97.6 Use of Signing and Crypto, Security Concerns
-------------------------------------------------

97.7 Vendor products
--------------------

97.7.1 Symlabs Federated Identity Suite (SFIS)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Metadata import to IdP?

What I usually do is

  cd /opt/SYMfiam/3.0.x/conf/symdemo-idpa
  echo 'sp: zxid-sp1$https://sp1.zxidsp.org:8443/zxid?o=B$$' >>cot.ldif

Double check with text editor that the file is sensible.
Note that the single quotes are essential as the dollars
are to be interpretted literally, as separators.

  cd pem
  wget https://sp1.zxidsp.org:8443/zxid?o=B >zxid-sp1.xml

Here the intent is to fetch the metadata from the SP and
store it in a file whose name (without .xml extension)
matches the first component of the sp: line. I am not
100% on the wget syntax. You can also use browser
to fetch the metadata and simply Save as under the
correct name.

  cd /opt/SYMfiam/3.0.x/conf/symdemo-idpa/start.sh restart

This should restart the IdP server process and cause a
refresh of the metadata it may have cached. You may
want to

  tail -f /opt/SYMfiam/3.0.x/conf/symdemo-idpa/log/debug.log

to see if its getting indigestion.

N.B. FIAM seems to have NameID encryption on by default, Turn
this off by editing slimidp.ldif:

  encnids: 0

If this is not done, the SSO will fail (with what appears like signature
error).1x

97.8 Known Bugs
---------------

Following are known limitations. We document them here
because we do not plan to fix them in foreseeable future.

1. Unknown XML attributes are not sorted according to rules
   of exc-c14n. Instead they appear always +after+ known
   XML attributes and in the order they happen to be
   in the linked list.

   *Work around:* Add the attribute to schema (.sg) and
   regenerate and rebuild.

2. Namespace qualified XML attributes have underscore instead of colon

97.9 Mysterious Error Messages
------------------------------

"Random number generator not seeded!!!"

This warning indicates that randomize() was not able to read
/dev/random or /dev/urandom, possibly because your system does not
have them or they are differently named. You can still use SSL, but
the encryption will not be as strong. Investigate setting up
EGD (entropy gathering daemon) or PRNG (Pseudo Random Number
Generator). Both are available on the net.

"msg 123: 1 - error:140770F8:SSL routines:SSL23_GET_SERVER_HELLO:unknown proto"

SSLeay error string. First number (123) is PID, second number (1) indicates
the position of the error message in SSLeay error stack. You often see
a pile of these messages as errors cascade.

"msg 123: 1 - error:02001002::lib(2) :func(1) :reason(2)"

The same as above, but you didn't call load_error_strings() so SSLeay
couldn't verbosely explain the error. You can still find out what it
means with this command:

     /usr/local/ssl/bin/ssleay errstr 02001002

97.9.1 Password is being asked for private key
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This is normal behaviour if your private key is encrypted. Either
you have to supply the password or you have to use unencrypted
private key.

One way to remove password is

  openssl rsa -in key.pem -out keyout-nopw.pem

For this to work, key.pem must have only the provate key. On the other
hand, for ZXID to work, the file must have both certificate and
private key. You will need to use your favorite text editor to
accomplish this.

Scan OpenSSL.org for the FAQ for full explanation on how to
remove password from the private key.

97.9.2 Quick command for looking at certificate
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

(*** also appears in zxid-cot.pd)

Sometimes you get warning messages (in browser) or signature
validation errors (in IdP end) because the Subject field of the
certificate does not match your actual domain name. You can
check this with

  openssl x509 -text </var/zxid/pem/ssl-nopw-cert.pem | grep Subject:

If the domain name is different, then you need to obtain a certificate
with correct domain name, see next question.

97.9.3 Self signed certificate
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

(*** also appears in zxid-cot.pd)

ZXID ships with zxid.pem which gets by default copied to /var/zxid/pem
under various different names. This is fine for testing, but disastrous
for production or security sentitive use as the private key corresponding
to zxid.pem certificate is of public knowledge (it is distributed with
every copy of ZXID) - it offers no security and no non-repudiation
what-so-ever.

For production or security sensitive install you need to either

1. Obtain certificates from an official certification authority,
   usually a commercial one. ZXID uses same certificate format as
   Apache (i.e. the pem format), so aquiring certificates is easi. Or,

2. Generate your own certificate. The simplest case is a self signed
   certificate:

     openssl req -new -x509 -nodes -keyout pkey.pem -out cert.pem
     cat cert.pem pkey.pem >/var/zxid/pem/ssl-nopw-cert.pem

The cat step is there because you need to supply both certificate
and the private key in same file for ZXID to understand it.

> Warning: Although ZXID wants to see the private key in the same
> file as the certificate, you MUST NOT give this concatenated
> file to any outsider. Others have legitimate need to know your
> certificate, but they MUST NOT know your private key. If they
> ask, you should take special care to delete the private key from
> the file prior to giving it to them. Often those who need to
> get your certificate, actually need your metadata: just tell them
> to fetch it from the Well Known Location URL (i.e. the Entity ID
> of your SP). ZXID will never leak the private key to the metadata.

97.9.4 snprintf() multibyte character related errors in log
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This is due to locale setting. Try

  export LANG=C

This will disable any UTF-8 processing in sprintf().

97.9.5 My own messages are redirected back to me
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

In several SAML profiles a HTTP redirect is performed to
send the user to other party, usually with a request or
response in the query string.

A mysterious error is when you see yourself receiving
as input the stuff that was supposed to be sent to the
other. The way this happens is if for some reason the
other party's URL can not be determined, then the
Location header will only consist of the query string
that you are trying to send. Without domain name part
of the URL, the browser will redirect back to the
web site where the redirection came from. This is
called "local redirect" and is usually the cause
of you receiving your own output as input.

To fix this, make sure you have the other site's metadata
and make sure it parses and loads correctly. If that
does not resolve the problem, see if the metadata
has any binding for the operation you are trying.
No binding will result in no URL.

97.10 Author's Pet Peeves
-------------------------

1. What is Schema Grammar (.sg) and why are you using it?
   * Schema Grammar is a compact formal description of XML documents. It is
     mostly bidirectionally convertible to XML Schema (XSD) and captures
     the useful essence of most XML schemata.
   * Schema Grammars are intuitive and compact, often allowing the
     essence to be understood at glance, and even most complex cases
     being only about 50% of the volume of the corresponding XSD.
   * We use Schema Grammar descriptions because they are more human readable
     than XSD and still equally amenable to automated code generation.
   * Schema Grammar descriptions are usually converted using xsd2sg.pl, which is
     part of the PlainDoc distribution.
   * See http://mercnet.pt/plaindoc
   * N.B. You do not need xsd2sg.pl or PlainDoc if you just want to compile and use ZXID.

2. What is PlainDoc (.pd)?
   * PlainDoc is a document preparation system that uses intuitive plain text files
     with minimal markup to generate PDF and HTML outputs.
   * We use PlainDoc because it makes it easy to maintain documentation.
   * See http://mercnet.pt/plaindoc
   * N.B. You do not need PlainDoc if you just want to compile and use ZXID.

3. How come zxid is so heavy to compile?
   * SAML 2.0 and related specs have a lot of functionality and detail, even
     if you really only need 1% of it. We do not wish to arbitrate which
     functionality is best or most needed, so we simply provide it all.
   * A lot of the code is generated, thus the input for C compiler is well
     in excess of half a million lines of code (of which only about 6k
     were written by a human).
   * Some of the generated files are gigantic, e.g. Net/SAML/zxid_wrap.c
     is over 380k lines. Compiler has to process all of this as a single
     compilation unit.
   * gcc and gnu ld were, perhaps, not designed to process this large inputs
     efficiently. Often the implementation strategy of keeping
     everything in memory will cause a smaller machines to swap.
   * My 1GHz CPU, 256 MB RAM machine definitely swaps and thus
     takes about 45 minutes to compile all this stuff.
   * I recommend at least 1GB RAM and 3GHz CPU for development
     machine. On such machine, you should be able to build in about 10 min.

4. Why do you not use ./configure and GNU autoconf?
   * ~autoconf~ is not for everyone. World does not stop without
     ~autoconf~. Or indeed need ~autoconf~. It is Yet Another Dependency
     I Do Not Need (YADIDNN).
   * I find the GNU ~autoconf~ stuff much more difficult to understand than
     my own ~Makefile~. Why should I debug ~autoconf~ when I could
     spend the time debugging my ~Makefile~ or the actual code?
   * I find resolving problems much easier at source code and ~Makefile~ level
     than trying to debug a million line script generated by some system
     I do not understand (perhaps some hardcore ~autoconf~ advocate could
     try to convince me and educate me, but I doubt).
   * My policy is to only support systems I have first hand experience with,
     or I have trustworthy friends to rely on. It does not help me
     to have a system that tries to guess +gazillion irrelevant variables+
     to an unpredictable state. It's much easier to stick to standards like
     POSIX and make sure you have predictable results from predictable inputs.
   * If the deterministic and predictable results are wrong, they can
     at least be debugged and fixed with a finite amount of work.
   * Supporting all relevant systems manually is not that much of work. The
     inhabitants of the irrelevant systems can support themselves, probably
     learning a great deal on the side.

97.11 What does ZXID aim at - an answer
---------------------------------------

A recent (Sept 2006) conversation that touched on the aims of ZXID project:

> So just generally, what are your goals for it, are you interested in making
> it work well with what other people are producing (e.g. SAML -> WSF
> cross-over), etc? I'm certainly assuming the answer's yes to that.

I aim at full stack client side implementation. ID-FF, SAML 2.0, WSF
(both versions). The generation technique I use will yield the
encoders and decoders for both WSP and WSC, but the hand written
higher level logic will at first be only written for SP and WSC. 
Some WSP support has now been written as well (complete WSP support
was completed as of July 2007).

It is Apache licensed project, of course, so if someone contributes
the IdP and WSP capabilities, I'll merge them into the distribution.

I am interested to have it working with other people's code at 3 levels:

1. Over-the-wire interoperability
2. I have split the functionality of the SP from the WSC such that
   zxid SP could probably be used with someone else's WSC and someone
   else's SP would reasonably easily be able to use zxid WSC.
3. Interfaces to non IdM parts of the complete system, typically
   used to implement the application layer, shall be
   plentiful: C/C++ API, Net::SAML/mod_perl, php - whatever you
   can SWIGify.

One thing I am NOT interested in is "layered" stack. I strongly
believe it's better each vertically integrated slice is implemented by
one mind. Thus, except for lowest HTTP, TLS, and TCP/IP layers, my SP,
or WSC, or WSP, handles the whole depth of the stack - SOAP,
signature, and app interface layers (of course the actual app should
be its own layer and probably user written). That is by design.

I have found in practise that if you attempt a layered stack, you have
impedance mismatches between the modules at different layers because
they were designed and written by different minds. By having vertical
integration I avoid impedance mismatches. This is the reason why
monolithic TCP/IP implementations tend to be better than explicitly
layered, such as the streams approach.

Now, if someone else wanted to take my generated encoders and
decoders and use them as a "layer" in their layered stack, I guess
I would not have any issue. If you do that, please let me know
because I would have to commit to API stability at that layer.
I am willing to do that once there are real projects that depend
on it, but until then I still may redesign those APIs, after
all, I am at revision 0.4 :-)

In the end, it seems that ZXID is actually somewhat layered approach -
what I mean by "vertical integration" is that all the layers are
designed and controlled by the same mind.

> BTW, I gather that it's SAML 2.0 at the moment, which I can't offer any test
> capability for, but if you get to SAML 1.1, I'm happy to set up some kind of
> IdP test capability for that.

In SSO world SAML 1.1 and ID-FF 1.2 capabilities are definitely on the
road map. In ID-WSF world, I'll probably start with 2.0 DS-WSC (don't
we all) followed by ID-DAP WSC and then tackle 1.1 after
that.<<footnote: As of version 0.18, July 2007, both WSC and WSP roles
of ID-DAP as well as ID-HR-XML have been implemented. Discovery client
was implemented as well. This means the generic WSC and WSP support is
there.>>

97.12 Annoyances and improvement ideas
--------------------------------------

There is a lot of commonality that is not leveraged, especially in the
way service end points are chose given the metadata.  The descriptors
are nearly identical so casting them to one should work.

Many of the SAML2 responses are nearly identical. Rather than
construct them fully formally, we could have just one "SAML any
response" function. Perhaps this could be supported by some schema
grammar level aliasing feature: if an element derives from base type
without adding anything at all of its own, we might as well only
generate code for the base type.

Namespace aliasing scheme would allow us to consider two versions of
schema the same. It seems to be fairly common that the schema
changes are so minor that there is no justification for two
different decoding engines.

97.13 Non-obvious SAML
----------------------

1.  Destination XML attribute is needed in redirect and POST bindings.

2.  Assertion//SubjectConfirmationData/@InResponseTo XML attribute
    is needed in SSO assertions, unless the SSO was unsolicited.
    SAML is not very explicit about this, [SAML2core], ll.729-732
    describes it as optional, but [SAML2prof], ll.580-582 and
    ll.559-560 seem to imply this requirement.

3.  Some deployments use POST binding for many more things than
    officially sanctioned by SAML [SAML2conf], Table 1 "Possible
    Implementations", p.6. None of the offical profiles, see
    [SAML2conf], Table 2 "Feature Matrix", p.9, require support
    for POST for sending or receiving Single Logout or Manage NameID
    requests. Nor is sending AuthnRequest using POST officially
    sanctioned. Using artifact profile for anything else than
    fetching the SSO assertion is not official. Never-the-less,
    some of these bindings are perfectly implementable and some
    deployments actually use them. ZXID may support some of them,
    especially the POST bindings, if it is easy to do so, but
    we make no commitment beyound official SAML conformance.

4.  In SAML SOAP bindings it is bit unclear if the caller needs
    to be authenticated. Currently ZXID solves this by signing
    the SOAP requests (see SSO_SOAP_SIGN configuration options).
    Other approaches are using HTTP Basic authentication,
    using Client-TLS, or simply not authenticating the peer.

5.  Interpretation of metadata KeyDescriptor/EncryptionMethod

    Algos on [SAML2conf], section 4.2 "XML Encryption Algorithms",
    ll.252-253.

    The interpretation in [SAML2meta], section 2.4.1.1 "Element
    <KeyDescriptor>", ll.621-624, p.16, and the example
    on l.1117.

    Since the <EncryptionMethod> can appear several times, it
    would seem reasonable to specify it once for assymmetric crypto
    and once for symmetric crypto. If specified, then for each
    of the cases, only one of the allowed algos may be used.
    If not specified, then any algo authorized in [SAML2conf]
    is allowed. If specified, but the algo is not authorized
    by [SAML2conf], then implementation is nonconformant.

6.  The selection of protocol binding for return path of
    SSO is non-trivial. The Authentication Request may
    specify any number of parameters like ProtocolBinding
    or Index. Generally it should not be specified at
    all, leaving the decision to the IdP, or it should
    be specified using the Index method.

7.  When passing around Name IDs or storing them in database,
    remember to store all components, including NameQualifier
    and SPNameQualifier.

8.  Single Logout: IdP should not call originator of SLO when
    it is logging out everybody.

9.  SAML Redirect binding signs the base64 and URL encoded
    payload. This is problematic as there is no canonical
    way to URL encode, i.e. some implementations encode
    more than others. When signature needs to be verified,
    CGI or other layer of processing may already have
    removed the URL encoding, thus breaking the signature.
    Correct implementation requires capturing the URL encoded
    version of ~SAMLRequest~ or ~SAMLResponse~ field
    as it came from wire and using that for signature
    verification. This is what ZXID does, but historically
    some implementations have tried to URL reencode for
    signature verification, resulting "it depends" type
    bugs where sometimes it works when sender's URL
    encoding happens to match the URL encoding the receiver
    applies. Of course all of this could have been avoided
    had the design been to sign the base64 encoded form
    prior to URL encoding. And URL encoding would not
    have been needed at all if safebase64 ([RFC3548], sec 4)
    encoding had been used in the first place.

10. SAML SimpleSignPOST binding may superficially seem
    similar to Redirect binding in the signature area. Well,
    it is not. SimpleSign signs the payload data prior to
    base64 (and URL) encoding. This avoids the bug that
    easily creeps into Redirect signature verification,
    see above. Downside is that the payload can't really be
    binary, unless you base64 encode twice.

97.14 Best Practises
--------------------

1.  Each entity chooses its own Entity ID. When you are setting
    up a SP, you choose your Entity ID and the IdP(s) MUST be
    able to adapt to your choice. Similarily, an IdP decides
    its own Entity ID and all SPs MUST be able to adapt to it.

2.  Entity IDs MUST be unique within a Circle of Trust (CoT). Given
    that CoT relationships may change from time to time, its best
    to choose Entity ID so that it is globally unique. If Entity ID
    contains a domain name as a component, then the +globally unique+
    property tends to be enforced by the domain name allocation
    system.

3.  Entity ID SHOULD be the Well Known Location (WKL), i.e. the
    URL from which the metadata can be fetched.

4.  Providing metadata by URL, ideally by the Entity ID, SHOULD
    always be enabled. This greatly facilitates configuration.

5.  <KeyDescriptor> elements should have ~use~ XML attribute

97.15 Cardspace / Infocard / DigitalMe Tutorial
-----------------------------------------------

N.B. zxid.org does not yet support Infocard, but since we
are starting the investigation, we thought to share
some of it

97.15.1 Installing DigitalMe and Firefox plugin
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

DigitalMe by Bandit project is an open source Infocard
implementation, providing functionality roughly similar to
CardSpace. You can download it from

  http://www.bandit-project.org/index.php/Digital_Me

rpm2cpio digitalme-0.4.1238-2.1.i586.rpm | cpio -di

97.15.2 Setting up IdP account
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

For one InfoCard aware IdP, please see: http://www.cdatazone.org/index.php?/archives/27-Managed-Infocard-Demo.html

1. Register at the IdP site (e.g. https://www.ctindustries.net/icard/index.php)
2. Download the card ("Retrieve Managed Card" link (savea as "cdatamanaged.crd" by default).
3. Install the card to DigitalMe

97.15.9 Legal
~~~~~~~~~~~~~

Microsoft promises to not sue you: http://www.microsoft.com/interop/osp/default.mspx

97.16 Attributes
----------------

Q:: I want to read the attributes that come in the assertion. how do I do that?

A:: You get attributes back as an LDIF entry as return value of zxid_simple()
    The attributes are also available by reparsing the assertion, which gets
    stored in /var/zxid/rely hierarchy.

    /var/zxid/ses/SuzZQS5Ub/.ses file contains the path to the assertion file.

Q:: In the zxid directory you store some users. what does the extension .mni stand for?
    Why is the info stored? I assume it is some sort of local cache. I would like
    to store the attributes there too. how do I do that?

A:: The .mni file is used to support Manage NameID requests. In normal operation of ZXID
    it really is not needed, but to support some of the SAML conformance test requests
    it is needed.

    Rather than store attributes in that directory, I'd suggest reparsing
    the assertion when you need them. But if you must, you could create a
    file of your own in that directory. We of course need a naming
    convention that prevents naming conflicts with future versions of
    ZXID: Your file extension should start by ".x-", for example:
    "attributes.x-attr"

Q:: The ldif returned by zxid_simple() is perfect for my needs. but
    nothing is being stored in log\rely directory. could be some
    configuration issue? also, can I have zxid automatically store the
    ldif file returned zxid_simple()?

A:: The log/rely should be populated by default, but if the directory
    structure itself is missing, may be it does not work. Try make dirs.
    Or check that web server user's permissions allow writing there.

A:: Re ldif cached: the logic is supposed to be that the zxid_simple() will
    be called to protect every page, therefore its return value is available
    on every page.

    If you do not call it every time, but instead bootstrap some sort of
    app specific session, then you would strore the LDIF (or the attributes
    parsed out of it) to that app specific session.

98 Support
==========

98.1 Mailing list and forums
----------------------------

* Official ZXID mailing list is zxid.user@lists.unh.edu
* The archives can be seen at http://listproc.unh.edu/archives/zxid.user

98.2 Bugs
---------

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

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

98.9 Commercial Support
-----------------------

Following companies provide consultancy and support contracts for
ZXID:

* symlabs.com
* mercnet.pt

99 Appendix: Schema Grammars
============================

Large parts of ZXID code are generated from +schema grammars+ which
are a convenient notation for describing XML schmata. This chapter
gives a sampling of some schema grammars that are currently implemented and
distributed in the ZXID package. For fuller list, see sg subdirectory
of the distribution or schemata.pd file.

<<table: Schema grammar syntax
Construct     Description
============= ====================================================================
  ee          Bareword signifies an XML element
  @aa         At (@) prefix signifies an XML attribute
  %tt         Percent (%) prefix signifies a complexType
  &gg         Ampersand (&) prefix a signifies group
  &@ag        Ampersand and at (&@) prefix signifies attributeGroup
  xx -> %tt   Arrow (->) signifies reference to type that defines element or attribute
  xx: ... ;   Colon (:) means that the definition of type follows immediately
  ee          An element or attribute by itself means exactly one occurance is expected
  ee?         Question mark (?) means the element or attribute is optional
  ee*         Asterisk (*) means the element may appear from zero to infinite number of times (same as * in regular expressions)
  ee+         Plus (+) means the element must appear at least once, but may appear an infinite number of times (same as + in regular expressions)
  ee{x,y}     The element must appear between x and y times (same as in regex)
  ee | ee     The pipey symbol (|) means elements are mutually exclusive choices.
  ee ee       Concatenation of elements or attributes means sequence
  base( t )   Introduce Extension base type (derive a type)
  redef( .. ) Redefine a type (using <xs:redefine> construct)
  mixed(1)    Mark a complex type as having mixed content type, i.e. strings and elements alternate
  enum( ... ) Introduce enumeration of xs:strings
  any         xs:any, the XML arbitrary element extension mechanism
  @any        xs:anyAttribute, the XML arbitrary attribute extension mechanism
target( ... ) Define target namespace described by the schema
import( ... ) Bring in other schemata and namespaces
ns( ... )     Declare existence of another namespace (without importing it)
>>

<<tex: \small>>

99.1 SAML 2.0
-------------

99.1.1 saml-schema-assertion-2.0 (sa)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

<<schema:
<<sg/saml-schema-assertion-2.0.sg>>
>>

99.1.2 saml-schema-protocol-2.0 (sp)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

<<schema:
<<sg/saml-schema-protocol-2.0.sg>>
>>

99.1.4 saml-schema-metadata-2.0 (md)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

<<schema:
<<sg/saml-schema-metadata-2.0.sg>>
>>

99.5 Liberty ID-WSF 2.0
-----------------------

99.5.1 liberty-idwsf-utility-v2.0 (lu)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

<<schema:
<<sg/liberty-idwsf-utility-v2.0.sg>>
>>

99.5.3 liberty-idwsf-soap-binding-v2.0 (b)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

<<schema:
<<sg/liberty-idwsf-soap-binding-v2.0.sg>>
>>

99.5.4 liberty-idwsf-security-mechanisms-v2.0 (sec)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

<<schema:
<<sg/liberty-idwsf-security-mechanisms-v2.0.sg>>
>>

99.5.5 liberty-idwsf-disco-svc-v2.0 (di)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

<<schema:
<<sg/liberty-idwsf-disco-svc-v2.0.sg>>
>>

99.5.7 id-dap (dap)
~~~~~~~~~~~~~~~~~~~

<<schema:
<<sg/id-dap.sg>>
>>

99.5.8 liberty-idwsf-subs-v1.0 (subs)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

<<schema:
<<sg/liberty-idwsf-subs-v1.0.sg>>
>>

99.5.9 liberty-idwsf-dst-v2.1 (dst)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

<<schema:
<<sg/liberty-idwsf-dst-v2.1.sg>>
>>

99.6 SOAP 1.1 Processor wsf-soap11 (e)
--------------------------------------

<<schema:
<<sg/wsf-soap11.sg>>
>>

99.7 XML and Web Services Infrastructure
----------------------------------------

99.7.1 xmldsig-core (ds)
~~~~~~~~~~~~~~~~~~~~~~~~

<<schema:
<<sg/xmldsig-core.sg>>
>>

99.7.2 xenc-schema (xenc)
~~~~~~~~~~~~~~~~~~~~~~~~~

<<schema:
<<sg/xenc-schema.sg>>
>>

99.7.3 ws-addr-1.0 (a)
~~~~~~~~~~~~~~~~~~~~~~

<<schema:
<<sg/ws-addr-1.0.sg>>
>>

100 Appendix: Some Example XML Blobs
====================================

These XML blobs are for reference. They have been pretty
printed. Indentation indicates nesting level and closing tags have
been abbreviated as "</>". The actual XML on wire generally does not
have any whitespace.

100.1 SAML 2.0 Artifact Response with SAML 2.0 SSO Assertion and Two Bootstraps
-------------------------------------------------------------------------------

This example corresponds to t/sso-w-bootstraps.xml in the distribution.

Both bootstraps illustrate SAML assertion as bearer token.

 <soap:Envelope
    xmlns:lib="urn:liberty:iff:2003-08"
    xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:wsa="http://www.w3.org/2005/08/addressing">
  <soap:Body>

    <sp:ArtifactResponse
        xmlns:sp="urn:oasis:names:tc:SAML:2.0:protocol"
        ID="REvgoIIlkzTmk-aIX6tKE"
        InResponseTo="RfAsltVf2"
        IssueInstant="2007-02-10T05:38:15Z"
        Version="2.0">
      <sa:Issuer
          xmlns:sa="urn:oasis:names:tc:SAML:2.0:assertion"
          Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">
        https://a-idp.liberty-iop.org:8881/idp.xml</>
      <sp:Status>
        <sp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/></>

      <sp:Response
          xmlns:sp="urn:oasis:names:tc:SAML:2.0:protocol"
          ID="RCCzu13z77SiSXqsFp1u1"
          InResponseTo="NojFIIhxw"
          IssueInstant="2007-02-10T05:37:42Z"
          Version="2.0">
        <sa:Issuer
            xmlns:sa="urn:oasis:names:tc:SAML:2.0:assertion"
            Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">
          https://a-idp.liberty-iop.org:8881/idp.xml</>
        <sp:Status>
          <sp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/></>

        <sa:Assertion
            xmlns:sa="urn:oasis:names:tc:SAML:2.0:assertion"
            ID="ASSE6bgfaV-sapQsAilXOvBu"
            IssueInstant="2007-02-10T05:37:42Z"
            Version="2.0">
          <sa:Issuer Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">
            https://a-idp.liberty-iop.org:8881/idp.xml</>

          <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
            <ds:SignedInfo>
              <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
              <ds:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
              <ds:Reference URI="#ASSE6bgfaV-sapQsAilXOvBu">
                <ds:Transforms>
                  <ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
                  <ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/></>
                <ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
                <ds:DigestValue>r8OvtNmq5LkYwCNg6bsRZAdT4NE=</></></>
            <ds:SignatureValue>GtWVZzHYW54ioHk/C7zjDRThohrpwC4=</></>

          <sa:Subject>
            <sa:NameID
                Format="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent"
                NameQualifier="https://a-idp.liberty-iop.org:8881/idp.xml">PB5fLIA4lRU2bH4HkQsn9</>
            <sa:SubjectConfirmation
                Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
              <sa:SubjectConfirmationData
                  NotOnOrAfter="2007-02-10T06:37:41Z"
                  Recipient="https://sp1.zxidsp.org:8443/zxidhlo?o=B"/></></>

          <sa:Conditions
              NotBefore="2007-02-10T05:32:42Z"
              NotOnOrAfter="2007-02-10T06:37:42Z">
            <sa:AudienceRestriction>
              <sa:Audience>https://sp1.zxidsp.org:8443/zxidhlo?o=B</></></>

          <sa:Advice>

            <!-- This assertion is the credential for the ID-WSF 1.1 bootstrap (below). -->

            <sa:Assertion
                ID="CREDOTGAkvhNoP1aiTq4bXBg"
                IssueInstant="2007-02-10T05:37:42Z"
                Version="2.0">
              <sa:Issuer
                  Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">
                https://a-idp.liberty-iop.org:8881/idp.xml</>
              <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
                <ds:SignedInfo>
                  <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
                  <ds:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
                  <ds:Reference URI="#CREDOTGAkvhNoP1aiTq4bXBg">
                    <ds:Transforms>
                      <ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
                      <ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/></>
                    <ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
                    <ds:DigestValue>dqq/28hw5eEv+ceFyiLImeJ1P8w=</></></>
                <ds:SignatureValue>UKlEgHKQwuoCE=</></>
              <sa:Subject>
                <sa:NameID/>  <!-- *** Bug here!!! -->
                <sa:SubjectConfirmation
                    Method="urn:oasis:names:tc:SAML:2.0:cm:bearer"/></>
              <sa:Conditions
                  NotBefore="2007-02-10T05:32:42Z"
                  NotOnOrAfter="2007-02-10T06:37:42Z">
                <sa:AudienceRestriction>
                  <sa:Audience>https://sp1.zxidsp.org:8443/zxidhlo?o=B</></></></></>

          <sa:AuthnStatement
              AuthnInstant="2007-02-10T05:37:42Z"
              SessionIndex="1171085858-4">
            <sa:AuthnContext>
              <sa:AuthnContextClassRef>
                urn:oasis:names:tc:SAML:2.0:ac:classes:Password</></></>

          <sa:AttributeStatement>

            <!-- Regular attribute -->

            <sa:Attribute
                Name="cn"
                NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
              <sa:AttributeValue>Sue</></>

            <!-- ID-WSF 1.1 Bootstrap for discovery. See also the Advice, above. -->

            <sa:Attribute
                Name="DiscoveryResourceOffering"
                NameFormat="urn:liberty:disco:2003-08">
              <sa:AttributeValue>
                <di12:ResourceOffering
                    xmlns:di12="urn:liberty:disco:2003-08"
                    entryID="2">
                  <di12:ResourceID>
                    https://a-idp.liberty-iop.org/profiles/WSF1.1/RID-DISCO-sue</>
                  <di12:ServiceInstance>
                    <di12:ServiceType>urn:liberty:disco:2003-08</>
                    <di12:ProviderID>https://a-idp.liberty-iop.org:8881/idp.xml</>
                    <di12:Description>
                      <di12:SecurityMechID>urn:liberty:security:2005-02:TLS:Bearer</>
                      <di12:CredentialRef>CREDOTGAkvhNoP1aiTq4bXBg</>
                      <di12:Endpoint>https://a-idp.liberty-iop.org:8881/DISCO-S</></></>
                  <di12:Abstract>Symlabs Discovery Service Team G</></></></>

            <!-- ID-WSF 2.0 Bootstrap for Discovery. The credential (bearer token) is inline. -->

            <sa:Attribute
                Name="urn:liberty:disco:2006-08:DiscoveryEPR"
                NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
              <sa:AttributeValue>
                <wsa:EndpointReference
                    xmlns:wsa="http://www.w3.org/2005/08/addressing"
                    xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
                    notOnOrAfter="2007-02-10T07:37:42Z"
                    wsu:Id="EPRIDcjP8ObO9In47SDjO9b37">
                  <wsa:Address>https://a-idp.liberty-iop.org:8881/DISCO-S</>
                  <wsa:Metadata xmlns:di="urn:liberty:disco:2006-08">
                    <di:Abstract>SYMfiam Discovery Service</>
                    <sbf:Framework xmlns:sbf="urn:liberty:sb" version="2.0"/>
                    <di:ProviderID>https://a-idp.liberty-iop.org:8881/idp.xml</>
                    <di:ServiceType>urn:liberty:disco:2006-08</>
                    <di:SecurityContext>
                      <di:SecurityMechID>urn:liberty:security:2005-02:TLS:Bearer</>

                      <sec:Token
                          xmlns:sec="urn:liberty:security:2006-08"
                          usage="urn:liberty:security:tokenusage:2006-08:SecurityToken">

                        <sa:Assertion
                            ID="CREDV6ZBMyicmyvDq9pLIoSR"
                            IssueInstant="2007-02-10T05:37:42Z"
                            Version="2.0">
                          <sa:Issuer Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">
                            https://a-idp.liberty-iop.org:8881/idp.xml</>
                          <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
                            <ds:SignedInfo>
                              <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
                              <ds:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
                              <ds:Reference URI="#CREDV6ZBMyicmyvDq9pLIoSR">
                                <ds:Transforms>
                                  <ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
                                  <ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/></>
                                <ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
                                <ds:DigestValue>o2SgbuKIBzl4e0dQoTwiyqXr/8Y=</></></>
                            <ds:SignatureValue>hHdUKaZ//cZ8UYJxvTReNU=</></>
                          <sa:Subject>
                            <sa:NameID
                                Format="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent"
                                NameQualifier="https://a-idp.liberty-iop.org:8881/idp.xml">
                              9my93VkP3tSxEOIb3ckvjLpn0pa6aV3yFXioWX-TzZI=</>
                            <sa:SubjectConfirmation
                                Method="urn:oasis:names:tc:SAML:2.0:cm:bearer"/></>
                          <sa:Conditions
                              NotBefore="2007-02-10T05:32:42Z"
                              NotOnOrAfter="2007-02-10T06:37:42Z">
                            <sa:AudienceRestriction>
                              <sa:Audience>https://a-idp.liberty-iop.org:8881/idp.xml</></></>
                          <sa:AuthnStatement AuthnInstant="2007-02-10T05:37:42Z">
                            <sa:AuthnContext>
                              <sa:AuthnContextClassRef>
                                urn:oasis:names:tc:SAML:2.0:ac:classes:Password</></></></></></></></></></></></></></></></>

N.B. The AttributeStatement/Attribute/AttributeValue/
EndpointReference/Metadata/SecurityContext/
Token/Assertion/Conditions/AudienceRestriction/Audience is the same as
the IdP because in many products the IdP and Discovery Service roles
are implemented by the same entity. Note also that the audience of the inner
assertion is the discovery service where as the audience of the outer assertion
is the SP that will eventually call the Discovery Service.

100.2 ID-WSF 2.0 Call with X509v3 Sec Mech
------------------------------------------

 <e:Envelope
    xmlns:e="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:b="urn:liberty:sb:2005-11"
    xmlns:sec="urn:liberty:security:2005-11"
    xmlns:wsse="http://docs.oasis-open.org/wss/20 04/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
    xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
    xmlns:wsa="http://www.w3.org/2005/08/ addressing">
  <e:Header>
    <wsa:MessageID wsu:Id="MID">123</>
    <wsa:To wsu:Id="TO">...</>
    <wsa:Action wsu:Id="ACT">urn:xx:Query</>
    <wsse:Security mustUnderstand="1">
      <wsu:Timestamp wsu:Id="TS"><wsu:Created>2005-06-17T04:49:17Z</></>
      <wsse:BinarySecurityToken
          ValueType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3"
          wsu:Id="X509Token"
          EncodingType="http://docs.oas is-open.org/wss/2004/01/oasis-200401-wss-soap-message-securiy-1.0#Base64Binary">
        MIIB9zCCAWSgAwIBAgIQ...</>
      <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        <ds:SignedInfo>
          <ds:Reference URI="#MID">...</>
          <ds:Reference URI="#TO">...</>
          <ds:Reference URI="#ACT">...</>
          <ds:Reference URI="#TS">...</>
          <ds:Reference URI="#X509">
            <ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
            <ds:DigestValue>Ru4cAfeBAB</></>
          <ds:Reference URI="#BDY">
            <ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
            <ds:DigestValue>YgGfS0pi56p</></></>
        <ds:KeyInfo><wsse:SecurityTokenReference><wsse:Reference URI="#X509"/></></>
        <ds:SignatureValue>HJJWbvqW9E84vJVQkjDElgscSXZ5Ekw==</></></></>
  <e:Body wsu:Id="BDY">
    <xx:Query/></></>

The salient features of the above XML blob are

* Signature that covers relevant SOAP headers and Body
* Absence of any explicit identity token.

Absence of identity token means that from the headers it is not
possible to identify the taget identity. The signature generally
coveys the Invoker identity (the WSC that is calling the
service). Since one WSC typically serves many principals, knowing
which principal is impossible.  For this reason X509 security mechanism is
seldom used in ID-WSF 2.0 world (with ID-WSF 1.1 the ResourceID
provides an alternative way of identifying the principal, thus making
X509 a viable option).

100.3 ID-WSF 2.0 Call with Bearer (Binary) Sec Mech
---------------------------------------------------

 <e:Envelope
    xmlns:e="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:b="urn:liberty:sb:2005-11"
    xmlns:sec="urn:liberty:security:2005-11"
    xmlns:wsse="http://docs.oasis-open.org/wss/20 04/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
    xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
    xmlns:wsa="http://www.w3.org/2005/03/ addressing">
  <e:Header>
    <wsa:MessageID wsu:Id="MID">...</>
    <wsa:To wsu:Id="TO">...</>
    <wsa:Action wsu:Id="ACT">urn:xx:Query</>
    <wsse:Security mustUnderstand="1">
      <wsu:Timestamp wsu:Id="TS">
        <wsu:Created>2005-06-17T04:49:17Z</></>
      <wsse:BinarySecurityToken
          ValueType="anyNSPrefix:ServiceSess ionContext"
          EncodingType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64 Binary"
          wsu:Id="BST">
        mQEMAzRniWkAAAEH9RWir0eKDkyFAB7PoFazx3ftp0vWwbbzqXdgcX8fpEqSr1v4
        YqUc7OMiJcBtKBp3+jlD4HPUaurIqHA0vrdmMpM+sF2BnpND118f/mXCv3XbWhiL
        VT4r9ytfpXBluelOV93X8RUz4ecZcDm9e+IEG+pQjnvgrSgac1NrW5K/CJEOUUjh
        oGTrym0Ziutezhrw/gOeLVtkywsMgDr77gWZxRvw01w1ogtUdTceuRBIDANj+KVZ
        vLKlTCaGAUNIjkiDDgti=</>
      <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig #">
        <ds:SignedInfo>
          <ds:Reference URI="#MID">...</>
          <ds:Reference URI="#TO">...</>
          <ds:Reference URI="#ACT">...</>
          <ds:Reference URI="#TS">...</>
          <ds:Reference URI="#BST">...</>
          <ds:Reference URI="#BDY">
            <ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1 "/>
            <ds:DigestValue>YgGfS0pi56pu</></></>
        ...</></></>
  <e:Body wsu:Id="BDY">
    <xx:Query/></></>

100.4 ID-WSF 2.0 Call with Bearer (SAML) Sec Mech
-------------------------------------------------

 <e:Envelope
    xmlns:e="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:sb="urn:liberty:sb:2005-11"
    xmlns:sec="urn:liberty:security:2005-11"
    xmlns:wsse="http://docs.oasis-open.org/wss/20 04/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
    xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
    xmlns:wsa="http://www.w3.org/2005/08/addressing"
    xmlns:ds="http://www.w3.org/2000/09/xmldsig#"
    xmlns:xenc="http://www.w3.org/2001/04/xmlenc#">
  <e:Header>
    <sbf:Framework version="2.0-simple" e:mustUnderstand="1"
      e:actor="http://schemas.../next"
      wsu:Id="SBF"/>
    <wsa:MessageID wsu:Id="MID">...</>
    <wsa:To wsu:Id="TO">...</>
    <wsa:Action wsu:Id="ACT">urn:xx:Query</>
    <wsse:Security mustUnderstand="1">
      <wsu:Timestamp wsu:Id="TS">
        <wsu:Created>2005-06-17T04:49:17Z</></>

      <sa:Assertion
          xmlns:sa="urn:oasis:names:tc:SAML:2.0:assertion"
          Version="2.0"
          ID="A7N123"
          IssueInstant="2005-04-01T16:58:33.173Z">
        <sa:Issuer>http://idp.symdemo.com/idp.xml</>
        <ds:Signature>...</>
        <sa:Subject>
          <sa:EncryptedID>
            <xenc:EncryptedData>U2XTCNvRX7Bl1NK182nmY00TEk==</>
            <xenc:EncryptedKey>...</></>
          <sa:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer"/></>
        <sa:Conditions
            NotBefore="2005-04-01T16:57:20Z"
            NotOnOrAfter="2005-04-01T21:42:4 3Z">
          <sa:AudienceRestrictionCondition>
            <sa:Audience>http://wsp.zxidsp.org</></></>
        <sa:AuthnStatement
            AuthnInstant="2005-04-01T16:57:30.000Z"
            SessionIndex="6345789">
          <sa:AuthnContext>
            <sa:AuthnContextClassRef>
              urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</></></>
        <sa:AttributeStatement>
          <sa:EncryptedAttribute>
            <xenc:EncryptedData Type="http://www.w3.org/2001/04/xmlenc#Element">
              mQEMAzRniWkAAAEH9RbzqXdgcX8fpEqSr1v4=</>
            <xenc:EncryptedKey>...</></></></>

      <wsse:SecurityTokenReference
          xmlns:wsse11="..."
          wsu:Id="STR1"
          wsse11:TokenType="http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV2.0">
        <wsse:KeyIdentifier
            ValueType="http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLID">
          A7N123</></>

      <ds:Signature>
        <ds:SignedInfo>
          <ds:Reference URI="#MID">...</>
          <ds:Reference URI="#TO">...</>
          <ds:Reference URI="#ACT">...</>
          <ds:Reference URI="#TS">...</>
          <ds:Reference URI="#STR1">
            <ds:Transform Algorithm="...#STR-Transform">
              <wsse:TransformationParameters>
                <ds:CanonicalizationMethod Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315"/></></></>
          <ds:Reference URI="#BDY"/></>
        ...</></></>
  <e:Body wsu:Id="BDY">
    <xx:Query/></></>

*** is the reference above to wsse11:TokenType really correct?

Note how the <Subject> and the attributes are encrypted such that only
the WSP can open them. This protects against WSC gaining knowledge of
the NameID at the WSP.

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

[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

>>

<<htmlpreamble: <title>README ZXID</title><body bgcolor="#330033" text="#ffaaff" link="#ffddff" vlink="#aa44aa" alink="#ffffff"><font face=sans><h1>README ZXID</h1> >>

<<notapath: TCP/IP a.k.a xBSD/Unix n/a Perl/mod_perl PHP/mod_php Java/Tomcat>>
<<EOF: >>

SAML Open Source catalogs
http://saml.xml.org/saml-open-source-implementations
http://openliberty.org/wiki/index.php/Existing_Identity_Systems#Open_Source_
http://docs.safehaus.org/display/HAUS/Id+OSS+Map

Suspicious: when decrypting elements and plugging their plain
text variants into original data structure, the wo pointers
are not updated. Thus the "old" encrypted data may remain
accessible for some purposes.

Pointers from Pat
http://rnd.feide.no/2007/04/13/light-bulb-update-request-for-testing/
https://opensso.dev.java.net/public/extensions/index.html

Add macros for OK response.

http://wiki.oasis-open.org/security/SstcSamlX509AuthnAttribProfile
http://wiki.oasis-open.org/security/SimpleSignBinding


On CYGWIN lockf() and flock() apparently are not defined.
On mingw they are.

Way to pass RelayState through zxid_simple()

AuditExplorer

elgg.org is very relevant for e-Learning / HR-XML market
https://imb.phil.uni-augsburg.de/elgg/

FEDORA

Moodle (Open Source, Open University)
MyStuff (Open Source, Open University)

Privacy features of SAML/Liberty
User centric features of SAML/Liberty
- User control (not necessarily interaction every steps of the way)

ECP + IS plugin for Firefox

==================
In general, wild card cert is one whose cn field is of form *.cellmail.com

The openssl command for creating CSR is 'openssl req', for example

> openssl req -new -nodes -keyout pkey.pem -out req.pem       
Generating a 1024 bit RSA private key
......................++++++
.................................................................................++++++
writing new private key to 'pkey.pem'
-----
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:FI
State or Province Name (full name) [Some-State]:
Locality Name (eg, city) []:Helsinki
Organization Name (eg, company) [Internet Widgits Pty Ltd]:Tietosampo
Organizational Unit Name (eg, section) []:
Common Name (eg, YOUR name) []:*.tietosampo.fi
Email Address []:sampo@iki.fi

Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:
An optional company name []:


In the example above I left the challenge password and company name empty, but
it could be that Thawte insists that you fill in something there. They may
also have specific requirements about the company name (and possibly the Organization
Name and Oraganization Unit Name) matching the registered name of your company.

Anyway, the output from the above should be

> cat req.pem 
-----BEGIN CERTIFICATE REQUEST-----

vxz/z/oQ8oFxyCwVUtTb4zKhT9rFEw==
-----END CERTIFICATE REQUEST-----

Or if you want to convince yourself that the wild card is
really in there, you can check with

> openssl asn1parse  <req.pem      
    0:d=0  hl=4 l= 450 cons: SEQUENCE          
    4:d=1  hl=4 l= 299 cons: SEQUENCE          
    8:d=2  hl=2 l=   1 prim: INTEGER           :00
   11:d=2  hl=3 l= 129 cons: SEQUENCE          
   14:d=3  hl=2 l=  11 cons: SET               
   16:d=4  hl=2 l=   9 cons: SEQUENCE          
   18:d=5  hl=2 l=   3 prim: OBJECT            :countryName
   23:d=5  hl=2 l=   2 prim: PRINTABLESTRING   :FI
   27:d=3  hl=2 l=  19 cons: SET               
   29:d=4  hl=2 l=  17 cons: SEQUENCE          
   31:d=5  hl=2 l=   3 prim: OBJECT            :stateOrProvinceName
   36:d=5  hl=2 l=  10 prim: PRINTABLESTRING   :Some-State
   48:d=3  hl=2 l=  17 cons: SET               
   50:d=4  hl=2 l=  15 cons: SEQUENCE          
   52:d=5  hl=2 l=   3 prim: OBJECT            :localityName
   57:d=5  hl=2 l=   8 prim: PRINTABLESTRING   :Helsinki
   67:d=3  hl=2 l=  19 cons: SET               
   69:d=4  hl=2 l=  17 cons: SEQUENCE          
   71:d=5  hl=2 l=   3 prim: OBJECT            :organizationName
   76:d=5  hl=2 l=  10 prim: PRINTABLESTRING   :Tietosampo
   88:d=3  hl=2 l=  24 cons: SET               
   90:d=4  hl=2 l=  22 cons: SEQUENCE          
   92:d=5  hl=2 l=   3 prim: OBJECT            :commonName
   97:d=5  hl=2 l=  15 prim: T61STRING         :*.tietosampo.fi
  114:d=3  hl=2 l=  27 cons: SET               
  116:d=4  hl=2 l=  25 cons: SEQUENCE          
  118:d=5  hl=2 l=   9 prim: OBJECT            :emailAddress
  129:d=5  hl=2 l=  12 prim: IA5STRING         :sampo@iki.fi
  143:d=2  hl=3 l= 159 cons: SEQUENCE          
  146:d=3  hl=2 l=  13 cons: SEQUENCE          
  148:d=4  hl=2 l=   9 prim: OBJECT            :rsaEncryption
  159:d=4  hl=2 l=   0 prim: NULL              
  161:d=3  hl=3 l= 141 prim: BIT STRING        
  305:d=2  hl=2 l=   0 cons: cont [ 0 ]        
  307:d=1  hl=2 l=  13 cons: SEQUENCE          
  309:d=2  hl=2 l=   9 prim: OBJECT            :sha1WithRSAEncryption
  320:d=2  hl=2 l=   0 prim: NULL              
  322:d=1  hl=3 l= 129 prim: BIT STRING        

Here we can see that hitting empty for State or Provice question was not
such a smart idea after all: it used nonsensical default value. I guess
you would have to invent something as place holder.
 
> On another train of thought, if I was to have a local CA here, could I use the
> commercial certificate I get to sign the x509 certificates I would make? The
> x509 would be used to sign emails via smart cards. This is not a commercial
> project but rather one to learn more about smart cards. Sun has made code
> available to manage smart cards so it may be interesting to learn more.

The regular SSL certificate usually will not work as CA certificate due
to certificate usage indicators. Technically it is possible to ignore
such indicators and use the certificate anyway, but a lot of widely
distributed software does not ignore them so you would have a lot of
interoperability problems or at least confirmation questions.

Commercial CAs do issue CA certificates, but they tend to be expensive.

Even if you get commercial CA certificate, you should know that some (older)
software only supports one level of certificate hierarchy. This problem
has surfaced when some commercial CAs tried to structure themselves
internally as multi layer CA.

If you want to run your own CA, all you really have to do is configure
the CA cert of yours to be trusted by all the software. For browsers
this is easy enough within the GUI itself. For servers (such as apache
or dsproxy), there is a way to do this at config file level. Configuring
direct trust to your CA cert tends to be easier than trying to get
commercial CA cert and playing multilayer CA games.

Re Thunderbird, I am bit surprised that it does not accept self signed
certs. It seems more probable to me that it actually can be configured
to accept them, but does not ship with that turned on to protect
naive users. The most basic way to use self signed cert would be
to import the self signed cert as one of the trusted CA certs.

Was your problem with Thunderbird not accepting the IMAPS connection? In
that case the Thunderbird client software needs to start trusting the
self signed cert as CA cert. There is probably a GUI way to do this - probably
something very similar to the Firefox GUI for configuring certs.

If you were trying to configure a ClientTLS certificate and the IMAPS
server refused it, then you need to adjust configuration in the
server end, probably in a config file.



-----

ZXID CARML stack

* frontend API bindings
* middle layer routing and mapping engine
* backend connectors

--Sampo


-----

http://saml.xml.org/products
http://saml.xml.org/zxid

ZXID.org Identity Management toolkit implements standalone SAML 2.0
and Liberty ID-WSF 2.0 stacks. It is a C implementation with minimal
external dependencies - OpenSSL, CURL, and zlib - ensuring easy
deployment (no DLLhell). Due to its small footprint and efficient and
accurate schema driven implementation, it is suitable for embedded and
high volume applications. Language bindings to all popular highlevel
languages such as PHP, Perl, and Java, are provided via SWIG.  ZXID
implements, as of July 07, SP, WSC, and WSP roles.




Paul Madsen wrote:
> http://saml.xml.org/forum/calculating-digest-of-an-authentication-statement
> 
> Dear Sirs, my name is Gianluca from Italy
>  I'm trying to calculate the Digest value of a SAML Authentication
> STatement whith the SHA-1 algorithm. Let us suppose that we are dealing
> with a string representing the following node:
> 
> <saml:AuthenticationStatement>
>     <saml:Subject>
>         <saml:NameIdentifier>GIANLUCA</saml:NameIdentifier>
>     </saml:Subject>
> </saml:AuthenticationStatement>
> 
> When I try to calculate SHA-1 with the function  b64_sha1(str2Digest) 
> what
> exactly should the string str2Digest contain? I mean it should be equal to
> "<saml:AuthenticationStatement><saml:Subject><saml:NameIdentifier>GIANLUCA<
> /saml:NameIdentifier></saml:Subject></saml:AuthenticationStatement>"
> or only "GIANLUCA" or ....what else?

Its a pity he did not provide email address, but lets hope this reaches
him anyway.

1. There is no univesally agreed way to digest Authentication Statements
2. "Universally" agreed way to digest XML in general is exc-c14n (exclusive
   canonicalization) [XML-EXC-C14N]. This method is used by all certified
   SAML implementations. It is also the method used by digital
   signatures [XMLDSIG].
3. Canonicalization is difficult and typically 80% of digital signature
   failures derive from canonicalization bugs. Of those 95% are
   XML namespace related (curse the inventor of XML namespaces), and
   4% are whitespace related.
4. For what you are apparently trying to do, it is important to
   digest the entire canonicalized Authentication Statement.
   If the question had been about canonicalizing the NameID, it
   would still be important to digest the entire canonicalized
   Name Identifier as the actual value in isolation is meaningless.
   You need the identifier type and namespace qualification
   for the digest to be meaningful.

[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/ 

[XMLDSIG] "XML-Signature Syntax and Processing", W3C Recommendation, 12.2.2002, http://www.w3.org/TR/xmldsig-core, RFC3275

Cheers,
--Sampo
