アドオンのバージョン付け
アドオンは、Toolkit バージョンフォーマット を使って自身のバージョンを指定すべきです。簡単に説明すると、これはピリオドによって区切られたバージョン文字列です。いくつかの例を示します。
- 2.0
- 1.0b1
- 3.0pre1
- 5.0.1.2
アプリケーションの互換性判断方法
アドオンをインストールしたとき、アプリケーションはアドオンの <tt>install.rdf</tt> の中の targetApplication 項目を見ます。アプリケーションの ID に一致した項目が存在しなくてはなりません。さらに、実行しているアプリケーションのバージョンはこの項目の minVersion と maxVersion の範囲内でなくてはなりません。
アプリケーションが targetApplication 項目を持っており、しかしそれが互換性の無いバージョン向けだった場合、アプリケーションはアドオンの updateURL から更新された互換性情報を読み込みます。
もし install.rdf が targetPlatform 項目をもっているなら、現在実行しているアプリケーションのプラットフォームが含まれていない限り、インストールは拒否されます。
Gecko 1.9 ベースのアプリケーションでは targetApplication 項目に、ID が [email protected] で、実行しているアプリケーションが使っている Toolkit のバージョンに一致する minVersion と maxVersion を指定することができます。これによって Toolkit ベースのいかなるアプリケーションにもインストール可能であると宣言することができます。
互換性チェックを無効にする
テスト目的で、アプリケーションにアドオンインストール時の互換性チェックを無視するよう指示することができます。単に真偽値設定の extensions.checkCompatibility を作り、false に設定してください。
app.extensions.version 設定でアプリケーション自身のバージョンを上書きすることが可能でした。
minVersion と maxVersion を選択する
minVersion と maxVersion はテストしたアプリケーションのバージョンの範囲を指定すべきです。特に、そのアプリケーションで現在利用できるバージョンよりも大きな値を maxVersion に指定すべきではありません。なぜなら、あなたはまもなく行われる (かもしれない) API と UI の変更について知らないのですから。互換性のある更新 では、maxVersion を上げるために拡張機能丸ごとの新バージョンをリリースする必要はありません。
普通、maxVersion ではサポートしているアプリケーションのマイナバージョンの箇所に * を使うことができます。例えば 2.0.0.* はそのアプリケーションのバージョン 2 におけるマイナアップデート全てをサポートするということを意味しています。通常、アプリケーションは拡張機能作者に、これを使うのに適しているバージョンの部分を示します。
バージョンの * が全てのバージョンを表すものだと誤解しないでください。 実際には、* は無限に大きい数を表すので、maxVersion で賢く使用されるだけのものです。通常それを minVersion で使っても望む効果は生みだしません。
自動アドオン更新チェック
アプリケーションは、updateURL を読み込むことで、インストールされたアドオンの更新を定期的に確認するでしょう。返された情報によって、アドオンの更新されたバージョンをユーザに知らせることや新しいバージョンのアプリケーションがアドオンが互換性があることを知らせることができます。
互換性のある更新
自動更新チェックの間、アプリケーションは新しいバージョンと、現在インストールされているバージョンの更新された互換性情報を探します。これは更新マニフェストがアドオンの現在インストールされているバージョンの項目を含んでおり、その項目の targetApplication 項目が より大きな maxVersion を指定している場合、アプリケーションはアドオンの <tt>install.rdf</tt> で指定された値ではなく、この値を使うでしょう。これは非互換なため無効にされたアドオンを有効にし、通常はインストールされないアドオンをインストールすることができます。
アップデート RDF の形式
もしあなたがアドオンの updateURL を自分自身で提供している場合、あなたは RDF の形式でアドオンのバージョン情報を帰す必要があるでしょう。以下は更新情報の定義の例です。[email protected]という ID の拡張機能について 2 つの異なるバージョンの情報を列挙しています。含まれているバージョンは 2.2 と 2.5 で、どちらも Firefox 1.5 から 2.0.0.* までに対して互換性があることを示しています。バージョン 2.2 用には更新用のリンクに https が使われていて、バージョン 2.5 用には通常の http のリンクと、取得したファイルを検証するためのハッシュの情報が含まれています。
最初の RDF:Description の about 属性を正確にすることに気をつけてください。あなたが提供している情報がどの種類のアドオンに対するものであるかによって、その値は変化します。
- 拡張機能の場合は
urn:mozilla:extension:<id>でなければなりません。 - テーマの場合は
urn:mozilla:theme:<id>でなければなりません。 - それ以外の種類のアドオンの場合は
urn:mozilla:item:<id>でなければなりません。
以下の例ではいずれも、<RDF:Seq> 要素内のバージョンの順序が重要で、より新しいバージョンを、古いバージョンよりも後に配置する必要があります。最新のバージョンのみ提供する場合は、すべてのバージョンを記載する必要はありません。
<?xml version="1.0" encoding="UTF-8"?>
<RDF:RDF xmlns:RDF="https://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:em="https://www.mozilla.org/2004/em-rdf#">
<!-- この Description リソースは、[email protected] という ID のあるアドオンに
関する、すべての更新情報と互換性の情報を含んでいます。複数のアドオンの情報を
同じ RDF ファイルの中に列挙することもできます。 -->
<RDF:Description about="urn:mozilla:extension:[email protected]">
<em:updates>
<RDF:Seq>
<!-- それぞれの li は、同じアドオンの異なるバージョンを示します。 -->
<RDF:li>
<RDF:Description>
<em:version>2.2</em:version> <!-- これはこのアドオンのバージョン番号です。 -->
<!-- アドオンの互換性があるアプリケーション 1 つ毎に 1 つの
targetApplication を記述します。 -->
<em:targetApplication>
<RDF:Description>
<em:id>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</em:id>
<em:minVersion>1.5</em:minVersion>
<em:maxVersion>2.0.0.*</em:maxVersion>
<!-- これは、そのバージョンのアドオンがどこからダウンロードできるかを示します。 -->
<em:updateLink>https://www.mysite.com/foobar2.2.xpi</em:updateLink>
<!-- この更新されたバージョンでの変更点を説明したページ -->
<em:updateInfoURL>https://www.mysite.com/updateinfo2.2.xhtml</em:updateInfoURL>
</RDF:Description>
</em:targetApplication>
</RDF:Description>
</RDF:li>
<RDF:li>
<RDF:Description>
<em:version>2.5</em:version>
<em:targetApplication>
<RDF:Description>
<em:id>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</em:id>
<em:minVersion>1.5</em:minVersion>
<em:maxVersion>2.0.0.*</em:maxVersion>
<em:updateLink>https://www.mysite.com/foobar2.5.xpi</em:updateLink>
<em:updateHash>sha1:78fc1d2887eda35b4ad2e3a0b60120ca271ce6e6</em:updateHash>
</RDF:Description>
</em:targetApplication>
</RDF:Description>
</RDF:li>
</RDF:Seq>
</em:updates>
<!-- 署名は、あなたのアドオンが install.rdf の中に updateKey を含んでいる
場合にのみ有効です。 -->
<em:signature>MIGTMA0GCSqGSIb3DQEBBQUAA4GBAMO1O2gwSCCth1GwYMgscfaNakpN40PJfOWt
ub2HVdg8+OXMciF8d/9eVWm8eH/IxuxyZlmRZTs3O5tv9eWAY5uBCtqDf1WgTsGk
jrgZow1fITkZI7w0//C8eKdMLAtGueGfNs2IlTd5P/0KH/hf1rPc1wUqEqKCd4+L
BcVq13ad</em:signature>
</RDF:Description>
</RDF:RDF>
人によっては、以下のもう 1 つの形式の方が好みかもしれません。(註：この例では、基本的な構造を示すために多くの情報を省略しています)
<?xml version="1.0" encoding="UTF-8"?>
<RDF:RDF xmlns:RDF="https://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:em="https://www.mozilla.org/2004/em-rdf#">
<!-- この Description リソースは、[email protected] という ID のあるアドオンに
関する、すべての更新情報と互換性の情報を含んでいます。複数のアドオンの情報を
同じ RDF ファイルの中に列挙することもできます。 -->
<RDF:Description about="urn:mozilla:extension:[email protected]">
<em:updates>
<RDF:Seq>
<!-- resource 属性は、about 属性が対応している以下のそれぞれの RDF:Description
エントリを指し示しています。実際の URI は好きなように書いて構いませんが、
RDF の文法に従ってそれぞれ固有の URI を持たなくてはなりませんので、
バージョン番号をそれぞれのバージョンの末尾に追加しました -->
<RDF:li resource="urn:mozilla:extension:[email protected]:2.2"/>
<RDF:li resource="urn:mozilla:extension:[email protected]:2.5"/>
</RDF:Seq>
</em:updates>
<em:signature>MIGTMA0GCSqGSIb3DQEBBQUAA4GBAMO1O2gwSCCth1GwYMgscfaNakpN40PJfOWt
ub2HVdg8+OXMciF8d/9eVWm8eH/IxuxyZlmRZTs3O5tv9eWAY5uBCtqDf1WgTsGk
jrgZow1fITkZI7w0//C8eKdMLAtGueGfNs2IlTd5P/0KH/hf1rPc1wUqEqKCd4+L
BcVq13ad</em:signature>
</RDF:Description>
<!-- これは前の例で li の中に置かれている Description と同じ情報を示しています -->
<RDF:Description about="urn:mozilla:extension:[email protected]:2.2">
<em:version>2.2</em:version>
<!-- ここにある残りの情報は省略します -->
</RDF:Description>
<RDF:Description about="urn:mozilla:extension:[email protected]:2.5">
<em:version>2.5</em:version>
<!-- ここにある残りの情報は省略します -->
</RDF:Description>
</RDF:RDF>
更新の詳細情報の提供
あなたのアドオンの更新されたバージョンにおける新しい点について、ユーザに詳細情報を提供することができます。これはユーザがアドオンの更新通知を見る際に、どんな新機能が追加され、どんなセキュリティ上の問題が解決されたのか、簡単な概要を示すために表示されます。
この機能を使うには、updateInfoURLエントリをその更新情報の定義に追加する必要があります (上の例を見てください)。この URL で示されたページが取得され、ユーザに示されます。通常の Web ページの文脈から外れてページが表示されるまでの間に、そのページは厳重に無害化されます。これはつまり、ごく僅かな整形のための手段のみが利用できて、スクリプトや画像は利用できないということを意味します。一般的なルールとして、あなたは以下のタグのみを利用することができます (これら以外は全て無視されます)。
- 一般的な見出しのための h1, h2, h3
- 段落のための p
- リストのための ul と ol
リストの中でそれぞれのリストの項目を示すためには、通常の li タグを使います。
h1, h2, h3, p, li のそれぞれのタグの中では、あなたは以下のタグを使えます。
- 太字のための b もしくは strong
- 斜体のための i もしくは em
取得された詳細情報のページは現在の所、MIME Type が application/xhtml+xml で届けられなければならない事も含めて、完全に妥当な XHTML でなければなりません。
ロケール情報を URL に含めたい場合は、updateInfoURL に %APP_LOCALE% を使うことができます。これにより、ユーザのロケールに合わせて文章をカスタマイズできるようになります。また、あまり実用的ではないかもしれませんが、updateURL でサポートされている他の代入文字列を使うこともできます。
安全な更新
Gecko 1.9には、ユーザをアドオンの更新中に行われる 中間者攻撃 から保護するために設計された、追加の要求事項が加えられました。インストール済みのアドオンの install.rdf の中において、updateURL は以下のいずれかの方法で示される必要があります。
- https を使った
updateURL、もしくは全くupdateURLを提供しない。(この場合、初期状態では https で通信する <tt>addons.mozilla.org</tt> へアクセスすることになります) - http を使った
updateURLで、updateKeyエントリが指定されている。(それは更新情報の定義の内容を検証するために使われるでしょう。)
<tt>install.rdf</tt> の中で updateKey を指定する場合、更新情報の定義への署名 を行う必要があります。さもなければ、更新情報は拒絶されます。
updateURL によって伝えられた更新情報の中の updateLink は、以下の方法のうちのいずれかによって指定される必要があります。
- XPI ファイルへの
updateLinkは https を使ったものでなければなりません。 updateLinkは http を使うことができ、この場合、あなたは sha1、sha256、sha384、sha512 のいずれかのハッシュアルゴリズムで生成した XPI の 更新ファイルのハッシュ (updateHash) を含める必要があります。
更新情報の定義の中において、それらの 2 つの条件を満たさないあらゆる情報は、新しいバージョンをチェックする際にはすべて無視されます。
註：不正な証明書を使ったサイトへの https なリンクや、http のサイトへのリダイレクトは、<tt>update.rdf</tt> と updateLink のどちらのケースにおいても読み込みに失敗するでしょう。
更新ファイルのハッシュ (updateHash)
ダウンロードされた XPI の完全性を検証するために、あなたは updateLink と並べて updateHash エントリを提供することができます。これはファイルの内容を文字列として解釈して生成されたハッシュであるべきです。ハッシュ化に使われたアルゴリズムの名前は、文字列全体の最初に、ハッシュ値の手前に : で区切って置かれます。
<em:updateHash>sha1:78fc1d2887eda35b4ad2e3a0b60120ca271ce6e6</em:updateHash>
ハッシュが示されている場合、ダウンロードされたファイルはハッシュと比較され、それらが一致しない場合はエラーが表示されます。
更新情報の定義への署名
もしあなたが更新情報の RDF を通常の http を使って提供したい場合、Gecko 1.9 ベースのアプリケーションは、更新情報の定義について、あなたが作成してからアプリケーションがそれを取得するまでの間に第三者によって改変されていないことを確かめるため、電子署名を施すことが求められるでしょう。更新情報の RDF に署名するには McCoy というツールを使うべきです。
署名の仕組みの技術的な詳細はこの文書の目的から外れますが、基本的には以下の通りです。
アドオンの作者は RSA 暗号による公開鍵と秘密鍵のペアを作成します。
公開鍵は DER と base 64 でエンコードされた後、アドオンの <tt>install.rdf</tt> に updateKey エントリとして追加されます。
作者が更新情報の RDF ファイルを作成する時には、秘密鍵を使って署名するツールを使用します。大まかにいうと、更新情報は文字列に変換された後、SHA512 のハッシュアルゴリズムによってハッシュ化され、このハッシュが秘密鍵によって署名されます。最終的なデータは DER と base 64 でエンコードされた後、更新情報の RDF に em:signature エントリとして追加されます。