1
2
3
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
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
|
======================
Common Lasso Knowledge
======================
Starting with basics on using Lasso in a given program.
Lasso Projects Basics
=====================
Lasso functions are defined in several header files typically located in
``/usr/include/lasso/`` or ``/usr/local/include/lasso/``. It is possible to
include individual files even if the main lasso.h is sufficient most often.
The first thing to do is then to call ``lasso_init()``. Similarly the last
thing will be to call ``lasso_shutdown()``. The smallest and useless Lasso
project will therefore be::
#include <lasso/lasso.h>
int main(int argc, char *argv[])
{
lasso_init();
printf("Hello world.\n");
lasso_shutdown();
return 0;
}
Lasso uses a tool called ``pkg-config`` to know the necessary flags for
compilation and linking.
::
$ pkg-config lasso --cflags
-DXMLSEC_CRYPTO=\"openssl\" -DXMLSEC_LIBXML_260=1 -D__XMLSEC_FUNCTION__=__FUNCTION__
-DXMLSEC_NO_XKMS=1 -DXMLSEC_NO_CRYPTO_DYNAMIC_LOADING=1 -DXMLSEC_CRYPTO_OPENSSL=1
-I/usr/include/lasso -I/usr/include/libxml2 -I/usr/include/xmlsec1 -I/usr/include/glib-2.0
-I/usr/lib/glib-2.0/include
$ pkg-config lasso --libs
-llasso -lxmlsec1-openssl -lxmlsec1 -lssl -lcrypto -ldl -lgobject-2.0 -lxslt -lxml2
-lpthread -lz -lm -lglib-2.0
Creating an executable from the previous sample *will then be* a simple
matter of calling gcc with the right flags
Creating an executable from the previous sample would then a simple matter of
calling ``gcc`` with the right flags. But there is currently in bug in
XMLSec, the library used by Lasso to provide XML Signature and XML Encryption
support. It is possible to workaround the bug::
$ gcc hello.c -o hello $(pkg-config lasso --cflags --libs)
<command line>:4:16: missing terminating " character
$ gcc hello.c -o hello $(pkg-config xmlsec1 --cflags --libs | tr -d '\\')
$ ./hello
Hello world.
.. XXX talks about autoconf/automake; that really helps. But that could be in
an appendix.
Lasso Objects
=============
The Lasso Architecture chapter described the different objects provided by
Lasso. The profile objects will be detailed in the following chapters; common
objects such as server, identity and session are explained here.
LassoServer
-----------
A ``LassoServer`` object may be created as follows:
::
LassoServer *server;
server = lasso_server_new("sp-metadata.xml",
NULL, "sp-private-key.pem", "sp-crt.pem", lassoSignatureMethodRsaSha1);
lasso_server_add_provider(server, "idp-metadata.xml",
"idp-public-key.pem", "ca-crt.pem");
- ``sp-metadata.xml`` is the Liberty metadata file for the service provider
- ``idp-metadata.xml`` is the Liberty metadata file for the identity provider
- ``sp-private-key.pem`` is the service provider private key; used to sign
documents
- ``sp-crt.pem`` is the service provider certificate; sent within signed
documents
- ``idp-public-key.pem`` is the identity provider public key; used to verify
signature in documents sent by the identity provider
- ``ca-crt.pem`` is the certificate of the certification authority used by the
identity provider.
It is of course possible to have several calls to ``lasso_server_add_provider``
if there are more than one identity provider.
LassoProfile
------------
This is the virtual base class for profiles. It notably provides access to the
identity and session parts of a profile. See below for examples.
LassoIdentity
-------------
::
/* profile is a pointer to a LassoProfile object */
LassoIdentity *identity;
if (lasso_profile_is_identity_dirty(profile)) {
identity = lasso_profile_get_identity(profile);
if (identity) {
dump = lasso_identity_dump(identity);
}
}
LassoSession
------------
::
/* profile is a pointer to a LassoProfile object */
LassoSession *session;
if (lasso_profile_is_session_dirty(profile)) {
session = lasso_profile_get_session(profile);
if (session) {
dump = lasso_session_dump(session);
}
}
Serialization
-------------
``LassoServer``, ``LassoIdentity`` and ``LassoSession``objects can be
serialized into XML files. Example with a ``LassoServer``::
gchar *dump;
FILE *fd;
dump = lasso_server_dump(server);
/* write dump into a file, a database, whatever */
g_free(dump);
.. note:: ``lasso_server_dump`` (and other Lasso dump functions) allocates
memory through GLib. ``g_free`` is the function to use instead
of ``free`` to release memory.
It is then really easy to have properly constructed objects returned::
LassoServer *server;
gchar *dump;
/* restore dump from file, database, whatever */
server = lasso_server_new_from_dump(dump);
.. warning:: The server dump only contains the filenames; not the actual file
contents. Files should not be moved afterwards.
The functions are:
================ ==================== =============================
Object Dump Restore
================ ==================== =============================
LassoServer lasso_server_dump lasso_server_new_from_dump
LassoIdentity lasso_identity_dump lasso_identity_new_from_dump
LassoSession lasso_session_dump lasso_session_new_from_dump
================ ==================== =============================
|
