This article aims to deeply explore the technical details of the Huawei HarmonyOS Next system (up to API 12 as of now), 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 journey of developing for the HarmonyOS system, the APIs of the Device Certificate Kit are like magical keys that can help developers unlock the door to device security. Today, let's take an in-depth look at these APIs to see how to skillfully call and integrate them to make our applications more secure and reliable.
Firstly, let's get to know some of the core APIs of the Device Certificate Kit. For example, in terms of certificate management, there is theinstallPrivateCertificatefunction, which is used to install private credentials. It requires parameters such as the credential data (keystore), the password (keystorePwd), and the certificate alias (certAlias) to be passed in. It's just like when you want to put an important file into a safe, you need to provide the file itself, the password of the safe, and give the file an easily recognizable name. Here is a calling example:
import { certificateManager } from '@kit.DeviceCertificateKit';
import { BusinessError } from '@kit.BasicServicesKit';
// Hypothetical credential data
let keystore: Uint8Array = new Uint8Array([0x30, 0x82, 0x04, 0x6a, 0x02, 0x01]);
let keystorePwd: string = '123456';
let appKeyUri: string = '';
try {
const res: certificateManager.CMResult = await certificateManager.installPrivateCertificate(keystore, keystorePwd, "testPriCredential");
appKeyUri = (res.uri!= undefined)? res.uri : '';
} catch (err) {
let e: BusinessError = err as BusinessError;
console.error(`Failed to install private certificate. Code: ${e.code}, message: ${e.message}`);
}
Another example is getPrivateCertificate, which is used to obtain private credentials by passing in the identifier (keyUri) of the certificate to get the corresponding certificate information. It's like looking for a specific book in the library according to its book number.
In terms of certificate verification, there is the verify method. Taking the verification of an X509 certificate as an example, you first need to obtain the public key in the certificate and then use the verify method to pass in the public key and relevant data for verification. It's just like when you are verifying a person's identity, you need to check whether his ID card (public key) is genuine and valid.
Here is a more complete example of calling device certificate APIs, covering a series of operations such as initialization, management, and verification. Suppose we want to create a certificate chain and verify it:
import { cert } from '@kit.DeviceCertificateKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { util } from '@kit.ArkTS';
// Certificate chain data (example, needs to be replaced according to the actual situation)
let certChainData = "-----BEGIN CERTIFICATE-----\n" +
"MIID6jCCAtKgAwIBAgIIIM2q/TmRoLcwDQYJKoZIhvcNAQELBQAwWjELMAkGA1\n" +
"UEBhMCRU4xEDAOBgNVBAgTB0VuZ2xhbmQxDzANBgNVBAcTBkxvbmRvbjEMMA\n" +
"oGA1UEChMDdHMyMQwwCgYDVQQLEwN0czIxDDAKBgNVBAMTA3RzMjAeFw0yMzEy\n" +
"MDUwNzM5MDBaFw0yNDEwMzEyMzU5MDBaMGExCzAJBgNVBAYTAkNOMRAwDgYDVQQI\n" +
"EwdKaWFuZ3N1MRAwDgYDVQQHEwdOYW5qaW5nMQwwCgYDVQQKEwN0czMxDDAKBg\n" +
"NVBAsTA3RzMzESMBAGA1UEAxMJMTI3LjAuMC4xMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A\n" +
"MIIBCgKCAQEAtt+2QxUevbolYLp51QGcUpageI4fwGLIqv4fj4aoVnHFOOBqVOVpfCLR\n" +
"p26LFV/F8ebwPyo8YEBKSwXzMD1573rMSbaH9BalscH5lZYAbetXoio6YRvzlcmc\n" +
"rVvLBNMeVnxY86xHpo0MTNyP7W024rZsxWO98xFQVdoiaBC+7+midlisx2Y+7u0\n" +
"zT9GjeUP6JLdLFUZJKUPSTK3jVzw9v1eZQZKYoNfU6vFMd6ndtwW6qEnwpzmmX\n" +
"/UT+p5ThAMH593zszlz330nTSXBjIsGkyvOz9gSB0Z0LAuJj06XUNhGL5xKJYKbdI3\n" +
"8MFQFJKvRHfgTAvVsvAvpBUM2DuBKwIDAQABo4GsMIGpMAkGA1UdEwQCMAA\n" +
"wHQYDVR0OBBYEFDfsHTMZwoA6eaDFlBUyDpka+sYtMAsGA1UdDwQEAwID+DAnBgN\n" +
"VHSUEIDAeBggrBgEFBQcDAQYIKwYBBQUHAwIGCCsGAQUFBwMEMBQGA1UdEQQNM\n" +
"AuCCTEyNy4wLjAuMTARBglghkgBhvhCAQEEBAMCBkAwHgYJYIZIAYb4QgENBBEWD3hj\n" +
"YSBjZXJ0aWZpY2F0ZTANBgkqhkiG9w0BAQsFAAOCAQEAp5vTvXrt8ZpgRJVtzv9ss0lJ\n" +
"izp1fJf+ft5cDXrs7TSD5oHrSW2vk/ZieIMhexU4LFwhs4OE7jK6pgI48Dseqxx7\n" +
"B/KktxhVMJUmVXd9Ayjp6f+BtZlIk0cArPuoXToXjsV8caTGBXHRdzxpAk/w9syc\n" +
"GYrbH9TrdNMuTizOb+k268oKXUageZNxHmd7YvOXkcNgrd29jzwXKDYYiUa1DI\n" +
"SzDnYaJOgPt0B/5izhoWNK7GhJDy9KEuLURcTSWFysbbnljwO9INPT9MmlS83PdAg\n" +
"NiS8VXF4pce1W9U5jH7d7k0JDVSXybebe1iPFphsZpYM/NE+jap+mPy1nTCbf9g==\n" +
"-----END CERTIFICATE-----\n" +
"-----BEGIN CERTIFICATE-----\n" +
"MIIC0zCCAoWgAwIBAgIIXpLoPpQVWnkwBQYDK2VwMFoxCzAJBgNVBAYTAkV\n" +
"OMRAwDgYDVQQIEwdFbmdsYW5kMQ8wDQYDVQQHEwZMb25kb24xDDAKBgNVBAoT\n" +
"A3RzMTEMMAoGA1UECxMDdHMxMQwwCgYDVQQDEwN0czEwHhcNMjMxMjA1MDczNzA\n" +
"wWhcNMjQwOTAxMjM1OTAwWjBaMQswCQYDVQQGEwJFTjEQMA4GA1UECBMHRW5nbGFu\n" +
"DEPMA0GA1UEBxMGTG9uZG9uMQwwCgYDVQQKEwN0czIxDDAKBgNVBAsTA3RzMjEMM\n" +
"AoGA1UEAxMDdHMyMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAtt+2QxUev\n" +
"bolYLp51QGcUpageI4fwGLIqv4fj4aoVnHFOOBqVOVpfCLRp26LFV/F8ebwPyo8YEBK\n" +
"SwXzMD1573rMSbaH9BalscH5lZYAbetXoio6YRvzlcmcrVvLBNMeVnxY86xHpo0\n" +
"MNTyP7W024rZsxWO98xFQVdoiaBC+7+midlisx2Y+7u0jzT9GjeUP6JLdLFUZJKUP\n" +
"STK3jVzw9v1eZQZKYoNfU6vFMd6ndtwW6qEnwpzmmX/UT+p5ThAMH593zszlz\n" +
"330nTSXBjIsGkyvOz9gSB0Z0LAuJj06XUNhGL5xKJYKbdI38MFQFJKvRHfgTAvVsvAv\n" +
"pBUM2DuBKwIDAQABo28wbTAMBgNVHRMEBTADAQH/MB0GA1UdDgQWBBQ3\n" +
"7B0zGcKAOnmgxZQVMg6ZGvrGLTALBgNVHQ8EBAMCAQYwEQYJYIZIAYb4QgEBBAQDAg\n" +
"AHMB4GCGCGSAGG+EIBDQQRFg94Y2EgY2VydGlmaWNhdGUwBQYDK2VwA0EAuasLBe\n" +
"55YgvFb4wmHeohylc9r8cFGS1LNQ5UcSn3sGqMYf6ehnef16NLuCW6upHCs8Sui4iAMvs\n" +
"uKPWR9dKBA==\n" +
"-----END CERTIFICATE-----\n" +
"-----BEGIN CERTIFICATE-----\n" +
"MIIB3zCCAZGgAwIBAgIIWQvOEDl+ya4wBQYDK2VwMFoxCzAJBgNVBAYTAkVO\n" +
"MRAwDgYDVQQIEwdFbmdsYW5kMQ8wDQYDVQQHEwZMb25kb24xDDAKBgNVBAoT\n" +
"A3RzMTEMMAoGA1UECxMDdHMxMQwwCgYDVQQDEwN0czEwHhcNMjMxMjA1MDAwMD\n" +
"AwWhcNMjQxMjA0MjM1OTU5WjBaMQswCQYDVQQGEwJFTjEQMA4GA1UECBMHRW5nbGFuZ\n" +
"DEPMA0GA1UEBxMGTG9uZG9uMQwwCgYDVQQKEwN0czExDDAKBgNVBAsTA3RzMTEM\n" +
"AoGA1UEAxMDdHMxMCowBQYDK2VwAyEAuxadj1ww0LqPN24zr28jcSOlSWAe0QdLyRF+Z\n" +
"gG6klKjdTBzMBIGA1UdEwEB/wQIMAYBAf8CARQwHQYDVR0OBBYEFNSgpoQvfxR8\n" +
"A1Y4St8NjOHkRpm4MAsGA1UdDwQEAwIBBjARBglghkgBhvhCAQEEBAMCAAcwHgYJ\n" +
"YIZIAYb4QgENBBEWD3hjYSBjZXJ0aWZpY2F0ZTAFBgMrZXADQQAblBgoa72X/K13W\n" +
"OvcKW0fqBgFKvLy85hWD6Ufi61k4ProQiZzMK+0+y9jReKelPx/zRdCCgSbQroAR2mV\n" +
"xjoE\n" +
"-----END CERTIFICATE-----\n";
// Certificate chain validation data (example, needs to be replaced according to the actual situation)
const param: cert.CertChainValidationParameters = {
date: '20231212080000Z',
trustAnchors: [{
CAPubKey: new Uint8Array([0x30, 0x2a, 0x30, 0x05, 0x06, 0x03, 0x2b, 0x65, 0x70,
0x03, 0x21, 0x00, 0xbb, 0x16, 0x9d, 0x8f, 0x5c, 0x30, 0xd0, 0xba, 0x8f, 0x37, 0x6e,
0x33, 0xaf, 0x6f, 0x23, 0x71, 0x23, 0xa5, 0x49, 0x60, 0x1e, 0xd1, 0x07, 0x4b, 0xc9,
0x11, 0x7e, 0x66, 0x01, 0xba, 0x92, 0x52]),
CASubject: new Uint8Array([0x30, 0x5a, 0x31, 0x0b, 0x30, 0x09, 0x06, 0x03, 0x55,
0x04, 0x06, 0x13, 0x02, 0x45, 0x4e, 0x31, 0x10, 0x30, 0x0e, 0x06, 0x03, 0x55, 0x04,
0x08, 0x13, 0x07, 0x45, 0x6e, 0x67, 0x6c, 0x61, 0x6e, 0x64, 0x31, 0x0f, 0x30, 0x0d,
0x06, 0x03, 0x55, 0x04, 0x07, 0x13, 0x06, 0x4c, 0x6f, 0x6e, 0x64, 0x6f, 0x6e, 0x31,
0x0c, 0x30, 0x0a, 0x06, 0x03, 0x55, 0x04, 0x0a, 0x13, 0x03, 0x74, 0x73, 0x31, 0x31,
0x0c, 0x30, 0x0a, 0x06, 0x03, 0x55, 0x04, 0x0b, 0x13, 0x03, 0x74, 0x73, 0x31, 0x31,
0x0c, 0x30, 0x0a, 0x06, 0x03, 0x55, 0x04, 0x03, 0x13, 0x03, 0x74, 0x73, 0x31])
}]
};
let textEncoder = new util.TextEncoder();
const encodingBlob: cert.EncodingBlob = {
data: textEncoder.encodeInto(certChainData),
encodingFormat: cert.EncodingFormat.FORMAT_PEM
};
let x509CertChain: cert.X509CertChain = {} as cert.X509CertChain;
try {
x509CertChain = await cert.createX509CertChain(encodingBlob);
} catch (err) {
let e: BusinessError = err as BusinessError;
console.error(`createX509CertChain failed, errCode: ${e.code}, errMsg: ${e.message}`);
}
try {
let certList = x509CertChain.getCertList();
} catch (err) {
let e: BusinessError = err as BusinessError;
console.error(`X509CertChain getCertList failed, errCode: ${e.code}, errMsg: ${e.message}`);
}
try {
const validationRes = await x509CertChain.validate(param);
console.log('X509CertChain validate success');
} catch (err) {
console.error('X509CertChain validate failed');
}
During the process of using these APIs, we may encounter some common errors. For example, incorrect parameter passing may lead to API call failures. It's just like when you pass the wrong type of parameters to a function, and the function naturally doesn't know how to handle them. At this time, we need to carefully check whether the types, formats, and value ranges of the parameters meet the requirements of the API. Additionally, insufficient permissions can also be an issue. If the relevant permissions are not configured correctly, the API call may be rejected by the system. It's like trying to open a door without the key, which definitely won't work. We need to ensure that permissions such as ohos.permission.ACCESS_CERT_MANAGER are correctly configured in the module.json5 file.
To make it more convenient for everyone to understand the commonly used APIs of the Device Certificate Kit, here is a table of API names and their function descriptions:
| API Name | Function Description | Parameter Description |
| ---- | ---- | ---- |
| installPrivateCertificate | Install private credentials | keystore (credential data), keystorePwd (password), certAlias (certificate alias) |
| getPrivateCertificate | Obtain private credentials | keyUri (certificate identifier) |
| createX509CertChain | Create an X509 certificate chain object | Certificate chain data (encodingBlob) |
| getCertList | Obtain the list of certificates in the certificate chain | None (for the already created certificate chain object) |
| validate | Validate the certificate chain | Validation parameters (param, including information such as date and trust anchors) |
In conclusion, mastering the API calls and integration of the Device Certificate Kit is a crucial step in building secure and reliable HarmonyOS applications. By using these APIs reasonably, we can effectively manage certificates and ensure the security of communication between devices. Just like skilled craftsmen using various tools to create exquisite works, developers can also use these APIs to build secure and stable HarmonyOS applications. I hope that everyone will practice and explore more in actual development. If you encounter problems, don't give up easily. Refer to the documentation, carefully troubleshoot, and I believe you will surely be able to solve the problems and make your applications shine in the HarmonyOS ecosystem. Come on, fellow developer friends!
Top comments (0)