Web Authentication API 9章 WebAuthn拡張機能の日本語訳

W3CのWebAuthnの仕様書の9章拡張機能について書かれている部分について、読んだので残しておく。

前にWeb Authentication API 7章 Relying Party処理の日本語訳 - s1r-Jの技術ブログについては日本語訳した。

9 WebAuthn拡張機能

公開鍵クレデンシャルを生成する機構は、認証アサーションの要求・生成と同じく5章 Web Authentication APIで定義されており、特定のユースケースに沿うように拡張することができる。それぞれのケースは 登録拡張機能 （ registration extension ）およびまたは 認証拡張機能 （ authentication extension ）を定義することで対応されている。

すべての拡張機能は クライアント拡張機能 （ client extension ）であり、つまり拡張機能はクライアントと通信し、クライアントによって処理される。クライアント拡張機能は以下のステップとデータを定義している：

navigator.credentials.create()拡張機能　登録拡張機能のためのリクエストパラメータとレスポンス値
navigator.credentials.get()拡張機能　認証拡張機能のためのリクエストパラメータとレスポンス値
登録拡張機能および認証拡張機能に対するクライアント拡張機能の処理

公開鍵クレデンシャルの生成または認証アサーションの要求の際、WebAuthnリライングパーティは一連の拡張機能の利用を要求することができる。これらの拡張機能はクライアントおよびまたはWebAuthn認証器によってサポートされている場合、要求処理中に呼び出される。リライングパーティは、get()（認証拡張機能のため）の呼び出し中またはcreate()（登録拡張機能のため）の呼び出し中に、各拡張機能のためのクライアント拡張機能インプットをクライアントに送る。クライアントは、クライアントプラットフォームがサポートする各拡張機能に対してクライアント拡張機能処理を実行し、拡張機能識別子およびクライアント拡張機能アウトプット値を含めた各拡張機能で定義されているクライアントデータを拡張します。

また、拡張機能は 認証拡張機能 （ authenticator extension ）でもあり、つまり拡張機能は認証器と通信し、認証器によって処理される。認証拡張機能は以下のステップとデータを定義している：

authenticatorMakeCredential 拡張機能　登録拡張機能のためのリクエストパラメータとレスポンス値
authenticatorGetAssertion 拡張機能　認証拡張機能のためのリクエストパラメータとレスポンス値
登録拡張機能および認証拡張機能に対する認証器拡張機能の処理

認証器拡張機能に対して、認証器拡張機能処理の一部としてクライアントも各拡張機能のためのCBOR 認証器拡張機能インプット値（しばしば対応しているクライアント拡張機能インプット値に基づいて）を作成し、get()（認証拡張機能のため）の呼び出し中またはcreate()（登録拡張機能のため）の呼び出し中に認証機にそれらを受け渡す。これら認証器拡張機能インプット値はCBORで表され、ネーム・バリューのペアで受け渡される。拡張機能識別子はネームとして、対応する認証器拡張機能インプットはバリューとして扱われる。次に、認証器はサポートしている拡張機能にたいして追加の処理をおこない、格納機能によって定義されるCBOR 認証器拡張機能アウトプットを返す。認証器拡張機能に対するクライアント拡張機能処理の一部は、クライアント拡張機能アウトプットを作成する入力値として認証器拡張機能アウトプットを利用する。

すべてのWebAuthn拡張機能はクライアントおよび認証器にとってOPTIONALである。つまり、リライングパーティから要求されたいかなる拡張機能でもクライアントブラウザまたはOSによって無視されたり、認証器に渡されなかったりすることがあり（MAY）、また認証器によって無視されることがある（MAY）。拡張機能を無視することはWebAuthn APIの処理では失敗として扱われることは決してなく、リライングパーティがどのAPI呼び出しでも拡張機能を含めたときでも、一部もしくは全ての拡張機能が無視されるケースについてハンドリングする準備しなければならない（MUST)。

可能なかぎり多くの拡張機能にサポートしたいクライアントは、認識できない拡張機能を認証器に渡すことを選んでもよく（MAY）、シンプルにクライアント拡張機能インプットをCBORにエンコードした認証器拡張機能インプットを生成する。すべてのWebAuthn拡張機能はこの実装選択がユーザのセキュリティやプライバシーを危険に晒さない方法で定義されていなければならない（MUST)。例えば、クライアント処理を要求する拡張機能の場合、意味のない認証器拡張機能インプット値を生成するようなナイーブな受け渡しを保証するような方法で定義されると、結果としてその拡張機能は認証器によって無視される。すべての拡張機能はOPTIONALであることから、API処理中の機能的失敗を発生させることはない。同様にクライアントは、CBOR出力がJSONだけに存在する型を使用する場合、認証器拡張機能アウトプット値をJSONにエンコードしたことで解釈できない拡張機能のクライアント拡張機能アウトプット値の処理を選ぶことができる。

クライアントは認識できない拡張機能を受け渡すと選択したとき、クライアント拡張機能インプットのJavaScriptの値を認証器拡張機能インプットのCBORの値に変換する。JavaScriptの値が%ArrayBuffer%の場合、CBOR byte arrayに変換される。JavaScriptの値が非整数値の場合、64ビットCBOR浮動小数点数に変換される。一方、JSONの型に対応したJavaScriptの型の場合、変換は[RFC8949]の6.2節（JSONからCBORへの変換）で定義されているルールに従って実施されますが、JSONの型の値のインプットに対してではなくJavaScriptの型の値のインプットに処理をおこないます。これらの変換が実施された場合、変換結果のCBORの正規化はCTAP2 カノニカルCBORエンコード形式を使って実行しなければならない（MUST）。

JavaScriptの数値変換ルールは、クライアントが認識していない拡張機能を受け渡すときに拡張機能が浮動小数点数を利用していた場合、認証器はCBOR整数としてそれらの値を受け取る準備が必要であり、認証器は実際のクライアントの助けなしに常に動作すべきということに注意する。これは使われている浮動小数点数がたまたま整数である場合に発生する。

同様に、クライアントが認識していない拡張機能からアウトプットを受け取ったとき、認証器拡張機能アウトプットのCBORの値はクライアント拡張機能アウトプットのJavaScriptの値に変換される。CBORの値はバイト文字列のとき、JavaScript %ArrayBuffer%（base64urlエンコードされた文字列ではなく）に変換される。一方、CBORの型はJSONの型に対応しているとき、変換は[RFC8949]の6.1節（CBORからJSONへの変換）に定義されているルールに従って実施されるが、JSONの型の値ではなくJavaScriptの型の値のアウトプットが生成される。

一部のクライアントは機能フラグのもとでこの受け渡し機能を実装することを選択する可能性があることに注意する。認証器が新しい拡張機能を実験することを許可し、クライアントで明示的にサポートする前にリライングパーティがそれらを利用できるようになり、この機能をサポートすることでイノベーションを促進する。

[RFC8809]によって設立されたIANA「WebAuthn Extension Identifiers」レジストリ [IANA-WebAuthn-Registries] は登録済WebAuthn拡張機能の最新のリストについて協議する。

9.1 拡張機能識別子

拡張機能は、拡張機能の作成者が決定した 拡張機能識別子 （ extension identifier ）と呼ばれる文字列によって識別されています。

拡張機能識別子は、[RFC8809]によって設立されたIANA 「WebAuthn Extension Identifiers」レジストリ [IANA-WebAuthn-Registries]に登録すべきである（SHOULD）。当然ではあるが登録されている拡張機能識別子はユニークである。

すべての拡張機能識別子は最大32オクテット長でなければならず（MUST）、バックスラッシュおよびダブルクォート、つまり%x22および%x5cを除いた[RFC5234]で定義されているVCHARを除く印字可能USASCII文字だけで構成されなければならない（MUST）。実装はケースセンシティブにWebAuthn拡張機能識別子に一致しなければならない（MUST）。

複数のバージョンが存在する可能性がある拡張機能は、それらの識別子にバージョンが含まれていることに注意するべきである。実際、つまり異なるバージョンは異なる拡張機能として扱われる。例：myCompany_extension_01

10章定義済拡張機能は追加の拡張機能および拡張機能識別子の一覧を定義する。登録済のWebAuthn拡張機能識別子の最新リストのための[RFC8809]によって設立されたIANA 「WebAuthn拡張機能識別子」レジストリ [IANA-WebAuthn-Registries]を参照する。

9.2 拡張機能の定義

拡張機能の定義では、拡張機能識別子、get()またはcreate()を介して送られたクライアント拡張機能インプット引数、クライアント拡張機能処理のルール、そしてクライアント拡張機能アウトプットを定義する。認証器と連携する拡張機能（つまり認証器拡張機能）の場合、authenticatorGetAssertionまたはauthenticatorMakeCredentialの呼び出しによってCBOR 認証器拡張機能インプット引数、認証器拡張機能処理のルールおよびCBOR 認証器拡張機能アウトプットの値も定義しなければならない（MUST）。

クライアントによって処理されたすべてのクライアント拡張機能はクライアント拡張機能アウトプットを返却しなればならず（MUST）、WebAuthnリライングパーティはクライアントによって利用された拡張機能を知ることになる。同じように、認証器での処理を必須とするすべての拡張機能は、リライングパーティが認証器によって利用された拡張機能を知るために認証器拡張機能アウトプットを返却しなければならない（MUST）。拡張機能が如何なる結果の値も必須としない場合、JSON Boolean クライアント拡張機能アウトプットの結果をその拡張機能が理解されて処理されたことを知らせるためにtrueをセットして返却するように定義すべきである（SHOULD）。同様に如何なる結果の値も必須としない認証器拡張機能は値を返却しなくてはならず（MUST）、CBOR Boolean 認証器拡張機能アウトプットの結果をその拡張機能が理解されて処理されたことを知らせるためにtrueをセットして返すべきである（SHOULD）。

9.3 リクエストパラメータの拡張

拡張機能は1つか2つのリクエスト引数を定義する。値がJSONにエンコードされている クライアント拡張機能インプット （ client extension input ）は、get()またはcreate()の呼び出しにおいてWebAuthnリライングパーティからクライアントに渡され、一方で 認証器拡張機能 （ authenticator extension input ）向けのCBOR形式の認証器拡張機能インプットはそれらの呼び出し時にクライアントから認証器に渡される。

リライングパーティは同時に拡張機能の利用を要求し、create()またはget()の呼び出しに対してextensionsのオプションにエントリを含めることでそのクライアント拡張機能インプットをセットする。

注意：他のドキュメントでは、拡張機能インプットがエントリキーとして拡張機能識別子を常に利用しているとは限らないと定義していた。新しい拡張機能には上述の変換に従うべきである（SHOULD）。

EXAMPLE 10

var assertionPromise = navigator.credentials.get({
    publicKey: {
        // Other members omitted for brevity
        extensions: {
            // An "entry key" identifying the "webauthnExample_foobar" extension, 
            // whose value is a map with two input parameters:
            "webauthnExample_foobar": {
              foo: 42,
              bar: "barfoo"
            }
        }
    }
});

拡張機能の定義は、クライアント拡張機能インプットとして正当な値を定義しなくてはならない（MUST）。クライアントは不正なクライアント拡張機能インプットを持つ拡張機能を無視すべきである（SHOULD）。拡張機能がリライングパーティからのパラメータを一切必要としない場合、リライングパーティから要求された拡張機能が処理されたことを示すためにtrueを設定するBoolean型のクライアント引数を取るように定義すべきである（SHOULD）。

クライアントでの処理に対してだけ影響する拡張機能は、認証器拡張機能インプットを定義する必要がない。認証器で処理をおこなう拡張機能は、クライアント拡張機能インプットから認証器拡張機能インプットの算出方法を定義しなければならず（MUST）、AuthenticationExtensionsAuthenticatorInputsおよびAuthenticationExtensionsAuthenticatorOutputsのCDDLを、エントリキーとして拡張機能識別子を利用して$$extensionInputおよび$$extensionOutput グループソケットに対する追加選択を定義することで定義しなければならない（MUST)。インプットパラメータを必須としない、つまりBoolean型のクライアント拡張機能インプットの値をtrueに設定する拡張機能は、認証器拡張機能インプットもBoolean値true(CBOR major type 7, value 21)として定義するべきである（SHOULD）。

以下の例では、識別子 WebauthnExample_foobarを持つ拡張機能が認証器拡張機能インプットとして符号なし整数を取り、認証器拡張機能アウトプットとして最小1バイト列の配列を返すことを定義している：

EXAMPLE 11

$$extensionInput //= (
  webauthnExample_foobar: uint
)
$$extensionOutput //= (
  webauthnExample_foobar: [+ bytes]
)

注意：拡張機能は認証器引数をできる限り小さくなることを目指して定義すべきである。一部の認証器はBluetooth Low-EnergyやNFCのような低帯域接続による通信をおこなっている。

9.4 クライアント拡張機能処理

拡張機能は、クレデンシャルの作成またはアサーションの生成のあいだにクライアントでの追加処理の要求を定義しているかもしれない（MAY）。拡張機能に対するクライアント拡張機能インプットはクライアント処理に対する入力として利用される。サポートされている各クライアント拡張機能に対し、クライアントは clientExtensions mapに対して拡張機能識別子をキー、クライアント拡張機能インプットをバリューとして拡張機能のエントリを追加する。

同様に、クライアント拡張機能アウトプットは、拡張機能識別子をキー、各拡張機能の クライアント拡張機能アウトプット （ client extension output ）の値をバリューとしてgetClientExtensionResults()の結果のディクショナリとして表現される。クライアント拡張機能インプットと同じく、クライアント拡張機能アウトプットはJSONにエンコードされた値である。無視した拡張機能に対しては如何なる値も返却してはならない（MUST NOT）。

認証器処理を必須とする拡張機能は、CBOR 認証器拡張機能インプットを決定するためのクライアント拡張機能インプットを利用する処理およびクライアント拡張機能アウトプットを決定するためのCBOR 認証器拡張機能インプットを利用する処理を定義しなければならない（MUST）。

9.5 認証器拡張機能処理

処理された各認証器拡張機能のCBOR 認証器拡張機能インプットの値は、authenticatorMakeCredentialおよびauthenticatorGetAssertionの処理の拡張機能パラメータに含まれる。拡張機能パラメータは各キーが拡張機能識別子で対応する値が認証器拡張機能インプットとなっているCBORマップである。

同様に、拡張機能アウトプットはauthenticator dataのextensions部分に表記されている。authenticator dataのextensions部分は、各キーが拡張機能識別子で対応する値が 認証器拡張機能アウトプット （ authenticator extension output ）となっているCBORマップである。

サポートされている各拡張機能に対し、認証器拡張機能処理ルールは認証器拡張機能インプットから認証器拡張機能アウトプットを生成するために利用され、その他入力値に対しても可能な限り同様である。無視する拡張機能に対しては如何なる値も返却してはならない（MUST NOT）。