apksigner

Android SDK Build Tools のリビジョン 24.0.3 以上で利用可能な apksigner ツールを使用すると、APK に署名し、その APK がサポートする Android プラットフォームのすべてのバージョンで APK の署名が正常に検証されることを確認できます。このページは、このツールの使い方について簡単に説明するガイドであり、このツールがサポートするさまざまなコマンドライン オプションのリファレンスとしても参照できます。apksigner ツールを使って APK に署名する方法についての全詳細は、アプリの署名のガイドをご覧ください。

注意: apksigner を使用して APK に署名した後で APK にさらに変更を加えると、APK の署名は無効になります。そのため、zipalign のようなツールは APK に署名する前に実行する必要があります。

使い方

APK に署名する

apksigner ツールを使用して APK に署名するための構文は次のとおりです。

    apksigner sign --ks keystore.jks |
      --key key.pk8 --cert cert.x509.pem
      [signer_options] app-name.apk

apksigner ツールを使用して APK に署名する場合、その署名者の秘密鍵と証明書を指定する必要があります。この情報を指定する方法は 2 つあります。

  • --ks オプションを使用してキーストア ファイルを指定します。
  • --key オプションと --cert オプションを使用して、それぞれ秘密鍵ファイルと証明書ファイルを別個に指定します。秘密鍵ファイルには PKCS＃8 形式を使用し、証明書ファイルには X.509 形式を使用する必要があります。

通常は 1 つの APK の署名に指定する署名者は 1 人です。複数の署名者を指定して APK に署名する必要がある場合は、--next-signer オプションを使って、各署名者に適用する全般オプションのセットを区切ります。

    apksigner sign [signer_1_options] --next-signer [signer_2_options] app-name.apk

APK の署名を検証する

サポートしているプラットフォーム上で APK の署名が正常に検証されるかどうかを確かめるには、次の構文を使用します。

    apksigner verify [options] app-name.apk

署名鍵をローテートする

署名証明書の系列、つまり署名の新しいシーケンスをローテートするには、次の構文を使用します。

    $ apksigner rotate --in /path/to/existing/lineage \
      --out /path/to/new/file \
      --old-signer --ks old-signer-jks \
      --new-signer --ks new-signer-jks

オプション

apksigner ツールがサポートする各コマンドのオプションのセットを、次のリストに示します。

署名コマンド

全般オプション

以下のオプションでは、署名者に適用する基本設定を指定します。

--out <apk-filename>
署名した APK を保存する場所です。このオプションを明示的に指定しない場合、APK パッケージはその場で署名され、入力 APK ファイルが上書きされます。
--min-sdk-version <integer>
APK の署名が検証されることを確認するために apksigner が使用する Android Framework API の最低レベルです。値が大きいほど、ツールでのアプリの署名に使用できるセキュリティ パラメータの強度が高くなりますが、APK を利用できるデバイスは Android のバージョンが新しいものに限定されます。デフォルトでは、apksigner はアプリのマニフェスト ファイル内の minSdkVersion 属性の値を使用します。
--max-sdk-version <integer>
APK の署名が検証されることを確認するために apksigner が使用する Android Framework API の最高レベルです。デフォルトでは、このツールで可能な API の最高レベルを使用します。
--v1-signing-enabled <true | false>
指定した APK パッケージに apksigner が署名する際に、従来の JAR ベースの署名スキームを使用するかどうかを指定します。デフォルトでは、このツールは --min-sdk-version と --max-sdk-version の値から、この署名スキームをいつ適用するかを決めます。
--v2-signing-enabled <true | false>
指定した APK パッケージに apksigner が署名する際に、APK 署名スキーム v2 を使用するかどうかを指定します。デフォルトでは、このツールは --min-sdk-version と --max-sdk-version の値から、この署名スキームをいつ適用するかを決めます。
-v、--verbose
詳細出力モードを使用します。

署名者ごとのオプション

以下のオプションでは、1 人の特定の署名者の設定を指定します。1 人の署名者だけがアプリに署名する場合、これらのオプションは必要ありません。

--next-signer <signer-options>
署名者ごとに異なる全般オプションを指定するのに使用します。
--v1-signer-name <basename>
現在の署名者の JAR ベース署名を構成するファイルのベース名です。デフォルトでは、apksigner はキーストアのキーエイリアスか、この署名者のキーファイルのベース名を使用します。

鍵と証明書のオプション

以下のオプションでは、署名者の秘密鍵と証明書を指定します。

--ks <filename>
指定する Java ベースのキーストア ファイル内に、署名者の秘密鍵と証明書チェーンがあります。ファイル名を "NONE" に設定する場合、その鍵と証明書を含むキーストアにはファイルの指定が不要です。これは、一部の PKCS #11 が該当します。
--ks-key-alias <alias>
キーストア内で、その署名者の秘密鍵と証明書のデータを示すエイリアス名です。署名者に関連付けられているキーストアに複数の鍵が含まれている場合、このオプションを指定する必要があります。
--ks-pass <input-format>

署名者の秘密鍵と証明書が含まれているキーストアのパスワードです。キーストアを開くためにパスワードを指定する必要があります。apksigner ツールでは、以下の形式がサポートされています。

  • pass:<password> - apksigner sign コマンドの他の部分と一緒にパスワードをインラインで指定します。
  • env:<name> - 指定する環境変数にパスワードを保存します。
  • file:<filename> - 指定するファイル内にパスワードを 1 行で保存します。
  • stdin - 標準の入力ストリーム内にパスワードを 1 行で指定します。これは --ks-pass のデフォルトです。

注: 同じファイルに複数のパスワードを含める場合は、別々の行に指定します。apksigner ツールは、署名者が指定された順序に基づいて、パスワードと APK の署名者を関連付けます。1 人の署名者に 2 つのパスワードを指定した場合、apksigner は最初のパスワードをキーストアのパスワード、2 番目のパスワードを鍵のパスワードと解釈します。

--pass-encoding <charset>
非 ASCII 文字が含まれるパスワードを処理する際の文字エンコード（ibm437、utf-8 など）を指定します。

Keytool は多くの場合、コンソールのデフォルトの文字セットを使用してパスワードを変換することにより、キーストアを暗号化します。デフォルトでは、apksigner はパスワードの複数の形式を使って復号を試みます。使用するのは、Unicode 形式、JVM のデフォルト文字セットを使ってエンコードされた形式、および Java 8 以前でコンソールのデフォルト文字セットを使用してエンコードされた形式です。Java 9 では、apksigner はコンソールの文字セットを検出できません。そのため、非 ASCII パスワードを使用する場合は --pass-encoding の指定が必要になることがあります。また、異なる OS 上または異なるロケールで Keytool が作成したキーストアの場合も、このオプションの指定が必要になることがあります。

--key-pass <input-format>

署名者の秘密鍵のパスワードです。これは、秘密鍵がパスワードで保護されている場合に必要です。apksigner ツールでは、以下の形式がサポートされています。

  • pass:<password> - apksigner sign コマンドの他の部分と一緒にパスワードをインラインで指定します。
  • env:<name> - 指定する環境変数にパスワードを保存します。
  • file:<filename> - 指定するファイル内にパスワードを 1 行で保存します。
  • stdin - 標準の入力ストリーム内にパスワードを 1 行で指定します。これは --key-pass のデフォルトです。

注: 同じファイルに複数のパスワードを含める場合は、別々の行に指定します。apksigner ツールは、署名者が指定された順序に基づいて、パスワードと APK の署名者を関連付けます。1 人の署名者に 2 つのパスワードを指定した場合、apksigner は最初のパスワードをキーストアのパスワード、2 番目のパスワードを鍵のパスワードと解釈します。

--ks-type <algorithm>
署名者の秘密鍵と証明書が含まれているキーストアに関連付けられているタイプまたはアルゴリズムです。デフォルトでは apksigner は、セキュリティ プロパティ ファイル内の keystore.type 定数として定義されているタイプを使用します。
--ks-provider-name <name>
署名者のキーストアの実装をリクエストするときに使用する JCA プロバイダの名前です。デフォルトでは apksigner は優先順位の最も高いプロバイダを使用します。
--ks-provider-class <class-name>
署名者のキーストアの実装をリクエストするときに使用する JCA プロバイダの完全修飾クラス名です。このオプションは --ks-provider-name の代わりとなります。デフォルトでは apksigner は、--ks-provider-name オプションで指定されたプロバイダを使用します。
--ks-provider-arg <value>
JCA プロバイダ クラスのコンストラクタの引数として渡す文字列です。クラスそのものは --ks-provider-class オプションを使って定義します。デフォルトでは apksigner はそのクラスの 0 引数コンストラクタを使用します。
--key <filename>
署名者の秘密鍵を含むファイルの名前です。このファイルは PKCS＃8 DER 形式を使用する必要があります。鍵がパスワードで保護されている場合、--key-pass オプションで別の種類の入力形式が指定されていなければ、apksigner は標準入力を使ってパスワードの入力を求めます。
--cert <filename>
署名者の証明書チェーンが含まれるファイルの名前です。このファイルは、X.509 PEM 形式または DER 形式を使用する必要があります。

検証コマンド

--print-certs
APK の署名証明書に関する情報を表示します。
--min-sdk-version <integer>
APK の署名が検証されることを確認するために apksigner が使用する Android Framework API の最低レベルです。値が大きいほど、ツールでのアプリの署名に使用できるセキュリティ パラメータの強度が高くなりますが、APK を利用できるデバイスは Android のバージョンが新しいものに限定されます。デフォルトでは、apksigner はアプリのマニフェスト ファイル内の minSdkVersion 属性の値を使用します。
--max-sdk-version <integer>
APK の署名が検証されることを確認するために apksigner が使用する Android Framework API の最高レベルです。デフォルトでは、このツールで可能な API の最高レベルを使用します。
-v、--verbose
詳細出力モードを使用します。
-Werr
警告をエラーとして扱います。

例

APK に署名する

キーストア内の唯一の鍵である release.jks を使って、APK に署名します。

    $ apksigner sign --ks release.jks app.apk

別々のファイルに保存されている秘密鍵と証明書を使って、APK に署名します。

    $ apksigner sign --key release.pk8 --cert release.x509.pem app.apk

2 つの鍵を使って、APK に署名します。

    $ apksigner sign --ks first-release-key.jks --next-signer --ks second-release-key.jks app.apk

APK の署名を検証する

APK がサポートするすべての Android プラットフォームで、APK の署名の有効性が検証されると想定できるかどうかを確認します。

    $ apksigner verify app.apk

Android 4.0.3（API レベル 15）以上で APK の署名の有効性が検証されると想定できるかどうかを確認します。

    $ apksigner verify --min-sdk-version 15 app.apk

署名鍵をローテートする

鍵のローテーションをサポートする署名証明書の系列を有効にします。

    $ apksigner rotate --out /path/to/new/file --old-signer \
        --ks release.jks --new-signer --ks release2.jks

署名鍵を再度ローテートします。

    $ apksigner rotate --in /path/to/existing/lineage \
      --out /path/to/new/file --old-signer --ks release2.jks \
      --new-signer --ks release3.jks