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