• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Importing a Key in Plaintext (ArkTS)
2
3
4This topic walks you through on how to import an AES 256-bit key and an RSA 2048-bit key. For details about the scenarios and supported algorithm specifications, see [Supported Algorithms](huks-key-import-overview.md#supported-algorithms).
5
6
7## How to Develop
8
91. Set the alias **keyAlias** of the key to import.
10   The key alias cannot exceed 128 bytes.
11
122. Encapsulate the key property set and key material.
13   - The key property set must contain [HuksKeyAlg](../../reference/apis-universal-keystore-kit/js-apis-huks.md#hukskeyalg), [HuksKeySize](../../reference/apis-universal-keystore-kit/js-apis-huks.md#hukskeysize), and [HuksKeyPurpose](../../reference/apis-universal-keystore-kit/js-apis-huks.md#hukskeypurpose).
14   - The key material must comply with the [HUKS key material format](huks-concepts.md#key-material-format) and is used to fill the **inData** field of [HuksOptions](../../reference/apis-universal-keystore-kit/js-apis-huks.md#huksoptions) in Uint8Array format.
15
163. Use [huks.importKeyItem](../../reference/apis-universal-keystore-kit/js-apis-huks.md#huksimportkeyitem9) to import the key.
17
18```ts
19/* Import an AES 256-bit key in plaintext. This example uses callback-based APIs. */
20import { huks } from '@kit.UniversalKeystoreKit'
21
22/* Key material */
23let plainTextSize32 = new Uint8Array([
24  0xfb, 0x8b, 0x9f, 0x12, 0xa0, 0x83, 0x19, 0xbe, 0x6a, 0x6f, 0x63, 0x2a, 0x7c, 0x86, 0xba, 0xca,
25  0x64, 0x0b, 0x88, 0x96, 0xe2, 0xfa, 0x77, 0xbc, 0x71, 0xe3, 0x0f, 0x0f, 0x9e, 0x3c, 0xe5, 0xf9
26]);
27/* 1. Set the key alias. */
28let keyAlias = 'AES256Alias_sample';
29/* 2. Encapsulate the key property set and key material. */
30
31let properties: Array<huks.HuksParam> = [
32  {
33    tag: huks.HuksTag.HUKS_TAG_ALGORITHM,
34    value: huks.HuksKeyAlg.HUKS_ALG_AES
35  },
36  {
37    tag: huks.HuksTag.HUKS_TAG_KEY_SIZE,
38    value: huks.HuksKeySize.HUKS_AES_KEY_SIZE_256
39  },
40  {
41    tag: huks.HuksTag.HUKS_TAG_PURPOSE,
42    value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_ENCRYPT | huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_DECRYPT
43  },
44]
45let options: huks.HuksOptions = {
46  properties: properties,
47  inData: plainTextSize32
48};
49/* 3. Import the key in plaintext. */
50try {
51  huks.importKeyItem(keyAlias, options, (error, data) => {
52    if (error) {
53      console.error(`callback: importKeyItem failed` + JSON.stringify(error));
54    } else {
55      console.info(`callback: importKeyItem success`);
56    }
57  });
58} catch (error) {
59  console.error(`callback: importKeyItem input arg invalid` + JSON.stringify(error));
60}
61```
62
63```ts
64/* Import an RSA 2048-bit key in plaintext. This example uses callback-based APIs. */
65import { huks } from '@kit.UniversalKeystoreKit'
66
67let rsa2048KeyPairMaterial = new Uint8Array([
68  0x01, 0x00, 0x00, 0x00, // Key algorithm (expressed in little-endian) huks.HuksKeyAlg.HUKS_ALG_RSA = 1
69  0x00, 0x08, 0x00, 0x00, // Key size (bit): 2048
70  0x00, 0x01, 0x00, 0x00, // Length of modulus n (byte): 256
71  0x03, 0x00, 0x00, 0x00, // Length of the public key exponent e (byte): 3
72  0x00, 0x01, 0x00, 0x00, // Length of the private key exponent d (byte): 256
73  // Modulus n
74  0xc5, 0x35, 0x62, 0x48, 0xc4, 0x92, 0x87, 0x73, 0x0d, 0x42, 0x96, 0xfc, 0x7b, 0x11, 0x05, 0x06,
75  0x0f, 0x8d, 0x66, 0xc1, 0x0e, 0xad, 0x37, 0x44, 0x92, 0x95, 0x2f, 0x6a, 0x55, 0xba, 0xec, 0x1d,
76  0x54, 0x62, 0x0a, 0x4b, 0xd3, 0xc7, 0x05, 0xe4, 0x07, 0x40, 0xd9, 0xb7, 0xc2, 0x12, 0xcb, 0x9a,
77  0x90, 0xad, 0xe3, 0x24, 0xe8, 0x5e, 0xa6, 0xf8, 0xd0, 0x6e, 0xbc, 0xd1, 0x69, 0x7f, 0x6b, 0xe4,
78  0x2b, 0x4e, 0x1a, 0x65, 0xbb, 0x73, 0x88, 0x6b, 0x7c, 0xaf, 0x7e, 0xd0, 0x47, 0x26, 0xeb, 0xa5,
79  0xbe, 0xd6, 0xe8, 0xee, 0x9c, 0xa5, 0x66, 0xa5, 0xc9, 0xd3, 0x25, 0x13, 0xc4, 0x0e, 0x6c, 0xab,
80  0x50, 0xb6, 0x50, 0xc9, 0xce, 0x8f, 0x0a, 0x0b, 0xc6, 0x28, 0x69, 0xe9, 0x83, 0x69, 0xde, 0x42,
81  0x56, 0x79, 0x7f, 0xde, 0x86, 0x24, 0xca, 0xfc, 0xaa, 0xc0, 0xf3, 0xf3, 0x7f, 0x92, 0x8e, 0x8a,
82  0x12, 0x52, 0xfe, 0x50, 0xb1, 0x5e, 0x8c, 0x01, 0xce, 0xfc, 0x7e, 0xf2, 0x4f, 0x5f, 0x03, 0xfe,
83  0xa7, 0xcd, 0xa1, 0xfc, 0x94, 0x52, 0x00, 0x8b, 0x9b, 0x7f, 0x09, 0xab, 0xa8, 0xa4, 0xf5, 0xb4,
84  0xa5, 0xaa, 0xfc, 0x72, 0xeb, 0x17, 0x40, 0xa9, 0xee, 0xbe, 0x8f, 0xc2, 0xd1, 0x80, 0xc2, 0x0d,
85  0x44, 0xa9, 0x59, 0x44, 0x59, 0x81, 0x3b, 0x5d, 0x4a, 0xde, 0xfb, 0xae, 0x24, 0xfc, 0xa3, 0xd9,
86  0xbc, 0x57, 0x55, 0xc2, 0x26, 0xbc, 0x19, 0xa7, 0x9a, 0xc5, 0x59, 0xa3, 0xee, 0x5a, 0xef, 0x41,
87  0x80, 0x7d, 0xf8, 0x5e, 0xc1, 0x1d, 0x32, 0x38, 0x41, 0x5b, 0xb6, 0x92, 0xb8, 0xb7, 0x03, 0x0d,
88  0x3e, 0x59, 0x0f, 0x1c, 0xb3, 0xe1, 0x2a, 0x95, 0x1a, 0x3b, 0x50, 0x4f, 0xc4, 0x1d, 0xcf, 0x73,
89  0x7c, 0x14, 0xca, 0xe3, 0x0b, 0xa7, 0xc7, 0x1a, 0x41, 0x4a, 0xee, 0xbe, 0x1f, 0x43, 0xdd, 0xf9,
90  // Public key exponent e
91  0x01, 0x00, 0x01,
92  // Private key exponent d
93  0x88, 0x4b, 0x82, 0xe7, 0xe3, 0xe3, 0x99, 0x75, 0x6c, 0x9e, 0xaf, 0x17, 0x44, 0x3e, 0xd9, 0x07,
94  0xfd, 0x4b, 0xae, 0xce, 0x92, 0xc4, 0x28, 0x44, 0x5e, 0x42, 0x79, 0x08, 0xb6, 0xc3, 0x7f, 0x58,
95  0x2d, 0xef, 0xac, 0x4a, 0x07, 0xcd, 0xaf, 0x46, 0x8f, 0xb4, 0xc4, 0x43, 0xf9, 0xff, 0x5f, 0x74,
96  0x2d, 0xb5, 0xe0, 0x1c, 0xab, 0xf4, 0x6e, 0xd5, 0xdb, 0xc8, 0x0c, 0xfb, 0x76, 0x3c, 0x38, 0x66,
97  0xf3, 0x7f, 0x01, 0x43, 0x7a, 0x30, 0x39, 0x02, 0x80, 0xa4, 0x11, 0xb3, 0x04, 0xd9, 0xe3, 0x57,
98  0x23, 0xf4, 0x07, 0xfc, 0x91, 0x8a, 0xc6, 0xcc, 0xa2, 0x16, 0x29, 0xb3, 0xe5, 0x76, 0x4a, 0xa8,
99  0x84, 0x19, 0xdc, 0xef, 0xfc, 0xb0, 0x63, 0x33, 0x0b, 0xfa, 0xf6, 0x68, 0x0b, 0x08, 0xea, 0x31,
100  0x52, 0xee, 0x99, 0xef, 0x43, 0x2a, 0xbe, 0x97, 0xad, 0xb3, 0xb9, 0x66, 0x7a, 0xae, 0xe1, 0x8f,
101  0x57, 0x86, 0xe5, 0xfe, 0x14, 0x3c, 0x81, 0xd0, 0x64, 0xf8, 0x86, 0x1a, 0x0b, 0x40, 0x58, 0xc9,
102  0x33, 0x49, 0xb8, 0x99, 0xc6, 0x2e, 0x94, 0x70, 0xee, 0x09, 0x88, 0xe1, 0x5c, 0x4e, 0x6c, 0x22,
103  0x72, 0xa7, 0x2a, 0x21, 0xdd, 0xd7, 0x1d, 0xfc, 0x63, 0x15, 0x0b, 0xde, 0x06, 0x9c, 0xf3, 0x28,
104  0xf3, 0xac, 0x4a, 0xa8, 0xb5, 0x50, 0xca, 0x9b, 0xcc, 0x0a, 0x04, 0xfe, 0x3f, 0x98, 0x68, 0x81,
105  0xac, 0x24, 0x53, 0xea, 0x1f, 0x1c, 0x6e, 0x5e, 0xca, 0xe8, 0x31, 0x0d, 0x08, 0x12, 0xf3, 0x26,
106  0xf8, 0x5e, 0xeb, 0x10, 0x27, 0xae, 0xaa, 0xc3, 0xad, 0x6c, 0xc1, 0x89, 0xdb, 0x7d, 0x5a, 0x12,
107  0x55, 0xad, 0x11, 0x19, 0xa1, 0xa9, 0x8f, 0x0b, 0x6d, 0x78, 0x8d, 0x1c, 0xdf, 0xe5, 0x63, 0x82,
108  0x0b, 0x7d, 0x23, 0x04, 0xb4, 0x75, 0x8c, 0xed, 0x77, 0xfc, 0x1a, 0x85, 0x29, 0x11, 0xe0, 0x61,
109]);
110
111/* 1. Set the key alias. */
112let keyAlias = 'RSA_sample';
113/* 2. Encapsulate the key property set and key material. */
114let properties: Array<huks.HuksParam> = [
115  {
116    tag: huks.HuksTag.HUKS_TAG_ALGORITHM,
117    value: huks.HuksKeyAlg.HUKS_ALG_RSA
118  },
119  {
120    tag: huks.HuksTag.HUKS_TAG_KEY_SIZE,
121    value: huks.HuksKeySize.HUKS_RSA_KEY_SIZE_2048
122  },
123  {
124    // This tag indicates the usage of the imported key, which cannot be changed after the import.
125    tag: huks.HuksTag.HUKS_TAG_PURPOSE,
126    value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_ENCRYPT | huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_DECRYPT
127  },
128  {
129    // This tag indicates the type of the key to be imported.
130    tag: huks.HuksTag.HUKS_TAG_IMPORT_KEY_TYPE,
131    // The value here means to import a key parit. To import a public key, set value to HUKS_KEY_TYPE_PUBLIC_KEY.
132    value: huks.HuksImportKeyType.HUKS_KEY_TYPE_KEY_PAIR
133  },
134]
135let options: huks.HuksOptions = {
136  properties: properties,
137  inData: rsa2048KeyPairMaterial
138};
139/* 3. Import the key in plaintext. */
140try {
141  huks.importKeyItem(keyAlias, options, (error, data) => {
142    if (error) {
143      console.error(`callback: importKeyItem failed` + error);
144    } else {
145      console.info(`callback: importKeyItem success`);
146    }
147  });
148} catch (error) {
149  console.error(`callback: importKeyItem input arg invalid` + error);
150}
151```
152
153
154## Verification
155
156Use [huks.isKeyItemExist](../../reference/apis-universal-keystore-kit/js-apis-huks.md#huksiskeyitemexist9) to check whether the key exists. If the key exists, the key is successfully imported.
157
158```ts
159import { huks } from '@kit.UniversalKeystoreKit';
160
161let keyAlias = 'AES256Alias_sample';
162let isKeyExist = false;
163
164let keyProperties: Array<huks.HuksParam> = [
165  {
166    tag: huks.HuksTag.HUKS_TAG_ALGORITHM,
167    value: huks.HuksKeyAlg.HUKS_ALG_AES
168  }
169]
170let huksOptions: huks.HuksOptions = {
171  properties: keyProperties, // It cannot be empty.
172  inData: new Uint8Array(new Array()) // It cannot be empty.
173}
174try {
175  huks.isKeyItemExist(keyAlias, huksOptions, (error, data) => {
176    if (error) {
177      console.error(`callback: isKeyItemExist failed, ` + JSON.stringify(error));
178    } else {
179      if (data !== null && data.valueOf() !== null) {
180        isKeyExist = data.valueOf();
181        console.info(`callback: isKeyItemExist success, isKeyExist = ${isKeyExist}`);
182      }
183    }
184  });
185} catch (error) {
186  console.error(`callback: isKeyItemExist input arg invalid, ` + JSON.stringify(error));
187}
188```
189