记一个 Base64 有关的 Bug

本文原计划写两部分内容，第一是记录最近遇到的与 Base64 有关的 Bug，第二是 Base64 编码的原理详解。结果写了一半发现，诶？不复杂的一个事儿怎么也要讲这么长？不利于阅读和理解啊（其实是今天有点懒想去休闲娱乐会儿），所以 Base64 编码的原理详解的部分将在下一篇带来，敬请关注。

0x01 遇到的现象

A 向 B 提供了一个接口，约定接口参数 Base64 编码后传递。

但 A 对 B 传递的参数进行 Base64 解码时报错了：

Illegal base64 character a

0x02 原因分析

搜索后发现这是一个好多网友们都踩过的坑，简而言之就一句话：Base64 编/解码器有不同实现，有的不相互兼容。

比如我上面遇到的现象，可以使用下面这段代码完整模拟复现：

package org.mazhuang.base64test;

import org.springframework.boot.CommandLineRunner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.util.Base64Utils;
import sun.misc.BASE64Encoder;

@SpringBootApplication
public class Base64testApplication implements CommandLineRunner {
    @Override
    public void run(String... args) throws Exception {
        byte[] content = "It takes a strong man to save himself, and a great man to save another.".getBytes();
        String encrypted = new BASE64Encoder().encode(content);
        byte[] decrypted = Base64Utils.decodeFromString(encrypted);
        System.out.println(new String(decrypted));
    }

    public static void main(String[] args) {
        SpringApplication.run(Base64testApplication.class, args);
    }

}

以上代码执行会报异常：

Caused by: java.lang.IllegalArgumentException: Illegal base64 character a
	at java.util.Base64$Decoder.decode0(Base64.java:714) ~[na:1.8.0_202-release]
	at java.util.Base64$Decoder.decode(Base64.java:526) ~[na:1.8.0_202-release]

注：测试代码里的那个字符串如果很短，比如「Hello, World」这种，可以正常解码。

也就是说，用 sun.misc.BASE64Encoder 编码，用 org.springframework.util.Base64Utils 进行解码，是有问题的，我们可以用它俩分别对以上符串进行编码，然后输出看看差异。测试代码：

byte[] content = "It takes a strong man to save himself, and a great man to save another.".getBytes();

System.out.println(new BASE64Encoder().encode(content));
System.out.println("--- 华丽的分隔线 ---");
System.out.println(Base64Utils.encodeToString(content));

输出：

SXQgdGFrZXMgYSBzdHJvbmcgbWFuIHRvIHNhdmUgaGltc2VsZiwgYW5kIGEgZ3JlYXQgbWFuIHRv
IHNhdmUgYW5vdGhlci4=
--- 华丽的分隔线 ---
SXQgdGFrZXMgYSBzdHJvbmcgbWFuIHRvIHNhdmUgaGltc2VsZiwgYW5kIGEgZ3JlYXQgbWFuIHRvIHNhdmUgYW5vdGhlci4=

可以看到 sun.misc.BASE64Encoder 编码后的内容换行了，而换行符的 ASCII 编码正好是 0x0a，如此貌似解释得通了。让我们进一步跟踪一下，找一下出现这种差异的源头。

0x03 更进一步

在 IDEA 里按住 CTRL 或 COMMAND 键点击方法名，可以跳转到它们的实现。

3.1 sun.misc.BASE64Encoder.encode

这种写法主要涉及到两个类，sun.misc 包下的 BASE64Encoder 和 CharacterEncoder，其中后者是前者的父类。

它实际工作的 encode 方法是在 CharacterEncoder 文件里，带注释版如下：

public void encode(InputStream inStream, OutputStream outStream)
    throws IOException {
    int     j;
    int     numBytes;
    // bytesPerLine 在 BASE64Encoder 里实现，返回 57
    byte    tmpbuffer[] = new byte[bytesPerLine()];

    // 用 outStream 构造一个 PrintStream
    encodeBufferPrefix(outStream);

    while (true) {
        // 读取最多 57 个 bytes
        numBytes = readFully(inStream, tmpbuffer);
        if (numBytes == 0) {
            break;
        }
        // 啥也没干
        encodeLinePrefix(outStream, numBytes);
        // 每次处理 3 bytes，编码成 4 bytes，不足位的补 0 位和 '='
        for (j = 0; j < numBytes; j += bytesPerAtom()) {
            // ...
        }
        if (numBytes < bytesPerLine()) {
            break;
        } else {
            // 换行
            encodeLineSuffix(outStream);
        }
    }
    // 啥也没干
    encodeBufferSuffix(outStream);
}

然后在 CharacterEncoder 类的注释里我们可以看到编码后的格式：

[Buffer Prefix]
[Line Prefix][encoded data atoms][Line Suffix]
[Buffer Suffix]

而结合 BASE64Encoder 这个实现类来看，Buffer Prefix、Buffer Suffix 和 Line Prefix 都为空，Line Suffix 为 \n。

至此，我们已经找到实现中换行的部分——这个编码器实现里，读取 57 个 byte 作为一行进行编码（编码完成后是 76 个 byte）。

3.2 org.springframework.util.Base64Utils.encodeToString

这种写法主要涉及到 org.springframework.util.Base64Utils 和 java.util.Base64 两个类，可以看到前者主要是后者的封装。

Base64Utils.encodeToString 这种写法最终用到的是 Base64.Encoder.RFC4648 这种编码器：

// isURL = false，newline = null，linemax = -1，doPadding = true
static final Encoder RFC4648 = new Encoder(false, null, -1, true);

留意 newline 和 linemax 的值。

然后看实际的编码实现所在的 Base64.encode0 方法：

private int encode0(byte[] src, int off, int end, byte[] dst) {
    // ...
    while (sp < sl) {
        // ...

        // 这个条件不会满足，不会加换行
        if (dlen == linemax && sp < end) {
            for (byte b : newline){
                dst[dp++] = b;
            }
        }
    }
    // ...
    return dp;
}

所以……这个实现里没有换行。

0x04 小结

经过以上的分析，真相已经大白了，就是两个编码器的实现不一样，我们在开发过程中注意使用匹配的编码解码器就 OK 了，就是用哪个 Java 包下面的编码器编码，就用相同包下的对应解码器解码。

至于为啥会出现不一样的实现，它们之间有过什么来龙去脉、恩怨情仇，Base64 的详细原理等等，就厚着老脸，邀请大家且听下回分解吧！:-P

文档信息

本文作者：Zhuang Ma
本文链接：https://mazhuang.org/2020/03/01/base64-bug/
版权声明：自由转载-非商用-非衍生-保持署名（创意共享3.0许可证）

码志