LassoServer: Lasso Reference Manual

## LassoServer LassoServer — Representation of the current server |

## Functions

LassoServer * | lasso_server_new ()
LassoServer * | lasso_server_new_from_buffers ()
LassoServer * | lasso_server_new_from_dump ()
lasso_error_t | lasso_server_add_provider ()
lasso_error_t | lasso_server_add_provider2 ()
lasso_error_t | lasso_server_add_provider_from_buffer ()
lasso_error_t | lasso_server_load_metadata ()
void | lasso_server_destroy ()
gchar * | lasso_server_dump ()
LassoProvider * | lasso_server_get_provider ()
lasso_error_t | lasso_server_set_encryption_private_key ()
lasso_error_t | lasso_server_set_encryption_private_key_with_password ()
lasso_error_t | lasso_server_load_affiliation ()
gchar * | lasso_server_get_endpoint_url_by_id ()
GList * | lasso_server_get_filtered_provider_list ()
lasso_error_t | lasso_server_saml2_assertion_setup_signature ()

## Types and Values

struct | LassoServer

## Description

It holds the data about a provider, other providers it knows, which certificates to use, etc.

## Functions

### lasso_server_new ()

    LassoServer *
    lasso_server_new (const gchar *metadata,
                      const gchar *private_key,
                      const gchar *private_key_password,
                      const gchar *certificate);

Creates a new LassoServer.

#### Parameters

metadata | path to the provider metadata file or NULL, for a LECP server |
private_key | path to the the server private key file or NULL. | [allow-none]
private_key_password | password to private key if it is encrypted, or NULL. | [allow-none]
certificate | path to the server certificate file, or NULL. | [allow-none]

#### Returns

a newly created LassoServer object; or NULL if an error occured

### lasso_server_new_from_buffers ()

    LassoServer *
    lasso_server_new_from_buffers (const gchar *metadata,
                                   const gchar *private_key_content,
                                   const gchar *private_key_password,
                                   const gchar *certificate_content);

Creates a new LassoServer.

#### Parameters

metadata | NULL terminated string containing the content of an ID-FF 1.2 metadata file |
private_key_content | NULL terminated string containing a PEM formatted private key. | [allow-none]
private_key_password | a NULL terminated string which is the optional password of the private key. | [allow-none]
certificate_content | NULL terminated string containing a PEM formatted X509 certificate. | [allow-none]

#### Returns

a newly created LassoServer object; or NULL if an error occured

### lasso_server_new_from_dump ()

    LassoServer *
    lasso_server_new_from_dump (const gchar *dump);

Restores the `dump` to a new LassoServer.

#### Parameters

dump | XML server dump |

#### Returns

a newly created LassoServer; or NULL if an error occured

### lasso_server_add_provider ()

    lasso_error_t
    lasso_server_add_provider (LassoServer *server,
                               LassoProviderRole role,
                               const gchar *metadata,
                               const gchar *public_key,
                               const gchar *ca_cert_chain);

Creates a new LassoProvider and makes it known to the `server`

#### Parameters

server | a LassoServer |
role | provider role, identity provider or service provider |
metadata | path to the provider metadata file |
public_key | provider public key file (may be a certificate) or NULL. | [allow-none]
ca_cert_chain | provider CA certificate chain file or NULL. | [allow-none]

#### Returns

0 on success; a negative value if an error occured.

### lasso_server_add_provider2 ()

    lasso_error_t
    lasso_server_add_provider2 (LassoServer *server,
                                LassoProvider *provider);

Add `provider` to the list of known providers object of `server` .

Return 0 if successful, LASSO_PARAM_ERROR_BAD_TYPE_OR_NULL_OBJ otherwise.

#### Parameters

server | a LassoServer object |
provider | a LassoProvider object |

### lasso_server_add_provider_from_buffer ()

    lasso_error_t
    lasso_server_add_provider_from_buffer (LassoServer *server,
                                           LassoProviderRole role,
                                           const gchar *metadata,
                                           const gchar *public_key,
                                           const gchar *ca_cert_chain);

Creates a new LassoProvider and makes it known to the `server`

#### Parameters

server | a LassoServer |
role | provider role, identity provider or service provider |
metadata | a string buffer containg the metadata file for a new provider |
public_key | provider public key file (may be a certificate) or NULL. | [allow-none]
ca_cert_chain | provider CA certificate chain file or NULL. | [allow-none]

#### Returns

0 on success; a negative value if an error occured.

### lasso_server_load_metadata ()

    lasso_error_t
    lasso_server_load_metadata (LassoServer *server,
                                LassoProviderRole role,
                                const gchar *federation_file,
                                const gchar *trusted_roots,
                                GList *blacklisted_entity_ids,
                                GList **loaded_entity_ids,
                                LassoServerLoadMetadataFlag flags);

Load all the SAML 2.0 entities from `federation_file` which contains a declaration for `role` . If `trusted_roots` is non-NULL, use it to check a signature on the metadata file, otherwise ignore signature validation.

#### Parameters

server | a LassoServer object |
role | a LassoProviderRole value |
federation_file | path to a SAML 2.0 metadata file |
trusted_roots | a PEM encoded files containing the certificates to check signatures on the metadata file (optional). | [allow-none]
blacklisted_entity_ids | a list of EntityID which should not be loaded, can be NULL. | [allow-none][element-type string]
loaded_entity_ids | an output parameter for the list of the loaded EntityID, can be NULL. | [transfer full][element-type string][allow-none]
flags | flags modifying the behaviour for checking signatures on EntityDescriptor and EntitiesDescriptors nodes. |

#### Returns

0 on success, an error code otherwise, among:

- LASSO_PARAM_ERROR_BAD_TYPE_OR_NULL_OBJ if server is not a LassoServer object or `role` is not a valid role value,

- LASSO_DS_ERROR_CA_CERT_CHAIN_LOAD_FAILED if the `trusted_root` file cannot be loaded,

### lasso_server_destroy ()

    void
    lasso_server_destroy (LassoServer *server);

Destroys a server.

#### Parameters

server | a LassoServer |

### lasso_server_dump ()

    gchar *
    lasso_server_dump (LassoServer *server);

Dumps `server` content to an XML string.

#### Parameters

server | a LassoServer |

#### Returns

the dump string. It must be freed by the caller.

[transfer full]

### lasso_server_get_provider ()

    LassoProvider *
    lasso_server_get_provider (const LassoServer *server,
                               const gchar *providerID);

Looks up for a LassoProvider whose ID is `providerID` and returns it.

#### Parameters

server | a LassoServer |
providerID | the provider ID |

#### Returns

the LassoProvider, NULL if it was not found. The LassoProvider is owned by Lasso and should not be freed.

[transfer none]

### lasso_server_set_encryption_private_key ()

    lasso_error_t
    lasso_server_set_encryption_private_key
                                   (LassoServer *server,
                                    const gchar *filename_or_buffer);

`lasso_server_set_encryption_private_key` has been deprecated since version 2.3 and should not be used in newly-written code.

Use `lasso_server_set_encryption_private_key_with_password()` instead.

Load an encryption private key from a file and set it in the server object

If `filename_or_buffer` is NULL, it frees the currently setted key.

#### Parameters

server | a LassoServer |
filename_or_buffer | file name of the encryption key to load or its content as a NULL-terminated string. | [allow-none]

#### Returns

0 on success; another value if an error occured.

### lasso_server_set_encryption_private_key_with_password ()

    lasso_error_t
    lasso_server_set_encryption_private_key_with_password
                                   (LassoServer *server,
                                    const gchar *filename_or_buffer,
                                    const gchar *password);

Load an encryption private key from a file and set it in the server object. If `password` is non-NULL try to decrypt the key with it.

If `filename_or_buffer` is NULL, it frees the currently setted key.

#### Parameters

server | a LassoServer |
filename_or_buffer | file name of the encryption key to load or its content as a NULL-terminated string. | [allow-none]
password | an optional password to decrypt the encryption key. | [allow-none]

#### Returns

0 on success; another value if an error occured.

Since: 2.3

### lasso_server_load_affiliation ()

    lasso_error_t
    lasso_server_load_affiliation (LassoServer *server,
                                   const gchar *filename);

Load an affiliation metadata file into `server` ; this must be called after providers have been added to `server` .

#### Parameters

server | a LassoServer |
filename | file name of the affiliation metadata to load |

#### Returns

0 on success; another value if an error occured.

### lasso_server_get_endpoint_url_by_id ()

    gchar *
    lasso_server_get_endpoint_url_by_id (const LassoServer *server,
                                         const gchar *provider_id,
                                         const gchar *endpoint_description);

Locate the provider in the server's list of providers, then select an endpoint given the `endpoint_description` and return than endpoint's URL. If the provider cannot be found or if the provider does not have a matching endpoint NULL will be returned.

#### Parameters

server | a LassoServer |
provider_id | the EntityID whose endpoints will be examined. |
endpoint_description | string describing criteria used to select endpoint. |

#### Returns

url (must be freed by caller)

### lasso_server_get_filtered_provider_list ()

    GList *
    lasso_server_get_filtered_provider_list
                                   (const LassoServer *server,
                                    LassoProviderRole role,
                                    LassoMdProtocolType protocol_type,
                                    LassoHttpMethod http_method);

Iterate over the `server` providers and build a list of provider EntityID's who have the specified `role` and at least one endpoint matching the `protocol_type` and `http_method` . Return a GList list of EntityID's at the `provider_list` pointer. The caller is responsible for freeing the `provider_list` by calling `lasso_release_list_of_strings()`.

#### Parameters

server | a LassoServer |
role | each returned provider will match this LassoProviderRole |
protocol_type | provider must have endpoint matching LassoMdProtocolType and `http_method` |
http_method | provider must have endpoint matching LassoHttpMethod and `protocol_type` |

#### Returns

GList of matching provider EntityID's returned here.

[transfer full][element-type string]

### lasso_server_saml2_assertion_setup_signature ()

    lasso_error_t
    lasso_server_saml2_assertion_setup_signature
                                   (LassoServer *server,
                                    LassoSaml2Assertion *saml2_assertion);

Configure signature on a saml2:Assertion element.

#### Parameters

server | a LassoServer object |
saml2_assertion | a LassoSaml2Assertion object |

#### Returns

0 if successfull, an error code otherwise.

## Types and Values

### struct LassoServer

    struct LassoServer {
    	LassoProvider parent;

    	GHashTable *providers; /* of LassoProvider */
    	/* Can actually contain LassoDataService or LassoIdWsf2DataService or any subclass */

    	gchar *private_key;
    	gchar *private_key_password;
    	gchar *certificate;
    	LassoSignatureMethod signature_method;
    };