001/**
002 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003 *
004 * Copyright (c) 2006 Sun Microsystems Inc. All Rights Reserved
005 *
006 * The contents of this file are subject to the terms
007 * of the Common Development and Distribution License
008 * (the License). You may not use this file except in
009 * compliance with the License.
010 *
011 * You can obtain a copy of the License at
012 * https://opensso.dev.java.net/public/CDDLv1.0.html or
013 * opensso/legal/CDDLv1.0.txt
014 * See the License for the specific language governing
015 * permission and limitations under the License.
016 *
017 * When distributing Covered Code, include this CDDL
018 * Header Notice in each file and include the License file
019 * at opensso/legal/CDDLv1.0.txt.
020 * If applicable, add the following below the CDDL Header,
021 * with the fields enclosed by brackets [] replaced by
022 * your own identifying information:
023 * "Portions Copyrighted [year] [name of copyright owner]"
024 *
025 * $Id: Assertion.java,v 1.2 2008/06/25 05:47:39 qcheng Exp $
026 *
027 * Portions Copyrighted 2015 ForgeRock AS.
028 */
029
030
031package com.sun.identity.saml2.assertion;
032
033import java.util.Date;
034import java.util.List;
035import java.security.Key;
036import java.security.PrivateKey;
037import java.security.cert.X509Certificate;
038import java.util.Set;
039
040import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
041import com.sun.identity.saml2.assertion.impl.AssertionImpl;
042import com.sun.identity.saml2.common.SAML2Exception;
043
044/**
045 * The <code>Assertion</code> element is a package of information
046 * that supplies one or more <code>Statement</code> made by an issuer. 
047 * There are three kinds of assertions: Authentication, Authorization Decision,
048 * and Attribute assertions.
049 * @supported.all.api
050 */
051@JsonDeserialize(as=AssertionImpl.class)
052public interface Assertion {
053
054    /**
055     * Returns the version number of the assertion.
056     *
057     * @return The version number of the assertion.
058     */
059    String getVersion();
060
061    /**
062     * Sets the version number of the assertion.
063     *
064     * @param version the version number.
065     * @exception SAML2Exception if the object is immutable
066     */
067    void setVersion(String version) throws SAML2Exception;
068
069    /**
070     * Returns the time when the assertion was issued
071     *
072     * @return the time of the assertion issued
073     */
074    Date getIssueInstant();
075
076    /**
077     * Sets the time when the assertion was issued
078     *
079     * @param issueInstant the issue time of the assertion
080     * @exception SAML2Exception if the object is immutable
081    */
082    void setIssueInstant(Date issueInstant) throws SAML2Exception;
083
084    /**
085     * Returns the subject of the assertion
086     *
087     * @return the subject of the assertion
088     */
089    Subject getSubject();
090
091    /**
092     * Sets the subject of the assertion
093     *
094     * @param subject the subject of the assertion
095     * @exception SAML2Exception if the object is immutable
096     */
097    void setSubject(Subject subject) throws SAML2Exception;
098
099    /**
100     * Returns the advice of the assertion
101     *
102     * @return the advice of the assertion
103     */
104    Advice getAdvice();
105
106    /**
107     * Sets the advice of the assertion
108     *
109     * @param advice the advice of the assertion
110     * @exception SAML2Exception if the object is immutable
111     */
112    void setAdvice(Advice advice) throws SAML2Exception;
113
114    /**
115     * Returns the signature of the assertion
116     *
117     * @return the signature of the assertion
118     */
119    String getSignature();
120
121    /**
122     * Returns the conditions of the assertion
123     *
124     * @return the conditions of the assertion
125     */
126    Conditions getConditions();
127
128    /**
129     * Sets the conditions of the assertion
130     *
131     * @param conditions the conditions of the assertion
132     * @exception SAML2Exception if the object is immutable
133     */
134    void setConditions(Conditions conditions) throws SAML2Exception;
135
136    /**
137     * Returns the id of the assertion
138     *
139     * @return the id of the assertion
140     */
141    String getID();
142
143    /**
144     * Sets the id of the assertion
145     *
146     * @param id the id of the assertion
147     * @exception SAML2Exception if the object is immutable
148     */
149    void setID(String id) throws SAML2Exception;
150
151    /**
152     * Returns the statements of the assertion
153     *
154     * @return the statements of the assertion
155     */
156    List<Object> getStatements();
157
158    /**
159     * Returns the <code>AuthnStatements</code> of the assertion
160     *
161     * @return the <code>AuthnStatements</code> of the assertion
162     */
163    List<AuthnStatement> getAuthnStatements();
164
165    /**
166     * Returns the <code>AuthzDecisionStatements</code> of the assertion
167     *
168     * @return the <code>AuthzDecisionStatements</code> of the assertion
169     */
170    List<AuthzDecisionStatement> getAuthzDecisionStatements();
171
172    /**
173     * Returns the attribute statements of the assertion
174     *
175     * @return the attribute statements of the assertion
176     */
177    List<AttributeStatement> getAttributeStatements();
178
179    /**
180     * Sets the statements of the assertion
181     *
182     * @param statements the statements of the assertion
183     * @exception SAML2Exception if the object is immutable
184     */
185    void setStatements(List<Object> statements) throws SAML2Exception;
186
187    /**
188     * Sets the <code>AuthnStatements</code> of the assertion
189     *
190     * @param statements the <code>AuthnStatements</code> of the assertion
191     * @exception SAML2Exception if the object is immutable
192     */
193    void setAuthnStatements(List<AuthnStatement> statements) throws SAML2Exception;
194
195    /**
196     * Sets the <code>AuthzDecisionStatements</code> of the assertion
197     *
198     * @param statements the <code>AuthzDecisionStatements</code> of 
199     *        the assertion
200     * @exception SAML2Exception if the object is immutable
201     */
202    void setAuthzDecisionStatements(List<AuthzDecisionStatement> statements)
203        throws SAML2Exception;
204
205    /**
206     * Sets the attribute statements of the assertion
207     *
208     * @param statements the attribute statements of the assertion
209     * @exception SAML2Exception if the object is immutable
210     */
211    void setAttributeStatements(List<AttributeStatement> statements) throws SAML2Exception;
212
213    /**
214     * Returns the issuer of the assertion
215     *
216     * @return the issuer of the assertion
217     */
218    Issuer getIssuer();
219
220    /**
221     * Sets the issuer of the assertion
222     *
223     * @param issuer the issuer of the assertion
224     * @exception SAML2Exception if the object is immutable
225     */
226    void setIssuer(Issuer issuer) throws SAML2Exception;
227
228    /**
229     * Return true if the assertion is signed 
230     *
231     * @return true if the assertion is signed
232     */
233    boolean isSigned();
234
235    /**
236     * Return whether the signature is valid or not.
237     *
238     * @param verificationCerts Certificates containing the public keys which may be used for signature verification;
239     *                          This certificate may also may be used to check against the certificate included in the
240     *                          signature.
241     * @return true if the signature is valid; false otherwise.
242     * @throws SAML2Exception if the signature could not be verified
243     */
244    boolean isSignatureValid(Set<X509Certificate> verificationCerts)
245        throws SAML2Exception;
246    
247    /**
248     * Gets the validity of the assertion evaluating its conditions if
249     * specified.
250     *
251     * @return false if conditions is invalid based on it lying between
252     *         <code>NotBefore</code> (current time inclusive) and
253     *         <code>NotOnOrAfter</code> (current time exclusive) values 
254     *         and true otherwise or if no conditions specified.
255     */
256    boolean isTimeValid();
257
258    /**
259     * Signs the Assertion.
260     *
261     * @param privateKey Signing key
262     * @param cert Certificate which contain the public key correlated to
263     *             the signing key; It if is not null, then the signature
264     *             will include the certificate; Otherwise, the signature
265     *             will not include any certificate
266     * @exception SAML2Exception if it could not sign the assertion.
267     */
268    void sign(
269        PrivateKey privateKey,
270        X509Certificate cert
271    ) throws SAML2Exception;
272
273    /**
274     * Returns an <code>EncryptedAssertion</code> object.
275     *
276     * @param recipientPublicKey Public key used to encrypt the data encryption
277     *                           (secret) key, it is the public key of the
278     *                           recipient of the XML document to be encrypted.
279     * @param dataEncAlgorithm Data encryption algorithm.
280     * @param dataEncStrength Data encryption strength.
281     * @param recipientEntityID Unique identifier of the recipient, it is used
282     *                          as the index to the cached secret key so that
283     *                          the key can be reused for the same recipient;
284     *                          It can be null in which case the secret key will
285     *                          be generated every time and will not be cached
286     *                          and reused. Note that the generation of a secret
287     *                          key is a relatively expensive operation.
288     * @return <code>EncryptedAssertion</code> object
289     * @throws SAML2Exception if error occurs during the encryption process.
290     */
291    EncryptedAssertion encrypt(
292        Key recipientPublicKey,
293        String dataEncAlgorithm,
294        int dataEncStrength,
295        String recipientEntityID
296    ) throws SAML2Exception;
297
298   /**
299    * Returns a String representation
300    * @param includeNSPrefix Determines whether or not the namespace qualifier
301    *        is prepended to the Element when converted
302    * @param declareNS Determines whether or not the namespace is declared
303    *        within the Element.
304    * @return A String representation
305    * @exception SAML2Exception if something is wrong during conversion
306     */
307    String toXMLString(boolean includeNSPrefix, boolean declareNS)
308     throws SAML2Exception;
309
310   /**
311    * Returns a String representation
312    *
313    * @return A String representation
314    * @exception SAML2Exception if something is wrong during conversion
315    */
316    String toXMLString() throws SAML2Exception;
317
318   /**
319    * Makes the object immutable
320    */
321    void makeImmutable();
322
323   /**
324    * Returns true if the object is mutable
325    *
326    * @return true if the object is mutable
327    */
328    boolean isMutable();
329
330}