apksigner

버전 24.0.3 이상의 Android SDK Build Tools에서 제공하는 apksigner 도구를 사용하면, APK에 서명하고 APK가 지원하는 모든 버전의 Android 플랫폼에서 APK의 서명이 인증되는지 확인할 수 있습니다. 이 페이지는 도구 사용에 관한 간단한 가이드를 제공하며 도구가 지원하는 다양한 명령줄 옵션에 관한 참조로 사용됩니다. apksigner 도구를 사용하여 APK에 서명하는 방법에 관한 자세한 내용은 앱 서명 가이드를 참조하세요.

주의: apksigner를 사용하여 APK에 서명한 후 APK를 추가로 변경하면 APK의 서명이 무효화됩니다. 따라서 APK에 서명하기 전에 zipalign과 같은 도구를 사용해야 합니다.

사용

APK 서명

apksigner 도구를 사용하여 APK에 서명하는 구문은 다음과 같습니다.

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

apksigner 도구를 사용하여 APK에 서명할 때 서명자의 비공개 키와 인증서를 제공해야 합니다. 이 정보를 두 가지 방법으로 포함할 수 있습니다.

  • --ks 옵션을 사용하여 키 저장소 파일을 지정합니다.
  • --key--cert 옵션을 각각 사용하여 비공개 키 파일과 인증서 파일을 별도로 지정합니다. 비공개 키 파일은 PKCS #8 형식, 인증서 파일은 X.509 형식을 사용해야 합니다.

일반적으로 하나의 서명자만 사용하여 APK에 서명합니다. 여러 서명자를 사용하여 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 도구가 지원하는 각 명령어의 옵션 집합이 포함되어 있습니다.

Sign 명령어

일반 옵션

다음 옵션은 서명자에 적용할 기본 설정을 지정합니다.

--out <apk-filename>
서명된 APK를 저장할 위치입니다. 이 옵션을 명시적으로 제공하지 않으면 APK 패키지가 내부에서 서명되어 입력 APK 파일을 덮어씁니다.
--min-sdk-version <integer>
apksigner가 APK의 서명을 확인하는 데 사용하는 가장 낮은 Android 프레임워크 API 레벨입니다. 값이 클수록 도구가 앱에 서명할 때 더 강력한 보안 매개변수를 사용할 수 있지만 최신 버전의 Android를 실행하는 기기에서는 APK의 가용성이 제한됩니다. 기본적으로 apksigner는 앱 manifest 파일에서 minSdkVersion 속성의 값을 사용합니다.
--max-sdk-version <integer>
apksigner가 APK의 서명을 확인하는 데 사용하는 가장 높은 Android 프레임워크 API 레벨입니다. 기본적으로 이 도구는 가능한 가장 높은 API 레벨을 사용합니다.
--v1-signing-enabled <true | false>
apksigner가 기존의 JAR 기반 서명 체계를 사용하여 지정된 APK 패키지에 서명하는지 여부를 결정합니다. 기본적으로 이 도구는 --min-sdk-version--max-sdk-version의 값을 사용하여 이 서명 체계의 적용 시기를 결정합니다.
--v2-signing-enabled <true | false>
apksignerAPK Signature Scheme v2를 사용하여 지정된 APK 패키지에 서명하는지 여부를 결정합니다. 기본적으로 이 도구는 --min-sdk-version--max-sdk-version의 값을 사용하여 이 서명 체계의 적용 시기를 결정합니다.
-v, --verbose
상세 출력 모드를 사용합니다.

서명자 단위 옵션

다음 옵션은 특정 서명자의 구성을 지정합니다. 하나의 서명자만 사용하여 앱에 서명하는 경우 이러한 옵션이 필요하지 않습니다.

--next-signer <signer-options>
서명자마다 서로 다른 일반 옵션을 지정하기 위해 사용합니다.
--v1-signer-name <basename>
현재 서명자의 JAR 기반 서명을 구성하는 파일의 기본 이름입니다. 기본적으로 apksigner는 이 서명자에 키 저장소의 키 별칭 또는 키 파일의 기본 이름을 사용합니다.

키 및 인증서 옵션

다음 옵션은 서명자의 비공개 키 및 인증서를 지정합니다.

--ks <filename>
서명자의 비공개 키 및 인증서 체인은 지정된 자바 기반 키 저장소 파일에 있습니다. 파일 이름이 "NONE"으로 설정되면, 일부 PKCS #11 키 저장소의 경우와 같이 키와 인증서를 포함하는 키 저장소에 지정된 파일이 필요하지 않습니다.
--ks-key-alias <alias>
키 저장소 내에서 서명자의 비공개 키 및 인증서 데이터를 나타내는 별칭의 이름입니다. 서명자와 관련된 키 저장소에 여러 키가 포함된 경우 이 옵션을 지정해야 합니다.
--ks-pass <input-format>

서명자의 비공개 키 및 인증서가 포함된 키 저장소의 비밀번호입니다. 키 저장소를 열려면 비밀번호를 제공해야 합니다. apksigner 도구는 다음 형식을 지원합니다.

  • pass:<password> – 비밀번호가 apksigner sign 명령어의 나머지와 함께 인라인으로 제공됩니다.
  • env:<name> – 비밀번호가 지정된 환경 변수에 저장됩니다.
  • file:<filename> – 비밀번호가 지정된 파일에서 단일 줄로 저장됩니다.
  • stdin – 비밀번호가 표준 입력 스트림에서 단일 줄로 제공됩니다. --ks-pass의 기본 동작입니다.

참고: 같은 파일에 여러 비밀번호를 포함하는 경우 각 비밀번호를 별도의 줄에 지정하세요. APK 서명자를 지정한 순서에 따라 apksigner 도구가 비밀번호를 서명자와 연결합니다. 서명자에 두 개의 비밀번호를 제공한 경우 apksigner는 첫 번째를 키 저장소 비밀번호로 해석하고 두 번째를 키 비밀번호로 해석합니다.

--pass-encoding <charset>
비 ASCII 문자를 포함하는 비밀번호를 처리하려고 시도할 때 지정된 문자 인코딩(예: ibm437 또는 utf-8)을 포함합니다.

Keytool은 종종 콘솔의 기본 문자 집합을 사용해 비밀번호를 변환하여 키 저장소를 암호화합니다. 기본적으로 apksigner는 유니코드 형식, JVM 기본 문자 집합을 사용하여 인코딩된 형식, 그리고 Java 8 및 이전 버전에서는 콘솔의 기본 문자 집합을 사용하여 인코딩된 형식 등 여러 비밀번호 형식을 사용하여 복호화를 시도합니다. 자바 9에서 apksigner는 콘솔의 문자 집합을 감지할 수 없습니다. 따라서 비 ASCII 비밀번호를 사용하는 경우 --pass-encoding을 지정해야 할 수도 있습니다. keytool이 다른 OS 또는 다른 언어에서 작성한 키 저장소와 함께 이 옵션을 지정해야 할 수도 있습니다.

--key-pass <input-format>

서명자의 비공개 키의 비밀번호입니다. 비공개 키가 비밀번호로 보호되는 경우 필요합니다. apksigner 도구는 다음 형식을 지원합니다.

  • pass:<password> – 비밀번호가 apksigner sign 명령어의 나머지와 함께 인라인으로 제공됩니다.
  • env:<name> – 비밀번호가 지정된 환경 변수에 저장됩니다.
  • file:<filename> – 비밀번호가 지정된 파일에서 단일 줄로 저장됩니다.
  • stdin – 비밀번호가 표준 입력 스트림에서 단일 줄로 제공됩니다. --key-pass의 기본 동작입니다.

참고: 같은 파일에 여러 비밀번호를 포함하는 경우 각 비밀번호를 별도의 줄에 지정하세요. APK 서명자를 지정한 순서에 따라 apksigner 도구가 비밀번호를 서명자와 연결합니다. 서명자에 두 개의 비밀번호를 제공한 경우 apksigner는 첫 번째를 키 저장소 비밀번호로 해석하고 두 번째를 키 비밀번호로 해석합니다.

--ks-type <algorithm>
서명자의 비공개 키 및 인증서가 포함된 키 저장소와 관련된 유형 또는 알고리즘입니다. 기본적으로 apksigner는 보안 속성 파일에 keystore.type 상수로 정의된 유형을 사용합니다.
--ks-provider-name <name>
서명자의 키 저장소 구현을 요청할 때 사용할 JCA 제공자의 이름입니다. 기본적으로 apksigner는 우선순위가 가장 높은 제공자를 사용합니다.
--ks-provider-class <class-name>
서명자의 키 저장소 구현을 요청할 때 사용할 JCA Provider의 정규화된 클래스 이름입니다. 이 옵션을 --ks-provider-name 대신 사용할 수 있습니다. 기본적으로 apksigner--ks-provider-name 옵션으로 지정된 제공자를 사용합니다.
--ks-provider-arg <value>
JCA Provider 클래스의 생성자용 인수로 전달할 문자열 값입니다. 클래스 자체는 --ks-provider-class 옵션으로 정의됩니다. 기본적으로 apksigner는 클래스의 0 인수 생성자를 사용합니다.
--key <filename>
서명자의 비공개 키가 포함된 파일 이름입니다. 이 파일은 PKCS #8 DER 형식을 사용해야 합니다. 키가 비밀번호로 보호되는 경우 apksigner는 표준 입력을 사용하여 비밀번호를 제공하도록 요청합니다. 단, --key-pass 옵션을 사용하여 다른 입력 형식을 지정하지 않은 경우에 한합니다.
--cert <filename>
서명자의 인증서 체인이 포함된 파일의 이름입니다. 이 파일은 X.509 PEM 또는 DER 형식을 사용해야 합니다.

Verify 명령어

--print-certs
APK의 서명 인증서에 관한 정보를 표시합니다.
--min-sdk-version <integer>
apksigner가 APK의 서명을 확인하는 데 사용하는 가장 낮은 Android 프레임워크 API 레벨입니다. 값이 클수록 도구가 앱에 서명할 때 더 강력한 보안 매개변수를 사용할 수 있지만 최신 버전의 Android를 실행하는 기기에서는 APK의 가용성이 제한됩니다. 기본적으로 apksigner는 앱 manifest 파일에서 minSdkVersion 속성의 값을 사용합니다.
--max-sdk-version <integer>
apksigner가 APK의 서명을 확인하는 데 사용하는 가장 높은 Android 프레임워크 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
    

두 개의 키를 사용하여 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
    

APK의 서명이 Android 4.0.3(API 레벨 15) 이상에서 유효한 것으로 확인되는지 검토합니다.

    $ 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