LassoSaml2Assertion

## LassoSaml2Assertion LassoSaml2Assertion — <saml2:Assertion> |

## Synopsis

    struct              LassoSaml2Assertion;
    enum                LassoSaml2AssertionValidationState;
    #define             LASSO_DURATION_DAY
    #define             LASSO_DURATION_HOUR
    #define             LASSO_DURATION_MINUTE
    #define             LASSO_DURATION_WEEK
    LassoNode *         lasso_saml2_assertion_new           (void);
    gboolean            lasso_saml2_assertion_has_audience_restriction
                                                            (LassoSaml2Assertion *saml2_assertion);
    gboolean            lasso_saml2_assertion_is_audience_restricted
                                                            (LassoSaml2Assertion *saml2_assertion,
                                                             char *providerID);
    void                lasso_saml2_assertion_set_subject_name_id
                                                            (LassoSaml2Assertion *saml2_assertion,
                                                             LassoNode *node);
    void                lasso_saml2_assertion_set_subject_confirmation_name_id
                                                            (LassoSaml2Assertion *saml2_assertion,
                                                             LassoNode *node);
    LassoSaml2SubjectConfirmationData * lasso_saml2_assertion_get_subject_confirmation_data
                                                            (LassoSaml2Assertion *saml2_assertion,
                                                             gboolean create);
    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);
    void                lasso_saml2_assertion_set_basic_conditions
                                                            (LassoSaml2Assertion *saml2_assertion,
                                                             time_t tolerance,
                                                             time_t length,
                                                             gboolean one_time_use);
    void                lasso_saml2_assertion_add_audience_restriction
                                                            (LassoSaml2Assertion *saml2_assertion,
                                                             const char *providerID);
    void                lasso_saml2_assertion_add_proxy_limit
                                                            (LassoSaml2Assertion *saml2_assertion,
                                                             int proxy_count,
                                                             GList *proxy_audiences);
    LassoSaml2AssertionValidationState lasso_saml2_assertion_validate_conditions
                                                            (LassoSaml2Assertion *saml2_assertion,
                                                             const char *relaying_party_providerID);
    LassoSaml2AssertionValidationState lasso_saml2_assertion_validate_time_checks
                                                            (LassoSaml2Assertion *saml2_assertion,
                                                             unsigned int tolerance,
                                                             time_t now);
    LassoSaml2AssertionValidationState lasso_saml2_assertion_validate_audience
                                                            (LassoSaml2Assertion *saml2_assertion,
                                                             const gchar *audience);
    LassoSaml2AssertionValidationState lasso_saml2_assertion_allows_proxying
                                                            (LassoSaml2Assertion *saml2_assertion);
    LassoSaml2AssertionValidationState lasso_saml2_assertion_allows_proxying_to
                                                            (LassoSaml2Assertion *saml2_assertion,
                                                             const char *audience);
    LassoProvider *     lasso_saml2_assertion_get_issuer_provider
                                                            (const LassoSaml2Assertion *saml2_assertion,
                                                             const LassoServer *server);
    lasso_error_t       lasso_saml2_assertion_add_attribute_with_node
                                                            (LassoSaml2Assertion *assertion,
                                                             const char *name,
                                                             const char *nameformat,
                                                             LassoNode *content);
    const char *        lasso_saml2_assertion_get_in_response_to
                                                            (LassoSaml2Assertion *assertion);
    lasso_error_t       lasso_saml2_assertion_decrypt_subject
                                                            (LassoSaml2Assertion *assertion,
                                                             LassoServer *server);
    gboolean            lasso_saml2_assertion_has_one_time_use
                                                            (LassoSaml2Assertion *saml2_assertion);
    void                lasso_saml2_assertion_set_one_time_use
                                                            (LassoSaml2Assertion *saml2_assertion,
                                                             gboolean one_time_use);

## Description

Figure 44. 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>

## Details

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

    typedef enum {
    	LASSO_SAML2_ASSERTION_VALID,
    	LASSO_SAML2_ASSERTION_INVALID,
    	LASSO_SAML2_ASSERTION_INDETERMINATE
    } LassoSaml2AssertionValidationState;

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

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

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

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

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

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

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

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

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

`saml2_assertion` : | a LassoSaml2Assertion object
`relaying_party_providerID:(allow-none)` : | the providerID of the current relaying party, use to check for audience restrictions.
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.

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

`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).

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

`saml2_assertion` : | a LassoSaml2Assertion object
`audience:(allow-none)` : | the relaying party which we want to proxy to
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.

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

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

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

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

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

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