apksigner

버전 24.0.3 이상의 Android SDK 빌드 도구에서 제공하는 apksigner 도구를 사용하면 APK에 서명하고 그 APK가 지원하는 모든 버전의 Android 플랫폼에서 APK의 서명이 인증되는지 확인할 수 있습니다.

이 페이지는 도구 사용에 관한 간단한 가이드를 제공하며 도구에서 지원하는 다양한 명령줄 옵션에 관한 참조로 사용됩니다. apksigner 도구를 사용하여 APK에 서명하는 방법에 관한 자세한 내용은 앱 서명을 참고하세요.

주의: apksigner를 사용하여 APK에 서명한 후 APK를 추가로 변경하면 APK의 서명이 무효화됩니다. zipalign을 사용하여 APK를 정렬하는 경우 APK에 서명하기 전에 사용합니다.

사용

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 도구에서 지원하는 각 명령어의 옵션 집합이 포함되어 있습니다.

서명 명령어

apksigner 서명 명령어에는 다음과 같은 옵션이 있습니다.

일반 옵션

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

--out <apk-filename>
서명된 APK를 저장할 위치입니다. 이 옵션을 명시적으로 제공하지 않으면 APK 패키지가 내부에서 서명되어 입력 APK 파일을 덮어씁니다.
--min-sdk-version <integer>
apksigner가 APK의 서명이 인증되는지 확인하는 데 사용하는 가장 낮은 Android 프레임워크 API 수준입니다. 값이 클수록 도구가 앱에 서명할 때 더 강력한 보안 매개변수를 사용할 수 있지만 최신 버전의 Android를 실행하는 기기에서는 APK의 가용성이 제한됩니다. 기본적으로 apksigner는 앱 매니페스트 파일의 minSdkVersion 속성 값을 사용합니다.
--max-sdk-version <integer>
apksigner가 APK의 서명이 인증되는지 확인하는 데 사용하는 가장 높은 Android 프레임워크 API 수준입니다. 기본적으로 이 도구는 가능한 가장 높은 API 수준을 사용합니다.
--rotation-min-sdk-version <integer>
APK의 순환된 서명 키의 가장 낮은 API 수준은 APK의 서명을 생성하는 데 사용해야 합니다. APK의 원래(순환되지 않은) 서명 키는 모든 이전 플랫폼 버전에 사용됩니다. 기본적으로, Android 13(API 수준 33) 이상을 실행하는 기기에서 지원되는 순환된 서명 키는 v3.1 서명 블록과 함께 사용됩니다.

참고: Android 12L(API 수준 32) 이하를 실행하는 기기에서 앱이 순환된 서명 키로 서명되었다면 --rotation-min-sdk-version 28을 사용하여 Android 9(API 수준 28)의 순환된 서명 키로 앱에 계속 서명해야 합니다.

--v1-signing-enabled <true | false>
apksigner가 기존 JAR 기반 서명 체계를 사용하여 지정된 APK 패키지에 서명하는지 여부를 결정합니다. 기본적으로 이 도구는 --min-sdk-version 및 --max-sdk-version의 값을 사용하여 이 서명 체계의 적용 시점을 결정합니다.
--v2-signing-enabled <true | false>
apksigner가 APK 서명 체계 v2를 사용하여 지정된 APK 패키지에 서명하는지 여부를 결정합니다. 기본적으로 이 도구는 --min-sdk-version 및 --max-sdk-version의 값을 사용하여 이 서명 체계의 적용 시점을 결정합니다.
--v3-signing-enabled <true | false>
apksigner가 APK 서명 체계 v3을 사용하여 지정된 APK 패키지에 서명하는지 여부를 결정합니다. 기본적으로 이 도구는 --min-sdk-version 및 --max-sdk-version의 값을 사용하여 이 서명 체계의 적용 시점을 결정합니다.
--v4-signing-enabled <true | false | only>

apksigner가 APK 서명 체계 v4를 사용하여 지정된 APK 패키지에 서명하는지 여부를 결정합니다. 이 체계는 별도의 파일(apk-name.apk.idsig)에서 서명을 생성합니다. true이고 APK가 서명되지 않은 경우 --min-sdk-version 및 --max-sdk-version의 값을 기준으로 v2 또는 v3 서명이 생성됩니다. 그런 다음 서명된 APK의 콘텐츠를 기반으로 명령어가 .idsig 파일을 생성합니다.

APK와 호출 전에 있던 서명을 수정하지 않고 v4 서명만 생성하려면 only를 사용합니다. APK에 v2 또는 v3 서명이 없거나 현재 호출에 제공된 키가 아닌 다른 키가 서명에 사용된 경우 only는 실패합니다.

기본적으로 이 도구는 --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의 기본 동작입니다.

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

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

Keytool은 종종 콘솔의 기본 문자 집합을 사용해 비밀번호를 변환하여 키 저장소를 암호화합니다. 기본적으로 apksigner는 여러 형식의 비밀번호를 사용하여 복호화를 시도합니다.

  • 유니코드 형식
  • JVM 기본 문자 집합을 사용하여 인코딩된 형식
  • 자바 8 이하에서는 콘솔의 기본 문자 집합을 사용하여 인코딩된 형식

    • 자바 9에서 apksigner는 콘솔의 문자 집합을 감지할 수 없습니다. 비 ASCII 비밀번호를 사용할 때는 --pass-encoding을 지정해야 할 수도 있습니다. 또한 keytool이 다른 OS 또는 다른 언어에서 생성한 키 저장소와 함께 이 옵션을 지정해야 할 수도 있습니다.

    --key-pass <input-format>

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

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

    인증 명령어

    apksigner 인증 명령어에는 다음과 같은 옵션이 있습니다.

    --print-certs
    APK의 서명 인증서에 관한 정보를 표시합니다.
    --min-sdk-version <integer>
    apksigner가 APK의 서명이 인증되는지 확인하는 데 사용하는 가장 낮은 Android 프레임워크 API 수준입니다. 값이 클수록 도구가 앱에 서명할 때 더 강력한 보안 매개변수를 사용할 수 있지만 최신 버전의 Android를 실행하는 기기에서는 APK의 가용성이 제한됩니다. 기본적으로 apksigner는 앱 매니페스트 파일의 minSdkVersion 속성 값을 사용합니다.
    --max-sdk-version <integer>
    apksigner가 APK의 서명이 인증되는지 확인하는 데 사용하는 가장 높은 Android 프레임워크 API 수준입니다. 기본적으로 이 도구는 가능한 가장 높은 API 수준을 사용합니다.
    -v, --verbose
    상세 출력 모드를 사용합니다.
    -Werr
    경고를 오류로 취급합니다.

    예

    다음은 apksigner를 사용하는 예입니다.

    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

    순환된 서명 키 및 순환 타겟팅 SDK 버전 28 이상을 사용하여 APK에 서명합니다. 

    $ apksigner sign --ks release.jks --next-signer --ks release2.jks \
  --lineage /path/to/signing/history/lineage app.apk \
  --rotation-min-sdk-version 28

    순환된 서명 키 및 순환 타겟팅 SDK 버전 33 이상을 사용하여 APK에 서명합니다. 

    $ apksigner sign --ks release.jks --next-signer --ks release2.jks \
  --lineage /path/to/signing/history/lineage 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