/*

 * Copyright (c) 1997, 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 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.*;

/**

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

 *

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

 *        ks.load(fis, password);

 *    }

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

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

    }

    /**

     * Configuration data that specifies the keystores in a keystore domain.

     * A keystore domain is a collection of keystores that are presented as a

     * single logical keystore. The configuration data is used during

     * {@code KeyStore}

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

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

     * <p>

     * The following syntax is supported for configuration data:

     * <pre>

     *

     *     domain <domainName> [<property> ...] {

     *         keystore <keystoreName> [<property> ...] ;

     *         ...

     *     };

     *     ...

     *

     * </pre>

     * where {@code domainName} and {@code keystoreName} are identifiers

     * and {@code property} is a key/value pairing. The key and value are

     * separated by an 'equals' symbol and the value is enclosed in double

     * quotes. A property value may be either a printable string or a binary

     * string of colon-separated pairs of hexadecimal digits. Multi-valued

     * properties are represented as a comma-separated list of values,

     * enclosed in square brackets.

     * See {@link Arrays#toString(java.lang.Object[])}.

     * <p>

     * To ensure that keystore entries are uniquely identified, each

     * entry's alias is prefixed by its {@code keystoreName} followed

     * by the entry name separator and each {@code keystoreName} must be

     * unique within its domain. Entry name prefixes are omitted when

     * storing a keystore.

     * <p>

     * Properties are context-sensitive: properties that apply to

     * all the keystores in a domain are located in the domain clause,

     * and properties that apply only to a specific keystore are located

     * in that keystore's clause.

     * Unless otherwise specified, a property in a keystore clause overrides

     * a property of the same name in the domain clause. All property names

     * are case-insensitive. The following properties are supported:

     * <dl>

     * <dt> {@code keystoreType="<type>"} </dt>

     *     <dd> The keystore type. </dd>

     * <dt> {@code keystoreURI="<url>"} </dt>

     *     <dd> The keystore location. </dd>

     * <dt> {@code keystoreProviderName="<name>"} </dt>

     *     <dd> The name of the keystore's JCE provider. </dd>

     * <dt> {@code keystorePasswordEnv="<environment-variable>"} </dt>

     *     <dd> The environment variable that stores a keystore password.

     *          Alternatively, passwords may be supplied to the constructor

     *          method in a {@code Map<String, ProtectionParameter>}. </dd>

     * <dt> {@code entryNameSeparator="<separator>"} </dt>

     *     <dd> The separator between a keystore name prefix and an entry name.

     *          When specified, it applies to all the entries in a domain.

     *          Its default value is a space. </dd>

     * </dl>

     * <p>

     * For example, configuration data for a simple keystore domain

     * comprising three keystores is shown below:

     * <pre>

     *

     * domain app1 {

     *     keystore app1-truststore

     *         keystoreURI="file:///app1/etc/truststore.jks"

     *

     *     keystore system-truststore

     *         keystoreURI="${java.home}/lib/security/cacerts"

     *

     *     keystore app1-keystore

     *         keystoreType="PKCS12"

     *         keystoreURI="file:///app1/etc/keystore.p12"

     * };

     *

     * </pre>

     * @since 1.8

     */

    public static final class DomainLoadStoreParameter

        implements LoadStoreParameter {

        private final URI configuration;

        private final Map<String,ProtectionParameter> protectionParams;

        /**

         * Constructs a DomainLoadStoreParameter for a keystore domain with

         * the parameters used to protect keystore data.

         *

         * @param configuration identifier for the domain configuration data.

         *     The name of the target domain should be specified in the

         *     {@code java.net.URI} fragment component when it is necessary

         *     to distinguish between several domain configurations at the

         *     same location.

         *

         * @param protectionParams the map from keystore name to the parameter

         *     used to protect keystore data.

         *     A {@code java.util.Collections.EMPTY_MAP} should be used

         *     when protection parameters are not required or when they have

         *     been specified by properties in the domain configuration data.

         *     It is cloned to prevent subsequent modification.

         *

         *     {@code protectionParams} is {@code null}

         */

        public DomainLoadStoreParameter(URI configuration,

            Map<String,ProtectionParameter> protectionParams) {

            if (configuration == null || protectionParams == null) {

                throw new NullPointerException("invalid null input");

            }

            this.configuration = configuration;

            this.protectionParams =

                Collections.unmodifiableMap(new HashMap<>(protectionParams));

        }

        /**

         * Gets the identifier for the domain configuration data.

         *

         * @return the identifier for the configuration data

         */

        public URI getConfiguration() {

            return configuration;

        }

        /**

         * Gets the keystore protection parameters for keystores in this

         * domain.

         *

         * @return an unmodifiable map of keystore names to protection

         *     parameters

         */

        public Map<String,ProtectionParameter> getProtectionParams() {

            return protectionParams;

        }

        /**

         * Gets the keystore protection parameters for this domain.

         * Keystore domains do not support a protection parameter.

         *

         * @return always returns {@code null}

         */

        @Override

        public KeyStore.ProtectionParameter getProtectionParameter() {

            return null;

        }

    }

    /**

     * 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 final String protectionAlgorithm;

        private final AlgorithmParameterSpec protectionParameters;

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

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

        }