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    import org.bouncycastle.crypto.CipherParameters;
021    import org.bouncycastle.crypto.Mac;
022    
023    /**
024     * <p>
025     * A <code>MACCalculator</code> calculates <a target="_blank" href="http://en.wikipedia.org/wiki/Message_authentication_code">message
026     * authentication codes</a>.
027     * </p><p>
028     * Use {@link CryptoRegistry#createMACCalculator(String, boolean)} to obtain a <code>MACCalculator</code> instance.
029     * </p><p>
030     * <b>Important: <code>MACCalculator</code>s are not thread-safe!</b>
031     * </p>
032     *
033     * @author Marco หงุ่ยตระกูล-Schulze - marco at nightlabs dot de
034     */
035    public interface MACCalculator
036    extends Mac
037    {
038            void setAlgorithmName(String algorithmName);
039    
040            CipherParameters getParameters();
041    
042            /**
043             * Get the required size of the key (in bytes).
044             * @return the required size of the key (in bytes).
045             */
046            int getKeySize();
047    
048            /**
049             * Get the required size of the IV (in bytes). If a MAC supports multiple sizes, this is the optimal (most secure) IV size.
050             * If a MAC supports no IV, this is 0.
051             * @return the required size of the IV.
052             */
053            int getIVSize();
054    
055            /**
056             * Convenience method to process the complete input byte array at once.
057             * @param in the input to calculate a MAC for.
058             * @return the MAC.
059             * @throws IllegalStateException if the <code>MACCalculator</code> isn't initialised.
060             */
061            byte[] doFinal(byte[] in)
062            throws IllegalStateException;
063    }