LassoProvider

LassoProvider — Service or identity provider

Functions

Types and Values

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.

Functions

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.

Parameters

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


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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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 .

Parameters

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 .

Parameters

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


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 .

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

provider

a LassoProvider object

 

Returns

a value in the LassoProtocolConformance enumeration.


lasso_provider_get_encryption_mode ()

LassoEncryptionMode
lasso_provider_get_encryption_mode (LassoProvider *provider);

Return the current encryption mode.

Parameters

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

Parameters

provider

provider to set encryption for

 

encryption_mode

TRUE to activate, FALSE to desactivate

 

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

Parameters

provider

provider to set encryption for

 

encryption_sym_key_type

enum type for generated symetric key

 

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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 .

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

provider

a LassoProvider object

 

another_provider

a LassoProvider object

 

Returns

TRUE or FALSE.


lasso_provider_set_protocol_conformance ()

void
lasso_provider_set_protocol_conformance
                               (LassoProvider *provider,
                                LassoProtocolConformance protocol_conformance);

Normally the protocol conformance is set when the metadata for the provider is loaded because the metadata defines the type of server. However some LassoServer variants do not have metadata (e.g. ECP) therefore instead of loading the metadata it is necessary to explicitly set the protocol conformance because parts of the Lasso library dispatch based on the protocol conformance. Without the protocol conformance being set it is likely the wrong code will execute.

**WARNING**, do not manually set the protocol conformance if metadata has been loaded, metadata is the final arbiter of protocol conformance.

Parameters

provider

a LassoProvider object

 

protocol_conformance

LassoProtocolConformance enumerated value.

 

Returns

0 on success; another value if an error occured.

Types and Values

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().

Members

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).

 

enum 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).

Members

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_ROLE_ALL

   

enum LassoHttpMethod

Method.

Members

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

Liberty Metadata Type.

Members

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

   

enum LassoProtocolConformance

Provider protocol conformance.

Members

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

 

enum LassoEncryptionMode

Encryption mode.

Members

LASSO_ENCRYPTION_MODE_NONE

Encrypt nothing

 

LASSO_ENCRYPTION_MODE_NAMEID

Encrypt NameIDs

 

LASSO_ENCRYPTION_MODE_ASSERTION

Encrypt Assertions

 

enum LassoEncryptionSymKeyType

Encryption symetric key type.

Members

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