> For the complete documentation index, see [llms.txt](https://docs.metasleuth.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.metasleuth.io/ja/blocksec-aml-api/introduction/request-signing.md).

# Request Signing

Request Signing は API シークレットでリクエストを検証します。API キーは API アクセスを識別し、シークレットは署名の生成に使用します。シークレット自体をリクエストで送信してはいけません。

Address Label API と Risk Score API は個別の API キーとシークレットを使用します。呼び出すサービスの認証情報を使用してください。

## Request Signing の有効化

設定、ローテーション、無効化の完全な手順は [API Security Settings](https://docs.metasleuth.io/ja/blocksec-aml-api/introduction/api-security-settings.md) を参照してください。

1. [Settings → APIs → API Keys](https://metasleuth.io/system/settings/personal/apis) を開き、対象の API の **Security Settings** を開きます。
2. **Request Signing** を選択し、API シークレットを生成します。一度しか表示されないため、コピーして安全に保管してください。
3. 署名を必須にする時刻を選び、**Save Changes** を選択します。
   * **In 24 hours**：移行期間にアプリケーションの更新とテストを行います。新しいシークレットは保存後に使用可能です。表示された必須化時刻までは、他のアクセスルールの下で署名なしのリクエストも受け付けられます。
   * **Immediately**：保存後のすべてのリクエストに有効な署名が必要です。アプリケーションの準備を完了してください。
4. 以下の手順で署名付きリクエストを送信します。Security Settings に表示された必須化時刻までに全アプリケーションを更新してください。

移行期間中も無効な署名は拒否されます。IP Allowlist も有効な場合は、送信元 IP が許可され、かつ署名が有効である必要があります。テストは実際の業務 API リクエストであり、クォータを消費する場合があります。専用のテストシークレットや署名検証エンドポイントはありません。

## リクエストヘッダー

| ヘッダー          | 値                                     |
| ------------- | ------------------------------------- |
| `Api-Key`     | 対象サービスの API キー                        |
| `X-Timestamp` | 現在の Unix タイムスタンプ（秒）                   |
| `X-Nonce`     | リクエストごとに新しく生成する、ランダムで一意の値（最大 256 バイト） |
| `X-Signature` | `v1=` に続く小文字の 16 進数の HMAC-SHA256 署名   |

タイムスタンプとサーバー時刻の差は **5 分以内**である必要があります。システム時計を同期し、再試行ごとに新しいタイムスタンプ、nonce、署名を生成してください。

API キーとシークレットはサーバー側コードのみで使用してください。環境変数やシークレット管理サービスから読み込み、ソース管理にコミットしたり、ブラウザーやモバイルアプリのバンドルに含めたりしないでください。

証明書検証を有効にした HTTPS を使用してください。Request Signing はリクエストを認証しますが、内容を暗号化しません。認証情報を URL やクエリパラメーターに含めないでください。ログ、トレース、スクリーンショット、サポート添付資料では、API キー、シークレット、署名ヘッダー、機密のリクエスト/応答データをマスキングしてください。

## 正規化文字列の構築

次の 6 フィールドを単一の改行文字（`\n`）で連結します。末尾に改行を追加しないでください。

```
METHOD
PATH
SORTED_QUERY_STRING
BODY_SHA256
TIMESTAMP
NONCE
```

* **METHOD**：`GET` や `POST` などの大文字の HTTP メソッド。
* **PATH**：サービスプレフィックスを含む完全な URL パス。スキーム、ホスト、クエリ文字列は含めません。例：`/address-compliance/api/v3/risk-score`。`/risk-score` だけでは検証に失敗します。
* **SORTED\_QUERY\_STRING**：以下の規則で正規化したクエリ文字列。パラメーターがない場合は空文字列を使用します。
* **BODY\_SHA256**：実際に送信するリクエストボディのバイト列の SHA-256 ハッシュ（小文字の 16 進数）。ボディが空の場合は空のバイト列をハッシュします。
* **TIMESTAMP** と **NONCE**：リクエストヘッダーで送信するものと同じ値。

ボディを一度だけシリアライズし、そのバイト列をハッシュして、そのまま送信します。署名後に JSON の空白を変更すると署名は無効になります。

### クエリパラメーターの正規化

1. 生のクエリ文字列を `&` で分割し、各ペアを最初の `=` で分割します。値がない場合は空文字列として扱います。
2. キーと値をデコードします。
3. デコード済みのキー、次に値を UTF-8 バイト順で並べ替えます。重複キーは保持します。
4. RFC 3986 のパーセントエンコードを各キーと値に適用します。`A–Z`、`a–z`、`0–9`、`-`、`_`、`.`、`~` のみエスケープしません。空白は `%20`、リテラルのプラス記号は `%2B` にします。
5. 各 `key=value` を `&` で連結し、先頭の `?` は付けません。

例：

```
Raw:        b=2&a=1&a=%20&c=x%3Dy
Normalized: a=%20&a=1&b=2&c=x%3Dy
```

UTF-8 を使用します。クエリ値に生の `+` を使わず、空白は `%20`、リテラルのプラスは `%2B` にしてください。`flag` と `flag=` はどちらも `flag=` に正規化されます。

### 署名の計算

```
X-Signature = "v1=" + hex_lowercase(
    HMAC-SHA256(secret_utf8_bytes, canonical_string_utf8_bytes)
)
```

表示されたシークレット値の UTF-8 バイト列を使用します。16 進数や Base64 としてデコードしないでください。

## Python の例

この例は Risk Score API のサポート対象チェーンのエンドポイントを呼び出します。`MS_API_KEY` と `MS_API_SECRET` に Risk Score の認証情報を設定してください。本番の HTTPS エンドポイントを使用します。承認されたテスト環境には別の認証情報を使用し、本番の認証情報を信頼できないホストに送信しないでください。

```python
import hashlib
import hmac
import os
import time
import uuid
from urllib.parse import parse_qsl, quote, urlencode, urlsplit
from urllib.error import HTTPError
from urllib.request import HTTPRedirectHandler, Request, build_opener


def normalize_query(raw_query):
    pairs = parse_qsl(raw_query, keep_blank_values=True,
                      encoding="utf-8", errors="strict")
    pairs.sort(key=lambda p: (p[0].encode("utf-8"), p[1].encode("utf-8")))
    return urlencode(pairs, quote_via=quote, safe="-_.~")


class NoRedirect(HTTPRedirectHandler):
    def redirect_request(self, req, fp, code, msg, headers, newurl):
        raise HTTPError(req.full_url, code, "Redirect refused", headers, fp)


base = "https://aml.blocksec.com/address-compliance/api/v3"
url = base + "/chain-list"
method = "GET"
body = b""
parts = urlsplit(url)
timestamp = str(int(time.time()))
nonce = uuid.uuid4().hex
canonical = "\n".join([
    method,
    parts.path,
    normalize_query(parts.query),
    hashlib.sha256(body).hexdigest(),
    timestamp,
    nonce,
])
signature = "v1=" + hmac.new(
    os.environ["MS_API_SECRET"].encode("utf-8"),
    canonical.encode("utf-8"),
    hashlib.sha256,
).hexdigest()
request = Request(url, method=method, headers={
    "Api-Key": os.environ["MS_API_KEY"],
    "X-Timestamp": timestamp,
    "X-Nonce": nonce,
    "X-Signature": signature,
})
with build_opener(NoRedirect()).open(request, timeout=20) as response:
    print("HTTP status:", response.status)
    # Process response.read() in your application; avoid logging sensitive data.
```

JSON POST では、ペイロードを UTF-8 バイト列にシリアライズし、ボディハッシュに使用した同じバイト列を `data=body` として `Request` に渡します。`Content-Type: application/json` を設定してください。

リクエストパラメーターは [APIs](https://docs.metasleuth.io/ja/blocksec-aml-api/wallet-screening-api/apis.md) を参照してください。

## Node.js の例

Node.js 18 以降が必要です。Python の例と同じ Risk Score 環境変数を使用します。実際に送信する UTF-8 バイト列に署名します。

```javascript
import { createHash, createHmac, randomUUID } from 'node:crypto';

function encode(value) {
  return encodeURIComponent(value).replace(/[!'()*]/g, ch =>
    '%' + ch.charCodeAt(0).toString(16).toUpperCase());
}
function normalizeQuery(raw) {
  const pairs = [...new URLSearchParams(raw).entries()];
  pairs.sort((a, b) => Buffer.compare(Buffer.from(a[0]), Buffer.from(b[0]))
    || Buffer.compare(Buffer.from(a[1]), Buffer.from(b[1])));
  return pairs.map(([k, v]) => `${encode(k)}=${encode(v)}`).join('&');
}
const key = process.env.MS_API_KEY;
const secret = process.env.MS_API_SECRET;
if (!key || !secret) throw new Error('Set MS_API_KEY and MS_API_SECRET');
const base = 'https://aml.blocksec.com/address-compliance/api/v3';
const url = new URL(base + '/risk-score');
const method = 'POST';
const body = Buffer.from(JSON.stringify({
  chain_id: 1,
  address: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045',
  interaction_risk: false,
}), 'utf8');
const timestamp = Math.floor(Date.now() / 1000).toString();
const nonce = randomUUID();
const canonical = [method, url.pathname, normalizeQuery(url.search.slice(1)),
  createHash('sha256').update(body).digest('hex'), timestamp, nonce].join('\n');
const signature = 'v1=' + createHmac('sha256', Buffer.from(secret, 'utf8'))
  .update(canonical, 'utf8').digest('hex');
const response = await fetch(url, {
  method,
  headers: {
    'Content-Type': 'application/json',
    'Api-Key': key,
    'X-Timestamp': timestamp,
    'X-Nonce': nonce,
    'X-Signature': signature,
  },
  body,
  redirect: 'error',
});
console.log('HTTP status:', response.status);
// Process await response.json() in your application; avoid logging sensitive data.
```

どちらの例もリダイレクトを拒否します。リダイレクト先に認証情報や署名ヘッダーを転送しないでください。新しいリクエストを構築して署名する前に、意図した HTTPS ホストとパスを確認します。HTTP ステータスだけでは業務処理の成功を判断できません。[応答形式](https://docs.metasleuth.io/ja/blocksec-aml-api/introduction/response-format.md)に従って JSON の業務コードを確認してください。

## トラブルシューティング

| コード      | メッセージ                                       | 確認事項                                                                          |
| -------- | ------------------------------------------- | ----------------------------------------------------------------------------- |
| `401001` | Request signing is not configured           | 署名を設定し、この API サービスに使用可能なシークレットがあることを確認してください。                                 |
| `401002` | Invalid request signature                   | サービスの認証情報、全ヘッダー、完全なパス、メソッド、正規化クエリ、実際のボディのバイト列、nonce の長さ（最大 256 バイト）を確認してください。 |
| `401003` | Invalid request timestamp                   | Unix 秒を使用して時計を同期してください。サーバー時刻との差は 5 分以内である必要があります。                            |
| `401004` | Request has already been used               | 再試行ごとに新しい nonce と署名を生成してください。                                                 |
| `403002` | Request IP is not allowed                   | 有効な許可リストとアプリケーションのパブリック送信元 IP を照合してください。                                      |
| `500003` | Request signing verification is unavailable | 上限付きバックオフで、新しい nonce/署名を使って再試行してください。解決しない場合はサポートにお問い合わせください。                 |

完全な一覧と HTTP の扱いは[応答形式](https://docs.metasleuth.io/ja/blocksec-aml-api/introduction/response-format.md)を参照してください。

再試行が成功すると再び課金される場合があります。nonce はリプレイを防止しますが、重複課金は防ぎません。署名機能が無効でも、空でない署名ヘッダーを送ると検証が行われます。

## シークレットのローテーション

Security Settings で新しいシークレットを生成し、安全にコピーして保存し、古いシークレットの失効時刻を選択します。**Save Changes** で適用します。未保存のシークレットを生成しても現在のものは置き換わりません。

* **In 24 hours**：保存後、移行期間中は両方のシークレットが有効です。古いシークレットの失効前に全アプリケーションを更新してください。
* **Immediately**：保存後に古いシークレットは使用できなくなります。漏えいの疑いがある場合に選択してください。

API キーは変わりません。ローテーション中に次のローテーションは開始できません。古いシークレットの失効を待つか、早期に取り消してから再度ローテーションします。早期取り消しにより、そのシークレットで署名したリクエストは即座に拒否されます。
