LassoProvider: lasso Reference Manual

## LassoProvider LassoProvider — Service or identity provider |

## Functions

LassoProvider * | lasso_provider_new ()
LassoProvider * | lasso_provider_new_from_buffer ()
gchar * | lasso_provider_get_assertion_consumer_service_url ()
gchar * | lasso_provider_get_metadata_one ()
GList * | lasso_provider_get_metadata_list ()
LassoProvider * | lasso_provider_new_from_dump ()
LassoHttpMethod | lasso_provider_get_first_http_method ()
gboolean | lasso_provider_accept_http_method ()
gboolean | lasso_provider_has_protocol_profile ()
gchar * | lasso_provider_get_base64_succinct_id ()
xmlNode * | lasso_provider_get_organization ()
LassoProtocolConformance | lasso_provider_get_protocol_conformance ()
LassoEncryptionMode | lasso_provider_get_encryption_mode ()
void | lasso_provider_set_encryption_mode ()
void | lasso_provider_set_encryption_sym_key_type ()
lasso_error_t | lasso_provider_verify_single_node_signature ()
gchar * | lasso_provider_get_default_name_id_format ()
const char * | lasso_provider_get_sp_name_qualifier ()
GList * | lasso_provider_get_idp_supported_attributes ()
char * | lasso_provider_get_valid_until ()
char * | lasso_provider_get_cache_duration ()
char * | lasso_provider_get_metadata_one_for_role ()
GList * | lasso_provider_get_metadata_list_for_role ()
GList * | lasso_provider_get_metadata_keys_for_role ()
LassoProviderRole | lasso_provider_get_roles ()
gboolean | lasso_provider_match_conformance ()
void | lasso_provider_set_protocol_conformance ()

## Types and Values

struct | LassoProvider
enum | LassoProviderRole
enum | LassoHttpMethod
enum | LassoMdProtocolType
enum | LassoProtocolConformance
enum | LassoEncryptionMode
enum | LassoEncryptionSymKeyType

## Object Hierarchy

        GObject
        ╰── LassoNode
            ╰── LassoProvider
                ╰── LassoServer

## 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 | path to the provider public key file (may be a certificate) or NULL. | [allow-none]
ca_cert_chain | path to the provider CA certificate chain file or NULL. | [allow-none]

#### 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 | path to the provider public key file (may be a certificate) or NULL. | [allow-none]
ca_cert_chain | path to the provider CA certificate chain file or NULL. | [allow-none]

#### 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 | the AssertionConsumerServiceID, NULL for default. | [allow-none]

#### 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 {
    	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

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