1 /* 2 * Copyright (c) 1998, 2013, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package javax.security.auth; 27 28 import java.util.*; 29 import java.io.*; 30 import java.lang.reflect.*; 31 import java.text.MessageFormat; 32 import java.security.AccessController; 33 import java.security.AccessControlContext; 34 import java.security.DomainCombiner; 35 import java.security.Permission; 36 import java.security.PermissionCollection; 37 import java.security.Principal; 38 import java.security.PrivilegedAction; 39 import java.security.PrivilegedExceptionAction; 40 import java.security.PrivilegedActionException; 41 import java.security.ProtectionDomain; 42 import sun.security.util.ResourcesMgr; 43 44 /** 45 * <p> A {@code Subject} represents a grouping of related information 46 * for a single entity, such as a person. 47 * Such information includes the Subject's identities as well as 48 * its security-related attributes 49 * (passwords and cryptographic keys, for example). 50 * 51 * <p> Subjects may potentially have multiple identities. 52 * Each identity is represented as a {@code Principal} 53 * within the {@code Subject}. Principals simply bind names to a 54 * {@code Subject}. For example, a {@code Subject} that happens 55 * to be a person, Alice, might have two Principals: 56 * one which binds "Alice Bar", the name on her driver license, 57 * to the {@code Subject}, and another which binds, 58 * "999-99-9999", the number on her student identification card, 59 * to the {@code Subject}. Both Principals refer to the same 60 * {@code Subject} even though each has a different name. 61 * 62 * <p> A {@code Subject} may also own security-related attributes, 63 * which are referred to as credentials. 64 * Sensitive credentials that require special protection, such as 65 * private cryptographic keys, are stored within a private credential 66 * {@code Set}. Credentials intended to be shared, such as 67 * public key certificates or Kerberos server tickets are stored 68 * within a public credential {@code Set}. Different permissions 69 * are required to access and modify the different credential Sets. 70 * 71 * <p> To retrieve all the Principals associated with a {@code Subject}, 72 * invoke the {@code getPrincipals} method. To retrieve 73 * all the public or private credentials belonging to a {@code Subject}, 74 * invoke the {@code getPublicCredentials} method or 75 * {@code getPrivateCredentials} method, respectively. 76 * To modify the returned {@code Set} of Principals and credentials, 77 * use the methods defined in the {@code Set} class. 78 * For example: 79 * <pre> 80 * Subject subject; 81 * Principal principal; 82 * Object credential; 83 * 84 * // add a Principal and credential to the Subject 85 * subject.getPrincipals().add(principal); 86 * subject.getPublicCredentials().add(credential); 87 * </pre> 88 * 89 * <p> This {@code Subject} class implements {@code Serializable}. 90 * While the Principals associated with the {@code Subject} are serialized, 91 * the credentials associated with the {@code Subject} are not. 92 * Note that the {@code java.security.Principal} class 93 * does not implement {@code Serializable}. Therefore all concrete 94 * {@code Principal} implementations associated with Subjects 95 * must implement {@code Serializable}. 96 * 97 * @see java.security.Principal 98 * @see java.security.DomainCombiner 99 */ 100 public final class Subject implements java.io.Serializable { 101 102 private static final long serialVersionUID = -8308522755600156056L; 103 104 /** 105 * A {@code Set} that provides a view of all of this 106 * Subject's Principals 107 * 108 * <p> 109 * 110 * @serial Each element in this set is a 111 * {@code java.security.Principal}. 112 * The set is a {@code Subject.SecureSet}. 113 */ 114 Set<Principal> principals; 115 116 /** 117 * Sets that provide a view of all of this 118 * Subject's Credentials 119 */ 120 transient Set<Object> pubCredentials; 121 transient Set<Object> privCredentials; 122 123 /** 124 * Whether this Subject is read-only 125 * 126 * @serial 127 */ 128 private volatile boolean readOnly = false; 129 130 private static final int PRINCIPAL_SET = 1; 131 private static final int PUB_CREDENTIAL_SET = 2; 132 private static final int PRIV_CREDENTIAL_SET = 3; 133 134 private static final ProtectionDomain[] NULL_PD_ARRAY 135 = new ProtectionDomain[0]; 136 137 /** 138 * Create an instance of a {@code Subject} 139 * with an empty {@code Set} of Principals and empty 140 * Sets of public and private credentials. 141 * 142 * <p> The newly constructed Sets check whether this {@code Subject} 143 * has been set read-only before permitting subsequent modifications. 144 * The newly created Sets also prevent illegal modifications 145 * by ensuring that callers have sufficient permissions. 146 * 147 * <p> To modify the Principals Set, the caller must have 148 * {@code AuthPermission("modifyPrincipals")}. 149 * To modify the public credential Set, the caller must have 150 * {@code AuthPermission("modifyPublicCredentials")}. 151 * To modify the private credential Set, the caller must have 152 * {@code AuthPermission("modifyPrivateCredentials")}. 153 */ 154 public Subject() { 155 156 this.principals = Collections.synchronizedSet 157 (new SecureSet<Principal>(this, PRINCIPAL_SET)); 158 this.pubCredentials = Collections.synchronizedSet 159 (new SecureSet<Object>(this, PUB_CREDENTIAL_SET)); 160 this.privCredentials = Collections.synchronizedSet 161 (new SecureSet<Object>(this, PRIV_CREDENTIAL_SET)); 162 } 163 164 /** 165 * Create an instance of a {@code Subject} with 166 * Principals and credentials. 167 * 168 * <p> The Principals and credentials from the specified Sets 169 * are copied into newly constructed Sets. 170 * These newly created Sets check whether this {@code Subject} 171 * has been set read-only before permitting subsequent modifications. 172 * The newly created Sets also prevent illegal modifications 173 * by ensuring that callers have sufficient permissions. 174 * 175 * <p> To modify the Principals Set, the caller must have 176 * {@code AuthPermission("modifyPrincipals")}. 177 * To modify the public credential Set, the caller must have 178 * {@code AuthPermission("modifyPublicCredentials")}. 179 * To modify the private credential Set, the caller must have 180 * {@code AuthPermission("modifyPrivateCredentials")}. 181 * <p> 182 * 183 * @param readOnly true if the {@code Subject} is to be read-only, 184 * and false otherwise. <p> 185 * 186 * @param principals the {@code Set} of Principals 187 * to be associated with this {@code Subject}. <p> 188 * 189 * @param pubCredentials the {@code Set} of public credentials 190 * to be associated with this {@code Subject}. <p> 191 * 192 * @param privCredentials the {@code Set} of private credentials 193 * to be associated with this {@code Subject}. 194 * 195 * @exception NullPointerException if the specified 196 * {@code principals}, {@code pubCredentials}, 197 * or {@code privCredentials} are {@code null}. 198 */ 199 public Subject(boolean readOnly, Set<? extends Principal> principals, 200 Set<?> pubCredentials, Set<?> privCredentials) 201 { 202 203 if (principals == null || 204 pubCredentials == null || 205 privCredentials == null) 206 throw new NullPointerException 207 (ResourcesMgr.getString("invalid.null.input.s.")); 208 209 this.principals = Collections.synchronizedSet(new SecureSet<Principal> 210 (this, PRINCIPAL_SET, principals)); 211 this.pubCredentials = Collections.synchronizedSet(new SecureSet<Object> 212 (this, PUB_CREDENTIAL_SET, pubCredentials)); 213 this.privCredentials = Collections.synchronizedSet(new SecureSet<Object> 214 (this, PRIV_CREDENTIAL_SET, privCredentials)); 215 this.readOnly = readOnly; 216 } 217 218 /** 219 * Set this {@code Subject} to be read-only. 220 * 221 * <p> Modifications (additions and removals) to this Subject's 222 * {@code Principal} {@code Set} and 223 * credential Sets will be disallowed. 224 * The {@code destroy} operation on this Subject's credentials will 225 * still be permitted. 226 * 227 * <p> Subsequent attempts to modify the Subject's {@code Principal} 228 * and credential Sets will result in an 229 * {@code IllegalStateException} being thrown. 230 * Also, once a {@code Subject} is read-only, 231 * it can not be reset to being writable again. 232 * 233 * <p> 234 * 235 * @exception SecurityException if the caller does not have permission 236 * to set this {@code Subject} to be read-only. 237 */ 238 public void setReadOnly() { 239 java.lang.SecurityManager sm = System.getSecurityManager(); 240 if (sm != null) { 241 sm.checkPermission(AuthPermissionHolder.SET_READ_ONLY_PERMISSION); 242 } 243 244 this.readOnly = true; 245 } 246 247 /** 248 * Query whether this {@code Subject} is read-only. 249 * 250 * <p> 251 * 252 * @return true if this {@code Subject} is read-only, false otherwise. 253 */ 254 public boolean isReadOnly() { 255 return this.readOnly; 256 } 257 258 /** 259 * Get the {@code Subject} associated with the provided 260 * {@code AccessControlContext}. 261 * 262 * <p> The {@code AccessControlContext} may contain many 263 * Subjects (from nested {@code doAs} calls). 264 * In this situation, the most recent {@code Subject} associated 265 * with the {@code AccessControlContext} is returned. 266 * 267 * <p> 268 * 269 * @param acc the {@code AccessControlContext} from which to retrieve 270 * the {@code Subject}. 271 * 272 * @return the {@code Subject} associated with the provided 273 * {@code AccessControlContext}, or {@code null} 274 * if no {@code Subject} is associated 275 * with the provided {@code AccessControlContext}. 276 * 277 * @exception SecurityException if the caller does not have permission 278 * to get the {@code Subject}. <p> 279 * 280 * @exception NullPointerException if the provided 281 * {@code AccessControlContext} is {@code null}. 282 */ 283 public static Subject getSubject(final AccessControlContext acc) { 284 285 java.lang.SecurityManager sm = System.getSecurityManager(); 286 if (sm != null) { 287 sm.checkPermission(AuthPermissionHolder.GET_SUBJECT_PERMISSION); 288 } 289 290 if (acc == null) { 291 throw new NullPointerException(ResourcesMgr.getString 292 ("invalid.null.AccessControlContext.provided")); 293 } 294 295 // return the Subject from the DomainCombiner of the provided context 296 return AccessController.doPrivileged 297 (new java.security.PrivilegedAction<Subject>() { 298 public Subject run() { 299 DomainCombiner dc = acc.getDomainCombiner(); 300 if (!(dc instanceof SubjectDomainCombiner)) 301 return null; 302 SubjectDomainCombiner sdc = (SubjectDomainCombiner)dc; 303 return sdc.getSubject(); 304 } 305 }); 306 } 307 308 /** 309 * Perform work as a particular {@code Subject}. 310 * 311 * <p> This method first retrieves the current Thread's 312 * {@code AccessControlContext} via 313 * {@code AccessController.getContext}, 314 * and then instantiates a new {@code AccessControlContext} 315 * using the retrieved context along with a new 316 * {@code SubjectDomainCombiner} (constructed using 317 * the provided {@code Subject}). 318 * Finally, this method invokes {@code AccessController.doPrivileged}, 319 * passing it the provided {@code PrivilegedAction}, 320 * as well as the newly constructed {@code AccessControlContext}. 321 * 322 * <p> 323 * 324 * @param subject the {@code Subject} that the specified 325 * {@code action} will run as. This parameter 326 * may be {@code null}. <p> 327 * 328 * @param <T> the type of the value returned by the PrivilegedAction's 329 * {@code run} method. 330 * 331 * @param action the code to be run as the specified 332 * {@code Subject}. <p> 333 * 334 * @return the value returned by the PrivilegedAction's 335 * {@code run} method. 336 * 337 * @exception NullPointerException if the {@code PrivilegedAction} 338 * is {@code null}. <p> 339 * 340 * @exception SecurityException if the caller does not have permission 341 * to invoke this method. 342 */ 343 public static <T> T doAs(final Subject subject, 344 final java.security.PrivilegedAction<T> action) { 345 346 java.lang.SecurityManager sm = System.getSecurityManager(); 347 if (sm != null) { 348 sm.checkPermission(AuthPermissionHolder.DO_AS_PERMISSION); 349 } 350 if (action == null) 351 throw new NullPointerException 352 (ResourcesMgr.getString("invalid.null.action.provided")); 353 354 // set up the new Subject-based AccessControlContext 355 // for doPrivileged 356 final AccessControlContext currentAcc = AccessController.getContext(); 357 358 // call doPrivileged and push this new context on the stack 359 return java.security.AccessController.doPrivileged 360 (action, 361 createContext(subject, currentAcc)); 362 } 363 364 /** 365 * Perform work as a particular {@code Subject}. 366 * 367 * <p> This method first retrieves the current Thread's 368 * {@code AccessControlContext} via 369 * {@code AccessController.getContext}, 370 * and then instantiates a new {@code AccessControlContext} 371 * using the retrieved context along with a new 372 * {@code SubjectDomainCombiner} (constructed using 373 * the provided {@code Subject}). 374 * Finally, this method invokes {@code AccessController.doPrivileged}, 375 * passing it the provided {@code PrivilegedExceptionAction}, 376 * as well as the newly constructed {@code AccessControlContext}. 377 * 378 * <p> 379 * 380 * @param subject the {@code Subject} that the specified 381 * {@code action} will run as. This parameter 382 * may be {@code null}. <p> 383 * 384 * @param <T> the type of the value returned by the 385 * PrivilegedExceptionAction's {@code run} method. 386 * 387 * @param action the code to be run as the specified 388 * {@code Subject}. <p> 389 * 390 * @return the value returned by the 391 * PrivilegedExceptionAction's {@code run} method. 392 * 393 * @exception PrivilegedActionException if the 394 * {@code PrivilegedExceptionAction.run} 395 * method throws a checked exception. <p> 396 * 397 * @exception NullPointerException if the specified 398 * {@code PrivilegedExceptionAction} is 399 * {@code null}. <p> 400 * 401 * @exception SecurityException if the caller does not have permission 402 * to invoke this method. 403 */ 404 public static <T> T doAs(final Subject subject, 405 final java.security.PrivilegedExceptionAction<T> action) 406 throws java.security.PrivilegedActionException { 407 408 java.lang.SecurityManager sm = System.getSecurityManager(); 409 if (sm != null) { 410 sm.checkPermission(AuthPermissionHolder.DO_AS_PERMISSION); 411 } 412 413 if (action == null) 414 throw new NullPointerException 415 (ResourcesMgr.getString("invalid.null.action.provided")); 416 417 // set up the new Subject-based AccessControlContext for doPrivileged 418 final AccessControlContext currentAcc = AccessController.getContext(); 419 420 // call doPrivileged and push this new context on the stack 421 return java.security.AccessController.doPrivileged 422 (action, 423 createContext(subject, currentAcc)); 424 } 425 426 /** 427 * Perform privileged work as a particular {@code Subject}. 428 * 429 * <p> This method behaves exactly as {@code Subject.doAs}, 430 * except that instead of retrieving the current Thread's 431 * {@code AccessControlContext}, it uses the provided 432 * {@code AccessControlContext}. If the provided 433 * {@code AccessControlContext} is {@code null}, 434 * this method instantiates a new {@code AccessControlContext} 435 * with an empty collection of ProtectionDomains. 436 * 437 * <p> 438 * 439 * @param subject the {@code Subject} that the specified 440 * {@code action} will run as. This parameter 441 * may be {@code null}. <p> 442 * 443 * @param <T> the type of the value returned by the PrivilegedAction's 444 * {@code run} method. 445 * 446 * @param action the code to be run as the specified 447 * {@code Subject}. <p> 448 * 449 * @param acc the {@code AccessControlContext} to be tied to the 450 * specified <i>subject</i> and <i>action</i>. <p> 451 * 452 * @return the value returned by the PrivilegedAction's 453 * {@code run} method. 454 * 455 * @exception NullPointerException if the {@code PrivilegedAction} 456 * is {@code null}. <p> 457 * 458 * @exception SecurityException if the caller does not have permission 459 * to invoke this method. 460 */ 461 public static <T> T doAsPrivileged(final Subject subject, 462 final java.security.PrivilegedAction<T> action, 463 final java.security.AccessControlContext acc) { 464 465 java.lang.SecurityManager sm = System.getSecurityManager(); 466 if (sm != null) { 467 sm.checkPermission(AuthPermissionHolder.DO_AS_PRIVILEGED_PERMISSION); 468 } 469 470 if (action == null) 471 throw new NullPointerException 472 (ResourcesMgr.getString("invalid.null.action.provided")); 473 474 // set up the new Subject-based AccessControlContext 475 // for doPrivileged 476 final AccessControlContext callerAcc = 477 (acc == null ? 478 new AccessControlContext(NULL_PD_ARRAY) : 479 acc); 480 481 // call doPrivileged and push this new context on the stack 482 return java.security.AccessController.doPrivileged 483 (action, 484 createContext(subject, callerAcc)); 485 } 486 487 /** 488 * Perform privileged work as a particular {@code Subject}. 489 * 490 * <p> This method behaves exactly as {@code Subject.doAs}, 491 * except that instead of retrieving the current Thread's 492 * {@code AccessControlContext}, it uses the provided 493 * {@code AccessControlContext}. If the provided 494 * {@code AccessControlContext} is {@code null}, 495 * this method instantiates a new {@code AccessControlContext} 496 * with an empty collection of ProtectionDomains. 497 * 498 * <p> 499 * 500 * @param subject the {@code Subject} that the specified 501 * {@code action} will run as. This parameter 502 * may be {@code null}. <p> 503 * 504 * @param <T> the type of the value returned by the 505 * PrivilegedExceptionAction's {@code run} method. 506 * 507 * @param action the code to be run as the specified 508 * {@code Subject}. <p> 509 * 510 * @param acc the {@code AccessControlContext} to be tied to the 511 * specified <i>subject</i> and <i>action</i>. <p> 512 * 513 * @return the value returned by the 514 * PrivilegedExceptionAction's {@code run} method. 515 * 516 * @exception PrivilegedActionException if the 517 * {@code PrivilegedExceptionAction.run} 518 * method throws a checked exception. <p> 519 * 520 * @exception NullPointerException if the specified 521 * {@code PrivilegedExceptionAction} is 522 * {@code null}. <p> 523 * 524 * @exception SecurityException if the caller does not have permission 525 * to invoke this method. 526 */ 527 public static <T> T doAsPrivileged(final Subject subject, 528 final java.security.PrivilegedExceptionAction<T> action, 529 final java.security.AccessControlContext acc) 530 throws java.security.PrivilegedActionException { 531 532 java.lang.SecurityManager sm = System.getSecurityManager(); 533 if (sm != null) { 534 sm.checkPermission(AuthPermissionHolder.DO_AS_PRIVILEGED_PERMISSION); 535 } 536 537 if (action == null) 538 throw new NullPointerException 539 (ResourcesMgr.getString("invalid.null.action.provided")); 540 541 // set up the new Subject-based AccessControlContext for doPrivileged 542 final AccessControlContext callerAcc = 543 (acc == null ? 544 new AccessControlContext(NULL_PD_ARRAY) : 545 acc); 546 547 // call doPrivileged and push this new context on the stack 548 return java.security.AccessController.doPrivileged 549 (action, 550 createContext(subject, callerAcc)); 551 } 552 553 private static AccessControlContext createContext(final Subject subject, 554 final AccessControlContext acc) { 555 556 557 return java.security.AccessController.doPrivileged 558 (new java.security.PrivilegedAction<AccessControlContext>() { 559 public AccessControlContext run() { 560 if (subject == null) 561 return new AccessControlContext(acc, null); 562 else 563 return new AccessControlContext 564 (acc, 565 new SubjectDomainCombiner(subject)); 566 } 567 }); 568 } 569 570 /** 571 * Return the {@code Set} of Principals associated with this 572 * {@code Subject}. Each {@code Principal} represents 573 * an identity for this {@code Subject}. 574 * 575 * <p> The returned {@code Set} is backed by this Subject's 576 * internal {@code Principal} {@code Set}. Any modification 577 * to the returned {@code Set} affects the internal 578 * {@code Principal} {@code Set} as well. 579 * 580 * <p> 581 * 582 * @return The {@code Set} of Principals associated with this 583 * {@code Subject}. 584 */ 585 public Set<Principal> getPrincipals() { 586 587 // always return an empty Set instead of null 588 // so LoginModules can add to the Set if necessary 589 return principals; 590 } 591 592 /** 593 * Return a {@code Set} of Principals associated with this 594 * {@code Subject} that are instances or subclasses of the specified 595 * {@code Class}. 596 * 597 * <p> The returned {@code Set} is not backed by this Subject's 598 * internal {@code Principal} {@code Set}. A new 599 * {@code Set} is created and returned for each method invocation. 600 * Modifications to the returned {@code Set} 601 * will not affect the internal {@code Principal} {@code Set}. 602 * 603 * <p> 604 * 605 * @param <T> the type of the class modeled by {@code c} 606 * 607 * @param c the returned {@code Set} of Principals will all be 608 * instances of this class. 609 * 610 * @return a {@code Set} of Principals that are instances of the 611 * specified {@code Class}. 612 * 613 * @exception NullPointerException if the specified {@code Class} 614 * is {@code null}. 615 */ 616 public <T extends Principal> Set<T> getPrincipals(Class<T> c) { 617 618 if (c == null) 619 throw new NullPointerException 620 (ResourcesMgr.getString("invalid.null.Class.provided")); 621 622 // always return an empty Set instead of null 623 // so LoginModules can add to the Set if necessary 624 return new ClassSet<T>(PRINCIPAL_SET, c); 625 } 626 627 /** 628 * Return the {@code Set} of public credentials held by this 629 * {@code Subject}. 630 * 631 * <p> The returned {@code Set} is backed by this Subject's 632 * internal public Credential {@code Set}. Any modification 633 * to the returned {@code Set} affects the internal public 634 * Credential {@code Set} as well. 635 * 636 * <p> 637 * 638 * @return A {@code Set} of public credentials held by this 639 * {@code Subject}. 640 */ 641 public Set<Object> getPublicCredentials() { 642 643 // always return an empty Set instead of null 644 // so LoginModules can add to the Set if necessary 645 return pubCredentials; 646 } 647 648 /** 649 * Return the {@code Set} of private credentials held by this 650 * {@code Subject}. 651 * 652 * <p> The returned {@code Set} is backed by this Subject's 653 * internal private Credential {@code Set}. Any modification 654 * to the returned {@code Set} affects the internal private 655 * Credential {@code Set} as well. 656 * 657 * <p> A caller requires permissions to access the Credentials 658 * in the returned {@code Set}, or to modify the 659 * {@code Set} itself. A {@code SecurityException} 660 * is thrown if the caller does not have the proper permissions. 661 * 662 * <p> While iterating through the {@code Set}, 663 * a {@code SecurityException} is thrown 664 * if the caller does not have permission to access a 665 * particular Credential. The {@code Iterator} 666 * is nevertheless advanced to next element in the {@code Set}. 667 * 668 * <p> 669 * 670 * @return A {@code Set} of private credentials held by this 671 * {@code Subject}. 672 */ 673 public Set<Object> getPrivateCredentials() { 674 675 // XXX 676 // we do not need a security check for 677 // AuthPermission(getPrivateCredentials) 678 // because we already restrict access to private credentials 679 // via the PrivateCredentialPermission. all the extra AuthPermission 680 // would do is protect the set operations themselves 681 // (like size()), which don't seem security-sensitive. 682 683 // always return an empty Set instead of null 684 // so LoginModules can add to the Set if necessary 685 return privCredentials; 686 } 687 688 /** 689 * Return a {@code Set} of public credentials associated with this 690 * {@code Subject} that are instances or subclasses of the specified 691 * {@code Class}. 692 * 693 * <p> The returned {@code Set} is not backed by this Subject's 694 * internal public Credential {@code Set}. A new 695 * {@code Set} is created and returned for each method invocation. 696 * Modifications to the returned {@code Set} 697 * will not affect the internal public Credential {@code Set}. 698 * 699 * <p> 700 * 701 * @param <T> the type of the class modeled by {@code c} 702 * 703 * @param c the returned {@code Set} of public credentials will all be 704 * instances of this class. 705 * 706 * @return a {@code Set} of public credentials that are instances 707 * of the specified {@code Class}. 708 * 709 * @exception NullPointerException if the specified {@code Class} 710 * is {@code null}. 711 */ 712 public <T> Set<T> getPublicCredentials(Class<T> c) { 713 714 if (c == null) 715 throw new NullPointerException 716 (ResourcesMgr.getString("invalid.null.Class.provided")); 717 718 // always return an empty Set instead of null 719 // so LoginModules can add to the Set if necessary 720 return new ClassSet<T>(PUB_CREDENTIAL_SET, c); 721 } 722 723 /** 724 * Return a {@code Set} of private credentials associated with this 725 * {@code Subject} that are instances or subclasses of the specified 726 * {@code Class}. 727 * 728 * <p> The caller must have permission to access all of the 729 * requested Credentials, or a {@code SecurityException} 730 * will be thrown. 731 * 732 * <p> The returned {@code Set} is not backed by this Subject's 733 * internal private Credential {@code Set}. A new 734 * {@code Set} is created and returned for each method invocation. 735 * Modifications to the returned {@code Set} 736 * will not affect the internal private Credential {@code Set}. 737 * 738 * <p> 739 * 740 * @param <T> the type of the class modeled by {@code c} 741 * 742 * @param c the returned {@code Set} of private credentials will all be 743 * instances of this class. 744 * 745 * @return a {@code Set} of private credentials that are instances 746 * of the specified {@code Class}. 747 * 748 * @exception NullPointerException if the specified {@code Class} 749 * is {@code null}. 750 */ 751 public <T> Set<T> getPrivateCredentials(Class<T> c) { 752 753 // XXX 754 // we do not need a security check for 755 // AuthPermission(getPrivateCredentials) 756 // because we already restrict access to private credentials 757 // via the PrivateCredentialPermission. all the extra AuthPermission 758 // would do is protect the set operations themselves 759 // (like size()), which don't seem security-sensitive. 760 761 if (c == null) 762 throw new NullPointerException 763 (ResourcesMgr.getString("invalid.null.Class.provided")); 764 765 // always return an empty Set instead of null 766 // so LoginModules can add to the Set if necessary 767 return new ClassSet<T>(PRIV_CREDENTIAL_SET, c); 768 } 769 770 /** 771 * Compares the specified Object with this {@code Subject} 772 * for equality. Returns true if the given object is also a Subject 773 * and the two {@code Subject} instances are equivalent. 774 * More formally, two {@code Subject} instances are 775 * equal if their {@code Principal} and {@code Credential} 776 * Sets are equal. 777 * 778 * <p> 779 * 780 * @param o Object to be compared for equality with this 781 * {@code Subject}. 782 * 783 * @return true if the specified Object is equal to this 784 * {@code Subject}. 785 * 786 * @exception SecurityException if the caller does not have permission 787 * to access the private credentials for this {@code Subject}, 788 * or if the caller does not have permission to access the 789 * private credentials for the provided {@code Subject}. 790 */ 791 public boolean equals(Object o) { 792 793 if (o == null) 794 return false; 795 796 if (this == o) 797 return true; 798 799 if (o instanceof Subject) { 800 801 final Subject that = (Subject)o; 802 803 // check the principal and credential sets 804 Set<Principal> thatPrincipals; 805 synchronized(that.principals) { 806 // avoid deadlock from dual locks 807 thatPrincipals = new HashSet<Principal>(that.principals); 808 } 809 if (!principals.equals(thatPrincipals)) { 810 return false; 811 } 812 813 Set<Object> thatPubCredentials; 814 synchronized(that.pubCredentials) { 815 // avoid deadlock from dual locks 816 thatPubCredentials = new HashSet<Object>(that.pubCredentials); 817 } 818 if (!pubCredentials.equals(thatPubCredentials)) { 819 return false; 820 } 821 822 Set<Object> thatPrivCredentials; 823 synchronized(that.privCredentials) { 824 // avoid deadlock from dual locks 825 thatPrivCredentials = new HashSet<Object>(that.privCredentials); 826 } 827 if (!privCredentials.equals(thatPrivCredentials)) { 828 return false; 829 } 830 return true; 831 } 832 return false; 833 } 834 835 /** 836 * Return the String representation of this {@code Subject}. 837 * 838 * <p> 839 * 840 * @return the String representation of this {@code Subject}. 841 */ 842 public String toString() { 843 return toString(true); 844 } 845 846 /** 847 * package private convenience method to print out the Subject 848 * without firing off a security check when trying to access 849 * the Private Credentials 850 */ 851 String toString(boolean includePrivateCredentials) { 852 853 String s = ResourcesMgr.getString("Subject."); 854 String suffix = ""; 855 856 synchronized(principals) { 857 Iterator<Principal> pI = principals.iterator(); 858 while (pI.hasNext()) { 859 Principal p = pI.next(); 860 suffix = suffix + ResourcesMgr.getString(".Principal.") + 861 p.toString() + ResourcesMgr.getString("NEWLINE"); 862 } 863 } 864 865 synchronized(pubCredentials) { 866 Iterator<Object> pI = pubCredentials.iterator(); 867 while (pI.hasNext()) { 868 Object o = pI.next(); 869 suffix = suffix + 870 ResourcesMgr.getString(".Public.Credential.") + 871 o.toString() + ResourcesMgr.getString("NEWLINE"); 872 } 873 } 874 875 if (includePrivateCredentials) { 876 synchronized(privCredentials) { 877 Iterator<Object> pI = privCredentials.iterator(); 878 while (pI.hasNext()) { 879 try { 880 Object o = pI.next(); 881 suffix += ResourcesMgr.getString 882 (".Private.Credential.") + 883 o.toString() + 884 ResourcesMgr.getString("NEWLINE"); 885 } catch (SecurityException se) { 886 suffix += ResourcesMgr.getString 887 (".Private.Credential.inaccessible."); 888 break; 889 } 890 } 891 } 892 } 893 return s + suffix; 894 } 895 896 /** 897 * Returns a hashcode for this {@code Subject}. 898 * 899 * <p> 900 * 901 * @return a hashcode for this {@code Subject}. 902 * 903 * @exception SecurityException if the caller does not have permission 904 * to access this Subject's private credentials. 905 */ 906 public int hashCode() { 907 908 /** 909 * The hashcode is derived exclusive or-ing the 910 * hashcodes of this Subject's Principals and credentials. 911 * 912 * If a particular credential was destroyed 913 * ({@code credential.hashCode()} throws an 914 * {@code IllegalStateException}), 915 * the hashcode for that credential is derived via: 916 * {@code credential.getClass().toString().hashCode()}. 917 */ 918 919 int hashCode = 0; 920 921 synchronized(principals) { 922 Iterator<Principal> pIterator = principals.iterator(); 923 while (pIterator.hasNext()) { 924 Principal p = pIterator.next(); 925 hashCode ^= p.hashCode(); 926 } 927 } 928 929 synchronized(pubCredentials) { 930 Iterator<Object> pubCIterator = pubCredentials.iterator(); 931 while (pubCIterator.hasNext()) { 932 hashCode ^= getCredHashCode(pubCIterator.next()); 933 } 934 } 935 return hashCode; 936 } 937 938 /** 939 * get a credential's hashcode 940 */ 941 private int getCredHashCode(Object o) { 942 try { 943 return o.hashCode(); 944 } catch (IllegalStateException ise) { 945 return o.getClass().toString().hashCode(); 946 } 947 } 948 949 /** 950 * Writes this object out to a stream (i.e., serializes it). 951 */ 952 private void writeObject(java.io.ObjectOutputStream oos) 953 throws java.io.IOException { 954 synchronized(principals) { 955 oos.defaultWriteObject(); 956 } 957 } 958 959 /** 960 * Reads this object from a stream (i.e., deserializes it) 961 */ 962 @SuppressWarnings("unchecked") 963 private void readObject(java.io.ObjectInputStream s) 964 throws java.io.IOException, ClassNotFoundException { 965 966 ObjectInputStream.GetField gf = s.readFields(); 967 968 readOnly = gf.get("readOnly", false); 969 970 Set<Principal> inputPrincs = (Set<Principal>)gf.get("principals", null); 971 972 // Rewrap the principals into a SecureSet 973 if (inputPrincs == null) { 974 throw new NullPointerException 975 (ResourcesMgr.getString("invalid.null.input.s.")); 976 } 977 try { 978 principals = Collections.synchronizedSet(new SecureSet<Principal> 979 (this, PRINCIPAL_SET, inputPrincs)); 980 } catch (NullPointerException npe) { 981 // Sometimes people deserialize the principals set only. 982 // Subject is not accessible, so just don't fail. 983 principals = Collections.synchronizedSet 984 (new SecureSet<Principal>(this, PRINCIPAL_SET)); 985 } 986 987 // The Credential {@code Set} is not serialized, but we do not 988 // want the default deserialization routine to set it to null. 989 this.pubCredentials = Collections.synchronizedSet 990 (new SecureSet<Object>(this, PUB_CREDENTIAL_SET)); 991 this.privCredentials = Collections.synchronizedSet 992 (new SecureSet<Object>(this, PRIV_CREDENTIAL_SET)); 993 } 994 995 /** 996 * Prevent modifications unless caller has permission. 997 * 998 * @serial include 999 */ 1000 private static class SecureSet<E> 1001 extends AbstractSet<E> 1002 implements java.io.Serializable { 1003 1004 private static final long serialVersionUID = 7911754171111800359L; 1005 1006 /** 1007 * @serialField this$0 Subject The outer Subject instance. 1008 * @serialField elements LinkedList The elements in this set. 1009 */ 1010 private static final ObjectStreamField[] serialPersistentFields = { 1011 new ObjectStreamField("this$0", Subject.class), 1012 new ObjectStreamField("elements", LinkedList.class), 1013 new ObjectStreamField("which", int.class) 1014 }; 1015 1016 Subject subject; 1017 LinkedList<E> elements; 1018 1019 /** 1020 * @serial An integer identifying the type of objects contained 1021 * in this set. If {@code which == 1}, 1022 * this is a Principal set and all the elements are 1023 * of type {@code java.security.Principal}. 1024 * If {@code which == 2}, this is a public credential 1025 * set and all the elements are of type {@code Object}. 1026 * If {@code which == 3}, this is a private credential 1027 * set and all the elements are of type {@code Object}. 1028 */ 1029 private int which; 1030 1031 SecureSet(Subject subject, int which) { 1032 this.subject = subject; 1033 this.which = which; 1034 this.elements = new LinkedList<E>(); 1035 } 1036 1037 SecureSet(Subject subject, int which, Set<? extends E> set) { 1038 this.subject = subject; 1039 this.which = which; 1040 this.elements = new LinkedList<E>(set); 1041 } 1042 1043 public int size() { 1044 return elements.size(); 1045 } 1046 1047 public Iterator<E> iterator() { 1048 final LinkedList<E> list = elements; 1049 return new Iterator<E>() { 1050 ListIterator<E> i = list.listIterator(0); 1051 1052 public boolean hasNext() {return i.hasNext();} 1053 1054 public E next() { 1055 if (which != Subject.PRIV_CREDENTIAL_SET) { 1056 return i.next(); 1057 } 1058 1059 SecurityManager sm = System.getSecurityManager(); 1060 if (sm != null) { 1061 try { 1062 sm.checkPermission(new PrivateCredentialPermission 1063 (list.get(i.nextIndex()).getClass().getName(), 1064 subject.getPrincipals())); 1065 } catch (SecurityException se) { 1066 i.next(); 1067 throw (se); 1068 } 1069 } 1070 return i.next(); 1071 } 1072 1073 public void remove() { 1074 1075 if (subject.isReadOnly()) { 1076 throw new IllegalStateException(ResourcesMgr.getString 1077 ("Subject.is.read.only")); 1078 } 1079 1080 java.lang.SecurityManager sm = System.getSecurityManager(); 1081 if (sm != null) { 1082 switch (which) { 1083 case Subject.PRINCIPAL_SET: 1084 sm.checkPermission(AuthPermissionHolder.MODIFY_PRINCIPALS_PERMISSION); 1085 break; 1086 case Subject.PUB_CREDENTIAL_SET: 1087 sm.checkPermission(AuthPermissionHolder.MODIFY_PUBLIC_CREDENTIALS_PERMISSION); 1088 break; 1089 default: 1090 sm.checkPermission(AuthPermissionHolder.MODIFY_PRIVATE_CREDENTIALS_PERMISSION); 1091 break; 1092 } 1093 } 1094 i.remove(); 1095 } 1096 }; 1097 } 1098 1099 public boolean add(E o) { 1100 1101 if (subject.isReadOnly()) { 1102 throw new IllegalStateException 1103 (ResourcesMgr.getString("Subject.is.read.only")); 1104 } 1105 1106 java.lang.SecurityManager sm = System.getSecurityManager(); 1107 if (sm != null) { 1108 switch (which) { 1109 case Subject.PRINCIPAL_SET: 1110 sm.checkPermission(AuthPermissionHolder.MODIFY_PRINCIPALS_PERMISSION); 1111 break; 1112 case Subject.PUB_CREDENTIAL_SET: 1113 sm.checkPermission(AuthPermissionHolder.MODIFY_PUBLIC_CREDENTIALS_PERMISSION); 1114 break; 1115 default: 1116 sm.checkPermission(AuthPermissionHolder.MODIFY_PRIVATE_CREDENTIALS_PERMISSION); 1117 break; 1118 } 1119 } 1120 1121 switch (which) { 1122 case Subject.PRINCIPAL_SET: 1123 if (!(o instanceof Principal)) { 1124 throw new SecurityException(ResourcesMgr.getString 1125 ("attempting.to.add.an.object.which.is.not.an.instance.of.java.security.Principal.to.a.Subject.s.Principal.Set")); 1126 } 1127 break; 1128 default: 1129 // ok to add Objects of any kind to credential sets 1130 break; 1131 } 1132 1133 // check for duplicates 1134 if (!elements.contains(o)) 1135 return elements.add(o); 1136 else 1137 return false; 1138 } 1139 1140 public boolean remove(Object o) { 1141 1142 final Iterator<E> e = iterator(); 1143 while (e.hasNext()) { 1144 E next; 1145 if (which != Subject.PRIV_CREDENTIAL_SET) { 1146 next = e.next(); 1147 } else { 1148 next = java.security.AccessController.doPrivileged 1149 (new java.security.PrivilegedAction<E>() { 1150 public E run() { 1151 return e.next(); 1152 } 1153 }); 1154 } 1155 1156 if (next == null) { 1157 if (o == null) { 1158 e.remove(); 1159 return true; 1160 } 1161 } else if (next.equals(o)) { 1162 e.remove(); 1163 return true; 1164 } 1165 } 1166 return false; 1167 } 1168 1169 public boolean contains(Object o) { 1170 final Iterator<E> e = iterator(); 1171 while (e.hasNext()) { 1172 E next; 1173 if (which != Subject.PRIV_CREDENTIAL_SET) { 1174 next = e.next(); 1175 } else { 1176 1177 // For private credentials: 1178 // If the caller does not have read permission for 1179 // for o.getClass(), we throw a SecurityException. 1180 // Otherwise we check the private cred set to see whether 1181 // it contains the Object 1182 1183 SecurityManager sm = System.getSecurityManager(); 1184 if (sm != null) { 1185 sm.checkPermission(new PrivateCredentialPermission 1186 (o.getClass().getName(), 1187 subject.getPrincipals())); 1188 } 1189 next = java.security.AccessController.doPrivileged 1190 (new java.security.PrivilegedAction<E>() { 1191 public E run() { 1192 return e.next(); 1193 } 1194 }); 1195 } 1196 1197 if (next == null) { 1198 if (o == null) { 1199 return true; 1200 } 1201 } else if (next.equals(o)) { 1202 return true; 1203 } 1204 } 1205 return false; 1206 } 1207 1208 public boolean removeAll(Collection<?> c) { 1209 Objects.requireNonNull(c); 1210 boolean modified = false; 1211 final Iterator<E> e = iterator(); 1212 while (e.hasNext()) { 1213 E next; 1214 if (which != Subject.PRIV_CREDENTIAL_SET) { 1215 next = e.next(); 1216 } else { 1217 next = java.security.AccessController.doPrivileged 1218 (new java.security.PrivilegedAction<E>() { 1219 public E run() { 1220 return e.next(); 1221 } 1222 }); 1223 } 1224 1225 Iterator<?> ce = c.iterator(); 1226 while (ce.hasNext()) { 1227 Object o = ce.next(); 1228 if (next == null) { 1229 if (o == null) { 1230 e.remove(); 1231 modified = true; 1232 break; 1233 } 1234 } else if (next.equals(o)) { 1235 e.remove(); 1236 modified = true; 1237 break; 1238 } 1239 } 1240 } 1241 return modified; 1242 } 1243 1244 public boolean retainAll(Collection<?> c) { 1245 Objects.requireNonNull(c); 1246 boolean modified = false; 1247 boolean retain = false; 1248 final Iterator<E> e = iterator(); 1249 while (e.hasNext()) { 1250 retain = false; 1251 E next; 1252 if (which != Subject.PRIV_CREDENTIAL_SET) { 1253 next = e.next(); 1254 } else { 1255 next = java.security.AccessController.doPrivileged 1256 (new java.security.PrivilegedAction<E>() { 1257 public E run() { 1258 return e.next(); 1259 } 1260 }); 1261 } 1262 1263 Iterator<?> ce = c.iterator(); 1264 while (ce.hasNext()) { 1265 Object o = ce.next(); 1266 if (next == null) { 1267 if (o == null) { 1268 retain = true; 1269 break; 1270 } 1271 } else if (next.equals(o)) { 1272 retain = true; 1273 break; 1274 } 1275 } 1276 1277 if (!retain) { 1278 e.remove(); 1279 retain = false; 1280 modified = true; 1281 } 1282 } 1283 return modified; 1284 } 1285 1286 public void clear() { 1287 final Iterator<E> e = iterator(); 1288 while (e.hasNext()) { 1289 E next; 1290 if (which != Subject.PRIV_CREDENTIAL_SET) { 1291 next = e.next(); 1292 } else { 1293 next = java.security.AccessController.doPrivileged 1294 (new java.security.PrivilegedAction<E>() { 1295 public E run() { 1296 return e.next(); 1297 } 1298 }); 1299 } 1300 e.remove(); 1301 } 1302 } 1303 1304 /** 1305 * Writes this object out to a stream (i.e., serializes it). 1306 * 1307 * <p> 1308 * 1309 * @serialData If this is a private credential set, 1310 * a security check is performed to ensure that 1311 * the caller has permission to access each credential 1312 * in the set. If the security check passes, 1313 * the set is serialized. 1314 */ 1315 private void writeObject(java.io.ObjectOutputStream oos) 1316 throws java.io.IOException { 1317 1318 if (which == Subject.PRIV_CREDENTIAL_SET) { 1319 // check permissions before serializing 1320 Iterator<E> i = iterator(); 1321 while (i.hasNext()) { 1322 i.next(); 1323 } 1324 } 1325 ObjectOutputStream.PutField fields = oos.putFields(); 1326 fields.put("this$0", subject); 1327 fields.put("elements", elements); 1328 fields.put("which", which); 1329 oos.writeFields(); 1330 } 1331 1332 @SuppressWarnings("unchecked") 1333 private void readObject(ObjectInputStream ois) 1334 throws IOException, ClassNotFoundException 1335 { 1336 ObjectInputStream.GetField fields = ois.readFields(); 1337 subject = (Subject) fields.get("this$0", null); 1338 which = fields.get("which", 0); 1339 1340 LinkedList<E> tmp = (LinkedList<E>) fields.get("elements", null); 1341 if (tmp.getClass() != LinkedList.class) { 1342 elements = new LinkedList<E>(tmp); 1343 } else { 1344 elements = tmp; 1345 } 1346 } 1347 } 1348 1349 /** 1350 * This class implements a {@code Set} which returns only 1351 * members that are an instance of a specified Class. 1352 */ 1353 private class ClassSet<T> extends AbstractSet<T> { 1354 1355 private int which; 1356 private Class<T> c; 1357 private Set<T> set; 1358 1359 ClassSet(int which, Class<T> c) { 1360 this.which = which; 1361 this.c = c; 1362 set = new HashSet<T>(); 1363 1364 switch (which) { 1365 case Subject.PRINCIPAL_SET: 1366 synchronized(principals) { populateSet(); } 1367 break; 1368 case Subject.PUB_CREDENTIAL_SET: 1369 synchronized(pubCredentials) { populateSet(); } 1370 break; 1371 default: 1372 synchronized(privCredentials) { populateSet(); } 1373 break; 1374 } 1375 } 1376 1377 @SuppressWarnings("unchecked") /*To suppress warning from line 1374*/ 1378 private void populateSet() { 1379 final Iterator<?> iterator; 1380 switch(which) { 1381 case Subject.PRINCIPAL_SET: 1382 iterator = Subject.this.principals.iterator(); 1383 break; 1384 case Subject.PUB_CREDENTIAL_SET: 1385 iterator = Subject.this.pubCredentials.iterator(); 1386 break; 1387 default: 1388 iterator = Subject.this.privCredentials.iterator(); 1389 break; 1390 } 1391 1392 // Check whether the caller has permisson to get 1393 // credentials of Class c 1394 1395 while (iterator.hasNext()) { 1396 Object next; 1397 if (which == Subject.PRIV_CREDENTIAL_SET) { 1398 next = java.security.AccessController.doPrivileged 1399 (new java.security.PrivilegedAction<Object>() { 1400 public Object run() { 1401 return iterator.next(); 1402 } 1403 }); 1404 } else { 1405 next = iterator.next(); 1406 } 1407 if (c.isAssignableFrom(next.getClass())) { 1408 if (which != Subject.PRIV_CREDENTIAL_SET) { 1409 set.add((T)next); 1410 } else { 1411 // Check permission for private creds 1412 SecurityManager sm = System.getSecurityManager(); 1413 if (sm != null) { 1414 sm.checkPermission(new PrivateCredentialPermission 1415 (next.getClass().getName(), 1416 Subject.this.getPrincipals())); 1417 } 1418 set.add((T)next); 1419 } 1420 } 1421 } 1422 } 1423 1424 public int size() { 1425 return set.size(); 1426 } 1427 1428 public Iterator<T> iterator() { 1429 return set.iterator(); 1430 } 1431 1432 public boolean add(T o) { 1433 1434 if (!o.getClass().isAssignableFrom(c)) { 1435 MessageFormat form = new MessageFormat(ResourcesMgr.getString 1436 ("attempting.to.add.an.object.which.is.not.an.instance.of.class")); 1437 Object[] source = {c.toString()}; 1438 throw new SecurityException(form.format(source)); 1439 } 1440 1441 return set.add(o); 1442 } 1443 } 1444 1445 static class AuthPermissionHolder { 1446 static final AuthPermission DO_AS_PERMISSION = 1447 new AuthPermission("doAs"); 1448 1449 static final AuthPermission DO_AS_PRIVILEGED_PERMISSION = 1450 new AuthPermission("doAsPrivileged"); 1451 1452 static final AuthPermission SET_READ_ONLY_PERMISSION = 1453 new AuthPermission("setReadOnly"); 1454 1455 static final AuthPermission GET_SUBJECT_PERMISSION = 1456 new AuthPermission("getSubject"); 1457 1458 static final AuthPermission MODIFY_PRINCIPALS_PERMISSION = 1459 new AuthPermission("modifyPrincipals"); 1460 1461 static final AuthPermission MODIFY_PUBLIC_CREDENTIALS_PERMISSION = 1462 new AuthPermission("modifyPublicCredentials"); 1463 1464 static final AuthPermission MODIFY_PRIVATE_CREDENTIALS_PERMISSION = 1465 new AuthPermission("modifyPrivateCredentials"); 1466 } 1467 } 1468
