ZXID Book - ZXID.org

Transcription

1
ZXID Book
2
Sampo Kellomäki ([email protected])
3
January 29, 2011
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
ZXID.org Identity Management toolkit implements standalone SAML 2.0, Liberty IDWSF 2.0, and XACML 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 January 2011, SP, IdP, Discovery, WSC, WSP, and PEP roles. ZXID.org
is the reference implementation of TAS3.eu project.
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, WSFederation, 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, IdP, Discovery, WSC, WSP und PEP fungieren.
A biblioteca de gestão de identidades ZXID.org é uma implementação, em C, das normas SAML 2.0, Liberty ID-WSF 2.0, e XACML 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 de performance. A biblioteca é disponibilizada para todos
as linguagens de programação de alto nível como, p.ex., PHP, Perl, e Java, atravez
de interfáces SWIG. ZXID de hoje (Jan 11) pode funcionar nos papeis SP (Provedor
de Serviços), IdP (Provedor de Identidade), Discovery (catálogo de serviços), WSC
(Cliente de Serviços Web), WSP (Provedor de Serviços Web), e PEP (Ponto de Enforçamento de Políticas). ZXID.org é a implementação de referência do projecto
TAS3.eu.
La librería de gestión de identidades ZXID.org es una implementación en C de las normas SAML 2.0, Liberty ID-WSF 2.0, y XAML 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 (Enero 2011) el ZXID soporta los
roles SP (proveedor de servicios), IdP (proveedor de identidades), Discovery (catalogo
de servicios), WSC (cliente de los servicios web), WSP (proveedor de servicios web)
y PEP (Punto de Enforco de Politicas). ZXID.org es el implantacion de referencia del
proyecto TAS3.eu.
ZXID.org on verkkohenkilöllisyyden ja -tunnisteiden hallintakirjasto joka tukee SAML
2.0 (sisäänkirjaantuminen), Liberty ID-WSF 2.0 (henkilöllisyyteen pohjautuvat webbipalvelut), ja XACML 2.0 (auktorisointi) 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 (Tammikuu 2011)
SP (palveluntarjoaja), IdP (henkilöllisyydenvarmentaja), Service Discovery (palvelunpaikannus), WSC (webbipalvelunkutsuja), WSP (webbipalveluntarjoaja) ja PEP (politiikantoteutuspiste) rooleja. ZXID.org on TAS3.eu projektin referenssitoteutus.
January 29, 2011
ZXID Book 34, p. 2
51
52
53
54
Contents
1
Introduction
17
1.1
17
ZXID Documentation Set . . . . . . . . . . . . . . . . . . . . . . . .
2 Install (package or from source)
Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
20
56
2.1.1
Additional Prerequisites for Complete Rebuild from Scratch .
20
57
2.1.2
Operating System and Platform Support . . . . . . . . . . . .
21
Canned Tutorial: Running ZXID as CGI under mini_httpd . . . . . .
21
59
2.2.1
Getting and installing mini_httpd . . . . . . . . . . . . . . .
22
60
2.2.2
Running mini_httpd . . . . . . . . . . . . . . . . . . . . . .
22
61
2.2.3
Accessing ZXID . . . . . . . . . . . . . . . . . . . . . . . .
22
62
2.2.4
Setting up an IdP . . . . . . . . . . . . . . . . . . . . . . . .
24
63
2.2.5
Your first SSO . . . . . . . . . . . . . . . . . . . . . . . . .
25
55
58
64
2.1
19
2.2
3 Compilation for Experts
27
65
3.1
Build Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
27
66
3.2
Special or embedded compile (reduced functionality) . . . . . . . . .
28
67
3.2.1
Compilation without OpenSSL . . . . . . . . . . . . . . . . .
28
68
3.2.2
Compilation without libcurl . . . . . . . . . . . . . . . . . .
29
69
3.2.3
Compiling without zlib (not supported) . . . . . . . . . . . .
29
70
3.3
Choosing Which Standards to Include (default: all) . . . . . . . . . .
30
71
3.4
localconf.mk . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
30
72
3.5
Known Compilation Warnings . . . . . . . . . . . . . . . . . . . . .
31
73
3.6
Tough Compilation Errors . . . . . . . . . . . . . . . . . . . . . . .
31
74
3.7
Tough Linking Errors . . . . . . . . . . . . . . . . . . . . . . . . . .
31
75
3.8
Overview of the xsd2sg.pl Tool (guru level) . . . . . . . . . . . . .
32
76
3.8.1
Process .sg to create %dt hash (throw away XSD output) . .
32
77
3.8.2
The expanding element definitions in %dt . . . . . . . . . . .
33
78
3.8.3
Generation Phase . . . . . . . . . . . . . . . . . . . . . . . .
33
3
CONTENTS
Integration with Existing Web Sites
35
80
4.1
Brief Overview of Control Flow . . . . . . . . . . . . . . . . . . . .
35
81
4.2
Redirect Approach to Integration . . . . . . . . . . . . . . . . . . . .
36
82
4.3
Pass-thru Approach to Integration . . . . . . . . . . . . . . . . . . .
37
83
4.3.1
mod_auth_saml pass-thru . . . . . . . . . . . . . . . . . . .
37
84
4.3.2
mod_perl pass-thru . . . . . . . . . . . . . . . . . . . . . . .
37
85
4.3.3
PHP pass-thru . . . . . . . . . . . . . . . . . . . . . . . . .
37
Proxy Approach to Integration . . . . . . . . . . . . . . . . . . . . .
37
79
4
CONTENTS
4.4
86
Testing
39
88
5.1
Test Suite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
40
89
5.2
Test Coverage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
43
87
5
Configuring Runtime
47
6.1
Configuration Parameters . . . . . . . . . . . . . . . . . . . . . . . .
48
92
6.1.1
zxidroot (PATH configuration parameter) . . . . . . . . . . .
48
93
6.1.2
pem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
48
94
6.1.3
cot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
49
ZXID Configuration File Format . . . . . . . . . . . . . . . . . . . .
49
90
6
91
6.2
95
96
7 zxid_simple() API Specific Configuration
51
97
7.0.1
Configuration Options . . . . . . . . . . . . . . . . . . . . .
51
98
7.0.2
AUTO options (auto flags) . . . . . . . . . . . . . . . . . . .
51
99
7.0.3
Configuration options for customizing HTML . . . . . . . . .
53
ZXID Attribute Broker (ZXAB)
55
8.1
Attribute Broker Configuration Directives . . . . . . . . . . . . . . .
56
102
8.1.1
NEED specification . . . . . . . . . . . . . . . . . . . . . . .
56
103
8.1.2
WANT specification . . . . . . . . . . . . . . . . . . . . . .
57
104
8.1.3
ATTRSRC specification . . . . . . . . . . . . . . . . . . . .
57
105
8.1.4
INMAP specification . . . . . . . . . . . . . . . . . . . . . .
58
106
8.1.5
OUTMAP specification . . . . . . . . . . . . . . . . . . . .
59
107
8.1.6
AAMAP specification . . . . . . . . . . . . . . . . . . . . .
59
100
101
8
January 29, 2011
ZXID Book 34, p. 4
CONTENTS
ZXID XACML PEP (and local PDP)
61
109
9.1
Local PDP Authorization Functionality . . . . . . . . . . . . . . . .
61
110
9.2
Configuring XACML PEP for Single Sign-On . . . . . . . . . . . . .
62
111
9.3
Configuring XACML PEPs for Web Service Calls . . . . . . . . . . .
63
112
9.4
Configuring UsageDirectives, including obligations pledges and requests 64
108
113
9
CONTENTS
10 Full Configuration Option Reference
65
114
10.1 Configuration Options . . . . . . . . . . . . . . . . . . . . . . . . .
65
115
10.1.1 Compile time configuration enforcement . . . . . . . . . . .
65
116
10.1.2 ZXID configuration and working directory path . . . . . . . .
66
117
10.1.3 SP Nickname for IdP User Interface . . . . . . . . . . . . . .
66
118
10.1.4 Web Site URL - root of EntityID . . . . . . . . . . . . . . . .
66
119
10.1.5 Override standard EntityID Construction . . . . . . . . . . .
66
120
10.1.6 Illadviced ACS URL Hack . . . . . . . . . . . . . . . . . . .
66
121
10.1.7 Common Domain Cookie URL . . . . . . . . . . . . . . . .
67
122
10.1.8 CDC designated IdP Handling . . . . . . . . . . . . . . . . .
67
123
10.1.9 Metadata Fetching Options . . . . . . . . . . . . . . . . . . .
67
124
10.1.10 Authentication Request Signing . . . . . . . . . . . . . . . .
68
125
10.1.11 Assertion Signing . . . . . . . . . . . . . . . . . . . . . . . .
68
126
10.1.12 SOAP Message Signing . . . . . . . . . . . . . . . . . . . .
68
127
10.1.13 IdP Signing Options . . . . . . . . . . . . . . . . . . . . . .
68
128
10.1.14 NameID Encryption . . . . . . . . . . . . . . . . . . . . . .
68
129
10.1.15 Assertion Encryption in POST . . . . . . . . . . . . . . . . .
68
130
10.1.16 Bit length of identifiers, unguessability . . . . . . . . . . . .
69
131
10.1.17 True randomness vs. pseudorandom source . . . . . . . . . .
69
132
10.1.18 Session Archival Directory . . . . . . . . . . . . . . . . . . .
69
133
10.1.19 Session cookies. . . . . . . . . . . . . . . . . . . . . . . . .
70
134
10.1.20 Local user account management. . . . . . . . . . . . . . . . .
70
135
10.1.21 Mini IdP . . . . . . . . . . . . . . . . . . . . . . . . . . . .
70
136
10.1.22 IdP Insitence on Signed AuthnReq . . . . . . . . . . . . . . .
70
137
10.1.23 Logging Options . . . . . . . . . . . . . . . . . . . . . . . .
70
138
10.1.24 Choice of log given Error or Action . . . . . . . . . . . . . .
72
139
10.1.25 Log level for activity log. . . . . . . . . . . . . . . . . . . . .
72
140
10.1.26 Assertion validation options. . . . . . . . . . . . . . . . . . .
73
January 29, 2011
ZXID Book 34, p. 5
CONTENTS
CONTENTS
141
10.1.27 Time Slop . . . . . . . . . . . . . . . . . . . . . . . . . . . .
73
142
10.1.28 Redirect to Content . . . . . . . . . . . . . . . . . . . . . . .
73
143
10.1.29 ID-WSF SOAP Call parameters */ . . . . . . . . . . . . . . .
73
144
10.1.30 Session Management Trigger Suffix . . . . . . . . . . . . . .
74
145
10.1.31 Attribute Prefix . . . . . . . . . . . . . . . . . . . . . . . . .
74
146
10.1.32 Anonymous can see protected content . . . . . . . . . . . . .
74
147
10.1.33 Required Authentication Context Class Ref. . . . . . . . . . .
74
148
10.1.34 IdP: Authentication Context Class Ref for Passwords . . . . .
74
149
10.1.35 IdP preference for ACS . . . . . . . . . . . . . . . . . . . . .
75
150
10.1.36 Simple API HTML customization. . . . . . . . . . . . . . . .
75
151
10.1.37 Body tag for the ZXID generated pages. . . . . . . . . . . . .
75
152
10.1.38 IdP Selector Page URL . . . . . . . . . . . . . . . . . . . . .
76
153
10.1.39 Authentication Page URL . . . . . . . . . . . . . . . . . . .
76
154
11 Circle-of-Trust: Create a Federation with Other Partners
77
155
12 Certificates and PKI Trust
79
156
13 ZXID Logging and Audit Trail
81
157
13.1 Filesystem Layout for Logs . . . . . . . . . . . . . . . . . . . . . . .
81
158
13.2 ZXID Log Format . . . . . . . . . . . . . . . . . . . . . . . . . . . .
82
159
13.3 Log Signing and Encryption . . . . . . . . . . . . . . . . . . . . . .
86
160
13.4 Internal Crypto Formats . . . . . . . . . . . . . . . . . . . . . . . . .
88
161
13.5 Logging Assertions . . . . . . . . . . . . . . . . . . . . . . . . . . .
89
162
13.6 Logging Requests and Responses . . . . . . . . . . . . . . . . . . . .
89
163
13.7 Session Storage and Bootstraps . . . . . . . . . . . . . . . . . . . . .
90
164
13.7.1 Session directory . . . . . . . . . . . . . . . . . . . . . . . .
91
165
13.7.2 User directory (user/) . . . . . . . . . . . . . . . . . . . . .
92
166
13.7.3 Local UID Directory (uid/) . . . . . . . . . . . . . . . . . .
92
167
13.7.4 IdP Use of Local UID Directory (uid/) . . . . . . . . . . . .
93
168
14 mod_auth_saml: Apache SSO without Programming
95
169
14.1 Compiling from Source . . . . . . . . . . . . . . . . . . . . . . . . .
96
170
14.2 Configuration and Testing . . . . . . . . . . . . . . . . . . . . . . . .
97
171
14.2.1 httpd.conf . . . . . . . . . . . . . . . . . . . . . . . . . .
97
172
14.2.2 Trying it out . . . . . . . . . . . . . . . . . . . . . . . . . .
98
January 29, 2011
ZXID Book 34, p. 6
CONTENTS
CONTENTS
173
14.2.3 Setting up Circle of Trust . . . . . . . . . . . . . . . . . . . .
98
174
14.3 Real World Example . . . . . . . . . . . . . . . . . . . . . . . . . .
98
175
14.4 Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
176
14.5 mod_auth_saml FAQ . . . . . . . . . . . . . . . . . . . . . . . . . . 101
177
14.6 Important TODO items for mod_auth_saml . . . . . . . . . . . . . . 102
178
14.7 mod_authz_xacml . . . . . . . . . . . . . . . . . . . . . . . . . . . .
179
180
15 Simple API: Easy way to SSO
102
103
15.1 Hello World SSO . . . . . . . . . . . . . . . . . . . . . . . . . . . .
103
181
15.1.1 Attributes Returned in the SSO . . . . . . . . . . . . . . . . . 104
182
15.1.2 Configuration Options . . . . . . . . . . . . . . . . . . . . . 106
183
15.1.3 AUTO options (auto flags) . . . . . . . . . . . . . . . . . . . 106
184
15.1.4 Configuration options for customizing HTML . . . . . . . . . 108
185
15.2 Gaining More Control . . . . . . . . . . . . . . . . . . . . . . . . . .
109
186
15.3 Some Generalization and Optimizations . . . . . . . . . . . . . . . .
110
187
15.4 Java Servlet Example Using Tomcat . . . . . . . . . . . . . . . . . .
112
188
15.5 Samma på Perl . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
113
189
15.6 Shell Script API . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
115
190
16 ZXID Simple Form Fields
117
191
16.1 Common Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
117
192
16.2 IdP Selection (Login) Screen . . . . . . . . . . . . . . . . . . . . . .
117
193
16.3 Single Logout and Federation Management . . . . . . . . . . . . . .
119
194
16.4 Login Button Abreviations . . . . . . . . . . . . . . . . . . . . . . .
120
195
16.5 ZXID IdP Login Screen Form Fields . . . . . . . . . . . . . . . . . .
120
196
17 ZXID Simple API Reference
121
197
17.1 Creating Configuration Object . . . . . . . . . . . . . . . . . . . . .
121
198
17.2 zxid_simple() main protocol dispatch . . . . . . . . . . . . . . . . . .
121
199
17.3 Generating Login Screen . . . . . . . . . . . . . . . . . . . . . . . .
121
200
17.4 Generating HTML for Logout button or Management Screens . . . .
122
201
17.5 Explicitly Calling PEP (which makes SOAP/XACML call to PDP) . . . .
122
202
17.5.1 zxid_az(conf, qs, sesid) . . . . . . . . . . . . . . . . . . . . .
123
203
17.5.2 zxid_pep_az_soap() - Underlying PEP Function . . . . . . . .
124
204
18 Miscellaneous Function Documentation
January 29, 2011
125
ZXID Book 34, p. 7
CONTENTS
205
206
CONTENTS
19 Raw API: Full Control, You Decide
127
19.1 C Data Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . .
127
207
19.1.1 Handling XML Namespaces . . . . . . . . . . . . . . . . . . 129
208
19.1.2 Handling any and anyAttribute . . . . . . . . . . . . . . . . . 131
209
19.1.3 Root data structure . . . . . . . . . . . . . . . . . . . . . . . 132
210
19.1.4 Per element data structures . . . . . . . . . . . . . . . . . . . 132
211
19.1.5 Memory Allocation . . . . . . . . . . . . . . . . . . . . . . . 132
212
19.2 Decoder as Recursive Descent Parser . . . . . . . . . . . . . . . . . .
133
213
19.2.1 Element Decoders . . . . . . . . . . . . . . . . . . . . . . . 134
214
19.2.2 Decoder Extension Points . . . . . . . . . . . . . . . . . . . 134
215
19.3 Exclusive Canonical Encoder (Serializer) . . . . . . . . . . . . . . .
135
216
19.3.1 Length computation . . . . . . . . . . . . . . . . . . . . . . 136
217
19.3.2 Encoding in schema order . . . . . . . . . . . . . . . . . . . 136
218
19.3.3 Encoding in wire order . . . . . . . . . . . . . . . . . . . . . 137
219
19.4 Signatures (XMLDSIG) . . . . . . . . . . . . . . . . . . . . . . . . .
137
220
19.4.1 Signature Generation . . . . . . . . . . . . . . . . . . . . . . 137
221
19.4.2 Signature Validation . . . . . . . . . . . . . . . . . . . . . . 138
222
19.4.3 Certificate Validation and Trust Model . . . . . . . . . . . . . 139
223
19.5 Data Accessor Functions . . . . . . . . . . . . . . . . . . . . . . . .
139
224
19.6 Memory Allocation and Free . . . . . . . . . . . . . . . . . . . . . .
140
225
19.7 Walking the data structure . . . . . . . . . . . . . . . . . . . . . . .
140
226
19.8 Thread Safety . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
140
227
20 Creating New Interfaces Using ZXID Methodology
141
228
21 Code Generation Tools
143
229
230
21.1 Special Support for Specific Programming Languages . . . . . . . . .
22 Identity Web Services
144
145
231
22.1 EPR Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
145
232
22.2 High level WSC API . . . . . . . . . . . . . . . . . . . . . . . . . .
146
233
22.2.1 zxid_callf() - Make SOAP call with specified body . . . . . .
146
234
22.2.2 ZXID_CHK_STATUS() - Macro for checking OK status . . . .
147
235
22.3 Low Level WSC API . . . . . . . . . . . . . . . . . . . . . . . . . .
148
236
22.3.1 zxid_get_epr() - Obtain EPR fron cache or by discovery . . .
148
January 29, 2011
ZXID Book 34, p. 8
CONTENTS
CONTENTS
237
22.4 ID-DAP Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
238
22.4.1 Short example of using low level API . . . . . . . . . . . . . 149
239
22.4.2 Fully winded example of using low level API . . . . . . . . . 150
240
22.4.3 zxid_mk_dap_query() . . . . . . . . . . . . . . . . . . . . . .
151
241
22.4.4 zxid_mk_dap_query_item() . . . . . . . . . . . . . . . . . . .
151
242
22.4.5 zxid_mk_dap_select() . . . . . . . . . . . . . . . . . . . . . .
153
243
22.4.6 zxid_mk_dap_test_item() . . . . . . . . . . . . . . . . . . . .
153
244
22.4.7 zxid_mk_dap_testop() . . . . . . . . . . . . . . . . . . . . .
154
245
22.4.8 zxid_mk_dap_subscription() . . . . . . . . . . . . . . . . . .
154
246
22.4.9 zxid_mk_dap_resquery() . . . . . . . . . . . . . . . . . . . .
155
247
22.5 ID Messaging Interface . . . . . . . . . . . . . . . . . . . . . . . . .
155
248
22.6 ID Geo Location Interface . . . . . . . . . . . . . . . . . . . . . . .
155
249
22.7 Contact Book Interface . . . . . . . . . . . . . . . . . . . . . . . . .
155
250
22.8 People Service Interface . . . . . . . . . . . . . . . . . . . . . . . .
155
251
22.9 Interface to Conor’s Demo Media Service . . . . . . . . . . . . . . .
155
252
22.10ID-SIS Data Service for HR-XML . . . . . . . . . . . . . . . . . . .
155
253
23 Function Reference (generated from source)
157
254
24 Structures
159
255
25 Important Functions
161
256
26 Functions Alphabetical
163
257
26.0.1 Configuring SSO Servlet to Tomcat . . . . . . . . . . . . . . 164
258
26.1 Running as servlet under Tomcat . . . . . . . . . . . . . . . . . . . .
165
259
26.2 Using ZXID with AXIS2 . . . . . . . . . . . . . . . . . . . . . . . .
165
260
26.3 Programming with ZXID Java API . . . . . . . . . . . . . . . . . . .
166
261
26.3.1 Integrating SSO Directly to Your Java Servlet . . . . . . . . . 166
262
26.4 Known Problems and Limitations . . . . . . . . . . . . . . . . . . .
168
263
26.5 Troubleshooting class loader . . . . . . . . . . . . . . . . . . . . . .
168
264
26.5.1 Symlinks . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
265
26.5.2 Class Path . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
266
26.5.3 LD_LIBRARY_PATH . . . . . . . . . . . . . . . . . . . . . 169
267
26.5.4 Native Library Already Loaded . . . . . . . . . . . . . . . . 170
268
26.5.5 Win32 Java loanLibrary() error . . . . . . . . . . . . . . . .
171
269
26.6 Logging and Debugging Tips . . . . . . . . . . . . . . . . . . . . . .
171
270
26.7 Debugging libzxidjni.so under jdb and gdb . . . . . . . . . . . .
171
January 29, 2011
ZXID Book 34, p. 9
CONTENTS
271
CONTENTS
27 Net::SAML - ZXID Perl Bindings
173
272
27.1 Example Program (see also zxidhlo.pl) . . . . . . . . . . . . . . .
173
273
27.2 Current major modules are . . . . . . . . . . . . . . . . . . . . . . .
176
274
27.3 Planned modules . . . . . . . . . . . . . . . . . . . . . . . . . . . .
176
275
27.4 Perl API Adaptations . . . . . . . . . . . . . . . . . . . . . . . . . .
176
276
27.5 Testing Net::SAML and zxid.pl as CGI script . . . . . . . . . . . .
177
277
27.6 Testing Net::SAML and zxid.pl under mod_perl . . . . . . . . . . .
177
278
27.7 Debugging Net::SAML with GDB . . . . . . . . . . . . . . . . . . .
177
279
28 php_zxid
179
280
28.1 Installing Binaries or from Package . . . . . . . . . . . . . . . . . .
179
281
28.2 Building and Installing ZXID PHP extension . . . . . . . . . . . . .
179
282
28.2.1 Running PHP as Apache mod_php . . . . . . . . . . . . . . . 179
283
28.2.2 Running PHP as CGI (any web server) . . . . . . . . . . . . 180
284
28.3 Programming with ZXID PHP Extension . . . . . . . . . . . . . . .
181
285
28.4 Simple API Using PHP . . . . . . . . . . . . . . . . . . . . . . . . .
181
286
29 Integration of Other Libraries with ZXID PHP
183
287
29.1 Pat Patterson’s php module . . . . . . . . . . . . . . . . . . . . . . .
183
288
29.2 Sun OpenSSO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
183
289
290
30 FAQ
185
30.1 Build and Linking Problems . . . . . . . . . . . . . . . . . . . . . .
185
291
30.1.1 Dry run test . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
292
30.1.2 Duplicate symbols . . . . . . . . . . . . . . . . . . . . . . . 185
293
31 Apache Compilation Tips
187
294
31.1 apache httpd-2.2.3 . . . . . . . . . . . . . . . . . . . . . . . . . . . .
187
295
31.2 perl-5.8.8 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
188
296
31.3 mod_perl-2.0.4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
189
297
31.4 php-5.1.6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
189
298
32 Configuring Apache
191
299
33 Trying Out Apache
197
300
34 Debugging Apache Cores
199
January 29, 2011
ZXID Book 34, p. 10
CONTENTS
301
CONTENTS
35 Mediawiki Integration Tips
201
302
35.1 Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
303
35.2 Building MediaWiki . . . . . . . . . . . . . . . . . . . . . . . . . .
304
35.3 Trying It Out . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
305
36 ZXID Testing Plan
202
203
306
36.1 SSO Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
307
36.2 Test targets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
203
308
36.2.1 CGI Based Hello World Tests . . . . . . . . . . . . . . . . . 203
309
36.2.2 CGI Based Full API Tests . . . . . . . . . . . . . . . . . . . 203
310
36.2.3 mod_php tests . . . . . . . . . . . . . . . . . . . . . . . . . 204
311
36.2.4 mod_perl tests . . . . . . . . . . . . . . . . . . . . . . . . . 204
312
36.2.5 Tomcat Integration Tests . . . . . . . . . . . . . . . . . . . . 204
313
36.2.6 mod_auth_saml tests . . . . . . . . . . . . . . . . . . . . . . 204
314
315
36.3 Signature tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
37 FAQ
204
205
316
37.1 Compilation Problems . . . . . . . . . . . . . . . . . . . . . . . . .
205
317
37.1.1 OpenSSL not found: you need to create localconf.mk . . .
206
318
37.1.2 Missing gperf . . . . . . . . . . . . . . . . . . . . . . . . . . 207
319
37.1.3 make samlmod gives "incompatible types in assignment" . . . 207
320
37.1.4 Perl compiled with different compiler than zxid . . . . . . . . 208
321
37.1.5 All files under zx missing . . . . . . . . . . . . . . . . . . . 208
322
37.1.6 Compiler Warnings . . . . . . . . . . . . . . . . . . . . . . . 209
323
37.1.7 SWIG and Java Problems . . . . . . . . . . . . . . . . . . . 209
324
37.2 Platform Specifics . . . . . . . . . . . . . . . . . . . . . . . . . . . .
211
325
37.2.1 Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
326
37.2.2 FreeBSD . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
327
37.2.3 Solaris (Sparc) . . . . . . . . . . . . . . . . . . . . . . . . . 211
328
37.2.4 MacOS X (PowerPC?) . . . . . . . . . . . . . . . . . . . . . 211
329
37.2.5 Windows Using MinGW . . . . . . . . . . . . . . . . . . . . 211
330
37.2.6 Windows Using Cygwin . . . . . . . . . . . . . . . . . . . . 212
331
37.2.7 Windows Using MSVC . . . . . . . . . . . . . . . . . . . . . 212
332
333
37.3 Configuration Questions . . . . . . . . . . . . . . . . . . . . . . . .
212
37.3.1 No certificates appear in metadata . . . . . . . . . . . . . . . 214
January 29, 2011
ZXID Book 34, p. 11
CONTENTS
CONTENTS
334
37.3.2 Skipping IdP Selection: Hardwiring the IdP . . . . . . . . . . 214
335
37.3.3 Web Service Provider Metadata . . . . . . . . . . . . . . . . 215
336
37.4 API Questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
216
337
37.5 Common Mistakes . . . . . . . . . . . . . . . . . . . . . . . . . . .
216
338
37.5.1 Doubts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
339
37.6 Consent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
219
340
37.7 Deployment Planning . . . . . . . . . . . . . . . . . . . . . . . . . .
220
341
37.8 Use of Signing and Crypto, Security Concerns . . . . . . . . . . . . .
221
345
37.8.1 How is mod_auth_saml better than HTTP Basic Auth that it
claims to emulate? HTTP Basic Auth does not address transport encryption. Is mod_auth_saml HTTP Basic Auth emulation vulnearable due to this? . . . . . . . . . . . . . . . . . .
221
346
37.8.2 Receipe for debugging signature validation problems . . . . . 222
347
37.8.3 Signature validation problems in body . . . . . . . . . . . . . 223
348
37.8.4 VFY FAIL CANON SIGINFO . . . . . . . . . . . . . . . . . 223
342
343
344
349
37.9 Audit Trail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
223
350
37.10Vendor products . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
224
351
37.10.1 Symlabs Federated Identity Suite (SFIS) . . . . . . . . . . . . 224
352
37.10.2 Shibboleth and OpenSAML . . . . . . . . . . . . . . . . . . 225
353
37.10.3 Lasso and Authentic . . . . . . . . . . . . . . . . . . . . . . 225
354
37.10.4 OpenSSO . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
355
37.10.5 simpleSAMLphp . . . . . . . . . . . . . . . . . . . . . . . . 225
356
37.10.6 Ping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
357
37.10.7 SiteMinder . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
358
37.10.8 Bouncing Castle vs. OpenSSL Padding Problem . . . . . . . 226
359
37.11Known Bugs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
227
360
37.12Mysterious Error Messages . . . . . . . . . . . . . . . . . . . . . . .
227
361
37.12.1 snprintf() multibyte character related errors in log . . . . . . .
228
362
37.12.2 My own messages are redirected back to me . . . . . . . . . . 228
363
37.13Certificates and Private Keys . . . . . . . . . . . . . . . . . . . . . .
228
364
37.13.1 Password is being asked for private key . . . . . . . . . . . . 228
365
37.13.2 Quick command for looking at certificate . . . . . . . . . . . 229
366
37.13.3 Self signed certificate . . . . . . . . . . . . . . . . . . . . . . 229
367
37.13.4 Installing CA Certificates . . . . . . . . . . . . . . . . . . . . 230
368
37.14Author’s Pet Peeves . . . . . . . . . . . . . . . . . . . . . . . . . . .
January 29, 2011
231
ZXID Book 34, p. 12
CONTENTS
CONTENTS
369
37.14.1 What does ZXID aim at - an answer . . . . . . . . . . . . . .
232
370
37.14.2 Annoyances and improvement ideas . . . . . . . . . . . . . . 233
371
37.14.3 Non-obvious SAML . . . . . . . . . . . . . . . . . . . . . . 234
372
37.14.4 Non-obvious ID-WSF . . . . . . . . . . . . . . . . . . . . . 235
374
37.14.5 Non-obvious XML Exclusive Canonicalization (XML-EXCC14N) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
375
37.14.6 I do not want to know service type, but I want to call the service 236
373
376
37.15Best Practises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
240
377
37.16Cardspace / Infocard / DigitalMe Tutorial . . . . . . . . . . . . . . .
240
378
37.16.1 Installing DigitalMe and Firefox plugin . . . . . . . . . . . . 241
379
37.16.2 Setting up IdP account . . . . . . . . . . . . . . . . . . . . . 241
380
37.16.3 Yubikey Support . . . . . . . . . . . . . . . . . . . . . . . . 241
381
37.16.4 Legal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
382
37.17Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
241
383
37.18SOAP Binding . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
242
384
385
37.18.1 Axis2 wants wsa:Action header . . . . . . . . . . . . . . . . 242
38 Support
245
386
38.1 Mailing list and forums . . . . . . . . . . . . . . . . . . . . . . . . .
245
387
38.2 Bugs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
245
388
38.3 Developer access . . . . . . . . . . . . . . . . . . . . . . . . . . . .
245
389
38.4 Commercial Support . . . . . . . . . . . . . . . . . . . . . . . . . .
245
390
39 License
247
391
39.1 Dependency Library Licenses . . . . . . . . . . . . . . . . . . . . .
247
392
39.2 Specification IPR . . . . . . . . . . . . . . . . . . . . . . . . . . . .
248
393
39.3 Further Warranties . . . . . . . . . . . . . . . . . . . . . . . . . . .
248
394
40 Protocol Schema and Examples
249
395
41 Appendix: Schema Grammars
251
396
41.1 SAML 2.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
251
397
41.1.1 saml-schema-assertion-2.0 (sa) . . . . . . . . . . . . . . . . . 251
398
41.1.2 saml-schema-protocol-2.0 (sp) . . . . . . . . . . . . . . . . . 256
399
41.1.3 saml-schema-metadata-2.0 (md) . . . . . . . . . . . . . . . . 260
400
41.2 SAML 1.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
January 29, 2011
264
ZXID Book 34, p. 13
CONTENTS
CONTENTS
401
41.2.1 oasis-sstc-saml-schema-assertion-1.1 (sa11) . . . . . . . . . . 264
402
41.2.2 oasis-sstc-saml-schema-protocol-1.1 (sp11) . . . . . . . . . . 268
403
41.3 Liberty ID-FF 1.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . .
270
404
41.3.1 liberty-idff-protocols-schema-1.2 (ff12) . . . . . . . . . . . . 270
405
41.3.2 liberty-metadata-v2.0 (m20) . . . . . . . . . . . . . . . . . . 274
406
41.3.3 liberty-authentication-context-v2.0 (ac) . . . . . . . . . . . . 276
407
41.4 Liberty ID-WSF 1.1 . . . . . . . . . . . . . . . . . . . . . . . . . . .
281
408
41.4.1 liberty-idwsf-soap-binding-v1.2 (b12) . . . . . . . . . . . . . 281
409
41.4.2 liberty-idwsf-security-mechanisms-v1.2 (sec12) . . . . . . . . 283
410
41.4.3 liberty-idwsf-disco-svc-v1.2 (di12) . . . . . . . . . . . . . . 284
411
41.4.4 liberty-idwsf-interaction-svc-v1.1 (is12) . . . . . . . . . . . . 286
412
41.5 Liberty ID-WSF 2.0 . . . . . . . . . . . . . . . . . . . . . . . . . . .
289
413
41.5.1 liberty-idwsf-utility-v2.0 (lu) . . . . . . . . . . . . . . . . . . 289
414
41.5.2 liberty-idwsf-soap-binding (no version, sbf) . . . . . . . . . . 290
415
41.5.3 liberty-idwsf-soap-binding-v2.0 (b) . . . . . . . . . . . . . . 290
416
41.5.4 liberty-idwsf-security-mechanisms-v2.0 (sec) . . . . . . . . . 292
417
41.5.5 liberty-idwsf-disco-svc-v2.0 (di) . . . . . . . . . . . . . . . . 293
418
41.5.6 liberty-idwsf-interaction-svc-v2.0 (is) . . . . . . . . . . . . . 297
419
41.5.7 id-dap (dap) . . . . . . . . . . . . . . . . . . . . . . . . . . . 298
420
41.5.8 liberty-idwsf-subs-v1.0 (subs) . . . . . . . . . . . . . . . . . 301
421
41.5.9 liberty-idwsf-dst-v2.1 (dst) . . . . . . . . . . . . . . . . . . . 302
422
41.5.10 liberty-idwsf-idmapping-svc-v2.0 (im) . . . . . . . . . . . . . 305
423
41.5.11 liberty-idwsf-people-service-v1.0 (ps) . . . . . . . . . . . . . 306
424
41.5.12 liberty-idwsf-authn-svc-v2.0 (as) . . . . . . . . . . . . . . . . 310
425
426
427
41.6 SOAP 1.1 Processors . . . . . . . . . . . . . . . . . . . . . . . . . .
311
41.6.1 wsf-soap11 (e) . . . . . . . . . . . . . . . . . . . . . . . . . 311
41.7 XML and Web Services Infrastructure . . . . . . . . . . . . . . . . .
318
428
41.7.1 xmldsig-core (ds) . . . . . . . . . . . . . . . . . . . . . . . . 318
429
41.7.2 xenc-schema (xenc) . . . . . . . . . . . . . . . . . . . . . . . 321
430
41.7.3 ws-addr-1.0 (a) . . . . . . . . . . . . . . . . . . . . . . . . . 323
431
41.7.4 wss-secext-1.0 (wsse) . . . . . . . . . . . . . . . . . . . . . 325
432
41.7.5 wss-util-1.0 (wsu) . . . . . . . . . . . . . . . . . . . . . . . 328
January 29, 2011
ZXID Book 34, p. 14
CONTENTS
433
CONTENTS
42 Appendix: Some Example XML Blobs
329
435
42.1 SAML 2.0 Artifact Response with SAML 2.0 SSO Assertion and Two
Bootstraps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
436
42.2 ID-WSF 2.0 Call with X509v3 Sec Mech . . . . . . . . . . . . . . . 333
437
42.3 ID-WSF 2.0 Call with Bearer (Binary) Sec Mech . . . . . . . . . . . 334
438
42.4 ID-WSF 2.0 Call with Bearer (SAML) Sec Mech . . . . . . . . . . . 335
439
42.5 XACML 2.0 SAML Profile SOAP Call . . . . . . . . . . . . . . . . 336
434
January 29, 2011
329
ZXID Book 34, p. 15
CONTENTS
January 29, 2011
CONTENTS
ZXID Book 34, p. 16
440
441
442
443
444
Chapter 1
Introduction
1.1
ZXID Documentation Set
The present book is mainly amalgamation of the following documents, which you may
want to consult separately.
445
• mod_auth_saml Apache module documentation: SSO without programming.
446
• zxid_simple() Easy API for SAML
448
• ZXID Raw API: Program like the pros (and fix your own problems). See also
Function Reference
449
• ZXID ID-WSF API: Make Identity Web Services Calls using ID-WSF
447
451
• ZXID Compilation and Installation: Compile and install from source or package.
See also INSTALL.zxid for quick overview.
452
• ZXID Configuration Reference: Nitty gritty on all options.
450
454
• ZXID Circle of Trust Reference: How to set up the Circle of Trust, i.e. the
partners your web site works with.
455
• ZXID Logging Reference: ZXID digitally signed logging facility
456
• javazxid: Using ZXID from Java
457
• Net::SAML: Using ZXID from Perl
458
• php_zxid: Using ZXID from PHP
459
• zxididp: Using ZXID IdP and Discovery
460
• README.smime: Crypto and Cert Tutorial
461
• FAQ: Frequently Asked Questions
462
• README.zxid: ZXID project overview
453
17
1.1. ZXID DOCUMENTATION SET
January 29, 2011
CHAPTER 1. INTRODUCTION
ZXID Book 34, p. 18
463
464
Chapter 2
Install (package or from source)
467
If you want to try ZXID out immediately, we recommend compiling the library and
examples and installing one of the examples as a CGI script in an existing web server.
See later chapters for more details.
468
Download from zxid.org or get it with anon git: git clone git://zxid.org/zxid
465
466
469
470
471
472
473
474
475
476
477
478
479
tar xvzf zxid-0.76.tgz
cd zxid-0.76
# N.B. There is no configure script. The Makefile works for all
#
supported platforms by provision of correct TARGET option.
# N.B2: We distribute some generated files. If they are missing, you need
#
to regenerate them: make cleaner; make dep ENA_GEN=1
# Standard place is /var/zxid. You can change this with, e.g.
#
make ZXID_PATH=/usr/local/var/zxid
make
# default Linux. Do ‘make TARGET=sol8’ for Solaris
make all
# Also builds the optional language bindings, see below
make dir
# Creates /var/zxid hierarchy (may need to be root)
480
481
482
483
484
485
486
487
make
make
make
make
make
make
make
apachezxid
apachezxid_install
samlmod
samlmod_install
phpzxid
phpzxid_install
javazxid
#
#
#
#
#
#
#
optional
optional: install the mod_auth_saml Apache module
optional
optional: install Net::SAML perl module
optional
optional: install php_zxid.so PHP extension
optional
488
489
490
491
cp zxidhlo <webroot>/
# configure your web server to recognize zxid a CGI, e.g.
mini_httpd -p 8443 -c ’zxid*’ -S -E zxid.pem
492
493
494
# Edit your /etc/hosts to contain
127.0.0.1
localhost sp1.zxidcommon.org sp1.zxidsp.org
495
496
# Point your browser to (zxid_simple() API version)
19
2.1. PREREQUISITES CHAPTER 2. INSTALL (PACKAGE OR FROM SOURCE)
497
498
499
500
https://sp1.zxidsp.org:8443/zxidhlo?o=E
https://sp1.zxidsp.org:8443/zxidhlo.pl?o=E
# Perl version
https://sp1.zxidsp.org:8443/zxidhlo.php?o=E
# PHP version
http://sp1.zxidsp.org:8080/zxidservlet/zxidHLO?o=E # Java version
501
502
503
504
# Find an IdP to test with and configure it...
# see zxididp and zxid-idp.pd for documentation, or use the
# free IdP on the net: https://zxidp.org/index-idp.html
505
506
2.1
507
This software depends on the following packages:
508
1. zlib from zlib.net. Generally whatever comes with your distro is sufficient.
509
510
511
512
513
514
515
516
517
Prerequisites
2. openssl-0.9.8l or openssl-1.0.0c (earlier versions contain a man-in-the-middle security vulnearability) or later. See www.openssl.org. Generally openssl libraries
distributed with most Linux distros are sufficient.1
3. libcurl from http://curl.haxx.se/. I used version 7.15.5, but probably whatever ships with your distribution is fine. libcurl is needed for SOAP bindings and
for fetching metadata. It needs to be compiled to support HTTPS.2
4. HTTPS capable web server. For most trivial testing CGI support is needed. We recommend mini_httpd(8) available from http://www.acme.com/software/mini_httpd/
We also provide Apache HTTP receipe: apache.html
519
5. Perl, PHP, and Java interfaces depend on the respective development tools but should
not need any additional modules or tools.
520
2.1.1
518
Additional Prerequisites for Complete Rebuild from Scratch
523
Following additional packages are needed by developers who wish to build from scratch,
including the code generation (the standard distribution includes the output of the code
generation, so most people do not need these).
524
A. gperf from gnu.org (only for build process when generating code)
521
522
525
526
527
528
B. swig from swig.org (only for build process and only if you want scripting interfaces)
C. perl from cpan.org (only for build process and only if you want to generate code
from .sg)
1 It is possible to compile without OpenSSL, e.g. for space constrained embedded system, but this has
serious security implications.
2 Compilation without libcurl is possible with some loss of functionality.
January 29, 2011
ZXID Book 34, p. 20
CHAPTER
2.2. CANNED
2. INSTALL
TUTORIAL:
(PACKAGE
RUNNING
OR FROM
ZXID
SOURCE)
AS CGI UNDER MINI_HTTPD
529
530
D. plaindoc from http://zxid.org/plaindoc/pd.html (only for build process, for
code generation from .sg, and for documentation)
534
Although technically not needed to build zxid, you will need an IdP to test against. You
can use the free IdP at https://zxidp.org/index-idp.html - it allows anyone to
register a user and any SP to join the Circle of Trust. Or you can compile and configure
the zxididp, see zxid-idp.pd.
535
2.1.2
536
As of January 2011, following platforms are "officially" supported:
531
532
533
Operating System and Platform Support
538
• Linux/Unix (default platform, also should work for other Unixes, e.g. FreeBSD,
with gnu tools)
539
• Solaris 8 (and later) (make TARGET=sol8)
540
• MacOS X (make TARGET=macosx)
541
• Windows 2000 or later using mingw (make TARGET=mingw)
537
542
Many other platforms have been occasionally tested and found to work, such as
543
• Windows using Microsoft compilers (MSVC) (make TARGET=win32cl)
544
• Windows using cygwin (make TARGET=cygwin)
545
• Linux hosted cross compilation targets: xsol8, xmingw
546
547
548
549
As of January 2011 most testing has been on 32bit architectures, with only occasional
64bit experiences. Most testing has been in little endian (ix86) architectures, with only
occasional testing in big endian architectures like PowerPC and Sparc. Never-the-less,
we are committed to support every modern architecture and OS out there.
N.B. We prefer to support every supported architecture via an explicit
Makefile TARGET section. We believe debugging gnu autohell generated
configure scripts is more pain and distraction than it’s worth. If you add
new platform support, please do so directly in the Makefile.
550
551
552
553
554
555
556
557
2.2
Canned Tutorial: Running ZXID as CGI under mini_httpd
While zxid will run easily under Apache httpd (see recipe), for sake of simplicity we
first illustrate running it with mini_httpd(8), a very simple SSL capable web server by
Jef Poskanzer.
January 29, 2011
ZXID Book 34, p. 21
2.2. CANNED TUTORIAL:
CHAPTER
RUNNING
2. INSTALL
ZXID AS(PACKAGE
CGI UNDER
ORMINI_HTTPD
FROM SOURCE)
558
2.2.1
559
You can download the source for mini_httpd from http://www.acme.com/software/mini_httpd/
560
561
562
563
564
Getting and installing mini_httpd
You should already have installed OpenSSL, or quite probably OpenSSL shipped with
your distribution. If it is not located at /usr/local/ssl, the you need to edit the
mini_httpd Makefile to indicate where it is. At any rate you need to uncomment all
lines that start by SSL_ in the Makefile. Then say
make
565
Now copy the mini_httpd binary somewhere in your path.
566
2.2.2
567
After building zxid, cd to zxid directory and run
568
569
570
571
572
573
574
575
mini_httpd -p 8443 -c ’zxid*’ -S -E zxid.pem
where
-p 8443
-c ’zxid*’
-S
-E zxid.pem
578
579
580
581
584
585
586
587
the port to listen to
that URL paths with "zxid" are CGI scripts
that https is to be used
the SSL certificate to use
N.B. The zxid.pem certificate and private key combo is shipped with zxid
for demonstration purposes. Obviously everybody who downloads zxid
has that private key, so there is no real security what-so-ever. For production use, you must generate, or acquire, your own private key-certificate
pair (and keep the private key secret). See Certificates chapter for further
info.
577
583
specifies
specifies
specifies
specifies
See Apache recipe for alternative that avoids mini_httpd, but is more complicated otherwise.
576
582
Running mini_httpd
2.2.3
Accessing ZXID
Edit your /etc/hosts file so that the definition of localhost also includes sp1.zxidcommon.org
and sp1.zxidsp.org domain names, e.g:
127.0.0.1
localhost sp1.zxidcommon.org sp1.zxidsp.org
Point your browser to
https://sp1.zxidsp.org:8443/zxidhlo
January 29, 2011
ZXID Book 34, p. 22
CHAPTER
2.2. CANNED
2. INSTALL
TUTORIAL:
(PACKAGE
RUNNING
OR FROM
ZXID
SOURCE)
588
or if you do not want the common domain cookie check
589
590
591
592
593
594
Dynamic linking problems
If accessing the URL (while running mini_httpd) you get no error message and no content - everything just mysteriously fails - you may be hitting a dynamic linking problem.
If mini_httpd(8) fails to launch CGI script it will silently fail. This is unfortunate, but I
guess that is what the "mini" in the name implies.
597
To make matters even worse, mini_httpd(8), probably in the interest of security, will
ignore LD_LIBRARY_PATH variable. Apparently it has its fixed notion of the library
paths that is set at compile time.
598
If you suspect this problem, try following:
599
1. Create shell script called test.sh:
595
596
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
#!/bin/sh
echo Content-Type: text/plain
echo
echo Test $$
echo lib_path is --$LD_LIBRARY_PATH-ldd zxidhlo
./zxidhlo -h 2>&1
echo Exit value --$?-2. Restart mini_httpd(8) like this
chmod a+x test.sh
mini_httpd -p 8443 -c test.sh -S -E zxid.pem -l mini.out
3. Access https://sp1.zxidsp.org:8443/test.sh - you may see something like
Test 1655
lib_path is --/usr/local/lib:/usr/lib-./zxidhlo: error while loading shared libraries: libcurl.so.3: cannot
open shared object file: No such file or directory
Now you at least see why it’s failing (in this case the directory where libcurl was
installed is not in mini_httpd’s notion of LD_LIBRARY_PATH). If the zxidhlo
binary runs fine from comman line, try ‘ldd zxidhlo’ to see where it is finding its
libraries.
Easiest dirty fix is to copy the missing libraries to one of the hardwired directories of
mini_httpd(8) (e.g. /usr/lib). More sophisticated fixes include using ldconfig(8),
recompiling your mini_httpd(8), or statically linking the offending library into zxidhlo
binary.
January 29, 2011
ZXID Book 34, p. 23
CHAPTER
RUNNING
2. INSTALL
ZXID AS(PACKAGE
CGI UNDER
ORMINI_HTTPD
FROM SOURCE)
624
625
626
627
628
629
2.2.4
Setting up an IdP
ZXID now ships with an IdP: zxididp. You may set this up, see documentation in
zxid-idp.pd, or you may want to use a free IdP on the net, such as https://zxidp.org/index-idp.html
For you to test zxidhlo, you will need to acquire an IdP from somewhere - any vendor
whose product is SAML 2.0 certified will do. Possible sources are
• https://zxidp.org/index-idp.html
631
• http://symlabs.com/Products/SFIAM.html who have a free download of
commercial product
632
• Lasso: http://lasso.entrouvert.org/
633
• Their IDP: http://authentic.labs.libre-entreprise.org/
630
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
If you do not want to install an IdP yourself (even for testing), find someone who
already runs one (e.g. https://zxidp.org/index-idp.html) and ask if they would
be willing to load the metadata of your zxid SP. If you do this, you will need to get
externally visible domain names. This canned tutorial uses /etc/hosts (see previous
step) which is only visible on your own machine.
Once you get your IdP up and running, you need to make sure it accepts the zxid SP in
its Circle of Trust (CoT). This is done by placing the metadata of the SP in right place
in the IdP product configuration. If your IdP supports automatic CoT management, just
turn it on and chances are you are done.3
If not, you can obtain the zxid SP metadata (which is slightly different for each install
so you can’t just copy it from existing install) from
https://sp1.zxidsp.org:8443/zxidhlo?o=B
This URL is the well known location method metadata URL. It is also the SP Entity
ID or Provider ID, should the IdP product ask for this in its configuration. If the IdP
product needs you to supply the metadata manually as an xml file, just point your web
browser to the above URL and save to file, or use curl(1) or wget(1).
zxid SP, by default, has automatic fetching of IdP metadata enabled so there is no manual configuration step needed, provided that the IdP supports the well known location
method. All SAML 2.0 certified IdP implementations must support it (but you may
still need to enable it in configuration). See [?] section 4.1 "Publication and Resolution
via Well-Known Location", p.29, for normative description of this method.
However, you will need the Entity ID (Provider ID) of the IdP. This is the URL that the
IdP uses for well known location method of metadata sharing. You may need to dig the
IdP documentation or GUI for a while to find it. If you already have the IdP metadata
as an xml file, open it and look for EntityDescriptor/entityID. If you already have
the file, you can also import it manually by running the following command
./zxcot -a </path/to/idp-meta.xml
But the preferred method still is: just let the automatic method do its job. See also
zxcot(8) documentation, or run zxcot -h
3 On production IdP you should understand the trust implications (i.e. no trust) of flipping automatic CoT
management on.
January 29, 2011
ZXID Book 34, p. 24
CHAPTER
2.2. CANNED
2. INSTALL
TUTORIAL:
(PACKAGE
RUNNING
OR FROM
ZXID
SOURCE)
663
2.2.5
664
1. Start at
https://sp1.zxidsp.org:8443/zxidhlo
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
Your first SSO
or
If you had common domain cookie already in place, and you are already logged in
the IdP, the SSO may happen automatically (go to step 3). The automatic experience
will be typical when you use SSO regularly for more than one web site (i.e. several
SPs).
However, if you get a screen titled "ZXID SP SSO", you need to paste the IdP’s
Entity ID to the supplied field and click "Login". If zxid SP already obtained the
metadata for the IdP, you may also see a button specific for your IdP (and in this
case there is no need to know the Entity ID anymore or paste anything).
2. Next step depends on the IdP product you are using. Usually a login screen will
appear asking for user name and password. Supply these and login. You will need
an account at the IdP.
3. For more slick IdPs, that’s all you need to do and you will land right back at the
zxid SP page titled "ZXID SP Management".
Congratulations, you have made your first SSO!
However, some IdPs will pester you with additional questions and you will have
to jump through their hoops. A typical question is whether you want to accept a
federation. You do.
Sometimes the federation question does not appear automatically and you need to
figure out a way to create a federation in their user interface and how to get them to
send you back to the SP. Sometimes the word used is "account linking" instead of
federation.4
4 Vendor products are constantly improving in this area. From protocol perspective all the additional
gyrations are unnecessary. Be sure to provide feedback to the vendor so that simpler, easier to use, products
will emerge in future.
January 29, 2011
ZXID Book 34, p. 25
CHAPTER
RUNNING
2. INSTALL
ZXID AS(PACKAGE
CGI UNDER
ORMINI_HTTPD
FROM SOURCE)
January 29, 2011
ZXID Book 34, p. 26
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
Chapter 3
Compilation for Experts
make cleaner
make dep ENA_GEN=1
make
make all ENA_GEN=1
3.1
Build Process
The build process of ZXID relies heavily on code generation techniques that are not
for the faint of heart. Some of these techniques, like xsd2sg.pl were innovated for
this project, while others like SWIG and gperf(1) are existing software. Here and there
some additional perl(1) 1 scripts are run to fix a thing or two.
Carefully study the Makefile, and this should all start to make sense (no pun intended).
Please note that there is no configure script and GNU Auto-tools ("GNU Autohell")
are not used. This is because they have been evaluated to be unsuitable to this project
(or to author’s tastes). If the Makefile does not do what you want, you should first
study if you can change necessary variables using localconf.mk, or if that does not
work, then just edit the Makefile itself. You can temporarily customize the variables
in the Makefile by providing new value on command line, e.g.
make CC=cc
# override the default of CC=gcc
Another philosophical tidbit is that, although some source code is in subdirectories,
all the build logic is kept in one top level Makefile, eliminating all the complexity of
hierarchical make. The Makefile supports building outside source tree using vpath
feature of gnu make(1).
1 There used to be a sed(1) dependency as well, but nowdays sed-zxid.pl perl script handles all seddish
stuff.
27
3.2. SPECIAL OR EMBEDDED COMPILE
CHAPTER
(REDUCED
3. COMPILATION
FUNCTIONALITY)
FOR EXPERTS
.sg
xsd2sg.pl
xsd2sg.pl
.gperf
gperf
.i
swig
.h and .c
swig
.pm and glue
perl, gcc, ld
Net::SAML
gcc
gen-consts-from-gperf-output.pl
swig
libzxid
ld
ld
zxid
phpzxid.i
swig
php glue
ld
gcc, ld
php_zxid
Figure 3.1: ZXID Build Process
712
3.2
713
714
715
716
Special or embedded compile (reduced functionality)
libzxid contains thousands of functions and any given application is unlikely to use
them all. Thus the easiest, safest, no loss of functionality, way to reduce the footprint
is to simply enable compiler and linker flags that support dead function elimination.2
On gcc you should investigate compilation with "-ffunction-sections -fdatasections" and linking with "-Wl,–gc-sections".
717
718
722
If you need to squeeze zxid into as minimal space as possible, some functionality tradeoffs are supported. I stress that you should only attempt these trade-offs once you are
familiar with zxid and know what you are doing. The canned install instructions and
tutorial walk thrus stop working if you omit significant functionality.
723
3.2.1
724
Comment out the -DUSE_OPENSSL flag from CFLAGS in Makefile and recompile.
719
720
721
Compilation without OpenSSL
2 Unfortunately the gnu ld does not support dead function elimination. You should file this as a bug to
them. If they tell you to put every one of the 7000-some functions in a separate .c file, consider the scalability
implications of this. Read the comments in pulverize.pl for a full scoop and an approach.
January 29, 2011
ZXID Book 34, p. 28
CHAPTER
3.2. SPECIAL
3. COMPILATION
OR EMBEDDED
FOR EXPERTS
COMPILE (REDUCED FUNCTIONALITY)
725
726
727
728
This will cripple zxid from security perspective because it will no longer be able to
verify or generate digital signatures. Unless your environment does not need trust
and security, or you understand thoroughly how to provide trust and security by other
means, it is a very bad idea to compile without OpenSSL.
N.B. Compiling, or not, zxid with OpenSSL does not affect whether your
web server will use SSL or TLS. Unless you know what you are doing, you
should be using SSL at web server layer. Given that SSL is used at web
server layer, the memory footprint savings you would gain from compiling
zxid without OpenSSL may be negligible if you use dynamic linking.
729
730
731
732
733
734
3.2.2
Compilation without libcurl
735
Comment out the -DUSE_CURL flag from CFLAGS in Makefile and recompile.
737
Disabling libcurl does not have adverse security implications: you only loose some
functionality and depending on your situation you may well be able to live without it.
738
1. Without libcurl, zxid can not act as a SOAP client. This has a few consequences
736
739
740
741
742
743
744
745
746
747
748
749
750
751
a. Artifact profile for SSO is not supported because it needs SOAP to resolve the
artifact. In most cases a perfectly viable alternative is to use POST profile for
SSO.
b. SOAP profiles for Single Logout and NameID management (aka defederation)
are not supported. You can use the redirect profiles and get mostly the same
functionality.
c. ID-WSF Web Services Client (WSC) and Discovery Client (DIC), as well as
XACML client (PEP) functionality is not available.
2. Automatic CoT metadata fetching using well known location method is not supported without libcurl. You can fetch the metadata manually, e.g. using web
browser, and place it in /var/zxid/cot directory.
If you want to manually control your Circle of Trust relationships, you probably
want to do this anyway so loss of automatic functionality may be a non-issue.3
755
3. Web Services Client (WSC) functionality is not supported without libcurl. Effectively this is just another case of "SOAP needed". If you have your own SOAP
implementation, you may, at lesser automation, achieve much of the same functionality by calling the encoder and decoder functions manually.
756
3.2.3
752
753
754
757
758
759
Compiling without zlib (not supported)
zlib is used mainly in redirect profiles. Since zlib is widely available and its foot print
is small, we have made no supported provision to compile without it. If you hack
something together, let us know.
3 If you compile with libcurl, but still want to disable automatic metadata fetching, investigate the
MD_FETCH and related configuration options.
January 29, 2011
ZXID Book 34, p. 29
3.3. CHOOSING WHICH STANDARDS
CHAPTER
TO INCLUDE
3. COMPILATION
(DEFAULT:FOR
ALL)
EXPERTS
760
3.3
761
WARNING: Only regularly tested configuration is to compile all standards in.
762
763
764
765
766
767
768
769
770
771
Choosing Which Standards to Include (default: all)
On space constrained systems you may shed additional weight by only compiling in the
IdM standards you actually use. Of course, if you do not use them, the dead function
elimination should take care of them, but sometimes you can gain additional savings in
space and especially compile time.
Another reason could be, in the land of the free, if some modules are covered by a
software patent, you may want to compile a binary without the contested functionality.4
You can tweak the flags, shown in accompanying table, in the Makefile or by supplying new values in localconf.mk or on commend line. For example
make TARGET=sol8 ENA_SAML2=0
would disable SAML 2.0 (and trigger build for Sparc Solaris 8).
Table 3.1: Conditional inclusion of standards
Makefile flag
ENA_SSO=1
ENA_SAML2=1
ENA_FF12=1
ENA_SAML11=1
ENA_WSF=1
ENA_WSF2=1
ENA_WSF11=1
772
773
774
775
776
777
778
779
780
781
782
783
784
785
3.4
Standard
All SSO
SAML 2.0
ID-FF 1.2
SAML 1.1
All WSF
ID-WSF 2.0
ID-WSF 1.1
Comments
Must be enabled for any of SSO to work
Requires ENA_SAML11=1
Must be enabled for any of WSF to work
localconf.mk
You can use localconf.mk to remember your own make(1) options, such as TARGET
and different ENA flags, without editing the distributed Makefile.
One useful option to put in localconf.mk is ENA_GEN which will turn on the dependencies that will trigger generation of the files in zxid/c directory. For example
echo ’ENA_GEN=1’ >>localconf.mk
make
WARNING: If you are confused about compilation flags appearing "out
of nowhere", despite not being mentioned in the Makefile, be sure you
have not inadvertently created a localconf.mk (perhaps you rsynced the
sources from another machine and forgot to remove localconf.mk). A
similar problem can occur if you accidentally copied deps.dep from another machine. It will reference the dependencies with the paths of that
machine. Just remove the deps.dep to solve that issue.
4 Please do not ask me to add additional baggage to avoid patents. Software patents are a plague and your
efforts are best spent in getting them overturned or changing laws so they go away.
January 29, 2011
ZXID Book 34, p. 30
CHAPTER 3. COMPILATION FOR EXPERTS
3.5. KNOWN COMPILATION WARNINGS
786
3.5
Known Compilation Warnings
787
This list was reated around August 2010. Things are likely to have changed since then.
788
1. __FUNCTION__ definition incompatible with char*. Ignore.
789
2. const char *file incompatible with &((const char)file
zxsig.c:314: warning: passing arg 1 of ‘ERR_get_error_line_data’ from incompatible pointer
zxsig.c:314: warning: passing arg 3 of ‘ERR_get_error_line_data’ from incompatible pointer
790
791
792
This probably is due to const being, or not, defined differently.
793
Ignore.
794
3. Warning about sentinel: Ignore.
795
3.6
Tough Compilation Errors
799
ZXID was mostly developed on gcc 3.4.6 and explicitly has not been tested on 4.x
series of gcc (due to deprecation of commonly useful features in that gcc series). If
you hit compile time problems with 4.x gcc, try with 3.4.x series gcc first, before
reporting bugs.
800
*** elaborate more - until then, mail the author
801
3.7
796
797
798
802
803
804
805
806
807
808
809
810
811
812
813
814
Tough Linking Errors
• There are some, yet unspecified, compilation or linking errors that manifest on
64 bit or mixed 32 and 64 bit Linux platforms. Current suggested workaround is
to compile 32 bit only.
• Linking error that has been reported a lot on the Google for other software packages:
/usr/lib/libc_nonshared.a(elf-init.oS): In function ‘__libc_csu_init’:
(.text+0x2a): undefined reference to ‘__init_array_start’
/usr/bin/ld: zxidjava/libzxidjni.so: hidden symbol ‘__fini_array_end’ isn’t defined
/usr/bin/ld: final link failed: Nonrepresentable section on output
This seems to be either glibc version related or linker configuration related (or
compiler version?). See
http://www-gatago.com/gnu/gcc/help/43379636.html
http://lists.debian.org/debian-68k/2006/07/msg00017.html
January 29, 2011
ZXID Book 34, p. 31
3.8. OVERVIEW OF THE XSD2SG.PL
CHAPTER
TOOL 3.
(GURU
COMPILATION
LEVEL) FOR EXPERTS
818
The verdict seems to be that somewhere in glibc-2.3 development it was broken
by design and nobody cared to provide any viable fix short of upgrading your
binutils. Seems to be Ulrich Drepper at it again, turning symbols hidden in teeny
version number upgrade.
819
A symptom of this is if this command gives the follwing output
815
816
817
ld --verbose | egrep ’__init_array_(start|end)’
PROVIDE_HIDDEN (__init_array_start = .);
PROVIDE_HIDDEN (__init_array_end = .);
820
821
822
You can manually attempt to link with
823
gcc -nostdlib -o zxidjava/libzxidjni.so -shared --export-all-symbols -Wl,-whole
824
The trick is to supply the -nostdlib flag.
825
ZXID project considers this to be glibc or binutils bug and will not investigate
further. Either use the workaround link line or upgrade binutils, glibc, or both
and complain to glibc authors or binutils authors.
826
827
828
829
830
831
832
3.8
Overview of the xsd2sg.pl Tool (guru level)
The xsd2sg.pl tool, distributed as part of Plaindoc (http://zxid.org/plaindoc/pd.html)
system, is at the heart of the ZXID code generation. Unfortunately the tool is still in
flux. What follows is general outline valid as of March 2007.
840
xsd2sg.pl can be invoked in three ways (see xsd2sg.pl –help), but the invocation
of interest to us is the -S (SG to XSD with Code generation mode). This mode takes
as inputs all .sg files and names of decoding root elelment. It will generate one mega
parser that is capable of decoding any root element (and since root elements contain
other elements, then really all elements). The decoder works by recursive descent
parser principle so there will be smaller decoder functions to call. Similarily the encoder is generated by creating many unit encoders for different elements. Then the
parent elements will call the child element encoders.
841
3.8.1
833
834
835
836
837
838
839
842
843
844
845
846
847
848
849
850
Process .sg to create %dt hash (throw away XSD output)
xsd2sg.pl first processes the .sg files to XSD. As a side effect it populates %dt multidimentsional hash
$dt{’element’}{elemname}[array-of-sublemens-and-attrs]
$dt{’attribute’}{attrname} = "";
$dt{’complexType’}{typename}[array-of-sublemens-and-attrs]
$dt{’group’}{groupname}[array-of-sublemens-and-attrs]
$dt{’attributeGroup’}{agname}[array-of-attrs]
Where the array-of-subelems-and-attrs can contain tag or reference to fundamental or
derived type, e.g.
January 29, 2011
ZXID Book 34, p. 32
CHAPTER 3. COMPILATION
3.8. OVERVIEW
FOR EXPERTS
OF THE XSD2SG.PL TOOL (GURU LEVEL)
851
852
853
854
855
856
857
858
859
"tag$sa:Assertion$min$max"
"ref$xs:anyURI$"
"ref$sa:Assertion$"
"base$$0$1$base-type"
"enum$n1$n2$n3$n4$n5"
"any$$min$max$pc$ns"
"anyAttribute$$min$1"
"_d$$0$1$simplecontent"
3.8.2
The expanding element definitions in %dt
863
Since the concrete goal is to generate data structures for elements irrespective of how
types were used to describe the data, we need to expand any type reference into element
definition where it appears. This is done by expand_element() which will in its turn call
expand_complex_type(), expand_group() and expand_attribute_group() to do the job.
864
3.8.3
860
861
862
865
866
867
868
869
870
871
872
873
874
Generation Phase
Once %dt is in expanded form, the get_element() is called for each XML namespace. It
will generate the code for encoders and decoders for the elements in the XML namespace. Finally the root decoder is gnerated using gen_element(). Furing generation
following template files are used
aux-templ.c
dec-templ.c
enc-templ.c
getput-templ.c
-
Code
Code
Code
Code
generation
generation
generation
generation
template
template
template
template
for
for
for
for
auxiliary functions
decoders
encoders
accessor functions
A lot of the generated headers are simply hard coded in the xsd2sg.pl (i.e. no templates).
January 29, 2011
ZXID Book 34, p. 33
3.8. OVERVIEW OF THE XSD2SG.PL
CHAPTER
TOOL 3.
(GURU
COMPILATION
LEVEL) FOR EXPERTS
January 29, 2011
ZXID Book 34, p. 34
875
876
877
Chapter 4
Integration with Existing Web
Sites
882
Single Sign-On is used to protect some useful resources. ZXID does not have any
means of serving these resources, rather a normal web server or application server
should do it (e.g. Apache httpd(8) or Tomcat, or our favorite mini_httpd(8) ). ZXID
just concentrates on verifying that a user has a valid session, and if not, establishing the
session by way of SSO.
883
4.1
878
879
880
881
884
885
886
887
888
889
890
891
892
893
894
895
896
897
Brief Overview of Control Flow
The SAML 2.0 specifications mandate a wire protocol, and in order to speak the wire
protocol, the SP application typically has to follow certain standard sequence of control
flow.
First a user1 tries to access a web site that acts in SP role. This triggers following
sequence of events
1. User is redirected to URL in a common domain. This is so that we can read the
Common Domain Cookie that indicates which IdP the user uses. Alternatively, if
you started at https://sp1.zxidsp.org:8443/zxid?o=E, the CDC check is bypassed and flow 2b. happens.
2. After the CDC check, a Authentication Request (AuthnReq) is generated. The IdP
may have been chosen automatically using CDC (2a), or there may have been some
user interface interaction (not show in the diagram) to choose the IdP.
3. User is redirected to the IdP. The redirection carries as a query string a compressed
and encoded form of the SAML 2.0 AuthnReq.
1 The user is often referred to as "Principal" in more technical jargon. Although the human user and
web browser are distinct entities, we do not stress that separation here. Whatever user "does" really will, in
protocol, appear as web browser sending requests.
35
4.2. REDIRECT APPROACH
CHAPTERTO
4. INTEGRATION
INTEGRATION WITH EXISTING WEB SITES
SP (a web site)
Check CDC
1.
2a.
Web Application
or Content
Check
Session
2b.
5a.
User
(Principal)
Generate AuthnReq Redirect
5b.
Process AuthnResponse
3.
4.
4bis.
IdP
Figure 4.1: Typical control flow of ZXID SP
899
4. Once the IdP has authenticated the user, or observed that there already is a valid IdP
session (perhaps from a cookie), the IdP redirects the user back to the SP.
900
The AuthnResponse may be carried in this redirection in a number of alternate ways
898
901
902
903
904
905
906
907
908
909
910
911
912
913
914
a. The redirect contains a special token called artifact. The artifact is a reference to
the AuthnResponse and the SP needs to get the actual AuthnResponse by using
a SOAP call (the 4bis step).
b. The "redirect" is actually a HTML page with a form and little JavaScript that
causes the form to be automatically posted to the SP. The AuthnResponse is
carried as a form field.
5. After verifying that AuthnResponse indicated a success, the SP establishes a local
session for the user (perhaps setting a cookie to indicate this).
Depending on how the SP to web site integration is done the user is taken to the web
site in one of the two ways
a. Redirect to the content. This time the session is there, therefore the flow passes
directly from check session to the web content.
b. It is also possible to show the content directly without any intervening redirection.
915
4.2
Redirect Approach to Integration
916
*** TBW
January 29, 2011
ZXID Book 34, p. 36
CHAPTER 4. INTEGRATION WITH
4.3. PASS-THRU
EXISTING WEB
APPROACH
SITES TO INTEGRATION
917
4.3
Pass-thru Approach to Integration
918
4.3.1
919
*** TBW, but see mod_auth_saml.pd for some documentation.
920
4.3.2
921
*** TBW, but see zxid-perl.pd for some documentation.
922
4.3.3
923
*** TBW, but see zxid-php.pd for some documentation.
924
4.4
925
*** TBD
mod_auth_saml pass-thru
mod_perl pass-thru
PHP pass-thru
Proxy Approach to Integration
January 29, 2011
ZXID Book 34, p. 37
4.4. PROXY APPROACH
CHAPTER
TO INTEGRATION
4. INTEGRATION WITH EXISTING WEB SITES
January 29, 2011
ZXID Book 34, p. 38
926
927
928
929
930
931
932
933
934
935
936
Chapter 5
Testing
ZXID test suite is driven by zxtest.pl and the test input in t/ subdirectory. The test
suite is not distributed in the tar ball, but is available from the git repository. Some tests
still rely on detailed manual setup, YMMV.
Test coverage of the project is monitored using gcov and lcov tools. This requires
ZXID to be compiled in a special way:
make clean
make all ENA_PG=1
# Enables -pg flag to gcc, among others
Then you need to start the web servers that are used by the tests, for example:
mini_httpd -p 8081 -c ’zx*’ &
937
938
939
940
941
942
943
944
945
946
cd /home/sampo/apache-tomcat-5.5.20/
killall java; bin/startup.sh
Now you are ready to run, in the zxid distribution directory, the test suite
./zxtest.pl -a -a -dx
The test suite can also be run using web interface: http://localhost:8081/zxtest.pl
After running the test suite and possibly performing manual tests, you can generate the
test coverage report by running.
make lcov
You can then view the coverage report by pointing your web browser to lcovhtml/index.html
39
5.1. TEST SUITE
CHAPTER 5. TESTING
947
5.1
948
The test suite as of release 0.76, January 2011, covers following items:
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
Test Suite
Test suite 0.76
STATUS
SECS GOAL
OK
0.052 0.1
OK
0.038 0.1
OK
0.049 0.1
OK
0.044 0.1
OK
0.056 0.1
OK
0.058 0.1
OK
0.020 0.1
OK
0.058 0.1
OK
0.034 0.1
OK
0.056 0.1
OK
0.021 0.1
OK
0.027 0.1
OK
0.070 0.1
OK
0.100 0.1
OK
0.023 0.1
OK
0.020 0.1
OK
0.062 0.1
OK
0.039 0.1
OK
0.043 0.1
OK
0.042 0.1
OK
0.021 0.1
OK
0.024 0.1
OK
0.021 0.1
OK
0.020 0.1
OK
0.020 0.1
OK
0.023 0.1
OK
0.620 0.1
OK
0.027 0.1
OK
0.024 0.1
OK
0.023 0.1
OK
0.045 0.1
OK
0.043 0.1
OK
0.057 0.1
OK
0.054 0.1
OK
0.037 0.1
OK
0.042 0.1
OK
0.083 0.1
OK
0.046 0.1
OK
0.023 0.1
OK
0.039 0.1
OK
0.024 0.1
OK
0.050 0.1
OK
0.022 0.1
TEST NAME
HELP1 zxcall -h
HELP2 zxpasswd -h
HELP3 zxcot -h
HELP4 zxdecode -h
HELP5 zxlogview -h
SOENC1 EncDec Status
ATORD1 Attribute sorting
ATCERT1 Attribute certificate
CONF1 zxcall -dc dump config
CONF2 zxidhlo o=d dump config
CONF3 zxidhlo o=c dump carml
CONF4 zxidhlo o=B dump metadata
CONF5 zxididp o=B dump metadata
META1 Java LEAF Meta
HLO1 zxidhlo o=M LECP check
HLO2 zxidhlo o=C CDC
HLO3 zxidhlo o=E idp select page
HLO4 zxidhlo o=L start sso failure
HLO5 zxidhlo o=A artifact failure
HLO6 zxidhlo o=P POST failure
HLO7 zxidhlo o=D deleg invite fail
HLO8 zxidhlo o=F not an idp fail
IDP1 zxididp o=R fail
IDP2 zxididp o=F fail
IDP3 zxididp o=N new user fail
IDP4 zxididp o=W pwreset fail
IDP5 zxididp o=S SASL Req
PW1 zxpasswd list user
PW2 zxpasswd pw an ok
PW3 zxpasswd pw an fail
PW4 zxpasswd create user
PW5 zxpasswd change pw
PW6 zxpasswd list user
COT1 zxcot list
COT2 zxcot list swap
COT3 zxcot list s2
COT4 zxcot get idp meta dry
COT5 zxcot get sp meta dry
COT6 zxcot my meta
COT7 zxcot my meta add
COT8 zxcot gen epr
COT9 zxcot gen epr add
COT10 zxcot my meta
January 29, 2011
MESSAGES
ZXID Book 34, p. 40
CHAPTER 5. TESTING
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
OK
OK
OK
OK slow
OK slow
Diff ERR
Diff ERR
App Err
Diff ERR
Diff ERR
OK
App Err
App Err
App Err
App Err
App Err
App Err
App Err
App Err
OK
OK
Diff ERR
Diff ERR
App Err
OK
OK
OK
OK
OK
OK
OK
App Err
OK
OK
OK
OK
OK
OK
OK
OK
OK
App Err
OK
OK
OK
OK
OK
OK
OK
0.045
0.019
0.063
0.349
0.239
0.025
0.028
0.034
0.034
0.031
0.026
0.044
0.050
0.042
0.048
0.020
0.020
0.020
0.021
0.016
0.015
0.029
0.021
0.020
0.030
0.071
0.037
0.061
0.056
0.030
0.031
0.030
0.024
0.026
0.040
0.029
0.028
0.028
0.027
0.026
0.025
0.041
0.026
0.024
0.026
0.046
0.031
0.022
0.023
January 29, 2011
0.1
0.1
0.1
0.1
0.1
0.1
0.1
0.1
0.1
0.1
0.1
0.1
0.1
0.1
0.1
0.1
0.1
0.1
0.1
0.1
0.1
0.1
0.1
0.1
0.1
0.1
0.1
0.1
0.1
0.1
0.1
0.1
0.1
0.1
0.1
0.1
0.1
0.1
0.1
0.1
0.1
0.1
0.1
0.1
0.1
0.1
0.1
0.1
0.1
5.1. TEST SUITE
COT11 zxcot list s2
LOG1 zxlogview list
LOG2 zxlogview list
SMIME1 smime key gen ca
SMIME2 smime key gen joe
SMIME3 smime ca
SMIME4 smime code sig
SMIME5 smime code vfy
SMIME6 smime sig
SMIME7 smime clear sig
SMIME8 smime pubenc
SMIME8b smime pubencdec
SMIME9 smime sigenc
SMIME10 smime encsig
SMIME11 smime multi sigenc
SMIME12 smime query sig
SMIME13 smime verify
SMIME14 smime query cert
SMIME15 smime verify cert
SMIME16 smime mime ent
SMIME17 smime mime ent b64
SMIME18 smime pkcs12 exp
SMIME19 smime pkcs12 imp
SMIME20 smime query req
SMIME21 smime covimp
SIG1 sig vry shib resp
SIG2 sig vry shib post
SIG3 sig vry zxid resp
SIG4 sig vry zxid post
SIG5 sig vry sm resp
SIG6 sig vry sm post
SIG7 * sig vry shib resp undecl prefix
SIG8 * sig vry ping resp
SIG9 sig vry ping post
SIG10 sig vry hp a7n
SIG11 sig vry hp post
SIG12 sig vry hp resp
SIG13 sig vry hp resp2
SIG15 sig vry saml artifact response
SIG18b sig vry prstnt-a7n
SIG20b sig vry rsa-a7n
SIG21b sig vry rsa-a7n2
SIG22b sig vry rsa-idp-post
SIG32b sig vry enc-nid-enc-attr
SIG37 sig vry
SIG38 sig vry
SIG39 sig vry
exit=256
exit=256
exit=256
exit=256
exit=256
exit=256
exit=256
exit=256
exit=256
exit=256
exit=2816
exit=2816
ZXID Book 34, p. 41
5.1. TEST SUITE
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
OK
OK
OK
OK
OK
OK
OK
OK
OK
OK
OK
OK
OK
OK
OK
OK
OK
OK
OK
OK
OK
OK
OK
OK
OK
OK
OK
OK
OK
OK
OK
OK
OK
OK
OK
OK
OK
OK
OK
OK
OK
OK
OK
OK
OK
OK
OK
OK
OK
slow
slow
slow
slow
slow
slow
slow
slow
slow
slow
0.034
0.025
0.187
0.139
0.164
0.014
0.413
0.056
0.166
0.327
0.257
0.572
0.223
0.261
0.333
0.281
0.577
0.435
0.046
0.220
0.055
0.017
0.019
0.045
0.041
0.021
0.032
0.029
0.021
0.033
0.018
0.019
0.014
2.736
1.069
5.019
5.059
7.840
1.667
2.024
9.880
16.51
9.338
2.879
1.086
9.408
9.677
9.855
9.787
January 29, 2011
CHAPTER 5. TESTING
0.1
0.1
10
10
10
0.01
10
10
10
10
10
10
10
10
10
10
10
10
10
10
10
0.1
0.1
0.1
0.1
0.1
0.1
0.1
0.1
0.1
0.1
0.1
0.1
30
0.1
30
30
30
30
0.03
30
30
0.1
0.1
0.1
0.1
0.1
0.1
0.1
SIG40 sig vry
SIG41 sig vry
XML1 Decode-Encode SO and WO: ns-bug
XML2 Decode-Encode SO and WO: azrq1
XML3 Decode-Encode SO and WO: azrs1
XML4 * Decode-Encode RIS malformed 1
XML5 Decode-Encode SO and WO: ana7n1
XML6 Decode-Encode SO and WO: anrq1
XML7 Decode-Encode SO and WO: anrs1
XML8 Decode-Encode SO and WO: dirq1
XML9 Decode-Encode SO and WO: dirs1
XML10 Decode-Encode SO and WO: dirq2
XML11 Decode-Encode SO and WO: dia7n1
XML12 Decode-Encode SO and WO: epr1
XML13 Decode-Encode SO and WO: wsrq1
XML14 Decode-Encode SO and WO: wsrs1
XML15 Decode-Encode SO and WO: wsrq2
XML16 Decode-Encode SO and WO: wsrs2
XML17 Decode-Encode SO and WO: as-req
XML18 Decode-Encode SO and WO: as-resp
XML19 Decode-Encode SO and WO: authnreq
XML20 Decode-Encode SO and WO: sun-md
XML21 Decode-Encode SO and WO: provisio
XML22 Decode-Encode SO and WO: provisio
XML23 Decode-Encode SO and WO: pds-crea
XML24 Decode-Encode SO and WO: pds-quer
XML25 Decode-Encode SO and WO: AdvCliennt
XML26 Decode-Encode SO and WO: AdvClient
XML27 Decode-Encode SO and WO: AdvClient
XML28 Decode-Encode SO and WO: AdvClien
XML29 Decode-Encode SO and WO: AdvClien
XML30 Decode-Encode SO and WO: zx a7n
XML31 Decode-Encode SO and WO: covimp
ZXC-AS1 Authentication Service call: SS
ZXC-AS2 Authentication Service call: An
ZXC-IM1 Identity Mapping Service call
ZXC-IM2 * SAML NID Map call
ZXC-IM3 SSOS call
ZXC-DI1 Discovery Service call
ZXC-DI2 List EPR cache
ZXC-WS1 AS + WSF call: idhrxml
ZXC-WS2 AS + WSF call: x-foobar
ZXC-WS3 AS + WSF call leaf (x-recurs)
ZXC-WS4 AS + WSF call EPR not found
ZXC-WS5 AS + WSF call bad pw
ZXC-WS6 AS + WSF call hr-xml bad
ZXC-WS7 AS + WSF call hr-xml create
ZXC-WS8 AS + WSF call hr-xml query
ZXC-WS9 AS + WSF call hr-xml mod
ZXID Book 34, p. 42
CHAPTER 5. TESTING
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
OK slow
OK
OK
OK
OK
OK
App Err
OK
OK slow
OK
OK
OK
OK
OK
=== Test
5.2. TEST COVERAGE
9.697 0.1
ZXC-WS10 AS + WSF call hr-xml mod
0.116 0.5
LOGIN-IDP1 IdP Login screen
0.219 0.5
LOGIN-IDP2 IdP Give password
0.121 0.5
LOGIN-IDP3 IdP Local Logout
0.120 0.5
SSOHLO1 IdP selection screen
0.441 0.5
SSOHLO2 Selected IdP
0.115 0.5
SSOHLO3 Login to IdP
0.120 0.5
SSOHLO4 POST to SP
0.674 0.5
SSOHLO5 SP SOAP Az
0.113 0.5
SSOHLO6 SP SOAP defed
0.109 0.5
SSOHLO7 SP SOAP defed
0.110 0.5
SSOHLO8 SP SOAP logout
0.110 0.5
SSOHLO9 SP local logout
3.010 10
COVIMP1 Silly tests, to improve cov
success 135/155 (87.1%) ===
len=1933
len=685
len=2309
len=3280
len=2649
len=3280
len=52742
len=3280
len=3280
len=3280
len=3280
len=3280
1110
As can be seen from the output, the smime tool has still many unresolved problems.
Other test failures are explained in the comments in the zxtest.pl application. Major
part of that application is a large table of tests where the test setup is described and any
anomalies are commented on.
1111
5.2
1112
The test coverage report looks as follows
1107
1108
1109
Test Coverage
1116
As of R0.73, December 2010, the test coverage was about 63% of the handwritten lines
of code that could execute. While this figure is still mediocre, it should be noted that
100% test coverage is inachievable and useless stretch goal. We feel about 80% would
be good.
1117
There are several reasons why 100% is not achievable:
1113
1114
1115
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1. Defensive coding requires us to insert error checks at many layers. This means
that some of the error checks will never trigger because the checks in other layers
already checked the situation. It is therefore virutally impossible to construct a test
case that would cause the code path to be taken.
2. Similar to above, some checks require extreme inputs, e.g. to overflow buffers. Such
inputs may be very expensive to generate and extremely unlikely in real practise.
While these situations should be tested for security vulnearabilities, there is not
much harm done if null pointer exception causes a cgi process to crash rather than
return meaningful error message. The cost of testing these corner cases can be hard
to justify.
3. We have peppered the code with extensive debug prints. While crash due to debug
print is nasty, it is also avoidable by turning off the debug flag. Not worth burning
too much midnight oil to concot test cases to test every corner case in this area.
4. The test coverage considerations do not include subdirectory c/ as that contains
machine generated code. This is highly repetitive and there is no point to include it
in coverage score.
January 29, 2011
ZXID Book 34, p. 43
5.2. TEST COVERAGE
CHAPTER 5. TESTING
ZXTEST
file:///home/sampo/zxid/zxtest-web.html
ZXID Testing Tool 20110129-011643 nodiff
zxtest.pl
Status Secs Goal Test name Messages
OK 0.031 0.1 HELP1 * zxcall -h
OK 0.024 0.1 HELP2 * zxpasswd -h
OK 0.032 0.1 HELP3 * zxcot -h
OK 0.019 0.1 HELP4 * zxdecode -h
OK 0.019 0.1 HELP5 * zxlogview -h
OK 0.027 0.1 SOENC1 * EncDec Status
OK 0.028 0.1 ATORD1 * Attribute sorting
OK 0.055 0.1 ATCERT1 * Attribute certificate
OK 0.028 0.1 CONF1 * zxcall -dc dump config
Diff ERR 0.035 0.1 CONF2 * zxidhlo o=d dump config
OK 0.041 0.1 CONF3 * zxidhlo o=c dump carml
OK 0.032 0.1 CONF4 * zxidhlo o=B dump metadata
OK 0.042 0.1 CONF5 * zxididp o=B dump metadata
OK 0.098 0.1 META1 * Java LEAF Meta
OK 0.021 0.1 HLO1 * zxidhlo o=M LECP check
OK 0.023 0.1 HLO2 * zxidhlo o=C CDC
OK 0.051 0.1 HLO3 * zxidhlo o=E idp select page
OK 0.040 0.1 HLO4 * zxidhlo o=L start sso failure
OK 0.040 0.1 HLO5 * zxidhlo o=A artifact failure
OK 0.049 0.1 HLO6 * zxidhlo o=P POST failure
OK 0.026 0.1 HLO7 * zxidhlo o=D deleg invite fail
OK 0.023 0.1 HLO8 * zxidhlo o=F not an idp fail
OK 0.021 0.1 IDP1 * zxididp o=R fail
OK 0.024 0.1 IDP2 * zxididp o=F fail
OK 0.029 0.1 IDP3 * zxididp o=N new user fail
OK 0.021 0.1 IDP4 * zxididp o=W pwreset fail
OK slow 0.552 0.1 IDP5 * zxididp o=S SASL Req
OK 0.028 0.1 PW1 * zxpasswd list user
OK 0.034 0.1 PW2 * zxpasswd pw an ok
OK 0.025 0.1 PW3 * zxpasswd pw an fail
OK 0.031 0.1 PW4 * zxpasswd create user
OK 0.024 0.1 PW5 * zxpasswd change pw
OK 0.020 0.1 PW6 * zxpasswd list user
OK 0.088 0.1 COT1 * zxcot list
OK 0.055 0.1 COT2 * zxcot list swap
OK 0.079 0.1 COT3 * zxcot list s2
OK slow 0.161 0.1 COT4 * zxcot get idp meta dry
OK 0.060 0.1 COT5 * zxcot get sp meta dry
1 of 4
01/29/11 01:44
Figure 5.1: Test output using web interface.
1134
1135
1136
With the above caveats, it still needs to be admitted that more testing could be done. In
particular the biggest gaps appear in areas where new functionality is already supported
at encoder-decoder level, but not yet realized in hand written logic.
January 29, 2011
ZXID Book 34, p. 44
CHAPTER 5. TESTING
5.2. TEST COVERAGE
LCOV - ZXID Code Coveragezxid
http://zxid.org/lcovhtml-0.73/zxid/index.html
LCOV - code coverage report
Current view: top level - zxid
Hit
Total
Lines:
8686
13796
63.0 %
Functions:
513
623
82.3 %
Branches:
5736
14043
40.8 %
Test: ZXID Code Coverage
Date: 2010-12-19
Filename
Line Coverage
Functions
Coverage
Branches
certauth.c
35.4 %
29 / 82
66.7 %
2/3
19.3 %
17 / 88
keygen.c
82.3 %
130 / 158
100.0 %
6/6
47.2 %
67 / 142
pkcs12.c
smime-enc.c
9.7 %
24 / 247
33.3 %
2/6
6.6 %
15 / 226
57.3 %
86 / 150
62.5 %
5/8
31.0 %
36 / 116
smime-qry.c
9.6 %
16 / 166
14.3 %
2 / 14
5.4 %
6 / 112
smime-vfy.c
46.8 %
66 / 141
71.4 %
5/7
26.9 %
35 / 130
smime.c
62.3 %
230 / 369
100.0 %
7/7
51.0 %
100 / 196
smimemime.c
49.0 %
76 / 155
72.7 %
8 / 11
33.6 %
47 / 140
smimeutil.c
68.6 %
109 / 159
73.3 %
11 / 15
40.7 %
44 / 108
ykaes.c
0.0 %
0 / 60
0.0 %
0/2
0.0 %
0 / 18
ykcrc.c
0.0 %
0 / 10
0.0 %
0/1
0.0 %
0/6
zxcall.c
82.4 %
211 / 256
100.0 %
3/3
53.5 %
147 / 275
zxcot.c
83.5 %
202 / 242
100.0 %
7/7
64.0 %
121 / 189
zxcrypto.c
73.5 %
285 / 388
85.7 %
12 / 14
46.3 %
99 / 214
zxdecode.c
71.9 %
182 / 253
100.0 %
5/5
48.4 %
139 / 287
zxencdectest.c
88.6 %
279 / 315
100.0 %
9/9
47.2 %
83 / 176
zxida7n.c
76.2 %
16 / 21
100.0 %
1/1
27.8 %
15 / 54
zxidcdc.c
81.0 %
34 / 42
100.0 %
2/2
50.0 %
24 / 48
zxidcgi.c
89.7 %
130 / 145
100.0 %
3/3
61.7 %
171 / 277
zxidconf.c
68.4 %
524 / 766
96.6 %
28 / 29
43.2 %
396 / 916
zxidcurl.c
90.3 %
140 / 155
88.9 %
8/9
55.1 %
49 / 89
zxiddec.c
69.2 %
83 / 120
100.0 %
2/2
34.8 %
73 / 210
zxiddi.c
60.3 %
91 / 151
100.0 %
2/2
38.7 %
103 / 266
zxidecp.c
93.2 %
55 / 59
100.0 %
4/4
54.8 %
23 / 42
zxidepr.c
42.5 %
147 / 346
30.6 %
11 / 36
43.1 %
199 / 462
zxidhlo.c
91.5 %
43 / 47
100.0 %
1/1
56.2 %
18 / 32
zxidhrxmlwsp.c
69.1 %
103 / 149
100.0 %
1/1
59.6 %
62 / 104
zxididp.c
95.8 %
46 / 48
100.0 %
1/1
56.2 %
zxididpx.c
14.6 %
6 / 41
100.0 %
1/1
4.8 %
2 / 42
zxidim.c
28.3 %
68 / 240
60.0 %
3/5
8.6 %
21 / 244
zxidlib.c
65.2 %
288 / 442
100.0 %
23 / 23
37.1 %
160 / 431
zxidloc.c
30.1 %
37 / 123
42.9 %
3/7
24.2 %
38 / 157
zxidmeta.c
71.2 %
307 / 431
84.4 %
27 / 32
41.3 %
161 / 390
zxidmk.c
88.6 %
248 / 280
100.0 %
21 / 21
58.0 %
91 / 157
zxidmkwsf.c
92.5 %
186 / 201
96.4 %
27 / 28
57.3 %
141 / 246
zxidmni.c
30.9 %
21 / 68
75.0 %
3/4
13.2 %
10 / 76
zxidpdp.c
53.6 %
30 / 56
100.0 %
2/2
42.6 %
26 / 61
zxidpep.c
40.9 %
96 / 235
50.0 %
6 / 12
25.6 %
68 / 266
zxidpool.c
58.7 %
262 / 446
78.6 %
11 / 14
39.3 %
251 / 638
zxidps.c
12.1 %
38 / 315
30.8 %
4 / 13
3.2 %
7 / 222
zxidpsso.c
65.5 %
293 / 447
100.0 %
14 / 14
40.0 %
263 / 657
zxidses.c
68.5 %
122 / 178
100.0 %
8/8
49.5 %
108 / 218
zxidsimp.c
62.7 %
418 / 667
74.3 %
26 / 35
41.6 %
384 / 923
1 of 2
18 / 32
01/29/11 01:47
Figure 5.2: Test coverage report.
January 29, 2011
ZXID Book 34, p. 45
5.2. TEST COVERAGE
January 29, 2011
CHAPTER 5. TESTING
ZXID Book 34, p. 46
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
Chapter 6
Configuring Runtime
ZXID, out-of-box, needs very little configuration. Generally you only need to decide
the URL of your web site.
Compile time configuration, based on Makefile and zxidconf.h is possible but generally should not be attempted, unless the intent is embedded system running without
any configuration file.
In addition to setting runtime configure options, you will need to join a Circle of Trust
- or create your own. This is explained in the "Circle-of-Trust" chapter, below.
If you are interested in using mod_auth_saml Apache module, you can perform some
of the configuration in the Apache httpd.conf file as explained in mod_auth_saml.
You should remember that some of the configuration will happen in the web server
level, see your web server’s configuration reference, e.g. httpd.conf
1151
ZXID ships with working demo configuration so you can run it right away and once
you are familiar with the concepts, you can return to this chapter.
1152
ZXID uses a configuration file in default path1
1150
1153
/var/zxid/zxid.conf
1159
for figuring out its parameters. If this file is not present, built-in default configuration
is used (see zxidconf.h).2 The built-in configuration will allow you to test features of
ZXID, but should not be used in production because it uses default certificates and private keys. Obviously the demo private key is of public knowledge since it is distributed
with the ZXID package, and as such it provides no privacy protection what-so-ever.
For production use you MUST generate your own certificate and private key.
1160
Usually configuring a system involves following tasks
1161
1. Configure web server (see your web server documentation)
1154
1155
1156
1157
1158
1 See
Simple API for description on how to change this path at deplyment or run time.
can override configuration options at run time by supplying fragments of configuration using -O
flags, but for CGI use you would have to use a wrapper shell script to supply them. Hence, easier to just use
the config file.
2 You
47
6.1. CONFIGURATION PARAMETERSCHAPTER 6. CONFIGURING RUNTIME
1162
1163
1164
1165
1166
1167
1168
1169
1170
a. HTTPS operation and TLS certificate. In the minimum you need the main site,
but you may want to configure the Common Domain Cookie virtual host as well.
b. Arrange for ZXID to be invoked. This could mean configuring zxid, zxid-java.sh,
or zxid.pl to be recognized as a CGI script, or it could mean setting up your
mod_perl or mod_php system to call ZXID at the appropriate place.
2. Configure ZXID, including signing certificate and CoT with peer metadata
a. generate or acquire certificate
b. Obtain peer metadata (from their well known location) or enable Auto CoT feature.
1173
3. Configure CoT peers with your metadata. They can download your metadata from
your well known location (which is the URL that is your entity ID). For this to
happen you need to have web server and ZXID up and running.
1174
6.1
1175
6.1.1
1171
1172
1176
1177
1178
1179
1180
1181
1182
1183
1184
Configuration Parameters
zxidroot (PATH configuration parameter)
The root directory of ZXID configuration files and directories. By default this is
/var/zxid and has following directories and files in it
/var/zxid/
|
+-- zxid.conf
+-- pem/
+-- cot/
+-- ses/
‘-- log/
Main configuration file
Our certificates
Metadata of CoT partners (metadata cache)
Sessions
Log files, pid files, and the like
1185
See also zxid-log.pd for detailed description of the filesystem layout.
1186
6.1.2
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
pem
Directory that holds various certificates. The certificates have hardwired names that
are not configurable.
ca.pem Certification Authority certificates. These are used for validating any certificates received from peers (other sites on the CoT). The CA certificates may
also be shipped to the peers to facilitate them validating our signatures. This is
especially relevant if the certificate is issued by multilayer CA hierarchy where
the peer may not have the intermediate CA certificates.
sign-nopw-cert.pem The signing certificate AND private key (concatenated in
one file). The private key MUST NOT be encrypted (there will not be any opportunity to supply decryption password).
January 29, 2011
ZXID Book 34, p. 48
CHAPTER 6. CONFIGURING RUNTIME
6.2. ZXID CONFIGURATION FILE FORMAT
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
enc-nopw-cert.pem The encryption certificate AND private key (concatenated
in one file). The private key MUST NOT be encrypted (there will not be any opportunity to supply decryption password). The signing certificate can be used as
the encryption certificate. If encryption certificate is not specified it will default
to signing certificate.
In addition to the above certificates and private keys, you will need to configure your
web server to use TLS or SSL certificates for the main site and the Common Domain
site. We suggest the following naming
ssl-nopw-cert.pem SSL or TLS certificate for main site. In order to avoid
browser warnings, the CN field of this certificate should match the domain name
of the site. The SSL certificate can be same as signing or encryption certificate.
1211
cdc-nopw-cert.pem SSL or TLS certificate for Common Domain Cookie introduction site. In order to avoid browser warnings, the CN field of this certificate
should match the domain name of the site. The SSL certificate can be same as
signing or encryption certificate.
1212
6.1.3
1208
1209
1210
cot
1214
Directory that holds metadata of the Circle of Trust (CoT) partners. If Auto CoT is
enabled, this directory needs to be writable at run time.
1215
Typical metadata file path would be
1213
1216
1217
/var/zxid/cot/Inkl5fOnhVNa0LbWjHem2Y2UphY
If the metadata file appears in this directory, then the entity is in the CoT.
1219
The file name component of the path is safe base64 encoded SHA1 hash of the Entity
ID, with last character stripped (that character would always be an equals sign).
1220
6.2 ZXID Configuration File Format
1218
1221
1222
1223
1224
1225
1226
1227
1228
1229
Most configuration details are kept as comments in zxidconf.h, which you should
see.
Configuration file is line oriented. Comments can be introduced with cardinal ("#")
and empty lines are ignored. End of line comments are NOT supported at this time.
Each configuration option is a name=value pair. The name is the same as in zxidconf.h
except that ZXID_ prefix does not appear. Only single line values are supported, but
you can embed characters using URI encoding, e.g. %0a for newline. In fact, the
configuration lines are treated as CGI variables, thus & can also be used as separator
instead of newline (and needs to be encoded if not intended as separator).
1231
When option is not specified, the default from zxidconf.h prevails. Thus in the following the PATH specification is redundant.
1232
To give some idea consider following /var/zxid/zxid.conf example:
1230
January 29, 2011
ZXID Book 34, p. 49
6.2. ZXID CONFIGURATION FILE FORMAT
CHAPTER 6. CONFIGURING RUNTIME
1233
1234
1235
1236
1237
# Demo /var/zxid/zxid.conf file
PATH=/var/zxid/
URL=https://sp.mydomain.com:8443/zxid
NICE_NAME=My SP’s human%0areadable name.
#EOF
1239
The configuration is processed in following order, with last instance of an option prevailing:
1240
1. Built in default configuration
1241
2. Configuration file, usually /var/zxid/zxid.conf, if any
1242
3. Configuration string passed as first argument.
1238
1243
1244
1245
1246
1247
1248
1249
1250
Configuration string is processed in order and overrides values from compiled in
defaults as well as from zxid.conf in the compiled in default path.
While processing options, if PATH is found, the (new) config file is read, effectively
overriding any options thus far.
Essentially this allows you to provide early in configuration string options that can then
be overridden by the config file ready by virtue of PATH apprearing in the config string.
The options in the string that come later in the string can then override values in config
file.
January 29, 2011
ZXID Book 34, p. 50
1251
1252
1253
Chapter 7
zxid_simple() API Specific
Configuration
1254
For full description of the simple API, plese see zxid_simple() Easy API for SAML.
1255
7.0.1
1256
1257
1258
1259
1260
Configuration Options
The zxid_simple() can be configured by conf string as argument as well as by configuration file. In addition a flags argument is accepted, see next subsection "AUTO
options", to specify simple API specific automation options.
Turns out that often the default configuration modified by the configurations string is
all you need - you do not need to prepare a configuration file.
1262
See section "Configuring and Running" for complete list of configuration options, but
generally it is sufficient to specify only a handful:
1263
PATH Where files are kept and configuration file is found.
1264
URL The URL of the SP
1261
1266
CDC_URL The Common Domain URL (optional, if omitted the Common Domain
Cookie processing is disabled)
1267
7.0.2
1265
AUTO options (auto flags)
1270
The auto_flags argument allows you to control which operations should be performed automatically and which should be passed to the calling application, see "Gaining More Control" section, below, for full description of this case.
1271
The auto options can be added together.
1268
1269
1273
If the AUTO_REDIR flag is true, the LOCATION header is sent to stdout and exit(0)
may be called, depending on the AUTO_NOEXIT flag.
1274
The SOAP, META, LOGIN, and MGMT flags follow convention:
1272
51
CHAPTER 7. ZXID_SIMPLE() API SPECIFIC CONFIGURATION
Table 7.1: zxid_simple() AUTO options
Dec
1
2
4
8
16
32
64
128
256
512
1024
2048
4095
4096
8192
16384
1275
1276
1277
1278
1279
HC
00
01
10
11
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
Hex
0x01
0x02
0x04
0x08
0x10
0x20
0x40
0x80
0x100
0x200
0x400
0x800
0xfff
0x1000
0x2000
0x4000
Symbol
ZXID_AUTO_EXIT
ZXID_AUTO_REDIR
ZXID_AUTO_SOAPC
ZXID_AUTO_SOAPH
ZXID_AUTO_METAC
ZXID_AUTO_METAH
ZXID_AUTO_LOGINC
ZXID_AUTO_LOGINH
ZXID_AUTO_MGMTC
ZXID_AUTO_MGMTH
ZXID_AUTO_FORMF
ZXID_AUTO_FORMT
ZXID_AUTO_ALL
ZXID_AUTO_DEBUG
ZXID_AUTO_OFMTQ
ZXID_AUTO_OFMTJ
Description
Call exit(), 0=return "n", even if auto CGI
Automatic. handle redirects, assume CGI (calls exit(2))
SOAP response handling, content gen
SOAP response handling, header gen
Metadata response handling, content gen
Metadata response handling, header gen
IdP select / Login page handling, content gen
IdP select / Login page handling, header gen
Management page handling, content gen
Management page handling, header gen
In idp list and mgmt screen, generate form fields
In idp list & mgmt screen, wrap in <form> tag.
Enable all automatic CGI behaviour.
Enable debugging output to stderr.
Output Format Query String
Output Format JSON
No automation. Only action letter is returned ("e"=login, "b"=meta, etc.)
Content, not wrapped in headers, is returned as a string
Headers and content is returned as a string
Headers and content are sent to stdout, CGI style and
exit(0) may be called, depending on AUTO_EXIT. Otherwise "n" is returned.
Whether exit(0) is called in 11 case depends on ZXID_AUTO_NOEXIT flag.
How much HTML is generated for Login page and Mgmt page in 01 (content only)
mode depends on AUTO_PAGE and AUTO_FORM flags
TF
00
01
10
11
reserved / nothing is generated
Only form fields (but not form tag itself) are generated.
Complete form is generated
Whole page is generated (best support)
The output format in the successful SSO case depends on OFMT bits as follows
JQ
00
01
10
11
LDIF (default)
Query String
JSON
empty res, caller is expected to access ses for attributes
January 29, 2011
ZXID Book 34, p. 52
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
7.0.3
Configuration options for customizing HTML
When whole page is generated, some templating information is taken from the configuration.
IDP_SEL_START All the HTML before <form> tag. This can include HTML headers and the <body> tag, as well as beginning of the page, allowing for complete
color selection, stylesheet embedding, and general branding of the page.
IDP_SEL_NEW_IDP The HTML fragment to allow login using a new IdP (Auto
CoT using IdP URL). Set to empty to hide this possibility.
IDP_SEL_OUR_EID Message displaying SP Entity ID, in case (technically minded)
user needs to know this to establish relationship with an IdP.
IDP_TECH_USER Technical parameters that user might want to set, and typically
would be allowed to set. May be hidden (not user controllable) or visible.
1307
fc Create federation (AllowCreate flag)
1308
fn Name ID format
1309
1310
1311
1312
prstnt Persistent (pseudonym)
trnsnt Transient, temporary pseudonym
IDP_TECH_SITE Technical parameters that the site administrator should decide and
set. Usually hidden fields:
1313
fq Affiliation ID (usually empty)
1314
fy Consent obtained by SP for the federation or SSO
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
empty No statement about consent
urn:liberty:consent:obtained Has been obtained (unspecified
way)
urn:liberty:consent:obtained:prior Obtained prior to present
transaction, e.g. user signed terms and conditions of service
urn:liberty:consent:obtained:current:implicit Consent
is implicit in the situation where user came to invoke service
urn:liberty:consent:obtained:current:explicit Obtained
explicitly
urn:liberty:consent:unavailable Consent can not be obtained
urn:liberty:consent:inapplicable Obtaining consent is not
relevant for the SP or service.
1327
fa Authentication Context (strength of authentication) needed by the SP
1328
fm Matching rule for authentication strength (usually empty, IdP decides)
1329
fp Forbid IdP from interacting with the user (IsPassive flag)
1330
ff Request reauthentication of user (ForceAuthn flag)
January 29, 2011
ZXID Book 34, p. 53
January 29, 2011
ZXID Book 34, p. 54
1331
1332
Chapter 8
ZXID Attribute Broker (ZXAB)
Liberty IGF
AAPML
Source
namespace
SSO AttrStmt
Liberty IGF
CARML
Sources
Attr
Broker
and
Router
Configuration
(per Location)
Mappings
ID-DAP
needs
PersonalProfile
LDAP query
MySQL query
Filesystem
©20080324 Sampo
Src Attr
Mapper
and
Rename
Application
namespace
Need
&
Want
Filter
OUT
MAP
Common
namespace
Apache
subprocess
environment
Obligations
Static Content
CGI
mod_perl
mod_php
Figure 8.1: Liberty IGF Compliant Attribute Broker fetches the needed attributes from available
providers and populates them to the subprocess environment.
1335
As can be seen in the accompanying figure, the provision of attributes to the applications in the Apache subprocess environment (CGI, mod_perm, mod_php, etc.) is
handled as follows:
1336
1. Configure attribute needs and names (this corresponds to CARML declaration)
1337
2. Configure attribute sources (this corresponds to AAPML declaration)
1338
3. Configure source or input mappings (INMAP)
1339
4. Filter for needs (and optional wants)
1340
5. Map to application domain (OUTMAP)
1341
6. Provide attributes in to subprocess environment
1333
1334
1342
1343
7. Comply with obligations (large part of this responsibility rests with the subprocesses
and can not be automatically enforced)
55
8.1. ATTRIBUTE BROKER CONFIGURATION
CHAPTER 8. ZXID
DIRECTIVES
ATTRIBUTE BROKER (ZXAB)
N.B. For an attribute to be available, four conditions must be met: (i) it
must actually exist, (ii) it must be specified in NEED (or WANT, if no
absolute guarantee of availability is necessary), (iii) it must pass INMAP,
and (iv) it must pass OUTMAP or purpose specific map like PEPMAP.
1344
1345
1346
1347
1348
8.1
Attribute Broker Configuration Directives
1349
*** This is provisory specification
1351
The Attribute Broker configuration in Apache set-up is per <Location> directive. Different Locations within same server can have different needs.
1352
Example
1350
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
<Location /protected>
ZXIDConf "NEED=CN$GUI$40000000$none$ext"
ZXIDConf "NEED=age$adult-content$100000$log-upon-sso,report-to-dashboard-if-avail$ext"
ZXIDConf "WANT=birthday$horoscope$40000000$log-upon-sso,must-report-to-dashboard$ext"
ZXIDConf "WANT=street,l,st,zip,c$ship$40000000$log-upon-sso,report-to-dashboard-if-ava
</Location>
8.1.1
NEED specification
NEED specification expresses attributes that are required for the application to work.
Attribute names are in the Common Namespace (often same as subprocess environment
application namespace). Inavailability of the attributes aborts application processing.
NEED=A,B$usage$retention$oblig$ext
A,B Names of attributes (comma separated list) needed by subprocess environment
usage The promised usage of the attributes (feeds out to CARML declaration). Specific usage enumerators or policy language are still To Be Defined. Special value
"reset" clears previous need configuration.
retention The data retention policy that will be applied to these attributes if they are
received. Specific enumerators or language are still To Be Defined. The example
illustrates retention in seconds.
1372
oblig The obligations that will be complied to WRT these attributes if they are received. Specific enumerators or language are still TBD.
1373
ext Extension fields to describe attribute policies in more detail.
1371
January 29, 2011
ZXID Book 34, p. 56
CHAPTER 8. ZXID8.1.
ATTRIBUTE
ATTRIBUTE
BROKER
BROKER
(ZXAB)
CONFIGURATION DIRECTIVES
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
8.1.2
WANT specification
WANT specification expresses attributes that are optional, but useful, for the application.
Inavailability of the attributes may cause reduced application functionality or the application querying the missing attributes directly from the user. WANT specification has
same syntax as NEED specification. Inavailability of the attribute has no consequence
or may cause default to be supplied.
WANT=A,B$usage$retention$oblig$ext$default
A,B Names of attributes (comma separated list) needed by subprocess environment. If
star (*) is specified, all available attributes are requested.1
usage The promised usage of the attributes (feeds out to CARML declaration). Specific usage enumerators or policy language are still To Be Defined.
retention The data retention policy that will be applied to these attributes if they are
received. Specific enumerators or language are still To Be Defined.
1388
oblig The obligations that will be complied to WRT these attributes if they are received. Specific enumerators or language are still TBD.
1389
ext Extension fields to describe attribute policies in more detail.
1390
default Optional default value to use in case the attribute is not available.
1391
8.1.3
1387
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
ATTRSRC specification
The Single Sign-On is an implicit Attribute Source and need not be specifically listed.
The attribute namespace will be IdP’s Entity ID.
N.B. As of Sept 2009, the SSO source is the only one implemented.
Attribute Source (ATTRSRC for short) specification indicates a potential source of attribute data and the mechanics for retreiving them. Each attribute originating from a
determined source is in namespace of that source (source namespace). This avoids
attribute naming conflicts and provides for clean attribute renaming framework. If an
attribute is not renamed, then it is passed to the common namespace by just dropping
the namespace prefix.
ATTRSRC=namespace$A,B$weight$accessparamURL$AAPMLref$otherLim$ext
1402
namespace Namespace string assigned to this attribute source.
1403
A,B List of attributes available from this source
1404
1405
weight Weighting factor (integer) determining the prioirity of this source. Less indicates higher preference.
1 This should not be used light heartedly. Much better to spell out explicitly the attribute requirements so
that proper CARML description can be made.
January 29, 2011
ZXID Book 34, p. 57
CHAPTER 8. ZXID
DIRECTIVES
1406
1407
accessparam Typically URL for contacting the source, or special value "reset" to clear
the list and start building anew.
1409
AAPMLref Reference to AAPML declaration about policies applying to this attribute
source
1410
otherLim Description of additional policies applying to this attribute source
1411
ext Extensions
1408
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
In a Web Service call, on Web Service Provider’s side, the implicit attribute sources
include
• Requester token (assertion). This attribute source will use as namespace the issuer’s entity ID. Essentially this is similar to the Single Sign-On assertion treatment.
• Target Identity token (assertion). This attribute source will use as namespace the
issuer’s entity ID. Further, the actual attributes are prefixed with "tgt_".
• Attributes passed in SOL (Simple Obligations Language) formatted UsageDirective. This attribute source will use as namespace the entity ID of the message
signer, i.e. the WSC that pledges to respect the obligations.
8.1.4
INMAP specification
INMAP specification provides for various input attribute renaming and input attribute
value decoding operations.
INMAP=ns$A$rule$b$ext
1426
ns Source namespace of the attribute
1427
A Attribute name in the source namespace
1428
b Attribute name in common namespace (if omitted, same as +A+)
1429
rule transformation rule:
1430
rename Just renames the attribute. Value is passed intact. Default.
1431
del Deletes the attribute.
1432
1433
1434
1435
1436
1437
1438
1439
feidedec Decode the attribute value accoring to Feide (Norway) rules. Also
rename if +b+ provided.
feideenc Encode the attribute value accoring to Feide (Norway) rules. Also
unsb64-inf Decode the attribute value accoring to safebase64-inflate rules ([?],
[?]). Also rename if +b+ provided.
def-sb64 Encode the attribute value accoring to deflate-safebase64 rules ([?],
[?]). Also rename if +b+ provided.
January 29, 2011
ZXID Book 34, p. 58
CHAPTER 8. ZXID8.1.
ATTRIBUTE
ATTRIBUTE
BROKER
BROKER
(ZXAB)
CONFIGURATION DIRECTIVES
unsb64 Decode the attribute value according to safebase64 [?] rule (NZ). Also
1440
1441
1443
sb64 Encode the attribute value according to safebase64 [?] rule (NZ). Also
1444
a7n Wrap the attribute in a SAML2 assertion
1445
x509 Wrap the attribute in a X509 AC attribute certificate
1446
file Obtain the value of the attribute from file specified in the ext field
1447
a7n-feideenc Combination of a7n and fedieenc
1448
a7n-def-sb64 Combination of a7n and def-sb64
1449
a7n-sb64 Combination of a7n and sb64
1450
x509-feideenc Combination of x509 and fedieenc
1451
x509-def-sb64 Combination of x509 and def-sb64
1452
x509-sb64 Combination of x509 and sb64
1453
file-feideenc Combination of file and fedieenc
1454
file-def-sb64 Combination of file and def-sb64
1455
file-sb64 Combination of file and sb64
1456
reset Special pseudo rule that clears previous map configuration.
1442
1457
ext Extended argument that may be used by some rules.
1459
The order of evaluation of INMAP stanzas is not defined, therefore it is not avisable to
include same attribute in two stanzas as only one would fire.
1460
SSO derived attributes
1458
nameid Concatenation of affid and idpnid like: "affidid pnid”.
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
8.1.5
OUTMAP specification
OUTMAP specification provides for various attribute renaming and value encoding operations just before passing attributes to the subprocess environment (i.e. what CGI
scripts see). Syntax and available operations are the same as for INMAP.
OUTMAP=src$A$rule$b$ext
8.1.6
AAMAP specification
AAMAP specification is used by IdP Attribute Authority feature to decide whinc attributes from the .at files to include in the assertion. Unlike other MAP directives,
AAMAP can not be placed in regular configuration. Instead it is looked for in .cf file
in following paths (first found will be used):
/var/zxid/idpuid/.all/SP_SHA1_NAME/.cf
/var/zxid/idpuid/.all/.bs/.cf
January 29, 2011
ZXID Book 34, p. 59
CHAPTER 8. ZXID
DIRECTIVES
1473
1474
1475
1476
1477
The first allows per SP tweaking of what attributes are sent. The latter allows global
policy to be set. In absence of either .cf file, the default is
AAMAP=$*$$$;$idpsesid$del$$
which passes all attributes excapt for idpsesid (passing idpsesid would cause privacy loss as it can be used as correlation handle).
January 29, 2011
ZXID Book 34, p. 60
1478
1479
1480
Chapter 9
ZXID XACML PEP (and local
PDP)
Important: You need a functioning XACML PDP (Policy Decision Point
to use this functionality. zxididp includes a PDP that always returns "Permit", unless role is "deny" - you need to acquire and configure a real PDP,
such as commercial (e.g. Axiomatics or Symlabs XACML PDP) or a third
party open source PDP (e.g. PERMIS or Sun).
1481
1482
1483
1484
1485
1486
1487
1488
The attributes gathered by the Attribute Broker phase are available for authorization decisions. The local authorization is applied before, and after, the XACML authorization,
if any.
1489
• Explicit Deny stops processing
1490
• Explicit Allow moves to next phase
1491
• Lack of Allow or Deny at end of phase moves to next phase
1492
• Lack of Allow after all phases is Deny
1493
9.1
1494
The authorization module can authorize access locally based on
1495
• List of approved user names or forbidden user names
1496
• Role attribute having a value or not having a value
1497
• Authorization token (NI 20090904)
1498
Local PDP Authorization Functionality
Local PDP specifications have format as follows
61
9.2. CONFIGURING XACML
CHAPTER
PEP FOR
9. SINGLE
ZXID XACML
SIGN-ON
PEP (AND LOCAL PDP)
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
LOCALPDP_ROLE_PERMIT=role,role
LOCALPDP_ROLE_DENY=role,role
LOCALPDP_IDPNID_PERMIT=idpnid,idpnid
LOCALPDP_IDPNID_DENY=idpnid,idpnid
1516
1517
1518
1519
1520
1521
N.B. It is expected that local PDP will grow in ritchness to address additional common cases, but if you have complex requirements, you should
be using an external PDP.
9.2
Configuring XACML PEP for Single Sign-On
XACML2 PEP (client) functionality allows an external XACML2 PDP (server) to be
queried for the authorization decision, permitting Single Sign-On to happen. The
attributes gathered by the Attribute Broker phase are available for formulating the
XACML request.
Since the XACML PDP may expect attributes names differently from the Common
Namespace, an additional mapping directive, PEPMAP, is provided. It works in a manner
similar to OUTMAP in that it extracts and filters attributes from the common pool. The
source namespace field is used for indicating whether the attribute is
1522
• "subj": Subject Attributes (default: idpnid and role=guest)
1523
• "rsrc": Resource Attributes (default: URL=url of page)
1524
• "act": Action Attributes (default: Action=access)
1525
• "env": Environment Attributes (default: ZXID_PEPvers)
1526
1527
1528
1529
1530
roles
roles
permitted users
denied users
The local PDP authority is consulted at all PEPs, i.e. at SSO, RQOUT1, RQIN2,
RSOUT3, and RSIN4.
1512
1515
of
of
of
of
The lists accumulate over default configuration and repeated instances of the configuration directive. The special value "reset" can be used to reset any of the lists.
1511
1514
Whitelist
Blacklist
Whitelist
Blacklist
If whitelist exists, anyone not listed is denied. If blacklist exists, anyone listed is denied.
If both lists exist, then white is applied first and black then, i.e. blacklist overrides
whitelist.
1510
1513
#
#
#
#
Multiple PEPMAP stanzas can appear as separate PEPMAP declarations, which are cumulative, or they can be put on single PEPMAP separated by semicolon. Within stanzas the
fields are separated by semicolons:
ns$srcattr$rule$dstattr$ext
The fields, such as rule are discussed in detail in description of INMAP, above.
January 29, 2011
ZXID Book 34, p. 62
CHAPTER 9. ZXID
9.3. XACML
CONFIGURING
PEP (AND
XACML
LOCAL
PEPS
PDP)
FOR WEB SERVICE CALLS
Built-in rules of the application
Client App
Built-in rules of the service
Org D PDP
Org C PDP
Alice
Service
Rules of the operator
Rules of the operator
Bob
TN PDP
PEP
Rq Out
PEP
Rs Out
Rules of the TN
1
Master
PDP
4
Master
PDP
Trust PDP
2
3
PEP
Rq In
PEP
Rs In
Alice PDP
Personal rules
Corp C Firewall
or Packet Filter
Bob PDP
Personal rules
Corp D Firewall
or Packet Filter
20100531 Sampo
Figure 9.1: Four PEP Control Points on the Web Service call path.
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
9.3
Configuring XACML PEPs for Web Service Calls
ZXID implements a four points of control PEP model for web service calls. This is
adopted from the TAS3 project.
Each control point extracts the attributes from the common namespace of the pool using
directives similar to PEPMAP as follows:
PEPMAP_RQOUT Request outbound enforement point on Web Service Client (WSC)
side, see (1) in the diagram. Typically this enforcement point can be used to control whether WSC is allowed to talk to the Web Service Provider (WSP). It can
also be used to control whether the data whose submission to WSP is contemplated, is allwed to leave the WSC, and if so, under which obligations or usage
directives. Finally, this control point can be used to formulate pledges about
which obligations the WSC is willing to honour. Again, such pledges are passed
as a usage directive on the wire.
PEPMAP_RQIN Request inbound enforcement point on WSP side, see (2) in the diagram. This is the main PEP that filters the requests "at the gate" before they get
in. When most people think about a PEP, they think about this type of PEP. The
PEPMAP_RQIN can implement tests on requesting identity attributes, target identity (resource owner) attributes, obligations requirements and obligations pledges
conveyed in the usage directives, as well as the actual operation contemplated
and data in the operation.
PEPMAP_RSOUT Response outbound enforcement point on WSP side, see (3) in
the diagram. This PEP is in position to filter outbound data before it is returned
to the WSC. It can also attach obligations to this data, as usage directives.
PEPMAP_RSIN Response inbound enforcement point on WSC side, see (4) in the
diagram. This PEP is mainly useful for checking whether the usage directives
and obligations attached to the data are acceptable. If not, the data can be rejected
at this point.
January 29, 2011
ZXID Book 34, p. 63
9.4. CONFIGURING USAGEDIRECTIVES, INCLUDING OBLIGATIONS
PLEDGES AND REQUESTS
CHAPTER 9. ZXID XACML PEP (AND LOCAL PDP)
1558
1559
1560
1561
1562
1563
1564
1565
1566
9.4
Configuring UsageDirectives, including obligations
pledges and requests
All ID-WSF messages, requests and responses, are able to carry a UsageDirectives
SOAP header, but unfortunately the content and meaning of this header is not well
specified (as of 2010). In essence, the header can carry obligations imposed on the sent
data, or it can carry a pledge to respect obligations if data is returned. While Liberty
ID-WSF UsageDirective has no way of separating between the two cases, we can make
the distinction at the level of the XACML <xa:Oblication> tag’s FullfillOn XML
attribute.
January 29, 2011
ZXID Book 34, p. 64
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
Chapter 10
Full Configuration Option
Reference
This section is generated based on comments in zxidconf.h and is updated periodically. See zxidconf.h for authorative definitions. See also zxid.h for struct
zxid_conf which is the internal runtime structure capturing these options.
Most of the configuration options can be set via configuration file /var/zxid/zxid.conf
or using -O command line flag(s). In config file or on command line you should omit
the ZXID_ prefix and use attribute=value syntax separated by newlines or & characters
(the parser implements CGI query string syntax with extension that also is accepted as
separator).
1579
N.B. The options marked as "(compile)" can not be set on command line or configuration file. They require a recompile.
1580
10.1
1581
10.1.1
Compile time configuration enforcement
1578
1585
Whether configuration is entirely determined at compile time by this file or whether it
is possible to use a config file or provide options on command line using -O flags (such
as via shell script wrapper). When zxid is used as a library, it depends on application
to call zxid_parse_conf(). Generally we recommend you leave these turned on (1).
1586
CONF_FILE (compile) (default: 1)
1587
CONF_FLAG (compile) (default: 1)
1588
MAX_CONF (compile) Maximum size of conf file. (default: 4096)
1582
1583
1584
65
10.1. CONFIGURATION
CHAPTER
OPTIONS
10. FULL CONFIGURATION OPTION REFERENCE
1589
10.1.2
ZXID configuration and working directory path
1593
Where metadata cache and session files are created. Note that the directory is not
hashed: you should use a file system that scales easily to oodles of small files in one
directory. Say ‘make dir’ to create the directory with proper layout. If you change it
here, also edit Makefile.
1594
PATH (default: "/var/zxid/")
1595
10.1.3
1590
1591
1592
SP Nickname for IdP User Interface
1597
The nice name may be used by IdP user interface to refer to the SP. It is usually be
short human readable name or description.
1598
NICE_NAME (default: "ZXID Demo SP")
1599
10.1.4
1596
1600
1601
1602
1603
Web Site URL - root of EntityID
URL for most zxid operations. It must end in whatever triggers the ZXID functionality
in the web server. The hostname and port number should match the server under which
zxid CGI is accessible. N.B. There is no explicit way to configure Entity ID (Provider
ID) for the zxid SP. The Entity ID is always of form ZXID_URL?o=B, for example
1604
https://sp1.zxidsp.org:8443/zxid?o=B
1605
URL (default: "https://sp1.zxidsp.org:8443/zxid")
1606
10.1.5
Override standard EntityID Construction
1612
The best practise is that SP Entity ID is chosen by the SP (and not forced upon SP by
IdP). In ZXID this is done by setting ZXID_URL, see above. However, should you
have to work with an obstinate IdP that refuses to follow this best practise, you can
use this option to manually set the Entity ID. Not following the best practise breaks
automatic metadata exchange (Auto-CoT). Recommended value: leave as 0 so that
Entity ID is formed from ZXID_URL
1613
NON_STANDARD_ENTITYID (default: 0)
1614
10.1.6
1607
1608
1609
1610
1611
1615
1616
1617
1618
1619
1620
Illadviced ACS URL Hack
Sometimes an illadvised authority may impose to you Assertion Consumer Service
URL, this URL happens to be different than ZXID uses, and you do not have political
leverage to change these decisions. In those times you can use this hack to try to map
the imposed URL to the one that works in ZXID. Normally you should register at IdP
to use the ZXID default URLs (easiest way to do this is to use metadata). This only
works in mod_auth_saml.
January 29, 2011
ZXID Book 34, p. 66
CHAPTER 10. FULL CONFIGURATION OPTION
10.1. REFERENCE
CONFIGURATION OPTIONS
1621
REDIRECT_HACK_IMPOSED_URL (default: 0)
1622
REDIRECT_HACK_ZXID_URL (default: 0)
1623
10.1.7
Common Domain Cookie URL
1626
URL for reading Common Domain Cookie. It must end in "zxid". The hostname and
port number should match the server under which zxid CGI is accessible. Specifying
empty CDC_URL disables CDC check in zxid_simple() API.
1627
CDC_URL CDC disabled (default: "")
1628
10.1.8
1629
How to handle CDC designated IdP. See zxid.h for explanation of constants.
1630
CDC_CHOICE (default: ZXID_CDC_CHOICE_UI_PREF)
1631
10.1.9
1624
1625
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
CDC designated IdP Handling
Metadata Fetching Options
Following four boolean configuration options control how (IdP) metadata is obtained.
The metadata can be in a cache (by default directory /var/zxid/cot) or it can be
fetched "on the fly" using the well known location (WKL) method.
ZXID_MD_FETCH controls whether fetching is performed. This necessitates that
ZXID was linked with libcurl. If you do not enable fetching, you will need
to populate the cache manually, perhaps by using a web browser to fetch the
meta data xml files from well known location URLs (or other URLs if you know
better).
ZXID_MD_POPULATE_CACHE controls whether ZXID will write the metadata
to the cache. This requires ZXID_MD_FETCH to be enabled and the file system
permissions of the cache directory (e.g. /var/zxid/cot) to allow writing.
ZXID_MD_CACHE_FIRST controls whether cache will be checked before fetching is attempted. If cache misses, ZXID_MD_FETCH governs whether fetch is
tried.
ZXID_MD_CACHE_LAST If true, metadata is obtained from cache if fetch was
disabled or failed.
1649
If you want to control manually your CoT (e.g. because human process is needed to
verify that all the paperwork is in place), set ZXID_MD_FETCH to 0.
1650
If you want as automatic operation as possible, set all four to 1.
1651
MD_FETCH (default: 1)
1652
MD_POPULATE_CACHE (default: 1)
1653
MD_CACHE_FIRST (default: 1)
1654
MD_CACHE_LAST (default: 1)
1648
January 29, 2011
ZXID Book 34, p. 67
10.1. CONFIGURATION
CHAPTER
OPTIONS
1655
10.1.10
Authentication Request Signing
1656
Whether AuthnReq is signed SP (controls both metadata and actual behavior).
1657
AUTHN_REQ_SIGN (default: 1)
1658
10.1.11
Assertion Signing
1661
Whether SP insists that SSO assertions are signed. Affects metadata. The actual insistence on signing is controlled by ZXID_NOSIG_FATAL, far below. Boolean. Recommended value: 1.
1662
WANT_SSO_A7N_SIGNED (default: 1)
1663
10.1.12
1659
1660
SOAP Message Signing
1665
Whether SOAP messages for ArtifactResolution, SLO, and MNI are signed. Whether
responses are signed as well.
1666
SSO_SOAP_SIGN (default: 1)
1667
SSO_SOAP_RESP_SIGN (default: 1)
1668
10.1.13
1669
Which components should be signed by IdP in SSO Response and Assertion. Bit mask:
1664
1670
1671
1672
0x01
0x02
0x03
IdP Signing Options
Assertion should be signed (default and highly recommended)
The surrounding Response element should be signed
Both Assertion and Response are signed.
1673
SSO_SIGN (default: 0x01)
1674
10.1.14
NameID Encryption
1677
Whether SLO and MNI requests emitted by ZXID will encrypt the NameID (on received requests ZXID accepts either plain or encrypted automatically and without configuration).
1678
NAMEID_ENC (default: 0x0f)
1679
10.1.15
1680
Whether to encrypt assertions when using POST bindings.
1681
POST_A7N_ENC (default: 1)
1675
1676
Assertion Encryption in POST
January 29, 2011
ZXID Book 34, p. 68
10.1. REFERENCE
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
10.1.16
Bit length of identifiers, unguessability
How many random bits to use in an ID. It would be useful if this was such that it produces nice unpadded base64 string, i.e. multiple of 24 bits. Longer IDs reduce chances
of random collision (most code does not check uniqueness of ID) and may increase
security. For security purposes 144 bits is probably good enugh. The unguessability
of ID has security implications, among others, in session IDs. You may want to use
less than 144 bits if your application could benefit from shorter IDs (e.g. you target
browsers with length constrained URLs) and does not need to be secure against attacks
with government level resources. E.g: 24 bits == 3 bytes == 4 base64 chars,
48 bits ==
6 bytes ==
8 base64 chars,
120 bits == 15 bytes == 20 base64 chars,
144 bits == 18 bytes == 24 base64 chars
1694
ID_BITS (compile) (default: 48)
1695
ID_MAX_BITS used for static buffer allocation (compile) (default: 168)
1696
10.1.17
1697
1698
True randomness vs. pseudorandom source
Whether true randomness is obtained. 0=use OpenSSL RAND_pseudo_bytes(), which
usually uses /dev/urandom 1=use OpenSSL RAND_bytes(), which usually uses /dev/random
1702
Although true randomness may be more secure, it is operationally problematic because
if not enough randomness is available, the system will block (stop) until enough randomness arrives. Generally true randomness is not feasible in a server environment
unless you have hardware random number generator.
1703
TRUE_RAND (compile) (default: 0)
1704
10.1.18
1699
1700
1701
Session Archival Directory
1710
If set to a string, indicates a file system directory to which dead sessions are moved
(sessions are files). This directory must be on the same file system as active session
directory, usually /var/zxid/ses, for example /var/zxid/oldses. You may want
to archieve old sessions because they contain the SSO assertions that allowed the users
to log in. This may have legal value for your application, you may even be required by
law to keep this audit trail.
1711
If set to 0, causes old sessions to be unlink(2)’d.
1712
SES_ARCH_DIR 0=Remove dead sessions. (default: 0)
1705
1706
1707
1708
1709
January 29, 2011
ZXID Book 34, p. 69
10.1. CONFIGURATION
CHAPTER
OPTIONS
1713
1714
1715
10.1.19
Session cookies.
For original Netscape cookie spec see: http://curl.haxx.se/rfc/cookie_spec.html
(Oct2007)
1721
If SES_COOKIE_NAME is nonempty string, then zxid_simple() will look for said
cookie and use it as session ID. It will also attempt to set a cookie by that name when
new session is created (but this may rely on some support in the calling app, generally
the need to set a cookie is expressed by presence of setcookie attribute in the LDIF
entry. setcookie specifies what should appear in the Set-Cookie HTTP header of HTTP
response).
1722
SES_COOKIE_NAME (default: "ZXIDSES")
1723
10.1.20
1716
1717
1718
1719
1720
Local user account management.
1727
This is optional unless you require IdP initiated ManageNameID requests to work.
Local user account management may be useful on its own right if your application
does not yet have such system. If it has, you probably want to continue to use the
application’s own system. Local accounts are stored under /var/zxid/user/SHA1
1728
USER_LOCAL (default: 1)
1729
10.1.21
1730
Whether limited IdP functionality is enabled. Affects generated metadata.
1731
IDP_ENA (default: 0)
1732
10.1.22
1724
1725
1726
Mini IdP
IdP Insitence on Signed AuthnReq
1734
Must AuthnReq be signed (controls both IdP metadata and actual behavior, i.e. the
check).
1735
WANT_AUTHN_REQ_SIGNED (default: 1)
1736
MAX_BUF (compile) (default: 1024)
1737
10.1.23
1733
1738
1739
1740
1741
Logging Options
See zxid-log.pd for further explanation. Generally you need error and activity logs
to know yourself what is going on. You need the issue logs to know whether other’s
claims towards you are justified. You need the rely logs to hold others responsible. The
bits of the value are as follows 0x00 Don’t log. 0x01 Log enable 0x06 Signing options
January 29, 2011
ZXID Book 34, p. 70
10.1. REFERENCE
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
0::
2::
4::
6::
no signing (Px)
sha1 MD only (Sx)
RSA-SHA1 (Rx)
DSA-SHA1 (Dx)
0x08 reserved 0x70 Encryption options
0x00::
0x10::
0x20::
0x30::
0x40::
0x50::
0x60::
0x70::
no encryption (xP)
zip-base64 (xZ)
RSA-AES (xA)
RSA-3DES (xT)
Symmetric AES (xB)
Symmetric 3DES (xU)
reserved
reserved
0x80 reserved
N.B. Every encryption and signature has computational cost so be sure to factor this in
when doing benchmarks - or disable log enc and sign when performance is at premium.
Log signing may help you to argue that log evidence was (not) tampered with. The private key for signing must be available in /var/zxid/pem/logsign-nopw-cert.pem
1764
Log encryption may help to keep the logs confidential. For RSA modes the public key
for encryption must be available in /var/zxid/pem/logenc-nopw-cert.pem. For
symmetric encryption the key is the sha1 hash of file /var/zxid/pem/logenc.key
All modes, except for 0, also RFC1951 zip compress the log line and safe-base64
encode the result of the encryption.
1765
LOG_OP_NOLOG (default: 0x00)
1766
LOG_OP_LOG (default: 0x01)
1767
LOG_OP_LOG_SIGN (default: 0x05)
1768
LOG_OP_LOG_ENC (default: 0x21)
1769
LOG_OP_LOG_SIGN_ENC (default: 0x25)
1770
LOG_ERR Log errors to /var/zxid/log/err (default: 0x01)
1771
LOG_ACT Log activity to /var/zxid/log/act (default: 0x01)
1760
1761
1762
1763
1772
1773
1774
1775
1776
1777
LOG_ISSUE_A7N Log each issued assertion to /var/zxid/log/issue/SHA1/a7n/asn
(default: 0x01)
LOG_ISSUE_MSG Log each issued PDU to /var/zxid/log/issue/SHA1/msg/asn
(default: 0x01)
LOG_RELY_A7N Log each received assertion to /var/zxid/log/rely/SHA1/a7n/asn
(default: 0x01)
January 29, 2011
ZXID Book 34, p. 71
10.1. CONFIGURATION
CHAPTER
OPTIONS
1779
LOG_RELY_MSG Log each received PDU to /var/zxid/log/rely/SHA1/a7n/asn
(default: 0x01)
1780
LOG_ERR (default: 0x00)
1781
LOG_ACT (default: 0x25)
1782
LOG_ISSUE_A7N (default: 0x23)
1783
LOG_ISSUE_MSG (default: 0x45)
1784
LOG_RELY_A7N (default: 0x41)
1785
LOG_RELY_MSG (default: 0x11)
1786
10.1.24
1778
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
Choice of log given Error or Action
Each operation has its status code and generally those lines that indicate successful status (or intermediate status like "continue" or "redirect") are considered normal activity.
However, you may want to consider carefully whether signature failure in assertion or
message disqualifies an operation as "activity". One approach is to simply log everything (errors and all) to activity log and rely on some log analysis software to flag the
errors.
LOG_ERR_IN_ACT Log errors to /var/zxid/log/act (in addition to err) (default:
1)
LOG_ACT_IN_ERR Log actions to /var/zxid/log/err (in addition to act) (default: 1)
1798
LOG_SIGFAIL_IS_ERR Log line with signature validation error to /var/zxid/log/err
(default: 1)
1799
10.1.25
1800
0 = Only essential audit relevant events are logged. Note that
1797
1801
Log level for activity log.
there is no way to turn off logging audit relevant events.
1803
1 = Audit and external interactions 2 = Audit, external interactions, and significant
internal events 3 and higher: reserved for future definition and debugging
1804
LOG_LEVEL (default: 2)
1802
January 29, 2011
ZXID Book 34, p. 72
10.1. REFERENCE
1805
10.1.26
Assertion validation options.
1807
These MUST all be turned on (and assertions signed) if you want to rely on assertions
to hold the other party liable.
1808
SIG_FATAL Signature validation error is fatal (prevents SSO) (default: 0)
1809
NOSIG_FATAL Missing signature is fatal (prevents SSO) (default: 1)
1806
1811
MSG_SIG_OK Message layer signature (e.g. SimpleSign) is sufficeint when assertion signature is missing. (default: 1)
1812
AUDIENCE_FATAL Whether AudienceRestriction is checked. (default: 1)
1813
TIMEOUT_FATAL Whether NotBefore and NotOnOrAfter are checked (default: 1)
1810
1814
1815
DUP_A7N_FATAL Whether duplication of AssertionID is considered fatal. (default:
0)
1817
DUP_MSG_FATAL Whether duplication of MessageID or message is considered fatal. (default: 0)
1818
10.1.27
1816
Time Slop
1823
Because clock sychronization amoung the servers in the CoT is unlikely to be perfect,
not to speak of timezone misconfigurations and the dreaded officially introduced time
errors (e.g. daylight "savings" time), you can configure some slop in how the timeout is
evaluated. For production use something like 60 seconds could be a good value. 3600
= 1 hour, 86400 = 1 day.
1824
BEFORE_SLOP Number of seconds before that is acceptable. (default: 86400)
1825
AFTER_SLOP Number of seconds after that is acceptable. (default: 86400)
1826
TIMESKEW Timeskew, in seconds, for timestamps we emit. (default: 0)
1827
A7NTTL Time To Live for IdP issued Assertions (default: 3600)
1828
10.1.28
1819
1820
1821
1822
Redirect to Content
1832
Should explicit redirect to content be used (vs. internal redir). With internal redirect
there is one over-the-wire transaction less, but the URL appears as whatever was sent
by the IdP. With explicit (302) redirect the URL will appear as the true content URL,
without the SAML SSO goo.
1833
REDIR_TO_CONTENT (default: 0)
1834
10.1.29
1835
MAX_SOAP_RETRY Maximum retries due, e.g., EndpointMoved (default: 5)
1829
1830
1831
ID-WSF SOAP Call parameters */
January 29, 2011
ZXID Book 34, p. 73
10.1. CONFIGURATION
CHAPTER
OPTIONS
1836
10.1.30
Session Management Trigger Suffix
1837
In mod_auth_saml the URL ending that triggers session management (e.g. SLO MNI).
1838
10.1.31
Attribute Prefix
1840
In mod_auth_saml the prefix (potentially empty) for attributes brought into environment.
1841
MOD_SAML_ATTR_PREFIX (default: "SAML_")
1839
1843
DEFAULTQS Default Query String used by mod_auth_saml for protected page (default: "")
1844
10.1.32
1842
Anonymous can see protected content
1852
If ANON_OK is set and matches prefix of the local URL, SSO failure does not block
protected content from being shown. While this usually is a security problem, in some
circumstances you may want to show error message or nonpersonalized content from
the application layer. If application checks that the SSO really happened, then there is
no security problem - the responsibility is application’s. Typically ANON_OK=/dir/
is used with IsPassive (fp=1) to implement personalization if user already has session,
but allow the user to access page anonymously without logging in if he does not have
session.
1853
ANON_OK (default: 0)
1854
10.1.33
1845
1846
1847
1848
1849
1850
1851
Required Authentication Context Class Ref.
1860
This can be used to ensure that the IdP has authenticated user sufficiently. In some
cases this can trigger step-up authentication. Value should be dollar separated string of
acceptable authn context class refs, e.g. "" If step-up authentication is triggered, you
need to ensure the fa query string argument of the IdP selection page also requests the
desired authentication contrext class reference. If not specified, then any authentication
context is acceptable.
1861
REQUIRED_AUTHNCTX (default: 0)
1862
10.1.34
1855
1856
1857
1858
1859
IdP: Authentication Context Class Ref for Passwords
1866
What authentication context IdP issues for password authentication. The problem here
is that ZXID does not know whether transport layer is TLS (assumed). If it is not, you
should configure this to be "urn:oasis:names:tc:SAML:2.0:ac:classes:Password" or you
can configure this according to your IdP operational policies.
1867
ISSUE_AUTHNCTX_PW (default: "urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport")
1863
1864
1865
January 29, 2011
ZXID Book 34, p. 74
10.1. REFERENCE
1868
1869
1870
1871
10.1.35
IdP preference for ACS
If SP does not manifest preference regarding the binding for Assertion Consumer Service, then this IdP preference is used, unless SP metadata indicates it can not support
this binding, in which case the first ACS from metadata is used.
1873
IDP_PREF_ACS_BINDING (default: "urn:oasis:names:tc:SAML:2.0:bindings:HTTPPOST")
1874
10.1.36
1872
Simple API HTML customization.
1876
These allow simple branding and customization. If these options are not enough for
you, consider simply rendering your own forms.
1877
10.1.37
1878
Edit this to change the colors.
1875
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
Body tag for the ZXID generated pages.
BODY_TAG (compile) (default: "<body bgcolor=#̈330033ẗext=#̈ffaaffl̈ink=#̈ffddffv̈link=#̈aa44aaälink=#̈ffffff
face=sans>")
IDP_SEL_START (default: "<title>ZXID SP SSO: Choose IdP</title>" ZXID_BODY_TAG
"<h1>ZXID SP Federated SSO (user NOT logged in, no session)</h1>")
IDP_SEL_NEW_IDP (default: "<h3>Login Using New IdP</h3><i>A new IdP is
one whose metadata we do not have yet. We need to know the IdP URL (aka
Entity ID) in order to fetch the metadata using the well known location method.
You will need to ask the adminstrator of the IdP to tell you what the EntityID
is.</i><p>IdP URL <input name=e size=80><input type=submit name=l1
value=L̈ogin (A2) ¨
><input type=submit name=l2 value=L̈ogin (P2) ¨
><br>")
IDP_SEL_OUR_EID (default: "Entity ID of this SP (click on the link to fetch the SP
metadata): ")
IDP_SEL_TECH_USER (default: "<h3>Technical options</h3><input type=checkbox
name=fc value=1 checked> Create federation, NID Format: <select name=fn><option
value=prstnt>Persistent<option value=trnsnt>Transient<option value=¨¨>(none)</select><br>")
1898
IDP_SEL_TECH_SITE (default: "<input type=hidden name=fq value=¨¨><input
type=hidden name=fy value=¨¨><input type=hidden name=fa value=¨¨><input
type=hidden name=fm value=¨¨><input type=hidden name=fp value=0><input
type=hidden name=ff value=0><!– ZXID built-in defaults, see IDP_SEL_TECH_SITE
in zxidconf.h –>")
1899
IDP_SEL_FOOTER (default: "<hr><a href=ḧttp://zxid.org/¨
>zxid.org</a>, ")
1900
IDP_SEL_END (default: "<!– EOF –>")
1894
1895
1896
1897
January 29, 2011
ZXID Book 34, p. 75
10.1. CONFIGURATION
CHAPTER
OPTIONS
1901
10.1.38
IdP Selector Page URL
1904
If the above simple customization options are not sufficient, you can provide URL to
page of your own design. This page will receive as query string argument the relay
state. 0 (zero) disables.
1905
IDP_SEL_PAGE (default: 0)
1902
1903
1906
1907
1908
1909
1910
1911
1912
1913
1914
AN_START (default: "<title>ZXID IdP: Authentication</title>" ZXID_BODY_TAG
"<h1>ZXID IdP Authentication for Federated SSO (user NOT logged in, no
session)</h1><h3>Please authenticate yourself using one of following methods:</h3>")
AN_OUR_EID (default: "Entity ID of this IdP (click on the link to fetch the IdP
metadata): ")
AN_TECH_USER (default: "<h3>Technical options</h3><input type=checkbox
name=fc value=1 checked> Create federation, NID Format: <select name=fn><option
value=prstnt>Persistent<option value=trnsnt>Transient<option value=¨¨>(none)</select><br
1919
AN_TECH_SITE (default: "<input type=hidden name=fq value=¨¨><input type=hidden
name=fy value=¨¨><input type=hidden name=fa value=¨¨><input type=hidden
name=fm value=¨¨><input type=hidden name=fp value=0><input type=hidden
name=ff value=0><!– ZXID built-in defaults, see IDP_SEL_TECH_SITE in
zxidconf.h –>")
1920
AN_FOOTER (default: "<hr><a href=ḧttp://zxid.org/¨
>zxid.org</a>, ")
1921
AN_END (default: "<!– EOF –>")
1922
10.1.39
1915
1916
1917
1918
Authentication Page URL
1924
If the above simple customization options are not sufficient, you can provide URL to
page of your own design. 0 (zero) disables.
1925
AN_PAGE (default: 0)
1923
1926
1927
1928
1929
1930
MGMT_START (default: "<title>ZXID SP Mgmt</title>" ZXID_BODY_TAG
"<h1>ZXID SP Management (user logged in, session active)</h1>")
MGMT_LOGOUT (default: "<input type=submit name=gl value=L̈ocal Logout
¨
><input type=submit name=gr value=S̈ingle Logout (R) ¨
><input type=submit
name=gs value=S̈ingle Logout (S) ¨
>")
1932
MGMT_DEFED (default: "<input type=submit name=gt value=D̈efederate (R)
¨
><input type=submit name=gu value=D̈efederate (S) ¨
>")
1933
MGMT_FOOTER (default: "<hr><a href=ḧttp://zxid.org/¨
>zxid.org</a>, ")
1934
MGMT_END (default: "<!– EOF –>")
1931
January 29, 2011
ZXID Book 34, p. 76
1935
1936
1937
1938
Chapter 11
Circle-of-Trust: Create a
Federation with Other Partners
TBD - This chapter to be written
77
CHAPTER 11. CIRCLE-OF-TRUST: CREATE A FEDERATION WITH OTHER
PARTNERS
January 29, 2011
ZXID Book 34, p. 78
1939
1940
1941
1942
Chapter 12
Certificates and PKI Trust
*** TBD - This chapter should be elaborated to be a certificate tutorial with following
contents:
1943
• Intro to certs and private keys
1944
• Generating self signed cert
1946
• Generating certificate signing request and using it to obtain commercially issued
cert
1947
• Installing root certs so you can recognize other people’s certs
1948
• Client TLS considerations
1945
1949
1950
1951
1952
1953
1954
1955
For the time being, the short answer is that ZXID uses OpenSSL and PEM format
certificates. You can use same techniques as you would use for Apache / mod_ssl for
acquiring certificates.
You should NEVER password protect your private key. There will not be any opportunity to supply the password. You should instead protect your private key using Unix
filesystem permissions. See OpenSSL.org or modssl.org FAQs for further information, including how to remove a password if you accidentally enabled it.
79
CHAPTER 12. CERTIFICATES AND PKI TRUST
January 29, 2011
ZXID Book 34, p. 80
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
Chapter 13
ZXID Logging and Audit Trail
N.B. zxidconf.h contains a wealth of logging related config options, see ZXID Configuration Reference
Tip: Your web server also has logging options. You may want to correlate
the web server logs with zxid audit logs.
In serious use of SSO it is fundamental that the relying party, the SP, WSC, or WSP,
archives the digitally signed evidence that justifies its actions. Generally this means that
at least the SSO or credential assertions have to be archived. Quite often, especially in
the WSC world, the entire SOAP response (which may be partially signed) needs to be
preserved as a proof of an authorized action or attested attributes.
To lesser extent, it is also important that the issuing party, the IdP (or sometimes the
DS, PS, WSC, or WSP), keeps records so that it can confirm or refute the claims of
the relying party – in the minimum it should be able to refute any obviously false
claim and it should be able to detect breaches of its own security arrangements, e.g.
situations where somebody is signing messages in its name although internal audit
trail demonstrates this to be impossible. The IdP audit trail consists of preserving
any (signed) request made by anyone as well as preserving every (signed) response it
makes.
1980
Generally every assertion, request, and response will have its unique ID that can be
used as the primary key, or filename, for storing it in a database. Unfortunately these
namespaces1 are not disjoint (it is not very well specified in any of the standards how
they interact or how wide their uniqueness properties are).2 The only safe assumption
is the pessimistic one: each type of object observes a unique namespace only towards
its issuer and type and hence we need to map such namespaces to subdirectories.
1981
13.1
1982
Please consider following layout of the log directory:
1975
1976
1977
1978
1979
Filesystem Layout for Logs
1 Namespace,
as used here, has nothing to do with XML namespaces.
rational implementations use 128 bit random identifiers, which statistically guarantees that there
will not be collisions, but unfortunately we can not rely on other parties to adopt this behaviour.
2 Many
81
13.2. ZXID LOG FORMAT CHAPTER 13. ZXID LOGGING AND AUDIT TRAIL
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
/var/zxid/
|
+-- zxid.conf Main configuration file
+-- pem/
Our certificates
+-- cot/
+-- ses/
Sessions (see refinement in Sesstion Storage section)
‘-- log/
|
+-- issue/
|
|
|
+-- SHA1NAME/
Evidence issued to entity is kept in directory named after
|
|
|
|
|
+-- a7n/
Assertions issued to the given 3rd party, named by Assertio
|
|
+-- msg/
Messages of any type issued to the given 3rd party, named b
|
|
‘-- wir/
Wire messages, such as redirects, and posts (e.g. POST Simp
|
...
|
‘-- SHA1NAME2/ Evidence issued to another entity ID
|
+-- rely/
|
|
|
+-- SHA1NAME/
Evidence from entity is kept in directory named after entit
|
|
|
|
|
+-- a7n/
Assertions from 3rd parties, named by AssertionID
|
|
+-- msg/
Messages of any type from 3rd parties, named by MessageID o
|
|
‘-- wir/
Wire messages, such as redirects, and posts (e.g. POST Simp
|
...
|
‘-- SHA1NAME2/ Evidence from another entity ID
|
+-- tmp/
Subdirectory used for atomic operations à la Maildir
+-- act
Global activity log
+-- err
Global error log
‘-- debug
Global debugging log
13.2
ZXID Log Format
2020
The log file is line oriented, one record per line irrespective of line length, and plain
text: binary data is generally omitted or represented as (safe) base64. Fields are separated by exactly one space character (0x20), except for the last free format field.
Records are separated by exactly one new line (0x0a) character (never by CRLF sequence).
2021
The log file format supports
2022
1. Plain text logging
2023
2. Signed plain text logging using either RSA-SHA1 or DSA-SHA1
2024
3. Symmetrically encrypted logging using either 3DES or AES
2025
4. Asymmetrically encrypted logging using RSA (or DSA?)
2016
2017
2018
2019
January 29, 2011
ZXID Book 34, p. 82
CHAPTER 13. ZXID LOGGING AND AUDIT TRAIL 13.2. ZXID LOG FORMAT
2026
5. Signed and symmetrically encrypted logging
2027
6. Signed and Asymmetrically encrypted logging
2028
All activity and error log file lines have the following format (any one of the 3):
2029
2030
2031
2032
2033
2034
# comment
SE HH CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC
SE HH SIG OURTS SRCTS IP:PORT SUCCEID MID A7NID NID MM VVV RES OP PPP FMT
where
SE Log signing and encryption designator. In all cases the actual signing or encryption
key is not identified on the log line. This will need to be determined out-of-band.
2035
PP PlainPlain: not signed and not encrypted
2036
Rx RSA-SHA1 signed (x = any encryption)
2037
Dx DSA-SHA1 signed
2038
Sx SHA1 check-summed, but not signed (SSSS is the checksum)
2039
xA Asymmetrically AES encrypted (x = any signing method)
2040
xT Asymmetrically 3DES encrypted
2041
xB Symmetrically AES encrypted (theoretical: how to safeguard the key?)
2042
xU Symmetrically 3DES encrypted (theoretical: how to safeguard the key?)
2043
xZ [?] zipped (not really encryption)
2044
Xxx Experimental arrangements.
2045
2046
HH HMAC chaining code to previous message, to protect against log line deletion. If
not used, this will be "-".
2049
CCCC Safe base64 encoded log encryption blob. In case of encryption blob, the rest
of the log fields will not appear. Decrypted logline will contain fields starting
from SSSS.
2050
SIG Safe base64 encoded log line signature blob. If no signature, this is a dash ("-").
2047
2048
2051
2052
2053
2054
2055
OURTS Our time stamp, format YYYYMMDD-HHMMSS.TTT where TTT are the milliseconds. The time is always in GMT (UTC, Zulutime).
SRCTS Source time stamp, format YYYYMMDD-HHMMSS.TTT. If TTT was not originally
specified it is represented as "501". The time is always in GMT (UTC, Zulutime).
2057
IP:PORT The IP address and the port number of the other end point (usually client,
but could be spoofed, caveat emptor).
2058
SUCCEID The SHA1 name of the entity (succinct entity ID without the equals sign).
2056
2059
2060
2061
MID Message ID relating to the log line. Allows message to be fetched from the
database or the file system. Any relates-to or similar ID is only available by
fetching the original message. Dash ("-") if none.
January 29, 2011
ZXID Book 34, p. 83
13.2. ZXID LOG FORMAT CHAPTER 13. ZXID LOGGING AND AUDIT TRAIL
2062
2063
2064
2065
2066
2067
2068
A7NID Assertion ID relating to the log line. Allows assertion to be fetched from the
database or the file system. If message benefits from multiple assertions, this
is the one relating to the outermost one. Other A7NIDs are only available by
fetching the original assertion. Dash ("-") if none. If the assertion is encrypted
and can not be decrypted, then placehoder "-enca7n-" is used.
NID IdP assigned NameID relating to the message, if any. If the NameID is encrypted
and can not be decrypted, then placeholder "-encnid-" is used.
2070
MM Module or subsystem indicator (e.g. discriminate between SP and IdP that log to
same file)
2071
VVV Signature validation codes
2069
2072
U Signature issued ("Underwritten" - getit?).
2073
O Capital Oh (not zero). All relevant signatures validate (generally assertion)
2074
A Unsupported or bad signature or message digest algorithm
2075
G Checksum of XML DSIG does not validate
2076
R The RSA layer of the signature does not validate
2077
N No signature detected (or issued) or expected or not applicable.
2078
M Malformed signature, e.g. SignedInfo or Reference missing
2079
I Issuer metadata not found (or not in CoT, or corrupt metadata).
2080
V Assertion validity error (e.g. not in time range or wrong audience)
2081
F Operation failed or faulted by error code (low level protocol ok)
2082
Exx Extended signature validation code (generally error or failure)
2083
Xxx Experimental signature validation code (generally failure)
2084
RES Result of the operation.
2085
K Operation was success
2086
C Operation failed because client did not provide valid input
2087
S Operation failed due to server side error
2088
P Operation failed due to policy or permissions issue
2089
T Temporary error, client was encouraged to retry
2090
B Metadata related error (no metadata or parse error in metadata)
2091
D Redirect or recredential. Client was encouraged to retry.
2092
W Way point message. Neither success nor failure.
2093
Exx Extended result (generally error or failure)
2094
Xxx Experimental result (generally failure)
2095
OP The documented operation
2096
FEDNEW New federation was created (usually due to SSO or discovery).
2097
FEDSSO SP SSO using federated ID was performed
2098
TMPSSO SP SSO using transient NameID was performed
January 29, 2011
ZXID Book 34, p. 84
CHAPTER 13. ZXID LOGGING AND AUDIT TRAIL 13.2. ZXID LOG FORMAT
2099
IFSSO IdP SSO using federated ID was issued
2100
ITSSO IdP SSO using transient NameID was issued
2101
NEWSES SP new session
2102
INEWSES IdP new session
2103
PNEWSES WSP new session
2104
SLO Single Logout was completed (SP)
2105
ISLO Single Logout completed (IdP)
2106
DEFED Defederation was performed
2107
BADCF Server configuration (/var/zxid/zxid.conf) is bad
2108
NOMD No metadata found after options exhausted (cache, fetch from net)
2109
BADMD Metadata parsing error
2110
BADXML XML parsing error in protocol
2111
SAMLFAIL SAML call failed (often SOAP call)
2112
EMISS Missing element (in otherwise correct XML)
2113
EFILE File missing, wrong permissions, corrupt content. Install errors.
2114
ECRYPT Crypto or signature error, usually due to corrupt or wrong key.
2115
EDUP Duplicate message. Suspect replay attack.
2116
ERR Other error
2117
For WSP the OP is the command verb that was exercised.
2118
FEDDI Discovery: Issue of EPR with assertion using federated NameID
2119
TMPDI Discovery: Issue of EPR with assertion using transient NameID
2120
DIOK Summary status of successful discovery on server side
2121
VALID Message was validated OK and accepted for processing. See zxid_wsp_validate()
2122
DECOR Message was decorated and issued, see zxid_wsp_decorate()
2123
CGIRESP Notification of issued message written in local audit trail
2124
For WSC the OP is the command verb preceded by capital C, e.g. "CQuery".
2126
Additional OP verbs may need to be specified for protocol substeps like artifact
resolution (ART) and direct authentication (AUTH).
2127
ART Artifact resolution request sent with SOAP (1)
2128
ANREDIR Redirection with Authentication Request
2129
LOCLO Local Logout (1)
2130
SLOREDIR Redirection with Single Logout Request
2131
SLORESREDIR Redirection with Single Logout Response
2132
MNIREDIR Redirection with Manage NameID Request for changing NameID
2133
DEFEDREDIR Redirection with Manage NameID Request for defederation
2134
SLOSOAP Single Logout Request SOAP call made
2135
MNISOAP Manage NameID Request for changing NameID SOAP call
2125
January 29, 2011
ZXID Book 34, p. 85
13.3. LOG SIGNING AND ENCRYPTION
CHAPTER 13. ZXID LOGGING AND AUDIT TRAIL
2136
DEFEDSOAP Manage NameID Request for defederation SOAP call
2137
SAMLOK SAML call OK (often SOAP call)
2139
Additional OP verbs may need to be specified for other logging operations like
regular web access logs (HEAD, GET, POST).
2140
IDPSEL IdP Selection screen is shown (2)
2141
MGMT Management screen is shown (2)
2138
2143
SHOWPC Logged in (by SSO or session). Show protected content. arg is sid.
(1)
2144
SPDISP SP Command Dispatch (received POST or redir) (2)
2145
IDPDISP IdP Command Dispatch (received POST or redir) (2)
2146
MYMD My metadata was served to requester on the net (1)
2147
GETMD Getting metadata from net (2)
2148
GOTMD Got metadata from net (1)
2149
BADCGI Unknown CGI options (0, but not implemented yet)
2150
REDIRDEC Redirect or POST Bindong decoding
2151
ANREDIR Authentication redirect
2152
AUTHN Authentication
2153
SSOA7N Issuance of SSO Assertion
2154
SSORESP Issuance of SSO response
2155
DIA7N Issuance of Discovery Assertion
2156
DIRESP Issuance of Discovery response
2157
KEYGEN Auto-Cert generation of a self-signed certificate
2158
NEWUSR New user creation
2142
2159
PPP Operation dependent one most relevant parameter. Dash ("-") if none.
2160
FMT Operation dependent free-form data. May contain spaces. Dash ("-") if none.
2161
13.3
2162
2163
2164
2165
Log Signing and Encryption
Logs are enabled in the config file zxidconf.h (compile time) by ZXLOG macros
which provide default values for the log flags in struct zxid_conf. Each log flag is
a bitmask of signing and encryption options. Zero value means no logging. "1" can be
used to enable plain text logging.
2167
Log signing may help you to argue that log evidence was (not) tampered with. You can
configure the signing level in the config file zxidconf.h (compile time):
2168
0 no signing (Px)
2169
2 sha1 MD only (Sx)
2166
January 29, 2011
ZXID Book 34, p. 86
CHAPTER 13. ZXID LOGGING AND AUDIT
13.3. LOG
TRAIL
SIGNING AND ENCRYPTION
2170
4 RSA-SHA1 (Rx)
2171
6 DSA-SHA1 (Dx)
2172
2173
2174
2175
2176
2177
For actual signing (options 2 and 3), the private key for signing must be available in
/var/zxid/pem/logsign-nopw-cert.pem. Note that this file need not contain the
actual certificate (but it may, it just will not be used).
The weak point of log signing is that if the private key is stolen, then someone can
create falsified logs and the private key needs to be available on the point where the
logs are generated - thus it is actually quite vulnerable.
2179
Log encryption may help to keep the logs confidential. You can configure the configuration level in the config file zxidconf.h (compile time):
2180
0x00 no encryption (xP)
2181
0x10 [?] zip - safe-base64 [?] (xZ)
2182
0x20 RSA-AES (xA)
2183
0x30 RSA-3DES (xT)
2184
0x40 Symmetric AES (xB)
2185
0x50 Symmetric 3DES (xU)
2178
2186
2187
2188
2189
2190
2191
2192
For RSA modes the public key for encryption must be available in /var/zxid/pem/logenc-nopw-cert.pem.
Note that the private key should NOT be kept in this file: the whole point of public key
encryption is that even if your server machine is stolen, the bad guys can’t access the
logs - if the private key was anywhere in the stolen machine, they will find it.
For symmetric encryption the key is the SHA1 hash of file /var/zxid/pem/logenc.key.
Obviously this key must be kept secret, but see the caveat about stolen machine in the
previous paragraph.
2195
All encryption modes, except for 0, [?] zip compress the log line before encryption and
safe-base64 encode the result of the encryption. All encryption modes, except 0 and 1,
prefix the zipped log line with 128 bit nonce before encrypting.
2196
The algorithm is roughly
2197
1. If encrypt, zip the raw log line
2198
2. If sign, compute the signature (over zipped version if applicable)
2193
2194
2200
3. Prepend signature blob to log line. If encrypting, the signature is embedded in
binary form, otherwise it is embedded in safe-base64 form.
2201
4. If encrypt, perform the encryption.
2202
5. If encrypt, apply safe-base64.
2199
2203
2204
The supplied tool zxlogview(1) allows the logs to be decrypted and the signatures verified.
January 29, 2011
ZXID Book 34, p. 87
13.4. INTERNAL CRYPTO CHAPTER
FORMATS 13. ZXID LOGGING AND AUDIT TRAIL
2205
2206
2207
2208
2209
2210
2211
2212
2213
2214
./zxlogview logsign-nopw-cert.pem logenc-nopw-cert.pem <some-log-lines
Note that for zxlogview(1) to work the logsign-nopw-cert.pem needs to contain the
public key (and need not contain the privatekey) which is the opposite of the situation
what zxid(1) needs to see in order to sign. Similarly logenc-nopw-cert.pem needs to
contain the private key (and may contain the certificate, though this will not be used).
N.B. While encrypted logs are cool, you should evaluate the gain against
the incovenience: if you encrypt them, the lesser mortal sysadmins may
not be able to debug your installation because they do not know how to
decrypt logs or you are not willing to trust them with the keys. For this
reason, you can configure the encryption of error log separately.
2215
13.4
2216
For [?] zipped safe-base64 [?] output the input to base64 encoding is
2217
2218
2219
2220
2221
2222
2223
2224
2225
2226
2227
2228
Internal Crypto Formats
LLSSSSZZZZZZZZZZZZZZ
-- RFC1951 zipped safe-base64
For encrypted modes the input to AES (or other symmetric cipher) is
NNNNLLSSSSZZZZZZZZZZ
-- Note how nonce is prepended
The NNNN is used as initialization vector and actual encryption encompasses LL,
SSSS, and ZZZZ.
In RSA-AES the session key is encrypted using RSA and prepended to the input for
base64 encoding.
KKEEEECCCCCCCCCCCCCC
-- RSA-AES: note prepended session key
NNNN 16 bytes of nonce. This is used as initialization vector
for AES or 3DES cipher operated in CBC mode.
LL Bigendian integer representing signature length in bytes.
0 means none. Negative values reserved for future use.
2229
SSSS The signature in binary
2230
ZZZZ [?] zipped safe-base64 [?] of the payload
2231
KK Bigendian integer representing encrypted session key
2232
length in bytes. Negative values are reserved for future use.
2233
EEEE RSA encrypted session key in binary
2234
CCCC Ciphertext from the symmetric cipher, including nonce.
2235
In RSA operations RSA_PKCS1_OAEP_PADDING padding is used (PKCS #1 v2.0).
January 29, 2011
ZXID Book 34, p. 88
CHAPTER 13. ZXID LOGGING AND AUDIT TRAIL
13.5. LOGGING ASSERTIONS
2236
13.5
Logging Assertions
2241
Logging of assertions is controlled by configuration options ZXLOG_ISSUE_A7N and
ZXLOG_RELY_A7N. At least ZXLOG_RELY_A7N should be turned on for ID-WSF
web services to work correctly. Logging relied assertions also allows detection of duplicate assertion IDs. Logging, or not, of issued assertions does not have any operational effect and is only for audit trail purposes.
2242
Assertions are logged in directories depending on issuer’s sha1 name.
2237
2238
2239
2240
2243
/var/zxid/log/rely/ISSUER-SHA1-NAME/a7n/A7N-ID-AS-SHA1
2245
Sha1 names are used to avoid any attack through issuer entity ID or the assertion ID
being evilly crafted to contain shell metacharacters or filesystem significant characters.
2246
Assertions issued by ourselves follow similar pattern
2244
2247
2248
2249
/var/zxid/log/issue/DEST-SHA1-NAME/a7n/A7N-ID-AS-SHA1
If the logfile starts by less-than character ("<") then it is in plain text. Encrypted or
signed formats will start in another way, but are not specified at this time.
2253
N.B. The relied-on assertions may be referenced from session objects and used in construction of credentials for ID-WSF based web services calls. Therefore the rely directory should not be cleaned too aggressively: the assertions must remain there until the
referencing session expires.
2254
13.6
2250
2251
2252
Logging Requests and Responses
2258
Logging of requests and responses is controlled by ZXLOG_ISSUE_MSG and ZXLOG_RELY_MSG.
Logging, or not, messages has no operational effect and is only for audit trail purposes.
If logging of relied messages is turned on, then it is possible to detect duplicate message
IDs.
2259
Request messages are logged in directories depending on issuer’s sha1 name.
2255
2256
2257
2260
/var/zxid/log/rely/ISSUER-SHA1-NAME/msg/REQ-ID-AS-SHA1
2262
Sha1 names are used to avoid any attack through issuer entity ID or the assertion ID
being evilly crafted to contain shell metacharacters or filesystem significant characters.
2263
Responses issued by ourselves follow similar pattern
2261
2264
2265
2266
/var/zxid/log/issue/DEST-SHA1-NAME/msg/RESP-ID-AS-SHA1
If the logfile starts by less-than character ("<") then it is in plain text. Encrypted or
signed formats will start in another way, but are not specified at this time.
January 29, 2011
ZXID Book 34, p. 89
13.7. SESSION STORAGE AND
CHAPTER
BOOTSTRAPS
13. ZXID LOGGING AND AUDIT TRAIL
2267
13.7
2268
The ZXID session system serves three purposes:
2269
2270
Session Storage and Bootstraps
1. Remember whether user has logged in. The session ID is carried either in a cookie
or as part of the URL.
2272
2. Make it possible to perform Single Logout (SLO) and certain federation management tasks.
2273
3. Remember the service end points (EPRs) that were either
2271
2274
a. supplied as bootstrap attributes in the SSO assertion, or
2275
b. later discovered
2276
2277
2278
2279
2280
2281
2282
2283
2284
2285
2286
2287
2288
2289
2290
2291
2292
2293
2294
2295
2296
2297
2298
2299
2300
2301
2302
2303
2304
2305
2306
2307
2308
The biggest complication is the requirement to remember the EPRs and the solution
currently used is to keep them as files in a per session directory under the /var/zxid/ses
tree.
/var/zxid/
|
+-- zxid.conf Main configuration file
+-- pem/
Our certificates
+-- cot/
+-- ses/
Sessions
|
|
|
+-- SESID/
Each session has its own directory
|
|
|
+-- .ses
The session file
|
‘-- SVC,SHA1 Each bootstrap is kept in its own file
|
+-- user/
Local user accounts (if enabled)
|
|
|
+-- SHA1/ Each local user has a directory whose name is SHA1
|
|
|
of the user’s NameID (idpnid) and IdP Entity ID
|
|
+-- .mni
Information needed by Name ID management
|
|
+-- PS,SHA1 Long term People Service EPR, kept in its own file
|
|
+-- .deleg/ Delegations (invitations) user has issued
|
|
|
|
|
|
|
+-- DELEG
|
|
|
‘-- DELEG
|
|
|
|
|
+-- .access/ Invitations user has received (delegations to access other’s r
|
|
|
|
|
|
|
+-- ACCESS
|
|
|
‘-- ACCESS
|
|
|
|
|
+-- .bs/
Local user attribute directory
|
|
|
|
January 29, 2011
ZXID Book 34, p. 90
CHAPTER 13. ZXID LOGGING AND
13.7. AUDIT
SESSION
TRAIL
STORAGE AND BOOTSTRAPS
2309
2310
2311
2312
2313
2314
2315
2316
2317
2318
2319
2320
2321
2322
2323
2324
2325
|
|
|
‘-- .at Local user attributes as LDIF (see zxid_ses_to_pool())
|
|
|
|
|
‘-- .pw
User’s local password if any (usually none)
|
|
|
‘-- SHA1b -> ../uid/Sue
SHA1 can also be symlink to local account
|
+-- uid/
Local user ID (local login name) to SHA1 mapping
|
|
|
+-- joe -> ../user/SHA1
Symlink points to the real user directory
|
+-- Sue/
Local user can have directory whose name is the uid
|
|
|
+-- .mni
Information needed by Name ID management
|
‘-- .pw
User’s local password if any (usually none)
|
|
‘-- log/
13.7.1
Session directory
2328
The session ID is an unguessable (but see ID_BITS configuration options) safe base64
encoded pseudorandom number. Unguessability ensures that the session can only be
crated via SSO.
2329
The service EPRs are XML documents whose name is composed from two components
2326
2327
2330
2331
2332
2333
2334
2335
2336
2337
2338
2339
2340
SVC,SHA1
SVC The service type URI, with file system unsafe characters (e.g. "/" and ",") folded
to underscore ("_"). Purpose of the SVC is to allow quick identification, without
opening, of the files that contain EPRs for a given service type. Only first 200
bytes of the service type are used.
SHA1 safe base64 encoded SHA1 hash of the content of the EPR. The purpose of the
SHA1 hash is to produce a unique identifier so that two distinct EPRs for same
service will have different file names.
The session directory also contains .ses file. The first line is as follows (still subject
to change, Oct 2007):
NameID|a7n-ref
2342
The pipey symbol (|) is a field separator. Future versions may define further fields
beyound these original two. All other lines are reserved for future expansion. Fields:
2343
NameID NameID, extracted during SSO
2344
a7n-ref Filesystem path to the SSO assertion.
2341
January 29, 2011
ZXID Book 34, p. 91
CHAPTER
BOOTSTRAPS
2345
2346
2347
2348
2349
2350
2351
2352
2353
2354
2355
2356
2357
13.7.2
User directory (user/)
User directories are used for storage of local account information. Since many web applications, to which ZXID may be integrated, already have their own local user storage,
the ZXID user directory is optional, see USER_LOCAL configuration option.
IdP initiated ManageNameID requests depend on local user accounts, so if you want
this to work you need to enable them. Local user account management may be useful
on its own right if your application does not yet have such system. If it has, you
probably want to continue to use the application’s own system.
Another functionality that needs the local user accounts is delegation using people service. In this case the invitations / delegations and PS-EPR of the user are remembered.
Each user is represented by a directory whose filename is safe base64 of the SHA1 hash
of the user’s NameID and the IdP’s Entity ID. The directory can actually be a symlink
to some other place, such as uid/ directory, see below.
2360
Inside the directory, a file called .mni captures the information needed for NameID
Management. It is expected that other files about the user may be populated to capture
other aspects. Your own applications could even create files here.
2361
The first line of the .mni file is as follows
2362
FMT|IDPEnt|SPqual|NameID|MNIptr
2358
2359
2364
The pipey symbol (|) is a field separator. Future versions may define further fields
beyound these original two. All other lines are reserved for future expansion. Fields:
2365
FMT NameID Format
2363
2366
2367
IDPent IdP entity ID that qualifies the NameID (namespace if you like). This usually
corresponds to the NameQualifier of <NameID>
2369
SPqual SP entity or affilitation ID (optionally) sent by IdP. This further qualifies the
namespace of the Name ID.
2370
NameID NameID of the account
2368
2373
MNIptr If NameID Management has been used to change the IdP assigned NameID,
then the new NameID. There will be a local user account directory for the new
NameID. Consider this as a sort of symlink functionality.
2374
13.7.3
2371
2372
2375
2376
2377
2378
2379
2380
Local UID Directory (uid/)
The main purpose of the local uid/ directory is to support local logins. Since the main
objective of ZXID is to support Single Sign On, there should be little need to support
local logins. Hence uid/ directory is optional.
Often uid/ directory is implemented by providing symlinks to the user/ directory. In
this case uid/ only acts as an index or mapping from local UID to the safe base64
encoded SHA1 of the IdP assigned Name ID, see above.
January 29, 2011
ZXID Book 34, p. 92
CHAPTER 13. ZXID LOGGING AND
13.7. AUDIT
SESSION
TRAIL
STORAGE AND BOOTSTRAPS
2381
2382
2383
2384
2385
2386
2387
2388
2389
2390
2391
2392
2393
2394
2395
2396
2397
2398
2399
2400
2401
2402
2403
2404
2405
2406
2407
2408
2409
2410
2411
2412
2413
2414
2415
2416
2417
2418
2419
2420
2421
2422
2423
2424
2425
2426
2427
13.7.4
IdP Use of Local UID Directory (uid/)
zxididp uses local uid/ directory to implement the IdP logins and to store users federations, bootstraps, and attributes.
/var/zxid/
|
+-- idpzxid.conf Main configuration file
+-- idppem/
Our certificates
+-- idpcot/
+-- idpses/
Sessions
|
|
|
+-- SESID/
Each session has its own directory
|
|
|
+-- .ses
The session file
|
‘-- SVC,SHA1 Each bootstrap is kept in its own file
|
+-- idpuid/
Local user ID (local login name) to SHA1 mapping
|
|
|
+-- JOE/ Local user has directory whose name is the login uid
|
|
|
|
|
+-- .log
Log of operations regarding the user
|
|
+-- .pw
User’s local password
|
|
+-- .yk
User’s yubikey shared aes128 secret in hex
|
|
+-- .ykspent/ Cache of already used One TIme Passwords
|
|
|
|
|
|
|
‘-- OTP File name is the spent Yubikey ticket (w/o uid)
|
|
|
|
|
+-- .bs/
Directory of bootstraps to be included
|
|
|
|
|
|
|
+-- .at
Attributes to be included in each SSO
|
|
|
‘-- SVC,SHA1
Bootstrap for a service
|
|
|
|
|
‘-- SP,SHA1/ One directory for each SP user is federated with
|
|
|
|
|
+-- .mni
Federated name id to be used with this SP
|
|
+-- .at
Attributes to be included for this SP
|
|
‘-- SVC,SHA1
Bootstrap to be included for this SP
|
|
|
‘-- .all/ Template used for all users
|
|
|
+-- .bs/
Directory of default bootstraps to be included
|
|
|
|
|
+-- .at
Attributes to be included in each SSO
|
|
‘-- SVC,SHA1
Bootstrap for a service
|
|
|
‘-- SP,SHA1/ One directory for each SP
|
|
|
+-- .at
Attributes to be included for this SP
January 29, 2011
ZXID Book 34, p. 93
CHAPTER
BOOTSTRAPS
2428
2429
2430
2431
2432
2433
2434
2435
2436
2437
2438
2439
2440
|
‘-- SVC,SHA1
|
+-- idpnid/
Index of federated NameIDs, to map to uid
|
|
|
‘-- SVC,SHA1
|
|
|
‘-- NID
Content of the file is uid
|
+-- idpdimd/
|
|
|
‘-- SVC,SHA1
Discovery MD registration for a service
|
‘-- idplog/
2441
When generating SSO assertion, the attributes are collected as follows:
2442
1. LDIF at /var/zxid/uid/JOE/.bs/.at
2443
2. LDIF at /var/zxid/uid/JOE/SP,SHA/.at
2444
3. LDIF at /var/zxid/uid/.all/.bs/.at
2445
4. LDIF at /var/zxid/uid/.all/SP,SHA/.at
2448
As of version 0.33 (20090904) the attributes are rendered singlevalued. If multiple occurrances of an attribute happen, the first instance is used and others ignored. However,
in a future version, we expect to support multivalued attributes.
2449
The order for attaching bootstrap attributes is similar.
2446
2447
2450
2451
2452
2453
2454
2455
2456
2457
2458
2459
2460
2461
2462
2463
2464
2465
2466
2467
Yubikey support works by using the initial part of the ticket (passed in as user field)
as uid and the latter as the ticket proper. The uid part is used to locate correct directory. Mapping from yubikey modhex to real UID is done by creating a symlink. The
AES128 shared (between yubikey token and IdP) key is kept in the .yk file. As this is
not a password has, but rather directly the shared secret, it requires rigorous approach
to the filesystem security. The fact that .pw and .yk are separate files caters for the
possibility of user authenticating either by yubikey or by password. By default yubikey is one factor authentication (in fairly secure and very convenient form). If two
factor authentication is desired, the password component should be prefixed to the UID
component, i.e. first user types PIN and then presses yubikey to add UID and ticket.
TLS Client Certificate authentication of users has not been implemented yet, but in
any case would be mainly implemented by configuration of web server to request such
certificate and verify it. By the time zxid gets called, the client cert authentication
will already have happened. HTTP Basic authentication works in similar way and we
make no attempt to cater for it, although it can be used of configured separately (in the
traditional way).
zxpasswd(8) is a user provisioning tool that allows creation of new accounts as well as
manipulation of .pw and .yk files.
January 29, 2011
ZXID Book 34, p. 94
2468
2469
2470
Chapter 14
mod_auth_saml: Apache SSO
without Programming
User
B
r
o
w
s
e
r
2
IdP
DS
3
ID-DAP WSP
XACML PDP
4
Static Content
5
Apache httpd (mod_auth_saml attaches to Apache API hooks)
check_user_id hook
mod_auth_saml
Singe Sign-On (SSO)
1
Liberty IGF
Attribute Broker
(ID-WSF, local)
Authorization
XACML PEP
Apache
subprocess
environment
6
CGI
mod_perl
Dependency
libraries
{
zxid simple API
zlib
ZXID core
libcurl
openssl
Session
Mgmt
CoT
Mgmt
Local User
Mgmt
Backend Abstraction
= To be
implemented
©20091029 Sampo
Filesystem
(/var/zxid)
LDAP
MySQL
Schema driven
XML ENC/DEC
...
mod_php
ZXID SSO and Attribute Broker
1. Request protected content
2. Single Sign-On (SAML)
3. Discover attribute sources
4. Get attributes
5. Authorize
6. Deliver content w/attributes
Figure 14.1: ZXID, via mod_auth_saml, adds to Apache httpd Single Sign-On (SSO), Attribute
Broker, and XACML PEP Capabilities that can be used by existing static and dynamic content
without alteration.
95
CHAPTER 14. MOD_AUTH_SAML: APACHE SSO WITHOUT
14.1. COMPILING FROM SOURCE
PROGRAMMING
2471
2472
2473
2474
2475
2476
2477
2478
2479
2480
2481
2482
2483
2484
2485
2486
2487
2488
For avoidance of doubt, mod_auth_saml - based on zxid.org - is a separate project
from mod_authn_casa, mod_scalp and mod_mellon, which provide somewhat similar functionality, but have different code bases. It may be possible to use all of these
simultaneously, but this is not recommended unless you are an expert that can sort out
the differences.
mod_auth_saml provides Apache2 native integration at authentication layer. The objective of mod_auth_saml is to cause Apache to trigger SAML 2.0 Single Sign-On
instead of HTTP Basic or Digest authentication.
mod_auth_saml does not backend in any module in the mod_authn_* sense. All
authentication information is obtained from the frontend IdP without consulting any
backend. (However, the zxid.org session mechanism needs backend storage - once
zxid.org is generalized to support other backends than the default file system, we may
factor out the local session storage to a backend of its own.)
If you want to perform local authentication after the SSO, mod_auth_saml will provide
for downstream mod_authz_* modules a (pseudonymous) user identifier that can be
used to make the authorization decisions. It will also provide the attributes that were
received in the SSO or that were retrieved by later web services calls (like ID-DAP or
Personal Profile calls).
2491
Eventually mod_auth_saml may call on a mod_authn_* backend to obtain additional
local attributes (beyond the ones received in the SSO). Such call will use the pseudonym
as key.
2492
14.1
2489
2490
2493
2494
2495
2496
2497
2498
2499
2500
2501
2502
2503
2504
2505
2506
2507
2508
Compiling from Source
You may be able to get mod_auth_saml.so in binary form, in which case all you need
to do is
make dir
# Create /var/zxid hierarchy
cp mod_auth_saml.so /usr/local/httpd/modules
For more in-depth compilation instructions, please refer to general ZXID documentation (README.zxid).
Before you try compilation and installation of mod_auth_saml, you should investigate
what type of Apache install you have. Unfortunately different OS distributions do
this differently, making it difficult to provide one set of instructions that would always
work.
Out of box, zxid/Makefile assumes your Apache is installed where the Apache
project source code distribution would put it, namely in APACHE_ROOT=/usr/local/httpd.
You can change this by adding a new definition in localconf.mk.
On some distributions the Apache related files are scattered in many places that are
not under any specific "root" directory. In these cases you may need to define separate
variable for each use, e.g:
January 29, 2011
ZXID Book 34, p. 96
PROGRAMMING
14.2. CONFIGURATION AND TESTING
2509
2510
2511
2512
2513
2514
2515
2516
2517
2518
2519
2520
localconf.mk:
APACHE_INCLUDE=-I/usr/include/apache2
APR_INCLUDE=-I/usr/include/apr-1.0
APACHE_MODULES=/usr/lib/apache2/modules
To locate the correct directories, you can try
find / -name ap_config.h
find / -name apr.h
find / -name mod_auth_basic.so
Once everything is correctly set up, you can compile and install by saying
make apachezxid
make apachezxid_install
make dir
# Compiles
# Copies
# Create directory structure
2522
The installation step really just copies mod_auth_saml.so to modules/ subdirectory
of the Apache installation.
2523
14.2
Configuration and Testing
2524
14.2.1
httpd.conf
2521
2525
2526
2527
2528
2529
2530
2531
2532
2533
2534
2535
2536
2537
2538
2539
2540
2541
2542
2543
2544
2545
First you have to make sure mod_auth_saml.so is located in the modules/ directory of
your Apache httpd installation (e.g. /usr/local/httpd/modules/mod_auth_saml.so).
Then you should pull the module into the configuration with directive:
LoadModule auth_saml_module modules/mod_auth_saml.so
Next you should configure the Location protected by SSO:
Require valid-user
AuthType "saml"
ZXIDConf "URL=https://sp1.zxidsp.org:5443/protected/saml"
</Location>
The /protected is the directory you choose to protect. AuthType must be "saml".
The ZXIDConf directive allows you to pass any and all ZXID configuration directives,
using query string format. Please see main ZXID documentation (README.zxid) for
full discussion of the configuration options.
While most options can be left at their default value, the URL always needs to be specified. It must match the domain name and the directory that you choose to protect. The
final suffix /saml is used as communications end point during protocol exchanges. You
can choose any word you want (i.e. need not be "saml"), but it must not conflict with
any actual content in the directory and must be immediate child of the directory.
As of version 0.28 (Sept 2008) you still need to create actual file to correspond to the
URL:
January 29, 2011
ZXID Book 34, p. 97
14.3. REAL WORLD EXAMPLE
PROGRAMMING
2546
touch /usr/local/httpd/htdocs/protected/saml
2547
We expect to remove this requirement for dummy file in a future version.
2548
14.2.2
2549
Try accessing
2550
Trying it out
https://sp1.zxidsp.org:5443/protected/somefile
2552
You should first land on IdP selection and then after authentication to the IdP, see the
file, or error message if the file does not exist.
2553
14.2.3
2551
Setting up Circle of Trust
2554
• Auto-CoT method
2555
• Manual methods
2556
2557
2558
2559
2560
2561
2562
2563
2564
2565
2566
2567
2568
2569
2570
2571
2572
2573
14.3
Real World Example
Assume you want to set up a complex web site with some areas protected strongly,
others moderately, and some not at all.
/
/pers
-- No protection
-- Optional SAML SSO. If SSO has been performed, the
content will be personalized. If no SSO has been
performed -- or fails -- nonpersonalized content
is served. Default IdP is used.
/intra
-- Requires SAML SSO with default IdP
/protected -- Requires any SAML SSO with choice of IdP
/strong
-- Requires SAML SSO with strong credentials and choice of IdP
/other
-- Independent SP colocated with same web server. Login
to any of the first 4 directories does not count
as login to /other. It is its own entity and needs
separate SAML SSO.
1. Here’s how you would configure it in httpd.conf (SSL and other configuration
items are as usual and are not reproduced here):
LoadModule auth_saml_module modules/mod_auth_saml.so
2574
2575
2576
2577
<Location /pers>
Require valid-user
AuthType "saml"
January 29, 2011
ZXID Book 34, p. 98
PROGRAMMING
14.3. REAL WORLD EXAMPLE
ZXIDConf "DEFAULTQS=l0https://s-idp.liberty-iop.org:8881/idp.xml=1%26fp=1"
</Location>
2578
2579
2580
2581
<Location /intra>
Require valid-user
AuthType "saml"
ZXIDConf "DEFAULTQS=l0https://s-idp.liberty-iop.org:8881/idp.xml=1%26fc=1"
ZXIDConf "REQUIRED_AUTHNCTX=urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTrans
</Location>
2582
2583
2584
2585
2586
2587
2588
2589
Require valid-user
AuthType "saml"
ZXIDConf "ANON_OK=/pers/"
ZXIDConf "REDIR_TO_CONTENT=1"
</Location>
2590
2591
2592
2593
2594
2595
2596
2597
<Location /strong>
Require valid-user
AuthType "saml"
ZXIDConf "REQUIRED_AUTHNCTX=urn:oasis:names:tc:SAML:2.0:ac:classes:Strong"
ZXIDConf "IDP_SEL_PAGE=/idpsel.cgi"
</Location>
2598
2599
2600
2601
2602
2603
2604
2605
<Location /other>
Require valid-user
AuthType "saml"
ZXIDConf "PATH=/var/other/"
ZXIDConf "URL=https://sp1.zxidsp.org:5443/other/saml"
ZXIDConf "SES_COOKIE_NAME=OtherSes"
</Location>
2606
2607
2608
2609
2610
2611
2612
2613
Notes
2616
a. /pers, /intra, and /strong are "slaves" of /protected. This means they can
have some settings of their own, but other settings, especially those that apply
after SSO, are shared with /protected
2617
b. The slaves share Entity ID, session cookie, and session with the master.
2614
2615
2618
2619
2620
2621
2622
2623
2624
c. /other is genuinely different SP with its own Entity ID, cookie and session
directory.
d. The ANON_OK describes prefix under which SSO failure is not considered fatal. Currently there can only be one such prefix per master SP. This is known
limitation.
e. The REDIR_TO_CONTENT is set in master and shared with slaves. This causes
the SSO to end with 302 redirection to the original content so that the URL in
January 29, 2011
ZXID Book 34, p. 99
14.4. TESTING
2625
2626
2627
2628
2629
2630
2631
2632
2633
2634
2635
2636
2637
2638
2639
2640
2641
browser’s address bar will appear clean. Without this option, the last step of the
SSO protocol might be visible and since SSO terminates in master SP, the slaves
would have their relative URLs wrong.
f. The DEFAULTQS specification is used to simulate user submitting the IdP selection form. It is used for the SPs for which the IdP is always the same. The
Query String can also have some other form fields that control things like the
ispassive flag (fp=1) or the allowcreate flag (fc=1). To understand what fields
are possible, you can "View Source" the regular IdP selection page. The value
of the DEFAULTQS option needs to be URL encoded to prevent premature interpretation as multiple configuration options. In particular the ampersand must
be encoded as %26.
g. The IDP_SEL_PAGE allows you to build a fully custom IdP selection page.
Here we use it for requesting strong authentication context. Other simpler ways
to customize the IdP Selection Page exist, see e.g. IDP_SEL_START.
2. Create directories in the web root according to above plan. You also need to create
the /var/other hierarchy since you want to keep /other as separate entity from
rest of the directories
make dir ZXID_PATH=/var/other/
2642
2643
2644
2645
PROGRAMMING
N.B. The last slash is important.
Make sure the web server process has file system permissions to write to /var/zxid
and /var/other.
2646
14.4
2647
To enable debugging output, you should add
2648
Testing
ZXIDDebug "0x61"
2649
to the above configuration.
2650
1. Make sure you are logged out from your IdP and SP (e.g. delete cookies in browser)
2651
2. https://sp1.zxidsp.org:5443/pers/env.cgi
2652
• IdP selection should not show up.
2653
• IdP should not ask credentials.
2654
• You should see dump of environment variables
2655
• SAML_authnctxlevel=-
2656
• SAML_idpnid=-
2657
2658
3. https://sp1.zxidsp.org:5443/intra/env.cgi
• IdP selection should not show up. (bug: currently it does ***)
January 29, 2011
ZXID Book 34, p. 100
PROGRAMMING
14.5. MOD_AUTH_SAML FAQ
2659
• IdP should ask credentials
2660
• You should see dump of environment variables
2661
• SAML_authnctxlevel=urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport
2662
• SAML_idpnid=Peq7sdf-o0brJQcyrFvVh
2663
2664
2665
4. https://sp1.zxidsp.org:5443/pers/env.cgi
• This time the session is well authenticated so you should see the same dump
as in step (3).
2667
5. Logout by https://sp1.zxidsp.org:5443/protected/saml?o=m and clicking
"Single Logout (R)"
2668
14.5 mod_auth_saml FAQ
2669
1. How it actually works, does the module intercept every http request/response?
2666
2670
2671
It intercepts every HTTP request destined to URL prefixed by what appears in
httpd.conf <Location> configuration, i.e. Apache itself prefilters by URL prefix.
2675
Then it checks if cookie session is present - if so, the request is passed through to rest
of Apache processing. If not, it will start the SSO processing by presenting the IdP
selection screen. Eventually this will be improved to attempt automatic detection of
IdP, e.g. if there is only one IdP in the CoT.
2676
If the URL is the special one configured in
2672
2673
2674
2677
2678
2679
2680
2681
2682
2683
2684
2685
2686
2687
2688
2689
2690
2691
2692
2693
it will pass control to the ZXID code.
If SSO was triggered, the original URL is held in RelayState and once the SSO
completes (which will happen at the special URL), a redirect is performed to the
original URL found from RelayState. This could be used beneficially in unsolicited
SSO as well.
2. Does it have the reverse proxy functionality or is it located elsewhere?
mod_auth_saml works at the same layer and much the same way as HTTP Basic
authentication is implemented in Apache. It runs in the Apache process itself and
does not invoke any external helper.
It is not a reverse proxy. However, it is possible to configure a frontend Apache
server, with mod_auth_saml, to act as a reverse proxy.1
3. Is it OS independant? I mean, works both for Apache-Linux and Apache-Windows
and Apache-Solaris? I wonder not directly, but could be compiled, right?
It should not be OS dependant. For Unixes I am pretty sure this is a fact. For
Windows we need more testing (as of May 2008). It does not yet (May 2008) work
in IIS.
1 Integrating zxid to a dedicated reverse proxy like Pound (http://www.apsis.ch/pound/) should not
be difficult.
January 29, 2011
14.6. IMPORTANT TODO ITEMS FOR MOD_AUTH_SAML PROGRAMMING
2694
2695
2696
2697
2698
2699
2700
2701
2702
2703
2704
2705
2706
2707
2708
2709
2710
2711
2712
4. How the session creation at application is handled?
The name of the cookie that ZXID sets is configurable (by default it is called ZXIDSES). This may be enough for some applications.
14.6
Important TODO items for mod_auth_saml
Memory management needs an audit. The problem centers around memory management of dependency libraries openssl and libcurl. Both libraries as well as ZXID itself
have vectorable memory allocators, i.e. you can supply your own implementation of
malloc(3) and free(3). This allows Apache pool allocation functions to be used instead
of the traditional malloc(3) and free(3).
Unfortunately life is not that simple. Which pool should we use? The per request
pool is suitable for most purposes, but how can we know for what purpose openssl and
libcurl allocate memory? There is no easy way of knowing and the ephemeral nature
of per request allocation may land us in trouble. Other option would be to allocate
everything from global pool to make sure the memory will never be freed under us.
Unfortunately memory from the global pool can not be freed. Thus we may be better
sticking to malloc(3) and free(3).
To make matters worse, openssl is used by all of zxid, libcurl, and Apache mod_ssl.
Which one gets to set the function pointers that point to the allocator? There is no easy
answer - or at least we have not seen one yet.
2714
The allocator problems may be just about manageable for Apache running in traditional
pre-fork server mode, but become a real nightmare for threaded execution modes.
2715
14.7
2713
2716
2717
2718
2719
mod_authz_xacml
We plan to develop a mod_authz_* layer module that will perform the authorization
using XACML. mod_authz_xacml will act as a PEP and pass all available session
attributes to a PDP and then act on the decision of the PDP to deny or permit access to
a web resource. This is still WIP.
January 29, 2011
2720
2721
Chapter 15
Simple API: Easy way to SSO
2725
The ZXID library provides two main APIs: the Simple and the Raw. The ZXID Simple
API is meant to get you going with minimal understanding about SAML or SSO. It tries
to encapsulate as much of the control flow as possible. You only need to learn this API,
not the underlying protocol.
2726
15.1
2722
2723
2724
2727
2728
2729
2730
2731
2732
2733
2734
2735
2736
2737
2738
2739
2740
2741
2742
2743
2744
Hello World SSO
Consider the following "Hello World" SSO CGI example in C1 (the zxid_simple() API
is available in all language bindings):
01
02
03
04
05
06
07
08
09
10
11
12
13
#include <zx/zxid.h>
#define CONF "PATH=/var/zxid/&URL=https://sp1.zxidsp.org:8443/zxid"
void main() {
char* res = zxid_simple(CONF, 0, 255);
switch (res[0]) {
case ’d’: /* Logged in case */
my_parse_ldif(res);
my_render_content();
exit(0);
default:
ERR("Unknown zxid_simple() response(%s)", res);
}
}
What happens here:
1. The CGI script calls zxid_simple() to handle SAML protocol according to the configuration
1 zxidhlo.c in the source distribution is an actually usable example program. You should also look at its
cousins zxidhlo.php and zxidhlo.pl
103
15.1. HELLO WORLD SSO
2745
2746
2747
2748
2749
2750
2751
2752
2. The last argument with value 255 tells zxid_simple() to automatically handle redirections, login screen and any other protocol interaction needed to make SSO happen.
3. If zxid_simple() returns, we have either succeeded in SSO or we have failed (all
other cases are handled internally by zxid_simple() which calls exit(2) so it never
returns).
4. In the success case, zxid_simple() returns an LDIF entry (as a nul terminated C
string) describing the SSO and the attributes received. For example
dn: idpnid=Pa45XAs2332SDS2asFs,affid=https://idp.demo.com/idp.xml
objectclass: zxidsession
affid: https://idp.demo.com/idp.xml
idpnid: Pa45XAs2332SDS2asFs
authnctxlevel: password
sesid: S12aF3Xi4A
cn: Joe Doe
2753
2754
2755
2756
2757
2758
2759
2760
CHAPTER 15. SIMPLE API: EASY WAY TO SSO
15.1.1
Attributes Returned in the SSO
2764
In the returned LDIF entry some attributes, such as cn, are as they came from the
IdP (you need to consult your IdP configuration and documentation to alter them).
Other attributes are always created by zxid_simple(), albeit sometimes based on values
received from the IdP. They have the following meaning:
2765
dn LDAP distinguished name (part of LDIF format). Always first.
2766
objectclass Part of LDIF format.
2767
eid The Entity ID of the SP
2768
issuer The Entity ID of the authority that issued SSO assertion.
2761
2762
2763
2770
affid Specifies which IdP was used for SSO. More accurately, this describes the affiliation namespace in which the idpnid and tgtnid attributes are meaningful.
2771
idpinfo Human readable description of which IdP was used.
2769
2773
idpnid The federated ID, or pseudonym (IdP assigned NameID) of the user performing action
2774
nidfmt The format (category) of value returned in idpnid. P=persistent
2772
2777
localpath Path to acting user’s local account directory. The application can create its
own user specific files here. Please note that the directory may not be automatically created.
2778
ssoa7npath Path to the raw data of the Single Sign-On assertion in the local audit trail
2775
2776
2779
2780
tgtnid The federated ID, or pseudonym (IdP assigned NameID) of the user targeted
by the action. This indicates the resource owner.
January 29, 2011
2781
tgtfmt The format (category) of value returned in tgtnid. P=persistent
2782
tgta7npath Path to the raw data of the target identity assertion in the local audit trail
2785
tgtpath Path to targetted user’s local account directory. The application can create its
own user specific files here. Please note that the directory may not be automatically created.
2786
authnctxlevel Rough indication of how IdP authenticated user
2783
2784
2787
2788
2789
2790
2791
2792
2793
2794
sesid Session ID, as may be stored in cookie or used for file name in the session cache
(/var/zxid/ses)
sespath Directory corresponding to local ZXID session. This may allow your application to access the raw data behind the ZXID session, or it could allow you
to add new data to the session. However, beware that just altering the files in
this directory may not be enough to update values cached in memory. If session
backend is not filesystem, the contents of this attribute may be URI appropriate
for accessing the session, or this attribute may not be populated at all.
2796
sigres Signature validation error code, if any. 0=OK. For other codes see ZXSIG_*
definitions in the source.
2797
ssores Error code for most recent operation. 0=OK
2795
2802
setcookie If this field is not empty and not equal to ’-’ (single dash), then the controlling application should take the necessary actions to set the cookie as specified.
Namely, the controlling application should create ’Set-Cookie’ HTTP response
header whose value is the value of the setcookie field. How this is done is environment dependent.
2803
cookie The ZXIDSES (or other, as configured) cookie value. For reference.
2798
2799
2800
2801
2804
2805
2806
2807
2808
2809
2810
2811
2812
2813
2814
2815
tgt_* Any attribute starting by "tgt_" refers to the target identity and was retrieved
from local attribute authority (typically a user specific directory inside /var/zxid/user,
see tgtpath). They are prefixed so that their provenance is clear. SP administrator can add these attributes by editing tgtpath/.bs/.at file, which is in LDIF
format.
It is also possible to define SP site global attributes in /var/zxid/user/.all/.bs/.at
file, in LDIF format. Since these are common to all users of SP, there is no prefix.
local_* Any attribute starting by "local_" refers to the acting user’s identity and was
retrieved from local attribute authority (typically a user specific directory inside
/var/zxid/user, see localpath). They are prefixed so that their provenance is
clear. SP administrator can add these attributes by editing localpath/.bs/.at
file, which is in LDIF format.
2817
cn Common Name. This attribute just exemplifies how any additional attributes the
IdP may have set will appear. Typically the LDAP attribute names are used.
2818
fedusername pseudonym@idpdomain, for example: [email protected]
2816
2819
2820
The fedusername attribute is a helper for the SP web sites that are fixated on
the notion of needing a username and/or requiring the username to look like an
January 29, 2011
2821
2822
2823
2824
2825
2826
2827
2828
email. By packaging the psedonym this way it is easy to get them to work with
minimal modification.
N.B. Although it looks like an email address, it is not. Do not try sending mail
to it (unless you hack your mailserver to understand it).
urn:oid:1.3.6.1.4.1.5923.1.1.1.6 pseudonym@idpdomain (aka eduPersonPrincipalName)
This is essentially the same as fedusername, but it seems in some shibboleth
federations this is the right attribute name. At least protectnetwork.org works
this way.
2830
The dn line will always be the first. All other lines may appear in any order. String representation of LDIF was chosen as it is easy to parse in most programming languages.
2831
15.1.2
2829
2833
The zxid_simple() can be configured in the following ways (later ways can override
earlier ones).
2834
1. Built in default configuration
2835
2. Configuration file, usually /var/zxid/zxid.conf, if any
2832
2836
2837
2838
2839
2840
3. Configuration string passed as first argument. While configuration string can override all other options (i.e. it is processed last), the PATH specification is parsed
before the configuration file is looked up.
Turns out that often the default configuration modified by the configurations string is
all you need - you do not need to prepare configuration file.
2842
See section "Configuring and Running" for complete list of configuration options, but
generally it is sufficient to specify only a handful:
2843
PATH Where files are kept and configuration file is found.
2844
URL The URL of the SP
2841
2846
CDC_URL The Common Domain URL (optional, if omitted the Common Domain
Cookie processing is disabled)
2847
15.1.3
2845
AUTO options (auto flags)
2850
The auto_flags argument allows you to control which operations should be performed automatically and which should be passed to the calling application, see "Gaining More Control" section, below, for full description of this case.
2851
The auto options can be added together.
2848
2849
2853
If the AUTO_REDIR flag is true, the LOCATION header is sent to stdout and exit(0)
may be called, depending on the AUTO_NOEXIT flag.
2854
The SOAP, META, LOGIN, and MGMT flags follow convention:
2852
January 29, 2011
Table 15.1: zxid_simple() AUTO options
Dec
1
2
4
8
16
32
64
128
256
512
1024
2048
4095
4096
8192
16384
2855
2856
2857
2858
2859
HC
00
01
10
11
2860
2861
2862
2863
2864
2865
2866
2867
2868
2869
2870
2871
2872
2873
2874
2875
Hex
0x01
0x02
0x04
0x08
0x10
0x20
0x40
0x80
0x100
0x200
0x400
0x800
0xfff
0x1000
0x2000
0x4000
Symbol
ZXID_AUTO_EXIT
ZXID_AUTO_REDIR
ZXID_AUTO_SOAPC
ZXID_AUTO_SOAPH
ZXID_AUTO_METAC
ZXID_AUTO_METAH
ZXID_AUTO_LOGINC
ZXID_AUTO_LOGINH
ZXID_AUTO_MGMTC
ZXID_AUTO_MGMTH
ZXID_AUTO_FORMF
ZXID_AUTO_FORMT
ZXID_AUTO_ALL
ZXID_AUTO_DEBUG
ZXID_AUTO_OFMTQ
ZXID_AUTO_OFMTJ
Description
Call exit(), 0=return "n", even if auto CGI
Automatic. handle redirects, assume CGI (calls exit(2))
SOAP response handling, content gen
SOAP response handling, header gen
Metadata response handling, content gen
Metadata response handling, header gen
IdP select / Login page handling, content gen
IdP select / Login page handling, header gen
Management page handling, content gen
Management page handling, header gen
In idp list and mgmt screen, generate form fields
In idp list & mgmt screen, wrap in <form> tag.
Enable all automatic CGI behaviour.
Enable debugging output to stderr.
Output Format Query String
Output Format JSON
No automation. Only action letter is returned ("e"=login, "b"=meta, etc.)
Content, not wrapped in headers, is returned as a string
Headers and content is returned as a string
Headers and content are sent to stdout, CGI style and
exit(0) may be called, depending on AUTO_EXIT. Otherwise "n" is returned.
Whether exit(0) is called in 11 case depends on ZXID_AUTO_NOEXIT flag.
How much HTML is generated for Login page and Mgmt page in 01 (content only)
mode depends on AUTO_PAGE and AUTO_FORM flags
TF
00
01
10
11
reserved / nothing is generated
Only form fields (but not form tag itself) are generated.
Complete form is generated
Whole page is generated (best support)
The output format in the successful SSO case depends on OFMT bits as follows
JQ
==
00
01
10
11
LDIF (default)
Query String
JSON
Reserved
January 29, 2011
15.2. GAINING MORE CONTROL
2876
2877
2878
2879
2880
2881
2882
2883
2884
2885
2886
2887
15.1.4
Configuration options for customizing HTML
When whole page is generated, some templating information is taken from the configuration.
IDP_SEL_START All the HTML before <form> tag. This can include HTML headers and the <body> tag, as well as beginning of the page, allowing for complete
color selection, stylesheet embedding, and general branding of the page.
IDP_SEL_NEW_IDP The HTML fragment to allow login using a new IdP (Auto
CoT using IdP URL). Set to empty to hide this possibility.
IDP_SEL_OUR_EID Message displaying SP Entity ID, in case (technically minded)
user needs to know this to establish relationship with an IdP.
IDP_TECH_USER Technical parameters that user might want to set, and typically
would be allowed to set. May be hidden (not user controllable) or visible.
2888
fc Create federation (AllowCreate flag)
2889
fn Name ID format
2890
2891
2892
2893
prstnt Persistent (pseudonym)
trnsnt Transient, temporary pseudonym
IDP_TECH_SITE Technical parameters that the site administrator should decide and
set. Usually hidden fields:
2894
fq Affiliation ID (usually empty)
2895
fy Consent obtained by SP for the federation or SSO
2896
2897
2898
2899
2900
2901
2902
2903
2904
2905
2906
2907
empty No statement about consent
urn:liberty:consent:obtained Has been obtained (unspecified
way)
urn:liberty:consent:obtained:prior Obtained prior to present
transaction, e.g. user signed terms and conditions of service
urn:liberty:consent:obtained:current:implicit Consent
is implicit in the situation where user came to invoke service
urn:liberty:consent:obtained:current:explicit Obtained
explicitly
urn:liberty:consent:unavailable Consent can not be obtained
urn:liberty:consent:inapplicable Obtaining consent is not
relevant for the SP or service.
2908
fa Authentication Context (strength of authentication) needed by the SP
2909
fm Matching rule for authentication strength (usually empty, IdP decides)
2910
fp Forbid IdP from interacting with the user (IsPassive flag)
2911
ff Request reauthentication of user (ForceAuthn flag)
January 29, 2011
15.2. GAINING MORE CONTROL
2912
2913
2914
2915
2916
2917
2918
2919
2920
2921
2922
2923
2924
2925
2926
2927
2928
2929
2930
2931
2932
2933
2934
2935
2936
2937
2938
2939
2940
2941
2942
2943
2944
2945
2946
2947
2948
2949
15.2
Gaining More Control
The fully automated interface works well for CGI deployment but probably is not appropriate in more complex situations. You can use zxid_simple() without automation
and prevent it from accessing the system layer too directly. Consider
01 #define CONF "PATH=/var/zxid/&URL=https://sp1.zxidsp.org:8443/zxid"
02 int main() {
03
char* res;
04
res = zxid_simple(CONF, getenv("QUERY_STRING"), 0);
05
switch (res[0]) {
06
case ’L’: printf("%s", res); exit(0); /* Redirect */
07
case ’C’: printf("%s", res); exit(0); /* Content-type + content */
08
case ’<’: printf("Content-Type: text/html\r\n\r\n%s", res); exit(0);
09
case ’n’: exit(0);
10
case ’b’: my_send_metadata();
11
case ’e’: my_render_login_screen();
12
13
my_parse_ldif(res);
14
my_render_content();
15
exit(1);
16
default:
17
18
}
19 }
Here we specify zero as auto_flags, thus all automation is disabled. This means
that the res can take more varied shape and the calling application has to be prepared
to handle them. The different cases are distinguished by the first character of the res
string:
L Redirection request (L as in Location header). The full contents of the res is the
redirection request, ready to be printed to stdout of a CGI. If you want to handle
the redirection some other way, you can parse the string to extract the URL and
do your thing. This res is only returned if you did not set ZXID_AUTO_REDIR.
Example:
Location: https://sp1.zxidsp.org:8443/zxid?o=C
C Content with Content-type header. The res is ready to be printed to the stdout of a
CGI, but if you want to handle it some other way, you can parse the res to extract
the header and the actual body.
Example:
CONTENT-TYPE: text/html
2950
2951
2952
<title>Login page</title>
...
January 29, 2011
15.3. SOME GENERALIZATION
CHAPTER
AND OPTIMIZATIONS
15. SIMPLE API: EASY WAY TO SSO
2953
Example (metadata):
CONTENT-TYPE: text/xml
2954
2955
<m:EntityDescriptor>
...
2956
2957
2958
2959
2960
2961
2962
2963
2964
2965
2966
2967
2968
2969
2970
2971
2972
2973
2974
2975
2976
2977
2978
2979
2980
2981
2982
Less than ("<") Content without headers. This could be HTML content for login
page or metadata XML. To know which (and set content type correctly), you
would have to parse the content. This res format is only applicable if you did not
specify ZXID_AUTO_CTYPE (but did specify ZXID_AUTO_CONTENT).
n Do nothing. The operation was somehow handled internally but the exit(2) was not
called (e.g. ZXID_AUTO_SOAP was NOT specified). The application should
NOT attempt generating any output.
b Indication that the application should send SP metadata to the client. This res is only
returned if you did not set ZXID_AUTO_META.
c Indication that the application should send SP CARML declaration to the client. This
res is only returned if you did not set ZXID_AUTO_META.
e Indication that the application should display the IdP selection page. Application
may use zxid_idp_list() to render the IdP selection area. This res is only returned
if you did not set ZXID_AUTO_CONTENT.
a Indication that the application should display the authentication page (usually this
happens on IdP).
d Indication that SSO has been completed or that there was an existing valid session
in place. The res is an LDIF entry containing attributes that describe the SSO or
session. See "Hello World" section for description of the LDIF data.
Usually your application would parse the attributes and then render its application specific content. If you want to render the SSO management form (with
logout and defederate buttons), you can call zxid_fed_mgmt().
z Authorization failure. Application MUST NOT display protected content. Instead,
it should offer user interface where the user can understand what happened and
possibly gain the extra credentials needed.
2984
Asterisk ("*") Although any unknown letter should be interpreted as an error, we
follow convention of prefixing errors with an asterisk ("*").
2985
15.3
2983
2986
2987
2988
2989
Some Generalization and Optimizations
The simplest APIs are easy to use and suitable for CGIs where the program is restarted
anew every time. However in situations where the script engine stays alive persistently,
it is wasteful to reparse (and reallocate) the configuration every time. Consider following PHP snippet designed to be used with mod_php:
January 29, 2011
CHAPTER 15. SIMPLE15.3.
API: EASY
SOME WAY
GENERALIZATION
TO SSO
AND OPTIMIZATIONS
2990
2991
2992
2993
2994
2995
2996
2997
2998
2999
3000
3001
3002
3003
3004
3005
3006
3007
3008
3009
3010
3011
3012
3013
3014
3015
3016
3017
3018
3019
3020
3021
3022
3023
3024
3025
3026
3027
3028
3029
3030
3031
3032
3033
3034
3035
01
02
03
04
05
06
07
08
09
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
# Put this in the PHP initialization (it only needs to run once)
dl("php_zxid.so");
$conf = "PATH=/var/zxid/&URL=https://sp1.zxidsp.org:8443/zxiddemo.php";
$cf = zxid_new_conf_to_cf($conf);
<?
# For every page that is accessed
$qs = $_SERVER[’REQUEST_METHOD’] == ’GET’
? $_SERVER[’QUERY_STRING’]
: file_get_contents(’php://input’);
$res = zxid_simple_cf($cf, -1, $qs, null, 0x1800);
switch (substr($res, 0, 1)) {
case ’L’: header($res); exit; # Redirect
case ’n’: exit;
# already handled
case ’d’: break; # Logged in case -- fall through
default: error_log("Unknown zxid_simple() res(%s)", res); exit;
}
# *** Parse the LDIF in $res into a hash of attributes (see zxidhlo.php)
?>
<html><title>Protected content, logged in as <$=$attr[’cn’]$></title>
...
</html>
<?
function my_render_login_screen()
{
?>
<html><title>Please Login Using IdP</title>
...
<?=zxid_idp_select_cf($cf, null, 0x1800)?>
...</html>
<? exit; }?>
Notes
1. Line 4 creates a system-wide configuration object that is later used by the other API
calls
2. On line 9 we call zxid_simple_cf() with the created object. The second and third argument specify a buffer or string that contains the CGI form data to parse. This may
come from QUERY_STRING of a GET request or from HTTP body of a POST request,
as determined on line 8. The -1 means the length of the data should be determined
using strlen(3), i.e. C string nul termination. The auto_flags == 0x1800 enables
form tag wrapping and debug prints, but otherwise automation is disabled.
3. Since automation was disabled, we need to handle several cases of possible outcomes from zxid_simple_cf(), on lines 10-17.
4. From line 18 onwards we handle the login successful or already logged in case.
First we split the LDIF entry into a hash so that we can access the attributes easily
(e.g. cn on line 20).
January 29, 2011
15.4. JAVA SERVLET EXAMPLE
CHAPTER
USING TOMCAT
15. SIMPLE API: EASY WAY TO SSO
3038
5. On line 30 we call zxid_idp_list_cf() to create the form for choosing which IdP to
use for login (remember that auto_flags == 0xc0 enabled the form wrapper). As
can be seen the same configuration object, $cf, is used through out.
3039
15.4
3040
Consider
3036
3037
3041
3042
3043
3044
3045
3046
3047
3048
3049
3050
3051
3052
3053
3054
3055
3056
3057
3058
3059
3060
3061
3062
3063
3064
3065
3066
3067
3068
3069
3070
3071
3072
3073
3074
3075
3076
3077
3078
3079
3080
01
02
03
04
05
06
07
08
09
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
Java Servlet Example Using Tomcat
import zxidjava.*;
import java.io.*;
import javax.servlet.*;
import javax.servlet.http.*;
public class zxidhlo extends HttpServlet {
static { System.loadLibrary("zxidjni"); }
static final String conf
= "PATH=/var/zxid/&URL=http://sp1.zxidsp.org:8080/zxidservlet/zxidHLO";
public void do_zxid(HttpServletRequest req, HttpServletResponse res, String qs)
throws ServletException, IOException {
String ret = zxidjni.simple(conf, qs, 0xd54);
switch (ret.charAt(0)) {
case ’L’: /* Redirect: ret == "LOCATION: urlCRLF2" */
res.sendRedirect(ret.substring(10, ret.length() - 4));
return;
case ’<’:
case ’s’: /* <se: SOAP envelope */
case ’m’: /* <m20: metadata */
res.setContentType("text/xml");
break;
default:
res.setContentType("text/html");
break;
}
res.setContentLength(ret.length());
res.getOutputStream().print(ret);
break;
//my_parse_ldif(ret);
res.getOutputStream().print(zxidjni.fed_mgmt(conf, sesid, 0xd54));
break;
default:
System.err.print("Unknown zxid_simple() response:");
System.err.print(ret);
}
}
public void doGet(HttpServletRequest req, HttpServletResponse res)
January 29, 2011
3081
3082
3083
3084
3085
3086
3087
3088
3089
3090
3091
3092
3093
41
// LECP/ECP PAOS header checks
42
do_zxid(req, res, req.getQueryString());
43
}
44
public void doPost(HttpServletRequest req, HttpServletResponse res)
45
46
String qs;
47
int len = req.getContentLength();
48
byte[] b = new byte[len];
49
int got = req.getInputStream().read(b, 0, len);
50
qs = new String(b, 0, got);
51
do_zxid(req, res, qs);
52
}
53 }
3094
15.5
3095
See also zxid-perl.pd
3096
3097
3098
3099
3100
3101
3102
3103
3104
3105
3106
3107
3108
3109
3110
3111
3112
3113
3114
3115
3116
3117
3118
3119
3120
3121
3122
3123
3124
3125
15.5. SAMMA PÅ PERL
Samma på Perl
01 use Net::SAML;
02 $| = 1; undef $/; # Flush pipes, read all in at once
03 $url = "http://sp.tas3.pt:8082/zxidhlo.pl"; # Edit to match your conf
04 $conf = "PATH=/var/zxid/&URL=$url";
05 $cf = Net::SAML::new_conf_to_cf($conf);
06 $qs = $ENV{’QUERY_STRING’};
07 $qs = <STDIN> if $qs =~ /o=P/;
08 $res = Net::SAML::simple_cf($cf, -1, $qs, undef, 0x1828);
09 $op = substr($res, 0, 1);
10 if ($op eq ’L’ || $op eq ’C’) { print $res; exit; } # LOCATION (Redir) or\
CONTENT
11 if ($op eq ’n’) { exit; } # already handled
12 if ($op eq ’e’) { my_render_idpsel_screen(); exit; }
13 if ($op ne ’d’) { die "Unknown Net::SAML::simple() res($res)"; }
14
15 ($sid) = $res =~ /^sesid: (.*)$/m; # Extract a useful attribute from SSO\
output
16
17 print <<HTML
18 CONTENT-TYPE: text/html
19
20 <title>ZXID perl HLO SP Mgmt & Protected Content</title>
21 <link rel="shortcut icon" href="/favicon.ico" type="image/x-icon">
22 <link type="text/css" rel=stylesheet href="idpsel.css">
23 <body bgcolor=white><font face=sans>
24
25 <h1>ZXID SP Perl HLO Management & Protected Content (user logged in, sess\
ion active)</h1>
26 sesid: $sid
27 HTML
January 29, 2011
15.5. SAMMA PÅ PERL
3170
28
;
29 print Net::SAML::fed_mgmt_cf($cf, undef, -1, $sid, 0x1900);
30 exit;
31
32 sub my_render_idpsel_screen { # Replaces traditional login screen
33
print <<HTML;
35
36 <title>ZXID SP PERL HLO SSO IdP Selection</title>
40 <h1>ZXID SP Perl HLO Federated SSO IdP Selection (user NOT logged in, no \
session.)</h1>
41 <form method=get action="zxidhlo.pl">
42
43 <h3>Login Using New IdP</h3>
44
45 <i>A new IdP is one whose metadata we do not have yet. We need to know
46 the Entity ID in order to fetch the metadata using the well known
47 location method. You will need to ask the adminstrator of the IdP to
48 tell you what the EntityID is.</i>
49
50 <p>IdP URL <input name=e size=60><input type=submit name=l2 value=" Login\
">
51 HTML
52 ;
53
print Net::SAML::idp_list_cf($cf, undef, 0x1c00);
# Get the IdP sel\
ection form
54
print <<HTML;
55 <h3>CoT configuration parameters your IdP may need to know</h3>
56
57 Entity ID of this SP: <a href="$url?o=B">$url?o=B</a> (Click on the link \
to fetch SP metadata.)
58
59 <input type=hidden name=fc value=1><input type=hidden name=fn value=prstn\
t>
60 <input type=hidden name=fq value=""><input type=hidden name=fy value="">
61 <input type=hidden name=fa value=""><input type=hidden name=fm value="">
62 <input type=hidden name=fp value=0><input type=hidden name=ff value=0>
63
64 </form><hr><a href="http://zxid.org/">zxid.org</a>
65 HTML
66
;
67 }
3171
This example only demonstrates SSO.
3172
Lines 1-5 set up the configuration. See zxid-conf.pd for guidance.
3173
ll.6-7 reads in the CGI input the perl way.
3126
3127
3128
3129
3130
3131
3132
3133
3134
3135
3136
3137
3138
3139
3140
3141
3142
3143
3144
3145
3146
3147
3148
3149
3150
3151
3152
3153
3154
3155
3156
3157
3158
3159
3160
3161
3162
3163
3164
3165
3166
3167
3168
3169
January 29, 2011
3174
3175
3176
3177
3178
3179
3180
3181
3182
3183
3184
3185
3186
3187
3188
3189
3190
15.6. SHELL SCRIPT API
l.8 runs the SAML engine of ZXID. The engine will return result that is processed
below. The magic constant 0x1828 sets some flags, see zxid-simple.pd for explanation. This explanation may be especially relevant if you plan to run as mod_perl
process rather than as a CGI. With these flags you could eliminate the need to render
the IdP selection screen.
ll.9-13: interpret the return value. l.10 deals with parts of SAML protocol that need
redirect or content. l.12 deals with rendering the IdP selection screen. This screen
replaces the traditional login screen in most applications.
l.15 demonstrates how to extract attributes from the return value. The ret is formatted
as LDIF so it is very easy to parse with perl.
ll.17-30 render the "protected content". Most protected content should contain also
Single Logout button. This is accomplished on l.29. Protected content is where your
normal application after SSO lives. You can rely in ZXID session mechanism and just
show the content, or you could bootstrap your application’s session mechanism here.
ll.32-67 render the "idp selection" screen. This could have been automatically generated has the flags to Net::SAML::simple_cf() been different (see zxid-simple.pd for
explanation).
3192
As can be seen, the most central logic for SSO is only about 10 lines. The rest is user
interface.
3193
15.6
3191
Shell Script API
3197
Any Bourne shell (Unix shell) shell script can be converted to a SAML SSO enabled
CGI script using zxidsimple(1) helper utility executable. The program simply wraps
the zxid_simple() API function so that the inputs can be provided as command line
arguments, or in case of qs as stdin, and the output is returned on stdout.
3198
Synopsis
3194
3195
3196
3199
3200
3201
3202
3203
3204
3205
3206
3207
3208
3209
3210
3211
3212
zxidsimple -o ldif CONF AUTO_FLAGS <cgi-input
Typical usage (see also zxidhlo.sh):
01
02
03
04
05
06
07
08
09
10
11
12
CONF="PATH=/var/zxid/&URL=https://sp1.zxidsp.org:8443/zxidhlo.sh"
./zxidsimple -o /tmp/zxidhlo.sh.$$ $CONF 4094 || exit;
IFS="
"
res=‘cat /tmp/zxidhlo.sh.$$‘
case "$res" in
dn*)
# SSO successful case
for x in $res; do
case "$x" in
sesid:*) SID=${x##*sesid: } ;;
idpnid:*) NID=${x##*idpnid: } ;;
cn:*)
CN=${x##*cn: } ;;
January 29, 2011
15.6. SHELL SCRIPT API
3213
3214
3215
3216
3217
3218
3219
3220
3221
3222
3223
3224
3225
3226
3227
3228
3229
3230
3231
3232
3233
3234
3235
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
esac
done
;;
*) echo "ERROR($res)" >>/tmp/hlo.err; exit ;;
esac
cat << EOF
Content-Type: text/html
<title>ZXID HELLO SP Mgmt (Logged In)</title>
<h1>ZXID HELLO SP Management (user $CN logged in, session active)</h1>
<form method=post action="zxidhlo.sh?o=P">
<input type=hidden name=s value="$SID">
<input type=submit name=gl value=" Local Logout ">
<input type=submit name=gr value=" Single Logout (Redir) ">
</form>
EOF
The zxidsimple(1) utility will return exit value 1 if it handled a SAML protocol operation (by outputting to stdout whatever was appropriate). The shell script should not do
any further processing and just exit.
If the exit value is 0 (success) then SSO has been done. Since the attributes from the
SAML assertion are usually interesting, you can capture them to a temporary file using
the -o option.
3238
First we split the result of the backtick into a list on (literal) newline. Then we process
the list with for loop and look with case for the interesting attributes and capture them
into local variables.
3239
Finally the protected content page is output.
3236
3237
January 29, 2011
3240
3241
Chapter 16
ZXID Simple Form Fields
3246
The ZXID cgi interface assumes certain hardwired form field names. These are not
configurable (and there is no intent to make them configurable). The cgi fields may
appear either in query string (GET method) or as POST content (though depending on
your programming environment and language, you may need to read the POST data in
yourself prior to calling zxid_simple()).
3247
16.1
3248
These fields appear often in requests and have universal meaning.
3249
o Operation. In particular o=P means that form uses POST method.
3250
s Session ID
3251
RelayState SAML 2.0 mandated field name for relay state
3252
SAMLart SAML 2.0 mandated field name for SAML artifact
3242
3243
3244
3245
Common Fields
3254
SAMLResponse SAML 2.0 mandated field name for SAML response, especially in
POST profile
3255
SAMLRequest SAML 2.0 mandated field name for SAML request
3256
SigAlg SAML 2.0 mandated field name for signature algorithm in redirect binding
3257
Signature SAML 2.0 mandated field name for signature in redirect binding
3258
16.2
3259
These are typically embdedded or visible fields of the IdP Selection screen.
3260
u User (local login)
3253
IdP Selection (Login) Screen
117
16.2. IDP SELECTION (LOGIN) SCREEN
CHAPTER 16. ZXID SIMPLE FORM FIELDS
3261
p Password (local login)
3262
c Common Domain Cookie
3263
e Entity ID (manual entry field)
3264
d Entity ID (from popup or radio box)
3265
i Protocol index
3266
l1 Login using artifact profile (same as i=1)
3267
l2 Login using POST profile (same as i=2)
3268
l1EID Login using specified IdP (artifact profile), same as e=EID&i=1
3269
l2EID Login using specified IdP (POST profile), same as e=EID&i=2
3270
fc Allow Create flag
3271
fp IsPassive flag
3272
ff Force Authentication flag
3273
fn NameID format
3274
fq Affiliation ID
3275
fy Consent field
3276
fm Matching rule
3277
fa Authentication Context Class
3278
fr Relay State
3279
3280
3281
3282
3283
3284
Please understand that a significant part of any SSO configuration is realized via f*
fields, which will typically be hidden fields in the IdP selection form. Some of these
configuration options can not be set or overridden from the configuration file. You must
provide them as (hidden) fields of the HTML form.
The DEFAULTQS option often will emulate the IdP Selection form submission and set
some f* options.
3286
The IdP selection form (aka Login) screen can be implemented, using the above documented form interface, in many ways as following examples illustrate.
3287
Example IdP Selection Form: Popup menu method
3288
***
3289
Example IdP Selection Form: Separate IdP buttons method
3285
3290
3291
3292
3293
3294
<form method=post
action="http://sp1.zxidsp.org:8080/zxidservlet/zxidHLO?o=P">
<h3>Login Using New IdP</h3>
<p>IdP URL <input name=e size=80>
<input type=submit name=l1 value=" Login (A2) ">
January 29, 2011
CHAPTER 16. ZXID
16.3.
SIMPLE
SINGLE
FORM
LOGOUT
FIELDS
AND FEDERATION MANAGEMENT
<input type=submit name=l2 value=" Login (P2) "><br>
3295
3296
3297
3298
3299
3300
3301
<h3>Login Using Known IdP</h3>
<input type=submit name="l1https://a-idp.liberty-iop.org:8881/idp.xml"
value=" Login to https://a-idp.liberty-iop.org:8881/idp.xml (A2) ">
<input type=submit name="l2https://a-idp.liberty-iop.org:8881/idp.xml"
value=" Login to https://a-idp.liberty-iop.org:8881/idp.xml (P2) ">
3302
3303
3304
3305
3306
3307
3308
3309
<h3>Technical options</h3>
<input type=checkbox name=fc value=1 checked> Create federation,
NID Format: <select name=fn>
<option value=prstnt>Persistent
<option value=trnsnt>Transient
<option value="">(none)
</select><br>
3310
3311
3312
3313
3314
3315
3316
3317
<input type=hidden
<input type=hidden
<input type=hidden
<input type=hidden
<input type=hidden
<input type=hidden
</form>
name=fq
name=fy
name=fa
name=fm
name=fp
name=ff
value="">
value="">
value="">
value="">
value=0>
value=0>
3318
Example IdP Selection Form: IdP links method
3319
***
3320
16.3
Single Logout and Federation Management
3323
Following fields typically appear in form implementing logout button. You will usually
need to embed them to your application’s screens where logout button or link appears.
Typically you would include one of them and teh s argument in the query string.
3324
gl Local Logout
3325
gr Single Logout using redirection
3326
gs Single Logout using SOAP
3327
gt NameID Managment (redirect)
3328
gu NameID Management (SOAP)
3329
Example Management Form
3321
3322
3330
3331
3332
<form method=post action="zxid?o=P">
<input type=hidden name=s value="">
January 29, 2011
16.4. LOGIN BUTTON ABREVIATIONS
CHAPTER 16. ZXID SIMPLE FORM FIELDS
3333
3334
3335
3336
3337
3338
3339
3340
3341
3342
3343
3344
3345
3346
3347
3348
3349
3350
3351
3352
3353
3354
3355
3356
3357
3358
3359
3360
3361
3362
3363
3364
<input type=submit
<input type=submit
<input type=submit
<input type=submit
</form>
16.4
name=gr
name=gs
name=gt
name=gu
value="
value="
value="
value="
Single Logout (Redir) ">
Single Logout (SOAP) ">
Defederate (Redir) ">
Defederate (SOAP) ">
Login Button Abreviations
Sometimes you will see in the IdP Selection screen a small abbreviation like "(A2)".
This indicates the protocol binding that will be used (if supported in metadata). The
button without such legend will automatically pick binding that is best among available.
If both POST and artifact are available, it will pick artifact.
A2 = SAML 2.0 Artifact Profile
P2 = SAML 2.0 POST Profile
’’ = SAML 2.0 POST Simple Sign
A12 = Liberty ID-FF 1.2 Artifact Profile
P12 = Liberty ID-FF 1.2 POST Profile
A1 = Bare SAML 1.x Artifact Profile
P1 = Base SAML 1.x POST Profile
A0 = WS-Federation Artifact Profile
P0 = WS-Federation POST Profile
16.5
ZXID IdP Login Screen Form Fields
N.B. The IdP functionality is not fully developed as of Nov 2008.
<form method=post action="zxididp?o=P">
<input type=hidden name=s value="">
<input name=au>
<input type=password name=ap>
<input type=submit name=alp value=" Login ">
<input type=submit name=gr value=" Single Logout (Redir) ">
<input type=submit name=gs value=" Single Logout (SOAP) ">
<input type=submit name=gt value=" Defederate (Redir) ">
<input type=submit name=gu value=" Defederate (SOAP) ">
</form>
January 29, 2011
3365
3366
Chapter 17
ZXID Simple API Reference
3367
See also ref/html/index.html:Function reference
3368
17.1
Creating Configuration Object
3370
int zxid_conf_to_cf_len(struct zxid_conf* cf, int conf_len, char* conf);
struct zxid_conf* zxid_new_conf_to_cf(char* conf);
3371
17.2
3369
3372
3373
3374
3375
3376
/*
*
*
*
*
zxid_simple() main protocol dispatch
Simple handler that assumes the configuration has already been read in.
The memory for result is grabbed from ZX_ALLOC(), usually malloc(3)
and is "given" away to the caller, i.e. caller must free it. The
return value is LDIF of attributes in success case.
res_len, if non-null, will receive the length of the response. */
3377
3378
3379
/* Process simple configuration and then call simple handler. Strings
* are length + pointer (no C string nul termination needed). */
3380
3385
char* zxid_simple_cf(struct zxid_conf* cf, int qs_len, char* qs, int* res_le\
n, int auto_flags);
char* zxid_simple_len(int conf_len, char* conf, int qs_len, char* qs, int* r\
es_len, int auto_flags);
char* zxid_simple(char* conf, char* qs, int auto_flags);
3386
17.3
3387
/* ------------ zxid_idp_list() ------------ */
3381
3382
3383
3384
Generating Login Screen
3388
3389
char* zxid_idp_list_cf_cgi(struct zxid_conf* cf, struct zxid_cgi* cgi, int* \
121
17.4. GENERATING HTML FOR LOGOUT BUTTON OR MANAGEMENT
SCREENS
CHAPTER 17. ZXID SIMPLE API REFERENCE
3390
3391
3392
3393
3394
res_len, int auto_flags)
char* zxid_idp_list_cf(struct zxid_conf* cf, int* res_len, int auto_flags)
char* zxid_idp_list_len(int conf_len, char* conf, int* res_len, int auto_fla\
gs)
char* zxid_idp_list(char* conf, int auto_flags)
3395
3396
3397
struct zx_str* zxid_idp_select_zxstr_cf_cgi(struct zxid_conf* cf, struct zxi\
d_cgi* cgi, int auto_flags)
3398
3399
3400
3401
3402
3403
struct zx_str* zxid_idp_select_zxstr_cf(struct zxid_conf* cf, int auto_flags)
char* zxid_idp_select_cf(struct zxid_conf* cf, int* res_len, int auto_flags)
char* zxid_idp_select_len(int conf_len, char* conf, int* res_len, int auto_f\
lags)
char* zxid_idp_select(char* conf, int auto_flags)
3404
3405
struct zx_str* zxid_ses_to_ldif(struct zxid_conf* cf, struct zxid_ses* ses)
3406
3407
3408
char* zxid_simple_render_ses(struct zxid_conf* cf, struct zxid_ses* ses, int\
* res_len, int auto_flags)
3409
3410
3411
static char* zxid_simple_show_meta(struct zxid_conf* cf, struct zxid_cgi* cg\
i, int* res_len, int auto_flags)
3412
3413
3414
/* NULL return means the not logged in processing is needed, see zxid_simple\
_no_ses_cf() */
3415
3416
3417
char* zxid_simple_ses_active_cf(struct zxid_conf* cf, struct zxid_cgi* cgi, \
struct zxid_ses* ses, int* res_len, int auto_flags)
3418
3420
char* zxid_simple_no_ses_cf(struct zxid_conf* cf, struct zxid_cgi* cgi, stru\
ct zxid_ses* ses, int* res_len, int auto_flags)
3421
17.4
3419
3422
Generating HTML for Logout button or Management Screens
3427
char* zxid_fed_mgmt_cf(struct zxid_conf* cf, int* res_len, int sid_len, char\
* sid, int auto_flags)
char* zxid_fed_mgmt_len(int conf_len, char* conf, int* res_len, char* sid, i\
nt auto_flags)
char* zxid_fed_mgmt(char* conf, char* sid, int auto_flags)
3428
17.5
3423
3424
3425
3426
3429
3430
3431
Explicitly Calling PEP (which makes SOAP/XACML
call to PDP)
Although a simple PEP functionality is built-in to zxid_simple() API through configuration options like PEPMAP, LOCALPDP_* family, and PDP_URL, it is sometimes deJanuary 29, 2011
17.5. EXPLICITLY CALLING PEP (WHICH MAKES SOAP/XACML CALL TO
PDP)
3437
sirable to implement a Policy Enforcement Point (PEP) at application layer where full
particluars of the request or response are available. To assist in this, the simple API provides authorization client, which we term PEP because at protocol layer it is a XACML
PEP, which your application code can call to implement the protocols specifics of calling a PDP. However, your own code still needs to implement the actual enforcement or
filtering logic.
3438
17.5.1
3432
3433
3434
3435
3436
3439
3440
3441
3442
zxid_az(conf, qs, sesid)
conf the configuration will need to have PEPMAP and PDP_URL options set according to
your situation.
qs if supplied, any CGI variables are imported to session environment as attributes
(according to INMAP). Format is CGI Query String.
3445
sesid attributes are obtained from the session, if supplied (see also CGI). The session
ID is supplied as a string. If none is supplied, then session will be entirely defined
by the CGI attributes.
3446
returns 0 if deny (for any reason, e.g. indeterminate), or 1 if permit
3443
3444
3447
3448
This function calls underlying zxid_pep_az_soap() with the difference that it is possible
to import attributes to the session via CGI string.
3452
The XACML request is constructed by applying PEPMAP configuration to the attributes
in the session. For this to work, the PEPMAP MUST have subj, rsrc, and act stanzas
and should have env stanza if you have environment attributes to pass. See zxid-conf.pd
for further information and default values.
3453
Variants
3449
3450
3451
3454
3455
3456
3457
3458
zxid_az_cf(cf, qs, sesid)
The configuration is received as binary object, usually obtained from zxid_conf_to_cf_len().
This avoids reparsing configuration in case multiple calls are made. Typically the same
configuration object might have been used with zxid_simple_cf().
zxid_az_cf_ses(cf, qs, ses)
3460
Both configuration and session are supplied as binary objects, such as may have been
received from zxid_conf_to_cf_len() and zxid_alloc_ses() as used with zxid_simple_cf_ses().
3461
Example Pseudocode
3459
3462
3463
3464
3465
3466
3467
3468
3469
3470
3471
cf = zxid_new_conf();
ses = zxid_alloc_ses(cf);
ret = zxid_simple_cf_ses(cf, 0, $QUERY_STRING, ses, 0, 0x1800);
if (ret =~ /^d/) {
perr "SSO ok, now checking authorization";
if (zxid_az(cf, "", ses))
perr "Permit, add code to deliver application content";
else
perr "Deny, send back an error";
}
January 29, 2011
17.5. EXPLICITLY CALLING PEP (WHICH MAKES SOAP/XACML CALL TO
PDP)
3472
17.5.2
3473
The simple PEP is based on this function:
3474
3475
zxid_pep_az_soap() - Underlying PEP Function
int zxid_pep_az_soap(struct zxid_conf* cf, struct zxid_cgi* cgi, struct zxid_ses* ses)
In particular
3477
cf the configuration will need to have PEPMAP and PDP_URL options set according to
your situation.
3478
cgi if non-null, will resceive error and status codes
3476
3480
ses all attributes are obtained from the session. You may wish to add additional attributes that are not known by SSO.
3481
returns 0 if deny (for any reason, e.g. indeterminate), or 1 if permit
3479
3482
3483
The XACML request is constructed by applying PEPMAP configuration to the attributes
in the session.
January 29, 2011
3484
3485
3486
Chapter 18
Miscellaneous Function
Documentation
125
CHAPTER 18. MISCELLANEOUS FUNCTION DOCUMENTATION
many_callers
get_ent_ss
get_meta_ss
addmd
lscot_line
get_ent_from_cache
load_cot_cache
load_cot_cache_from_file
get_meta
get_ent_by_succinct_id
get_ent_by_sha1_name
get_ent_from_file
parse_meta
Figure 18.1: Relevant parts of the call graph for metadata fetching.
January 29, 2011
3487
3488
3489
3490
3491
Chapter 19
Raw API: Full Control, You
Decide
The generated aspects of the native C API are in c/*-data.h, for example
c/zx-sa-data.h
3492
Studying this file is very instructive.1
3493
19.1
C Data Structures
3498
From .sg a header (NN-data.h) is generated. This header contains structs that represent the data of the elements. Each element and attribute generates its own node.
Even trivial nodes like strings have to be kept this way because the nodes form basis of remembering the ordering of data. This ordering is needed for exclusive XML
canonicalization, and thus for signature verification.2
3499
Any missing data is represented by NULL pointer.
3494
3495
3496
3497
3500
3501
3502
3503
Any repeating data is kept as a linked list, in reverse order of being seen in the data
stream.3
Simple elements and all attributes are represented by simple string node (even if they
are booleans or integers).
1 emacs tip: run ‘make tags’ and then try hitting M-. while cursor is over a struct or function name in
c/zx-sa-data.h - this makes navigation painless.
2 It’s unfortunate that the XML standards do not make this any easier. Without order maintenance requirement, it would be possible to represent trivial child elements directly as struct fields. An approach that tried
to do just this is available from CVS tag GEN_LALR (ca. 29.5.2006).
3 Reverse order is just an optimization - or an artifact of simply adding latest element to the head of the
list. If this bothers you, it’s easy enough to reverse the list afterwards. Linked list is simple and works well
for data whose order does not matter much (we use separate pointer for remembering the canonicalization
order) and where random access is not needed, or cardinality is low enough so that simple pointer chasing is
efficient enough.
127
19.1. C DATA STRUCTURES
CHAPTER 19. RAW API: FULL CONTROL, YOU DECIDE
3504
Example
3505
Consider following XML
3506
3507
3508
3509
3510
3511
3512
3513
3514
3515
3516
3517
3518
3519
3520
3521
3522
3523
3524
<ds:Signature>
<ds:SignedInfo>
<ds:CanonicalizationMethod
Algorithm="http://w3.org/xml-exc-c14n#"/>
<ds:SignatureMethod
Algorithm="http://w3.org/xmldsig#rsa-sha1"/>
<ds:Reference
URI="#RrcrNwFIw6n">
<ds:Transforms>
<ds:Transform
Algorithm="http://w3.org/xml-exc-c14n#"/>
<ds:Transform
Algorithm="http://w3.org/xmldsig#env-sig"/></>
<ds:DigestMethod
Algorithm="http://w3.org/xmldsig#sha1"/>
<ds:DigestValue>lNIzVMrp8CwTE=</></></>
<ds:SignatureValue>GeMp7LS...vnjn8=</></>
Decoding would produce the data structure in Fig-??. You should also look at c/zx-sa-data.h
to see the structs involved in this example.
GRAPHIC (decode-data)
Figure 19.1: Typical data structure produced by decode.
3525
3526
3527
3528
3529
3530
3531
3532
3533
3534
3535
3536
3537
3538
3539
3540
3541
3542
There are two pointer systems at play here. The black solid arrows depict the logical structure of the XML document. For each child element there is a struct field
that simply points to the child. If there are multiple occurrences of the child, as in
sig->SignedInfo->Reference->Transforms->Transform, the children are kept in
a linked list connected by gg.g.n (next) fields.4
The wire order structure, depicted by red hollow arrows, is maintained using gg.kids
and gg.g.wo fields. For example sig->SignedInfo->Reference->Transforms keeps
its kids, the zx_ds_Transform objects, in the original order hanging from the kids and
linked with the wo field. As can be seen, the order kept with wo fields can be different than the one kept using n (next) fields. What’s more, the kids list can contain
dissimilar objects, witness sig->SignedInfo->Reference->gg.kids. The wire order representation is only captured when decoding the document and is mainly useful
for correctly canonicalizing the document for signature verification. If you are building a data structure in your own program, you typically will not set the gg.kids and
gg.g.wo fields.
In the diagram, the objects of type zx_str were collapsed to double quoted strings. Superfluous gg.kids, gg.g.wo, and gg.g.n fields were omitted: they exist in all structures, but are not shown when they are NULL. The NULL is depicted as zero (0).5
4 This linked list may be in inverted order depending on the phase of the moon and position of the trams
in Helsinki. Until implementation matures, its better not to depend on the ordering.
5 All this gg.g business is just C’s way of referencing the fields of a common base type of element objects.
January 29, 2011
3543
19.1.1
Handling XML Namespaces
3547
An annoying feature of XML documents is that they have variable namespace prefixes.
The namespace prefix for the unqualified elements is taken to be the one specified in
target() directive of the .sg input. Name of an element in C code is formed by prefixing
the element by the namespace prefix and an underscore.
3548
Attributes will only have namespace prefix if such was expressly specified in .sg input.
3544
3545
3546
3549
3550
3551
3552
3553
3554
3555
3556
3557
3558
3559
3560
3561
3562
3563
3564
3565
3566
3567
When decoding, the actual namespace prefixes are recorded. The wire order encoder
knows to use these recorded prefixes so that accurate canonicalization for XMLDSIG
can be produced.
If the message on wire uses wrong namespaces, the wrong ones are remembered so that
canonicalization for signature validation will work irrespective. The ability to accept
wrong namespaces only works as long as there is no ambiguity as to which tag was
meant - there are some tags that need namespace information to distinguish. If you
hit one of these then either you get lucky and the one that is arbitrarily picked by the
decoder happens to be the correct one, or you are stuck with no easy way to make it
right. Of course the XML document was wrong to start with so theoretically this is
not a concern. Generally the more schemata that are simultaneously generated to one
package, the greater the risk of collisions between tags.
The schema order encoder always uses the prefixes defined using target() directives in
.sg files. The runtime notion of namespaces is handled by ns_tab field of the decoding
and encoding context. It is initialized to contain all namespaces known by virtue of
.sg declarations. The runtime assigned prefixes are held in a linked list hanging from
n (next) field of struct zx_ns_s.
The code generation creates a file, such as c/zx-ns.c, which contains initialization
for the table. The main program should point the ns_tab field of context as follows:
3572
main {
struct zx_ctx* ctx;
...
ctx->ns_tab = zx_ns_tab;
}
3573
Consider the following evil contortion
3568
3569
3570
3571
3574
3575
3576
3577
3578
3579
3580
3581
3582
3583
/* Here zx_ is the prefix chosen in code generation */
<e:E xmlns:e="uri">
<h:H xmlns:h="uri"/>
<b:B xmlns:b="uri">
<e:C xmlns:e="uri"/>
<e:D xmlns:e="iru">
<e:F xmlns:e="uri"/></></></>
Assuming the ns_tab assigns prefix y to the namespace URI, we would have following
data structure as a result of a decode
The red hollow arrows indicate how the elements reference the namespaces. Since none
of the elements used the prefix originally specified in the schema grammar target()
January 29, 2011
E
B
C
H
D
F
ns_tab
y
uri
z
iru
e
uri
e
iru
h
uri
b
uri
0
0
Figure 19.2: Decode of XML and resulting namespace structures.
3584
3585
3586
3587
3588
3589
3590
3591
3592
3593
3594
3595
3596
directive, we ended up allocating "alias" nodes for the uri. However, since E and C use
the same prefix, they share the alias node. Things get interesting with D: it redefines
the prefix e to mean different namespace URI, "iru", which happens to be an alias of
prefix z.
Later, when wire order canonical encode is done, the red thin arrows are chased to
determine the namespaces. However, we need to keep a separate "seen" stack to track
whether parent has already declared the prefix and URI. E would declare xmlns:e="uri",
but C would not because it had already been "seen". However, F would have to declare
it again because the xmlns:e="iru" in D masks the declaration. The zx_ctx structure
is used to track the namespaces and "seen" status through out decoders and encoders.
Here we can see how the seen_n list, represented by the blue dotted arrows, was built:
at the head of the list, ctx->seen_n, is the last seen prefix, namely b (because, although
the meaning of e at F was different, e as a prefix had already been seen earlier at E),
January 29, 2011
E
B
D
H
C
F
ns_tab
P
URI
S
SN
y
uri
0
0
z
iru
0
0
N
e
uri
0
e
uri
0
0
h
uri
0
b
uri
0
0
ctx
e
iru
0
0
ns_tab
seen_n
Figure 19.3: Seen data structure (blue dotted and green dashed arrows) in the end of decoding
F. S=seen, SN=seen_n.
3603
followed by other prefixes in inverse order of first occurrence.6 The green dashed
arrows from e:uri to e:iru and then on to second e:uri reflect the fact that e:uri (second)
was put to the list first (when we were at E), but later, at D, a different meaning, iru,
was given to prefix e. Finally at F we give again a different meaning for e, thus pushing
to the "seen stack" another node. Although e at E and at F have namespace URI, "uri",
we are not able to use the same node because we need to keep the stack order. Thus we
are forced to allocate two identical nodes.
3604
19.1.2
3597
3598
3599
3600
3601
3602
3605
3606
3607
3608
3609
3610
3611
3612
3613
3614
3615
Handling any and anyAttribute
Since our aim is to be lax in what we accept, every element can handle unexpected additional attributes as well as unexpected elements. Thus whether the schema specifies
any or anyAttribute or not, we handle everything as if they were there. However, when
attributes and elements are received outside of their expected context, they are simply
treated as strings with string names. This is true even for those attributes and elements
that would be recognizable in their proper context.
The any extension points, as well as some bookkeeping data are hidden inside ZX_ELEM_EXT
macro. If you tinker with this macro, be sure you know what you are doing. If you
want to add your own specific fields to all structs, redefining ZX_ELEM_EXT may be
appropriate, but if you want to add more fields only to some specific structures, you
can define a macro of form
6 This is a mere artifact of implementation: it’s cheapest to add to the head of the list. This may change
in future.
January 29, 2011
3616
TPF_EEE_EXT
3621
and put in it whatever fields you want. These fields will be initialized to zero when
the structure is created, but are not touched in any other way by the generated code. In
particular, if some of your fields are pointers, it will be your responsibility to free them.
The standard free functions will not understand to free them. See the data structure
walking functions, below for one way to accomplish this.
3622
19.1.3
3623
The root data structure
3617
3618
3619
3620
3624
Root data structure
struct zx_root_s;
3625
is a special structure that has a field for every top level recognizable element.
3626
19.1.4
3627
*** TBW
3628
19.1.5
3629
3630
3631
3632
3633
3634
3635
3636
Per element data structures
Memory Allocation
After decoding all string data points directly into the input buffer, i.e. strings are NOT
copied. Be sure to not free the input buffer until you are done processing the data
structure. If you need to take a copy of the strings, you will need to walk the data
structure as a post processing step and do your copies. This can be done using
void TPF_dup_strs_len_NS_EEE(struct zx_dec_ctx* c, struct TPF_NS_EEE_s* x);
The structures are allocated via ZX_ZALLOC() macro, which by default calls zx_zalloc()
function, which in turn uses system malloc(3). However, you can redefine the macro
to use whatever other allocation scheme you desire.
3639
The generated libraries never free(3) memory. In many programming patterns, this is
actually desirable: for example a CGI program can count on dying - the process exit(2)
will free all the memory.
3640
If you need to free(3) the data structure, you will need to walk it using
3637
3638
3641
3642
3643
3644
3645
3646
void TPF_free_len_NS_EEE(struct zx_dec_ctx* c,
struct TPF_NS_EEE_s* x,
int free_strings);
void zx_free_any(struct zx_dec_ctx* c,
struct zx_note_s* n,
int free_strs);
January 29, 2011
CHAPTER 19. RAW API: 19.2.
FULLDECODER
CONTROL,AS
YOU
RECURSIVE
DECIDE DESCENT PARSER
3648
The zx_free_any() works by having a gigantic switch statement that calls the appropriate specific free function.
3649
You can deep clone the data structure with
3647
3650
3651
3652
3653
3654
3655
void TPF_deep_clone_NS_EEE(struct zx_dec_ctx* c,
int dup_strings);
struct zx_note_s* zx_clone_any(struct zx_dec_ctx* c,
struct zx_note_s* n,
int dup_strs);
3657
The zx_clone_any() works by having a gigantic switch statement that calls the appropriate specific free function.
3658
19.2
3659
The entry point to the decoder is
3656
3660
3661
3662
3663
3664
3665
3666
3667
3668
3669
3670
3671
3672
3673
3674
3675
3676
3677
3678
3679
3680
Decoder as Recursive Descent Parser
struct zx_root_s* zx_DEC_root(struct zx_dec_ctx* c,
struct zx_ns_s* dummy,
int n_decode);
The decoding context holds pointer to the raw data and must be initialized prior to
calling the decoder. The third argument specifies how many recognized elements are
decoded before returning. Usually you would specify 1 to consume one top level element from the stream.7
The returned data structure, struct zx_root_s, contains one pointer for each type of
top level element that can be recognized. The tok field of the returned value identifies
the last top level element recognized and can be used to dispatch to correct request
handler:
zx_prepare_dec_ctx(c, TPF_ns_tab, start_ptr, end_ptr);
struct TPF_root_s* x = TPF_DEC_root(c, 0, 1);
switch (x->gg.g.tok) {
case TPF_NS_EEE_ELEM: return process_EEE_req(x->NN_EEE);
}
When processing responses, it is generally already known which type of response you
are expecting, so you can simply check for NULLness of the respective pointer in the
returned data structure.
Internally zx_DEC_root() works much the same way: it scans a beginning of an element from the stream, looks up the token number corresponding to the element name,
7 The second argument, the dummy namespace, is meaningless for root node, but makes sense for element
decoders. For root you can simply supply 0 (NULL).
January 29, 2011
19.2. DECODER AS RECURSIVE
CHAPTER 19.DESCENT
RAW API:
PARSER
FULL CONTROL, YOU DECIDE
3681
3682
and switches on that, calling element specific decoder functions (see next section) to
do the detailed processing.
3688
In the above code fragment, you should note the call to zx_prepare_dec_ctx() which
initializes the decoder machinery. It takes ns_tab argument, which specifies which
namespaces will be recognized. This table MUST match the TPF_DEC_root() function
you call (i.e. both must have been generated as part of the same xsd2sg.pl invocation).
The other arguments are the start of the buffer to decode and pointer one past the end
of the buffer to decode.
3689
19.2.1
3690
For each recognizable element there is a function of form
3683
3684
3685
3686
3687
3691
3692
3693
3694
Element Decoders
struct TPF_NS_EEE_s* zx_DEC_NS_EEE(struct zx_dec_ctx* c);
where TPF is the prefix, NS is the namespace prefix, and EEE is the element name. For
example:
struct zx_se_Envelope_s* zx_DEC_se_Envelope(struct zx_ctx* c);
3700
These functions work much the same way as the root decoder. You should consult
dec-templ.c for the skeleton of the decoder. Generally you should not be calling
element specific decoders: they exist so that zx_DEC_root() can call them. They have
somewhat nonintuitive requirements, for example the opening <, the namespace prefix,
and the element name must have already been scanned from the input stream by the
time you call element specific decoder.
3701
19.2.2
3702
The generated code is instrumented with following macros
3703
ZX_ATTR_DEC_EXT(ss) Extension point called just after decoding known attribute
3704
ZX_XMLNS_DEC_EXT(ss) Extension point called just after decoding xmlns attribute
3695
3696
3697
3698
3699
3705
3706
Decoder Extension Points
ZX_UNKNOWN_ATTR_DEC_EXT(ss) Extension point called just after decoding unknown attr
3708
ZX_START_DEC_EXT(x) Extension point called just after decoding element name
and allocating struct, but before decoding any of the attributes.
3709
ZX_END_DEC_EXT(x) Extension point called just after decoding the entire element.
3707
3710
3711
3712
3713
ZX_START_BODY_DEC_EXT(x) Extension point called just after decoding element
tag, including attributes, but before decoding the body of the element.
ZX_PI_DEC_EXT(pi) Extension point called just after decoding processing instruction
January 29, 2011
CHAPTER 19. RAW19.3.
API: EXCLUSIVE
FULL CONTROL,
CANONICAL
YOU DECIDE
ENCODER (SERIALIZER)
3715
ZX_COMMENT_DEC_EXT(comment) Extension point called just after decoding comment
3716
ZX_CONTENT_DEC(ss) Extension point called just after decoding string content
3714
3718
ZX_UNKNOWN_ELEM_DEC_EXT(elem) Extension point called just after decoding unknown element
3719
Following macros are available to the extension points
3720
TPF Type prefix (as specified by -p during code generation)
3721
EL_NAME Namespaceful element name (NS_EEE)
3722
EL_STRUCT Name of the struct that describes the element
3723
EL_NS Namespace prefix of the element (as seen in input schema)
3724
EL_TAG Name of the element without any namespace qualification.
3725
19.3
3717
3726
3727
3728
3729
3730
3731
3732
3733
3734
3735
3736
3737
3738
3739
3740
3741
3742
3743
3744
3745
3746
3747
3748
Exclusive Canonical Encoder (Serializer)
The encoder receives a C data structure and generates a gigantic string containing an
XML document corresponding to the data structure and the input schemata. The XML
document conforms to the rules of exclusive XML canonicalization and hence is useful
as input to XMLDSIG.
One encoder is generated for each root node specified at the code generation. Often
these encoders share code for interior nodes.
The encoders allow two pass rendering. You can first use the length computation
method to calculate the amount of storage needed and then call one of the rendering functions to actually render. Or if you simply have large enough buffer, you can
just render directly.
The encoders take as argument next free position in buffer and return a char pointer
one past the last byte used. Thus you can discover the length after rendering by subtracting the pointers. This is guaranteed to result same length as returned by the length
computation method.8 You can also call the next encoder with the return value of the
previous encoder to render back-to-back elements.
The XML namespace and XML attribute handling of the encoders is novel in that the
specified sort is done already at code generation time, i.e. the renderers are already in
the order that the sort mandates.
For attributes we know the sort order directly from the schema because [?], sec 2.2,
p.7, specifies that they sort first by namespace URI and then by name, both of which
we know from the schema.
For xmlns specifications the situation is similarly easy in the schema order encoder case
because we know the namespace prefixes already at code generation time. However,
8 This
is a useful sanity check. If the two ever disagree, please report a bug.
January 29, 2011
19.3. EXCLUSIVE CANONICAL
CHAPTER 19.
ENCODER
RAW API:
(SERIALIZER)
FULL CONTROL, YOU DECIDE
3754
for the wire order encoder we actually need a runtime sort because we can not control
which namespace prefixes get used. However, for both cases we can make a pretty
good guess about which namespaces might need to be declared at any given element:
the element’s own namespace and namespaces of each of its attributes. That’s all,
and it’s all known at code generation time. At runtime we only need to check if the
namespace has already been seen at outer layer.
3755
19.3.1
3749
3750
3751
3752
3753
3756
3757
3758
3759
3760
3761
3762
3763
3764
3765
3766
3767
3768
3769
3770
3771
3772
3773
3774
3775
3776
3777
3778
Length computation
Compute length of an element (and its subelements). The XML attributes and elements
are processed in schema order.
int TPF_LEN_SO_NS_EEE(struct zx_ctx* c,
struct TPF_NS_EEE_s* x);
For example:
int zx_LEN_SO_se_Envelope(struct zx_ctx* c,
struct zx_se_Envelope_s* x);
Compute length of an element (and its subelements). The XML namespaces and elements are processed in wire order.
int TPF_LEN_WO_NS_EEE(struct zx_ctx* c,
struct TPF_NS_EEE_s* x);
For example:
int zx_LEN_WO_se_Envelope(struct zx_ctx* c,
19.3.2
Encoding in schema order
Render an element into string. The XML elements are processed in schema order. The
xmlns declarations and XML attributes are always sorted per [?] rules.9 This is what
you generally want for rendering new data structure to a string. The wo pointers are
not used.
char* TPF_ENC_SO_NS_EEE(struct zx_ctx* c,
char* p);
For example:
9 The
sort is actually done already at code generation time by xsd2sg.pl.
January 29, 2011
CHAPTER 19. RAW API: FULL CONTROL, YOU
19.4.
DECIDE
SIGNATURES (XMLDSIG)
3779
3780
3781
3782
3783
3784
3785
char* zx_ENC_SO_se_Envelope(struct zx_ctx* c,
struct zx_se_Envelope_s* x,
char* p);
Since it is a very common requirement to allocate correct sized buffer and then render
an element, a helper function is provided to do this in one step.
struct zx_str* zx_EASY_ENC_SO_se_Envelope(struct zx_ctx* c,
3786
The returned string is allocated from allocation arena described by zx_ctx.
3787
19.3.3 Encoding in wire order
3788
3789
3790
3791
3792
3793
3794
3795
3796
3797
3798
3799
3800
3801
3802
3803
Render element into string. The XML elements are processed in wire order by chasing
wo pointers. This is what you want for validating signatures on other people’s XML
documents. If the wire representation was schema invalid, e.g. elements were in wrong
order, the wire representation is still respected, except for xmlns declarations and XML
attributes, which are always sorted, per exc-c14n rules. For each element a function is
generated as follows
char* TPF_ENC_WO_NS_EEE(struct zx_ctx* c,
char* p);
For example
char* zx_ENC_WO_se_Envelope(struct zx_ctx* c,
struct zx_se_Envelope_s* x,
char* p);
A helper function is also available
struct zx_str* zx_EASY_ENC_WO_se_Envelope(struct zx_ctx* c,
3804
19.4
Signatures (XMLDSIG)
3805
19.4.1
Signature Generation
3806
*** TBW
January 29, 2011
19.4. SIGNATURES (XMLDSIG)
3807
3808
3809
3810
3811
3812
3813
3814
3815
3816
3817
19.4.2
Signature Validation
For signature validation you need to walk the decoded data structure to locate the signature as well as the references and pass them to zxsig_validate(). The validation involves
wire order exclusive canonical encoding of the referenced XML blobs, computation of
SHA1 or MD5 checksums over them, and finally computation of SHA1 check sum over
the <SignedInfo> element and validation of the actual <SignatureValue> against
that. The validation involves public key decryption using the signer’s certificate.
A nasty problem in exclusive canonicalization is that the namespaces that are needed in
the blob may actually appear in the containing XML structures, thus in order to know
the correct meaning of a namespace prefix, we need to perform the seen computation
for all elements outside and above the blob of interest.10
3823
To verify signature, you have to do certain amount of preparatory work to locate the
signature and the data that was signed. Generally what should be signed will be evident from protocol specifications or from the security requirements of your application
environment. Conversely, if there is a signature, but it does not reference the appropriate elements, its worthless and you might as well reject the document without even
verifying the signature.
3824
Example
3818
3819
3820
3821
3822
3825
3826
3827
struct zxsig_ref refs[1];
cf = zxid_new_conf("/var/zxid/");
ent = zxid_get_ent_from_file(cf, "YV7HPtu3bfqW3I4W_DZr-_DKMP4.");
3828
3829
3830
3831
3832
3833
3834
3835
3836
3837
3838
3839
3840
3841
3842
3843
3844
3845
3846
refs[0].ref = r->Envelope->Body->ArtifactResolve
->Signature->SignedInfo->Reference;
refs[0].blob = (struct zx_elem_s*)r->Envelope->Body->ArtifactResolve;
res = zxsig_validate(cf->ctx, ent->sign_cert,
r->Envelope->Body->ArtifactResolve->Signature,
1, refs);
if (res == ZXSIG_OK) {
D("sig vfy ok %d", res);
} else {
ERR("sig vfy failed due to(%d)", res);
}
This code illustrates
1. You have to determine who signed and provide the entity object that corresponds
to the signer. Often you would determine the entity from <Issuer> element somewhere inside the message.
The entity is used for retrieving the signing certificate. Another alternative is that
the signature itself contains a <KeyInfo> element and you extract the certificate
from there. You would still need to have a way to know if you trust the certificate.
10 This is yet another indication of how botched the XML namespace concept is. Or this could have been
fixed in the exclusive canonicalization spec by not using namespace prefixes at all.
January 29, 2011
CHAPTER 19. RAW API: FULL CONTROL,
19.5.
YOU
DATA
DECIDE
ACCESSOR FUNCTIONS
3847
3848
3849
3850
3851
3852
3853
3854
3855
3856
3857
3858
3859
3860
3861
3862
2. You have to prepare the refs array. It contains pairs of <SignedInfo><Reference>
specifications combined with the actual elements that are signed. Generally the
URI XML attribute of the <Reference> element points to the data that was signed.
However, it is application dependent what type of ID XML attribute the URI actually references or the URI could even reference something outside the document.
It would be way too unreliable for the zxsig_validate() to attempt guessing how to
locate the signed data: therefore we push the responsibility to you. Your code will
have to walk the data to locate all referenced bits and pieces.
In the above example, locating the one signed bit was very easy: the specification
says where it is (and this location is fixed so there really is no need to check the URI
either).
You pass the length of the refs array and the array itself as two last arguments to
zxsig_validate().
3. You need to locate the <Signature> element in the document and pass it as argument to zxsig_validate(). Usually a protocol specification will say where the
<Signature> element is to be found, so locating it is not difficult.
3864
4. The return value will indicate validation status. ZXSIG_OK, which has numerical
value of 0, indicates success. Other nonzero values indicate various kinds of failure.
3865
19.4.3
3863
3866
3867
3868
Certificate Validation and Trust Model
Trust models for TLS and signature validation are separate. TLS layer is handled
mainly by libcurl or in case of ClientTLS, by the https web server (which is not part of
zxid).
3874
In signature validation the primary trust mechanism is that entity’s metadata specifies
the signing certificate and there is no Certification Authority check at all.11 This model
works well if you control the admission to your CoT. However, ZXID ships by default
with the automatic CoT feature turned on, thus anyone can get added to the CoT and
therefore signature with any certificate they declare is "valid". This hardly is acceptable
for anything involving money.
3875
19.5
3869
3870
3871
3872
3873
3876
3877
3878
3879
3880
Data Accessor Functions
Simple read access to data should, in C, be done by simply referencing the fields of the
struct, e.g.
if (!r->EntitiesDescriptor->EntityDescriptor)
goto bad_md;
*** TBW
11 If
you develop CA check, please submit patches to ZXID project.
January 29, 2011
19.6. MEMORY ALLOCATION
CHAPTERAND
19. RAW
FREEAPI: FULL CONTROL, YOU DECIDE
3881
19.6
3882
*** TBW
3883
19.7
3884
*** TBW
3885
19.8
3886
3887
Memory Allocation and Free
Walking the data structure
Thread Safety
All generated libraries are designed to be thread safe, provided that the underlying libc
APIs, such as malloc(3) are thread safe.
January 29, 2011
3888
3889
3890
3891
3892
3893
3894
3895
3896
3897
3898
3899
Chapter 20
Creating New Interfaces Using
ZXID Methodology
The ZXID code generation methodology can be used to create interfaces to any XML
document or protocol that can be described as a Schema Grammar (which includes any
document that can be expressed as XML Schema - XSD). The general steps are
1. Convert .xsd file to .sg, or write the .sg directly. For conversion, you would
typically use a command like
~/pd/xsd2sg.pl <foo.xsd >foo.sg
2. Tweak and rationalize the resulting .sg file. In ideal world any construct expressible
as .xsd should be nicely representable, but in practise some work better than others,
thus you can create a much nicer interface if you invest in some manual tweaking.
3901
Note that the tweaked .sg still is able to represent the same document as the original
.xsd described, though often the tweaking causes some relaxation.
3902
Most common tweaks
3900
3903
3904
3905
3906
3907
3908
3909
3910
3911
3912
3913
3914
a. If the .xsd is written so that the targeted namespace is also the default namespace, you should introduce a namespace prefix because this is needed during
code generation to keep different C identifiers from clashing with each other.
Ideally you should coordinate the namespace prefixes globally so that even two
different projects will not clash.
b. Where the choice construct is used, indicated by pipey symbol (|) in the .sg file,
you should refactor these into sequences of zero-or-one occurrence (?) instances
of the alternatives of the choice. This is needed because for the foreseeable
future xsd2sg.pl has a limitation in code generation feature. If the choice has
maxOccurs="unbounded" you should use (*) instead.
c. xml:lang and other similar attributes may need to be factored open to be just of
type %xs:string. This is a bug in xsd2sg.pl
141
CHAPTER 20. CREATING NEW INTERFACES USING ZXID METHODOLOGY
3915
3916
3917
3918
3919
3920
3921
3922
3923
3924
3925
3926
3927
3. "Connect" the schema to bigger framework. Usually this means adding your schema
grammar to the ZX_SG variable in zxid/Makefile and supplying additional -r
flags in ZX_ROOT variable. This allows your new schema to be visible at top level.
If your schema is meant to extend leafs or interior nodes of the parse tree, such
as SOAP Body, you would edit the SOAP schema to accept your new protocol elements in the Body. Or that the generic SOAP header can accept your specific header
schemata, or that the SAML attribute definitions accept your kind of attributes whatever makes sense in your context.
Alternative to this is to create an entirely new monolithic encoder decoder, i.e. instead of extending the existing ZXID project to accommodate your new protocol,
you just start a new project that uses the same methodology. You should see how
the SAML protocol part is separated from the SAML metadata parsing and from the
WSF parsing in the existing project.
January 29, 2011
3928
3929
3930
Chapter 21
Code Generation Tools
Main work horse of code generation is xsd2sg.pl, which serves multiple purposes
3933
1. Build hashes of all declarations in .sg input. Each hash element consists of array
of elements and attributes, as well as groups and attribute groups. The type of array
element sis determined from prefix, per .sg rules.
3934
2. Expand groups and attribute groups
3935
3. Evaluate each element wrt its type and generate
3931
3932
3936
a. C data structures
3937
b. Decoder grammar
3938
c. Token descriptions for perfect hash and lexical analyzer
3939
d. Encoder C code
3941
The code to build hashes is interwoven in the code that generates .xsd from .sg. The
rest of the generation happens in a function called generate().
3942
Typical command line (to generate SAML 2.0 protocol engine)
3940
3951
~/plaindoc/xsd2sg.pl -d -gen saml2 -p zx_ \
-r saml:Assertion -r se:Envelope \
-S \
sg/saml-schema-assertion-2.0.sg \
sg/saml-schema-protocol-2.0.sg \
sg/xmldsig-core.sg \
sg/xenc-schema.sg \
sg/soap11.sg \
>/dev/null
3952
To generate SAML 2.0 Metadata engine you would issue
3943
3944
3945
3946
3947
3948
3949
3950
143
21.1. SPECIAL SUPPORT FOR SPECIFIC
CHAPTER
PROGRAMMING
21. CODE GENERATION
LANGUAGES
TOOLS
3953
3954
3955
3956
3957
3958
3959
3960
3961
3962
3963
3964
3965
3966
3967
3968
~/plaindoc/xsd2sg.pl -d -gen saml2md -p zx_ \
-r md:EntityDescriptor -r md:EntitiesDescriptor \
-S \
sg/saml-schema-assertion-2.0.sg \
sg/saml-schema-metadata-2.0.sg \
sg/xmldsig-core.sg \
sg/xenc-schema.sg \
>/dev/null
21.1
Special Support for Specific Programming Languages
While C code generation is the main output, and this can always be converted to other
languages using SWIG, sometimes a more natural language interface can be built by
directly generating it.
We plan to enhance the code generation to do something like this. At least direct
hash-of-hashes-of-arrays-of-hashes type data-structure generation for benefit of some
scripting languages is planned.
January 29, 2011
3969
3970
3971
Chapter 22
Identity Web Services
22.1
EPR Cache
3975
Calling an ID Web Service requires an Endpoint Reference (EPR) that indicates not
only the URL of the web service, but also the security mechanism and any tokens or
credentials required by the security mechanism, collectively called the metadata of the
EPR.1
3976
An EPR can be obtained from two sources
3972
3973
3974
3978
1. From the SSO assertion containing an attribute statement that has the EPR. This is
called the bootstrap method.
3979
2. By calling the discovery service.
3980
Either way, the EPRs are cached in the SSO session as files with paths like
3977
3981
3982
3983
3984
3985
3986
3987
3988
3989
3990
3991
3992
3993
3994
3995
/var/zxid/ses/SESID/SVCTYPE,SHA1
where SESID is the SSO session ID (safe base64 of a random number). SVCTYPE
and SHA1 form a unique file name inside the session directory. SVCTYPE component
allows easy identification of the EPRs that are relevant for calling a given service. The
SHA1 component is a SHA1 hash over the canonical XML representation of the EPR.
When bootstrap EPRs are present in the SSO assertion, they are automatically extracted
to the EPR cache (internally zxid_snarf_eprs_from_ses() is called). Generally this will
yield at least bootstrap EPR for discovery service. Later, when calling web services,
discovery is automatically performed as needed and the results are automatically populated to the EPR cache (internally zxid_cache_epr() is called).
When calling higher level WSC APIs, the discovery will happen automatically, but if
you work in terms of lower level APIs, you can obtain an EPR by calling zxid_get_epr()
which will first consult the cache, and if there is a miss, then try discovering the EPR
using discovery service EPR, if any (usually one was obtained as bootstrap during the
SSO).
1 While the role of the EPR metadata is broadly similar to SAML metadata, the two should not be confused.
145
22.2. HIGH LEVEL WSC API
3996
3997
3998
3999
4000
4001
4002
4003
4004
4005
4006
4007
4008
22.2
CHAPTER 22. IDENTITY WEB SERVICES
High level WSC API
The high level API is based on the idea of constructing the SOAB body (the payload) as
a string and passing that to function that performs the SOAP call and returns response.
01
02
03
04
05
06
07
08
09
10
cf = zxid_new_conf_to_cf(CONF);
res = zxid_simple_cf(cf, cl, qs2, 0, 0x1fff);
switch (res[0]) {
default:
case ’d’: break; /* Logged in case */
}
sid = strstr(res, "sesid: ");
zxid_get_ses(cf, &sess, sid);
4009
4019
11 env = zxid_callf(cf, &sess, 0,0,0, zx_xmlns_idhrxml,
12
"<idhrxml:Modify>"
13
"<idhrxml:ModifyItem>"
14
"<idhrxml:Select>%s</idhrxml:Select>"
15
"<idhrxml:NewData>%s</idhrxml:NewData>"
16
"</idhrxml:ModifyItem>"
17
"</idhrxml:Modify>", cgi.select, cgi.data);
18 ZXID_CHK_STATUS(env, idhrxml_ModifyResponse,
19
hrxml_resp = "Modify failed"; break);
20 hrxml_resp = "Modify OK";
4020
On lines 1-10 a single sign on is done to prepare the session and EPR cache.
4021
22.2.1
4010
4011
4012
4013
4014
4015
4016
4017
4018
4022
4023
4024
4025
4026
4027
4028
4029
4030
4031
zxid_callf() - Make SOAP call with specified body
env = zxid_callf(cf, ses, svctype, url, di_opt, az_cred, fmt, ...)
zxid_callf() first creates the body of the SOAP call by expanding the format string
(which may involve additional arguments). Next it parses the string into XML data
structure. If the format string uses unresolved namespaces, they are resolved using the
svctype argument.
Next zxid_callf() will attempt to locate an EPR for the service type. This may already
be in cache, or discovery step may be performed.
Then zxid_callf() augments the XML data structure with Liberty ID-WSF mandated
headers. It will look at the security mechanism and token specified in the EPR and
perform appropriate steps to create WS-Security header and apply signature as needed.
4033
Finally a SOAP call is made. The result is XML parsed and returned as SOAP envelope
object.
4034
cf Configuration object, see zxid_new_conf_to_cf()
4032
January 29, 2011
4035
4036
4037
4038
4039
4040
4041
4042
4043
4044
4045
4046
4047
4048
22.3. LOW LEVEL WSC API
ses Session object, used to locate EPRs, see zxid_get_ses()
svctype Service type and namespace that is applicable to the body. This is one of the
constants from c/zx-ns.h
url (Optional) If provided, this argument has to match either the ProviderID, EntityID,
or actual service endpoint URL.
di_opt (Optional) Additional discovery options for selecting the service, query string
format
az_cred (Optional) Additional authorization credentials or attributes, query string format. These credentials will be populated to the attribute pool in addition to the
ones obtained from SSO and other sources. Then a PDP is called to get an
authorization decision (as well as obligations we pledge to support). See also
PEPMAP configuration option. This implementes generalized (application independent) Requestor Out and Requestor In PEPs. To implement application
dependent PEP features you should call zxid_az() directly.
4051
fmt printf style format string that is used to describe the body of the call as a string.
If fmt contains format specifiers, then additional arguments are used to expand
these.
4052
Return value SOAP envelope as a string.
4049
4050
4053
4054
4055
4056
4057
4058
4059
4060
4061
N.B. Although the request body is formulated as a string, you can only use
XML constructs whose schema is known to ZXID. The resulting XML
must be validly parseable by ZXID.
22.2.2
ZXID_CHK_STATUS() - Macro for checking OK status
ZXID_CHK_STATUS(env, resp_tag, abort-action);
ZXID_CHK_STATUS(env, idhrxml_ModifyResponse, break);
In ID-WSF web services it is very common that the overall outcome of the operation
is expressed by <Status> element at top level. This macro makes it easy to check the
status.
4064
If status is NOT "OK", then abort-action is invoked. This would be whatever needed
in your program to report error and abort further processing of the response. It could
be a break, return, or even a goto statement.
4065
env SOAP envelope representing the response
4066
resp_tag The response tag as it appears as a child of env->Body
4067
abort-action Statement, or statements, used to report error and abort processing.
4068
There is no return value. This macro is "procedural".
4062
4063
January 29, 2011
22.3. LOW LEVEL WSC API
4069
22.3
4070
Typical code for calling a web service at low level
4071
4072
4073
4074
4075
4076
4077
4078
4079
4080
4081
4082
4083
4084
4085
4086
4087
4088
4089
4090
4091
4092
4093
4094
4095
4096
4097
4098
4099
4100
4101
4102
4103
4104
4105
4106
4107
4108
01
02
03
04
05
06
07
08
09
10
11
12
13
14
15
16
17
18
19
20
21
Low Level WSC API
#include
#include
#include
#include
#include
#include
<zx/errmac.h>
<zx/zxid.h>
<zx/zxidconf.h>
<zx/saml2.h>
<zx/wsf.h>
<zx/c/zx-ns.h>
struct zx_e_Envelope_s* env;
struct zx_a_EndpointReference_s* epr;
epr = zxid_get_epr(cf, ses, zx_xmlns_dap, 1);
if (epr) {
env = zx_NEW_e_Envelope(cf->ctx);
env->Header = zx_NEW_e_Header(cf->ctx);
env->Body = zx_NEW_e_Body(cf->ctx);
env->Body->Query = zxid_mk_dap_query(cf, ...); /* See ID-DAP inteface */
env = zxid_wsc_call(cf, ses, epr, env);
/* The beef */
if (env->dap_QueryResponse)
D("Result is LDIF(%.*s)",
env->Body->dap_QueryResponse->Data->LDIF->gg.content->len,
env->Body->dap_QueryResponse->Data->LDIF->gg.content->s);
}
1. On line 10 zxid_get_epr() is used with following arguments
cf Configuration object
ses Session object (generallly obtained from SSO)
zx_xmlns_dap The service type of the service that is to be called. Generally this is
same as the namespace URI. The include <zx/c/zx-ns.h> contains macros,
such as zx_xmlns_dap, for the namespaces supported by zxid. Alternatively
you could simply supply the string.
1 The last argument ("1", one) is an iterator index that, in case of multiple EPRs
allows you to pick which one to use. Most common usage is to simply supply
1 which picks the first one.2
22.3.1
zxid_get_epr() - Obtain EPR fron cache or by discovery
epr = zxid_get_epr(cf, ses, svctype, n);
See if an EPR for service svctype is available in current session EPR cache. If not, see
if discovery EPR is available and try to discover the EPR for the svctype. Note that the
discovery is transparent to the programmer - indeed programmer can not know whether
EPR was served from cache (where it may have appeared by virtue of a bootstrap) or
whether it was discovered.
2 However, the ordering of the eprs in not currently well defined and may change from one version of
ZXID to another.
January 29, 2011
22.4. ID-DAP INTERFACE
4109
cf Configuration object, see zxid_new_conf_to_cf()
4110
ses Session object, used to locate EPRs in cache, see zxid_get_ses()
4111
4112
4113
4114
svctype Service type (usually namespace of the service). This is one of the constants
from c/zx-ns.h
n Ordinal. If more than one EPR is available, specifies which one is desired. Usually
1 is supplied, to pick the first EPR.
4116
Return Value An EPR object (URL of the service, security mechanism, and possibly
security token (SAML assertion)).
4117
22.4
4115
ID-DAP Interface
4119
The ID-DAP search filters and data model are very similar to LDAP, see [?] for further
explanation.
4120
22.4.1
4118
4121
4122
4123
4124
4125
4126
4127
4128
4129
4130
4131
4132
4133
4134
4135
4136
4137
4138
4139
4140
4141
4142
4143
4144
4145
4146
Short example of using low level API
env->Body->dap_Query
= zxid_mk_dap_query(cf,
0,
/* No tests */
zxid_mk_dap_query_item(cf,
zxid_mk_dap_select(cf,
0, /* DN from ID-WSF */
"objecttype=svcprofile",
0, /* all attributes */
1, /* chase symlinks */
ZXID_DAP_SCOPE_SUBTREE,
0, /* no size limit */
0, /* no time limit */
0), /* return data */
0, /* regular data entries */
0, /* No predefined operation */
0, /* No sorting. */
0, /* No changed since specification. */
0, /* Do not include LDAP common attributes. */
0, /* Start from first result (offset == 0) */
0, /* Return all results (count == 0) */
0, /* Do not request snapshot */
0, /* Do not refer to snapshot */
0), /* No contingent item ID reference */
0); /* No subscriptions */
As can be seen, it is common to specify nearly all arguments as 0, relying on default
values. Thus the code typically appears without comments as
January 29, 2011
4147
4148
4149
4150
4151
4152
4153
4154
4155
4156
4157
4158
4159
4160
4161
4162
4163
4164
4165
4166
4167
4168
4169
4170
4171
4172
4173
4174
4175
4176
4177
4178
4179
4180
4181
4182
4183
4184
4185
4186
4187
4188
4189
4190
4191
4192
= zxid_mk_dap_query(cf, 0,
zxid_mk_dap_select(cf, 0, "objecttype=svcprofile",
0, 1, ZXID_DAP_SCOPE_SUBTREE, 0, 0, 0),
0, 0, 0, 0, 0, 0, 0, 0, 0, 0), /* 10 zeroes here */
0); /* No subscriptions */
22.4.2
Fully winded example of using low level API
As a query can also have test and subscription clauses, the fully winded example becomes quite onerous. Of course for many daily tasks you will not need all the frills, or
you can just use the simple API instead.
= zxid_mk_dap_query(cf,
zxid_mk_dap_test_item(cf,
zxid_mk_dap_testop(cf,
0,
/* regular data entries */
0), /* No predefined operation */
0, /* Start from first result (offset == 0) */
0, /* Return all results (count == 0) */
0, /* Do not request snapshot */
0, /* Do not refer to snapshot */
zxid_mk_dap_subscription(cf,
January 29, 2011
"subsID",
0, /* No item ID reference */
zxid_mk_dap_resquery(cf,
0, /* No notification aggregation spec. */
0, /* No notification trigger spec. */
0, /* Subscription starts immediately. */
0, /* Subscription never expires. */
1, /* Include changed data in the notifications. */
0, /* Use notification reference for administrative notifications. */
"http://host/notif_sink")
4193
4194
4195
4196
4197
4198
4199
4200
4201
4202
4203
4204
4205
4206
4207
4208
4209
4210
4211
4212
4213
4214
4215
4216
4217
);
4218
4219
4220
4221
4222
4223
4224
4225
4226
4227
4228
4229
4230
4231
4232
4233
4234
4235
4236
22.4.3
zxid_mk_dap_query()
struct zx_dap_Query_s* zxid_mk_dap_query(struct
struct
struct
struct
22.4.4
zxid_conf* cf,
zx_dap_TestItem_s* tis,
zx_dap_QueryItem_s* qis,
zx_dap_Subscription_s* subs);
zxid_mk_dap_query_item()
struct zx_dap_QueryItem_s* zxid_mk_dap_query_item(struct zxid_conf* cf,
struct zx_dap_Select_s* sel,
char* objtype,
char* predef,
char* sort,
char* changed_since,
int incl_common_attrs,
int offset,
int count,
char* setreq,
char* setid,
char* contingent_itemidref);
January 29, 2011
4237
4238
4239
4240
4241
4242
4243
4244
4245
4246
4247
4248
4249
4250
4251
4252
4253
4254
4255
4256
4257
4258
4259
4260
4261
4262
4263
4264
4265
4266
4267
4268
4269
4270
4271
4272
4273
4274
4275
4276
sel Selection expression, see zxid_mk_dap_select().
objtype Either "entry", or "_Subsciption". The former is used for searching and manipulating the normal attribute data while the latter is used for manipulating subscription objects. Specifying NULL selects "entry".
predef Predefined serverside operation identifier. This is server dependent, but you
can think of it as a stored procedure. If you pass predef, it is common to leave
sel and objtype as NULL and vice versa, i.e. you should pass NULL as predef
unless you know your server to expect otherwise.
sort String specifying sorting of the result set. See ID-DAP specification for further
details. N.B. Not all servers support sorting. Pass NULL if you do not need
sorting.
changed_since LDAP date time string specifying that only entries that have changed
since specified moment should be returned.
incl_common_attrs If 1 (true), "common" LDAP attributes such as modificationtime
are included. If you do not need these attributes you can save the server some
work and also some network transmission overhead by not requesting these attributes, i.e. pass 0 (false).
offset If search matches multiple entries, the zero based index of the first entry to
return. Pass 0 to get the beginning of the result set.
count Maximum number of entries to return in the response. 0 means return all. offset
and count allow pagination through large result set. N.B. count is very different
from sizelimit that you may specify in zxid_mk_dap_select(). The latter causes
the actual backend search operation to abort or return partial result set if the
result would be too large and is unsuitable for pagination.
setreq Request creation of a result set snapshot for pagination. N.B. It is possible to
paginate through large result set even without creating a snapshot, but the results
may be inconsistent because the underlying data may change between queries
that paginate through it. Creating a snapshot avoids this problem. Whether pagination with or without snapshot is cheaper depends on the backend implementation. setreq is specified on the first query that referes to the snapshot. The
subsequent queries referring to the same snapshot will specify setid. The two are
mutually exclusive: if setid is specified the setreq must be NULL.
setid If you are paginating through a result set snapshot created using setreq, then
you must specify setid in subsequent queries that refer to same snapshot. When
specifying setreq, you muse leave setid as NULL.
contingent_itemidref A query item can be made contingent on a test item, i.e. the
query will only be made if the test succeeded. If you want this, you must pass
the item ID of the test item here. Passing NULL means that no such dependency
exists. N.B. The server side implementation of the tests may actually require a
query to be made anyway.
January 29, 2011
4277
4278
4279
4280
4281
4282
4283
4284
4285
4286
22.4.5
zxid_mk_dap_select()
struct zx_dap_Select_s* zxid_mk_dap_select(struct zxid_conf* cf,
char* dn,
char* filter,
char* attributes,
int deref_aliases,
int scope,
int sizelimit,
int timelimit,
int typesonly);
4289
dn Distinguished or relative distinguished name. Since ID-DAP usually uses the identity conveyed using ID-WSF headers to determine the distinguished name, it is
common to pass simply a NULL.
4290
filter LDAP filter to apply. NULL if none.
4291
attributes List of attributes to return. NULL means return all attributes.
4287
4288
4294
deref_aliases Boolean: whether the server should chase any "symlinks", i.e. an entry
may appear at some location as an alias that is just a pointer to the real location
of the entry. This is usually what you want so pass 1 (true).
4295
scope The scope of the ID-DAP search.
4292
4293
4296
4297
4298
4299
ZXID_DAP_SCOPE_BASE (0) Only what is pointed to by DN, e.g. one entry.
The default.
ZXID_DAP_SCOPE_SINGLE (1) Single level of directory right under DN.
ZXID_DAP_SCOPE_SUBTREE (2) Full subtree search under the DN.
4303
sizelimit Maximum number of entries to return. 0 means no limit. This is intended to
stop the server from accidentally performing expensive queries. N.B. sizelimit
is different from count, see zxid_mk_dap_query_item(), the latter is meant for
pagination of a large result set without aborting it.
4304
timelimit Maximum number of seconds to spend in the search. 0 means no limit.
4300
4301
4302
4307
typesonly If true, only attribute names are returned, without their values. This allows
an existence test to be performed without passing the values over the network.
Usually you want the values so you would pass 0 (false).
4308
22.4.6
4305
4306
4309
4310
4311
4312
zxid_mk_dap_test_item()
struct zx_dap_TestItem_s* zxid_mk_dap_test_item(struct zxid_conf* cf,
struct zx_dap_TestOp_s* tstop,
char* objtype,
char* predef);
4313
tstop See zxid_mk_dap_testop().
4314
objtype See objtype in zxid_mk_dap_query_item().
4315
predef See predef in zxid_mk_dap_query_item().
January 29, 2011
4316
4317
4318
4319
4320
4321
4322
4323
4324
4325
22.4.7
zxid_mk_dap_testop()
struct zx_dap_TestOp_s* zxid_mk_dap_testop(struct zxid_conf* cf,
char* dn,
char* filter,
char* attributes,
int deref_aliases,
int scope,
int sizelimit,
int timelimit,
int typesonly);
4329
See description of zxid_mk_dap_select(). For ID-DAP protocol the Select and TestOp
are defined to be the same. However, this need not be the case for Data Services
Template (DST) based services in general. Hence, the data types for Select and TestOp
are different (although very similar) and two separate constructors are needed.
4330
22.4.8
4326
4327
4328
4331
4332
4333
4334
4335
4336
4337
4338
4339
4340
4341
4342
4343
4344
4345
4346
4347
zxid_mk_dap_subscription()
struct zx_dap_Subscription_s* zxid_mk_dap_subscription(struct zxid_conf* cf,
char* subsID,
char* itemidref,
struct zx_dap_ResultQuery_s* rq
char* aggreg,
char* trig,
char* starts,
char* expires,
int incl_data,
char* admin_notif,
char* notify_ref);
subsID Subscription ID
itemidref When subscribing to data described by a query item, create item, or modify
item, the reference to the relevant item. NULL if no such item exists, in which
case rq is usually specified.
rq Result query that identifies the data of interest for the subscription. See zxid_mk_dap_resquery().
Pass NULL if the data is identified otherwise, e.g. via itemidref.
4352
aggreg Notification aggregation mode. Implementation dependent. Pass NULL. Notification aggregation is an optimization where some notification may be delayed
a little so that it can be sent more optimally in same message with other notifications that may happen a little later. This functionality need not be supported by
the backend implementations.
4353
trig Implementation dependent notification triggers. Pass NULL.
4348
4349
4350
4351
4354
4355
starts Start date time of the subscription. NULL means subscription starts immediately.
January 29, 2011
CHAPTER 22. IDENTITY WEB SERVICES 22.5. ID MESSAGING INTERFACE
4356
4357
4358
4359
4360
4361
expires End data time of the subscription. NULL means the subscription will not
expire.
incl_data If 1 (true), the notifications resulting from the subscription will contain the
changed data (push model). If 0 (false), the notification will just say that something changed, but interested party will need to perform a separate query to retrieve the data (pull model).
4363
admin_notif Administrative notification address. If NULL, the notify_ref will be used
for administrative notifications as well.
4364
notify_ref Notification address.
4365
22.4.9
4362
4366
4367
4368
4369
4370
4371
4372
4373
zxid_mk_dap_resquery()
struct zx_dap_ResultQuery_s* zxid_mk_dap_resquery(struct zxid_conf* cf,
struct zx_dap_Select_s* sel,
char* objtype,
char* predef,
char* sort,
int incl_common_attr,
char* changed_since,
char* contingent_itemidref);
4374
See description of zxid_mk_dap_query_item().
4375
22.5 ID Messaging Interface
4376
22.6 ID Geo Location Interface
4377
22.7 Contact Book Interface
4378
22.8 People Service Interface
4379
22.9 Interface to Conor’s Demo Media Service
4380
22.10 ID-SIS Data Service for HR-XML
4381
4382
4383
4384
4385
HR-XML defines a XML document format that can be used for data interchange in the
Human Resources world. The essence of HR-XML is to represent CV (Curriculum
Vitae, a.k.a. Resume) in structured form.
At the moment (June 2007) HR-XML does not define any standard way to pass these
documents around. In CV 2007 conference organized by EIfE-L in Paris, an idea
January 29, 2011
22.10. ID-SIS DATA SERVICE FOR HR-XML
4388
was canvassed: use Liberty Data Service to exchange HR-XML documents. I tried to
implement such service during the conference, but only got it working at the air port
after the conference.
4389
This service is a good example of how to apply ZXID to implement your own services.
4390
Files
4386
4387
4391
4392
4393
4394
4395
sg/hr-xml-sampo.sg
sg/id-hrxml.sg
zxidhrxmlwsc.c
zxidhrxmlwsp.c
-
A slightly modified version of HR-XML schema
Liberty DST 2.1 based data service for HR-XML
Web Services Client for HR-XML
Web Services Provider for HR-XML
Running demo
4397
1. Set up your /etc/hosts. At least you need sp1.zxidsp.org and you may also
need your IdPs domain name (e.g. idp.symdemo.com).
4398
2. Start your IdP and DS (not supplied with ZXID)
4396
4399
4400
cd /opt/SYMfiam/std
conf/test-idp3/start.sh start log
4402
Next you need to cause the id-hr-xml services to be registered in the discovery
service. This depends on product.
4403
Then you need to create an association for id-hr-xml service for some test user.
4401
4404
4405
4406
4407
4408
4409
4410
4411
4412
4413
4414
3. Start the web services client
mini_httpd -p 8443 -c ’zxid*’ -S -E zxid.pem -l tmp/mini.stderr &
tail -f tmp/zxid.stderr&
4. Start the web services provider
mini_httpd -p 8444 -c ’zxid*’ -S -E zxid.pem -l tmp/mini2.stderr &
tail -f tmp/zxid2.stderr&
5. Start browsing from
https://sp1.zxidsp.org:8443/zxidhrxmlwsc?o=E
6. Login using the test user that has the association
7. Paste <Candidate> element in HR-XML Data form field and click Create. This
creates a Candidate record in the WSP.
4416
8. Click Query. This queries the WSP for the record we saved in previous step. You
should see the record appear in the HR-XML Response field.
4417
http://s-idp.liberty-iop.org:8881/N
4415
January 29, 2011
4418
4419
4420
Chapter 23
Function Reference (generated
from source)
157
CHAPTER 23. FUNCTION REFERENCE (GENERATED FROM SOURCE)
January 29, 2011
4421
4422
Chapter 24
Structures
159
CHAPTER 24. STRUCTURES
January 29, 2011
4423
4424
Chapter 25
Important Functions
4425
• chkuid
4426
• zx_EASY_ENC_elem
4427
• zx_dec_zx_root
4428
• zx_easy_enc_elem_opt
4429
• zx_strf
4430
• zxid_add_qs_to_ses
4431
• zxid_az_cf
4432
• zxid_az_cf_ses
4433
• zxid_call
4434
• zxid_check_fed
4435
• zxid_chk_sig
4436
• zxid_decode_redir_or_post
4437
• zxid_fed_mgmt_cf
4438
• zxid_fetch_ses
4439
• zxid_get_at
4440
• zxid_get_ent_ss
4441
• zxid_get_epr
4442
• zxid_idp_list_cf_cgi
4443
• zxid_idp_select_zxstr_cf_cgi
4444
• zxid_idp_sso
161
CHAPTER 25. IMPORTANT FUNCTIONS
4445
• zxid_init_conf
4446
• zxid_map_identity_token
4447
• zxid_mk_usr_a7n_to_sp
4448
• zxid_my_ent_id
4449
• zxid_nidmap_identity_token
4450
• zxid_parse_cgi
4451
• zxid_parse_conf_raw
4452
• zxid_pep_az_base_soap_pepmap
4453
• zxid_pep_az_soap_pepmap
4454
• zxid_pool_to_ldif
4455
• zxid_saml2_post_enc
4456
• zxid_saml2_redir_enc
4457
• zxid_ses_to_pool
4458
• zxid_set_delegated_discovery_epr
4459
• zxid_simple_ab_pep
4460
• zxid_simple_cf_ses
4461
• zxid_soap_call_raw
4462
• zxid_sp_deref_art
4463
• zxid_sp_slo_redir
4464
• zxid_sp_slo_soap
4465
• zxid_sp_sso_finalize
4466
• zxid_start_sso_url
4467
• zxid_validate_cond
4468
• zxid_wsc_call
4469
• zxid_wsc_prepare_call
4470
• zxid_wsc_valid_resp
4471
• zxid_wsf_decor
4472
• zxid_wsp_decorate
4473
• zxid_wsp_validate
4474
• zxlog_path
4475
• zxsig_sign
4476
• zxsig_validate
January 29, 2011
4477
4478
4479
4480
4481
4482
4483
4484
4485
4486
4487
4488
4489
4490
4491
4492
4493
4494
4495
4496
4497
4498
4499
4500
4501
4502
4503
4504
4505
4506
4507
4508
4509
Chapter 26
Functions Alphabetical
On lines 14-18 we check whether the servlet session is active. If it is, there is nothing
more to do and we proceed to the application, on line 20. However, if the session
does not exist yet, we trigger Single Sign-On by redirecting the user to /sso (this must
match the configuration in servlet/WEB-INF/web.xml). A very important part of the
redirect is supplying the fr query string parameter (l.16) which allows the SSO servlet
to redirect the user back to the original application after the SSO. The o=E query string
parameter is needed as well and will trigger the IdP selection screen. Alternatively you
could supply your own IdP selection screen.
On first attempt to access the protected content, the if on l.15 will trigger, sending the
user to the Single Sign-On. On second attempt (i.e. just after the SSO) the if will not
fire and application can start its normal operation, outputting the protected content page
(l.20).
On line 25 we render the logout buttons. This is optional, but your web site user
interface should include these buttons somewhere. It is important that the query strings
for the buttons indicate the operation (gl=1 means local logout, gr=1 means Single
Logout (SLO) and the session ID (s=...) which you can obtain from the servlet session
under name "sesid". Clicking these links will send the user to the SSO servlet with
appropriate information to end the session. After logout, the user will land on IdP
selection screen, where he can login again, if desired.
On ll.30-35 we perform an optional authorization check. Usually, if configured, an
authorization step is taken already during the SSO servlet phase. However, sometimes the generic authorization is not specific enough and the application wants to
make an explicit authorization request to a PDP. Calling zxidjni.az() accomplishes just
that. It is pulled in by the import statement on l.1. The first argument is a configuration string, which usually has just one argument: the ZXID directory PATH (normally
"/var/zxid/"), but it could contain additional options such as
PDP_CALL_URL URL of the PDP to call. Default is not to call any PDP, i.e. attempting to call zxidjni.az() without this set in either /var/zxid/zxid.conf
configuration file or in the conf string is futile.
NEED Comma separated list of the attributes needed for decision. If an attribute or a
wild card is not listed in the NEED or WANT, it is not passed to the PDP. Thus,
163
CHAPTER 26. FUNCTIONS ALPHABETICAL
4510
4511
4512
4513
4514
4515
4516
4517
4518
4519
4520
4521
4522
it is not sufficient to supply an attribute in query string: it is also necessary to list
it, or a wild card, in NEED or WANT as well as in PEPMAP.
WANT Comma separated list of the attributes useful (but not needed) for decision.
PEPMAP How tp pass attributes from attribute pool, or the query string argument, to
the PDP. If attribute or wild card is not listed in the PEPMAP, it is not passed to
the PDP.
It is important that you address NEED and PEPMAP in your configuration. Without
them the attributes supplied in query string argument will not be passed on to the PDP.
The second argument ("Action=Show") allows you to pass in attributes that were not
part of the context before. Each attribute is considered accoring to NEED, WANT, and
PEPMAP configurations and is classified as belonging in Subject, Resource, Action, or
Environment categories. You would typically supply using thsi argument the specifics
of the application dependent operation that is to be authorized.
4524
The third argument specifies the ZXID session ID, which is used to fetch some additional attributes.
4525
26.0.1
4523
4526
4527
4528
4529
4530
4531
4532
4533
4534
4535
4536
4537
4538
4539
4540
4541
4542
4543
4544
4545
4546
4547
4548
4549
4550
4551
Configuring SSO Servlet to Tomcat
In addition to your own applet that redirects to the SSO servlet, you need to configure
Tomcat to recognize both your applet and the SSO applet. This is typically done by
editing servlet/WEB-INF/web.xml file (servlet/WEB-INF/web.xml in zxid source
tree). Consider
01 <web-app> 02 03 <display-name>ZXID SSO Servlet Example</display-name>
04 <description>SSO capability for other servlets.</description> 05 06 <servlet> 07
<servlet-name>zxidsrvlet</servlet-name> 08 <servlet-class>zxidsrvlet</servlet-class>
09 </servlet> 10 11 <servlet-mapping> 12 <servlet-name>zxidsrvlet</servlet-name>
13 <url-pattern>/sso</url-pattern> 14 </servlet-mapping> 15 16 <servlet> 17 <servletname>zxidappdemo</servlet-name> 18 <servlet-class>zxidappdemo</servlet-class> 19
</servlet> 20 21 <servlet-mapping> 22 <servlet-name>zxidappdemo</servlet-name>
23 <url-pattern>/appdemo</url-pattern> 24 </servlet-mapping> 25 26 </web-app>
Here lines 16-24 represent your own payload application. The <servlet-name> is
used to match together <servlet> and the <servlet-mapping> sections. <servlet-class>
points to the Java class file that implements the servler, in this case zxidappdemo.class.
Finally <url-pattern> specifies where in the web servers hierarchy the servlet will
appear. Here you have to realize that the pattern will be prefixed by the directory path
where the servlet lives (i.e. in our example the actual path is /zxidservlet/appdemo).
ll.06-14 represent the SSO servlet. As can be seen, the corresponding class file is
zxidsrvlet.class, which you will find at top level of the zxid distribution after compiling. The <url-pattern> and the servlet directory MUST match the redirection on
l.16 of the servlet code example above. If application servlet and the SSO servlet live
in the same directory, mere local redirect will do the trick, as illustrated on l.16.
The <url-patterm> also MUST correspond to the URL parameter in the /var/zxid/zxid.conf
file (the URL parameter is also prefix of the EntityID which is also the Well Know Location (WKL) for metadata exchange).
January 29, 2011
26.1. RUNNING AS SERVLET UNDER TOMCAT
4552
4553
4554
4555
4556
4557
4558
4559
4560
4561
4562
4563
4564
4565
4566
4567
4568
4569
4570
4571
4572
4573
4574
4575
4576
4577
26.1
Running as servlet under Tomcat
ZXID distribution contains subdirectory called servlet. You should link this into
webapps directory of Tomcat servlet container
cd ~/apache-tomcat-5.5.20/webapps
ln -s ~/zxid-0.34/servlet zxidservlet
and also
cd ~/apache-tomcat-5.5.20/webapps/zxidservlet/WEB-INF
ln -s ../.. classes
You also need to set allowLinking flag in apache-tomcat-5.5.20/conf/context.xml
(the reloadable flag avoids having to restart Tomcat if you recompile the .class file):
<Context allowLinking="true" reloadable="true">...
The file servlet/WEB-INF/web.xml describes the example zxid application. The actual application lives in servlet/WEB-INF/classes which is actually just a symlink
back to the top level of the ZXID distribution. Therefore the zxidhello.class file appears on the top level and the wrapper classes, which are scoped in zxidjava package,
appear in zxidjava/ subdirectory. From the servlet container’s perspective the directory appears to be apache-tomcat-5.5.20/webapps/zxidservlet/WEB-INF/classes/zxidjava
After make javazxid and restart of Tomcat (killall java; apache-tomcat-5.5.20/bin/startup.sh),
you can access the application using URL (defined in servlet/WEB-INF/web.xml)
make javazxid
export JAVA_HOME=/apps/java/j2sdk1.4.2
export LD_LIBRARY_PATH=~/zxid-0.34/zxidjava:$LD_LIBRARY_PATH
cd ~/apache-tomcat-5.5.20
# Need to be here to avoid class path problems
killall java; bin/startup.sh
tail -f ~/apache-tomcat-5.5.20/logs/catalina.out &
http://sp1.zxidsp.org:8080/zxidservlet/zxidHLO?o=E
4579
N.B. You should make sure sp1.zxidsp.org resolves to the machine where you are
running Tomcat, e.g. localhost (127.0.0.1).
4580
26.2
4578
4581
4582
4583
4584
Using ZXID with AXIS2
axis2-1.4.1-war.zip
zxidservlet/META-INF/module.xml
/d/sampo/apache-tomcat-5.5.20/webapps/axis2/WEB-INF/services/META-INF/services.xml
/d/sampo/apache-tomcat-5.5.20/webapps/axis2/WEB-INF/conf/axis2.xml
January 29, 2011
26.3. PROGRAMMING WITH ZXID
CHAPTER
JAVA API
26. FUNCTIONS ALPHABETICAL
4585
26.3
Programming with ZXID Java API
4586
For detailed usage examples of the Java interface you should study the zxid.java file.
4590
The Java interface is contained in a package called zxidjava. This package contains
the main wrapper class zxidjni as well as a number of data type specific classes. The
zxidjni class is just a container for procedural zxid API - all methods of this class are
static.
4591
To start using the ZXID Java interface you need to do two things:
4587
4588
4589
4592
4593
4594
4595
4596
4597
4598
4599
import zxidjava.*;
somewhere near top of your program pulls in the zxidjava package, including the zxidjni class. Then you need to have a static initializer somewhere in your program to pull
in the libzxidjni.so:
public class myprog {
static {
System.loadLibrary("zxidjni");
}
4600
public static void main(String argv[]) throws java.io.IOException
{
// ...
}
4601
4602
4603
4604
4605
4606
4607
4608
}
From here on you can call the C API procedures as static methods of the zxidjni class,
e.g:
cf = zxidjni.new_conf("/var/zxid/");
4609
Note that the zxid_ prefix is omitted in favour of the zxidjni class name qualifier.
4610
26.3.1
Integrating SSO Directly to Your Java Servlet
4614
Although zxidsrvlet.java provides a "no programming required" SSO integration
for Servlet, just like mod_auth_saml provides for Apache httpd, sometimes you will
want to integrate SSO directly into your servlet, e.g. to avoid distributing a second
servlet.
4615
Consider
4611
4612
4613
4616
4617
4618
4619
01
02
03
04
import
import
import
import
zxidjava.*;
java.io.*;
javax.servlet.*;
javax.servlet.http.*;
January 29, 2011
26.3. PROGRAMMING WITH ZXID JAVA API
4620
4621
4622
4623
4624
4625
4626
4627
4628
4629
4630
4631
4632
4633
4634
4635
4636
4637
4638
4639
4640
4641
4642
4643
4644
4645
4646
4647
4648
4649
4650
4651
4652
4653
4654
4655
4656
4657
4658
4659
4660
4661
4662
4663
4664
4665
4666
4667
4668
05 public class zxidhlo extends HttpServlet {
06
static { System.loadLibrary("zxidjni"); }
07
static final String conf
08
= "PATH=/var/zxid/&URL=http://sp1.zxidsp.org:8080/zxidservlet/zxidHLO";
09
public void do_zxid(HttpServletRequest req, HttpServletResponse res, String qs)
10
11
String ret = zxidjni.simple(conf, qs, 0xd54);
12
13
case ’L’: /* Redirect: ret == "LOCATION: urlCRLF2" */
14
res.sendRedirect(ret.substring(10, ret.length() - 4));
15
return;
16
case ’<’:
17
18
case ’s’: /* <se: SOAP envelope */
19
case ’m’: /* <m20: metadata */
20
res.setContentType("text/xml");
21
break;
22
default:
23
24
break;
25
}
26
res.setContentLength(ret.length());
27
res.getOutputStream().print(ret);
28
break;
29
30
//my_parse_ldif(ret);
31
32
res.getOutputStream().print(zxidjni.fed_mgmt(conf, sesid, 0xd54));
33
break;
34
default:
35
System.err.print("Unknown zxid_simple() response:");
36
System.err.print(ret);
37
}
38
}
39
public void doGet(HttpServletRequest req, HttpServletResponse res)
40
41
// LECP/ECP PAOS header checks
42
do_zxid(req, res, req.getQueryString());
43
}
44
public void doPost(HttpServletRequest req, HttpServletResponse res)
45
46
String qs;
47
int len = req.getContentLength();
48
byte[] b = new byte[len];
49
int got = req.getInputStream().read(b, 0, len);
50
qs = new String(b, 0, got);
51
do_zxid(req, res, qs);
52
}
53 }
January 29, 2011
26.4. KNOWN PROBLEMS AND CHAPTER
LIMITATIONS
4669
4670
4671
4672
4673
4674
4675
4676
26.4
Known Problems and Limitations
The zx_str type is generally NOT nul terminated. We try to map these in the SWIG
type maps, but any function returning char* currently maps to Java String type, yet
there is no way of knowing how long the string type is. Therefore it’s not safe to call
functions returning char*. For example, consider
int zx_LEN_SO_sa_Action(struct zx_ctx* c, struct zx_sa_Action_s* x);
char* zx_ENC_SO_sa_Action(struct zx_ctx* c, struct zx_sa_Action_s* x, char* p);
struct zx_str* zx_EASY_ENC_SO_sa_Action(struct zx_ctx* c, struct zx_sa_Action_s* x);
4682
The intent of the LEN_SO plus ENC_SO pair is that you first compute length, allocate
sufficient buffer, and then render the encoding into the buffer. The ENC_SO in fact
returns char* one past the end of the string. It is NOT safe to cal ENC_SO from Java
because the SWIG generated interface would make Java believe that the char* one
past end of string is a C string in its own right. Thus the only safe one to call is the
EASY_ENC_SO variant.
4683
26.5
Troubleshooting class loader
4684
26.5.1
Symlinks
4685
If you get
4677
4678
4679
4680
4681
4686
4687
4688
4689
4690
4691
4692
4693
4694
4695
4696
java.lang.ClassNotFoundException: zxidhlo
org.apache.catalina.loader.WebappClassLoader.loadClass(WebappClassLoader.java:13
org.apache.catalina.loader.WebappClassLoader.loadClass(WebappClassLoader.java:12
org.apache.catalina.valves.ErrorReportValve.invoke(ErrorReportValve.java:105)
org.apache.catalina.connector.CoyoteAdapter.service(CoyoteAdapter.java:148)
org.apache.coyote.http11.Http11Processor.process(Http11Processor.java:869)
org.apache.coyote.http11.Http11BaseProtocol$Http11ConnectionHandler.processConne
org.apache.tomcat.util.net.PoolTcpEndpoint.processSocket(PoolTcpEndpoint.java:52
org.apache.tomcat.util.net.LeaderFollowerWorkerThread.runIt(LeaderFollowerWorker
org.apache.tomcat.util.threads.ThreadPool$ControlRunnable.run(ThreadPool.java:68
java.lang.Thread.run(Thread.java:595)
4697
Then you forgot to turn on the symlinks (see allowLinking, above).
4698
26.5.2
4699
If you get
4700
Class Path
javax.servlet.ServletException: Error allocating a servlet instance
January 29, 2011
26.5. TROUBLESHOOTING CLASS LOADER
4701
4702
4703
4704
4705
4706
4707
4708
4709
org.apache.coyote.http11.Http11BaseProtocol$Http11ConnectionHandler.processConnection(Http11BasePr
org.apache.tomcat.util.net.PoolTcpEndpoint.processSocket(PoolTcpEndpoint.java:527)
org.apache.tomcat.util.net.LeaderFollowerWorkerThread.runIt(LeaderFollowerWorkerThread.java:80)
org.apache.tomcat.util.threads.ThreadPool$ControlRunnable.run(ThreadPool.java:684)
root cause
4710
4711
4712
4713
4714
4715
4716
4717
4718
4719
4720
4721
4722
4723
4724
4725
4726
4727
4728
4729
4730
4731
4732
java.lang.NoClassDefFoundError: javax/servlet/http/HttpServlet
java.lang.ClassLoader.defineClass1(Native Method)
java.lang.ClassLoader.defineClass(ClassLoader.java:620)
java.security.SecureClassLoader.defineClass(SecureClassLoader.java:124)
java.net.URLClassLoader.defineClass(URLClassLoader.java:260)
java.net.URLClassLoader.access$100(URLClassLoader.java:56)
java.net.URLClassLoader$1.run(URLClassLoader.java:195)
java.security.AccessController.doPrivileged(Native Method)
java.net.URLClassLoader.findClass(URLClassLoader.java:188)
java.lang.ClassLoader.loadClass(ClassLoader.java:306)
sun.misc.Launcher$AppClassLoader.loadClass(Launcher.java:268)
java.lang.ClassLoader.loadClass(ClassLoader.java:251)
org.apache.catalina.loader.WebappClassLoader.loadClass(WebappClassLoader.java:1270)
org.apache.catalina.loader.WebappClassLoader.loadClass(WebappClassLoader.java:1201)
org.apache.coyote.http11.Http11BaseProtocol$Http11ConnectionHandler.processConnection(Http
org.apache.tomcat.util.net.LeaderFollowerWorkerThread.runIt(LeaderFollowerWorkerThread.jav
4734
Then the problem is with class path. Apparently running the startup.sh script from
anywhere else than top level of Tomcat distribution produces the above error.
4735
26.5.3 LD_LIBRARY_PATH
4736
If you get
4733
4737
4738
4739
4740
4741
4742
javax.servlet.ServletException: Error instantiating servlet class zxidhlo
org.apache.coyote.http11.Http11BaseProtocol$Http11ConnectionHandler.processConnection(Http11BasePr
January 29, 2011
26.5. TROUBLESHOOTING CLASS
CHAPTER
LOADER
4743
4744
4745
4746
org.apache.tomcat.util.net.LeaderFollowerWorkerThread.runIt(LeaderFollowerWorkerThread.j
root cause
4747
4748
4749
4750
4751
4752
4753
4754
4755
4756
4757
4758
4759
4760
4761
4762
4763
4764
4765
4766
4767
4768
java.lang.UnsatisfiedLinkError: no zxidjni in java.library.path
java.lang.ClassLoader.loadLibrary(ClassLoader.java:1517)
java.lang.Runtime.loadLibrary0(Runtime.java:788)
java.lang.System.loadLibrary(System.java:834)
zxidhlo.<clinit>(zxidhlo.java:20)
sun.reflect.NativeConstructorAccessorImpl.newInstance0(Native Method)
sun.reflect.NativeConstructorAccessorImpl.newInstance(NativeConstructorAccessorI
sun.reflect.DelegatingConstructorAccessorImpl.newInstance(DelegatingConstructorA
java.lang.reflect.Constructor.newInstance(Constructor.java:274)
java.lang.Class.newInstance0(Class.java:308)
java.lang.Class.newInstance(Class.java:261)
org.apache.coyote.http11.Http11BaseProtocol$Http11ConnectionHandler.processConne
org.apache.tomcat.util.net.PoolTcpEndpoint.processSocket(PoolTcpEndpoint.java:52
org.apache.tomcat.util.net.LeaderFollowerWorkerThread.runIt(LeaderFollowerWorker
org.apache.tomcat.util.threads.ThreadPool$ControlRunnable.run(ThreadPool.java:68
Then it is not finding zxidjava/libzxidjni.so. Either say
export LD_LIBRARY_PATH=~/zxid-0.34/zxidjava:$LD_LIBRARY_PATH
or place libzxidjni.so in CATALINAH OME/shared/lib.Notethatthelibrarynamereallyislibzxidjni.sodes
4769
26.5.4
4770
If you get
4771
4772
4773
4774
4775
4776
4777
4778
4779
4780
4781
Native Library Already Loaded
java.lang.UnsatisfiedLinkError: Native Library /home/sampo/zxid/zxidjava/libzxidjni.so
java.lang.ClassLoader.loadLibrary0(ClassLoader.java:1551)
java.lang.ClassLoader.loadLibrary(ClassLoader.java:1511)
java.lang.Runtime.loadLibrary0(Runtime.java:788)
java.lang.System.loadLibrary(System.java:834)
zxidhlo.<clinit>(zxidhlo.java:20)
sun.reflect.NativeConstructorAccessorImpl.newInstance0(Native Method)
sun.reflect.NativeConstructorAccessorImpl.newInstance(NativeConstructorAccessorI
sun.reflect.DelegatingConstructorAccessorImpl.newInstance(DelegatingConstructorA
java.lang.reflect.Constructor.newInstance(Constructor.java:274)
java.lang.Class.newInstance0(Class.java:308)
January 29, 2011
26.6. LOGGING AND DEBUGGING TIPS
java.lang.Class.newInstance(Class.java:261)
org.apache.coyote.http11.Http11BaseProtocol$Http11ConnectionHandler.processConnection(Http
org.apache.tomcat.util.net.LeaderFollowerWorkerThread.runIt(LeaderFollowerWorkerThread.jav
4782
4783
4784
4785
4786
4787
4788
4789
4790
4791
Then ... ? Currently it seems you have to restart Tomcat.
4792
See
4793
• http://forums.sun.com/thread.jspa?threadID=633985
4796
In essence the Java environment has arbitrary restriction that same library can not be
used twice, e.g. due to two instances of same application. Most trivial way around this
is to create two copies of the libzxidjni.so with different names.
4797
26.5.5
4794
4795
4798
Win32 Java loanLibrary() error
java.lang.UnsatisfiedLinkError: Given procedure could not be found
4799
4800
4801
-mno-cygwin
-Wl,--add-stdcall-alias
4803
No documented solution to this mystery error. It is believed to come from Windows
dynamic linker.
4804
26.6
4802
Logging and Debugging Tips
4806
In case you add debug prints, the stderr (System.err) output appears to go by default
to apache-tomcat-5.5.20/logs/catalina.out
4807
26.7
4805
4808
4809
4810
4811
4812
4813
4814
Debugging libzxidjni.so under jdb and gdb
Debugging the JNI C code would appear to require running java or jdb under gdb and
setting break points in the C code. Unfortunately this appears to be particularly tricky.
A possible approach is to introduce a sleep(1) in the C code and then use gdb to attach
to the java process. Unfortunately even this method does not seem to allow us to set
break points.
export LD_LIBRARY_PATH=zxidjava:$LD_LIBRARY_PATH
export QUERY_STRING=’e=https%3A%2F%2Fidp.symdemo.com%3A8880%2Fidp.xml&l2=+Login+%28SAML20%3APOST
January 29, 2011
26.7. DEBUGGING LIBZXIDJNI.SO
CHAPTER
UNDER
26.JDB
FUNCTIONS
AND GDBALPHABETICAL
N.B. In following "”meansUnixshell prompt, ”%”gdbprompt, and” > ” jdbprompt.
4815
4816
4817
4818
4819
4820
4821
4822
4823
$
%
%
%
>
>
>
>
>
gdb jdb
set env LD_LIBRARY_PATH=zxidjava
set env QUERY_STRING=e=https%3A%2F%2Fidp.symdemo.com%3A8880%2Fidp.xml&l2=+Login+%28S
r zxid
stop at zxid:24
run
next
# or step
print cf
cont
January 29, 2011
4824
4825
4826
Chapter 27
Net::SAML - ZXID Perl
Bindings
4827
• perl CGI example: zxid.pl
4828
• using with mod_perl
4829
4830
4831
4832
4833
4834
4835
4836
4837
4838
4839
4840
4841
4842
4843
4844
4845
After building the main zxid tree, you can
cd Net
perl Makefile.PL
make
make test
# Tests are extremely sparse at the moment
make install
This assumes you use the pregenerated Net/SAML_wrap.c and Net/SAML.pm files that
we distribute. If you wish to generate these files from origin, you need to have SWIG
installed and then say in main zxid directory
make perlmod ENA_GEN=1
make samlmod ENA_GEN=1
make wsfmod ENA_GEN=1
# Makes all available perl modules (including heavy low level ones)
# Only makes Net::SAML (much faster)
# Only makes Net::WSF (much faster)
WARNING: Low level interface is baroque, and consequently, it will take
a lot of disk space, RAM and CPU to build it: 100 MB would not be
exaggeration and over an hour (on 1GHz CPU). Build time memory consumption of single cc1 process will be over 256 MB of RAM. You have
been warned.
4846
27.1
Example Program (see also zxidhlo.pl)
4847
01 use Net::SAML;
173
27.1. EXAMPLE PROGRAM
CHAPTER
(SEE ALSO
27. ZXIDHLO.PL)
NET::SAML - ZXID PERL BINDINGS
4848
4849
4850
4851
4852
4853
4854
4855
4856
4857
4858
4859
4860
4861
4862
4863
4864
4865
4866
4867
4868
4869
4870
4871
4872
4873
4874
4875
4876
4877
4878
4879
4880
4881
4882
4883
4884
4885
4886
4887
4888
4889
4890
4891
4892
4893
4894
4895
4896
02 $| = 1; undef $/; # Flush pipes, read all in at once
03 $url = "http://sp.tas3.pt:8082/zxidhlo.pl"; # Edit to match your situati\
on
04 $conf = "PATH=/var/zxid/&URL=$url";
05 $cf = Net::SAML::new_conf_to_cf($conf);
06 $qs = $ENV{’QUERY_STRING’};
07 $qs = <STDIN> if $qs =~ /o=P/;
08 $res = Net::SAML::simple_cf($cf, -1, $qs, undef, 0x1828);
09 $op = substr($res, 0, 1);
10 if ($op eq ’L’ || $op eq ’C’) { print $res; exit; } # LOCATION (Redir) or\
CONTENT
11 if ($op eq ’n’) { exit; } # already handled
12 if ($op eq ’e’) { my_render_idpsel_screen(); exit; }
13 if ($op ne ’d’) { die "Unknown Net::SAML::simple() res($res)"; }
14
15 ($sid) = $res =~ /^sesid: (.*)$/m; # Extract a useful attribute from SSO\
output
16
17 print <<HTML
19
20 <title>ZXID perl HLO SP Mgmt & Protected Content</title>
24 $az
25 <h1>ZXID SP Perl HLO Management & Protected Content (user logged in, sess\
ion active)</h1>
26 sesid: $sid
27 HTML
28
;
29 print Net::SAML::fed_mgmt_cf($cf, undef, -1, $sid, 0x1900);
30 exit;
31
32 sub my_render_idpsel_screen { # Replaces traditional login screen
33
print <<HTML;
35
36 <title>ZXID SP PERL HLO SSO IdP Selection</title>
40 <h1>ZXID SP Perl HLO Federated SSO IdP Selection (user NOT logged in, no \
session.)</h1>
41 <form method=get action="zxidhlo.pl">
42
43 <h3>Login Using New IdP</h3>
44
45 <i>A new IdP is one whose metadata we do not have yet. We need to know
January 29, 2011
CHAPTER 27. NET::SAML
27.1.- ZXID
EXAMPLE
PERL PROGRAM
BINDINGS (SEE ALSO ZXIDHLO.PL)
4922
46 the Entity ID in order to fetch the metadata using the well known
47 location method. You will need to ask the adminstrator of the IdP to
48 tell you what the EntityID is.</i>
49
50 <p>IdP URL <input name=e size=60><input type=submit name=l2 value=" Login\
">
51 HTML
52 ;
53
print Net::SAML::idp_list_cf($cf, undef, 0x1c00);
# Get the IdP sel\
ection form
54
print <<HTML;
55 <h3>CoT configuration parameters your IdP may need to know</h3>
56
57 Entity ID of this SP: <a href="$url?o=B">$url?o=B</a> (Click on the link \
to fetch SP metadata.)
58
59 <input type=hidden name=fc value=1><input type=hidden name=fn value=prstn\
t>
60 <input type=hidden name=fq value=""><input type=hidden name=fy value="">
61 <input type=hidden name=fa value=""><input type=hidden name=fm value="">
62 <input type=hidden name=fp value=0><input type=hidden name=ff value=0>
63
64 </form><hr><a href="http://zxid.org/">zxid.org</a>
65 HTML
66
;
67 }
4923
This example only demosntrates SSO.
4924
Lines 1-5 set up the configuration. See zxid-conf.pd for guidance.
4925
ll.6-7 reads in the CGI input the perl way.
4897
4898
4899
4900
4901
4902
4903
4904
4905
4906
4907
4908
4909
4910
4911
4912
4913
4914
4915
4916
4917
4918
4919
4920
4921
4926
4927
4928
4929
4930
4931
4932
4933
4934
4935
4936
4937
4938
4939
4940
4941
4942
l.8 runs the SAML engine of ZXID. The engine will return result that is processed
below. The magic constant 0x1828 sets some flags, see zxid-simple.pd for explanation. This explanation may be especially relevant if you plan to run as mod_perl
process rather than as a CGI. With these flags you could eliminate the need to render
the IdP selection screen.
ll.9-13: interpret the return value. l.10 deals with parts of SAML protocol that need
redirect or content. l.12 deals with rendering the IdP selection screen. This screen
replaces the traditional login screen in most applications.
l.15 demonstrates how to extract attributes from the return value. The ret is formatted
as LDIF so it is very easy to parse with perl.
ll.17-30 render the "protected content". Most protected content should contain also
Single Logout button. This is accomplished on l.29. Protected content is where your
normal application after SSO lives. You can rely in ZXID session mechanism and just
show the content, or you could bootstrap your application’s session mechanism here.
ll.32-67 render the "idp selection" screen. This could have been automatically generated has the flags to Net::SAML::simple_cf() been different (see zxid-simple.pd for
explanation).
January 29, 2011
27.2. CURRENT MAJOR MODULES
CHAPTERARE
27. NET::SAML - ZXID PERL BINDINGS
4944
As can be seen, the most central logic for SSO is only about 10 lines. The rest is user
interface.
4945
27.2
4943
Current major modules are
4946
• Net::SAML - The high level interfaces for Single Sign-On (SSO)
4947
• Net::SAML::Raw - Low level assertion and protocol manipulation interfaces
4948
• Net::SAML::Metadata - Low level metadata manipulation interfaces
4949
27.3
Planned modules
4950
• Net::WSF - The high level interfaces for Web Services Frameworks (WSF)
4951
• Net::WSF::Raw - The low level interfaces for WSF variants
4952
• Net::WSF::WSC - The high level interfaces for Web Services Clients
4953
• Net::WSF::WSC:Raw
4954
4955
4956
4957
4958
4959
4960
4961
4962
4963
4964
4965
4966
4967
4968
4969
27.4
Perl API Adaptations
The perl APIs were generated from the C .h files using SWIG. Generally any C functions and constants that start by zxid_, ZXID_, SAML2_, or SAML_ have that prefix
changed to Net::SAML::. Note, however, that the zx_ prefix is not stripped.
Since ZXID wants to keep strings in many places in length + data representation,
namely as struct zx_str, SWIG typemaps were used to make this happen automatically. Thus any C function that takes as an argument struct zx_str* can take a
perl string directly. Similarly any C function that returns such a pointer, will return a
perl string instead. As a final goodie, any C function, such as
struct zx_str* zx_ref_len_str(struct zx_ctx* c, int len, char* s);
that takes length and s as explicit arguments, takes only single argument that is a
perl string (the one argument automatically satisfies two C arguments, thanks to a type
map). The above could be called like
$a = Net::SAML::zx_ref_len_str(c, "foo");
First the "foo" satisfies both len and s , and then the return value is converted back to
perl string.
January 29, 2011
CHAPTER 27. NET::SAML
27.5. TESTING
- ZXID NET::SAML
PERL BINDINGS
AND ZXID.PL AS CGI SCRIPT
4970
4971
4972
4973
4974
4975
4976
4977
4978
27.5
Testing Net::SAML and zxid.pl as CGI script
To test the perl module, you must restart the mini_httpd(8) so that it recognizes zxid.pl
as CGI script:
mini_httpd -p 8443 -c zxid.pl -S -E zxid.pem
Then start browsing from
https://sp1.zxidsp.org:8443/zxid.pl
or if you want to avoid the common domain cookie check
https://sp1.zxidsp.org:8443/zxid.pl?o=E
27.6 Testing Net::SAML and zxid.pl under mod_perl
4981
You can run zxid.pl under mod_perl using the Apache::Registry module. See Apache
recipe for how to compile Apache to support mod_perl. After configuration it should
work the same as the CGI approach.
4982
27.7 Debugging Net::SAML with GDB
4979
4980
4983
4984
4985
4986
4987
4988
4989
4990
4991
4992
4993
4994
4995
4996
4997
4998
4999
5000
5001
As bizarre as it may sound, it is actually quite feasible to debug libzxid and the SAML_wrap.c
using GDB while in perl. For example
cd zxid
gdb /usr/local/bin/perl
set env QUERY_STRING=o=E
r ./zxid.pl
If the script crashes inside the C code, GDB will perfectly reasonably take control,
allowing you to see stack back-trace (bt) and examine variables. Of course it helps if
openssl and perl were compiled with debug symbols (libzxid is compiled with debug
symbols by default), but even if they weren’t you can usually at least get some clue.
When preparing a perl module, generally Makefile.PL mechanism causes the same
compilation flags to be used as were used to compile the perl itself. Generally this is
good, but if libzxid was compiled with different flags, mysterious errors can crop up.
For example, I compile my libzxid against openssl that I have also compiled myself.
However, I once had a bug where the perl had been compiled such that the Linux
distribution’s incompatible openssl would be picked by perl compile flags, resulting in
mystery crashes deep inside openssl ASN.1 decoder routines (c2i_ASN1_INTEGER()
while in d2i_X509() to be exact). When I issued ‘info files’ in GDB I finally realized
that I was using the wrong openssl library.
January 29, 2011
27.7. DEBUGGING NET::SAML
CHAPTER
WITH27.
GDB
NET::SAML - ZXID PERL BINDINGS
January 29, 2011
5002
5003
Chapter 28
php_zxid
5006
The PHP integration is incomplete due to incomplete support in SWIG for php5. However, enough interface exists to get most high level API working and thus successfully
run an SP.
5007
28.1
5008
TBD
5009
28.2
5010
After building main zxid distribution, say
5004
5005
5011
5012
5013
5014
5015
5016
Installing Binaries or from Package
Building and Installing ZXID PHP extension
make phpzxid
You MUST have php-config(1) in path. If not, try
make phpzxid PHP_CONFIG=/path/to/php-config
If the extension built successfully, you can use it by copying it to a suitable place, e.g.
make phpzxid_install
The install again uses the php-config(1) to figure out where php(1) can find the module.
5018
Next you need to decide whether to run under Apache mod_php setup (apache), or as
CGI (any web server).
5019
28.2.1 Running PHP as Apache mod_php
5020
See Apache recipe for how to compile Apache to support mod_php.
5017
179
28.2. BUILDING AND INSTALLING ZXID PHP EXTENSION
CHAPTER 28. PHP_ZXID
5021
28.2.2
5022
In the CGI case you generally make sure your CGI script starts like
5023
5024
5025
5026
5027
5028
5029
5030
5031
5032
5033
5034
5035
Running PHP as CGI (any web server)
#!/usr/bin/php
<?
dl("php_zxid.so"); # These three lines can go to initialization: they only need to ru
$conf = "PATH=/var/zxid/&URL=https://sp1.zxidsp.org:8443/zxidhlo.php";
?>
The first line makes sure the file is executed with php interpreter. You should change it
to match the path where your php is installed. You also need to make your CGI script
executable, e.g:
chmod a+x mycgi.php
Then you place the CGI script in a directory in the document tree of the web site and
make sure your http server is configured (permitted) to execute CGI scripts in that
directory.
5042
One tricky thing that can go wrong is dynamic linking. When you compiled the
php_zxid.so module, some linking dependencies are usually created. Problem arises
if some of the dependencies are not in the paths allowed for dynamic linking by your
web server. The paths allowed by web server can easily be different than in your shell
and some web servers even ignore LD_LIBRARY_PATH environment variable. Sometimes you just have to copy the dependency libraries to one of the allowed directories.
This is "dirty", but works. See ldconfig(8) and section ?? for further information.
5043
You can easily see the dependencies using ldd(1)
5036
5037
5038
5039
5040
5041
5044
5045
5046
5047
5048
5049
5050
5051
5052
5053
5054
5055
5056
5057
5058
5059
5060
ldd /apps/php/5.1.6/lib/php/extensions/no-debug-non-zts-20050922/php_zxid.so
linux-gate.so.1 => (0xffffe000)
libpthread.so.0 => /lib/libpthread.so.0 (0xb7796000)
libdl.so.2 => /lib/libdl.so.2 (0xb7792000)
libcurl.so.3 => /apps/lib/libcurl.so.3 (0xb7611000)
libz.so.1 => /apps/lib/libz.so.1 (0xb75fe000)
libc.so.6 => /lib/libc.so.6 (0xb74dd000)
/lib/ld-linux.so.2 (0x80000000)
In this example the suspect library dependencies are /apps/lib/libcurl.so.3 and
/apps/lib/libz.so.1 because they are outside normal places, i.e. /lib and /usr/lib.
Another thing to remember is that CGI specification requires that the Content-Type
header and an empty line (to separate headers from content) is emitted before the actual
page. If this fails to happen, the page will mysteriously not appear although your script
ran successfully.
Sometimes the debug output can end up in stdout (e.g. somewhere stderr was redirected
to stdout) and this will garble the returned web page. Easy fix is to disable debug output
by not supplying ZXID_AUTO_DEBUG. See section ??.
January 29, 2011
CHAPTER 28. PHP_ZXID28.3. PROGRAMMING WITH ZXID PHP EXTENSION
5061
28.3
5062
To use the ZXID PHP extension you must add near beginning of your script
5063
5064
Programming with ZXID PHP Extension
dl("php_zxid.so");
// Load the module
You may need to tweak the paths, or LD_LIBRARY_PATH, to get this to work.
5066
After this, you can use the PHP interface much the same way as you would use the C
interface. See the distributed zxid.php and zxidhlo.php for further usage examples.
5067
28.4
5065
5068
5069
5070
5071
5072
5073
5074
5075
5076
5077
5078
5079
5080
5081
5082
5083
5084
5085
5086
5087
5088
5089
5090
5091
5092
5093
5094
5095
5096
5097
5098
5099
5100
Simple API Using PHP
The simplest APIs are easy to use and suitable for CGIs where the program is restarted
anew every time. However in situations where the script engine stays alive persistently,
it is wasteful to reparse (and reallocate) the configuration every time. Consider following PHP snippet designed to be used with mod_php:
01
02
03
04
05
06
07
08
09
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
# Put this in the PHP initialization (it only needs to run once)
dl("php_zxid.so");
$conf = "PATH=/var/zxid/&URL=https://sp1.zxidsp.org:8443/zxiddemo.php";
<?
# For every page that is accessed
$qs = $_SERVER[’REQUEST_METHOD’] == ’GET’
? $_SERVER[’QUERY_STRING’]
: file_get_contents(’php://input’);
$res = zxid_simple_cf($cf, -1, $qs, null, 0x1800);
switch (substr($res, 0, 1)) {
case ’L’: header($res); exit; # Redirect
case ’n’: exit;
# already handled
case ’d’: break; # Logged in case -- fall through
default: error_log("Unknown zxid_simple() res(%s)", res); exit;
}
# *** Parse the LDIF in $res into a hash of attributes (see zxidhlo.php)
?>
<html><title>Protected content, logged in as <$=$attr[’cn’]$></title>
...
</html>
<?
function my_render_login_screen()
{
?>
<html><title>Please Login Using IdP</title>
...
January 29, 2011
28.4. SIMPLE API USING PHP
5101
5102
5103
5104
5105
5106
5107
5108
5109
5110
5111
5112
5113
5114
5115
5116
5117
5118
5119
5120
CHAPTER 28. PHP_ZXID
30 <?=zxid_idp_select_cf($cf, 0, 0x1800)?>
31 ...</html>
32 <? exit; }?>
Notes
1. Line 4 creates a system-wide configuration object that is later used by the other API
calls
2. On line 9 we call zxid_simple_cf() with the created object. The second and third argument specify a buffer or string that contains the CGI form data to parse. This may
come from QUERY_STRING of a GET request or from HTTP body of a POST request,
as determined on line 8. The -1 means the length of the data should be determined
using strlen(3), i.e. C string nul termination. The auto_flags == 0x1800 enables
form tag wrapping and debug prints, but otherwise automation is disabled.
3. Since automation was disabled, we need to handle several cases of possible outcomes from zxid_simple_cf(), on lines 10-17.
4. From line 18 onwards we handle the login successful or already logged in case.
First we split the LDIF entry into a hash so that we can access the attributes easily
(e.g. cn on line 20).
5. On line 30 we call zxid_idp_list_cf() to create the form for choosing which IdP to
use for login (remember that auto_flags == 0xc0 enabled the form wrapper). As
can be seen the same configuration object, $cf, is used through out.
January 29, 2011
5121
5122
5123
5124
5125
5126
5127
5128
5129
5130
5131
5132
5133
5134
5135
5136
Chapter 29
Integration of Other Libraries
with ZXID PHP
29.1
Pat Patterson’s php module
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.
5139
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.
5140
29.2
5137
5138
5141
5142
5143
5144
5145
5146
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.
183
29.2. SUN
CHAPTER
OPENSSO
29. INTEGRATION OF OTHER LIBRARIES WITH ZXID PHP
January 29, 2011
5147
5148
Chapter 30
FAQ
5149
30.1
Build and Linking Problems
5150
30.1.1
Dry run test
5151
5152
5153
5154
A good way to test whether php is able to run at all is to simulate running of a CGI
script by setting few environment variables and then invoking the script from command
line:
QUERY_STRING=o=E REQUEST_METHOD=GET php ./zxidhlo.php
5156
The result should be the IdP selection page as HTML. Another test is to run o=B to
obtain the metadata.
5157
30.1.2
5158
Following types of error messages
5155
5159
Duplicate symbols
Warning: Function registration failed - duplicate name - hexdec in /a/d/sampo/zxid/zxidhlo.php on
5160
5161
Warning: zxid:
Unable to register functions, unable to load in Unknown on line 0
5162
5163
5164
5165
Fatal error: Call to undefined function zxid_new_conf_to_cf() in /a/d/sampo/zxid/zxidhlo.php on l
Theory: the zxid library has already been loaded in some other way, such as part of
mod_auth_saml or Net::SAML loading.
185
30.1. BUILD AND LINKING PROBLEMS
January 29, 2011
CHAPTER 30. FAQ
5166
5167
5168
5169
5170
Chapter 31
Apache Compilation Tips
While I am not a guru in Apache set ups and others will do this much better, not to
speak of the official documentation, I still find that to ensure initial success of the new
installer, some help may be in order.
5173
Consider this receipe only one of many possible setups and not necessarily even the
best. The receipe worked for me in August 2006. If you come much later, things may
have changed.
5174
This Apache setup aims to illustrate
5171
5172
5175
• CGI invocation of zxid C binary
5176
• mod_php5 invocation of zxid.php
5177
• mod_perlinvocation of zxid.pl
5178
• CGI invocation of zxid.pl (alternative to mod_perl)
5179
• Support mod_auth_saml
5181
You may also install from binaries, but I feel the compilation route is only reliable way
to have reproducible results.
5182
31.1
5183
Download from: http://httpd.apache.org/download.cgi
5180
5184
5185
5186
5187
5188
5189
apache httpd-2.2.3
For PHP it is critical that –enable-so is supplied as that seems to be the only documented (supported?) installation route. PHP recommends (Aug 2006) against using
Apache 2 threaded MPM. My stock perl does not support threads either, I guess the
prefork MPM route is fine.
tar xvjf /t/httpd-2.2.3.tar.bz2
./configure --prefix=/apps/apache/2.2.3 --with-mpm=prefork --enable-so --enable-cgi --disable-cg
187
31.2. PERL-5.8.8
5190
5191
5192
5193
5194
5195
5196
5197
5198
5199
5200
5201
5202
5203
5204
CHAPTER 31. APACHE COMPILATION TIPS
I got following configure error
checking for SSL_set_cert_store... no
This seems to be documented as bug http://issues.apache.org/bugzilla/show_bug.cgi?id=39913,
but no solution was known as of Aug 2006. Further investigation shows that httpd-2.2.3/modules/ssl/READM
has following
o per-directory SSLCACertificate{File,Path} is now thread-safe but
requires SSL_set_cert_store patch to OpenSSL
but fails to provide the patch or give any hint as to how to obtain it.
Apparently hacking the configure script to remove all references to the offending variable in question is the only way forward. Look at config.log to identify the places to
hack. Iterate ./configure script until it works and then say
make
A couple of linking failures dues to missing -lz happen. Just run the links manually,
supplying the -lz flag. Sheesh, apache is supposed to be stable software.
make install
5205
31.2
5206
From http://ftp.funet.fi/pub/CPAN/src/
5207
5208
5209
5210
perl-5.8.8
This can be usually skipped if your stock perl is 5.8 series and nonthreaded and you
are happy with prefork MPM. Try
perl -V:useithreads -V:usemultiplicity
If it says
5212
useithreads=’undef’;
usemultiplicity=’undef’;
5213
then its fine for using prefork MPM.
5214
To compile perl you would
5211
5215
5216
./Configure -prefix=/apps/perl/5.8.8 -des -Dusethreads -Doptimize=’-g’ -Dusedevel
make && make test && make install
January 29, 2011
31.3. MOD_PERL-2.0.4
5217
31.3
5218
From http://perl.apache.org/dist/
5219
Install instructions: http://perl.apache.org/docs/2.0/user/install/install.html
5220
tar xvf /t/mod_perl-2.0.4.tar.gz
5221
5222
5223
5224
5225
5226
mod_perl-2.0.4
perl Makefile.PL MP_APXS=/apps/apache/std/bin/apxs MP_DEBUG=1
make
make test
# Seems to fail because wants to create core files and I do not let it to!
make install
# installs stuff to perl lib directory as well as apache modules directory
5227
You can read futher at http://perl.apache.org/docs/2.0/user/intro/start_fast.html
5228
31.4
5229
From php.net
5230
Install instructions: http://www.php.net/manual/en/install.unix.apache2.php
5231
5232
5233
php-5.1.6
./configure --prefix=/apps/php/5.1.6 --with-apxs2=/apps/apache/std/bin/apxs --with-openssl=/apps
make
make install
January 29, 2011
31.4. PHP-5.1.6
January 29, 2011
5234
5235
5236
5237
Chapter 32
Configuring Apache
These configuration steps are to enable all ZXID Apache related functionality, including mod_auth_saml, mod_perl, mod_php, and CGI.
5238
• Allow zxid to be triggered as CGI (the trick is SetHandler inside <Location>)
5239
• Allow zxid.pl to be triggered by mod_perl. The trick is
5240
5241
5242
5243
5244
AddHandler perl-script .pl
PerlResponseHandler ModPerl::Registry
PerlOptions +ParseHeaders
• Allow zxid.php to be triggered by mod_php5. Trick is
AddType application/x-httpd-php .php .phtml
5245
• Enable the mod_auth_saml for some directories
5246
• Set port number and domain
5247
• Enable SSL operation
5248
5249
5250
5251
5252
5253
5254
5255
5256
Once you have edited the Apache config files, you say
/apps/apache/std/bin/apachectl restart
tail -f tmp/err-httpd &
# Apache errorlog, per configuration
to get apache running. Below are the edits I applied to my apache config files (in
/apps/apache/std/conf directory if you followed this receipe). It’s a shame the
apache config wizardry is so bloated that the diff does not fit on one page. Also distributions with an attitude tend to complicate apache configuration files further by pulverizing them in many files over many directories. Some of the known distribution
locations
191
CHAPTER 32. CONFIGURING APACHE
5257
5258
5259
5260
5261
5262
5263
5264
5265
5266
5267
5268
/etc/apache2/sites-available/default
# Ubuntu ca. 2009
diff -u /apps/apache/std/conf/httpd.conf.orig /apps/apache/std/conf/httpd.co\
nf
--- httpd.conf.orig
2006-08-31 19:23:42.000000000 -0400
+++ httpd.conf 2006-08-31 20:31:17.000000000 -0400
@@ -37,7 +37,8 @@
# prevent Apache from glomming onto all bound IP addresses.
#
#Listen 12.34.56.78:80
-Listen 80
+##Listen 80
+Listen 8080
5269
5270
5271
5272
5273
5274
5275
5276
5277
#
# Dynamic Shared Object (DSO) Support
@@ -51,6 +52,8 @@
# Example:
# LoadModule foo_module modules/mod_foo.so
#
+LoadModule perl_module modules/mod_perl.so
+LoadModule php5_module modules/libphp5.so
5278
5279
5280
5281
5282
5283
5284
5285
5286
5287
<IfModule !mpm_netware_module>
#
@@ -98,7 +101,8 @@
# documents. By default, all requests are taken from this directory, but
# symbolic links and aliases may be used to point to other locations.
#
-DocumentRoot "/apps/apache/2.2.3/htdocs"
+##DocumentRoot "/apps/apache/2.2.3/htdocs"
+DocumentRoot "/home/sampo/zxid"
5288
5289
5290
5291
5292
5293
5294
5295
5296
5297
5298
5299
5300
5301
5302
5303
5304
5305
#
# Each directory to which Apache has access can be configured with respect
@@ -125,7 +129,8 @@
#
# This should be changed to whatever you set DocumentRoot to.
#
-<Directory "/apps/apache/2.2.3/htdocs">
+##<Directory "/apps/apache/2.2.3/htdocs">
+<Directory "/home/sampo/zxid">
#
# Possible values for the Options directive are "None", "All",
# or any combination of:
@@ -138,7 +143,13 @@
# http://httpd.apache.org/docs/2.2/mod/core.html#options
# for more information.
#
Options Indexes FollowSymLinks
January 29, 2011
5306
5307
5308
5309
5310
5311
5312
+
+
+
+
+
+
+
##Options Indexes FollowSymLinks
Options All
AddHandler cgi-script .cgi
AddHandler perl-script .pl
PerlResponseHandler ModPerl::Registry
PerlOptions +ParseHeaders
5313
5314
5315
5316
5317
#
# AllowOverride controls what directives may be placed in .htaccess fil\
es.
@@ -155,6 +166,10 @@
5318
5319
</Directory>
5320
5321
5322
5323
5324
5325
5326
5327
5328
5329
5330
5331
5332
5333
5334
+<Location "/zxid">
+SetHandler cgi-script
+</Location>
+
#
# DirectoryIndex: sets the file that Apache will serve if a directory
# is requested.
@@ -180,14 +195,16 @@
# logged here. If you *do* define an error logfile for a <VirtualHost>
# container, that host’s errors will be logged there and not here.
#
-ErrorLog logs/error_log
+##ErrorLog logs/error_log
+ErrorLog /home/sampo/zxid/tmp/err-httpd
5335
5336
5337
5338
5339
5340
5341
5342
5343
#
# LogLevel: Control the number of messages logged to the error_log.
# Possible values include: debug, info, notice, warn, error, crit,
# alert, emerg.
#
-LogLevel warn
+##LogLevel warn
+LogLevel debug
5344
5345
5346
5347
5348
5349
5350
5351
5352
<IfModule log_config_module>
#
@@ -209,13 +226,14 @@
# define per-<VirtualHost> access logfiles, transactions will be
# logged therein and *not* in this file.
#
CustomLog logs/access_log common
+
##CustomLog logs/access_log common
5353
5354
#
January 29, 2011
5355
5356
5357
5358
5359
5360
# If you prefer a logfile with access, agent, and referer information
# (Combined Logfile Format) you can use the following directive.
#
#CustomLog logs/access_log combined
+
CustomLog /home/sampo/zxid/tmp/log.httpd combined
</IfModule>
5361
5362
5363
5364
5365
5366
5367
5368
<IfModule alias_module>
@@ -245,7 +263,7 @@
# client. The same rules about trailing "/" apply to ScriptAlias
# directives as to Alias.
#
ScriptAlias /cgi-bin/ "/apps/apache/2.2.3/cgi-bin/"
+
##ScriptAlias /cgi-bin/ "/apps/apache/2.2.3/cgi-bin/"
5369
5370
</IfModule>
5371
5372
5373
5374
5375
5376
5377
5378
5379
5380
5381
5382
5383
@@ -303,7 +321,7 @@
#
AddType application/x-compress .Z
AddType application/x-gzip .gz .tgz
+AddType application/x-httpd-php .php .phtml
#
# AddHandler allows you to map certain file extensions to "handlers":
# actions unrelated to filetype. These can be either built into the ser\
ver
@@ -394,7 +412,7 @@
#Include conf/extra/httpd-default.conf
5384
5385
5386
5387
5388
5389
5390
# Secure (SSL/TLS) connections
-#Include conf/extra/httpd-ssl.conf
+Include conf/extra/httpd-ssl.conf
#
# Note: The following must must be present to support
#
starting without SSL on platforms with no /dev/random equivalent
5391
5392
5393
5394
5395
5396
5397
5398
5399
5400
5401
5402
5403
diff -u httpd-ssl.conf.orig httpd-ssl.conf
--- httpd-ssl.conf~
2006-08-31 18:24:09.000000000 -0400
+++ httpd-ssl.conf
2006-08-31 19:35:53.000000000 -0400
@@ -22,9 +22,9 @@
# Manual for more details.
#
#SSLRandomSeed startup file:/dev/random 512
-#SSLRandomSeed startup file:/dev/urandom 512
+SSLRandomSeed startup file:/dev/urandom 512
#SSLRandomSeed connect file:/dev/random 512
-#SSLRandomSeed connect file:/dev/urandom 512
+SSLRandomSeed connect file:/dev/urandom 512
5404
January 29, 2011
5405
5406
5407
5408
5409
5410
5411
5412
#
@@ -34,7 +34,7 @@
# Note: Configurations that use IPv6 but not IPv4-mapped addresses need two
#
Listen directives: "Listen [::]:443" and "Listen 0.0.0.0:443"
#
-Listen 443
+Listen 5443
5413
5414
5415
5416
5417
5418
##
## SSL Global Context
@@ -71,14 +71,16 @@
## SSL Virtual Host Context
##
5419
5420
5421
-<VirtualHost _default_:443>
+<VirtualHost _default_:5443>
5422
5423
5424
5425
5426
5427
5428
5429
5430
5431
5432
5433
5434
#
General setup for the virtual host
-DocumentRoot "/apps/apache/2.2.3/htdocs"
-ServerName www.example.com:443
+##DocumentRoot "/apps/apache/2.2.3/htdocs"
+DocumentRoot "/home/sampo/zxid"
+##ServerName www.example.com:443
+ServerName sp1.zxidsp.org:443
ServerAdmin [email protected]
-ErrorLog /apps/apache/2.2.3/logs/error_log
-TransferLog /apps/apache/2.2.3/logs/access_log
+##ErrorLog /apps/apache/2.2.3/logs/error_log
+##TransferLog /apps/apache/2.2.3/logs/access_log
5435
5436
5437
5438
5439
5440
5441
5442
5443
5444
5445
#
SSL Engine Switch:
#
Enable/Disable SSL for this virtual host.
@@ -96,15 +98,16 @@
#
in mind that if you have both an RSA and a DSA certificate you
#
can configure both in parallel (to also allow the use of DSA
#
ciphers, etc.)
-SSLCertificateFile /apps/apache/2.2.3/conf/server.crt
+##SSLCertificateFile /apps/apache/2.2.3/conf/server.crt
#SSLCertificateFile /apps/apache/2.2.3/conf/server-dsa.crt
+SSLCertificateFile /home/sampo/zxid/zxid.pem
5446
5447
5448
5449
5450
5451
5452
5453
#
Server Private Key:
#
If the key is not combined with the certificate, use this
#
directive to point at the key file. Keep in mind that if
#
you’ve both a RSA and a DSA private key you can configure
#
both in parallel (to also allow the use of DSA ciphers, etc.)
-SSLCertificateKeyFile /apps/apache/2.2.3/conf/server.key
+##SSLCertificateKeyFile /apps/apache/2.2.3/conf/server.key
January 29, 2011
5454
#SSLCertificateKeyFile /apps/apache/2.2.3/conf/server-dsa.key
5455
5456
5457
5458
5459
5460
5461
5462
5463
5464
#
Server Certificate Chain:
@@ -225,7 +228,7 @@
#
Per-Server Logging:
#
The home of a custom SSL log file. Use this when you want a
#
compact non-error SSL logfile on a virtual host basis.
-CustomLog /apps/apache/2.2.3/logs/ssl_request_log \
"%t %h %{SSL_PROTOCOL}x %{SSL_CIPHER}x \"%r\" %b"
+#CustomLog /apps/apache/2.2.3/logs/ssl_request_log \
+#
"%t %h %{SSL_PROTOCOL}x %{SSL_CIPHER}x \"%r\" %b"
5465
5466
</VirtualHost>
January 29, 2011
5467
5468
5469
5470
5471
5472
5473
5474
5475
Chapter 33
Trying Out Apache
Check sp1.zxidsp.org resolves
ping sp1.zxidsp.org
Start Apache httpd using
apachectl restart
or possibly some other distribution dependent way
apache2ctl restart
sudo invoke-rc.d apache2 restart
# Ubuntu ca. 2009
5478
At this stage you should observe carefully for any unresolved symbols or missing
shared libraries (.so) (or dynamic link libraries, DLLs). If you see any, you need
to resolve them, e.g. by setting LD_LIBRARY_PATH environment variable.
5479
Now, use browser to access following URLs to try your accomplishments out:
5476
5477
5481
1. https://sp1.zxidsp.org:5443/README.zxid tests (tests simple file access and
that the server works at all)
5482
2. https://sp1.zxidsp.org:5443/zxid?o=E (tests the SP CGI written in C)
5483
3. https://sp1.zxidsp.org:5443/zxid.pl?o=E (tests the SP mod_perl way)
5484
4. https://sp1.zxidsp.org:5443/zxid.php?o=E (tests the SP mod_php5 way)
5485
5. https://sp1.zxidsp.org:5443/protected/content.txt
5480
5486
5487
If any of the above does not work, be sure to inspect the apache logs (be sure to replace
/home/sampo with whatever makes sense):
197
CHAPTER 33. TRYING OUT APACHE
5488
tail -f /home/sampo/zxid/tmp/err-httpd
5490
If you can’t get any access at all, be sure you do not have the mini_httpd or some other
process running on the same port.
5491
Also make sure the execute permission is set for any CGI scripts, e.g:
5489
5492
chmod a+x zxid.pl
January 29, 2011
5493
5494
5495
5496
5497
5498
5499
5500
Chapter 34
Debugging Apache Cores
mod_auth_saml, mod_php, or mod_perl with Net::SAML can crash in C code. That
can be debugged using this receipe. If using all three simultaneously, beware of version
discrepancy: a newer module can pick up libzxid symbols from an older module. This
leads to rather confusing "warning: Source file is more recent than executable."
tail -f tmp/log.httpd tail -f tmp/err-httpd ulimit -c unlimited /apps/apache/std/bin/httpd
-X Run Apache in single threaded debug mode gdb /apps/apache/std/bin/httpd /d/sampo/zxid/core
5501
199
CHAPTER 34. DEBUGGING APACHE CORES
January 29, 2011
5502
5503
Chapter 35
Mediawiki Integration Tips
5506
MediaWiki supports the SAML identity protocol so you can use your identity by supplying IdP URL to authenticate and log nto MediaWiki! SAML support was added by
Sampo Kellomaki ([email protected]) and uses the zxid.org SSO library.
5507
This receipe is accurate as of Jan 2007, zxid-0.8 and MediaWiki-1.9.0
5504
5505
5510
Consider this receipe only one of many possible setups and not ncessarily even the best.
The receipe worked for me in August 2006. If you come much later, things may have
changed.
5511
This Apache setup aims to illustrate
5508
5509
5512
• mod_php5 invocation of zxid inside MediaWiki
5513
35.1
Prerequisites
5514
1. PHP (version 5 recommended)
5516
2. zxid base and mod_ssl dependency: openssl-0.9.8d from http://openssl.org,
usually what comes with your Linux distribution is OK
5517
3. Apache with mod_ssl and mod_php, see Apache Setup Receipe for ZXID
5515
5519
4. zxid base dependency: libcurl from http://curl.haxx.se/, usually what comes
with your Linux distribution is OK
5520
5. zxid base, e.g. http://zxid.org/zxid-0.8.tgz
5518
5521
5522
5523
5524
5525
5526
5527
tar xvzf zxid-0.8.tgz
cd zxid-0.8
make dep
make
6. zxid for PHP (part of zxid base)
make phpzxid
make phpzxid_install
# Possibly as root
201
35.2. BUILDING MEDIAWIKICHAPTER 35. MEDIAWIKI INTEGRATION TIPS
5528
35.2
5529
1. Get MediaWiki from mediawiki.org
5530
35.3
5531
Use browser to access following URLs to try your accomplishments out:
5532
5533
Building MediaWiki
Trying It Out
1. https://sp1.zxidsp.org:8443/README.zxid tests (tests simple file access and
that the server works at all)
January 29, 2011
5534
5535
Chapter 36
ZXID Testing Plan
5536
36.1
5537
1. SSO to previously unknown IdP by supplying entity ID, using Artifact
5538
2. SSO to known IdP using POST
5539
36.2
Test targets
5540
36.2.1
CGI Based Hello World Tests
5541
5542
5543
5544
5545
5546
5547
5548
5549
5550
SSO Tests
zxidhlo (the C program)
zxidhlo.sh (tests zxidsimple - the C program)
zxidhlo.php
zxidhlo.pl
zxidhlo-java.sh (tests zxidhlo.java)
36.2.2 CGI Based Full API Tests
zxid (the C program)
zxid.php
zxid.pl
zxid-java.sh
203
36.3. SIGNATURE TESTS
CHAPTER 36. ZXID TESTING PLAN
5551
36.2.3
mod_php tests
5552
36.2.4
mod_perl tests
5553
36.2.5
Tomcat Integration Tests
5554
36.2.6
mod_auth_saml tests
5555
36.3
Signature tests
5556
N.B. The signature validation requires metadata to be present.
5557
5558
5559
./zxbench -d -n 1 <t/hp-idp-post-resp.xml
./zxbench -d -n 1 <t/rsa-a7n-sig.xml
./zxbench -d -n 1 <t/slim-inner-a7n-sig.xml
January 29, 2011
5560
5561
5562
5563
5564
5565
5566
5567
Chapter 37
FAQ
37.1
Compilation Problems
• Makefile tries to compile a bunch of check programs early in the compilation
to detect common problems with missing headers (include files) and missing
libraries.
• If the checks fail, you need to adjust the -I and -L flags in Makefile variables
CDIR and LIBS (around line 123)
5569
• Alternately you can create localconf.mk file that will be included by the main
Makefile and put your modifications there.
5570
• ZXID dependency libraries are libcurl, openssl (libssl, libcrypto), and zlib
5568
5571
5572
5573
5574
5575
5576
5577
5578
5579
5580
5581
5582
5583
5584
5585
5586
5587
• Although compiling the dependency libraries from source is adviced, usually
you can use the versions that are supplied with your distribution. However in this
case you MUST install also the headers. Usually these are called "development"
packages.
• zxid assumes openssl, libcurl, Java, and Apache to be installed in the locations
where source distributions of those packages install them in their default configuration (e.g. /usr/local/ssl, /usr/local/httpd, etc.)
• Many distributions (e.g. Ubuntu, Redhat, SUSE, ...) choose to install those libraries in different places, thus requiring distribution specific edits to localconf.mk
• If you have difficulty in finding the headers and libraries (or whether a package
is installed at all), try the following commands
find
find
find
find
find
find
/
/
/
/
/
/
-name
-name
-name
-name
-name
-name
’stdio.h’
’libc.*’
’zlib.h’
’libz.*’
’opensslv.h’
’libssl.*’
205
37.1. COMPILATION PROBLEMS
find
find
find
find
find
find
find
5588
5589
5590
5591
5592
5593
5594
5595
5596
5597
5598
5599
5600
5601
5602
5603
5604
5605
5606
5607
5608
5609
5610
5611
5612
5613
5614
5615
5616
5617
5618
5619
5620
5621
5622
/
/
/
/
/
/
/
-name
-name
-name
-name
-name
-name
-name
CHAPTER 37. FAQ
’libcrypto.*’
’curlver.h’
’libcurl.*’
’ap_release.h’
’apr_version.h’
’libapr-1.*’
’servlet-api.jar’
If you find more than one of any of the above, you need to be extra careful about
which one you use.
37.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
January 29, 2011
CHAPTER 37. FAQ
5628
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.
5629
37.1.2
5623
5624
5625
5626
5627
5630
5631
5632
5633
5634
5635
5636
5637
5638
5639
5640
5641
5642
5643
5644
5645
5646
5647
5648
5649
5650
5651
5652
5653
5654
5655
5656
5657
5658
5659
5660
Missing gperf
gcc -g -fpic -fmessage-length=0 -Wno-unused-label -Wno-unknown-pragmas -fno-strict-aliasing -D_R
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
37.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.
January 29, 2011
5661
5662
5663
5664
5665
5666
5667
5668
5669
5670
5671
5672
5673
5674
37.1.4
Perl compiled with different compiler than zxid
Perl modules generally want to be compiled with the same C compiler and options as
were used to compile perl itself (see perl -V). If this happens to be different than the
compiler you have defined in CC variable (gcc by default, near top of Makefile or in
localconf.mk), you may get an error like:
cd Net; perl Makefile.PL && make
Warning: -L.. changed to -L/home/sampo/zxid/Net/..
Writing Makefile for Net::SAML
make[1]: Entering directory ‘/home/sampo/zxid/Net’
cc -c -I.. -I/apps/openssl/std/include -I/apps/include -D_REENTRANT -D_GNU_SOURCE -DT
/bin/sh: cc: command not found
make[1]: *** [SAML_wrap.o] Error 127
make[1]: Leaving directory ‘/zxid/Net’
make: *** [samlmod] Error 2
5675
Solutions
5676
1. Compile zxid with compiler that was used for perl, e.g.
make CC=the-compiler-that-perl-wants
5677
5678
5679
5680
5681
5682
5683
CHAPTER 37. FAQ
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.
5686
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.
5687
37.1.5
5688
You need to symlink zx to zxid source directory, thus
5684
5685
5689
5690
5691
5692
5693
5694
5695
All files under zx missing
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.
January 29, 2011
CHAPTER 37. FAQ
5696
37.1.6
Compiler Warnings
5700
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.
5701
Following warnings in partuclar are unwarranted:
5697
5698
5699
5702
5703
5704
5705
5706
5707
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.
5709
3. "Suggest parenthesis around && when used in ||". I rely on C language operator
precedence, hence the suggestion is redundant.
5710
Some warnings you may want to worry about
5708
5713
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.
5714
37.1.7 SWIG and Java Problems
5711
5712
5715
5716
5717
5718
5719
5720
5721
5722
5723
5724
5725
5726
5727
5728
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 p
^
public static zx_str zx_rsa_priv_dec(zx_ctx c, zx_str ciphered, SWIGTYPE_p_p_void rsa_pkey, int
^
January 29, 2011
37.2. PLATFORM SPECIFICS
5729
5730
5731
5732
5733
public static zx_str zx_rsa_priv_enc(zx_ctx c, zx_str plain, SWIGTYPE_p_p_void rsa_pke
^
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/");
^
5734
5735
5736
5737
CHAPTER 37. FAQ
zxid.java:27: cannot find symbol symbol : method url_set(zxidjava.zxid_conf,java.lang.String)
zxidjni.url_set(cf, url);
^
5738
5739
5740
zxid.java:28: cannot find symbol
5741
jar cf zxidjava.jar .class jar cf /tmp/zxidjava.jar zxidjava/.class
5742
5743
5744
5745
5746
5747
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)
^
5748
1 error
5749
Underscore in linking error
5750
5751
5752
5753
5754
5755
5756
5757
5758
./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)
January 29, 2011
CHAPTER 37. FAQ
37.2. PLATFORM SPECIFICS
5759
37.2
5760
If your Unix platform is not mentioned, you should try saying just
5761
Platform Specifics
make
5763
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.
5764
37.2.1
5765
Native development platform. Just say
5762
5766
5767
5768
5769
5770
5771
5772
5773
Linux
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.
5776
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.
5777
37.2.2
5778
No target available on Makefile, but a port is available from http://www.freshports.org/security/zxid/
5779
37.2.3
5774
5775
5780
5781
5782
5783
5784
5785
5786
FreeBSD
Solaris (Sparc)
make TARGET=sol8
make TARGET=xsol8
# Cross compile for Solaris (e.g. on Linux host)
37.2.4 MacOS X (PowerPC?)
make TARGET=macosx
37.2.5
Windows Using MinGW
make zxid.dll TARGET=xmingw
make zxid.dll TARGET=mingw
# Cross compile on Linux host (best supported)
# Native compile for mingw target in Cygwin environment
5788
Either way, the net result is native Windows DLL that does not have Cygwin library
dependencies or GPL encumberation.
5789
See Makefile for further mingw notes.
5787
January 29, 2011
37.3. CONFIGURATION QUESTIONS
5790
5791
5792
5793
5794
5795
5796
5797
5798
5799
5800
5801
37.2.6
CHAPTER 37. FAQ
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.
5803
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.
5804
The results of Cygwin compile may be GPL encumbered due to libraries.
5805
37.2.7
5802
5806
5807
5808
5809
5810
5811
5812
5813
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.
As of June 2010 the MSVC support has improved. The sed dependency was removed
and any C language constructs that MSVC has indigestion with have been removed.
We are still aiming at Makefile based build using Microsoft’s cl compiler. You should
try
make TARGET=win32cl
5817
If you manage to build it using some IDE project, please contribute the project file.
For ongoing maintenance, it would be good if the project was a text file to which new
source code files and be added easily without using the IDE, i.e. using simple text
editor.
5818
37.3
5819
1. Q: In mod_auth_saml, what is the relation between ZXIDConf and httpd.conf?
5814
5815
5816
5820
5821
5822
5823
Configuration Questions
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).
January 29, 2011
CHAPTER 37. FAQ
5824
5825
2. Q: In mod_auth_saml, what is the relation between the port in ZXIDConf and the
port in the httpd.conf?
5827
A: The ports must agree. ZXID configuration must match the way the Apache layer
is configured.
5828
3. Q: Multiple roles of same entity, acting as SP, WSC, and WSP for different services
5826
5829
5830
5831
5832
5833
5834
5835
5836
5837
5838
5839
5840
5841
5842
5843
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.
5847
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.
5848
No confusion as far as I can see.
5844
5845
5846
5849
5850
5851
5852
5853
5854
5855
5856
5857
5858
4. Q: What the "Entity ID" and the "Service Type" should be?
While entityID and Service Type selection are flexible and there is sophisticated
philosophy behind them, the short answers are:
a. entityID should be the URL from which your metadata can be fetched. The
URL should match the entityID field inside the metadata document. In zxid
deployments the entityID usually ends in "?o=B" and be beginning part depends
on the URL configuration parameter.
b. Service Type should be the namespace URI of the (first) top level child of SOAP
envelope Body element.
Cheers, –Sampo
January 29, 2011
5859
5860
5861
37.3.1
CHAPTER 37. FAQ
No certificates appear in metadata
Q: I’ve been trying to set up ZXID’s mod_auth_saml on an OS X server. The EntityDescriptor XML doesn’t seem to contain the public x.509 cert.
5864
A: The metadata (the URL ending in o=B) will not have certificates if none actually
were available. Thus visualizing the metadata in a brower is a good way to check
whether it is finding the certs. So it is a feature ;-)
5865
Q: +Does mod_auth_saml use the cert from /var/zxid/pem/ssl-nopw-cert.pem?+
5866
A: The certs for metadata live in files
5867
/var/zxid/pem/sign-nopw-cert.pem /var/zxid/pem/enc-nopw-cert.pem
5862
5863
5868
5869
5870
5871
5872
5873
5874
5875
5876
5877
5878
In more recent versions (current is 0.38, which version were you using?) ZXID will
automatically generate self signed certs if the certs are not installed yet. However it
may fail to write them to the filesystem due to permissions problem. You should check
that the user as which Apache runs can indeed read from and write to /var/zxid/pem
directory.
If you want to use officially issued certificates, you will of course need to place them in
the two files mentioned. Please note that the files should be concatenation of certificate
and the private key. Due to this and the practise of not using password on the private
keys you should pay attention to protecting these files with filesystem permissions the caveat is that if you protect too well then even the apache process can’t read them.
Recommended permissions are
chown APACHEUSER /var/zxid/pem
chmod -R 02750 /var/zxid/pem
5879
5880
5882
where APACHEUSER is distribution dependent user account used to run the apache
process. You can do ‘ps axu | grep httpd’ to see what user apache runs as.
5883
37.3.2
5881
I was hoping that you could answer a question for me about mod_auth_saml.
I have it installed on CentOS5 with Apache and every request to our protected URL does bring up the IDP selection screen. Since we only want
customers to use the sole IDP we have configured, we’d like to automatically redirect to the IDP instead of having the users’s click a login button.
5884
5885
5886
5887
5888
5889
5890
5891
5892
5893
5894
5895
Skipping IdP Selection: Hardwiring the IdP
>
Is there a setting for zxid.conf or Apache that I need to set so it will
always redirect to the sole IDP if a session needs to be created without
presenting that IDP selection screen?
This in fact is possible. It is a bit convoluted (and not documented) in that it effectively
works by simulating submission of the IdP selection screen, with the form fields and all.
This is done by setting DEFAULT_QS configuration option. For example, following
January 29, 2011
CHAPTER 37. FAQ
5896
37.4. API QUESTIONS
ZXIDConf "DEFAULTQS=l0https://idp.tas3.eu/zxididp%25%33%66o%25%33%3dB=1%26fc=1%26fn=prstnt"
5901
would simulate clicking login button for idp.tas3.eu. Note the URL escaping that
needs to be applied: %25%33%66 is decoded by the configuration layer to mean
"%3f", which is how at query string layer the question mark needs to be escaped. The
%26 means ampersand that separates the arguments at querystring layer. It is encoded
only once. Hope this is not too confusing.
5902
37.3.3
5897
5898
5899
5900
5903
5904
5905
5906
5907
5908
5909
5910
5911
5912
5913
5914
5915
5916
5917
5918
5919
Web Service Provider Metadata
The metadata is needed in the web service call mainly to know the certificates. The
endpoints in the metadata are ignored for purposes of the web service call as the endpoint is supplied by the EPR.
Since SAML defines a metadata format with certificates (and SAML relevant endpoints), the convention is that web service call consults the SAML metadata for the
certificates.
It is very common for same service to be accessible as a web GUI (SAML SP) and web
service (ID-WSF WSP), therefore it is considered convenient for the SAML metadata
to be used.
If the service does not want to be SAML SP and only wants to be ID-WSF WSP, then
it still needs to supply the SAML SP metadata just for the purpose of the certificates
(the SAML SP end point URLs will not be used).
My service only wants to be a ID-WSF WSP. For example, Custodix want
to be able to call a SOA Gateway web service, and the SOA Gateawy
knows nothing about SAML, etc.
I need to ensure that ZXID will process necessary soap headers and accept
or reject as appriorate.
5923
You still need to generate metadata. Since your service does not have SAML SP facet,
you can’t (directly) use o=B method (but see my example zxidwspdemo.java how
it still supports o=B). However you can just hand edit a metadata file (perhaps using
something from o=B as a template).
5924
If you place the hand edited metadata in the right file on WSC side, using
5920
5921
5922
5925
.zxcot -a <meta.xml
5926
then no dynamic metadata fetch will be attempted and you do not need to support o=B.
5927
See also zxid-idp.pd for registration of EPR and bootstrap.
January 29, 2011
37.4. API QUESTIONS
CHAPTER 37. FAQ
5928
37.4
5929
1. *Q*: What do I need to pass in as enve argument to zxidjni.wsc_prepare_call()?
5930
5931
5932
5933
5934
5935
5936
5937
5938
5939
5940
5941
5942
5943
API Questions
*A*: zxidjni.wsc_prepare_call() has some auto detection. If you pass entire SOAP
<e:Envelope>, then it will just add some headers. If you pass <e:Body> it will add
<e:Envelope> and headers. If you pass anything else, it assumes that is meant to be
content of the body and will add <e:Envelope><e:Headers>...</><e:Body>your
stuff</></>
2. *Q*: What exactly is a "sha1 name"?
*A*: Since ZXID (originally) uses filesystem as backend, a method for generating
filesystem-safe strings, to be used as filenames, was needed. Further, there was
occasionally requirement that each different file have different name. Solution to
these problems is to hash the whatever part that is unique and use safe base64 [?]
encoding of the hash as the filename.
They are not very human friendly, but they are filesystem safe and unique as required. They are also constant width, which tends to make directory listing prettier,
and also handles anomalously long Entity IDs gracefully.
5948
sha1 hashing is much less error prone than trying to escape or squash the various
Entity IDs, Name IDs, and who-know-what to be filesystem safe. Add to the squasing bugs, the convolutions of ensuring uniqueness and dealing with too long input
and you should see why sha1 names are the most secure, easiest to implement, approach.
5949
See also sha1_safe_base64() in zxutil.c
5944
5945
5946
5947
5950
5951
5952
5953
5954
5955
5956
5957
5958
5959
5960
5961
5962
5963
5964
5965
5966
5967
37.5
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 ?? 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
January 29, 2011
CHAPTER 37. FAQ
5968
5969
5970
5971
5972
5973
5974
5975
5976
5977
5978
5979
5980
5981
5982
5983
5984
5985
5986
5987
5988
5989
5990
5991
5992
5993
5994
5995
5996
5997
5998
5999
6000
6001
37.5. COMMON MISTAKES
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 . See [?] 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.
6004
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.
6005
7. Writes a user...
6002
6003
6006
6007
6008
6009
6010
6011
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
January 29, 2011
37.5. COMMON MISTAKES
6012
6013
6014
6015
CHAPTER 37. FAQ
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?
6016
It is supposed to be /var/zxid/cot
6017
When configuring PATH, did you forget trailing slash? E.g.
6018
6019
6020
6021
6022
6023
6024
6025
"PATH=/var/zxid&URL=..."
"PATH=/var/zxid/&URL=..."
# WRONG!
# 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.
10. Q1: I get rejection due to NotOnOrAfter or NotBefore. I think I have synchronized
the clocks on IdP and SP. Log messages are
t
t
zxidsso.c:466 zxid_validate_cond
zxidsso.c:476 zxid_validate_cond
zx d ssof: NotOnOrAfter ok. Time to expi
zx E ssof: NotBefore rejected with slop
6030
A1: This seems awful lot like a timezone issue. Slop is ZXID config parameter
that defines the tolerance. I recently reduced it from 1 day to 3 hours because I got
feeback that it was security issue to have such overbroad tolerance (which it is, but
1 day slop allows people with bad time zone configs to still have initial success may be I go back to one day).
6031
On both IdP and SP, run
6026
6027
6028
6029
6032
TZ=GMT date
6036
and see if that is about 6 hour difference. I stronly suspect other machine being
correctly on GMT (which does not even have concept of summer time that causes
so much productivity losss :-) and other is on something like US Central time (your
guess if summer time error applies).
6037
You can synchronize using
6033
6034
6035
6038
6039
6040
6041
6042
6043
6044
6045
6046
6047
6048
6049
TZ=GMT ntpdate ntp1.funet.fi
(there may be server closer to you than Finland)
Q2: I double checked the clocks, the SP and IdP are very close to our NTP server,
within 100ms or so. Why would it say there’s a slop of 7300 seconds?
A2: Slop is just tolerance. The real problem is "Time to validity 21600 secs". If
you can’t get the clocks to synchronize, you can increase the config option BEFORE_SLOP=22000 in /var/zxid/zxid.conf. This of course has some security
implications.
Q3: My time zone is set to CDT on both machines. Is it possible that Shibboleth
is using GMT and zxid is using my local time? (Or the other way around) 21600
seconds seems too obvious to be a real clock skew. If both systems have the same
locale settings, then something in software must be choosing the wrong time zone.
January 29, 2011
CHAPTER 37. FAQ
37.6. CONSENT
6052
I set TIMEOUT_FATAL=0 and it does work. I get my nid and my login session is
working! So, major hurtle accomplished, but I think I’d like to get to the bottom of
this and find out what the real problem is.
6053
A3: 21600 seems very obvious timezone issue.
6050
6051
6054
6055
6056
6057
6058
6059
On Unix the timezone behavior of a process is determined by setting of TZ environment variable. To my best knowledge I always use gmtime(3) which to my best
understanding ignores the TZ environment variable. However, it is possible that I
errornously or the Shib IdP use localtime(3), which will take TZ in account. Therefore I recommend launching all processes with environment TZ=GMT (see the date
example above).
6060
37.5.1
6061
How to decode auto_flags
6062
6063
6064
6065
6066
6067
6068
6069
6070
6071
6072
6073
6074
6075
6076
6077
6078
6079
6080
6081
6082
6083
6084
6085
6086
6087
Doubts
0x1d54
37.6
1 = debug; d = FORMT + FORMF + MGMTC; 5 = METAC + LOGINC; 4 = SOAPC
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).
January 29, 2011
37.7. DEPLOYMENT PLANNING
6088
6089
6090
6091
6092
6093
6094
6095
6096
6097
6098
6099
6100
6101
6102
6103
6104
6105
6106
6107
6108
6109
6110
6111
6112
6113
6114
6115
6116
6117
6118
CHAPTER 37. FAQ
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.
6121
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.
6122
37.7
6123
Here is a rudimentary decision tree for deployment planning
6124
1. List your applications
6119
6120
6125
Deployment Planning
a. Any provided by external partner?
January 29, 2011
CHAPTER 37. FAQ
37.8. USE OF SIGNING AND CRYPTO, SECURITY CONCERNS
6126
6127
b. Non web apps
2. Document your existing identity stores and approaches to
6128
a. User provisioning (when someone is employed)
6129
b. Application provisioning (when someone starts using app)
6130
c. Authorization: how do you know who is supposed to be doing what?
6131
d. Deprovisioning: what happens when someone is fired?
6132
e. Login? Per app? Harmonized user names? Enterprise SSO?
6133
3. Document your goal: federated SAML SSO über alles :-)
6134
a. Do you want to run IdP?
6135
b. Could you out-source IdP?
6136
c. Will your partners / customers be running their own IdPs?
6137
6138
d. Will you participate (or run) single CoT or do you need to consider cross CoT
inter-operation (e.g. IdP proxying)
6139
To be continued...
6140
37.8
Use of Signing and Crypto, Security Concerns
6141
37.8.1
How is mod_auth_saml better than HTTP Basic Auth that
it claims to emulate? HTTP Basic Auth does not address
transport encryption. Is mod_auth_saml HTTP Basic Auth
emulation vulnearable due to this?
6142
6143
6144
6145
6146
6147
6148
6149
6150
6151
6152
6153
6154
6155
6156
6157
I have looked at HTTP basic auth and it does not provide any transport
level security, is it secure to use HTTP basic auth with certificates? is it
common to do it that way?
HTTP-Basic is a method for authenticating a user using username and password. This
is orthogonal to whether the connection is encrypted. Most common current practise is to combine HTTP-Basic-Auth with TLS (SSL) encryption. This is considered
safe, to the extent that passwords can ever be safe. mod_auth_saml keeps the TLS
encryption part intact, but improves on the password insecurity part by either allowing
nonpassword authentication, such as Yubikey token, or at least allowing one password
disclosed to only one party (the IdP), rather than multiple passwords at multiple parties
(the weakness of the latter approach is that the users tend to use the same passwords
at the multiple parties, allowing each party to impersonate the user at the other party and then there is the guessable password vulnearability).
January 29, 2011
37.8. USE OF SIGNING AND CRYPTO, SECURITY CONCERNS
CHAPTER 37. FAQ
6158
6159
6160
6161
6162
6163
6164
6165
6166
6167
6168
6169
6170
6171
6172
6173
6174
37.8.2
Receipe for debugging signature validation problems
This mail thread fragment discusses how to debug signature problems between ZXID
deployments. If the signer is not ZXID, then you need to figure out how to get it to
print the canonicalized form. Often this turns out to be surprisingly difficult because
the signing end uses some library which does not document how this vital debugging
information can be obtained.
> > Message digest does not match because canonicalizations
> > are different. You can dig the canonicalized forms of body from /var/zxi\
d/log/xml.dbg
> > There should be one entry from time when signature is created and anothe\
r from time
> > the signature validation was attempted. The two are different.
> >
> > BTW, I usually run
> >
> > tailf /var/zxid/log/xml.dbg | ./xml-pretty.pl
> >
6175
6176
6177
6178
6179
6180
6181
6182
6183
6184
6185
6186
6187
6188
> The failure appears in log as:
>
> 
> <a:MessageID xmlns:a="http://www.w3.org/2005/08/addressing"
> xmlns:e="http://schemas.xmlsoap.org/soap/envelope/"
> xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecur\
ity-utility-1.0.xsd"
> wsu:Id="MID" e:actor="http://schemas.xmlsoap.org/soap/actor/next"
> e:mustUnderstand="1">urn:MlQY4jARBIitwHPf6vIIyk_LZ</a:MessageID>
> 
>
> now what?
6189
6190
6191
6192
Yes, this is the failure, but somewhere earlier in the log (perhaps in diffe\
rent server - the
WSC server), there should be block labelled similar to
6193
6194
6195
6196
6197

...

zx d call:
SIG CANON len=33\
6198
6199
6200
6201
You can find it quickly by searching backwards for something like the messag\
e ID or timestamp
string.
6202
6203
6204
6205
That block indicates how the signer canonicalized the blob. I claim the two \
will turn
out to be different. Once the difference is known, I can investigate whether\
January 29, 2011
CHAPTER 37. FAQ
37.9. AUDIT TRAIL
6207
it is
my bug or due to somehow malformed or incomplete input.
6208
37.8.3
6206
6209
6210
6211
6212
Signature validation problems in body
In typical web service call, using zxid_call() API, the programmer supplies a fragment
of payload XML. This can be a source of canonicalization problems.
ZXID will attempt to canonicalize it on basis of well formed XML and if it is not well
formed, it will almost certainly give unpredictable results.
6216
Another common problem is omitting namespace declarations: ZXID considers all
XML to have namespace, and if it does not find a namespace, then it will fabricate one.
By supplying a namespace declaration, you control the situation instead of relying on
unpredictable fabricated one.
6217
37.8.4
6218
The logs say VFY FAIL CANON SIGINFO
6213
6214
6215
6219
6220
6221
VFY FAIL CANON SIGINFO
Basically a signature has message digests at two layers: 1. over payload data (e.g.
#BDY), 2. over the <SignedInfo> element. The latter is what gets private key encrypted when signature is made. The encrypted value appears in <SignatureValue>.
6224
The validation decrypts <SignatureValue> with public key from cert. If the public
key does not match the private key, you will get, if you are lucky, a padding error, which
you were getting earlier. But if you are not lucky, you will just get garbage decrypt.
6225
The garbage decrypt is then compared against message digest computed over <SignedInfo>.
6222
6223
6226
6227
6228
6229
6230
6231
This is reported as VFY FAIL CANON SIGINFO, which may be misleading if the
real reson was garbage decrypt. However, it would be the right error message in case
the <SignatureValue> decrypt was valid, but the <SignedInfo> had actually been
tampered with.
I would concentrate the investigation on the theory of garbage decrypt due to wrong
certificate.
6233
The certificate for signature validation is chosen on basis of <Sender> header’s providerID
XML attribute.
6234
37.9
6235
1. How can I see what attributes the single sign on assertion contains?
6232
Audit Trail
6236
From IdP side (assuming zxididp, for other IdPs consult respective documentation):
6237
a. Locate the SSOA7N line from IdP activity log, e.g.
grep SSOA7N /var/zxid/log/act
6238
6239
which might return (single line, linewrap is only for this document)
January 29, 2011
37.10. VENDOR PRODUCTS
PP - 20100112-144157.750 20100112-144157.750 127.0.0.1:- \
9u_7LsQjkz0VaXKucmx1_sYjQnM - AWTILy8_0yre96om7n4H-4fMW ENC \
zxidp U K SSOA7N - -
6240
6241
6242
6243
6244
b. The 8th field is the assertion ID, here AWTILy8_0yre96om7n4H-4fMW. With
A7N ID you can grep the issued assertions, e.g.
grep -l AWTILy8_0yre96om7n4H-4fMW /var/zxid/idplog/issue/*/a7n/*
6245
6246
which might return something like
/var/zxid/idplog/issue/9u_7LsQjkz0VaXKucmx1_sYjQnM/a7n/MxevnQGqKFwyBTPUZ-h
6247
6248
6249
This file contains the assertion in plain text. You can inspect it to see what
NameID is sent and what attributes are sent. One convenient command is
grep -l AWTILy8_0yre96om7n4H-4fMW /var/zxid/idplog/issue/*/a7n/* \
| xargs cat | ./xml-pretty.pl
6250
6251
6252
6253
From SP side the steps would be
i. Locate FEDSSO line
grep SSOA7N /var/zxid/log/act
6254
6255
which might return (single line, linewrap is only for this document)
PP - 20100112-144639.184 20100112-144157.501 -:- \
xsKJr3DL7sUPDdbdqgC2H_eP-UM - AWTILy8_0yre96om7n4H-4fMW \
FIrFwFdR4wO2UFLQZl8c3LlUW
zx O K FEDSSO MSES6GOG4ta-nQdYlRVJriv24dj8
6256
6257
6258
6259
6260
CHAPTER 37. FAQ
ii. The 8th field is the assertion ID. To locate the assertion in the rely audit trail of
the SP you can grep as follows:
grep -l AWTILy8_0yre96om7n4H-4fMW /var/zxid/log/rely/*/a7n/* \
| xargs cat | ./xml-pretty.pl
6261
6262
6263
37.10
Vendor products
6264
37.10.1
Symlabs Federated Identity Suite (SFIS)
6265
Interoperates. SP and IdP.
6266
Metadata import to IdP?
6267
What I usually do is
6268
6269
6270
6271
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.
January 29, 2011
CHAPTER 37. FAQ
6272
6273
6274
6275
6276
6277
6278
6279
6280
6281
6282
6283
6284
6285
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
6286
If this is not done, the SSO will fail (with what appears like signature error).
6287
37.10.2
Shibboleth and OpenSAML
6289
Shibboleth 2.1.5 IdP interoperates since 0.65. Earlier versions interoperated in some
configurations.
6290
Many Shibboleth SPs interoperate (exact version numbers lost).
6291
37.10.3
6292
Used to work, may be still does. Not tested in recent memory.
6293
37.10.4
6294
Used to work, may be still does. Not tested in recent memory.
6295
37.10.5
6288
Lasso and Authentic
OpenSSO
simpleSAMLphp
6298
Interoperates, but as of Sept 2010, simpleSAMLphp IdP has problems with EncryptedAssertions. Nothing ZXID can do (but you can turn off the encryption if you are willing to
assume the consequences).
6299
simpleSAMLphp SP works.
6296
6297
January 29, 2011
6300
37.10.6
6301
Not tested in recent memory.
6302
37.10.7
6303
CRLF emitting. Works since 0.65.
6304
37.10.8
6305
6306
6307
6308
6309
6310
6311
CHAPTER 37. FAQ
Ping
SiteMinder
Bouncing Castle vs. OpenSSL Padding Problem
There is a XML ENC padding problem between OpenSSL and Bouncing Castle Java
Crypto Library. See OpenSSL bug number 1067: http://rt.openssl.org/Ticket/Display.html?user=guest&;pass=gu
From: [email protected]
To: [email protected], [email protected]
Cc: [email protected], [email protected]
Subject: OpenSSL symmetric crypto padding check incompatible with XMLENC
Date: Thu, 12 May 2005 20:22:50 +0000
6312
6313
Please find below a patch, with spec reference, against OpenSSL 0.9.7g.
6314
6315
6316
6317
6318
6319
6320
It could be argued that XMLENC spec is wrong in insisting on unpredictable
values for the padding because this allows padding to be used as a
covert channel. However, to deploy interoperable implementations it seems
patching OpenSSL is the right thing to do. It has been observed that
other crypto libraries, such as bouncing castle (a pure Java
implementation) do not set all padding bytes to OpenSSL’s satisfaction.
6321
6322
--Sampo
6323
6324
6325
6326
6327
6328
6329
6330
6331
6332
6333
6334
6335
6336
6337
6338
6339
6340
6341
--- evp_enc.c~ 2005-01-28 14:03:53.000000000 +0000
+++ evp_enc.c 2005-05-12 03:26:44.000000000 +0000
@@ -509,6 +509,21 @@
EVPerr(EVP_F_EVP_DECRYPTFINAL,EVP_R_BAD_DECRYPT);
return(0);
}
+#ifdef PADDING_CHECK
+ /* Following loop checks that all padding has known value,
+ * presumably to prevent covert channel or some form of
+ * chosen text attack. However this check is in violation
+ * of [XMLENC] specification section 5.2 subsection
+ * "Padding", which states that only last octet of the
+ * block matters and values of other octets are not
+ * predictable. Thus to implement XMLENC decryption with
+ * openssl it is necessary to disable this code.
+ * -- 11.5.2005, Sampo Kellomaki ([email protected])
+ *
+ * [XMLENC] D. Eastlake, ed., XML Encryption Syntax and
January 29, 2011
CHAPTER 37. FAQ
6342
6343
6344
6345
6346
6347
6348
6349
6350
6351
6352
6353
6354
6355
37.11. KNOWN BUGS
+ * Processing, W3C Recommendation 10. Dec. 2002,
+ * http://www.w3.org/TR/2002/REC-xmlenc-core-20021210 */
+
for (i=0; i<n; i++)
{
if (ctx->final[--b] != n)
@@ -517,6 +532,7 @@
return(0);
}
}
+#endif
n=ctx->cipher->block_size-n;
for (i=0; i<n; i++)
out[i]=ctx->final[i];
6356
6357
-----------
6358
6359
6360
OpenSSL is complying with various other standards with its current
behaviour. For example PKCS#7.
6361
6362
6363
6364
6365
If the EVP functions are being called directly (instead of inside
OpenSSL in its PKCS#7 code for example) you can disable the padding
altogether EVP_CIPHER_CTX_set_padding() and perfom padding and pad
checking at an application level.
6366
6367
Steve.
6369
Since ZXID version 0.65 (Oct 2010), this has been addressed via the EVP_CIPHER_CTX_set_padding()
route.
6370
37.11
6368
Known Bugs
6372
Following are known limitations. We document them here because we do not plan to
fix them in foreseeable future.
6373
1. Namespace qualified XML attributes have underscore instead of colon
6374
37.12
6375
"Random number generator not seeded!!!"
6371
6376
6377
6378
6379
6380
Mysterious Error Messages
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.
January 29, 2011
37.13. CERTIFICATES AND PRIVATE KEYS
6381
6382
CHAPTER 37. FAQ
"msg 123: 1 - error:140770F8:SSL routines:SSL23_GET_SERVER_HELLO:unknown
proto"
6385
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.
6386
"msg 123: 1 - error:02001002::lib(2) :func(1) :reason(2)"
6383
6384
6387
6388
6389
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
6390
37.12.1
6391
This is due to locale setting. Try
6392
6393
snprintf() multibyte character related errors in log
export LANG=C
This will disable any UTF-8 processing in sprintf().
6395
BTW, Win32 native _snprintf() on does not nul terminate if buffer is full. Gotcha! All
zxid code has additional manual nul termination, just in case.
6396
37.12.2
6394
6397
6398
6399
6400
6401
6402
6403
6404
6405
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 end. 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.
6408
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.
6409
37.13
Certificates and Private Keys
6410
37.13.1
Password is being asked for private key
6406
6407
6412
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.
6413
One way to remove password is
6411
January 29, 2011
CHAPTER 37. FAQ
6414
6415
6416
6417
37.13. CERTIFICATES AND PRIVATE KEYS
openssl rsa -in key.pem -out keyout-nopw.pem
For this to work, key.pem must have only the private 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.
6419
Scan OpenSSL.org for the FAQ for full explanation on how to remove password from
the private key.
6420
37.13.2
6418
6421
6422
6423
6424
Quick command for looking at certificate
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:
6426
If the domain name is different, then you need to obtain a certificate with correct domain name, see next question.
6427
37.13.3
6425
Self signed certificate
6432
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.
6433
For production or security sensitive install you need to either
6428
6429
6430
6431
6436
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,
6437
2. Generate your own certificate. The simplest case is a self signed certificate:
6434
6435
6438
6439
6440
6441
6442
6443
6444
6445
6446
6447
6448
6449
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.
January 29, 2011
37.14. AUTHOR’S PET PEEVES
6450
6451
6452
6453
6454
37.13.4
CHAPTER 37. FAQ
Installing CA Certificates
Some versions of libcurl apparently do not respect setting CURLOPT_SSL_VERIFYHOST
to 0 and thus require a CA certificate to be trusted. This may result SSL connection
error messages like
CURLcode(35) CURLerr(SSL connect error)
6455
See: http://gagravarr.org/writing/openssl-certs/others.shtml#ca-openssl
6456
To fix this
6457
1. Determine what is your OpenSSL library’s directory ("OPENSSLDIR")
strace -e file openssl version 2>&1 | grep openssl.cnf
6458
6459
6460
6461
may result
open("/apps/openssl/0.9.8g/ssl/openssl.cnf", O_RDONLY|O_LARGEFILE) = 3
Here the /apps/openssl/0.9.8g/ssl/ is the OPENSSLDIR.
6463
2. Download from the certificate authority their certificate in PEM format ("Apache"
format) and save it in OPENSSLDIR/cert.pem
6464
3. Check
6462
6465
6466
6467
6468
6469
6470
6471
openssl verify -CApath OPENSSLDIR/certs/ OPENSSLDIR/cert.pem
which should in successful case print
/apps/openssl/0.9.8g/ssl/certs/the_ca.pem: OK
If the hash is not right, it will print something like
/apps/openssl/0.9.8g/ssl/certs/the_ca.pem: /C=US/O=TheCA/OU=TheCA
error 18 at 0 depth lookup:self signed certificate
OK
6473
4. Alternative approach using certs/ directory with hashes. Save the certificate under
OPENSSLDIR/certs with any name (say, the_ca.pem)
6474
5. Create a hash
6472
6475
6476
6477
cd OPENSSLDIR
ln -s the_ca.pem ‘openssl x509 -hash -noout -in the_ca.pem‘.0
6. Check: see step 3, substituting cert.pem with the_ca.pem.
January 29, 2011
CHAPTER 37. FAQ
6478
37.14
6479
1. What is Schema Grammar (.sg) and why are you using it?
6480
6481
6482
6483
6484
6485
6486
6487
Author’s Pet Peeves
• 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.
6489
• Schema Grammar descriptions are usually converted using xsd2sg.pl, which
is part of the PlainDoc distribution.
6490
• See http://mercnet.pt/plaindoc
6488
6491
6492
6493
• N.B. You do not need xsd2sg.pl or PlainDoc if you just want to compile and
use ZXID.
2. What is PlainDoc (.pd)?
6495
• PlainDoc is a document preparation system that uses intuitive plain text files
with minimal markup to generate PDF and HTML outputs.
6496
• We use PlainDoc because it makes it easy to maintain documentation.
6497
• See http://mercnet.pt/plaindoc
6498
• N.B. You do not need PlainDoc if you just want to compile and use ZXID.
6494
6499
6500
6501
6502
6503
6504
6505
6506
6507
6508
6509
6510
6511
6512
6513
6514
6515
6516
6517
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).
January 29, 2011
6518
6519
6520
6521
6522
6523
6524
6525
6526
6527
6528
6529
6530
6531
6532
6533
6534
CHAPTER 37. FAQ
• 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.
6535
37.14.1
6536
A recent (Sept 2006) conversation that touched on the aims of ZXID project:
6537
6538
6539
6540
6541
6542
6543
6544
What does ZXID aim at - an answer
Q: 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).
6547
It is Apache licensed project, of course, so if someone contributes the IdP and WSP
capabilities, I’ll merge them into the distribution. (IdP and Discovery exist in the distribution as of Janyary 2010.)
6548
I am interested to have it working with other people’s code at 3 levels:
6549
1. Over-the-wire interoperability
6545
6546
6550
6551
6552
6553
6554
6555
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.
January 29, 2011
CHAPTER 37. FAQ
6556
6557
6558
6559
6560
6561
6562
6563
6564
6565
6566
6567
6568
6569
6570
6571
6572
6573
6574
6575
6576
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.
Q: 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.
6579
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.1
6580
37.14.2
6577
6578
6581
6582
6583
6584
6585
6586
6587
6588
6589
6590
6591
Annoyances and improvement ideas
There is a lot of commonality that is not leveraged, especially in the way service end
points are chosen 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.
1 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.
January 29, 2011
CHAPTER 37. FAQ
6592
37.14.3
6593
1. Destination XML attribute is needed in redirect and POST bindings.
6594
6595
6596
6597
6598
6599
6600
6601
6602
6603
6604
6605
6606
Non-obvious SAML
2. Assertion//SubjectConfirmationData/@InResponseTo XML attribute is needed in
SSO assertions, unless the SSO was unsolicited. SAML is not very explicit about
this, [?], ll.729-732 describes it as optional, but [?], 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 [?], Table 1 "Possible Implementations", p.6. None of the offical
profiles, see [?], 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.
6610
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.
6611
5. Interpretation of metadata KeyDescriptor/EncryptionMethod
6607
6608
6609
6612
6613
6614
6615
6616
6617
6618
6619
6620
6621
6622
6623
6624
6625
6626
6627
6628
6629
6630
6631
6632
6633
6634
Algos on [?], section 4.2 "XML Encryption Algorithms", ll.252-253.
The interpretation in [?], section 2.4.1.1 "Element <KeyDescriptor>", ll.621624, 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 [?] is allowed. If specified, but the algo is
not authorized by [?], 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
January 29, 2011
CHAPTER 37. FAQ
6635
6636
6637
6638
6639
6640
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 ([?], sec 4) encoding
had been used in the first place.
6645
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.
6646
11. EncryptedAssertion and EncryptedID: how is the EncryptedKey found?
6641
6642
6643
6644
6647
6648
6649
6650
6651
6652
6653
6654
6655
6656
6657
6658
6659
6660
6661
a. The EncryptedData/KeyInfo/RetrievalMethod references the Id attribute of
the EncryptedKey element, which is sister of the EncryptedData. Shibboleth
2010 can be kludged to work with this method if EncryptedKey element has
Recipient XML attribute equal to the EntityID of the SP. This is nowhere well
documented, but appears to work.
b. EncryptedKey is child of EncryptedData/KeyInfo, i.e. EncryptedData/KeyInfo/EncryptedKey.
Shibboleth SP appears to use this latter method as of 2010. Scott ackowledged
method (a) as also valid and will fix Shibboleth SP.
See saml-core-2.0-os.pdf, sec 2.2.4 Element <EncryptedID>, p.14, l.495 specifies that EncryptedData and EncryptedKey are sister elements. See also ll.515-521
for schema fragment. Sec 2.3.4 Element <EncryptedAssertion> on p.17 contains
similar language. as does 2.7.3.2 Element <EncryptedAttribute> on p.31.
37.14.4
Non-obvious ID-WSF
1. Should you include Sender SOAP header? Conor says usually not. But how do you
then know SOAP request issuer? Perhaps from some field of the signature?
6664
2. In case bearer token is <EncryptedAssertion>, how is env->Header->Security>SecurityTokenReference->KeyIdentifier populated (normally it would be populated from Assertion->ID)?
6665
37.14.5
6662
6663
6666
6667
6668
6669
6670
6671
Non-obvious XML Exclusive Canonicalization (XML-EXCC14N)
XML Exclusive Canonicalization bugs cause vast majority of signature failures (once
trivial configuration issues like using wrong certificates are taken care of). Here are
some gotchas:
1. XML namespace prefixes must be tracked correctly and they can alter at every layer,
even reusing already used prefixes.
January 29, 2011
6672
6673
6674
6675
6676
6677
6678
6679
6680
6681
6682
6683
CHAPTER 37. FAQ
2. InclusiveNamespaces/@PrefixList namespaces must always be rendered. However,
if the list inclides a prefix that in fact has not been declared in parent node of
the canonicalization, then this prefix is supposed to be ignored (says Scott Cantor, 20101005). I have not found any specification references saying this to be the
case. In fact [?] section 3, bullet 2, and section 3.1, bullet 3.2.1, seem to imply otherwise. However if the prefix has not been declared, it is not easy to see how the spec
could be satisfied (unless a bug leaks the declaration from inside the canonicalized
element, such as ds from embedded signature).
3. Pay attention to line end canonicalization ([?], section 1.1 "Terminology", 3rd bullet): CRLF to LF. Many implementations only ever produce NL, or avoid producing any superfluous whitespace at all (best strategy to avoid interop problems), and
therefore work fine until the day when CRLF emitting implementation appears.
6685
4. Namespace declarations are ordered by namespace prefix, while namespaced attributes are ordered by namespace URI. Gotcha!
6686
37.14.6
6684
6687
6688
6689
6690
6691
6692
6693
6694
6695
6696
6697
6698
6699
6700
6701
6702
6703
6704
6705
6706
6707
6708
6709
6710
6711
6712
6713
6714
6715
6716
I do not want to know service type, but I want to call the
service
if possible i would be able to create a new structure zx_a_EndpointReferenc\
e_s
[11:50:11] ? from scratch where i can set the url that can be get from
[11:50:21] ? zxidjni.get_epr_address(cf, epr);
[11:59:00] sampo.kellomaki: Hmm. EPRs are complex objects. Even if you creat\
ed a blank EPR with just URL in it, it would not be all that useful without \
the <Metadata> and especially <SecurityContext> with token within.
[11:59:52] Gulyx: ok i see
[12:00:05] ? however as we discussed in sophia
[12:00:35] ? the statement : SWIGTYPE_p_zx_a_EndpointReference_s epr = zxidj\
ni.get_epr(cf, zxses, "x-recurs", null, null, null, 1);
[12:00:52] ? may be moven from the axis2 zxid module
[12:00:59] ? to the application level
[12:01:23] ? in this way the developer can choose
[12:01:27] sampo.kellomaki: It is also suboptimal that the datatype is as ug\
ly as zx_a_EndpointReference_s. Since EPRs clearly have arisen to be a conce\
pt that user of the API actively have to known about, I should typedef that \
to be zxid_epr or something.
[12:02:01] Gulyx: ...
[12:02:07] ? sorry i am lost
[12:03:48] ? what i am saying is that a developer of a web service client ca\
n explicitely define a url, or may use your disco in order to look for the m\
ost appropriate one
[12:04:07] sampo.kellomaki: I am saying that EPR, being common documented co\
ncept, should not be SWIGTYPE_p_zx_a_EndpointReference_s, but should be name\
d zxid_epr.
[12:04:30] Gulyx: ok
[12:04:51] sampo.kellomaki: Explicitly defining URL is inadequate unless you\
also define the security token to access the service.
January 29, 2011
CHAPTER 37. FAQ
6717
6718
6719
6720
6721
6722
6723
6724
6725
6726
6727
6728
6729
6730
6731
6732
6733
6734
6735
6736
6737
6738
6739
6740
6741
6742
6743
6744
6745
6746
6747
6748
6749
6750
6751
6752
6753
6754
6755
6756
6757
6758
6759
6760
6761
6762
6763
6764
6765
[12:05:28] ? Generally creating security token without consulting discovery \
(or ID Mapper service in more general context) is not feasible.
[12:05:45] ? THerefore having a simple constructor for EPR accomplishes very\
little.
[12:06:36] Gulyx: mmm
[12:07:15] ? what i am saying is that is due to the developer of a web servi\
ce client choose
[12:07:17] sampo.kellomaki: If you know the URL (and the service has been re\
gistered to discovery), then you can get the EPR with zxidjni.get_epr(cf, se\
s, svc_type, URL, null, null, 1).
[12:07:29] Gulyx: an explicit url or look for one from a disco
[12:07:58] ? thus this part of the zxidapi should be used (in case) at the a\
pplication layer
[12:08:05] sampo.kellomaki: Rather than look for URL from disco, why not jus\
t get the EPR from disco, i.e. call get_epr()?
[12:08:08] Gulyx: and not in the zxid security module
[12:09:01] sampo.kellomaki: What would you do with the EPR created by the co\
nstructor?
[12:09:30] Gulyx: well it is ok to use "zxidjni.get_epr(cf, ses, svc_t\
ype, URL, null, null, 1)."
[12:09:59] ? however is not always given that "svc_type" is known/\
available
[12:10:13] ? what happen if it is not provided?
[12:10:21] ? that it may be possible
[12:10:45] ? i understand that is important from a discovery point of view
[12:11:23] ? but the coould be the case in which the developer of a web serv\
ice client do not want to use it or does not know it
[12:11:39] ? he would only contat that URL
[12:11:54] sampo.kellomaki: If you do not know service type, how do you know\
what kind of SOAP body you are supposed to send to the service?
[12:12:47] ? Developer of the web service ultimately is the authority that d\
ecides what the service type URI. If he does not know it, he can just invent\
it.
[12:13:03] Gulyx: for example because i am executing a RPC and i got all the\
information from the wsdl
[12:13:29] ? in this case i simply need a URL
[12:14:00] ? isn't it ?
[12:14:17] sampo.kellomaki: As a general rule, if web service developer has \
poor imagination in inventing a service type URI, I recommend using the name\
space URI of the top level element in the SOAP body.
[12:14:45] Gulyx: sampo i am not saying that what you are proposing is wrong
[12:15:03] ? i am just sayin that in some cases people does not use the serv\
ice type
[12:15:03] sampo.kellomaki: To speak RPC, you do need to know how to format \
the SOAP body according to the RPC marshalling conventions.
[12:15:22] ? CLearly you need to know what the body looks like, therefore yo\
u should know its namespace.
[12:15:33] Gulyx: and the zxid module in axis shuould support both
[12:15:59] sampo.kellomaki: If people do not use service type, then they can\
January 29, 2011
6766
6767
6768
6769
6770
6771
6772
6773
6774
6775
6776
6777
6778
6779
6780
6781
6782
6783
6784
6785
6786
6787
6788
6789
6790
6791
6792
6793
6794
6795
6796
6797
6798
6799
6800
6801
6802
6803
6804
6805
6806
6807
6808
6809
6810
6811
6812
6813
6814
CHAPTER 37. FAQ
not get registered in discovery.
[12:16:14] Gulyx: so the case in which the developer (at the application lev\
el) specified the service type and the case when he does not
[12:16:22] sampo.kellomaki: If they are not registered in discovery, how do \
you propose to generate the token for accessing the web service?
[12:16:59] Gulyx: "[15.18.49] sampo.kellomaki: If people do not use ser\
vice type, then they can not get registered in discovery." ????
[12:17:20] ? should a client be registered to a disco?
[12:17:27] sampo.kellomaki: That’s right. Registering without service type i\
s not possible.
[12:17:38] Gulyx: no sorry
[12:17:59] ? probably i was
[12:18:06] ? saying something in the wrong manner
[12:18:16] ? let's start again
[12:18:27] ? service MUST have a service type
[12:18:39] ? service MUST register to a disco with a service type
[12:19:12] ? clients SHOULD know the service type and MAY use it in order to\
look for a service
[12:19:33] ? client MAY contact directly a service without knowing a service\
type
[12:19:49] ? client MAY not be registered to the disco
[12:19:55] ? ok?
[12:22:11] sampo.kellomaki: Client is need not be registered in Disco.
[12:22:22] Gulyx: ok
[12:22:25] ? perfect
[12:22:37] sampo.kellomaki: However, I claim that client can not contact the\
service without knowing what the SOAP body looks like.
[12:23:08] Gulyx: of course
[12:23:40] ? but they can also do it from the wsdl
[12:23:59] ? ?
[12:24:01] ? as i said above
[12:24:45] sampo.kellomaki: Yes, knowing WSDL constitutes knowing what the S\
OAP body is.
[12:25:02] Gulyx: ok
[12:25:08] sampo.kellomaki: If you know WSDL, you know what the namespace UR\
I of the top level element of the SOAP body is.
[12:25:25] ? Now if you follow the convention that the namespace is the serv\
ice-type, then you are done.
[12:25:37] Gulyx: so a client may not know the service type
[12:25:56] sampo.kellomaki: If the service developer chose a service type d\
ifferent from the namespace, then you have to find out from the documentatio\
n the service developer provided.
[12:25:59] Gulyx: (i am not saying that is the most appropriate or the only \
way to do it)
[12:26:07] ? yes
[12:26:11] ? of course
[12:26:33] ? i am only proposing to include into the zxid axis2 module
[12:26:38] ? both the possibility
[12:26:43] ? possibilities
January 29, 2011
CHAPTER 37. FAQ
6815
6816
6817
6818
6819
6820
6821
6822
6823
6824
6825
6826
6827
6828
6829
6830
6831
6832
6833
6834
6835
6836
6837
6838
6839
6840
6841
6842
6843
6844
6845
6846
6847
6848
6849
6850
6851
6852
6853
6854
6855
6856
6857
6858
6859
6860
[12:26:49] ? with and without service type
[12:27:30] ? (sorry i got a call back to you soon)
[12:32:59] sampo.kellomaki: If you want to support the without service type \
case, then you should program in the axis2 module automatic derivation of th\
e service type using the rule that the namespace of the top level element is\
the service type.
[12:37:41] Gulyx: (back)
[12:39:38] ? well if is it possible to forge from the service url an "a\
ppropriate" epr that i can pass to the zxidjni.wsc_prepare_call
[12:39:56] ? i would prefere
[12:40:15] ? what do you think?
[12:40:24] sampo.kellomaki: If you "forge" wrong, then things will not work.
[12:41:04] Gulyx: if the automatic derivation is wrong , then things will n\
ot work too :-D
[12:41:07] sampo.kellomaki: Having a default rule like using top level names\
pace as service type will work if that indeed was the convention everybody u\
ses.
[12:41:25] ? But there is no universal agreement that this is always the con\
vention.
[12:41:36] Gulyx: exactely
[12:41:38] sampo.kellomaki: In practise in Liberty it has been the conventio\
n, but there is no guarantee.
[12:42:38] Gulyx: so having something like "zxidjni.get_defaultEpr(URL)\
"
[12:42:43] sampo.kellomaki: Why are you so hell bent in not wanting to know \
the service type?
[12:42:47] Gulyx: would be useful
[12:42:53] sampo.kellomaki: What service type do you not know?
[12:43:00] Gulyx: i want service type
[12:43:20] ? and i am almost supporting it into the module
[12:43:49] ? i am just saying that people that i hope would use the module
[12:44:15] ? may not use service type
[12:44:40] sampo.kellomaki: If the people want to play in TAS3, they need to\
know the service type. Knowing it is a requirement to join TAS3.
[12:44:43] Gulyx: so i would that the module supports both the cases
[12:44:51] ? yes yes
[12:44:55] ? ok
[12:45:04] ? i was referring people out of tas3
[12:45:14] ? i mean if we realese the zxid module for apache
[12:45:27] ? i assume that axis2 users may
[12:45:34] ? prefer zxid module instead of rampart
[12:45:51] ? so i would include this feature into the module too
[12:47:31] sampo.kellomaki: Ok, if you do not want to make TAS3 web service \
calls and do not want to use identities or security tokens, then plain EPR w\
ith just URL would be good enough.
[12:47:57] Gulyx: right
January 29, 2011
37.15. BEST PRACTISES
6861
6862
6863
6864
6865
6866
6867
6868
6869
6870
6871
37.15
CHAPTER 37. FAQ
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.
6873
4. Providing metadata by URL, ideally by the Entity ID, SHOULD always be enabled.
This greatly facilitates configuration.
6874
5. <KeyDescriptor> elements should have use XML attribute
6872
6875
6876
6877
6878
6879
6880
6881
6882
6883
6884
6885
6886
6887
6888
6889
6890
6891
6892
6893
6894
6895
6896
6897
6898
6899
6900
6901
6. After you get an installation to work, be sure to review whether the default configuration is appropriate for production use
a. Decide whether you want to run open federation, see MD_FETCH config option
(default: 1=open federation)
b. Prune your Circle of Trust. Use zxcot(8) tool to list who you trust and delete the
misfits.
c. Check validity time tolerances you accept: BEFORE_SLOP and AFTER_SLOP.
The defaults are rather generous for production use.
d. Review that you did not turn off any signature validation just to get it to work
(SIG_FATAL=0, NOSIG_FATAL=0 and similar config options). All signature
validations are there for reason and you should not go to production if any of
them fail.
e. Check permissions on /var/zxid/pem and think whether your private keys, including web server SSL one, are protected. Could they have been compromised
during trial period?
f. Check that your public image is conveyed right in your metadata, e.g. NICE_NAME,
ORG_NAME, ORG_URL, and FEDUSERNAME_SUFFIX (if used, generally
only on IdP). However, be forewarned that changing these on last minute changes
your metadata and you may need to engage in an additional round of metadata
exchanges when you go to production.
g. Make sure you have a solution in place to keep your audit trail in case you ever
have to go to court. See zxid-log.pd for details. You may also want to think
about encrypting or deleting some items after a while to reduce your liability for
breaches.
37.16
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 in next sections...
January 29, 2011
CHAPTER 37. FAQ
6902
6903
6904
6905
37.16.1
37.17. ATTRIBUTES
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
6906
rpm2cpio digitalme-0.4.1238-2.1.i586.rpm | cpio -di
6907
37.16.2
6908
For one InfoCard aware IdP, please see: http://www.cdatazone.org/index.php?/archives/27-Managed-Infocard-De
6909
1. Register at the IdP site (e.g. https://www.ctindustries.net/icard/index.php)
Setting up IdP account
6911
2. Download the card ("Retrieve Managed Card" link (savea as "cdatamanaged.crd"
by default).
6912
3. Install the card to DigitalMe
6913
37.16.3
6910
6914
6915
6916
6917
6918
6919
6920
6921
6922
6923
Yubikey Support
ZXID supports the yubikey USB One Time Password (OTP) tokens from yubico.com.
The token should be personalized such that the prefix of the ticket is the UID and
the remainder is the ticket proper. The AES128 shared secret in hex is populated in
UID/.yk directory. See also zxid-log.pd for description.
You would typically plan the user names, taking in account the yubikey modhex restrictions, and then use ykpersonalize to create thephysical tokens. At the same time
you would generate and record the AES128 shared secrets to the .yk files (and inside
the yubikey USB tokens themselves, of course).
The contents of the .yk file is 32 hexadecimal digits (ascii 0-9a-f) representing 128 bits
of key information.
6925
The value is not hashed, salted, or nonced, so it needs to be carefully protected by the
filesystem permissions.
6926
37.16.4
6927
Microsoft promises to not sue you: http://www.microsoft.com/interop/osp/default.mspx
6928
37.17
6929
Q I want to read the attributes that come in the assertion. how do I do that?
6924
Legal
Attributes
January 29, 2011
37.18. SOAP BINDING
6930
6931
6932
6933
6934
6935
6936
6937
6938
6939
6940
6941
6942
6943
6944
6945
6946
6947
6948
6949
6950
6951
6952
6953
6954
6955
6956
CHAPTER 37. FAQ
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.
6957
37.18
SOAP Binding
6958
37.18.1
Axis2 wants wsa:Action header
6959
6960
6961
6962
6963
6964
6965
The recommended course of action is to change Axis2 config such that it does not
require wsa:Action header. All the necessary information for dispatch of the SOAP
message is already available on the top child element of SOAP Body element.
HTTP Action header and the wsa:Action SOAP header are historical design errors as
they effectively duplicate information from the top child of the Body. Exactly how
this duplication is to be done is poorly specified and great source of interoperability
problems.
January 29, 2011
CHAPTER 37. FAQ
6966
6967
6968
6969
6970
37.18. SOAP BINDING
Please point me to a specification document (with line number or section reference)
where wsa:Action is specified as mandatory. Remember that Axis2 is just an implementation and just because Axis2 happens to want it, does not make it required by any
standard. If you can show it to be mandatory, then point me to document that specifies
what the proper value would be.
6974
Historically many web service specs have been silent on the value of wsa:Action as
they were designed not to use wsa:Action. When people the try to use wsa:Action,
they end up inventing the value themselves and, voila, you have an interoperability
mess.
6975
If you really want to have a wsa:Action header, you can generate one yourself:
6971
6972
6973
6976
6977
zxid_call(...,"<e:Envelope><e:Header><a:Action>...</a:Action></e:Header><e:Body>...</e:Body></e:Envelope>
...)
6980
In other words, the zxid_call() family of functions will accept full SOAP envelope if
you give it one. It will then add the TAS3 specific headers to it, but it will preserve the
headers you supplied as long as there is no conflict.
6981
Cheers, –Sampo
6978
6979
January 29, 2011
37.18. SOAP BINDING
January 29, 2011
CHAPTER 37. FAQ
6982
6983
6984
Chapter 38
Support
38.1
Mailing list and forums
6985
• Official ZXID mailing list is [email protected]
6986
• The archives can be seen at http://listproc.unh.edu/archives/zxid.user
6987
38.2
6988
Mail the author until we get bug tracking set up. Or volunteer.
6989
38.3
6990
6991
6992
6993
6994
Bugs
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.
6997
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.
6998
38.4
6999
Following companies provide consultancy and support contracts for ZXID:
6995
6996
Commercial Support
7000
• symlabs.com
7001
• Mercnet, Lda.
7002
• Levelview, Lda.
245
38.4. COMMERCIAL SUPPORT
January 29, 2011
CHAPTER 38. SUPPORT
7003
7004
7005
7006
7007
7008
7009
7010
7011
7012
7013
7014
7015
7016
7017
7018
7019
7020
7021
7022
7023
7024
Chapter 39
License
Copyright (c) 2010-2011 Sampo Kellomäki ([email protected]), All Rights Reserved.
Copyright (c) 2006-2009 Symlabs ([email protected]), All Rights Reserved.
Author: Sampo Kellomäki ([email protected])
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 ([email protected]). Binary distribution of this product includes software
written by Tim Hudson ([email protected]). See LICENSE.ssleay for further information.
7027
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.
7028
39.1
7025
7026
7029
7030
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
247
39.2. SPECIFICATION IPR
7031
• OpenSSL under BSDish (with "advertising" clause)
7032
• libcurl under BSDish
7033
• zlib under BSDish
7034
• libc available as part of the operating system
CHAPTER 39. LICENSE
7035
Please see each library package for the exact details of their licenses.
7036
39.2
7037
7038
7039
7040
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.
7043
Some protocols, such as WS-Trust and WS-Federation enjoy Microsoft’s pledge1 that
they will not sue you even if you implement these specifications. You should evaluate
yourself whether this is good enough for your situation.
7044
39.3
7041
7042
7045
7046
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 [email protected]
7048
Legal queries and clarifications will be answered at then-current Symlabs Professional
Services rate, please contact [email protected].
7049
39.4
7047
7050
7051
Per decisions of TAS3 General Assembly of 2010-09-13 (TAS3_General_Assembly_minutes_2010_09_13_Le
following declaration was made:
TAS3 architecture and specifications, as described in public deliverables
D2.1, D2.4, and D7.1, are licensed free for implementation and use by
anyone. Up to June 2010, TAS3 consortium partners do not hold patents
nor will exercise patents that cover implementation and use of the TAS3
architecture and specifications of those deliverables. This license is only
granted for the specific purpose of correct implementations of TAS3 specifications.
7052
7053
7054
7055
7056
7057
7058
7059
7060
7061
7062
TAS3 Free to Implement and Use Pledge
For further openness, it should be noted that ZXID, which is distributed under Apache2
open source license, is the Reference Implementation of the TAS3 Core Security Architecture, i.e. from software licensing perspective TAS3 is available in open source.
Many other components of TAS3 are available in open source as well.
1 If
you have a reference to where this pledge can be found, please let me know so it can be included here.
January 29, 2011
7063
7064
Chapter 40
Protocol Schema and Examples
249
CHAPTER 40. PROTOCOL SCHEMA AND EXAMPLES
January 29, 2011
7065
7066
Chapter 41
Appendix: Schema Grammars
7069
Large parts of ZXID code are generated from schema grammars which are a convenient
notation for describing XML schmata. This appendix contains the schema grammars
that are currently implemented and distributed in the ZXID package.
7070
41.1
SAML 2.0
7071
41.1.1
saml-schema-assertion-2.0 (sa)
7067
7068
7072
7073
7074
7075
7076
7077
7078
7079
7080
7081
7082
7083
# zxid/sg/saml-schema-assertion-2.0.sg
# $Id: saml-schema-assertion-2.0.sg,v 1.10 2009-11-14 22:44:43 sampo Exp $
#
# N.B. This file is not a direct conversion. Instead it has been manually ed\
ited to
# make it simpler and to facilitate code generation.
# 15.10.2006, extended AttributeValue schema to cater for bootstrap, Sampo K\
ellomaki ([email protected])
# 10.2.2007, added other types of assertions as potential Advice content --S\
ampo
# 3.3.2007, added XACML support --Sampo
# 24.8.2009, modified sa:Statement to be able to carry xac:Response --Sampo
7084
7085
7086
7087
7088
7089
7090
7091
7092
7093
7094
7095
7096
7097
target(sa, urn:oasis:names:tc:SAML:2.0:assertion)
ns(xs,http://www.w3.org/2001/XMLSchema)
import(ds,http://www.w3.org/2000/09/xmldsig#,http://www.w3.org/TR/2002/REC-x\
mldsig-core-20020212/xmldsig-core-schema.xsd)
import(xenc,http://www.w3.org/2001/04/xmlenc#,http://www.w3.org/TR/2002/REC-\
xmlenc-core-20021210/xenc-schema.xsd)
ns(di12, urn:liberty:disco:2003-08)
ns(a,
http://www.w3.org/2005/08/addressing)
ns(sa11, urn:oasis:names:tc:SAML:1.0:assertion)
ns(ff12, urn:liberty:iff:2003-08)
ns(xasa, urn:oasis:xacml:2.0:saml:assertion:schema:os)
ns(xasacd1, urn:oasis:names:tc:xacml:2.0:profile:saml2.0:v2:schema:assertion\
:cd-01)
251
41.1. SAML 2.0
7098
7099
7100
ns(xac,
ns(xsi,
ns(idp,
CHAPTER 41. APPENDIX: SCHEMA GRAMMARS
urn:oasis:names:tc:xacml:2.0:context:schema:os)
http://www.w3.org/2001/XMLSchema-instance)
urn:liberty:idp:2006-12)
7101
7102
7103
7104
7105
&@IDNameQualifiers:
@NameQualifier?
-> %xs:string
@SPNameQualifier? -> %xs:string
;
7106
7107
7108
7109
7110
BaseID -> %sa:BaseIDAbstractType
%BaseIDAbstractType:
&@sa:IDNameQualifiers
;
7111
7112
7113
7114
7115
7116
7117
NameID -> %sa:NameIDType
%NameIDType: base(xs:string)
@Format? -> %xs:anyURI
&@sa:IDNameQualifiers
@SPProvidedID? -> %xs:string
;
7118
7119
7120
7121
7122
%EncryptedElementType:
xenc:EncryptedData
xenc:EncryptedKey*
;
7123
7124
7125
7126
7127
EncryptedID
Issuer
AssertionIDRef
AssertionURIRef
->
->
->
->
%sa:EncryptedElementType
%sa:NameIDType
%xs:NCName
%xs:anyURI
7128
7129
7130
7131
7132
7133
7134
7135
7136
7137
7138
7139
7140
7141
7142
7143
7144
7145
7146
7147
Assertion
-> %sa:AssertionType
%AssertionType:
sa:Issuer
ds:Signature?
sa:Subject?
sa:Conditions?
sa:Advice?
sa:Statement*
# *** how to express * for choice
sa:AuthnStatement*
sa:AuthzDecisionStatement*
sa:AttributeStatement*
xasa:XACMLAuthzDecisionStatement*
xasa:XACMLPolicyStatement*
xasacd1:XACMLAuthzDecisionStatement*
xasacd1:XACMLPolicyStatement*
@ID
-> %xs:ID
@IssueInstant -> %xs:dateTime
@Version
-> %xs:string
;
7148
7149
7150
7151
Subject -> %sa:SubjectType
%SubjectType:
sa:BaseID?
January 29, 2011
# Only one of the IDs should occur
7152
7153
7154
7155
7156
41.1. SAML 2.0
sa:NameID?
sa:EncryptedID?
sa:SubjectConfirmation*
# SAML spec is more lax than the schema: sa\
ml-core-2.0-os.pdf ll.653-657 says <SubjectConfirmation> [Zero or More]
;
7157
7158
7159
7160
7161
7162
7163
7164
7165
SubjectConfirmation -> %sa:SubjectConfirmationType
%SubjectConfirmationType:
sa:BaseID?
# Only one of the IDs should occur
sa:NameID?
sa:EncryptedID?
sa:SubjectConfirmationData?
@Method -> %xs:anyURI
;
7166
7167
7168
7169
7170
7171
7172
7173
7174
7175
7176
7177
SubjectConfirmationData -> %sa:SubjectConfirmationDataType
%SubjectConfirmationDataType: base(anyType)
ds:KeyInfo+
@Address? -> %xs:string
@InResponseTo? -> %xs:NCName
@NotBefore? -> %xs:dateTime
@NotOnOrAfter? -> %xs:dateTime
@Recipient? -> %xs:anyURI
@xsi:type?
@any
;
7178
7179
7180
7181
%KeyInfoConfirmationDataType:
ds:KeyInfo+
;
base(sa:SubjectConfirmationDataType)
7182
7183
7184
7185
7186
7187
7188
7189
7190
7191
7192
Conditions -> %sa:ConditionsType
%ConditionsType:
sa:Condition*
# *** Stated differently in XSD
sa:AudienceRestriction*
sa:OneTimeUse*
sa:ProxyRestriction*
idp:SubjectRestriction*
@NotBefore? -> %xs:dateTime
;
7193
7194
Condition
-> %sa:ConditionAbstractType
7195
7196
7197
7198
7199
AudienceRestriction -> %sa:AudienceRestrictionType
%AudienceRestrictionType: base(sa:ConditionAbstractType)
sa:Audience+
;
7200
7201
Audience
-> %xs:anyURI
7202
7203
7204
OneTimeUse -> %sa:OneTimeUseType
%OneTimeUseType: base(sa:ConditionAbstractType) ;
7205
January 29, 2011
41.1. SAML 2.0
7206
7207
7208
7209
7210
ProxyRestriction -> %sa:ProxyRestrictionType
%ProxyRestrictionType: base(sa:ConditionAbstractType)
sa:Audience*
@Count? -> %xs:nonNegativeInteger
;
7211
7212
7213
7214
7215
7216
7217
7218
7219
7220
7221
Advice -> %sa:AdviceType
%AdviceType:
sa:AssertionIDRef*
# *** really a choice, but maxOccurs="unbounded"
sa:AssertionURIRef*
sa:Assertion*
sa:EncryptedAssertion*
sa11:Assertion*
ff12:Assertion*
any* ns(##other) processContents(lax)
;
7222
7223
EncryptedAssertion -> %sa:EncryptedElementType
7224
7225
#Statement
-> %sa:StatementAbstractType
7226
7227
Statement
-> %sa:StatementType
7228
7229
7230
7231
7232
7233
7234
%StatementType:
base(sa:StatementAbstractType)
xac:Response*
xac:Request*
@xsi:type? -> %xs:string
;
7235
7236
7237
7238
7239
7240
7241
7242
7243
AuthnStatement -> %sa:AuthnStatementType
%AuthnStatementType: base(sa:StatementAbstractType)
sa:SubjectLocality?
sa:AuthnContext
@AuthnInstant
-> %xs:dateTime
@SessionIndex? -> %xs:string
@SessionNotOnOrAfter? -> %xs:dateTime
;
7244
7245
7246
7247
7248
7249
SubjectLocality -> %sa:SubjectLocalityType
%SubjectLocalityType:
@Address? -> %xs:string
@DNSName? -> %xs:string
;
7250
7251
7252
7253
7254
7255
7256
7257
AuthnContext -> %sa:AuthnContextType
%AuthnContextType:
sa:AuthnContextClassRef?
# N.B. We diverge from canonical XSD
sa:AuthnContextDecl?
sa:AuthnContextDeclRef?
sa:AuthenticatingAuthority*
;
7258
7259
AuthnContextClassRef
January 29, 2011
-> %xs:anyURI
7260
7261
7262
41.1. SAML 2.0
AuthnContextDeclRef -> %xs:anyURI
AuthnContextDecl -> %xs:anyType
AuthenticatingAuthority -> %xs:anyURI
7263
7264
7265
7266
7267
7268
7269
7270
AuthzDecisionStatement -> %sa:AuthzDecisionStatementType
%AuthzDecisionStatementType: base(sa:StatementAbstractType)
sa:Action+
sa:Evidence?
@Decision -> %sa:DecisionType
@Resource -> %xs:anyURI
;
7271
7272
%DecisionType:
enum( Permit Deny Indeterminate ) ;
7273
7274
7275
7276
7277
Action -> %sa:ActionType
%ActionType: base(string)
@Namespace -> %xs:anyURI
;
7278
7279
7280
7281
7282
7283
7284
7285
Evidence -> %sa:EvidenceType
%EvidenceType:
sa:AssertionIDRef*
# XSD has choice maxOccurs="unbounded"
sa:AssertionURIRef*
sa:Assertion*
;
7286
7287
7288
7289
7290
7291
AttributeStatement -> %sa:AttributeStatementType
%AttributeStatementType: base(sa:StatementAbstractType)
sa:Attribute*
# XSD has choice maxOccurs="unbounded"
sa:EncryptedAttribute*
;
7292
7293
7294
7295
7296
7297
7298
7299
7300
Attribute -> %sa:AttributeType
%AttributeType:
sa:AttributeValue*
@FriendlyName? -> %xs:string
@Name
-> %xs:string
@NameFormat? -> %xs:anyURI
@any
;
7301
7302
7303
# To cater for discovery bootstraps we add them to schema here
#AttributeValue
-> %xs:anyType
7304
7305
7306
7307
7308
7309
7310
7311
7312
7313
AttributeValue -> %sa:AttributeValueType
%AttributeValueType:
di12:ResourceOffering*
a:EndpointReference*
sa:Assertion*
@xsi:type?
# often any attribute extension point is used for \
this
;
January 29, 2011
41.1. SAML 2.0
7314
7315
EncryptedAttribute -> %sa:EncryptedElementType
7316
7317
7318
7319
TestElem:
sa:AttributeValue*
;
7320
7321
#EOF
7322
7323
7324
7325
7326
7327
7328
41.1.2
#
#
#
#
#
saml-schema-protocol-2.0 (sp)
zxid/sg/saml-schema-protocol-2.0.sg
$Id: saml-schema-protocol-2.0.sg,v 1.5 2008-02-23 03:59:31 sampo Exp $
N.B. This file is not a direct conversion. Instead it has been manually
edited to make it simpler and to facilitate code generation.
7329
7330
7331
7332
7333
7334
7335
target(sp,urn:oasis:names:tc:SAML:2.0:protocol)
import(sa,urn:oasis:names:tc:SAML:2.0:assertion,saml-schema-assertion-2.0.xs\
d)
ns(xs, http://www.w3.org/2001/XMLSchema)
7336
7337
7338
7339
7340
7341
7342
7343
7344
7345
7346
%RequestAbstractType:
sa:Issuer?
ds:Signature?
sp:Extensions?
@ID -> %xs:ID
@Version -> %xs:string
@Destination? -> %xs:anyURI
@Consent? -> %xs:anyURI
;
7347
7348
7349
7350
7351
Extensions -> %sp:ExtensionsType
%ExtensionsType:
any+
;
7352
7353
7354
7355
7356
7357
7358
7359
7360
7361
7362
7363
7364
%StatusResponseType:
sa:Issuer?
ds:Signature?
sp:Extensions?
sp:Status
@ID -> %xs:ID
@Version -> %xs:string
@Destination? -> %xs:anyURI
@Consent? -> %xs:anyURI
;
January 29, 2011
41.1. SAML 2.0
7365
7366
7367
7368
7369
7370
7371
Status -> %sp:StatusType
%StatusType:
sp:StatusCode
sp:StatusMessage?
sp:StatusDetail?
;
7372
7373
7374
7375
7376
7377
StatusCode -> %sp:StatusCodeType
%StatusCodeType:
sp:StatusCode?
@Value -> %xs:anyURI
;
7378
7379
StatusMessage
-> %xs:string
7380
7381
7382
7383
7384
StatusDetail -> %sp:StatusDetailType
%StatusDetailType:
any*
;
7385
7386
7387
7388
7389
AssertionIDRequest -> %sp:AssertionIDRequestType
%AssertionIDRequestType: base(sp:RequestAbstractType)
sa:AssertionIDRef+
;
7390
7391
7392
7393
7394
SubjectQuery -> %sp:SubjectQueryAbstractType
%SubjectQueryAbstractType: base(sp:RequestAbstractType)
sa:Subject
;
7395
7396
7397
7398
7399
7400
AuthnQuery -> %sp:AuthnQueryType
%AuthnQueryType: base(sp:SubjectQueryAbstractType)
sp:RequestedAuthnContext?
@SessionIndex? -> %xs:string
;
7401
7402
7403
7404
7405
7406
7407
RequestedAuthnContext -> %sp:RequestedAuthnContextType
%RequestedAuthnContextType:
sa:AuthnContextClassRef*
sa:AuthnContextDeclRef*
@Comparison? -> %sp:AuthnContextComparisonType
;
7408
7409
%AuthnContextComparisonType:
enum( exact minimum maximum better ) ;
7410
7411
7412
7413
7414
AttributeQuery -> %sp:AttributeQueryType
%AttributeQueryType: base(sp:SubjectQueryAbstractType)
sa:Attribute*
;
7415
7416
7417
7418
AuthzDecisionQuery -> %sp:AuthzDecisionQueryType
%AuthzDecisionQueryType: base(sp:SubjectQueryAbstractType)
sa:Action+
January 29, 2011
41.1. SAML 2.0
7419
7420
7421
sa:Evidence?
;
7422
7423
7424
7425
7426
7427
7428
7429
7430
7431
7432
7433
7434
7435
7436
7437
AuthnRequest -> %sp:AuthnRequestType
%AuthnRequestType: base(sp:RequestAbstractType)
sa:Subject?
sp:NameIDPolicy?
sa:Conditions?
sp:Scoping?
@ForceAuthn? -> %xs:boolean
@IsPassive? -> %xs:boolean
@ProtocolBinding? -> %xs:anyURI
@AssertionConsumerServiceIndex? -> %xs:unsignedShort
@AssertionConsumerServiceURL? -> %xs:anyURI
@AttributeConsumingServiceIndex? -> %xs:unsignedShort
@ProviderName? -> %xs:string
;
7438
7439
7440
7441
7442
7443
7444
NameIDPolicy -> %sp:NameIDPolicyType
%NameIDPolicyType:
@SPNameQualifier? -> %xs:string
@AllowCreate? -> %xs:boolean
;
7445
7446
7447
7448
7449
7450
7451
Scoping -> %sp:ScopingType
%ScopingType:
sp:IDPList?
sp:RequesterID*
@ProxyCount? -> %xs:nonNegativeInteger
;
7452
7453
RequesterID
-> %xs:anyURI
7454
7455
7456
7457
7458
7459
IDPList -> %sp:IDPListType
%IDPListType:
sp:IDPEntry+
sp:GetComplete?
;
7460
7461
7462
7463
7464
7465
7466
IDPEntry -> %sp:IDPEntryType
%IDPEntryType:
@ProviderID -> %xs:anyURI
@Name? -> %xs:string
@Loc? -> %xs:anyURI
;
7467
7468
GetComplete
-> %xs:anyURI
7469
7470
7471
7472
Response -> %sp:ResponseType
%ResponseType: base(sp:StatusResponseType)
sa:Assertion?
January 29, 2011
7473
7474
41.1. SAML 2.0
sa:EncryptedAssertion?
;
7475
7476
7477
7478
7479
ArtifactResolve -> %sp:ArtifactResolveType
%ArtifactResolveType: base(sp:RequestAbstractType)
sp:Artifact
;
7480
7481
Artifact
-> %xs:string
7482
7483
7484
7485
7486
7487
ArtifactResponse -> %sp:ArtifactResponseType
%ArtifactResponseType: base(sp:StatusResponseType)
sp:Response?
any?
;
7488
7489
7490
7491
7492
7493
7494
7495
7496
ManageNameIDRequest -> %sp:ManageNameIDRequestType
%ManageNameIDRequestType: base(sp:RequestAbstractType)
sa:NameID?
sa:EncryptedID?
sp:NewID?
sp:NewEncryptedID?
sp:Terminate?
;
7497
7498
NewID
-> %xs:string
7499
7500
NewEncryptedID
-> %sa:EncryptedElementType
7501
7502
Terminate
-> %sp:TerminateType
7503
7504
ManageNameIDResponse
-> %sp:StatusResponseType
7505
7506
7507
7508
7509
7510
7511
7512
7513
7514
LogoutRequest -> %sp:LogoutRequestType
%LogoutRequestType: base(sp:RequestAbstractType)
sa:BaseID?
sa:NameID?
sa:EncryptedID?
sp:SessionIndex*
@Reason? -> %xs:string
;
7515
7516
SessionIndex
-> %xs:string
7517
7518
LogoutResponse
-> %sp:StatusResponseType
7519
7520
7521
7522
7523
7524
7525
7526
NameIDMappingRequest -> %sp:NameIDMappingRequestType
%NameIDMappingRequestType: base(sp:RequestAbstractType)
sa:BaseID?
sa:NameID?
sa:EncryptedID?
sp:NameIDPolicy
;
January 29, 2011
41.1. SAML 2.0
7527
7528
7529
7530
7531
7532
NameIDMappingResponse -> %sp:NameIDMappingResponseType
%NameIDMappingResponseType: base(sp:StatusResponseType)
sa:NameID?
sa:EncryptedID?
;
7533
7534
#EOF
7535
7536
7537
7538
7539
7540
41.1.3
#
#
#
#
saml-schema-metadata-2.0 (md)
zxid/sg/saml-schema-metadata-2.0.sh .sg
Slightly edited, 27.5.2006, Sampo Kellomaki ([email protected])
22.11.2009, added shib metadata support --Sampo
$Id: saml-schema-metadata-2.0.sg,v 1.4 2009-11-24 23:53:40 sampo Exp $
7541
7542
7543
7544
7545
7546
7547
7548
7549
7550
7551
7552
7553
7554
target(md,urn:oasis:names:tc:SAML:2.0:metadata)
import(xenc,http://www.w3.org/2001/04/xmlenc#,http://www.w3.org/TR/2002/REC-\
xmlenc-core-20021210/xenc-schema.xsd)
import(sa,urn:oasis:names:tc:SAML:2.0:assertion,saml-schema-assertion-2.0.xs\
d)
ns(idpdisc,urn:oasis:names:tc:SAML:profiles:SSO:idp-discovery-protocol)
# import(xml,http://www.w3.org/XML/1998/namespace,http://www.w3.org/2001/xml\
.xsd)
ns(xml, http://www.w3.org/XML/1998/namespace)
ns(shibmd, urn:mace:shibboleth:metadata:1.0)
7555
7556
%entityIDType:
base(xs:anyURI) ;
7557
7558
7559
7560
7561
%localizedNameType: base(xs:string)
@xml:lang? -> %xs:string #@xml:lang vs. @lang
#@lang? -> %xs:string
;
***
7562
7563
7564
7565
7566
%localizedURIType: base(xs:anyURI)
@xml:lang? -> %xs:string #@xml:lang vs. @lang
#@lang? -> %xs:string
;
***
7567
7568
7569
7570
7571
7572
7573
7574
Extensions -> %md:ExtensionsType
%ExtensionsType:
shibmd:Scope*
shibmd:KeyAuthority*
idpdisc:DiscoveryResponse*
any+
;
7575
7576
7577
# What about IndexedEndpointType as needed in idpdisc,urn:oasis:names:tc:SAM\
L:profiles:SSO:idp-discovery-protocol --Sampo
January 29, 2011
41.1. SAML 2.0
7578
7579
7580
7581
7582
7583
7584
7585
7586
7587
%EndpointType:
any*
@Binding -> %xs:anyURI
@Location -> %xs:anyURI
@ResponseLocation? -> %xs:anyURI
@index? -> %xs:unsignedShort
@isDefault? -> %xs:boolean
@any
;
7588
7589
7590
7591
7592
7593
7594
7595
7596
7597
7598
7599
EntitiesDescriptor -> %md:EntitiesDescriptorType
%EntitiesDescriptorType:
ds:Signature?
md:Extensions?
md:EntityDescriptor*
# these were originally choice unbounded
md:EntitiesDescriptor*
@validUntil? -> %dateTime
@cacheDuration? -> %duration
@ID? -> %xs:ID
@Name? -> %xs:string
;
7600
7601
7602
7603
7604
7605
7606
7607
7608
7609
7610
7611
7612
7613
7614
7615
7616
7617
7618
7619
7620
7621
EntityDescriptor -> %md:EntityDescriptorType
%EntityDescriptorType:
ds:Signature?
md:Extensions?
md:RoleDescriptor*
# following were originally choice unbo\
unded
md:IDPSSODescriptor*
md:SPSSODescriptor*
md:AuthnAuthorityDescriptor*
md:AttributeAuthorityDescriptor*
md:PDPDescriptor*
md:AffiliationDescriptor*
md:Organization?
md:ContactPerson*
md:AdditionalMetadataLocation*
@entityID -> %md:entityIDType
@ID? -> %xs:ID
@any
;
7622
7623
7624
7625
7626
7627
7628
7629
7630
Organization -> %md:OrganizationType
%OrganizationType:
md:Extensions?
md:OrganizationName+
md:OrganizationDisplayName+
md:OrganizationURL+
@any
;
7631
January 29, 2011
41.1. SAML 2.0
7632
7633
7634
OrganizationName -> %md:localizedNameType
OrganizationDisplayName -> %md:localizedNameType
OrganizationURL -> %md:localizedURIType
7635
7636
7637
7638
7639
7640
7641
7642
7643
7644
7645
7646
ContactPerson -> %md:ContactType
%ContactType:
md:Extensions?
md:Company?
md:GivenName?
md:SurName?
md:EmailAddress*
md:TelephoneNumber*
@contactType -> %md:ContactTypeType
@any
;
7647
7648
7649
7650
7651
7652
Company -> %xs:string
GivenName -> %xs:string
SurName -> %xs:string
EmailAddress -> %xs:anyURI
TelephoneNumber -> %xs:string
7653
7654
%ContactTypeType:
enum( technical support administrative billing other ) ;
7655
7656
7657
7658
7659
AdditionalMetadataLocation -> %md:AdditionalMetadataLocationType
%AdditionalMetadataLocationType: base(xs:anyURI)
@namespace -> %xs:anyURI
;
7660
7661
7662
7663
7664
7665
7666
7667
7668
7669
7670
7671
7672
7673
7674
RoleDescriptor -> %md:RoleDescriptorType
%RoleDescriptorType:
ds:Signature?
md:Extensions?
md:KeyDescriptor*
md:Organization?
md:ContactPerson*
@ID? -> %xs:ID
@protocolSupportEnumeration -> %xs:anyURI
@errorURL? -> %xs:anyURI
@any
;
7675
7676
7677
7678
7679
7680
7681
KeyDescriptor -> %md:KeyDescriptorType
%KeyDescriptorType:
ds:KeyInfo
md:EncryptionMethod*
@use? -> %md:KeyTypes
;
7682
7683
7684
7685
%KeyTypes: enum( encryption signing ) ;
EncryptionMethod -> %xenc:EncryptionMethodType
%SSODescriptorType: base(md:RoleDescriptorType)
January 29, 2011
7686
7687
7688
7689
7690
41.1. SAML 2.0
md:ArtifactResolutionService*
md:SingleLogoutService*
md:ManageNameIDService*
md:NameIDFormat*
;
7691
7692
7693
7694
7695
ArtifactResolutionService -> %md:EndpointType
SingleLogoutService -> %md:EndpointType
ManageNameIDService -> %md:EndpointType
NameIDFormat -> %xs:anyURI
7696
7697
7698
7699
7700
7701
7702
7703
7704
7705
IDPSSODescriptor -> %md:IDPSSODescriptorType
%IDPSSODescriptorType: base(md:SSODescriptorType)
md:SingleSignOnService+
md:NameIDMappingService*
md:AssertionIDRequestService*
md:AttributeProfile*
sa:Attribute*
@WantAuthnRequestsSigned? -> %xs:boolean
;
7706
7707
7708
7709
7710
SingleSignOnService -> %md:EndpointType
NameIDMappingService -> %md:EndpointType
AssertionIDRequestService -> %md:EndpointType
AttributeProfile -> %xs:anyURI
7711
7712
7713
7714
7715
7716
7717
7718
SPSSODescriptor -> %md:SPSSODescriptorType
%SPSSODescriptorType: base(md:SSODescriptorType)
md:AssertionConsumerService+
md:AttributeConsumingService*
@AuthnRequestsSigned? -> %xs:boolean
@WantAssertionsSigned? -> %xs:boolean
;
7719
7720
AssertionConsumerService
-> %md:EndpointType
7721
7722
7723
7724
7725
7726
7727
7728
7729
AttributeConsumingService -> %md:AttributeConsumingServiceType
%AttributeConsumingServiceType:
md:ServiceName+
md:ServiceDescription*
md:RequestedAttribute+
@index -> %xs:unsignedShort
@isDefault? -> %xs:boolean
;
7730
7731
7732
ServiceName -> %md:localizedNameType
ServiceDescription -> %md:localizedNameType
7733
7734
7735
7736
7737
RequestedAttribute -> %md:RequestedAttributeType
%RequestedAttributeType: base(sa:AttributeType)
@isRequired? -> %xs:boolean
;
7738
7739
AuthnAuthorityDescriptor
January 29, 2011
-> %md:AuthnAuthorityDescriptorType
41.2. SAML 1.1
7740
7741
7742
7743
7744
%AuthnAuthorityDescriptorType: base(md:RoleDescriptorType)
md:AuthnQueryService+
md:NameIDFormat*
;
7745
7746
AuthnQueryService
-> %md:EndpointType
7747
7748
7749
7750
7751
7752
7753
PDPDescriptor -> %md:PDPDescriptorType
%PDPDescriptorType: base(md:RoleDescriptorType)
md:AuthzService+
md:NameIDFormat*
;
7754
7755
AuthzService
-> %md:EndpointType
7756
7757
7758
7759
7760
7761
7762
7763
7764
AttributeAuthorityDescriptor -> %md:AttributeAuthorityDescriptorType
%AttributeAuthorityDescriptorType: base(md:RoleDescriptorType)
md:AttributeService+
md:NameIDFormat*
md:AttributeProfile*
sa:Attribute*
;
7765
7766
AttributeService
-> %md:EndpointType
7767
7768
7769
7770
7771
7772
7773
7774
7775
7776
7777
7778
7779
AffiliationDescriptor -> %md:AffiliationDescriptorType
%AffiliationDescriptorType:
ds:Signature?
md:Extensions?
md:AffiliateMember+
md:KeyDescriptor*
@affiliationOwnerID -> %md:entityIDType
@ID? -> %xs:ID
@any
;
7780
7781
AffiliateMember
-> %md:entityIDType
7782
7783
#EOF
7784
7785
41.2
SAML 1.1
7786
41.2.1
oasis-sstc-saml-schema-assertion-1.1 (sa11)
7787
7788
# zxid/sg/oasis-sstc-saml-schema-assertion-1.1.sg
# Slightly edited, 5.9.2006, Sampo Kellomaki ([email protected])
January 29, 2011
7789
7790
7791
7792
7793
7794
41.2. SAML 1.1
# 15.10.2006, extended AttributeValue schema to cater for bootstraps --Sampo
# 10.2.2007, added other types of assertions as potential Advice content --S\
ampo
# 3.3.2007, added XACML support --Sampo
# $Id: oasis-sstc-saml-schema-assertion-1.1.sg,v 1.6 2009-11-14 22:44:43 sam\
po Exp $
7795
7796
7797
7798
7799
7800
7801
7802
7803
7804
7805
7806
target(sa11, urn:oasis:names:tc:SAML:1.0:assertion)
import(ds, http://www.w3.org/2000/09/xmldsig#, http://www.w3.org/TR/xmldsig-\
core/xmldsig-core-schema.xsd)
ns(a,
ns(sa,
urn:oasis:names:tc:SAML:2.0:assertion)
ns(ff12, urn:liberty:iff:2003-08)
ns(xasa, urn:oasis:xacml:2.0:saml:assertion:schema:os)
ns(xasacd1, urn:oasis:names:tc:xacml:2.0:profile:saml2.0:v2:schema:assertion\
:cd-01)
7807
7808
7809
%DecisionType:
enum( Permit Deny Indeterminate ) ;
AssertionIDReference -> %xs:NCName
7810
7811
7812
7813
7814
7815
7816
7817
7818
7819
7820
7821
7822
7823
7824
7825
7826
7827
7828
7829
7830
Assertion
-> %sa11:AssertionType
%AssertionType:
sa11:Conditions?
sa11:Advice?
sa11:Statement*
sa11:SubjectStatement*
sa11:AuthenticationStatement*
sa11:AuthorizationDecisionStatement*
sa11:AttributeStatement*
xasa:XACMLAuthzDecisionStatement*
xasa:XACMLPolicyStatement*
xasacd1:XACMLAuthzDecisionStatement*
xasacd1:XACMLPolicyStatement*
ds:Signature?
@MajorVersion -> %xs:integer
@MinorVersion -> %xs:integer
@AssertionID
-> %xs:ID
@Issuer
-> %xs:string
;
7831
7832
7833
7834
7835
7836
7837
7838
7839
7840
Conditions
-> %sa11:ConditionsType
%ConditionsType:
sa11:AudienceRestrictionCondition*
sa11:DoNotCacheCondition*
sa11:Condition*
@NotBefore?
-> %xs:dateTime
;
Condition
-> %sa11:ConditionAbstractType
7841
7842
AudienceRestrictionCondition
January 29, 2011
-> %sa11:AudienceRestrictionConditionType
41.2. SAML 1.1
7843
7844
7845
%AudienceRestrictionConditionType: base(sa11:ConditionAbstractType)
sa11:Audience+
;
7846
7847
Audience -> %xs:anyURI
7848
7849
7850
DoNotCacheCondition
-> %sa11:DoNotCacheConditionType
%DoNotCacheConditionType: base(sa11:ConditionAbstractType) ;
7851
7852
7853
7854
7855
7856
7857
7858
7859
Advice -> %sa11:AdviceType
%AdviceType:
sa11:AssertionIDReference*
sa11:Assertion*
ff12:Assertion*
sa:Assertion*
;
7860
7861
Statement -> %sa11:StatementAbstractType
7862
7863
7864
7865
7866
SubjectStatement -> %sa11:SubjectStatementAbstractType
%SubjectStatementAbstractType: base(sa11:StatementAbstractType)
sa11:Subject
;
7867
7868
7869
7870
7871
7872
Subject -> %sa11:SubjectType
%SubjectType:
sa11:NameIdentifier?
sa11:SubjectConfirmation?
;
7873
7874
7875
7876
7877
7878
NameIdentifier -> %sa11:NameIdentifierType
%NameIdentifierType: base(xs:string)
@NameQualifier? -> %xs:string
;
7879
7880
7881
7882
7883
7884
7885
SubjectConfirmation -> %sa11:SubjectConfirmationType
%SubjectConfirmationType:
sa11:ConfirmationMethod+
sa11:SubjectConfirmationData?
ds:KeyInfo?
;
7886
7887
7888
SubjectConfirmationData -> %xs:anyType
ConfirmationMethod -> %xs:anyURI
7889
7890
7891
7892
7893
7894
7895
7896
AuthenticationStatement -> %sa11:AuthenticationStatementType
%AuthenticationStatementType: base(sa11:SubjectStatementAbstractType)
sa11:SubjectLocality?
sa11:AuthorityBinding*
@AuthenticationMethod -> %xs:anyURI
@AuthenticationInstant -> %xs:dateTime
;
January 29, 2011
41.2. SAML 1.1
7897
7898
7899
7900
7901
7902
SubjectLocality -> %sa11:SubjectLocalityType
%SubjectLocalityType:
@IPAddress?
-> %xs:string
@DNSAddress?
-> %xs:string
;
7903
7904
7905
7906
7907
7908
7909
AuthorityBinding -> %sa11:AuthorityBindingType
%AuthorityBindingType:
@AuthorityKind -> %xs:QName
@Location
-> %xs:anyURI
@Binding
-> %xs:anyURI
;
7910
7911
7912
7913
7914
7915
7916
7917
7918
AuthorizationDecisionStatement
-> %sa11:AuthorizationDecisionStatement\
Type
%AuthorizationDecisionStatementType: base(sa11:SubjectStatementAbstractType)
sa11:Action+
sa11:Evidence?
@Resource
-> %xs:anyURI
@Decision
-> %sa11:DecisionType
;
7919
7920
7921
7922
7923
Action
%ActionType:
@Namespace?
;
-> %sa11:ActionType
base(string)
-> %xs:anyURI
7924
7925
7926
7927
7928
7929
Evidence
-> %sa11:EvidenceType
%EvidenceType:
sa11:AssertionIDReference*
sa11:Assertion*
;
7930
7931
7932
7933
7934
AttributeStatement -> %sa11:AttributeStatementType
%AttributeStatementType: base(sa11:SubjectStatementAbstractType)
sa11:Attribute+
;
7935
7936
7937
7938
7939
7940
AttributeDesignator
-> %sa11:AttributeDesignatorType
%AttributeDesignatorType:
@AttributeName
-> %xs:string
@AttributeNamespace -> %xs:anyURI
;
7941
7942
7943
7944
7945
Attribute -> %sa11:AttributeType
%AttributeType: base(sa11:AttributeDesignatorType)
sa11:AttributeValue+
;
7946
7947
7948
# To cater for discovery bootstraps we add them to schema here --Sampo
#AttributeValue
-> %xs:anyType
7949
7950
AttributeValue -> %sa11:AttributeValueType
January 29, 2011
41.2. SAML 1.1
7951
7952
7953
7954
%AttributeValueType:
;
7955
7956
#EOF
7957
7958
7959
7960
7961
7962
41.2.2
#
#
#
o
oasis-sstc-saml-schema-protocol-1.1 (sp11)
zxid/sg/oasis-sstc-saml-schema-protocol-1.1.sg
$Id: oasis-sstc-saml-schema-protocol-1.1.sg,v 1.2 2009-09-05 02:23:41 samp\
Exp $
7963
7964
target(sp11, urn:oasis:names:tc:SAML:1.0:protocol)
7965
7966
7967
7968
7969
import(sa11, urn:oasis:names:tc:SAML:1.0:assertion, oasis-sstc-saml-schema-a\
ssertion-1.1.xsd)
import(ds,
http://www.w3.org/2000/09/xmldsig#, http://www.w3.org/TR/xmldsi\
g-core/xmldsig-core-schema.xsd)
7970
7971
7972
7973
7974
7975
7976
7977
7978
7979
7980
7981
sp11:RespondWith*
ds:Signature?
@RequestID -> %xs:ID
;
RespondWith -> %xs:QName
7982
7983
7984
7985
7986
7987
7988
7989
7990
7991
7992
Request -> %sp11:RequestType
%RequestType: base(sp11:RequestAbstractType)
sp11:Query?
sp11:SubjectQuery?
sp11:AuthenticationQuery?
sp11:AttributeQuery?
sp11:AuthorizationDecisionQuery?
sa11:AssertionIDReference+
sp11:AssertionArtifact+
;
7993
7994
AssertionArtifact -> %xs:string
7995
7996
Query
-> %sp11:QueryAbstractType
7997
7998
7999
8000
8001
SubjectQuery -> %sp11:SubjectQueryAbstractType
%SubjectQueryAbstractType: base(sp11:QueryAbstractType)
sa11:Subject
;
January 29, 2011
41.2. SAML 1.1
8002
8003
8004
8005
8006
AuthenticationQuery
-> %sp11:AuthenticationQueryType
%AuthenticationQueryType: base(sp11:SubjectQueryAbstractType)
@AuthenticationMethod? -> %xs:anyURI
;
8007
8008
8009
8010
8011
8012
AttributeQuery -> %sp11:AttributeQueryType
%AttributeQueryType: base(sp11:SubjectQueryAbstractType)
sa11:AttributeDesignator*
@Resource? -> %xs:anyURI
;
8013
8014
8015
8016
8017
8018
8019
AuthorizationDecisionQuery -> %sp11:AuthorizationDecisionQueryType
%AuthorizationDecisionQueryType: base(sp11:SubjectQueryAbstractType)
sa11:Action+
sa11:Evidence?
;
8020
8021
8022
8023
8024
8025
8026
8027
8028
8029
%ResponseAbstractType:
ds:Signature?
@ResponseID -> %xs:ID
@Recipient? -> %xs:anyURI
;
8030
8031
8032
8033
8034
8035
Response -> %sp11:ResponseType
%ResponseType: base(sp11:ResponseAbstractType)
sp11:Status
sa11:Assertion*
;
8036
8037
8038
8039
8040
8041
8042
Status -> %sp11:StatusType
%StatusType:
sp11:StatusCode
sp11:StatusMessage?
sp11:StatusDetail?
;
8043
8044
8045
8046
8047
8048
StatusCode -> %sp11:StatusCodeType
%StatusCodeType:
sp11:StatusCode?
@Value -> %xs:QName
;
8049
8050
StatusMessage
-> %xs:string
8051
8052
8053
8054
8055
StatusDetail -> %sp11:StatusDetailType
%StatusDetailType:
any* processContents(lax)
;
January 29, 2011
41.3. LIBERTY ID-FF 1.2
8056
8057
#EOF
8058
8059
41.3
Liberty ID-FF 1.2
8060
41.3.1
liberty-idff-protocols-schema-1.2 (ff12)
8061
8062
8063
8064
8065
8066
8067
8068
8069
# zxid/sg/liberty-idff-protocols-schema-1.2-errata-v2.0.sg
# $Id: liberty-idff-protocols-schema-1.2-errata-v2.0.sg,v 1.4 2009-09-05 02:\
23:41 sampo Exp $
#
# N.B. In order to remove dependency on metadata, all instances
# of %m12:entityIDType have been replaced with %xs:anyURI, which
# is what the former expands to in the metadata schema. This makes
# world a simpler and better place.
8070
8071
target(ff12, urn:liberty:iff:2003-08)
8072
8073
8074
8075
8076
8077
8078
8079
8080
8081
import(sa11, urn:oasis:names:tc:SAML:1.0:assertion,oasis-sstc-saml-schema-as\
sertion-1.1.xsd)
import(sp11, urn:oasis:names:tc:SAML:1.0:protocol,oasis-sstc-saml-schema-pro\
tocol-1.1.xsd)
import(xenc, http://www.w3.org/2001/04/xmlenc#, http://www.w3.org/TR/xmlenc-\
core/xenc-schema.xsd)
#import(ac,
urn:liberty:ac:2003-08, liberty-authentication-context-1.2-err\
ata-v1.0.xsd)
import(ac,
urn:liberty:ac:2004-12, liberty-authentication-context-v2.0.xsd)
8082
8083
8084
#include(liberty-idff-utility-v1.0.xsd)
line expanded
necessary definitions have been in\
8085
8086
8087
8088
8089
Extension
-> %ff12:extensionType
%extensionType:
any+ ns(##other) processContents(lax)
;
8090
8091
8092
8093
8094
8095
8096
8097
8098
8099
8100
8101
8102
8103
8104
ProviderID -> %xs:anyURI
AffiliationID -> %xs:anyURI
AuthnRequest -> %ff12:AuthnRequestType
%AuthnRequestType: base(sp11:RequestAbstractType)
ff12:Extension*
ff12:ProviderID
ff12:AffiliationID?
ff12:NameIDPolicy?
ff12:ForceAuthn? -> %xs:boolean
ff12:IsPassive? -> %xs:boolean
ff12:ProtocolProfile?
ff12:AssertionConsumerServiceID? -> %xs:string
ff12:RequestAuthnContext?
ff12:RelayState?
January 29, 2011
8105
8106
8107
ff12:Scoping?
@consent? -> %xs:string
;
8108
8109
8110
%NameIDPolicyType: enum( none onetime federated any ) ;
NameIDPolicy -> %ff12:NameIDPolicyType
8111
8112
%AuthnContextComparisonType:
enum( exact minimum maximum better ) ;
8113
8114
8115
8116
8117
8118
%ScopingType:
ff12:ProxyCount? -> %xs:nonNegativeInteger
ff12:IDPList?
;
Scoping -> %ff12:ScopingType
8119
8120
RelayState
-> %xs:string
8121
8122
ProtocolProfile
-> %xs:anyURI
8123
8124
8125
8126
8127
8128
RequestAuthnContext:
ff12:AuthnContextClassRef+
-> %xs:anyURI
ff12:AuthnContextStatementRef+ -> %xs:anyURI
ff12:AuthnContextComparison?
-> %ff12:AuthnContextComparisonType
;
8129
8130
8131
8132
8133
8134
8135
8136
AuthnResponse -> %ff12:AuthnResponseType
%AuthnResponseType: base(sp11:ResponseType)
ff12:Extension*
ff12:ProviderID
ff12:RelayState?
;
8137
8138
8139
8140
8141
Assertion -> %ff12:AssertionType
%AssertionType: base(sa11:AssertionType)
;
8142
8143
8144
8145
8146
%SubjectType: base(sa11:SubjectType)
ff12:IDPProvidedNameIdentifier?
;
Subject -> %ff12:SubjectType
8147
8148
8149
8150
8151
8152
EncryptableNameIdentifier -> %ff12:EncryptableNameIdentifierType
%EncryptableNameIdentifierType: base(sa11:NameIdentifierType)
@IssueInstant? -> %xs:dateTime
@Nonce? -> %xs:string
;
8153
8154
8155
8156
8157
8158
EncryptedNameIdentifier -> %ff12:EncryptedNameIdentifierType
%EncryptedNameIdentifierType:
xenc:EncryptedData
xenc:EncryptedKey?
;
January 29, 2011
8159
8160
8161
8162
8163
8164
8165
8166
8167
8168
8169
AuthenticationStatement -> %ff12:AuthenticationStatementType
%AuthenticationStatementType: base(sa11:AuthenticationStatementType)
ff12:AuthnContext?:
ff12:AuthnContextClassRef? -> %xs:anyURI
ac:AuthenticationContextStatement?
ff12:AuthnContextStatementRef? -> %xs:anyURI
;
@ReauthenticateOnOrAfter? -> %xs:dateTime
@SessionIndex -> %xs:string
;
8170
8171
8172
8173
8174
8175
8176
8177
8178
8179
8180
8181
8182
AuthnRequestEnvelope -> %ff12:AuthnRequestEnvelopeType
%AuthnRequestEnvelopeType: base(ff12:RequestEnvelopeType)
ff12:AuthnRequest
ff12:ProviderID
ff12:ProviderName? -> %xs:string
ff12:AssertionConsumerServiceURL -> %xs:anyURI
ff12:IDPList?
ff12:IsPassive? -> %xs:boolean
;
%RequestEnvelopeType:
ff12:Extension*
;
8183
8184
8185
8186
8187
8188
8189
8190
8191
8192
8193
8194
8195
8196
8197
IDPList -> %ff12:IDPListType
%IDPListType:
ff12:IDPEntries
ff12:GetComplete?
;
IDPEntry:
ff12:ProviderID
ff12:ProviderName? -> %xs:string
ff12:Loc -> %xs:anyURI
;
IDPEntries:
ff12:IDPEntry+
;
GetComplete -> %xs:anyURI
8198
8199
8200
8201
8202
8203
8204
8205
8206
8207
8208
8209
8210
8211
8212
AuthnResponseEnvelope -> %ff12:AuthnResponseEnvelopeType
%AuthnResponseEnvelopeType: base(ff12:ResponseEnvelopeType)
ff12:AuthnResponse
ff12:AssertionConsumerServiceURL -> %xs:anyURI
;
%ResponseEnvelopeType:
ff12:Extension*
;
RegisterNameIdentifierRequest -> %ff12:RegisterNameIdentifierRequestType
%RegisterNameIdentifierRequestType: base(sp11:RequestAbstractType)
ff12:Extension*
ff12:ProviderID
ff12:IDPProvidedNameIdentifier
ff12:SPProvidedNameIdentifier?
January 29, 2011
8213
8214
8215
ff12:OldProvidedNameIdentifier
ff12:RelayState?
;
8216
8217
8218
8219
IDPProvidedNameIdentifier -> %sa11:NameIdentifierType
SPProvidedNameIdentifier -> %sa11:NameIdentifierType
OldProvidedNameIdentifier -> %sa11:NameIdentifierType
8220
8221
8222
8223
8224
8225
8226
8227
RegisterNameIdentifierResponse -> %ff12:StatusResponseType
%StatusResponseType: base(sp11:ResponseAbstractType)
ff12:Extension*
ff12:ProviderID
sp11:Status
ff12:RelayState?
;
8228
8229
8230
8231
8232
8233
8234
8235
8236
FederationTerminationNotification -> %ff12:FederationTerminationNotificatio\
nType
%FederationTerminationNotificationType: base(sp11:RequestAbstractType)
ff12:Extension*
ff12:ProviderID
sa11:NameIdentifier
;
8237
8238
8239
8240
8241
8242
8243
8244
8245
8246
8247
8248
LogoutRequest
-> %ff12:LogoutRequestType
%LogoutRequestType:
base(sp11:RequestAbstractType)
ff12:Extension*
ff12:ProviderID
sa11:NameIdentifier
ff12:SessionIndex* -> %xs:string
ff12:RelayState?
@consent?
-> %xs:string
@NotOnOrAfter?
-> %xs:dateTime
;
LogoutResponse -> %ff12:StatusResponseType
8249
8250
8251
8252
8253
8254
8255
8256
8257
NameIdentifierMappingRequest -> %ff12:NameIdentifierMappingRequestType
%NameIdentifierMappingRequestType: base(sp11:RequestAbstractType)
ff12:Extension*
ff12:ProviderID
sa11:NameIdentifier
ff12:TargetNamespace -> %xs:anyURI
@consent?
-> %xs:string
;
8258
8259
8260
8261
8262
8263
8264
8265
NameIdentifierMappingResponse -> %ff12:NameIdentifierMappingResponseType
%NameIdentifierMappingResponseType: base(sp11:ResponseAbstractType)
ff12:Extension*
ff12:ProviderID
sp11:Status
sa11:NameIdentifier?
;
8266
January 29, 2011
8267
# EOF
8268
8269
8270
8271
8272
8273
8274
8275
8276
8277
41.3.2
#
#
#
#
#
#
#
#
liberty-metadata-v2.0 (m20)
zxid/sg/liberty-metadata-v2.0.sg
$Id: liberty-metadata-v2.0.sg,v 1.5 2009-09-05 02:23:41 sampo Exp $
N.B. Older Liberty metadata, liberty-metadata-1.0-errata-v2.0.xsd,
urn:liberty:metadata:2003-08, is nearly identical to this one except
for the actual namespace URI. We therfore adopt convention of using
this new metadata even where strictly speaking the old one should be used.
8278
8279
8280
8281
target(m20, urn:liberty:metadata:2004-12)
import(ds, http://www.w3.org/2000/09/xmldsig#,
http://www.w3.org/TR/2002/\
REC-xmldsig-core-20020212/xmldsig-core-schema.xsd)
8282
8283
8284
8285
8286
import(xs, http://www.w3.org/2001/XMLSchema, http://www.w3.org/2001/xml.xsd)
#import(xs, http://www.w3.org/XML/1998/namespace, http://www.w3.org/2001/xm\
l.xsd)
# include(liberty-idwsf-utility-v2.0.xsd)
8287
8288
8289
8290
8291
Extension
-> %m20:extensionType
%extensionType:
;
8292
8293
%entityIDType:
base(xs:anyURI) ;
8294
8295
8296
8297
%additionalMetadataLocationType:
@namespace? -> %xs:anyURI
;
base(xs:anyURI)
8298
8299
8300
8301
%organizationNameType: base(xs:string)
@lang -> %xs:string #@xml:lang
***
;
8302
8303
8304
8305
%organizationDisplayNameType: base(xs:string)
***
;
8306
8307
8308
8309
8310
8311
8312
%organizationType:
m20:OrganizationName+
m20:OrganizationDisplayName+
m20:OrganizationURL+
m20:Extension?
;
-> %m20:organizationNameType
-> %m20:organizationDisplayNameType
-> %m20:localizedURIType
8313
8314
8315
8316
%localizedURIType: base(xs:anyURI)
***
;
8317
January 29, 2011
8318
8319
8320
8321
8322
8323
8324
8325
8326
8327
%contactType:
m20:Company?
-> %xs:string
m20:GivenName?
-> %xs:string
m20:SurName?
-> %xs:string
m20:EmailAddress*
-> %xs:anyURI
m20:TelephoneNumber* -> %xs:string
m20:Extension?
@libertyPrincipalIdentifier? -> %m20:entityIDType
@contactType -> %m20:attrContactType
;
8328
8329
%attrContactType: enum( technical administrative billing other ) ;
8330
8331
%keyTypes:
enum( encryption signing ) ;
8332
8333
8334
8335
8336
8337
8338
8339
8340
8341
8342
8343
8344
8345
8346
8347
8348
8349
8350
8351
8352
8353
8354
8355
8356
8357
%providerDescriptorType:
m20:KeyDescriptor*
m20:SoapEndpoint? -> %xs:anyURI
m20:SingleLogoutServiceURL?
-> %xs:anyURI
m20:SingleLogoutServiceReturnURL?
-> %xs:anyURI
m20:FederationTerminationServiceURL?
-> %xs:anyURI
m20:FederationTerminationServiceReturnURL?
-> %xs:anyURI
m20:FederationTerminationNotificationProtocolProfile* -> %xs:anyURI
m20:SingleLogoutProtocolProfile*
-> %xs:anyURI
m20:RegisterNameIdentifierProtocolProfile*
-> %xs:anyURI
m20:RegisterNameIdentifierServiceURL?
-> %xs:anyURI
m20:RegisterNameIdentifierServiceReturnURL?
-> %xs:anyURI
m20:NameIdentifierMappingProtocolProfile*
-> %xs:anyURI
m20:NameIdentifierMappingEncryptionProfile*
-> %xs:anyURI
m20:Organization?
-> %m20:organization\
Type
m20:ContactPerson*
-> %m20:contactType
m20:AdditionalMetaLocation* -> %m20:additionalMetadataLocationType
m20:Extension?
ds:Signature?
@protocolSupportEnumeration -> %xs:string
@id?
-> %xs:ID
@validUntil?
-> %xs:dateTime
@cacheDuration?
-> %xs:duration
;
8358
8359
8360
8361
8362
8363
8364
8365
8366
KeyDescriptor -> %m20:keyDescriptorType
%keyDescriptorType:
m20:EncryptionMethod? -> %xs:anyURI
m20:KeySize?
-> %xs:integer
ds:KeyInfo?
m20:Extension?
@use? -> %keyTypes
;
8367
8368
8369
8370
8371
EntitiesDescriptor -> %m20:entitiesDescriptorType
%entitiesDescriptorType:
m20:EntityDescriptor{2,unbounded}
;
January 29, 2011
8372
8373
8374
8375
8376
8377
8378
8379
8380
8381
8382
8383
8384
8385
8386
EntityDescriptor -> %m20:entityDescriptorType
%entityDescriptorType:
m20:IDPDescriptor*
-> %m20:IDPDescriptorType
m20:SPDescriptor*
-> %m20:SPDescriptorType
m20:AffiliationDescriptor* -> %m20:affiliationDescriptorType
m20:ContactPerson?
-> %m20:contactType
m20:Organization?
-> %m20:organizationType
m20:Extension?
ds:Signature?
@providerID
-> %m20:entityIDType
@id?
-> %xs:ID
@validUntil?
-> %xs:dateTime
@cacheDuration?
-> %xs:duration
;
8387
8388
8389
8390
8391
8392
8393
8394
%SPDescriptorType: base(m20:providerDescriptorType)
m20:AssertionConsumerServiceURL+: base(xs:anyURI)
@id
-> %xs:ID
@isDefault? -> %xs:boolean default (false)
;
m20:AuthnRequestsSigned -> %xs:boolean
;
8395
8396
8397
8398
8399
8400
%IDPDescriptorType: base(m20:providerDescriptorType)
m20:SingleSignOnServiceURL
-> %xs:anyURI
m20:SingleSignOnProtocolProfile+ -> %xs:anyURI
m20:AuthnServiceURL?
-> %xs:anyURI
;
8401
8402
8403
8404
8405
8406
8407
8408
8409
8410
8411
%affiliationDescriptorType:
m20:AffiliateMember+ -> %m20:entityIDType
m20:Extension?
m20:KeyDescriptor* -> %m20:keyDescriptorType
ds:Signature?
@affiliationOwnerID -> %m20:entityIDType
@validUntil?
-> %xs:dateTime
@cacheDuration? -> %xs:duration
@id? -> %xs:ID
;
8412
8413
#EOF
8414
8415
8416
8417
8418
8419
8420
8421
8422
41.3.3
#
#
#
o
#
#
#
liberty-authentication-context-v2.0 (ac)
zxid/sg/liberty-authentication-context-v2.0.sg
$Id: liberty-authentication-context-v2.0.sg,v 1.3 2009-09-05 02:23:41 samp\
Exp $
N.B. This file is nearly identical to urn:liberty:ac:2003-08,
liberty-authentication-context-1.2-errata-v1.0.xsd. Thus we adopt the conv\
January 29, 2011
8423
8424
ention
# of using this collection of authentication contexts.
8425
8426
8427
8428
target(ac, urn:liberty:ac:2004-12)
#include(liberty-utility-v2.0.xsd)
expanded
necessary definitions have been inline \
8429
8430
8431
8432
8433
Extension
-> %ac:extensionType
%extensionType:
;
8434
8435
8436
AuthenticationContextStatement -> %ac:AuthenticationContextStatementType
Identification -> %ac:IdentificationType
8437
8438
8439
8440
8441
8442
8443
PhysicalVerification:
@credentialLevel?: enum( primary secondary ) ;
;
WrittenConsent:
ac:Extension*
;
8444
8445
8446
8447
8448
8449
8450
8451
8452
8453
8454
TechnicalProtection -> %ac:TechnicalProtectionType
SecretKeyProtection -> %ac:SecretKeyProtectionType
PrivateKeyProtection -> %ac:PrivateKeyProtectionType
KeyActivation -> %ac:KeyActivationType
KeySharing -> %ac:KeySharingType
KeyStorage -> %ac:KeyStorageType
Password -> %ac:PasswordType
ActivationPin -> %ac:ActivationPinType
Token
-> %ac:TokenType
TimeSyncToken -> %ac:TimeSyncTokenType
8455
8456
8457
8458
Smartcard:
ac:Extension*
;
8459
8460
8461
Length
ActivationLimit
-> %ac:LengthType
-> %ac:ActivationLimitType
8462
8463
8464
8465
Generation:
@mechanism:
;
enum( principalchosen automatic ) ;
8466
8467
8468
8469
AuthenticationMethod -> %ac:AuthenticationMethodType
PrincipalAuthenticationMechanism -> %ac:PrincipalAuthenticationMechanismType
Authenticator -> %ac:AuthenticatorType
8470
8471
8472
8473
8474
8475
8476
PreviousSession:
ac:Extension*
;
ResumeSession:
ac:Extension*
;
January 29, 2011
8477
8478
8479
8480
8481
8482
8483
8484
8485
8486
8487
8488
8489
8490
8491
8492
8493
8494
8495
8496
8497
8498
8499
8500
8501
8502
8503
8504
8505
8506
8507
8508
8509
8510
8511
8512
8513
8514
8515
8516
8517
8518
8519
8520
8521
8522
8523
8524
8525
8526
8527
8528
8529
8530
ZeroKnowledge:
ac:Extension*
;
SharedSecretChallengeResponse:
ac:Extension*
;
DigSig:
ac:Extension*
;
IPAddress:
ac:Extension*
;
AsymmetricDecryption:
ac:Extension*
;
AsymmetricKeyAgreement:
ac:Extension*
;
SharedSecretDynamicPlaintext:
ac:Extension*
;
AuthenticatorTransportProtocol -> %ac:AuthenticatorTransportProtocolType
HTTP:
ac:Extension*
;
IPSec:
ac:Extension*
;
WTLS:
ac:Extension*
;
MobileNetworkNoEncryption:
ac:Extension*
;
MobileNetworkRadioEncryption:
ac:Extension*
;
MobileNetworkEndToEndEncryption:
ac:Extension*
;
SSL:
ac:Extension*
;
OperationalProtection -> %ac:OperationalProtectionType
SecurityAudit -> %ac:SecurityAuditType
SwitchAudit:
ac:Extension*
;
DeactivationCallCenter:
ac:Extension*
;
GoverningAgreements -> %ac:GoverningAgreementsType
GoverningAgreementRef -> %ac:GoverningAgreementRefType
AuthenticatingAuthority -> %ac:AuthenticatingAuthorityType
January 29, 2011
8531
8532
8533
8534
8535
8536
8537
8538
8539
8540
8541
8542
8543
8544
8545
8546
8547
8548
8549
8550
8551
8552
8553
8554
8555
8556
8557
8558
8559
8560
8561
8562
8563
8564
8565
8566
8567
8568
8569
8570
8571
8572
8573
8574
8575
8576
8577
8578
8579
8580
8581
8582
8583
8584
%IdentificationType:
ac:PhysicalVerification?
ac:WrittenConsent?
ac:Extension*
@nym?: enum( anonymity verinymity pseudonymity ) ;
;
%GoverningAgreementsType:
ac:GoverningAgreementRef+
;
%GoverningAgreementRefType:
@governingAgreementRef -> %xs:anyURI
;
%AuthenticatingAuthorityType:
ac:GoverningAgreements
@ID -> %xs:anyURI
;
%AuthenticatorTransportProtocolType:
ac:HTTP?
ac:SSL?
ac:MobileNetworkNoEncryption?
ac:MobileNetworkRadioEncryption?
ac:MobileNetworkEndToEndEncryption?
ac:WTLS?
ac:IPSec?
ac:Extension+
;
%PrincipalAuthenticationMechanismType:
ac:Password?
ac:Token?
ac:Smartcard?
ac:ActivationPin?
ac:Extension+
;
%AuthenticationMethodType:
ac:PrincipalAuthenticationMechanism?
ac:Authenticator?
ac:AuthenticatorTransportProtocol?
ac:Extension*
;
%AuthenticationContextStatementType:
ac:Identification?
ac:TechnicalProtection?
ac:OperationalProtection?
ac:AuthenticationMethod?
ac:GoverningAgreements?
ac:AuthenticatingAuthority*
ac:Extension*
@ID? -> %xs:ID
;
%TechnicalProtectionType:
ac:PrivateKeyProtection?
ac:SecretKeyProtection?
ac:Extension*
;
January 29, 2011
8585
8586
8587
8588
8589
8590
8591
8592
8593
8594
8595
8596
8597
8598
8599
8600
8601
8602
8603
8604
8605
8606
8607
8608
8609
8610
8611
8612
8613
8614
8615
8616
8617
8618
8619
8620
8621
8622
8623
8624
8625
8626
8627
8628
%OperationalProtectionType:
ac:SecurityAudit?
ac:DeactivationCallCenter?
ac:Extension*
;
%AuthenticatorType:
ac:PreviousSession?
ac:ResumeSession?
ac:DigSig?
ac:Password?
ac:ZeroKnowledge?
ac:SharedSecretChallengeResponse?
ac:SharedSecretDynamicPlaintext?
ac:IPAddress?
ac:AsymmetricDecryption?
ac:AsymmetricKeyAgreement?
ac:Extension+
;
%KeyActivationType:
ac:ActivationPin?
ac:Extension+
;
%KeySharingType:
@sharing -> %xs:boolean
;
%PrivateKeyProtectionType:
ac:KeyActivation?
ac:KeyStorage?
ac:KeySharing?
ac:Extension*
;
%PasswordType:
ac:Length?
ac:Alphabet?
ac:Generation?
ac:Extension*
;
%ActivationPinType:
ac:Length?
ac:Alphabet?
ac:Generation?
ac:ActivationLimit?
ac:Extension*
;
8629
8630
8631
8632
8633
8634
8635
Alphabet -> %ac:AlphabetType
%AlphabetType:
@requiredChars -> %xs:string
@excludedChars? -> %xs:string
@case?
-> %xs:string
;
8636
8637
8638
%TokenType:
ac:TimeSyncToken
January 29, 2011
CHAPTER 41. APPENDIX: SCHEMA GRAMMARS 41.4. LIBERTY ID-WSF 1.1
ac:Extension*
8639
8640
8641
8642
8643
8644
8645
8646
;
%TimeSyncTokenType:
@DeviceType: enum( hardware software ) ;
@SeedLength -> %xs:integer
@DeviceInHand: enum( true false ) ;
;
8647
8648
8649
8650
8651
8652
8653
8654
8655
8656
8657
8658
8659
8660
8661
%ActivationLimitType:
ac:ActivationLimitDuration?
ac:ActivationLimitUsages?
ac:ActivationLimitSession?
;
ActivationLimitDuration -> %ac:ActivationLimitDurationType
ActivationLimitUsages -> %ac:ActivationLimitUsagesType
ActivationLimitSession -> %ac:ActivationLimitSessionType
%ActivationLimitDurationType:
@duration -> %xs:duration
;
%ActivationLimitUsagesType:
@number -> %xs:integer
;
8662
8663
8664
8665
8666
8667
8668
8669
8670
8671
8672
8673
8674
8675
8676
8677
8678
%LengthType:
@min -> %xs:integer
@max? -> %xs:integer
;
%KeyStorageType:
@medium: enum( memory smartcard token MobileDevice MobileAuthCard ) ;
;
%SecretKeyProtectionType:
ac:KeyActivation?
ac:KeyStorage?
ac:Extension+
;
%SecurityAuditType:
ac:SwitchAudit?
ac:Extension*
;
8679
8680
# EOF
8681
8682
41.4
Liberty ID-WSF 1.1
8683
41.4.1
liberty-idwsf-soap-binding-v1.2 (b12)
8684
8685
8686
8687
#
#
#
p
zxid/sg/liberty-idwsf-disco-svc-v1.2.sg
$Id: liberty-idwsf-soap-binding-v1.2.sg,v 1.3 2009-09-05 02:23:41 sampo Ex\
$
January 29, 2011
41.4. LIBERTY ID-WSF 1.1 CHAPTER 41. APPENDIX: SCHEMA GRAMMARS
8688
8689
8690
8691
8692
target(b12, urn:liberty:sb:2003-08)
import(e, http://schemas.xmlsoap.org/soap/envelope/, http://schemas.xmlsoap.\
org/soap/envelope/)
include(liberty-idwsf-utility-v1.1.xsd)
8693
8694
8695
8696
8697
8698
8699
8700
8701
8702
%CorrelationType:
@messageID
-> %xs:string
# %IDType
@refToMessageID? -> %xs:string
# %IDType
@timestamp
-> %xs:dateTime
@id?
-> %xs:ID
@e:mustUnderstand?
@e:actor?
;
Correlation -> %b12:CorrelationType
8703
8704
8705
8706
8707
8708
8709
8710
8711
%ProviderType:
@providerID
-> %xs:anyURI
@affiliationID? -> %xs:anyURI
@id?
-> %xs:ID
@e:mustUnderstand?
@e:actor?
;
Provider -> %b12:ProviderType
8712
8713
8714
8715
8716
8717
8718
%ProcessingContextType: base(xs:anyURI)
@id? -> %xs:ID
@e:mustUnderstand?
@e:actor?
;
ProcessingContext -> %b12:ProcessingContextType
8719
8720
8721
8722
8723
8724
8725
8726
8727
%ConsentType:
@uri
-> %xs:anyURI
@timestamp? -> %xs:dateTime
@id?
-> %xs:ID
@e:mustUnderstand?
@e:actor?
;
Consent -> %b12:ConsentType
8728
8729
8730
8731
8732
8733
8734
8735
8736
%UsageDirectiveType:
@id? -> %xs:ID
@ref -> %xs:IDREF
@e:mustUnderstand?
@e:actor?
;
UsageDirective -> %b12:UsageDirectiveType
8737
8738
#EOF
8739
January 29, 2011
8740
8741
8742
8743
8744
41.4.2
liberty-idwsf-security-mechanisms-v1.2 (sec12)
# zxid/sg/liberty-idwsf-security-mechanism-v1.2.sg
# $Id: liberty-idwsf-security-mechanisms-v1.2.sg,v 1.3 2009-09-05 02:23:41 s\
ampo Exp $
8745
8746
8747
8748
8749
8750
8751
8752
8753
target(sec12, urn:liberty:sec:2003-08)
import(sa11, urn:oasis:names:tc:SAML:1.0:assertion, oasis-sstc-saml-schema-a\
ssertion-1.1.xsd)
import(ff12, urn:liberty:iff:2003-08,liberty-idff-protocols-schema-1.2-errat\
a-v3.0.xsd)
import(di12, urn:liberty:disco:2003-08,liberty-idwsf-disco-svc-v1.2.xsd)
import(ds, http://www.w3.org/2000/09/xmldsig#, http://www.w3.org/TR/2002/REC\
-xmldsig-core-20020212/xmldsig-core-schema.xsd)
8754
8755
8756
8757
8758
ValidityRestrictionCondition
-> %sec12:ValidityRestrictionConditionType
%ValidityRestrictionConditionType: base(sa11:ConditionAbstractType)
sec12:NumberOfUses -> %xs:integer
;
8759
8760
ProxySubject -> %sa11:SubjectType
8761
8762
ProxyTransitedStatement -> %sa11:SubjectStatementAbstractType
8763
8764
8765
8766
8767
8768
8769
8770
8771
ProxyInfoConfirmationData -> %sec12:ProxyInfoConfirmationType
%ProxyInfoConfirmationType:
sa11:AssertionIDReference
sec12:Issuer -> %xs:string
sec12:IssueInstant -> %xs:dateTime
ds:Signature?
@id? -> %xs:ID
;
8772
8773
8774
8775
8776
8777
8778
8779
8780
8781
SessionContext -> %sec12:SessionContextType
%SessionContextType:
sec12:SessionSubject
-> %ff12:SubjectType
sec12:ProviderID
-> %xs:anyURI
# %md:entityIDType
ff12:RequestAuthnContext?
@SessionIndex?
-> %xs:string
@AuthenticationInstant -> %xs:dateTime
@AssertionIssueInstant -> %xs:dateTime
;
8782
8783
8784
8785
8786
8787
SessionContextStatement
-> %sec12:SessionContextStatementType
%SessionContextStatementType: base(sa11:SubjectStatementAbstractType)
sec12:ProxySubject?
sec12:SessionContext
;
8788
8789
8790
8791
8792
ResourceAccessStatement
-> %sec12:ResourceAccessStatementType
%ResourceAccessStatementType: base(sa11:SubjectStatementAbstractType)
&di12:ResourceIDGroup
sec12:ProxySubject
January 29, 2011
8793
8794
sec12:SessionContext?
;
8795
8796
#EOF
8797
8798
8799
8800
8801
41.4.3
liberty-idwsf-disco-svc-v1.2 (di12)
# zxid/sg/liberty-idwsf-disco-svc-v1.2.sg
# $Id: liberty-idwsf-disco-svc-v1.2.sg,v 1.3 2009-09-05 02:23:41 sampo Exp $
8802
8803
8804
8805
8806
target(di12, urn:liberty:disco:2003-08)
import(xenc, http://www.w3.org/2001/04/xmlenc#, http://www.w3.org/TR/2002/RE\
C-xmlenc-core-20021210/xenc-schema.xsd)
#include(liberty-idwsf-utility-v1.1.xsd)
8807
8808
ServiceType
-> %xs:anyURI
8809
8810
8811
8812
%ResourceIDType: base(xs:anyURI)
@id? -> %xs:ID
;
8813
8814
8815
8816
8817
%EncryptedResourceIDType:
xenc:EncryptedData
xenc:EncryptedKey
# N.B. Encrypted data itself can carry a key, too
;
8818
8819
ResourceID -> %di12:ResourceIDType
8820
8821
EncryptedResourceID -> %di12:EncryptedResourceIDType
8822
8823
8824
8825
8826
&ResourceIDGroup:
di12:ResourceID?
di12:EncryptedResourceID?
;
8827
8828
8829
8830
8831
8832
8833
8834
%DescriptionType:
di12:SecurityMechID+ -> %xs:anyURI
di12:CredentialRef* -> %xs:IDREF
&di12:WsdlRef*
&di12:BriefSoapHttpDescription*
@id? -> %xs:ID
;
8835
8836
8837
8838
8839
&WsdlRef:
di12:WsdlURI
-> %xs:anyURI
di12:ServiceNameRef -> %xs:QName
;
8840
8841
8842
8843
&BriefSoapHttpDescription:
di12:Endpoint
-> %xs:anyURI
di12:SoapAction? -> %xs:anyURI
January 29, 2011
8844
;
8845
8846
8847
8848
8849
8850
%ServiceInstanceType:
di12:ServiceType
di12:ProviderID -> %xs:anyURI
#%md:entityIDType
di12:Description+ -> %di12:DescriptionType
;
8851
8852
8853
8854
8855
8856
8857
8858
8859
ResourceOffering -> %di12:ResourceOfferingType
%ResourceOfferingType:
di12:ServiceInstance -> %di12:ServiceInstanceType
di12:Options?
di12:Abstract? -> %xs:string
@entryID? -> %xs:string
#%IDType
;
8860
8861
8862
8863
8864
Options -> %di12:OptionsType
%OptionsType:
di12:Option* -> %xs:anyURI
;
8865
8866
8867
8868
8869
8870
8871
8872
8873
8874
Query -> %di12:QueryType
%QueryType:
di12:RequestedServiceType*:
di12:ServiceType
di12:Options?
;
@id? -> %xs:ID
;
8875
8876
8877
8878
8879
8880
8881
8882
8883
8884
QueryResponse -> %di12:QueryResponseType
%QueryResponseType:
di12:Status
di12:Credentials?:
;
@id? -> %xs:ID
;
8885
8886
8887
8888
8889
%InsertEntryType:
di12:ResourceOffering
;
8890
8891
8892
8893
%RemoveEntryType:
@entryID -> %xs:string #%IDReferenceType
;
8894
8895
8896
8897
Modify -> %di12:ModifyType
%ModifyType:
January 29, 2011
8898
8899
8900
8901
di12:InsertEntry*
di12:RemoveEntry*
@id? -> %xs:ID
;
-> %di12:InsertEntryType
-> %di12:RemoveEntryType
8902
8903
8904
8905
%DirectiveType:
@descriptionIDRefs?
;
-> %xs:IDREFS
8906
8907
8908
8909
8910
AuthenticateRequester
-> %di12:DirectiveType
AuthorizeRequester
AuthenticateSessionContext -> %di12:DirectiveType
EncryptResourceID
8911
8912
8913
8914
8915
8916
8917
8918
ModifyResponse -> %di12:ModifyResponseType
%ModifyResponseType:
di12:Status
di12:Extension?
@id? -> %xs:ID
@newEntryIDs? -> %xs:string
# : list (IDReferenceType) ;
;
8919
8920
# From liberty-idwsf-utility-v1.1.sg
8921
8922
8923
8924
8925
8926
8927
8928
Status
-> %di12:StatusType
%StatusType:
di12:Status*
@code
-> %xs:QName
@ref?
-> %xs:string
@comment? -> %xs:string
;
8929
8930
8931
8932
8933
Extension
-> %di12:extensionType
%extensionType:
;
8934
8935
#EOF
8936
8937
8938
8939
8940
8941
41.4.4
liberty-idwsf-interaction-svc-v1.1 (is12)
# zxid/sg/liberty-idwsf-interaction-svc-v1.2.sg
# $Id: liberty-idwsf-interaction-svc-v1.1.sg,v 1.3 2009-09-05 02:23:41 sampo\
Exp $
8942
8943
8944
8945
8946
8947
8948
target(is12, urn:liberty:is:2003-08)
import(di12, urn:liberty:disco:2003-08, liberty-idwsf-disco-svc-v1.2.xsd)
import(e,
http://schemas.xmlsoap.org/soap/envelope/, http://schemas.xmlso\
ap.org/soap/envelope/)
import(ds,
http://www.w3.org/2000/09/xmldsig#,http://www.w3.org/TR/2002/RE\
C-xmldsig-core-20020212/xmldsig-core-schema.xsd)
January 29, 2011
8949
#include(liberty-idwsf-utility-v1.1.xsd)
8950
8951
8952
8953
8954
8955
8956
8957
8958
8959
8960
8961
UserInteraction -> %is12:UserInteractionHeaderType
%UserInteractionHeaderType:
is12:InteractionService? -> %di12:ResourceOfferingType
@id?
-> %xs:ID
@interact?
-> %xs:QName default (is12:interactIfNeeded)
@language?
-> %xs:NMTOKENS
@redirect?
-> %xs:boolean default (0)
@maxInteractTime? -> %xs:integer
@e:actor?
@e:mustUnderstand?
;
8962
8963
8964
8965
8966
RedirectRequest -> %is12:RedirectRequestType
%RedirectRequestType:
@redirectURL -> %xs:anyURI
;
8967
8968
ResourceID -> %di12:ResourceIDType
8969
8970
EncryptedResourceID -> %di12:EncryptedResourceIDType
8971
8972
8973
8974
&ResourceIDGroup:
is12:ResourceID | is12:EncryptedResourceID
;
8975
8976
8977
8978
8979
8980
8981
8982
8983
8984
8985
InteractionRequest -> %is12:InteractionRequestType
%InteractionRequestType:
&is12:ResourceIDGroup?
is12:Inquiry+
ds:KeyInfo?
@id?
-> %xs:ID
@language?
-> %xs:NMTOKENS
@signed?
-> %xs:token
;
8986
8987
8988
8989
8990
8991
8992
8993
8994
8995
Inquiry
%InquiryType:
is12:Help?
is12:Select*
is12:Confirm*
is12:Text*
@id?
@title?
;
-> %is12:InquiryType
-> %is12:InquiryElementType
-> %xs:ID
-> %xs:string
8996
8997
8998
8999
9000
9001
9002
Help
%HelpType:
@label?
@link?
@moreLink?
;
-> %is12:HelpType
-> %xs:string
-> %xs:anyURI
-> %xs:anyURI
January 29, 2011
9003
9004
Hint
-> %xs:string
9005
9006
9007
9008
9009
9010
9011
9012
9013
9014
Select
-> %is12:SelectType
%SelectType:
base(is12:InquiryElementType)
is12:Item{2,unbounded}:
is12:Hint?
@label? -> %xs:string
@value -> %xs:NMTOKEN
;
@multiple? -> %xs:boolean default (false)
;
9015
9016
9017
9018
9019
9020
9021
Text
%TextType:
@minChars?
@maxChars?
@format?
;
-> %is12:TextType
base(is12:InquiryElementType)
-> %xs:integer
-> %xs:integer
-> %xs:string
9022
9023
9024
9025
9026
9027
9028
9029
%InquiryElementType:
is12:Help?
is12:Hint?
is12:Label? -> %xs:normalizedString
is12:Value? -> %xs:normalizedString
@name
-> %xs:ID
;
9030
9031
9032
9033
9034
9035
9036
InteractionResponse
-> %is12:InteractionResponseType
%InteractionResponseType:
is12:Status
is12:InteractionStatement* -> %is12:InteractionStatementType
is12:Parameter*
-> %is12:ParameterType
;
9037
9038
9039
9040
9041
%InteractionStatementType:
is12:Inquiry+
ds:Signature
;
9042
9043
9044
9045
9046
%ParameterType:
@name -> %xs:ID
@value -> %xs:string
;
9047
9048
# From liberty-idwsf-utility-v1.1.sg
9049
9050
9051
9052
9053
9054
9055
9056
Status
-> %is12:StatusType
%StatusType:
is12:Status*
@code
-> %xs:QName
@ref?
-> %xs:string
@comment? -> %xs:string
;
January 29, 2011
9057
9058
9059
9060
9061
Extension
-> %is12:extensionType
%extensionType:
;
9062
9063
#EOF
9064
9065
41.5
Liberty ID-WSF 2.0
9066
41.5.1
liberty-idwsf-utility-v2.0 (lu)
9067
9068
9069
# zxid/sg/liberty-idwsf-utility-v2.0.sg
# $Id: liberty-idwsf-utility-v2.0.sg,v 1.3 2009-09-05 02:23:41 sampo Exp $
9070
9071
target(lu, urn:liberty:util:2006-08)
9072
9073
9074
9075
9076
%IDType:
base(xs:string) ;
%IDReferenceType: base(xs:string) ;
@itemID
-> %lu:IDType
@itemIDRef -> %lu:IDReferenceType
9077
9078
9079
9080
9081
9082
9083
9084
%StatusType:
lu:Status*
@code
->
@ref?
->
@comment? ->
;
Status
->
%xs:string
%lu:IDReferenceType
%xs:string
%lu:StatusType
9085
9086
9087
9088
9089
9090
9091
%ResponseType:
lu:Status
lu:Extension*
@itemIDRef? -> %lu:IDReferenceType
@any
;
9092
9093
9094
9095
9096
TestResult
-> %lu:TestResultType
%TestResultType: base(xs:boolean)
;
9097
9098
%EmptyType:
base(xs:anyType) ;
9099
9100
9101
9102
9103
Extension -> %lu:extensionType
%extensionType:
;
9104
9105
#EOF
January 29, 2011
9106
9107
9108
9109
9110
41.5.2
liberty-idwsf-soap-binding (no version, sbf)
# zxid/sg/liberty-idwsf-soap-binding.sg
# $Id: liberty-idwsf-soap-binding.sg,v 1.4 2009-09-05 02:23:41 sampo Exp $
9111
9112
9113
9114
9115
target(sbf, urn:liberty:sb)
import(wsu, http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecuri\
ty-utility-1.0.xsd)
import(e,
http://schemas.xmlsoap.org/soap/envelope/)
9116
9117
9118
9119
9120
9121
9122
9123
9124
9125
%FrameworkType:
@version -> %xs:string
@wsu:Id?
@e:mustUnderstand?
@e:actor?
@any
;
Framework
-> %sbf:FrameworkType
9126
9127
#EOF
9128
9129
9130
9131
9132
9133
41.5.3
#
#
#
p
liberty-idwsf-soap-binding-v2.0 (b)
zxid/sg/liberty-idwsf-soap-binding-v2.0.sg
$Id: liberty-idwsf-soap-binding-v2.0.sg,v 1.8 2009-11-24 23:53:40 sampo Ex\
$
9134
9135
9136
9137
9138
9139
9140
9141
9142
9143
9144
9145
9146
9147
target(b,
urn:liberty:sb:2006-08)
import(sp,
urn:oasis:names:tc:SAML:2.0:protocol)
import(wsu, http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecur\
ity-utility-1.0.xsd,wss-util-1.0.xsd)
import(a,
http://www.w3.org/2005/08/addressing,ws-addr-1.0.xsd)
import(lu,
urn:liberty:util:2006-08,liberty-idwsf-utility-v2.0.xsd)
import(e,
import(sa11, urn:oasis:names:tc:SAML:1.0:assertion)
import(sa,
import(ff12, urn:liberty:iff:2003-08)
import(xa,
urn:oasis:names:tc:xacml:2.0:policy:schema:os, http://docs.oasi\
s-open.org/xacml/access_control-xacml-2.0-policy-schema-os.xsd)
import(tas3sol, http://tas3.eu/tas3sol/200911/)
9148
9149
9150
9151
9152
9153
&@hdr:
@wsu:Id?
@e:mustUnderstand?
@e:actor?
@id? -> %xs:anyURI
January 29, 2011
9154
;
9155
9156
9157
9158
9159
9160
9161
9162
Framework -> %b:FrameworkType
%FrameworkType:
@version -> %xs:string
&@b:hdr
# Added by Sampo
@any
;
9163
9164
9165
9166
9167
9168
9169
9170
Sender -> %b:SenderType
%SenderType:
@providerID
-> %xs:anyURI
@affiliationID? -> %xs:anyURI
&@b:hdr
# Added by Sampo
@any
;
9171
9172
9173
9174
9175
9176
9177
9178
9179
9180
9181
TargetIdentity -> %b:TargetIdentityType
%TargetIdentityType:
sa:Assertion?
sa11:Assertion?
ff12:Assertion?
&@b:hdr
# Added by Sampo
@any
;
9182
9183
9184
9185
9186
9187
9188
9189
CredentialsContext -> %b:CredentialsContextType
%CredentialsContextType:
b:SecurityMechID* -> %xs:anyURI
&@b:hdr
# Added by Sampo
@any
;
9190
9191
9192
9193
9194
EndpointUpdate -> %b:EndpointUpdateType
%EndpointUpdateType: base(a:EndpointReferenceType)
@updateType? -> %xs:anyURI
;
9195
9196
9197
9198
9199
9200
9201
Timeout -> %b:TimeoutType
%TimeoutType:
@maxProcessingTime -> %xs:integer
&@b:hdr
# Added by Sampo
@any
;
9202
9203
9204
9205
9206
9207
ProcessingContext -> %b:ProcessingContextType
%ProcessingContextType: base(xs:anyURI)
&@b:hdr
# Added by Sampo
@any
;
January 29, 2011
9208
9209
9210
9211
9212
9213
9214
9215
Consent -> %b:ConsentType
%ConsentType:
@uri -> %xs:anyURI
@timestamp? -> %xs:dateTime
&@b:hdr
# Added by Sampo
@any
;
9216
9217
9218
9219
9220
9221
9222
9223
9224
9225
UsageDirective -> %b:UsageDirectiveType
%UsageDirectiveType:
xa:Obligation*
tas3sol:Dict?
@ref -> %xs:IDREF
&@b:hdr
# Added by Sampo
@any
;
9226
9227
#
tas3sol:Obligations?
9228
9229
ApplicationEPR
-> %a:EndpointReferenceType
9230
9231
9232
9233
9234
9235
9236
9237
9238
9239
9240
UserInteraction -> %b:UserInteractionHeaderType
%UserInteractionHeaderType:
b:InteractionService* -> %a:EndpointReferenceType
@interact? -> %xs:string default (interactIfNeeded)
@language? -> %xs:NMTOKENS
@redirect? -> %xs:boolean default (0)
&@b:hdr
# Added by Sampo
@any
;
9241
9242
9243
9244
9245
9246
RedirectRequest -> %b:RedirectRequestType
%RedirectRequestType:
@redirectURL -> %xs:anyURI
&@b:hdr
# Added by Sampo
;
9247
9248
#EOF
9249
9250
9251
9252
9253
9254
9255
41.5.4
liberty-idwsf-security-mechanisms-v2.0 (sec)
# zxid/sg/liberty-idwsf-security-mechanisms-v2.0.sg
# 10.2.2007, added sa:Assertion as potential security token type --Sampo
# $Id: liberty-idwsf-security-mechanisms-v2.0.sg,v 1.7 2009-08-25 16:22:45 s\
ampo Exp $
9256
9257
9258
target(sec, urn:liberty:security:2006-08)
ns(sa,
January 29, 2011
9259
9260
9261
ns(sp,
ns(sa11,
ns(ff12,
urn:oasis:names:tc:SAML:2.0:protocol)
urn:liberty:iff:2003-08)
9262
9263
9264
9265
9266
9267
9268
9269
9270
9271
TokenPolicy -> %sec:TokenPolicyType
%TokenPolicyType:
sp:NameIDPolicy?
@validUntil? -> %xs:dateTime
@issueTo? -> %xs:anyURI
@type? -> %xs:anyURI
@wantDSEPR?
-> %xs:boolean
;
9272
9273
#
@any*
9274
9275
9276
9277
9278
9279
TransitedProvider -> %sec:TransitedProviderType
%TransitedProviderType: base(xs:anyURI)
@timeStamp? -> %xs:dateTime
@confirmationURI? -> %xs:anyURI
;
9280
9281
9282
9283
9284
TransitedProviderPath -> %sec:TransitedProviderPathType
%TransitedProviderPathType:
sec:TransitedProvider+
;
9285
9286
9287
9288
9289
9290
9291
9292
9293
9294
9295
9296
Token
-> %sec:TokenType
%TokenType:
sa:Assertion?
sa11:Assertion?
ff12:Assertion?
@id?
-> %xs:ID
@ref?
-> %xs:anyURI
@usage? -> %xs:anyURI
;
9297
9298
#EOF
9299
9300
9301
9302
9303
41.5.5
liberty-idwsf-disco-svc-v2.0 (di)
# zxid/sg/liberty-idwsf-disco-svc-v2.0.sg
# $Id: liberty-idwsf-disco-svc-v2.0.sg,v 1.2 2009-09-05 02:23:41 sampo Exp $
9304
9305
9306
9307
9308
9309
target(di,
import(md,
sd)
import(b,
import(sbf,
urn:liberty:disco:2006-08)
urn:oasis:names:tc:SAML:2.0:metadata, saml-schema-metadata-2.0.x\
urn:liberty:sb:2006-08, liberty-idwsf-soap-binding-v2.0.xsd)
urn:liberty:sb, liberty-idwsf-soap-binding.xsd)
January 29, 2011
9310
9311
9312
9313
import(a,
http://www.w3.org/2005/08/addressing, ws-addr-1.0.xsd)
import(lu, urn:liberty:util:2006-08, liberty-idwsf-utility-v2.0.xsd)
import(sec, urn:liberty:security:2006-08, liberty-idwsf-security-mechanisms-\
v2.0.xsd)
9314
9315
9316
9317
9318
9319
Abstract -> %xs:string
ProviderID -> %xs:anyURI
ServiceType -> %xs:anyURI
Framework -> %sbf:FrameworkType
@NotOnOrAfter -> %xs:dateTime
9320
9321
9322
9323
9324
9325
SecurityContext:
di:SecurityMechID+
sec:Token*
;
SecurityMechID -> %xs:anyURI
9326
9327
9328
9329
9330
9331
Options -> %di:OptionsType
Option -> %xs:anyURI
%OptionsType:
di:Option*
;
9332
9333
9334
Address -> %xs:anyURI
Action -> %xs:anyURI
9335
9336
9337
9338
9339
Keys -> %di:KeysType
%KeysType:
md:KeyDescriptor+
;
9340
9341
9342
9343
9344
9345
9346
9347
SvcMD -> %di:SvcMetadataType
%SvcMetadataType:
di:Abstract
di:ProviderID
di:ServiceContext+
@svcMDID? -> %xs:string
;
9348
9349
9350
9351
9352
9353
9354
ServiceContext -> %di:ServiceContextType
%ServiceContextType:
di:ServiceType+
di:Options*
di:EndpointContext+
;
9355
9356
9357
9358
9359
9360
9361
9362
EndpointContext -> %di:EndpointContextType
%EndpointContextType:
di:Address+
sbf:Framework+
di:SecurityMechID+
di:Action*
;
9363
January 29, 2011
9364
SvcMDID
-> %xs:string
9365
9366
9367
9368
9369
9370
Query -> %di:QueryType
%QueryType:
di:RequestedService* -> %di:RequestedServiceType
@any
;
9371
9372
9373
9374
9375
9376
9377
9378
9379
9380
9381
9382
%RequestedServiceType:
di:ServiceType*
di:ProviderID*
di:Options*
di:SecurityMechID*
di:Framework*
di:Action*
@reqID? -> %xs:string
@resultsType? -> %xs:string
;
9383
9384
9385
9386
9387
9388
9389
QueryResponse -> %di:QueryResponseType
%QueryResponseType:
lu:Status
@any
;
9390
9391
9392
9393
9394
9395
SvcMDAssociationAdd -> %di:SvcMDAssociationAddType
%SvcMDAssociationAddType:
di:SvcMDID+
@any
;
9396
9397
9398
9399
9400
9401
SvcMDAssociationAddResponse -> %di:SvcMDAssociationAddResponseType
%SvcMDAssociationAddResponseType:
lu:Status
@any
;
9402
9403
9404
9405
9406
9407
SvcMDAssociationDelete -> %di:SvcMDAssociationDeleteType
%SvcMDAssociationDeleteType:
di:SvcMDID+
@any
;
9408
9409
9410
9411
9412
9413
SvcMDAssociationDeleteResponse -> %di:SvcMDAssociationDeleteResponseType
%SvcMDAssociationDeleteResponseType:
lu:Status
@any
;
9414
9415
9416
9417
SvcMDAssociationQuery -> %di:SvcMDAssociationQueryType
%SvcMDAssociationQueryType:
di:SvcMDID*
January 29, 2011
9418
9419
@any
;
9420
9421
9422
9423
9424
9425
9426
SvcMDAssociationQueryResponse -> %di:SvcMDAssociationQueryResponseType
%SvcMDAssociationQueryResponseType:
lu:Status
di:SvcMDID*
@any
;
9427
9428
9429
9430
9431
9432
SvcMDRegister -> %di:SvcMDRegisterType
%SvcMDRegisterType:
di:SvcMD+
@any
;
9433
9434
9435
9436
9437
9438
9439
9440
SvcMDRegisterResponse -> %di:SvcMDRegisterResponseType
%SvcMDRegisterResponseType:
lu:Status
di:SvcMDID*
di:Keys*
@any
;
9441
9442
9443
9444
9445
9446
SvcMDDelete -> %di:SvcMDDeleteType
%SvcMDDeleteType:
di:SvcMDID+
@any
;
9447
9448
9449
9450
9451
9452
SvcMDDeleteResponse -> %di:SvcMDDeleteResponseType
%SvcMDDeleteResponseType:
lu:Status
@any
;
9453
9454
9455
9456
9457
9458
SvcMDQuery -> %di:SvcMDQueryType
%SvcMDQueryType:
di:SvcMDID*
@any
;
9459
9460
9461
9462
9463
9464
9465
SvcMDQueryResponse -> %di:SvcMDQueryResponseType
%SvcMDQueryResponseType:
lu:Status
di:SvcMD*
@any
;
9466
9467
9468
9469
9470
9471
SvcMDReplace -> %di:SvcMDReplaceType
%SvcMDReplaceType:
di:SvcMD+
@any
;
January 29, 2011
9472
9473
9474
9475
9476
9477
SvcMDReplaceResponse -> %di:SvcMDReplaceResponseType
%SvcMDReplaceResponseType:
lu:Status
@any
;
9478
9479
#EOF
9480
9481
9482
9483
9484
9485
41.5.6
liberty-idwsf-interaction-svc-v2.0 (is)
# zxid/sg/liberty-idwsf-interaction-svc-v2.0.sg
# $Id: liberty-idwsf-interaction-svc-v2.0.sg,v 1.3 2009-09-05 02:23:41 sampo\
Exp $
9486
9487
9488
9489
9490
target(is, urn:liberty:is:2006-08)
import(lu, urn:liberty:util:2006-08,liberty-idwsf-utility-v2.0.xsd)
import(ds, http://www.w3.org/2000/09/xmldsig#, http://www.w3.org/TR/2002/REC\
-xmldsig-core-20020212/xmldsig-core-schema.xsd)
9491
9492
9493
9494
9495
9496
9497
9498
9499
9500
InteractionRequest -> %is:InteractionRequestType
%InteractionRequestType:
is:Inquiry+
ds:KeyInfo?
@id? -> %xs:ID
@language? -> %xs:NMTOKENS
@signed? -> %xs:token
;
9501
9502
9503
9504
9505
9506
9507
9508
9509
9510
Inquiry -> %is:InquiryType
%InquiryType:
is:Help?
is:Select*
is:Confirm* -> %is:InquiryElementType
is:Text*
@id?
-> %xs:ID
@title?
-> %xs:string
;
9511
9512
9513
9514
9515
9516
9517
Help -> %is:HelpType
%HelpType:
@link? -> %xs:anyURI
@moreLink? -> %xs:anyURI
;
9518
9519
Hint
-> %xs:string
9520
9521
9522
Select -> %is:SelectType
%SelectType: base(is:InquiryElementType)
January 29, 2011
is:Item{2,unbounded}:
is:Hint?
@value -> %xs:NMTOKEN
;
@multiple? -> %xs:boolean
;
9523
9524
9525
9526
9527
9528
9529
default (false)
9530
9531
9532
9533
9534
9535
9536
Text -> %is:TextType
%TextType: base(is:InquiryElementType)
@minChars? -> %xs:integer
@maxChars? -> %xs:integer
@format? -> %xs:string
;
9537
9538
9539
9540
9541
9542
9543
9544
%InquiryElementType:
is:Help?
is:Hint?
is:Label? -> %xs:normalizedString
is:Value? -> %xs:normalizedString
@name -> %xs:ID
;
9545
9546
9547
9548
9549
9550
9551
InteractionResponse -> %is:InteractionResponseType
%InteractionResponseType:
lu:Status
is:InteractionStatement* -> %is:InteractionStatementType
is:Parameter* -> %is:ParameterType
;
9552
9553
9554
9555
9556
%InteractionStatementType:
is:Inquiry+
ds:Signature
;
9557
9558
9559
9560
9561
%ParameterType:
@name -> %xs:ID
@value -> %xs:string
;
9562
9563
#EOF
9564
9565
9566
9567
9568
9569
9570
9571
41.5.7
#
#
#
#
#
#
id-dap (dap)
id-dap.sg -- Authorative ID-DAP 1.0 Service Schema
Author: Sampo Kellomaki ([email protected])
http://www.w3.org/2001/03/webdata/xsv
$Id: id-dap.sg,v 1.2 2007-06-19 15:17:04 sampo Exp $
This schema reflects Liberty ID Directory Access Protocol,
version 1.0-07 of 11.10.2006
9572
9573
target(dap,
January 29, 2011
urn:liberty:id-sis-dap:2006-08:dst-2.1)
9574
9575
9576
import(dst,
import(subs,
import(lu,
urn:liberty:dst:2006-08,
urn:liberty:ssos:2006-08,
urn:liberty:util:2006-08,
liberty-idwsf-dst-v2.1.xsd)
liberty-idwsf-subs-v1.0.xsd)
liberty-idwsf-utility-v2.0.xsd)
9577
9578
9579
9580
9581
9582
9583
9584
9585
9586
9587
Create
CreateResponse
Query
QueryResponse
Modify
ModifyResponse
Delete
DeleteResponse
Notify
NotifyResponse
->
->
->
->
->
->
->
->
->
->
%dap:CreateType
%dap:CreateResponseType
%dap:QueryType
%dap:QueryResponseType
%dap:ModifyType
%dap:ModifyResponseType
%dap:DeleteType
%dap:DeleteResponseType
%dap:NotifyType
%dap:NotifyResponseType
9588
9589
9590
9591
9592
9593
9594
9595
9596
9597
9598
%SelectType:
dap:dn?
dap:filter?
@scope?
@sizelimit?
@timelimit?
@attributes?
@typesonly?
@derefaliases?
;
->
->
->
->
->
->
-> %xs:string
-> %xs:string
%xs:integer default(0)
%xs:string
%xs:boolean default(false)
9599
9600
9601
9602
9603
%TestOpType:
%SortType:
%TriggerType:
%AggregationType:
base(dap:SelectType) ;
base(xs:string) ;
base(xs:string) ;
base(xs:string) ;
9604
9605
9606
9607
9608
%AppDataType:
dap:LDIF?
dap:Subscription?
;
9609
9610
9611
9612
LDIF: base(xs:string)
&@dst:localizedLeafAttributes
;
9613
9614
9615
9616
9617
9618
%CreateType:
dap:Subscription*
dap:CreateItem+
dap:ResultQuery*
;
base(dst:RequestType)
9619
9620
9621
9622
9623
9624
CreateItem
-> %dap:CreateItemType
%CreateItemType:
dap:NewData?
&@dst:CreateItemAttributeGroup
;
9625
9626
NewData
-> %dap:AppDataType
9627
January 29, 2011
9628
9629
9630
9631
%CreateResponseType:
%DataResponseType:
dap:ItemData*
;
base(dap:DataResponseType) ;
base(dst:DataResponseBaseType)
9632
9633
9634
9635
9636
9637
%QueryType:
dap:TestItem*
dap:QueryItem*
dap:Subscription*
;
9638
9639
9640
9641
9642
TestItem
%TestItemType:
dap:TestOp?
;
-> %dap:TestItemType
base(dst:TestItemBaseType)
-> %dap:TestOpType
9643
9644
9645
9646
9647
QueryItem
-> %dap:QueryItemType
%QueryItemType: base(dap:ResultQueryType)
&@dst:PaginationAttributeGroup
;
9648
9649
9650
9651
9652
%QueryResponseType:
dst:TestResult*
dap:Data*
;
base(dst:DataResponseBaseType)
9653
9654
9655
9656
9657
Data
-> %dap:DataType
%DataType:
base(dap:ItemDataType)
&@dst:PaginationResponseAttributeGroup
;
9658
9659
9660
9661
9662
9663
%ModifyType:
dap:Subscription*
dap:ModifyItem+
dap:ResultQuery*
;
9664
9665
9666
9667
9668
9669
9670
ModifyItem
-> %dap:ModifyItemType
%ModifyItemType:
dap:Select?
dap:NewData?
&@dst:ModifyItemAttributeGroup
;
9671
9672
%ModifyResponseType:
base(dap:DataResponseType) ;
%DeleteType:
dap:DeleteItem+
;
DeleteItem
%DeleteItemType:
dap:Select?
;
-> %dap:DeleteItemType
base(dst:DeleteItemBaseType)
9673
9674
9675
9676
9677
9678
9679
9680
9681
January 29, 2011
9682
9683
%DeleteResponseType:
base(lu:ResponseType) ;
Select
-> %dap:SelectType
ResultQuery
%ResultQueryType:
dap:Select?
dap:Sort?
;
-> %dap:ResultQueryType
base(dst:ResultQueryBaseType)
9684
9685
9686
9687
9688
9689
9690
9691
-> %dap:SortType
9692
9693
9694
9695
9696
ItemData
-> %dap:ItemDataType
%ItemDataType:
base(dap:AppDataType)
&@dst:ItemDataAttributeGroup
;
9697
9698
9699
9700
9701
9702
9703
Subscription
%SubscriptionType:
dap:ResultQuery*
dap:Aggregation?
dap:Trigger?
;
-> %dap:SubscriptionType
base(subs:SubscriptionType)
-> %dap:AggregationType
-> %dap:TriggerType
9704
9705
9706
9707
9708
%NotifyType:
dap:Notification*
&@subs:NotifyAttributeGroup
;
9709
9710
9711
9712
9713
Notification
%NotificationType:
dap:ItemData*
;
-> %dap:NotificationType
base(subs:NotificationType)
%NotifyResponseType:
base(subs:NotifyResponseType) ;
9714
9715
9716
9717
#EOF
9718
9719
9720
9721
9722
41.5.8
liberty-idwsf-subs-v1.0 (subs)
# zxid/sg/liberty-idwsf-subs-v1.0.sg
# $Id: liberty-idwsf-subs-v1.0.sg,v 1.2 2009-09-05 02:23:41 sampo Exp $
9723
9724
9725
target(subs, urn:liberty:ssos:2006-08)
import(lu, urn:liberty:util:2006-08,liberty-idwsf-utility-v2.0.xsd)
9726
9727
9728
9729
9730
9731
9732
%SubscriptionType:
subs:RefItem*
lu:Extension*
@subscriptionID
-> %lu:IDType
@notifyToRef
-> %xs:anyURI
@adminNotifyToRef? -> %xs:anyURI
January 29, 2011
9733
9734
9735
9736
9737
@starts?
@expires?
@id?
@includeData?:
;
-> %xs:dateTime
-> %xs:dateTime
-> %xs:ID
enum( Yes No YesWithCommonAttributes ) ;
9738
9739
9740
9741
9742
9743
RefItem -> %subs:RefItemType
%RefItemType:
@subscriptionID?
-> %lu:IDType
@lu:itemIDRef
;
9744
9745
9746
9747
&@NotifyAttributeGroup:
@timeStamp?
-> %xs:dateTime
;
9748
9749
9750
9751
9752
9753
9754
9755
%NotificationType:
lu:TestResult*
@id?
@subscriptionID
@expires?
@endReason?
;
->
->
->
->
%xs:ID
%lu:IDType
%xs:dateTime
%xs:anyURI
9756
9757
%NotifyResponseType:
base(lu:ResponseType) ;
9758
9759
#EOF
9760
9761
9762
9763
9764
41.5.9
liberty-idwsf-dst-v2.1 (dst)
# zxid/sg/liberty-idwsf-dst-v2.1.sg
# $Id: liberty-idwsf-dst-v2.1.sg,v 1.2 2009-09-05 02:23:41 sampo Exp $
9765
9766
9767
9768
9769
target(dst, urn:liberty:dst:2006-08)
import(xml, http://www.w3.org/XML/1998/namespace, http://www.w3.org/2001/xml\
.xsd)
9770
9771
9772
9773
9774
9775
9776
9777
9778
9779
@id -> %lu:IDType
@modificationTime -> %xs:dateTime
&@commonAttributes:
@dst:id?
@dst:modificationTime?
;
@ACC -> %xs:anyURI
@ACCTime -> %xs:dateTime
@modifier -> %xs:string
9780
9781
9782
9783
&@leafAttributes:
&@dst:commonAttributes
@dst:ACC?
January 29, 2011
9784
9785
9786
@dst:ACCTime?
@dst:modifier?
;
9787
9788
@script
-> %xs:anyURI
9789
9790
9791
9792
9793
9794
&@localizedLeafAttributes:
&@dst:leafAttributes
@xml:lang
@dst:script?
;
9795
9796
9797
@refreshOnOrAfter
@destroyOnOrAfter
-> %xs:dateTime
-> %xs:dateTime
9798
9799
9800
9801
%DSTLocalizedString: base(xs:string)
&@dst:localizedLeafAttributes
;
9802
9803
9804
9805
%DSTString: base(xs:string)
;
9806
9807
9808
9809
%DSTInteger: base(xs:integer)
;
9810
9811
9812
9813
%DSTURI: base(xs:anyURI)
;
9814
9815
9816
9817
%DSTDate: base(xs:date)
;
9818
9819
9820
9821
%DSTMonthDay: base(xs:gMonthDay)
;
9822
9823
9824
@itemID
-> %lu:IDType
9825
9826
9827
9828
9829
9830
%RequestType:
lu:Extension*
@dst:itemID?
@any
;
9831
9832
9833
9834
9835
9836
9837
%ResponseType:
lu:Status
lu:Extension*
@dst:itemIDRef?
@any
;
January 29, 2011
9838
9839
9840
9841
%DataResponseBaseType: base(dst:ResponseType)
@timeStamp? -> %xs:dateTime
;
9842
9843
9844
9845
9846
ChangeFormat: enum( ChangedElements CurrentElements ) ;
@changeFormat: enum( ChangedElements CurrentElements All ) ;
@objectType -> %xs:NCName
@predefined -> %xs:string
9847
9848
9849
9850
9851
&@selectQualif:
@dst:objectType?
@dst:predefined?
;
9852
9853
9854
9855
9856
9857
9858
9859
9860
9861
%ResultQueryBaseType:
dst:ChangeFormat{0,2}
&@dst:selectQualif
@dst:itemIDRef?
@contingency? -> %xs:boolean
@includeCommonAttributes? -> %xs:boolean
@changedSince? -> %xs:dateTime
@dst:itemID?
;
default (0)
9862
9863
9864
9865
9866
9867
&@ItemDataAttributeGroup:
@dst:itemIDRef?
@notSorted?: enum( Now Never ) ;
@dst:changeFormat?
;
9868
9869
9870
9871
9872
9873
%TestItemBaseType:
&@dst:selectQualif
@id? -> %xs:ID
@dst:itemID?
;
9874
9875
9876
9877
9878
TestResult
%TestResultType:
@dst:itemIDRef
;
-> %dst:TestResultType
base(xs:boolean)
9879
9880
9881
9882
9883
9884
9885
&@PaginationAttributeGroup:
@count? -> %xs:nonNegativeInteger
@offset? -> %xs:nonNegativeInteger default (0)
@setID? -> %lu:IDType
@setReq?: enum( Static DeleteSet ) ;
;
9886
9887
9888
9889
9890
9891
&@PaginationResponseAttributeGroup:
@remaining? -> %xs:integer
@nextOffset? -> %xs:nonNegativeInteger
@setID? -> %lu:IDType
;
January 29, 2011
default (0)
9892
9893
9894
9895
9896
9897
&@CreateItemAttributeGroup:
@dst:objectType?
@id? -> %xs:ID
@dst:itemID?
;
9898
9899
9900
9901
9902
9903
9904
9905
&@ModifyItemAttributeGroup:
&@dst:selectQualif
@notChangedSince? -> %xs:dateTime
@overrideAllowed? -> %xs:boolean default (0)
@id? -> %xs:ID
@dst:itemID?
;
9906
9907
9908
9909
9910
9911
9912
9913
%DeleteItemBaseType:
&@dst:selectQualif
@notChangedSince? -> %xs:dateTime
@id? -> %xs:ID
@dst:itemID?
;
%DeleteResponseType: base(dst:ResponseType) ;
9914
9915
#EOF
9916
9917
9918
9919
9920
9921
41.5.10
liberty-idwsf-idmapping-svc-v2.0 (im)
# zxid/sg/liberty-idwsf-idmapping-svc-v2.0.sg
# $Id: liberty-idwsf-idmapping-svc-v2.0.sg,v 1.2 2009-03-27 18:40:46 sampo E\
xp $
9922
9923
9924
9925
9926
target(im, urn:liberty:ims:2006-08)
import(sec, urn:liberty:security:2006-08, liberty-idwsf-security-mechanisms-\
v2.0.xsd)
9927
9928
9929
9930
9931
9932
9933
MappingInput -> %im:MappingInputType
%MappingInputType:
sec:TokenPolicy?
sec:Token?
@reqID? -> %lu:IDType
;
9934
9935
9936
9937
9938
9939
MappingOutput -> %im:MappingOutputType
%MappingOutputType:
sec:Token
@reqRef? -> %lu:IDReferenceType
;
9940
9941
9942
IdentityMappingRequest -> %im:IdentityMappingRequestType
%IdentityMappingRequestType:
January 29, 2011
9943
9944
9945
im:MappingInput+
@any
;
9946
9947
9948
9949
9950
9951
9952
IdentityMappingResponse -> %im:IdentityMappingResponseType
%IdentityMappingResponseType:
lu:Status
im:MappingOutput*
@any
;
9953
9954
#EOF
9955
9956
9957
9958
9959
9960
41.5.11
liberty-idwsf-people-service-v1.0 (ps)
# zxid/sg/liberty-idwsf-people-service-v1.0.sg
# $Id: liberty-idwsf-people-service-v1.0.sg,v 1.2 2009-09-05 02:23:41 sampo \
Exp $
9961
9962
9963
9964
9965
9966
9967
9968
9969
target(ps, urn:liberty:ps:2006-08)
import(lu,
urn:liberty:util:2006-08,liberty-idwsf-utility-v2.0.xsd)
import(im,
urn:liberty:ims:2006-08,liberty-idwsf-idmapping-svc-v2.0.xsd)
import(subs, urn:liberty:ssos:2006-08,liberty-idwsf-subs-v1.0.xsd)
import(sec, urn:liberty:security:2006-08,liberty-idwsf-security-mechanisms-\
v2.0.xsd)
#import(sp, urn:oasis:names:tc:SAML:2.0:protocol,saml-schema-protocol-2.0.x\
sd)
9970
9971
9972
9973
9974
%LocalizedDisplayNameType: base(xs:string)
@Locale
-> %xs:language
@IsDefault? -> %xs:boolean
;
9975
9976
9977
9978
%TagType: base(xs:string)
@Ref
-> %xs:anyURI
;
9979
9980
9981
9982
ObjectID -> %ps:ObjectIDType
TargetObjectID -> %ps:ObjectIDType
%ObjectIDType: base(xs:anyURI) ;
9983
9984
9985
9986
9987
9988
9989
9990
9991
9992
9993
Object -> %ps:ObjectType
%ObjectType:
ps:ObjectID?
ps:DisplayName+
-> %ps:LocalizedDisplayNameType
ps:Tag?
-> %ps:TagType
ps:Object*
ps:ObjectRef*
-> %ps:ObjectIDType
@NodeType
-> %xs:anyURI
@CreatedDateTime?
-> %xs:dateTime
@ModifiedDateTime? -> %xs:dateTime
January 29, 2011
9994
;
9995
9996
9997
PStoSPRedirectURL -> %ps:PStoSPRedirectURLType
%PStoSPRedirectURLType: base(xs:anyURI) ;
9998
9999
10000
SPtoPSRedirectURL -> %ps:SPtoPSRedirectURLType
%SPtoPSRedirectURLType: base(xs:anyURI) ;
10001
10002
10003
QueryString -> %ps:QueryStringType
%QueryStringType: base(xs:string) ;
10004
10005
CreatePSObject: ;
10006
10007
10008
10009
@id
-> %xs:ID
;
10010
10011
10012
10013
10014
10015
%ResponseAbstractType:
lu:Status
@id
-> %xs:ID
@TimeStamp -> %xs:dateTime
;
10016
10017
10018
10019
10020
10021
10022
10023
10024
AddEntityRequest
-> %ps:AddEntityRequestType
%AddEntityRequestType: base(ps:RequestAbstractType)
ps:Object
ps:PStoSPRedirectURL?
ps:CreatePSObject?
ps:Subscription?
sec:TokenPolicy?
;
10025
10026
10027
10028
10029
10030
10031
AddEntityResponse
-> %ps:AddEntityResponseType
%AddEntityResponseType: base(ps:ResponseAbstractType)
ps:Object?
ps:SPtoPSRedirectURL?
ps:QueryString?
;
10032
10033
10034
10035
10036
10037
10038
10039
10040
AddKnownEntityRequest
-> %ps:AddKnownEntityRequestType
%AddKnownEntityRequestType: base(ps:RequestAbstractType)
ps:Object
sec:Token
ps:CreatePSObject?
ps:Subscription?
sec:TokenPolicy?
;
10041
10042
10043
10044
10045
10046
10047
AddKnownEntityResponse
-> %ps:AddKnownEntityResponseType
%AddKnownEntityResponseType: base(ps:ResponseAbstractType)
ps:Object?
ps:SPtoPSRedirectURL?
ps:QueryString?
;
January 29, 2011
10048
10049
10050
10051
10052
10053
AddCollectionRequest
-> %ps:AddCollectionRequestType
%AddCollectionRequestType: base(ps:RequestAbstractType)
ps:Object
ps:Subscription?
;
10054
10055
10056
10057
10058
AddCollectionResponse
-> %ps:AddCollectionResponseType
%AddCollectionResponseType: base(ps:ResponseAbstractType)
ps:Object?
;
10059
10060
10061
10062
10063
10064
10065
AddToCollectionRequest
-> %ps:AddToCollectionRequestType
%AddToCollectionRequestType: base(ps:RequestAbstractType)
ps:TargetObjectID
ps:ObjectID+
ps:Subscription?
;
10066
10067
AddToCollectionResponse -> %ps:ResponseAbstractType
10068
10069
10070
10071
10072
RemoveEntityRequest
-> %ps:RemoveEntityRequestType
%RemoveEntityRequestType: base(ps:RequestAbstractType)
ps:TargetObjectID+
;
10073
10074
RemoveEntityResponse -> %ps:ResponseAbstractType
10075
10076
10077
10078
10079
RemoveCollectionRequest -> %ps:RemoveCollectionRequestType
%RemoveCollectionRequestType: base(ps:RequestAbstractType)
ps:TargetObjectID+
;
10080
10081
RemoveCollectionResponse -> %ps:ResponseAbstractType
10082
10083
10084
10085
10086
10087
10088
RemoveFromCollectionRequest
-> %ps:RemoveFromCollectionRequestType
%RemoveFromCollectionRequestType: base(ps:RequestAbstractType)
ps:TargetObjectID
ps:ObjectID+
ps:Subscription?
;
10089
10090
RemoveFromCollectionResponse -> %ps:ResponseAbstractType
10091
10092
10093
10094
10095
10096
10097
10098
10099
ListMembersRequest
-> %ps:ListMembersRequestType
%ListMembersRequestType: base(ps:RequestAbstractType)
ps:TargetObjectID?
ps:Subscription?
@Structured? -> %xs:anyURI
@Offset? -> %xs:nonNegativeInteger default (0)
;
10100
10101
ListMembersResponse
January 29, 2011
-> %ps:ListMembersResponseType
10102
10103
10104
%ListMembersResponseType: base(ps:ResponseAbstractType)
ps:Object*
;
10105
10106
10107
10108
10109
10110
10111
10112
QueryObjectsRequest -> %ps:QueryObjectsRequestType
%QueryObjectsRequestType: base(ps:RequestAbstractType)
ps:Filter -> %xs:string
ps:Subscription?
@Offset? -> %xs:nonNegativeInteger default (0)
;
10113
10114
10115
10116
10117
QueryObjectsResponse -> %ps:QueryObjectsResponseType
%QueryObjectsResponseType: base(ps:ResponseAbstractType)
ps:Object*
;
10118
10119
10120
10121
10122
10123
GetObjectInfoRequest -> %ps:GetObjectInfoRequestType
%GetObjectInfoRequestType: base(ps:RequestAbstractType)
ps:TargetObjectID?
ps:Subscription?
;
10124
10125
10126
10127
10128
GetObjectInfoResponse -> %ps:GetObjectInfoResponseType
%GetObjectInfoResponseType: base(ps:ResponseAbstractType)
ps:Object?
;
10129
10130
10131
10132
10133
10134
SetObjectInfoRequest -> %ps:SetObjectInfoRequestType
%SetObjectInfoRequestType: base(ps:RequestAbstractType)
ps:Object+
ps:Subscription?
;
10135
10136
SetObjectInfoResponse -> %ps:ResponseAbstractType
10137
10138
10139
10140
10141
10142
10143
TestMembershipRequest -> %ps:TestMembershipRequestType
%TestMembershipRequestType: base(ps:RequestAbstractType)
ps:TargetObjectID?
sec:Token
ps:Subscription?
;
10144
10145
%ResultType: base(xs:boolean) ;
10146
10147
10148
10149
10150
TestMembershipResponse -> %ps:TestMembershipResponseType
%TestMembershipResponseType: base(ps:ResponseAbstractType)
ps:Result? -> %ps:ResultType
;
10151
10152
10153
10154
10155
ResolveIdentifierRequest -> %ps:ResolveIdentifierRequestType
%ResolveIdentifierRequestType: base(ps:RequestAbstractType)
ps:ResolveInput+
;
January 29, 2011
10156
10157
10158
10159
10160
ResolveInput -> %ps:ResolveInputType
%ResolveInputType: base(im:MappingInputType)
ps:TargetObjectID?
;
10161
10162
10163
10164
10165
ResolveIdentifierResponse -> %ps:ResolveIdentifierResponseType
%ResolveIdentifierResponseType: base(ps:ResponseAbstractType)
ps:ResolveOutput+
;
10166
10167
ResolveOutput -> %im:MappingOutputType
10168
10169
Subscription -> %subs:SubscriptionType
10170
10171
10172
10173
10174
Notification -> %ps:NotificationType
%NotificationType: base(subs:NotificationType)
ps:ItemData*
;
10175
10176
10177
10178
10179
ItemData -> %ps:ItemDataType
%ItemDataType:
ps:Object
;
10180
10181
10182
10183
10184
10185
10186
Notify -> %ps:NotifyType
%NotifyType: base(ps:RequestAbstractType)
ps:Notification*
&@subs:NotifyAttributeGroup
;
NotifyResponse -> %subs:NotifyResponseType
10187
10188
#EOF
10189
10190
10191
10192
10193
41.5.12
liberty-idwsf-authn-svc-v2.0 (as)
# zxid/sg/liberty-idwsf-people-service-v1.0.sg
# $Id: liberty-idwsf-authn-svc-v2.0.sg,v 1.2 2009-09-05 02:23:41 sampo Exp $
10194
10195
10196
10197
10198
10199
target(as,
import(a,
import(sp,
sd)
import(lu,
urn:liberty:sa:2006-08)
http://www.w3.org/2005/08/addressing,ws-addr-1.0.xsd)
urn:oasis:names:tc:SAML:2.0:protocol, saml-schema-protocol-2.0.x\
urn:liberty:util:2006-08, liberty-idwsf-utility-v2.0.xsd)
10200
10201
10202
10203
10204
10205
10206
SASLRequest:
as:Data?
as:Extensions?:
;
January 29, 2011
41.6. SOAP 1.1 PROCESSORS
@mechanism
-> %xs:string
@authzID?
-> %xs:string
@advisoryAuthnID? -> %xs:string
@any
;
10207
10208
10209
10210
10211
10212
10213
10214
10215
10216
10217
10218
10219
10220
SASLResponse:
lu:Status
as:PasswordTransforms?
as:Data?
@serverMechanism? -> %xs:string
@any
;
10221
10222
Data: base(xs:base64Binary) ;
10223
10224
10225
10226
10227
10228
10229
10230
10231
10232
PasswordTransforms:
as:Transform+:
as:Parameter*: base(xs:string)
@name -> %xs:string
;
@name -> %xs:anyURI
@any
;
;
10233
10234
#EOF
10235
10236
41.6
SOAP 1.1 Processors
10237
41.6.1
wsf-soap11 (e)
10238
10239
10240
10241
10242
10243
10244
10245
10246
10247
10248
10249
10250
10251
10252
10253
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
zxid/sg/wsf-soap11.sg
$Id: wsf-soap11.sg,v 1.15 2010-01-08 02:10:09 sampo Exp $
Heavily edited, 27.5.2006, Sampo Kellomaki ([email protected])
26.2.2007, merged saml20-soap11.sg and di-soap11.sg to only
one SOAP processor. --Sampo
3.3.2007, added XACML support --Sampo
22.11.2009, added TAS3 support --Sampo
Mega SOAP processor for Web Services and SSO Frameworks
Main purpose of this schema is to permit direct, one pass, parsing of
of SAML and WSF content in SOAP envelope. Thus relevant SOAP extension
points have been replaced with actual SAML and WSF elements.
When you add new SOAP messages, you need to add them here, to the body.
See also zxid/c/zx-e-data.h, which is generated.
10254
10255
target(e, http://schemas.xmlsoap.org/soap/envelope/)
January 29, 2011
10256
10257
10258
10259
10260
10261
10262
10263
10264
10265
10266
10267
10268
10269
10270
10271
10272
10273
10274
10275
10276
10277
10278
10279
10280
10281
10282
10283
10284
ns(xs,
http://www.w3.org/2001/XMLSchema)
ns(a,
ns(sbf,
urn:liberty:sb)
ns(b,
ns(b12,
ns(di,
urn:liberty:disco:2006-08)
ns(lu,
urn:liberty:util:2006-08)
ns(dap,
urn:liberty:id-sis-dap:2006-08:dst-2.1)
ns(ps,
urn:liberty:ps:2006-08)
ns(im,
urn:liberty:ims:2006-08)
ns(as,
urn:liberty:sa:2006-08)
ns(wsse, http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity\
-secext-1.0.xsd)
ns(xasp, urn:oasis:xacml:2.0:saml:protocol:schema:os)
ns(xaspcd1, urn:oasis:names:tc:xacml:2.0:profile:saml2.0:v2:schema:protocol:\
cd-01)
ns(mm7,
http://www.3gpp.org/ftp/Specs/archive/23_series/23.140/schema/REL-\
6-MM7-1-4)
ns(cb,
urn:liberty:id-sis-cb:2004-10)
ns(gl,
urn:liberty:id-sis-gl:2005-07)
ns(dp,
urn:liberty:dp:2006-12)
ns(pmm,
urn:liberty:pmm:2006-12)
ns(prov, urn:liberty:prov:2006-12)
ns(shps, urn:liberty:shps:2006-12)
ns(idp,
urn:liberty:idp:2006-12)
ns(idhrxml, urn:id-sis-idhrxml:2007-06:dst-2.1)
ns(demomed, urn:x-demo:me:2006-01)
ns(tas3, http://tas3.eu/tas3/200911/)
10285
10286
10287
10288
10289
10290
10291
10292
10293
Envelope -> %e:Envelope
%Envelope:
e:Header?
e:Body
@id? -> %xs:ID
any*
@any?
;
10294
10295
10296
10297
10298
10299
10300
10301
10302
10303
10304
10305
10306
10307
10308
10309
Header -> %e:Header
%Header:
paos:Request?
paos:Response?
ecp:Request?
ecp:Response?
ecp:RelayState?
sbf:Framework?
b:Sender?
a:MessageID?
wsse:Security?
tas3:Status?
a:RelatesTo?
a:ReplyTo?
a:From?
January 29, 2011
10310
10311
10312
10313
10314
10315
10316
10317
10318
10319
10320
10321
10322
10323
10324
10325
10326
10327
10328
10329
10330
10331
10332
10333
10334
10335
10336
a:FaultTo?
a:To?
a:Action?
a:ReferenceParameters?
b:Framework?
b:TargetIdentity?
b:CredentialsContext?
b:EndpointUpdate?
b:Timeout?
b:ProcessingContext?
b:Consent?
b:UsageDirective?
b:ApplicationEPR?
b:UserInteraction?
b:RedirectRequest?
b12:Correlation?
b12:Provider?
b12:ProcessingContext?
b12:Consent?
b12:UsageDirective?
mm7:TransactionID?
tas3:Credentials?
tas3:ESLPolicies?
@id? -> %xs:ID
any*
@any?
;
10337
10338
10339
10340
10341
10342
10343
10344
10345
10346
10347
10348
10349
10350
10351
10352
10353
10354
10355
10356
10357
10358
10359
10360
10361
10362
10363
Body -> %e:Body
%Body:
sp:ArtifactResolve?
sp:ArtifactResponse?
sp:ManageNameIDRequest?
sp:ManageNameIDResponse?
sp:LogoutRequest?
sp:LogoutResponse?
sp:NameIDMappingRequest?
sp:NameIDMappingResponse?
sp:AttributeQuery?
sp:AuthnQuery?
sp:AuthzDecisionQuery?
sp:AssertionIDRequest?
sp:Response?
sp:AuthnRequest?
sp11:Request?
sp11:Response?
ff12:RegisterNameIdentifierRequest?
ff12:RegisterNameIdentifierResponse?
ff12:FederationTerminationNotification?
ff12:LogoutRequest?
ff12:LogoutResponse?
ff12:NameIdentifierMappingRequest?
ff12:NameIdentifierMappingResponse?
xasp:XACMLAuthzDecisionQuery?
January 29, 2011
10364
10365
10366
10367
10368
10369
10370
10371
10372
10373
10374
10375
10376
10377
10378
10379
10380
10381
10382
10383
10384
10385
10386
10387
10388
10389
10390
10391
10392
10393
10394
10395
10396
10397
10398
10399
10400
10401
10402
10403
10404
10405
10406
10407
10408
10409
10410
10411
10412
10413
10414
10415
10416
10417
xasp:XACMLPolicyQuery?
xaspcd1:XACMLAuthzDecisionQuery?
xaspcd1:XACMLPolicyQuery?
xac:Request?
xac:Response?
di:Query?
di:QueryResponse?
di12:Query?
di12:QueryResponse?
di12:Modify?
di12:ModifyResponse?
e:Fault?
di:SvcMDAssociationAdd?
di:SvcMDAssociationAddResponse?
di:SvcMDAssociationDelete?
di:SvcMDAssociationDeleteResponse?
di:SvcMDAssociationQuery?
di:SvcMDAssociationQueryResponse?
di:SvcMDRegister?
di:SvcMDRegisterResponse?
di:SvcMDDelete?
di:SvcMDDeleteResponse?
di:SvcMDQuery?
di:SvcMDQueryResponse?
di:SvcMDReplace?
di:SvcMDReplaceResponse?
dap:Create?
dap:CreateResponse?
dap:Query?
dap:QueryResponse?
dap:Modify?
dap:ModifyResponse?
dap:Delete?
dap:DeleteResponse?
dap:Notify?
dap:NotifyResponse?
ps:AddEntityRequest?
ps:AddEntityResponse?
ps:AddKnownEntityRequest?
ps:AddKnownEntityResponse?
ps:AddCollectionRequest?
ps:AddCollectionResponse?
ps:AddToCollectionRequest?
ps:AddToCollectionResponse?
ps:RemoveEntityRequest?
ps:RemoveEntityResponse?
ps:RemoveCollectionRequest?
ps:RemoveCollectionResponse?
ps:RemoveFromCollectionRequest?
ps:RemoveFromCollectionResponse?
ps:ListMembersRequest?
ps:ListMembersResponse?
ps:QueryObjectsRequest?
ps:QueryObjectsResponse?
January 29, 2011
10418
10419
10420
10421
10422
10423
10424
10425
10426
10427
10428
10429
10430
10431
10432
10433
10434
10435
10436
10437
10438
10439
10440
10441
10442
10443
10444
10445
10446
10447
10448
10449
10450
10451
10452
10453
10454
10455
10456
10457
10458
10459
10460
10461
10462
10463
10464
10465
10466
10467
10468
10469
10470
10471
ps:GetObjectInfoRequest?
ps:GetObjectInfoResponse?
ps:SetObjectInfoRequest?
ps:SetObjectInfoResponse?
ps:TestMembershipRequest?
ps:TestMembershipResponse?
ps:ResolveIdentifierRequest?
ps:ResolveIdentifierResponse?
ps:Notify?
ps:NotifyResponse?
im:IdentityMappingRequest?
im:IdentityMappingResponse?
as:SASLRequest?
as:SASLResponse?
mm7:SubmitReq?
mm7:SubmitRsp?
mm7:DeliverReq?
mm7:DeliverRsp?
mm7:CancelReq?
mm7:CancelRsp?
mm7:ReplaceReq?
mm7:ReplaceRsp?
mm7:extendedCancelReq?
mm7:extendedCancelRsp?
mm7:extendedReplaceReq?
mm7:extendedReplaceRsp?
mm7:DeliveryReportReq?
mm7:DeliveryReportRsp?
mm7:ReadReplyReq?
mm7:ReadReplyRsp?
mm7:RSErrorRsp?
mm7:VASPErrorRsp?
mm7:QueryStatusReq?
mm7:QueryStatusRsp?
cb:Query?
cb:QueryResponse?
cb:Create?
cb:CreateResponse?
cb:Delete?
cb:DeleteResponse?
cb:Modify?
cb:ModifyResponse?
cb:Notify?
cb:NotifyResponse?
cb:ReportUsage?
cb:ReportUsageResponse?
gl:Query?
gl:QueryResponse?
gl:Create?
gl:CreateResponse?
gl:Delete?
gl:DeleteResponse?
gl:Modify?
gl:ModifyResponse?
January 29, 2011
10472
10473
10474
10475
10476
10477
10478
10479
10480
10481
10482
10483
10484
10485
10486
10487
10488
10489
10490
10491
10492
10493
10494
10495
10496
10497
10498
10499
10500
10501
10502
10503
10504
10505
10506
10507
10508
10509
10510
10511
10512
10513
10514
10515
10516
10517
10518
10519
10520
10521
10522
10523
10524
10525
gl:Notify?
gl:NotifyResponse?
demomed:StoreObjectRequest?
demomed:StoreObjectResponse?
demomed:GetObjectListRequest?
demomed:GetObjectListResponse?
demomed:GetObjectRequest?
demomed:GetObjectResponse?
demomed:DeleteObjectRequest?
demomed:DeleteObjectResponse?
pmm:Provision?
pmm:ProvisionResponse?
pmm:PMActivate?
pmm:PMActivateResponse?
pmm:PMDeactivate?
pmm:PMDeactivateResponse?
pmm:PMDelete?
pmm:PMDeleteResponse?
pmm:PMUpdate?
pmm:PMUpdateResponse?
pmm:PMGetStatus?
pmm:PMGetStatusResponse?
pmm:PMSetStatus?
pmm:PMSetStatusResponse?
prov:PMERegister?
prov:PMERegisterResponse?
prov:PMEUpload?
prov:PMEUploadResponse?
prov:PMEDownload?
prov:PMEDownloadResponse?
prov:PMEEnable?
prov:PMEEnableResponse?
prov:PMEDisable?
prov:PMEDisableResponse?
prov:PMEDelete?
prov:PMEDeleteResponse?
prov:PMEGetInfo?
prov:PMEGetInfoResponse?
prov:PMGetStatus?
prov:PMGetStatusResponse?
prov:PMSetStatus?
prov:PMSetStatusResponse?
prov:PMGetDescriptor?
prov:PMGetDescriptorResponse?
prov:PMActivate?
prov:PMActivateResponse?
prov:PMDeactivate?
prov:PMDeactivateResponse?
prov:PMRegisterDescriptor?
prov:PMRegisterDescriptorResponse?
prov:PMUpdate?
prov:PMUpdateResponse?
prov:PMDelete?
prov:PMDeleteResponse?
January 29, 2011
10526
10527
10528
10529
10530
10531
10532
10533
10534
10535
10536
10537
10538
10539
10540
10541
10542
10543
10544
10545
10546
10547
10548
10549
10550
10551
10552
10553
10554
10555
10556
10557
10558
10559
10560
10561
10562
10563
10564
10565
10566
10567
prov:Poll?
prov:PollResponse?
prov:UpdateEPR?
prov:UpdateEPRResponse?
idp:GetAssertion?
idp:GetAssertionResponse?
idp:GetProviderInfo?
idp:GetProviderInfoResponse?
idp:CreatedStatus?
idp:CreatedStatusResponse?
shps:Delete?
shps:DeleteResponse?
shps:GetStatus?
shps:GetStatusResponse?
shps:Query?
shps:QueryResponse?
shps:Invoke?
shps:InvokeResponse?
shps:QueryRegistered?
shps:QueryRegisteredResponse?
shps:Register?
shps:RegisterResponse?
shps:SetStatus?
shps:SetStatusResponse?
shps:Update?
shps:UpdateResponse?
shps:Poll?
shps:PollResponse?
shps:ProxyInvoke?
shps:ProxyInvokeResponse?
idhrxml:Create?
idhrxml:CreateResponse?
idhrxml:Query?
idhrxml:QueryResponse?
idhrxml:Modify?
idhrxml:ModifyResponse?
idhrxml:Delete?
idhrxml:DeleteResponse?
idhrxml:Notify?
idhrxml:NotifyResponse?
@id? -> %xs:ID
;
10568
10569
10570
10571
10572
10573
10574
@mustUnderstand -> %xs:boolean
@actor
-> %xs:anyURI
@encodingStyle -> %xs:anyURI
&@encodingStyle:
@e:encodingStyle?
;
10575
10576
10577
10578
10579
Fault -> %e:Fault
%Fault:
e:faultcode
-> %xs:QName
e:faultstring -> %xs:string
January 29, 2011
41.7. XML AND WEB SERVICES
CHAPTER
INFRASTRUCTURE
41. APPENDIX: SCHEMA GRAMMARS
10580
10581
10582
e:faultactor? -> %xs:anyURI
e:detail?
-> %e:detail
;
10583
10584
10585
10586
10587
10588
%detail:
lu:Status*
any*
@any
;
10589
10590
#EOF
10591
10592
41.7
XML and Web Services Infrastructure
10593
41.7.1
xmldsig-core (ds)
10594
10595
# xmldsig-core.sg -- Slightly edited after generation
# $Id: xmldsig-core.sg,v 1.3 2007-09-24 02:34:34 sampo Exp $
10596
10597
10598
10599
10600
target(ds, http://www.w3.org/2000/09/xmldsig#)
ns(exca, http://www.w3.org/2001/10/xml-exc-c14n#)
ns(xenc, http://www.w3.org/2001/04/xmlenc#)
10601
10602
%CryptoBinary:
base(xs:base64Binary) ;
10603
10604
10605
10606
10607
10608
10609
10610
10611
Signature -> %ds:SignatureType
%SignatureType:
ds:SignedInfo
ds:SignatureValue
ds:KeyInfo?
ds:Object*
@Id? -> %xs:ID
;
10612
10613
10614
10615
10616
SignatureValue -> %ds:SignatureValueType
%SignatureValueType: base(xs:base64Binary)
@Id? -> %xs:ID
;
10617
10618
10619
10620
10621
10622
10623
10624
SignedInfo -> %ds:SignedInfoType
%SignedInfoType:
ds:CanonicalizationMethod
ds:SignatureMethod
ds:Reference+
@Id? -> %xs:ID
;
10625
10626
10627
10628
CanonicalizationMethod -> %ds:CanonicalizationMethodType
%CanonicalizationMethodType:
any*
January 29, 2011
CHAPTER 41. APPENDIX:
41.7.
SCHEMA
XML AND
GRAMMARS
WEB SERVICES INFRASTRUCTURE
10629
10630
@Algorithm
;
-> %xs:anyURI
10631
10632
10633
10634
10635
10636
10637
SignatureMethod -> %ds:SignatureMethodType
%SignatureMethodType:
ds:HMACOutputLength? -> %ds:HMACOutputLengthType
any*
@Algorithm -> %xs:anyURI
;
10638
10639
10640
10641
10642
10643
10644
10645
10646
10647
Reference -> %ds:ReferenceType
%ReferenceType:
ds:Transforms?
ds:DigestMethod
ds:DigestValue
@Id? -> %xs:ID
@URI? -> %xs:anyURI
@Type? -> %xs:anyURI
;
10648
10649
10650
10651
10652
Transforms -> %ds:TransformsType
%TransformsType:
ds:Transform+
;
10653
10654
10655
10656
10657
10658
10659
10660
Transform -> %ds:TransformType
%TransformType:
ds:XPath* -> %xs:string
exca:InclusiveNamespaces?
any*
;
10661
10662
10663
10664
10665
10666
DigestMethod -> %ds:DigestMethodType
%DigestMethodType:
any*
;
10667
10668
10669
DigestValue -> %ds:DigestValueType
%DigestValueType: base(xs:base64Binary) ;
10670
10671
10672
10673
10674
10675
10676
10677
10678
10679
10680
10681
10682
KeyInfo -> %ds:KeyInfoType
%KeyInfoType:
ds:KeyName*
ds:KeyValue*
ds:RetrievalMethod*
ds:X509Data*
ds:PGPData*
ds:SPKIData*
ds:MgmtData*
xenc:EncryptedKey*
any*
@Id? -> %xs:ID
January 29, 2011
CHAPTER
INFRASTRUCTURE
10683
;
10684
10685
KeyName
-> %xs:string
10686
10687
MgmtData
-> %xs:string
10688
10689
10690
10691
10692
10693
10694
KeyValue -> %ds:KeyValueType
%KeyValueType:
ds:DSAKeyValue?
ds:RSAKeyValue?
any?
;
10695
10696
10697
10698
10699
10700
10701
RetrievalMethod -> %ds:RetrievalMethodType
%RetrievalMethodType:
ds:Transforms?
@URI? -> %xs:anyURI
;
10702
10703
10704
10705
10706
10707
10708
10709
10710
10711
X509Data -> %ds:X509DataType
%X509DataType:
ds:X509IssuerSerial* -> %ds:X509IssuerSerialType
ds:X509SKI* -> %xs:base64Binary
ds:X509SubjectName* -> %xs:string
ds:X509Certificate* -> %xs:base64Binary
ds:X509CRL* -> %xs:base64Binary
any*
;
10712
10713
10714
10715
10716
%X509IssuerSerialType:
ds:X509IssuerName -> %xs:string
ds:X509SerialNumber -> %xs:integer
;
10717
10718
10719
10720
10721
10722
10723
PGPData -> %ds:PGPDataType
%PGPDataType:
ds:PGPKeyID? -> %xs:base64Binary
ds:PGPKeyPacket? -> %xs:base64Binary
any*
;
10724
10725
10726
10727
10728
10729
SPKIData -> %ds:SPKIDataType
%SPKIDataType:
ds:SPKISexp -> %xs:base64Binary
any?
;
10730
10731
10732
10733
10734
10735
10736
Object -> %ds:ObjectType
%ObjectType:
@Id? -> %xs:ID
@MimeType? -> %xs:string
@Encoding? -> %xs:anyURI
January 29, 2011
41.7.
SCHEMA
XML AND
GRAMMARS
10737
;
10738
10739
10740
10741
10742
10743
Manifest -> %ds:ManifestType
%ManifestType:
ds:Reference+
@Id? -> %xs:ID
;
10744
10745
10746
10747
10748
10749
SignatureProperties -> %ds:SignaturePropertiesType
%SignaturePropertiesType:
ds:SignatureProperty+
@Id? -> %xs:ID
;
10750
10751
10752
10753
10754
10755
10756
SignatureProperty -> %ds:SignaturePropertyType
%SignaturePropertyType:
any+
@Target -> %xs:anyURI
@Id? -> %xs:ID
;
10757
10758
%HMACOutputLengthType:
base(xs:integer) ;
10759
10760
10761
10762
10763
10764
10765
10766
10767
10768
10769
DSAKeyValue -> %ds:DSAKeyValueType
%DSAKeyValueType:
ds:P? -> %ds:CryptoBinary
ds:Q? -> %ds:CryptoBinary
ds:G? -> %ds:CryptoBinary
ds:Y -> %ds:CryptoBinary
ds:J? -> %ds:CryptoBinary
ds:Seed? -> %ds:CryptoBinary
ds:PgenCounter? -> %ds:CryptoBinary
;
10770
10771
10772
10773
10774
10775
RSAKeyValue -> %ds:RSAKeyValueType
%RSAKeyValueType:
ds:Modulus -> %ds:CryptoBinary
ds:Exponent -> %ds:CryptoBinary
;
10776
10777
#EOF
10778
10779
10780
10781
41.7.2
xenc-schema (xenc)
# xenc-schema.sg -- Slightly edited after generation
# $Id: xenc-schema.sg,v 1.2 2007-09-24 02:34:34 sampo Exp $
10782
10783
10784
10785
10786
target(xenc,http://www.w3.org/2001/04/xmlenc#)
10787
January 29, 2011
CHAPTER
INFRASTRUCTURE
10788
10789
10790
10791
10792
10793
10794
10795
10796
10797
%EncryptedType:
xenc:EncryptionMethod? -> %xenc:EncryptionMethodType
ds:KeyInfo?
xenc:CipherData
xenc:EncryptionProperties?
@Id? -> %xs:ID
@MimeType? -> %xs:string
@Encoding? -> %xs:anyURI
;
10798
10799
10800
10801
10802
10803
10804
%EncryptionMethodType:
xenc:KeySize? -> %xenc:KeySizeType
xenc:OAEPparams? -> %xs:base64Binary
any*
;
10805
10806
%KeySizeType:
base(xs:integer) ;
10807
10808
10809
10810
10811
10812
CipherData -> %xenc:CipherDataType
%CipherDataType:
xenc:CipherValue? -> %xs:base64Binary
xenc:CipherReference?
;
10813
10814
10815
10816
10817
10818
CipherReference -> %xenc:CipherReferenceType
%CipherReferenceType:
xenc:Transforms? -> %xenc:TransformsType
@URI -> %xs:anyURI
;
10819
10820
10821
10822
%TransformsType:
ds:Transform+
;
10823
10824
10825
EncryptedData -> %xenc:EncryptedDataType
%EncryptedDataType: base(xenc:EncryptedType) ;
10826
10827
10828
10829
10830
10831
10832
EncryptedKey -> %xenc:EncryptedKeyType
%EncryptedKeyType: base(xenc:EncryptedType)
xenc:ReferenceList?
xenc:CarriedKeyName? -> %xs:string
@Recipient? -> %xs:string
;
10833
10834
10835
10836
10837
10838
10839
10840
10841
AgreementMethod -> %xenc:AgreementMethodType
%AgreementMethodType:
xenc:KA-Nonce? -> %xs:base64Binary
any*
xenc:OriginatorKeyInfo? -> %ds:KeyInfoType
xenc:RecipientKeyInfo? -> %ds:KeyInfoType
;
January 29, 2011
41.7.
SCHEMA
XML AND
GRAMMARS
10842
10843
10844
10845
10846
ReferenceList:
xenc:DataReference? -> %xenc:ReferenceType
xenc:KeyReference? -> %xenc:ReferenceType
;
10847
10848
10849
10850
10851
%ReferenceType:
any*
@URI -> %xs:anyURI
;
10852
10853
10854
10855
10856
10857
EncryptionProperties -> %xenc:EncryptionPropertiesType
%EncryptionPropertiesType:
xenc:EncryptionProperty+
@Id? -> %xs:ID
;
10858
10859
10860
10861
10862
10863
10864
10865
EncryptionProperty -> %xenc:EncryptionPropertyType
%EncryptionPropertyType:
any*
@Target? -> %xs:anyURI
@Id? -> %xs:ID
@any?
;
10866
10867
#EOF
10868
10869
10870
10871
10872
10873
41.7.3
#
#
#
#
ws-addr-1.0 (a)
zxid/sg/ws-addr-1.0.sg
6.2.2007, Added Discovery specifics to the Metadata --Sampo
$Id: ws-addr-1.0.sg,v 1.9 2007-09-30 05:10:03 sampo Exp $
10874
10875
10876
10877
10878
10879
10880
10881
10882
10883
10884
target(a, http://www.w3.org/2005/08/addressing)
#t arget(a, http://schemas.xmlsoap.org/ws/2004/08/addressing) # used by WS \
Federation?
import(di, urn:liberty:disco:2006-08, liberty-idwsf-disco-svc-v2.0.xsd)
import(e,
import(wsu, http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecuri\
ty-utility-1.0.xsd,wss-util-1.0.xsd)
import(tas3, http://tas3.eu/tas3/200911/)
ns(sbf,
urn:liberty:sb)
ns(b,
10885
10886
10887
10888
10889
10890
10891
10892
&@hdrs:
@wsu:Id?
@e:mustUnderstand?
@e:actor?
@id? -> %xs:anyURI
@ID? -> %xs:anyURI
;
January 29, 2011
CHAPTER
INFRASTRUCTURE
10893
10894
10895
10896
10897
10898
10899
10900
10901
10902
10903
EndpointReference -> %a:EndpointReferenceType
%EndpointReferenceType:
a:Address -> %a:AttributedURIType
a:ReferenceParameters?
a:Metadata?
@notOnOrAfter? -> %xs:dateTime
# Added by Sampo
&@a:hdrs
# Added by Sampo
@any
;
10904
10905
10906
10907
10908
10909
10910
10911
ReferenceParameters -> %a:ReferenceParametersType
%ReferenceParametersType:
b:TargetIdentity*
&@a:hdrs
# Added by Sampo
@any
;
10912
10913
10914
10915
10916
10917
10918
10919
10920
10921
10922
10923
Metadata -> %a:MetadataType
%MetadataType:
sbf:Framework?
di:Abstract?
di:ProviderID?
di:ServiceType?
di:SecurityContext?
tas3:Trust?
@any
;
10924
10925
MessageID
-> %a:AttributedURIType
10926
10927
10928
10929
10930
10931
10932
10933
RelatesTo -> %a:RelatesToType
%RelatesToType: base(xs:anyURI)
@RelationshipType? -> %a:RelationshipTypeOpenEnum
w3.org/2005/08/addressing/reply)
&@a:hdrs
# Added by Sampo
@any
;
# default (http://www.\
10934
10935
10936
%RelationshipTypeOpenEnum: union(a:RelationshipType xs:anyURI) ;
%RelationshipType: enum( http://www.w3.org/2005/08/addressing/reply ) ;
10937
10938
10939
10940
10941
10942
ReplyTo -> %a:EndpointReferenceType
From -> %a:EndpointReferenceType
FaultTo -> %a:EndpointReferenceType
To -> %a:AttributedURIType
Action -> %a:AttributedURIType
10943
10944
10945
10946
%AttributedURIType: base(xs:anyURI)
&@a:hdrs
# Added by Sampo
@any
January 29, 2011
41.7.
SCHEMA
XML AND
GRAMMARS
10947
;
10948
10949
@IsReferenceParameter
-> %xs:boolean
10950
10951
10952
%FaultCodesOpenEnumType:
;
union(a:FaultCodesType xs:QName)
10953
10954
10955
10956
10957
%FaultCodesType: enum( a:InvalidAddressingHeader a:InvalidAddress a:Invalid\
EPR a:InvalidCardinality a:MissingAddressInEPR a:DuplicateMessageID a:Action\
Mismatch a:MessageAddressingHeaderRequired a:DestinationUnreachable a:Action\
NotSupported a:EndpointUnavailable ) ;
10958
10959
RetryAfter
-> %a:AttributedUnsignedLongType
10960
10961
10962
10963
10964
%AttributedUnsignedLongType: base(xs:unsignedLong)
&@a:hdrs
# Added by Sampo
@any
;
10965
10966
ProblemHeaderQName -> %a:AttributedQNameType
10967
10968
10969
10970
10971
%AttributedQNameType: base(xs:QName)
&@a:hdrs
# Added by Sampo
@any
;
10972
10973
ProblemHeader
-> %a:AttributedAnyType
10974
10975
10976
10977
10978
10979
%AttributedAnyType:
&@a:hdrs
# Added by Sampo
@any
;
10980
10981
ProblemURI
-> %a:AttributedURIType
10982
10983
10984
10985
10986
10987
10988
10989
ProblemAction -> %a:ProblemActionType
%ProblemActionType:
a:Action?
a:SoapAction? -> %xs:anyURI
&@a:hdrs
# Added by Sampo
@any
;
10990
10991
#EOF
10992
10993
10994
10995
10996
41.7.4
wss-secext-1.0 (wsse)
# zxid/sg/wss-secext-1.0.sg
# $Id: wss-secext-1.0.sg,v 1.6 2009-11-20 20:27:13 sampo Exp $
10997
January 29, 2011
CHAPTER
INFRASTRUCTURE
10998
10999
11000
11001
11002
11003
11004
11005
11006
11007
11008
11009
11010
11011
target(wsse, http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecur\
ity-secext-1.0.xsd)
import(wsu, http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecur\
ity-utility-1.0.xsd,wss-util-1.0.xsd)
import(xml, http://www.w3.org/XML/1998/namespace,http://www.w3.org/2001/xml\
.xsd)
import(ds,
http://www.w3.org/2000/09/xmldsig#,http://www.w3.org/TR/2002/RE\
C-xmldsig-core-20020212/xmldsig-core-schema.xsd)
import(e,
import(sa11, urn:oasis:names:tc:SAML:1.0:assertion)
import(sa,
import(ff12, urn:liberty:iff:2003-08)
import(sec, urn:liberty:security:2006-08)
ns(xs,
http://www.w3.org/2001/XMLSchema)
11012
11013
11014
11015
11016
11017
&@header:
@wsu:Id?
@e:mustUnderstand?
@e:actor?
;
11018
11019
11020
11021
11022
11023
11024
11025
11026
11027
11028
%AttributedString: base(xs:string)
@wsu:Id?
@any
;
%PasswordString: base(wsse:AttributedString)
;
%EncodedString: base(wsse:AttributedString)
@EncodingType? -> %xs:anyURI
;
11029
11030
11031
11032
11033
11034
11035
%UsernameTokenType:
wsse:Username -> %wsse:AttributedString
@wsu:Id?
@any
;
11036
11037
11038
11039
%BinarySecurityTokenType: base(wsse:EncodedString)
@ValueType? -> %xs:anyURI
;
11040
11041
11042
11043
%KeyIdentifierType: base(wsse:EncodedString)
;
11044
11045
11046
%tUsage: xs:anyURI* ;
@Usage
-> %wsse:tUsage
11047
11048
11049
11050
11051
%ReferenceType:
@URI? -> %xs:anyURI
@any
January 29, 2011
41.7.
SCHEMA
XML AND
GRAMMARS
11052
;
11053
11054
11055
11056
11057
11058
%EmbeddedType:
@any
;
11059
11060
11061
11062
11063
11064
11065
11066
%SecurityTokenReferenceType:
wsse:KeyIdentifier?
@wsu:Id?
@wsse:Usage?
@any
;
11067
11068
11069
11070
11071
11072
11073
11074
11075
11076
11077
11078
11079
11080
11081
11082
%SecurityHeaderType:
ds:Signature?
sa:Assertion?
sa11:Assertion?
ff12:Assertion?
#sec:Token? assertion is used directly
wsse:BinarySecurityToken?
# Useful for X509 and binary bearer sec me\
chs
wsse:SecurityTokenReference?
# Useful for SAML bearer sec mech
wsu:Timestamp?
&@wsse:header
@any
;
11083
11084
11085
11086
11087
%TransformationParametersType:
@any
;
11088
11089
11090
11091
11092
11093
11094
11095
11096
11097
11098
UsernameToken -> %wsse:UsernameTokenType
BinarySecurityToken -> %wsse:BinarySecurityTokenType
Reference -> %wsse:ReferenceType
Embedded -> %wsse:EmbeddedType
KeyIdentifier -> %wsse:KeyIdentifierType
SecurityTokenReference
-> %wsse:SecurityTokenReferenceType
Security -> %wsse:SecurityHeaderType
TransformationParameters -> %wsse:TransformationParametersType
Password -> %wsse:PasswordString
Nonce
-> %wsse:EncodedString
11099
11100
11101
11102
%FaultcodeEnum: enum( wsse:UnsupportedSecurityToken wsse:UnsupportedAlgorit\
hm wsse:InvalidSecurity wsse:InvalidSecurityToken wsse:FailedAuthentication \
wsse:FailedCheck wsse:SecurityTokenUnavailable ) ;
11103
11104
# EOF
11105
January 29, 2011
CHAPTER
INFRASTRUCTURE
11106
11107
11108
11109
41.7.5
wss-util-1.0 (wsu)
# zxid/sg/wss-util-1.0.sg
# $Id: wss-util-1.0.sg,v 1.2 2007-09-30 05:10:03 sampo Exp $
11110
11111
11112
11113
target(wsu, http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecuri\
ty-utility-1.0.xsd)
11114
11115
%tTimestampFault:
enum( wsu:MessageExpired ) ;
11116
11117
@Id
-> %xs:ID
11118
11119
11120
11121
11122
11123
11124
&@commonAtts:
@wsu:Id?
@id? -> %xs:anyURI
@ID? -> %xs:anyURI
@any
;
11125
11126
11127
11128
%AttributedDateTime:
&@wsu:commonAtts
;
base(xs:string)
11129
11130
11131
11132
%AttributedURI: base(xs:anyURI)
&@wsu:commonAtts
;
11133
11134
11135
11136
11137
11138
11139
%TimestampType:
wsu:Created?
wsu:Expires?
any* ns(##other)
&@wsu:commonAtts
;
processContents(lax)
11140
11141
11142
11143
Timestamp -> %wsu:TimestampType
Expires
-> %wsu:AttributedDateTime
Created
-> %wsu:AttributedDateTime
11144
11145
#EOF
11146
January 29, 2011
11147
11148
11149
Chapter 42
Appendix: Some Example XML
Blobs
11152
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.
11153
42.1
11150
11151
11154
SAML 2.0 Artifact Response with SAML 2.0 SSO
Assertion and Two Bootstraps
11155
This example corresponds to t/sso-w-bootstraps.xml in the distribution.
11156
Both bootstraps illustrate SAML assertion as bearer token.
11157
11158
11159
11160
11161
<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>
11162
11163
11164
11165
11166
11167
11168
11169
11170
11171
11172
11173
11174
<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"/></>
11175
11176
<sp:Response
329
42.1. SAML 2.0 ARTIFACT RESPONSE WITH SAML 2.0 SSO ASSERTION
AND TWO BOOTSTRAPS
CHAPTER 42. APPENDIX: SOME EXAMPLE XML BLOBS
11177
11178
11179
11180
11181
11182
11183
11184
11185
11186
11187
ID="RCCzu13z77SiSXqsFp1u1"
InResponseTo="NojFIIhxw"
Version="2.0">
<sa:Issuer
<sp:Status>
11188
11189
11190
11191
11192
11193
11194
11195
<sa:Assertion
ID="ASSE6bgfaV-sapQsAilXOvBu"
Version="2.0">
<sa:Issuer Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">
11196
11197
11198
11199
11200
11201
11202
11203
11204
11205
11206
11207
<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=</></>
11208
11209
11210
11211
11212
11213
11214
11215
11216
11217
<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"/></></>
11218
11219
11220
11221
11222
11223
<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</></></>
11224
11225
<sa:Advice>
11226
11227

11228
11229
11230
<sa:Assertion
ID="CREDOTGAkvhNoP1aiTq4bXBg"
January 29, 2011
AND TWO BOOTSTRAPS
11231
11232
11233
11234
11235
11236
11237
11238
11239
11240
11241
11242
11243
11244
11245
11246
11247
11248
11249
11250
11251
11252
11253
11254
11255
Version="2.0">
<sa:Issuer
<ds:SignedInfo>
<ds:Reference URI="#CREDOTGAkvhNoP1aiTq4bXBg">
<ds:Transforms>
<ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
<ds:DigestValue>dqq/28hw5eEv+ceFyiLImeJ1P8w=</></></>
<ds:SignatureValue>UKlEgHKQwuoCE=</></>
<sa:Subject>
<sa:NameID/> 
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:Audience>https://sp1.zxidsp.org:8443/zxidhlo?o=B</></></></></>
11256
11257
11258
11259
11260
11261
11262
<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</></></>
11263
11264
<sa:AttributeStatement>
11265
11266

11267
11268
11269
11270
11271
11272
11273
11274
11275
11276
11277
11278
11279
11280
11281
11282
<sa:Attribute
Name="cn"
NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
<sa:AttributeValue>Sue</></>

<sa:Attribute
Name="DiscoveryResourceOffering"
NameFormat="urn:liberty:disco:2003-08">
<sa:AttributeValue>
<disco:ResourceOffering
xmlns:disco="urn:liberty:disco:2003-08"
entryID="2">
<disco:ResourceID>
https://a-idp.liberty-iop.org/profiles/WSF1.1/RID-DISCO-sue</>
<disco:ServiceInstance>
January 29, 2011
AND TWO BOOTSTRAPS
<disco:ServiceType>urn:liberty:disco:2003-08</>
<disco:ProviderID>
<disco:Description>
<disco:SecurityMechID>urn:liberty:security:2005-02:TLS:Bearer</>
<disco:CredentialRef>CREDOTGAkvhNoP1aiTq4bXBg</>
<disco:Endpoint>
https://a-idp.liberty-iop.org:8881/DISCO-S</></></>
<disco:Abstract>Symlabs Discovery Service Team G</></></></>
11283
11284
11285
11286
11287
11288
11289
11290
11291
11292
11293

11294
11295
11296
11297
11298
11299
11300
11301
11302
11303
11304
11305
11306
11307
11308
11309
11310
11311
11312
11313
11314
11315
11316
11317
11318
11319
<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-wssecuritynotOnOrAfter="2007-02-10T07:37:42Z"
wsu:Id="EPRIDcjP8ObO9In47SDjO9b37">
<wsa:Address>
https://a-idp.liberty-iop.org:8881/DISCO-S</>
<wsa:Metadata>
<disco:Abstract
xmlns:disco="urn:liberty:disco:2006-08">SYMfiam Discovery Service</>
<sbf:Framework
xmlns:sbf="urn:liberty:sb"
version="2.0"/>
<disco:ProviderID
xmlns:disco="urn:liberty:disco:2006-08">
<disco:ServiceType
xmlns:disco="urn:liberty:disco:2006-08">urn:liberty:disco:2006-08</>
<disco:SecurityContext
xmlns:disco="urn:liberty:disco:2006-08">
<disco:SecurityMechID>urn:liberty:security:2005-02:TLS:Bearer</>
11320
<sec:Token
xmlns:sec="urn:liberty:security:2006-08"
usage="urn:liberty:security:tokenusage:2006-08:SecurityToken">
11321
11322
11323
11324
<sa:Assertion
ID="CREDV6ZBMyicmyvDq9pLIoSR"
Version="2.0">
<sa:Issuer Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">
<ds:SignedInfo>
<ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml<ds:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa
<ds:Reference URI="#CREDV6ZBMyicmyvDq9pLIoSR">
<ds:Transforms>
11325
11326
11327
11328
11329
11330
11331
11332
11333
11334
11335
11336
January 29, 2011
CHAPTER 42. APPENDIX: SOME
42.2. ID-WSF
EXAMPLE
2.0 XML
CALLBLOBS
WITH X509V3 SEC MECH
<ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signat
<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=</>
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:Audience>
https://a-idp.liberty-iop.org:8881/idp.xml</></></>
<sa:AuthnStatement
AuthnInstant="2007-02-10T05:37:42Z">
<sa:AuthnContext>
urn:oasis:names:tc:SAML:2.0:ac:classes:Password</></></></></></></></></></>
11337
11338
11339
11340
11341
11342
11343
11344
11345
11346
11347
11348
11349
11350
11351
11352
11353
11354
11355
11356
11357
11358
11359
11360
11361
11362
11363
11364
11365
11366
11367
11368
11369
11370
11371
11372
11373
11374
11375
11376
11377
11378
11379
11380
11381
11382
11383
11384
11385
11386
42.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: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">...</>
<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/0 1/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#Ba
MIIB9zCCAWSgAwIBAgIQ...</>
<ds:Signature xmlns:ds="http://www.w3.org/2000/09/x mldsig#">
<ds:SignedInfo>
<ds:Reference URI="#MID">...</>
<ds:Reference URI="#TO">...</>
<ds:Reference URI="#ACT">...</>
<ds:Reference URI="#TS">...</>
<ds:Reference URI="#X509">
January 29, 2011
42.3. ID-WSF 2.0 CALL
CHAPTER
WITH BEARER
42. APPENDIX:
(BINARY)
SOME
SECEXAMPLE
MECH
XML BLOBS
11387
11388
11389
11390
11391
11392
11393
11394
11395
<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
11396
• Signature that covers relevant SOAP headers and Body
11397
• Absence of any explicit identity token.
11403
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 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).
11404
42.3
11398
11399
11400
11401
11402
11405
11406
11407
11408
11409
11410
11411
11412
11413
11414
11415
11416
11417
11418
11419
11420
11421
11422
11423
11424
11425
11426
11427
11428
11429
11430
11431
11432
11433
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: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">...</>
<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-secur
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>
January 29, 2011
42.4. ID-WSF
SOME2.0
EXAMPLE
CALL WITH
XML
BEARER
BLOBS (SAML) SEC MECH
11434
11435
11436
11437
11438
11439
11440
11441
11442
11443
11444
11445
11446
11447
11448
11449
11450
11451
11452
11453
11454
11455
11456
11457
<ds:Reference URI="#BST">...</>
<ds:Reference URI="#BDY">
<ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1 "/>
<ds:DigestValue>YgGfS0pi56pu</></></>
...</></></>
<xx:Query/></></>
42.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: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>
<wsa:MessageID wsu:Id="MID">...</>
<wsu:Timestamp wsu:Id="TS">
<wsu:Created>2005-06-17T04:49:17Z</></>
11458
11459
11460
11461
11462
11463
11464
11465
11466
11467
11468
11469
11470
11471
11472
11473
11474
11475
11476
11477
11478
11479
11480
11481
11482
11483
<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/</>
<ds:Signature>...</>
<sa:Subject>
<sa:EncryptedID>
<xenc:EncryptedData>U2XTCNvRX7 Bl1NK182nmY00TEk==</>
<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>
urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</></></>
<sa:AttributeStatement>
<sa:EncryptedAttribute>
January 29, 2011
42.5. XACML 2.0 SAML
CHAPTER
PROFILE
42. SOAP
APPENDIX:
CALL SOME EXAMPLE XML BLOBS
<xenc:EncryptedData Type="http://www.w3.org/2001/04/xmlenc#Element">
mQEMAzRniWkAAAEH9RbzqXdgcX8fpEqSr1v4=</>
<xenc:EncryptedKey>...</></></></>
11484
11485
11486
11487
<wsse:SecurityTokenReference
xmlns:wsse11="..."
wsu:Id="STR1"
wsse11:TokenType="http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV2
<wsse:KeyIdentifier
ValueType="http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLID">
A7N123</></>
11488
11489
11490
11491
11492
11493
11494
11495
11496
11497
11498
11499
11500
11501
11502
11503
11504
11505
11506
11507
11508
11509
11510
<ds:Signature>
<ds:SignedInfo>
<ds:Reference URI="#STR1">
<ds:Transform Algorithm="...#STR-Transform">
<wsse:TransformationParameters>
<ds:CanonicalizationMethod Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010
<ds:Reference URI="#BDY"/></>
...</></></>
<xx:Query/></></>
*** is the reference above to wsse11:TokenType really correct?
11512
Note who 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.
11513
42.5
11511
11514
11515
11516
11517
11518
11519
11520
11521
11522
11523
11524
11525
11526
11527
11528
11529
11530
11531
XACML 2.0 SAML Profile SOAP Call
<e:Envelope xmlns:e="http://schemas.xmlsoap.org/soap/envelope/">
<e:Body>
<xasp:XACMLAuthzDecisionQuery
xmlns:xasp="urn:oasis:xacml:2.0:saml:protocol:schema:os"
ID="RX3eHFSEBW6-OnPG5sGV_EevU"
Version="2.0">
<sa:Issuer xmlns:sa="urn:oasis:names:tc:SAML:2.0:assertion">https://sp1.zxidsp.org:5443/prot
<ds:SignedInfo>
<ds:Reference URI="#RX3eHFSEBW6-OnPG5sGV_EevU">
<ds:Transforms>
<ds:DigestValue>F2r41OppQA2ZLsosLO6V9VNJ0J8=</></></>
January 29, 2011
CHAPTER 42. APPENDIX: SOME
42.5.
EXAMPLE
XACMLXML
2.0 SAML
BLOBS
PROFILE SOAP CALL
11532
11533
11534
11535
11536
11537
11538
11539
11540
11541
11542
11543
11544
11545
11546
11547
11548
11549
11550
11551
11552
11553
11554
11555
11556
11557
11558
11559
11560
11561
11562
11563
11564
11565
11566
11567
11568
11569
11570
11571
11572
11573
11574
11575
11576
<ds:SignatureValue>sAvByKH9--(snip)--HV+1oqcdUw=</></>
<xac:Request xmlns:xac="urn:oasis:names:tc:xacml:2.0:context:schema:os">
<xac:Subject>
<xac:Attribute
AttributeId="permisRole"
DataType="xs:string"
Issuer="https://idp.tas3.pt:8443/zxididp?o=B">
<xac:AttributeValue>guest</></>
<xac:Attribute
AttributeId="permisRole"
<xac:AttributeValue>jesterbester</></>
<xac:Attribute
AttributeId="urn:oasis:names:tc:xacml:1.0:subject:subject-id"
DataType="xs:string">
<xac:AttributeValue>FdGaMOmtJPfvK9dN64lWgKTOp</></></>
<xac:Resource>
<xac:Attribute
AttributeId="urn:oasis:names:tc:xacml:1.0:resource:resource-id"
<xac:AttributeValue>/protected/env.cgi</></></>
<xac:Action>
<xac:Attribute
AttributeId="urn:oasis:names:tc:xacml:1.0:action:action-id"
<xac:AttributeValue>urn:oasis:names:tc:xacml:1.0:action:implied-action</></></>
<xac:Environment>
<xac:Attribute
AttributeId="zxididp"
<xac:AttributeValue>0.33 1251217347</></>
<xac:Attribute
AttributeId="affid"
<xac:AttributeValue>https://idp.tas3.pt:8443/zxididp?o=B</></>
<xac:Attribute
AttributeId="authnctxlevel"
<xac:AttributeValue>urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</></>
<xac:Attribute
AttributeId="sesid"
<xac:AttributeValue>S6QaJzAylXfkw1tFlrZSD9Zwr</></></></></></></>
11577
11578
11579
11580
11581
11582
11583
11584
<e:Envelope xmlns:e="http://schemas.xmlsoap.org/soap/envelope/">
<e:Body>
<sp:Response
ID="R-Dn3MxxJ0xo7jjOeVpC1aezO"
InResponseTo="RX3eHFSEBW6-OnPG5sGV_EevU"
January 29, 2011
42.5. XACML 2.0 SAML
CHAPTER
PROFILE
42. SOAP
APPENDIX:
CALL SOME EXAMPLE XML BLOBS
11585
11586
11587
11588
11589
11590
11591
11592
11593
11594
11595
11596
11597
11598
11599
11600
11601
11602
11603
11604
11605
11606
11607
11608
11609
11610
11611
11612
11613
11614
11615
Version="2.0">
<sa:Issuer xmlns:sa="urn:oasis:names:tc:SAML:2.0:assertion">https://idp.tas3.pt:8443/zxididp
<ds:SignedInfo>
<ds:Reference URI="#R-Dn3MxxJ0xo7jjOeVpC1aezO">
<ds:Transforms>
<ds:DigestValue>jdBsc0wOvJsBJCCc4eyq1bnG1u4=</></></>
<ds:SignatureValue>AZyw2fK5--(snip)--UTOSSov7kc=</></>
<sp:Status>
<sa:Assertion
ID="A73VuYGSDQ8MI-TUNk8PORrZT"
Version="2.0">
<sa:Issuer>https://idp.tas3.pt:8443/zxididp?o=B</>
<sa:Conditions
NotBefore="2009-09-07T18:48:03Z"
NotOnOrAfter="2009-09-07T19:48:03Z"/>
<xasa:XACMLAuthzDecisionStatement xmlns:xasa="urn:oasis:xacml:2.0:saml:assertion:schema:os
<xac:Response xmlns:xac="urn:oasis:names:tc:xacml:2.0:context:schema:os">
<xac:Result>
<xac:Decision>Permit</>
<xac:Status>
<xac:StatusCode Value="urn:oasis:names:tc:xacml:1.0:status:ok"/></></></></></></>
January 29, 2011
11616
Bibliography
11617
[SAMLCore11] SAML 1.1 Core
11618
[SAMLCore2]
SAML 2.0 Core
11619
[xml-c14n]
XML Canonicalization (non-exclusive), http://www.w3.org/TR/2001/RECxml-c14n-20010315
11620
11621
[xml-exc-c14n] Exclusive XML Canonicalization, http://www.w3.org/TR/xml-exc-c14n/
11622
[Disco2]
Liberty ID-WSF Discovery service 2.0
11623
[Disco12]
Liberty ID-WSF Discovery service 1.1 (liberty-idwsf-disco-svc-v1.2.pdf)
11624
[SecMech2]
Liberty ID-WSF 2.0 Security Mechanisms
11625
[SOAPAuthn2] Liberty ID-WSF 2.0 Authentication Service
11626
[SOAPBinding2] Liberty ID-WSF 2.0 framework document that pulls together all aspects
11627
[DST21]
Liberty Data Services Template 2.1
11628
[DST20]
Liberty DST v2.0
11629
[DST11]
Liberty DST v1.1
11630
[IDDAP]
Liberty Identity based Directory Access Protocol
11631
[IDPP]
Liberty Personal Profile specification.
11632
[Interact11]
Liberty ID-WSF Interaction Service protocol 1.1
11633
[FF12]
Liberty ID Federation Framework 1.2, Protocols and Schemas
11634
[SUBS2]
Liberty Subscriptions and Notifications specification
11635
[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
11636
11637
339

ZXID Book - ZXID.org

Transcription

Similar documents

Cash Management

PDF - Elena Mîndru

forest harvesters forest harvesters

50 years of finnish combine harvester manufacture

kabasa idp settlement

DOWNLOAD 2045 BROCHURE - Sampo

Enrolling in iBenefits Through Single Sign

Blank IDP Outline

tgs ip phone - TGS Enterprise Networks