Lasso Reference Manual | ||||
---|---|---|---|---|
Top | Description |
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 |
|
gchar * |
the identifier URI of this provider |
LassoProviderRole |
the role prescribed when this LassoProvider was built |
file path or content of the metadata description for this provider. | |
gchar * |
file path or content of the public key file for this provider. |
gchar * |
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.
|
provider role, identity provider or service provider |
|
path to the provider metadata file |
|
path to the provider public key file (may be a certificate) or NULL |
|
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).
unitialized value (internal use) | |
service provider. | |
identity provider. | |
service&identity provider. | |
an authentification authority, i.e. an endpoint able to return previously returned assertion, | |
an authorization authority, i.e. an endpoint able to return assertion providing authorization about a principal acessing a resource, | |
an attribute authority, i.e. an endpoint able to return attributes aboute a principal, | |
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.
|
provider role, identity provider or service provider |
|
string buffer containing a metadata file |
|
path to the provider public key file (may be a certificate) or NULL |
|
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.
|
a LassoProvider |
|
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.
|
a LassoProvider |
|
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.
|
a LassoProvider |
|
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.
|
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
.
|
a LassoProvider. [transfer none] |
|
a LassoProvider depicting the remote provider |
|
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
.
|
a LassoProvider |
|
a LassoProvider depicting the remote provider |
|
a Liberty profile type |
|
an HTTP method |
|
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.
invalid value (internal use) | |
any method will do | |
not a method, for IdP initiated profile | |
HTTP GET | |
Browser POST | |
HTTP-Redirect based | |
SOAP/HTTP based | |
Artifact by HTTP GET (SAML 2.0) | |
Artifact by HTTP POST (SAML 2.0) | |
PAOS/HTTP based (SAML 2.0) | |
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.
Federation Termination Notification | |
Name Identifier Mapping | |
Name Registration | |
Single Logout | |
Single Sign-On and Federation | |
Artifact Resolution (SAML 2.0) | |
Manage Name Identifier (SAML 2.0) | |
Assertion ID Request (SAML 2.0) | |
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
.
|
a LassoProvider |
|
a Liberty profile type |
|
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.
|
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.
|
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.
|
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_provider_get_encryption_mode ()
LassoEncryptionMode lasso_provider_get_encryption_mode (LassoProvider *provider
);
Return the current encryption mode.
|
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 to set encryption for |
|
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_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 to set encryption for |
|
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_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.
|
a LassoProvider object |
|
a LassoNode object, still having its originalXmlnode content, and containing an XML signature. |
|
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.
|
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.
|
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.
|
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.
|
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.
|
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.
|
a LassoProvider object |
|
a LassoProviderRole value |
|
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
.
|
a LassoProvider |
|
a LassoProviderRole value |
|
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.
|
a LassoProvider object |
|
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.
|
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.
|
a LassoProvider object |
|
a LassoProvider object |
Returns : |
TRUE or FALSE. |