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 * https://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.io.InputStream;
21
22 import org.apache.commons.codec.CodecPolicy;
23
24 /**
25 * Provides Base64 decoding in a streaming fashion (unlimited size). When encoding the default lineLength
26 * is 76 characters and the default lineEnding is CRLF, but these can be overridden by using the appropriate
27 * constructor.
28 * <p>
29 * The default behavior of the Base64InputStream is to DECODE, whereas the default behavior of the Base64OutputStream
30 * is to ENCODE, but this behavior can be overridden by using a different constructor.
31 * </p>
32 * <p>
33 * This class implements section <cite>6.8. Base64 Content-Transfer-Encoding</cite> from RFC 2045 <cite>Multipurpose
34 * Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies</cite> by Freed and Borenstein.
35 * </p>
36 * <p>
37 * Since this class operates directly on byte streams, and not character streams, it is hard-coded to only encode/decode
38 * character encodings which are compatible with the lower 127 ASCII chart (ISO-8859-1, Windows-1252, UTF-8, etc).
39 * </p>
40 * <p>
41 * You can set the decoding behavior when the input bytes contain leftover trailing bits that cannot be created by a
42 * valid encoding. These can be bits that are unused from the final character or entire characters. The default mode is
43 * lenient decoding.
44 * </p>
45 * <ul>
46 * <li>Lenient: Any trailing bits are composed into 8-bit bytes where possible. The remainder are discarded.
47 * <li>Strict: The decoding will raise an {@link IllegalArgumentException} if trailing bits are not part of a valid
48 * encoding. Any unused bits from the final character must be zero. Impossible counts of entire final characters are not
49 * allowed.
50 * </ul>
51 * <p>
52 * When strict decoding is enabled it is expected that the decoded bytes will be re-encoded to a byte array that matches
53 * the original, i.e. no changes occur on the final character. This requires that the input bytes use the same padding
54 * and alphabet as the encoder.
55 * </p>
56 * @see <a href="http://www.ietf.org/rfc/rfc2045.txt">RFC 2045</a>
57 * @since 1.4
58 */
59 public class Base64InputStream extends BaseNCodecInputStream {
60
61 /**
62 * Constructs a Base64InputStream such that all data read is Base64-decoded from the original provided InputStream.
63 *
64 * @param inputStream
65 * InputStream to wrap.
66 */
67 public Base64InputStream(final InputStream inputStream) {
68 this(inputStream, false);
69 }
70
71 /**
72 * Constructs a Base64InputStream such that all data read is either Base64-encoded or Base64-decoded from the original
73 * provided InputStream.
74 *
75 * @param inputStream
76 * InputStream to wrap.
77 * @param doEncode
78 * true if we should encode all data read from us, false if we should decode.
79 */
80 public Base64InputStream(final InputStream inputStream, final boolean doEncode) {
81 super(inputStream, new Base64(false), doEncode);
82 }
83
84 /**
85 * Constructs a Base64InputStream such that all data read is either Base64-encoded or Base64-decoded from the original
86 * provided InputStream.
87 *
88 * @param inputStream
89 * InputStream to wrap.
90 * @param doEncode
91 * true if we should encode all data read from us, false if we should decode.
92 * @param lineLength
93 * If doEncode is true, each line of encoded data will contain lineLength characters (rounded down to
94 * the nearest multiple of 4). If lineLength <= 0, the encoded data is not divided into lines. If
95 * doEncode is false, lineLength is ignored.
96 * @param lineSeparator
97 * If doEncode is true, each line of encoded data will be terminated with this byte sequence (for example \r\n).
98 * If lineLength <= 0, the lineSeparator is not used. If doEncode is false lineSeparator is ignored.
99 */
100 public Base64InputStream(final InputStream inputStream, final boolean doEncode, final int lineLength, final byte[] lineSeparator) {
101 super(inputStream, new Base64(lineLength, lineSeparator), doEncode);
102 }
103
104 /**
105 * Constructs a Base64InputStream such that all data read is either Base64-encoded or Base64-decoded from the original
106 * provided InputStream.
107 *
108 * @param inputStream
109 * InputStream to wrap.
110 * @param doEncode
111 * true if we should encode all data read from us, false if we should decode.
112 * @param lineLength
113 * If doEncode is true, each line of encoded data will contain lineLength characters (rounded down to
114 * the nearest multiple of 4). If lineLength <= 0, the encoded data is not divided into lines. If
115 * doEncode is false, lineLength is ignored.
116 * @param lineSeparator
117 * If doEncode is true, each line of encoded data will be terminated with this byte sequence (for example \r\n).
118 * If lineLength <= 0, the lineSeparator is not used. If doEncode is false lineSeparator is ignored.
119 * @param decodingPolicy The decoding policy.
120 * @since 1.15
121 */
122 public Base64InputStream(final InputStream inputStream, final boolean doEncode, final int lineLength, final byte[] lineSeparator,
123 final CodecPolicy decodingPolicy) {
124 super(inputStream, new Base64(lineLength, lineSeparator, false, decodingPolicy), doEncode);
125 }
126 }