001/**
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements.  See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership.  The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License.  You may obtain a copy of the License at
009 *
010 *     http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS,
014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015 * See the License for the specific language governing permissions and
016 * limitations under the License.
017 */
018package org.apache.commons.crypto.cipher;
019
020import java.io.Closeable;
021import java.nio.ByteBuffer;
022import java.security.InvalidAlgorithmParameterException;
023import java.security.InvalidKeyException;
024import java.security.Key;
025import java.security.spec.AlgorithmParameterSpec;
026
027import javax.crypto.BadPaddingException;
028import javax.crypto.IllegalBlockSizeException;
029import javax.crypto.ShortBufferException;
030
031/**
032 * The interface of cryptographic cipher for encryption and decryption.
033 *
034 * <p>
035 * Note that implementations must provide a constructor that has 2 parameters:
036 * <br>
037 * a Properties instance and a String (transformation)
038 *
039 */
040public interface CryptoCipher extends Closeable {
041
042    /**
043     * Returns the block size (in bytes).
044     *
045     * @return the block size (in bytes), or 0 if the underlying algorithm is
046     * not a block cipher
047     */
048    int getBlockSize();
049
050    /**
051     * Returns the algorithm name of this {@code CryptoCipher} object.
052     *
053     * <p>This is the same name that was specified in one of the
054     * {@code CryptoCipherFactory#getInstance} calls that created this
055     * {@code CryptoCipher} object..
056     *
057     * @return the algorithm name of this {@code CryptoCipher} object.
058     */
059    String getAlgorithm();
060
061    /**
062     * Initializes the cipher with mode, key and iv.
063     *
064     * @param mode {@link javax.crypto.Cipher#ENCRYPT_MODE} or
065     *             {@link javax.crypto.Cipher#DECRYPT_MODE}
066     * @param key crypto key for the cipher
067     * @param params the algorithm parameters
068     * @throws InvalidKeyException if the given key is inappropriate for
069     *         initializing this cipher, or its keysize exceeds the maximum
070     *         allowable keysize (as determined from the configured jurisdiction
071     *         policy files).
072     * @throws InvalidAlgorithmParameterException if the given algorithm
073     *         parameters are inappropriate for this cipher, or this cipher
074     *         requires algorithm parameters and {@code params} is null, or
075     *         the given algorithm parameters imply a cryptographic strength
076     *         that would exceed the legal limits (as determined from the
077     *         configured jurisdiction policy files).
078     */
079    void init(int mode, Key key, AlgorithmParameterSpec params)
080            throws InvalidKeyException, InvalidAlgorithmParameterException;
081
082    /**
083     * Continues a multiple-part encryption/decryption operation. The data is
084     * encrypted or decrypted, depending on how this cipher was initialized.
085     *
086     * @param inBuffer the input ByteBuffer
087     * @param outBuffer the output ByteBuffer
088     * @return int number of bytes stored in {@code output}
089     * @throws ShortBufferException if there is insufficient space in the output
090     *         buffer
091     */
092    int update(ByteBuffer inBuffer, ByteBuffer outBuffer)
093            throws ShortBufferException;
094
095    /**
096     * Continues a multiple-part encryption/decryption operation. The data is
097     * encrypted or decrypted, depending on how this cipher was initialized.
098     *
099     * @param input the input byte array
100     * @param inputOffset the offset in input where the input starts
101     * @param inputLen the input length
102     * @param output the byte array for the result
103     * @param outputOffset the offset in output where the result is stored
104     * @return the number of bytes stored in output
105     * @throws ShortBufferException if there is insufficient space in the output
106     *         byte array
107     */
108    int update(byte[] input, int inputOffset, int inputLen, byte[] output,
109            int outputOffset) throws ShortBufferException;
110
111    /**
112     * Encrypts or decrypts data in a single-part operation, or finishes a
113     * multiple-part operation.
114     *
115     * @param inBuffer the input ByteBuffer
116     * @param outBuffer the output ByteBuffer
117     * @return int number of bytes stored in {@code output}
118     * @throws BadPaddingException if this cipher is in decryption mode, and
119     *         (un)padding has been requested, but the decrypted data is not
120     *         bounded by the appropriate padding bytes
121     * @throws IllegalBlockSizeException if this cipher is a block cipher, no
122     *         padding has been requested (only in encryption mode), and the
123     *         total input length of the data processed by this cipher is not a
124     *         multiple of block size; or if this encryption algorithm is unable
125     *         to process the input data provided.
126     * @throws ShortBufferException if the given output buffer is too small to
127     *         hold the result
128     */
129    int doFinal(ByteBuffer inBuffer, ByteBuffer outBuffer)
130            throws ShortBufferException, IllegalBlockSizeException,
131            BadPaddingException;
132
133    /**
134     * Encrypts or decrypts data in a single-part operation, or finishes a
135     * multiple-part operation.
136     *
137     * @param input the input byte array
138     * @param inputOffset the offset in input where the input starts
139     * @param inputLen the input length
140     * @param output the byte array for the result
141     * @param outputOffset the offset in output where the result is stored
142     * @return the number of bytes stored in output
143     * @throws ShortBufferException if the given output byte array is too small
144     *         to hold the result
145     * @throws BadPaddingException if this cipher is in decryption mode, and
146     *         (un)padding has been requested, but the decrypted data is not
147     *         bounded by the appropriate padding bytes
148     * @throws IllegalBlockSizeException if this cipher is a block cipher, no
149     *         padding has been requested (only in encryption mode), and the
150     *         total input length of the data processed by this cipher is not a
151     *         multiple of block size; or if this encryption algorithm is unable
152     *         to process the input data provided.
153     */
154    int doFinal(byte[] input, int inputOffset, int inputLen, byte[] output,
155            int outputOffset) throws ShortBufferException,
156            IllegalBlockSizeException, BadPaddingException;
157
158    /**
159     * Continues a multi-part update of the Additional Authentication
160     * Data (AAD).
161     * <p>
162     * Calls to this method provide AAD to the cipher when operating in
163     * modes such as AEAD (GCM).  If this cipher is operating in
164     * GCM mode, all AAD must be supplied before beginning
165     * operations on the ciphertext (via the {@code update} and
166     * {@code doFinal} methods).
167     *
168     * @param aad the buffer containing the Additional Authentication Data
169     *
170     * @throws IllegalArgumentException if the {@code aad}
171     * byte array is null
172     * @throws IllegalStateException if this cipher is in a wrong state
173     * (e.g., has not been initialized), does not accept AAD, or if
174     * operating in either GCM or CCM mode and one of the {@code update}
175     * methods has already been called for the active
176     * encryption/decryption operation
177     * @throws UnsupportedOperationException if the corresponding method
178     * has not been overridden by an implementation
179     *
180     */
181    default void updateAAD(final byte[] aad)
182            throws IllegalArgumentException, IllegalStateException, UnsupportedOperationException {
183      throw new UnsupportedOperationException();
184    }
185
186    /**
187     * Continues a multi-part update of the Additional Authentication
188     * Data (AAD).
189     * <p>
190     * Calls to this method provide AAD to the cipher when operating in
191     * modes such as AEAD (GCM).  If this cipher is operating in
192     * GCM mode, all AAD must be supplied before beginning
193     * operations on the ciphertext (via the {@code update} and
194     * {@code doFinal} methods).
195     *
196     * @param aad the buffer containing the Additional Authentication Data
197     *
198     * @throws IllegalArgumentException if the {@code aad}
199     * byte array is null
200     * @throws IllegalStateException if this cipher is in a wrong state
201     * (e.g., has not been initialized), does not accept AAD, or if
202     * operating in either GCM or CCM mode and one of the {@code update}
203     * methods has already been called for the active
204     * encryption/decryption operation
205     * @throws UnsupportedOperationException if the corresponding method
206     * has not been overridden by an implementation
207     *
208     */
209    default void updateAAD(final ByteBuffer aad)
210            throws IllegalArgumentException, IllegalStateException, UnsupportedOperationException {
211      throw new UnsupportedOperationException();
212    }
213}