Skip to main content

Fixing 'Invalid App Signature' Error When Publishing to Huawei AppGallery

 Rejections during the final stage of release are costly. You build your Android App Bundle (AAB) or APK, initiate the AppGallery Connect upload, and immediately hit an "Invalid App Signature" rejection. This blocks Huawei AppGallery publishing pipelines and disrupts deployment schedules.

The error indicates a cryptographic mismatch between your build artifact and AppGallery Connect's (AGC) expected signature schemes or upload certificates. Resolving this requires aligning your build system's signing configuration with Huawei's backend validation rules.

The Root Cause: Signature Schemes and Key Custody

Android application signing relies on a strict cryptographic hierarchy. When an AGC signature error occurs, it stems from one of two architectural misconfigurations in your release pipeline.

First, the artifact may lack Android APK Signature Scheme v2 or v3. AppGallery Connect strictly enforces v2/v3 signing to prevent malicious tampering. Relying solely on the legacy v1 (JAR signing) scheme triggers an immediate rejection. While v1 protects the APK contents, v2 and v3 protect the integrity of the APK as a whole by computing a hash over the entire file.

Second, there is a key custody mismatch. Modern Android distribution utilizes cloud-managed app signing. If you use App Signing by AppGallery (mandatory for AABs), AGC acts as the custodian of your production App Signing Key. You must sign your upload artifact with a designated Upload Key. If you mistakenly sign the artifact with your production key, or if the Upload Key certificate registered in AGC doesn't match the keystore used by your CI/CD runner, validation fails.

The Fix: Configuring Signatures and Upload Keys

To resolve the AGC signature error, you must explicitly enforce modern signing schemes in your build configuration and synchronize your upload certificate with AppGallery Connect.

Step 1: Enforce Signature Schemes in Gradle

Update your module-level build.gradle.kts (Kotlin DSL) to explicitly enable v1, v2, and v3 signature schemes. Do not rely on default compiler behaviors, as varying Android Gradle Plugin (AGP) versions handle signing defaults differently.

// app/build.gradle.kts
android {
    signingConfigs {
        create("release") {
            storeFile = file(System.getenv("KEYSTORE_PATH") ?: "keystore.jks")
            storePassword = System.getenv("KEYSTORE_PASSWORD")
            keyAlias = System.getenv("KEY_ALIAS")
            keyPassword = System.getenv("KEY_PASSWORD")
            
            // Explicitly enable signature schemes
            enableV1Signing = true
            enableV2Signing = true
            enableV3Signing = true
            enableV4Signing = true // Recommended for incremental installs
        }
    }

    buildTypes {
        release {
            signingConfig = signingConfigs.getByName("release")
            isMinifyEnabled = true
            proguardFiles(
                getDefaultProguardFile("proguard-android-optimize.txt"),
                "proguard-rules.pro"
            )
        }
    }
}

Step 2: Extract the Upload Certificate

If you are using Huawei app signing, AGC needs to know the public certificate of the keystore you are using to sign your local builds. Extract the .pem certificate from your upload keystore using the Java keytool utility.

keytool -export -rfc \
  -keystore path/to/upload-keystore.jks \
  -alias your_key_alias \
  -file huawei_upload_certificate.pem

Provide the correct keystore password when prompted. This generates a base64-encoded X.509 certificate file.

Step 3: Register the Certificate in AppGallery Connect

Navigate to the AppGallery Connect console. Select your project and go to App Information > App Signature.

If you are setting up App Signing for the first time, select the option to let AppGallery Connect create and manage your app signature key. Then, in the Upload Key section, upload the huawei_upload_certificate.pem file you generated in Step 2. If an old upload key is currently registered, you must submit an upload key reset request through the console and wait for Huawei's approval.

Step 4: Verify the Artifact Locally

Before attempting another AppGallery Connect upload, verify the cryptographic signatures locally using the Android SDK apksigner tool. This prevents wasting time on failed pipeline uploads.

# Locate apksigner in your Android SDK build-tools directory
apksigner verify --verbose --print-certs app-release.apk

# Expected Output:
# Verifies
# Verified using v1 scheme (JAR signing): true
# Verified using v2 scheme (APK Signature Scheme v2): true
# Verified using v3 scheme (APK Signature Scheme v3): true

If Verified using v2 scheme returns false, your Gradle configuration was not applied correctly, or a post-processing tool (like an aggressive zip-aligner or obfuscator) stripped the signature after compilation.

Deep Dive: How AppGallery Cryptographic Validation Works

Understanding Huawei app signing requires looking at the ingress pipeline. When you upload an AAB, AGC verifies the upload key signature against the .pem file you registered.

Once authenticated, the AGC backend strips your upload signature, generates the device-specific APK configurations from the bundle, and re-signs those APKs using your production key stored in Huawei's Hardware Security Module (HSM). If the SHA-256 hash of your uploaded artifact's signature block does not perfectly match the expected ingress key, the system halts the pipeline to prevent potential supply-chain injection attacks.

This mechanism ensures that even if your local CI/CD environment is compromised and an attacker steals your upload key, they cannot generate a valid production application, as the production key remains isolated in Huawei's infrastructure.

Common Pitfalls and Edge Cases

HMS Core Fingerprint Mismatches

A frequent side-effect of configuring app signing is breaking Huawei Mobile Services (HMS Core) integrations like Push Kit or Auth Service. The SHA-256 fingerprint registered in your AGC Project Settings > General Information must match the production key managed by AGC, not your local upload key. If you register the upload key's SHA-256, your app will fail API authentication in production.

CI/CD Keystore Corruption

When automating Huawei AppGallery publishing via GitHub Actions or GitLab CI, keystores are typically stored as base64-encoded environment variables. A common cause of the "Invalid App Signature" error is incorrect decoding during the build step, resulting in a corrupted .jks file. Always use strict decoding flags:

# GitHub Actions example for safe keystore decoding
echo "${{ secrets.KEYSTORE_BASE64 }}" | base64 --decode > app/upload-keystore.jks

Zipalign Ordering

If your CI/CD pipeline runs zipalign and apksigner manually via shell scripts instead of relying on Gradle, ordering is critical. You must run zipalign before apksigner. Running zipalign after signing modifies the archive structure, instantly invalidating the v2 and v3 signature hashes and causing an immediate AGC rejection.

Conclusion

Resolving AppGallery Connect signature rejections requires strict adherence to modern Android packaging standards. By enforcing v2/v3 signature schemes in your build scripts, correctly exporting your upload certificate, and ensuring your CI/CD environment strictly isolates the upload key, you can stabilize your deployment pipeline. Always utilize apksigner as a pre-flight check to validate artifact integrity before pushing to Huawei's distribution network.

Labels: