1. 项目概述为什么我们需要一个自研的RSA工具类最近在做一个涉及用户敏感数据传输的项目对接的第三方平台要求使用RSA非对称加密来签名和验签。我本以为用Java自带的java.security包分分钟就能搞定结果却踩了一连串的坑。比如对方只提供了一个PEM格式的私钥文件我需要自己算出公钥又比如生成的密钥对在不同系统间导入时因为格式问题老是报“RSA public key not find”或者“invalid-signature”。网上的代码片段要么不全要么就是各种NoSuchAlgorithmException和InvalidKeySpecException满天飞调试起来非常痛苦。正是这些实际开发中的痛点催生了这个“Java RSA加密工具类”的诞生。它不是一个简单的加密解密Demo而是一个从密钥对生成、格式转换、到加密解密、签名验签的完整解决方案尤其解决了“根据私钥推导计算公钥”这个在对接外部系统时经常遇到的需求。如果你也在为RSA的各种边界情况头疼或者不想每次用到时都去网上零散地复制粘贴代码那么这个工具类或许能成为你项目中的一个可靠“瑞士军刀”。2. 核心设计思路与方案选型2.1 为什么选择RSA而不是AES在开始设计工具类之前首先要明确场景。RSA和AES是两种最常用的加密算法但它们的定位完全不同。AES对称加密加密和解密使用同一把密钥。它的优点是速度快适合加密大量数据比如文件内容、数据库字段。但缺点是如何安全地交换这把共同的密钥是个难题。RSA非对称加密使用公钥和私钥一对密钥。公钥公开用于加密或验签私钥自己保管用于解密或签名。它的优点是解决了密钥分发问题天生适用于不信任的网络环境。但缺点是速度慢通常只用于加密少量关键数据如会话密钥或进行数字签名。我们的工具类定位很明确解决身份认证、数据防篡改、安全密钥交换等场景这些正是RSA的用武之地。例如用户登录时用私钥签名一段数据服务器用公钥验签客户端用服务器的公钥加密一个临时生成的AES密钥实现安全传输。2.2 工具类的核心能力规划基于常见需求我决定让这个工具类具备以下核心能力这构成了类的骨架密钥对生成支持指定密钥长度如2048位生成RSA密钥对。密钥格式化与解析这是重中之重。必须支持多种格式的相互转换尤其是PEM格式-----BEGIN XXX KEY-----与Java原生Key对象之间的转换。很多“RSA public key not find”错误都源于格式不兼容。加密与解密提供标准的公钥加密、私钥解密功能。签名与验签提供用私钥对数据生成签名以及用公钥验证签名的功能确保数据的完整性和来源可信。根据私钥计算公钥这是特色功能。当第三方只提供私钥或者我们从存储中只读取到私钥信息时能够直接推导出对应的公钥对象。2.3 技术栈选型坚持标准库避免过度依赖在选型上我坚持使用Java标准库JCA - Java Cryptography Architecture中的java.security和javax.crypto包。原因有三无依赖项目无需引入任何第三方Jar包如Bouncy Castle减少了依赖冲突和部署复杂度。通用性强标准API在任何Java环境中都可用兼容性好。足够成熟对于RSA的常规操作标准库的API已经完全够用。当然标准库对某些非标准PEM格式的处理比较麻烦这就需要我们编写一些格式解析的辅助代码。这是一个权衡用一些编码工作换来项目的简洁性。注意有同学可能会遇到“未能加载文件或程序集‘aspose.pdf’或它的某一个依赖项。未能验证强名称签名……”这类错误这通常是.NET强名称签名的问题与Java RSA无关切勿混淆。我们的工具类纯粹基于Java标准库不涉及此类问题。3. 核心细节解析与实操要点3.1 密钥的“模样”PKCS#1与PKCS#8格式辨析在编码之前必须理解密钥的格式这是后续所有操作的基础。我们最常听到的是PEM格式但它只是一个封装里面包裹的密钥数据本身还有不同的标准。PKCS#1传统格式专门用于RSA密钥。私钥以-----BEGIN RSA PRIVATE KEY-----开头公钥以-----BEGIN RSA PUBLIC KEY-----开头。这种格式定义较早很多老系统或OpenSSL默认生成这种格式。PKCS#8更通用的格式可以封装任何算法的私钥。私钥以-----BEGIN PRIVATE KEY-----开头没有“RSA”字样。公钥也有对应的-----BEGIN PUBLIC KEY-----。Java的KeyFactory在解析时更“偏爱”PKCS#8格式。实操心得Java标准库的RSAPrivateCrtKeySpec更适合解析PKCS#1格式的私钥而PKCS8EncodedKeySpec用于解析PKCS#8格式的私钥。如果你的私钥是OpenSSL默认生成的PKCS#1格式直接使用PKCS8EncodedKeySpec会报错。我们的工具类需要能智能处理或明确告知用户格式。3.2 填充模式与算法标识OAEP与PKCS#1_v1.5RSA加密本身是数学运算但直接对原始数据进行运算存在安全漏洞因此需要填充Padding。常见的填充模式有PKCS#1 v1.5 Padding这是老标准使用非常广泛。但在某些情况下可能存在理论上的弱点。在代码中对应的算法标识符通常是RSA/ECB/PKCS1Padding。OAEP Padding (PKCS#1 v2)更安全的填充方案推荐在新项目中使用。它在算法标识中需要指定哈希函数如RSA/ECB/OAEPWithSHA-256AndMGF1Padding。关键点加密方和解密方必须使用完全相同的填充模式如果你用OAEP加密用PKCS#1解密一定会失败。在工具类设计时我将填充模式作为可配置参数但为常用场景提供了默认值如PKCS#1_v1.5并在文档中强调一致性。3.3 Base64编码密钥与密文的“通行证”无论是将二进制的密钥保存为文本文件PEM还是将加密后的二进制密文在网络中传输都需要用到Base64编码。PEM格式本质上就是“头部信息 Base64编码的密钥数据 尾部信息”。在工具类中我们需要频繁地在byte[]和Base64字符串之间进行转换。这里要特别注意换行符有些标准的PEM文件每64个字符会有一个换行符解析时需要先去除这些无关字符如\n,\r,-, 。URL安全当密文需要放在URL或Cookie中时要使用URL安全的Base64编码将和/替换为-和_我们的工具类也包含了对应的处理选项。4. 工具类核心代码实现与解析下面我将分模块展示工具类的核心代码并解释每一部分的意图和注意事项。4.1 密钥对生成器这是最基础的功能。我们通过KeyPairGenerator来生成指定长度的RSA密钥对。import java.security.*; import java.util.Base64; public class RSAUtil { // 默认密钥长度2048位是目前安全与性能的平衡点 private static final int DEFAULT_KEY_SIZE 2048; /** * 生成RSA密钥对 * param keySize 密钥长度建议至少2048 * return 生成的KeyPair对象 * throws NoSuchAlgorithmException */ public static KeyPair generateKeyPair(int keySize) throws NoSuchAlgorithmException { if (keySize 512) { throw new IllegalArgumentException(密钥长度过短不安全。建议使用2048或以上。); } KeyPairGenerator keyPairGen KeyPairGenerator.getInstance(RSA); keyPairGen.initialize(keySize, new SecureRandom()); // 使用强随机数源 return keyPairGen.generateKeyPair(); } /** * 使用默认密钥长度(2048)生成密钥对 */ public static KeyPair generateKeyPair() throws NoSuchAlgorithmException { return generateKeyPair(DEFAULT_KEY_SIZE); } }注意SecureRandom()是密码学安全的随机数生成器比普通的Random类安全得多务必使用它来初始化密钥生成器否则生成的密钥可能被预测。4.2 密钥格式化与解析核心难点这部分代码最多也最容易出错。我们实现PEM格式与JavaKey对象的互转。import java.security.spec.*; import java.util.regex.Pattern; public class RSAUtil { // ... 其他代码 ... /** * 将公钥对象转换为PKCS#8格式的PEM字符串 */ public static String getPublicKeyPem(PublicKey publicKey) { String base64Key Base64.getEncoder().encodeToString(publicKey.getEncoded()); return -----BEGIN PUBLIC KEY-----\n formatBase64WithLineBreak(base64Key) \n-----END PUBLIC KEY-----; } /** * 将私钥对象转换为PKCS#8格式的PEM字符串 */ public static String getPrivateKeyPem(PrivateKey privateKey) { String base64Key Base64.getEncoder().encodeToString(privateKey.getEncoded()); return -----BEGIN PRIVATE KEY-----\n formatBase64WithLineBreak(base64Key) \n-----END PRIVATE KEY-----; } // 辅助方法为Base64字符串添加换行使其更符合PEM文件观感 private static String formatBase64WithLineBreak(String str) { // 每64字符插入一个换行 return str.replaceAll((.{64}), $1\n).trim(); } /** * 从PEM字符串解析出公钥对象 (支持 PKCS#8 格式) * param pemString 以 -----BEGIN PUBLIC KEY----- 开头的字符串 */ public static PublicKey parsePublicKeyFromPem(String pemString) throws GeneralSecurityException { byte[] keyBytes parsePemContent(pemString, PUBLIC); KeyFactory keyFactory KeyFactory.getInstance(RSA); X509EncodedKeySpec keySpec new X509EncodedKeySpec(keyBytes); return keyFactory.generatePublic(keySpec); } /** * 从PEM字符串解析出私钥对象 (自动尝试PKCS#8失败则尝试PKCS#1) * param pemString 以 -----BEGIN (RSA) PRIVATE KEY----- 开头的字符串 */ public static PrivateKey parsePrivateKeyFromPem(String pemString) throws GeneralSecurityException { byte[] keyBytes parsePemContent(pemString, PRIVATE); KeyFactory keyFactory KeyFactory.getInstance(RSA); // 优先尝试PKCS#8格式 try { PKCS8EncodedKeySpec keySpec new PKCS8EncodedKeySpec(keyBytes); return keyFactory.generatePrivate(keySpec); } catch (InvalidKeySpecException e1) { // 如果PKCS#8失败尝试PKCS#1格式 try { // 将PKCS#1的二进制数据转换为RSAPrivateCrtKeySpec需要额外的解析 // 这里为了简化我们可以借助BouncyCastle但为了无依赖我们换一种方式。 // 实际上OpenSSL生成的PKCS#1私钥可以通过以下命令转换为PKCS#8 // openssl pkcs8 -topk8 -inform PEM -in pkcs1.key -outform PEM -nocrypt -out pkcs8.key // 因此工具类可以提示用户先转换格式或者我们实现一个简单的PKCS#1解析。 // 由于篇幅此处抛出更明确的异常提示用户格式问题。 throw new InvalidKeySpecException(私钥格式可能为PKCS#1。请使用PKCS#8格式的私钥或使用工具进行转换。原始错误: e1.getMessage()); } catch (Exception e2) { throw new InvalidKeySpecException(无法解析私钥请确认PEM格式是否正确。, e2); } } } // 辅助方法从PEM字符串中提取Base64编码的密钥数据部分并解码为byte[] private static byte[] parsePemContent(String pemString, String keyType) { // 移除所有空白字符和PEM头尾标记 String normalized pemString.replaceAll(\\s, ); Pattern pattern Pattern.compile(-----BEGIN keyType KEY-----(.*?)-----END keyType KEY-----, Pattern.DOTALL); java.util.regex.Matcher matcher pattern.matcher(normalized); if (!matcher.find()) { throw new IllegalArgumentException(无效的PEM格式: 未找到正确的 keyType KEY 头尾标记); } String base64Content matcher.group(1); return Base64.getDecoder().decode(base64Content); } }代码解析与避坑getEncoded()方法返回的是密钥的DER编码格式直接做Base64就是PEM的内容。解析时X509EncodedKeySpec用于公钥PKCS8EncodedKeySpec用于私钥PKCS#8格式。最大的坑在于私钥的PKCS#1格式。上述代码选择在遇到PKCS#1时抛出明确异常。在生产环境中更稳健的做法是要么约定统一使用PKCS#8格式要么引入一个轻量级的解析库如BouncyCastle来同时支持两种格式。为了保持工具类的纯净我这里采用了第一种策略并在异常信息中给出解决方案。4.3 根据私钥计算公钥这是很多工具类缺失的功能。原理是RSA私钥特别是RSAPrivateCrtKey包含了构成公钥的所有信息模数n和公钥指数e。import java.security.interfaces.RSAPrivateCrtKey; import java.security.interfaces.RSAPublicKey; public class RSAUtil { // ... 其他代码 ... /** * 从私钥对象中提取并生成对应的公钥对象 * param privateKey 必须是 RSAPrivateCrtKey 类型的私钥 * return 对应的公钥 * throws IllegalArgumentException 如果私钥不是 RSAPrivateCrtKey 类型 */ public static PublicKey getPublicKeyFromPrivate(PrivateKey privateKey) throws GeneralSecurityException { if (!(privateKey instanceof RSAPrivateCrtKey)) { throw new IllegalArgumentException(提供的私钥不是 RSAPrivateCrtKey 类型无法提取公钥信息。); } RSAPrivateCrtKey rsaPrivateKey (RSAPrivateCrtKey) privateKey; // 从私钥中获取公钥的模数(n)和公钥指数(e) java.math.BigInteger modulus rsaPrivateKey.getModulus(); java.math.BigInteger publicExponent rsaPrivateKey.getPublicExponent(); // 注意这是公钥指数通常是65537 // 使用获取的n和e重新构造公钥 RSAPublicKeySpec publicKeySpec new RSAPublicKeySpec(modulus, publicExponent); KeyFactory keyFactory KeyFactory.getInstance(RSA); return keyFactory.generatePublic(publicKeySpec); } /** * 直接从PEM格式的私钥字符串计算出公钥PEM字符串 */ public static String calculatePublicKeyPemFromPrivatePem(String privateKeyPem) throws GeneralSecurityException { PrivateKey privateKey parsePrivateKeyFromPem(privateKeyPem); PublicKey publicKey getPublicKeyFromPrivate(privateKey); return getPublicKeyPem(publicKey); } }关键点RSAPrivateCrtKey是RSAPrivateKey的一个子接口它包含了中国剩余定理CRT所需的参数其中就有公钥指数e。并非所有PrivateKey对象都能强转为RSAPrivateCrtKey但由标准KeyPairGenerator生成的RSA私钥通常都是这种类型。这个方法在从第三方获取的私钥推导公钥时极其有用。4.4 加密、解密、签名、验签有了密钥对象核心操作就相对标准了。这里以PKCS#1_v1.5填充为例。import javax.crypto.Cipher; public class RSAUtil { // ... 其他代码 ... private static final String TRANSFORMATION RSA/ECB/PKCS1Padding; private static final String SIGNATURE_ALGORITHM SHA256withRSA; /** * 公钥加密 * param data 明文数据 * param publicKey 公钥 * return 密文字节数组 */ public static byte[] encrypt(byte[] data, PublicKey publicKey) throws GeneralSecurityException { Cipher cipher Cipher.getInstance(TRANSFORMATION); cipher.init(Cipher.ENCRYPT_MODE, publicKey); return cipher.doFinal(data); } /** * 私钥解密 * param encryptedData 密文数据 * param privateKey 私钥 * return 明文字节数组 */ public static byte[] decrypt(byte[] encryptedData, PrivateKey privateKey) throws GeneralSecurityException { Cipher cipher Cipher.getInstance(TRANSFORMATION); cipher.init(Cipher.DECRYPT_MODE, privateKey); return cipher.doFinal(encryptedData); } /** * 私钥签名 * param data 待签名数据 * param privateKey 私钥 * return 签名字节数组 */ public static byte[] sign(byte[] data, PrivateKey privateKey) throws GeneralSecurityException { Signature signature Signature.getInstance(SIGNATURE_ALGORITHM); signature.initSign(privateKey); signature.update(data); return signature.sign(); } /** * 公钥验签 * param data 原始数据 * param sign 签名数据 * param publicKey 公钥 * return 验签是否通过 */ public static boolean verify(byte[] data, byte[] sign, PublicKey publicKey) throws GeneralSecurityException { Signature signature Signature.getInstance(SIGNATURE_ALGORITHM); signature.initVerify(publicKey); signature.update(data); return signature.verify(sign); } }重要提示RSA加密有数据长度限制。对于RSA/ECB/PKCS1Padding明文数据长度必须 密钥长度(字节) - 11。例如2048位密钥256字节最多能加密245字节的明文。加密更长的数据需要采用“混合加密”用RSA加密一个随机的AES密钥再用这个AES密钥加密实际数据。5. 常见问题与排查技巧实录在实际使用中我遇到了各种各样的问题。下面这个表格整理了一些典型错误和解决方法问题现象可能原因排查步骤与解决方案java.security.spec.InvalidKeySpecException1. 密钥格式错误如用PKCS8解析PKCS1。2. PEM字符串头尾标记不正确或含有非法字符。3. Base64编码损坏。1. 确认密钥格式。用文本编辑器打开PEM文件看头尾标记。如果是BEGIN RSA PRIVATE KEY是PKCS#1需要转换或使用对应解析方法。2. 使用parsePemContent方法打印清理后的Base64字符串检查是否完整。3. 尝试用在线Base64工具解码看是否报错。javax.crypto.BadPaddingException: Decryption error或InvalidSignature1.最可能加密/签名与解密/验签使用的密钥不配对。2. 填充模式不一致。3. 数据在传输过程中被篡改或编码出错。1.双重检查密钥对是否匹配。可以用工具类生成一对新密钥测试。2. 确认双方代码中的TRANSFORMATION字符串完全一致。3. 检查加密/签名后的字节数组在传输或存储前后是否经过了一致的Base64编解码。RSA public key not find(常见于Navicat等工具)1. 公钥格式不被工具识别。2. 公钥文件损坏或内容不正确。3. 工具要求的密钥格式特殊如OpenSSH格式。1. 确保公钥是标准的PKCS#8 PEM格式(BEGIN PUBLIC KEY)。2. 用我们的getPublicKeyPem方法重新生成并保存文件注意换行符。3. 查阅对应工具的文档看是否需要特定的密钥格式转换。加密时抛出IllegalBlockSizeException明文数据长度超过了当前密钥和填充模式允许的最大值。计算最大加密长度(密钥位数/8) - 11。对于超长数据必须采用“混合加密”方案。从私钥计算公钥时抛出IllegalArgumentException提供的私钥对象不是RSAPrivateCrtKey类型。确认私钥来源。如果是通过parsePrivateKeyFromPem解析标准PEM文件得到的通常是这个类型。如果是其他方式生成的可能需要转换。与其他系统如PHP、Python加解密/签名结果不一致1. 默认参数不同如哈希算法、MGF1参数。2. 数据编码不同如字符串的字符集UTF-8 vs GBK。3. 填充模式不同。1.对齐所有参数明确指定哈希算法如SHA-256、MGF1算法、盐值长度等。2.统一数据预处理在加密/签名前明确将字符串转换为字节数组的编码如data.getBytes(StandardCharsets.UTF_8)。3. 使用相同的填充模式。一个典型的调试案例我曾对接一个支付平台验签一直失败。排查过程如下检查密钥确认匹配。检查签名算法都是SHA256withRSA。将待签名的原始字符串、我方生成的签名、对方返回的签名分别做Base64打印出来对比。发现差异对方提供的“待签名原文”末尾比我们拼接的字符串多了一个换行符(\n)。根本原因双方对接文档对参数拼接规则描述有歧义。修正拼接逻辑后验签通过。实操心得在涉及加解密的联调中十六进制(Hex)或Base64日志是你的最好朋友。将关键步骤的输入输出原始数据、密钥指纹、签名结果打印出来与对方对比能快速定位问题出在哪个环节。不要只看“成功”或“失败”的布尔值。