001/*
002 * jPOS Project [http://jpos.org]
003 * Copyright (C) 2000-2026 jPOS Software SRL
004 *
005 * This program is free software: you can redistribute it and/or modify
006 * it under the terms of the GNU Affero General Public License as
007 * published by the Free Software Foundation, either version 3 of the
008 * License, or (at your option) any later version.
009 *
010 * This program is distributed in the hope that it will be useful,
011 * but WITHOUT ANY WARRANTY; without even the implied warranty of
012 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
013 * GNU Affero General Public License for more details.
014 *
015 * You should have received a copy of the GNU Affero General Public License
016 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
017 */
018
019package  org.jpos.security;
020
021import org.jpos.iso.ISOException;
022
023import java.util.Map;
024
025
026/**
027 * <p>
028 * Represents a collection of Secure Keys and typically stores them in some
029 * persistent storage. SecureKeyStore isolates from particular DB implementations.
030 * A Secure Key Store need not implement any security itself, it just holds keys
031 * that are inherently secure (like SecureDESKey).
032 * </p>
033 * <p>
034 * Note: SecureKeyStore doesn't have any relation with java.security.KeyStore
035 * SecureKeyStore works on objects of type org.jpos.security.SecureKey
036 * </p>
037 * @author Hani S. Kirollos
038 * @version $Revision$ $Date$
039 * @see SecureKey
040 */
041public interface SecureKeyStore {
042
043    /** Exception type raised by {@link SecureKeyStore} implementations. */
044    class SecureKeyStoreException extends ISOException {
045
046        private static final long serialVersionUID = 1976885367352075834L;
047
048        /** Constructs a new exception with no detail message. */
049        public SecureKeyStoreException () {
050            super();
051        }
052
053        /**
054         * Constructs a new exception with the given detail message.
055         *
056         * @param detail failure description
057         */
058        public SecureKeyStoreException (String detail) {
059            super(detail);
060        }
061
062        /**
063         * Constructs a new exception wrapping {@code nested}.
064         *
065         * @param nested underlying cause
066         */
067        public SecureKeyStoreException (Exception nested) {
068            super(nested);
069        }
070
071        /**
072         * Constructs a new exception with the given detail message and cause.
073         *
074         * @param detail failure description
075         * @param nested underlying cause
076         */
077        public SecureKeyStoreException (String detail, Exception nested) {
078            super(detail, nested);
079        }
080    }
081
082
083    /**
084     * Returns the key assiciated with the given alias.
085     *
086     * @param <T> desired type of requested key
087     * @param alias the alias name
088     * @return the requested key, or {@code null} if the given alias does not exist.
089     * @throws SecureKeyStoreException if SecureKeyStore is not initialized or if
090     * the operation fails for some other reason.
091     */
092    <T extends SecureKey> T getKey(String alias) throws SecureKeyStoreException;
093
094    /**
095     * Assigns the given key to the given alias.
096     * If the given alias already exists, the keystore information associated
097     * with it is overridden by the given key.
098     * @param alias the alias name
099     * @param key the key to be associated with the alias
100     * @throws SecureKeyStoreException if SecureKeyStore is not initialized or the key
101     * can't be recovered.
102     */
103    void setKey(String alias, SecureKey key) throws SecureKeyStoreException;
104
105    /**
106     * Returns map of existing keys assiciated with aliases.
107     *
108     * @param <T> desired type of requested keys
109     * @return map of existing keys assiciated with aliases.
110     * @throws SecureKeyStoreException if SecureKeyStore is not initialized or if
111     * the operation fails for some other reason.
112     */
113    <T extends SecureKey> Map<String, T> getKeys() throws SecureKeyStoreException;
114
115}
116
117
118