CryptoCipher.java

  1.  /*
  2.  * Licensed to the Apache Software Foundation (ASF) under one
  3.  * or more contributor license agreements.  See the NOTICE file
  4.  * distributed with this work for additional information
  5.  * regarding copyright ownership.  The ASF licenses this file
  6.  * to you under the Apache License, Version 2.0 (the
  7.  * "License"); you may not use this file except in compliance
  8.  * with the License.  You may obtain a copy of the License at
  9.  *
  10.  *     http://www.apache.org/licenses/LICENSE-2.0
  11.  *
  12.  * Unless required by applicable law or agreed to in writing, software
  13.  * distributed under the License is distributed on an "AS IS" BASIS,
  14.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15.  * See the License for the specific language governing permissions and
  16.  * limitations under the License.
  17.  */
  18. package org.apache.commons.crypto.cipher;

  20. import java.io.Closeable;
  21. import java.nio.ByteBuffer;
  22. import java.security.InvalidAlgorithmParameterException;
  23. import java.security.InvalidKeyException;
  24. import java.security.Key;
  25. import java.security.spec.AlgorithmParameterSpec;

  27. import javax.crypto.BadPaddingException;
  28. import javax.crypto.IllegalBlockSizeException;
  29. import javax.crypto.ShortBufferException;

  31. /**
  32.  * The interface of cryptographic cipher for encryption and decryption.
  33.  *
  34.  * <p>
  35.  * Note that implementations must provide a constructor that has 2 parameters: a Properties instance and a String (transformation)
  36.  * </p>
  37.  */
  38. public interface CryptoCipher extends Closeable {

  40.     /**
  41.      * Encrypts or decrypts data in a single-part operation, or finishes a
  42.      * multiple-part operation.
  43.      *
  44.      * @param input the input byte array
  45.      * @param inputOffset the offset in input where the input starts
  46.      * @param inputLen the input length
  47.      * @param output the byte array for the result
  48.      * @param outputOffset the offset in output where the result is stored
  49.      * @return the number of bytes stored in output
  50.      * @throws ShortBufferException if the given output byte array is too small
  51.      *         to hold the result
  52.      * @throws BadPaddingException if this cipher is in decryption mode, and
  53.      *         (un)padding has been requested, but the decrypted data is not
  54.      *         bounded by the appropriate padding bytes
  55.      * @throws IllegalBlockSizeException if this cipher is a block cipher, no
  56.      *         padding has been requested (only in encryption mode), and the
  57.      *         total input length of the data processed by this cipher is not a
  58.      *         multiple of block size; or if this encryption algorithm is unable
  59.      *         to process the input data provided.
  60.      */
  61.     int doFinal(byte[] input, int inputOffset, int inputLen, byte[] output,
  62.             int outputOffset) throws ShortBufferException,
  63.             IllegalBlockSizeException, BadPaddingException;

  65.     /**
  66.      * Encrypts or decrypts data in a single-part operation, or finishes a
  67.      * multiple-part operation.
  68.      *
  69.      * @param inBuffer the input ByteBuffer
  70.      * @param outBuffer the output ByteBuffer
  71.      * @return int number of bytes stored in {@code output}
  72.      * @throws BadPaddingException if this cipher is in decryption mode, and
  73.      *         (un)padding has been requested, but the decrypted data is not
  74.      *         bounded by the appropriate padding bytes
  75.      * @throws IllegalBlockSizeException if this cipher is a block cipher, no
  76.      *         padding has been requested (only in encryption mode), and the
  77.      *         total input length of the data processed by this cipher is not a
  78.      *         multiple of block size; or if this encryption algorithm is unable
  79.      *         to process the input data provided.
  80.      * @throws ShortBufferException if the given output buffer is too small to
  81.      *         hold the result
  82.      */
  83.     int doFinal(ByteBuffer inBuffer, ByteBuffer outBuffer)
  84.             throws ShortBufferException, IllegalBlockSizeException,
  85.             BadPaddingException;

  87.     /**
  88.      * Returns the algorithm name of this {@code CryptoCipher} object.
  89.      *
  90.      * <p>
  91.      * This is the same name that was specified in one of the
  92.      * {@code CryptoCipherFactory#getInstance} calls that created this
  93.      * {@code CryptoCipher} object..
  94.      * </p>
  95.      *
  96.      * @return the algorithm name of this {@code CryptoCipher} object.
  97.      */
  98.     String getAlgorithm();

  100.     /**
  101.      * Returns the block size (in bytes).
  102.      *
  103.      * @return the block size (in bytes), or 0 if the underlying algorithm is
  104.      * not a block cipher
  105.      */
  106.     int getBlockSize();

  108.     /**
  109.      * Initializes the cipher with mode, key and iv.
  110.      *
  111.      * @param mode {@link javax.crypto.Cipher#ENCRYPT_MODE} or
  112.      *             {@link javax.crypto.Cipher#DECRYPT_MODE}
  113.      * @param key crypto key for the cipher
  114.      * @param params the algorithm parameters
  115.      * @throws InvalidKeyException if the given key is inappropriate for
  116.      *         initializing this cipher, or its keysize exceeds the maximum
  117.      *         allowable keysize (as determined from the configured jurisdiction
  118.      *         policy files).
  119.      * @throws InvalidAlgorithmParameterException if the given algorithm
  120.      *         parameters are inappropriate for this cipher, or this cipher
  121.      *         requires algorithm parameters and {@code params} is null, or
  122.      *         the given algorithm parameters imply a cryptographic strength
  123.      *         that would exceed the legal limits (as determined from the
  124.      *         configured jurisdiction policy files).
  125.      */
  126.     void init(int mode, Key key, AlgorithmParameterSpec params)
  127.             throws InvalidKeyException, InvalidAlgorithmParameterException;

  129.     /**
  130.      * Continues a multiple-part encryption/decryption operation. The data is
  131.      * encrypted or decrypted, depending on how this cipher was initialized.
  132.      *
  133.      * @param input the input byte array
  134.      * @param inputOffset the offset in input where the input starts
  135.      * @param inputLen the input length
  136.      * @param output the byte array for the result
  137.      * @param outputOffset the offset in output where the result is stored
  138.      * @return the number of bytes stored in output
  139.      * @throws ShortBufferException if there is insufficient space in the output
  140.      *         byte array
  141.      */
  142.     int update(byte[] input, int inputOffset, int inputLen, byte[] output,
  143.             int outputOffset) throws ShortBufferException;

  145.     /**
  146.      * Continues a multiple-part encryption/decryption operation. The data is
  147.      * encrypted or decrypted, depending on how this cipher was initialized.
  148.      *
  149.      * @param inBuffer the input ByteBuffer
  150.      * @param outBuffer the output ByteBuffer
  151.      * @return int number of bytes stored in {@code output}
  152.      * @throws ShortBufferException if there is insufficient space in the output
  153.      *         buffer
  154.      */
  155.     int update(ByteBuffer inBuffer, ByteBuffer outBuffer)
  156.             throws ShortBufferException;

  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.      * </p>
  168.      *
  169.      * @param aad the buffer containing the Additional Authentication Data
  170.      *
  171.      * @throws IllegalArgumentException if the {@code aad}
  172.      * byte array is null
  173.      * @throws IllegalStateException if this cipher is in a wrong state
  174.      * (e.g., has not been initialized), does not accept AAD, or if
  175.      * operating in either GCM or CCM mode and one of the {@code update}
  176.      * methods has already been called for the active
  177.      * encryption/decryption operation
  178.      * @throws UnsupportedOperationException if the corresponding method
  179.      * has not been overridden by an implementation
  180.      *
  181.      */
  182.     default void updateAAD(final byte[] aad)
  183.             throws IllegalArgumentException, IllegalStateException, UnsupportedOperationException {
  184.       throw new UnsupportedOperationException();
  185.     }

  187.     /**
  188.      * Continues a multi-part update of the Additional Authentication
  189.      * Data (AAD).
  190.      * <p>
  191.      * Calls to this method provide AAD to the cipher when operating in
  192.      * modes such as AEAD (GCM).  If this cipher is operating in
  193.      * GCM mode, all AAD must be supplied before beginning
  194.      * operations on the ciphertext (via the {@code update} and
  195.      * {@code doFinal} methods).
  196.      * </p>
  197.      *
  198.      * @param aad the buffer containing the Additional Authentication Data
  199.      *
  200.      * @throws IllegalArgumentException if the {@code aad}
  201.      * byte array is null
  202.      * @throws IllegalStateException if this cipher is in a wrong state
  203.      * (e.g., has not been initialized), does not accept AAD, or if
  204.      * operating in either GCM or CCM mode and one of the {@code update}
  205.      * methods has already been called for the active
  206.      * encryption/decryption operation
  207.      * @throws UnsupportedOperationException if the corresponding method
  208.      * has not been overridden by an implementation
  209.      *
  210.      */
  211.     default void updateAAD(final ByteBuffer aad)
  212.             throws IllegalArgumentException, IllegalStateException, UnsupportedOperationException {
  213.       throw new UnsupportedOperationException();
  214.     }
  215. }
Created with JaCoCo 0.8.8.202204050719