View Javadoc
1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *      http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  
18  package org.apache.commons.codec.binary;
19  
20  import java.util.Arrays;
21  
22  import org.apache.commons.codec.BinaryDecoder;
23  import org.apache.commons.codec.BinaryEncoder;
24  import org.apache.commons.codec.DecoderException;
25  import org.apache.commons.codec.EncoderException;
26  
27  /**
28   * Abstract superclass for Base-N encoders and decoders.
29   *
30   * <p>
31   * This class is thread-safe.
32   * </p>
33   *
34   * @version $Id: BaseNCodec.java 1634404 2014-10-26 23:06:10Z ggregory $
35   */
36  public abstract class BaseNCodec implements BinaryEncoder, BinaryDecoder {
37  
38      /**
39       * Holds thread context so classes can be thread-safe.
40       *
41       * This class is not itself thread-safe; each thread must allocate its own copy.
42       *
43       * @since 1.7
44       */
45      static class Context {
46  
47          /**
48           * Place holder for the bytes we're dealing with for our based logic.
49           * Bitwise operations store and extract the encoding or decoding from this variable.
50           */
51          int ibitWorkArea;
52  
53          /**
54           * Place holder for the bytes we're dealing with for our based logic.
55           * Bitwise operations store and extract the encoding or decoding from this variable.
56           */
57          long lbitWorkArea;
58  
59          /**
60           * Buffer for streaming.
61           */
62          byte[] buffer;
63  
64          /**
65           * Position where next character should be written in the buffer.
66           */
67          int pos;
68  
69          /**
70           * Position where next character should be read from the buffer.
71           */
72          int readPos;
73  
74          /**
75           * Boolean flag to indicate the EOF has been reached. Once EOF has been reached, this object becomes useless,
76           * and must be thrown away.
77           */
78          boolean eof;
79  
80          /**
81           * Variable tracks how many characters have been written to the current line. Only used when encoding. We use
82           * it to make sure each encoded line never goes beyond lineLength (if lineLength &gt; 0).
83           */
84          int currentLinePos;
85  
86          /**
87           * Writes to the buffer only occur after every 3/5 reads when encoding, and every 4/8 reads when decoding. This
88           * variable helps track that.
89           */
90          int modulus;
91  
92          Context() {
93          }
94  
95          /**
96           * Returns a String useful for debugging (especially within a debugger.)
97           *
98           * @return a String useful for debugging.
99           */
100         @SuppressWarnings("boxing") // OK to ignore boxing here
101         @Override
102         public String toString() {
103             return String.format("%s[buffer=%s, currentLinePos=%s, eof=%s, ibitWorkArea=%s, lbitWorkArea=%s, " +
104                     "modulus=%s, pos=%s, readPos=%s]", this.getClass().getSimpleName(), Arrays.toString(buffer),
105                     currentLinePos, eof, ibitWorkArea, lbitWorkArea, modulus, pos, readPos);
106         }
107     }
108 
109     /**
110      * EOF
111      *
112      * @since 1.7
113      */
114     static final int EOF = -1;
115 
116     /**
117      *  MIME chunk size per RFC 2045 section 6.8.
118      *
119      * <p>
120      * The {@value} character limit does not count the trailing CRLF, but counts all other characters, including any
121      * equal signs.
122      * </p>
123      *
124      * @see <a href="http://www.ietf.org/rfc/rfc2045.txt">RFC 2045 section 6.8</a>
125      */
126     public static final int MIME_CHUNK_SIZE = 76;
127 
128     /**
129      * PEM chunk size per RFC 1421 section 4.3.2.4.
130      *
131      * <p>
132      * The {@value} character limit does not count the trailing CRLF, but counts all other characters, including any
133      * equal signs.
134      * </p>
135      *
136      * @see <a href="http://tools.ietf.org/html/rfc1421">RFC 1421 section 4.3.2.4</a>
137      */
138     public static final int PEM_CHUNK_SIZE = 64;
139 
140     private static final int DEFAULT_BUFFER_RESIZE_FACTOR = 2;
141 
142     /**
143      * Defines the default buffer size - currently {@value}
144      * - must be large enough for at least one encoded block+separator
145      */
146     private static final int DEFAULT_BUFFER_SIZE = 8192;
147 
148     /** Mask used to extract 8 bits, used in decoding bytes */
149     protected static final int MASK_8BITS = 0xff;
150 
151     /**
152      * Byte used to pad output.
153      */
154     protected static final byte PAD_DEFAULT = '='; // Allow static access to default
155 
156     /**
157      * @deprecated Use {@link #pad}. Will be removed in 2.0.
158      */
159     @Deprecated
160     protected final byte PAD = PAD_DEFAULT; // instance variable just in case it needs to vary later
161 
162     protected final byte pad; // instance variable just in case it needs to vary later
163 
164     /** Number of bytes in each full block of unencoded data, e.g. 4 for Base64 and 5 for Base32 */
165     private final int unencodedBlockSize;
166 
167     /** Number of bytes in each full block of encoded data, e.g. 3 for Base64 and 8 for Base32 */
168     private final int encodedBlockSize;
169 
170     /**
171      * Chunksize for encoding. Not used when decoding.
172      * A value of zero or less implies no chunking of the encoded data.
173      * Rounded down to nearest multiple of encodedBlockSize.
174      */
175     protected final int lineLength;
176 
177     /**
178      * Size of chunk separator. Not used unless {@link #lineLength} &gt; 0.
179      */
180     private final int chunkSeparatorLength;
181 
182     /**
183      * Note <code>lineLength</code> is rounded down to the nearest multiple of {@link #encodedBlockSize}
184      * If <code>chunkSeparatorLength</code> is zero, then chunking is disabled.
185      * @param unencodedBlockSize the size of an unencoded block (e.g. Base64 = 3)
186      * @param encodedBlockSize the size of an encoded block (e.g. Base64 = 4)
187      * @param lineLength if &gt; 0, use chunking with a length <code>lineLength</code>
188      * @param chunkSeparatorLength the chunk separator length, if relevant
189      */
190     protected BaseNCodec(final int unencodedBlockSize, final int encodedBlockSize,
191                          final int lineLength, final int chunkSeparatorLength) {
192         this(unencodedBlockSize, encodedBlockSize, lineLength, chunkSeparatorLength, PAD_DEFAULT);
193     }
194 
195     /**
196      * Note <code>lineLength</code> is rounded down to the nearest multiple of {@link #encodedBlockSize}
197      * If <code>chunkSeparatorLength</code> is zero, then chunking is disabled.
198      * @param unencodedBlockSize the size of an unencoded block (e.g. Base64 = 3)
199      * @param encodedBlockSize the size of an encoded block (e.g. Base64 = 4)
200      * @param lineLength if &gt; 0, use chunking with a length <code>lineLength</code>
201      * @param chunkSeparatorLength the chunk separator length, if relevant
202      * @param pad byte used as padding byte.
203      */
204     protected BaseNCodec(final int unencodedBlockSize, final int encodedBlockSize,
205                          final int lineLength, final int chunkSeparatorLength, final byte pad) {
206         this.unencodedBlockSize = unencodedBlockSize;
207         this.encodedBlockSize = encodedBlockSize;
208         final boolean useChunking = lineLength > 0 && chunkSeparatorLength > 0;
209         this.lineLength = useChunking ? (lineLength / encodedBlockSize) * encodedBlockSize : 0;
210         this.chunkSeparatorLength = chunkSeparatorLength;
211 
212         this.pad = pad;
213     }
214 
215     /**
216      * Returns true if this object has buffered data for reading.
217      *
218      * @param context the context to be used
219      * @return true if there is data still available for reading.
220      */
221     boolean hasData(final Context context) {  // package protected for access from I/O streams
222         return context.buffer != null;
223     }
224 
225     /**
226      * Returns the amount of buffered data available for reading.
227      *
228      * @param context the context to be used
229      * @return The amount of buffered data available for reading.
230      */
231     int available(final Context context) {  // package protected for access from I/O streams
232         return context.buffer != null ? context.pos - context.readPos : 0;
233     }
234 
235     /**
236      * Get the default buffer size. Can be overridden.
237      *
238      * @return {@link #DEFAULT_BUFFER_SIZE}
239      */
240     protected int getDefaultBufferSize() {
241         return DEFAULT_BUFFER_SIZE;
242     }
243 
244     /**
245      * Increases our buffer by the {@link #DEFAULT_BUFFER_RESIZE_FACTOR}.
246      * @param context the context to be used
247      */
248     private byte[] resizeBuffer(final Context context) {
249         if (context.buffer == null) {
250             context.buffer = new byte[getDefaultBufferSize()];
251             context.pos = 0;
252             context.readPos = 0;
253         } else {
254             final byte[] b = new byte[context.buffer.length * DEFAULT_BUFFER_RESIZE_FACTOR];
255             System.arraycopy(context.buffer, 0, b, 0, context.buffer.length);
256             context.buffer = b;
257         }
258         return context.buffer;
259     }
260 
261     /**
262      * Ensure that the buffer has room for <code>size</code> bytes
263      *
264      * @param size minimum spare space required
265      * @param context the context to be used
266      * @return the buffer
267      */
268     protected byte[] ensureBufferSize(final int size, final Context context){
269         if ((context.buffer == null) || (context.buffer.length < context.pos + size)){
270             return resizeBuffer(context);
271         }
272         return context.buffer;
273     }
274 
275     /**
276      * Extracts buffered data into the provided byte[] array, starting at position bPos, up to a maximum of bAvail
277      * bytes. Returns how many bytes were actually extracted.
278      * <p>
279      * Package protected for access from I/O streams.
280      *
281      * @param b
282      *            byte[] array to extract the buffered data into.
283      * @param bPos
284      *            position in byte[] array to start extraction at.
285      * @param bAvail
286      *            amount of bytes we're allowed to extract. We may extract fewer (if fewer are available).
287      * @param context
288      *            the context to be used
289      * @return The number of bytes successfully extracted into the provided byte[] array.
290      */
291     int readResults(final byte[] b, final int bPos, final int bAvail, final Context context) {
292         if (context.buffer != null) {
293             final int len = Math.min(available(context), bAvail);
294             System.arraycopy(context.buffer, context.readPos, b, bPos, len);
295             context.readPos += len;
296             if (context.readPos >= context.pos) {
297                 context.buffer = null; // so hasData() will return false, and this method can return -1
298             }
299             return len;
300         }
301         return context.eof ? EOF : 0;
302     }
303 
304     /**
305      * Checks if a byte value is whitespace or not.
306      * Whitespace is taken to mean: space, tab, CR, LF
307      * @param byteToCheck
308      *            the byte to check
309      * @return true if byte is whitespace, false otherwise
310      */
311     protected static boolean isWhiteSpace(final byte byteToCheck) {
312         switch (byteToCheck) {
313             case ' ' :
314             case '\n' :
315             case '\r' :
316             case '\t' :
317                 return true;
318             default :
319                 return false;
320         }
321     }
322 
323     /**
324      * Encodes an Object using the Base-N algorithm. This method is provided in order to satisfy the requirements of
325      * the Encoder interface, and will throw an EncoderException if the supplied object is not of type byte[].
326      *
327      * @param obj
328      *            Object to encode
329      * @return An object (of type byte[]) containing the Base-N encoded data which corresponds to the byte[] supplied.
330      * @throws EncoderException
331      *             if the parameter supplied is not of type byte[]
332      */
333     @Override
334     public Object encode(final Object obj) throws EncoderException {
335         if (!(obj instanceof byte[])) {
336             throw new EncoderException("Parameter supplied to Base-N encode is not a byte[]");
337         }
338         return encode((byte[]) obj);
339     }
340 
341     /**
342      * Encodes a byte[] containing binary data, into a String containing characters in the Base-N alphabet.
343      * Uses UTF8 encoding.
344      *
345      * @param pArray
346      *            a byte array containing binary data
347      * @return A String containing only Base-N character data
348      */
349     public String encodeToString(final byte[] pArray) {
350         return StringUtils.newStringUtf8(encode(pArray));
351     }
352 
353     /**
354      * Encodes a byte[] containing binary data, into a String containing characters in the appropriate alphabet.
355      * Uses UTF8 encoding.
356      *
357      * @param pArray a byte array containing binary data
358      * @return String containing only character data in the appropriate alphabet.
359     */
360     public String encodeAsString(final byte[] pArray){
361         return StringUtils.newStringUtf8(encode(pArray));
362     }
363 
364     /**
365      * Decodes an Object using the Base-N algorithm. This method is provided in order to satisfy the requirements of
366      * the Decoder interface, and will throw a DecoderException if the supplied object is not of type byte[] or String.
367      *
368      * @param obj
369      *            Object to decode
370      * @return An object (of type byte[]) containing the binary data which corresponds to the byte[] or String
371      *         supplied.
372      * @throws DecoderException
373      *             if the parameter supplied is not of type byte[]
374      */
375     @Override
376     public Object decode(final Object obj) throws DecoderException {
377         if (obj instanceof byte[]) {
378             return decode((byte[]) obj);
379         } else if (obj instanceof String) {
380             return decode((String) obj);
381         } else {
382             throw new DecoderException("Parameter supplied to Base-N decode is not a byte[] or a String");
383         }
384     }
385 
386     /**
387      * Decodes a String containing characters in the Base-N alphabet.
388      *
389      * @param pArray
390      *            A String containing Base-N character data
391      * @return a byte array containing binary data
392      */
393     public byte[] decode(final String pArray) {
394         return decode(StringUtils.getBytesUtf8(pArray));
395     }
396 
397     /**
398      * Decodes a byte[] containing characters in the Base-N alphabet.
399      *
400      * @param pArray
401      *            A byte array containing Base-N character data
402      * @return a byte array containing binary data
403      */
404     @Override
405     public byte[] decode(final byte[] pArray) {
406         if (pArray == null || pArray.length == 0) {
407             return pArray;
408         }
409         final Context context = new Context();
410         decode(pArray, 0, pArray.length, context);
411         decode(pArray, 0, EOF, context); // Notify decoder of EOF.
412         final byte[] result = new byte[context.pos];
413         readResults(result, 0, result.length, context);
414         return result;
415     }
416 
417     /**
418      * Encodes a byte[] containing binary data, into a byte[] containing characters in the alphabet.
419      *
420      * @param pArray
421      *            a byte array containing binary data
422      * @return A byte array containing only the basen alphabetic character data
423      */
424     @Override
425     public byte[] encode(final byte[] pArray) {
426         if (pArray == null || pArray.length == 0) {
427             return pArray;
428         }
429         final Context context = new Context();
430         encode(pArray, 0, pArray.length, context);
431         encode(pArray, 0, EOF, context); // Notify encoder of EOF.
432         final byte[] buf = new byte[context.pos - context.readPos];
433         readResults(buf, 0, buf.length, context);
434         return buf;
435     }
436 
437     // package protected for access from I/O streams
438     abstract void encode(byte[] pArray, int i, int length, Context context);
439 
440     // package protected for access from I/O streams
441     abstract void decode(byte[] pArray, int i, int length, Context context);
442 
443     /**
444      * Returns whether or not the <code>octet</code> is in the current alphabet.
445      * Does not allow whitespace or pad.
446      *
447      * @param value The value to test
448      *
449      * @return <code>true</code> if the value is defined in the current alphabet, <code>false</code> otherwise.
450      */
451     protected abstract boolean isInAlphabet(byte value);
452 
453     /**
454      * Tests a given byte array to see if it contains only valid characters within the alphabet.
455      * The method optionally treats whitespace and pad as valid.
456      *
457      * @param arrayOctet byte array to test
458      * @param allowWSPad if <code>true</code>, then whitespace and PAD are also allowed
459      *
460      * @return <code>true</code> if all bytes are valid characters in the alphabet or if the byte array is empty;
461      *         <code>false</code>, otherwise
462      */
463     public boolean isInAlphabet(final byte[] arrayOctet, final boolean allowWSPad) {
464         for (int i = 0; i < arrayOctet.length; i++) {
465             if (!isInAlphabet(arrayOctet[i]) &&
466                     (!allowWSPad || (arrayOctet[i] != pad) && !isWhiteSpace(arrayOctet[i]))) {
467                 return false;
468             }
469         }
470         return true;
471     }
472 
473     /**
474      * Tests a given String to see if it contains only valid characters within the alphabet.
475      * The method treats whitespace and PAD as valid.
476      *
477      * @param basen String to test
478      * @return <code>true</code> if all characters in the String are valid characters in the alphabet or if
479      *         the String is empty; <code>false</code>, otherwise
480      * @see #isInAlphabet(byte[], boolean)
481      */
482     public boolean isInAlphabet(final String basen) {
483         return isInAlphabet(StringUtils.getBytesUtf8(basen), true);
484     }
485 
486     /**
487      * Tests a given byte array to see if it contains any characters within the alphabet or PAD.
488      *
489      * Intended for use in checking line-ending arrays
490      *
491      * @param arrayOctet
492      *            byte array to test
493      * @return <code>true</code> if any byte is a valid character in the alphabet or PAD; <code>false</code> otherwise
494      */
495     protected boolean containsAlphabetOrPad(final byte[] arrayOctet) {
496         if (arrayOctet == null) {
497             return false;
498         }
499         for (final byte element : arrayOctet) {
500             if (pad == element || isInAlphabet(element)) {
501                 return true;
502             }
503         }
504         return false;
505     }
506 
507     /**
508      * Calculates the amount of space needed to encode the supplied array.
509      *
510      * @param pArray byte[] array which will later be encoded
511      *
512      * @return amount of space needed to encoded the supplied array.
513      * Returns a long since a max-len array will require &gt; Integer.MAX_VALUE
514      */
515     public long getEncodedLength(final byte[] pArray) {
516         // Calculate non-chunked size - rounded up to allow for padding
517         // cast to long is needed to avoid possibility of overflow
518         long len = ((pArray.length + unencodedBlockSize-1)  / unencodedBlockSize) * (long) encodedBlockSize;
519         if (lineLength > 0) { // We're using chunking
520             // Round up to nearest multiple
521             len += ((len + lineLength-1) / lineLength) * chunkSeparatorLength;
522         }
523         return len;
524     }
525 }