院方端點
簽章驗證
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))| 項目 | 說明 |
|---|---|
t | Unix 秒 |
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 字元),不是解碼後的位元組 |
驗證#
- 解析
t與一或兩個v1(格式不符即拒絕)。 |現在 − t| > 300秒即拒絕。- 以收到的原始內容計算 stringToSign,對手上的每一把金鑰(目前與前一把)計算 HMAC。
- 以常數時間比較;任一
v1符合任一金鑰即接受。 - 拒絕時回 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;
}Verify.cs (.NET 6+)
using System.Linq;
using System.Security.Cryptography;
using System.Text;
using System.Text.RegularExpressions;
static bool Verify(string header, string[] keys, string method, string target, byte[] rawBody)
{
var m = Regex.Match(header ?? "", "^t=([0-9]{1,12}),v1=([0-9a-f]{64})(?:,v1=([0-9a-f]{64}))?$");
if (!m.Success) return false;
var t = long.Parse(m.Groups[1].Value);
if (Math.Abs(DateTimeOffset.UtcNow.ToUnixTimeSeconds() - t) > 300) return false;
var prefix = Encoding.UTF8.GetBytes($"poieti-his/1\n{t}\n{method}\n{target}\n");
var message = prefix.Concat(rawBody).ToArray();
var ok = false;
foreach (var key in keys)
{
using var hmac = new HMACSHA256(Encoding.ASCII.GetBytes(key));
var expected = hmac.ComputeHash(message);
foreach (var g in new[] { m.Groups[2], m.Groups[3] })
if (g.Success)
ok |= CryptographicOperations.FixedTimeEquals(expected, Convert.FromHexString(g.Value));
}
return ok;
}測試向量#
以下向量取自 signature-vectors.json:金鑰 current、previous(輪替)與 alert(告警)。實作需重現每個簽章,並對驗證向量得到相同結果。
| 名稱 | 方法與 target | t | 金鑰 | X-Poieti-Signature |
|---|---|---|---|---|
push-delivery | POST /deliveries | 1792136580 | current | t=1792136580,v1=cbd3d789b548dde62f2a1983ca27d630064d90fa754bd922e847ef57fd23a6cd |
push-delivery-rotation | POST /deliveries | 1792136580 | current + previous | t=1792136580,v1=cbd3d789b548dde62f2a1983ca27d630064d90fa754bd922e847ef57fd23a6cd,v1=42d802a38f90f30f014707d4c7712a35536bf98312307739a667f638f71f49c1 |
push-delivery-status | GET /deliveries/3d2c1b0a-9f8e-4d7c-8b6a-5f4e3d2c1b0a | 1792136580 | current | t=1792136580,v1=ce2fbc610ae4ac770606c90bde1083d6f7c6dd727b10375b9dfd3d84eaf3feb8 |
push-health | GET /health | 1792136580 | current | t=1792136580,v1=913309a2def1d4598a4f1110678650f3d633799157f831dac370155cf2041542 |
push-census | GET /census/wards/8B | 1792136580 | current | t=1792136580,v1=9b5840736987a9cf1c4edd5262cec25211a59d4e4e40d73d6b4b038cd341577c |
push-patient-search | POST /patients/search | 1792136580 | current | t=1792136580,v1=b5fee6047e7749e66c92bd1f27e57dcd59dd1d5e4e25095d2258dac37fdf0de5 |
alert-webhook | POST /services/T0000/B0000/XXXXXXXX?channel=his-alerts | 1792136580 | alert | t=1792136580,v1=89f94e4592877f398c2e36c939606efab603ea4b8a200e606092d838d0e0dfaa |
| 名稱 | now | 持有金鑰 | 預期 | 原因 |
|---|---|---|---|---|
accept-current-key | 1792136879 | current + previous | 接受 | — |
accept-rotation-previous-key | 1792136590 | previous | 接受 | — |
reject-stale | 1792136881 | current | 拒絕 | timestamp |
reject-future | 1792136279 | current | 拒絕 | timestamp |
reject-replayed-path | 1792136585 | current | 拒絕 | signature |
reject-tampered-body | 1792136585 | current | 拒絕 | signature |
reject-unknown-key | 1792136585 | previous | 拒絕 | signature |
reject-malformed | 1792136585 | current | 拒絕 | format |
告警 webhook#
告警 webhook 以同樣方式簽署,使用告警簽章金鑰,target 為 webhook 網址的路徑與查詢字串(見向量 alert-webhook)。