/**
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
 *
 * Copyright (c) 2006 Sun Microsystems Inc. All Rights Reserved
 *
 * The contents of this file are subject to the terms
 * of the Common Development and Distribution License
 * (the License). You may not use this file except in
 * compliance with the License.
 *
 * You can obtain a copy of the License at
 * https://opensso.dev.java.net/public/CDDLv1.0.html or
 * opensso/legal/CDDLv1.0.txt
 * See the License for the specific language governing
 * permission and limitations under the License.
 *
 * When distributing Covered Code, include this CDDL
 * Header Notice in each file and include the License file
 * at opensso/legal/CDDLv1.0.txt.
 * If applicable, add the following below the CDDL Header,
 * with the fields enclosed by brackets [] replaced by
 * your own identifying information:
 * "Portions Copyrighted [year] [name of copyright owner]"
 *
 * $Id: Assertion.java,v 1.2 2008/06/25 05:47:39 qcheng Exp $
 *
 * Portions Copyrighted 2015 ForgeRock AS.
 */


package com.sun.identity.saml2.assertion;

import java.util.Date;
import java.util.List;
import java.security.Key;
import java.security.PrivateKey;
import java.security.cert.X509Certificate;
import java.util.Set;

import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
import com.sun.identity.saml2.assertion.impl.AssertionImpl;
import com.sun.identity.saml2.common.SAML2Exception;

/**
 * The <code>Assertion</code> element is a package of information
 * that supplies one or more <code>Statement</code> made by an issuer. 
 * There are three kinds of assertions: Authentication, Authorization Decision,
 * and Attribute assertions.
 * @supported.all.api
 */
@JsonDeserialize(as=AssertionImpl.class)
public interface Assertion {

    /**
     * Returns the version number of the assertion.
     *
     * @return The version number of the assertion.
     */
    String getVersion();

    /**
     * Sets the version number of the assertion.
     *
     * @param version the version number.
     * @exception SAML2Exception if the object is immutable
     */
    void setVersion(String version) throws SAML2Exception;

    /**
     * Returns the time when the assertion was issued
     *
     * @return the time of the assertion issued
     */
    Date getIssueInstant();

    /**
     * Sets the time when the assertion was issued
     *
     * @param issueInstant the issue time of the assertion
     * @exception SAML2Exception if the object is immutable
    */
    void setIssueInstant(Date issueInstant) throws SAML2Exception;

    /**
     * Returns the subject of the assertion
     *
     * @return the subject of the assertion
     */
    Subject getSubject();

    /**
     * Sets the subject of the assertion
     *
     * @param subject the subject of the assertion
     * @exception SAML2Exception if the object is immutable
     */
    void setSubject(Subject subject) throws SAML2Exception;

    /**
     * Returns the advice of the assertion
     *
     * @return the advice of the assertion
     */
    Advice getAdvice();

    /**
     * Sets the advice of the assertion
     *
     * @param advice the advice of the assertion
     * @exception SAML2Exception if the object is immutable
     */
    void setAdvice(Advice advice) throws SAML2Exception;

    /**
     * Returns the signature of the assertion
     *
     * @return the signature of the assertion
     */
    String getSignature();

    /**
     * Returns the conditions of the assertion
     *
     * @return the conditions of the assertion
     */
    Conditions getConditions();

    /**
     * Sets the conditions of the assertion
     *
     * @param conditions the conditions of the assertion
     * @exception SAML2Exception if the object is immutable
     */
    void setConditions(Conditions conditions) throws SAML2Exception;

    /**
     * Returns the id of the assertion
     *
     * @return the id of the assertion
     */
    String getID();

    /**
     * Sets the id of the assertion
     *
     * @param id the id of the assertion
     * @exception SAML2Exception if the object is immutable
     */
    void setID(String id) throws SAML2Exception;

    /**
     * Returns the statements of the assertion
     *
     * @return the statements of the assertion
     */
    List<Object> getStatements();

    /**
     * Returns the <code>AuthnStatements</code> of the assertion
     *
     * @return the <code>AuthnStatements</code> of the assertion
     */
    List<AuthnStatement> getAuthnStatements();

    /**
     * Returns the <code>AuthzDecisionStatements</code> of the assertion
     *
     * @return the <code>AuthzDecisionStatements</code> of the assertion
     */
    List<AuthzDecisionStatement> getAuthzDecisionStatements();

    /**
     * Returns the attribute statements of the assertion
     *
     * @return the attribute statements of the assertion
     */
    List<AttributeStatement> getAttributeStatements();

    /**
     * Sets the statements of the assertion
     *
     * @param statements the statements of the assertion
     * @exception SAML2Exception if the object is immutable
     */
    void setStatements(List<Object> statements) throws SAML2Exception;

    /**
     * Sets the <code>AuthnStatements</code> of the assertion
     *
     * @param statements the <code>AuthnStatements</code> of the assertion
     * @exception SAML2Exception if the object is immutable
     */
    void setAuthnStatements(List<AuthnStatement> statements) throws SAML2Exception;

    /**
     * Sets the <code>AuthzDecisionStatements</code> of the assertion
     *
     * @param statements the <code>AuthzDecisionStatements</code> of 
     *        the assertion
     * @exception SAML2Exception if the object is immutable
     */
    void setAuthzDecisionStatements(List<AuthzDecisionStatement> statements)
        throws SAML2Exception;

    /**
     * Sets the attribute statements of the assertion
     *
     * @param statements the attribute statements of the assertion
     * @exception SAML2Exception if the object is immutable
     */
    void setAttributeStatements(List<AttributeStatement> statements) throws SAML2Exception;

    /**
     * Returns the issuer of the assertion
     *
     * @return the issuer of the assertion
     */
    Issuer getIssuer();

    /**
     * Sets the issuer of the assertion
     *
     * @param issuer the issuer of the assertion
     * @exception SAML2Exception if the object is immutable
     */
    void setIssuer(Issuer issuer) throws SAML2Exception;

    /**
     * Return true if the assertion is signed 
     *
     * @return true if the assertion is signed
     */
    boolean isSigned();

    /**
     * Return whether the signature is valid or not.
     *
     * @param verificationCerts Certificates containing the public keys which may be used for signature verification;
     *                          This certificate may also may be used to check against the certificate included in the
     *                          signature.
     * @return true if the signature is valid; false otherwise.
     * @throws SAML2Exception if the signature could not be verified
     */
    boolean isSignatureValid(Set<X509Certificate> verificationCerts)
        throws SAML2Exception;
    
    /**
     * Gets the validity of the assertion evaluating its conditions if
     * specified.
     *
     * @return false if conditions is invalid based on it lying between
     *         <code>NotBefore</code> (current time inclusive) and
     *         <code>NotOnOrAfter</code> (current time exclusive) values 
     *         and true otherwise or if no conditions specified.
     */
    boolean isTimeValid();

    /**
     * Signs the Assertion.
     *
     * @param privateKey Signing key
     * @param cert Certificate which contain the public key correlated to
     *             the signing key; It if is not null, then the signature
     *             will include the certificate; Otherwise, the signature
     *             will not include any certificate
     * @exception SAML2Exception if it could not sign the assertion.
     */
    void sign(
        PrivateKey privateKey,
        X509Certificate cert
    ) throws SAML2Exception;

    /**
     * Returns an <code>EncryptedAssertion</code> object.
     *
     * @param recipientPublicKey Public key used to encrypt the data encryption
     *                           (secret) key, it is the public key of the
     *                           recipient of the XML document to be encrypted.
     * @param dataEncAlgorithm Data encryption algorithm.
     * @param dataEncStrength Data encryption strength.
     * @param recipientEntityID Unique identifier of the recipient, it is used
     *                          as the index to the cached secret key so that
     *                          the key can be reused for the same recipient;
     *                          It can be null in which case the secret key will
     *                          be generated every time and will not be cached
     *                          and reused. Note that the generation of a secret
     *                          key is a relatively expensive operation.
     * @return <code>EncryptedAssertion</code> object
     * @throws SAML2Exception if error occurs during the encryption process.
     */
    EncryptedAssertion encrypt(
        Key recipientPublicKey,
        String dataEncAlgorithm,
        int dataEncStrength,
        String recipientEntityID
    ) throws SAML2Exception;

   /**
    * Returns a String representation
    * @param includeNSPrefix Determines whether or not the namespace qualifier
    *        is prepended to the Element when converted
    * @param declareNS Determines whether or not the namespace is declared
    *        within the Element.
    * @return A String representation
    * @exception SAML2Exception if something is wrong during conversion
     */
    String toXMLString(boolean includeNSPrefix, boolean declareNS)
     throws SAML2Exception;

   /**
    * Returns a String representation
    *
    * @return A String representation
    * @exception SAML2Exception if something is wrong during conversion
    */
    String toXMLString() throws SAML2Exception;

   /**
    * Makes the object immutable
    */
    void makeImmutable();

   /**
    * Returns true if the object is mutable
    *
    * @return true if the object is mutable
    */
    boolean isMutable();

}