API Key

API key của Fystack sử dụng HMAC secret hoặc cặp khóa client Ed25519 để ký yêu cầu. Trang này hướng dẫn cách lấy đúng vật liệu khóa cho từng lược đồ ký. Xem Xác thực API để biết cách hoạt động của việc ký.

HMAC Secret

Bạn không cần tạo khóa. Khi bạn tạo API key từ dashboard mà không đăng ký khóa công khai, Fystack sẽ tạo secret cho bạn và chỉ hiển thị một lần, dưới dạng chuỗi mã hóa hex. Cách này dễ thiết lập hơn cặp khóa client, nhưng secret là thông tin xác thực dạng văn bản thuần mà ứng dụng của bạn phải lưu giữ, hãy ưu tiên Client Key Pair bên dưới khi có thể.

import { FystackSDK, Environment } from '@fystack/sdk'

const sdk = new FystackSDK({
  credentials: {
    apiKey: 'YOUR_API_KEY',
    apiSecret: 'YOUR_API_SECRET'
  },
  workspaceId: 'YOUR_WORKSPACE_ID',
  environment: Environment.Production
})

Client Key Pair

Với lược đồ Ed25519, khóa riêng tư không bao giờ rời khỏi tiến trình của bạn, chỉ có khóa công khai PEM tương ứng được đăng ký với Fystack khi bạn tạo API key từ dashboard. Hãy tạo cặp khóa bằng công cụ phù hợp với hệ thống của bạn, sau đó dán khóa công khai vào dashboard.

Sử dụng SDK

Nếu bạn dùng @fystack/sdk, hãy truyền một signer vào credentials thay vì khóa thô, SDK sẽ tự xây dựng chuỗi chuẩn hóa và ký từng yêu cầu cho bạn. Sử dụng LocalPrivateKeySigner cho khóa PEM trong tiến trình, hoặc AwsKmsSigner khi khóa riêng tư nằm trong AWS KMS:

import { FystackSDK, LocalPrivateKeySigner, Environment } from '@fystack/sdk'

const sdk = new FystackSDK({
  credentials: {
    apiKey: 'YOUR_API_KEY',
    signer: new LocalPrivateKeySigner('-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----')
  },
  workspaceId: 'YOUR_WORKSPACE_ID',
  environment: Environment.Production
})

AwsKmsSigner yêu cầu cài đặt @aws-sdk/client-kms (được tải lười), hoặc truyền một client đã cấu hình sẵn qua client thay vì clientConfig. clientConfig được truyền trực tiếp vào new KMSClient(...), vì vậy nó khác nhau giữa phát triển cục bộ với LocalStack/ministack và môi trường production:

import { FystackSDK, AwsKmsSigner, Environment } from '@fystack/sdk'

const sdk = new FystackSDK({
  credentials: {
    apiKey: API_KEY,
    signer: new AwsKmsSigner({
      keyId: 'alias/signer',
      clientConfig: {
        region: 'ap-southeast-1',
        endpoint: 'http://localhost:4566',
        credentials: { accessKeyId: 'test', secretAccessKey: 'test' }
      }
    })
  },
  environment: Environment.Production,
  debug: true
})

import { FystackSDK, AwsKmsSigner, Environment } from '@fystack/sdk'

const sdk = new FystackSDK({
  credentials: {
    apiKey: API_KEY,
    // Drop endpoint and credentials, the KMS client picks up the
    // task/instance IAM role and the real region automatically.
    signer: new AwsKmsSigner({
      keyId: 'alias/signer',
      clientConfig: { region: 'ap-southeast-1' }
    })
  },
  environment: Environment.Production,
  debug: true
})

Không dùng Node.js? Xem Ký Ed25519 để ký trực tiếp chuỗi chuẩn hóa, với cả khóa PEM cục bộ và AWS KMS, bằng Go, Python, PHP và Java.

Tạo cặp khóa bằng OpenSSL

openssl genpkey -algorithm ed25519 -out private.pem
openssl pkey -in private.pem -pubout -out public.pem

Dán nội dung của public.pem vào dashboard khi tạo API key, và giữ private.pem để ký, truyền nó vào SDK dưới dạng new LocalPrivateKeySigner(privateKeyPem).

Tạo cặp khóa bằng AWS KMS

AWS KMS hỗ trợ Ed25519 làm khóa ký bất đối xứng (ECC_NIST_EDWARDS25519). Tạo khóa, sau đó xuất phần khóa công khai:

KEY_ID=$(awslocal kms create-key \
  --key-spec ECC_NIST_EDWARDS25519 --key-usage SIGN_VERIFY \
  --query KeyMetadata.KeyId --output text)
echo "$KEY_ID"

get-public-key đã trả về khóa dưới dạng DER mã hóa base64 (SubjectPublicKeyInfo), chính là nội dung mà một khóa công khai PEM bao bọc, nên không cần chuyển qua openssl để định dạng lại. Chỉ cần bọc kết quả base64 bằng các header PEM:

{
  echo "-----BEGIN PUBLIC KEY-----"
  awslocal kms get-public-key --key-id alias/signer \
    --query PublicKey --output text
  echo "-----END PUBLIC KEY-----"
} > pub.pem

Cách tương đương nhưng dài hơn (giải mã sang DER, rồi để openssl mã hóa lại thành PEM) cũng tạo ra tệp giống hệt:

awslocal kms get-public-key --key-id alias/signer \
  --query PublicKey --output text | base64 -d > pub.der
openssl pkey -pubin -inform DER -in pub.der -out pub.pem

Dù theo cách nào, bạn cũng sẽ có:

-----BEGIN PUBLIC KEY-----
MCowBQYDK2VwAyEAKZ0GCR0MBIQGZowZI/1xmWjXlBy09I98JC6Tgn0l0L4=
-----END PUBLIC KEY-----

Dán nội dung đó vào dashboard làm khóa công khai của key. Khóa riêng tư vẫn nằm trong KMS, sử dụng new AwsKmsSigner({ keyId: 'alias/signer' }) như trên để ký yêu cầu, KMS không bao giờ để lộ vật liệu khóa riêng tư.