App Bundle의 코드 투명성

코드 투명성은 Android App Bundle로 게시된 앱을 위한 선택적 코드 서명 및 확인 메커니즘입니다. 앱 개발자만 보유하는 코드 투명성 서명 키를 사용합니다.

코드 투명성은 App Bundle과 APK에 사용되는 서명 체계와는 관련이 없습니다. 코드 투명성 키는 Play 앱 서명을 사용할 때 Google의 보안 인프라에 저장되는 앱 서명 키와는 별개이며 다릅니다.

코드 투명성 작동 방식

이 프로세스는 빌드된 후에 그러나 배포를 위해 Play Console에 업로드되기 전에 번들에 코드 투명성 파일을 포함하여 작동합니다.

코드 투명성 파일은 번들에 포함된 DEX 파일 및 네이티브 라이브러리의 목록과 해시가 포함된 JSON 웹 토큰(JWT)입니다. 그런 다음 개발자만 보유하고 있는 코드 투명성 키를 사용하여 서명됩니다.

코드 투명성 다이어그램

이 코드 투명성 파일은 App Bundle에서 빌드된 기본 APK로(특히 기본 모듈의 기본 분할로) 전파됩니다. 그러면 다음을 확인할 수 있습니다.

  • APK에 있는 모든 DEX 및 네이티브 코드 파일은 코드 투명성 파일에 일치하는 해시가 있습니다.
  • 앱에서 코드 투명성 서명 키의 공개 키 구성요소는 개발자의 공개 키와 일치합니다(개발자가 별도의 보안 채널을 통해 제공해야 함).

종합하면 이 정보는 APK에 포함된 코드가 개발자가 의도한 것과 일치하는지, 코드가 수정되지 않았는지 확인합니다.

코드 투명성 파일은 리소스나 애셋, Android 매니페스트, lib/ 폴더에 포함된 DEX 파일 또는 네이티브 라이브러리가 아닌 다른 모든 파일을 확인하지 않습니다.

코드 투명성 확인은 실행 중인 코드가 원래 앱 개발자가 빌드하고 서명한 코드와 일치하는지 확인하려는 개발자 및 최종 사용자의 검사 목적으로만 사용됩니다.

알려진 제한사항

코드 투명성을 사용할 수 없는 특정 상황은 다음과 같습니다.

  • 앱이 매니페스트에서 sharedUserId 속성을 지정합니다. 이러한 애플리케이션은 다른 애플리케이션과 프로세스를 공유할 수 있으므로 실행하는 코드를 확인하기가 어렵습니다.
  • 조작 방지 서비스 또는 코드 투명성 파일이 생성된 후 코드를 변경하는 기타 서비스를 사용하는 앱에서는 코드 투명성 확인이 실패합니다.
  • 앱이 API 수준 21 미만(Android 5.0)에서 기존 멀티덱스를 사용하고 기능 모듈을 사용합니다. 코드 투명성은 앱이 Android 5.0 이상 기기에 Google Play를 통해 설치되면 계속 작동합니다. 이전 OS 버전에서는 코드 투명성이 사용 중지됩니다.

코드 투명성 추가 방법

앱에 코드 투명성을 추가하려면 코드 투명성 서명에 사용할 수 있는 비공개 및 공개 키 쌍이 있는지 확인하세요. Play 앱 서명에 사용하는 앱 서명 키와는 다른 고유한 키여야 하고 안전하게 보관되어야 하며 조직 외부에서 공유해서는 안 됩니다.

키가 없다면 앱 서명 가이드의 안내를 따라 컴퓨터에서 키를 생성하면 됩니다. 코드 투명성은 표준 키 저장소 파일을 사용하므로 가이드가 앱 서명에 관한 것이라도 키 생성 프로세스는 같습니다.

Android Gradle 플러그인 사용

코드 투명성을 지원하려면 Android Gradle 플러그인 버전 7.1.0-alpha03 이상이 필요합니다. 코드 투명성 서명에 사용되는 키를 구성하려면 bundle 블록에 다음을 추가합니다.

Groovy

// In your app module's build.gradle file:
android {
    ...
    bundle {
        codeTransparency {
            signing {
                keyAlias = "ALIAS"
                keyPassword = "PASSWORD"
                storeFile = file("path/to/keystore")
                storePassword = "PASSWORD"
            }
        }
        ...
    }
}

Kotlin

// In your app module's build.gradle.kts file:
android {
    ...
    bundle {
        codeTransparency {
            signing {
                keyAlias = "ALIAS"
                keyPassword = "PASSWORD"
                storeFile = file("path/to/keystore")
                storePassword = "PASSWORD"
            }
        }
        ...
    }
}

사용된 키는 코드 투명성에만 사용하는 키여야 하고 Play 앱 서명에 사용되는 앱 서명 키가 아니어야 합니다.

명령줄에 bundletool 사용

코드 투명성을 지원하려면 GitHub에서 다운로드할 수 있는 bundletool 버전 1.7.0 이상이 필요합니다.

다음 명령어를 실행하여 코드 투명성을 Android App Bundle에 추가합니다. 사용된 키는 코드 투명성에만 사용하는 키여야 하고 Play 앱 서명에 사용되는 앱 서명 키가 아니어야 합니다.

bundletool add-transparency \
  --bundle=/MyApp/my_app.aab \
  --output=/MyApp/my_app_with_transparency.aab \
  --ks=/MyApp/keystore.jks \
  --ks-pass=file:/MyApp/keystore.pwd \
  --ks-key-alias=MyKeyAlias \
  --key-pass=file:/MyApp/key.pwd

또는 자체 서명 도구를 사용하려는 경우 bundletool을 사용하여 서명되지 않은 코드 투명성 파일을 생성하고 별도의 환경에서 서명한 후 서명을 번들에 삽입할 수 있습니다.

# Generate code transparency file
bundletool add-transparency \
  --mode=generate_code_transparency_file \
  --bundle=/MyApp/my_app.aab \
  --output=/MyApp/code_transparency_file.jwt \
  --transparency-key-certificate=/MyApp/transparency.cert

# Add code transparency signature to the bundle
bundletool add-transparency \
  --mode=inject_signature \
  --bundle=/MyApp/my_app.aab \
  --output=/MyApp/my_app_with_transparency.aab \
  --transparency-key-certificate=/MyApp/transparency.cert \
  --transparency-signature=/MyApp/signature

앱의 코드 투명성 확인

Android 기기에 APK를 설치했는지 또는 컴퓨터에 로컬로 다운로드했는지에 따라, 코드 투명성 파일과 비교하여 코드를 확인하는 방법에는 여러 가지가 있습니다.

Bundletool을 사용하여 App Bundle 또는 APK 세트 확인

bundletool을 사용하여 App Bundle이나 APK 세트의 코드 투명성을 확인할 수 있습니다. check-transparency 명령어를 사용하여 공개 인증서 지문을 출력합니다.

# For checking a bundle:
bundletool check-transparency \
  --mode=bundle \
  --bundle=/MyApp/my_app_with_transparency.aab

No APK present. APK signature was not checked.
Code transparency signature is valid. SHA-256 fingerprint of the code transparency key certificate (must be compared with the developer's public key manually): 01 23 45 67 89 AB CD EF ..
Code transparency verified: code related file contents match the code transparency file.


# For checking a ZIP containing app's APK splits:
bundletool check-transparency \
  --mode=apk \
  --apk-zip=/MyApp/my_app_with_transparency.zip

APK signature is valid. SHA-256 fingerprint of the apk signing key certificate (must be compared with the developer's public key manually): 02 34 E5 98 CD A7 B2 12 ..
Code transparency signature is valid. SHA-256 fingerprint of the code transparency key certificate (must be compared with the developer's public key manually): 01 23 45 67 89 AB CD EF ..
Code transparency verified: code related file contents match the code transparency file.

번들이나 APK 세트를 확인하려는 공개 인증서를 선택적으로 지정할 수 있으므로 해시를 수동으로 비교하지 않아도 됩니다.

bundletool check-transparency \
  --mode=bundle \
  --bundle=/MyApp/my_app_with_transparency.aab \
  --transparency-key-certificate=/MyApp/transparency.cert

No APK present. APK signature was not checked.
Code transparency signature verified for the provided code transparency key certificate.
Code transparency verified: code related file contents match the code transparency file.


bundletool check-transparency \
  --mode=apk \
  --apk-zip=/MyApp/my_app_with_transparency.zip \
  --apk-signing-key-certificate=/MyApp/apk.cert \
  --transparency-key-certificate=/MyApp/transparency.cert

APK signature verified for the provided apk signing key certificate.
Code transparency signature verified for the provided code transparency key certificate.
Code transparency verified: code related file contents match the code transparency file.

Bundletool을 사용하여 기기에 설치된 앱 확인

Android 기기에 설치된 앱을 확인하려면 기기가 ADB를 통해 컴퓨터에 연결되어 있는지 확인하고 다음 명령어를 실행합니다.

bundletool check-transparency \
  --mode=connected_device \
  --package-name="com.my.app"

APK signature is valid. SHA-256 fingerprint of the apk signing key certificate (must be compared with the developer's public key manually): 02 34 E5 98 CD A7 B2 12 ..
Code transparency signature is valid. SHA-256 fingerprint of the code transparency key certificate (must be compared with the developer's public key manually): 01 23 45 67 89 AB CD EF ..
Code transparency verified: code related file contents match the code transparency file.

연결된 기기 투명성 검사는 개발자가 지정하는 공개 키와 비교하여 선택적으로 서명을 확인할 수도 있습니다.

bundletool check-transparency \
  --mode=connected-device \
  --package-name="com.my.app" \
  --apk-signing-key-certificate=/MyApp/apk.cert \
  --transparency-key-certificate=/MyApp/transparency.cert

APK signature verified for the provided apk signing key certificate.
Code transparency signature verified for the provided code transparency key certificate.
Code transparency verified: code related file contents match the code transparency file.