- java.lang.Object
-
- javax.security.auth.Subject
-
- All Implemented Interfaces:
Serializable
public final class Subject extends Object implements Serializable
A
Subjectrepresents a grouping of related information for a single entity, such as a person. Such information includes the Subject's identities as well as its security-related attributes (passwords and cryptographic keys, for example).Subjects may potentially have multiple identities. Each identity is represented as a
Principalwithin theSubject. Principals simply bind names to aSubject. For example, aSubjectthat happens to be a person, Alice, might have two Principals: one which binds "Alice Bar", the name on her driver license, to theSubject, and another which binds, "999-99-9999", the number on her student identification card, to theSubject. Both Principals refer to the sameSubjecteven though each has a different name.A
Subjectmay also own security-related attributes, which are referred to as credentials. Sensitive credentials that require special protection, such as private cryptographic keys, are stored within a private credentialSet. Credentials intended to be shared, such as public key certificates or Kerberos server tickets are stored within a public credentialSet. Different permissions are required to access and modify the different credential Sets.To retrieve all the Principals associated with a
Subject, invoke thegetPrincipalsmethod. To retrieve all the public or private credentials belonging to aSubject, invoke thegetPublicCredentialsmethod orgetPrivateCredentialsmethod, respectively. To modify the returnedSetof Principals and credentials, use the methods defined in theSetclass. For example:Subject subject; Principal principal; Object credential; // add a Principal and credential to the Subject subject.getPrincipals().add(principal); subject.getPublicCredentials().add(credential);This
Subjectclass implementsSerializable. While the Principals associated with theSubjectare serialized, the credentials associated with theSubjectare not. Note that thejava.security.Principalclass does not implementSerializable. Therefore all concretePrincipalimplementations associated with Subjects must implementSerializable.- Since:
- 1.4
- See Also:
Principal,DomainCombiner, Serialized Form
-
-
Constructor Summary
Constructors Constructor Description Subject()Create an instance of aSubjectwith an emptySetof Principals and empty Sets of public and private credentials.Subject(boolean readOnly, Set<? extends Principal> principals, Set<?> pubCredentials, Set<?> privCredentials)Create an instance of aSubjectwith Principals and credentials.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description static <T> TdoAs(Subject subject, PrivilegedAction<T> action)Perform work as a particularSubject.static <T> TdoAs(Subject subject, PrivilegedExceptionAction<T> action)Perform work as a particularSubject.static <T> TdoAsPrivileged(Subject subject, PrivilegedAction<T> action, AccessControlContext acc)Perform privileged work as a particularSubject.static <T> TdoAsPrivileged(Subject subject, PrivilegedExceptionAction<T> action, AccessControlContext acc)Perform privileged work as a particularSubject.booleanequals(Object o)Compares the specified Object with thisSubjectfor equality.Set<Principal>getPrincipals()Return theSetof Principals associated with thisSubject.<T extends Principal>
Set<T>getPrincipals(Class<T> c)Return aSetof Principals associated with thisSubjectthat are instances or subclasses of the specifiedClass.Set<Object>getPrivateCredentials()Return theSetof private credentials held by thisSubject.<T> Set<T>getPrivateCredentials(Class<T> c)Return aSetof private credentials associated with thisSubjectthat are instances or subclasses of the specifiedClass.Set<Object>getPublicCredentials()Return theSetof public credentials held by thisSubject.<T> Set<T>getPublicCredentials(Class<T> c)Return aSetof public credentials associated with thisSubjectthat are instances or subclasses of the specifiedClass.static SubjectgetSubject(AccessControlContext acc)Get theSubjectassociated with the providedAccessControlContext.inthashCode()Returns a hashcode for thisSubject.booleanisReadOnly()Query whether thisSubjectis read-only.voidsetReadOnly()Set thisSubjectto be read-only.StringtoString()Return the String representation of thisSubject.
-
-
-
Constructor Detail
-
Subject
public Subject()
Create an instance of aSubjectwith an emptySetof Principals and empty Sets of public and private credentials.The newly constructed Sets check whether this
Subjecthas been set read-only before permitting subsequent modifications. The newly created Sets also prevent illegal modifications by ensuring that callers have sufficient permissions. These Sets also prohibit null elements, and attempts to add, query, or remove a null element will result in aNullPointerException.To modify the Principals Set, the caller must have
AuthPermission("modifyPrincipals"). To modify the public credential Set, the caller must haveAuthPermission("modifyPublicCredentials"). To modify the private credential Set, the caller must haveAuthPermission("modifyPrivateCredentials").
-
Subject
public Subject(boolean readOnly, Set<? extends Principal> principals, Set<?> pubCredentials, Set<?> privCredentials)Create an instance of aSubjectwith Principals and credentials.The Principals and credentials from the specified Sets are copied into newly constructed Sets. These newly created Sets check whether this
Subjecthas been set read-only before permitting subsequent modifications. The newly created Sets also prevent illegal modifications by ensuring that callers have sufficient permissions. These Sets also prohibit null elements, and attempts to add, query, or remove a null element will result in aNullPointerException.To modify the Principals Set, the caller must have
AuthPermission("modifyPrincipals"). To modify the public credential Set, the caller must haveAuthPermission("modifyPublicCredentials"). To modify the private credential Set, the caller must haveAuthPermission("modifyPrivateCredentials").- Parameters:
readOnly- true if theSubjectis to be read-only, and false otherwise.principals- theSetof Principals to be associated with thisSubject.pubCredentials- theSetof public credentials to be associated with thisSubject.privCredentials- theSetof private credentials to be associated with thisSubject.- Throws:
NullPointerException- if the specifiedprincipals,pubCredentials, orprivCredentialsarenull, or a null value exists within any of these three Sets.
-
-
Method Detail
-
setReadOnly
public void setReadOnly()
Set thisSubjectto be read-only.Modifications (additions and removals) to this Subject's
PrincipalSetand credential Sets will be disallowed. Thedestroyoperation on this Subject's credentials will still be permitted.Subsequent attempts to modify the Subject's
Principaland credential Sets will result in anIllegalStateExceptionbeing thrown. Also, once aSubjectis read-only, it can not be reset to being writable again.- Throws:
SecurityException- if a security manager is installed and the caller does not have anAuthPermission("setReadOnly")permission to set thisSubjectto be read-only.
-
isReadOnly
public boolean isReadOnly()
Query whether thisSubjectis read-only.- Returns:
- true if this
Subjectis read-only, false otherwise.
-
getSubject
public static Subject getSubject(AccessControlContext acc)
Get theSubjectassociated with the providedAccessControlContext.The
AccessControlContextmay contain many Subjects (from nesteddoAscalls). In this situation, the most recentSubjectassociated with theAccessControlContextis returned.- Parameters:
acc- theAccessControlContextfrom which to retrieve theSubject.- Returns:
- the
Subjectassociated with the providedAccessControlContext, ornullif noSubjectis associated with the providedAccessControlContext. - Throws:
SecurityException- if a security manager is installed and the caller does not have anAuthPermission("getSubject")permission to get theSubject.NullPointerException- if the providedAccessControlContextisnull.
-
doAs
public static <T> T doAs(Subject subject, PrivilegedAction<T> action)
Perform work as a particularSubject.This method first retrieves the current Thread's
AccessControlContextviaAccessController.getContext, and then instantiates a newAccessControlContextusing the retrieved context along with a newSubjectDomainCombiner(constructed using the providedSubject). Finally, this method invokesAccessController.doPrivileged, passing it the providedPrivilegedAction, as well as the newly constructedAccessControlContext.- Type Parameters:
T- the type of the value returned by the PrivilegedAction'srunmethod.- Parameters:
subject- theSubjectthat the specifiedactionwill run as. This parameter may benull.action- the code to be run as the specifiedSubject.- Returns:
- the value returned by the PrivilegedAction's
runmethod. - Throws:
NullPointerException- if thePrivilegedActionisnull.SecurityException- if a security manager is installed and the caller does not have anAuthPermission("doAs")permission to invoke this method.
-
doAs
public static <T> T doAs(Subject subject, PrivilegedExceptionAction<T> action) throws PrivilegedActionException
Perform work as a particularSubject.This method first retrieves the current Thread's
AccessControlContextviaAccessController.getContext, and then instantiates a newAccessControlContextusing the retrieved context along with a newSubjectDomainCombiner(constructed using the providedSubject). Finally, this method invokesAccessController.doPrivileged, passing it the providedPrivilegedExceptionAction, as well as the newly constructedAccessControlContext.- Type Parameters:
T- the type of the value returned by the PrivilegedExceptionAction'srunmethod.- Parameters:
subject- theSubjectthat the specifiedactionwill run as. This parameter may benull.action- the code to be run as the specifiedSubject.- Returns:
- the value returned by the
PrivilegedExceptionAction's
runmethod. - Throws:
PrivilegedActionException- if thePrivilegedExceptionAction.runmethod throws a checked exception.NullPointerException- if the specifiedPrivilegedExceptionActionisnull.SecurityException- if a security manager is installed and the caller does not have anAuthPermission("doAs")permission to invoke this method.
-
doAsPrivileged
public static <T> T doAsPrivileged(Subject subject, PrivilegedAction<T> action, AccessControlContext acc)
Perform privileged work as a particularSubject.This method behaves exactly as
Subject.doAs, except that instead of retrieving the current Thread'sAccessControlContext, it uses the providedAccessControlContext. If the providedAccessControlContextisnull, this method instantiates a newAccessControlContextwith an empty collection of ProtectionDomains.- Type Parameters:
T- the type of the value returned by the PrivilegedAction'srunmethod.- Parameters:
subject- theSubjectthat the specifiedactionwill run as. This parameter may benull.action- the code to be run as the specifiedSubject.acc- theAccessControlContextto be tied to the specified subject and action.- Returns:
- the value returned by the PrivilegedAction's
runmethod. - Throws:
NullPointerException- if thePrivilegedActionisnull.SecurityException- if a security manager is installed and the caller does not have aAuthPermission("doAsPrivileged")permission to invoke this method.
-
doAsPrivileged
public static <T> T doAsPrivileged(Subject subject, PrivilegedExceptionAction<T> action, AccessControlContext acc) throws PrivilegedActionException
Perform privileged work as a particularSubject.This method behaves exactly as
Subject.doAs, except that instead of retrieving the current Thread'sAccessControlContext, it uses the providedAccessControlContext. If the providedAccessControlContextisnull, this method instantiates a newAccessControlContextwith an empty collection of ProtectionDomains.- Type Parameters:
T- the type of the value returned by the PrivilegedExceptionAction'srunmethod.- Parameters:
subject- theSubjectthat the specifiedactionwill run as. This parameter may benull.action- the code to be run as the specifiedSubject.acc- theAccessControlContextto be tied to the specified subject and action.- Returns:
- the value returned by the
PrivilegedExceptionAction's
runmethod. - Throws:
PrivilegedActionException- if thePrivilegedExceptionAction.runmethod throws a checked exception.NullPointerException- if the specifiedPrivilegedExceptionActionisnull.SecurityException- if a security manager is installed and the caller does not have aAuthPermission("doAsPrivileged")permission to invoke this method.
-
getPrincipals
public Set<Principal> getPrincipals()
Return theSetof Principals associated with thisSubject. EachPrincipalrepresents an identity for thisSubject.The returned
Setis backed by this Subject's internalPrincipalSet. Any modification to the returnedSetaffects the internalPrincipalSetas well.If a security manager is installed, the caller must have a
AuthPermission("modifyPrincipals")permission to modify the returned set, or aSecurityExceptionwill be thrown.- Returns:
- the
Setof Principals associated with thisSubject.
-
getPrincipals
public <T extends Principal> Set<T> getPrincipals(Class<T> c)
Return aSetof Principals associated with thisSubjectthat are instances or subclasses of the specifiedClass.The returned
Setis not backed by this Subject's internalPrincipalSet. A newSetis created and returned for each method invocation. Modifications to the returnedSetwill not affect the internalPrincipalSet.- Type Parameters:
T- the type of the class modeled byc- Parameters:
c- the returnedSetof Principals will all be instances of this class.- Returns:
- a
Setof Principals that are instances of the specifiedClass. - Throws:
NullPointerException- if the specifiedClassisnull.
-
getPublicCredentials
public Set<Object> getPublicCredentials()
Return theSetof public credentials held by thisSubject.The returned
Setis backed by this Subject's internal public CredentialSet. Any modification to the returnedSetaffects the internal public CredentialSetas well.If a security manager is installed, the caller must have a
AuthPermission("modifyPublicCredentials")permission to modify the returned set, or aSecurityExceptionwill be thrown.- Returns:
- a
Setof public credentials held by thisSubject.
-
getPrivateCredentials
public Set<Object> getPrivateCredentials()
Return theSetof private credentials held by thisSubject.The returned
Setis backed by this Subject's internal private CredentialSet. Any modification to the returnedSetaffects the internal private CredentialSetas well.If a security manager is installed, the caller must have a
AuthPermission("modifyPrivateCredentials")permission to modify the returned set, or aSecurityExceptionwill be thrown.While iterating through the
Set, aSecurityExceptionis thrown if a security manager is installed and the caller does not have aPrivateCredentialPermissionto access a particular Credential. TheIteratoris nevertheless advanced to the next element in theSet.- Returns:
- a
Setof private credentials held by thisSubject.
-
getPublicCredentials
public <T> Set<T> getPublicCredentials(Class<T> c)
Return aSetof public credentials associated with thisSubjectthat are instances or subclasses of the specifiedClass.The returned
Setis not backed by this Subject's internal public CredentialSet. A newSetis created and returned for each method invocation. Modifications to the returnedSetwill not affect the internal public CredentialSet.- Type Parameters:
T- the type of the class modeled byc- Parameters:
c- the returnedSetof public credentials will all be instances of this class.- Returns:
- a
Setof public credentials that are instances of the specifiedClass. - Throws:
NullPointerException- if the specifiedClassisnull.
-
getPrivateCredentials
public <T> Set<T> getPrivateCredentials(Class<T> c)
Return aSetof private credentials associated with thisSubjectthat are instances or subclasses of the specifiedClass.If a security manager is installed, the caller must have a
PrivateCredentialPermissionto access all of the requested Credentials, or aSecurityExceptionwill be thrown.The returned
Setis not backed by this Subject's internal private CredentialSet. A newSetis created and returned for each method invocation. Modifications to the returnedSetwill not affect the internal private CredentialSet.- Type Parameters:
T- the type of the class modeled byc- Parameters:
c- the returnedSetof private credentials will all be instances of this class.- Returns:
- a
Setof private credentials that are instances of the specifiedClass. - Throws:
NullPointerException- if the specifiedClassisnull.
-
equals
public boolean equals(Object o)
Compares the specified Object with thisSubjectfor equality. Returns true if the given object is also a Subject and the twoSubjectinstances are equivalent. More formally, twoSubjectinstances are equal if theirPrincipalandCredentialSets are equal.- Overrides:
equalsin classObject- Parameters:
o- Object to be compared for equality with thisSubject.- Returns:
- true if the specified Object is equal to this
Subject. - Throws:
SecurityException- if a security manager is installed and the caller does not have aPrivateCredentialPermissionpermission to access the private credentials for thisSubjector the providedSubject.- See Also:
Object.hashCode()
-
toString
public String toString()
Return the String representation of thisSubject.
-
hashCode
public int hashCode()
Returns a hashcode for thisSubject.- Overrides:
hashCodein classObject- Returns:
- a hashcode for this
Subject. - Throws:
SecurityException- if a security manager is installed and the caller does not have aPrivateCredentialPermissionpermission to access this Subject's private credentials.- See Also:
Object.equals(java.lang.Object)
-
-