Đội phát triển cần biết đầu ra là chữ ký của một giá trị băm hay cả tệp PDF đã ký. Với PKCS#11, ứng dụng mở phiên, tìm đối tượng khóa rồi gọi hàm ký. Với API dịch vụ, ứng dụng còn phải theo luồng cấp quyền mà nhà cung cấp công bố. Chốt đầu ra và phạm vi ủy quyền trước khi ước lượng công tích hợp.

Chọn giao diện theo phần ứng dụng đang thiếu
PKCS#11 định nghĩa giao diện thao tác với token mật mã, gồm phiên, đối tượng khóa và các hàm mật mã. Ứng dụng sử dụng thư viện do bên triển khai cung cấp. Với HSM mạng, thư viện có thể xử lý kết nối tới thiết bị; không nên hiểu “gọi thư viện” là thiết bị buộc phải cắm trực tiếp vào máy ứng dụng.
REST API là cách một dịch vụ công bố giao diện qua HTTP. Phạm vi thực tế phụ thuộc dịch vụ: có nơi nhận giá trị băm rồi trả chữ ký, có nơi nhận tài liệu và xử lý đầu ra. Trước khi chọn, yêu cầu tài liệu mô tả rõ đầu vào, đầu ra, xác thực và cách lấy kết quả.

Từ phiên PKCS#11 đến C_Sign
Theo đặc tả OASIS PKCS#11, luồng rút gọn cho ứng dụng ký gồm các nhóm thao tác sau. Đây là sơ đồ gọi hàm, không phải chương trình chạy được; cần bổ sung kiểm lỗi, lựa chọn cơ chế và quản lý tài nguyên theo SDK.
- Khởi tạo thư viện bằng “C_Initialize”, lấy danh sách slot phù hợp và đọc cơ chế được hỗ trợ bằng “C_GetMechanismList”.
- Mở phiên bằng “C_OpenSession”, đăng nhập bằng “C_Login” khi thao tác cần xác thực.
- Tìm đối tượng khóa bằng nhóm “C_FindObjectsInit”, “C_FindObjects”, “C_FindObjectsFinal”. Chọn theo các thuộc tính đã quy định trong triển khai.
- Gọi “C_SignInit” với cơ chế và tham chiếu khóa đúng. Thực hiện “C_Sign” cho dữ liệu một phần, hoặc luồng ký nhiều phần mà cơ chế hỗ trợ.
- Hoàn tất quản lý phiên và thư viện theo vòng đời ứng dụng, rồi kiểm chữ ký bằng dữ liệu và khóa công khai tương ứng.
Cần phân biệt khóa được nhìn thấy với khóa được phép dùng để ký. Đặc tả nêu thuộc tính “CKA_SIGN” phải cho phép chức năng ký ở luồng này. Khi gặp “CKR_KEY_FUNCTION_NOT_PERMITTED”, hãy kiểm quyền chức năng của khóa và cơ chế đang chọn, không vội tạo một khóa mới.
“CKR_USER_NOT_LOGGED_IN” cũng khác với việc không tìm thấy đối tượng khóa. Ghi hàm đang gọi và mã trả về để xử lý đúng bước. Không đổi nhiều tham số cùng lúc rồi chỉ nhìn xem lỗi có biến mất hay không.

Với dịch vụ ký từ xa, kiểm quyền trước khi gửi dữ liệu
Đặc tả Cloud Signature Consortium tách việc cho phép sử dụng chứng thư và tạo chữ ký. Khi đã có quyền phù hợp, ứng dụng gọi signatures/signHash với giá trị băm theo thuật toán đã chọn.
Do đó, chỉ có thông tin đăng nhập dịch vụ chưa đủ để viết ngay lệnh ký đúng nghiệp vụ. Cần xác định chứng thư sẽ dùng, phạm vi cho phép, thuật toán và định dạng dữ liệu. Không dùng tên “REST API” để suy rằng toàn bộ phần xác thực người ký đã được giải quyết sẵn.
Nếu đầu ra là chữ ký trên giá trị băm, ứng dụng vẫn phải hoàn thiện cấu trúc tài liệu theo định dạng đang triển khai. Hãy đưa trách nhiệm tạo tệp đầu ra vào thiết kế: bên nào đóng gói chữ ký, gắn chứng thư và kiểm tệp sau ký? Đây là câu hỏi hợp đồng tích hợp, không nên để tới lúc nghiệm thu mới phân công.
Hai ca lỗi cần có trong bộ thử nghiệm thu
Bắt đầu bằng một khóa kiểm thử và tài liệu mẫu đã biết nội dung. Chạy ca thành công, sau đó thử riêng tài khoản thiếu quyền, tham chiếu khóa sai, cơ chế không hỗ trợ và dữ liệu bị thay đổi. Đánh dấu đây là các ca kiểm thử do đội triển khai thiết kế, không phải bộ kiểm định pháp lý.
Với ký qua mạng, bổ sung tình huống nhận kết quả chậm hoặc mất phản hồi. Trước khi gửi lại yêu cầu, dùng cơ chế tra cứu hoặc chống lặp mà API thực tế cung cấp. Nếu tài liệu không mô tả cơ chế đó, ghi thành điểm phải giải quyết trước vận hành; không tự giả định gọi lại sẽ luôn an toàn.
Có PKCS#11 thì đổi HSM không phải sửa ứng dụng?
Không bảo đảm. Phải kiểm cơ chế, thuộc tính, hệ điều hành và phần chức năng SDK hỗ trợ thực tế.
REST API có luôn trả PDF đã ký không?
Không. Cần đọc đúng phương thức: ký giá trị băm và ký tài liệu có đầu vào, đầu ra khác nhau.
Có cần đưa khóa bí mật vào mã nguồn để gọi HSM?
Không nên thiết kế như vậy. Dùng cơ chế xác thực và tham chiếu khóa theo SDK hoặc dịch vụ, tách thông tin bí mật khỏi mã nguồn.
Cập nhật ngày 18/11/2026. Căn cứ kỹ thuật: OASIS, PKCS#11 Specification Version 3.1, nhóm hàm phiên, đối tượng và ký; AWS CloudHSM, Client SDKs và PKCS#11 library; Cloud Signature Consortium, Architectures and protocols for remote signature applications; Cloud Signature Consortium, Content Trust API. Bài mô tả luồng, không cam kết SDK nào hỗ trợ toàn bộ chuẩn.
Xem nền tảng HSM và ký số Server; đối chiếu giải pháp HSM FPT trước khi chốt tích hợp.