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}