poieti/developers
院方端點

簽章驗證

X-Poieti-Signature 的計算、驗證與測試向量。

本頁內容與 contracts/his v1.0.0 及 Poieti 伺服器實作一致。

格式#

標頭
X-Poieti-Signature: t=1792136580,v1=cbd3d789…a6cd[,v1=<前一把金鑰>]
計算方式
stringToSign = "poieti-his/1\n" + t + "\n" + METHOD + "\n" + target + "\n" + rawBody
v1 = hex(HMAC-SHA256(key = 簽章金鑰的 ASCII 文字, stringToSign))
項目說明
tUnix 秒
METHOD大寫 HTTP 方法
target相對於 base URL 的路徑與查詢字串:去掉 base 路徑(不含結尾斜線);例如 base https://his.example.org/poieti/v1、網址 …/poieti/v1/census/wards/8B → /census/wards/8B
rawBody收到的原始位元組(Poieti 的 POST 內容為標準化 JSON;GET 為空字串)
金鑰簽章金鑰的 ASCII 文字(43 個 base64url 字元),不是解碼後的位元組

驗證#

  1. 解析 t 與一或兩個 v1(格式不符即拒絕)。
  2. |現在 − t| > 300 秒即拒絕。
  3. 以收到的原始內容計算 stringToSign,對手上的每一把金鑰(目前與前一把)計算 HMAC。
  4. 以常數時間比較;任一 v1 符合任一金鑰即接受。
  5. 拒絕時回 401,不寫入任何資料。
verify.mjs
import { createHmac, timingSafeEqual } from "node:crypto";

export function verify(header, keys, method, target, rawBody, now = Date.now() / 1000) {
  const m = /^t=(\d{1,12}),v1=([0-9a-f]{64})(?:,v1=([0-9a-f]{64}))?$/.exec(header ?? "");
  if (!m || Math.abs(now - Number(m[1])) > 300) return false;
  const message = Buffer.concat([
    Buffer.from(`poieti-his/1\n${m[1]}\n${method}\n${target}\n`), rawBody]);
  let ok = false;
  for (const key of keys) {
    const expected = createHmac("sha256", key).update(message).digest();
    for (const v of [m[2], m[3]].filter(Boolean))
      ok = timingSafeEqual(expected, Buffer.from(v, "hex")) || ok;
  }
  return ok;
}

測試向量#

以下向量取自 signature-vectors.json:金鑰 current、previous(輪替)與 alert(告警)。實作需重現每個簽章,並對驗證向量得到相同結果。

名稱方法與 targett金鑰X-Poieti-Signature
push-deliveryPOST /deliveries1792136580currentt=1792136580,v1=cbd3d789b548dde62f2a1983ca27d630064d90fa754bd922e847ef57fd23a6cd
push-delivery-rotationPOST /deliveries1792136580current + previoust=1792136580,v1=cbd3d789b548dde62f2a1983ca27d630064d90fa754bd922e847ef57fd23a6cd,v1=42d802a38f90f30f014707d4c7712a35536bf98312307739a667f638f71f49c1
push-delivery-statusGET /deliveries/3d2c1b0a-9f8e-4d7c-8b6a-5f4e3d2c1b0a1792136580currentt=1792136580,v1=ce2fbc610ae4ac770606c90bde1083d6f7c6dd727b10375b9dfd3d84eaf3feb8
push-healthGET /health1792136580currentt=1792136580,v1=913309a2def1d4598a4f1110678650f3d633799157f831dac370155cf2041542
push-censusGET /census/wards/8B1792136580currentt=1792136580,v1=9b5840736987a9cf1c4edd5262cec25211a59d4e4e40d73d6b4b038cd341577c
push-patient-searchPOST /patients/search1792136580currentt=1792136580,v1=b5fee6047e7749e66c92bd1f27e57dcd59dd1d5e4e25095d2258dac37fdf0de5
alert-webhookPOST /services/T0000/B0000/XXXXXXXX?channel=his-alerts1792136580alertt=1792136580,v1=89f94e4592877f398c2e36c939606efab603ea4b8a200e606092d838d0e0dfaa
名稱now持有金鑰預期原因
accept-current-key1792136879current + previous接受—
accept-rotation-previous-key1792136590previous接受—
reject-stale1792136881current拒絕timestamp
reject-future1792136279current拒絕timestamp
reject-replayed-path1792136585current拒絕signature
reject-tampered-body1792136585current拒絕signature
reject-unknown-key1792136585previous拒絕signature
reject-malformed1792136585current拒絕format

告警 webhook#

告警 webhook 以同樣方式簽署,使用告警簽章金鑰,target 為 webhook 網址的路徑與查詢字串(見向量 alert-webhook)。

Poieti · HIS 介接contracts/his v1.0.0

搜尋文件

OpenAPI 契約 3.1