Starting with basics on using Lasso in a given program.
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.
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.
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 provideridp-metadata.xml is the Liberty metadata file for the identity providersp-private-key.pem is the service provider private key; used to sign
documentssp-crt.pem is the service provider certificate; sent within signed
documentsidp-public-key.pem is the identity provider public key; used to verify
signature in documents sent by the identity providerca-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.
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.
/* 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);
}
}
/* 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);
}
}
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 |