Cài đặt và sử dụng

Kích hoạt plugin

Vào Settings → Plugin Manager, bật @digiforce-nc/plugin-field-encryption. Plugin đăng ký field type encryption và các hook mã hóa tự động.

Thêm field Encryption

1. Mở Collection Manager → chọn collection.
2. Thêm field mới → chọn interface Encryption.
3. Đặt tên field (ví dụ: ssn, bankAccount, secretNote).
4. Lưu — field sẽ tự động mã hóa khi ghi và giải mã khi đọc.

const ssnField = {
  name: 'ssn',
  type: 'encryption',
  interface: 'encryption',
  uiSchema: {
    type: 'string',
    title: 'Số CCCD',
    'x-component': 'InputEncryption',
  },
};

Hành vi AES mã hóa

Plugin sử dụng thuật toán AES (Advanced Encryption Standard):

Bước	Mô tả
Ghi dữ liệu	Hooks beforeCreate / beforeUpdate tự động encrypt plaintext thành ciphertext trước khi lưu
Đọc dữ liệu	Hook afterFind tự động decrypt ciphertext thành plaintext trước khi trả về client
Lưu trữ DB	Cột dạng TEXT chứa ciphertext — không đọc được khi truy vấn trực tiếp DB

Toàn bộ quá trình transparent với application — người dùng nhập/xem plaintext bình thường, mã hóa xảy ra tự động ở tầng server.

Truy vấn dữ liệu mã hóa

Sử dụng custom operators để so sánh giá trị mã hóa:

const result = await repository.find({
  filter: {
    ssn: { $encryptionEq: '001234567890' },
  },
});

Operator	Mô tả
$encryptionEq	So sánh bằng — encrypt giá trị cần tìm rồi so với ciphertext trong DB
$encryptionNe	So sánh khác — ngược lại

Giao diện người dùng

Widget	Chức năng
InputEncryptionFieldWidget	Ô nhập liệu — người dùng nhập plaintext
DisplayEncryptionFieldWidget	Hiển thị — giá trị đã giải mã từ server

Lưu ý

• Dữ liệu trong database là ciphertext — nếu mất encryption key, không thể khôi phục plaintext.
• Mỗi field có thể có encryption key riêng (xem Technical Reference).
• Custom operators chỉ hỗ trợ so sánh chính xác, không hỗ trợ tìm kiếm mờ (LIKE).
• Khác với Mask (chỉ che trên UI), Encryption mã hóa thực sự trong database.