001    /*
002     * Cumulus4j - Securing your data in the cloud - http://cumulus4j.org
003     * Copyright (C) 2011 NightLabs Consulting GmbH
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    package org.cumulus4j.crypto;
019    
020    /**
021     * <p>
022     * Factory creating instances of {@link MACCalculator}.
023     * </p><p>
024     * Implementations of this interface are used by {@link CryptoRegistry#createMACCalculator(String, boolean)}
025     * to provide instances of <code>MACCalculator</code>.
026     * </p><p>
027     * Note: Implementors should subclass {@link AbstractMACCalculatorFactory} instead of directly implementing this
028     * interface.
029     * </p>
030     *
031     * @author Marco หงุ่ยตระกูล-Schulze - marco at nightlabs dot de
032     */
033    public interface MACCalculatorFactory
034    {
035            /**
036             * <p>
037             * Create a new instance of {@link MACCalculator} and optionally
038             * {@link MACCalculator#init(org.bouncycastle.crypto.CipherParameters) initialise} it.
039             * </p>
040             *
041             * @param initWithDefaults whether to
042             * {@link MACCalculator#init(org.bouncycastle.crypto.CipherParameters) initialise} the <code>MACCalculator</code> with default values
043             * so that it can be used immediately as-is.
044             * @return a new instance of {@link MACCalculator} (iff <code>initWithDefaults==true</code> ready-to-use;
045             * otherwise requiring {@link MACCalculator#init(org.bouncycastle.crypto.CipherParameters) initialisation}
046             * before it can be used).
047             */
048            MACCalculator createMACCalculator(boolean initWithDefaults);
049    
050            /**
051             * Get the name of the MAC algorithm implemented by the {@link MACCalculator} created by this factory.
052             * See <a target="_blank" href="http://cumulus4j.org/1.2.0-SNAPSHOT/documentation/supported-algorithms.html">Supported algorithms</a>
053             * for a list of supported algorithms.
054             * @return the name of the MAC algorithm.
055             */
056            String getAlgorithmName();
057    
058            /**
059             * Set the name of the MAC algorithm. This method is called once and should throw an {@link IllegalStateException}
060             * if it is called again.
061             * @param algorithmName the name of the MAC algorithm; never <code>null</code>.
062             * @see #getAlgorithmName()
063             */
064            void setAlgorithmName(String algorithmName);
065    }