178 lines
5.3 KiB
ReStructuredText
178 lines
5.3 KiB
ReStructuredText
======================
|
|
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
|
|
================ ==================== =============================
|
|
|