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    class SecureKeyStoreException extends ISOException {
044
045        private static final long serialVersionUID = 1976885367352075834L;
046
047        public SecureKeyStoreException () {
048            super();
049        }
050
051        public SecureKeyStoreException (String detail) {
052            super(detail);
053        }
054
055        public SecureKeyStoreException (Exception nested) {
056            super(nested);
057        }
058
059        public SecureKeyStoreException (String detail, Exception nested) {
060            super(detail, nested);
061        }
062    }
063
064
065    /**
066     * Returns the key assiciated with the given alias.
067     *
068     * @param <T> desired type of requested key
069     * @param alias the alias name
070     * @return the requested key, or {@code null} if the given alias does not exist.
071     * @throws SecureKeyStoreException if SecureKeyStore is not initialized or if
072     * the operation fails for some other reason.
073     */
074    <T extends SecureKey> T getKey(String alias) throws SecureKeyStoreException;
075
076    /**
077     * Assigns the given key to the given alias.
078     * If the given alias already exists, the keystore information associated
079     * with it is overridden by the given key.
080     * @param alias the alias name
081     * @param key the key to be associated with the alias
082     * @throws SecureKeyStoreException if SecureKeyStore is not initialized or the key
083     * can't be recovered.
084     */
085    void setKey(String alias, SecureKey key) throws SecureKeyStoreException;
086
087    /**
088     * Returns map of existing keys assiciated with aliases.
089     *
090     * @param <T> desired type of requested keys
091     * @return map of existing keys assiciated with aliases.
092     * @throws SecureKeyStoreException if SecureKeyStore is not initialized or if
093     * the operation fails for some other reason.
094     */
095    <T extends SecureKey> Map<String, T> getKeys() throws SecureKeyStoreException;
096
097}
098
099
100