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