/*

 * Copyright (c) 1998, 2013, 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;

/**

 * 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.

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

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

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

 *

 * which are referred to as credentials.

 * Sensitive credentials that require special protection, such as

 * private cryptographic keys, are stored within a private credential

 * public key certificates or Kerberos server tickets are stored

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

 *

 * 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>

 *

 *

 * @see java.security.Principal

 * @see java.security.DomainCombiner

 */

public final class Subject implements java.io.Serializable {

    private static final long serialVersionUID = -8308522755600156056L;

    /**

     * Subject's Principals

     *

     * <p>

     *

     * @serial Each element in this set is a

     */

    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];

    /**

     * Sets of public and private credentials.

     *

     * has been set read-only before permitting subsequent modifications.

     * The newly created Sets also prevent illegal modifications

     * by ensuring that callers have sufficient permissions.

     *

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

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

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

     */

    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));

    }

    /**

     * Principals and credentials.

     *

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

     * are copied into newly constructed Sets.

     * has been set read-only before permitting subsequent modifications.

     * The newly created Sets also prevent illegal modifications

     * by ensuring that callers have sufficient permissions.

     *

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

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

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

     * <p>

     *

     *          and false otherwise. <p>

     *

     *

     *

     *

     * @exception NullPointerException if the specified

     */

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

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

    {

        if (principals == null ||

            pubCredentials == null ||

            privCredentials == null)

            throw new NullPointerException

                (ResourcesMgr.getString("invalid.null.input.s."));

        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;

    }

    /**

     *

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

     * credential Sets will be disallowed.

     * still be permitted.

     *

     * and credential Sets will result in an

     * it can not be reset to being writable again.

     *

     * <p>

     *

     * @exception SecurityException if the caller does not have permission

     */

    public void setReadOnly() {

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

        if (sm != null) {

            sm.checkPermission(AuthPermissionHolder.SET_READ_ONLY_PERMISSION);

        }

        this.readOnly = true;

    }

    /**

     *

     * <p>

     *

     */

    public boolean isReadOnly() {

        return this.readOnly;

    }

    /**

     *

     *

     * <p>

     *

     *

     *

     * @exception SecurityException if the caller does not have permission

     *

     * @exception NullPointerException if the provided

     */

    public static Subject getSubject(final AccessControlContext acc) {

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

        if (sm != null) {

            sm.checkPermission(AuthPermissionHolder.GET_SUBJECT_PERMISSION);

        }

        if (acc == null) {

            throw new NullPointerException(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();

            }

        });

    }

    /**

     *

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

     * using the retrieved context along with a new

     *

     * <p>

     *

     *

     * @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

     *

     *

     * @exception SecurityException if the caller does not have permission

     *                  to invoke this 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);

        }

        if (action == null)

            throw new NullPointerException

                (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));

    }

    /**

     *

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

     * using the retrieved context along with a new

     *

     * <p>

     *

     *

     * @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

     *

     * @exception PrivilegedActionException if the

     *                  method throws a checked exception. <p>

     *

     * @exception NullPointerException if the specified

     *

     * @exception SecurityException if the caller does not have permission

     *                  to invoke this method.

     */

    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);

        }

        if (action == null)

            throw new NullPointerException

                (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));

    }

    /**

     *

     * except that instead of retrieving the current Thread's

     * with an empty collection of ProtectionDomains.

     *

     * <p>

     *

     *

     * @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

     *

     *                  specified <i>subject</i> and <i>action</i>. <p>

     *

     * @return the value returned by the PrivilegedAction's

     *

     *

     * @exception SecurityException if the caller does not have permission

     *                  to invoke this 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);

        }

        if (action == null)

            throw new NullPointerException

                (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));

    }

    /**

     *

     * except that instead of retrieving the current Thread's

     * with an empty collection of ProtectionDomains.

     *

     * <p>

     *

     *

     * @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