WebAPI共通情報

WebAPI共通情報

• APIは全てHTTPS通信でアクセスします。
• 全てのAPIは、https://fss-app.yubion.com/api/以下に対してAPI名をパスとして指定する事で呼び出します。
• HTTPメソッドは全てPOSTでリクエストを行います。
• getNonceを除いた全てのAPIは、後述する共通HTTPヘッダの設定とヘッダでの認証情報の送付が必須となります。
• APIパラメータの送信・リクエスト結果の受信は全てJSON形式で行われます。
• 一部の連続して処理される必要があるリクエスト（FIDO認証の登録・認証処理）はCookieの保持が必要になります。

APIリクエスト時共通HTTPヘッダ

API認証方法

API認証方法は3種類の方法を提供しています。

署名認証（Nonce署名認証・日付署名認証）

シークレットキーが署名作成用の秘密鍵情報(ECDSA P-256、pkcs8形式の秘密鍵情報をBase64Urlエンコードしたもの)となっています。
その秘密鍵を用いて、以下の連結されたバイト列に対して署名を行います。

[ 認証形式ごとの署名対象データ ] || [ リクエストボディのSHA-256ハッシュ値 ]

• 「認証形式ごとの署名対象データ」は、以下のUTF-8文字列のバイト列です。

  • Nonce署名認証
    getNonceリクエストで取得したNonce文字列。この文字列をリクエストヘッダの「X-Fss-Auth-Nonce」に指定する必要があります。以下のような場合、API認証に失敗します。
    • FSSサーバーが発行していないNonce文字列を用いた場合
    • 既に使用したNonce文字列を用いた場合
    • 発効後、一定期間が経過したNonce文字列を用いた場合
  • 日付署名認証
    現在日時をISO8601形式で表した文字列。この文字列をリクエストヘッダの「X-Fss-Auth-Request-Time」に指定する必要があります。FSSサーバーの時刻と30秒以上の差がある場合、API認証に失敗します。

• 「リクエストボディのSHA-256ハッシュ値」は、リクエストボディのSHA-256ハッシュのバイト列です。リクエストヘッダの「X-Fss-Auth-Body-Hash」に、ハッシュ値をBase64Urlエンコードした文字列を指定する必要があります。

• 署名結果は、RとSを連結した64byteのRaw Format（P1363 Format）で出力し、それをBase64Urlエンコードした文字列をリクエストヘッダの「X-Fss-Auth-Signature」に指定します。

アクセスキー認証

• 発行されたシークレットキーをそのままリクエストヘッダの「X-Fss-Auth-Access-Key」に指定します。

API応答基本形式

全てのAPI応答の基本的な形式を解説します。

{
	appStatus : "OK",
	data : {
		...
	},
	message : "...",
	appSubStatus : {
		...
	},
}

API実行結果情報（ApplicationResultStatus）

ApplicationResultStatusは以下の値を取ります。

FIDO認証登録・認証処理時の詳細エラー情報

FIDO認証の登録・認証処理（registerCredential/xxx、authenticate/xxx）でエラーが発生した際は、appSubStatus内にerrorCodeプロパティが設定される事があります。

{
	appStatus : "PARAMETER_ERROR",
	message : "...",
	appSubStatus : {
		errorCode : "",
		...
	},
}

このerrorCodeは以下の値を取ります。