/*

 * Copyright (c) 1998, 2014, Oracle and/or its affiliates. All rights reserved.

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle in the LICENSE file that accompanied this code.

 *

 * This code is distributed in the hope that it will be useful, but WITHOUT

 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

 * or visit www.oracle.com if you need additional information or have any

 * questions.

 */

package javax.security.auth;

import java.util.*;

import java.io.*;

import java.lang.reflect.*;

import java.text.MessageFormat;

import java.security.AccessController;

import java.security.AccessControlContext;

import java.security.DomainCombiner;

import java.security.Permission;

import java.security.PermissionCollection;

import java.security.Principal;

import java.security.PrivilegedAction;

import java.security.PrivilegedExceptionAction;

import java.security.PrivilegedActionException;

import java.security.ProtectionDomain;

import sun.security.util.ResourcesMgr;

/**

 * <p> A {@code Subject} represents 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).

 *

 * <p> Subjects may potentially have multiple identities.

 * Each identity is represented as a {@code Principal}

 * within the {@code Subject}.  Principals simply bind names to a

 * {@code Subject}.  For example, a {@code Subject} that happens

 * to be a person, Alice, might have two Principals:

 * one which binds "Alice Bar", the name on her driver license,

 * to the {@code Subject}, and another which binds,

 * "999-99-9999", the number on her student identification card,

 * to the {@code Subject}.  Both Principals refer to the same

 * {@code Subject} even though each has a different name.

 *

 * <p> A {@code Subject} may 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 credential

 * {@code Set}.  Credentials intended to be shared, such as

 * public key certificates or Kerberos server tickets are stored

 * within a public credential {@code Set}.  Different permissions

 * are required to access and modify the different credential Sets.

 *

 * <p> To retrieve all the Principals associated with a {@code Subject},

 * invoke the {@code getPrincipals} method.  To retrieve

 * all the public or private credentials belonging to a {@code Subject},

 * invoke the {@code getPublicCredentials} method or

 * {@code getPrivateCredentials} method, respectively.

 * To modify the returned {@code Set} of Principals and credentials,

 * use the methods defined in the {@code Set} class.

 * For example:

 * <pre>

 *      Subject subject;

 *      Principal principal;

 *      Object credential;

 *

 *      // add a Principal and credential to the Subject

 *      subject.getPrincipals().add(principal);

 *      subject.getPublicCredentials().add(credential);

 * </pre>

 *

 * <p> This {@code Subject} class implements {@code Serializable}.

 * While the Principals associated with the {@code Subject} are serialized,

 * the credentials associated with the {@code Subject} are not.

 * Note that the {@code java.security.Principal} class

 * does not implement {@code Serializable}.  Therefore all concrete

 * {@code Principal} implementations associated with Subjects

 * must implement {@code Serializable}.

 *

 * @see java.security.Principal

 * @see java.security.DomainCombiner

 */

public final class Subject implements java.io.Serializable {

    private static final long serialVersionUID = -8308522755600156056L;

    /**

     * A {@code Set} that provides a view of all of this

     * Subject's Principals

     *

     * <p>

     *

     * @serial Each element in this set is a

     *          {@code java.security.Principal}.

     *          The set is a {@code Subject.SecureSet}.

     */

    Set<Principal> principals;

    /**

     * Sets that provide a view of all of this

     * Subject's Credentials

     */

    transient Set<Object> pubCredentials;

    transient Set<Object> privCredentials;

    /**

     * Whether this Subject is read-only

     *

     * @serial

     */

    private volatile boolean readOnly = false;

    private static final int PRINCIPAL_SET = 1;

    private static final int PUB_CREDENTIAL_SET = 2;

    private static final int PRIV_CREDENTIAL_SET = 3;

    private static final ProtectionDomain[] NULL_PD_ARRAY

        = new ProtectionDomain[0];

    /**

     * Create an instance of a {@code Subject}

     * with an empty {@code Set} of Principals and empty

     * Sets of public and private credentials.

     *

     * <p> The newly constructed Sets check whether this {@code Subject}

     * has 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 or query a null

     * element will result in a {@code NullPointerException}.

     *

     * <p> To modify the Principals Set, the caller must have

     * {@code AuthPermission("modifyPrincipals")}.

     * To modify the public credential Set, the caller must have

     * {@code AuthPermission("modifyPublicCredentials")}.

     * To modify the private credential Set, the caller must have

     * {@code AuthPermission("modifyPrivateCredentials")}.

     */

    public Subject() {

        this.principals = Collections.synchronizedSet

                        (new SecureSet<Principal>(this, PRINCIPAL_SET));

        this.pubCredentials = Collections.synchronizedSet

                        (new SecureSet<Object>(this, PUB_CREDENTIAL_SET));

        this.privCredentials = Collections.synchronizedSet

                        (new SecureSet<Object>(this, PRIV_CREDENTIAL_SET));

    }

    /**

     * Create an instance of a {@code Subject} with

     * Principals and credentials.

     *

     * <p> The Principals and credentials from the specified Sets

     * are copied into newly constructed Sets.

     * These newly created Sets check whether this {@code Subject}

     * has 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 or query a null

     * element will result in a {@code NullPointerException}.

     *

     * <p> To modify the Principals Set, the caller must have

     * {@code AuthPermission("modifyPrincipals")}.

     * To modify the public credential Set, the caller must have

     * {@code AuthPermission("modifyPublicCredentials")}.

     * To modify the private credential Set, the caller must have

     * {@code AuthPermission("modifyPrivateCredentials")}.

     *

     * @param readOnly true if the {@code Subject} is to be read-only,

     *

     * @param principals the {@code Set} of Principals

     *

     * @param pubCredentials the {@code Set} of public credentials

     *

     * @param privCredentials the {@code Set} of private credentials

     *          to be associated with this {@code Subject}.

     *

     *          {@code principals}, {@code pubCredentials},

     *          or {@code privCredentials} are {@code null},

     *          or a null value exists within any of these three

     *          Sets.

     */

    public Subject(boolean readOnly, Set<? extends Principal> principals,

                   Set<?> pubCredentials, Set<?> privCredentials)

    {

        collectionNullClean(principals);

        collectionNullClean(pubCredentials);

        collectionNullClean(privCredentials);

        this.principals = Collections.synchronizedSet(new SecureSet<Principal>

                                (this, PRINCIPAL_SET, principals));

        this.pubCredentials = Collections.synchronizedSet(new SecureSet<Object>

                                (this, PUB_CREDENTIAL_SET, pubCredentials));

        this.privCredentials = Collections.synchronizedSet(new SecureSet<Object>

                                (this, PRIV_CREDENTIAL_SET, privCredentials));

        this.readOnly = readOnly;

    }

    /**

     * Set this {@code Subject} to be read-only.

     *

     * <p> Modifications (additions and removals) to this Subject's

     * {@code Principal} {@code Set} and

     * credential Sets will be disallowed.

     * The {@code destroy} operation on this Subject's credentials will

     * still be permitted.

     *

     * <p> Subsequent attempts to modify the Subject's {@code Principal}

     * and credential Sets will result in an

     * {@code IllegalStateException} being thrown.

     * Also, once a {@code Subject} is read-only,

     * it can not be reset to being writable again.

     *

     */

    public void setReadOnly() {

        java.lang.SecurityManager sm = System.getSecurityManager();

        if (sm != null) {

            sm.checkPermission(AuthPermissionHolder.SET_READ_ONLY_PERMISSION);

        }

        this.readOnly = true;

    }

    /**

     * Query whether this {@code Subject} is read-only.

     *

     * @return true if this {@code Subject} is read-only, false otherwise.

     */

    public boolean isReadOnly() {

        return this.readOnly;

    }

    /**

     * Get the {@code Subject} associated with the provided

     * {@code AccessControlContext}.

     *

     * <p> The {@code AccessControlContext} may contain many

     * Subjects (from nested {@code doAs} calls).

     * In this situation, the most recent {@code Subject} associated

     * with the {@code AccessControlContext} is returned.

     *

     * @param  acc the {@code AccessControlContext} from which to retrieve

     *          the {@code Subject}.

     *

     * @return  the {@code Subject} associated with the provided

     *          {@code AccessControlContext}, or {@code null}

     *          if no {@code Subject} is associated

     *          with the provided {@code AccessControlContext}.

     *

     *

     *          {@code AccessControlContext} is {@code null}.

     */

    public static Subject getSubject(final AccessControlContext acc) {

        java.lang.SecurityManager sm = System.getSecurityManager();

        if (sm != null) {

            sm.checkPermission(AuthPermissionHolder.GET_SUBJECT_PERMISSION);

        }

        Objects.requireNonNull(acc, ResourcesMgr.getString

                ("invalid.null.AccessControlContext.provided"));

        // return the Subject from the DomainCombiner of the provided context

        return AccessController.doPrivileged

            (new java.security.PrivilegedAction<Subject>() {

            public Subject run() {

                DomainCombiner dc = acc.getDomainCombiner();

                if (!(dc instanceof SubjectDomainCombiner)) {

                    return null;

                }

                SubjectDomainCombiner sdc = (SubjectDomainCombiner)dc;

                return sdc.getSubject();

            }

        });

    }

    /**

     * Perform work as a particular {@code Subject}.

     *

     * <p> This method first retrieves the current Thread's

     * {@code AccessControlContext} via

     * {@code AccessController.getContext},

     * and then instantiates a new {@code AccessControlContext}

     * using the retrieved context along with a new

     * {@code SubjectDomainCombiner} (constructed using

     * the provided {@code Subject}).

     * Finally, this method invokes {@code AccessController.doPrivileged},

     * passing it the provided {@code PrivilegedAction},

     * as well as the newly constructed {@code AccessControlContext}.

     *

     * @param subject the {@code Subject} that the specified

     *                  {@code action} will run as.  This parameter

     *

     * @param <T> the type of the value returned by the PrivilegedAction's

     *                  {@code run} method.

     *

     * @param action the code to be run as the specified

     *

     * @return the value returned by the PrivilegedAction's

     *                  {@code run} method.

     *

     *

     */

    public static <T> T doAs(final Subject subject,

                        final java.security.PrivilegedAction<T> action) {

        java.lang.SecurityManager sm = System.getSecurityManager();

        if (sm != null) {

            sm.checkPermission(AuthPermissionHolder.DO_AS_PERMISSION);

        }

        Objects.requireNonNull(action,

                ResourcesMgr.getString("invalid.null.action.provided"));

        // set up the new Subject-based AccessControlContext

        // for doPrivileged

        final AccessControlContext currentAcc = AccessController.getContext();

        // call doPrivileged and push this new context on the stack

        return java.security.AccessController.doPrivileged

                                        (action,

                                        createContext(subject, currentAcc));

    }

    /**

     * Perform work as a particular {@code Subject}.

     *

     * <p> This method first retrieves the current Thread's

     * {@code AccessControlContext} via

     * {@code AccessController.getContext},

     * and then instantiates a new {@code AccessControlContext}

     * using the retrieved context along with a new

     * {@code SubjectDomainCombiner} (constructed using

     * the provided {@code Subject}).

     * Finally, this method invokes {@code AccessController.doPrivileged},

     * passing it the provided {@code PrivilegedExceptionAction},

     * as well as the newly constructed {@code AccessControlContext}.

     *

     * @param subject the {@code Subject} that the specified

     *                  {@code action} will run as.  This parameter

     *

     * @param <T> the type of the value returned by the

     *                  PrivilegedExceptionAction's {@code run} method.

     *

     * @param action the code to be run as the specified

     *

     * @return the value returned by the

     *                  PrivilegedExceptionAction's {@code run} method.

     *

     *                  {@code PrivilegedExceptionAction.run}

     *

     *                  {@code PrivilegedExceptionAction} is

     *

     */

    public static <T> T doAs(final Subject subject,

                        final java.security.PrivilegedExceptionAction<T> action)

                        throws java.security.PrivilegedActionException {

        java.lang.SecurityManager sm = System.getSecurityManager();

        if (sm != null) {

            sm.checkPermission(AuthPermissionHolder.DO_AS_PERMISSION);

        }

        Objects.requireNonNull(action,

                ResourcesMgr.getString("invalid.null.action.provided"));

        // set up the new Subject-based AccessControlContext for doPrivileged

        final AccessControlContext currentAcc = AccessController.getContext();

        // call doPrivileged and push this new context on the stack

        return java.security.AccessController.doPrivileged

                                        (action,

                                        createContext(subject, currentAcc));

    }

    /**

     * Perform privileged work as a particular {@code Subject}.

     *

     * <p> This method behaves exactly as {@code Subject.doAs},

     * except that instead of retrieving the current Thread's

     * {@code AccessControlContext}, it uses the provided

     * {@code AccessControlContext}.  If the provided

     * {@code AccessControlContext} is {@code null},

     * this method instantiates a new {@code AccessControlContext}

     * with an empty collection of ProtectionDomains.

     *

     * @param subject the {@code Subject} that the specified

     *                  {@code action} will run as.  This parameter

     *

     * @param <T> the type of the value returned by the PrivilegedAction's

     *                  {@code run} method.

     *

     * @param action the code to be run as the specified

     *

     * @param acc the {@code AccessControlContext} to be tied to the

     *

     * @return the value returned by the PrivilegedAction's

     *                  {@code run} method.

     *

     *

     */

    public static <T> T doAsPrivileged(final Subject subject,

                        final java.security.PrivilegedAction<T> action,

                        final java.security.AccessControlContext acc) {

        java.lang.SecurityManager sm = System.getSecurityManager();

        if (sm != null) {

            sm.checkPermission(AuthPermissionHolder.DO_AS_PRIVILEGED_PERMISSION);

        }

        Objects.requireNonNull(action,

                ResourcesMgr.getString("invalid.null.action.provided"));

        // set up the new Subject-based AccessControlContext

        // for doPrivileged

        final AccessControlContext callerAcc =

                (acc == null ?

                new AccessControlContext(NULL_PD_ARRAY) :

                acc);

        // call doPrivileged and push this new context on the stack

        return java.security.AccessController.doPrivileged

                                        (action,

                                        createContext(subject, callerAcc));

    }

    /**

     * Perform privileged work as a particular {@code Subject}.

     *

     * <p> This method behaves exactly as {@code Subject.doAs},

     * except that instead of retrieving the current Thread's

     * {@code AccessControlContext}, it uses the provided

     * {@code AccessControlContext}.  If the provided

     * {@code AccessControlContext} is {@code null},

     * this method instantiates a new {@code AccessControlContext}

     * with an empty collection of ProtectionDomains.

     *

     * @param subject the {@code Subject} that the specified

     *                  {@code action} will run as.  This parameter