LassoSaml2Assertion: Lasso Reference Manual

## LassoSaml2Assertion LassoSaml2Assertion — <saml2:Assertion> |

## Functions

LassoNode * | lasso_saml2_assertion_new ()
gboolean | lasso_saml2_assertion_has_audience_restriction ()
gboolean | lasso_saml2_assertion_is_audience_restricted ()
void | lasso_saml2_assertion_set_subject_name_id ()
void | lasso_saml2_assertion_set_subject_confirmation_name_id ()
LassoSaml2SubjectConfirmationData * | lasso_saml2_assertion_get_subject_confirmation_data ()
void | lasso_saml2_assertion_set_subject_confirmation_data ()
void | lasso_saml2_assertion_set_basic_conditions ()
void | lasso_saml2_assertion_add_audience_restriction ()
void | lasso_saml2_assertion_add_proxy_limit ()
LassoSaml2AssertionValidationState | lasso_saml2_assertion_validate_conditions ()
LassoSaml2AssertionValidationState | lasso_saml2_assertion_validate_time_checks ()
LassoSaml2AssertionValidationState | lasso_saml2_assertion_validate_audience ()
LassoSaml2AssertionValidationState | lasso_saml2_assertion_allows_proxying ()
LassoSaml2AssertionValidationState | lasso_saml2_assertion_allows_proxying_to ()
LassoProvider * | lasso_saml2_assertion_get_issuer_provider ()
lasso_error_t | lasso_saml2_assertion_add_attribute_with_node ()
const char * | lasso_saml2_assertion_get_in_response_to ()
lasso_error_t | lasso_saml2_assertion_decrypt_subject ()
gboolean | lasso_saml2_assertion_has_one_time_use ()
void | lasso_saml2_assertion_set_one_time_use ()

## Types and Values

struct | LassoSaml2Assertion
enum | LassoSaml2AssertionValidationState
#define | LASSO_DURATION_DAY
#define | LASSO_DURATION_HOUR
#define | LASSO_DURATION_MINUTE
#define | LASSO_DURATION_WEEK

## Description

Figure 46. Schema fragment for saml2:Assertion

    <complexType name="AssertionType">
      <sequence>
        <element ref="saml:Issuer"/>
        <element ref="ds:Signature" minOccurs="0"/>
        <element ref="saml:Subject" minOccurs="0"/>
        <element ref="saml:Conditions" minOccurs="0"/>
        <element ref="saml:Advice" minOccurs="0"/>
        <choice minOccurs="0" maxOccurs="unbounded">
          <element ref="saml:Statement"/>
          <element ref="saml:AuthnStatement"/>
          <element ref="saml:AuthzDecisionStatement"/>
          <element ref="saml:AttributeStatement"/>
        </choice>
      </sequence>
      <attribute name="Version" type="string" use="required"/>
      <attribute name="ID" type="ID" use="required"/>
      <attribute name="IssueInstant" type="dateTime" use="required"/>
    </complexType>

## Functions

### lasso_saml2_assertion_new ()

    LassoNode *
    lasso_saml2_assertion_new (void);

Creates a new LassoSaml2Assertion object.

#### Returns

a newly created LassoSaml2Assertion object

### lasso_saml2_assertion_has_audience_restriction ()

    gboolean
    lasso_saml2_assertion_has_audience_restriction
                                   (LassoSaml2Assertion *saml2_assertion);

Verify that a LassoSaml2AudienceRestriction is present in the assertion.

#### Parameters

saml2_assertion | a LassoSaml2Assertion object |

#### Returns

TRUE if a LassoSaml2AudienceRestriction is present in the Conditions of the LassoSaml2Assertion.

### lasso_saml2_assertion_is_audience_restricted ()

    gboolean
    lasso_saml2_assertion_is_audience_restricted
                                   (LassoSaml2Assertion *saml2_assertion,
                                    char *providerID);

Verify that the assertion is restricted to the given providerID.

#### Parameters

saml2_assertion | a LassoSaml2Assertion object |
providerID | the providerID that will be compared to the audience restriction declarations. |

#### Returns

TRUE if `providerID` is part of a LassoSaml2AudienceRestriction element in the assertion, FALSE otherwise.

### lasso_saml2_assertion_set_subject_name_id ()

    void
    lasso_saml2_assertion_set_subject_name_id
                                   (LassoSaml2Assertion *saml2_assertion,
                                    LassoNode *node);

Set the subject NameID, which can be a simple LassoSaml2NameID object or an encrypted LassoSaml2NameID as a LassoSaml2EncryptedElement.

#### Parameters

saml2_assertion | a LassoSaml2Assertion object |
node | a LassoSaml2NameID or LassoSaml2EncryptedElement |

### lasso_saml2_assertion_set_subject_confirmation_name_id ()

    void
    lasso_saml2_assertion_set_subject_confirmation_name_id
                                   (LassoSaml2Assertion *saml2_assertion,
                                    LassoNode *node);

Set the subject NameID, which can be a simple LassoSaml2NameID object or an encrypted LassoSaml2NameID as a LassoSaml2EncryptedElement.

#### Parameters

saml2_assertion | a LassoSaml2Assertion object |
node | a LassoSaml2NameID or LassoSaml2EncryptedElement |

### lasso_saml2_assertion_get_subject_confirmation_data ()

    LassoSaml2SubjectConfirmationData *
    lasso_saml2_assertion_get_subject_confirmation_data
                                   (LassoSaml2Assertion *saml2_assertion,
                                    gboolean create);

### lasso_saml2_assertion_set_subject_confirmation_data ()

    void
    lasso_saml2_assertion_set_subject_confirmation_data
                                   (LassoSaml2Assertion *saml2_assertion,
                                    time_t tolerance,
                                    time_t length,
                                    const char *Recipient,
                                    const char *InResponseTo,
                                    const char *Address);

### lasso_saml2_assertion_set_basic_conditions ()

    void
    lasso_saml2_assertion_set_basic_conditions
                                   (LassoSaml2Assertion *saml2_assertion,
                                    time_t tolerance,
                                    time_t length,
                                    gboolean one_time_use);

Set conditions limiting usage of the assertion.

`tolerance` and `length` are time quantity measured in seconds, it defines the time range in which the assertion is valid, it is computed as [`now()`-tolerance, `now()`+length+tolerance]. `one_time_use` allows the issuer to limit caching of the assertion. `proxy_count` specify how many proxy hop can be traversed before this assertion should lose any trust.

#### Parameters

tolerance | tolerance to the range of time when the assertion is valid. | [default -1]
length | length of the range of time when the assertion is valid. | [default -1]
one_time_use | can the assertion be kept or should it be used immediately. | [default FALSE]

### lasso_saml2_assertion_add_audience_restriction ()

    void
    lasso_saml2_assertion_add_audience_restriction
                                   (LassoSaml2Assertion *saml2_assertion,
                                    const char *providerID);

Add an audience restriction to a LassoSaml2Assertion.

#### Parameters

saml2_assertion | a LassoSaml2Assertion object |
providerId | the provider id to restrict audience to |

### lasso_saml2_assertion_add_proxy_limit ()

    void
    lasso_saml2_assertion_add_proxy_limit (LassoSaml2Assertion *saml2_assertion,
                                           int proxy_count,
                                           GList *proxy_audiences);

A LassoSaml2ProxyRestriction to the conditions of consumption of `saml2_assertion` .

#### Parameters

saml2_assertion | a LassoSaml2Assertion object |
proxy_count | the number of hops in the proxy chain, a negative value means no limitation. | [default -1]
proxy_audiences | a list of audience restriction for newly issued assertion based on the `saml2_assertion` assertion. An empty list means no audience restriction. | [allow-none][element-type string]

### lasso_saml2_assertion_validate_conditions ()

    LassoSaml2AssertionValidationState
    lasso_saml2_assertion_validate_conditions
                                   (LassoSaml2Assertion *saml2_assertion,
                                    const char *relaying_party_providerID);

Check the validation of the assertion with respect to the conditions of consumption that it contains. System functions are used for getting current time and checking eventual time constraints.

#### Parameters

saml2_assertion | a LassoSaml2Assertion object |
relaying_party_providerID | the providerID of the current relaying party, use to check for audience restrictions. | [allow-none]

#### Returns

LASSO_SAML2_ASSERTION_VALID if the assertion is valid, LASSO_SAML2_ASSERTION_INVALID is some check failed, LASSO_SAML2_ASSERTION_INDETERMINATE if somehting was impossible to eveluate.

### lasso_saml2_assertion_validate_time_checks ()

    LassoSaml2AssertionValidationState
    lasso_saml2_assertion_validate_time_checks
                                   (LassoSaml2Assertion *saml2_assertion,
                                    unsigned int tolerance,
                                    time_t now);

Check if the `saml2_assertion` conditions about NotBefore and NotOnOrAfter are valid with respect to the `now` time or the current time. `tolerance` allows to loosely check for validatity, i.e. start time is decreased of `tolerance` seconds and end time is increased of `tolerance` seconds.

#### Parameters

saml2_assertion | a LassoSaml2Assertion object |
tolerance | a duration as seconds |
now | the current time as seconds since EPOCH or 0 to use the system time. | [default 0]

#### Returns

a value among LassoSaml2AssertionValidationState.

### lasso_saml2_assertion_validate_audience ()

    LassoSaml2AssertionValidationState
    lasso_saml2_assertion_validate_audience
                                   (LassoSaml2Assertion *saml2_assertion,
                                    const gchar *audience);

Check if the `saml2_assertion` is directed to a given `audience` .

#### Parameters

saml2_assertion | a LassoSaml2Assertion object |
audience | the name of an entity |

#### Returns

a value among LassoSaml2AssertionValidationState enumeration.

### lasso_saml2_assertion_allows_proxying ()

    LassoSaml2AssertionValidationState
    lasso_saml2_assertion_allows_proxying (LassoSaml2Assertion *saml2_assertion);

Test whether this `saml2_assertion` allows to mint new assertion on the basis of it.

It verifies that the proxying count is positive (or absent).

#### Parameters

saml2_assertion | a LassoSaml2Assertion object |

#### Returns

a value among LassoSaml2AssertionValidationState enumeration. LASSO_SAML2_ASSERTION_INDETERMINATE usually means that an element was not conform to the XML Schema for SAML 2.0.

### lasso_saml2_assertion_allows_proxying_to ()

    LassoSaml2AssertionValidationState
    lasso_saml2_assertion_allows_proxying_to
                                   (LassoSaml2Assertion *saml2_assertion,
                                    const char *audience);

Test whether this `saml2_assertion` allows to mint new assertion on the basis of it targetted for `audience`.

It verifies that if `audience` is non-NULL it is part of the proxy Audience restriction. If `audience` is NULL, it checks that no proxying Audience restriction is present.

#### Parameters

saml2_assertion | a LassoSaml2Assertion object |
audience | the relaying party which we want to proxy to. | [allow-none]

#### Returns

a value among LassoSaml2AssertionValidationState enumeration. LASSO_SAML2_ASSERTION_INDETERMINATE usually means that an element was not conform to the XML Schema for SAML 2.0.

### lasso_saml2_assertion_get_issuer_provider ()

    LassoProvider *
    lasso_saml2_assertion_get_issuer_provider
                                   (const LassoSaml2Assertion *saml2_assertion,
                                    const LassoServer *server);

Return the LassoProvider object for the provider who created this assertion.

#### Parameters

saml2_assertion | a LassoSaml2 assertion |
server | a LassoServer object |

#### Returns

a LassoProvider object, or NULL if the Issuer element is missing, or the given provider unknown to the LassoServer object.

### lasso_saml2_assertion_add_attribute_with_node ()

    lasso_error_t
    lasso_saml2_assertion_add_attribute_with_node
                                   (LassoSaml2Assertion *assertion,
                                    const char *name,
                                    const char *nameformat,
                                    LassoNode *content);

Add a new attribute declaration and set this node as the content.

#### Parameters

assertion | a LassoSaml2Assertion object |
name | the attribute name |
name_format | the attribute name format (the namespace of the name) |
content | a LassoNode object to put as content of the attribute |

#### Returns

0 if successful, an error code otherwise.

### lasso_saml2_assertion_get_in_response_to ()

    const char *
    lasso_saml2_assertion_get_in_response_to
                                   (LassoSaml2Assertion *assertion);

Return the ID of the request this assertion respond to.

#### Parameters

assertion | a LassoSaml2Assertion object |

#### Returns

the InResponseTo attribute content of the SubjectConfirmationData if found

### lasso_saml2_assertion_decrypt_subject ()

    lasso_error_t
    lasso_saml2_assertion_decrypt_subject (LassoSaml2Assertion *assertion,
                                           LassoServer *server);

Decipher (if needed) the EncryptedID of the Subject.

#### Parameters

assertion | a LassoSaml2Assertion object |
server | a LassoServer object |

#### Returns

0 if successful, an error code otherwise. See `lasso_saml2_encrypted_element_server_decrypt()`.

### lasso_saml2_assertion_has_one_time_use ()

    gboolean
    lasso_saml2_assertion_has_one_time_use
                                   (LassoSaml2Assertion *saml2_assertion);

Return whether this assertion has the OneTimeUse property.

In this case the relaying party must add the assertion ID to a OneTimeUser cache and discards any assertion received in the future with the same ID.

#### Parameters

saml2_assertion | a LassoSaml2Assertion object |

#### Returns

TRUE if this assertion has the property OneTimeUse, FALSE otherwise.

### lasso_saml2_assertion_set_one_time_use ()

    void
    lasso_saml2_assertion_set_one_time_use
                                   (LassoSaml2Assertion *saml2_assertion,
                                    gboolean one_time_use);

Set the one time use condition on this assertion.

#### Parameters

saml2_assertion | a LassoSaml2Assertion object |
one_time_use | is this assertion to be used one time only ? |

## Types and Values

### struct LassoSaml2Assertion

    struct LassoSaml2Assertion {
    	LassoNode parent;

    	/* elements */
    	LassoSaml2NameID *Issuer;
    	LassoSaml2Subject *Subject;
    	LassoSaml2Conditions *Conditions;
    	LassoSaml2Advice *Advice;
    	GList *Statement; /* of LassoSaml2StatementAbstract */
    	GList *AuthnStatement; /* of LassoSaml2AuthnStatement */
    	GList *AuthzDecisionStatement; /* of LassoSaml2AuthzDecisionStatement */
    	GList *AttributeStatement; /* of LassoSaml2AttributeStatement */
    	/* attributes */
    	char *Version;
    	char *ID;
    	char *IssueInstant;
    };

### enum LassoSaml2AssertionValidationState

#### Members

LASSO_SAML2_ASSERTION_VALID |  |
LASSO_SAML2_ASSERTION_INVALID |  |
LASSO_SAML2_ASSERTION_INDETERMINATE |  |

### LASSO_DURATION_DAY

    #define LASSO_DURATION_DAY 24*LASSO_DURATION_HOUR

Number of seconds in a day.

### LASSO_DURATION_HOUR

    #define LASSO_DURATION_HOUR 3600

Number of seconds in a hour.

### LASSO_DURATION_MINUTE

    #define LASSO_DURATION_MINUTE 60

Number of seconds in a minute.

### LASSO_DURATION_WEEK

    #define LASSO_DURATION_WEEK 7*LASSO_DURATION_DAY

Number of seconds in a week.