Uygulama paketleri için kod şeffaflığı

Kod şeffaflığı, Android App Bundle ile yayınlanan uygulamalar için isteğe bağlı bir kod imzalama ve doğrulama mekanizmasıdır. Yalnızca uygulama geliştiricisine ait olan bir kod şeffaflığı imzalama anahtarı kullanır.

Kod şeffaflığı, uygulama paketleri ve APK'lar için kullanılan imzalama şemasından bağımsızdır. Kod şeffaflık anahtarı, Play Uygulama İmzalama kullanılırken Google'ın güvenli altyapısında depolanan uygulama imzalama anahtarından ayrı ve farklıdır.

Kod şeffaflığının işleyiş şekli

Bu süreç, paket oluşturulduktan sonra, ancak dağıtım için Play Console'a yüklenmeden önce pakete bir kod şeffaflık dosyası ekleyerek çalışır.

Kod şeffaflık dosyası, pakette yer alan DEX dosyaları, yerel kitaplıklar ve bunların karmalarını içeren bir JSON Web Token'dır (JWT). Daha sonra yalnızca geliştirici tarafından tutulan kod şeffaflık anahtarı kullanılarak imzalanır.

Bu kod şeffaflık dosyası, uygulama paketinden oluşturulan temel APK'ya (özellikle temel modülün ana bölmesine) iletilir. Daha sonra aşağıdakilerin yapıldığı doğrulanabilir:

• APK'larda bulunan tüm DEX ve yerel kod dosyalarının kod şeffaflık dosyasında eşleşen karmaları vardır.
• Uygulamadaki kod şeffaflık imzalama anahtarının ortak anahtar bileşeni, geliştiricinin ortak anahtarıyla eşleşir (geliştirici tarafından ayrı, güvenli bir kanal üzerinden sağlanmalıdır).

Bu bilgiler birlikte, APK'larda bulunan kodun geliştiricinin amaçladığıyla eşleştiğini ve değiştirilmediğini doğrular.

Kod şeffaflık dosyası; kaynakları, öğeleri, Android Manifest'i veya lib/ klasöründe yer alan DEX dosyası ya da yerel kitaplık olmayan diğer dosyaları doğrulamaz.

Kod şeffaflık doğrulaması, yalnızca çalıştırdıkları kodun uygulama geliştirici tarafından orijinal olarak oluşturulup imzalanan kodla eşleştiğinden emin olmak isteyen geliştiriciler ve son kullanıcıların denetimi amacıyla kullanılır.

Bilinen sınırlamalar

Kod şeffaflığının kullanılamayacağı belirli durumlar vardır:

• Manifest'te sharedUserId özelliğini belirten uygulamalar. Bu tür uygulamalar süreçlerini diğer uygulamalarla paylaşabilir. Bu da yürüttükleri kod hakkında güvence verilmesini zorlaştırır.
• Kurcalama koruması kullanan uygulamalar veya kod şeffaflık dosyası oluşturulduktan sonra kod değişiklikleri yapan başka hizmetler, kod şeffaflığı doğrulamasının başarısız olmasına neden olur.
• 21'in altındaki API düzeylerinde (Android 5.0) eski Multidex'i kullanan ve özellik modüllerini kullanan uygulamalar. Uygulama, Android 5.0 ve sonraki sürümleri çalıştıran cihazlara Google Play tarafından yüklendiğinde kod şeffaflığı çalışmaya devam eder. Eski OS sürümlerinde kod şeffaflığı devre dışı bırakılacaktır.

Kod şeffaflığı ekleme

Uygulamanıza kod şeffaflığı eklemeden önce kod şeffaflığı imzalama için kullanabileceğiniz özel ve ortak anahtar çiftiniz olduğundan emin olun. Bu, Play Uygulama İmzalama için kullandığınız uygulama imzalama anahtarından farklı, benzersiz bir anahtar olmalı, güvenli bir şekilde tutulmalı ve hiçbir zaman kuruluşunuz dışında paylaşılmamalıdır.

Anahtarınız yoksa makinenizde bir anahtar oluşturmak için Uygulamanızı imzalayın kılavuzundaki talimatları uygulayabilirsiniz. Kod şeffaflığı standart bir anahtar deposu dosyası kullanır. Bu nedenle, kılavuz uygulama imzalama için olsa da anahtar oluşturma süreci aynıdır.

Android Gradle eklentisini kullanma

Kod şeffaflığı desteği, Android Gradle eklentisi 7.1.0-alpha03 veya daha yeni bir sürümü gerektirir. Kod şeffaflığı imzalamada kullanılacak anahtarı yapılandırmak için aşağıdakileri bundle blokuna ekleyin.

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

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

Kullanılan anahtar, Play Uygulama İmzalama tarafından kullanılan uygulama imzalama anahtarı değil, yalnızca kod şeffaflığı için kullanacağınız anahtar olmalıdır.

Komut satırında bundletool kullanma

Kod şeffaflığı desteği için Bundletool 1.7.0 veya daha yeni bir sürüm gerekir. Bu sürümü GitHub'dan indirebilirsiniz.

Android App Bundle'a kod şeffaflığı eklemek için aşağıdaki komutu çalıştırın. Kullanılan anahtar, Play Uygulama İmzalama tarafından kullanılan uygulama imzalama anahtarı değil, yalnızca kod şeffaflığı için kullanacağınız anahtar olmalıdır.

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

Alternatif olarak kendi imzalama araçlarınızı kullanmak isterseniz imzasız kod şeffaflık dosyasını oluşturmak için Bundletool'u kullanabilir, ayrı bir ortamda imzalayabilir ve imzayı pakete ekleyebilirsiniz:

# 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

Bir uygulamanın kod şeffaflığını doğrulama

APK'ların bir Android cihazda yüklü veya bilgisayarınıza yerel olarak indirilmiş olmasına bağlı olarak, kod şeffaflık dosyasına göre kodu doğrulamanın farklı yöntemleri vardır.

Uygulama paketini veya APK grubunu kontrol etmek için Bundletool'u kullanma

Bir uygulama paketi veya APK grubundaki kod şeffaflığını doğrulamak için Bundletool'u kullanabilirsiniz. Genel sertifika parmak izini yazdırmak için check-transparency komutunu kullanın:

# 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.

Karmaları manuel olarak karşılaştırmak zorunda kalmamak için paketi veya APK'yı doğrulamak istediğiniz genel sertifikayı isteğe bağlı olarak belirtebilirsiniz:

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.

Cihazda yüklü bir uygulamayı kontrol etmek için Bundletool'u kullanma

Bir Android cihazda yüklü olan bir uygulamayı kontrol etmek için cihazın ADB üzerinden bilgisayarınıza bağlı olduğundan emin olun ve aşağıdaki komutu uygulayın:

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.

Bağlı cihaz şeffaflık kontrolü, belirttiğiniz bir ortak anahtara göre imzayı isteğe bağlı olarak doğrulayabilir:

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.