【最佳实践】鸿蒙5应用安全开发规范 (AGC安全服务指南)

引言
在鸿蒙5应用开发中，安全性是至关重要的考量因素。AppGallery Connect (AGC) 提供了一系列安全服务来帮助开发者构建更安全的应用程序。本文将详细介绍鸿蒙5应用的安全开发规范，并结合AGC安全服务的代码实现，为开发者提供全面的安全实践指南。

一、鸿蒙5应用安全架构概述
鸿蒙5应用的安全架构建立在以下几个核心原则上：

​​数据最小化原则​​：只收集必要的数据
​​权限最小化原则​​：只申请必要的权限
​​端到端加密原则​​：数据传输全程加密
​​防御性编程原则​​：假设所有输入都是恶意的
​​持续验证原则​​：持续验证应用运行环境的安全性
二、AGC安全服务集成

1. 添加安全SDK依赖
   在entry/build.gradle中添加依赖：

dependencies {
implementation 'com.huawei.agconnect:agconnect-auth-harmony:1.9.0.300'
implementation 'com.huawei.agconnect:agconnect-appsecurity-harmony:1.9.0.300'
implementation 'com.huawei.agconnect:agconnect-clouddb-harmony:1.9.0.300'
}
2. 初始化AGC安全服务
import agconnect from '@agconnect/api';
import '@agconnect/instance';
import '@agconnect/appsecurity';
import '@agconnect/auth';

export default class EntryAbility extends Ability {
onCreate(want, launchParam) {
// 初始化AGC核心服务
agconnect.instance().init(this.context);

// 初始化应用安全检查
this.initAppSecurity();
}

private async initAppSecurity() {
try {
const appSecurity = require('@agconnect/appsecurity').appSecurityService;
await appSecurity.initialize();

// 检查应用完整性
const result = await appSecurity.verifyApp();
if (!result.isValid) {
console.error("应用完整性校验失败:", result.errorMsg);
// 处理异常情况
}
} catch (error) {
console.error("安全服务初始化失败:", error);
}
}
}
三、身份认证与授权

1. 用户认证最佳实践
   import { AuthService, AuthUser } from '@agconnect/auth';

export class AuthManager {
private authService: AuthService;

constructor() {
this.authService = agconnect.auth().getAuthService();
}

// 匿名登录
async anonymousLogin(): Promise {
try {
const user = await this.authService.signInAnonymously();
console.log("匿名登录成功:", user.getUid());
return user;
} catch (error) {
console.error("匿名登录失败:", error);
throw error;
}
}

// 手机号登录（带验证码）
async phoneLogin(countryCode: string, phoneNumber: string, verifyCode: string): Promise {
try {
const credential = agconnect.auth.PhoneAuthProvider.credentialWithVerifyCode(
countryCode,
phoneNumber,
verifyCode
);
const user = await this.authService.signIn(credential);
console.log("手机号登录成功:", user.getUid());
return user;
} catch (error) {
console.error("手机号登录失败:", error);
throw error;
}
}

// 登出
async logout(): Promise {
try {
await this.authService.signOut();
console.log("用户已登出");
} catch (error) {
console.error("登出失败:", error);
throw error;
}
}

// 获取当前用户
getCurrentUser(): AuthUser | null {
return this.authService.getCurrentUser();
}

// 监听认证状态变化
setupAuthListener(callback: (user: AuthUser | null) => void): void {
this.authService.onAuthStateChanged(callback);
}
}
2. 权限控制示例
import abilityAccessCtrl from '@ohos.abilityAccessCtrl';

export class PermissionManager {
private atManager: abilityAccessCtrl.AtManager;

constructor() {
this.atManager = abilityAccessCtrl.createAtManager();
}

// 检查权限
async checkPermission(permission: string): Promise {
try {
const result = await this.atManager.checkAccessToken(
globalThis.abilityContext,
permission
);
return result === abilityAccessCtrl.GrantStatus.PERMISSION_GRANTED;
} catch (error) {
console.error("检查权限失败:", error);
return false;
}
}

// 请求权限
async requestPermission(permission: string): Promise {
try {
const result = await this.atManager.requestPermissionsFromUser(
globalThis.abilityContext,
[permission]
);
return result.authResults[0] === abilityAccessCtrl.GrantStatus.PERMISSION_GRANTED;
} catch (error) {
console.error("请求权限失败:", error);
return false;
}
}

// 检查并请求权限（组合操作）
async ensurePermission(permission: string): Promise {
const hasPermission = await this.checkPermission(permission);
if (!hasPermission) {
return await this.requestPermission(permission);
}
return true;
}
}
四、数据安全保护

1. 本地数据加密存储
   import dataPreferences from '@ohos.data.preferences';
   import cipher from '@ohos.security.crypto';

export class SecureStorage {
private preferences: dataPreferences.Preferences;
private cipher: cipher.Crypto;

constructor(name: string) {
this.preferences = dataPreferences.getPreferencesSync(globalThis.abilityContext, name);

// 初始化加密模块（使用AES-256-GCM）
const key = new Uint8Array(32); // 实际应用中应从安全位置获取密钥
const spec: cipher.SymKeySpec = { algName: 'AES256', key: key };
this.cipher = cipher.createSymKeyGenerator('AES256').generateSymKey(spec);
}

// 加密数据
private async encrypt(data: string): Promise {
const params: cipher.GcmParams = {
algName: 'AES256',
iv: new Uint8Array(12), // 初始化向量
aad: new Uint8Array(0), // 附加认证数据
authTagLen: 16 // 认证标签长度
};
const transformer = cipher.createCipher('AES256|GCM|PKCS7');
return await transformer.init(this.cipher, params)
.then(() => transformer.update(new TextEncoder().encode(data)))
.then(() => transformer.doFinal());
}

// 解密数据
private async decrypt(encrypted: Uint8Array): Promise {
const params: cipher.GcmParams = {
algName: 'AES256',
iv: new Uint8Array(12),
aad: new Uint8Array(0),
authTagLen: 16
};
const transformer = cipher.createCipher('AES256|GCM|PKCS7');
const result = await transformer.init(this.cipher, params, false)
.then(() => transformer.update(encrypted))
.then(() => transformer.doFinal());
return new TextDecoder().decode(result);
}

// 安全存储数据
async putSecure(key: string, value: string): Promise {
try {
const encrypted = await this.encrypt(value);
await this.preferences.put(key, Array.from(encrypted));
await this.preferences.flush();
} catch (error) {
console.error("安全存储失败:", error);
throw error;
}
}

// 安全读取数据
async getSecure(key: string): Promise<string | null> {
try {
const encrypted = await this.preferences.get(key, []);
if (encrypted.length === 0) return null;
return await this.decrypt(new Uint8Array(encrypted));
} catch (error) {
console.error("安全读取失败:", error);
throw error;
}
}
}
2. 安全网络通信
import http from '@ohos.net.http';
import ssl from '@ohos.security.crypto';

export class SecureHttpClient {
private httpRequest: http.HttpRequest;

constructor() {
this.httpRequest = http.createHttp();
}

// 配置SSL证书校验
private async configureSSL(): Promise {
try {
// 加载可信CA证书（应来自安全存储）
const caCert = '-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----';
const certData = new TextEncoder().encode(caCert);

// 创建X509证书对象
const cert: ssl.X509Cert = ssl.createX509Cert(certData);

// 配置SSL选项
const sslOpts: http.HttpRequestOptions = {
protocol: http.HttpProtocol.HTTPS,
usingCache: true,
usingProxy: false,
ca: cert
};

this.httpRequest.setExtraOptions(sslOpts);
} catch (error) {
console.error("SSL配置失败:", error);
throw error;
}
}

// 安全POST请求
async securePost(url: string, data: object): Promise {
try {
await this.configureSSL();

const response = await this.httpRequest.request(
url,
{
method: http.RequestMethod.POST,
header: {
'Content-Type': 'application/json'
},
extraData: JSON.stringify(data)
}
);

if (response.responseCode === http.ResponseCode.OK) {
return JSON.parse(response.result);
} else {
throw new Error(HTTP请求失败: ${response.responseCode});
}
} catch (error) {
console.error("安全请求失败:", error);
throw error;
}
}
}
五、应用完整性保护

1. 运行时完整性检查
   import appSecurity from '@agconnect/appsecurity';

export class IntegrityChecker {
private appSecurity: appSecurity.AppSecurityService;

constructor() {
this.appSecurity = appSecurity.appSecurityService;
}

// 检查应用完整性
async checkIntegrity(): Promise {
try {
const result = await this.appSecurity.verifyApp();
if (!result.isValid) {
console.error("应用完整性校验失败:", result.errorMsg);
return false;
}
return true;
} catch (error) {
console.error("完整性检查异常:", error);
return false;
}
}

// 定期检查（每5分钟）
startPeriodicCheck(): void {
setInterval(async () => {
const isIntegrityValid = await this.checkIntegrity();
if (!isIntegrityValid) {
// 处理异常情况，如退出应用或提示用户
console.error("检测到应用完整性被破坏");
// 可以上报安全事件到服务器
this.reportSecurityIncident('app_integrity_failure');
}
}, 5 * 60 * 1000); // 5分钟
}

// 上报安全事件
private async reportSecurityIncident(eventType: string): Promise {
try {
const httpClient = new SecureHttpClient();
await httpClient.securePost('https://your-security-api.com/incidents', {
eventType,
timestamp: new Date().toISOString(),
deviceInfo: await this.getDeviceInfo()
});
} catch (error) {
console.error("安全事件上报失败:", error);
}
}

// 获取设备信息（匿名化处理）
private async getDeviceInfo(): Promise