diff --git a/configure.ac b/configure.ac index bf18fe5c..881f5861 100644 --- a/configure.ac +++ b/configure.ac @@ -652,6 +652,7 @@ csharp/lasso-sharp.pc docs/Makefile docs/lasso-book/Makefile docs/reference/Makefile +docs/reference/version.xml java/Makefile lasso/Makefile lasso/id-ff/Makefile diff --git a/docs/reference/Makefile.am b/docs/reference/Makefile.am index 4cc87582..c78cd5ea 100644 --- a/docs/reference/Makefile.am +++ b/docs/reference/Makefile.am @@ -1,7 +1,8 @@ EXTRA_DIST = \ lasso-sections.txt \ lasso.sgml \ - lasso.types + lasso.types \ + version.xml.in # We need to pre-process original source files # because gtkdoc does not understand some C features @@ -36,7 +37,7 @@ sgml: templates --tmpl-dir=../tmpl/ \ --source-dir=../$(DOC_SOURCE_DIR)/lasso \ --output-dir=../sgml/ - cp $(srcdir)/lasso.sgml build/ + cp $(srcdir)/*.sgml $(srcdir)/version.xml build/ (for i in `find sgml -name "*.sgml" -print` ; do \ cat $$i | \ sed 's!\(<dsig:\)\([^/]*\)\(\/>\)!\1\2\3!g' | \ diff --git a/docs/reference/lasso-sections.txt b/docs/reference/lasso-sections.txt index 75c819b1..1e0c8bd7 100644 --- a/docs/reference/lasso-sections.txt +++ b/docs/reference/lasso-sections.txt @@ -1,3 +1,34 @@ +lasso/lasso.h + +
+provider +LassoProvider +LassoProvider +LassoProviderRole +lassoHttpMethod +lassoMdProtocolType +lasso_provider_new +lasso_provider_get_metadata_one +lasso_provider_get_metadata_list +lasso_provider_load_metadata +lasso_provider_new_from_dump +lasso_provider_verify_signature +lasso_provider_get_first_http_method +lasso_provider_accept_http_method +lasso_provider_has_protocol_profile +lasso_provider_get_base64_succint_id + +LASSO_PROVIDER +LASSO_IS_PROVIDER +LASSO_TYPE_PROVIDER +lasso_provider_get_type +LASSO_PROVIDER_CLASS +LASSO_IS_PROVIDER_CLASS +LASSO_PROVIDER_GET_CLASS +
+ + +
lib_assertion LassoLibAssertion @@ -1186,49 +1217,6 @@ LASSO_IS_NAME_IDENTIFIER_MAPPING_RESPONSE_CLASS LASSO_NAME_IDENTIFIER_MAPPING_RESPONSE_GET_CLASS
-
-provider -LASSO_PROVIDER_NODE -LASSO_PROVIDER_PUBLIC_KEY_NODE -LASSO_PROVIDER_CA_CERTIFICATE_NODE -LassoProviderPrivate -LassoProvider -LassoProvider -LassoProviderClass -lasso_provider_new -lasso_provider_new_from_metadata_node -lasso_provider_new_metadata_filename -lasso_provider_copy -lasso_provider_destroy -lasso_provider_dump -lasso_provider_get_assertionConsumerServiceURL -lasso_provider_get_authnRequestsSigned -lasso_provider_get_federationTerminationNotificationProtocolProfile -lasso_provider_get_federationTerminationServiceReturnURL -lasso_provider_get_federationTerminationServiceURL -lasso_provider_get_nameIdentifierMappingProtocolProfile -lasso_provider_get_providerID -lasso_provider_get_registerNameIdentifierProtocolProfile -lasso_provider_get_registerNameIdentifierServiceURL -lasso_provider_get_registerNameIdentifierServiceReturnURL -lasso_provider_get_singleSignOnProtocolProfile -lasso_provider_get_singleSignOnServiceURL -lasso_provider_get_singleLogoutProtocolProfile -lasso_provider_get_singleLogoutServiceURL -lasso_provider_get_singleLogoutServiceReturnURL -lasso_provider_get_soapEndpoint -lasso_provider_set_public_key -lasso_provider_set_ca_certificate - -LASSO_PROVIDER -LASSO_IS_PROVIDER -LASSO_TYPE_PROVIDER -lasso_provider_get_type -LASSO_PROVIDER_CLASS -LASSO_IS_PROVIDER_CLASS -LASSO_PROVIDER_GET_CLASS -
-
register_name_identifier_request LassoRegisterNameIdentifierRequest @@ -1407,7 +1395,6 @@ LASSO_LOGOUT_GET_CLASS
profile LassoProfilePrivate -lassoHttpMethod lassoProviderType lassoMessageType lasso_profile_get_request_type_from_soap_msg diff --git a/docs/reference/lasso.sgml b/docs/reference/lasso.sgml index 6e8569ef..042189a2 100644 --- a/docs/reference/lasso.sgml +++ b/docs/reference/lasso.sgml @@ -53,15 +53,58 @@ - + + + ]> - Lasso API Reference + Lasso Reference Manual + for Lasso &version; - - Lasso + + Lasso Overview + +Lasso is a library which provides all the necessary functions for sites to +implement Liberty Alliance specifications. + + + + + + + Lasso Architecture + &LassoProvider; + &LassoServer; + &LassoIdentity; + &LassoSession; + + + + Identity Federation Framework + + &LassoProfile; + &LassoLogin; + &LassoFederation; + &LassoLecp; + &LassoLogout; + &LassoDefederation; + + + + + Identity Web Services Framework + + + + + + + + Schemas + + &LassoNode; &LassoLibAssertion; &LassoLibAuthnRequest; &lasso-LassoLibAuthnRequestEnvelope; @@ -90,7 +133,6 @@ &LassoSamlpResponseAbstract; &LassoSamlpStatus; &LassoSamlpStatusCode; - &LassoNode; &LassoLibLogoutRequest; &LassoLibFederationTerminationNotification; &LassoLibLogoutResponse; @@ -106,16 +148,5 @@ &lasso-export; &lasso-lasso; &lasso-version; - &LassoFederation; - &LassoLecp; - &LassoProvider; - &LassoDefederation; - &LassoIdentity; - &LassoLogin; - &LassoLogout; - &LassoProfile; - &LassoServer; - &LassoSession; - &lasso-tools; diff --git a/docs/reference/tmpl/provider.sgml b/docs/reference/tmpl/provider.sgml new file mode 100644 index 00000000..647442ec --- /dev/null +++ b/docs/reference/tmpl/provider.sgml @@ -0,0 +1,170 @@ + +LassoProvider + + +Representation of a provider + + + + + + + + + + + + + + + + +@ProviderID: +@role: +@public_key: +@ca_cert_chain: + + + + + + +@LASSO_PROVIDER_ROLE_NONE: +@LASSO_PROVIDER_ROLE_SP: Acts as service provider +@LASSO_PROVIDER_ROLE_IDP: Acts as identity provider + + + + + + +@LASSO_HTTP_METHOD_NONE: +@LASSO_HTTP_METHOD_ANY: Any method will do, select one automatically +@LASSO_HTTP_METHOD_IDP_INITIATED: +@LASSO_HTTP_METHOD_GET: HTTP-GET implementation (for image tags in Single Logout) +@LASSO_HTTP_METHOD_POST: use an HTML form to post message between service and + identity providers +@LASSO_HTTP_METHOD_REDIRECT: use HTTP 302 redirects to post message between + service and identity providers +@LASSO_HTTP_METHOD_SOAP: use a SOAP call to post message between service and + identity providers + + + + + + +@LASSO_MD_PROTOCOL_TYPE_FEDERATION_TERMINATION: Federation Termination + Notification +@LASSO_MD_PROTOCOL_TYPE_NAME_IDENTIFIER_MAPPING: Name Identifier Mapping +@LASSO_MD_PROTOCOL_TYPE_REGISTER_NAME_IDENTIFIER: Name Registration +@LASSO_MD_PROTOCOL_TYPE_SINGLE_LOGOUT: Single Logout +@LASSO_MD_PROTOCOL_TYPE_SINGLE_SIGN_ON: Single Sign-On and Federation + + + + + + +@role: +@metadata: +@public_key: +@ca_cert_chain: +@Returns: + + + + + + + +@provider: +@name: +@Returns: + + + + + + + +@provider: +@name: +@Returns: + + + + + + + +@provider: +@metadata: +@Returns: + + + + + + + +@dump: +@Returns: + + + + + + + +@provider: +@message: +@id_attr_name: +@format: +@Returns: + + + + + + + +@provider: +@remote_provider: +@protocol_type: +@Returns: + + + + + + + +@provider: +@remote_provider: +@protocol_type: +@http_method: +@initiate_profile: +@Returns: + + + + + + + +@provider: +@protocol_type: +@protocol_profile: +@Returns: + + + + + + + +@provider: +@Returns: + + diff --git a/docs/reference/version.xml.in b/docs/reference/version.xml.in new file mode 100644 index 00000000..d78bda93 --- /dev/null +++ b/docs/reference/version.xml.in @@ -0,0 +1 @@ +@VERSION@ diff --git a/lasso.pc.in b/lasso.pc.in index 7e2347b1..0efed0f2 100644 --- a/lasso.pc.in +++ b/lasso.pc.in @@ -7,5 +7,5 @@ Name: lasso Version: @VERSION@ Description: A free implementation of the Liberty Alliance specifications Requires: libxml-2.0 libxslt xmlsec1 glib-2.0 gobject-2.0 -Cflags: @LASSO_CORE_CFLAGS@ +Cflags: @LASSO_PUB_CFLAGS@ Libs: -L${libdir} @LASSO_CORE_LIBS@ diff --git a/lasso/id-ff/provider.c b/lasso/id-ff/provider.c index 9f6c9290..27abb9d6 100644 --- a/lasso/id-ff/provider.c +++ b/lasso/id-ff/provider.c @@ -62,6 +62,16 @@ char *protocol_methods[] = {"", "", "", "", "", "-http", "-soap"}; /* public methods */ /*****************************************************************************/ +/** + * lasso_provider_get_metadata_one: + * @provider: a #LassoProvider + * @name: the element name + * + * Extracts the element @name from the provider metadata descriptor. + * + * Return value: the element value, NULL if the element was not found. This + * string must be freed by the caller. + **/ gchar* lasso_provider_get_metadata_one(LassoProvider *provider, const char *name) { @@ -79,6 +89,18 @@ lasso_provider_get_metadata_one(LassoProvider *provider, const char *name) return NULL; } + +/** + * lasso_provider_get_metadata_list: + * @provider: a #LassoProvider + * @name: the element name + * + * Extracts zero to many elements from the provider metadata descriptor. + * + * Return value: a #GList with the elements. This GList is internally + * allocated and points to internally allocated strings. It must + * not be freed, modified or stored. + **/ GList* lasso_provider_get_metadata_list(LassoProvider *provider, const char *name) { @@ -92,6 +114,17 @@ lasso_provider_get_metadata_list(LassoProvider *provider, const char *name) } +/** + * lasso_provider_get_first_http_method: + * @provider: a #LassoProvider + * @remote_provider: a #LassoProvider depicting the remote provider + * @protocol_type: a Liberty profile + * + * Looks up and returns a #lassoHttpMethod appropriate for performing the + * @protocol_type between @provider and @remote_provider. + * + * Return value: the #lassoHttpMethod + **/ lassoHttpMethod lasso_provider_get_first_http_method(LassoProvider *provider, LassoProvider *remote_provider, lassoMdProtocolType protocol_type) { @@ -142,6 +175,19 @@ lassoHttpMethod lasso_provider_get_first_http_method(LassoProvider *provider, return LASSO_HTTP_METHOD_NONE; } +/** + * lasso_provider_accept_http_method: + * @provider: a #LassoProvider + * @remote_provider: a #LassoProvider depicting the remote provider + * @protocol_type: a Liberty profile type + * @http_method: an HTTP method + * @initiate_profile: whether @provider initiates the profile + * + * Gets if @http_method is an appropriate method for the @protocol_type profile + * between @provider and @remote_provider. + * + * Return value: %TRUE if it is appropriate + **/ gboolean lasso_provider_accept_http_method(LassoProvider *provider, LassoProvider *remote_provider, lassoMdProtocolType protocol_type, lassoHttpMethod http_method, @@ -176,6 +222,16 @@ lasso_provider_accept_http_method(LassoProvider *provider, LassoProvider *remote return TRUE; } +/** + * lasso_provider_has_protocol_profile: + * @provider: a #LassoProvider + * @protocol_type: a Liberty profile type + * @protocol_profile: a fully-qualified Liberty profile + * + * Gets if @provider supports @protocol_profile. + * + * Return value: %TRUE if it is supported + **/ gboolean lasso_provider_has_protocol_profile(LassoProvider *provider, lassoMdProtocolType protocol_type, const char *protocol_profile) @@ -191,11 +247,14 @@ lasso_provider_has_protocol_profile(LassoProvider *provider, } /** - * lasso_provider_get_base64_succint_id - * @provider: #LassoProvider + * lasso_provider_get_base64_succint_id: + * @provider: a #LassoProvider * * Computes and returns the base64-encoded provider succint ID. - */ + * + * Return value: the provider succint ID. This string must be freed by the + * caller. + **/ char* lasso_provider_get_base64_succint_id(LassoProvider *provider) { @@ -487,6 +546,17 @@ lasso_provider_load_metadata(LassoProvider *provider, const gchar *metadata) return TRUE; } +/** + * lasso_provider_new: + * @role: provider role, identity provider or service provider + * @metadata: path to metadata file for the provider + * @public_key: + * @ca_cert_chain: + * + * Creates a new #LassoProvider + * + * Return value: a newly created #LassoProvider + */ LassoProvider* lasso_provider_new(LassoProviderRole role, char *metadata, char *public_key, char *ca_cert_chain) { diff --git a/lasso/id-ff/provider.h b/lasso/id-ff/provider.h index 1884061a..80554a03 100644 --- a/lasso/id-ff/provider.h +++ b/lasso/id-ff/provider.h @@ -48,37 +48,39 @@ typedef struct _LassoProviderPrivate LassoProviderPrivate; typedef enum { LASSO_HTTP_METHOD_NONE = -1, - LASSO_HTTP_METHOD_ANY, - LASSO_HTTP_METHOD_IDP_INITIATED, - LASSO_HTTP_METHOD_GET, - LASSO_HTTP_METHOD_POST, - LASSO_HTTP_METHOD_REDIRECT, - LASSO_HTTP_METHOD_SOAP + LASSO_HTTP_METHOD_ANY, /* any method will do */ + LASSO_HTTP_METHOD_IDP_INITIATED, /* no method, IdP initiated profile */ + LASSO_HTTP_METHOD_GET, /* HTTP GET */ + LASSO_HTTP_METHOD_POST, /* Browser POST */ + LASSO_HTTP_METHOD_REDIRECT, /* HTTP-Redirect based */ + LASSO_HTTP_METHOD_SOAP /* SOAP/HTTP based */ } lassoHttpMethod; typedef enum { - LASSO_MD_PROTOCOL_TYPE_FEDERATION_TERMINATION = 0, - LASSO_MD_PROTOCOL_TYPE_NAME_IDENTIFIER_MAPPING, - LASSO_MD_PROTOCOL_TYPE_REGISTER_NAME_IDENTIFIER, - LASSO_MD_PROTOCOL_TYPE_SINGLE_LOGOUT, - LASSO_MD_PROTOCOL_TYPE_SINGLE_SIGN_ON + LASSO_MD_PROTOCOL_TYPE_FEDERATION_TERMINATION = 0, /* Federation Termination Notification */ + LASSO_MD_PROTOCOL_TYPE_NAME_IDENTIFIER_MAPPING, /* Name Identifier Mapping */ + LASSO_MD_PROTOCOL_TYPE_REGISTER_NAME_IDENTIFIER, /* Name Registration */ + LASSO_MD_PROTOCOL_TYPE_SINGLE_LOGOUT, /* Single Logout */ + LASSO_MD_PROTOCOL_TYPE_SINGLE_SIGN_ON /* Single Sign-On and Federation */ } lassoMdProtocolType; typedef enum { LASSO_PROVIDER_ROLE_NONE = 0, - LASSO_PROVIDER_ROLE_SP, - LASSO_PROVIDER_ROLE_IDP + LASSO_PROVIDER_ROLE_SP, /* Service Provider */ + LASSO_PROVIDER_ROLE_IDP /* Identity Provider */ } LassoProviderRole; struct _LassoProvider { LassoNode parent; + /*< public >*/ gchar *ProviderID; LassoProviderRole role; gchar *public_key; gchar *ca_cert_chain; + /*< private >*/ LassoProviderPrivate *private_data; };