omaha‎ > ‎

Omaha Client-Server Protocol V3

を適当に翻訳中

注意: TOEIC400点とかの人が急いで訳したものなので、あまり信用しないように

Overview

The client sends requests via HTTP POST with an XML data body. The response is an XML data body.

An HTTP request may concatenate multiple applications in one XML body; similarly, multiple request-actions may be included for any application. The server responds with a status and other information (as appropriate) for each action, organized in a similar nested XML structure.

Custom HTTP Headers

The Client can attach one or more custom HTTP headers to the POST request. They are purely advisory in nature, and their presence and content are not required in order to provide responses to update checks.


概要
クライアントはXMLデータのbodyと共にHTTP POSTリクエストを送ります。レスポンスはXMLデータのbodyです。

HTTPリクエストは1つのXMLbodyに複数のアプリケーションを結びつけるかもしれませんし、複数のリクエストアクションが、全てのアプリケーションに含まれているかもしれません。サーバーはステータスやそれぞれのアクションの情報を含んで、レスポンスを返します。レスポンスは似たようなネスト構造を持つXMLです。

カスタムHTTPヘッダー
クライアントは、1つかそれ以上のカスタムHTTPヘッダーをPOSTリクエストに付けることができます。それらは実際、単純に助言を与えるもので、それらの存在やコンテンツはアップデートチェックのためのレスポンスを提供するために必要ではありません。

Examples


Reference

A terse description of the XML elements and attributes follows.

request Element

This is the envelope around the entire request. The request attributes describe global data describing the machine or the Omaha client instance. The response attributes are minimal.

Request Attributes

  • protocol: Always "3.0".
  • version: The version number of the Omaha client.
  • ismachine: 0 or 1, depending on whether the Omaha client is a per-user or per-machine instance.
  • requestid: A random GUID generated for each request. (This is used to identify duplicate requests that are sent multiple times by buggy network stacks and/or proxy servers.)
  • sessionid: A random GUID associated with the current task - a clean install, a update check, etc. If a task requires sending multiple requests from different processes (for example, an Omaha self-update that sends event pings both before and afterwards), those requests will have identical session IDs.
  • userid (optional): A random GUID associated with the logged-in user. There will be a different userid for each username on the machine, as well as for the per-machine instance. UIDs are opt-in and will not be generated if not opted into.
  • installsource (optional): An arbitrary string that can mark the source of a request. This is set by the client driving Omaha. Typical examples: "scheduledtask", "ondemandupdate", "selfupdate", "update3web", "oneclick", and so on.
  • originurl (optional): If Omaha is invoked via a web browser plugin, contains the URL of the page invoking it.
  • testsource (optional): Identifies requests related to development and testing. May be omitted, or one of "dev", "qa", "prober", "auto","ossdev".
  • dedup: Identifies the algorithm used for reporting application activity. It may be either "cr" or "uid", for client regulated and unique user id respectively. In its recent versions, Omaha is always using "cr". Please see the description of attributes for the "ping" element in this document for how the application activity is reported.
  • updaterchannel: Identifies the channel that the updater is running on; for example "dev", "stable", "beta", or "canary".

Response Attributes

  • protocol: Always "3.0".
  • server: A string identifying the server that provided the response, mostly for diagnostic purposes. Typical examples: "prod", "unittest", etc.

リクエストエレメント

これはリクエスト全体を包みます。リクエストアトリビュートは、マシンについてかOmahaクライアントインスタンスについて述べる、(スコープ的に)グローバルなデータです。レスポンスアトリビュートは小さいです。

リクエストアトリビュート
  • protocol : 常に3.0
  • version : omahaクライアントのバージョン番号
  • ismachine : 0か1で、oomahaクライアントがマシン全体にインストールされているか、1人のユーザーへのインストールかどうか
  • requestid : それぞれのリクエストのためのランダムなGUID. (これはバグったネットワークスタックやプロ式サーバーによって複数回送られる重複したリクエストを区別するのためのもの)
  • sessionid : クリーンインストールや、アップデートチェックなどの、現在のタスクに関してのランダムなGUID. もしタスクが異なるプロセスからの複数のリクエスト(例えば、開始前と終了後のどちらでもpingイベントを送る、omahaの自己アップデート) を要求する場合、それらのリクエストはsession IDによって区別されます.
  • userid (オプション) : ログインしているユーザーに関してのランダムなGUID. 1マシンインスタンスと同様に、そのマシン上の、各ユーザ名について、異なるユーザIDがあります. ユーザIDは生成するには許可が必要なので生成はされません。
  • installsource (オプション) : リクエストのソースを示すことができる、任意の文字列. これはクライアント権限で動いているomahaによって設定されるもので、例えば"scheduledtask", "ondemandupdate", "selfupdate", "update3web", "oneclick"などがあります。
  • originurl (オプション) : omahaがウェブブラウザプラグインによって呼び出される場合、その処理を行ったページのURLが含まれます。
  • testsource (オプション) : 開発やテストに関する識別用リクエスト。省略されるかもしれないし、"dev", "qa", "prober", "auto","ossdev"のうちの1つかもしれない。
  • dedup : アプリケーションの活動レポートのためのアルゴリズムの識別。クライアントの権限とユニークユーザーIDそれぞれについて、"cr"か"uid"であるかもしれない。最近のバージョンでは、omahaは常に"cr"を使用している。どのようにアプリケーション活動がレポートされるかについては、このドキュメントの"ping"エレメントのアトリビュートの説明を見てください。
  • updaterchannel: アップデータが走っているチャンネルの識別。 例えば"dev", "stable", "beta",や "canary".
レスポンスアトリビュート
  • protocol : 常に3.0
  • server : レスポンスを返えすサーバーを識別する文字列で、ほとんど診断目的。例:  "prod", "unittest"等.

os Element

Inside the request envelope, but prior to any app-request elements, is an os element that describes the O/S of the machine. The server never supplies an os element in the response.

Request Attributes

  • platform: One of "win", "mac", "ios".
  • version: On Windows, the major-minor O/S version, e.g. "5.1", on the Mac, it is "MacOSX". On iOS, "4.3", "5.1.1", etc.
  • sp: On Windows, the service-pack version, e.g. "Service Pack 2", on the Mac, OS version and processor architecture, like "10.5.6_i486"or "10.4.11_ppc750".
  • arch: One of "x86", "x64", "arm".

Response Attributes

N/A


OSエレメント
リクエストの包みより内側だが、他のappリクエストエレメントより優先度が高く、マシンのO/Sについて述べるOSエレメントです。サーバーはレスポンスとして何も返さない。

リクエストアトリビュート
  • platform : "win", "mac", "ios"のどれか1つ
  • version : Windowsでは、"5.1"のようなメジャー-マイナーO/Sバージョンで、Macでは"MacOSX"です。iOSでは "4.3", "5.1.1"などです。
  • sp : Windowsでは、"Service Pack 2"のようなサービスパックのバージョンで、Macでは"10.5.6_i486""10.4.11_ppc750"のようなOSバージョンとプロセッサアーキテクチャです。
  • arch : "x86", "x64", "arm"のどれか1つ

レスポンスアトリビュート
なし

daystart Element

Inside the request envelope, but prior to any app-response elements, is a daystart element that gives the number of seconds since midnight at the server's locale. This is used by the client to calculate days-since attributes in pings.

Request Attributes

N/A

Response Attributes

  • elapsed_seconds: Number of seconds since midnight at the server's locale.

daystartエレメント
リクエストの包みより内側だが、他のappリクエストエレメントより優先度が高く、サーバーのロケールで午前0時から何分経っているかを示すdaystartエレメントです。
これはpingで、days-sinceアトリビュートを計算するために、クライアントによって使用されます。

リクエストアトリビュート
なし

レスポンスアトリビュート
  • elapsed_seconds : サーバーのロケールで午前0時から何分か
app Element

The app element may be repeated in the request any number of times. The server will reply with a corresponding app element for each request app element; In practice, the app elements of the response will be in the same order as the request.

Request Attributes

  • appid: The id of the app. On Windows this is a GUID, including the braces ({}); on Mac it is a bundle ID of the form com.google.appname. You can use GUIDs on the Mac, but it's usually easier to just get the application's bundle ID.
  • version: The dotted-quad version of the app. A "" value is interpreted as "0.0.0.0", namely a new install.
  • nextversion: The dotted-quad version of the app upgrade in progress. This is mainly used for sending events during or after an upgrade; it will be "" for initial update checks.
  • lang: Language of the app install. Should be in BCP 47 representation.
  • brand: Brand code specified at install time, if any. These are typically used to tabulate partner deals and website promotions.
  • client: Similar to brand code.
  • ap (optional): Additional parameters specified at install time, if any. These are usually used to denote experimental branches/tracks.
  • experiments (optional): An experiment key/value list, if any. This can be specified at install time, or set by the server in previous update responses. These are usually used to denote experimental branches/tracks.
  • iid (optional): A random GUID used to uniquely count install attempts. For example, if a user fails to install then re-runs the installer and succeeds, we might want to count that as one "attempt".
  • installage (optional): The number of days since the app was first installed. A new install should use -1 days.

Response Attributes

  • appid: The id of the app. See Request Attributes.
  • status: One of:
    • "ok": The appid was recognized; see the status attribute on the child updatecheck or event tags for further status.
    • "restricted": The appid was recognized, but the application is not available to this user (usually based on country export restrictions).
    • "error-unknownApplication": The appid was not recognized and no action elements are included.
    • "error-invalidAppId": The appid is not properly formed; no action elements are included.
    • ...any other string prefixed by "error-": Added to the protocol as needed.
  • experiments (optional): An experiment key/value list, if any. If the server responds with any entries in this attribute, the client should save those experiments in the Registry or other store, and include them in later requests.

appエレメント
appエレメントはリクエストに複数回繰り返し含まれているかもしれないです。サーバーは各リクエストのappエレメントについて矛盾しない返信を行います;実際、レスポンスのappエレメントはリクエストと同じ並びになります。

リクエストアトリビュート
  • appid : アプリケーションのid. WindowsではこれはGUIDで、大カッコ({})を含んだものである. Macでは、com.google.appnameのフォームのバンドルIDである。MacではGUIDを使えるが、しかしただアプリケーションのバンドルIDを取得するほうがたいてい簡単です。
  • version : アプリのバージョンでドットで区切られた4つの数値です。空文字の場合"0.0.0.0"と解釈され、新規インストールとなります。
  • nextversion : 進行中のアプリのアップグレードバージョンでドットで区切られた4つの数値です。これはアップデートの最中や後にイベントを送るのに主に使用されます;最初のアップデートチェックでは空文字が使用されます。
  • lang : インストールアプリの言語。BCP48表現にすべきです。
  • brand : インストール時の特定のブランドコードです。公平なパートナーとウェブサイトプロモーションの扱いのために使用されます。
  • ap (オプション) : もしある場合は、インストール時の特定の追加パラメータです。それらはたいてい実験的なブランチ/トラックを意味するために使用されます。
  • experiments (オプション) : もしある場合は、実験用のキーバリューのリストです。もしサーバーがこのアトリビュートのどんなエントリでも返した場合、クライアントはそれらの実験的なリストをレジストリや他の保存方法で保存するべきです、そして後のリクエストにそれらを含みます。
  • iid (オプション) : インストールを試行したユニークなカウントのためのGUIDです。例えばユーザーがインストールに失敗し再度インストーラを起動して成功した場合、我々は1回の試行としてカウントしたいはずです。
  • installage (オプション) : アプリを最初にインストールしてからの日数。新規インストールでは-1日を使用するべきである。
レスポンスアトリビュート
  • appid : アプリのid. リクエストアトリビュートを参照。
  • status : 次のうちの1つ
    • "ok" : appidが認識された; 子のupdatecheckのステータスアトリビュートか、次のステータスのためのイベントタグを参照。
    • "restricted" : appidが認証されたが、しかしアプリケーションはこのユーザーには利用できない。(通常国の輸出規制に基づく)
    • "error-unknownApplication" : appidが認証されなかった、そしてアクションエレメントが1つも含まれていない
    • "error-invalidAppId" : appidが適切な形式ではなかった; アクションエレメントが1つも含まれていない
    • 他の"error-"から始まる文字列: 必要に応じてプロトコルに追加されたもの
  • experiments(オプション): もしある場合は、実験用のキーバリューリスト。もしサーバーがこのアトリビュートのどんなエントリでも返した場合、クライアントはそれらの実験的なリストをレジストリや他の保存方法で保存するべきです、そして後のリクエストにそれらを含みます。

App Action Elements

Actions are always the child of an app element and pertain to that app.

updatecheck Element

Request whether a newer version of the application is available.

Request Attributes

  • tttoken (optional): An access token for protected downloads. The request should be sent over SSL if this attribute is present.
  • updatedisabled (optional): "true" indicates that an update response will not be applied because it is disallowed by Group Policy.
  • targetversionprefix (optional): A prefix of the update version that the client is ok receiving. If ended with $ then the version string must match exactly. (It may be ignored by the server.)

Response Attributes

The "status" attribute is always present; the rest are supplied only if an update is available.

The update check is over a secure channel. By providing the size and hash of the download binary, the binary itself may be fetched over an insecure channel and still be verified.

  • status: One of:
    • "noupdate": No update is available.
    • "ok": An update specification is included.
    • "error-osnotsupported": The operating system version is not supported by this application.
    • "error-unsupportedProtocol": The update specification cannot be expressed in this version of the protocol.
    • "error-pluginRestrictedHost": This application is restricted to only be installable from specific domains.
    • "error-hash": An internal error occurred on the server while obtaining the hash of the installer binary.
    • "error-internal": Other internal error.
  • tttoken (optional): An access token for protected downloads. The request should be sent over SSL if this attribute is present.
  • errorurl (optional): A URL that provides more information for the error in status. The Omaha client supports this for "error-osnotsupported".

On a status value of "ok", additional children will be included.


App アクションエレメント
アクションはいつもappエレメントの子で、そのappに付属します。

updatecheckエレメント
アプリケーションの新しいバージョンが利用可能かどうか問い合わせます

リクエストアトリビュート
  • tttoken(オプション) : 保護されたダウンロードのためのアクセストークン。もしこのアトリビュートがある場合は、リクエストはSSLを通じて送られるはずである。
  • updatedisabled(オプション) : "true"なら、グループポリシーによって許可されていないため、アプリケーションレスポンスが適用できないことを示す。
  • targetversionprefix(オプション) : クライアントがOKを受信しているアップデートバージョンのプレフィクス。もし$で終わっていれば、バージョン文字列が正確に一致する必要があります。(サーバーによっては無視されることがあります)
レスポンスアトリビュート
”status”アトリビュートは常に現れます; 残りはアップデートが可能なときに限り現れます。
アップデートチェックはセキュアなチャンネルを通じて行われます。ダウンロードバイナリのハッシュとサイズを提供することによって、バイナリ自身はセキュアではないチャンネルを通じて取得され、既に検証済となります。

  • status : 次のうちの1つ:
    • "noupdate" : アップデートは利用不可
    • "ok" : アップデート詳細が含まれていた
    • "error-osnotsupported" : オペレーティングシステムのバージョンがこのアプリケーションによってサポートされていない
    • "error-unsupportedProtocol" : アップデートの詳細はこのバージョンのプロトコルでは表現できない
    • "error-pluginRestrictedHost" : このアプリケーションは特定のドメインからのインストールのみに制限されています
    • "error-hash" : インストーラバイナリのハッシュを入手している間にサーバーで内部エラーが起きた
    • "error-internal" : 内部エラーが起きた
  • tttoken(オプション) :  保護されたダウンロードのためのアクセストークン。もしこのアトリビュートがある場合は、リクエストはSSLを通じて送られるはずである。
  • errorurl(オプション) : エラーの状態についてより多くの情報を与えるURLです。Omahaクライアントはこれを "error-osnotsupported"のためのサポートします。
"ok"のステータス値には、追加の子が含まれます。

event Element

Notifies the server of the progress or result of an install/update in progress.

Request Attributes

  • eventtype: One of
    • 0: unknown
    • 1: download complete
    • 2: install complete
    • 3: update complete
    • 4: uninstall
    • 5: download started
    • 6: install started
    • 9: new application install started
    • 10: setup started
    • 11: setup finished
    • 12: update application started
    • 13: update download started
    • 14: update download finished
    • 15: update installer started
    • 16: setup update begin
    • 17: setup update complete
    • 20: register product complete
    • 30: OEM install first check
    • 40: app-specific command started
    • 41: app-specific command ended
    • 100: setup failure
    • 102: COM server failure
    • 103: setup update failure
  • eventresult: One of
    • 0: error
    • 1: success
    • 2: success reboot
    • 3: success restart browser
    • 4: cancelled
    • 5: error installer MSI
    • 6: error installer other
    • 7: noupdate
    • 8: error installer system
    • 9: update deferred
    • 10: handoff error
  • errorcode: (optional)
    • For eventresult==0: Omaha error code
    • For eventresult=={1 | 2 | 3| 5 | 6 | 8}: Application-specific installer exit/result code.
  • extracode1: (optional) Additional numerical information related to errorcode.
  • download_time_ms: (optional) time taken for the download (if there had been one, note for cached app, download time is 0)
  • downloaded: (optional) bytes downloaded
  • total:(optional) sum of all packages sizes in this app
  • update_check_time_ms: (optional) time taken to do an update check for the app.
  • install_time_ms: (optional) time take to install Omaha or an app.
  • source_url_index: (optional) Index of the URL that served app installer download.
  • state_cancelled: (optional) App state when user cancels installation. One of:
    • 0: unknown
    • 1: init
    • 2: waiting to check for update
    • 3: checking for update
    • 4: update available
    • 5: waiting to download
    • 6: retrying download
    • 7: downloading
    • 8: download complete
    • 9: extracting
    • 10: applying differential patch
    • 11: ready to install
    • 12: waiting to install
    • 13: installing
    • 14: install complete
    • 15: paused
    • 16: no update
    • 17: error
  • time_since_update_available_ms: (optional) Time interval between update is available and user cancels installation.
  • time_since_download_start_ms: (optional) Time interval between update download starts and user cancels installation.
  • nextversion: (optional) The version of the app that an update was attempted to (regardless of whether or not the update succeeded).
  • previousversion: (optional) The version of the app prior to the update attempt.

Response Attributes

  • status: Always "ok".

eventエレメント
進行中のインストール/更新の進行状況や結果をサーバに通知します。

リクエストアトリビュート
  • eventtype : 次のうちの1つ
    • 0: 不明
    • 1: ダウンロード完了
    • 2: インストール完了
    • 3: アップデート完了
    • 4: アンインストール
    • 5: ダウンロードが開始された
    • 6: インストールが開始された
    • 9: 新しいアプリケーションのインストールが開始された
    • 10: setupが開始された
    • 11: setupが完了した
    • 12: アプリケーションのアップデートが開始された
    • 13: ダウンロードの更新が開始された
    • 14: ダウンロードの更新が終了した
    • 15: インストーラの更新が開始された
    • 16: 更新の設定が開始された
    • 17: 更新の設定が完了した
    • 20: プロダクトの登録が完了した
    • 30: OEMインストールの初回チェック
    • 40: アプリの特定のコマンドが開始された
    • 41: アプリの特定のコマンドが終了した
    • 100: セットアップが失敗した
    • 102: COMサーバーが失敗した
    • 103: セットアップの更新が失敗した
  • eventresult : 次のうちの1つ
    • 0: エラー
    • 1: 成功
    • 2: リブートが成功
    • 3: ブラウザの再起動に成功
    • 4: キャンセルされた
    • 5: MSIインストーラーのエラー
    • 6: 他のインストーラーのエラー
    • 7: アップデート無し
    • 8: インストーラシステムのエラー
    • 9: アップデートの遅延
    • 10: 捕捉していないエラー
  • errorcode(オプション) : 次のうちの1つ
    • 0: omahaエラーコード
    • {1 | 2 | 3| 5 | 6 | 8}: アプリケーションの特定のエラー/終了コード
  • extracode1: (オプション) : errorcodeに関する追加の数値の情報
  • download_time_ms : (オプション) : ダウンロードに掛かった時間。(もしあった場合でも、キャッシュしているアプリの場合は0になる)
  • downloaded : (オプション) ダウンロードしたバイト数
  • total: (オプション) このアプリの合計パッケージサイズ
  • update_check_time_ms : (オプション) アプリケーションのアップデートチェックに掛かった時間
  • install_time_ms : (オプション) Omahaかアプリをインストールするのにかかった時間
  • source_url_index: (オプション) ダウンロードされたアプリのインストーラから提供されたURLのインデックスです
  • state_cancelled: (オプション) ユーザーがインストールをキャンセルしたときのステートで、次のうちの1つ:
    • 0: 不明
    • 1: 初期化
    • 2: アップデートのチェックを待っている
    • 3: アップデートをチェックしている
    • 4: アップデートが利用可能
    • 5: ダウンロード状態になるのを待っている
    • 6: ダウンロードをリトライしている
    • 7: ダウンロードしている
    • 8: ダウンロード完了
    • 9: 解凍中
    • 10: 差分パッチの適用中
    • 11: インストールの準備
    • 12: インストール待ち
    • 13: インストール中
    • 14: インストール完了
    • 15: 中断した
    • 16: アップデートなし
    • 17: エラー
  • time_since_update_available_ms:(オプション) 更新が利用可能なのと、ユーザーがインストールをキャンセルする間のタイムインターバル
  • time_since_download_start_ms:(オプション) 更新ダウンロードが開始されるのと、ユーザーがインストールをキャンセルする間のタイムインターバル
  • next_version:(オプション) アップデートが試行されたアプリのバージョン。アップデートが成功したかどうかにかかわらない
  • previousversion:(オプション) アップデートが試行される前のアプリのバージョン。
レスポンスアトリビュート
  • status : いつもOK

ping Element

Reports the activity level of this application since the previous update check.

Request Attributes

  • active: "1" if the app was active since the last report; "0" otherwise.
  • a: If present, the app was active since the last report; the value is the number of days since the app last reported active. The attr is omitted if the app was not active.
  • r: The app is present; the value is the number of the days since the app last reported present.

For both a and r, the special value "-1" indicates a new install. Any attribute may be omitted if its value is "0"; the entire element may be omitted if all values are zero.

If a is nonzero, active should be set to "1".

Response Attributes

  • status: Always "ok".

pingエレメント
以前のアップデートチェックからの、このアプリケーションの活動レベルの報告

リクエストアトリビュート
  • active: もしアプリが前回のレポートからアクティブだった場合は"1"。そうでなければ"0"
  • a: もしある場合、アプリは前回のレポートからアクティブだった。値は前回のアクティブなレポートからの日数。もしアクティブでない場合は、アトリビュートは省かれる
  • r: アプリがある場合、アプリが最後に報告された時からの日数。
aとrのどちらも、特別な値"-1"は新規インストールを示します。値が"0"の場合、任意のアトリビュートが省略されても良い; 全ての値がゼロである場合、要素全体を省略してもよい.

ゼロではない場合は、アクティブでは"1"を設定する必要があります。

レスポンスアトリビュート
  • status : いつもOK

data Element

This element provides a way to pass data to the application installer. There can be many data elements in a request. In general, this data represents application configuration or some kind of run time parameter that the application installer needs, for a particular installation context. This data is less trusted in the sense that it is usually provided by 3rd parties and it is more vulnerable to attacks, such as MITM. The application code must take steps to harden and sanitize the data before use.

Currently, two mechanisms are provided here: install and untrusted.

In the case of install, the metainstaller or install command line includes an insecure data index, which corresponds to a specific blob of install data on the server. The client securely requests the data for this index from the server using the data element.

Additional arbitrary data can be passed by using untrusted. The source for the untrusted is usually a metainstaller tag, which is subsequently passed to the Google Update run time as an extra argument of the command line. Upon receiving the untrusted in the request, the server is expected do to additional validation. The server will reply with a status of "error-invalidargs" if the untrusted is invalid for any reason.

Request Attributes

  • name: A collection specifier (must be alphanumeric; "install" and "untrusted" are currently implemented).
  • index: For "install", the requested element of the collection (must be alphanumeric).

For "untrusted", the data itself is sent as a text element of the data element.

Response Attributes

  • status: One of:
    • "ok": Data blob included.
    • "error-invalidargs": the name, index, or untrusteddata were not alphanumeric or were invalid for any reason.
    • "error-nodata": the named collection or index was not found.
  • name: The collection specifier; could be "install" or "untrusted" respectively.
  • index: For "install", the requested element of the collection.

For "install", the data itself is returned as a text element child of the data element. There is no data returned for "untrusted".


dataエレメント
このエレメントはアプリケーションインストーラへデータを引き渡す方法を提供します。1リクエストには多くのデータエレメントが存在することができます。一般的に、このデータは、特定のインストールコンテキストのために、アプリケーション構成やアプリケーションインストーラが必要な実行時パラメータのようなものを表します。このデータはたいてい3rdパーティーによって与えられるシーンの中で低い信頼性で、中間者攻撃のようなアタックにはより脆弱です。アプリケーションコードは、使用する前に、データのセキュリティを強化し、サニタイズするための措置をとる必要があります。

現在、ここでは2つの仕組みが提供されています: インストールと、信頼できないリクエストです。

インストールの場合、メタインストーラかインストールコマンドラインが、サーバーにインストールするデータの特定のバイナリに対応した安全ではないデータインデックスを含みます。クライアントは、データエレメントを使用しているサーバーから、このインデックスのためのデータを安全にリクエストします。

追加の任意のデータは信頼できない通信によって引き渡されます。信頼できないソースはたいてい、その後、コマンドラインの実行時の追加引数としてGoogleUpdateに引き渡される、メタインストーラータグです。信頼できないリクエストを受信すると、サーバーは追加の確認を行うことを期待されている。もし信頼できないリクエストがどんな理由であれ有効でない場合は、サーバーは"error-invalidargs"ステータスを返します。

リクエストアトリビュート
  • status : 次のうちの1つ
    • "ok" : データバイナリが含まれていた
    • "error-invalidargs" : 名前、インデックス、または信頼できないデータが英数字でなかった場合や、何か有効でない理由があった。
    • "error-nodata" : 名前の付けられたコレクションかインデックスが見つからなかった。
  • name : コレクション指定子; "install"や"untrusted"のそれぞれにできる。
  • index : "install"のために、要求されたコレクション要素。
"install"では、データ自身はdataエレメントの子のテキストエレメントとして返ります。"untrusted"では何のデータも返りません。

unknown Element

If the client sends an unrecognized child element of the app element, the server may respond with an "unknown" element in the corresponding position of the response. It will always have a status attribute with a value of "error". (This is meant to maintain the structure of the response, which mirrors the app and action elements of the request.)


未知のエレメント
もしクライアントが、appエレメントの認識されていない子エレメントを送った場合、サーバーは、レスポンスの位置に対応した場所に、"unknown"エレメントを送り返す。それはいつも"error"の値のステータスアトリビュートを持っています。(これはリクエストのappとactionエレメントに酷似したレスポンスの構造を維持することを意味します)

UpdateCheck Response Elements

When an updatecheck response element has a status of "ok", the following child elements are included, describing the method for performing the update check.


updatecheckが"ok"のステータスで返るとき、アップデートチェックを行うための方法について述べられている、次の子エレメントが含まれている。

urls Element

Describes a set of locations where installer binaries can be downloaded.

Contains no attributes. Contains one or more url child elements describing URLs prefixes where a package can be downloaded.

url Element

Contains a URL fragment where packages in the following manifest element can be found. A complete URL to each installer binary may be formed by appending the filename in a package element to this URL fragment.

The URL fragment is stored as a text child element.

manifest Element

Describes the files needed to install the new version of an application, and the actions needed to be taken with those files.

Request Attributes

N/A

Response Attributes

  • version (optional): Contains the version that this manifest should deliver when finished.

The manifest element should contain two child elements - one packages element and one actions element.

urls エレメント
インストーラバイナリがダウンロードできた場所のセットを述べる。
アトリビュートは含んでいません。パッケージがダウンロードできるURLプレフィクスを述べる、1つかそれ以上のURLの子エレメントが含まれています。

urlエレメント
次のマニフェストエレメントの中で、どこにパッケージがあるかを見つけることができる、URLフラグメントが含まれています。各インストーラバイナリへの完全なURLは、次のURLフラグメントにpackageエレメントのファイル名を追加することによって形成することができる。

URLフラグメントは子textエレメントとして保存されます。

manifestエレメント
アプリケーションの新しいバージョンをインストールするために必要なファイル、およびそれらのファイルで撮影するために必要なアクションについて説明します。
リクエストアトリビュート
  • なし
レスポンスアトリビュート
  • version(オプション) : 終了したら、このマニフェストが届けるべきバージョンが含まれます。
manifestエレメントは2つの子エレメントを含んでいる必要があります。1つはpackagesエレメント、もう1つはactionsエレメントです。


packages Element

Describes the set of files needed to install the application.

Contains no attributes. Contains one or more package child elements.

package Element

Describes a single file needed to install the application.

Request Attributes

N/A

Response Attributes

  • name: Contains a filename to download. Omaha will sequentially attempt to build a URL by appending this name to each url in the urlselement and download it.
  • required: Contains "true" or "false". Denotes whether or not the file is required for the install to succeed.
  • size: Contains the size in bytes of the installer binary.
  • hash: Contains the SHA-1 hash of the installer binary, encoded in base64.

packagesエレメント

インストールアプリケーションのために必要なファイルのセットを記述します。
アトリビュートは含んでいません。1つかそれ以上の子エレメントを含みます。

packageエレメント

アプリケーションのインストールに必要な1つのファイルを記述します。

リクエストアトリビュート
  • なし
レスポンスエレメント
  • name : ダウンロードのためのファイル名を含みます。omahaは連続して、この名前をurlselementのそれぞれのURLに追加することによってURLの構築を連続して試み、それをダウンロードします
  • required : "true"か"false"を含みます。成功するために、インストール用のファイルが必要であるかどうかを示す。
  • size : インストールバイナリのサイズを含みます
  • hash : base64でエンコードされたインストールバイナリのSHA-1ハッシュを含みます

actions Element

Describes the actions to perform to install the application once all required files in the packages element have been successfully downloaded.

Contains no attributes. Contains one or more action child elements.

action Element

Describes a single action to perform as part of the install process.

Request Attributes

N/A

Response Attributes

  • event: Contains a fixed string denoting when this action should be run. One of:
    • "preinstall"
    • "install"
    • "postinstall"
    • "update"
  • run (optional): The name of an installer binary to run. (Typically, this binary was specified to be downloaded in the prior packages element.)
  • arguments (optional): Arguments to be passed to that installer binary.
  • successurl (optional): A URL to be opened using the system's default web browser on a successful install.
  • terminateallbrowsers (optional): If "true", close all browser windows before starting the installer binary.
  • successsaction (optional): Contains a fixed string denoting some action to take in response to a successful install. One of:
    • "default"
    • "exitsilently"
    • "exitsilentlyonlaunchcmd"

actionsエレメント
1度アプリケーション、ダウンロードに成功したpackagesエレメントにある、必要な全てのファイル、をインストールするためのactionを記述します。(訳怪しい)

アトリビュートは含んでいません。1つかそれ以上の子actionエレメントを含みます。

actionエレメント
インストールプロセスの一部として行う1つのアクションを記述します
リクエストアトリビュート
  • なし
レスポンスアトリビュート
  • event : アクションを走らせるべき時を意味する、固定の文字列。次のうちの1つ
    • "preinstall"
    • "Install"
    • "postinstall"
    • "update"
  • run (オプション) : インストールバイナリを走らせるための名前。(通常は、このバイナリは優先されるpackagesエレメントの中でダウンロードされるように指定されたものです)
  • arguments(オプション) : インストーラバイナリに引き渡される引数
  • successurl(オプション) : 成功したインストールの、システムのデフォルトウェブブラウザを使用して開くURL
  • terminateallbrowser(オプション) : もし"true"なら、インストーラバイナリを開始する前に全てのブラウザウインドウを閉じる
  • successaction(オプション) : インストールの成功のためのレスポンスを取り入れるための、いくつかのアクションを記述した、固定の文字列を含む。次のうちの1つ
    • "default"
    • "exitsilently"
    • "exitsilentlyonlaunchcmd"

Advisory HTTP Headers

The Windows Client currently attaches some custom HTTP headers to the request; they are mostly provided to aid the server in statistics generation. The client may send none, some, or all of them as appropriate for the current request.


補助的なHTTPヘッダー
Windowsクライアントは現在リクエストにいくつかのカスタムHTTPヘッダを付け加えています。それらのほとんどは統計の生成中にサーバーを補助するために与えられます。クライアントは何も送らないかもしれないし、現在のリクエストのためにそれらすべてを必要に応じて送るかもしれない。

Network Diagnostics Headers

If any of these headers are present, they imply that the network request was unsuccessful in the past and has been retried at least once.

  • X-Retry-Count -- Contains the total number of times that this network request has been retried.
  • X-Last-HR -- Contains the HRESULT error code returned from NetworkRequestImpl::DoSendHttpRequest() for the previous attempt.
  • X-Last-HTTP-Status-Code -- Contains the HTTP status code, if any, that we received for the previous attempt.
  • X-Proxy-Retry-Count -- If this header is present, it means that the request is being sent via at least one proxy that required authentication. Contains the number of times that we've received a HTTP 407 (Proxy Authentication Required) status code in the process of sending this request.
  • X-Proxy-Manual-Auth -- If this header is present, it means that this request is being sent through at least one proxy that required authentication and that Omaha had no cached credentials and displayed a UI to prompt the user. The header's value is always 1.

ネットワーク診断ヘッダ
これらのヘッダが少しでも現れる場合、これらは、過去のネットワークリクエストが失敗し、少なくとも1度は再試行されたことを示します。
  • X-Retry-Count -- ネットワークリクエストが再試行された合計回数を含む
  • X-Last-HR -- 前回の試行のNetworkRequestImpl::DoSendHttpRequest()から返ってきたHRESULTエラーコードを含みます。
  • X-Last-HTTP-Status-Code -- もしある場合は、我々が前回の試行で受け取った、HTTPステータスコードを含みます。
  • X-Proxy-Retry-Count -- もしヘッダがある場合は、認証に必要な、最低1つのプロキシを通じて送られたリクエストであることを意味します。このリクエストを送る過程で我々が受け取ったHTTP 407ステータスコード(プロキシ認証失敗)の回数です。
  • X-Proxy-Manual-Auth -- もしこのヘッダがある場合は、このリクエストが、認証に必要な、最低1つのプロキシを通じて送られたリクエストであり、さらに、Omahaはキャッシュされた資格を何も持っておらず、ユーザに指示するためUIを表示していたことを示します。ヘッダの値は常に1です。

Persisted Ping Headers

There may be cases where Omaha completes an update/install, but the network connection fails during the install, and the event ping notifying the server of the success/failure cannot be sent. (This is particularly common on laptops with wireless connections.) In this case, the client will serialize the event ping to the Registry, and attempt to resend it at a later date when the network connection is available again.

  • X-RequestAge -- If this header is present, it means that this request is an event ping that was persisted and is now being re-sent. The value is the age in seconds between the current time and the time at which the ping request was originally attempted.

持続pingヘッダー
Omahaが1つのアップデート/インストールを完了するケースがあるかもしれないが、しかしインストールの間にネットワーク接続失敗し、成功/失敗のサーバーへのイベントping通知が送れない。この場合、クライアントはイベントpingをレジストリにシリアライズし、ネットワーク接続が再び利用できるようになったときに、後日再送信を試みる。
  • X-RequestAge -- もしこのヘッダがある場合、このリクエストが持続イベントpingであり、現在も再送信していることを意味する。値は現在の時間と、もともと試されたPingリクエストの時間の間の秒数です。

Security Headers

The response must be secure: the client must be sure the response data blob came from Google and that it was not tampered with. This is done by either

  • using SSL
  • using the secure Client-Update Protocol (CUP)

If the client elects to use SSL, no further integrity checking is needed. If CUP is used, the following HTTP headers and parameters will be added, which allow a signature to be supplied by the server and verified by the client. The CUP design document describes the protocol in detail.


セキュリティーヘッダー
返信は安全でなければなりません: クライアントはGoogleから来たデータバイナリの返信を確認しなければならず、そして、それに不正があってはならない。これらのうちのどれかが行われます
  • SSLの使用
  • セキュアなクライアントアップデートプロトコル(CPU)の使用
もしクライアントがSSLの使用を選択した場合、それ以上の整合性チェックは必要ありません。もしCUPを使う場合、次のHTTPヘッダーと、サーバーによって与えられた署名とクライアントによる検証を許可するパラメータが、追加されます。CPU設計ドキュメントは詳細にプロトコルを記載しています。

CUP Request

  • w (URL parameter): Encodes a proposed private key. Provides nonce for protection against replay in the signed response.
  • If-Match (HTTP header): Signature that proves the client knows its own private key.
  • Cookie (HTTP header): (optional) Encrypted copy of the client's private verification key. (Not related to any browser cookie.)

CUP Response

  • ETag (HTTP header): Response signature
  • Set-Cookie (HTTP header): (optional) Encrypted copy of the client's private key, for the client to send in the next request. (Not related to any browser cookie.)


Implementation details

The server is expected to return a 400 response when the body of the request is empty. The body of the response will contain the reason for the the 'bad request', for instance, the server could not parse the request.


実装詳細

サーバはリクエストのbodyが空だったとき400を返すことが期待されています。レスポンスのbodyは"bad request"のための理由、例えば、サーバーはリクエストをパースできなかったなど、を含みます


Comments