Hướng dẫn cài đặt USB Token

✓

MobiFone CA — Đã xác nhận hoạt động
Driver mfca_v1.dll hoạt động ổn định với hệ thống ký số này.

📋 Thông tin kỹ thuật

Driver PKCS#11
Tên file	`mfca_v1.dll`
Đường dẫn Windows	`C:\Windows\System32\mfca_v1.dll`
Token label	`MobifoneCA Token v1.0`
PIN tối thiểu	8 ký tự số
Chip	Gemalto/SafeNet (eTPKCS11 không dùng được — phải dùng mfca_v1.dll)
Private key label	Rỗng — agent tìm theo cert ID (không dùng label)
Agent cần dùng	Agent 64-bit (port 8899)

📥 Cài đặt driver

1

Tải phần mềm MobiFone CA Token Manager

Truy cập trang MobiFone CA hoặc dùng CD đi kèm token. File cài đặt thường có tên MobifoneCA_TokenManager_Setup.exe

🌐 Trang MobiFone CA

2

Cài đặt Token Manager

Chạy file setup → Next → Next → Finish. Driver mfca_v1.dll tự động được cài vào System32.

3

Xác nhận driver đã cài

Mở Command Prompt, chạy lệnh sau:

dir "C:\Windows\System32\mfca_v1.dll"

Thấy file kích thước ~500KB là OK.

4

Cài agent ký số

Tải gói agent Windows từ trang này, giải nén vào C:\cks-win\

Cài Python 64-bit nếu chưa có (tick "Add to PATH").

:: Cài thư viện (chỉ lần đầu) C:\cks-win\INSTALL-CLIENT.bat

5

Chạy agent và ký

Cắm token → chạy agent → vào web ký số:

C:\cks-win\run-agent.bat :: Mở trình duyệt vào: :: https://vienthongdidong.vn/cnxcks/ky/

⚠️ Lỗi thường gặp & cách xử lý

Danh sách lỗi thường gặp

Không tìm thấy driver nào / mfca_v1.dll không trong danh sách quét

Driver chưa cài. Cài MobiFone CA Token Manager từ bước 1-2 ở trên. Sau đó quét lại.

Lỗi đọc chứng thư / Token không có chứng thư

Nhập sai PIN. PIN MobiFone là 8 chữ số (không phải 1234). Nhập sai 5 lần liên tiếp sẽ bị khóa — liên hệ MobiFone CA để mở khóa.

Slots: 0 / Không tìm thấy token

Token chưa cắm, hoặc cổng USB lỗi. Rút ra cắm lại cổng khác. Chờ 5 giây rồi quét lại.

Failed to fetch / Agent chưa chạy

Chưa chạy run-agent.bat trên máy này. Chạy xong mới vào web ký.

Lưu ý PIN: Token MobiFone mặc định là 12345678. Nên đổi PIN sau lần đăng nhập đầu tiên trong Token Manager để bảo mật.

⚠️

VNPT-CA (ePass2003) — Cần cài thêm driver PKCS#11
Token Manager đi kèm (Electron app) KHÔNG có driver PKCS#11. Cần xin file engnsp11.dll từ VNPT-CA.

📋 Thông tin kỹ thuật

Thông tin token
Chip	Feitian ePass2003 (CCID)
Reader	SecureMetric ST3Ace
ATR	`3b:9f:95:81:31:fe:9f:00:66:46:53:05:10:52:39:71:df:00:00:32:00:00:4a`
Driver PKCS#11 cần	`engnsp11.dll` (Feitian middleware)
Đường dẫn sau khi cài	`C:\Windows\System32\engnsp11.dll`
Token Manager đi kèm	VNPT-CA Token Manager (Electron — KHÔNG có PKCS#11)
OpenSC nhận được không	Nhận dạng chip nhưng chưa đọc được cert
Agent cần dùng	Agent 64-bit (port 8899)

📥 Cách lấy driver engnsp11.dll

1

Thử tải Driver Token v8 từ VNPT-CA

Link tải trực tiếp (có thể hết hạn):

⬇ Driver Token v8 (VNPT-CA)

Sau khi cài, kiểm tra:

dir "C:\Windows\System32\engnsp11.dll"

2

Nếu không có — Liên hệ VNPT-CA trực tiếp

Email yêu cầu file engnsp11.dll hoặc PKCS#11 middleware cho ePass2003:

Hotline: 1800 1260 (miễn phí) Email: hotrovnptca@vnpt.vn Nội dung: "Cần file engnsp11.dll cho token ePass2003 để tích hợp ký số PKCS#11"

3

Sau khi có engnsp11.dll

Copy file vào C:\Windows\System32\, cài agent, quét driver → tự tìm thấy.

:: Kiểm tra sau khi cài dir "C:\Windows\System32\engnsp11.dll" :: Chạy agent và ký bình thường C:\cks-win\run-agent.bat

🔍 Chẩn đoán token (đã cắm)

?

Kiểm tra Windows có nhận token không

certutil -scinfo

Tìm dòng ePass2003, VNPT-CA Ace và SecureMetric ST3Ace → Windows đã nhận token.

Lưu ý quan trọng: Chứng thư VNPT-CA ePass2003 cần gia hạn định kỳ. Token Manager hiển thị ngày hết hạn — đảm bảo cert còn hiệu lực trước khi ký.

✓

Viettel-CA — Đã xác nhận hoạt động (dùng Agent 32-bit)
Driver viettel-ca_v4.dll hoạt động với Python 32-bit. Phải chạy AGENT RIÊNG 32-bit (port 8898).

⚠️

Quan trọng: Driver Viettel là file DLL 32-bit. Agent thông thường (64-bit) KHÔNG load được. Phải dùng CHAY-AGENT-VIETTEL.bat thay vì run-agent.bat.

📋 Thông tin kỹ thuật

Driver PKCS#11
File driver (hoạt động)	`viettel-ca_v4.dll` ← dùng cái này
Đường dẫn đầy đủ	`C:\Program Files (x86)\Viettel-CA Token Agent v1.0\viettel-ca_v4.dll`
Kiến trúc DLL	32-bit (i686) — không load được bằng Python 64-bit
Token label	`dvs`
Python cần dùng	Python 3.12 (32-bit) — `py -3.12-32`
Agent port	8898 (khác agent chính 8899)
Cert còn hiệu lực	Chứng thư SHA2 hết hạn 2027-04-13
Có bao nhiêu cert	5 cert (nhiều cert cũ hết hạn — agent tự chọn cert mới nhất)
Thư mục cài đặt	`C:\Program Files (x86)\Viettel-CA Token Agent v1.0\`

📥 Cài đặt

1

Cài Viettel-CA Token Agent

Tải từ CD đi kèm hoặc từ trang Viettel CA:

🌐 ca.viettel.vn

Sau khi cài, kiểm tra thư mục:

dir "C:\Program Files (x86)\Viettel-CA Token Agent v1.0\viettel-ca_v*.dll"

Thấy 4 file: v2, v4, v5, v6 là đúng. Chỉ dùng v4.

2

Cài Python 32-bit (bắt buộc)

Tải Python 32-bit — chọn đúng file python-3.12.x.exe (không phải amd64):

⬇ Python 3.12 (32-bit)

Sau khi cài, xác nhận:

py -3.12-32 -c "import struct; print(struct.calcsize('P')*8, 'bit')" :: Phải in ra: 32 bit

3

Cài thư viện Python cho agent Viettel

:: Cài cryptography (binary, không cần OpenSSL) py -3.12-32 -m pip install cryptography --only-binary :all: :: Cài pyhanko và các thư viện khác py -3.12-32 -m pip install pyhanko pyhanko-certvalidator flask python-pkcs11 pypdfium2 pillow asn1crypto

4

Chạy agent Viettel (32-bit)

Cắm token Viettel → chạy file bat riêng (KHÔNG dùng run-agent.bat):

C:\cks-win\CHAY-AGENT-VIETTEL.bat :: Cửa sổ hiện: "Agent Viettel-CA 32-bit tại http://127.0.0.1:8898"

5

Vào web ký — quét driver sẽ thấy Viettel

Vào vienthongdidong.vn/cnxcks/ky/ → Bước 1 → Quét driver tự động

Sẽ thấy: Viettel-CA [Viettel 32-bit] với dấu ● Có token

Chọn driver đó → Bước 2 nhập PIN → ký bình thường.

⚠️ Lỗi thường gặp & cách xử lý

Danh sách lỗi

%1 is not a valid Win32 application

DLL 32-bit được load bởi Python 64-bit. Phải dùng CHAY-AGENT-VIETTEL.bat (Python 32-bit).

Chua co Python 32-bit

Cài Python 32-bit từ python.org — chọn đúng file .exe (không phải amd64).

ERROR: Failed building wheel for cryptography

Dùng flag --only-binary :all: khi cài:
py -3.12-32 -m pip install cryptography --only-binary :all:

Lỗi đọc chứng thư khi đổi sang MobiFone sau khi ký Viettel

Bấm nút "↺ Đổi token / driver" ở Bước 2 trên web. Web sẽ reset và quét lại driver — lần này chọn MobiFone (agent 64-bit, port 8899).

Slots: 0 / Không tìm thấy token Viettel

Thử tất cả 4 driver: v2, v4, v5, v6. Token của bạn dùng chip phiên bản nào thì driver đó mới nhận được.

Khi dùng cả 2 token: Có thể chạy cả 2 agent cùng lúc:
• run-agent.bat → port 8899 (MobiFone)
• CHAY-AGENT-VIETTEL.bat → port 8898 (Viettel)
Web tự detect và hiển thị cả 2 driver trong danh sách quét.

ℹ️

SafeNet eToken / Gemalto / Thales — Driver phổ biến, nhiều CA dùng
Dùng cho VNPT-CA bản cũ, FPT-CA, một số token Viettel.

📋 Thông tin kỹ thuật

Driver PKCS#11
File driver	`eTPKCS11.dll`
Đường dẫn 64-bit	`C:\Windows\System32\eTPKCS11.dll`
Đường dẫn 32-bit	`C:\Windows\SysWOW64\eTPKCS11.dll`
Phần mềm cài kèm	SafeNet Authentication Client (SAC)
Phiên bản khuyên dùng	SAC 10.8 GA Windows x64
Agent cần dùng	Agent 64-bit (port 8899)

📥 Cài đặt

1

Tải SafeNet Authentication Client

Tải từ nhà cung cấp token hoặc CA:

🌐 SafeNet Drivers (GlobalSign)

Chọn file SAC_10.8_GA_Win_x64.msi

2

Cài đặt và kiểm tra

dir "C:\Windows\System32\eTPKCS11.dll" :: Thấy file ~2MB là OK

3

Chạy agent và ký

C:\cks-win\run-agent.bat

Vào web → Quét driver → thấy SafeNet eToken → chọn → nhập PIN.

ℹ️

OpenSC — Driver mã nguồn mở, dùng khi không có driver chính hãng
Hỗ trợ nhiều loại chip nhưng một số token (VNPT-CA ePass2003) vẫn không đọc được.

📋 Thông tin kỹ thuật

Driver PKCS#11
File driver	`opensc-pkcs11.dll`
Đường dẫn Windows	`C:\Program Files\OpenSC Project\OpenSC\pkcs11\opensc-pkcs11.dll`
Linux	`/usr/lib/x86_64-linux-gnu/pkcs11/opensc-pkcs11.so`
macOS	`/Library/OpenSC/lib/opensc-pkcs11.so`
Phiên bản tốt nhất	0.25.x trở lên
Chip hỗ trợ	ePass2003, ACOS5, Athena, Gemalto, nhiều loại khác

📥 Cài đặt

1

Tải và cài OpenSC

⬇ OpenSC Releases (GitHub)

Chọn file OpenSC-X.Y.Z_win64.msi

Linux: sudo apt install opensc hoặc sudo yum install opensc

macOS: brew install opensc

2

Cấu hình cho ePass2003 (VNPT-CA)

Mở file C:\Program Files\OpenSC Project\OpenSC\opensc.conf bằng Notepad (Run as Administrator), thêm:

app default { card_drivers = epass2003, default; force_card_driver = epass2003; } app opensc-pkcs11 { card_drivers = epass2003, default; force_card_driver = epass2003; }

Rút token → cắm lại → thử lại.

3

Kiểm tra OpenSC đọc được token chưa

"C:\Program Files\OpenSC Project\OpenSC\tools\opensc-tool.exe" --reader 1 --name :: Nếu in ra "epass2003" là OpenSC nhận chip :: Nếu in ra "token not recognized" cần driver chính hãng

4

Nhập thủ công vào web nếu quét không thấy

Vào Bước 1 → ô "Nhập đường dẫn driver thủ công" → điền:

C:\Program Files\OpenSC Project\OpenSC\pkcs11\opensc-pkcs11.dll

Bấm Thêm → Quét lại.

Lỗi thường gặp với OpenSC

token not recognized

OpenSC thấy chip nhưng chưa có profile. Thêm force_card_driver vào opensc.conf như bước 2. Nếu vẫn lỗi → cần driver chính hãng của CA.

CKR_TOKEN_NOT_RECOGNIZED (0xe1)

Firmware token khác với chuẩn OpenSC hỗ trợ. Liên hệ nhà cung cấp CA để lấy middleware PKCS#11 chính hãng.