/*

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

import java.security.cert.X509Certificate;

import java.security.cert.CertificateException;

import java.util.*;

import javax.crypto.SecretKey;

import javax.security.auth.callback.*;

/**

 * This class represents a storage facility for cryptographic

 * keys and certificates.

 *

 * <p> A <code>KeyStore</code> manages different types of entries.

 * Each type of entry implements the <code>KeyStore.Entry</code> interface.

 * Three basic <code>KeyStore.Entry</code> implementations are provided:

 *

 * <ul>

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

 * <p> This type of entry holds a cryptographic <code>PrivateKey</code>,

 * 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</code>,

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

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

 * <p>

 *

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

 * {@link #load(java.io.InputStream, char[]) loaded}.

 * <pre>

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

 *

 *    // get user password and file input stream

 *    char[] password = getPassword();

 *

 *    java.io.FileInputStream fis = null;

 *    try {

 *        fis = new java.io.FileInputStream("keyStoreName");

 *        ks.load(fis, password);

 *    } finally {

 *        if (fis != null) {

 *            fis.close();

 *        }

 *    }

 * </pre>

 *

 * To create an empty keystore using the above <code>load</code> method,

 * pass <code>null</code> as the <code>InputStream</code> 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

 *    java.io.FileOutputStream fos = null;

 *    try {

 *        fos = new java.io.FileOutputStream("newKeyStoreName");

 *        ks.store(fos, password);

 *    } finally {

 *        if (fos != null) {

 *            fos.close();

 *        }

 *    }

 * </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</code> type:

 * <ul>

 * <li><tt>PKCS12</tt></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 {

    /*

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

     * {@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</code>

     * 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</code>).

     *

     * @since 1.5

     */

    public static interface ProtectionParameter { }

    /**

     * A password-based implementation of <code>ProtectionParameter</code>.

     *

     * @since 1.5

     */

    public static class PasswordProtection implements

                ProtectionParameter, javax.security.auth.Destroyable {

        private final char[] password;

        private volatile boolean destroyed = false;

        /**

         * Creates a password parameter.

         *

         * <p> The specified <code>password</code> is cloned before it is stored

         * in the new <code>PasswordProtection</code> object.

         *

         * @param password the password, which may be <code>null</code>

         */

        public PasswordProtection(char[] password) {

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

        }

        /**

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

         * @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 javax.security.auth.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</code> entry types.

     *

     * @since 1.5

     */

    public static interface Entry { }

    /**

     * A <code>KeyStore</code> entry that holds a <code>PrivateKey</code>

     * and corresponding certificate chain.

     *

     * @since 1.5

     */

    public static final class PrivateKeyEntry implements Entry {

        private final PrivateKey privKey;

        private final Certificate[] chain;

        /**

         * Constructs a <code>PrivateKeyEntry</code> with a

         * <code>PrivateKey</code> and corresponding certificate chain.

         *

         * <p> The specified <code>chain</code> is cloned before it is stored

         * in the new <code>PrivateKeyEntry</code> object.

         *

         * @param privateKey the <code>PrivateKey</code>

         * @param chain an array of <code>Certificate</code>s

         *      representing the certificate chain.

         *      The chain must be ordered and contain a

         *      <code>Certificate</code> at index 0

         *      corresponding to the private key.

         *

         * @exception NullPointerException if

         *      <code>privateKey</code> or <code>chain</code>

         *      is <code>null</code>

         * @exception IllegalArgumentException if the specified chain has a

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

         *      <code>Certificate</code>s of the same type,

         *      or if the <code>PrivateKey</code> algorithm

         *      does not match the algorithm of the <code>PublicKey</code>

         *      in the end entity <code>Certificate</code> (at index 0)

         */

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

            if (privateKey == null || chain == null) {

                throw new NullPointerException("invalid null input");

            }

            if (chain.length == 0) {

                throw new IllegalArgumentException

                                ("invalid zero-length input chain");

            }

            Certificate[] clonedChain = chain.clone();

            String certType = clonedChain[0].getType();

            for (int i = 1; i < clonedChain.length; i++) {

                if (!certType.equals(clonedChain[i].getType())) {

                    throw new IllegalArgumentException

                                ("chain does not contain certificates " +

                                "of the same type");

                }

            }

            if (!privateKey.getAlgorithm().equals

                        (clonedChain[0].getPublicKey().getAlgorithm())) {

                throw new IllegalArgumentException

                                ("private key algorithm does not match " +

                                "algorithm of public key in end entity " +

                                "certificate (at index 0)");

            }

            this.privKey = privateKey;

            if (clonedChain[0] instanceof X509Certificate &&

                !(clonedChain instanceof X509Certificate[])) {

                this.chain = new X509Certificate[clonedChain.length];

                System.arraycopy(clonedChain, 0,

                                this.chain, 0, clonedChain.length);

            } else {

                this.chain = clonedChain;

            }

        }

        /**

         * Gets the <code>PrivateKey</code> from this entry.

         *

         * @return the <code>PrivateKey</code> from this entry

         */

        public PrivateKey getPrivateKey() {

            return privKey;

        }

        /**

         * Gets the <code>Certificate</code> chain from this entry.

         *

         * <p> The stored chain is cloned before being returned.

         *

         * @return an array of <code>Certificate</code>s corresponding

         *      to the certificate chain for the public key.

         *      If the certificates are of type X.509,

         *      the runtime type of the returned array is

         *      <code>X509Certificate[]</code>.

         */

        public Certificate[] getCertificateChain() {

            return chain.clone();

        }

        /**

         * Gets the end entity <code>Certificate</code>

         * from the certificate chain in this entry.

         *

         * @return the end entity <code>Certificate</code> (at index 0)

         *      from the certificate chain in this entry.

         *      If the certificate is of type X.509,

         *      the runtime type of the returned certificate is

         *      <code>X509Certificate</code>.

         */

        public Certificate getCertificate() {

            return chain[0];

        }

        /**

         * Returns a string representation of this PrivateKeyEntry.

         * @return a string representation of this PrivateKeyEntry.

         */

        public String toString() {

            StringBuilder sb = new StringBuilder();

            sb.append("Private key entry and certificate chain with "

                + chain.length + " elements:\r\n");

            for (Certificate cert : chain) {

                sb.append(cert);

                sb.append("\r\n");

            }

            return sb.toString();

        }

    }

    /**

     * A <code>KeyStore</code> entry that holds a <code>SecretKey</code>.

     *

     * @since 1.5

     */

    public static final class SecretKeyEntry implements Entry {

        private final SecretKey sKey;

        /**

         * Constructs a <code>SecretKeyEntry</code> with a

         * <code>SecretKey</code>.

         *

         * @param secretKey the <code>SecretKey</code>

         *

         * @exception NullPointerException if <code>secretKey</code>

         *      is <code>null</code>

         */

        public SecretKeyEntry(SecretKey secretKey) {

            if (secretKey == null) {

                throw new NullPointerException("invalid null input");

            }

            this.sKey = secretKey;

        }

        /**

         * Gets the <code>SecretKey</code> from this entry.

         *

         * @return the <code>SecretKey</code> from this entry

         */

        public SecretKey getSecretKey() {

            return sKey;

        }

        /**

         * Returns a string representation of this SecretKeyEntry.

         * @return a string representation of this SecretKeyEntry.

         */

        public String toString() {

            return "Secret key entry with algorithm " + sKey.getAlgorithm();

        }

    }

    /**

     * A <code>KeyStore</code> entry that holds a trusted

     * <code>Certificate</code>.