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}