5
Starting with basics on using Lasso in a given program.
10
Lasso functions are defined in several header files typically located in
11
``/usr/include/lasso/`` or ``/usr/local/include/lasso/``. It is possible to
12
include individual files even if the main lasso.h is sufficient most often.
14
The first thing to do is then to call ``lasso_init()``. Similarly the last
15
thing will be to call ``lasso_shutdown()``. The smallest and useless Lasso
16
project will therefore be::
18
#include <lasso/lasso.h>
20
int main(int argc, char *argv[])
23
printf("Hello world.\n");
28
Lasso uses a tool called ``pkg-config`` to know the necessary flags for
29
compilation and linking.
33
$ pkg-config lasso --cflags
34
-DXMLSEC_CRYPTO=\"openssl\" -DXMLSEC_LIBXML_260=1 -D__XMLSEC_FUNCTION__=__FUNCTION__
35
-DXMLSEC_NO_XKMS=1 -DXMLSEC_NO_CRYPTO_DYNAMIC_LOADING=1 -DXMLSEC_CRYPTO_OPENSSL=1
36
-I/usr/include/lasso -I/usr/include/libxml2 -I/usr/include/xmlsec1 -I/usr/include/glib-2.0
37
-I/usr/lib/glib-2.0/include
38
$ pkg-config lasso --libs
39
-llasso -lxmlsec1-openssl -lxmlsec1 -lssl -lcrypto -ldl -lgobject-2.0 -lxslt -lxml2
40
-lpthread -lz -lm -lglib-2.0
43
Creating an executable from the previous sample *will then be* a simple
44
matter of calling gcc with the right flags
46
Creating an executable from the previous sample would then a simple matter of
47
calling ``gcc`` with the right flags. But there is currently in bug in
48
XMLSec, the library used by Lasso to provide XML Signature and XML Encryption
49
support. It is possible to workaround the bug::
51
$ gcc hello.c -o hello $(pkg-config lasso --cflags --libs)
52
<command line>:4:16: missing terminating " character
53
$ gcc hello.c -o hello $(pkg-config xmlsec1 --cflags --libs | tr -d '\\')
58
.. XXX talks about autoconf/automake; that really helps. But that could be in
65
The Lasso Architecture chapter described the different objects provided by
66
Lasso. The profile objects will be detailed in the following chapters; common
67
objects such as server, identity and session are explained here.
73
A ``LassoServer`` object may be created as follows:
78
server = lasso_server_new("sp-metadata.xml",
79
NULL, "sp-private-key.pem", "sp-crt.pem", lassoSignatureMethodRsaSha1);
80
lasso_server_add_provider(server, "idp-metadata.xml",
81
"idp-public-key.pem", "ca-crt.pem");
83
- ``sp-metadata.xml`` is the Liberty metadata file for the service provider
84
- ``idp-metadata.xml`` is the Liberty metadata file for the identity provider
85
- ``sp-private-key.pem`` is the service provider private key; used to sign
87
- ``sp-crt.pem`` is the service provider certificate; sent within signed
89
- ``idp-public-key.pem`` is the identity provider public key; used to verify
90
signature in documents sent by the identity provider
91
- ``ca-crt.pem`` is the certificate of the certification authority used by the
94
It is of course possible to have several calls to ``lasso_server_add_provider``
95
if there are more than one identity provider.
100
This is the virtual base class for profiles. It notably provides access to the
101
identity and session parts of a profile. See below for examples.
109
/* profile is a pointer to a LassoProfile object */
111
LassoIdentity *identity;
113
if (lasso_profile_is_identity_dirty(profile)) {
114
identity = lasso_profile_get_identity(profile);
116
dump = lasso_identity_dump(identity);
127
/* profile is a pointer to a LassoProfile object */
129
LassoSession *session;
131
if (lasso_profile_is_session_dirty(profile)) {
132
session = lasso_profile_get_session(profile);
134
dump = lasso_session_dump(session);
143
``LassoServer``, ``LassoIdentity`` and ``LassoSession``objects can be
144
serialized into XML files. Example with a ``LassoServer``::
149
dump = lasso_server_dump(server);
150
/* write dump into a file, a database, whatever */
153
.. note:: ``lasso_server_dump`` (and other Lasso dump functions) allocates
154
memory through GLib. ``g_free`` is the function to use instead
155
of ``free`` to release memory.
157
It is then really easy to have properly constructed objects returned::
162
/* restore dump from file, database, whatever */
163
server = lasso_server_new_from_dump(dump);
165
.. warning:: The server dump only contains the filenames; not the actual file
166
contents. Files should not be moved afterwards.
170
================ ==================== =============================
172
================ ==================== =============================
173
LassoServer lasso_server_dump lasso_server_new_from_dump
174
LassoIdentity lasso_identity_dump lasso_identity_new_from_dump
175
LassoSession lasso_session_dump lasso_session_new_from_dump
176
================ ==================== =============================
added
removed
docs/lasso-book/common-knowledge.rst
