README.zxid
Apr 17, 2008
Download as pdf
Single page
Table of Contents
1 Who needs this?
2 Installing
2.1 Prerequisites
2.2 Canned Tutorial: Running ZXID as CGI under mini_httpd
2.2.1 Getting and installing mini_httpd
2.2.2 Running mini_httpd
2.2.3 Accessing ZXID
2.2.4 Setting up an IdP
2.2.5 Your first SSO
3 Configuring and Running
3.1 Configuration Parameters
3.1.1 zxidroot (PATH configuration parameter)
3.1.2 pem
3.1.3 cot
3.2 Configuration File Format
4 Logging and Audit
4.1 Filesystem Layout for Logs
4.2 Log Line Format
4.3 Log Signing and Encryption
4.4 Internal Crypto Formats
4.5 Logging Assertions
4.6 Logging Requests and Responses
4.7 Session Storage and Bootstraps
4.7.1 Session directory
4.7.2 User directory
5 Compilation for Experts
5.1 Build Process
5.2 Special or embedded compile (reduced functionality)
5.2.1 Compilation without OpenSSL
5.2.2 Compilation without libcurl
5.2.3 Compiling without zlib (not supported)
5.3 Choosing Which Standards to Compile in (default: all)
5.4 localconf.mk
5.5 Tough Compilation Errors
5.6 Tough Linking Errors
5.7 Overview of the xsd2sg.pl Tool
5.7.1 Process .sg to create %dt hash (throw away XSD output)
5.7.2 The expanding element definitions in %dt
5.7.3 Generation Phase
6 Net::SAML Perl Module
6.1 Current major modules are
6.2 Planned modules
6.3 Perl API Adaptations
6.4 Testing Net::SAML and zxid.pl as CGI script
6.5 Testing Net::SAML and zxid.pl under mod_perl
6.6 Debugging Net::SAML with GDB
7 PHP extension php_zxid.so
7.1 Building and Installing ZXID PHP extension
7.1.1 Running PHP as Apache mod_php
7.1.2 Running PHP as CGI (any web server)
7.2 Programming with ZXID PHP Extension
8 Python Extension
9 Java Native API (JNI): zxidjava package and zxidjni class
9.1 Building the JNI
9.1.1 MacOS X: JNI Notes
9.2 Programming with ZXID Java API
9.3 Known Problems and Limitations
9.4 Running as servlet under Tomcat
9.5 Troubleshooting class loader
9.6 Logging and Debugging Tips
9.7 Debugging libzxidjni.so under jdb and gdb
10 zxid_simple() API
10.1 Hello World
10.1.1 Configuration Options
10.1.2 AUTO options
10.1.3 Configuration options for customizing HTML
10.2 Gaining More Control
10.3 Some Generalization and Optimizations
10.4 Java Servlet Example Using Tomcat
10.5 Shell Script API
10.6 Form Field Naming
10.6.1 Common Fields
10.6.2 IdP Selection (Login) Screen
10.6.3 Single Logout and Federation Management
11 Integration with Existing Web Sites
11.1 Brief Overview of Control Flow
11.2 Redirect Approach to Integration
11.3 Pass-thru Approach to Integration
11.3.1 mod_perl pass-thru
11.3.2 PHP pass-thru
11.3.3 mod_zxid pass-thru
11.4 Proxy Approach to Integration
12 Full Native C API
12.1 C Data Structures
12.1.1 Handling XML Namespaces
12.1.2 Handling any and anyAttribute
12.1.3 Root data structure
12.1.4 Per element data structures
12.1.5 Memory Allocation
12.2 Decoder as Recursive Descent Parser
12.2.1 Element Decoders
12.2.2 Decoder Extension Points
12.3 Exclusive Canonical Encoder
12.3.1 Length computation
12.3.2 Encoding in schema order
12.3.3 Encoding in wire order
12.4 Signatures (XMLDSIG)
12.4.1 Signature Generation
12.4.2 Signature Validation
12.4.3 Certificate Validation and Trust Model
12.5 Data Accessor Functions
12.6 Memory Allocation and Free
12.7 Walking the data structure
12.8 Thread Safety
13 ID-WSF Features of ZXID
13.1 EPR Cache
13.2 High level WSC API
13.2.1 zxid_callf() - Make SOAP call with specified body
13.2.2 ZXID_CHK_STATUS() - Macro for checking OK status
13.3 Low Level WSC API
13.3.1 zxid_get_epr() - Obtain EPR fron cache or by discovery
13.4 ID-DAP Interface
13.4.1 Short example of using low level API
13.4.2 Fully winded example of using low level API
13.4.3 zxid_mk_dap_query()
13.4.4 zxid_mk_dap_query_item()
13.4.5 zxid_mk_dap_select()
13.4.6 zxid_mk_dap_test_item()
13.4.7 zxid_mk_dap_testop()
13.4.8 zxid_mk_dap_subscription()
13.4.9 zxid_mk_dap_resquery()
13.5 ID Messaging Interface
13.6 ID Geo Location Interface
13.7 Contact Book Interface
13.8 People Service Interface
13.9 Interface to Conor's Demo Media Service
13.10 ID-SIS Data Service for HR-XML
14 Integration of Other Libraries with ZXID
14.1 Conor Cahill's C++ Library for ID-WSF
14.2 Pat Patterson's php module
14.3 Sun OpenSSO
15 Creating New Interfaces Using ZXID Methodology
16 ZXID Project
16.1 Project Layout
16.2 Protocol Encoders and Decoders
16.3 Standards and Namespaces
17 Code Generation Tools
17.1 Special Support for Specific Programming Languages
18 ZXID SP
19 Certificates
20 Testing
21 License
21.1 Dependency library licenses
21.2 Specification IPR
21.3 Further Warranties
22 FAQ
22.1 Compilation Problems
22.1.1 OpenSSL not found: you need to create localconf.mk
22.1.2 Missing gperf
22.1.3 make samlmod gives "incompatibe types in assignment"
22.1.4 Perl compiled with different compiler than zxid
22.1.5 All files under zx missing
22.1.6 Compiler Warnings
22.1.7 SWIG and Java Problems
22.2 Platform Specifics
22.2.1 Linux
22.2.2 FreeBSD
22.2.3 Solaris (Sparc)
22.2.4 MacOS X (PowerPC?)
22.2.5 Windows Using MinGW
22.2.6 Windows Using Cygwin
22.2.7 Windows Using MSVC
22.3 Common Mistakes
22.4 Consent
22.5 Deployment Planning
22.6 Use of Signing and Crypto, Security Concerns
22.7 Vendor products
22.7.1 Symlabs Federated Identity Suite (SFIS)
22.8 Known Bugs
22.9 Mysterious Error Messages
22.9.1 Password is being asked for private key
22.9.2 Quick command for looking at certificate
22.9.3 Self signed certificate
22.9.4 Checking that cert and private key belong together
22.9.5 snprintf() multibyte character related errors in log
22.9.6 My own messages are redirected back to me
22.9.7 SSL Handshake Fails
22.10 Author's Pet Peeves
22.11 What does ZXID aim at - an answer
22.12 Annoyances and improvement ideas
22.13 Non-obvious SAML
22.14 Best Practises
22.15 Cardspace / Infocard / DigitalMe Tutorial
22.15.1 Installing DigitalMe and Firefox plugin
22.15.2 Setting up IdP account
22.15.3 Legal
23 Support
23.1 Mailing list and forums
23.2 Bugs
23.3 Developer access
23.4 Commercial Support
24 Appendix: Schema Grammars
24.1 SAML 2.0
24.1.1 saml-schema-assertion-2.0 (sa)
24.1.2 saml-schema-protocol-2.0 (sp)
24.1.3 saml-schema-metadata-2.0 (md)
24.2 Liberty ID-WSF 2.0
24.2.1 liberty-idwsf-utility-v2.0 (lu)
24.2.2 liberty-idwsf-soap-binding-v2.0 (b)
24.2.3 liberty-idwsf-security-mechanisms-v2.0 (sec)
24.2.4 liberty-idwsf-disco-svc-v2.0 (di)
24.2.5 id-dap (dap)
24.2.6 liberty-idwsf-subs-v1.0 (subs)
24.2.7 liberty-idwsf-dst-v2.1 (dst)
24.3 SOAP 1.1 Processor wsf-soap11 (e)
24.4 XML and Web Services Infrastructure
24.4.1 xmldsig-core (ds)
24.4.2 xenc-schema (xenc)
24.4.3 ws-addr-1.0 (a)
25 Appendix: Some Example XML Blobs
25.1 SAML 2.0 Artifact Response with SAML 2.0 SSO Assertion and Two Bootstraps
25.2 ID-WSF 2.0 Call with X509v3 Sec Mech
25.3 ID-WSF 2.0 Call with Bearer (Binary) Sec Mech
25.4 ID-WSF 2.0 Call with Bearer (SAML) Sec Mech