LassoProvider

LassoProvider — Service or identity provider

Synopsis

struct              LassoProvider;
LassoProvider *     lasso_provider_new                  (LassoProviderRole role,
                                                         const char *metadata,
                                                         const char *public_key,
                                                         const char *ca_cert_chain);
enum                LassoProviderRole;
LassoProvider *     lasso_provider_new_from_buffer      (LassoProviderRole role,
                                                         const char *metadata,
                                                         const char *public_key,
                                                         const char *ca_cert_chain);
gchar *             lasso_provider_get_assertion_consumer_service_url
                                                        (LassoProvider *provider,
                                                         const char *service_id);
gchar *             lasso_provider_get_metadata_one     (LassoProvider *provider,
                                                         const char *name);
GList *             lasso_provider_get_metadata_list    (LassoProvider *provider,
                                                         const char *name);
LassoProvider *     lasso_provider_new_from_dump        (const gchar *dump);
LassoHttpMethod     lasso_provider_get_first_http_method
                                                        (LassoProvider *provider,
                                                         LassoProvider *remote_provider,
                                                         LassoMdProtocolType protocol_type);
gboolean            lasso_provider_accept_http_method   (LassoProvider *provider,
                                                         LassoProvider *remote_provider,
                                                         LassoMdProtocolType protocol_type,
                                                         LassoHttpMethod http_method,
                                                         gboolean initiate_profile);
enum                LassoHttpMethod;
enum                LassoMdProtocolType;
gboolean            lasso_provider_has_protocol_profile (LassoProvider *provider,
                                                         LassoMdProtocolType protocol_type,
                                                         const char *protocol_profile);
gchar *             lasso_provider_get_base64_succinct_id
                                                        (const LassoProvider *provider);
xmlNode *           lasso_provider_get_organization     (const LassoProvider *provider);
LassoProtocolConformance  lasso_provider_get_protocol_conformance
                                                        (const LassoProvider *provider);
enum                LassoProtocolConformance;
LassoEncryptionMode  lasso_provider_get_encryption_mode (LassoProvider *provider);
void                lasso_provider_set_encryption_mode  (LassoProvider *provider,
                                                         LassoEncryptionMode encryption_mode);
enum                LassoEncryptionMode;
void                lasso_provider_set_encryption_sym_key_type
                                                        (LassoProvider *provider,
                                                         LassoEncryptionSymKeyType encryption_sym_key_type);
enum                LassoEncryptionSymKeyType;
lasso_error_t       lasso_provider_verify_single_node_signature
                                                        (LassoProvider *provider,
                                                         LassoNode *node,
                                                         const char *id_attr_name);
gchar *             lasso_provider_get_default_name_id_format
                                                        (LassoProvider *provider);
const char *        lasso_provider_get_sp_name_qualifier
                                                        (LassoProvider *provider);
GList *             lasso_provider_get_idp_supported_attributes
                                                        (LassoProvider *provider);
char *              lasso_provider_get_valid_until      (LassoProvider *provider);
char *              lasso_provider_get_cache_duration   (LassoProvider *provider);
char *              lasso_provider_get_metadata_one_for_role
                                                        (LassoProvider *provider,
                                                         LassoProviderRole role,
                                                         const char *name);
GList *             lasso_provider_get_metadata_list_for_role
                                                        (const LassoProvider *provider,
                                                         LassoProviderRole role,
                                                         const char *name);
GList *             lasso_provider_get_metadata_keys_for_role
                                                        (LassoProvider *provider,
                                                         LassoProviderRole role);
LassoProviderRole   lasso_provider_get_roles            (LassoProvider *provider);
gboolean            lasso_provider_match_conformance    (LassoProvider *provider,
                                                         LassoProvider *another_provider);

Description

The LassoProvider object holds metadata about a provider. Metadata are sorted into descriptors, each descriptor being assigned a role. We refer you to Liberty Metadata Description and Discovery Specification and Metadata for the OASIS Security Assertion Markup Language (SAML) V2.0.

Roles are represented by the enumeration LassoProviderRole, you can access descriptors content using lasso_provider_get_metadata_list_for_role() and lasso_provider_get_metadata_by_role(). Descriptors resources are flattened inside a simple hashtable. For example to get the URL(s) for the SAML 2.0 single logout response endpoint using binding HTTP-POST of the SP descriptor of a provider called x, you would call:

GList *urls = lasso_provider_get_metadata_list_for_role(x, LASSO_PROVIDER_ROLE_SP, "SingleLogoutService HTTP-POST ResponseLocation");

A provider usually possess a default role stored in the LassoProvider.role field, which is initialized by the lasso_server_add_provider() method when registering a new remote provider to our current provider. The methods lasso_provider_get_metadata() and lasso_provider_get_metadata_list() use this default role to access descriptors.

Details

struct LassoProvider

struct LassoProvider {
	LassoNode parent;

	gchar *ProviderID;
	LassoProviderRole role;

	char *metadata_filename;
	gchar *public_key;
	gchar *ca_cert_chain;
};

Any kind of provider, identity provider, service provider, attribute authority, authorization authority will be represented by a LassoProvider object. This object will holds public keys, certificate chains and metadata informations. The ID-FF 1.2 and SAML 2.0 metadata files are flattened inside a key-value map that you can access using the functions lasso_provider_get_metadata_one_for_role(), lasso_provider_get_metadata_list_for_role(), lasso_provider_get_metadata_keys_for_role().

LassoNode `parent`;
gchar *`ProviderID`;	the identifier URI of this provider
LassoProviderRole `role`;	the role prescribed when this LassoProvider was built
char *`metadata_filename`;	file path or content of the metadata description for this provider.
gchar *`public_key`;	file path or content of the public key file for this provider.
gchar *`ca_cert_chain`;	file path or content of the CA cert chain used to validate signature of this provider (can be used instead of a public key to limit the need for metadata updates).

lasso_provider_new ()

LassoProvider *     lasso_provider_new                  (LassoProviderRole role,
                                                         const char *metadata,
                                                         const char *public_key,
                                                         const char *ca_cert_chain);

Creates a new LassoProvider.

`role` :	provider role, identity provider or service provider
`metadata` :	path to the provider metadata file
`public_key:(allow-none)` :	path to the provider public key file (may be a certificate) or NULL
`ca_cert_chain:(allow-none)` :	path to the provider CA certificate chain file or NULL
Returns :	a newly created LassoProvider; or NULL if an error occured

enum LassoProviderRole

typedef enum {
	LASSO_PROVIDER_ROLE_ANY = -1,
	LASSO_PROVIDER_ROLE_NONE = 0,
	LASSO_PROVIDER_ROLE_SP = 1,
	LASSO_PROVIDER_ROLE_IDP = 2,
	LASSO_PROVIDER_ROLE_BOTH = 3,
	LASSO_PROVIDER_ROLE_AUTHN_AUTHORITY = 4,
	LASSO_PROVIDER_ROLE_AUTHZ_AUTHORITY = 8,
	LASSO_PROVIDER_ROLE_ATTRIBUTE_AUTHORITY = 16,
	LASSO_PROVIDER_ROLE_LAST = 17
} LassoProviderRole;

LassoProviderRole is an enumeration allowing to enumerate the roles handled by a provider, it can be used in a bitmask as each value is a power of 2 (except LASSO_PROVIDER_ROLE_ANY which is the full bitmask and LASSO_PROVIDER_ROLE_NONE).

`LASSO_PROVIDER_ROLE_ANY`
`LASSO_PROVIDER_ROLE_NONE`	unitialized value (internal use)
`LASSO_PROVIDER_ROLE_SP`	service provider.
`LASSO_PROVIDER_ROLE_IDP`	identity provider.
`LASSO_PROVIDER_ROLE_BOTH`	service&identity provider.
`LASSO_PROVIDER_ROLE_AUTHN_AUTHORITY`	an authentification authority, i.e. an endpoint able to return previously returned assertion,
`LASSO_PROVIDER_ROLE_AUTHZ_AUTHORITY`	an authorization authority, i.e. an endpoint able to return assertion providing authorization about a principal acessing a resource,
`LASSO_PROVIDER_ROLE_ATTRIBUTE_AUTHORITY`	an attribute authority, i.e. an endpoint able to return attributes aboute a principal,
`LASSO_PROVIDER_ROLE_LAST`	all values in the enumeration are guaranteed to be < to `LASSO_PROVIDER_ROLE_LAST`.

lasso_provider_new_from_buffer ()

LassoProvider *     lasso_provider_new_from_buffer      (LassoProviderRole role,
                                                         const char *metadata,
                                                         const char *public_key,
                                                         const char *ca_cert_chain);

Creates a new LassoProvider.

`role` :	provider role, identity provider or service provider
`metadata` :	string buffer containing a metadata file
`public_key:(allow-none)` :	path to the provider public key file (may be a certificate) or NULL
`ca_cert_chain:(allow-none)` :	path to the provider CA certificate chain file or NULL
Returns :	a newly created LassoProvider; or NULL if an error occured

lasso_provider_get_assertion_consumer_service_url ()

gchar *             lasso_provider_get_assertion_consumer_service_url
                                                        (LassoProvider *provider,
                                                         const char *service_id);

Extracts the AssertionConsumerServiceURL from the provider metadata descriptor.

`provider` :	a LassoProvider
`service_id:(allow-none)` :	the AssertionConsumerServiceID, NULL for default
Returns :	the element value, NULL if the element was not found. This string must be freed by the caller. [allow-none][transfer full]

lasso_provider_get_metadata_one ()

gchar *             lasso_provider_get_metadata_one     (LassoProvider *provider,
                                                         const char *name);

Extracts the element name from the provider metadata descriptor.

`provider` :	a LassoProvider
`name` :	the element name
Returns :	the element value, NULL if the element was not found. This string must be freed by the caller. [transfer full][allow-none]

lasso_provider_get_metadata_list ()

GList *             lasso_provider_get_metadata_list    (LassoProvider *provider,
                                                         const char *name);

Extracts zero to many elements from the provider metadata descriptor.

`provider` :	a LassoProvider
`name` :	the element name
Returns :	a GList with the elements. This GList is internally allocated and points to internally allocated strings. It must not be freed, modified or stored. [transfer none][element-type string]

lasso_provider_new_from_dump ()

LassoProvider *     lasso_provider_new_from_dump        (const gchar *dump);

Restores the dump to a new LassoProvider.

`dump` :	XML provider dump
Returns :	a newly created LassoProvider; or NULL if an error occured.

lasso_provider_get_first_http_method ()

LassoHttpMethod     lasso_provider_get_first_http_method
                                                        (LassoProvider *provider,
                                                         LassoProvider *remote_provider,
                                                         LassoMdProtocolType protocol_type);

Looks up and returns a LassoHttpMethod appropriate for performing the protocol_type between provider and remote_provider.

`provider` :	a LassoProvider. [transfer none]
`remote_provider` :	a LassoProvider depicting the remote provider
`protocol_type` :	a Liberty profile
Returns :	the LassoHttpMethod

lasso_provider_accept_http_method ()

gboolean            lasso_provider_accept_http_method   (LassoProvider *provider,
                                                         LassoProvider *remote_provider,
                                                         LassoMdProtocolType protocol_type,
                                                         LassoHttpMethod http_method,
                                                         gboolean initiate_profile);

Gets if http_method is an appropriate method for the protocol_type profile between provider and remote_provider.

`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
Returns :	`TRUE` if it is appropriate

enum LassoHttpMethod

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_ARTIFACT_GET,
	LASSO_HTTP_METHOD_ARTIFACT_POST,
	LASSO_HTTP_METHOD_PAOS,
	LASSO_HTTP_METHOD_LAST
} LassoHttpMethod;

Method.

`LASSO_HTTP_METHOD_NONE`	invalid value (internal use)
`LASSO_HTTP_METHOD_ANY`	any method will do
`LASSO_HTTP_METHOD_IDP_INITIATED`	not a method, for 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
`LASSO_HTTP_METHOD_ARTIFACT_GET`	Artifact by HTTP GET (SAML 2.0)
`LASSO_HTTP_METHOD_ARTIFACT_POST`	Artifact by HTTP POST (SAML 2.0)
`LASSO_HTTP_METHOD_PAOS`	PAOS/HTTP based (SAML 2.0)
`LASSO_HTTP_METHOD_LAST`

enum LassoMdProtocolType

typedef enum {
	LASSO_MD_PROTOCOL_TYPE_FEDERATION_TERMINATION,
	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_ARTIFACT_RESOLUTION,
	LASSO_MD_PROTOCOL_TYPE_MANAGE_NAME_ID,
	LASSO_MD_PROTOCOL_TYPE_ASSERTION_ID_REQUEST,
	LASSO_MD_PROTOCOL_TYPE_AUTHN_QUERY,
	LASSO_MD_PROTOCOL_TYPE_AUTHZ,
	LASSO_MD_PROTOCOL_TYPE_ATTRIBUTE,
	LASSO_MD_PROTOCOL_TYPE_LAST
} LassoMdProtocolType;

Liberty Metadata Type.

`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
`LASSO_MD_PROTOCOL_TYPE_ARTIFACT_RESOLUTION`	Artifact Resolution (SAML 2.0)
`LASSO_MD_PROTOCOL_TYPE_MANAGE_NAME_ID`	Manage Name Identifier (SAML 2.0)
`LASSO_MD_PROTOCOL_TYPE_ASSERTION_ID_REQUEST`	Assertion ID Request (SAML 2.0)
`LASSO_MD_PROTOCOL_TYPE_AUTHN_QUERY`
`LASSO_MD_PROTOCOL_TYPE_AUTHZ`
`LASSO_MD_PROTOCOL_TYPE_ATTRIBUTE`
`LASSO_MD_PROTOCOL_TYPE_LAST`

lasso_provider_has_protocol_profile ()

gboolean            lasso_provider_has_protocol_profile (LassoProvider *provider,
                                                         LassoMdProtocolType protocol_type,
                                                         const char *protocol_profile);

Gets if provider supports protocol_profile.

`provider` :	a LassoProvider
`protocol_type` :	a Liberty profile type
`protocol_profile` :	a fully-qualified Liberty profile
Returns :	`TRUE` if it is supported

lasso_provider_get_base64_succinct_id ()

gchar *             lasso_provider_get_base64_succinct_id
                                                        (const LassoProvider *provider);

Computes and returns the base64-encoded provider succinct ID.

`provider` :	a LassoProvider
Returns :	the provider succinct ID. This string must be freed by the caller. [transfer full][allow-none]

lasso_provider_get_organization ()

xmlNode *           lasso_provider_get_organization     (const LassoProvider *provider);

Returns the provider metadata <Organization> XML node.

`provider` :	a LassoProvider
Returns :	the <Organization/> node (libxml2 xmlNode*); or NULL if it is not found. This xmlnode must be freed by the caller. [transfer full][allow-none]

lasso_provider_get_protocol_conformance ()

LassoProtocolConformance  lasso_provider_get_protocol_conformance
                                                        (const LassoProvider *provider);

Return the protocol conformance of the given provider, it should allow to switch behaviour of SP and IdP code toward a specific protocol. See also LassoProtocolConformance.

`provider` :	a LassoProvider object
Returns :	a value in the LassoProtocolConformance enumeration.

enum LassoProtocolConformance

typedef enum {
	LASSO_PROTOCOL_NONE = -1,
	LASSO_PROTOCOL_LIBERTY_1_0,
	LASSO_PROTOCOL_LIBERTY_1_1,
	LASSO_PROTOCOL_LIBERTY_1_2,
	LASSO_PROTOCOL_SAML_2_0
} LassoProtocolConformance;

Provider protocol conformance.

`LASSO_PROTOCOL_NONE`
`LASSO_PROTOCOL_LIBERTY_1_0`	Liberty ID-FF 1.0
`LASSO_PROTOCOL_LIBERTY_1_1`	Liberty ID-FF 1.1
`LASSO_PROTOCOL_LIBERTY_1_2`	Liberty ID-FF 1.2 / ID-WSF 1.0
`LASSO_PROTOCOL_SAML_2_0`	SAML 2.0

lasso_provider_get_encryption_mode ()

LassoEncryptionMode  lasso_provider_get_encryption_mode (LassoProvider *provider);

Return the current encryption mode.

`provider` :	a LassoProvider object
Returns :	a value in the LassoEncryptionMode enumeration.

lasso_provider_set_encryption_mode ()

void                lasso_provider_set_encryption_mode  (LassoProvider *provider,
                                                         LassoEncryptionMode encryption_mode);

Activate or desactivate encryption

`provider` :	provider to set encryption for
`encryption_mode` :	TRUE to activate, FALSE to desactivate

enum LassoEncryptionMode

typedef enum {
	LASSO_ENCRYPTION_MODE_NONE,
	LASSO_ENCRYPTION_MODE_NAMEID,
	LASSO_ENCRYPTION_MODE_ASSERTION
} LassoEncryptionMode;

Encryption mode.

`LASSO_ENCRYPTION_MODE_NONE`	Encrypt nothing
`LASSO_ENCRYPTION_MODE_NAMEID`	Encrypt NameIDs
`LASSO_ENCRYPTION_MODE_ASSERTION`	Encrypt Assertions

lasso_provider_set_encryption_sym_key_type ()

void                lasso_provider_set_encryption_sym_key_type
                                                        (LassoProvider *provider,
                                                         LassoEncryptionSymKeyType encryption_sym_key_type);

Set the type of the generated encryption symetric key

`provider` :	provider to set encryption for
`encryption_sym_key_type` :	enum type for generated symetric key

enum LassoEncryptionSymKeyType

typedef enum {
	LASSO_ENCRYPTION_SYM_KEY_TYPE_DEFAULT,
	LASSO_ENCRYPTION_SYM_KEY_TYPE_AES_256,
	LASSO_ENCRYPTION_SYM_KEY_TYPE_AES_128,
	LASSO_ENCRYPTION_SYM_KEY_TYPE_3DES,
	LASSO_ENCRYTPION_SYM_KEY_TYPE_LAST
} LassoEncryptionSymKeyType;

Encryption symetric key type.

`LASSO_ENCRYPTION_SYM_KEY_TYPE_DEFAULT`	Default type (AES 128)
`LASSO_ENCRYPTION_SYM_KEY_TYPE_AES_256`	Aes 256 bits key
`LASSO_ENCRYPTION_SYM_KEY_TYPE_AES_128`	Aes 128 bits key
`LASSO_ENCRYPTION_SYM_KEY_TYPE_3DES`	Triple DES 192 bits key
`LASSO_ENCRYTPION_SYM_KEY_TYPE_LAST`

lasso_provider_verify_single_node_signature ()

lasso_error_t       lasso_provider_verify_single_node_signature
                                                        (LassoProvider *provider,
                                                         LassoNode *node,
                                                         const char *id_attr_name);

Return wheter the provider signed this node.

`provider` :	a LassoProvider object
`node` :	a LassoNode object, still having its originalXmlnode content, and containing an XML signature.
`id_attr_name` :	the name of the ID attribute to lookup.
Returns :	0 if the node is signed by this provider, an error code otherwise.

lasso_provider_get_default_name_id_format ()

gchar *             lasso_provider_get_default_name_id_format
                                                        (LassoProvider *provider);

If the provider has a list of supported name id formats in its metadatas, return the first one.

`provider` :	a LassoProvider object
Returns :	a NameIDFormat URI or NULL, the returned value must be freed by the caller. [transfer full][allow-none]

lasso_provider_get_sp_name_qualifier ()

const char *        lasso_provider_get_sp_name_qualifier
                                                        (LassoProvider *provider);

Return the entityID to use for qualifying NameIdentifier.

`provider` :	a LassoPRovider object
Returns :	a private string or NULL. Do not keep a reference on this string or free it. [transfer none][allow-none]

lasso_provider_get_idp_supported_attributes ()

GList *             lasso_provider_get_idp_supported_attributes
                                                        (LassoProvider *provider);

If the provider supports the IDP SSO role, then return the list of Attribute definition that this provider declared supporting.

`provider` :	a LassoProvider object
Returns :	a list of LassoSaml2Attribute or LassoSamlAttribute. [transfer none][element-type LassoNode]

lasso_provider_get_valid_until ()

char *              lasso_provider_get_valid_until      (LassoProvider *provider);

Return the time after which the metadata for this provider will become invalid. This is an ISO-8601 formatted string.

`provider` :	a LassoProvider object
Returns :	an internally allocated string, you can copy it but not store it. [transfer none]

lasso_provider_get_cache_duration ()

char *              lasso_provider_get_cache_duration   (LassoProvider *provider);

Return the time during which the metadata for this provider can be kept.

`provider` :	a LassoProvider object
Returns :	an internally allocated string, you can copy it but not store it. [transfer none]

lasso_provider_get_metadata_one_for_role ()

char *              lasso_provider_get_metadata_one_for_role
                                                        (LassoProvider *provider,
                                                         LassoProviderRole role,
                                                         const char *name);

Return the given information extracted from the metadata of the given LassoProvider for the given role descriptor.

Retun value: a newly allocated string or NULL. If non-NULL must be freed by the caller.

`provider` :	a LassoProvider object
`role` :	a LassoProviderRole value
`name` :	a metadata information name

lasso_provider_get_metadata_list_for_role ()

GList *             lasso_provider_get_metadata_list_for_role
                                                        (const LassoProvider *provider,
                                                         LassoProviderRole role,
                                                         const char *name);

Extracts zero to many elements from the provider descriptor for the given role.

`provider` :	a LassoProvider
`role` :	a LassoProviderRole value
`name` :	the element name
Returns :	a GList with the elements. This GList is internally allocated and points to internally allocated strings. It must not be freed, modified or stored. [transfer none][element-type string]

lasso_provider_get_metadata_keys_for_role ()

GList *             lasso_provider_get_metadata_keys_for_role
                                                        (LassoProvider *provider,
                                                         LassoProviderRole role);

Returns the list of metadata keys existing for the given provider.

`provider` :	a LassoProvider object
`role` :	a LassoProviderRole value
Returns :	a newly allocated list of strings. [element-type utf8][transfer full]

lasso_provider_get_roles ()

LassoProviderRole   lasso_provider_get_roles            (LassoProvider *provider);

Return the bitmask of the supported roles.

`provider` :	a LassoProvider object
Returns :	a LassoProviderRole enumeration value.

lasso_provider_match_conformance ()

gboolean            lasso_provider_match_conformance    (LassoProvider *provider,
                                                         LassoProvider *another_provider);

Return whether the two provider support a same protocol. See also LassoProtocolConformance.

`provider` :	a LassoProvider object
`another_provider` :	a LassoProvider object
Returns :	TRUE or FALSE.

			Lasso Reference Manual
Top \| Description

Entr'ouvert Documentation