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: StatusResponse.java,v 1.2 2008/06/25 05:47:58 qcheng Exp $
026 *
027 * Portions Copyrighted 2015 ForgeRock AS.
028 */
029package com.sun.identity.saml2.protocol;
030
031import com.sun.identity.saml.xmlsig.XMLSignatureException;
032import com.sun.identity.saml2.assertion.Issuer;
033import com.sun.identity.saml2.common.SAML2Exception;
034import java.security.PublicKey;
035import java.security.Signature;
036import java.util.Date;
037import java.security.PrivateKey;
038import java.security.cert.X509Certificate;
039import java.util.Set;
040
041import com.sun.identity.saml2.xmlsig.SigManager;
042
043/**
044 * This class represents the <code>StatusResponseType</code> complex type in
045 * SAML protocol schema.
046 * All SAML responses are of types that are derived from the
047 * <code>StatusResponseType</code> complex type. This type defines common
048 * attributes and elements that are associated with all SAML responses.
049 *
050 * <pre>
051 * &lt;complexType name="StatusResponseType">
052 *   &lt;complexContent>
053 *     &lt;restriction base="{http://www.w3.org/2001/XMLSchema}anyType">
054 *       &lt;sequence>
055 *         &lt;element ref="{urn:oasis:names:tc:SAML:2.0:assertion}Issuer" minOccurs="0"/>
056 *         &lt;element ref="{http://www.w3.org/2000/09/xmldsig#}Signature" minOccurs="0"/>
057 *         &lt;element ref="{urn:oasis:names:tc:SAML:2.0:protocol}Extensions" minOccurs="0"/>
058 *         &lt;element ref="{urn:oasis:names:tc:SAML:2.0:protocol}Status"/>
059 *       &lt;/sequence>
060 *       &lt;attribute name="Consent" type="{http://www.w3.org/2001/XMLSchema}anyURI" />
061 *       &lt;attribute name="Destination" type="{http://www.w3.org/2001/XMLSchema}anyURI" />
062 *       &lt;attribute name="ID" use="required" type="{http://www.w3.org/2001/XMLSchema}ID" />
063 *       &lt;attribute name="InResponseTo" type="{http://www.w3.org/2001/XMLSchema}NCName" />
064 *       &lt;attribute name="IssueInstant" use="required" type="{http://www.w3.org/2001/XMLSchema}dateTime" />
065 *       &lt;attribute name="Version" use="required" type="{http://www.w3.org/2001/XMLSchema}string" />
066 *     &lt;/restriction>
067 *   &lt;/complexContent>
068 * &lt;/complexType>
069 * </pre>
070 *
071 * @supported.all.api
072 */
073public interface StatusResponse {
074    
075    /**
076     * Returns the value of the version property.
077     *
078     * @return the value of the version property
079     * @see #setVersion(String)
080     */
081    public java.lang.String getVersion();
082    
083    /**
084     * Sets the value of the version property.
085     *
086     * @param value the value of the version property to be set
087     * @throws SAML2Exception if the object is immutable
088     * @see #getVersion
089     */
090    public void setVersion(java.lang.String value) throws SAML2Exception;
091    
092    /**
093     * Returns the value of the issueInstant property.
094     *
095     * @return the value of the issueInstant property
096     * @see #setIssueInstant(java.util.Date)
097     */
098    public java.util.Date getIssueInstant();
099    
100    /**
101     * Sets the value of the issueInstant property.
102     *
103     * @param value the value of the issueInstant property to be set
104     * @throws SAML2Exception if the object is immutable
105     * @see #getIssueInstant
106     */
107    public void setIssueInstant(java.util.Date value) throws SAML2Exception;
108    
109    /**
110     * Returns the value of the destination property.
111     *
112     * @return the value of the destination property
113     * @see #setDestination(String)
114     */
115    public java.lang.String getDestination();
116    
117    /**
118     * Sets the value of the destination property.
119     *
120     * @param value the value of the destination property to be set
121     * @throws SAML2Exception if the object is immutable
122     * @see #getDestination
123     */
124    public void setDestination(java.lang.String value) throws SAML2Exception;
125    
126    /**
127     * Returns the signature element, the <code>StatusResponse</code> contains
128     * as <code>String</code>.  A null value is returned if the 
129     * <code>StatusResponse</code> has no signature.
130     *
131     * @return <code>String</code> representation of the signature.
132     */
133    public String getSignature();
134    
135    /**
136     * Returns the value of the extensions property.
137     *
138     * @return the value of the extensions property
139     * @see #setExtensions(Extensions)
140     */
141    public com.sun.identity.saml2.protocol.Extensions getExtensions();
142    
143    /**
144     * Sets the value of the extensions property.
145     *
146     * @param value the value of the extensions property to be set
147     * @throws SAML2Exception if the object is immutable
148     * @see #getExtensions
149     */
150    public void setExtensions(com.sun.identity.saml2.protocol.Extensions value)
151    throws SAML2Exception;
152    
153    /**
154     * Returns the value of the consent property.
155     *
156     * @return the value of the consent property
157     * @see #setConsent(String)
158     */
159    public java.lang.String getConsent();
160    
161    /**
162     * Sets the value of the consent property.
163     *
164     * @param value the value of the consent property to be set
165     * @throws SAML2Exception if the object is immutable
166     * @see #getConsent
167     */
168    public void setConsent(java.lang.String value) throws SAML2Exception;
169    
170    /**
171     * Returns the value of the inResponseTo property.
172     *
173     * @return the value of the inResponseTo property
174     * @see #setInResponseTo(String)
175     */
176    public java.lang.String getInResponseTo();
177    
178    /**
179     * Sets the value of the inResponseTo property.
180     *
181     * @param value the value of the inResponseTo property to be set
182     * @throws SAML2Exception if the object is immutable
183     * @see #getInResponseTo
184     */
185    public void setInResponseTo(java.lang.String value) throws SAML2Exception;
186    
187    /**
188     * Returns the value of the status property.
189     *
190     * @return the value of the status property
191     * @see #setStatus(Status)
192     */
193    public com.sun.identity.saml2.protocol.Status getStatus();
194    
195    /**
196     * Sets the value of the status property.
197     *
198     * @param value the value of the status property to be set
199     * @throws SAML2Exception if the object is immutable
200     * @see #getStatus
201     */
202    public void setStatus(com.sun.identity.saml2.protocol.Status value)
203    throws SAML2Exception;
204    
205    /**
206     * Returns the value of the id property.
207     *
208     * @return the value of the id property
209     * @see #setID(String)
210     */
211    public java.lang.String getID();
212    
213    /**
214     * Sets the value of the id property.
215     *
216     * @param value the value of the id property to be set
217     * @throws SAML2Exception if the object is immutable
218     * @see #getID
219     */
220    public void setID(java.lang.String value) throws SAML2Exception;
221    
222    /**
223     * Returns the value of the issuer property.
224     *
225     * @return the value of the issuer property
226     * @see #setIssuer(Issuer)
227     */
228    public com.sun.identity.saml2.assertion.Issuer getIssuer();
229    
230    /**
231     * Sets the value of the issuer property.
232     *
233     * @param value the value of the issuer property to be set
234     * @throws SAML2Exception if the object is immutable
235     * @see #getIssuer
236     */
237    public void setIssuer(com.sun.identity.saml2.assertion.Issuer value)
238    throws SAML2Exception;
239    
240    /**
241     * Returns whether the <code>StatusResponse</code> is signed or not.
242     * @return true if the <code>StatusResponse</code> is signed
243     *         false otherwise.
244     */
245    public boolean isSigned();
246    
247    /**
248     * Returns whether the signature on the <code>StatusResponse</code>
249     * is valid or not.
250     *
251     * @param verificationCerts Certificates containing the public keys which may be used for signature verification;
252     *                          This certificate may also may be used to check against the certificate included in the
253     *                          signature.
254     * @return true if the signature is valid; false otherwise.
255     * @throws SAML2Exception if the signature could not be verified
256     */
257    public boolean isSignatureValid(Set<X509Certificate> verificationCerts)
258        throws SAML2Exception;
259    
260    /**
261     * Signs the <code>StatusResponse</code>.
262     *
263     * @param privateKey Signing key
264     * @param cert Certificate which contain the public key correlated to
265     *             the signing key; It if is not null, then the signature
266     *             will include the certificate; Otherwise, the signature
267     *             will not include any certificate.
268     * @throws SAML2Exception if it could not sign the StatusResponse.
269     */
270    public void sign(PrivateKey privateKey, X509Certificate cert)
271        throws SAML2Exception; 
272        
273    /**
274     * Returns the <code>StatusResponse</code> in an XML document String format
275     * based on the <code>StatusResponse</code> schema described above.
276     *
277     * @return An XML String representing the <code>StatusResponse</code>.
278     * @throws SAML2Exception if some error occurs during conversion to
279     *         <code>String</code>.
280     */
281    public String toXMLString() throws SAML2Exception;
282    
283    /**
284     * Returns the <code>StatusResponse</code> in an XML document String format
285     * based on the <code>StatusResponse</code> schema described above.
286     * @param includeNSPrefix Determines whether or not the namespace qualifier 
287     * is prepended to the Element when converted
288     *
289     * @param declareNS Determines whether or not the namespace is declared
290     *        within the Element.
291     * @return A XML String representing the <code>StatusResponse</code>.
292     * @throws SAML2Exception if some error occurs during conversion to
293     *         <code>String</code>.
294     */
295    public String toXMLString(boolean includeNSPrefix, boolean declareNS)
296    throws SAML2Exception;
297    
298    /**
299     * Makes the object immutable
300     */
301    public void makeImmutable();
302    
303    /**
304     * Returns true if the object is mutable false otherwise
305     *
306     * @return true if the object is mutable false otherwise
307     */
308    public boolean isMutable();
309}