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: RequestAbstract.java,v 1.2 2008/06/25 05:47:57 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.PrivateKey;
036import java.security.cert.X509Certificate;
037import java.security.Signature;
038import com.sun.identity.saml2.xmlsig.SigManager;
039import java.util.Date;
040import java.util.Set;
041
042import org.w3c.dom.Element;
043
044/** 
045 * This interface defines methods for setting and retrieving attributes and 
046 * elements associated with a SAML request message used in SAML protocols.
047 *
048 * @supported.all.api
049 */
050
051public interface RequestAbstract {
052    
053    /** 
054     * Sets the <code>Issuer</code> object.
055     *
056     * @param nameID the new <code>Issuer</code> object.
057     * @throws SAML2Exception if the object is immutable.
058     * @see #getIssuer
059     */
060    public void setIssuer(Issuer nameID) throws SAML2Exception;
061    
062    /** 
063     * Returns the <code>Issuer</code> Object.
064     *
065     * @return the <code>Issuer</code> object.
066     * @see #setIssuer(Issuer)
067     */
068    public com.sun.identity.saml2.assertion.Issuer getIssuer();
069    
070    /** 
071     * Returns the <code>Signature</code> Object as a string.
072     *
073     * @return the <code>Signature</code> object as a string.
074     */
075    public String getSignature();   
076   
077   /**
078     * Signs the Request.
079     *
080     * @param privateKey Signing key
081     * @param cert Certificate which contain the public key correlated to
082     *             the signing key; It if is not null, then the signature
083     *             will include the certificate; Otherwise, the signature
084     *             will not include any certificate.
085     * @throws SAML2Exception if it could not sign the Request.
086     */
087    public void sign(PrivateKey privateKey, X509Certificate cert)
088        throws SAML2Exception; 
089    
090    /** 
091     * Sets the <code>Extensions</code> Object.
092     *
093     * @param extensions the <code>Extensions</code> object.
094     * @throws SAML2Exception if the object is immutable.
095     * @see #getExtensions
096     */
097    public void setExtensions(Extensions extensions) throws SAML2Exception;
098    
099    /** 
100     * Returns the <code>Extensions</code> Object.
101     *
102     * @return the <code>Extensions</code> object.
103     * @see #setExtensions(Extensions)
104     */
105    public Extensions getExtensions();
106    
107    /** 
108     * Sets the value of the <code>ID</code> attribute.
109     *
110     * @param id the new value of <code>ID</code> attribute.
111     * @throws SAML2Exception if the object is immutable.
112     * @see #getID
113     */
114    public void setID(String id) throws SAML2Exception;
115    
116    /** 
117     * Returns the value of the <code>ID</code> attribute.
118     *
119     * @return the value of <code>ID</code> attribute.
120     * @see #setID(String)
121     */
122    public String getID();
123    
124    /** 
125     * Sets the value of the <code>Version</code> attribute.
126     *
127     * @param version the value of <code>Version</code> attribute.
128     * @throws SAML2Exception if the object is immutable.
129     * @see #getVersion
130     */
131    public void setVersion(String version) throws SAML2Exception;
132    
133    /** 
134     * Returns the value of the <code>Version</code> attribute.
135     *
136     * @return value of <code>Version</code> attribute.
137     * @see #setVersion(String)
138     */
139    String getVersion();
140    
141    /** 
142     * Sets the value of <code>IssueInstant</code> attribute.
143     *
144     * @param dateTime new value of the <code>IssueInstant</code> attribute.
145     * @throws SAML2Exception if the object is immutable.
146     * @see #getIssueInstant     
147     */
148    public void setIssueInstant(Date dateTime) throws SAML2Exception;
149    
150    /** 
151     * Returns the value of <code>IssueInstant</code> attribute.
152     *
153     * @return value of the <code>IssueInstant</code> attribute.
154     * @see #setIssueInstant(Date)
155     */
156    public java.util.Date getIssueInstant();
157    
158    /** 
159     * Sets the value of the <code>Destination</code> attribute.
160     *
161     * @param destinationURI new value of <code>Destination</code> attribute.
162     * @throws SAML2Exception if the object is immutable.
163     * @see #getDestination
164     */
165    public void setDestination(String destinationURI) throws SAML2Exception;
166    
167    /** 
168     * Returns the value of the <code>Destination</code> attribute.
169     *
170     * @return  the value of <code>Destination</code> attribute.
171     * @see #setDestination(String)
172     */
173    public String getDestination();
174    
175    /** 
176     * Sets the value of the <code>Consent</code> attribute.
177     *
178     * @param consent new value of <code>Consent</code> attribute.
179     * @throws SAML2Exception if the object is immutable.
180     * @see #getConsent
181     */
182    public void setConsent(String consent) throws SAML2Exception;
183    
184    /** 
185     * Returns the value of the <code>Consent</code> attribute.
186     *
187     * @return value of <code>Consent</code> attribute.
188     * @see #setConsent(String)
189     */
190    public String getConsent();
191    
192    
193    /** 
194     * Returns true if message is signed.
195     *
196     * @return true if message is signed. 
197     */
198    
199    public boolean isSigned();
200    
201    
202    /**
203     * Return whether the signature is valid or not.
204     *
205     * @param verificationCerts Certificates containing the public keys which may be used for signature verification;
206     *                          This certificate may also may be used to check against the certificate included in the
207     *                          signature.
208     * @return true if the signature is valid; false otherwise.
209     * @throws SAML2Exception if the signature could not be verified
210     */
211    public boolean isSignatureValid(Set<X509Certificate> verificationCerts) throws SAML2Exception;
212    
213    /** 
214     * Returns a String representation of this Object.
215     *
216     * @return a String representation of this Object.
217     * @throws SAML2Exception if it could not create String object
218     */
219    public String toXMLString() throws SAML2Exception;
220    
221    /** 
222     * Returns a String representation of this Object.
223     *
224     * @param includeNSPrefix determines whether or not the namespace
225     *         qualifier is prepended to the Element when converted
226     * @param declareNS determines whether or not the namespace is declared
227     *         within the Element.
228     * @throws SAML2Exception if it could not create String object.
229     * @return a String representation of this Object.
230     **/
231    
232    public String toXMLString(boolean includeNSPrefix,boolean declareNS)
233        throws SAML2Exception;
234    
235        
236    /** 
237     * Makes this object immutable. 
238     */
239    public void makeImmutable() ;
240    
241    /** 
242     * Returns true if object is mutable.
243     *
244     * @return true if object is mutable.
245     */
246    public boolean isMutable();
247}