/*

 * 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 java.security;

import java.io.*;

import java.net.URI;

import java.security.cert.Certificate;

import java.security.cert.X509Certificate;

import java.security.cert.CertificateException;

import java.security.spec.AlgorithmParameterSpec;

import java.util.*;

import javax.crypto.SecretKey;

import javax.security.auth.DestroyFailedException;

import javax.security.auth.callback.*;

import sun.security.util.Debug;

/**

 * This class represents a storage facility for cryptographic

 * keys and certificates.

 *

 * <p> A {@code KeyStore} manages different types of entries.

 * Each type of entry implements the {@code KeyStore.Entry} interface.

 * Three basic {@code KeyStore.Entry} implementations are provided:

 *

 * <ul>

 * <li><b>KeyStore.PrivateKeyEntry</b>

 * <p> This type of entry holds a cryptographic {@code PrivateKey},

 * which is optionally stored in a protected format to prevent

 * unauthorized access.  It is also accompanied by a certificate chain

 * for the corresponding public key.

 *

 * <p> Private keys and certificate chains are used by a given entity for

 * self-authentication. Applications for this authentication include software

 * distribution organizations which sign JAR files as part of releasing

 * and/or licensing software.

 *

 * <li><b>KeyStore.SecretKeyEntry</b>

 * <p> This type of entry holds a cryptographic {@code SecretKey},

 * which is optionally stored in a protected format to prevent

 * unauthorized access.

 *

 * <li><b>KeyStore.TrustedCertificateEntry</b>

 * <p> This type of entry contains a single public key {@code Certificate}

 * belonging to another party. It is called a <i>trusted certificate</i>

 * because the keystore owner trusts that the public key in the certificate

 * indeed belongs to the identity identified by the <i>subject</i> (owner)

 * of the certificate.

 *

 * <p>This type of entry can be used to authenticate other parties.

 * </ul>

 *

 * <p> Each entry in a keystore is identified by an "alias" string. In the

 * case of private keys and their associated certificate chains, these strings

 * distinguish among the different ways in which the entity may authenticate

 * itself. For example, the entity may authenticate itself using different

 * certificate authorities, or using different public key algorithms.

 *

 * <p> Whether aliases are case sensitive is implementation dependent. In order

 * to avoid problems, it is recommended not to use aliases in a KeyStore that

 * only differ in case.

 *

 * <p> Whether keystores are persistent, and the mechanisms used by the

 * keystore if it is persistent, are not specified here. This allows

 * use of a variety of techniques for protecting sensitive (e.g., private or

 * secret) keys. Smart cards or other integrated cryptographic engines

 * (SafeKeyper) are one option, and simpler mechanisms such as files may also

 * be used (in a variety of formats).

 *

 * <p> Typical ways to request a KeyStore object include

 * relying on the default type and providing a specific keystore type.

 *

 * <ul>

 * <li>To rely on the default type:

 * <pre>

 *    KeyStore ks = KeyStore.getInstance(KeyStore.getDefaultType());

 * </pre>

 * The system will return a keystore implementation for the default type.

 *

 * <li>To provide a specific keystore type:

 * <pre>

 *      KeyStore ks = KeyStore.getInstance("JKS");

 * </pre>

 * The system will return the most preferred implementation of the

 * specified keystore type available in the environment. <p>

 * </ul>

 *

 * <p> Before a keystore can be accessed, it must be

 * <pre>

 *    KeyStore ks = KeyStore.getInstance(KeyStore.getDefaultType());

 *

 *    // get user password and file input stream

 *    char[] password = getPassword();

 *

 *    try (FileInputStream fis = new FileInputStream("keyStoreName")) {

 *        ks.load(fis, password);

 *    }

 * </pre>

 *

 * To create an empty keystore using the above {@code load} method,

 * pass {@code null} as the {@code InputStream} argument.

 *

 * <p> Once the keystore has been loaded, it is possible

 * to read existing entries from the keystore, or to write new entries

 * into the keystore:

 * <pre>

 *    KeyStore.ProtectionParameter protParam =

 *        new KeyStore.PasswordProtection(password);

 *

 *    // get my private key

 *    KeyStore.PrivateKeyEntry pkEntry = (KeyStore.PrivateKeyEntry)

 *        ks.getEntry("privateKeyAlias", protParam);

 *    PrivateKey myPrivateKey = pkEntry.getPrivateKey();

 *

 *    // save my secret key

 *    javax.crypto.SecretKey mySecretKey;

 *    KeyStore.SecretKeyEntry skEntry =

 *        new KeyStore.SecretKeyEntry(mySecretKey);

 *    ks.setEntry("secretKeyAlias", skEntry, protParam);

 *

 *    // store away the keystore

 *    try (FileOutputStream fos = new FileOutputStream("newKeyStoreName")) {

 *        ks.store(fos, password);

 *    }

 * </pre>

 *

 * Note that although the same password may be used to

 * load the keystore, to protect the private key entry,

 * to protect the secret key entry, and to store the keystore

 * (as is shown in the sample code above),

 * different passwords or other protection parameters

 * may also be used.

 *

 * <p> Every implementation of the Java platform is required to support

 * the following standard {@code KeyStore} type:

 * <ul>

 * <li>{@code PKCS12}</li>

 * </ul>

 * This type is described in the <a href=

 * "{@docRoot}/../technotes/guides/security/StandardNames.html#KeyStore">

 * KeyStore section</a> of the

 * Java Cryptography Architecture Standard Algorithm Name Documentation.

 * Consult the release documentation for your implementation to see if any

 * other types are supported.

 *

 * @author Jan Luehe

 *

 * @see java.security.PrivateKey

 * @see javax.crypto.SecretKey

 * @see java.security.cert.Certificate

 *

 * @since 1.2

 */

public class KeyStore {

    private static final Debug pdebug =

                        Debug.getInstance("provider", "Provider");

    private static final boolean skipDebug =

        Debug.isOn("engine=") && !Debug.isOn("keystore");

    /*

     * Constant to lookup in the Security properties file to determine

     * the default keystore type.

     * In the Security properties file, the default keystore type is given as:

     * <pre>

     * keystore.type=jks

     * </pre>

     */

    private static final String KEYSTORE_TYPE = "keystore.type";

    // The keystore type

    private String type;

    // The provider

    private Provider provider;

    // The provider implementation

    private KeyStoreSpi keyStoreSpi;

    // Has this keystore been initialized (loaded)?

    private boolean initialized = false;

    /**

     * A marker interface for {@code KeyStore}

     * {@link #load(KeyStore.LoadStoreParameter) load}

     * and

     * {@link #store(KeyStore.LoadStoreParameter) store}

     * parameters.

     *

     * @since 1.5

     */

    public static interface LoadStoreParameter {

        /**

         * Gets the parameter used to protect keystore data.

         *

         * @return the parameter used to protect keystore data, or null

         */

        public ProtectionParameter getProtectionParameter();

    }

    /**

     * A marker interface for keystore protection parameters.

     *

     * <p> The information stored in a {@code ProtectionParameter}

     * object protects the contents of a keystore.

     * For example, protection parameters may be used to check

     * the integrity of keystore data, or to protect the

     * confidentiality of sensitive keystore data

     * (such as a {@code PrivateKey}).

     *

     * @since 1.5

     */

    public static interface ProtectionParameter { }

    /**

     * A password-based implementation of {@code ProtectionParameter}.

     *

     * @since 1.5

     */

    public static class PasswordProtection implements

                ProtectionParameter, javax.security.auth.Destroyable {

        private final char[] password;

        private final String protectionAlgorithm;

        private final AlgorithmParameterSpec protectionParameters;

        private volatile boolean destroyed = false;

        /**

         * Creates a password parameter.

         *

         * <p> The specified {@code password} is cloned before it is stored

         * in the new {@code PasswordProtection} object.

         *

         * @param password the password, which may be {@code null}

         */

        public PasswordProtection(char[] password) {

            this.password = (password == null) ? null : password.clone();

            this.protectionAlgorithm = null;

            this.protectionParameters = null;

        }

        /**

         * Creates a password parameter and specifies the protection algorithm

         * and associated parameters to use when encrypting a keystore entry.

         * <p>

         * The specified {@code password} is cloned before it is stored in the

         * new {@code PasswordProtection} object.

         *

         * @param password the password, which may be {@code null}

         * @param protectionAlgorithm the encryption algorithm name, for

         *     example, {@code PBEWithHmacSHA256AndAES_256}.

         *     See the Cipher section in the <a href=

         * "{@docRoot}/../technotes/guides/security/StandardNames.html#Cipher">

         * Java Cryptography Architecture Standard Algorithm Name

         * Documentation</a>

         *     for information about standard encryption algorithm names.

         * @param protectionParameters the encryption algorithm parameter

         *     specification, which may be {@code null}

         * @exception NullPointerException if {@code protectionAlgorithm} is

         *     {@code null}

         *

         * @since 1.8

         */

        public PasswordProtection(char[] password, String protectionAlgorithm,

            AlgorithmParameterSpec protectionParameters) {

            if (protectionAlgorithm == null) {

                throw new NullPointerException("invalid null input");

            }

            this.password = (password == null) ? null : password.clone();

            this.protectionAlgorithm = protectionAlgorithm;

            this.protectionParameters = protectionParameters;

        }

        /**

         * Gets the name of the protection algorithm.

         * If none was set then the keystore provider will use its default

         * protection algorithm. The name of the default protection algorithm

         * for a given keystore type is set using the

         * {@code 'keystore.<type>.keyProtectionAlgorithm'} security property.

         * For example, the

         * {@code keystore.PKCS12.keyProtectionAlgorithm} property stores the

         * name of the default key protection algorithm used for PKCS12

         * keystores. If the security property is not set, an

         * implementation-specific algorithm will be used.

         *

         * @return the algorithm name, or {@code null} if none was set

         *

         * @since 1.8

         */

        public String getProtectionAlgorithm() {

            return protectionAlgorithm;

        }

        /**

         * Gets the parameters supplied for the protection algorithm.

         *

         * @return the algorithm parameter specification, or {@code  null},

         *     if none was set

         *

         * @since 1.8

         */

        public AlgorithmParameterSpec getProtectionParameters() {

            return protectionParameters;

        }

        /**

         * Gets the password.

         *

         * <p>Note that this method returns a reference to the password.

         * If a clone of the array is created it is the caller's

         * responsibility to zero out the password information

         * after it is no longer needed.

         *

         * @see #destroy()

         * @return the password, which may be {@code null}

         * @exception IllegalStateException if the password has

         *              been cleared (destroyed)

         */

        public synchronized char[] getPassword() {

            if (destroyed) {

                throw new IllegalStateException("password has been cleared");

            }

            return password;

        }

        /**

         * Clears the password.

         *

         * @exception DestroyFailedException if this method was unable

         *      to clear the password

         */

        public synchronized void destroy() throws DestroyFailedException {

            destroyed = true;

            if (password != null) {

                Arrays.fill(password, ' ');

            }

        }

        /**

         * Determines if password has been cleared.

         *

         * @return true if the password has been cleared, false otherwise

         */

        public synchronized boolean isDestroyed() {

            return destroyed;

        }

    }

    /**

     * A ProtectionParameter encapsulating a CallbackHandler.

     *

     * @since 1.5

     */

    public static class CallbackHandlerProtection

            implements ProtectionParameter {

        private final CallbackHandler handler;

        /**

         * Constructs a new CallbackHandlerProtection from a

         * CallbackHandler.

         *

         * @param handler the CallbackHandler

         * @exception NullPointerException if handler is null

         */

        public CallbackHandlerProtection(CallbackHandler handler) {

            if (handler == null) {

                throw new NullPointerException("handler must not be null");

            }

            this.handler = handler;

        }

        /**

         * Returns the CallbackHandler.

         *

         * @return the CallbackHandler.

         */

        public CallbackHandler getCallbackHandler() {

            return handler;

        }

    }

    /**

     * A marker interface for {@code KeyStore} entry types.

     *

     * @since 1.5

     */

    public static interface Entry {

        /**

         * Retrieves the attributes associated with an entry.

         *

         * @implSpec

         * The default implementation returns an empty {@code Set}.

         *

         * @return an unmodifiable {@code Set} of attributes, possibly empty

         *

         * @since 1.8

         */

        public default Set<Attribute> getAttributes() {

            return Collections.<Attribute>emptySet();

        }

        /**

         * An attribute associated with a keystore entry.

         * It comprises a name and one or more values.

         *

         * @since 1.8

         */

        public interface Attribute {

            /**

             * Returns the attribute's name.

             *

             * @return the attribute name

             */

            public String getName();

            /**

             * Returns the attribute's value.

             * Multi-valued attributes encode their values as a single string.

             *

             * @return the attribute value

             */

            public String getValue();

        }

    }

    /**

     * A {@code KeyStore} entry that holds a {@code PrivateKey}

     * and corresponding certificate chain.

     *

     * @since 1.5

     */

    public static final class PrivateKeyEntry implements Entry {

        private final PrivateKey privKey;

        private final Certificate[] chain;

        private final Set<Attribute> attributes;

        /**

         * Constructs a {@code PrivateKeyEntry} with a

         * {@code PrivateKey} and corresponding certificate chain.

         *

         * <p> The specified {@code chain} is cloned before it is stored

         * in the new {@code PrivateKeyEntry} object.

         *

         * @param privateKey the {@code PrivateKey}

         * @param chain an array of {@code Certificate}s

         *      representing the certificate chain.

         *      The chain must be ordered and contain a

         *      {@code Certificate} at index 0

         *      corresponding to the private key.

         *

         * @exception NullPointerException if

         *      {@code privateKey} or {@code chain}

         *      is {@code null}

         * @exception IllegalArgumentException if the specified chain has a

         *      length of 0, if the specified chain does not contain

         *      {@code Certificate}s of the same type,

         *      or if the {@code PrivateKey} algorithm

         *      does not match the algorithm of the {@code PublicKey}

         *      in the end entity {@code Certificate} (at index 0)

         */

        public PrivateKeyEntry(PrivateKey privateKey, Certificate[] chain) {

            this(privateKey, chain, Collections.<Attribute>emptySet());

        }