Khoá ký và xoay vòng khoá

Khoá ký của ứng dụng là gì

Mỗi ứng dụng được tạo kèm một cặp khoá Ed25519 riêng:

• Nửa bí mật chỉ nằm trên server, được mã hoá khi lưu (phương pháp Mã hoá khi lưu) và không bao giờ hiện trong dashboard. Server dùng nó để ký mọi câu trả lời gửi về phần mềm, kể cả câu trả lời lỗi, cùng token offline và manifest cập nhật.
• Nửa công khai là thứ bạn nhúng vào phần mềm. Nó chỉ xác minh được, không ký được gì, nên phát hành kèm bản build là an toàn.

Mỗi khoá công khai có một mã nhận diện kid: 16 ký tự hex đầu của SHA-256 khoá công khai. Theo giao thức CLV1.1, mỗi câu trả lời mang kid của khoá đã ký trong header x-clavis-kid; token offline và manifest cập nhật cũng mang kid. SDK tra kid trong danh sách khoá mà bản build tin tưởng: không thấy thì từ chối với mã unknown_key, thấy nhưng chữ ký không khớp thì từ chối với invalid_response_signature. Nhờ kid, một bản build có thể tin nhiều khoá cùng lúc, và đó là nền tảng của việc xoay vòng khoá. Chuỗi được ký và quy tắc xác minh nằm ở đặc tả giao thức.

Lấy khoá công khai ở đâu

Khoá công khai hiện ở ba chỗ, chỗ nào cũng có nút sao chép:

• Trang Tổng quan trong khối mang tên ứng dụng, thẻ Khoá công khai, cạnh App ID. Chỉ hiện khoá đang ký.
• Tích hợp › Kết nối phần mềm: cài đặt cho phần mềm và dự án mẫu tải về đã điền sẵn khoá công khai bằng khoá đang ký.
• Bảo mật ứng dụng › Bảo vệ, tab Phương pháp, bảng Khoá ký. Bảng này chỉ hiện ở Bảo vệ Advanced. Đây là nơi đầy đủ nhất, mỗi khoá hiện kèm kid và một dòng ghi chú.

Dưới bảng là dòng Danh sách khoá cho bản build kế tiếp, dán vào ClavisClient và một khối mã tiêu đề ClavisClient. Khối này liệt kê mọi khoá đang hiện (hiện tại, kế tiếp, trước đó) theo đúng định dạng appPublicKeys; bấm nút sao chép ở góc khối là dán thẳng được vào mã nguồn.

Mọi thành viên workspace đều xem và sao chép được khoá. Chuẩn bị, kích hoạt và huỷ khoá cần vai trò Quản trị hoặc Chủ sở hữu; vai trò Thành viên bấm vào sẽ nhận thông báo lỗi.

Nhúng khoá vào phần mềm

ClavisClient nhận khoá qua một trong hai trường, hoặc cả hai (SDK gộp chúng lại thành một danh sách):

• appPublicKey: một khoá duy nhất, đúng như khoá ở trang Kết nối phần mềm.
• appPublicKeys: danh sách { kid, key }. kid là tuỳ chọn, thiếu thì SDK tự tính từ khoá.

Thiếu cả hai, constructor ném lỗi ClavisClient needs appPublicKey or appPublicKeys. Bạn nên dùng appPublicKeys ngay từ đầu, để mỗi lần xoay khoá chỉ là dán lại một khối mã:

import { ClavisClient, hashComponent } from "@clavisauh/sdk";

const clavis = new ClavisClient({
  baseUrl: "https://api.example.com",
  appId: "app_…",
  // Dán nguyên khối từ bảng Khoá ký
  appPublicKeys: [
    { kid: "<kid hiện tại>", key: "<khoá công khai hiện tại>" },
    { kid: "<kid kế tiếp>", key: "<khoá công khai kế tiếp>" },
  ],
  device: { fingerprint: hashComponent(machineId) },
  deviceKey: await loadDeviceKey(),
});

Xoay vòng khoá qua hai bước

Nếu đổi khoá ngay lập tức, mọi bản build đã cài chỉ biết khoá cũ sẽ từ chối toàn bộ câu trả lời của server. Vì vậy việc xoay khoá được tách thành hai thao tác trong dashboard, với một lần phát hành ở giữa. Cạnh bảng Khoá ký có ba mốc tương ứng: Chuẩn bị, Phát hành bản mới, Kích hoạt.

Bước 1: Chuẩn bị khoá mới

1. Mở Bảo mật ứng dụng › Bảo vệ, tab Phương pháp, rồi kéo xuống bảng Khoá ký. Ở Bảo vệ Standard, hãy bật Bảo vệ Advanced trước.
2. Ở mốc Chuẩn bị, bấm Chuẩn bị khoá mới.
3. Dòng Kế tiếp xuất hiện với kid mới, và khối ClavisClient giờ chứa cả khoá hiện tại lẫn khoá kế tiếp.

Lúc này chưa có gì thay đổi với phần mềm: server vẫn ký bằng khoá hiện tại. Mỗi ứng dụng chỉ có tối đa một khoá kế tiếp, nên nút Chuẩn bị khoá mới ẩn đi cho tới khi bạn kích hoạt hoặc huỷ khoá đó.

Bước 2: Phát hành bản build mang cả hai khoá

Sao chép khối ClavisClient, thay appPublicKeys trong mã nguồn, build và phát hành. Bản build này tin cả khoá cũ lẫn khoá mới, nên chạy bình thường cả trước và sau khi kích hoạt. Bạn có thể phân phối nó qua bản phát hành có ký.

Sau đó hãy chờ tới khi phần lớn người dùng đã cập nhật. Dashboard không đếm giúp bạn còn bao nhiêu máy chạy bản cũ, nên thời điểm kích hoạt là quyết định của bạn.

Bước 3: Kích hoạt khoá mới

1. Trên dòng Kế tiếp, bấm Kích hoạt khoá mới.
2. Hộp thoại Kích hoạt khoá mới? nhắc lại hệ quả. Bấm Kích hoạt khoá mới để xác nhận, hoặc Để sau để dừng lại.

Ngay sau đó:

• Server ký mọi câu trả lời, token offline và manifest cập nhật bằng khoá mới. Thay đổi có hiệu lực gần như tức thì; khi API chạy nhiều instance, các instance còn lại bắt kịp trong khoảng 30 giây.
• Khoá cũ chuyển xuống dòng Trước đó, với ngày còn được tin tới là 14 ngày sau.
• Trang Tổng quan và Kết nối phần mềm hiện khoá mới.
• Bản build chỉ có khoá cũ nhận unknown_key ở mọi yêu cầu.

Không có thao tác quay lại: sau khi kích hoạt, server chỉ giữ nửa công khai của khoá cũ, nửa bí mật không còn. Nếu cần đổi tiếp, bạn chuẩn bị một khoá khác và làm lại từ bước 1.

Thời gian ân hạn 14 ngày

Trong 14 ngày sau khi kích hoạt, khoá cũ vẫn nằm trong bảng và trong khối ClavisClient. Server không ký gì bằng nó nữa; mục đích là để bản build bạn phát hành trong khoảng này vẫn tin khoá cũ, và nhờ đó chấp nhận token offline mà khoá cũ đã ký trước lúc đổi. Hết 14 ngày, dòng Trước đó biến mất và khối mã chỉ còn khoá hiện tại (cùng khoá kế tiếp nếu có).

Nếu bạn kích hoạt thêm một lần nữa trước khi hết 14 ngày, khoá vừa bị thay trở thành Trước đó, còn khoá cũ hơn rời khỏi danh sách ngay.

Huỷ khoá đã chuẩn bị

Bấm Huỷ khoá này trên dòng Kế tiếp khi khoá đã chuẩn bị không còn cần, ví dụ bạn đổi ý và chưa phát hành bản build nào mang nó. Thao tác chạy ngay, không có hộp thoại xác nhận, và không khôi phục được vì nửa bí mật bị xoá. Khoá hiện tại không bị ảnh hưởng.

Nếu đã lỡ phát hành bản build chứa khoá vừa huỷ, bản build đó vẫn chạy bình thường vì nó còn tin khoá hiện tại. Nhưng lần chuẩn bị sau sẽ tạo một khoá khác, nên bạn phải phát hành lại một bản build mang khoá mới đó trước khi kích hoạt.

Nhắc lịch xoay khoá

Xoay khoá ký nằm trong nhóm Khoá và bản phát hành của Bảo vệ Advanced, cùng tab Phương pháp. Bật công tắc, rồi đặt Xoay mỗi từ 30 đến 730 ngày; giá trị được lưu khi bạn rời ô nhập. Giá trị mặc định là 180 ngày. Liên kết Khoá ký cạnh ô nhập đưa bạn xuống thẳng bảng khoá.

Khi công tắc bật, góc trên bảng Khoá ký hiện Đến hạn xoay kèm ngày đến hạn: ngày khoá hiện tại bắt đầu ký (lần kích hoạt gần nhất, hoặc ngày tạo ứng dụng nếu chưa xoay lần nào) cộng số ngày đã đặt. Qua ngày đó, dòng chữ đổi thành Đã quá hạn xoay với màu cảnh báo.

Xử lý khoá lạ trong phần mềm

Bản build cũ gặp khoá nó không biết sẽ nhận ClavisVerificationError với mã unknown_key. Vì không có câu trả lời nào xác minh được, phần mềm không thể đọc link tải hay thông báo từ server, nên hãy xử lý mã này bằng nội dung có sẵn trong bản build:

import { ClavisVerificationError } from "@clavisauh/sdk";

try {
  await clavis.init();
} catch (err) {
  if (err instanceof ClavisVerificationError && err.code === "unknown_key") {
    // Bản build này không còn tin khoá server đang dùng
    showMessage("Vui lòng tải phiên bản mới nhất từ trang của chúng tôi.");
    return;
  }
  throw err;
}

Lưu ý thêm

• Token offline: bản build chỉ có khoá mới sẽ từ chối token ký bằng khoá cũ, và người dùng cần lên mạng một lần để nhận token mới. Xem License offline.
• Client tự viết: chỉ CLV1.1 (header x-clavis-proto: 1.1) mang kid. Client theo CLV1 gốc nhận câu trả lời không có kid, nên hãy nâng lên CLV1.1 trước khi xoay khoá.
• Mã lỗi khi gọi API dashboard trực tiếp: chuẩn bị khi đã có khoá kế tiếp trả next_key_exists; kích hoạt khi chưa chuẩn bị trả no_next_key. Giao diện đã ẩn nút trong hai trường hợp này.
• 2FA: nếu ứng dụng bật Bắt buộc MFA cho team, bạn cần có 2FA hoặc passkey trên tài khoản của mình mới làm việc được với ứng dụng đó, kể cả xem bảng Khoá ký. Xem Bảo mật tài khoản dashboard.

Liên quan

• Hai chế độ bảo vệ
• Bản phát hành có ký và cập nhật
• License offline
• SDK JavaScript