検証可能なクレデンシャルのレンダリング方法 v1.0

概要

本仕様は、検証可能なクレデンシャル・データモデルのための拡張機構について説明するものであり、視覚、聴覚、または触覚の媒体を通じて検証可能なクレデンシャルを表現するために使用できます。本仕様は、検証可能なクレデンシャルを物理文書、デジタル画像、スクリーンリーダー、または点字出力へレンダリングすることを扱います。

レンダリング方法は、発行者が、視覚、聴覚、または触覚の仕組みを通じて検証可能なクレデンシャルを観察者に表現する特定の方法を有している場合に使用できます。たとえば、従業員バッジ・クレデンシャルの発行者は、企業ロゴの豊かな画像表現や、バッジ上の特定領域への従業員情報の具体的な配置を含めたいと考えるかもしれません。また、視覚に関連するアクセシビリティ上のニーズを持つ個人のために、バッジの重要な側面を音声で読み上げる機能を提供したいと考えるかもしれません。

以下の用語は、本仕様における概念を説明するために使用されます。

クレーム: 主体について行われる表明。
クレデンシャル: 発行者によって行われる、1つ以上のクレームの集合。クレデンシャル内のクレームは、異なる主体に関するものである場合があります。
本仕様におけるクレデンシャルの定義は、 NISTによる credentialの定義とは異なります。
データ最小化: タスクまたは目的を正常に達成するために必要な最小限の量に、共有されるデータの量を厳密に制限する行為。
分散識別子: DIDとしても知られる、URLベースの可搬な識別子であり、エンティティに関連付けられます。これらの識別子は、ほとんどの場合検証可能なクレデンシャルで使用され、主体に関連付けられるため、検証可能なクレデンシャル自体を、クレデンシャルを再発行する必要なく、あるクレデンシャル・リポジトリから別のものへ容易に移行できます。 DIDの例は、did:example:123456abcdefです。
分散識別子文書: DID文書とも呼ばれ、これは検証可能なデータレジストリを用いてアクセスできる文書であり、関連するクレデンシャル・リポジトリや公開鍵情報など、特定の分散識別子に関連する情報を含みます。
デフォルトグラフ: 名前付きグラフの明示的な一部ではない、すべてのクレームを含むグラフ。
導出述語: 検証可能なクレデンシャル内の別の属性の値に関する、検証可能なブール表明。これらは、情報の開示を制限できるため、ゼロ知識証明形式の検証可能な提示において有用です。たとえば、検証可能なクレデンシャルに、特定の身長をセンチメートル単位で表す属性が含まれている場合、導出述語は検証可能なクレデンシャル内の身長属性を参照し、具体的な身長の値を実際には開示せずに、その身長値が最小身長要件を満たすことを発行者が証明していることを示すことができます。たとえば、主体は150センチメートルより背が高い、というものです。
デジタル署名: デジタル・メッセージの真正性を示すための数学的方式。
エンティティ: 抽象名詞または具体名詞として文において参照できるあらゆるもの。エンティティには、人、組織、物理的なもの、文書、抽象概念、架空のキャラクター、任意のテキストなどが含まれますが、これらに限定されません。エンティティは、それが可能であれば、エコシステム内で役割を果たすことがあります。ただし、文字列「abc」はクレデンシャルを発行できないなど、根本的に行動を取れないエンティティもあることに注意してください。
グラフ: 主体と、それらが他の主体またはデータと持つ関係から構成される情報ネットワークを形成する、クレームの集合。各クレームはグラフの一部です。これは、名前付きグラフの場合は明示的であり、デフォルトグラフの場合は暗黙的です。
保持者: 1つ以上の検証可能なクレデンシャルを所持し、それらから検証可能な提示を生成することで、エンティティが果たし得る役割。保持者は多くの場合、ただし常にではありませんが、保持している検証可能なクレデンシャルの主体です。保持者は自身のクレデンシャルをクレデンシャル・リポジトリに保存します。
アイデンティティ: 複数の文脈をまたいでエンティティを追跡するための手段。デジタル・アイデンティティは、通常は識別子と属性を用いて、デジタル文脈全体にわたるエンティティの相互作用の追跡とカスタマイズを可能にします。アイデンティティ情報の意図しない配布または使用は、プライバシーを損なう可能性があります。そのような情報の収集および使用は、データ最小化の原則に従うべきです。
アイデンティティ・プロバイダー: アイデンティティ・プロバイダーは、IdPと略されることもあり、保持者のためにアイデンティティ情報を作成、維持、管理し、同時にフェデレーションまたは分散ネットワーク内のリライング・パーティ・アプリケーションへ認証サービスを提供するシステムです。この場合、保持者は常に主体です。たとえ検証可能なクレデンシャルがベアラークレデンシャルであっても、検証可能なクレデンシャルは主体のもとに留まるものと想定され、そうでない場合は、攻撃者によって盗まれたものと見なされます。本仕様では、他の仕様における概念と比較または対応付ける場合を除き、この用語を使用しません。本仕様では、アイデンティティ・プロバイダーの概念を、発行者と保持者という 2つの別個の概念に分離しています。
発行者: 1つ以上の主体についてクレームを表明し、これらのクレームから検証可能なクレデンシャルを作成し、その検証可能なクレデンシャルを保持者へ送信することで、エンティティが果たせる役割。
名前付きグラフ: verifiableCredentialなどの特定のプロパティに関連付けられたグラフ。これらのプロパティは、対応するJSONオブジェクトで定義されたすべてのクレームを含む、個別のグラフをもたらします。
提示: 1つ以上の発行者によって発行された、1つ以上の検証可能なクレデンシャルから導出され、特定の検証者と共有されるデータ。
クレデンシャル・リポジトリ: ストレージ・ボールトや個人用検証可能なクレデンシャルウォレットなどのプログラムであり、保持者の検証可能なクレデンシャルへのアクセスを保存し、保護します。
選択的開示: どの情報を共有するかについて、保持者がきめ細かく判断できる能力。
主体: クレームが行われる対象となるもの。
ユーザーエージェント: ブラウザーまたはその他のWebクライアントなどのプログラムであり、保持者、発行者、および検証者の間の通信を仲介します。
validation: 特定の発行者からのクレームが、特定の用途について検証者の業務上の要件を満たすという保証。本仕様は、検証者が検証可能なクレデンシャルおよび検証可能な提示をどのように検証するかを定義します。
また、本仕様は、検証者が検証可能なクレデンシャルに含まれるクレームに依拠する前に、それらを検証することも規定します。しかし、そのような検証の手段は大きく異なり、本仕様の範囲外です。検証者は、特定の発行者を特定のクレームについて信頼し、どのクレデンシャル内のどのクレームが自らのシステムで使用するのに適しているかを判断するために、独自の規則を適用することが期待されます。
検証可能なクレデンシャル: 検証可能なクレデンシャルは、著作者性を暗号学的に検証できる、改ざんが検出可能なクレデンシャルです。検証可能なクレデンシャルは、検証可能な提示を構築するために使用でき、それらも暗号学的に検証できます。
検証可能なデータレジストリ: 識別子、鍵、およびその他の関連データ、たとえば検証可能なクレデンシャルのスキーマ、失効レジストリ、発行者の公開鍵などの作成と検証を仲介することで、システムが果たし得る役割。これらは、検証可能なクレデンシャルを使用するために必要となる場合があります。一部の構成では、主体に対する相関可能な識別子が必要になる場合があります。UUIDや公開鍵のためのレジストリなど、一部のレジストリは識別子の名前空間として機能するだけの場合があります。
検証可能な提示: 検証可能な提示は、暗号学的検証の過程を経た後にデータの著作者性を信頼できるような方法で符号化された、改ざんが検出可能な提示です。特定の種類の検証可能な提示は、元の検証可能なクレデンシャルから合成されたデータを含む場合がありますが、元の検証可能なクレデンシャル自体は含みません（たとえば、ゼロ知識証明）。
検証: 検証可能なクレデンシャルまたは検証可能な提示が、それぞれ発行者または提示者による真正かつ現在有効な記述であるかどうかの評価。これには、クレデンシャル（または提示）が仕様に適合していること、証明方法が満たされていること、および存在する場合はステータス確認が成功することの確認が含まれます。クレデンシャルの検証は、クレデンシャルに符号化されたクレームの真偽の評価を意味するものではありません。
検証者: 1つ以上の検証可能なクレデンシャルを、任意で処理のための検証可能な提示の内部に含めて受け取ることで、エンティティが果たす役割。他の仕様では、この概念をリライング・パーティと呼ぶ場合があります。
検証材料: 暗号学的公開鍵、または証明を検証するために使用されるその他の任意のデータであり得る情報。
URL: [URL]で定義されるUniform Resource Locator。 URLは逆参照でき、その結果として文書などのリソースが得られます。URLを逆参照する、すなわち取得するための規則は、URLのスキームによって定義されます。本仕様では、URIまたはIRIという用語は使用しません。これらの用語はWeb開発者にとって混乱を招くものと判断されているためです。

非規範的と示されたセクションに加えて、本仕様に含まれるすべての作成ガイドライン、図、例、および注記は非規範的です。本仕様におけるその他すべては規範的です。

本文書におけるキーワードMAY、MUST、MUST NOT、OPTIONAL、RECOMMENDED、REQUIRED、およびSHOULDは、ここに示されているようにすべて大文字で現れる場合に限り、 BCP 14 [RFC2119] [RFC8174] に記述されているとおりに解釈されます。

適合レンダー方法とは、本仕様の規範的記述に準拠する、データモデルの任意の具体的表現です。具体的には、本書の 2. データモデルおよび2.2.4.2 アルゴリズムの各セクションに含まれる、関連するすべての規範的記述が MUSTとして強制されなければなりません。

適合プロセッサーとは、適合レンダー方法を生成または消費する、ソフトウェアおよび/またはハードウェアとして実現された任意のアルゴリズムです。適合プロセッサーは、非適合文書が消費された場合にエラーを生成 MUSTです。

本文書には、JSONおよびJSON-LDコンテンツを含む例も含まれています。これらの例の一部には、インラインコメント（//）や、省略を示すための省略記号（...）の使用など、無効なJSONとなる文字が含まれています。実装者は、その情報を有効なJSONまたは JSON-LDとして使用したい場合、このコンテンツを削除するよう注意してください。

以下のセクションでは、本仕様でレンダリング方法のために使用されるデータモデルの概要を示します

renderMethodプロパティは、Verifiable Credentials Data Model 仕様 [VC-DATA-MODEL-2.0] における予約済み拡張ポイントです。発行者は、検証可能なクレデンシャルにおいてこのプロパティを利用し、1つ以上の望ましいレンダリング方法を表現できます。

renderMethod: renderMethodプロパティの値は、視覚、聴覚、または触覚の仕組みを用いてソフトウェアが検証可能なクレデンシャルを表現するために使用できる、1つ以上のレンダリング方法を指定しなければMUSTなりません。各renderMethod値は、そのtype、たとえば TemplateRenderMethodを指定しなければMUSTなりません。各レンダリング・ヒントの正確な内容は、特定のrenderMethod type定義によって決定されます。

発行者が、検証可能なクレデンシャルに対してテンプレートに基づくレンダリング指示を指定したい場合、その発行者は以下で説明するデータモデルを使用するrenderMethodプロパティを追加してもよい MAYです。

プロパティ説明

id URL Standardに従い、取得されるとレンダリング・テンプレートに逆参照される、OPTIONALな文字列。

type 値がTemplateRenderMethodでなければMUSTならない、REQUIREDな文字列。

renderSuite 具体的なレンダリングの生成に使用されるアルゴリズムを識別する、 REQUIREDな文字列。

name 実行されるレンダリングの種類に関するヒントを提供するために表示できる、 OPTIONALな人間可読の文字列。このプロパティは、個人が複数の提示モードの中から選択できるグラフィカル・インターフェイスで使用される場合があります。

description 特定のレンダリングがどのような場合に有用であるかについて、nameよりも詳しい説明を提供する、OPTIONALな人間可読の文字列。

renderProperty この特定のレンダリング方法を使用する際に、検証可能なクレデンシャルからどのプロパティが公開されるかを指定する、 JavaScript Object Notation (JSON) Pointer構文にそれぞれ適合する文字列値の OPTIONALなリスト。 renderPropertyが提供されない場合、レンダリング方法が使用される際には検証可能なクレデンシャル全体が共有されるものと推定されます。

template

レンダリングを実行するために使用されるテンプレートを提供または参照する、 OPTIONALなURLまたはマップ。値がURLである場合、それはテンプレート・コードを含むdata: URL [RFC2397] であってもよい MAYです。値がマップである場合、それは次の規則に適合しなければMUSTなりません。

プロパティ	説明
id	URL Standardに従い、取得されるとSVGファイルやPDFファイルなどのテンプレートに逆参照される、 REQUIREDな文字列。
mediaType	Media Type Specifications and Registration Proceduresで指定される `id`値のメディアタイプを識別する、 RECOMMENDEDな文字列。
digestMultibase	テンプレート・ファイルのmultibase符号化されたMultihash。 multibase値は`u`（base64url-nopad）でなければならず MUST、multihash値は 256ビット出力のSHA-2（`0x12`）でなければMUST なりません。

digestMultibase idが指定されている場合に参照されるレンダリング方法の、 OPTIONALなmultibase符号化されたMultihash。 multibase値はu （base64url-nopad）でなければならずMUST、 multihash値は256ビット出力のSHA-2（0x12）でなければ MUSTなりません。

上記に示したデータモデルは、以下の例において検証可能なクレデンシャルで表現されています。

例 1: 発行者によるrenderプロパティの使用

{
  "@context": [
    "https://www.w3.org/ns/credentials/v2",
    "https://www.w3.org/ns/credentials/examples/v2",
    "https://w3id.org/vc/render-method/v1"
  ],
  "id": "http://example.edu/credentials/3732",
  "type": ["VerifiableCredential", "UniversityDegreeCredential"],
  "issuer": "https://example.edu/issuers/14",
  "validFrom": "2010-01-01T19:23:24Z",
  "credentialSubject": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "degree": {
      "type": "BachelorDegree",
      "name": "Bachelor of Science and Arts"
    }
  },
  "renderMethod": {
    "type": "TemplateRenderMethod",
    "renderSuite": "svg-mustache",
    "template": {
      "id": "https://example.edu/credential-templates/BachelorDegree",
      "mediaType": "image/svg+xml",
      "digestMultibase": "zQmerWC85Wg6wFl9znFCwYxApG270iEu5h6JqWAPdhyxz2dR",
      "renderProperty": [
        "/issuer", "/validFrom", "/credentialSubject/degree/name"
      ]
    }
  }
  
}

上の例では、発行者が、renderPropertyに列挙された検証可能なクレデンシャルからの特定の情報で埋められる、学士号用のMustacheベースのSVGレンダリング・テンプレートを提供しています。

svg-mustacheレンダースイートは、Mustacheテンプレート言語を使用して SVGファイルを変更し、それを用いて検証可能なクレデンシャルの視覚的表現をレンダリングします。

以下の例では、完全に埋め込まれたSVGファイルがレンダリング・テンプレートとして使用されています。

例 2: svg-mustacheレンダースイートの基本的な使用法

{
  ...
  "renderMethod": {
    "type": "TemplateRenderMethod",
    "renderSuite": "svg-mustache",
    // SVGファイルはVCに埋め込まれる
    "template": "data:image/svg+xml;base64,Qjei89...3jZpW"
  }
}

次の例では、Web上のSVGファイルへリンクし、digestMultibaseプロパティを使用することで変更から保護しています。

例 3: SVGレンダリング・テンプレート用のリモートホストSVGファイル

{
...
"renderMethod": {
  "type": "TemplateRenderMethod",
  "renderSuite": "svg-mustache",
  "template": {
    // このSVGファイルはWebから取得される
    "id": "https://degree.example/credential-templates/bachelors",
    "mediaType": "image/svg+xml",
    "digestMultibase": "zQmerWC85Wg6wFl9znFCwYxApG270iEu5h6JqWAPdhyxz2dR"
  }
}

次の例では、Web上のレンダリング・テンプレートへリンクし、digestMultibase プロパティを使用して保護しています。

例 4: リモートホストされたSVGレンダリング方法

{
...
"renderMethod": {
  // このレンダリング方法はWebから取得される
  "id": "https://degrees.example/bachelors-svg.jsonld",
  "mediaType": "application/ld+json",
  "type": "TemplateRenderMethod",
  "renderSuite": "svg-mustache",
  "digestMultibase": "zQmG270iEu5h6JqWAPdhyxz2dRerWC85Wg6wFl9znFCwYxAp"
}

pdf-mustacheレンダースイートは、Mustacheテンプレート言語を使用して PDFファイルを変更し、それを用いて検証可能なクレデンシャルの視覚的表現をレンダリングします。

以下の例では、完全に埋め込まれたPDFファイルがレンダリング・テンプレートとして使用されています。

例 5: pdf-mustacheレンダースイートの基本的な使用法

{
  ...
  "renderMethod": {
    "type": "TemplateRenderMethod",
    "renderSuite": "pdf-mustache",
    // このPDFファイルはVCに埋め込まれる
    "template": "data:application/pdf;base64,k309SK...pwK83b"
  }
}

次の例では、Web上のPDFファイルへリンクし、digestMultibaseプロパティを使用することで変更から保護しています。

例 6: PDFレンダリング・テンプレート用のリモートホストPDFファイル

{
...
"renderMethod": {
  "type": "TemplateRenderMethod",
  "renderSuite": "pdf-mustache",
  "template": {
    // このPDFファイルはWebから取得される
    "id": "https://degree.example/bachelors.pdf",
    "mediaType": "application/pdf",
    "digestMultibase": "zQmznFCwYxApG270iEu5h6JqWAPdhyxz2dRerWC85Wg6wFl9"
  }
}

次の例では、Web上のレンダリング・テンプレートへリンクし、digestMultibase プロパティを使用して保護しています。

例 7: リモートホストされたPDFレンダリング・テンプレート

{
...
"renderMethod": {
  // このレンダリング方法はWebから取得される
  "id": "https://degrees.example/bachelors-pdf.jsonld",
  "type": "TemplateRenderMethod",
  "renderSuite": "pdf-mustache",
  "digestMultibase": "zQmEu5h6JqWAPdhyxmz2dRerWC85Wg6wFl9znFCwYxApG270"
}

nfcレンダースイートは、検証可能なクレデンシャルを表すバイナリ・ペイロードを無線NFC接続を介して送信します。

以下の例では、完全に埋め込まれたNFCペイロードがレンダリング・テンプレートとして使用され、クレデンシャルに関連付けられたバーコード識別子のみを開示します。

例 8: nfcレンダースイートの使用

{
  ...
  "renderMethod": {
    "type": "TemplateRenderMethod",
    "renderSuite": "nfc",
    "name": "Tap to send",
    // NFCペイロードは埋め込まれる
    "template": "data:application/octet-stream;base64,2QZkpQGDG...G8XJWnROcY4Biw",
    // NFC上ではバーコードのみが送信される
    "renderProperty": ["/credentialSubject/barcode"]
  }
  ...
}

htmlレンダースイートは、テンプレート作成者が検証可能なクレデンシャルをレンダリングする HTMLテンプレートを提供できるようにします。このHTMLは、templateまたは template.id（templateの値がオブジェクトである場合）の値として、リモートで参照するかdata: URL経由で参照できます。HTMLフラグメント内のJavaScriptは、 HTMLテンプレートと並んでサンドボックス化されたiframe内にホストされる HTMLデータブロック（すなわち<script type="application/vc"></script>）を介して提供される、フィルタリング済みの検証可能なクレデンシャルデータをレンダリングする役割を担います。

例 9: HTMLレンダースイートを使用するVCの例

{
  "@context": [
    "https://www.w3.org/ns/credentials/v2",
    "https://www.w3.org/ns/credentials/examples/v2"
  ],
  "type": [
    "VerifiableCredential",
    "NameCredential"
  ],
  "issuer": {
    "id": "did:example:1234",
    "name": "The Issuer"
  },
  "credentialSubject": {
    "name": "Example Name",
    "notRendered": "should not appear"
  },
  "renderMethod": {
    "type": "TemplateRenderMethod",
    "renderSuite": "html",
    "renderProperty": [
      "/issuer/name",
      "/credentialSubject/name"
    ],
    "template": {
      "id": "https://test.example/credential-templates/NameCredential.html",
      "mediaType": "text/html",
      "digestMultibase": "zQmerWC85Wg6wFl9znFCwYxApG270iEu5h6JqWAPdhyxz2dR"
    },
    "outputPreference": {
      "mode": [
        "visual"
      ],
      "mediaType": "application/html",
      "style": {
        "width": "800px",
        "height": "800px"
      }
    }
  }
}

実装は、フィルタリング済みの検証可能なクレデンシャルデータを用いて、 JavaScriptがHTMLテンプレートを安全にレンダリングできる環境を提供しなければ MUSTなりません。この環境を説明するために、次の用語が使用されます。

ホストページ: HTMLテンプレートをレンダリングするための安全な環境を提供します。
テンプレートコード: Render Method内で提供される、またはリモートで参照されるHTMLフラグメント。
ラッパーコード: HTMLテンプレートを包み込み、追加のセキュリティ制限およびホストページとの通信を提供するコード。

少なくとも、この環境は、追跡およびその他のプライバシー上の害を防止するために、ナビゲーション、外部コンテンツの読み込み、およびホストページへのアクセスを防止しなければMUSTなりません。

たとえばブラウザー・ベースの実装では、ホストページ上のContent Security Policy [CSP3] 制限、 HTMLテンプレートをホストするiframeのサンドボックス化、および HTMLテンプレートを包み込んで追加のCSP制限を加え、ホストページとの readyおよびerrorイベント通信を提供するラッパーコードを組み合わせることで、そのような環境を提供できます。

ホストページ（通常はウォレットまたは検証可能なクレデンシャルレンダラー）は、 HTMLテンプレートがトップレベル閲覧コンテキストをナビゲートすること、外部コンテンツにアクセスすること、ホストページにアクセスすること、および任意のリモートコンテンツを読み込むことを防止しなければMUSTなりません。

ホストページが使用される場合、次の規則が適用されます。

Content Security Policy（CSP）制限には frame-src 'none'を含めなければMUSTなりません。これにより、iframeではsrcではなくsrcdocの使用が強制され、ブラウザーがHTMLテンプレートを読み込むことを防ぎます。その結果、ホストページのコードは、リモートで参照されるテンプレートコードを事前に読み込み、テンプレートをラッパーコードに注入する前に、関連するdigestMultibase値に対して応答を確認する必要があります。
HTMLテンプレートをホストするiframeには、ナビゲーションとトップレベルアクセスを防止するために sandbox="allow-scripts"を設定しなければ MUSTなりません。

例 10: 最小限のホストページ

<html>
  <head>
    <meta http-equiv="content-security-policy" content="frame-src 'none'">
  </head>
  <body>
    <iframe id="renderer" sandbox="allow-scripts allow-modals" srcdoc=""></iframe>
  </body>
</html>

renderMethod内のtemplateプロパティによって参照される HTMLテンプレートコードは、検証可能なクレデンシャルをレンダリングするために必要な HTML、CSS、およびJavaScriptを含むHTMLフラグメントでなければ MUSTなりません。テンプレートコードは、 <html>、<head>、または <body>タグを含めてはならずMUST NOT、これらはラッパーコードによって提供されます。

例 11: HTMLテンプレート・フラグメントの例

<div>
  <script>
    document.addEventListener('DOMContentLoaded', (event) => {
      console.log('running template render script');

      // credentialをJSONとして表示するレンダラー例。代わりに、
      // mustache/その他の形式のテンプレート処理など、表示用HTMLを
      // 生成する任意の処理をここで実行できる

      // FIXME: datablock/scriptタグの最適な名前/場所を決定する
      const credential = JSON.parse(document.querySelector(
        'head > script[name="credential"]').innerHTML);

      document.querySelector('#credentialSubject-name').innerText =
        credential.credentialSubject.name;
      document.querySelector('#issuer-name').innerText =
        credential.issuer.name;

      // TBD: レンダリング完了をホストへ通知する
      window.renderMethodReady();
    });
  </script>
  <style>
    h1 {
      color: blue;
    }
  </style>

  <h1 id="credentialSubject-name"></h1>
  <p>発行者: <span id="issuer-name"></span></p>
</div>

テンプレートHTMLフラグメントは、部分的な検証可能なクレデンシャルを含むデータブロックを提供し、ナビゲーションおよび外部コンテンツ読み込みを防止する追加のCSPポリシーを加えるラッパーコードで包み込まれなければ MUSTなりません。具体的には、ラッパーコードは、テンプレートコードによってネットワーク要求が行われることを防ぐために、 default-src data: 'unsafe-inline'というCSP制限を追加しなければ MUSTなりません。

例 12: iframe[srcdoc]内でテンプレートと credentialを包むラッパーコード

<html>
  <head>
    <meta http-equiv="content-security-policy" content="default-src data: 'unsafe-inline'">
    <script name="credential" type="application/vc">${JSON.stringify(credential)}</script>
  </head>
  <body>${template}</body>
</html>

セットアップを完了するために、ホストページは、（検証可能なクレデンシャルおよびテンプレートコードが設定された）ラッパーコードをiframeのsrcdoc属性に注入しなければ MUSTなりません。これにより、ラッパーコードおよびテンプレートコードに含まれる JavaScriptが実行されます。

例 13: テンプレートとCredentialを含む組み合わせ済みラッパーコード

<html>
  <head>
    <meta http-equiv="content-security-policy" content="default-src 'none' data: 'unsafe-inline'">

<!-- ラッパーコードに注入されるcredentialデータブロック。 -->
<script name="credential" type="application/vc">{
  "@context": [
    "https://www.w3.org/ns/credentials/v2",
    "https://www.w3.org/ns/credentials/examples/v2"
  ],
  "type": [
    "VerifiableCredential",
    "NameCredential"
  ],
  "issuer": {
    "id": "did:example:1234",
    "name": "The Issuer"
  },
  "credentialSubject": {
    "name": "Example Name"
  }
}</script>
<!-- credentialデータブロック終わり -->

</head>
<body>

<!-- ラッパーコードに注入されるテンプレートHTML。 -->
<div>
  <script>
    console.log('running template render script');

    // credentialをJSONとして表示するレンダラー例。代わりに、
    // mustache/その他の形式のテンプレート処理など、表示用HTMLを
    // 生成する任意の処理をここで実行できる

    // FIXME: datablock/scriptタグの最適な名前/場所を決定する
    const credential = JSON.parse(document.querySelector(
      'head > script[name="credential"]').innerHTML);

    document.querySelector('#credentialSubject-name').innerText =
      credential.credentialSubject.name;
    document.querySelector('#issuer-name').innerText =
      credential.issuer.name;

    // TBD: レンダリング完了をホストへ通知する
    window.renderMethodReady()
  </script>
  <style>
    h1 {
      color: blue;
    }
  </style>

  <h1 id="credentialSubject-name"></h1>
  <p>発行者: <span id="issuer-name"></span></p>
</div>
<!-- テンプレートHTML終わり -->

  </body>
</html>

ラッパーコード内で作成されるiframeは、レンダリングが完了したとき、またはレンダリング中にエラーが発生したときに、テンプレートがホストページへ通知できるようにする通信チャネルを提供しなければMUSTなりません。これは、ラッパーコードによって設定される MessageChannelとpostMessage APIを使用して実現できます。

以下に示すJavaScriptは、上記のホストページに追加され、 MessageChannelを設定するiframeのonloadイベントを追加します。ホストページはまた、ラッパーコードからreadyメッセージを受信したときに解決し、errorメッセージを受信したときに拒否する Promiseを作成します。ラッパーコードはまた、テンプレートがレンダリング完了をホストページへ通知したり、エラーメッセージを送り返したりするために使用するwindow.renderMethodReadyメソッドを提供します。

例 14: MessageChannelを設定するためのホストページへの追加

// レンダリングがreadyになったときに解決する（失敗した場合は拒否する）promise。
// 表示やエラー表示に使用できる
let resolveRender;
let rejectRender;
const readyPromise = new Promise((resolve, reject) => {
  resolveRender = resolve;
  rejectRender = reject;
});

// iframe内のテンプレートコードで使用する通信チャネルを設定する
renderer.onload = () => {
  // MessageChannelを作成し、1つのportをiframeへ転送する
  const channel = new MessageChannel();
  // iframeの読み込み中にメッセージが失われないよう、メッセージキューを開始する
  channel.port1.start();
  // `ready`メッセージを処理する
  channel.port1.onmessage = function ready(event) {
    if(event.data === 'ready') {
      // readyになったためiframeを表示する
      resolveRender();
    } else {
      rejectRender(new Error(event.data?.error?.message));
    }
    channel.port1.onmessage = undefined;
  };
  // "start"メッセージを送信し、戻り通信のために`port2`をiframeへ送る
  renderer.contentWindow.postMessage('start', '*', [channel.port2]);
};

// readyまたはerrorへのイベント応答を設定する
// NOTE: このセクションはウォレット/レンダラーのUXニーズに固有である
readyPromise.then(() => {
  console.log('rendering ready');
  const renderer = document.getElementById('renderer');
  renderer.hidden = false;
}).catch(err => {
  const errorMessage = document.getElementById('error-message');
  errorMessage.style.display = 'block';
  errorMessage.innerText = 'Rendering failed: ' + err.message;
  console.error('rendering failed', err);
});

例 15: MessageChannelに接続し `renderMethodReady`を作成するラッパーコードへの追加

// 親ウィンドウから通信portへ解決されるpromiseを
// 追加する
const portPromise = new Promise(resolve => {
  window.addEventListener('message', function start(event) {
    if(event.data === 'start' && event.ports?.[0]) {
      window.removeEventListener('message', start);
      resolve(event.ports[0]);
    }
  });
});

// テンプレートが「ready」になった（またはエラーが発生した）ときに呼び出す
// 関数をwindowに取り付ける。この関数は親へメッセージを送信し、
// 親がiframeを表示するかどうかを判断できるようにする
window.renderMethodReady = function(err) {
  portPromise.then(port => port.postMessage(
    !err ? 'ready' : {error: {message: err.message}}));
};

この設定により、テンプレートJavaScriptはwindow.renderMethodReady()を呼び出してレンダリングが完了したことをホストページへ通知したり、 window.renderMethodReady(new Error("error message"))を呼び出してエラーをホストページへ通知したりできます。

以下のセクションでは、HTMLテンプレートを安全にレンダリングするために htmlレンダースイートによって使用されるアルゴリズムの概要を示します。セキュリティおよびプライバシー上の結果、ならびに出力が同じである限り、代替アルゴリズムを使用してもよいMAYです。

ホストページは、HTMLテンプレートをホストする iframe要素を作成しなければMUSTなりません。ホストページは、ナビゲーションおよびトップレベルアクセスを防止するために、iframeのsandbox属性を allow-scriptsに設定しなければMUSTなりません。

vcを、レンダリングされる検証可能なクレデンシャルとする。
renderMethodを、vc内で選択された renderMethodプロパティであり、 renderMethod.typeがTemplateRenderMethod、 renderMethod.renderSuiteがhtmlであるものとする。
renderMethod.templateが文字列である場合、 templateを renderMethod.templateの値とする。
renderMethod.templateがマップである場合、 templateを renderMethod.template.id内のURLを取得した結果とする。

ホストページは、renderMethod.renderPropertyが存在する場合、検証可能なクレデンシャルvcを renderMethod.renderPropertyで指定されたプロパティのみを含むようにフィルタリングしなければMUSTなりません。 renderMethod.renderPropertyが存在しない場合、検証可能なクレデンシャル全体が使用されます。

このフィルタリングは、renderMethod.renderPropertyに存在する JSON Pointer [RFC6901] 値に対し、 Data Integrity ECDSA Cryptosuites v1.0仕様 [VC-DI-ECDSA] のセクション3.4.13 selectJsonLd で定義されたselectJsonLdアルゴリズムを適用することによって行われなければMUSTなりません。

ホストページは、フィルタリング済みの検証可能なクレデンシャルおよびHTMLテンプレートを、上で定義されたラッパーコードテンプレートに埋め込むことで、ラッパーコードを作成しなければ MUSTなりません。

wrapperCodeを、<head>内に <meta http-equiv="Content-Security-Policy" content="default-src data: 'unsafe-inline'">を持つHTML Documentとする。
datablockを、typeが application/vcであるHTML Data Blockとする。
datablockの内容を、フィルタリング済みの検証可能なクレデンシャルをJSON文字列化した形式に設定する。
datablockをwrapperCodeの<head>に挿入する。
templateの値をwrapperCodeの<body>に挿入する。

ホストページは、iframeの srcdoc属性を、生成されたラッパーコードに設定しなければMUSTなりません。

iframeのsrcdoc属性を、 wrapperCodeを文字列化したHTMLに設定する。

ホストページは、上記の説明のとおり readyおよびerrorメッセージを受信するために、ラッパーコードとの通信チャネルを設定しなければMUSTなりません。

renderPromiseを、次の性質を持つ新しいPromiseとする。
1. resolve時には、iframeをユーザーに表示するために使用できる。
2. reject時には、ユーザーにエラーメッセージを表示する。
iframeのonloadイベントにおいて:
1. channelを新しいMessageChannelとする。
2. channel上に、wrapperCode経由で iframeへ注入されたtemplate内のコードからの readyメッセージを待ち受ける、新しいport1 リスナーを作成して開始する。
3. port1リスナーにおいて、readyメッセージを受信した場合は renderPromiseを解決する。 errorメッセージを受信した場合は、エラーメッセージで renderPromiseを拒否する。
4. postMessageを使用して、channelのport2を iframeのcontent windowへ送信する。

ホストページは、レンダリングが完了した時点、またはレンダリング中にエラーが発生したかどうかを判断するために、 renderPromiseを使用するべきSHOULDです。

ラッパーコードは、 MessageChannelを介してホストページからの通信を受信するように設定し、テンプレートコードで使用する window.renderMethodReadyメソッドを提供しなければ MUSTなりません。

window.onloadイベントにおいて...
1. portを、messageイベントを介してホストページから受信した MessagePortとする。
2. window.renderMethodReady関数を作成し、その関数は...
  1. 引数なしで呼び出された場合、portを介して readyメッセージをホストページへ送信する。
  2. Error引数で呼び出された場合、portを介してエラーメッセージ付きのerrorメッセージをホストページへ送信する。

EmbeddedRendererは、発行者が検証可能なクレデンシャルをレンダリングするために使用されます。検証可能なクレデンシャルは、文書内で参照されるTemplate Renderer Webサイトを通じて、埋め込まれた<iframe>内のHTMLとしてレンダリングされます。この構成により、OpenAttestationMerkleProofSignature2018を使用した対話的な選択的開示が可能になります。

Template Rendererは、iframe内に埋め込まれるWebアプリケーションです。これは、選択されたテンプレートに基づいて検証可能なクレデンシャルをレンダリングし、レンダリング処理を促進するためにHostアプリケーションからの特定のメッセージを待ち受けなければなりません。

現在、多数のEmbeddedRenderer発行者および埋め込みレンダラー実装が存在します。

発行者が、検証可能なクレデンシャルに対して埋め込みレンダリング指示を指定したい場合、その発行者は以下で説明するデータモデルを使用するrenderMethodプロパティを追加してもよい MAYです。

プロパティ	説明
id	EmbeddedRenderer Action APIを実装するWebサイトを指すURL。
type	`type`プロパティは `EmbeddedRenderer`でなければMUST なりません。
renderName	文書をレンダリングするために、`id`で指定されたWebサイトによって使用されるテンプレートの名前。埋め込みレンダラーが検証可能なクレデンシャルの異なるHTMLビューを提示するために、別のテンプレートを使用できます。

上記に示したデータモデルは、以下の例において検証可能なクレデンシャルで表現されています。

例 16: 発行者によるrenderMethodプロパティの使用

  {
    "@context": [
      "https://www.w3.org/ns/credentials/v2",
      "https://w3id.org/security/data-integrity/v2",
      "https://trustvc.io/context/render-method-context-v2.json",
    ],
    "credentialSubject": {
     ...
    },
    "type": ["VerifiableCredential"],
    "issuer": "did:web:trustvc.github.io:did:1",
    "validFrom": "2024-04-01T12:19:52Z",
    "id": "urn:uuid:01992e54-cc5e-700e-a80b-60ddf0fffca9",
  },
  "renderMethod": [
      {
        "type": "EMBEDDED_RENDERER",
        "templateName": "DEMO_CERTIFICATE",
        "id": "https://generic-templates.tradetrust.io"
      }
  ]
}

検証可能なクレデンシャルは、 DEMO_CERTIFICATEという名前のテンプレートを使用する埋め込みレンダラーを https://generic-templates.tradetrust.ioで指定します。

埋め込みレンダラーは、検証可能なクレデンシャルの異なるビューを提供できるさまざまなテンプレートをサポートできます。以下は、異なるテンプレートを使用した同一の検証可能なクレデンシャルの2つのレンダリングです。

Hostは、Template Rendererの助けを借りて文書を表示するアプリケーションです。 Template Rendererは、renderMethod.idで指定されるiframe内に埋め込まれたWebアプリケーションでなければMUSTならず、アクションを実行するためにpostMessage APIを用いてHostアプリケーションと通信しなければ MUSTなりません。

すべてのアクションは同じ構造に従います。これらはtypeと payloadで構成されます。

typeは、実行されるアクションの種類を示します。たとえば、 RENDER_DOCUMENTは文書をレンダリングすることを意味します。アクションのtypeは必須です。
payloadは、typeに関連付けられた任意のデータ、たとえばレンダリングする文書の内容を示します。

オープンソースの参照実装は GitHubで入手できます。

HostとTemplate Rendererの相互作用は、以下の図に示されています。

iframeが最初に表示されると、hostは文書をレンダリングするためのコマンドをiframeへ送信します。サポートされる4種類のアクションを以下に説明します。

type	payload	アクション
`GET_TEMPLATES`	`{ type: "GET_TEMPLATES" }`	指定された文書についてレンダラーがサポートするテンプレートの一覧を取得します。テンプレートの一覧は、iframeからのUPDATE_TEMPLATES呼び出しによって返されます。
`SELECT_TEMPLATE`	`{ type: "SELECT_TEMPLATE", payload: "CUSTOM_TEMPLATE" }`	レンダリングに使用するテンプレートを選択します。GET_TEMPLATESによって返された一覧に含まれているべきです。見つからない場合は、デフォルトのテンプレートが使用されます。
`RENDER_DOCUMENT`	`{ type: "RENDER_DOCUMENT", payload: { document: { credentialSubject: ..., renderMethod: ... } } }`	選択されたテンプレートを使用して、IFRAME内で検証可能なクレデンシャルをレンダリングします。Documentは、検証可能なクレデンシャルのJSONオブジェクト形式です。
`PRINT`	`{ type: "PRINT" }`	IFRAMEの内容を印刷できるように、印刷ダイアログを表示しなければ MUSTなりません。

これらはiframeによって、整形または選択的な墨消しの調整を行うためにhostを更新する目的で使用されます。

type	payload	アクション
`OBFUSCATE`	`{ type: "OBFUSCATE", payload: "a[0].b.c", }`	これは選択的な墨消しに使用されます。Hostには難読化されたフィールドのパスが通知され、 hostは選択されたフィールドを難読化した文書の更新版を作成できます。
`UPDATE_HEIGHT`	`{ type: "UPDATE_HEIGHT", payload: 150, }`	埋め込みiframeの高さをピクセル単位でHostへ通知し、Hostがブラウザー上でサイズを調整できるようにします。
`UPDATE_TEMPLATES`	`{ type: "UPDATE_TEMPLATES", payload: [ { id: "template1", label: "template1", }, { id: "template2", label: "template2", } ] }`	RENDER_METHODまたはGET_TEMPLATES呼び出しから使用可能なテンプレート名の一覧を Hostへ通知します。

検証可能なクレデンシャルのレンダリング方法 v1.0

概要

この文書の状態

1. 序論

1.1 用語

1.2 適合性

2. データモデル

2.1 `renderMethod` プロパティ

2.2 TemplateRenderMethod

2.2.1 `svg-mustache`レンダースイート

2.2.2 `pdf-mustache`レンダースイート

2.2.3 `nfc`レンダースイート

2.2.4 `html`レンダースイート

2.2.4.1 ホストページ

2.2.4.1.1 テンプレートコード

2.2.4.1.2 ラッパーコード

2.2.4.1.3 Readyおよび Errorイベント

2.2.4.2 アルゴリズム

2.2.4.2.1 ホストページ

2.2.4.2.2 ラッパーコード

2.3 EmbeddedRenderer

2.3.1 Action API

2.3.1.1 HostからFrameへのアクション

2.3.1.2 FrameからHostへのアクション

3. アルゴリズム

3.1 レンダー（TemplateRenderMethod）

A. セキュリティに関する考慮事項

B. プライバシーに関する考慮事項

C. 国際化に関する考慮事項

D. 参考文献

D.1 規範的参照

検証可能なクレデンシャルのレンダリング方法 v1.0

概要

この文書の状態

1. 序論

1.1 用語

1.2 適合性

2. データモデル

2.1 renderMethod プロパティ

2.2 TemplateRenderMethod

2.2.1 svg-mustacheレンダースイート

2.2.2 pdf-mustacheレンダースイート

2.2.3 nfcレンダー スイート

2.2.4 htmlレンダー スイート

2.2.4.1 ホストページ

2.2.4.1.1 テンプレートコード

2.2.4.1.2 ラッパーコード

2.2.4.1.3 Readyおよび Errorイベント

2.2.4.2 アルゴリズム

2.2.4.2.1 ホストページ

2.2.4.2.2 ラッパーコード

2.3 EmbeddedRenderer

2.3.1 Action API

2.3.1.1 HostからFrameへのアクション

2.3.1.2 FrameからHostへのアクション

3. アルゴリズム

3.1 レンダー（TemplateRenderMethod）

A. セキュリティに関する考慮事項

B. プライバシーに関する考慮事項

C. 国際化に関する 考慮事項

D. 参考文献

D.1 規範的参照

2.1 `renderMethod` プロパティ

2.2.1 `svg-mustache`レンダースイート

2.2.2 `pdf-mustache`レンダースイート

2.2.3 `nfc`レンダースイート

2.2.4 `html`レンダースイート

C. 国際化に関する考慮事項