Flutter XML数据加密解密插件 xml_crypto 的使用

xml_crypto 是一个用于 Dart 的 XML 数字签名库，它移植自 Node.js 库 xml-crypto。本文将介绍如何在 Flutter 项目中使用该插件进行 XML 数据的加密和解密。

安装

首先，在你的 Flutter 项目的 pubspec.yaml 文件中添加 xml_crypto 依赖：

dependencies:
  xml_crypto: ^latest_version

然后运行以下命令来安装：

dart pub get

支持的算法

规范化和转换算法

• Canonicalization: http://www.w3.org/TR/2001/REC-xml-c14n-20010315
• Canonicalization with comments: http://www.w3.org/TR/2001/REC-xml-c14n-20010315#WithComments
• Exclusive Canonicalization: http://www.w3.org/2001/10/xml-exc-c14n#
• Exclusive Canonicalization with comments: http://www.w3.org/2001/10/xml-exc-c14n#WithComments
• Enveloped Signature transform: http://www.w3.org/2000/09/xmldsig#enveloped-signature

哈希算法

• SHA1 digests: http://www.w3.org/2000/09/xmldsig#sha1
• SHA256 digests: http://www.w3.org/2001/04/xmlenc#sha256
• SHA512 digests: http://www.w3.org/2001/04/xmlenc#sha512

签名算法

• RSA-SHA1: http://www.w3.org/2000/09/xmldsig#rsa-sha1
• RSA-SHA256: http://www.w3.org/2001/04/xmldsig-more#rsa-sha256
• RSA-SHA512: http://www.w3.org/2001/04/xmldsig-more#rsa-sha512

HMAC-SHA1 也是可用的，但默认情况下是禁用的：

import 'package:xml_crypto/xml_crypto.dart';

SignedXml.enableHMAC();

启用 HMAC 后会禁用数字签名算法。

签名 XML 文档

签名 XML 文档时，可以指定以下属性来自定义签名过程：

• sign.signingKey: 必需，包含私钥的 Uint8List
• sign.keyInfoProvider: 可选，包含证书的 key info provider 实例
• sign.signatureAlgorithm: 可选，支持的签名算法之一
• sign.canonicalizationAlgorithm: 可选，支持的规范化算法之一

示例代码：

import 'dart:io';
import 'package:xml_crypto/xml_crypto.dart';

final xml = "<library>"
            "<book>"
              "<name>Harry Potter</name>"
            "</book>"
          "</library>";

final sig = SignedXml()
  ..addReference("//*[local-name()='book']")
  ..signingKey = File("client.pem").readAsBytesSync()
  ..computeSignature(xml);
File("signed.xml").writeAsStringSync(sig.signedXml);

结果将会是一个带有签名的 XML 文档：

<library>
  <book Id="_0">
    <name>Harry Potter</name>
  </book>
  <Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
    <SignedInfo>
      <CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
      <SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1" />
      <Reference URI="#_0">
        <Transforms>
          <Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
        </Transforms>
        <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" />
        <DigestValue>cdiS43aFDQMnb3X8yaIUej3+z9Q=</DigestValue>
      </Reference>
    </SignedInfo>
    <SignatureValue>vhWzpQyIYuncHUZV9W...[long base64 removed]...</SignatureValue>
  </Signature>
</library>

验证 XML 文档

验证 XML 文档时，必须指定以下属性：

• sign.keyInfoProvider: 必需，包含证书的 key info provider 实例

示例代码：

import 'dart:io';
import 'package:xml/xml.dart' as xml;
import 'package:xml_crypto/xml_crypto.dart';

final signedXml = File("signed.xml").readAsStringSync();
var doc = xml.XmlDocument.parse(signedXml);

var signature = doc.findAllElements('Signature').first;
final sig = SignedXml()
  ..keyInfoProvider = FileKeyInfo("client_public.pem")
  ..loadSignature(signature);
final res = sig.checkSignature(signedXml);
if (!res) print(sig.validationErrors);

如果验证失败，sig.validationErrors 将包含错误信息。

为了防止某些攻击，我们还需要检查内容是否是我们要验证的内容：

final elem = doc.findAllElements('book').first;
final uri = sig.references.first.uri; // might not be 0 - depending on the document you verify
final id = (uri.startsWith('#')) ? uri.substring(1) : uri;
if (elem.getAttribute('ID') != id && elem.getAttribute('Id') != id && elem.getAttribute('id') != id)
  throw Exception('the interesting element was not the one verified by the signature');

自定义算法

你可以通过实现接口来自定义算法，例如 KeyInfoProvider, HashAlgorithm, SignatureAlgorithm, 和 CanonicalizationAlgorithm。

示例：自定义签名算法

class MySignatureAlgorithm implements SignatureAlgorithm {
  @override
  String getSignature(String xml, Uint8List signingKey, [CalculateSignatureCallback? callback]) {
    final rsa = RSAPrivateKey.fromPEM(utf8.decode(signingKey));
    final res = rsa.signSsaPkcs1v15ToBase64(utf8.encode(xml), hasher: EmsaHasher.sha1);
    callback?.call(null, res);
    return '';
  }

  @override
  bool verifySignature(String xml, Uint8List key, String signatureValue, [ValidateSignatureCallback? callback]) => true;

  @override
  String get algorithmName => 'http://mySigningAlgorithm';
}

SignedXml.signatureAlgorithms["http://mySigningAlgorithm"] = MySignatureAlgorithm();

异步签名和验证

如果你需要使用异步回调来进行签名或验证，可以创建自定义签名算法：

class AsyncSignatureAlgorithm implements SignatureAlgorithm {
  @override
  String getSignature(String xml, Uint8List signingKey, [CalculateSignatureCallback? callback]) {
    final rsa = RSAPrivateKey.fromPEM(utf8.decode(signingKey));
    final res = rsa.signSsaPkcs1v15ToBase64(utf8.encode(xml), hasher: EmsaHasher.sha1);
    callback?.call(null, res);
    return '';
  }

  @override
  bool verifySignature(String xml, Uint8List key, String signatureValue, [ValidateSignatureCallback? callback]) => true;

  @override
  String get algorithmName => 'http://www.w3.org/2000/09/xmldsig#rsa-sha1';
}

SignedXml.signatureAlgorithms["http://asyncSignatureAlgorithm"] = AsyncSignatureAlgorithm();
final sig = SignedXml();
sig.signatureAlgorithm = "http://asyncSignatureAlgorithm";
sig.computeSignature(xml, opts: opts, callback: (err, _) {
  final signedResponse = sig.signedXml;
});

完整示例 Demo

以下是一个完整的示例，展示了如何签名和验证 XML 文档：

import 'dart:io';
import 'package:xml/xml.dart' as xml;
import 'package:xml_crypto/xml_crypto.dart';

void main() {
  final xmlContent = "<library>"
      "<book>"
      "<name>Harry Potter</name>"
      "</book>"
      "</library>";

  // 签名 XML 文档
  signXml(xmlContent, "//*[local-name()='book']", 'client.pem', 'result.xml');

  print('XML 已成功签名');

  final signedXmlContent = File('result.xml').readAsStringSync();
  print('正在验证签名...');

  // 验证 XML 文档
  if (validateXml(signedXmlContent, 'client_public.pem')) {
    print('签名有效');
  } else {
    print('签名无效');
  }
}

void signXml(String xml, String xpath, String keyPath, String destPath) {
  final sig = SignedXml()
    ..signingKey = File(keyPath).readAsBytesSync()
    ..addReference(xpath)
    ..computeSignature(xml);
  File(destPath).writeAsStringSync(sig.signedXml);
}

bool validateXml(String xml, String publicKeyPath) {
  final doc = xml.XmlDocument.parse(xml);
  final signature = doc.findAllElements('Signature').first;
  final sig = SignedXml()
    ..keyInfoProvider = FileKeyInfo(publicKeyPath)
    ..loadSignature(signature);
  final res = sig.checkSignature(xml);
  if (!res) print(sig.validationErrors);
  return res;
}