💡 Ví dụ hoạt động đầy đủ có trên GitHub: sign-pdf-with-vault-managed-key-java

Cách Cũ Đầy Khó Khăn

Sổ hướng dẫn cho một dịch vụ ký Java thường chứa một bước mà không ai muốn ghi lại: sao chép signing.pfx vào máy chủ mới, rồi đặt mật khẩu vào môi trường. Từ thời điểm đó, khóa riêng tồn tại ở ít nhất ba nơi hơn so với dự định. Nó nằm trong lớp ảnh, trong bản sao lưu của máy chủ, và trong bộ nhớ của JVM tải nó, nơi một dump heap sẽ hiển thị nó cho bất kỳ ai có dump.

Ký ngoại vi là một khả năng của GroupDocs.Signature cho Java cho phép bạn truyền bản tóm tắt tài liệu tới một callback mà bạn cung cấp thay vì ký bằng khóa riêng mà ứng dụng tải. Đó là phần cho phép bạn xóa bước trong sổ hướng dẫn. Khóa ký được chuyển vào HashiCorp Vault, dịch vụ giữ một token thay vì một khóa, và giá trị duy nhất truyền qua mạng trong quá trình ký là một hàm băm 32 byte.

Các nhóm dùng cách này khi một cuộc đánh giá đặt câu hỏi hiển nhiên - ai khác có thể ký thay bạn - và câu trả lời trung thực là “bất kỳ ai từng có quyền truy cập vào tệp đó”. Khóa tệp lại bằng phân quyền và một ổ đĩa được mã hoá thu hẹp khoảng thời gian; nó không loại bỏ bản sao.

Có Cách Tốt Hơn

Động cơ Transit của Vault thực hiện mật mã như một dịch vụ. Bạn gửi cho nó một giá trị, nó ký bằng một khóa mà nó giữ, và trả về kết quả. Một khóa được tạo trong Transit có thể được đánh dấu là không xuất khẩu, do đó không có gì để sao chép lên máy chủ ngay từ đầu, và Vault không lưu gì bạn gửi cho nó.

Điều này chỉ hữu ích nếu thư viện ký có thể ủy thác, và đây là nơi GroupDocs.Signature xuất hiện. DigitalSignOptions.setCustomSignHash nhận một callback. Thư viện thực hiện mọi thứ cho tới mật mã: nó mở PDF, tính toán phạm vi byte mà chữ ký bao phủ, băm nó, gọi callback của bạn với bản tóm tắt, rồi nhúng các byte trả về cùng với chứng chỉ.

Bạn cần JDK 8 trở lên, Maven, Docker cho một Vault cục bộ, và BouncyCastle cho chứng chỉ. Mẫu chạy với GroupDocs.Signature for Java 26.10; không có giấy phép, chế độ đánh giá cho phép tài liệu tối đa 2 trang.

Cách Mới: Callback Thay Vì Tệp Khóa

Bước 1 - Đọc khóa từ Vault

Dịch vụ yêu cầu Vault cung cấp khóa mà nó được phép sử dụng và nhận một số phiên bản cùng với khóa công khai. Phần riêng tư không bao giờ xuất hiện trong phản hồi.

VaultKey key = vault.readKey(KEY_NAME);
if (key == null) {
    vault.enableTransit();
    vault.createKey(KEY_NAME, "rsa-2048");
    key = vault.readKey(KEY_NAME);
}

Mã 404 từ Vault nghĩa là khóa hoặc mount Transit bị thiếu, vì vậy mẫu xử lý nó như một thiết lập lần đầu thay vì lỗi. Trong môi trường sản xuất, quản trị viên bật Transit và tạo khóa trước, và token của ứng dụng không được phép thực hiện bất kỳ hành động nào trong số đó.

Đọc phiên bản một lần và giữ lại. Một chứng chỉ chỉ chứa một khóa công khai, vì vậy chứng chỉ và mọi chữ ký phải đến từ cùng một phiên bản.

Bước 2 - Xây dựng chứng chỉ quanh phần công khai

Một chữ ký PDF mang một chứng chỉ X.509 để người xác thực có thể tìm khóa công khai. JDK không có cách nào để tạo chứng chỉ mà chữ ký của nó đến từ nơi khác, nhưng BouncyCastle có thể: X509v3CertificateBuilder ủy thác cho một ContentSigner, và một ContentSigner được hỗ trợ bởi Vault chỉ khoảng mười lăm dòng.

@Override
public byte[] getSignature() {
    try {
        byte[] digest =
            MessageDigest.getInstance("SHA-256").digest(data.toByteArray());
        return vault.signHash(keyName, keyVersion, digest, "sha2-256");
    } catch (IOException e) {
        throw new UncheckedIOException(e);
    }
}

BouncyCastle ghi các byte cần ký vào luồng của signer rồi yêu cầu chữ ký. Các byte được băm cục bộ và chỉ bản tóm tắt được gửi tới Vault. Giao diện không khai báo ngoại lệ kiểm tra, vì vậy một lỗi Vault phải được bọc và giải bọc bởi người gọi; bỏ qua điều đó và một lỗi 403 từ Vault sẽ xuất hiện dưới dạng lỗi runtime khó hiểu.

Bước 3 - Ký, rồi xác thực trong cùng một lần chạy

DigitalSignature digitalSignature = new DigitalSignature();
digitalSignature.setX509Certificate(certificate);

DigitalSignOptions options = new DigitalSignOptions();
options.setSignature(digitalSignature);
options.setCustomSignHash(signer::customSignHash);
options.setHashAlgorithm(HashAlgorithm.Sha256);

ByteArrayOutputStream signedPdf = new ByteArrayOutputStream();
signature.sign(signedPdf, options);
Files.write(outputPdf, trimTrailingZeros(signedPdf.toByteArray()));

Trong callback, bản tóm tắt được gửi tới transit/sign với hai trường quyết định kết quả có hợp lệ hay không: prehashed = true, vì đầu vào đã là một hàm băm, và signature_algorithm = pkcs1v15, vì Vault mặc định dùng PSS cho các khóa RSA trong khi một chữ ký PDF là sha256WithRSAEncryption.

Sau đó xác thực trước khi tệp được chuyển đi. Ký và xác thực trong một lần chạy là cách biến chế độ lỗi im lặng duy nhất thành lỗi ngay lập tức.

So Sánh: Trước và Sau

PFX trên máy chủ Callback Transit của Vault
Bản sao của khóa riêng một bản cho mỗi máy chủ, ảnh và sao lưu một bản, nằm trong Vault
Những gì dịch vụ giữ khóa và mật khẩu của nó một token có phạm vi cho hai thao tác
Bước triển khai cho máy chủ mới sao chép PFX, đặt mật khẩu không có gì
Ghi chép mỗi chữ ký log ứng dụng, nếu có một mục audit của Vault
Sau khi nghi ngờ rò rỉ thu hồi, phát hành lại, triển khai lại mọi nơi quay vòng trong Vault, phát hành lại một lần
Ai có thể ký thay bạn bất kỳ ai có tệp và mật khẩu bất kỳ ai có token Vault hợp lệ

Dòng cuối đáng được nêu rõ ràng: cách này di chuyển bí mật thay vì xóa bỏ nó. Sự khác biệt là token có thời gian ngắn, có thể thu hồi ở một nơi, giới hạn việc đọc một khóa và gọi ký, và được ghi lại mỗi khi sử dụng.

Ví Dụ Thực Tế: Dịch Vụ Bảng Sao Kê

Một dịch vụ tạo bảng sao kê hàng tháng và ký mỗi bản trước khi đưa vào cổng khách hàng. Với cách cũ, ảnh container mang chứng chỉ, và ba người có mật khẩu vì ai đó phải quay vòng nó. Với callback, ảnh không chứa bất kỳ bí mật nào: pod nhận token AppRole khi khởi động, chính sách trong vault/sample-signer.hcl cho phép đọc khóa và ký bằng nó, và bất kỳ hành động nào khác token thử sẽ trả về 403 permission denied.

Khi kiểm toán viên hỏi có bao nhiêu tài liệu đã được ký trong tháng Ba và bằng phiên bản khóa nào, câu trả lời đến từ thiết bị audit của Vault thay vì từ việc grep log ứng dụng.

Quay vòng là nơi thiết kế này thể hiện giá trị, và cũng là nơi có thể gây rắc rối. Sau transit/keys/:name/rotate Vault sẽ ký bằng phiên bản mới nhất trừ khi bạn chỉ định khác, vì vậy một chứng chỉ được tạo cho phiên bản 1 kết hợp với chữ ký từ phiên bản 2 sẽ tạo ra một PDF không báo lỗi và không thể xác thực. Vì signer được xây dựng với một phiên bản, điều này không thể xảy ra ngẫu nhiên ở đây: dịch vụ bảng sao kê tiếp tục ký với phiên bản mà chứng chỉ của nó thuộc về cho đến khi ai đó phát hành chứng chỉ mới cho phiên bản mới. Đặt min_encryption_version trên khóa sau đó làm cho phiên bản cũ không sử dụng được, Vault sẽ báo từ chối ký thay vì báo lỗi chữ ký.

Những điểm kỳ quặc tôi nên mong đợi ở phiên bản 26.10?

Bốn điểm, tất cả được phát hiện khi chạy bản dựng này. Tên phương thức ICustomSignHash bị làm rối trong jar, vì vậy hãy truyền một tham chiếu phương thức thay vì triển khai giao diện. Đầu ra đã ký xuất hiện các byte zero dư thừa bên ngoài chữ ký, vì vậy cần cắt bỏ chúng. DigitalVerifyOptions yêu cầu tệp chứng chỉ, không phải một luồng. Và hộp chữ ký hiển thị cần Arial được cài đặt.

Những Điều Khác Bạn Có Thể Làm Với GroupDocs.Signature?

Callback không biết gì phía sau nó, vì vậy ba bước này cũng hoạt động với một mô-đun phần cứng, thẻ thông minh hoặc KMS đám mây. Tôi đã chuyển mẫu này từ các phiên bản .NET và Python của cùng một mẫu, và phần thân yêu cầu Vault vẫn không thay đổi; việc xây dựng chứng chỉ và bốn điểm kỳ quặc trên là những phần duy nhất thực sự mang đặc trưng Java. Ngoài chữ ký số, thư viện còn thêm và tìm kiếm chữ ký văn bản, hình ảnh, mã vạch, QR code và siêu dữ liệu trên PDF, Word, Excel, PowerPoint và các định dạng hình ảnh.

Kết Luận

Ký một PDF trong Java mà không giữ khóa riêng yêu cầu một callback, một chứng chỉ được xây dựng xung quanh khóa công khai, và một token với hai quyền. Mẫu chạy với Vault ở chế độ dev chỉ bằng hai lệnh, và cùng một đoạn mã có thể hướng tới Vault sản xuất bằng cách thay đổi VAINT_ADDR và VAULT_TOKEN.

Tài Nguyên Bổ Sung