HarmonyOS Next - Understanding the Signature Verification Mechanism

Background Introduction

For Android applications, only one signature file is needed. In the development environment, we use the debug signature by default. The alias of the debug signature is androiddebugkey, and the password is android. The debugging certificate is stored in the .android folder in the user directory, and the certificate file is usually named debug.keystore. There is no need to specifically configure the debugging signature in build.gradle. HarmonyOS Next adopts a signature mechanism similar to that of iOS. The signature configuration information in the project is in the project-level build-profile.json5. If automatic signing is used, the path of the locally generated signature configuration will be automatically updated to build-profile.json5. This brings a problem that the signature paths generated by each person are inconsistent, and when multiple people collaborate, build-profile.json5 cannot be configured to be ignored by Git, and it is also difficult to keep it consistent.

Before Develop Beta6, by creating a sign signature folder in the project, using my own account for automatic signature generation to create signature files, and copying the signature files to the sign folder, others could also use my signature for development and debugging. However, starting from Develop Beta6, sharing the signature generated by automatic signing will cause the installation on real devices to fail:

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

Because as the HarmonyOS system iterates and gradually becomes stable, the system has strengthened security. During installation, it will verify whether the UDID of the signature is consistent with that of the mobile phone. So, we can only continue to use automatic signing and need to find a thorough solution.

HarmonyOS Signature Mechanism

To solve the problem, we must first understand the principle of signing. Let's first look at the files generated by automatic signing:

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

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

The Role of the Key

The P12 contains the public and private keys and is used in asymmetric encryption. Asymmetric encryption (a typical algorithm is RSA) is an encryption method where the encryption key and the decryption key are different. Typical usages are as follows:

• Confidentiality: Use the recipient's public key to encrypt the plaintext and then transmit it to the recipient. In this way, the ciphertext can only be decrypted by the recipient's private key. Even if the ciphertext is intercepted during transmission, it cannot be decrypted, which ensures the confidentiality of information transmission.
• Identity verification and anti-tampering (signature): Use the sender's private key to encrypt the message, which means the sender signs the message. The signed message can only be decrypted by the sender's public key, which ensures the authenticity of the message, that is, the message indeed belongs to the sender. In addition, if the ciphertext is intercepted, modified, and then sent during transmission, the ciphertext cannot be decrypted, and we can know that the message has been tampered with, thus ensuring the integrity of the message. Therefore, the role of the signature is to ensure the authenticity and integrity of the message.

The Role of the Digital Certificate

Asymmetric encryption algorithms have a disadvantage that encrypting very long plaintext takes a long time. Therefore, in actual use, usually, the message is first hashed using a digest algorithm to obtain a digest, and then the digest is encrypted. Then, the plaintext, the encrypted digest, and the public key are sent together. The recipient first decrypts the digest ciphertext, and then uses the digest algorithm on the plaintext to compare the obtained digest with the decrypted digest. If they are the same, it means that the plaintext has not been tampered with. This is the so-called digital signature. Typical digest algorithms include MD5 and SHA.

So, what is a certificate? Take an example of deception in the communication process: A wants to deceive B and prepares to send B a message that is forged to be sent by C. A encrypts the file with his own private key, sends his own public key along with it, and claims that the public key belongs to C. Then how does B know whether the public key really belongs to C? Here comes the role of the certificate. The existence of a certificate is surely to prove a certain fact. The CET-4 and CET-6 certificates prove my English level, and the ID card proves my unique identity in China. The existence of a digital certificate is to prove the identity of the certificate holder, just like an online ID card. The issuer of a digital certificate is a CA (Certificate Authority). The certificate holder can be an enterprise, an individual, or a network device. A digital certificate is a certificate signed by a CA, just like being stamped by an authoritative institution, so that the validity of the certificate can be established. The reason why a digital certificate can prove the identity of the certificate holder is that the certificate contains the information of the certificate holder and the certificate holder's public key. Through the authentication of an authoritative institution (CA), the digital certificate has its validity, just like an ID card can prove a person's identity after being stamped by the Public Security Bureau. In this way, A cannot pretend to be C. Because if B wants to verify the identity of the message holder, he only needs to take the digital certificate sent by A to the CA for verification. The public key in the digital certificate is already bound to the certificate holder. By checking, he can know whether the public key belongs to A or C. This process is just like A showing B an ID card, and B can tell whether the other person is A or C at a glance.

Using the AppGallery Connect Platform for Debugging Certificates

The AppGallery Connect platform provides debugging certificates. We can generate keys locally, generate debugging certificates on the AppGallery Connect platform, place them in the sign folder of the application project, configure a unified signature file, and add the device IDs of other developers to the debugging Profile. The following is how to generate debugging certificates.

Generating the P12 Key

DevEco Studio provides a tool for generating the P12 key. Click Build > Generate Key and CSR in the main menu bar:

Key generation configuration:

Select the path and file name for generating the key file for Key store file, and the file name should end with .p12:

Next, select the path of the CSR file:

After completion, you will get:

• qingkouwei.csr
• qingkouwei.p12
• material folder.

Applying for Debugging Certificates and Debugging Profile

The certificate is a digital certificate that configures signature information for HarmonyOS applications/atomic services and can ensure the integrity of software code and the authenticity of the publisher's identity. The certificate format is .cer and contains information such as the public key and certificate fingerprint. Refer to the document Applying for Debugging Certificates to apply for debugging certificates.

The Profile format is .p7b and contains the package name of the HarmonyOS application/atomic service, digital certificate information, a list of certificate permissions that the HarmonyOS application/atomic service is allowed to apply for, and a list of devices allowed for application/atomic service debugging (if the application/atomic service type is Release type, the device list is empty), etc. Each HarmonyOS application/atomic service package must contain a Profile file. Refer to Applying for Debugging Profile to apply for the debugging profile.

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

Note that storePassword here is not the password we set when generating the signature above. How can we get this password? We can configure the signature information through the project tool - signature tool, and it will automatically obtain storePassword. This is also the role of the material folder mentioned in signing.

Here, it should be noted that when generating the signature, you need to first generate the APPID on the AppGallery Connect platform:

In addition, the following points should be noted:

1. Before using automatic signing, please ensure that the local system time is consistent with Beijing time (UTC/GMT +8.00). If they are inconsistent, the signing will fail.
2. Each account can apply for a maximum of two debugging certificates. Automatic signing occupies the quota of debugging certificates. If two debugging certificates have already been created on the AppGallery Connect platform, subsequent automatic signing for that account will fail.
3. Once the certificate application is successful, it is in the "valid" state. If the certificate status becomes "invalid" or "revoked", it means that the current certificate is no longer available, and all Profiles applied for with this certificate will also be invalidated or revoked. You need to reapply for the certificate and Profile. Once a certificate is revoked, it cannot be restored, and all Profiles applied for with this certificate will be invalidated. Please operate carefully.
4. An application can apply for a maximum of 100 Profile files.
5. After modifying the debugging device, a new debugging Profile will be generated. Please download the new debugging Profile after it takes effect.
6. If the Profile status becomes "invalid" or "revoked", it means that the current Profile is no longer available, and you need to reapply for the Profile.
7. You can use the command hdc shell bm get --udid to obtain the UDID of the mobile phone.

If an account has already created two debugging certificates, using that account for automatic signing will fail, and the following error will be reported:

Summary

This article introduced the HarmonyOS signature mechanism and how to handle the problem of signature conflict management in collaborative development during the development process.

Reference Documents

1. Application/Service Signing
2. Applying for Debugging Certificates
3. Applying for Debugging Profile
4. Registering Debugging Devices