LassoNode: lasso Reference Manual

## LassoNode LassoNode — Base class for all Lasso objects |

## Functions

LassoNode * | lasso_node_new ()
LassoNode * | lasso_node_new_from_dump ()
LassoNode * | lasso_node_new_from_soap ()
LassoNode * | lasso_node_new_from_xmlNode ()
void | lasso_node_cleanup_original_xmlnodes ()
void | lasso_node_destroy ()
char * | lasso_node_dump ()
char * | lasso_node_debug ()
char * | lasso_node_export_to_base64 ()
char * | lasso_node_export_to_query ()
char * | lasso_node_export_to_query_with_password ()
char * | lasso_node_export_to_soap ()
char * | lasso_node_export_to_soap_with_headers ()
gchar * | lasso_node_export_to_xml ()
char * | lasso_node_export_to_paos_request ()
char * | lasso_node_export_to_paos_request_full ()
char * | lasso_node_export_to_ecp_soap_response ()
xmlNode * | lasso_node_get_xmlNode ()
const char * | lasso_node_get_name ()
xmlNode * | lasso_node_get_original_xmlnode ()
void | lasso_node_set_original_xmlnode ()
void | lasso_node_set_custom_namespace ()
void | lasso_node_set_custom_nodename ()
const char * | lasso_node_get_namespace ()
LassoMessageFormat | lasso_node_init_from_message ()
gboolean | lasso_node_init_from_query ()
lasso_error_t | lasso_node_init_from_xml ()
const char * | lasso_strerror ()

## Types and Values

enum | LassoMessageFormat
enum | LassoSignatureType
enum | LassoSignatureMethod
| LassoNodeClassData
struct | LassoNode

## Object Hierarchy

        GObject
        ╰── LassoNode
            ├── LassoProfile
            ├── LassoDsKeyInfo
            ├── LassoDsKeyValue
            ├── LassoDsRsaKeyValue
            ├── LassoFederation
            ├── LassoIdentity
            ├── LassoSamlAssertion
            ├── LassoSamlStatementAbstract
            ├── LassoLibAuthnContext
            ├── LassoLibAuthnRequestEnvelope
            ├── LassoSamlpRequestAbstract
            ├── LassoLibAuthnResponseEnvelope
            ├── LassoSamlpResponseAbstract
            ├── LassoLibIDPEntries
            ├── LassoLibIDPEntry
            ├── LassoLibIDPList
            ├── LassoLibRequestAuthnContext
            ├── LassoLibScoping
            ├── LassoSamlSubject
            ├── LassoMiscTextNode
            ├── LassoProvider
            ├── LassoSaml2Action
            ├── LassoSaml2Advice
            ├── LassoSaml2Assertion
            ├── LassoSaml2Attribute
            ├── LassoSaml2StatementAbstract
            ├── LassoSaml2AttributeValue
            ├── LassoSaml2ConditionAbstract
            ├── LassoSaml2AuthnContext
            ├── LassoSaml2BaseIDAbstract
            ├── LassoSaml2Conditions
            ├── LassoSaml2EncryptedElement
            ├── LassoSaml2Evidence
            ├── LassoSaml2KeyInfoConfirmationData
            ├── LassoSaml2NameID
            ├── LassoSaml2SubjectConfirmationData
            ├── LassoSaml2SubjectConfirmation
            ├── LassoSaml2Subject
            ├── LassoSaml2SubjectLocality
            ├── LassoSamlAdvice
            ├── LassoSamlAttributeDesignator
            ├── LassoSamlAttributeValue
            ├── LassoSamlConditionAbstract
            ├── LassoSamlAuthorityBinding
            ├── LassoSamlConditions
            ├── LassoSamlNameIdentifier
            ├── LassoSamlp2RequestAbstract
            ├── LassoSamlp2StatusResponse
            ├── LassoSamlp2Extensions
            ├── LassoSamlp2IDPEntry
            ├── LassoSamlp2IDPList
            ├── LassoSamlp2NameIDPolicy
            ├── LassoSamlp2RequestedAuthnContext
            ├── LassoSamlp2Scoping
            ├── LassoSamlp2StatusCode
            ├── LassoSamlp2StatusDetail
            ├── LassoSamlp2Status
            ├── LassoSamlp2Terminate
            ├── LassoSamlpStatusCode
            ├── LassoSamlpStatus
            ├── LassoSamlSubjectConfirmation
            ├── LassoSamlSubjectLocality
            ├── LassoSession
            ├── LassoSoapBody
            ├── LassoSoapDetail
            ├── LassoSoapEnvelope
            ├── LassoSoapFault
            ╰── LassoSoapHeader

## Description

LassoNode is the base class for Lasso objects; just a step over GObject as defined in glib.

## Functions

### lasso_node_new ()

    LassoNode *
    lasso_node_new (void);

Creates a new LassoNode.

#### Returns

a newly created LassoNode object

### lasso_node_new_from_dump ()

    LassoNode *
    lasso_node_new_from_dump (const char *dump);

Restores the `dump` to a new LassoNode subclass.

#### Parameters

dump | XML object dump |

#### Returns

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

### lasso_node_new_from_soap ()

    LassoNode *
    lasso_node_new_from_soap (const char *soap);

Parses SOAP message and creates a new Lasso object with the right class.

#### Parameters

soap | the SOAP message |

#### Returns

node if success; NULL otherwise

### lasso_node_new_from_xmlNode ()

    LassoNode *
    lasso_node_new_from_xmlNode (xmlNode *node);

Builds a new LassoNode from an xmlNode.

#### Parameters

node | an xmlNode |

#### Returns

a new node

### lasso_node_cleanup_original_xmlnodes ()

    void
    lasso_node_cleanup_original_xmlnodes (LassoNode *node);

`node` : a LassoNode

Traverse the LassoNode tree starting at Node and remove keeped xmlNode if one is found.

#### Returns

None

### lasso_node_destroy ()

    void
    lasso_node_destroy (LassoNode *node);

Destroys the LassoNode.

#### Parameters

node | a LassoNode |

### lasso_node_dump ()

    char *
    lasso_node_dump (LassoNode *node);

Dumps `node` . All datas in object are dumped in an XML format.

#### Parameters

node | a LassoNode |

#### Returns

a full XML dump of `node` . The string must be freed by the caller.

[transfer full]

### lasso_node_debug ()

    char *
    lasso_node_debug (LassoNode *node,
                      int level);

Create a debug dump for `node` , it is pretty printed so any contained signature will be uncheckable.

#### Parameters

node | a LassoNode |
level | the indentation depth, i.e. the depth of the last nodes to be indented. | [default 10]

#### Returns

a full indented and so human readable dump of `node` . The string must be freed by the caller.

[transfer full]

### lasso_node_export_to_base64 ()

    char *
    lasso_node_export_to_base64 (LassoNode *node);

Exports `node` to a base64-encoded message.

#### Parameters

node | a LassoNode |

#### Returns

a base64-encoded export of `node` . The string must be freed by the caller.

### lasso_node_export_to_query ()

    char *
    lasso_node_export_to_query (LassoNode *node,
                                LassoSignatureMethod sign_method,
                                const char *private_key_file);

Exports `node` to a HTTP query string. If `private_key_file` is NULL, query won't be signed.

#### Parameters

node | a LassoNode |
sign_method | the Signature transform method. | [default 1]
private_key_file | the path to the private key (may be NULL). | [allow-none]

#### Returns

a HTTP query export of `node` . The string must be freed by the caller.

### lasso_node_export_to_query_with_password ()

    char *
    lasso_node_export_to_query_with_password
                                   (LassoNode *node,
                                    LassoSignatureMethod sign_method,
                                    const char *private_key_file,
                                    const char *private_key_file_password);

Exports `node` to a HTTP query string. If `private_key_file` is NULL, query won't be signed.

#### Parameters

node | a LassoNode |
sign_method | the Signature transform method. | [default 1]
private_key_file | the path to the private key (may be NULL). | [allow-none]
private_key_file_password | the password needed to decrypt the private key. | [allow-none]

#### Returns

a HTTP query export of `node` . The string must be freed by the caller.

### lasso_node_export_to_soap ()

    char *
    lasso_node_export_to_soap (LassoNode *node);

Exports `node` to a SOAP message.

#### Parameters

node | a LassoNode |

#### Returns

a SOAP export of `node` . The string must be freed by the caller.

### lasso_node_export_to_soap_with_headers ()

    char *
    lasso_node_export_to_soap_with_headers
                                   (LassoNode *node,
                                    GList *headers);

Exports `node` to a SOAP message. The `node` becomes the SOAP body. each header in the headers list is added to the SOAP header if non-NULL. `headers` is permitted to be an empty list (e.g. NULL).

Example 1. Create SOAP envelope with variable number of header nodes

You need to form a SOAP message with authn_request as the body and paos_request, ecp_request and ecp_relaystate as SOAP header elements. It is possible one or more of these may be NULL and should be skipped.

    char *text = NULL;
    LassoNode *paos_request = NULL;
    LassoNode *ecp_request = NULL;
    LassoNode *ecp_relaystate = NULL;
    GList *headers = NULL;

    paos_request = lasso_paos_request_new(responseConsumerURL, message_id);
    ecp_request = lasso_ecp_request_new(issuer, is_passive, provider_name, idp_list);

    lasso_list_add_new_gobject(headers, paos_request);
    lasso_list_add_new_gobject(headers, ecp_request);
    lasso_list_add_new_gobject(headers, ecp_relaystate);

    text = lasso_node_export_to_soap_with_headers(node, headers);

    lasso_release_list_of_gobjects(headers);

#### Parameters

node | a LassoNode, becomes the SOAP body |
headers | GList of LassNode. | [allow-none]

#### Returns

a SOAP export of `node` . The string must be freed by the caller.

### lasso_node_export_to_xml ()

    gchar *
    lasso_node_export_to_xml (LassoNode *node);

Exports `node` to an xml message.

#### Parameters

node | a LassoNode |

#### Returns

an xml export of `node` . The string must be freed by the caller.

### lasso_node_export_to_paos_request ()

    char *
    lasso_node_export_to_paos_request (LassoNode *node,
                                       const char *issuer,
                                       const char *responseConsumerURL,
                                       const char *relay_state);

Exports `node` to a PAOS message.

Deprecated, use `lasso_node_export_to_paos_request_full()` instead

#### Parameters

node | a LassoNode |

#### Returns

a PAOS export of `node` . The string must be freed by the caller.

### lasso_node_export_to_paos_request_full ()

    char *
    lasso_node_export_to_paos_request_full
                                   (LassoNode *node,
                                    const char *issuer,
                                    const char *responseConsumerURL,
                                    const char *message_id,
                                    const char *relay_state,
                                    gboolean is_passive,
                                    gchar *provider_name,
                                    LassoSamlp2IDPList *idp_list);

Creates a new SOAP message. The SOAP headers include a PaosRequst, a EcpRequest and optionally a EcpRelayState. The SOAP body contains the `node` parameters.

#### Parameters

message_id | . | [allow-none]
relay_state | . | [allow-none]
provider_name | . | [allow-none]
idp_list | . | [allow-none]

#### Returns

string containing a PAOS request. The string must be freed by the caller.

### lasso_node_export_to_ecp_soap_response ()

    char *
    lasso_node_export_to_ecp_soap_response
                                   (LassoNode *node,
                                    const char *assertionConsumerURL);

Exports `node` to a ECP SOAP message.

#### Parameters

node | a LassoNode |

#### Returns

a ECP SOAP export of `node` . The string must be freed by the caller.

### lasso_node_get_xmlNode ()

    xmlNode *
    lasso_node_get_xmlNode (LassoNode *node,
                            gboolean lasso_dump);

Builds an XML representation of `node` .

#### Parameters

node | a LassoNode |
lasso_dump | whether to include lasso-specific nodes |

#### Returns

a new xmlNode. It must be freed by the caller.

### lasso_node_get_name ()

    const char *
    lasso_node_get_name (LassoNode *node);

Return the XML element name for this object, the one that would be used in the XML dump of this object.

#### Parameters

node | a LassoNode |

#### Returns

the name of the object, the value must not be stored.

### lasso_node_get_original_xmlnode ()

    xmlNode *
    lasso_node_get_original_xmlnode (LassoNode *node);

Retrieve the original xmlNode eventually associated to this LassoNode.

#### Parameters

node | a LassoNode |

#### Returns

an xmlNodePtr or NULL.

[transfer none]

### lasso_node_set_original_xmlnode ()

    void
    lasso_node_set_original_xmlnode (LassoNode *node,
                                     xmlNode *xmlnode);

Set the underlying XML representation of the object.

#### Parameters

node | the LassoNode object |
xmlnode | an xmlNode |

### lasso_node_set_custom_namespace ()

    void
    lasso_node_set_custom_namespace (LassoNode *node,
                                     const char *prefix,
                                     const char *href);

Set a custom namespace for an object instance, use it with object existing a lot of revision of the nearly same namespace.

#### Parameters

node | a LassoNode object |
prefix | the prefix to use for the definition |
href | the URI of the namespace |

### lasso_node_set_custom_nodename ()

    void
    lasso_node_set_custom_nodename (LassoNode *node,
                                    const char *nodename);

Set a custom nodename for an object instance, use it with object implement a schema type and not a real element.

#### Parameters

node | a LassoNode object |
nodename | the name to use for the node |

### lasso_node_get_namespace ()

    const char *
    lasso_node_get_namespace (LassoNode *node);

### lasso_node_init_from_message ()

    LassoMessageFormat
    lasso_node_init_from_message (LassoNode *node,
                                  const char *message);

Parses `message` and initialiazes `node` fields with data from it. Message type may be base64, SOAP, XML or query string, correct type is found automatically.

#### Parameters

node | a LassoNode (or derived class) |
message | a Liberty message |

#### Returns

a LassoMessageFormat value.

### lasso_node_init_from_query ()

    gboolean
    lasso_node_init_from_query (LassoNode *node,
                                const char *query);

Initialiazes `node` fields with data from `query` string.

#### Parameters

node | a LassoNode (or derived class) |
query | the query string |

#### Returns

`TRUE` if success

### lasso_node_init_from_xml ()

    lasso_error_t
    lasso_node_init_from_xml (LassoNode *node,
                              xmlNode *xmlnode);

Initialiazes `node` fields with data from `xmlnode` XML node.

#### Parameters

node | a LassoNode (or derived class) |
xmlnode | the libxml2 node |

#### Returns

0 on success; or a negative value otherwise.

### lasso_strerror ()

    const char *
    lasso_strerror (int error_code);

Convert an error code from a lasso fuction to a human readable string.

#### Parameters

error_code | a gint error code returned by a lasso function |

#### Returns

a static string.

## Types and Values

### enum LassoMessageFormat

Return code for lasso_node_init_from_message; it describes the type of the message that was passed to that function.

#### Members

LASSO_MESSAGE_FORMAT_XSCHEMA_ERROR |  |
LASSO_MESSAGE_FORMAT_ERROR | error while determining format |
LASSO_MESSAGE_FORMAT_UNKNOWN | unknown format |
LASSO_MESSAGE_FORMAT_XML | XML |
LASSO_MESSAGE_FORMAT_BASE64 | base-64 encoded |
LASSO_MESSAGE_FORMAT_QUERY | query string |
LASSO_MESSAGE_FORMAT_SOAP | SOAP |

### enum LassoSignatureType

Signature type.

#### Members

LASSO_SIGNATURE_TYPE_NONE | no signature |
LASSO_SIGNATURE_TYPE_SIMPLE | sign with the private key, copy the public part in the signature. |
LASSO_SIGNATURE_TYPE_WITHX509 | sign with the private key, copy the associated certificat in the signature. |
LASSO_SIGNATURE_TYPE_LAST |  |

### enum LassoSignatureMethod

Signature method.

#### Members

LASSO_SIGNATURE_METHOD_NONE |  |
LASSO_SIGNATURE_METHOD_RSA_SHA1 | sign using a RSA private key |
LASSO_SIGNATURE_METHOD_DSA_SHA1 | sign using a DSA private key |
LASSO_SIGNATURE_METHOD_HMAC_SHA1 | sign using a HMAC-SHA1 secret key |
LASSO_SIGNATURE_METHOD_RSA_SHA256 | sign using a RSA private key and use SHA256 digest |
LASSO_SIGNATURE_METHOD_HMAC_SHA256 | sign using a HMAC-SHA256 secret key |
LASSO_SIGNATURE_METHOD_RSA_SHA384 | sign using a RSA private key and use SHA384 digest |
LASSO_SIGNATURE_METHOD_HMAC_SHA384 | sign using a HMAC-SHA384 secret key |
LASSO_SIGNATURE_METHOD_RSA_SHA512 | sign using a RSA private key and use SHA521 digest |
LASSO_SIGNATURE_METHOD_HMAC_SHA512 | sign using a HMAC-SHA512 secret key |
LASSO_SIGNATURE_METHOD_LAST |  |

### LassoNodeClassData

    typedef struct _LassoNodeClassData LassoNodeClassData;

### struct LassoNode

    struct LassoNode;

Base type for all XML contents, or for object using serialization to XML.