RSA 非对称加密

RSA 是一种非对称加密算法，使用一对密钥：公钥用于加密、私钥用于解密；在数字签名场景下则相反，私钥用于签名、公钥用于验签。RSA 也常被用于加密对称密钥（如 AES 密钥），再由对称算法加密大量数据。

说明：RSA 加密的明文长度受密钥长度限制，超出上限会抛出异常，因此不适合直接加密大数据。密钥字符串可以是 Base64，也可以是带 -----BEGIN ...----- 头尾的 PEM 格式，模块会自动剥离头尾与空白字符。

rsa.generateKeyPair([keySize])

新增于：Hamibot 1.7.3

随机生成一对 RSA 密钥。

参数

名称	类型	描述
keySize	number	密钥长度（位），默认为 2048

返回值

字段	类型	描述
publicKey	string	公钥，X.509 格式的 Base64 字符串
privateKey	string	私钥，PKCS#8 格式的 Base64 字符串
keySize	number	密钥长度（位）

示例

var pair = rsa.generateKeyPair(); // 默认 2048 位
log('公钥：', pair.publicKey);
log('私钥：', pair.privateKey);
log('密钥长度：', pair.keySize); // => 2048
hamibot.exit();

rsa.encrypt(text, publicKey[, outputEncoding])

新增于：Hamibot 1.7.3

使用公钥加密文本，采用 RSA/ECB/PKCS1Padding 填充。

参数

名称	类型	描述
text	string	要加密的文本
publicKey	string	公钥（Base64 或 PEM）
outputEncoding	string	输出编码，默认为 Base64；传入 hex 时输出十六进制

返回值

类型	描述
string	加密后的密文

示例

var pair = rsa.generateKeyPair();
var encrypted = rsa.encrypt('Hello Hamibot!', pair.publicKey);
log('密文：', encrypted); // => Base64 字符串

var decrypted = rsa.decrypt(encrypted, pair.privateKey);
log('明文：', decrypted); // => Hello Hamibot!
hamibot.exit();

注意：明文长度上限为 密钥长度 ÷ 8 - 11 字节（2048 位密钥即 245 字节），超出会抛出异常。

rsa.encryptBytes(bytes, publicKey[, outputEncoding])

新增于：Hamibot 1.7.3

与 rsa.encrypt 相同，但加密的是字节数组而非字符串。

rsa.decrypt(cipherText, privateKey)

新增于：Hamibot 1.7.3

使用私钥解密，结果为 UTF-8 字符串。

参数

名称	类型	描述
cipherText	string	已加密的密文（Base64 或 PEM）
privateKey	string	私钥（Base64 或 PEM）

返回值

类型	描述
string	解密后的明文

rsa.decryptBytes(cipherText, privateKey)

新增于：Hamibot 1.7.3

与 rsa.decrypt 相同，但返回字节数组。

rsa.sign(text, privateKey[, algorithm])

新增于：Hamibot 1.7.3

使用私钥对文本进行签名。

参数

名称	类型	描述
text	string	要签名的文本
privateKey	string	私钥（Base64 或 PEM）
algorithm	string	签名算法，默认为 SHA256withRSA，可改为 SHA1withRSA 等

返回值

类型	描述
string	签名结果的 Base64

示例

var pair = rsa.generateKeyPair();
var sign = rsa.sign('Hello Hamibot!', pair.privateKey);
log('签名：', sign); // => Base64 字符串

log(rsa.verify('Hello Hamibot!', sign, pair.publicKey)); // => true
log(rsa.verify('tampered', sign, pair.publicKey)); // => false
hamibot.exit();

rsa.signBytes(bytes, privateKey[, algorithm])

新增于：Hamibot 1.7.3

与 rsa.sign 相同，但签名的是字节数组。

rsa.verify(text, signature, publicKey[, algorithm])

新增于：Hamibot 1.7.3

使用公钥验签。

参数

名称	类型	描述
text	string	原始文本
signature	string	签名结果（Base64 或 PEM）
publicKey	string	公钥（Base64 或 PEM）
algorithm	string	签名算法，默认为 SHA256withRSA

返回值

类型	描述
boolean	验签通过返回 true

rsa.verifyBytes(bytes, signature, publicKey[, algorithm])

新增于：Hamibot 1.7.3

与 rsa.verify 相同，但校验的是字节数组。

rsa.parsePublicKey(key)

新增于：Hamibot 1.7.3

将公钥字符串解析为底层公钥对象，便于配合其它原生 API 使用。

返回值

类型	描述
java.security.PublicKey	原生公钥对象

rsa.parsePrivateKey(key)

新增于：Hamibot 1.7.3

将私钥字符串解析为底层私钥对象。

返回值

类型	描述
java.security.PrivateKey	原生私钥对象