Comprehensive Analysis of the Basic Functions of Asset Store Kit in HarmonyOS Next

This article aims to deeply explore the technical details of the Huawei HarmonyOS Next system (up to API 12 as of now) in developing multilingual e-commerce platforms, and is summarized based on actual development practices. It mainly serves as a vehicle for technical sharing and communication. Mistakes and omissions are inevitable. Colleagues are welcome to put forward valuable opinions and questions so that we can make progress together. This article is original content, and any form of reprint must indicate the source and the original author.
In the security architecture of the HarmonyOS Next system, Asset Store Kit plays a pivotal role. It provides a solid foundation for the storage and management of critical assets and is an important part of ensuring system security and user data privacy.

(I) Introduction

Elaboration of the Important Status - Asset Store Kit is an indispensable part of the HarmonyOS Next ecosystem. It is like a solid fortress, specifically designed to protect those critical assets that are vital to applications and users. These critical assets include password data (such as account passwords), Token data (application credentials), and other sensitive plaintext information (such as bank card numbers, etc.). In today's digital age, the security of these data directly relates to users' property safety, privacy protection, and the normal operation of applications. For example, in mobile payment applications, users' bank card numbers and payment passwords and other critical assets must be properly protected; otherwise, they will face huge risks. Asset Store Kit ensures the security of these critical assets during storage, access, and management through a series of powerful functions and mechanisms, thus providing strong support for the stable operation of the entire HarmonyOS Next system.

Emphasis on the Key Role - Its key role is mainly reflected in two aspects. On the one hand, it provides unified interfaces and methods, enabling developers to store and manage critical assets conveniently and efficiently. Developers do not need to have a deep understanding of the complex underlying security mechanisms. They only need to call the simple and easy-to-use interfaces provided by Asset Store Kit to achieve the secure storage and operation of critical assets. On the other hand, Asset Store Kit effectively prevents critical assets from being illegally obtained and tampered with through various security measures such as encryption algorithms and access control mechanisms. This not only protects users' interests but also enhances users' trust in applications, promoting the widespread use and development of applications. ### (II) Storage Principle of Critical Assets

Dependence on the General Key Store System - The secure storage of critical assets highly depends on the underlying general key store system. The general key store system is like a secure safe, responsible for storing and managing the keys used for encrypting and decrypting critical assets. When an application needs to store critical assets, Asset Store Kit will interact with the general key store system to obtain the corresponding keys. Then, using these keys, it encrypts the critical assets through advanced encryption algorithms (such as the AES256-GCM algorithm) and converts them into ciphertext form before storing them in the ASSET database. For example, when storing a user's password, the encryption key is first obtained from the general key store system, and then the password is encrypted using this key to ensure the confidentiality of the password during storage.

Execution of Encryption and Decryption in a Secure Environment - Encryption and decryption operations are carried out in a secure environment (such as a trusted execution environment). This provides additional security for critical assets. The trusted execution environment is an independent and isolated hardware area with a high level of security. In this environment, even if other parts of the system are maliciously attacked, encryption and decryption operations can still be safely executed without leaking the information of critical assets. For example, when a user logs into an application and needs to verify the password, the password decryption operation is carried out in the trusted execution environment. The decrypted password is compared with the user-input password. Only when the comparison is successful can the user obtain the corresponding access rights. Such a design ensures that the password is always in a secure state during the entire verification process, effectively preventing the password from being stolen or tampered with. ### (III) Access Control Mechanisms

Access Control Based on Ownership - All critical assets are strictly protected by ownership access control, which is the most basic access control method and does not require additional settings for business. The core principle is that only the business that writes the critical asset (i.e., the owner) can access it. For example, in an e-commerce application, a user's order information is written into the critical asset storage by the e-commerce application. Then, only this e-commerce application has the right to access and manage these order information. Even if other applications attempt to obtain this order information, they will be denied access because they do not have the owner identity. This ownership-based access control mechanism effectively prevents cross-access of data between different businesses, ensuring the independence and security of each business's data.

Access Control Based on Lock Screen State - This access control is divided into three levels: accessible after power-on, accessible after the first unlock, and accessible when unlocked, with increasing security levels. - Accessible after power-on: Applicable to some scenarios with relatively low security requirements but a certain need for convenience. For example, for some news and information applications, users may hope to quickly access the content in the application after power-on without having to unlock the device first. In this case, the application can set the relevant critical assets (such as users' browsing history records, etc.) to be accessible after power-on to enhance the user experience. - Accessible after the first unlock: This is a commonly used setting, applicable to most ordinary applications. For example, for users' chat records and other critical assets in social applications, they can be accessed after the user first unlocks the device. This ensures a certain level of security, preventing critical assets from being illegally accessed when the device is not unlocked, and also enables users to conveniently use the application after unlocking, improving the application's usability. - Accessible when unlocked: For applications with extremely high security requirements, such as banking applications or enterprise applications involving important business secrets, the critical assets are usually set to be accessible when unlocked. This means that only when the device is in an unlocked state and the user has passed identity verification (such as password, fingerprint, face, etc.), can these critical assets be accessed. For example, for users' account balances, transaction details, and other critical information in banking applications, they can be accessed only after the user unlocks the device and passes identity verification, maximizing the protection of users' funds safety and privacy.

Access Control Based on Lock Screen Password Setting Status - This access control is defaulted to be off, and developers can decide whether to turn it on according to the actual application scenario. When this function is turned on, critical assets are only allowed to be accessed when the user has set a lock screen password. For example, in a photo album application that stores users' personal privacy photos, developers can choose to turn on the access control based on the lock screen password setting status. Thus, only when the user has set a lock screen password to ensure a certain level of device security can the photos in the album be accessed, effectively preventing others from easily obtaining users' privacy photos when the device is not set with a lock screen password.

Access Control Based on User Authentication - This is also defaulted to be off, and developers can turn it on as needed. Once turned on, critical assets will be allowed to be accessed only after the user has passed identity authentication (such as fingerprint, face, PIN code, etc., any one of the authentication methods). Moreover, developers can set the authentication validity period, with a maximum of 10 minutes. For example, in office applications used within an enterprise, users may need to frequently access some sensitive files (such as company financial statements and other critical assets). By turning on the access control based on user authentication and setting an appropriate authentication validity period (such as 5 minutes), users do not need to repeat the authentication when performing multiple file access operations within 5 minutes after the first authentication, which not only improves work efficiency but also ensures the security of the files. After the authentication validity period expires, if the user wants to access the critical assets again, they need to re-perform the identity authentication. ### (IV) Explanation of Critical Asset Attributes

Attribute List and Meanings (in Tabular Form) | Attribute Name | Meaning | Is it Required? | Explanation | |---|---|---|---| | ALIAS (Alias) | A string used to uniquely identify each critical asset, of type Uint8Array, with a length of 1 - 256 bytes | Optional | It is an important basis for business to find and operate critical assets, similar to an index in a database. The alias of each critical asset must be unique. | | ACCESSIBILITY (Access Control Level) | The access control setting based on the lock screen state, of type number, with the value range detailed in Accessibility | Optional | It determines under which lock screen state the critical asset can be accessed, such as after power-on, after the first unlock, or when unlocked. | | REQUIRE_PASSWORD_SET (Lock Screen Password Requirement) | Whether the critical asset can be accessed only when the lock screen password is set, of type bool | Optional | It can further enhance the security of the critical asset. Decide whether to turn on this restriction according to business needs. | | AUTH_TYPE (Authentication Type) | The type of user authentication required to access the critical asset, of type number, with the value range detailed in AuthType | Optional | It specifies the user authentication method required to access the critical asset, such as fingerprint, face, PIN code, etc. | | SYNC_TYPE (Synchronization Type) | The synchronization type supported by the critical asset, of type number, with the value range detailed in SyncType | Optional | It is used to control the synchronization behavior of the critical asset among multiple devices, such as whether to automatically synchronize, etc. | | IS_PERSISTENT (Persistence Property) | Whether the critical asset needs to be retained when the application is uninstalled, of type bool | Optional | It determines the retention situation of the critical asset after the application is uninstalled. For some data that needs to be stored for a long time (such as users' important configuration information), it can be set to be retained. | | DATA_LABEL_CRITICAL_1 - 4 (Critical Ancillary Information) | Ancillary information of the critical asset, with the content customized by the business and having integrity protection, of type Uint8Array, with a length of 1 - 2048 bytes (1 - 512 bytes before API 12) | Optional | It is used to store important additional information related to the critical asset and ensure the integrity of the information. Once written, it does not support updating. | | DATA_LABEL_NORMAL_1 - 4 (Normal Ancillary Information) | Ancillary information of the critical asset, with the content customized by the业务自定义且无完整性保护，类型为Uint8Array，长度为1 - 2048字节（API12前为1 - 512字节）| 可选 | 存储一般的附属信息，业务可根据需要自由更新内容 | | DATA_LABEL_NORMAL_LOCAL_1 - 4 (本地附属信息) | 关键资产附属的本地信息，内容由业务自定义且无完整性保护，该项信息不会进行同步，类型为Uint8Array，长度为1 - 2048字节 | 可选 | 用于存储仅在本地使用的关键资产相关信息，不会在多设备间同步，可减少不必要的数据传输和存储 | | RETURN_TYPE (查询返回类型) | 关键资产查询返回的结果类型，类型为number，取值范围详见ReturnType | 可选 | 指定查询关键资产时返回结果的格式和内容类型 | | RETURN_LIMIT (查询返回数量限制) | 关键资产查询返回的结果数量，类型为number | 可选 | 限制查询操作返回的关键资产数量，可用于控制数据量和提高查询效率 | | RETURN_OFFSET (查询返回偏移量) | 指定从第几个关键资产开始返回查询结果，取值范围为1 - 65536，类型为number | 可选 | 用于分批查询场景，可实现对大量关键资产的分页查询，提高查询性能和灵活性 | | RETURN_ORDERED_BY (查询结果排序依据) | 仅支持按照附属信息排序，取值范围为asset.Tag.DATA_LABEL_xxx，类型为number | 可选 | 决定查询结果的排序方式，方便业务根据特定需求获取有序的关键资产列表 |

属性在资产识别、访问控制和管理中的作用 - The ALIAS property plays a crucial role in asset identification. Through a unique alias, developers can quickly and accurately locate and operate specific critical assets. For example, in an application that contains multiple users' account passwords, each account password has its corresponding alias. Developers can find and update a specific user's password according to the alias. - The ACCESSIBILITY property directly affects the access control of critical assets. Different access control levels determine under which circumstances critical assets can be accessed, thus protecting critical assets from unauthorized access. - The REQUIRE_PASSWORD_SET property enhances the security of access control. It ensures that only when the device has set a lock screen password can critical assets be accessed, providing an additional protective barrier for critical assets. - The AUTH_TYPE property clarifies the user authentication method required to access critical assets. By specifying an appropriate authentication type, such as requiring fingerprint authentication or PIN code authentication, the access security of critical assets is further improved. - The SYNC_TYPE property plays a role in managing critical assets on multiple devices. Developers can set whether and how critical assets are synchronized according to application requirements to meet users' consistent experience of using the application on different devices. - Other properties such as IS_PERSISTENT, various DATA_LABEL properties, etc., provide rich functions in aspects such as persistent storage of assets, management of additional information, and control of query results, helping developers better manage and utilize critical assets. ### (V) Example Code Demonstration

The following is an ArkTS code example showing how to create a critical asset with specific properties (assuming storing a user's login credentials):

import { asset } from '@kit.AssetStoreKit';
import { util } from '@kit.ArkTS';
import { BusinessError } from '@kit.BasicServicesKit';
function stringToArray(str: string): Uint8Array {
    let textEncoder = new util.TextEncoder();
    return textEncoder.encodeInto(str);
}
// 创建一个关键资产，包含用户名、密码和相关属性
let attr: asset.AssetMap = new Map();
attr.set(asset.Tag.SECRET, stringToArray('userPassword123')); // 假设密码为"userPassword123"
attr.set(asset.Tag.ALIAS, stringToArray('loginCredential')); // 设置别名为"loginCredential"
attr.set(asset.Tag.ACCESSIBILITY, asset.Accessibility.FIRST_UNLOCKED); // 设置为首次解锁后可访问
attr.set(asset.Tag.DATA_LABEL_NORMAL_1, stringToArray('userLoginInfo')); // 存储一些普通附属信息，如登录相关的其他说明
try {
    asset.add(attr).then(() => {
        console.info('Key asset created successfully.');
    }).catch((err: BusinessError) => {
        console.error('Failed to create key asset. Code is ${err.code}, message is ${err.message}');
    });
} catch (error) {
    let err = error as BusinessError;
    console.error('Failed to create key asset. Code is ${err.code}, message is ${err.message}');
}

(VI) Summary and Reflection

Summary of the Key Points of Basic Functions - The basic functions of Asset Store Kit revolve around the secure storage, access control, and management of critical assets. By relying on the general key store system for secure storage, using various access control mechanisms to ensure asset security, and providing rich properties to meet different management needs. Developers need to understand the storage principle of critical assets, master the characteristics and applicable scenarios of various access control methods, and be familiar with the meanings and usages of critical asset properties in order to fully utilize the advantages of Asset Store Kit in application development.
Guidance for Thinking about Application Requirements - For our development, in actual application development, we need to rationally use the functions of Asset Store Kit according to the type of application, user requirements, and security requirements. For example, for financial applications, we should focus on high-strength access control (such as accessible when unlocked, based on user authentication, etc.) and strict password policies (such as setting password length, complexity requirements, etc.); while for some ordinary entertainment applications, we can pay more attention to user experience while ensuring a certain level of security, choosing an appropriate access control level (such as accessible after the first unlock). At the same time, we also need to consider how to reasonably design the properties of critical assets to optimize data storage and query efficiency. In a multi-device application scenario, we should make full use of the synchronization function to ensure the consistency and security of users' data on different devices. In conclusion, we should deeply consider how to perfectly combine the functions of Asset Store Kit with the specific requirements of the application to provide users with a safe and convenient application experience.