Mastering the HarmonyOS Next Signature Verification Mechanism

#harmonyosnext

Mastering the HarmonyOS Next Signature Verification Mechanism

Background Introduction

Android app signing requires only one signature file. In the development environment, we use a debug signature by default. The debug signature alias is androiddebugkey, with the password android. The debug certificate is stored in the .android folder under the user directory, typically named debug.keystore, and doesn’t require special configuration in build.gradle.

HarmonyOS Next adopts a signing mechanism similar to iOS. Signing configuration information for the project is stored in the project-level build-profile.json5. When using automatic signing, the locally generated signing configuration path is automatically updated in build-profile.json5. This creates an issue: since each person’s signing path differs, build-profile.json5 cannot be configured to be ignored by Git nor maintained consistently in multi-person collaboration.

Before Develop Beta6, we could create a sign folder in the project, use my account to generate signing files automatically, copy them to the sign folder, and allow others to use my signature for development and debugging. However, starting from Develop Beta6, sharing automatically generated signatures causes real-device installation failures:

09/06 18:10:04:702: $ hdc shell bm install -p data/local/tmp/140f0b9059b04d8286941346c79d8f7b  in 304 ms
Install Failed: error: failed to install bundle.
code:9568322
error: signature verification failed due to not trusted app source.
View detailed instructions.
09/06 18:10:04:791: $ hdc shell rm -rf data/local/tmp/140f0b9059b04d8286941346c79d8f7b
09/06 18:10:04:792: Launch com.qingkouwei.demo failed, starting handle failure progress
Error while Deploy Hap

As the HarmonyOS system stabilizes through iterations, system security has been strengthened. During installation, the system now verifies whether the UDID in the signature matches the device UDID. This necessitates continuing with automatic signing and finding a thorough solution.

HarmonyOS Signing Mechanism

To solve this problem, we must understand the signing principles. Let’s first look at the files generated by automatic signing:

.p12: Key file. The P12 certificate (PKCS#12, Public-Key Cryptography Standards #12) is an encryption standard for exchanging digital certificates. It describes personal identity information, includes public and private keys for asymmetric encryption, and is stored in a keystore file. The key pair is used for digital signatures and verification.
.csr: Certificate Signing Request file, containing the public key in the key pair, public name, organization name, organizational unit, etc., used to apply for a digital certificate from AppGallery Connect.
.cer: Digital certificate issued by Huawei AppGallery Connect.
.p7b: Profile file, containing the package name of the HarmonyOS app/service, digital certificate information, a list of certificate permissions the app/service is allowed to apply for, and a list of devices allowed for debugging (if the app/service type is Release, the device list is empty). Each app/service package must include a Profile file.
material folder: Stores signing scheme-related materials, such as passwords and certificates.

The P12 and CSR files are generated locally and used to upload to the AppGallery Connect platform to apply for certificates and P7B files. The role of the material folder is introduced later.

Role of the Key

The P12 file contains public and private keys for asymmetric encryption (RSA), where encryption and decryption keys differ. Typical uses include:

Confidentiality: Encrypt plaintext with the recipient’s public key and transmit it. The ciphertext can only be decrypted with the recipient’s private key, ensuring transmission confidentiality even if intercepted.
Identity Verification and Tamper Prevention (Signing): Encrypt a message with the sender’s private key to sign it. The signed message can only be decrypted with the sender’s public key, ensuring authenticity (the message indeed belongs to the sender). If the ciphertext is intercepted, modified, and resent, it cannot be decrypted, ensuring message integrity. Thus, signing ensures message authenticity and integrity.

Role of the Digital Certificate

Asymmetric encryption algorithms are time-consuming for encrypting long plaintexts. In practice, the message is first hashed using a digest algorithm (e.g., MD5, SHA), the digest is encrypted, and the plaintext, encrypted digest, and public key are sent together. The recipient decrypts the digest ciphertext, hashes the plaintext, and compares the digests to verify integrity. This is a digital signature.

What is a certificate? Consider a communication fraud scenario: A intends to deceive B by sending a forged message pretending to be from C. A encrypts the file with their private key, sends it with their public key, and claims the public key belongs to C. How does B verify the public key’s ownership? This is where certificates play a role—like a network ID card proving the holder’s identity.

A digital certificate is issued by a CA (Certificate Authority) and contains the holder’s information and public key. Like a notarized document, it gains validity through CA authentication. B can verify the message sender by querying the CA with the digital certificate, confirming whether the public key belongs to A or C—similar to checking an ID card.

Using AppGallery Connect Platform Debug Certificates

The AppGallery Connect platform provides debug certificates. We can generate local keys, create debug certificates on the platform, place them in the app project’s sign folder, configure a unified signing file, and add other developers’ device IDs to the debug Profile. Here’s how to generate debug certificates:

Generating a P12 Key

DevEco Studio provides a tool to generate P12 keys. In the main menu, click Build > Generate Key and CSR:

Key generation configuration:

For "Key store file," select the path and filename for the key file (ending with .p12):

Next, select the CSR file path:

Upon completion, you will obtain:

qingkouwei.csr
qingkouwei.p12
material folder

Applying for a Debug Certificate and Debug Profile

A certificate is a digital certificate configuring signing information for a HarmonyOS app/meta-service, ensuring code integrity and publisher identity. In .cer format, it contains public keys, certificate fingerprints, etc. For applying for a debug certificate, refer to: Apply for a Debug Certificate

The Profile (.p7b format) contains the package name, digital certificate information, allowed certificate permissions, and debug device list (empty for Release-type apps/services). Each app/meta-service must include a Profile. For applying for a debug Profile, refer to: Apply for a Debug Profile

Copy the downloaded .p7b and .cer files to the sign folder and configure signing information in build-profile.json:

Note: The storePassword is not the password used when generating the signature. How to obtain it? Configure signing information via the project tool’s signing tool, which will automatically retrieve storePassword—this is the role of the material folder mentioned in signing.

Note: To generate a signature, first create an APPID on the AppGallery Connect platform:

Additional considerations:

Before using automatic signing, ensure the local system time matches Beijing Time (UTC/GMT +8.00); otherwise, signing will fail.
Each account can apply for up to two debug certificates. Automatic signing consumes debug certificate quotas. If two debug certificates already exist on AppGallery Connect, subsequent automatic signing for the account will fail.
A certificate is "active" upon successful application. If its status becomes "invalid" or "revoked," it is no longer usable, and all Profiles applied for with this certificate will also become invalid or revoked. You need to reapply for certificates and Profiles. Revoked certificates cannot be recovered, so proceed with caution.
An app can apply for up to 100 Profile files.
Modifying debug devices generates a new debug Profile; download it after it takes effect.
If a Profile’s status becomes "invalid" or "revoked," it is no longer usable; reapply for a Profile.
Obtain the device UDID using the command hdc shell bm get --udid.

If an account has already created two debug certificates, using it for automatic signing will fail with the following error: