diff --git a/CODEOWNERS b/CODEOWNERS
index 1723d5288fa2d4fa89dff9a3c2999c31370b55fd..a57ea8f6e10f53e073eb37e4fe33e1fffea8b84d 100644
--- a/CODEOWNERS
+++ b/CODEOWNERS
@@ -129,11 +129,38 @@ zh-cn/device-dev/subsystems/subsys-toolchain-bytrace-guide.md @Austin23
zh-cn/device-dev/subsystems/subsys-toolchain-hdc-guide.md @Austin23
zh-cn/device-dev/subsystems/subsys-toolchain-hiperf.md @Austin23
zh-cn/device-dev/subsystems/subsys-xts-guide.md @Austin23
-
+zh-cn/application-dev/quick-start/arkts-get-started.md @HelloCrease @tomatodevboy @s10021109
+zh-cn/application-dev/quick-start/arkts-basic-syntax-overview.md @HelloCrease @tomatodevboy @s10021109
+zh-cn/application-dev/quick-start/arkts-declarative-ui-description.md @HelloCrease @tomatodevboy @s10021109
+zh-cn/application-dev/quick-start/arkts-create-custom-components.md @HelloCrease @tomatodevboy @s10021109
+zh-cn/application-dev/quick-start/arkts-page-custom-components-lifecycle.md @HelloCrease @tomatodevboy @s10021109
+zh-cn/application-dev/quick-start/arkts-builder.md @HelloCrease @tomatodevboy @s10021109
+zh-cn/application-dev/quick-start/arkts-builderparam.md @HelloCrease @tomatodevboy @s10021109
+zh-cn/application-dev/quick-start/arkts-style.md @HelloCrease @tomatodevboy @s10021109
+zh-cn/application-dev/quick-start/arkts-extend.md @HelloCrease @tomatodevboy @s10021109
+zh-cn/application-dev/quick-start/arkts-statestyles.md @HelloCrease @tomatodevboy @s10021109
+zh-cn/application-dev/quick-start/arkts-state-management-overview.md @HelloCrease @tomatodevboy @s10021109
+zh-cn/application-dev/quick-start/arkts-state.md @HelloCrease @tomatodevboy @s10021109
+zh-cn/application-dev/quick-start/arkts-prop.md @HelloCrease @tomatodevboy @s10021109
+zh-cn/application-dev/quick-start/arkts-link.md @HelloCrease @tomatodevboy @s10021109
+zh-cn/application-dev/quick-start/arkts-provide-and-consume.md @HelloCrease @tomatodevboy @s10021109
+zh-cn/application-dev/quick-start/arkts-observed-and-objectlink.md @HelloCrease @tomatodevboy @s10021109
+zh-cn/application-dev/quick-start/arkts-application-state-management-overview.md @HelloCrease @tomatodevboy @s10021109
+zh-cn/application-dev/quick-start/arkts-localstorage.md @HelloCrease @tomatodevboy @s10021109
+zh-cn/application-dev/quick-start/arkts-appstorage.md @HelloCrease @tomatodevboy @s10021109
+zh-cn/application-dev/quick-start/arkts-persiststorage.md @HelloCrease @tomatodevboy @s10021109
+zh-cn/application-dev/quick-start/arkts-environment.md @HelloCrease @tomatodevboy @s10021109
+zh-cn/application-dev/quick-start/arkts-other-state-mgmt-functions-overview.md @HelloCrease @tomatodevboy @s10021109
+zh-cn/application-dev/quick-start/arkts-watch.md @HelloCrease @tomatodevboy @s10021109
+zh-cn/application-dev/quick-start/arkts-two-way-sync.md @HelloCrease @tomatodevboy @s10021109
+zh-cn/application-dev/quick-start/arkts-rendering-control-overview.md @HelloCrease @tomatodevboy @s10021109
+zh-cn/application-dev/quick-start/arkts-rendering-control-ifelse.md @HelloCrease @tomatodevboy @s10021109
+zh-cn/application-dev/quick-start/arkts-rendering-control-foreach.md @HelloCrease @tomatodevboy @s10021109
+zh-cn/application-dev/quick-start/arkts-rendering-control-lazyforeach.md @HelloCrease @tomatodevboy @s10021109
zh-cn/application-dev/ability/ @RayShih @littlejerry1 @gwang2008 @ccllee @chengxingzhen
zh-cn/application-dev/IDL/ @RayShih @littlejerry1 @gwang2008 @ccllee @chengxingzhen
zh-cn/application-dev/device-usage-statistics/ @chenmingJay @ningningW @tangtiantian2021 @nan-xiansen @iceice1001
-zh-cn/application-dev/ui/ @HelloCrease @huaweimaxuchu @tomatodevboy @niulihua
+zh-cn/application-dev/ui/ @HelloCrease @tomatodevboy @niulihua
zh-cn/application-dev/notification/ @RayShih @jayleehw @li-weifeng2 @currydavids
zh-cn/application-dev/windowmanager/ @ge-yafang @zhangqiang183 @zhouyaoying @zxg-gitee @nobuggers
zh-cn/application-dev/webgl/ @zengyawen @zhangqiang183 @wind_zj @zxg-gitee
@@ -208,8 +235,8 @@ zh-cn/application-dev/device/vibrator-overview.md @ningningW @hellohyh001 @butte
zh-cn/application-dev/device/vibrator-guidelines.md @ningningW @hellohyh001 @butterls @star-wind-snow-and-rain
zh-cn/application-dev/device/sample-server-overview.md @ningningW @hughes802 @zhangzhengxue @mamba-ting
zh-cn/application-dev/device/sample-server-guidelines.md @ningningW @hughes802 @zhangzhengxue @mamba-ting
-zh-cn/application-dev/reference/arkui-js/ @HelloCrease @huaweimaxuchu @niulihua @tomatodevboy
-zh-cn/application-dev/reference/arkui-ts/ @HelloCrease @huaweimaxuchu @niulihua @tomatodevboy
+zh-cn/application-dev/reference/arkui-js/ @HelloCrease @niulihua @tomatodevboy
+zh-cn/application-dev/reference/arkui-ts/ @HelloCrease @niulihua @tomatodevboy
zh-cn/application-dev/reference/native-lib @zengyawen @gongjunsong @liwentao_uiw @BlackStone
zh-cn/application-dev/quick-start/start-overview.md @ge-yafang
zh-cn/application-dev/quick-start/start-with-ets-stage.md @ge-yafang
@@ -241,7 +268,7 @@ zh-cn/application-dev/quick-start/arkts-state-mgmt-application-level.md @gaoyong
zh-cn/application-dev/quick-start/arkts-dynamic-ui-elememt-building.md @gaoyong @niejiteng @jumozhanjiang @HelloCrease
zh-cn/application-dev/quick-start/arkts-rendering-control.md @gaoyong @niejiteng @jumozhanjiang @HelloCrease
zh-cn/application-dev/quick-start/arkts-restrictions-and-extensions.md @gaoyong @niejiteng @jumozhanjiang @HelloCrease
-zh-cn/application-dev/napi/napi-guidelines.md @RayShih @huaweimaxuchu @niulihua @tomatodevboy
+zh-cn/application-dev/napi/napi-guidelines.md @RayShih @niulihua @tomatodevboy
zh-cn/application-dev/napi/drawing-guidelines.md @zengyawen @zhangqiang183 @wind_zj @zxg-gitee
zh-cn/application-dev/napi/rawfile-guidelines.md @ningningW @Buda-Liu @budda-wang @yangqing3
zh-cn/application-dev/reference/js-service-widget-ui/ @HelloCrease
@@ -258,7 +285,7 @@ zh-cn/application-dev/reference/apis/js-apis-abilityDelegatorRegistry.md @little
zh-cn/application-dev/reference/apis/js-apis-abilityrunninginfo.md @littlejerry1 @RayShih @gwang2008 @chengxingzhen
zh-cn/application-dev/reference/apis/js-apis-abilitystagecontext.md @littlejerry1 @RayShih @gwang2008 @chengxingzhen
zh-cn/application-dev/reference/apis/js-apis-accessibility-extension-context.md @mupceet @RayShih @mupceet @gaoxi785
-zh-cn/application-dev/reference/apis/js-apis-animator.md @huaweimaxuchu @HelloCrease @niulihua @tomatodevboy
+zh-cn/application-dev/reference/apis/js-apis-animator.md @HelloCrease @niulihua @tomatodevboy
zh-cn/application-dev/reference/apis/js-apis-appAccount.md @nianCode @zengyawen @JiDong-CS @murphy1984
zh-cn/application-dev/reference/apis/js-apis-application-ability.md @littlejerry1 @RayShih @gwang2008 @chengxingzhen
zh-cn/application-dev/reference/apis/js-apis-application-abilityConstant.md @littlejerry1 @RayShih @gwang2008 @chengxingzhen
@@ -393,7 +420,7 @@ zh-cn/application-dev/reference/apis/js-apis-list.md @gongjunsong @ge-yafang @fl
zh-cn/application-dev/reference/apis/js-apis-logs.md @gongjunsong @ge-yafang @flyingwolf @BlackStone
zh-cn/application-dev/reference/apis/js-apis-media.md @liuyuehua1 @zengyawen @xxb-wzy @currydavids
zh-cn/application-dev/reference/apis/js-apis-medialibrary.md @panqinxu @zengyawen @bubble_mao @jinhaihw
-zh-cn/application-dev/reference/apis/js-apis-mediaquery.md @huaweimaxuchu @HelloCrease @niulihua @tomatodevboy
+zh-cn/application-dev/reference/apis/js-apis-mediaquery.md @HelloCrease @niulihua @tomatodevboy
zh-cn/application-dev/reference/apis/js-apis-missionManager.md @littlejerry1 @RayShih @gwang2008 @chengxingzhen
zh-cn/application-dev/reference/apis/js-apis-mouseevent.md @yuanxinying @ningningW @cococoler @alien0208
zh-cn/application-dev/reference/apis/js-apis-net-connection.md @zhang-hai-feng @zengyawen @jyh926 @gaoxi785
@@ -412,13 +439,13 @@ zh-cn/application-dev/reference/apis/js-apis-privacyManager.md @nianCode @zengya
zh-cn/application-dev/reference/apis/js-apis-process.md @gongjunsong @ge-yafang @flyingwolf @BlackStone
zh-cn/application-dev/reference/apis/js-apis-processrunninginfo.md @littlejerry1 @RayShih @gwang2008 @chengxingzhen
zh-cn/application-dev/reference/apis/js-apis-processrunninginformation.md @littlejerry1 @RayShih @gwang2008 @chengxingzhen
-zh-cn/application-dev/reference/apis/js-apis-prompt.md @huaweimaxuchu @HelloCrease @niulihua @tomatodevboy
+zh-cn/application-dev/reference/apis/js-apis-prompt.md @HelloCrease @niulihua @tomatodevboy
zh-cn/application-dev/reference/apis/js-apis-queue.md @gongjunsong @ge-yafang @flyingwolf @BlackStone
zh-cn/application-dev/reference/apis/js-apis-radio.md @zhang-hai-feng @zengyawen @jyh926 @gaoxi785
zh-cn/application-dev/reference/apis/js-apis-reminderAgent.md @jayleehw @RayShih @li-weifeng2 @currydavids
zh-cn/application-dev/reference/apis/js-apis-request.md @feng-aiwen @ningningW @nagexiucai @murphy1984
zh-cn/application-dev/reference/apis/js-apis-resource-manager.md @Buda-Liu @ningningW @mengjingzhimo @yangqing3
-zh-cn/application-dev/reference/apis/js-apis-router.md @huaweimaxuchu @HelloCrease @niulihua @tomatodevboy
+zh-cn/application-dev/reference/apis/js-apis-router.md @HelloCrease @niulihua @tomatodevboy
zh-cn/application-dev/reference/apis/js-apis-rpc.md @xuepianpian @RayShih @zhaopeng_gitee @vagrant_world
zh-cn/application-dev/reference/apis/js-apis-runninglock.md @aqxyjay @zengyawen @aqxyjay @alien0208
zh-cn/application-dev/reference/apis/js-apis-screen.md @zhangqiang183 @ge-yafang @zhouyaoying @zxg-gitee @nobuggers
@@ -427,14 +454,14 @@ zh-cn/application-dev/reference/apis/js-apis-securityLabel.md @panqinxu @zengyaw
zh-cn/application-dev/reference/apis/js-apis-sensor.md @hellohyh001 @ningningW @butterls @star-wind-snow-and-rain
zh-cn/application-dev/reference/apis/js-apis-service-extension-ability.md @littlejerry1 @RayShih @gwang2008 @chengxingzhen
zh-cn/application-dev/reference/apis/js-apis-service-extension-context.md @littlejerry1 @RayShih @gwang2008 @chengxingzhen
-zh-cn/application-dev/reference/apis/js-apis-settings.md @tetex @ge-yafang @cnzhaoxiaohu @anning7
+zh-cn/application-dev/reference/apis/js-apis-settings.md @xue-seu @ge-yafang
zh-cn/application-dev/reference/apis/js-apis-sim.md @zhang-hai-feng @zengyawen @jyh926 @gaoxi785
zh-cn/application-dev/reference/apis/js-apis-sms.md @zhang-hai-feng @zengyawen @jyh926 @gaoxi785
zh-cn/application-dev/reference/apis/js-apis-socket.md @zhang-hai-feng @zengyawen @jyh926 @gaoxi785
zh-cn/application-dev/reference/apis/js-apis-stack.md @gongjunsong @ge-yafang @flyingwolf @BlackStone
zh-cn/application-dev/reference/apis/js-apis-statfs.md @panqinxu @zengyawen @bubble_mao @jinhaihw
zh-cn/application-dev/reference/apis/js-apis-storage-statistics.md @panqinxu @zengyawen @bubble_mao @jinhaihw
-zh-cn/application-dev/reference/apis/js-apis-system-app.md @huaweimaxuchu @HelloCrease @niulihua @tomatodevboy
+zh-cn/application-dev/reference/apis/js-apis-system-app.md @HelloCrease @niulihua @tomatodevboy
zh-cn/application-dev/reference/apis/js-apis-system-battery.md @aqxyjay @zengyawen @aqxyjay @alien0208
zh-cn/application-dev/reference/apis/js-apis-system-bluetooth.md @cheng_guohong @RayShih @cheng_guohong @quanli125
zh-cn/application-dev/reference/apis/js-apis-system-brightness.md @aqxyjay @zengyawen @aqxyjay @alien0208
@@ -445,14 +472,14 @@ zh-cn/application-dev/reference/apis/js-apis-system-device.md @mupceet @zengyawe
zh-cn/application-dev/reference/apis/js-apis-system-fetch.md @zhang-hai-feng @zengyawen @jyh926 @gaoxi785
zh-cn/application-dev/reference/apis/js-apis-system-file.md @panqinxu @zengyawen @bubble_mao @jinhaihw
zh-cn/application-dev/reference/apis/js-apis-system-location.md @cheng_guohong @RayShih @cheng_guohong @xiangkejin123
-zh-cn/application-dev/reference/apis/js-apis-system-mediaquery.md @huaweimaxuchu @HelloCrease @niulihua @tomatodevboy
+zh-cn/application-dev/reference/apis/js-apis-system-mediaquery.md @HelloCrease @niulihua @tomatodevboy
zh-cn/application-dev/reference/apis/js-apis-system-network.md @zhang-hai-feng @zengyawen @jyh926 @gaoxi785
zh-cn/application-dev/reference/apis/js-apis-system-notification.md @jayleehw @RayShih @li-weifeng2 @currydavids
zh-cn/application-dev/reference/apis/js-apis-system-package.md @shuaytao @RayShih @wangzhen107 @inter515
zh-cn/application-dev/reference/apis/js-apis-system-parameter.md @mupceet @zengyawen @handyohos @nan-xiansen
-zh-cn/application-dev/reference/apis/js-apis-system-prompt.md @huaweimaxuchu @HelloCrease @niulihua @tomatodevboy
+zh-cn/application-dev/reference/apis/js-apis-system-prompt.md @HelloCrease @niulihua @tomatodevboy
zh-cn/application-dev/reference/apis/js-apis-system-request.md @zhang-hai-feng @zengyawen @jyh926 @gaoxi785
-zh-cn/application-dev/reference/apis/js-apis-system-router.md @huaweimaxuchu @HelloCrease @niulihua @tomatodevboy
+zh-cn/application-dev/reference/apis/js-apis-system-router.md @HelloCrease @niulihua @tomatodevboy
zh-cn/application-dev/reference/apis/js-apis-system-sensor.md @hellohyh001 @ningningW @butterls @star-wind-snow-and-rain
zh-cn/application-dev/reference/apis/js-apis-system-storage.md @feng-aiwen @ge-yafang @gong-a-shi @logic42
zh-cn/application-dev/reference/apis/js-apis-system-time.md @feng-aiwen @ningningW @illybyy @murphy1984
@@ -534,7 +561,7 @@ zh-cn/application-dev/reference/apis/js-apis-configPolicy.md @liuzuming @ningnin
zh-cn/application-dev/reference/apis/js-apis-cooperate.md @yuanxinying @ningningW @cococoler @alien0208
zh-cn/application-dev/reference/apis/js-apis-cryptoFramework.md @gaoyong @zengyawen @niejiteng @jumozhanjiang
zh-cn/application-dev/reference/apis/js-apis-cert.md @gaoyong @zengyawen @niejiteng @jumozhanjiang
-zh-cn/application-dev/reference/apis/js-apis-curve.md @huaweimaxuchu @HelloCrease @niulihua @tomatodevboy
+zh-cn/application-dev/reference/apis/js-apis-curve.md @HelloCrease @niulihua @tomatodevboy
zh-cn/application-dev/reference/apis/js-apis-defaultAppManager.md @shuaytao @RayShih @wangzhen107 @inter515
zh-cn/application-dev/reference/apis/js-apis-distributedBundle.md @shuaytao @RayShih @wangzhen107 @inter515
zh-cn/application-dev/reference/apis/js-apis-distributedKVStore.md @feng-aiwen @ge-yafang @gong-a-shi @logic42
@@ -555,11 +582,11 @@ zh-cn/application-dev/reference/apis/js-apis-hiviewdfx-hiappevent.md @stone2050
zh-cn/application-dev/reference/apis/js-apis-inputmethod-subtype.md @feng-aiwen @ningningW @SuperShrimp @murphy1984
zh-cn/application-dev/reference/apis/js-apis-installer.md @shuaytao @RayShih @wangzhen107 @inter515
zh-cn/application-dev/reference/apis/js-apis-launcherBundleManager.md @shuaytao @RayShih @wangzhen107 @inter515
-zh-cn/application-dev/reference/apis/js-apis-matrix4.md @huaweimaxuchu @HelloCrease @niulihua @tomatodevboy
+zh-cn/application-dev/reference/apis/js-apis-matrix4.md @HelloCrease @niulihua @tomatodevboy
zh-cn/application-dev/reference/apis/js-apis-net-ethernet.md @zhang-hai-feng @zengyawen @jyh926 @gaoxi785
zh-cn/application-dev/reference/apis/js-apis-net-sharing.md @zhang-hai-feng @zengyawen @jyh926 @gaoxi785
zh-cn/application-dev/reference/apis/js-apis-nfctech.md @cheng_guohong @RayShih @cheng_guohong @quanli125
-zh-cn/application-dev/reference/apis/js-apis-promptAction.md @huaweimaxuchu @HelloCrease @niulihua @tomatodevboy
+zh-cn/application-dev/reference/apis/js-apis-promptAction.md @HelloCrease @niulihua @tomatodevboy
zh-cn/application-dev/reference/apis/js-apis-reminderAgentManager.md @chenmingJay @ningningW @nan-xiansen @iceice1001
zh-cn/application-dev/reference/apis/js-apis-resourceschedule-deviceStandby.md @chenmingJay @ningningW @nan-xiansen @iceice1001
zh-cn/application-dev/reference/apis/js-apis-resourceschedule-backgroundTaskManager.md @chenmingJay @ningningW @nan-xiansen @iceice1001
@@ -572,7 +599,12 @@ zh-cn/application-dev/reference/apis/js-apis-system-parameterV9.md @mupceet @zen
zh-cn/application-dev/reference/apis/js-apis-tagSession.md @cheng_guohong @RayShih @cheng_guohong @quanli125
zh-cn/application-dev/reference/apis/js-apis-userFileManager.md @panqinxu @zengyawen @bubble_mao @jinhaihw
zh-cn/application-dev/reference/apis/js-apis-useriam-faceauth.md @gaoyong @zengyawen @niejiteng @jumozhanjiang
-
+zh-cn/application-dev/reference/apis/js-apis-arkui-componentSnapshot.md @HelloCrease @niulihua @tomatodevboy
+zh-cn/application-dev/reference/apis/js-apis-arkui-drawableDescriptor.md @HelloCrease @niulihua @tomatodevboy
+zh-cn/application-dev/reference/apis/js-apis-arkui-UIContext.md @HelloCrease @niulihua @tomatodevboy
+zh-cn/application-dev/reference/apis/js-apis-font.md @HelloCrease @niulihua @tomatodevboy
+zh-cn/application-dev/reference/apis/js-apis-plugincomponent.md @HelloCrease @niulihua @tomatodevboy
+zh-cn/application-dev/reference/apis/js-apis-uiappearance.md @HelloCrease @niulihua @tomatodevboy
zh-cn/application-dev/reference/errorcodes/errorcode-ability.md @RayShih
zh-cn/application-dev/reference/errorcodes/errorcode-access-token.md @zengyawen
zh-cn/application-dev/reference/errorcodes/errorcode-accessibility.md @RayShih
diff --git a/en/application-dev/application-models/arkts-ui-widget-update-by-status.md b/en/application-dev/application-models/arkts-ui-widget-update-by-status.md
index b27958c66d3e174a66c80c90e46cdd71f5ecf668..5fb323813741a81e01b120507561e377995b7d90 100644
--- a/en/application-dev/application-models/arkts-ui-widget-update-by-status.md
+++ b/en/application-dev/application-models/arkts-ui-widget-update-by-status.md
@@ -1,7 +1,8 @@
# Updating Widget Content by State
+There are cases where multiple copies of the same widget are added to the home screen to accommodate different needs. In these cases, the widget content needs to be dynamically updated based on the state. This topic exemplifies how this is implemented.
-There are cases where multiple copies of the same widget are added to the home screen to accommodate different needs. In these cases, the widget content needs to be dynamically updated based on the state. This topic exemplifies how this is implemented. In the following example, two weather widgets are added to the home screen: one for displaying the weather of London, and the other Beijing, both configured to be updated at 07:00 every morning. The widget provider detects the target city, and then displays the city-specific weather information on the widgets.
+In the following example, two copies of the weather widget are added to the home screen: one for displaying the weather of London, and the other Beijing, both configured to be updated at 07:00 every morning. The widget provider detects the target city, and then displays the city-specific weather information on the widgets.
- Widget configuration file: Configure the widget to be updated at 07:00 every morning.
@@ -94,7 +95,7 @@ There are cases where multiple copies of the same widget are added to the home s
import formProvider from '@ohos.app.form.formProvider';
import formBindingData from '@ohos.app.form.formBindingData';
import FormExtensionAbility from '@ohos.app.form.FormExtensionAbility';
- import dataStorage from '@ohos.data.storage'
+ import dataPreferences from '@ohos.data.preferences';
export default class EntryFormAbility extends FormExtensionAbility {
onAddForm(want) {
@@ -102,10 +103,10 @@ There are cases where multiple copies of the same widget are added to the home s
let isTempCard: boolean = want.parameters[formInfo.FormParam.TEMPORARY_KEY];
if (isTempCard === false) {// If the widget is a normal one, the widget information is persisted.
console.info('Not temp card, init db for:' + formId);
- let storeDB = dataStorage.getStorageSync(this.context.filesDir + 'myStore')
- storeDB.putSync('A' + formId, 'false');
- storeDB.putSync('B' + formId, 'false');
- storeDB.flushSync();
+ let storeDB = dataPreferences.getPreferences(this.context, 'mystore')
+ storeDB.put('A' + formId, 'false');
+ storeDB.put('B' + formId, 'false');
+ storeDB.flush();
}
let formData = {};
return formBindingData.createFormBindingData(formData);
@@ -113,24 +114,24 @@ There are cases where multiple copies of the same widget are added to the home s
onRemoveForm(formId) {
console.info('onRemoveForm, formId:' + formId);
- let storeDB = dataStorage.getStorageSync(this.context.filesDir + 'myStore')
- storeDB.deleteSync('A' + formId);
- storeDB.deleteSync('B' + formId);
+ let storeDB = dataPreferences.getPreferences(this.context, 'mystore')
+ storeDB.delete('A' + formId);
+ storeDB.delete('B' + formId);
}
// If the widget is a temporary one, it is recommended that the widget information be persisted when the widget is converted to a normal one.
onCastToNormalForm(formId) {
console.info('onCastToNormalForm, formId:' + formId);
- let storeDB = dataStorage.getStorageSync(this.context.filesDir + 'myStore')
- storeDB.putSync('A' + formId, 'false');
- storeDB.putSync('B' + formId, 'false');
- storeDB.flushSync();
+ let storeDB = dataPreferences.getPreferences(this.context, 'myStore')
+ storeDB.put('A' + formId, 'false');
+ storeDB.put('B' + formId, 'false');
+ storeDB.flush();
}
onUpdateForm(formId) {
- let storeDB = dataStorage.getStorageSync(this.context.filesDir + 'myStore')
- let stateA = storeDB.getSync('A' + formId, 'false').toString()
- let stateB = storeDB.getSync('B' + formId, 'false').toString()
+ let storeDB = dataPreferences.getPreferences(this.context, 'myStore')
+ let stateA = storeDB.get('A' + formId, 'false').toString()
+ let stateB = storeDB.get('B' + formId, 'false').toString()
// Update textA in state A.
if (stateA === 'true') {
let formInfo = formBindingData.createFormBindingData({
@@ -150,17 +151,17 @@ There are cases where multiple copies of the same widget are added to the home s
onFormEvent(formId, message) {
// Store the widget state.
console.info('onFormEvent formId:' + formId + 'msg:' + message);
- let storeDB = dataStorage.getStorageSync(this.context.filesDir + 'myStore')
+ let storeDB = dataPreferences.getPreferences(this.context, 'myStore')
let msg = JSON.parse(message)
if (msg.selectA != undefined) {
console.info('onFormEvent selectA info:' + msg.selectA);
- storeDB.putSync('A' + formId, msg.selectA);
+ storeDB.put('A' + formId, msg.selectA);
}
if (msg.selectB != undefined) {
console.info('onFormEvent selectB info:' + msg.selectB);
- storeDB.putSync('B' + formId, msg.selectB);
+ storeDB.put('B' + formId, msg.selectB);
}
- storeDB.flushSync();
+ storeDB.flush();
}
};
```
@@ -168,4 +169,4 @@ There are cases where multiple copies of the same widget are added to the home s
> **NOTE**
>
-> When the local database is used for widget information persistence, it is recommended that [TEMPORARY_KEY](../reference/apis/js-apis-app-form-formInfo.md#formparam) be used to determine whether the currently added widget is a normal one in the [onAddForm](../reference/apis/js-apis-app-form-formExtensionAbility.md#onaddform) lifecycle callback. If the widget is a normal one, the widget information is directly persisted. If the widget is a temporary one, the widget information is persisted when the widget is converted to a normal one ([onCastToNormalForm](../reference/apis/js-apis-app-form-formExtensionAbility.md#oncasttonormalform)). In addition, the persistent widget information needs to be deleted when the widget is destroyed ([onRemoveForm](../reference/apis/js-apis-app-form-formExtensionAbility.md#onremoveform)), preventing the database size from continuously increasing due to repeated widget addition and deletion.
+> When the local database is used for widget information persistence, it is recommended that [TEMPORARY_KEY](../reference/apis/js-apis-app-form-formInfo.md#formparam) be used in the [onAddForm](../reference/apis/js-apis-app-form-formExtensionAbility.md#onaddform) lifecycle callback to determine whether the currently added widget is a normal one. If the widget is a normal one, the widget information is directly persisted. If the widget is a temporary one, the widget information is persisted when the widget is converted to a normal one ([onCastToNormalForm](../reference/apis/js-apis-app-form-formExtensionAbility.md#oncasttonormalform)). In addition, the persistent widget information needs to be deleted when the widget is destroyed ([onRemoveForm](../reference/apis/js-apis-app-form-formExtensionAbility.md#onremoveform)), preventing the database size from continuously increasing due to repeated widget addition and deletion.
diff --git a/en/application-dev/faqs/Readme-EN.md b/en/application-dev/faqs/Readme-EN.md
index 5d67f4ab8aafba955da4a882b382f9df25896f3b..21effd689817299aabdaaab34724edd8349622dc 100644
--- a/en/application-dev/faqs/Readme-EN.md
+++ b/en/application-dev/faqs/Readme-EN.md
@@ -3,7 +3,7 @@
- [Full SDK Compilation](full-sdk-compile-guide.md)
- [Switching to Full SDK](full-sdk-switch-guide.md)
- [Application Model Development](faqs-ability.md)
-- ArkUI Framework Development (ArkTS)
+- ArkUI Development (ArkTS)
- [ArkTS Syntax Usage](faqs-arkui-arkts.md)
- [ArkUI Component Development (ArkTS)](faqs-arkui-component.md)
- [ArkUI Layout Development (ArkTS)](faqs-arkui-layout.md)
diff --git a/en/application-dev/file-management/app-sandbox-directory.md b/en/application-dev/file-management/app-sandbox-directory.md
index 2da514469b80369d2660d14a0fd715e282e57adf..f9cfb0317c29bff58664ed894f585a5127943fa5 100644
--- a/en/application-dev/file-management/app-sandbox-directory.md
+++ b/en/application-dev/file-management/app-sandbox-directory.md
@@ -47,12 +47,12 @@ The following figure shows the application file directories. The path of a file
3. Level 3 directories **el1/** and **el2/**: indicate directories for files of different encryption levels (els).
- **el1**: directory for the data that can be accessed once the device starts. This directory contains device-focused files.
- **el2**: directory for the data that can be accessed only after at lease one successful unlocking operation (by PIN, fingerprint, or facial authentication, or password-free sign-in) upon the start of the device. This directory contains user-focused files.
- Unless otherwise required, application data is placed in the **el2** directory for security purposes. However, the data that needs to be accessed before the screen is unlocked (such as the clock, alarm, and wallpaper data) can be placed in the **el1** directory. For details about how to switch to and modify the **el** directories, see [Obtaining and Modifying el Directories](../application-models/application-context-stage.md#obtaining-and-modifying-encryption-areas).
+ Unless otherwise required, application data is placed in the **el2** directory for security purposes. However, the data that needs to be accessed before the screen is unlocked (such as the clock, alarm, and wallpaper data) can be placed in the **el1** directory. For details about how to switch to and modify the **el** directories, see [Obtaining and Modifying el Directories](../application-models/application-context-stage.md#obtaining-and-modifying-encryption-levels).
4. Level 4 and level 5 directories:
The application's global data is stored in the **files**, **cache**, **preferences**, **temp**, and **distributedfiles** folders in **base**. You can use **ApplicationContext** to obtain the application file paths of these folders.
- You can use **UIAbilityContext**, **AbilityStageContext**, and **ExtensionContext** to obtain application file paths related to the OpenHarmoy Ability Package (HAP). When the HAP is uninstalled, the files stored in these directories are automatically deleted, without affecting the files in app-level directories. An application in the development state contains one or more HAPs. For details, see [Application Package Structure in Stage Mode](../quick-start/application-package-structure-stage.md).
+ You can use **UIAbilityContext**, **AbilityStageContext**, and **ExtensionContext** to obtain application file paths related to the OpenHarmony Ability Package (HAP). When the HAP is uninstalled, the files stored in these directories are automatically deleted, without affecting the files in app-level directories. An application in the development state contains one or more HAPs. For details, see [Application Package Structure in Stage Mode](../quick-start/application-package-structure-stage.md).
For details about how to obtain the context and application file paths, see [Context (Stage Model)](../application-models/application-context-stage.md).
diff --git a/en/application-dev/reference/apis/js-apis-cryptoFramework.md b/en/application-dev/reference/apis/js-apis-cryptoFramework.md
index afb1bd3f8d80a74415c359af492492286364008c..422104663d3902e3d02488ca879e4089394a7f83 100644
--- a/en/application-dev/reference/apis/js-apis-cryptoFramework.md
+++ b/en/application-dev/reference/apis/js-apis-cryptoFramework.md
@@ -8,2250 +8,2346 @@ The **cryptoFramework** module shields underlying hardware and algorithm librari
## Modules to Import
-```javascript
+```js
import cryptoFramework from "@ohos.security.cryptoFramework"
```
## Result
-Enumerates the error codes.
+ Enumerates the operation results.
-**System capability**: SystemCapability.Security.CryptoFramework
+ **System capability**: SystemCapability.Security.CryptoFramework
| Name | Value | Description |
| ------------------------------------- | -------- | ---------------------------- |
-| INVALID_PARAMS | 401 | Invalid parameters. |
+| INVALID_PARAMS | 401 | Invalid parameters. |
| NOT_SUPPORT | 801 | Unsupported operation. |
| ERR_OUT_OF_MEMORY | 17620001 | Memory error. |
| ERR_RUNTIME_ERROR | 17620002 | Runtime error. |
-| ERR_CRYPTO_OPERATION | 17630001 | Cryptographic operation error. |
+| ERR_CRYPTO_OPERATION | 17630001 | Failed to invoke the third-party cryptographic API. |
## DataBlob
Defines a binary data array.
-**System capability**: SystemCapability.Security.CryptoFramework
+ **System capability**: SystemCapability.Security.CryptoFramework
| Name| Type | Readable| Writable| Description |
| ---- | ---------- | ---- | ---- | ------ |
| data | Uint8Array | Yes | Yes | Binary data array. |
+## ParamsSpec
-## cryptoFramework.createMac
-
-createMac(algName : string) : Mac
+Defines the parameters used for encryption and decryption. For the symmetric encryption and decryption modes that require parameters such as the initialization vector (IV), you need to construct a child class object and pass it to [init()](#init-2). If the IV is not required (for example, the ECB mode), pass in **null** in [init()](#init-2).
-Creates a **Mac** instance for message authentication code (MAC) operations.
+**System capability**: SystemCapability.Security.CryptoFramework
-For details about the supported specifications, see [HMAC Algorithm Specifications](../../security/cryptoFramework-overview.md#hmac-algorithm-specifications).
+| Name | Type | Readable| Writable| Description |
+| ------- | ------ | ---- | ---- | ------------------------------------------------------------ |
+| algName | string | Yes | Yes | Symmetric encryption and decryption parameters. Options: - **IvParamsSpec**: applicable to the CBC, CTR, OFB, and CFB modes. - **GcmParamsSpec**: applicable to the GCM mode. - **CcmParamsSpec**: applicable to the CCM mode.|
-**System capability**: SystemCapability.Security.CryptoFramework
+> **NOTE**
+>
+> The **params** parameter in [init()](#init-2) is of the **ParamsSpec** type (parent class). However, a specific child class object (such as **IvParamsSpec**) needs to be passed in. When constructing the child class object, you need to set **algName** for the parent class **ParamsSpec** to specify the child class object in **init()**.
-**Parameters**
+## IvParamsSpec
-| Name | Type | Mandatory| Description |
-| ------- | ------ | ---- | ------------------------------------------------------------ |
-| algName | string | Yes | Digest algorithm. For details about the supported algorithms, see [HMAC Algorithm Specifications](../../security/cryptoFramework-overview.md#hmac-algorithm-specifications).|
+Defines the child class of [ParamsSpec](#paramsspec). It is used as the parameters of [init()](#init-2) during symmetric encryption and decryption. **IvParamsSpec** applies to the encryption and decryption modes such as CBC, CTR, OFB, and CFB, which use only the IV.
-**Return value**
+**System capability**: SystemCapability.Security.CryptoFramework
-| Type| Description |
-| ---- | --------------------------------------- |
-| Mac | [Mac](#mac) instance created.|
+| Name| Type | Readable| Writable| Description |
+| ---- | --------------------- | ---- | ---- | ------------------------------------------------------------ |
+| iv | [DataBlob](#datablob) | Yes | Yes | IV for encryption and decryption. Options: - AES CBC, CTR, OFB, or CFB mode: 16-byte IV - 3DES CBC, OFB, or CFB mode: 8-byte IV|
-**Error codes**
+> **NOTE**
+>
+> Before passing [init()](#init-2), specify **algName** for its parent class [ParamsSpec](#paramsspec).
-| ID| Error Message |
-| -------- | ------------------ |
-| 17620001 | memory error. |
+## GcmParamsSpec
-**Example**
+Defines the child class of [ParamsSpec](#paramsspec) for the GCM mode. It is used as the parameters of [init()](#init-2) during symmetric encryption and decryption. **GcmParamsSpec** applies to the GCM mode.
-```javascript
-import cryptoFramework from "@ohos.security.cryptoFramework"
+**System capability**: SystemCapability.Security.CryptoFramework
-var mac;
-try {
- // Set algName based on the algorithm supported.
- mac = cryptoFramework.createMac("SHA256");
-} catch (error) {
- console.error("[Promise]: error code: " + error.code + ", message is: " + error.message);
-}
-```
+| Name | Type | Readable| Writable| Description |
+| ------- | --------------------- | ---- | ---- | ------------------------------------------------------------ |
+| iv | [DataBlob](#datablob) | Yes | Yes | IV, which is of 12 bytes. |
+| aad | [DataBlob](#datablob) | Yes | Yes | Additional authentication data (AAD), which is of 8 bytes. |
+| authTag | [DataBlob](#datablob) | Yes | Yes | Authentication tag, which is of 16 bytes. When the GCM mode is used for encryption, the last 16 bytes of the [DataBlob](#datablob) output by [doFinal()](#dofinal-2) are used as the **authTag** in [GcmParamsSpec](#gcmparamsspec) of [init()](#init-2). |
-## Mac
+> **NOTE**
+>
+> Before passing [init()](#init-2), specify **algName** for its parent class [ParamsSpec](#paramsspec).
-Provides APIs for MAC operations. Before using any API of the **Mac** class, you must create a **Mac** instance by using [createMac](#cryptoframeworkcreatemac).
+## CcmParamsSpec
-### Attributes
+Defines the child class of [ParamsSpec](#paramsspec) for the CCM mode. It is used as the parameters of [init()](#init-2) during symmetric encryption and decryption. **CcmParamsSpec** applies to the CCM mode.
**System capability**: SystemCapability.Security.CryptoFramework
-| Name | Type | Readable| Writable| Description |
-| ------- | ------ | ---- | ---- | -------------------- |
-| algName | string | Yes | No | Digest algorithm to use.|
+| Name | Type | Readable| Writable| Description |
+| ------- | --------------------- | ---- | ---- | ------------------------------------------------------------ |
+| iv | [DataBlob](#datablob) | Yes | Yes | IV, which is of 7 bytes. |
+| aad | [DataBlob](#datablob) | Yes | Yes | Additional authentication data (AAD), which is of 8 bytes. |
+| authTag | [DataBlob](#datablob) | Yes | Yes | Authentication tag, which is of 12 bytes. When the CCM mode is used for encryption, the last 12 bytes of the [DataBlob](#datablob) output by [doFinal()](#dofinal-2) are used as the **authTag** in [CcmParamsSpec](#ccmparamsspec) of [init()](#init-2).|
-### init
+> **NOTE**
+>
+> Before passing [init()](#init-2), specify **algName** for its parent class [ParamsSpec](#paramsspec).
-init(key : SymKey, callback : AsyncCallback\) : void;
+## CryptoMode
-Initializes the MAC computation using a symmetric key. This API uses an asynchronous callback to return the result.
+Enumerates the cryptographic operations.
**System capability**: SystemCapability.Security.CryptoFramework
-**Parameters**
-
-| Name | Type | Mandatory| Description |
-| -------- | -------------------- | ---- | ------------ |
-| key | [SymKey](#symkey) | Yes | Shared symmetric key.|
-| callback | AsyncCallback\ | Yes | Callback invoked to return the result. |
+| Name | Value | Description |
+| ------------ | ---- | ------------------ |
+| ENCRYPT_MODE | 0 | Encryption.|
+| DECRYPT_MODE | 1 | Decryption.|
-**Error codes**
+## AsyKeySpecItem10+
-| ID| Error Message |
-| -------- | ---------------------- |
-| 17630001 | crypto operation error. |
+Enumerates the key parameters.
-**Example**
+**System capability**: SystemCapability.Security.CryptoFramework
-```javascript
-import cryptoFramework from "@ohos.security.cryptoFramework"
+| Name | Value | Description |
+| ------------ | ---- | ---------------- |
+| DSA_P_BN | 101 | Prime modulus **p** in the DSA algorithm.|
+| DSA_Q_BN | 102 | Parameter **q** (prime factor of p – 1) in the DSA algorithm.|
+| DSA_G_BN | 103 | Parameter **g** in the DSA algorithm.|
+| DSA_SK_BN | 104 | Private key **sk** in the DSA algorithm.|
+| DSA_PK_BN | 105 | Public key **pk** in the DSA algorithm.|
+| ECC_FP_P_BN | 201 | Prime number **p** in the **Fp** fields of the elliptic curve in the DSA algorithm.|
+| ECC_A_BN | 202 | First coefficient **a** of the elliptic curve in the DSA algorithm.|
+| ECC_B_BN | 203 | Second coefficient **b** of the elliptic curve in the DSA algorithm.|
+| ECC_G_X_BN | 204 | X coordinate of the base point **g** in the ECC algorithm.|
+| ECC_G_Y_BN | 205 | Y coordinate of the base point **g** in the ECC algorithm.|
+| ECC_N_BN | 206 | Order **n** of the base point **g** in the ECC algorithm.|
+| ECC_H_NUM | 207 | Cofactor **h** in the ECC algorithm.|
+| ECC_SK_BN | 208 | Private key **sk** in the ECC algorithm.|
+| ECC_PK_X_BN | 209 | X coordinate of the public key **pk** (a point on the elliptic curve) in the ECC algorithm.|
+| ECC_PK_Y_BN | 210 | Y coordinate of the public key **pk** (a point on the elliptic curve) in the ECC algorithm.|
+| ECC_FIELD_TYPE_STR | 211 | Elliptic curve field type in the ECC algorithm. Currently, only the **Fp** field is supported.|
+| ECC_FIELD_SIZE_NUM | 212 | Size of the field in the ECC algorithm, in bits. **NOTE**: For the **Fp** field, the field size is the length of the prime **p**, in bits. |
+| ECC_CURVE_NAME_STR | 213 | SECG curve name in the ECC algorithm.|
+| RSA_N_BN | 301 | Modulus **n** in the RSA algorithm.|
+| RSA_SK_BN | 302 | Private key **sk** (private key exponent **d**) in the RSA algorithm.|
+| RSA_PK_BN | 303 | Public key **pk** (public key exponent **e**) in the RSA algorithm.|
+
+## AsyKeySpecType10+
+
+Enumerates the key parameter types.
-var mac;
-try {
- mac = cryptoFramework.createMac("SHA256");
-} catch (error) {
- console.error("[Promise]: error code: " + error.code + ", message is: " + error.message);
-}
-var KeyBlob;
-var symKeyGenerator = cryptoFramework.createSymKeyGenerator("AES128");
-symKeyGenerator.convertKey(KeyBlob, (err, symKey) => {
- if (err) {
- console.error("[Callback] err: " + err.code);
- }
- mac.init(symKey, (err1, ) => {
- if (err1) {
- console.error("[Callback] err: " + err1.code);
- }
- });
-});
-```
+**System capability**: SystemCapability.Security.CryptoFramework
-### init
+| Name | Value | Description |
+| ------------ | ---- | ---------------- |
+| COMMON_PARAMS_SPEC | 0 | Common parameters contained in the public and private keys. You can use [generateKeyPair()](#generatekeypair-2) to randomly generate a key pair based on the parameters of this type.|
+| PRIVATE_KEY_SPEC | 1 | Parameter contained in the private key. You can use [generatePriKey()](#generateprikey) to generate a private key based on the parameters of this type.|
+| PUBLIC_KEY_SPEC | 2 | Parameter contained in the public key. You can use [generatePubKey()](#generatepubkey) to generate a public key based on the parameters of this type.|
+| KEY_PAIR_SPEC | 3 | All parameters contained in the public and private keys. You can use [generateKeyPair](#generatekeypair-2) to generate a key pair based on the parameters of this type.|
-init(key : SymKey) : Promise\;
+## CipherSpecItem10+
-Initializes the MAC computation using a symmetric key. This API uses a promise to return the result.
+Enumerates the cipher parameters. You can use [setCipherSpec](#setcipherspec10) to set cipher parameters, and use [getCipherSpec](#getcipherspec10) to obtain cipher parameters. Currently, only the RSA is supported. For details, see [Encryption and Decryption Specifications](../../security/cryptoFramework-overview.md#encryption-and-decryption-specifications).
**System capability**: SystemCapability.Security.CryptoFramework
-**Parameters**
+| Name | Value | Description |
+| ------------ | ---- | ---------------- |
+| OAEP_MD_NAME_STR | 100 | Name of the message digest algorithm when the PKCS1_OAEP padding mode is used in the RSA.|
+| OAEP_MGF_NAME_STR | 101 | Mask generation algorithm when the PKCS1_OAEP padding mode is used in the RSA. Currently, only MGF1 is supported.|
+| OAEP_MGF1_MD_STR | 102 | Message digest algorithm for the MGF1 mask generation when the PKCS1_OAEP padding mode is used in the RSA.|
+| OAEP_MGF1_PSRC_UINT8ARR | 103 | **pSource** byte stream when the PKCS1_OAEP padding mode is used in the RSA.|
-| Name| Type | Mandatory| Description |
-| ------ | ------ | ---- | ------------ |
-| key | [SymKey](#symkey) | Yes | Shared symmetric key.|
+## SignSpecItem10+
-**Return value**
+Enumerates the parameters for signing and signature verification. You can use [setSignSpec](#setsignspec10) and [setVerifySpec](#setverifyspec10) to set these parameters, and use [getSignSpec](#getsignspec10) and [getVerifySpec](#getverifyspec10) to obtain the parameters. Currently, only the RSA is supported. For details, see [Encryption and Decryption Specifications](../../security/cryptoFramework-overview.md#encryption-and-decryption-specifications).
-| Type | Description |
-| -------------- | ----------- |
-| Promise\ | Promise used to return the result.|
+**System capability**: SystemCapability.Security.CryptoFramework
-**Error codes**
+| Name | Value | Description |
+| ------------ | ---- | ---------------- |
+| PSS_MD_NAME_STR | 100 | Name of the message digest algorithm when the PSS padding mode is used in the RSA.|
+| PSS_MGF_NAME_STR | 101 | Mask generation algorithm when the PSS padding mode is used in the RSA. Currently, only MGF1 is supported.|
+| PSS_MGF1_MD_STR | 102 | Message digest parameters for the MGF1 mask generation when the PSS padding mode is used in the RSA.|
+| PSS_SALT_LEN_NUM | 103 | Length of the salt in bytes when the PSS padding mode is used in the RSA.|
+| PSS_TRAILER_FIELD_NUM | 104 | Integer used for encoding when the PSS padding mode is used in the RSA. The value is **1**.|
-| ID| Error Message |
-| -------- | ---------------------- |
-| 17630001 | crypto operation error. |
+## AsyKeySpec10+
-**Example**
+Defines the asymmetric key parameters for creating a key generator. You need to construct a child class object and pass it to [createAsyKeyGeneratorBySpec()](#cryptoframeworkcreateasykeygeneratorbyspec10) to create a key generator. All the parameters of the bigint type in the child class object must be integers in big-endian format.
-```javascript
-import cryptoFramework from "@ohos.security.cryptoFramework"
+**System capability**: SystemCapability.Security.CryptoFramework
-var mac;
-try {
- mac = cryptoFramework.createMac("SHA256");
-} catch (error) {
- console.error("[Promise]: error code: " + error.code + ", message is: " + error.message);
-}
-console.error("Mac algName is: " + mac.algName);
+| Name | Type | Readable| Writable| Description |
+| ------- | ------ | ---- | ---- | ------------------------------------------------------------ |
+| algName | string | Yes | Yes | Algorithm of the asymmetric key pair, for example, **RSA**, **DSA**, or **ECC**.|
+| specType | [AsyKeySpecType](#asykeyspectype10) | Yes | Yes| Key parameter type, which is used to distinguish public and private key parameters.|
-var KeyBlob;
-var symKeyGenerator = cryptoFramework.createSymKeyGenerator("AES128");
-var promiseConvertKey = symKeyGenerator.convertKey(KeyBlob);
-promiseConvertKey.then(symKey => {
- var promiseMacInit = mac.init(symKey);
- return promiseMacInit;
-}).catch(error => {
- console.error("[Promise]: error: " + error.message);
-});
+## DSACommonParamsSpec10+
-```
+Defines the common parameters contained in the public and private keys in the DSA algorithm. It is a child class of [AsyKeySpec](#asykeyspec10) and can be used to randomly generate public or private keys. When key parameters are used to generate a key, you can pass it to [createAsyKeyGeneratorBySpec()](#cryptoframeworkcreateasykeygeneratorbyspec10) to create a key generator.
-### update
+**System capability**: SystemCapability.Security.CryptoFramework
-update(input : DataBlob, callback : AsyncCallback\) : void;
+| Name | Type | Readable| Writable| Description |
+| ------- | ------ | ---- | ---- | ------------------------------------------------------------ |
+| p | bigint | Yes | Yes | Prime modulus **p** in the DSA algorithm.|
+| q | bigint | Yes | Yes | Parameter **q** (prime factor of **p** – 1) in the DSA algorithm.|
+| g | bigint | Yes | Yes | Parameter **g** in the DSA algorithm.|
-Updates the MAC computation data. This API uses an asynchronous callback to return the result.
+## DSAPubKeySpec10+
-> **NOTE**
-> For details about the sample code for calling **update()** multiple times, see [Generating a MAC](../../security/cryptoFramework-guidelines.md#generating-a-mac).
+Defines the parameters contained in the public key in the DSA algorithm. It is a child class of [AsyKeySpec](#asykeyspec10). When key parameters are used to generate a key, you can pass it to [createAsyKeyGeneratorBySpec()](#cryptoframeworkcreateasykeygeneratorbyspec10) to create a key generator.
**System capability**: SystemCapability.Security.CryptoFramework
-**Parameters**
+| Name | Type | Readable| Writable| Description |
+| ------- | ------ | ---- | ---- | ------------------------------------------------------------ |
+| params | [DSACommonParamsSpec](#dsacommonparamsspec10) | Yes | Yes | Common parameters contained in both public and private keys in the DSA algorithm.|
+| pk | bigint | Yes | Yes | Public key of the DSA algorithm.|
-| Name | Type | Mandatory| Description |
-| -------- | -------------------- | ---- | ---------- |
-| input | [DataBlob](#datablob)| Yes | Data to pass in.|
-| callback | AsyncCallback\ | Yes | Callback invoked to return the result. |
+## DSAKeyPairSpec10+
-**Error codes**
+Defines full parameters contained in the public and private keys in the DSA algorithm. It is a child class of [AsyKeySpec](#asykeyspec10). When key parameters are used to generate a key, you can pass it to [createAsyKeyGeneratorBySpec()](#cryptoframeworkcreateasykeygeneratorbyspec10) to create a key generator.
-| ID| Error Message |
-| -------- | ---------------------- |
-| 17630001 | crypto operation error. |
+**System capability**: SystemCapability.Security.CryptoFramework
-**Example**
+| Name | Type | Readable| Writable| Description |
+| ------- | ------ | ---- | ---- | ------------------------------------------------------------ |
+| params | [DSACommonParamsSpec](#dsacommonparamsspec10) | Yes | Yes | Common parameters contained in both public and private keys in the DSA algorithm.|
+| sk | bigint | Yes | Yes | Private key **sk** in the DSA algorithm.|
+| pk | bigint | Yes | Yes | Public key **pk** in the DSA algorithm.|
-```javascript
-import cryptoFramework from "@ohos.security.cryptoFramework"
+## ECField10+
-var KeyBlob;
-var mac;
-try {
- mac = cryptoFramework.createMac("SHA256");
-} catch (error) {
- console.error("[Callback]: error code: " + error.code + ", message is: " + error.message);
-}
-var symKeyGenerator = cryptoFramework.createSymKeyGenerator("AES128");
-symKeyGenerator.convertKey(KeyBlob, (err, symKey) => {
- if (err) {
- console.error("[Callback] err: " + err.code);
- }
- mac.init(symKey, (err1, ) => {
- if (err1) {
- console.error("[Callback] err: " + err1.code);
- }
- let blob;
- mac.update(blob, (err2, data) => {
- if (err2) {
- console.error("[Callback] err: " + err2.code);
- }
- });
- });
-});
-```
+Defines the elliptic curve field. Currently, only the **Fp** field is supported.
-### update
+**System capability**: SystemCapability.Security.CryptoFramework
-update(input : DataBlob) : Promise\;
+| Name | Type | Readable| Writable| Description |
+| ------- | ------ | ---- | ---- | ------------------------------------------------------------ |
+| fieldType | string | Yes | Yes | Type of the elliptic curve field. Currently, only **Fp** is supported.|
-Updates the MAC computation data. This API uses a promise to return the result.
+## ECFieldFp10+
-> **NOTE**
-> For details about the sample code for calling **update()** multiple times, see [Generating a MAC](../../security/cryptoFramework-guidelines.md#generating-a-mac).
+Defines the prime field of the elliptic curve. It is a child class of [ECField](#ecfield10).
**System capability**: SystemCapability.Security.CryptoFramework
-**Parameters**
+| Name | Type | Readable| Writable| Description |
+| ------- | ------ | ---- | ---- | ------------------------------------------------------------ |
+| p | bigint | Yes | Yes | Prime **p**.|
-| Name| Type | Mandatory| Description |
-| ------ | -------- | ---- | ---------- |
-| input | [DataBlob](#datablob) | Yes | Data to pass in.|
+## Point10+
-**Return value**
+Defines a point on the elliptic curve.
-| Type | Description |
-| -------------- | ----------- |
-| Promise\ | Promise used to return the result.|
+**System capability**: SystemCapability.Security.CryptoFramework
-**Error codes**
+| Name | Type | Readable| Writable| Description |
+| ------- | ------ | ---- | ---- | ------------------------------------------------------------ |
+| x | bigint | Yes | Yes | X coordinate of the point on an elliptic curve.|
+| y | bigint | Yes | Yes | Y coordinate of the point on an elliptic curve.|
-| ID| Error Message |
-| -------- | ---------------------- |
-| 17630001 | crypto operation error. |
+## ECCCommonParamsSpec10+
-**Example**
+Defines the common parameters contained in the public and private keys in the ECC algorithm. It is a child class of [AsyKeySpec](#asykeyspec10) and can be used to randomly generate public or private keys. When key parameters are used to generate a key, you can pass it to [createAsyKeyGeneratorBySpec()](#cryptoframeworkcreateasykeygeneratorbyspec10) to create a key generator.
-```javascript
-import cryptoFramework from "@ohos.security.cryptoFramework"
+**System capability**: SystemCapability.Security.CryptoFramework
-var mac;
-try {
- mac = cryptoFramework.createMac("SHA256");
-} catch (error) {
- console.error("[Promise]: error code: " + error.code + ", message is: " + error.message);
-}
-console.error("Mac algName is: " + mac.algName);
+| Name | Type | Readable| Writable| Description |
+| ------- | ------ | ---- | ---- | ------------------------------------------------------------ |
+| field | [ECField](#ecfield10) | Yes | Yes | Field of the elliptic curve. Currently, only the **Fp** field is supported.|
+| a | bigint | Yes | Yes | First coefficient **a** of the elliptic curve.|
+| b | bigint | Yes | Yes | Second coefficient **b** of the elliptic curve.|
+| g | [Point](#point10) | Yes | Yes | Base point g.|
+| n | bigint | Yes | Yes | Order **n** of the base point **g**.|
+| h | number | Yes | Yes | Cofactor **h**.|
-var KeyBlob;
-var symKeyGenerator = cryptoFramework.createSymKeyGenerator("AES128");
-var promiseConvertKey = symKeyGenerator.convertKey(KeyBlob);
-promiseConvertKey.then(symKey => {
- var promiseMacInit = mac.init(symKey);
- return promiseMacInit;
-}).then(() => {
- let blob;
- var promiseMacUpdate = mac.update(blob);
- return promiseMacUpdate;
-}).catch(error => {
- console.error("[Promise]: error: " + error.message);
-});
+## ECCPriKeySpec10+
-```
+Defines the parameters contained in the private key in the ECC algorithm. It is a child class of [AsyKeySpec](#asykeyspec10). When key parameters are used to generate a key, you can pass it to [createAsyKeyGeneratorBySpec()](#cryptoframeworkcreateasykeygeneratorbyspec10) to create a key generator.
-### doFinal
+**System capability**: SystemCapability.Security.CryptoFramework
-doFinal(callback : AsyncCallback\) : void;
+| Name | Type | Readable| Writable| Description |
+| ------- | ------ | ---- | ---- | ------------------------------------------------------------ |
+| params | [ECCCommonParamsSpec](#ecccommonparamsspec10) | Yes | Yes | Common parameters contained in both public and private keys in the ECC algorithm.|
+| sk | bigint | Yes | Yes | Private key **sk** in the ECC algorithm.|
-Finalizes the MAC computation. This API uses an asynchronous callback to return the result.
+## ECCPubKeySpec10+
+
+Defines the parameters contained in the public key in the ECC algorithm. It is a child class of [AsyKeySpec](#asykeyspec10). When key parameters are used to generate a key, you can pass it to [createAsyKeyGeneratorBySpec()](#cryptoframeworkcreateasykeygeneratorbyspec10) to create a key generator.
**System capability**: SystemCapability.Security.CryptoFramework
-**Parameters**
+| Name | Type | Readable| Writable| Description |
+| ------- | ------ | ---- | ---- | ------------------------------------------------------------ |
+| params | [ECCCommonParamsSpec](#ecccommonparamsspec10) | Yes | Yes | Common parameters contained in both public and private keys in the ECC algorithm.|
+| pk | [Point](#point10) | Yes | Yes | Public key **pk** in the ECC algorithm.|
-| Name | Type | Mandatory| Description |
-| -------- | ------------------------ | ---- | -------- |
-| callback | AsyncCallback\<[DataBlob](#datablob)> | Yes | Callback invoked to return the result.|
+## ECCKeyPairSpec10+
-**Error codes**
+Defines full parameters contained in the public and private keys in the ECC algorithm. It is a child class of [AsyKeySpec](#asykeyspec10). When key parameters are used to generate a key, you can pass it to [createAsyKeyGeneratorBySpec()](#cryptoframeworkcreateasykeygeneratorbyspec10) to create a key generator.
-| ID| Error Message |
-| -------- | ---------------------- |
-| 17620001 | memory error. |
-| 17630001 | crypto operation error. |
+**System capability**: SystemCapability.Security.CryptoFramework
-**Example**
+| Name | Type | Readable| Writable| Description |
+| ------- | ------ | ---- | ---- | ------------------------------------------------------------ |
+| params | [ECCCommonParamsSpec](#ecccommonparamsspec10) | Yes | Yes | Common parameters contained in both public and private keys in the ECC algorithm.|
+| sk | bigint | Yes | Yes | Private key **sk** in the ECC algorithm.|
+| pk | [Point](#point10) | Yes | Yes | Public key **pk** in the ECC algorithm.|
-```javascript
-import cryptoFramework from "@ohos.security.cryptoFramework"
+## RSACommonParamsSpec10+
-var KeyBlob;
-var mac;
-try {
- mac = cryptoFramework.createMac("SHA256");
-} catch (error) {
- console.error("[Callback]: error code: " + error.code + ", message is: " + error.message);
-}
-var symKeyGenerator = cryptoFramework.createSymKeyGenerator("AES128");
-symKeyGenerator.convertKey(KeyBlob, (err, symKey) => {
- if (err) {
- console.error("[Callback] err: " + err.code);
- }
- mac.init(symKey, (err1, ) => {
- if (err1) {
- console.error("[Callback] err: " + err1.code);
- }
- let blob;
- mac.update(blob, (err2, ) => {
- if (err2) {
- console.error("[Callback] err: " + err2.code);
- }
- mac.doFinal((err3, macOutput) => {
- if (err3) {
- console.error("[Callback] err: " + err3.code);
- } else {
- console.error("[Promise]: HMAC result: " + macOutput);
- }
- });
- });
- });
-});
-```
+Defines the common parameters contained in the public and private keys in the RSA algorithm. It is a child class of [AsyKeySpec](#asykeyspec10) and can be used to randomly generate public or private keys. When key parameters are used to generate a key, you can pass it to [createAsyKeyGeneratorBySpec()](#cryptoframeworkcreateasykeygeneratorbyspec10) to create a key generator.
-### doFinal
+**System capability**: SystemCapability.Security.CryptoFramework
+
+| Name | Type | Readable| Writable| Description |
+| ------- | ------ | ---- | ---- | ------------------------------------------------------------ |
+| n | bigint | Yes | Yes | Modulus **n**.|
-doFinal() : Promise\
+## RSAPubKeySpec10+
-Finalizes the MAC computation. This API uses a promise to return the result.
+Defines the parameters contained in the public key in the RSA algorithm. It is a child class of [AsyKeySpec](#asykeyspec10). When key parameters are used to generate a key, you can pass it to [createAsyKeyGeneratorBySpec()](#cryptoframeworkcreateasykeygeneratorbyspec10) to create a key generator.
**System capability**: SystemCapability.Security.CryptoFramework
-**Return value**
+| Name | Type | Readable| Writable| Description |
+| ------- | ------ | ---- | ---- | ------------------------------------------------------------ |
+| params | [RSACommonParamsSpec](#rsacommonparamsspec10) | Yes | Yes | Common parameters contained in both public and private keys in the RSA algorithm.|
+| pk | bigint | Yes | Yes | Public key **pk** in the RSA algorithm.|
-| Type | Description |
-| ------------------ | ----------- |
-| Promise\<[DataBlob](#datablob)> | Promise used to return the result.|
+## RSAKeyPairSpec10+
-**Error codes**
+Defines full parameters contained in the public and private keys in the RSA algorithm. It is a child class of [AsyKeySpec](#asykeyspec10). When key parameters are used to generate a key, you can pass it to [createAsyKeyGeneratorBySpec()](#cryptoframeworkcreateasykeygeneratorbyspec10) to create a key generator.
-| ID| Error Message |
-| -------- | ---------------------- |
-| 17620001 | memory error. |
-| 17630001 | crypto operation error. |
+**System capability**: SystemCapability.Security.CryptoFramework
-**Example**
+| Name | Type | Readable| Writable| Description |
+| ------- | ------ | ---- | ---- | ------------------------------------------------------------ |
+| params | [RSACommonParamsSpec](#rsacommonparamsspec10) | Yes | Yes | Common parameters contained in both public and private keys in the RSA algorithm.|
+| sk | bigint | Yes | Yes | Private key **sk** in the RSA algorithm.|
+| pk | bigint | Yes | Yes | Public key **pk** in the RSA algorithm.|
-```javascript
-import cryptoFramework from "@ohos.security.cryptoFramework"
+## Key
-var mac;
-try {
- mac = cryptoFramework.createMac("SHA256");
-} catch (error) {
- console.error("[Promise]: error code: " + error.code + ", message is: " + error.message);
-}
-console.error("Mac algName is: " + mac.algName);
+Provides APIs for key operations. Before performing cryptographic operations (such as encryption and decryption), you need to construct a child class object of **Key** and pass it to [init()](#init-2) of the [Cipher](#cipher) instance. Keys can be generated by a key generator.
-var KeyBlob;
-var symKeyGenerator = cryptoFramework.createSymKeyGenerator("AES128");
-var promiseConvertKey = symKeyGenerator.convertKey(KeyBlob);
-promiseConvertKey.then(symKey => {
- var promiseMacInit = mac.init(symKey);
- return promiseMacInit;
-}).then(() => {
- let blob;
- var promiseMacUpdate = mac.update(blob);
- return promiseMacUpdate;
-}).then(() => {
- var PromiseMacDoFinal = mac.doFinal();
- return PromiseMacDoFinal;
-}).then(macOutput => {
- console.error("[Promise]: HMAC result: " + macOutput.data);
-}).catch(error => {
- console.error("[Promise]: error: " + error.message);
-});
-```
+### Attributes
-### getMacLength
+**System capability**: SystemCapability.Security.CryptoFramework
+
+| Name | Type | Readable| Writable| Description |
+| ------- | ------ | ---- | ---- | ---------------------------- |
+| format | string | Yes | No | Format of the key. |
+| algName | string | Yes | No | Algorithm name (including the key length).|
-getMacLength() : number
+### getEncoded
-Obtains the MAC length, in bytes.
+getEncoded(): DataBlob
+
+Obtains the byte stream of the key data synchronously. The key can be a symmetric key, public key, or private key. The public key must be in DER encoding format and comply with the ASN.1 syntax and X.509 specifications. The private key must be in DER encoding format and comply with the ASN.1 syntax and PKCS#8 specifications.
+
+> **NOTE**
+>
+> When key parameters are used to generate an RSA private key, the private key object does not support **getEncoded()**.
**System capability**: SystemCapability.Security.CryptoFramework
**Return value**
-| Type | Description |
-| ------ | ------------------------- |
-| number | MAC length obtained.|
+| Type | Description |
+| --------------------- | ------------------------ |
+| [DataBlob](#datablob) | Key obtained.|
**Error codes**
| ID| Error Message |
| -------- | ---------------------- |
+| 801 | this operation is not supported. |
+| 17620001 | memory error. |
| 17630001 | crypto operation error. |
**Example**
-```javascript
+```js
import cryptoFramework from "@ohos.security.cryptoFramework"
-
-var mac;
-try {
- mac = cryptoFramework.createMac("SHA256");
-} catch (error) {
- console.error("[Promise]: error code: " + error.code + ", message is: " + error.message);
+function uint8ArrayToShowStr(uint8Array) {
+ return Array.prototype.map
+ .call(uint8Array, (x) => ('00' + x.toString(16)).slice(-2))
+ .join('');
}
-console.error("Mac algName is: " + mac.algName);
-var KeyBlob;
-var symKeyGenerator = cryptoFramework.createSymKeyGenerator("AES128");
-var promiseConvertKey = symKeyGenerator.convertKey(KeyBlob);
-promiseConvertKey.then(symKey => {
- var promiseMacInit = mac.init(symKey);
- return promiseMacInit;
-}).then(() => {
- let blob;
- var promiseMacUpdate = mac.update(blob);
- return promiseMacUpdate;
-}).then(() => {
- var PromiseMacDoFinal = mac.doFinal();
- return PromiseMacDoFinal;
-}).then(macOutput => {
- console.error("[Promise]: HMAC result: " + macOutput.data);
- let macLen = mac.getMacLength();
- console.error("MAC len: " + macLen);
-}).catch(error => {
- console.error("[Promise]: error: " + error.message);
-});
+let key; // The key is generated by a key generator. The generation process is omitted here.
+let encodedKey = key.getEncoded();
+console.info("key hex:" + uint8ArrayToShowStr(encodedKey.data));
```
-## cryptoFramework.createMd
-
-createMd(algName : string) : Md
-
-Creates an **Md** instance for message digest operations.
-
-For details about the supported specifications, see [MD Algorithm Specifications](../../security/cryptoFramework-overview.md#md-algorithm-specifications).
-
-**System capability**: SystemCapability.Security.CryptoFramework
-
-**Parameters**
+## SymKey
-| Name | Type | Mandatory| Description |
-| ------- | ------ | ---- | ------------------------------------------------------------ |
-| algName | string | Yes | Digest algorithm. For details about the supported algorithms, see [MD Algorithm Specifications](../../security/cryptoFramework-overview.md#md-algorithm-specifications).|
+Provides APIs for symmetric key operations. It is a child class of [Key](#key). Its objects need to be passed to [init()](#init-2) of the [Cipher](#cipher) instance in symmetric encryption and decryption. Symmetric keys can be generated by a [SymKeyGenerator](#symkeygenerator).
-**Return value**
+### clearMem
-| Type| Description |
-| ---- | ------------------------------------- |
-| Md | [Md](#md) instance created.|
+clearMem(): void
-**Error codes**
+Clears the keys in the memory. This API returns the result synchronously. You are advised to use this API when symmetric key instances are no longer used.
-| ID| Error Message |
-| -------- | ------------------ |
-| 17620001 | memory error. |
+**System capability**: SystemCapability.Security.CryptoFramework
**Example**
-```javascript
+```js
import cryptoFramework from "@ohos.security.cryptoFramework"
-
-var md;
-try {
- // Set algName based on the algorithm supported.
- md = cryptoFramework.createMd("SHA256");
-} catch (error) {
- console.error("[Promise]: error code: " + error.code + ", message is: " + error.message);
+function uint8ArrayToShowStr(uint8Array) {
+ return Array.prototype.map
+ .call(uint8Array, (x) => ('00' + x.toString(16)).slice(-2))
+ .join('');
}
+
+let key; // The key is generated by a symKeyGenerator. The generation process is omitted here.
+let encodedKey = key.getEncoded();
+console.info("key hex: "+ uint8ArrayToShowStr(encodedKey.data)); // Display key content.
+key.clearMem();
+encodedKey = key.getEncoded();
+console.info("key hex:" + uint8ArrayToShowStr(encodedKey.data)); // Display all 0s.
```
-## Md
+## PubKey
-Provides APIs for message digest operations. Before using any API of the **Md** class, you must create an **Md** instance by using [createMd](#cryptoframeworkcreatemd).
+Provides APIs for public key operations. It is a child class of [Key](#key). Its objects need to be passed in during asymmetric encryption and decryption, signature verification, and key agreement. The public key can be generated by using the asymmetric key generator [AsyKeyGenerator](#asykeygenerator) or [AsyKeyGeneratorBySpec](#asykeygeneratorbyspec10).
### Attributes
**System capability**: SystemCapability.Security.CryptoFramework
-| Name | Type | Readable| Writable| Description |
-| ------- | ------ | ---- | ---- | -------------------- |
-| algName | string | Yes | No | Digest algorithm.|
-
-### update
+| Name | Type | Readable| Writable| Description |
+| ------- | ------ | ---- | ---- | ---------------------------- |
+| format | string | Yes | No | Format of the key. |
+| algName | string | Yes | No | Algorithm name (including the key length).|
-update(input : DataBlob, callback : AsyncCallback\) : void;
+### getAsyKeySpec10+
-Updates the message digest data. This API uses an asynchronous callback to return the result.
+getAsyKeySpec(itemType: AsyKeySpecItem): bigint | string | number
-> **NOTE**
-> For details about the sample code for calling **update()** multiple times, see [Generating a Digest](../../security/cryptoFramework-guidelines.md#generating-a-digest).
+Obtains a key parameter synchronously.
**System capability**: SystemCapability.Security.CryptoFramework
**Parameters**
-| Name | Type | Mandatory| Description |
-| -------- | -------------------- | ---- | ---------- |
-| input | [DataBlob](#datablob)| Yes | Data to pass in.|
-| callback | AsyncCallback\ | Yes | Callback invoked to return the result. |
+| Name| Type | Mandatory| Description |
+| ---- | --------------------- | ---- | -------------------- |
+| item | [AsyKeySpecItem](#asykeyspecitem10) | Yes | Key parameter to obtain.|
+
+**Return value**
+
+| Type | Description |
+| --------------------------- | --------------------------------- |
+| bigint\|string\|number | Content of the key parameter obtained.|
**Error codes**
| ID| Error Message |
| -------- | ---------------------- |
+| 401 | invalid parameters. |
+| 17620001 | memory error. |
| 17630001 | crypto operation error. |
**Example**
-```javascript
-import cryptoFramework from "@ohos.security.cryptoFramework"
+```js
+let key; // key is a public key object. The generation process is omitted here.
+let p = key.getAsyKeySpec(cryptoFramework.AsyKeySpecItem.ECC_FP_P_BN);
+console.info("ecc item --- p: " + p.toString(16));
+```
-var md;
-try {
- md = cryptoFramework.createMd("SHA256");
-} catch (error) {
- console.error("[Callback]: error code: " + error.code + ", message is: " + error.message);
-}
-console.error("Md algName is: " + md.algName);
+## PriKey
-let blob;
-md.update(blob, (err,) => {
- if (err) {
- console.error("[Callback] err: " + err.code);
- }
-});
-```
+Provides APIs for private key operations. It is a child class of [Key](#key). Its objects need to be passed in during asymmetric encryption and decryption, signing, and key agreement. The public key can be generated by using the asymmetric key generator [AsyKeyGenerator](#asykeygenerator) or [AsyKeyGeneratorBySpec](#asykeygeneratorbyspec10).
-### update
+### Attributes
-update(input : DataBlob) : Promise\;
+**System capability**: SystemCapability.Security.CryptoFramework
-Updates the message digest data. This API uses a promise to return the result.
+| Name | Type | Readable| Writable| Description |
+| ------- | ------ | ---- | ---- | ---------------------------- |
+| format | string | Yes | No | Format of the key. |
+| algName | string | Yes | No | Algorithm name (including the key length).|
-> **NOTE**
-> For details about the sample code for calling **update()** multiple times, see [Generating a Digest](../../security/cryptoFramework-guidelines.md#generating-a-digest).
+### clearMem
+
+clearMem(): void
+
+Clears the keys in the memory. This API returns the result synchronously.
**System capability**: SystemCapability.Security.CryptoFramework
-| Name| Type | Mandatory| Description |
-| ------ | -------- | ---- | ---------- |
-| input | DataBlob | Yes | Data to pass in.|
+**Example**
+
+```js
+let key; // The key is a private key generated by the asymmetric key generator. The generation process is omitted here.
+key.clearMem();
+```
+
+### getAsyKeySpec10+
+
+getAsyKeySpec(itemType: AsyKeySpecItem): bigint | string | number
+
+Obtains a key parameter synchronously.
+
+**System capability**: SystemCapability.Security.CryptoFramework
+
+**Parameters**
+
+| Name| Type | Mandatory| Description |
+| ---- | --------------------- | ---- | -------------------- |
+| item | [AsyKeySpecItem](#asykeyspecitem10) | Yes | Key parameter to obtain.|
**Return value**
-| Type | Description |
-| -------------- | ----------- |
-| Promise\ | Promise used to return the result.|
+| Type | Description |
+| --------------------------- | --------------------------------- |
+| bigint\|string\|number | Content of the key parameter obtained.|
**Error codes**
| ID| Error Message |
| -------- | ---------------------- |
+| 401 | invalid parameters. |
+| 17620001 | memory error. |
| 17630001 | crypto operation error. |
**Example**
-```javascript
-import cryptoFramework from "@ohos.security.cryptoFramework"
+```js
+let key; // key is a private key object. The generation process is omitted here.
+let p = key.getAsyKeySpec(cryptoFramework.AsyKeySpecItem.ECC_FP_P_BN);
+console.info("ecc item --- p: " + p.toString(16));
+```
-var md;
-try {
- md = cryptoFramework.createMd("SHA256");
-} catch (error) {
- console.error("[Callback]: error code: " + error.code + ", message is: " + error.message);
-}
-console.error("Md algName is: " + md.algName);
-
-let blob;
-var promiseMdUpdate = md.update(blob);
-promiseMdUpdate.then(() => {
- // do something
-}).catch(error => {
- console.error("[Promise]: error: " + error.message);
-});
-```
+## KeyPair
-### digest
+Defines an asymmetric key pair, which includes a public key and a private key. The asymmetric key pair can be generated by using the asymmetric key generator [AsyKeyGenerator](#asykeygenerator) or [AsyKeyGeneratorBySpec](#asykeygeneratorbyspec10).
-digest(callback : AsyncCallback\) : void
+> **NOTE**
+>
+> The **pubKey** and **priKey** objects in the **KeyPair** object exist as one parameter in the **KeyPair** object. When **KeyPair** leaves the scope, its internal objects can be destructed.
+>
+> The service must reference the **KeyPair** object instead of the internal **pubKey** or **priKey** object.
-Generates a message digest. This API uses an asynchronous callback to return the result.
+### Attributes
**System capability**: SystemCapability.Security.CryptoFramework
-| Name | Type | Mandatory| Description |
-| -------- | ------------------------ | ---- | -------- |
-| callback | AsyncCallback\ | Yes | Callback invoked to return the result.|
-
-**Error codes**
-
-| ID| Error Message |
-| -------- | ---------------------- |
-| 17620001 | memory error. |
-| 17630001 | crypto operation error. |
-
-**Example**
+| Name | Type | Readable| Writable| Description |
+| ------- | ------ | ---- | ---- | ------------ |
+| priKey | [PriKey](#prikey) | Yes | No | Private key. |
+| pubKey | [PubKey](#pubkey) | Yes | No | Public key. |
-```javascript
-import cryptoFramework from "@ohos.security.cryptoFramework"
-var md;
-try {
- md = cryptoFramework.createMd("SHA256");
-} catch (error) {
- console.error("[Callback]: error code: " + error.code + ", message is: " + error.message);
-}
-console.error("Md algName is: " + md.algName);
+## cryptoFramework.createSymKeyGenerator
-let blob;
-md.update(blob, (err,) => {
- if (err) {
- console.error("[Callback] err: " + err.code);
- }
- md.digest((err1, mdOutput) => {
- if (err1) {
- console.error("[Callback] err: " + err1.code);
- } else {
- console.error("[Callback]: MD result: " + mdOutput);
- }
- });
-});
-```
+createSymKeyGenerator(algName: string): SymKeyGenerator
-### digest
+Creates a **symKeyGenerator** instance based on the specified algorithm. For details about the supported specifications, see [Key Generation Specifications](../../security/cryptoFramework-overview.md#key-generation-specifications).
-digest() : Promise\
+**System capability**: SystemCapability.Security.CryptoFramework
-Generates a message digest. This API uses a promise to return the result.
+**Parameters**
-**System capability**: SystemCapability.Security.CryptoFramework
+| Name | Type | Mandatory| Description |
+| ------- | ------ | ---- | ------------------------------------------------------------ |
+| algName | string | Yes | Algorithm used to create the **symKeyGenerator** instance. For details, see "String Parameter" in [Key Generation Specifications](../../security/cryptoFramework-overview.md#key-generation-specifications).|
**Return value**
-| Type | Description |
-| ------------------ | ----------- |
-| Promise\<[DataBlob](#datablob)> | Promise used to return the result.|
-
-**Error codes**
+| Type | Description |
+| ----------------------------------- | -------------------------- |
+| [SymKeyGenerator](#symkeygenerator) | **symKeyGenerator** instance created.|
| ID| Error Message |
| -------- | ---------------------- |
-| 17620001 | memory error. |
-| 17630001 | crypto operation error. |
+| 401 | invalid parameters. |
+| 801 | this operation is not supported. |
**Example**
-```javascript
-import cryptoFramework from "@ohos.security.cryptoFramework"
+```js
+import cryptoFramework from '@ohos.security.cryptoFramework';
+let symKeyGenerator = cryptoFramework.createSymKeyGenerator('3DES192');
+```
-var md;
-try {
- md = cryptoFramework.createMd("SHA256");
-} catch (error) {
- console.error("[Callback]: error code: " + error.code + ", message is: " + error.message);
-}
-console.error("Md algName is: " + md.algName);
+## SymKeyGenerator
-let blob;
-var promiseMdUpdate = md.update(blob);
-promiseMdUpdate.then(() => {
- var PromiseMdDigest = md.digest();
- return PromiseMdDigest;
-}).then(mdOutput => {
- console.error("[Promise]: MD result: " + mdOutput.data);
-}).catch(error => {
- console.error("[Promise]: error: " + error.message);
-});
-```
+Provides APIs for using the **symKeyGenerator**. Before using any API of the **SymKeyGenerator** class, you must create a **symKeyGenerator** instance by using [createSymKeyGenerator](#cryptoframeworkcreatesymkeygenerator).
-### getMdLength
+### Attributes
-getMdLength() : number
+**System capability**: SystemCapability.Security.CryptoFramework
-Obtains the message digest length, in bytes.
+| Name | Type | Readable| Writable| Description |
+| ------- | ------ | ---- | ---- | ------------------------------ |
+| algName | string | Yes | No | Algorithm used by the **symKeyGenerator**.|
+
+### generateSymKey
+
+generateSymKey(callback: AsyncCallback\): void
+
+Generates a key randomly. This API uses an asynchronous callback to return the result. This API can be used only after a **symKeyGenerator** instance is created by using [createSymKeyGenerator](#cryptoframeworkcreatesymkeygenerator). **RAND_priv_bytes()** of OpenSSL can be used to generate random keys.
**System capability**: SystemCapability.Security.CryptoFramework
-**Return value**
+**Parameters**
-| Type | Description |
-| ------ | ------------------------ |
-| number | Message digest length obtained.|
+| Name | Type | Mandatory| Description |
+| -------- | --------------------------------- | ---- | ------------------------------------------------------------ |
+| callback | AsyncCallback\<[SymKey](#symkey)> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **undefined** and **data** is the symmetric key generated. Otherwise, **err** is an error object.|
**Error codes**
-| ID| Error Message |
-| -------- | ---------------------- |
-| 17630001 | crypto operation error. |
+| ID| Error Message |
+| -------- | ------------- |
+| 17620001 | memory error. |
**Example**
-```javascript
-import cryptoFramework from "@ohos.security.cryptoFramework"
-
-var md;
-try {
- md = cryptoFramework.createMd("SHA256");
-} catch (error) {
- console.error("[Callback]: error code: " + error.code + ", message is: " + error.message);
-}
-console.error("Md algName is: " + md.algName);
-
-let blob;
-var promiseMdUpdate = md.update(blob);
-promiseMdUpdate.then(() => {
- var PromiseMdDigest = md.digest();
- return PromiseMdDigest;
-}).then(mdOutput => {
- console.error("[Promise]: MD result: " + mdOutput.data);
- let mdLen = md.getMdLength();
- console.error("MD len: " + mdLen);
-}).catch(error => {
- console.error("[Promise]: error: " + error.message);
-});
+```js
+import cryptoFramework from '@ohos.security.cryptoFramework';
+let symAlgName = '3DES192';
+let symKeyGenerator = cryptoFramework.createSymKeyGenerator(symAlgName);
+symKeyGenerator.generateSymKey((err, symKey) => {
+ if (err) {
+ console.error(`Generate symKey failed, ${err.code}, ${err.message}`);
+ } else {
+ console.info(`Generate symKey success, algName: ${symKey.algName}`);
+ }
+})
```
-## cryptoFramework.createRandom
+### generateSymKey
-createRandom() : Random
+generateSymKey(): Promise\
-Creates a **Random** instance for generating a random number and setting a seed.
+Generates a key randomly. This API uses a promise to return the result. This API can be used only after a **symKeyGenerator** instance is created by using [createSymKeyGenerator](#cryptoframeworkcreatesymkeygenerator). **RAND_priv_bytes()** of OpenSSL can be used to generate random keys.
**System capability**: SystemCapability.Security.CryptoFramework
**Return value**
-| Type | Description |
-| ------ | --------------------------------------------- |
-| Random | [Random](#random) instance created.|
+| Type | Description |
+| --------------------------- | --------------------------------- |
+| Promise\<[SymKey](#symkey)> | Promise used to return the symmetric key generated.|
**Error codes**
-| ID| Error Message |
-| -------- | ------------ |
+| ID| Error Message |
+| -------- | ------------- |
| 17620001 | memory error. |
**Example**
-```javascript
-import cryptoFramework from "@ohos.security.cryptoFramework"
-
-try {
- var rand = cryptoFramework.createRandom();
-} catch (error) {
- console.error("[Callback]: error code: " + error.code + ", message is: " + error.message);
-}
+```js
+import cryptoFramework from '@ohos.security.cryptoFramework';
+let symAlgName = 'AES128';
+let symKeyGenerator = cryptoFramework.createSymKeyGenerator(symAlgName);
+symKeyGenerator.generateSymKey()
+.then(symKey => {
+ console.info(`Generate symKey success, algName: ${symKey.algName}`);
+}, error => {
+ console.error(`Generate symKey failed, ${error.code}, ${error.message}`);
+})
```
-## Random
-
-Provides APIs for computing random numbers and setting seeds. Before using any API of the **Random** class, you must create a **Random** instance by using [createRandom](#cryptoframeworkcreaterandom).
-
-### generateRandom
+### convertKey
-generateRandom(len : number, callback: AsyncCallback\) : void;
+convertKey(key: DataBlob, callback: AsyncCallback\): void
-Generates a random number of the given length. This API uses an asynchronous callback to return the result.
+Converts data into a symmetric key. This API uses an asynchronous callback to return the result. This API can be used only after a **symKeyGenerator** instance is created by using [createSymKeyGenerator](#cryptoframeworkcreatesymkeygenerator).
**System capability**: SystemCapability.Security.CryptoFramework
**Parameters**
-| Name | Type | Mandatory| Description |
-| -------- | ------------------------ | ---- | -------------------- |
-| len | number | Yes | Length of the random number to generate.|
-| callback | AsyncCallback\<[DataBlob](#datablob)> | Yes | Callback invoked to return the result. |
+| Name | Type | Mandatory| Description |
+| -------- | --------------------------------- | ---- | ------------------------------------------------------------ |
+| key | [DataBlob](#datablob) | Yes | Data to convert. |
+| callback | AsyncCallback\<[SymKey](#symkey)> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **undefined** and **data** is the symmetric key generated. Otherwise, **err** is an error object.|
**Error codes**
-| ID| Error Message |
-| -------- | ---------------------- |
-| 17620001 | memory error. |
-| 17630001 | crypto operation error. |
+| ID| Error Message |
+| -------- | --------------------------------------------------- |
+| 401 | invalid parameters. |
+| 17620001 | memory error. |
**Example**
-```javascript
-import cryptoFramework from "@ohos.security.cryptoFramework"
+```js
+import cryptoFramework from '@ohos.security.cryptoFramework';
-var rand;
-try {
- rand = cryptoFramework.createRandom();
-} catch (error) {
- console.error("[Callback]: error code: " + error.code + ", message is: " + error.message);
+function genKeyMaterialBlob() {
+ let arr = [
+ 0xba, 0x3d, 0xc2, 0x71, 0x21, 0x1e, 0x30, 0x56,
+ 0xad, 0x47, 0xfc, 0x5a, 0x46, 0x39, 0xee, 0x7c,
+ 0xba, 0x3b, 0xc2, 0x71, 0xab, 0xa0, 0x30, 0x72]; // keyLen = 192 (24 bytes)
+ let keyMaterial = new Uint8Array(arr);
+ return {data: keyMaterial};
}
-rand.generateRandom(12, (err, randData) => {
- if (err) {
- console.error("[Callback] err: " + err.code);
- } else {
- console.error("[Callback]: generate random result: " + randData.data);
- }
-});
+
+let symAlgName = '3DES192';
+let symKeyGenerator = cryptoFramework.createSymKeyGenerator(symAlgName);
+let keyMaterialBlob = genKeyMaterialBlob();
+symKeyGenerator.convertKey(keyMaterialBlob, (err, symKey) => {
+ if (err) {
+ console.error(`Convert symKey failed, ${err.code}, ${err.message}`);
+ } else {
+ console.info(`Convert symKey success, algName: ${symKey.algName}`);
+ }
+})
```
-### generateRandom
+### convertKey
-generateRandom(len : number) : Promise\;
+convertKey(key: DataBlob): Promise\
-Generates a random number of the given length. This API uses a promise to return the result.
+Converts data into a symmetric key. This API uses a promise to return the result. This API can be used only after a **symKeyGenerator** instance is created by using [createSymKeyGenerator](#cryptoframeworkcreatesymkeygenerator).
**System capability**: SystemCapability.Security.CryptoFramework
**Parameters**
-| Name| Type | Mandatory| Description |
-| ------ | ------ | ---- | -------------------- |
-| len | number | Yes | Length of the random number to generate.|
+| Name| Type | Mandatory| Description |
+| ---- | --------------------- | ---- | -------------------- |
+| key | [DataBlob](#datablob) | Yes | Data to convert.|
**Return value**
-| Type | Description |
-| ------------------ | ----------- |
-| Promise\<[DataBlob](#datablob)> | Promise used to return the result.|
+| Type | Description |
+| --------------------------- | --------------------------------- |
+| Promise\<[SymKey](#symkey)> | Promise used to return the symmetric key generated.|
**Error codes**
-| ID| Error Message |
-| -------- | ---------------------- |
-| 17620001 | memory error. |
-| 17630001 | crypto operation error. |
+| ID| Error Message |
+| -------- | --------------------------------------------- |
+| 401 | invalid parameters. |
+| 17620001 | memory error. |
**Example**
-```javascript
-import cryptoFramework from "@ohos.security.cryptoFramework"
+```js
+import cryptoFramework from '@ohos.security.cryptoFramework';
-var rand;
-try {
- rand = cryptoFramework.createRandom();
-} catch (error) {
- console.error("[Callback]: error code: " + error.code + ", message is: " + error.message);
+function genKeyMaterialBlob() {
+ let arr = [
+ 0xba, 0x3d, 0xc2, 0x71, 0x21, 0x1e, 0x30, 0x56,
+ 0xad, 0x47, 0xfc, 0x5a, 0x46, 0x39, 0xee, 0x7c,
+ 0xba, 0x3b, 0xc2, 0x71, 0xab, 0xa0, 0x30, 0x72]; // keyLen = 192 (24 bytes)
+ let keyMaterial = new Uint8Array(arr);
+ return {data: keyMaterial};
}
-var promiseGenerateRand = rand.generateRandom(12);
-promiseGenerateRand.then(randData => {
- console.error("[Promise]: rand result: " + randData.data);
-}).catch(error => {
- console.error("[Promise]: error: " + error.message);
-});
+let symAlgName = '3DES192';
+let symKeyGenerator = cryptoFramework.createSymKeyGenerator(symAlgName);
+let keyMaterialBlob = genKeyMaterialBlob();
+symKeyGenerator.convertKey(keyMaterialBlob)
+.then(symKey => {
+ console.info(`Convert symKey success, algName: ${symKey.algName}`);
+}, error => {
+ console.error(`Convert symKey failed, ${error.code}, ${error.message}`);
+})
```
-### setSeed
+## cryptoFramework.createAsyKeyGenerator
-setSeed(seed : DataBlob) : void;
+createAsyKeyGenerator(algName: string): AsyKeyGenerator
-Sets a seed. This API uses an asynchronous callback to return the result.
+Creates an **AsyKeyGenerator** instance based on the specified algorithm. For details about the supported specifications, see [Key Generation Specifications](../../security/cryptoFramework-overview.md#key-generation-specifications).
**System capability**: SystemCapability.Security.CryptoFramework
-| Name | Type | Mandatory| Description |
-| -------- | --------------------- | ---- | ---------- |
-| seed | DataBlob | Yes | Seed to set.|
+**Parameters**
+
+| Name | Type | Mandatory| Description |
+| ------- | ------ | ---- | -------------------------------- |
+| algName | string | Yes | Algorithm used to create the **symkeyGenerator**.|
+
+**Return value**
+
+| Type | Description |
+| --------------- | ---------------------------- |
+| [AsyKeyGenerator](#asykeygenerator) | **AsyKeyGenerator** instance created.|
**Error codes**
-| ID| Error Message |
-| -------- | ----------------- |
-| 17620001 | memory error. |
+| ID| Error Message |
+| -------- | ---------------------- |
+| 401 | invalid parameters. |
+| 801 | this operation is not supported. |
+| 17620001 | memory error. |
**Example**
-```javascript
+```js
import cryptoFramework from "@ohos.security.cryptoFramework"
-var rand;
-try {
- rand = cryptoFramework.createRandom();
-} catch (error) {
- console.error("[Callback]: error code: " + error.code + ", message is: " + error.message);
-}
-
-rand.generateRandom(12, (err, randData) => {
- if (err) {
- console.error("[Callback] err: " + err.code);
- } else {
- console.error("[Callback]: generate random result: " + randData.data);
- try {
- rand.setSeed(randData);
- } catch (error) {
- console.log("setSeed failed, errCode: " + error.code + ", errMsg: " + error.message);
- }
- }
-});
+let asyKeyGenerator = cryptoFramework.createAsyKeyGenerator("ECC256");
```
-## ParamsSpec
+## AsyKeyGenerator
-Defines the parameters used for encryption and decryption.
+Provides APIs for using the **AsKeyGenerator**. Before using any API of the **AsKeyGenerator** class, you must create an **AsyKeyGenerator** instance by using **createAsyKeyGenerator()**.
-For the symmetric encryption and decryption modes that require parameters such as the initialization vector (IV), you must construct a child class object and pass it to [init()](#init-2). If no IV is required (for example, the ECB mode is used), pass in **null** in [init()](#init-2).
+### Attributes
**System capability**: SystemCapability.Security.CryptoFramework
-| Name | Type | Readable| Writable| Description |
-| ------- | ------ | ---- | ---- | ------------------------------------------------------------ |
-| algName | string | Yes | Yes | Symmetric encryption and decryption parameters. Options: - **IvParamsSpec**: applicable to the CBC, CTR, OFB, and CFB modes. - **GcmParamsSpec**: applicable to the GCM mode. - **CcmParamsSpec**: applicable to the CCM mode.|
-
-> **NOTE**
-> The **params** parameter in [init()](#init-2) is of the **ParamsSpec** type (parent class), but a child class object (such as **IvParamsSpec**) needs to be passed in. When constructing the child class object, set **algName** in the parent class **ParamsSpec** to let the algorithm library know the type of child class object to pass in in **init()**.
+| Name | Type | Readable| Writable| Description |
+| ------- | ------ | ---- | ---- | -------------------------------- |
+| algName | string | Yes | No | Algorithm used by the **AsKeyGenerator**.|
-## IvParamsSpec
+### generateKeyPair
-Defines the child class of [ParamsSpec](#paramsspec). It is used as the parameters of [init()](#init-2) during symmetric encryption and decryption.
+generateKeyPair(callback: AsyncCallback\): void
-**IvParamsSpec** applies to the encryption and decryption modes such as CBC, CTR, OFB, and CFB, which use only the IV.
+Generates a key pair randomly. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Security.CryptoFramework
-| Name| Type | Readable| Writable| Description |
-| ---- | --------------------- | ---- | ---- | ------------------------------------------------------------ |
-| iv | [DataBlob](#datablob) | Yes | Yes | IV for encryption and decryption. Options: - AES CBC, CTR, OFB, or CFB mode: 16-byte IV - 3DES CBC, OFB, or CFB mode: 8-byte IV|
-
-> **NOTE**
-> Before passing **IvParamsSpec** to [init()](#init-2), specify **algName** in its parent class [ParamsSpec](#paramsspec).
+**Parameters**
-## GcmParamsSpec
+| Name | Type | Mandatory| Description |
+| -------- | ----------------------- | ---- | ------------------------------ |
+| callback | AsyncCallback\<[KeyPair](#keypair)> | Yes | Callback invoked to return the key pair obtained.|
-Defines the child class of [ParamsSpec](#paramsspec) for the GCM mode. It is used as the parameters of [init()](#init-2) during symmetric encryption and decryption.
+**Error codes**
-**GcmParamsSpec** applies to the GCM mode.
+| ID| Error Message |
+| -------- | ---------------------- |
+| 401 | invalid parameters. |
+| 17620001 | memory error. |
+| 17630001 | crypto operation error. |
-**System capability**: SystemCapability.Security.CryptoFramework
+**Example**
-| Name | Type | Readable| Writable| Description |
-| ------- | --------------------- | ---- | ---- | ------------------------------------------------------------ |
-| iv | [DataBlob](#datablob) | Yes | Yes | IV, which is of 12 bytes. |
-| aad | [DataBlob](#datablob) | Yes | Yes | Additional authenticated data (AAD), which is of 8 bytes. |
-| authTag | [DataBlob](#datablob) | Yes | Yes | Authentication tag, which is of 16 bytes. When the GCM mode is used for encryption, [DataBlob](#datablob) output by [doFinal()](#dofinal-2) is required. The last 16 bytes of [DataBlob](#datablob) are used as as **authTag** in [GcmParamsSpec](#gcmparamsspec) of [init()](#init-2). |
+```js
+import cryptoFramework from "@ohos.security.cryptoFramework"
-> **NOTE**
-> Before passing **GcmParamsSpec** to [init()](#init-2), specify **algName** in its parent class [ParamsSpec](#paramsspec).
+let asyKeyGenerator = cryptoFramework.createAsyKeyGenerator("ECC256");
+asyKeyGenerator.generateKeyPair((err, keyPair) => {
+ if (err) {
+ console.error("generateKeyPair: error.");
+ return;
+ }
+ console.info("generateKeyPair: success.");
+})
+```
-## CcmParamsSpec
+### generateKeyPair
-Defines the child class of [ParamsSpec](#paramsspec) for the CCM mode. It is used as the parameters of [init()](#init-2) during symmetric encryption and decryption.
+generateKeyPair(): Promise\
-**CcmParamsSpec** applies to the CCM mode.
+Generates a key pair randomly. This API uses a promise to return the result.
**System capability**: SystemCapability.Security.CryptoFramework
-| Name | Type | Readable| Writable| Description |
-| ------- | --------------------- | ---- | ---- | ------------------------------------------------------------ |
-| iv | [DataBlob](#datablob) | Yes | Yes | IV, which is of 7 bytes. |
-| aad | [DataBlob](#datablob) | Yes | Yes | AAD, which is of 8 bytes. |
-| authTag | [DataBlob](#datablob) | Yes | Yes | Authentication tag, which is of 12 bytes. When the CCM mode is used for encryption, [DataBlob](#datablob) output by [doFinal()](#dofinal-2) is required. The last 12 bytes of [DataBlob](#datablob) are used as as **authTag** in [CcmParamsSpec](#ccmparamsspec) of [init()](#init-2).|
-
-> **NOTE**
-> Before passing **CcmParamsSpec** to [init()](#init-2), specify **algName** in its parent class [ParamsSpec](#paramsspec).
-
-## CryptoMode
+**Return value**
-Enumerates the cryptographic operations.
+| Type | Description |
+| ----------------- | --------------------------------- |
+| Promise\<[KeyPair](#keypair)> | Promise used to return the key pair generated.|
-**System capability**: SystemCapability.Security.CryptoFramework
+**Error codes**
-| Name | Value | Description |
-| ------------ | ---- | ---------------- |
-| ENCRYPT_MODE | 0 | Encryption.|
-| DECRYPT_MODE | 1 | Decryption.|
+| ID| Error Message |
+| -------- | ---------------------- |
+| 401 | invalid parameters. |
+| 17620001 | memory error. |
+| 17630001 | crypto operation error. |
-## Key
+**Example**
-Provides APIs for key operations. Before performing cryptographic operations (such as encryption and decryption), you need to construct a child class object of **Key** and pass it to [init()](#init-2) of the [Cipher](#cipher) instance. Keys can be generated by a key generator.
+```js
+import cryptoFramework from "@ohos.security.cryptoFramework"
-### Attributes
+let asyKeyGenerator = cryptoFramework.createAsyKeyGenerator("ECC256");
+let keyGenPromise = asyKeyGenerator.generateKeyPair();
+keyGenPromise.then( keyPair => {
+ console.info("generateKeyPair success.");
+}).catch(error => {
+ console.error("generateKeyPair error.");
+});
+```
-**System capability**: SystemCapability.Security.CryptoFramework
+### convertKey
-| Name | Type | Readable| Writable| Description |
-| ------- | ------ | ---- | ---- | ---------------------------- |
-| format | string | Yes | No | Format of the key. |
-| algName | string | Yes | No | Algorithm name (including the key length).|
+convertKey(pubKey: DataBlob, priKey: DataBlob, callback: AsyncCallback\): void
-### getEncoded
+Converts data into an asymmetric key. This API uses an asynchronous callback to return the result. For details, see **Key Conversion**.
-getEncoded() : DataBlob
+**System capability**: SystemCapability.Security.CryptoFramework
-Obtains a key in hexadecimal format. This API returns the result synchronously.
+**Parameters**
-**System capability**: SystemCapability.Security.CryptoFramework
+| Name | Type | Mandatory| Description |
+| -------- | ----------- | ---- | ------------------------------ |
+| pubKey | [DataBlob](#datablob) | Yes | Public key material to convert. If no public key is required, set this parameter to **null**. |
+| priKey | [DataBlob](#datablob) | Yes | Private key material to convert. If no private key is required, set this parameter to **null**. |
+| callback | AsyncCallback\<[KeyPair](#keypair)> | Yes | Callback invoked to return the key pair obtained.|
-**Return value**
+**Error codes**
-| Type | Description |
-| --------------------- | ------------------------ |
-| [DataBlob](#datablob) | Key obtained.|
+| ID| Error Message |
+| -------- | ---------------------- |
+| 401 | invalid parameters. |
+| 17620001 | memory error. |
+| 17630001 | crypto operation error. |
**Example**
```js
import cryptoFramework from "@ohos.security.cryptoFramework"
-function uint8ArrayToShowStr(uint8Array) {
- return Array.prototype.map
- .call(uint8Array, (x) => ('00' + x.toString(16)).slice(-2))
- .join('');
-}
-let key; // The key is generated by a symKeyGenerator. The generation process is omitted here.
-let encodedKey = key.getEncoded();
-console.info("key hex:" + uint8ArrayToShowStr(encodedKey.data));
+let pubKeyArray = new Uint8Array([48,89,48,19,6,7,42,134,72,206,61,2,1,6,8,42,134,72,206,61,3,1,7,3,66,0,4,83,96,142,9,86,214,126,106,247,233,92,125,4,128,138,105,246,162,215,71,81,58,202,121,26,105,211,55,130,45,236,143,55,16,248,75,167,160,167,106,2,152,243,44,68,66,0,167,99,92,235,215,159,239,28,106,124,171,34,145,124,174,57,92]);
+let priKeyArray = new Uint8Array([48,49,2,1,1,4,32,115,56,137,35,207,0,60,191,90,61,136,105,210,16,27,4,171,57,10,61,123,40,189,28,34,207,236,22,45,223,10,189,160,10,6,8,42,134,72,206,61,3,1,7]);
+let pubKeyBlob = {data: pubKeyArray}; // Data of the public key.
+let priKeyBlob = {data: priKeyArray}; // Data of the private key.
+let asyKeyGenerator = cryptoFramework.createAsyKeyGenerator("ECC256");
+asyKeyGenerator.convertKey(pubKeyBlob, priKeyBlob, (err, keyPair) => {
+ if (err) {
+ console.error("convertKey: error.");
+ return;
+ }
+ console.info("convertKey: success.");
+})
```
-## SymKey
+### convertKey
-Provides APIs for symmetric key operations. **SymKey** is a child class of [Key](#key), and its objects need to be passed to [init()](#init-2) of the [Cipher](#cipher) instance in symmetric encryption and decryption.
+convertKey(pubKey: DataBlob, priKey: DataBlob): Promise\
-Symmetric keys can be generated by a [SymKeyGenerator](#symkeygenerator).
+Converts data into an asymmetric key. This API uses a promise to return the result. For details, see **Key Conversion**.
-### clearMem
+**System capability**: SystemCapability.Security.CryptoFramework
+
+**Parameters**
-clearMem() : void
+| Name | Type | Mandatory| Description |
+| ------ | -------- | ---- | ---------------- |
+| pubKey | DataBlob | Yes | Public key material to convert. If no public key is required, set this parameter to **null**.|
+| priKey | DataBlob | Yes | Private key material to convert. If no private key is required, set this parameter to **null**.|
-Clears the keys in the memory. This API returns the result synchronously. You are advised to use this API when symmetric key instances are no longer used.
+**Return value**
-**System capability**: SystemCapability.Security.CryptoFramework
+| Type | Description |
+| ----------------- | --------------------------------- |
+| Promise\<[KeyPair](#keypair)> | Promise used to return the key pair generated.|
+
+**Error codes**
+
+| ID| Error Message |
+| -------- | ---------------------- |
+| 401 | invalid parameters. |
+| 17620001 | memory error. |
+| 17630001 | crypto operation error. |
**Example**
```js
import cryptoFramework from "@ohos.security.cryptoFramework"
-function uint8ArrayToShowStr(uint8Array) {
- return Array.prototype.map
- .call(uint8Array, (x) => ('00' + x.toString(16)).slice(-2))
- .join('');
-}
-let key; // The key is generated by a symKeyGenerator. The generation process is omitted here.
-let encodedKey = key.getEncoded();
-console.info("key hex: "+ uint8ArrayToShowStr(encodedKey.data)); // Key content is displayed.
-key.clearMem();
-encodedKey = key.getEncoded();
-console.info("key hex:" + uint8ArrayToShowStr(encodedKey.data)); // All 0s are displayed.
+let pubKeyArray = new Uint8Array([48,89,48,19,6,7,42,134,72,206,61,2,1,6,8,42,134,72,206,61,3,1,7,3,66,0,4,83,96,142,9,86,214,126,106,247,233,92,125,4,128,138,105,246,162,215,71,81,58,202,121,26,105,211,55,130,45,236,143,55,16,248,75,167,160,167,106,2,152,243,44,68,66,0,167,99,92,235,215,159,239,28,106,124,171,34,145,124,174,57,92]);
+let priKeyArray = new Uint8Array([48,49,2,1,1,4,32,115,56,137,35,207,0,60,191,90,61,136,105,210,16,27,4,171,57,10,61,123,40,189,28,34,207,236,22,45,223,10,189,160,10,6,8,42,134,72,206,61,3,1,7]);
+let pubKeyBlob = {data: pubKeyArray}; // Data of the public key.
+let priKeyBlob = {data: priKeyArray}; // Data of the private key.
+let asyKeyGenerator = cryptoFramework.createAsyKeyGenerator("ECC256");
+let keyGenPromise = asyKeyGenerator.convertKey(pubKeyBlob, priKeyBlob);
+keyGenPromise.then( keyPair => {
+ console.info("convertKey success.");
+}).catch(error => {
+ console.error("convertKey error.");
+});
```
-## PubKey
-
-Provides APIs for public key operations. **PubKey** is a child class of [Key](#key), and its objects need to be passed in during asymmetric encryption and decryption, signature verification, and key agreement.
+**Key Conversion**
-Public keys can be generated by an **AsyKeyGenerator**.
+1. After **getEncoded()** is called for the asymmetric (RSA, ECC, or DSA) public and private keys, binary data in X.509 format and binary data in PKCS #8 format are returned, respectively. The binary data can be used for cross-application transfer or persistent storage.
+2. The public key returned by **convertKey()** must comply with the ASN.1 syntax, X.509 specifications, and DER encoding format, and the private key must comply with the ASN.1 syntax, PKCS #8 specifications, and DER encoding format.
+3. In **convertKey()**, you can pass in either **pubKey** or **priKey**, or both of them. If one of them is passed in, the returned **KeyPair** instance contains only the key converted from the data you passed in.
-### Attributes
+## cryptoFramework.createAsyKeyGeneratorBySpec10+
-**System capability**: SystemCapability.Security.CryptoFramework
+createAsyKeyGeneratorBySpec(asyKeySpec: AsyKeySpec): AsyKeyGeneratorBySpec
-| Name | Type | Readable| Writable| Description |
-| ------- | ------ | ---- | ---- | ---------------------------- |
-| format | string | Yes | No | Format of the key. |
-| algName | string | Yes | No | Algorithm name (including the key length).|
+Creates an **AsyKeyGenerator** instance based on the key parameters. For details about the supported specifications, see [Key Generation Specifications](../../security/cryptoFramework-overview.md#key-generation-specifications).
+**System capability**: SystemCapability.Security.CryptoFramework
-### getEncoded
+**Parameters**
-getEncoded() : DataBlob
+| Name | Type | Mandatory| Description |
+| ------- | ------ | ---- | -------------------------------- |
+| asyKeySpec | [AsyKeySpec](#asykeyspec10) | Yes | Key parameters. The **AsyKeyGenerator** generates the public/private key based on the specified parameters.|
-Obtains a key in binary format. This API returns the result synchronously. The public key format must comply with the ASN.1 syntax, X.509 specifications, and DER encoding format.
+**Return value**
-**System capability**: SystemCapability.Security.CryptoFramework
+| Type | Description |
+| ----------------------------------------------- | -------------------------- |
+| [AsyKeyGeneratorBySpec](#asykeygeneratorbyspec10) | Returns the **AsyKeyGenerator** instance created.|
-**Return value**
+**Error codes**
-| Type | Description |
-| --------------------- | ------------------------ |
-| [DataBlob](#datablob) | Key obtained.|
+| ID| Error Message |
+| -------- | ---------------------- |
+| 401 | invalid parameters. |
+| 801 | this operation is not supported. |
+| 17620001 | memory error. |
**Example**
```js
-function uint8ArrayToShowStr(uint8Array) {
- return Array.prototype.map
- .call(uint8Array, (x) => ('00' + x.toString(16)).slice(-2))
- .join('');
+import cryptoFramework from "@ohos.security.cryptoFramework"
+
+// Set the common parameters contained in both the DSA1024 public and private keys.
+function genDsa1024CommonSpecBigE() {
+ let dsaCommonSpec = {
+ algName : "DSA",
+ specType : cryptoFramework.AsyKeySpecType.COMMON_PARAMS_SPEC,
+ p : BigInt("0xed1501551b8ab3547f6355ffdc2913856ddeca198833dbd04f020e5f25e47c50e0b3894f7690a0d2ea5ed3a7be25c54292a698e1f086eb3a97deb4dbf04fcad2dafd94a9f35c3ae338ab35477e16981ded6a5b13d5ff20bf55f1b262303ad3a80af71aa6aa2354d20e9c82647664bdb6b333b7bea0a5f49d55ca40bc312a1729"),
+ q : BigInt("0xd23304044019d5d382cfeabf351636c7ab219694ac845051f60b047b"),
+ g : BigInt("0x2cc266d8bd33c3009bd67f285a257ba74f0c3a7e12b722864632a0ac3f2c17c91c2f3f67eb2d57071ef47aaa8f8e17a21ad2c1072ee1ce281362aad01dcbcd3876455cd17e1dd55d4ed36fa011db40f0bbb8cba01d066f392b5eaa9404bfcb775f2196a6bc20eeec3db32d54e94d87ecdb7a0310a5a017c5cdb8ac78597778bd"),
+ }
+ return dsaCommonSpec;
+}
+// Set full parameters contained in the DSA1024 public and private keys.
+function genDsa1024KeyPairSpecBigE() {
+ let dsaCommonSpec = genDsa1024CommonSpecBigE();
+ let dsaKeyPairSpec = {
+ algName : "DSA",
+ specType : cryptoFramework.AsyKeySpecType.KEY_PAIR_SPEC,
+ params : dsaCommonSpec,
+ sk : BigInt("0xa2dd2adb2d11392c2541930f61f1165c370aabd2d78d00342e0a2fd9"),
+ pk : BigInt("0xae6b5d5042e758f3fc9a02d009d896df115811a75b5f7b382d8526270dbb3c029403fafb8573ba4ef0314ea86f09d01e82a14d1ebb67b0c331f41049bd6b1842658b0592e706a5e4d20c14b67977e17df7bdd464cce14b5f13bae6607760fcdf394e0b73ac70aaf141fa4dafd736bd0364b1d6e6c0d7683a5de6b9221e7f2d6b"),
+ }
+ return dsaKeyPairSpec;
}
-let key; // The key is a public key generated by the asymmetric key generator. The generation process is omitted here.
-console.info("key format:" + key.format);
-console.info("key algName:" + key.algName);
-var encodedKey = key.getEncoded();
-console.info("key encoded:" + uint8ArrayToShowStr(encodedKey.data));
+let asyKeyPairSpec = genDsa1024KeyPairSpecBigE(); // The JS input must be a positive number in big-endian format.
+let asyKeyGeneratorBySpec = cryptoFramework.createAsyKeyGeneratorBySpec(asyKeyPairSpec);
```
-## PriKey
-
-Provides APIs for private key operations. **PriKey** is a child class of [Key](#key), and its objects need to be passed in during asymmetric encryption and decryption, signature verification, and key agreement.
+## AsyKeyGeneratorBySpec10+
-Private keys can be generated by an **AsyKeyGenerator**.
+Provides APIs for using the **AsKeyGenerator**. Before using the APIs of this class, you need to use [createAsyKeyGeneratorBySpec()](#cryptoframeworkcreateasykeygeneratorbyspec10) to create an **AsyKeyGeneratorBySpec** instance.
### Attributes
**System capability**: SystemCapability.Security.CryptoFramework
-| Name | Type | Readable| Writable| Description |
-| ------- | ------ | ---- | ---- | ---------------------------- |
-| format | string | Yes | No | Format of the key. |
-| algName | string | Yes | No | Algorithm name (including the key length).|
+| Name | Type | Readable| Writable| Description |
+| ------- | ------ | ---- | ---- | -------------------------- |
+| algName | string | Yes | No | Algorithm used by the asymmetric key generator.|
-### getEncoded
+### generateKeyPair
-getEncoded() : DataBlob
+generateKeyPair(callback: AsyncCallback\): void
-Obtains a key in binary format. This API returns the result synchronously. The private key format must comply with the ASN.1 syntax, PKCS #8 specifications, and DER encoding mode.
+Generates an asymmetric key pair. This API uses an asynchronous callback to return the result. When you use key parameters of the **COMMON_PARAMS_SPEC** type to create the key generator, you can obtain a key pair randomly generated. When you use **KEY_PAIR_SPEC** to create the key generator, you can obtain a key pair that matches the key parameters.
**System capability**: SystemCapability.Security.CryptoFramework
-**Return value**
+**Parameters**
-| Type | Description |
-| --------------------- | ------------------------ |
-| [DataBlob](#datablob) | Key obtained.|
+| Name | Type | Mandatory| Description |
+| -------- | ----------------------- | ---- | ------------------------------ |
+| callback | AsyncCallback\<[KeyPair](#keypair)> | Yes | Callback invoked to return the key pair obtained.|
+
+**Error codes**
+
+| ID| Error Message |
+| -------- | ----------------------- |
+| 401 | invalid parameters. |
+| 17620001 | memory error. |
+| 17630001 | crypto operation error. |
**Example**
```js
-function uint8ArrayToShowStr(uint8Array) {
- return Array.prototype.map
- .call(uint8Array, (x) => ('00' + x.toString(16)).slice(-2))
- .join('');
-}
+import cryptoFramework from "@ohos.security.cryptoFramework"
-let key; // The key is a private key generated by the asymmetric key generator. The generation process is omitted here.
-console.info("key format:" + key.format);
-console.info("key algName:" + key.algName);
-var encodedKey = key.getEncoded();
-console.info("key encoded:" + uint8ArrayToShowStr(encodedKey.data));
+let asyKeyPairSpec; // asyKeyPairSpec specifies full parameters contained in the private and public keys. The generation process is omitted here.
+let asyKeyGeneratorBySpec = cryptoFramework.createAsyKeyGeneratorBySpec(asyKeyPairSpec);
+asyKeyGeneratorBySpec.generateKeyPair((err, keyPair) => {
+ if (err) {
+ console.error("generateKeyPair: error.");
+ return;
+ }
+ console.info("generateKeyPair: success.");
+})
```
-### clearMem
+### generateKeyPair
-clearMem() : void
+generateKeyPair(): Promise\
-Clears the keys in the memory. This API returns the result synchronously.
+Generates an asymmetric key pair. This API uses a promise to return the result. When you use key parameters of the **COMMON_PARAMS_SPEC** type to create the key generator, you can obtain a key pair randomly generated. When you use **KEY_PAIR_SPEC** to create the key generator, you can obtain a key pair that matches the key parameters.
**System capability**: SystemCapability.Security.CryptoFramework
-**Example**
-
-```js
-let key; // The key is a private key generated by the asymmetric key generator. The generation process is omitted here.
-key.clearMem();
-```
-
-## KeyPair
-
-Defines an asymmetric key pair, which includes a public key and a private key.
-
-Asymmetric key pairs can be generated by an **AsyKeyGenerator**.
+**Return value**
-> **NOTE**
->
-> The **pubKey** and **priKey** objects in the **KeyPair** object are defined as one parameter in **KeyPair**. When **KeyPair** leaves the scope, its internal objects may be destructed. The service must reference the **KeyPair** object instead of the **pubKey** or **priKey** object.
+| Type | Description |
+| ----------------- | --------------------------------- |
+| Promise\<[KeyPair](#keypair)> | Promise used to return the key pair generated.|
-### Attributes
+**Error codes**
-**System capability**: SystemCapability.Security.CryptoFramework
+| ID| Error Message |
+| -------- | ---------------------- |
+| 401 | invalid parameters. |
+| 17620001 | memory error. |
+| 17630001 | crypto operation error. |
-| Name | Type | Readable| Writable| Description |
-| ------- | ------ | ---- | ---- | ------------ |
-| priKey | [PriKey](#prikey) | Yes | No | Private key. |
-| pubKey | [PubKey](#pubkey) | Yes | No | Public key. |
+**Example**
+```js
+import cryptoFramework from "@ohos.security.cryptoFramework"
-## cryptoFramework.createSymKeyGenerator
+let asyKeyPairSpec; // asyKeyPairSpec specifies full parameters contained in the private and public keys. The generation process is omitted here.
+let asyKeyGeneratorBySpec = cryptoFramework.createAsyKeyGeneratorBySpec(asyKeyPairSpec);
+let keyGenPromise = asyKeyGeneratorBySpec.generateKeyPair();
+keyGenPromise.then( keyPair => {
+ console.info("generateKeyPair success.");
+}).catch(error => {
+ console.error("generateKeyPair error.");
+});
+```
-createSymKeyGenerator(algName : string) : SymKeyGenerator
+### generatePriKey
-Creates a **symKeyGenerator** instance based on the specified algorithm.
+generatePriKey(callback: AsyncCallback\): void
-For details about the supported specifications, see [Key Generation Specifications](../../security/cryptoFramework-overview.md#key-generation-specifications).
+Generates a private key. This API uses an asynchronous callback to return the result. If you use key parameters of the **PRIVATE_KEY_SPEC** type to create the key generator, you can obtain the specified private key. If you use **KEY_PAIR_SPEC** to create the key generator, you can obtain the private key from the generated key pair.
**System capability**: SystemCapability.Security.CryptoFramework
**Parameters**
-| Name | Type | Mandatory| Description |
-| ------- | ------ | ---- | ------------------------------------------------------------ |
-| algName | string | Yes | Algorithm used to create the **symKeyGenerator** instance. For details, see "String Parameter" in [Key Generation Specifications](../../security/cryptoFramework-overview.md#key-generation-specifications). |
+| Name | Type | Mandatory| Description |
+| -------- | ----------------------- | ---- | ------------------------------ |
+| callback | AsyncCallback\<[PriKey](#prikey)> | Yes | Callback invoked to return the key pair obtained.|
-**Return value**
+**Error codes**
-| Type | Description |
-| ----------------------------------- | -------------------------- |
-| [SymKeyGenerator](#symkeygenerator) | **symKeyGenerator** instance created.|
+| ID| Error Message |
+| -------- | ---------------------- |
+| 401 | invalid parameters. |
+| 17620001 | memory error. |
+| 17630001 | crypto operation error. |
**Example**
```js
-import cryptoFramework from '@ohos.security.cryptoFramework';
-let symKeyGenerator = cryptoFramework.createSymKeyGenerator('3DES192');
-```
+import cryptoFramework from "@ohos.security.cryptoFramework"
-## SymKeyGenerator
+let asyKeyPairSpec; // asyKeyPairSpec specifies full parameters contained in the private and public keys.
+let asyKeyGeneratorBySpec = cryptoFramework.createAsyKeyGeneratorBySpec(asyKeyPairSpec);
+asyKeyGeneratorBySpec.generatePriKey((err, prikey) => {
+ if (err) {
+ console.error("generatePriKey: error.");
+ return;
+ }
+ console.info("generatePriKey: success.");
+})
+```
-Provides APIs for using the **symKeyGenerator**.
+### generatePriKey
-Before using any API of the **SymKeyGenerator** class, you must create a **symKeyGenerator** instance by using [createSymKeyGenerator](#cryptoframeworkcreatesymkeygenerator).
+generatePriKey(): Promise\
-### Attributes
+Generates a private key. This API uses a promise to return the result. If you use key parameters of the **PRIVATE_KEY_SPEC** type to create the key generator, you can obtain the specified private key. If you use **KEY_PAIR_SPEC** to create the key generator, you can obtain the private key from the generated key pair.
**System capability**: SystemCapability.Security.CryptoFramework
-| Name | Type | Readable| Writable| Description |
-| ------- | ------ | ---- | ---- | ------------------------------ |
-| algName | string | Yes | No | Algorithm used by the **symKeyGenerator**.|
+**Return value**
-### generateSymKey
+| Type | Description |
+| ----------------- | --------------------------------- |
+| Promise\<[PriKey](#prikey)> | Promise used to return the key generated.|
+
+**Error codes**
+
+| ID| Error Message |
+| -------- | ---------------------- |
+| 401 | invalid parameters. |
+| 17620001 | memory error. |
+| 17630001 | crypto operation error. |
+
+**Example**
-generateSymKey(callback : AsyncCallback\) : void
+```js
+import cryptoFramework from "@ohos.security.cryptoFramework"
+
+let asyKeyPairSpec; // asyKeyPairSpec specifies full parameters contained in the private and public keys.
+let asyKeyGeneratorBySpec = cryptoFramework.createAsyKeyGeneratorBySpec(asyKeyPairSpec);
+let keyGenPromise = asyKeyGeneratorBySpec.generatePriKey();
+keyGenPromise.then( priKey => {
+ console.info("generatePriKey success.");
+}).catch(error => {
+ console.error("generatePriKey error.");
+});
+```
-Generates a symmetric key randomly. This API uses an asynchronous callback to return the result.
+### generatePubKey
-This API can be used only after a **symKeyGenerator** instance is created by using [createSymKeyGenerator](#cryptoframeworkcreatesymkeygenerator).
+generatePubKey(callback: AsyncCallback\): void
-**RAND_priv_bytes()** of OpenSSL can be used to generate random keys.
+Generates a public key. This API uses an asynchronous callback to return the result. If you use key parameters of the **PUBLIC_KEY_SPEC** type to create the key generator, you can obtain the specified public key. If you use **KEY_PAIR_SPEC** to create the key generator, you can obtain the public key from the generated key pair.
**System capability**: SystemCapability.Security.CryptoFramework
**Parameters**
-| Name | Type | Mandatory| Description |
-| -------- | --------------------------------- | ---- | ------------------------------------------------------------ |
-| callback | AsyncCallback\<[SymKey](#symkey)> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **undefined** and **data** is the symmetric key generated. Otherwise, **err** is an error object.|
+| Name | Type | Mandatory| Description |
+| -------- | ----------------------- | ---- | ------------------------------ |
+| callback | AsyncCallback\<[PubKey](#pubkey)> | Yes | Callback invoked to return the key pair obtained.|
**Error codes**
-| ID| Error Message |
-| -------- | ------------- |
-| 17620001 | memory error. |
+| ID| Error Message |
+| -------- | ---------------------- |
+| 401 | invalid parameters. |
+| 17620001 | memory error. |
+| 17630001 | crypto operation error. |
**Example**
```js
-import cryptoFramework from '@ohos.security.cryptoFramework';
-let symAlgName = '3DES192';
-let symKeyGenerator = cryptoFramework.createSymKeyGenerator(symAlgName);
-symKeyGenerator.generateSymKey((err, symKey) => {
+import cryptoFramework from "@ohos.security.cryptoFramework"
+
+let asyKeyPairSpec; // asyKeyPairSpec specifies full parameters contained in the private and public keys. The generation process is omitted here.
+let asyKeyGeneratorBySpec = cryptoFramework.createAsyKeyGeneratorBySpec(asyKeyPairSpec);
+asyKeyGeneratorBySpec.generateKeyPair((err, pubKey) => {
if (err) {
- console.error(`Generate symKey failed, ${err.code}, ${err.message}`);
- } else {
- console.info(`Generate symKey success, algName: ${symKey.algName}`);
+ console.error("generatePubKey: error.");
+ return;
}
+ console.info("generatePubKey: success.");
})
```
-### generateSymKey
-
-generateSymKey() : Promise\
+### generatePubKey
-Generates a symmetric key randomly. This API uses a promise to return the result.
+generatePubKey(): Promise\
-This API can be used only after a **symKeyGenerator** instance is created by using [createSymKeyGenerator](#cryptoframeworkcreatesymkeygenerator).
-
-**RAND_priv_bytes()** of OpenSSL can be used to generate random keys.
+Generates a public key. This API uses a promise to return the result. If you use key parameters of the **PUBLIC_KEY_SPEC** type to create the key generator, you can obtain the specified public key. If you use **KEY_PAIR_SPEC** to create the key generator, you can obtain the public key from the generated key pair.
**System capability**: SystemCapability.Security.CryptoFramework
**Return value**
-| Type | Description |
-| --------------------------- | --------------------------------- |
-| Promise\<[SymKey](#symkey)> | Promise used to return the symmetric key generated.|
+| Type | Description |
+| ----------------- | --------------------------------- |
+| Promise\<[PubKey](#pubkey)> | Promise used to return the key pair generated.|
**Error codes**
-| ID| Error Message |
-| -------- | ------------- |
-| 17620001 | memory error. |
+| ID| Error Message |
+| -------- | ---------------------- |
+| 401 | invalid parameters. |
+| 17620001 | memory error. |
+| 17630001 | crypto operation error. |
**Example**
```js
-import cryptoFramework from '@ohos.security.cryptoFramework';
-let symAlgName = 'AES128';
-let symKeyGenerator = cryptoFramework.createSymKeyGenerator(symAlgName);
-symKeyGenerator.generateSymKey()
-.then(symKey => {
- console.info(`Generate symKey success, algName: ${symKey.algName}`);
-}, error => {
- console.error(`Generate symKey failed, ${error.code}, ${error.message}`);
-})
+import cryptoFramework from "@ohos.security.cryptoFramework"
+
+let asyKeyPairSpec; // asyKeyPairSpec specifies full parameters contained in the private and public keys. The generation process is omitted here.
+let asyKeyGeneratorBySpec = cryptoFramework.createAsyKeyGeneratorBySpec(asyKeyPairSpec);
+let keyGenPromise = asyKeyGeneratorBySpec.generatePubKey();
+keyGenPromise.then( pubKey => {
+ console.info("generatePubKey success.");
+}).catch(error => {
+ console.error("generatePubKey error.");
+});
```
-### convertKey
+## cryptoFramework.createCipher
-convertKey(key : DataBlob, callback : AsyncCallback\) : void
+createCipher(transformation: string): Cipher
-Converts data into a symmetric key. This API uses an asynchronous callback to return the result. This API can be used only after a **symKeyGenerator** instance is created by using [createSymKeyGenerator](#cryptoframeworkcreatesymkeygenerator).
+Creates a [Cipher](#cipher) instance based on the specified algorithm. For details about the supported specifications, see [Encryption and Decryption Specifications](../../security/cryptoFramework-overview.md#encryption-and-decryption-specifications).
**System capability**: SystemCapability.Security.CryptoFramework
**Parameters**
-| Name | Type | Mandatory| Description |
-| -------- | --------------------------------- | ---- | ------------------------------------------------------------ |
-| key | [DataBlob](#datablob) | Yes | Data to convert. |
-| callback | AsyncCallback\<[SymKey](#symkey)> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **undefined** and **data** is the symmetric key generated. Otherwise, **err** is an error object.|
+| Name | Type | Mandatory| Description |
+| -------------- | ------ | ---- | ------------------------------------------------------------ |
+| transformation | string | Yes | Combination of the algorithm name (including the key length), encryption mode, and padding algorithm of the **Cipher** instance to create. For details, see **String Parameter** in [Encryption and Decryption Specifications](../../security/cryptoFramework-overview.md#encryption-and-decryption-specifications).|
+
+> **NOTE**
+>
+> 1. In symmetric encryption and decryption, the implementation of PKCS #5 is the same as that of PKCS #7. PKCS #5 and PKCS #7 use the same padding length and block length. That is, data is padded with 8 bytes in 3DES and 16 bytes in AES. **noPadding** indicates that no padding is performed. You need to understand the differences between different block cipher modes and use the correct parameter specifications. For example, padding is required for ECB and CBC. Otherwise, ensure that the plaintext length is an integer multiple of the block size. No padding is recommended for other modes. In this case, the ciphertext length is the same as the plaintext length.
+> 2. If RSA is used for asymmetric encryption and decryption, two **Cipher** objects must be created to perform encryption and decryption separately. For symmetric encryption and decryption, one **cipher** object can be used to perform both encryption and decryption as long as the algorithm specifications are the same.
+
+**Return value**
+
+| Type | Description |
+| ----------------- | ------------------------ |
+| [Cipher](#cipher) | [Cipher](#cipher) instance created.|
**Error codes**
-| ID| Error Message |
-| -------- | --------------------------------------------------- |
-| 17620001 | memory error. |
+| ID| Error Message |
+| -------- | ---------------------- |
+| 401 | invalid parameters. |
+| 801 | this operation is not supported. |
+| 17620001 | memory error. |
**Example**
```js
-import cryptoFramework from '@ohos.security.cryptoFramework';
+import cryptoFramework from "@ohos.security.cryptoFramework"
-function genKeyMaterialBlob() {
- let arr = [
- 0xba, 0x3d, 0xc2, 0x71, 0x21, 0x1e, 0x30, 0x56,
- 0xad, 0x47, 0xfc, 0x5a, 0x46, 0x39, 0xee, 0x7c,
- 0xba, 0x3b, 0xc2, 0x71, 0xab, 0xa0, 0x30, 0x72]; // keyLen = 192 (24 bytes)
- let keyMaterial = new Uint8Array(arr);
- return {data : keyMaterial};
+let cipherAlgName = '3DES192|ECB|PKCS7';
+var cipher;
+try {
+ cipher = cryptoFramework.createCipher(cipherAlgName);
+ console.info(`cipher algName: ${cipher.algName}`);
+} catch (error) {
+ console.error(`createCipher failed, ${error.code}, ${error.message}`);
}
-
-let symAlgName = '3DES192';
-let symKeyGenerator = cryptoFramework.createSymKeyGenerator(symAlgName);
-let keyMaterialBlob = genKeyMaterialBlob();
-symKeyGenerator.convertKey(keyMaterialBlob, (err, symKey) => {
- if (err) {
- console.error(`Convert symKey failed, ${err.code}, ${err.message}`);
- } else {
- console.info(`Convert symKey success, algName: ${symKey.algName}`);
- }
-})
```
-### convertKey
+## Cipher
-convertKey(key : DataBlob) : Promise\
+Provides APIs for cipher operations. The [init()](#init-2), [update()](#update-4), and [doFinal()](#dofinal-2) APIs in this class are called in sequence to implement symmetric encryption or decryption and asymmetric encryption or decryption. For details about the complete encryption and decryption process, see [Encryption and Decryption](../../security/cryptoFramework-guidelines.md#encryption-and-decryption).
-Converts data into a symmetric key. This API uses a promise to return the result. This API can be used only after a **symKeyGenerator** instance is created by using [createSymKeyGenerator](#cryptoframeworkcreatesymkeygenerator).
+A complete symmetric encryption/decryption process is slightly different from the asymmetric encryption/decryption process.
+
+- Symmetric encryption and decryption: **init()** and **doFinal()** are mandatory. **update()** is optional and can be called multiple times to encrypt or decrypt big data. After **doFinal()** is called to complete an encryption or decryption operation, **init()** can be called to start a new encryption or decryption operation.
+- RSA asymmetric encryption and decryption: **init()** and **doFinal()** are mandatory, and **update()** is not supported. **doFinal()** can be called multiple times to encrypt or decrypt big data. **init()** cannot be called repeatedly. If the encryption/decryption mode or padding mode is changed, a new **Cipher** object must be created.
+
+### Attributes
**System capability**: SystemCapability.Security.CryptoFramework
-**Parameters**
-| Name| Type | Mandatory| Description |
-| ---- | --------------------- | ---- | -------------------- |
-| key | [DataBlob](#datablob) | Yes | Data to convert.|
+| Name | Type | Readable| Writable| Description |
+| ------- | ------ | ---- | ---- | ---------------------------- |
+| algName | string | Yes | No | Algorithm.|
-**Return value**
+### init
-| Type | Description |
-| --------------------------- | --------------------------------- |
-| Promise\<[SymKey](#symkey)> | Promise used to return the symmetric key generated.|
+init(opMode: CryptoMode, key: Key, params: ParamsSpec, callback: AsyncCallback\): void
+
+Initializes a [cipher](#cipher) instance. This API uses an asynchronous callback to return the result. This API can be used only after a [Cipher](#cipher) instance is created by using [createCipher](#cryptoframeworkcreatecipher).
+
+**System capability**: SystemCapability.Security.CryptoFramework
+
+**Parameters**
+
+| Name | Type | Mandatory| Description |
+| -------- | ------------------------- | ---- | ------------------------------------------------------------ |
+| opMode | [CryptoMode](#cryptomode) | Yes | Operation (encryption or decryption) to perform. |
+| key | [Key](#key) | Yes | Key for encryption or decryption. |
+| params | [ParamsSpec](#paramsspec) | Yes | Parameters for encryption or decryption. For algorithm modes without parameters (such as ECB), **null** can be passed in.|
+| callback | AsyncCallback\ | Yes | Callback invoked to return the result. If the initialization is successful, **err** is **undefined**. Otherwise, **err** is an error object. |
**Error codes**
-| ID| Error Message |
-| -------- | --------------------------------------------- |
-| 17620001 | memory error. |
+| ID| Error Message |
+| -------- | --------------------------------------------------------- |
+| 401 | invalid parameters. |
+| 17620001 | memory error. |
+| 17620002 | runtime error. |
+| 17630001 | crypto operation error.|
**Example**
```js
import cryptoFramework from '@ohos.security.cryptoFramework';
+let symKey; // The process of generating the symmetric key is omitted here.
+let cipher; // The process of creating a Cipher instance is omitted here.
-function genKeyMaterialBlob() {
- let arr = [
- 0xba, 0x3d, 0xc2, 0x71, 0x21, 0x1e, 0x30, 0x56,
- 0xad, 0x47, 0xfc, 0x5a, 0x46, 0x39, 0xee, 0x7c,
- 0xba, 0x3b, 0xc2, 0x71, 0xab, 0xa0, 0x30, 0x72]; // keyLen = 192 (24 bytes)
- let keyMaterial = new Uint8Array(arr);
- return {data : keyMaterial};
-}
-
-let symAlgName = '3DES192';
-let symKeyGenerator = cryptoFramework.createSymKeyGenerator(symAlgName);
-let keyMaterialBlob = genKeyMaterialBlob();
-symKeyGenerator.convertKey(keyMaterialBlob)
-.then(symKey => {
- console.info(`Convert symKey success, algName: ${symKey.algName}`);
-}, error => {
- console.error(`Convert symKey failed, ${error.code}, ${error.message}`);
+cipher.init(cryptoFramework.CryptoMode.ENCRYPT_MODE, symKey, null, (err, ) => {
+ if (err) {
+ console.error(`Failed to init cipher, ${err.code}, ${err.message}`);
+ } else {
+ console.info(`Init cipher success`);
+ // Perform subsequent operations such as update.
+ }
})
```
-## cryptoFramework.createAsyKeyGenerator
-
-createAsyKeyGenerator(algName : string) : AsyKeyGenerator
+### init
-Creates an **AsyKeyGenerator** instance based on the specified algorithm.
+init(opMode: CryptoMode, key: Key, params: ParamsSpec): Promise\
-For details about the supported specifications, see [Key Generation Specifications](../../security/cryptoFramework-overview.md#key-generation-specifications).
+Initializes a [cipher](#cipher) instance. This API uses a promise to return the result. This API can be used only after a [Cipher](#cipher) instance is created by using [createCipher](#cryptoframeworkcreatecipher).
**System capability**: SystemCapability.Security.CryptoFramework
**Parameters**
-| Name | Type | Mandatory| Description |
-| ------- | ------ | ---- | -------------------------------- |
-| algName | string | Yes | Algorithm used to create the **symkeyGenerator**.|
+| Name | Type | Mandatory| Description |
+| ------ | ------------------------- | ---- | ------------------------------------------------------------ |
+| opMode | [CryptoMode](#cryptomode) | Yes | Operation (encryption or decryption) to perform. |
+| key | [Key](#key) | Yes | Key for encryption or decryption. |
+| params | [ParamsSpec](#paramsspec) | Yes | Parameters for encryption or decryption. For algorithm modes without parameters (such as ECB), **null** can be passed in.|
**Return value**
-| Type | Description |
-| --------------- | ---------------------------- |
-| [AsyKeyGenerator](#asykeygenerator) | **AsyKeyGenerator** instance created.|
-
-**Example**
-
-```javascript
-import cryptoFramework from "@ohos.security.cryptoFramework"
-
-let asyKeyGenerator = cryptoFramework.createAsyKeyGenerator("ECC256");
-```
+| Type | Description |
+| -------------- | -------------------------------------- |
+| Promise\ | Promise that returns no value.|
-## AsyKeyGenerator
+**Error codes**
-Provides APIs for using the **AsKeyGenerator**. Before using any API of the **AsKeyGenerator** class, you must create an **AsyKeyGenerator** instance by using **createAsyKeyGenerator()**.
+| ID| Error Message |
+| -------- | ------------------------------------------------- |
+| 401 | invalid parameters. |
+| 17620001 | memory error. |
+| 17620002 | runtime error. |
+| 17630001 | crypto operation error.|
-### Attributes
+**Example**
-**System capability**: SystemCapability.Security.CryptoFramework
+```js
+import cryptoFramework from '@ohos.security.cryptoFramework';
+let symKey; // The process of generating the symmetric key is omitted here.
+let cipher; // The process of creating a Cipher instance is omitted here.
+cipher.init(cryptoFramework.CryptoMode.ENCRYPT_MODE, symKey, null)
+.then(() => {
+ console.info(`Init cipher success`);
+ // Perform subsequent operations such as update.
+}, error => {
+ console.error(`Failed to init cipher, ${error.code}, ${error.message}`);
+})
+```
-| Name | Type | Readable| Writable| Description |
-| ------- | ------ | ---- | ---- | -------------------------------- |
-| algName | string | Yes | No | Algorithm used by the **AsKeyGenerator**.|
+### update
-### generateKeyPair
+update(data: DataBlob, callback: AsyncCallback\): void
-generateKeyPair(callback : AsyncCallback\) : void;
+Updates the data to encrypt or decrypt by segment. This API uses an asynchronous callback to return the encrypted or decrypted data. This API can be called only after the [Cipher](#cipher) instance is initialized by using [init()](init-2).
-Generates a key pair randomly. This API uses an asynchronous callback to return the result.
+> **NOTE**
+>
+> 1. If you are not familiar with the block modes for symmetric encryption and decryption, add a judgment to determine whether the result of each **update()** and **doFinal()** is null. If the result is not null, obtain the data to concatenate the complete ciphertext or plaintext. The reason is the block mode and the related specifications affect the **update()** and [doFinal()](#dofinal-2) results. For example, in ECB and CBC modes, data is encrypted or decrypted by block no matter whether the data passed in by **update()** is an integer multiple of the block length, and the encrypted/decrypted block data generated by this **update()** is output. That is, encrypted/decrypted data is returned as long as the data passed in by **update()** reaches the size of a block. Otherwise, **null** is returned and the data will be retained until a block is formed in the next **update()**/**doFinal()**. When **doFinal()** is called, the data that has not been encrypted or decrypted will be padded based on the padding mode set in [createCipher](#cryptoframeworkcreatecipher) to an integer multiple of the block length, and then encrypted or decrypted. For a mode in which a block cipher can be converted into a stream cipher, the length of the ciphertext may be the same as that of the plaintext.
+> 2. **update()** may be called multiple times or may not be called ([doFinal()](#dofinal-2) is called after [init](#init-2)), depending on the size of the data to encrypt or decrypt.
+> The algorithm library does not set a limit on the amount of data that can be passed in by **updated()** (once or accumulatively). For symmetric encryption and decryption of a large amount of data, you are advised to call **update()** multiple times to pass in the data by segment.
+> For details about the sample code for calling **update()** multiple times in AES, see [Encrypting and Decrypting Data](../../security/cryptoFramework-guidelines.md#encryption-and-decryption).
+> 3. RSA asymmetric encryption and decryption do not support **update()**.
**System capability**: SystemCapability.Security.CryptoFramework
**Parameters**
-| Name | Type | Mandatory| Description |
-| -------- | ----------------------- | ---- | ------------------------------ |
-| callback | AsyncCallback\<[KeyPair](#keypair)> | Yes | Callback invoked to return the key pair obtained.|
+| Name | Type | Mandatory| Description |
+| -------- | ------------------------------------- | ---- | ------------------------------------------------------------ |
+| data | [DataBlob](#datablob) | Yes | Data to encrypt or decrypt. It cannot be **null** or {data:Uint8Array (empty)}. |
+| callback | AsyncCallback\<[DataBlob](#datablob)> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **undefined**, and **data** is **DataBlob** (containing the encrypted or decrypted data). Otherwise, **err** is an error object.|
**Error codes**
-| ID| Error Message |
-| -------- | ---------------------- |
-| 17620001 | memory error. |
+| ID| Error Message |
+| -------- | ------------------------------------------- |
+| 401 | invalid parameters. |
+| 17620001 | memory error. |
+| 17620002 | runtime error. |
+| 17630001 | crypto operation error. |
**Example**
-```javascript
-import cryptoFramework from "@ohos.security.cryptoFramework"
+```js
+import cryptoFramework from '@ohos.security.cryptoFramework';
-let asyKeyGenerator = cryptoFramework.createAsyKeyGenerator("ECC256");
-asyKeyGenerator.generateKeyPair((err, keyPair) => {
+function stringToUint8Array(str) {
+ let arr = [];
+ for (let i = 0, j = str.length; i < j; ++i) {
+ arr.push(str.charCodeAt(i));
+ }
+ return new Uint8Array(arr);
+}
+
+let cipher; // The process of creating a Cipher instance is omitted here.
+// The init() process is omitted here.
+let plainText = {data: stringToUint8Array('this is test!')};
+cipher.update(plainText, (err, output) => { // Example of the encryption process.
if (err) {
- console.error("generateKeyPair: error.");
- return;
+ console.error(`Failed to update cipher`);
+ } else {
+ console.info(`Update cipher success`);
+ if (output != null) {
+ // Concatenate output.data to the ciphertext.
+ }
+ // Perform subsequent operations such as doFinal().
}
- console.info("generateKeyPair: success.");
})
```
+### update
-### generateKeyPair
+update(data: DataBlob): Promise\
-generateKeyPair() : Promise\
+Updates the data to encrypt or decrypt by segment. This API uses a promise to return the encrypted or decrypted data.
-Generates a key pair randomly. This API uses a promise to return the result.
+This API can be called only after the [Cipher](#cipher) instance is initialized by using [init()](init-2).
+
+> **NOTE**
+>
+> 1. If you are not familiar with the block modes for symmetric encryption and decryption, add a judgment to determine whether the result of each **update()** and **doFinal()** is null. If the result is not null, obtain the data to concatenate the complete ciphertext or plaintext. The reason is the block mode and the related specifications affect the **update()** and [doFinal()](#dofinal-2) results. For example, in ECB and CBC modes, data is encrypted or decrypted by block no matter whether the data passed in by **update()** is an integer multiple of the block length, and the encrypted/decrypted block data generated by this **update()** is output. That is, encrypted/decrypted data is returned as long as the data passed in by **update()** reaches the size of a block. Otherwise, **null** is returned and the data will be retained until a block is formed in the next **update()**/**doFinal()**. When **doFinal()** is called, the data that has not been encrypted or decrypted will be padded based on the padding mode set in [createCipher](#cryptoframeworkcreatecipher) to an integer multiple of the block length, and then encrypted or decrypted. For a mode in which a block cipher can be converted into a stream cipher, the length of the ciphertext may be the same as that of the plaintext.
+> 2. **update()** may be called multiple times or may not be called ([doFinal()](#dofinal-2) is called after [init](#init-2)), depending on the size of the data to encrypt or decrypt.
+> The algorithm library does not set a limit on the amount of data that can be passed in by **updated()** (once or accumulatively). For symmetric encryption and decryption of a large amount of data, you are advised to call **update()** multiple times to pass in the data by segment.
+> For details about the sample code for calling **update()** multiple times in AES, see [Encrypting and Decrypting Data](../../security/cryptoFramework-guidelines.md#encryption-and-decryption).
+> 3. RSA asymmetric encryption and decryption do not support **update()**.
**System capability**: SystemCapability.Security.CryptoFramework
+**Parameters**
+
+| Name| Type | Mandatory| Description |
+| ---- | --------------------- | ---- | -------------------- |
+| data | [DataBlob](#datablob) | Yes | Data to encrypt or decrypt. It cannot be **null** or {data:Uint8Array (empty)}.|
+
**Return value**
-| Type | Description |
-| ----------------- | --------------------------------- |
-| Promise\<[KeyPair](#keypair)> | Promise used to return the key pair generated.|
+| Type | Description |
+| ------------------------------- | ------------------------------------------------ |
+| Promise\<[DataBlob](#datablob)> | Promise used to return the **DataBlob** (containing the encrypted or decrypted data).|
**Error codes**
-| ID| Error Message |
-| -------- | ---------------------- |
-| 17620001 | memory error. |
+| ID| Error Message |
+| -------- | -------------------------------------------- |
+| 401 | invalid parameters. |
+| 17620001 | memory error. |
+| 17620002 | runtime error. |
+| 17630001 | crypto operation error. |
**Example**
-```javascript
-import cryptoFramework from "@ohos.security.cryptoFramework"
+```js
+import cryptoFramework from '@ohos.security.cryptoFramework';
-let asyKeyGenerator = cryptoFramework.createAsyKeyGenerator("ECC256");
-let keyGenPromise = asyKeyGenerator.generateKeyPair();
-keyGenPromise.then( keyPair => {
- console.info("generateKeyPair success.");
-}).catch(error => {
- console.error("generateKeyPair error.");
-});
+function stringToUint8Array(str) {
+ let arr = [];
+ for (let i = 0, j = str.length; i < j; ++i) {
+ arr.push(str.charCodeAt(i));
+ }
+ return new Uint8Array(arr);
+}
+
+let cipher; // The process of creating a Cipher instance is omitted here.
+// The init() process is omitted here.
+let plainText = {data: stringToUint8Array('this is test!')};
+cipher.update(plainText)
+.then((output) => {
+ console.info(`Update cipher success.`);
+ if (output != null) {
+ // Concatenate output.data to the ciphertext.
+ }
+ // Perform subsequent operations such as doFinal().
+}, error => {
+ console.info(`Update cipher failed.`);
+})
```
-### convertKey
+### doFinal
+
+doFinal(data: DataBlob, callback: AsyncCallback\): void
-convertKey(pubKey : DataBlob, priKey : DataBlob, callback : AsyncCallback\) : void
+(1) Encrypts or decrypts the remaining data (generated by the block cipher mode) and the data passed in by **doFinal()** to finalize the symmetric encryption or decryption. This API uses an asynchronous callback to return the encrypted or decrypted data. If a small amount of data needs to be encrypted or decrypted, you can use **doFinal()** to pass in data without using **update()**. If all the data has been passed in by [update()](#update-4), you can pass in **null** in **data** of **doFinal()**. The output of **doFinal()** varies with the symmetric encryption/decryption mode in use.
-Converts data into an asymmetric key. This API uses an asynchronous callback to return the result. For more information, see **Key Conversion**.
+- Symmetric encryption in GCM and CCM mode: The result consists of the ciphertext and **authTag** (the last 16 bytes for GCM and the last 12 bytes for CCM). If **null** is passed in by **data** of **doFinal()**, the result of **doFinal()** is **authTag**. **authTag** must be [GcmParamsSpec](#gcmparamsspec) or [CcmParamsSpec](#ccmparamsspec) used for decryption. The ciphertext is the **data** passed in for decryption.
+- Symmetric encryption and decryption in other modes and symmetric decryption in GCM and CCM modes: The result is the complete plaintext/ciphertext.
+
+(2) Encrypts or decrypts the input data for RSA asymmetric encryption/decryption. This API uses an asynchronous callback to return the result. If a large amount of data needs to be encrypted/decrypted, call **doFinal()** multiple times and concatenate the result of each **doFinal()** to obtain the complete plaintext/ciphertext.
+
+> **NOTE**
+>
+> 1. In symmetric encryption or decryption, calling **doFinal()** means the end of an encryption or decryption process, and the [Cipher](#cipher) instance state will be cleared. To start a new encryption or decryption operation, you must call [init()](#init-2) to pass in a complete parameter list for initialization. For example, if the same symmetric key is used for a **Cipher** instance to perform encryption and then decryption. After the encryption is complete, the **params** in **init** for decryption must be set instead of being **null**.
+> 2. If a decryption fails, check whether the data to be encrypted and decrypted matches the parameters in **[init](#init-2)**. For the GCM mode, check whether the **authTag** obtained after encryption is obtained from the **GcmParamsSpec** for decryption.
+> 3. The result of **doFinal()** may be **null**. To avoid exceptions, determine whether the result is **null** before using the **.data** field to access the **doFinal()** result.
+> 4. For details about the sample code for calling **doFinal()** multiple times during RSA asymmetric encryption and decryption, see [Encrypting and Decrypting Data](../../security/cryptoFramework-guidelines.md#encryption-and-decryption).
**System capability**: SystemCapability.Security.CryptoFramework
**Parameters**
-| Name | Type | Mandatory| Description |
-| -------- | ----------- | ---- | ------------------------------ |
-| pubKey | [DataBlob](#datablob) | Yes | Public key material to convert. If no public key is required, set this parameter to **null**. |
-| priKey | [DataBlob](#datablob) | Yes | Private key material to convert. If no private key is required, set this parameter to **null**. |
-| callback | AsyncCallback\<[KeyPair](#keypair)> | Yes | Callback invoked to return the key pair obtained.|
+| Name | Type | Mandatory| Description |
+| -------- | ------------------------------------- | ---- | ------------------------------------------------------------ |
+| data | [DataBlob](#datablob) | Yes | Data to encrypt or decrypt. It can be **null** in symmetric encryption or decryption, but cannot be {data:Uint8Array(empty)}. |
+| callback | AsyncCallback\<[DataBlob](#datablob)> | Yes | Callback invoked to return the result. If the data is successfully encrypted or decrypted, **err** is **undefined**, and **data** is the **DataBlob** (encryption or decryption result of the remaining data). Otherwise, **err** is an error object.|
**Error codes**
-| ID| Error Message |
-| -------- | ---------------------- |
-| 17620001 | memory error. |
+| ID| Error Message |
+| -------- | ----------------------- |
+| 401 | invalid parameters. |
+| 17620001 | memory error. |
+| 17620002 | runtime error. |
+| 17630001 | crypto operation error. |
**Example**
-```javascript
-import cryptoFramework from "@ohos.security.cryptoFramework"
-let pubKey; // Public key data in DER format complying with X.509 specifications. The data is omitted here.
-let priKey; // Private key data in DER format complying with PKCS#8 specifications. The data is omitted here.
-let asyKeyGenerator = cryptoFramework.createAsyKeyGenerator("ECC256");
-asyKeyGenerator.convertKey(pubKey, priKey, (err, keyPair) => {
+```js
+import cryptoFramework from '@ohos.security.cryptoFramework';
+
+let cipher; // The process of creating a Cipher instance is omitted here.
+let data; // The process of preparing the data to encrypt or decrypt is omitted here.
+// The init() and update() processes are omitted here.
+cipher.doFinal(data, (err, output) => {
if (err) {
- console.error("convertKey: error.");
- return;
+ console.error(`Failed to finalize cipher, ${err.code}, ${err.message}`);
+ } else {
+ console.info(`Finalize cipher success`);
+ if (output != null) {
+ // Concatenate output.data to obtain the complete plaintext/ciphertext (and authTag).
+ }
}
- console.info("convertKey: success.");
})
```
-### convertKey
+### doFinal
+
+doFinal(data: DataBlob): Promise\
+
+(1) Encrypts or decrypts the remaining data (generated by the block cipher mode) and the data passed in by **doFinal()** to finalize the symmetric encryption or decryption. This API uses a promise to return the encrypted or decrypted data. If a small amount of data needs to be encrypted or decrypted, you can use **doFinal()** to pass in data without using **update()**. If all the data has been passed in by [update()](#update-4), you can pass in **null** in **data** of **doFinal()**. The output of **doFinal()** varies with the symmetric encryption/decryption mode in use.
+
+- Symmetric encryption in GCM and CCM mode: The result consists of the ciphertext and **authTag** (the last 16 bytes for GCM and the last 12 bytes for CCM). If **null** is passed in by **data** of **doFinal()**, the result of **doFinal()** is **authTag**. **authTag** must be [GcmParamsSpec](#gcmparamsspec) or [CcmParamsSpec](#ccmparamsspec) used for decryption. The ciphertext is the **data** passed in for decryption.
+- Symmetric encryption and decryption in other modes and symmetric decryption in GCM and CCM modes: The result is the complete plaintext/ciphertext.
-convertKey(pubKey : DataBlob, priKey : DataBlob) : Promise\
+(2) Encrypts or decrypts the input data for RSA asymmetric encryption/decryption. This API uses a promise to return the result. If a large amount of data needs to be encrypted/decrypted, call **doFinal()** multiple times and concatenate the result of each **doFinal()** to obtain the complete plaintext/ciphertext.
-Converts data into an asymmetric key. This API uses a promise to return the result. For more information, see **Key Conversion**.
+> **NOTE**
+>
+> 1. In symmetric encryption or decryption, calling **doFinal()** means the end of an encryption or decryption process, and the [Cipher](#cipher) instance state will be cleared. To start a new encryption or decryption operation, you must call [init()](#init-2) to pass in a complete parameter list for initialization. For example, if the same symmetric key is used for a **Cipher** instance to perform encryption and then decryption. After the encryption is complete, the **params** in **init** for decryption must be set instead of being **null**.
+> 2. If a decryption fails, check whether the data to be encrypted and decrypted matches the parameters in **[init](#init-2)**. For the GCM mode, check whether the **authTag** obtained after encryption is obtained from the **GcmParamsSpec** for decryption.
+> 3. The result of **doFinal()** may be **null**. To avoid exceptions, determine whether the result is **null** before using the **.data** field to access the **doFinal()** result.
+> 4. For details about the sample code for calling **doFinal()** multiple times during RSA asymmetric encryption and decryption, see [Encrypting and Decrypting Data](../../security/cryptoFramework-guidelines.md#encryption-and-decryption).
**System capability**: SystemCapability.Security.CryptoFramework
**Parameters**
-| Name | Type | Mandatory| Description |
-| ------ | -------- | ---- | ---------------- |
-| pubKey | DataBlob | Yes | Public key material to convert. If no public key is required, set this parameter to **null**.|
-| priKey | DataBlob | Yes | Private key material to convert. If no private key is required, set this parameter to **null**.|
+| Name| Type | Mandatory| Description |
+| ---- | --------------------- | ---- | -------------------- |
+| data | [DataBlob](#datablob) | Yes | Data to encrypt or decrypt. It can be **null**, but cannot be {data:Uint8Array(empty)}.|
**Return value**
-| Type | Description |
-| ----------------- | --------------------------------- |
-| Promise\<[KeyPair](#keypair)> | Promise used to return the key pair obtained. |
+| Type | Description |
+| ------------------------------- | ------------------------------------------------ |
+| Promise\<[DataBlob](#datablob)> | Promise used to return the **DataBlob**, which is the encryption or decryption result of the remaining data.|
**Error codes**
-| ID| Error Message |
-| -------- | ---------------------- |
-| 17620001 | memory error. |
+| ID| Error Message |
+| -------- | -------------------------------------------- |
+| 401 | invalid parameters. |
+| 17620001 | memory error. |
+| 17620002 | runtime error. |
+| 17630001 | crypto operation error. |
**Example**
-```javascript
-import cryptoFramework from "@ohos.security.cryptoFramework"
+```js
+import cryptoFramework from '@ohos.security.cryptoFramework';
-let asyKeyGenerator = cryptoFramework.createAsyKeyGenerator("ECC256");
-let pubKey; // pubKey is a public key generated by the asymmetric key generator. The generation process is omitted here.
-let priKey; // priKey is a private key generated by the asymmetric key generator. The generation process is omitted here.
-let keyGenPromise = asyKeyGenerator.convertKey(pubKey, priKey);
-keyGenPromise.then( keyPair => {
- console.info("convertKey success.");
-}).catch(error => {
- console.error("convertKey error.");
-});
-```
-
-**Key Conversion**
+let cipher; // The process of creating a Cipher instance is omitted here.
+let data; // The process of preparing the data to encrypt or decrypt is omitted here.
+// The init() and update() processes are omitted here.
+cipher.doFinal(data)
+.then(output => {
+ console.info(`Finalize cipher success`);
+ if (output != null) {
+ // Concatenate output.data to obtain the complete plaintext/ciphertext (and authTag).
+ }
+}, error => {
+ console.error(`Failed to finalize cipher, ${error.code}, ${error.message}`);
+})
+```
-- If **getEncoded()** is called to obtain a public key and a private key (RSA and ECC), binary data in X.509 format and binary data in PKCS #8 format are returned, respectively. The data can be used for cross-application transfer or persistent storage.
-- When **convertKey()** is called to convert binary data into an asymmetric key pair, the public key material must comply with the ASN.1 syntax, X.509 specifications, and DER encoding format, and the private key material must comply with the ASN.1 syntax, PKCS #8 specifications, and DER encoding format.
-- In **convertKey()**, you can pass in either **pubKey** or **priKey**, or both of them. If one of them is passed in, the returned **KeyPair** instance contains only the key converted from the data you passed in.
+**RSA encryption example (callback)**
-## cryptoFramework.createCipher
+```js
+import cryptoFramework from "@ohos.security.cryptoFramework"
-createCipher(transformation : string) : Cipher
+function stringToUint8Array(str) {
+ let arr = [];
+ for (let i = 0, j = str.length; i < j; ++i) {
+ arr.push(str.charCodeAt(i));
+ }
+ return new Uint8Array(arr);
+}
-Creates a [Cipher](#cipher) instance based on the specified algorithm.
+let rsaGenerator = cryptoFramework.createAsyKeyGenerator("RSA1024|PRIMES_2");
+let cipher = cryptoFramework.createCipher("RSA1024|PKCS1");
+rsaGenerator.generateKeyPair(function (err, keyPair) {
+ let pubKey = keyPair.pubKey;
+ cipher.init(cryptoFramework.CryptoMode.ENCRYPT_MODE, pubKey, null, function (err, data) {
+ let plainText = "this is cipher text";
+ let input = {data: stringToUint8Array(plainText) };
+ cipher.doFinal(input, function (err, data) {
+ AlertDialog.show({ message: "EncryptOutPut is " + data.data} );
+ });
+ });
+});
+```
-For details about the supported specifications, see [Encryption and Decryption Specifications](../../security/cryptoFramework-overview.md#encryption-and-decryption-specifications).
+**RSA encryption example (promise)**
-**System capability**: SystemCapability.Security.CryptoFramework
+```js
+import cryptoFramework from "@ohos.security.cryptoFramework"
-**Parameters**
+function stringToUint8Array(str) {
+ let arr = [];
+ for (let i = 0, j = str.length; i < j; ++i) {
+ arr.push(str.charCodeAt(i));
+ }
+ return new Uint8Array(arr);
+}
-| Name | Type | Mandatory| Description |
-| -------------- | ------ | ---- | ------------------------------------------------------------ |
-| transformation | string | Yes | Combination of the algorithm name (including the key length), encryption mode, and padding algorithm of the **Cipher** instance to create. For details, see **Algorithm String** in [Encryption and Decryption Specifications](../../security/cryptoFramework-overview.md#encryption-and-decryption-specifications). |
+let rsaGenerator = cryptoFramework.createAsyKeyGenerator("RSA1024|PRIMES_2");
+let cipher = cryptoFramework.createCipher("RSA1024|PKCS1");
+let keyGenPromise = rsaGenerator.generateKeyPair();
+keyGenPromise.then(rsaKeyPair => {
+ let pubKey = rsaKeyPair.pubKey;
+ return cipher.init(cryptoFramework.CryptoMode.ENCRYPT_MODE, pubKey, null); // Pass in the private key and DECRYPT_MODE to initialize the decryption mode.
+}).then(() => {
+ let plainText = "this is cipher text";
+ let input = { data: stringToUint8Array(plainText) };
+ return cipher.doFinal(input);
+}).then(dataBlob => {
+ console.info("EncryptOutPut is " + dataBlob.data);
+});
+```
> **NOTE**
-> - In symmetric encryption and decryption, the implementation of PKCS #5 is the same as that of PKCS #7. PKCS #5 and PKCS #7 use the same padding length and block length. That is, data is padded with 8 bytes in 3DES and 16 bytes in AES. **noPadding** indicates that no padding is performed. You need to understand the differences between different block cipher modes and set parameter correctly. For example, padding is required for ECB and CBC. Otherwise, the plaintext length must be an integer multiple of the block size. No padding is recommended for other modes. In this case, the ciphertext length is the same as the plaintext length.
-> - If RSA is used for asymmetric encryption and decryption, two **Cipher** objects must be created to perform encryption and decryption separately. For symmetric encryption and decryption, one **cipher** object can be used to perform both encryption and decryption as long as the algorithm specifications are the same.
-
-**Return value**
-
-| Type | Description |
-| ----------------- | ------------------------ |
-| [Cipher](#cipher) | [Cipher](#cipher) instance created.|
-
-**Example**
-
-```javascript
-import cryptoFramework from "@ohos.security.cryptoFramework"
+>
+> For more encryption and decryption examples, see [Encryption and Decryption](../../security/cryptoFramework-guidelines.md#encryption-and-decryption).
-let cipherAlgName = '3DES192|ECB|PKCS7';
-var cipher;
-try {
- cipher = cryptoFramework.createCipher(cipherAlgName);
- console.info(`cipher algName: ${cipher.algName}`);
-} catch (error) {
- console.error(`createCipher failed, ${error.code}, ${error.message}`);
-}
-```
+### setCipherSpec10+
-## Cipher
+setCipherSpec(itemType: CipherSpecItem, itemValue: Uint8Array): void
-Provides APIs for cipher operations. The [init()](#init-2), [update()](#update-4), and [doFinal()](#dofinal-2) APIs in this class are called in sequence to implement symmetric encryption/decryption and asymmetric encryption/decryption.
+Sets cipher specifications. You can use this API to set cipher specifications that cannot be set by [createCipher](#cryptoframeworkcreatecipher). Currently, only the RSA is supported.
-For details about the complete encryption and decryption process, see [Encrypting and Decrypting Data](../../security/cryptoFramework-guidelines.md#encrypting-and-decrypting-data).
+**System capability**: SystemCapability.Security.CryptoFramework
-A complete symmetric encryption/decryption process is slightly different from the asymmetric encryption/decryption process.
+**Parameters**
-- In symmetric encryption and decryption, **init()** and **doFinal()** are mandatory. **update()** is optional and can be called multiple times to encrypt or decrypt big data by segment. After **doFinal()** is called to complete an encryption/decryption operation, **init()** can be called to start a new encryption/decryption operation.
-- In RSA asymmetric encryption and decryption, **init()** and **doFinal()** are mandatory, and **update()** is not supported. **doFinal()** can be called multiple times to encrypt or decrypt big data by segment. **init()** cannot be called repeatedly. If the encryption/decryption mode or padding mode is changed, a new **Cipher** object must be created.
+| Name | Type | Mandatory| Description |
+| -------- | -------------------- | ---- | ---------- |
+| itemType | [CipherSpecItem](#cipherspecitem10) | Yes | Cipher parameter to set.|
+| itemValue | Uint8Array | Yes | Value of the parameter to set.|
-### Attributes
+**Error codes**
-**System capability**: SystemCapability.Security.CryptoFramework
+| ID| Error Message |
+| -------- | ---------------------- |
+| 401 | invalid parameters. |
+| 801 | this operation is not supported. |
+| 17620001 | memory error. |
+| 17630001 | crypto operation error. |
+**Example**
-| Name | Type | Readable| Writable| Description |
-| ------- | ------ | ---- | ---- | ---------------------------- |
-| algName | string | Yes | No | Algorithm.|
+```js
+import cryptoFramework from '@ohos.security.cryptoFramework';
-### init
+let cipher; // The process of generating the Cipher instance is omitted here.
+let pSource = new Uint8Array([1,2,3,4]);
+cipher.setCipherSpec(cryptoFramework.CipherSpecItem.OAEP_MGF1_PSRC_UINT8ARR, pSource);
+```
-init(opMode : CryptoMode, key : Key, params : ParamsSpec, callback : AsyncCallback\) : void
+### getCipherSpec10+
-Initializes a [cipher](#cipher) instance. This API uses an asynchronous callback to return the result.
+getCipherSpec(itemType: CipherSpecItem): string | Uint8Array
-This API can be used only after a [Cipher](#cipher) instance is created by using [createCipher](#cryptoframeworkcreatecipher).
+Obtains cipher specifications. Currently, only the RSA is supported.
**System capability**: SystemCapability.Security.CryptoFramework
**Parameters**
-| Name | Type | Mandatory| Description |
-| -------- | ------------------------- | ---- | ------------------------------------------------------------ |
-| opMode | [CryptoMode](#cryptomode) | Yes | Operation (encryption or decryption) to perform. |
-| key | [Key](#key) | Yes | Key for encryption or decryption. |
-| params | [ParamsSpec](#paramsspec) | Yes | Parameters for encryption or decryption. For algorithm modes without parameters (such as ECB), **null** can be passed in.|
-| callback | AsyncCallback\ | Yes | Callback invoked to return the result. If the initialization is successful, **err** is **undefined**. Otherwise, **err** is an error object. |
+| Name| Type | Mandatory| Description |
+| ------ | -------- | ---- | ---------- |
+| itemType | [CipherSpecItem](#cipherspecitem10) | Yes | Cipher parameter to obtain.|
+
+**Return value**
+
+| Type | Description |
+| -------------- | ----------- |
+| string\|Uint8Array | Returns the value of the cipher parameter obtained.|
**Error codes**
-| ID| Error Message |
-| -------- | --------------------------------------------------------- |
-| 17620001 | memory error. |
-| 17620002 | runtime error. |
-| 17630001 | crypto operation error.|
+| ID| Error Message |
+| -------- | ---------------------- |
+| 401 | invalid parameters. |
+| 801 | this operation is not supported. |
+| 17620001 | memory error. |
+| 17630001 | crypto operation error. |
**Example**
```js
import cryptoFramework from '@ohos.security.cryptoFramework';
-let symKey; // The process of generating the symmetric key is omitted here.
-let cipher; // The process of creating a Cipher instance is omitted here.
-cipher.init(cryptoFramework.CryptoMode.ENCRYPT_MODE, symKey, null, (err, ) => {
- if (err) {
- console.error(`Failed to init cipher, ${err.code}, ${err.message}`);
- } else {
- console.info(`Init cipher success`);
- // Perform subsequent operations such as update.
- }
-})
+let cipher; // The process of generating the Cipher instance is omitted here.
+let mdName = cipher.getCipherSpec(cryptoFramework.CipherSpecItem.OAEP_MD_NAME_STR);
```
-### init
-
-init(opMode : CryptoMode, key : Key, params : ParamsSpec) : Promise\
+## cryptoFramework.createSign
-Initializes a [cipher](#cipher) instance. This API uses a promise to return the result.
+createSign(algName: string): Sign
-This API can be used only after a [Cipher](#cipher) instance is created by using [createCipher](#cryptoframeworkcreatecipher).
+Creates a **Sign** instance. For details about the supported specifications, see [Signing and Signature Verification Specifications](../../security/cryptoFramework-overview.md#signing-and-signature-verification-specifications).
**System capability**: SystemCapability.Security.CryptoFramework
**Parameters**
-| Name | Type | Mandatory| Description |
-| ------ | ------------------------- | ---- | ------------------------------------------------------------ |
-| opMode | [CryptoMode](#cryptomode) | Yes | Operation (encryption or decryption) to perform. |
-| key | [Key](#key) | Yes | Key for encryption or decryption. |
-| params | [ParamsSpec](#paramsspec) | Yes | Parameters for encryption or decryption. For algorithm modes without parameters (such as ECB), **null** can be passed in.|
+| Name | Type | Mandatory| Description |
+| ------- | ------ | ---- | ------------------------------------------------------------ |
+| algName | string | Yes | Signing algorithm, which can be RSA, ECC, or DSA. If the RSA PKCS1 mode is used, you need to set the digest. If the RSA PSS mode is used, you need to set the digest and mask digest.|
**Return value**
-| Type | Description |
-| -------------- | -------------------------------------- |
-| Promise\ | Promise that returns no value.|
+| Type| Description |
+| ---- | ---------------------------------- |
+| Sign | Returns the **Sign** instance created.|
**Error codes**
-| ID| Error Message |
-| -------- | ------------------------------------------------- |
-| 17620001 | memory error. |
-| 17620002 | runtime error. |
-| 17630001 | crypto operation error.|
+| ID| Error Message |
+| -------- | ---------------------- |
+| 401 | invalid parameters. |
+| 801 | this operation is not supported. |
+| 17620001 | memory error. |
**Example**
```js
-import cryptoFramework from '@ohos.security.cryptoFramework';
-let symKey; // The process of generating the symmetric key is omitted here.
-let cipher; // The process of creating a Cipher instance is omitted here.
-cipher.init(cryptoFramework.CryptoMode.ENCRYPT_MODE, symKey, null)
-.then(() => {
- console.info(`Init cipher success`);
- // Perform subsequent operations such as update.
-}, error => {
- console.error(`Failed to init cipher, ${error.code}, ${error.message}`);
-})
+import cryptoFramework from "@ohos.security.cryptoFramework"
+
+let signer1 = cryptoFramework.createSign("RSA1024|PKCS1|SHA256");
+
+let singer2 = cryptoFramework.createSign("RSA1024|PSS|SHA256|MGF1_SHA256");
+
+let singer3 = cryptoFramework.createSign("ECC224|SHA256");
+
+let singer4 = cryptoFramework.createSign("DSA2048|SHA256");
```
-### update
+## Sign
-update(data : DataBlob, callback : AsyncCallback\) : void
+Provides APIs for signing. Before using any API of the **Sign** class, you must create a **Sign** instance by using **createSign(algName: string): Sign**. Invoke **init()**, **update()**, and **sign()** in this class in sequence to complete the signing operation. For details about the sample code, see [Signing and Signature Verification](../../security/cryptoFramework-guidelines.md#signing-and-signature-verification).
-Updates the data to encrypt or decrypt by segment. This API uses an asynchronous callback to return the encrypted or decrypted data.
+The **Sign** class does not support repeated initialization. When a new key is used for signing, you must create a new **Sign** object and call **init()** for initialization.
-This API can be called only after the [Cipher](#cipher) instance is initialized by using [init()](init-2).
+The signing mode is determined in **createSign()**, and the key is set by **init()**.
-> **NOTE**
-> - The **update()** and [doFinal()](#dofinal-2) results vary with the block mode you use. If you are not familiar with the block modes for symmetric encryption and decryption, add a judgment to determine whether the result of each **update()** and **doFinal()** is null. If the result is not null, obtain the data to concatenate the complete ciphertext or plaintext. For example, in ECB and CBC modes, data is encrypted or decrypted by block no matter whether the data passed in by **update()** is an integer multiple of the block length, and the encrypted/decrypted block data generated by this **update()** is output. That is, data is output by **update()** as long as the input data is of the block size. Otherwise, **null** is returned and the data will be retained until a block is formed in the next **update()**/**doFinal()**. When **doFinal()** is called, the data that has not been encrypted or decrypted will be padded based on the padding mode set in [createCipher](#cryptoframeworkcreatecipher) to an integer multiple of the block length, and then encrypted or decrypted. For a mode in which a block cipher can be converted into a stream cipher, the length of the ciphertext may be the same as that of the plaintext.
-> - **update()** can be called multiple times or not be called ([doFinal()](#dofinal-2) is called after [init](#init-2)), depending on the size of the data to encrypt or decrypt. The algorithm library does not set a limit on the amount of data that can be passed in by **updated()** (once or accumulatively). For symmetric encryption and decryption of a large amount of data, you are advised to call **update()** multiple times to pass in the data by segment. For details about the sample code for calling **update()** multiple times in AES, see [Encrypting and Decrypting Data](../../security/cryptoFramework-guidelines.md#encrypting-and-decrypting-data).
-> - RSA asymmetric encryption and decryption do not support **update()**.
+If the data to be signed is short, you can directly call **sign()** to pass in the original data for signing after **init()**. That is, you do not need to use **update()**.
+
+If the data to be signed is long, you can use **update()** to pass in the data by segment, and then use **sign()** to sign the entire data.
+
+If **update()** is used to pass in data by segment, **data** of **sign()** can be **null**.
+
+### Attributes
**System capability**: SystemCapability.Security.CryptoFramework
-**Parameters**
+| Name | Type | Readable| Writable| Description |
+| ------- | ------ | ---- | ---- | ---------------------------- |
+| algName | string | Yes | No | Algorithm to use.|
-| Name | Type | Mandatory| Description |
-| -------- | ------------------------------------- | ---- | ------------------------------------------------------------ |
-| data | [DataBlob](#datablob) | Yes | Data to encrypt or decrypt. It cannot be **null** or {data:Uint8Array (null)}. |
-| callback | AsyncCallback\<[DataBlob](#datablob)> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **undefined**, and **data** is **DataBlob** (containing the encrypted or decrypted data). Otherwise, **err** is an error object.|
+### init
-**Error codes**
+init(priKey: PriKey, callback: AsyncCallback\): void
-| ID| Error Message |
-| -------- | ------------------------------------------- |
-| 17620001 | memory error. |
-| 17620002 | runtime error. |
-| 17630001 | crypto operation error. |
+Initializes a **Sign** object using a private key. This API uses an asynchronous callback to return the result. The **Sign** class does not support repeated calling of **init()**.
-**Example**
+**System capability**: SystemCapability.Security.CryptoFramework
-```js
-import cryptoFramework from '@ohos.security.cryptoFramework';
+**Parameters**
-function stringToUint8Array(str) {
- let arr = [];
- for (let i = 0, j = str.length; i < j; ++i) {
- arr.push(str.charCodeAt(i));
- }
- return new Uint8Array(arr);
-}
+| Name | Type | Mandatory| Description |
+| -------- | -------------------- | ---- | ---------------- |
+| priKey | [PriKey](#prikey) | Yes | Private key used for the initialization.|
+| callback | AsyncCallback\ | Yes | Callback invoked to return the result. |
-let cipher; // The process of creating a Cipher instance is omitted here.
-// The init() process is omitted here.
-let plainText = {data : stringToUint8Array('this is test!')};
-cipher.update(plainText, (err, output) => { // Example of the encryption process.
- if (err) {
- console.error(`Failed to update cipher`);
- } else {
- console.info(`Update cipher success`);
- if (output != null) {
- // Concatenate output.data to the ciphertext.
- }
- // Perform subsequent operations such as doFinal().
- }
-})
-```
+**Error codes**
-### update
+| ID| Error Message |
+| -------- | ---------------------- |
+| 401 | invalid parameters. |
+| 17620001 | memory error. |
+| 17620002 | runtime error. |
+| 17630001 | crypto operation error. |
-update(data : DataBlob) : Promise\
+### init
-Updates the data to encrypt or decrypt by segment. This API uses a promise to return the encrypted or decrypted data. This API can be called only after the [Cipher](#cipher) instance is initialized by using [init()](init-2).
+init(priKey: PriKey): Promise\
-> **NOTE**
-> - The **update()** and [doFinal()](#dofinal-2) results vary with the block mode you use. If you are not familiar with the block modes for symmetric encryption and decryption, add a judgment to determine whether the result of each **update()** and **doFinal()** is null. If the result is not null, obtain the data to concatenate the complete ciphertext or plaintext. For example, in ECB and CBC modes, data is encrypted or decrypted by block no matter whether the data passed in by **update()** is an integer multiple of the block length, and the encrypted/decrypted block data generated by this **update()** is output. That is, data is output as long as the data passed in by **update()** is of the block size. Otherwise, **null** is returned and the data will be retained until a block is formed in the next **update()**/**doFinal()**. When **doFinal()** is called, the data that has not been encrypted or decrypted will be padded based on the padding mode set in [createCipher](#cryptoframeworkcreatecipher) to an integer multiple of the block length, and then encrypted or decrypted. For a mode in which a block cipher can be converted into a stream cipher, the length of the ciphertext may be the same as that of the plaintext.
-> - **update()** can be called multiple times or not be called ([doFinal()](#dofinal-2) is called after [init](#init-2)), depending on the size of the data to encrypt or decrypt. The algorithm library does not set a limit on the amount of data that can be passed in by **updated()** (once or accumulatively). For symmetric encryption and decryption of a large amount of data, you are advised to call **update()** multiple times to pass in the data by segment. For details about the sample code for calling **update()** multiple times in AES, see [Encrypting and Decrypting Data](../../security/cryptoFramework-guidelines.md#encrypting-and-decrypting-data).
-> - RSA asymmetric encryption and decryption do not support **update()**.
+Initializes a **Sign** object using a private key. This API uses a promise to return the result. The **Sign** class does not support repeated calling of **init()**.
**System capability**: SystemCapability.Security.CryptoFramework
**Parameters**
-| Name| Type | Mandatory| Description |
-| ---- | --------------------- | ---- | -------------------- |
-| data | [DataBlob](#datablob) | Yes | Data to encrypt or decrypt. It cannot be **null** or {data:Uint8Array (null)}.|
+| Name| Type| Mandatory| Description |
+| ------ | ---- | ---- | ---------------- |
+| priKey | [PriKey](#prikey) | Yes | Private key used for the initialization.|
**Return value**
-| Type | Description |
-| ------------------------------- | ------------------------------------------------ |
-| Promise\<[DataBlob](#datablob)> | Promise used to return the **DataBlob** (containing the encrypted or decrypted data).|
+| Type | Description |
+| -------------- | ------------- |
+| Promise\ | Promise that returns no value.|
**Error codes**
-| ID| Error Message |
-| -------- | -------------------------------------------- |
-| 17620001 | memory error. |
-| 17620002 | runtime error. |
-| 17630001 | crypto operation error. |
+| ID| Error Message |
+| -------- | ---------------------- |
+| 401 | invalid parameters. |
+| 17620001 | memory error. |
+| 17620002 | runtime error. |
+| 17630001 | crypto operation error. |
-**Example**
+### update
-```js
-import cryptoFramework from '@ohos.security.cryptoFramework';
+update(data: DataBlob, callback: AsyncCallback\): void
-function stringToUint8Array(str) {
- let arr = [];
- for (let i = 0, j = str.length; i < j; ++i) {
- arr.push(str.charCodeAt(i));
- }
- return new Uint8Array(arr);
-}
+Updates the data to be signed. This API uses a callback to complete the update. This API can be called only after the [Sign](#sign) instance is initialized by using [init()](init-2).
-let cipher; // The process of creating a Cipher instance is omitted here.
-// The init() process is omitted here.
-let plainText = {data : stringToUint8Array('this is test!')};
-cipher.update(plainText)
-.then((output) => {
- console.info(`Update cipher success.`);
- if (output != null) {
- // Concatenate output.data to the ciphertext.
- }
- // Perform subsequent operations such as doFinal().
-}, error => {
- console.info(`Update cipher failed.`);
-})
-```
+> **NOTE**
+>
+> **update()** may be called multiple times or may not be called (call [sign](#sign-1) after [init](#init-2)), depending on the size of the data. The algorithm library does not set a limit on the amount of data to be updated (once or accumulatively). If a large amount of data needs to be signed, you are advised to use **update()** multiple times to pass in data. This can prevent too much memory from being requested at a time. For details about the sample code for calling **update()** multiple times, see [Signing and Signature verification](../../security/cryptoFramework-guidelines.md#signing-and-signature-verification).
-### doFinal
+**System capability**: SystemCapability.Security.CryptoFramework
-doFinal(data : DataBlob, callback : AsyncCallback\) : void
+**Parameters**
-(1) Encrypts or decrypts the remaining data (generated by the block ciper mode) and the data passed in by **doFinal()** to finalize the symmetric encryption or decryption. This API uses an asynchronous callback to return the encrypted or decrypted data. If a small amount of data needs to be encrypted or decrypted, you can use **doFinal()** to pass in data without using **update()**. If all the data has been passed in by [update()](#update-4), you can pass in **null** in **data** of **doFinal()**.
+| Name | Type | Mandatory| Description |
+| -------- | --------------------- | ---- | ------------ |
+| data | [DataBlob](#datablob) | Yes | Data to pass in.|
+| callback | AsyncCallback\ | Yes | Callback invoked to return the result. |
-The output of **doFinal()** varies with the symmetric encryption/decryption mode in use.
+**Error codes**
-- Symmetric encryption in GCM and CCM mode: The result consists of the ciphertext and **authTag** (the last 16 bytes for GCM and the last 12 bytes for CCM). If **null** is passed in by **data** of **doFinal()**, the result of **doFinal()** is **authTag**. **authTag** must be [GcmParamsSpec](#gcmparamsspec) or [CcmParamsSpec](#ccmparamsspec) used for decryption. The ciphertext is the **data** passed in for decryption.
-- Symmetric encryption and decryption in other modes and symmetric decryption in GCM and CCM modes: The result is the complete plaintext/ciphertext.
+| ID| Error Message |
+| -------- | ---------------------- |
+| 401 | invalid parameters. |
+| 17620001 | memory error. |
+| 17620002 | runtime error. |
+| 17630001 | crypto operation error. |
-(2) Encrypts or decrypts the input data for RSA asymmetric encryption/decryption. This API uses an asynchronous callback to return the result. If a large amount of data needs to be encrypted/decrypted, call **doFinal()** multiple times and concatenate the result of each **doFinal()** to obtain the complete plaintext/ciphertext.
+### update
+
+update(data: DataBlob): Promise\
-> **NOTE**
-> - In symmetric encryption or decryption, calling **doFinal()** means the end of an encryption or decryption process, and the [Cipher](#cipher) instance state will be cleared. To start a new encryption or decryption operation, you must call [init()](#init-2) to pass in a complete parameter list for initialization. For example, if the same symmetric key is used for a **Cipher** instance to perform encryption and then decryption. After the encryption is complete, the **params** in **init** for decryption must be set instead of being **null**.
-> - If a decryption operation fails, check whether the data to be encrypted and decrypted matches the parameters in **[init](#init-2)**. For the GCM mode, check whether the **authTag** obtained after encryption is obtained from the **GcmParamsSpec** for decryption.
-> - The result of **doFinal()** may be **null**. To avoid exceptions, determine whether the result is **null** before using the **.data** field to access the **doFinal()** result.
-> - For details about the sample code for calling **doFinal()** multiple times during RSA asymmetric encryption and decryption, see [Encrypting and Decrypting Data](../../security/cryptoFramework-guidelines.md#encrypting-and-decrypting-data).
+Updates the data to be signed. This API uses a promise to return the result. This API can be called only after the [Sign](#sign) instance is initialized by using [init()](#init-3).
+
+> **NOTE**
+>
+> **update()** may be called multiple times or may not be called (call [sign](#sign-2) after [init](#init-3)), depending on the size of the data.
+> The algorithm library does not set a limit on the amount of data to be updated (once or accumulatively). If a large amount of data needs to be signed, you are advised to use **update()** multiple times to pass in data. This can prevent too much memory from being requested at a time.
+> For details about the sample code for calling **update()** multiple times, see [Signing and Signature verification](../../security/cryptoFramework-guidelines.md#signing-and-signature-verification).
**System capability**: SystemCapability.Security.CryptoFramework
**Parameters**
-| Name | Type | Mandatory| Description |
-| -------- | ------------------------------------- | ---- | ------------------------------------------------------------ |
-| data | [DataBlob](#datablob) | Yes | Data to encrypt or decrypt. It can be **null** in symmetric encryption or decryption, but cannot be {data:Uint8Array(null)}. |
-| callback | AsyncCallback\<[DataBlob](#datablob)> | Yes | Callback invoked to return the result. If the data is successfully encrypted or decrypted, **err** is **undefined**, and **data** is the **DataBlob** (encryption or decryption result of the remaining data). Otherwise, **err** is an error object.|
+| Name| Type | Mandatory| Description |
+| ------ | -------- | ---- | ---------- |
+| data | [DataBlob](#datablob) | Yes | Data to pass in.|
+
+**Return value**
+
+| Type | Description |
+| -------------- | ------------- |
+| Promise\ | Promise that returns no value.|
**Error codes**
-| ID| Error Message |
-| -------- | ----------------------- |
-| 17620001 | memory error. |
+| ID| Error Message |
+| -------- | ---------------------- |
+| 401 | invalid parameters. |
+| 17620001 | memory error. |
| 17620002 | runtime error. |
| 17630001 | crypto operation error. |
-**Example**
+### sign
-```js
-import cryptoFramework from '@ohos.security.cryptoFramework';
+sign(data: DataBlob, callback: AsyncCallback\): void
-let cipher; // The process of creating a Cipher instance is omitted here.
-let data; // The process of preparing the data to encrypt or decrypt is omitted here.
-// The init() and update() processes are omitted here.
-cipher.doFinal(data, (err, output) => {
- if (err) {
- console.error(`Failed to finalize cipher, ${err.code}, ${err.message}`);
- } else {
- console.info(`Finalize cipher success`);
- if (output != null) {
- // Concatenate output.data to obtain the complete plaintext/ciphertext (and authTag).
- }
- }
-})
-```
+Signs the data. This API uses an asynchronous callback to return the result.
-### doFinal
+**System capability**: SystemCapability.Security.CryptoFramework
-doFinal(data : DataBlob) : Promise\
+**Parameters**
-(1) Encrypts or decrypts the remaining data (generated by the block ciper mode) and the data passed in by **doFinal()** to finalize the symmetric encryption or decryption. This API uses a promise to return the encrypted or decrypted data. If a small amount of data needs to be encrypted or decrypted, you can use **doFinal()** to pass in data without using **update()**. If all the data has been passed in by [update()](#update-4), you can pass in **null** in **data** of **doFinal()**.
+| Name | Type | Mandatory| Description |
+| -------- | -------------------- | ---- | ---------- |
+| data | [DataBlob](#datablob) | Yes | Data to pass in.|
+| callback | AsyncCallback\<[DataBlob](#datablob) > | Yes | Callback invoked to return the result. |
-The output of **doFinal()** varies with the symmetric encryption/decryption mode in use.
+**Error codes**
-- Symmetric encryption in GCM and CCM mode: The result consists of the ciphertext and **authTag** (the last 16 bytes for GCM and the last 12 bytes for CCM). If **null** is passed in by **data** of **doFinal()**, the result of **doFinal()** is **authTag**. **authTag** must be [GcmParamsSpec](#gcmparamsspec) or [CcmParamsSpec](#ccmparamsspec) used for decryption. The ciphertext is the **data** passed in for decryption.
-- Symmetric encryption and decryption in other modes and symmetric decryption in GCM and CCM modes: The result is the complete plaintext/ciphertext.
+| ID| Error Message |
+| -------- | ---------------------- |
+| 401 | invalid parameters. |
+| 17620001 | memory error. |
+| 17620002 | runtime error. |
+| 17630001 | crypto operation error. |
-(2) Encrypts or decrypts the input data for RSA asymmetric encryption/decryption. This API uses a promise to return the result. If a large amount of data needs to be encrypted/decrypted, call **doFinal()** multiple times and concatenate the result of each **doFinal()** to obtain the complete plaintext/ciphertext.
+### sign
-> **NOTE**
-> - In symmetric encryption or decryption, calling **doFinal()** means the end of an encryption or decryption process, and the [Cipher](#cipher) instance state will be cleared. To start a new encryption or decryption operation, you must call [init()](#init-2) to pass in a complete parameter list for initialization. For example, if the same symmetric key is used for a **Cipher** instance to perform encryption and then decryption. After the encryption is complete, the **params** in **init** for decryption must be set instead of being **null**.
-> - If a decryption fails, check whether the data to be encrypted and decrypted matches the parameters in **[init](#init-2)**. For the GCM mode, check whether the **authTag** obtained after encryption is obtained from the **GcmParamsSpec** for decryption.
-> - The result of **doFinal()** may be **null**. To avoid exceptions, determine whether the result is **null** before using the **.data** field to access the **doFinal()** result.
-> - For details about the sample code for calling **doFinal()** multiple times during RSA asymmetric encryption and decryption, see [Encrypting and Decrypting Data](../../security/cryptoFramework-guidelines.md#encrypting-and-decrypting-data).
+sign(data: DataBlob): Promise\
+
+Signs the data. This API uses a promise to return the result.
**System capability**: SystemCapability.Security.CryptoFramework
**Parameters**
-| Name| Type | Mandatory| Description |
-| ---- | --------------------- | ---- | -------------------- |
-| data | [DataBlob](#datablob) | Yes | Data to encrypt or decrypt. It can be **null**, but cannot be {data:Uint8Array(null)}.|
+| Name| Type | Mandatory| Description |
+| ------ | -------- | ---- | ---------- |
+| data | [DataBlob](#datablob) | Yes | Data to pass in.|
**Return value**
-| Type | Description |
-| ------------------------------- | ------------------------------------------------ |
-| Promise\<[DataBlob](#datablob)> | Promise used to return the **DataBlob**, which is the encryption or decryption result of the remaining data.|
+| Type | Description |
+| -------------- | ------------- |
+| Promise\ | Promise that returns no value.|
**Error codes**
-| ID| Error Message |
-| -------- | -------------------------------------------- |
-| 17620001 | memory error. |
-| 17620002 | runtime error. |
-| 17630001 | crypto operation error. |
+| ID| Error Message |
+| -------- | ---------------------- |
+| 401 | invalid parameters. |
+| 17620001 | memory error. |
+| 17620002 | runtime error. |
+| 17630001 | crypto operation error. |
-**Example**
+**Callback example**:
```js
-import cryptoFramework from '@ohos.security.cryptoFramework';
-
-let cipher; // The process of creating a Cipher instance is omitted here.
-let data; // The process of preparing the data to encrypt or decrypt is omitted here.
-// The init() and update() processes are omitted here.
-cipher.doFinal(data)
-.then(output => {
- console.info(`Finalize cipher success`);
- if (output != null) {
- // Concatenate output.data to obtain the complete plaintext/ciphertext (and authTag).
- }
-}, error => {
- console.error(`Failed to finalize cipher, ${error.code}, ${error.message}`);
-})
-```
-
-**RSA encryption example (callback)**
-
-```javascript
import cryptoFramework from "@ohos.security.cryptoFramework"
function stringToUint8Array(str) {
- let arr = [];
- for (let i = 0, j = str.length; i < j; ++i) {
+ var arr = [];
+ for (var i = 0, j = str.length; i < j; ++i) {
arr.push(str.charCodeAt(i));
}
- return new Uint8Array(arr);
+ var tmpArray = new Uint8Array(arr);
+ return tmpArray;
}
-let rsaGenerator = cryptoFramework.createAsyKeyGenerator("RSA1024|PRIMES_2");
-let cipher = cryptoFramework.createCipher("RSA1024|PKCS1");
-rsaGenerator.generateKeyPair(function (err, keyPair) {
- let pubKey = keyPair.pubKey;
- cipher.init(cryptoFramework.CryptoMode.ENCRYPT_MODE, pubKey, null, function (err, data) {
- let plainText = "this is cipher text";
- let input = {data : stringToUint8Array(plainText) };
- cipher.doFinal(input, function (err, data) {
- AlertDialog.show({ message : "EncryptOutPut is " + data.data} );
+let globalKeyPair;
+let SignMessageBlob;
+let plan1 = "This is Sign test plan1"; // The first segment of the data.
+let plan2 = "This is Sign test plan2"; // The second segment of the data.
+let input1 = { data: stringToUint8Array(plan1) };
+let input2 = { data: stringToUint8Array(plan2) };
+
+function signMessageCallback() {
+ let rsaGenerator = cryptoFramework.createAsyKeyGenerator("RSA1024|PRIMES_2");
+ let signer = cryptoFramework.createSign("RSA1024|PKCS1|SHA256");
+ rsaGenerator.generateKeyPair(function (err, keyPair) {
+ globalKeyPair = keyPair;
+ let priKey = globalKeyPair.priKey;
+ signer.init(priKey, function (err, data) {
+ signer.update(input1, function (err, data) { // Add the first segment of the data.
+ signer.sign(input2, function (err, data) { // Add the second segment of the data, and sign input1 and input2.
+ SignMessageBlob = data;
+ AlertDialog.show({message: "res" + SignMessageBlob.data});
+ });
+ });
});
});
-});
+}
```
-**RSA encryption example (promise)**
+**Promise example**:
-```javascript
+```js
import cryptoFramework from "@ohos.security.cryptoFramework"
function stringToUint8Array(str) {
- let arr = [];
- for (let i = 0, j = str.length; i < j; ++i) {
+ var arr = [];
+ for (var i = 0, j = str.length; i < j; ++i) {
arr.push(str.charCodeAt(i));
}
- return new Uint8Array(arr);
+ var tmpArray = new Uint8Array(arr);
+ return tmpArray;
}
-let rsaGenerator = cryptoFramework.createAsyKeyGenerator("RSA1024|PRIMES_2");
-let cipher = cryptoFramework.createCipher("RSA1024|PKCS1");
-let keyGenPromise = rsaGenerator.generateKeyPair();
-keyGenPromise.then(rsaKeyPair => {
- let pubKey = rsaKeyPair.pubKey;
- return cipher.init(cryptoFramework.CryptoMode.ENCRYPT_MODE, pubKey, null); // Pass in the private key and DECRYPT_MODE to initialize the decryption mode.
-}).then(() => {
- let plainText = "this is cipher text";
- let input = { data : stringToUint8Array(plainText) };
- return cipher.doFinal(input);
-}).then(dataBlob => {
- console.info("EncryptOutPut is " + dataBlob.data);
-});
-```
-
-> **NOTE**
-> For more encryption and decryption examples, see [Encrypting and Decrypting Data](../../security/cryptoFramework-guidelines.md#encrypting-and-decrypting data).
+let globalKeyPair;
+let SignMessageBlob;
+let plan1 = "This is Sign test plan1"; // The first segment of the data.
+let plan2 = "This is Sign test plan2"; // The second segment of the data.
+let input1 = { data: stringToUint8Array(plan1) };
+let input2 = { data: stringToUint8Array(plan2) };
-## cryptoFramework.createSign
+function signMessagePromise() {
+ let rsaGenerator = cryptoFramework.createAsyKeyGenerator("RSA1024|PRIMES_2");
+ let signer = cryptoFramework.createSign("RSA1024|PKCS1|SHA256");
+ let keyGenPromise = rsaGenerator.generateKeyPair();
+ keyGenPromise.then( keyPair => {
+ globalKeyPair = keyPair;
+ let priKey = globalKeyPair.priKey;
+ return signer.init(priKey);
+ }).then(() => {
+ return signer.update(input1); // Add the first segment of the data.
+ }).then(() => {
+ return signer.sign(input2); // Add the second segment of the data, and sign input1 and input2.
+ }).then(dataBlob => {
+ SignMessageBlob = dataBlob;
+ console.info("sign output is " + SignMessageBlob.data);
+ AlertDialog.show({message: "output" + SignMessageBlob.data});
+ });
+}
+```
-createSign(algName : string) : Sign
+### setSignSpec10+
-Creates a **Sign** instance.
+setSignSpec(itemType: SignSpecItem, itemValue: number): void
-For details about the supported specifications, see [Signing and Signature Verification Specifications](../../security/cryptoFramework-overview.md#signing-and-signature-verification-specifications).
+Sets signing specifications. You can use this API to set signing parameters that cannot be set by [createSign](#cryptoframeworkcreatesign). Currently, only the RSA is supported.
**System capability**: SystemCapability.Security.CryptoFramework
**Parameters**
-| Name | Type | Mandatory| Description |
-| ------- | ------ | ---- | ------------------------------------------------------------ |
-| algName | string | Yes | Signing algorithm to use, which can be RSA or ECC. If RSA PKCS #1 is used, the digest must be set. If RSA PSS is used, the digest and mask digest must be set.|
+| Name | Type | Mandatory| Description |
+| -------- | -------------------- | ---- | ---------- |
+| itemType | [SignSpecItem](#signspecitem10) | Yes | Signing parameter to set.|
+| itemValue | number | Yes | Value of the signing parameter to set.|
-**Return value**
+**Error codes**
-| Type| Description |
-| ---- | -------------------------------- |
-| Sign | **Sign** instance created.|
+| ID| Error Message |
+| -------- | ---------------------- |
+| 401 | invalid parameters. |
+| 801 | this operation is not supported. |
+| 17620001 | memory error. |
+| 17630001 | crypto operation error. |
**Example**
-```javascript
+```js
import cryptoFramework from "@ohos.security.cryptoFramework"
-let signer1 = cryptoFramework.createSign("RSA1024|PKCS1|SHA256");
-
-let singer2 = cryptoFramework.createSign("RSA1024|PSS|SHA256|MGF1_SHA256")
+let signer; // The process of generating the Sign instance is omitted here.
+let setN = 20;
+signer.setSignSpec(cryptoFramework.SignSpecItem.PSS_SALT_LEN_NUM, setN);
```
-## Sign
-
-Provides APIs for signing. Before using any API of the **Sign** class, you must create a **Sign** instance by using **createSign()**. The **Sign** class does not support repeated initialization. When a new key is used for signing, you must create a new **Sign** object and call **init()** for initialization.
-
-The signing mode is determined in **createSign()**, and the key is set by **init()**.
-
-If the data to be signed is short, you can use **sign()** to pass in the data for signing after **init()**.
-
-If the data to be signed is long, you can use **update()** to pass in the data by segment, and then use **sign()** to sign the entire data.
+### getSignSpec10+
-If **update()** is used to pass in data by segment, **data** of **sign()** can be **null**.
+getSignSpec(itemType: SignSpecItem): string | number
-### Attributes
+Obtains signing specifications. Currently, only the RSA is supported.
**System capability**: SystemCapability.Security.CryptoFramework
-| Name | Type | Readable| Writable| Description |
-| ------- | ------ | ---- | ---- | ---------------------------- |
-| algName | string | Yes | No | Algorithm to use.|
-
-### init
-
-init(priKey : PriKey, callback : AsyncCallback\) : void
-
-Initializes a **Sign** instance using a private key. This API uses an asynchronous callback to return the result. The **Sign** class does not support repeated calling of **init()**.
+**Parameters**
-**System capability**: SystemCapability.Security.CryptoFramework
+| Name| Type | Mandatory| Description |
+| ------ | -------- | ---- | ---------- |
+| itemType | [SignSpecItem](#signspecitem) | Yes | Signing parameter to obtain.|
-**Parameters**
+**Return value**
-| Name | Type | Mandatory| Description |
-| -------- | -------------------- | ---- | ---------------- |
-| priKey | [PriKey](#prikey) | Yes | Private key used for the initialization.|
-| callback | AsyncCallback\ | Yes | Callback invoked to return the result. |
+| Type | Description |
+| -------------- | ----------- |
+| string\|number | Returns the value of the signing parameter obtained.|
**Error codes**
| ID| Error Message |
| -------- | ---------------------- |
+| 401 | invalid parameters. |
+| 801 | this operation is not supported. |
| 17620001 | memory error. |
-| 17620002 | runtime error. |
| 17630001 | crypto operation error. |
-### init
+**Example**
+
+```js
+import cryptoFramework from "@ohos.security.cryptoFramework"
+
+let signer; // The process of generating the Sign instance is omitted here.
+let saltLen = signer.getSignSpec(cryptoFramework.SignSpecItem.PSS_SALT_LEN_NUM);
+```
+
+## cryptoFramework.createVerify
-init(priKey : PriKey) : Promise\
+createVerify(algName: string): Verify
-Initializes a **Sign** instance using a private key. This API uses a promise to return the result. The **Sign** class does not support repeated calling of **init()**.
+Creates a **Verify** instance. For details about the supported specifications, see [Signing and Signature Verification Specifications](../../security/cryptoFramework-overview.md#signing-and-signature-verification-specifications).
**System capability**: SystemCapability.Security.CryptoFramework
**Parameters**
-| Name| Type| Mandatory| Description |
-| ------ | ---- | ---- | ---------------- |
-| priKey | [PriKey](#prikey) | Yes | Private key used for the initialization.|
+| Name | Type | Mandatory| Description |
+| ------- | ------ | ---- | ------------------------------------------------------------ |
+| algName | string | Yes | Signing algorithm, which can be RSA, ECC, or DSA. If the RSA PKCS1 mode is used, you need to set the digest. If the RSA PSS mode is used, you need to set the digest and mask digest.|
**Return value**
-| Type | Description |
-| -------------- | ----------- |
-| Promise\ | Promise used to return the result.|
+| Type | Description |
+| ------ | ------------------------------------ |
+| Verify | Returns the **Verify** instance created.|
**Error codes**
| ID| Error Message |
| -------- | ---------------------- |
+| 401 | invalid parameters. |
+| 801 | this operation is not supported. |
| 17620001 | memory error. |
-| 17620002 | runtime error. |
-| 17630001 | crypto operation error. |
-### update
+**Example**
+
+```js
+import cryptoFramework from "@ohos.security.cryptoFramework"
+
+let verifyer1 = cryptoFramework.createVerify("RSA1024|PKCS1|SHA256");
+
+let verifyer2 = cryptoFramework.createVerify("RSA1024|PSS|SHA256|MGF1_SHA256")
+```
+
+## Verify
+
+Provides APIs for signature verification. Before using any API of the **Verify** class, you must create a **Verify** instance by using **createVerify(algName: string): Verify**. Invoke **init()**, **update()**, and **sign()** in this class in sequence to complete the signature verification. For details about the sample code, see [Signing and Signature Verification](../../security/cryptoFramework-guidelines.md#signing-and-signature-verification).
+
+The **Verify** class does not support repeated initialization. When a new key is used for signature verification, you must create a new **Verify** object and call **init()** for initialization.
+
+The signature verification mode is determined in **createVerify()**, and key is set by **init()**.
+
+If the signed message is short, you can call **verify()** to pass in the signed message and signature (**signatureData**) for signature verification after **init()**. That is, you do not need to use **update()**.
+
+If the signed message is too long, you can call **update()** multiple times to pass in the signed message by segment, and then call **verify()** to verify the full text of the message. The **data** parameter of **verify()** can be null. The service can call **update()** multiple times in the loop. When the loop ends, the service calls **verify()** to pass in the signature (**signatureData**) for signature verification.
+
+### Attributes
+
+**System capability**: SystemCapability.Security.CryptoFramework
+
+| Name | Type | Readable| Writable| Description |
+| ------- | ------ | ---- | ---- | ---------------------------- |
+| algName | string | Yes | No | Algorithm to be used for signature verification.|
-update(data : DataBlob, callback : AsyncCallback\) : void
+### init
-Updates the data to be signed. This API uses an asynchronous callback to return the result.
+init(pubKey: PubKey, callback: AsyncCallback\): void
-> **NOTE**
-> For details about the sample code for calling **update()** multiple times, see [Generating and Verifying a Signature](../../security/cryptoFramework-guidelines.md#generating-and-verifying-a-signature).
+Initializes the **Verify** instance using a public key. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Security.CryptoFramework
**Parameters**
-| Name | Type | Mandatory| Description |
-| -------- | -------------------- | ---- | ---------- |
-| data | [DataBlob](#datablob)| Yes | Data to pass in.|
-| callback | AsyncCallback\ | Yes | Callback invoked to return the result. |
+| Name | Type | Mandatory| Description |
+| -------- | -------------------- | ---- | ------------------------------ |
+| pubKey | [PubKey](#pubkey) | Yes | Public key used to initialize the **Verify** instance.|
+| callback | AsyncCallback\ | Yes | Callback invoked to return the result. |
**Error codes**
| ID| Error Message |
| -------- | ---------------------- |
+| 401 | invalid parameters. |
| 17620001 | memory error. |
| 17620002 | runtime error. |
| 17630001 | crypto operation error. |
-### update
-
-update(data : DataBlob) : Promise\;
+### init
-Updates the data to be signed. This API uses a promise to return the result.
+init(pubKey: PubKey): Promise\
-> **NOTE**
-> For details about the sample code for calling **update()** multiple times, see [Generating and Verifying a Signature](../../security/cryptoFramework-guidelines.md#generating-and-verifying-a-signature).
+Initializes the **Verify** instance using a public key. This API uses a promise to return the result.
**System capability**: SystemCapability.Security.CryptoFramework
**Parameters**
-| Name| Type | Mandatory| Description |
-| ------ | -------- | ---- | ---------- |
-| data | [DataBlob](#datablob) | Yes | Data to pass in.|
+| Name| Type| Mandatory| Description |
+| ------ | ---- | ---- | ---------------------------- |
+| pubKey | [PubKey](#pubkey) | Yes | Public key used to initialize the **Verify** instance.|
**Return value**
-| Type | Description |
-| -------------- | ----------- |
-| Promise\ | Promise used to return the result.|
+| Type | Description |
+| -------------- | ------------- |
+| Promise\ | Promise that returns no value.|
**Error codes**
| ID| Error Message |
| -------- | ---------------------- |
+| 401 | invalid parameters. |
| 17620001 | memory error. |
| 17620002 | runtime error. |
| 17630001 | crypto operation error. |
-### sign
+### update
-sign(data : DataBlob, callback : AsyncCallback\) : void
+update(data: DataBlob, callback: AsyncCallback\): void
-Signs the data. This API uses an asynchronous callback to return the result.
+Updates the data for signature verification. This API uses an asynchronous callback to return the result. This API can be called only after the [Verify](#verify) instance is initialized using [init()](#init-4).
+
+> **NOTE**
+>
+> **update()** may be called multiple times or may not be called (call [verify](#verify-1) after [init](#init-4)), depending on the size of the data.
+> The algorithm library does not set a limit on the amount of data to be updated (once or accumulatively). If a large amount of data is involved in signature verification, you are advised to use **update()** multiple times to pass in data. This can prevent too much memory from being requested at a time.
+> For details about the sample code for calling **update()** multiple times, see [Signing and Signature verification](../../security/cryptoFramework-guidelines.md#signing-and-signature-verification).
**System capability**: SystemCapability.Security.CryptoFramework
**Parameters**
-| Name | Type | Mandatory| Description |
-| -------- | -------------------- | ---- | ---------- |
-| data | [DataBlob](#datablob) | Yes | Data to pass in.|
-| callback | AsyncCallback\<[DataBlob](#datablob) > | Yes | Callback invoked to return the result. |
+| Name | Type | Mandatory| Description |
+| -------- | --------------------- | ---- | ------------ |
+| data | [DataBlob](#datablob) | Yes | Data to pass in.|
+| callback | AsyncCallback\ | Yes | Callback invoked to return the result. |
**Error codes**
| ID| Error Message |
| -------- | ---------------------- |
+| 401 | invalid parameters. |
| 17620001 | memory error. |
| 17620002 | runtime error. |
| 17630001 | crypto operation error. |
-### sign
+### update
-sign(data : DataBlob) : Promise\
+update(data: DataBlob): Promise\
-Signs the data. This API uses a promise to return the result.
+Updates the data for signature verification. This API uses a promise to return the result. This API can be called only after the [Verify](#verify) instance is initialized using [init()](#init-5).
+
+> **NOTE**
+>
+> **update()** may be called multiple times or may not be called (call [verify](#verify-2) after [init](#init-5)), depending on the size of the data.
+> The algorithm library does not set a limit on the amount of data to be updated (once or accumulatively). If a large amount of data is involved in signature verification, you are advised to use **update()** multiple times to pass in data. This can prevent too much memory from being requested at a time.
+> For details about the sample code for calling **update()** multiple times, see [Signing and Signature verification](../../security/cryptoFramework-guidelines.md#signing-and-signature-verification).
**System capability**: SystemCapability.Security.CryptoFramework
@@ -2263,237 +2359,833 @@ Signs the data. This API uses a promise to return the result.
**Return value**
-| Type | Description |
-| -------------- | ----------- |
-| Promise\ | Promise used to return the result.|
+| Type | Description |
+| -------------- | ------------- |
+| Promise\ | Promise that returns no value.|
**Error codes**
| ID| Error Message |
| -------- | ---------------------- |
+| 401 | invalid parameters. |
| 17620001 | memory error. |
| 17620002 | runtime error. |
| 17630001 | crypto operation error. |
-**Callback example**:
-
-```javascript
-import cryptoFramework from "@ohos.security.cryptoFramework"
-
-function stringToUint8Array(str) {
- var arr = [];
- for (var i = 0, j = str.length; i < j; ++i) {
- arr.push(str.charCodeAt(i));
- }
- var tmpArray = new Uint8Array(arr);
- return tmpArray;
-}
+### verify
-let globalKeyPair;
-let SignMessageBlob;
-let plan1 = "This is Sign test plan1"; // The first segment of the data.
-let plan2 = "This is Sign test plan2"; // The second segment of the data.
-let input1 = { data : stringToUint8Array(plan1) };
-let input2 = { data : stringToUint8Array(plan2) };
+verify(data: DataBlob, signatureData: DataBlob, callback: AsyncCallback\): void
-function signMessageCallback() {
- let rsaGenerator = cryptoFramework.createAsyKeyGenerator("RSA1024|PRIMES_2");
- let signer = cryptoFramework.createSign("RSA1024|PKCS1|SHA256");
- rsaGenerator.generateKeyPair(function (err, keyPair) {
- globalKeyPair = keyPair;
- let priKey = globalKeyPair.priKey;
- signer.init(priKey, function (err, data) {
- signer.update(input1, function (err, data) { // Add the first segment of the data.
- signer.sign(input2, function (err, data) { // Add the second segment of the data, and sign input1 and input2.
- SignMessageBlob = data;
- AlertDialog.show({message : "res" + SignMessageBlob.data});
- });
- });
- });
- });
-}
-```
+Verifies the signature. This API uses an asynchronous callback to return the result.
-**Promise example**:
+**System capability**: SystemCapability.Security.CryptoFramework
-```javascript
-import cryptoFramework from "@ohos.security.cryptoFramework"
+**Parameters**
-function stringToUint8Array(str) {
- var arr = [];
- for (var i = 0, j = str.length; i < j; ++i) {
- arr.push(str.charCodeAt(i));
- }
- var tmpArray = new Uint8Array(arr);
- return tmpArray;
-}
+| Name | Type | Mandatory| Description |
+| ------------- | -------------------- | ---- | ---------- |
+| data | [DataBlob](#datablob) | Yes | Data to pass in.|
+| signatureData | [DataBlob](#datablob) | Yes | Signature data. |
+| callback | AsyncCallback\ | Yes | Callback invoked to return the result. |
-let globalKeyPair;
-let SignMessageBlob;
-let plan1 = "This is Sign test plan1"; // The first segment of the data.
-let plan2 = "This is Sign test plan2"; // The second segment of the data.
-let input1 = { data : stringToUint8Array(plan1) };
-let input2 = { data : stringToUint8Array(plan2) };
+**Error codes**
-function signMessagePromise() {
- let rsaGenerator = cryptoFramework.createAsyKeyGenerator("RSA1024|PRIMES_2");
- let signer = cryptoFramework.createSign("RSA1024|PKCS1|SHA256");
- let keyGenPromise = rsaGenerator.generateKeyPair();
- keyGenPromise.then( keyPair => {
- globalKeyPair = keyPair;
- let priKey = globalKeyPair.priKey;
- return signer.init(priKey);
- }).then(() => {
- return signer.update(input1); // Add the first segment of the data.
- }).then(() => {
- return signer.sign(input2); // Add the second segment of the data, and sign input1 and input2.
- }).then(dataBlob => {
- SignMessageBlob = dataBlob;
- console.info("sign output is " + SignMessageBlob.data);
- AlertDialog.show({message : "output" + SignMessageBlob.data});
- });
-}
-```
+| ID| Error Message |
+| -------- | ---------------------- |
+| 401 | invalid parameters. |
+| 17620001 | memory error. |
+| 17620002 | runtime error. |
+| 17630001 | crypto operation error. |
-## cryptoFramework.createVerify
+### verify
-createVerify(algName : string) : Verify
+verify(data: DataBlob, signatureData: DataBlob): Promise\
-Creates a **Verify** instance. For details about the supported specifications, see [Signing and Signature Verification Specifications](../../security/cryptoFramework-overview.md#signing-and-signature-verification-specifications).
+Verifies the signature. This API uses a promise to return the result.
**System capability**: SystemCapability.Security.CryptoFramework
**Parameters**
-| Name | Type | Mandatory| Description |
-| ------- | ------ | ---- | ------------------------------------------------------------ |
-| algName | string | Yes | Signing algorithm to use, which can be RSA or ECC. If RSA PKCS #1 is used, the digest must be set. If RSA PSS is used, the digest and mask digest must be set.|
+| Name | Type | Mandatory| Description |
+| ------------- | -------- | ---- | ---------- |
+| data | [DataBlob](#datablob) | Yes | Data to pass in.|
+| signatureData | [DataBlob](#datablob) | Yes | Signature data. |
**Return value**
-| Type | Description |
-| ------ | ---------------------------------- |
-| Verify | **Verify** instance created.|
-
-**Example**
-
-```javascript
-import cryptoFramework from "@ohos.security.cryptoFramework"
-
-let verifyer1 = cryptoFramework.createVerify("RSA1024|PKCS1|SHA256");
-
-let verifyer2 = cryptoFramework.createVerify("RSA1024|PSS|SHA256|MGF1_SHA256")
-```
-
-## Verify
-
-Provides APIs for signature verification. Before using any API of the **Verify** class, you must create a **Verify** instance by using **createVerify()**.
-
-The **Verify** class does not support repeated initialization. When a new key is used for signature verification, you must create a new **Verify** object and call **init()** for initialization.
+| Type | Description |
+| ----------------- | ------------------------------ |
+| Promise\ | Promise used to return the result.|
-The signature verification mode is determined in **createVerify()**, and key is set by **init()**.
+**Error codes**
-If the signature data to be verified is short, you can call **verify()** to pass in the signature data and original data after **init()**.
+| ID| Error Message |
+| -------- | ---------------------- |
+| 401 | invalid parameters. |
+| 17620001 | memory error. |
+| 17620002 | runtime error. |
+| 17630001 | crypto operation error. |
-If the signature data to be verified is long, you can use **update()** to pass in the data by segment, and then use **verify()** to verify the entire data.
+**Callback example**:
-If **update()** is used to pass in data by segment, **data** of **verify()** can be **null**.
+```js
+import cryptoFramework from "@ohos.security.cryptoFramework"
-### Attributes
+let globalKeyPair; // globalKeyPair is an asymmetric key object generated by the asymmetric key generator. The generation process is omitted here.
+let input1 = null;
+let input2 = null;
+let signMessageBlob = null; // Signed data, which is omitted here.
+let verifyer = cryptoFramework.createVerify("RSA1024|PKCS1|SHA25");
+verifyer.init(globalKeyPair.pubKey, function (err, data) {
+ verifyer.update(input1, function(err, data) {
+ verifyer.verify(input2, signMessageBlob, function(err, data) {
+ console.info("verify result is " + data);
+ })
+ });
+})
+```
-**System capability**: SystemCapability.Security.CryptoFramework
+**Promise example**:
-| Name | Type | Readable| Writable| Description |
-| ------- | ------ | ---- | ---- | ---------------------------- |
-| algName | string | Yes | No | Algorithm to be used for signature verification.|
+```js
+import cryptoFramework from "@ohos.security.cryptoFramework"
+let globalKeyPair; // globalKeyPair is an asymmetric key object generated by the asymmetric key generator. The generation process is omitted here.
+let verifyer = cryptoFramework.createVerify("RSA1024|PKCS1|SHA256");
+let verifyInitPromise = verifyer.init(globalKeyPair.pubKey);
+let input1 = null;
+let input2 = null;
+let signMessageBlob = null; // Signed data, which is omitted here.
+verifyInitPromise.then(() => {
+ return verifyer.update(input1);
+}).then(() => {
+ return verifyer.verify(input2, signMessageBlob);
+}).then(res => {
+ console.log("Verify result is " + res);
+});
+```
+### setVerifySpec10+
-### init
+setVerifySpec(itemType: SignSpecItem, itemValue: number): void
-init(pubKey : PubKey, callback : AsyncCallback\) : void
+Set signature verification specifications. You can use this API to set signature verification parameters that cannot be set by [createVerify](#cryptoframeworkcreateverify). Currently, only the RSA is supported.
-Initializes the **Verify** instance using a public key. This API uses an asynchronous callback to return the result.
+The parameters for signature verification must be the same as those for signing.
**System capability**: SystemCapability.Security.CryptoFramework
**Parameters**
-| Name | Type | Mandatory| Description |
-| -------- | -------------------- | ---- | ---------------------------- |
-| pubKey | [PubKey](#pubkey) | Yes | Public key used for the initialization.|
-| callback | AsyncCallback\ | Yes | Callback invoked to return the result. |
+| Name | Type | Mandatory| Description |
+| -------- | -------------------- | ---- | ---------- |
+| itemType | [SignSpecItem](#signspecitem10) | Yes | Signature verification parameter to set.|
+| itemValue | number | Yes | Value of the signature verification parameter to set.|
**Error codes**
| ID| Error Message |
| -------- | ---------------------- |
+| 401 | invalid parameters. |
+| 801 | this operation is not supported. |
| 17620001 | memory error. |
-| 17620002 | runtime error. |
| 17630001 | crypto operation error. |
-### init
+**Example**
+
+```js
+import cryptoFramework from "@ohos.security.cryptoFramework"
-init(pubKey : PubKey) : Promise\
+let verifyer; //The process of generating the Verify instance is omitted here.
+let setN = 20;
+verifyer.setVerifySpec(cryptoFramework.SignSpecItem.PSS_SALT_LEN_NUM, setN);
+```
-Initializes the **Verify** instance using a public key. This API uses a promise to return the result.
+### getVerifySpec10+
+
+getVerifySpec(itemType: SignSpecItem): string | number
+
+Obtains signature verification specifications. Currently, only the RSA is supported.
+
+The parameters for signature verification must be the same as those for signing.
**System capability**: SystemCapability.Security.CryptoFramework
**Parameters**
-| Name| Type| Mandatory| Description |
-| ------ | ---- | ---- | ---------------------------- |
-| pubKey | [PubKey](#pubkey) | Yes | Public key used for the initialization.|
+| Name| Type | Mandatory| Description |
+| ------ | -------- | ---- | ---------- |
+| itemType | [SignSpecItem](#signspecitem10) | Yes | Signature verification parameter to obtain.|
**Return value**
| Type | Description |
| -------------- | ----------- |
-| Promise\ | Promise used to return the result.|
+| string\|number | Returns the value of the parameter obtained.|
**Error codes**
| ID| Error Message |
| -------- | ---------------------- |
+| 401 | invalid parameters. |
+| 801 | this operation is not supported. |
| 17620001 | memory error. |
-| 17620002 | runtime error. |
| 17630001 | crypto operation error. |
-### update
+**Example**
+
+```js
+import cryptoFramework from "@ohos.security.cryptoFramework"
-update(data : DataBlob, callback : AsyncCallback\) : void
+let verifyer; //The process of generating the Verify instance is omitted here.
+let saltLen = verifyer.getSignSpec(cryptoFramework.SignSpecItem.PSS_SALT_LEN_NUM);
+```
-Updates the data for signature verification. This API uses an asynchronous callback to return the result.
+## cryptoFramework.createKeyAgreement
-> **NOTE**
-> For details about the sample code for calling **update()** multiple times, see [Generating and Verifying a Signature](../../security/cryptoFramework-guidelines.md#generating-and-verifying-a-signature).
+createKeyAgreement(algName: string): KeyAgreement
+
+Creates a **KeyAgreement** instance. For details about the supported specifications, see [Key Agreement Specifications](../../security/cryptoFramework-overview.md#key-agreement-specifications).
**System capability**: SystemCapability.Security.CryptoFramework
**Parameters**
-| Name | Type | Mandatory| Description |
-| -------- | -------------------- | ---- | ---------- |
-| data | [DataBlob](#datablob)| Yes | Data to pass in.|
-| callback | AsyncCallback\ | Yes | Callback invoked to return the result. |
+| Name | Type | Mandatory| Description |
+| ------- | ------ | ---- | --------------------------------- |
+| algName | string | Yes | Key agreement algorithm to use. Currently, only the ECC is supported.|
-**Error codes**
+**Return value**
+
+| Type | Description |
+| ------------ | ------------------------------------------ |
+| KeyAgreement | Returns the **KeyAgreement** instance created.|
+
+**Error codes**
+
+| ID| Error Message |
+| -------- | ---------------------- |
+| 401 | invalid parameters. |
+| 801 | this operation is not supported. |
+| 17620001 | memory error. |
+
+**Example**
+
+```js
+import cryptoFramework from "@ohos.security.cryptoFramework"
+
+let keyAgreement = cryptoFramework.createKeyAgreement("ECC256");
+
+```
+
+## KeyAgreement
+
+Provides APIs for key agreement operations. Before using any API of the **KeyAgreement** class, you must create a **KeyAgreement** instance by using **createKeyAgreement(algName: string): KeyAgreement**.
+
+### Attributes
+
+**System capability**: SystemCapability.Security.CryptoFramework
+
+| Name | Type | Readable| Writable| Description |
+| ------- | ------ | ---- | ---- | ---------------------------- |
+| algName | string | Yes | No | Algorithm used for key agreement.|
+
+### generateSecret
+
+generateSecret(priKey: PriKey, pubKey: PubKey, callback: AsyncCallback\): void
+
+Generates a shared secret. This API uses an asynchronous callback to return the result.
+
+**System capability**: SystemCapability.Security.CryptoFramework
+
+**Parameters**
+
+| Name | Type | Mandatory| Description |
+| -------- | ------------------------ | ---- | ---------------------- |
+| priKey | [PriKey](#prikey) | Yes | Private key used for key agreement.|
+| pubKey | [PubKey](#pubkey) | Yes | Public key used for key agreement.|
+| callback | AsyncCallback\<[DataBlob](#datablob)> | Yes | Callback invoked to return the shared secret.|
+
+**Error codes**
+
+| ID| Error Message |
+| -------- | ---------------------- |
+| 401 | invalid parameters. |
+| 17620001 | memory error. |
+| 17620002 | runtime error. |
+| 17630001 | crypto operation error. |
+
+### generateSecret
+
+generateSecret(priKey: PriKey, pubKey: PubKey): Promise\
+
+Generates a shared secret. This API uses a promise to return the result.
+
+**System capability**: SystemCapability.Security.CryptoFramework
+
+**Parameters**
+
+| Name| Type | Mandatory| Description |
+| ------ | ------ | ---- | ---------------------- |
+| priKey | [PriKey](#prikey) | Yes | Private key used for key agreement.|
+| pubKey | [PubKey](#pubkey) | Yes | Public key used for key agreement.|
+
+**Return value**
+
+| Type | Description |
+| ------------------ | -------- |
+| Promise\<[DataBlob](#datablob)> | Promise used to return the shared secret.|
+
+**Error codes**
+
+| ID| Error Message |
+| -------- | ---------------------- |
+| 401 | invalid parameters. |
+| 17620001 | memory error. |
+| 17620002 | runtime error. |
+| 17630001 | crypto operation error. |
+
+**Callback example**:
+
+```js
+import cryptoFramework from "@ohos.security.cryptoFramework"
+
+let globalKeyPair; // globalKeyPair is an asymmetric key object generated by the asymmetric key generator. The generation process is omitted here.
+let keyAgreement = cryptoFramework.createKeyAgreement("ECC256");
+keyAgreement.generateSecret(globalKeyPair.priKey, globalKeyPair.pubKey, function (err, secret) {
+ if (err) {
+ console.error("keyAgreement error.");
+ return;
+ }
+ console.info("keyAgreement output is " + secret.data);
+});
+```
+
+**Promise example**:
+
+```js
+import cryptoFramework from "@ohos.security.cryptoFramework"
+
+let globalKeyPair; // globalKeyPair is an asymmetric key object generated by the asymmetric key generator. The generation process is omitted here.
+let keyAgreement = cryptoFramework.createKeyAgreement("ECC256");
+let keyAgreementPromise = keyAgreement.generateSecret(globalKeyPair.priKey, globalKeyPair.pubKey);
+keyAgreementPromise.then((secret) => {
+ console.info("keyAgreement output is " + secret.data);
+}).catch((error) => {
+ console.error("keyAgreement error.");
+});
+```
+
+## cryptoFramework.createMd
+
+createMd(algName: string): Md
+
+Creates an **Md** instance for message digest operations. For details about the supported specifications, see [MD Algorithm Specifications](../../security/cryptoFramework-overview.md#md-algorithm-specifications).
+
+**System capability**: SystemCapability.Security.CryptoFramework
+
+**Parameters**
+
+| Name | Type | Mandatory| Description |
+| ------- | ------ | ---- | ------------------------------------------------------------ |
+| algName | string | Yes | Digest algorithm. For details about the supported algorithms, see [MD Algorithm Specifications](../../security/cryptoFramework-overview.md#md-algorithm-specifications).|
+
+**Return value**
+
+| Type| Description |
+| ---- | --------------------------------------- |
+| Md | Returns the [Md](#md) instance created.|
+
+**Error codes**
+
+| ID| Error Message |
+| -------- | ------------------ |
+| 401 | invalid parameters. |
+| 17620001 | memory error. |
+
+**Example**
+
+```js
+import cryptoFramework from "@ohos.security.cryptoFramework"
+
+var md;
+try {
+ // Set algName based on the algorithm supported.
+ md = cryptoFramework.createMd("SHA256");
+} catch (error) {
+ console.error("[Promise]: error code: " + error.code + ", message is: " + error.message);
+}
+```
+
+## Md
+
+Provides APIs for message digest operations. Before using any API of the **Md** class, you must create an **Md** instance by using [createMd](#cryptoframeworkcreatemd).
+
+### Attributes
+
+**System capability**: SystemCapability.Security.CryptoFramework
+
+| Name | Type | Readable| Writable| Description |
+| ------- | ------ | ---- | ---- | ---------------------- |
+| algName | string | Yes | No | Digest algorithm.|
+
+### update
+
+update(input: DataBlob, callback: AsyncCallback\): void
+
+Updates the message digest data. This API uses an asynchronous callback to return the result.
+
+> **NOTE**
+>
+> For details about the sample code for calling **update()** multiple times, see [Generating a Digest](../../security/cryptoFramework-guidelines.md#generating-a-digest).
+
+**System capability**: SystemCapability.Security.CryptoFramework
+
+**Parameters**
+
+| Name | Type | Mandatory| Description |
+| -------- | --------------------- | ---- | ------------ |
+| input | [DataBlob](#datablob) | Yes | Data to pass in.|
+| callback | AsyncCallback\ | Yes | Callback invoked to return the result. |
+
+**Error codes**
+
+| ID| Error Message |
+| -------- | ---------------------- |
+| 401 | invalid parameters. |
+| 17630001 | crypto operation error. |
+
+**Example**
+
+```js
+import cryptoFramework from "@ohos.security.cryptoFramework"
+
+var md;
+try {
+ md = cryptoFramework.createMd("SHA256");
+} catch (error) {
+ console.error("[Callback]: error code: " + error.code + ", message is: " + error.message);
+}
+console.error("Md algName is: " + md.algName);
+
+let blob;
+md.update(blob, (err,) => {
+ if (err) {
+ console.error("[Callback] err: " + err.code);
+ }
+});
+```
+
+### update
+
+update(input: DataBlob): Promise\
+
+Updates the message digest data. This API uses a promise to return the result.
+
+> **NOTE**
+>
+> For details about the sample code for calling **update()** multiple times, see [Generating a Digest](../../security/cryptoFramework-guidelines.md#generating-a-digest).
+
+**System capability**: SystemCapability.Security.CryptoFramework
+
+| Name| Type | Mandatory| Description |
+| ------ | -------- | ---- | ------------ |
+| input | DataBlob | Yes | Data to pass in.|
+
+**Return value**
+
+| Type | Description |
+| -------------- | ------------- |
+| Promise\ | Promise that returns no value.|
+
+**Error codes**
+
+| ID| Error Message |
+| -------- | ---------------------- |
+| 401 | invalid parameters. |
+| 17630001 | crypto operation error. |
+
+**Example**
+
+```js
+import cryptoFramework from "@ohos.security.cryptoFramework"
+
+var md;
+try {
+ md = cryptoFramework.createMd("SHA256");
+} catch (error) {
+ console.error("[Callback]: error code: " + error.code + ", message is: " + error.message);
+}
+console.error("Md algName is: " + md.algName);
+
+let blob;
+var promiseMdUpdate = md.update(blob);
+promiseMdUpdate.then(() => {
+ // do something
+}).catch(error => {
+ console.error("[Promise]: error: " + error.message);
+});
+```
+
+### digest
+
+digest(callback: AsyncCallback\): void
+
+Generates a message digest. This API uses an asynchronous callback to return the result.
+
+**System capability**: SystemCapability.Security.CryptoFramework
+
+| Name | Type | Mandatory| Description |
+| -------- | ------------------------ | ---- | ---------- |
+| callback | AsyncCallback\ | Yes | Callback invoked to return the result.|
+
+**Error codes**
+
+| ID| Error Message |
+| -------- | ---------------------- |
+| 17620001 | memory error. |
+| 17630001 | crypto operation error. |
+
+**Example**
+
+```js
+import cryptoFramework from "@ohos.security.cryptoFramework"
+
+var md;
+try {
+ md = cryptoFramework.createMd("SHA256");
+} catch (error) {
+ console.error("[Callback]: error code: " + error.code + ", message is: " + error.message);
+}
+console.error("Md algName is: " + md.algName);
+
+let blob;
+md.update(blob, (err,) => {
+ if (err) {
+ console.error("[Callback] err: " + err.code);
+ }
+ md.digest((err1, mdOutput) => {
+ if (err1) {
+ console.error("[Callback] err: " + err1.code);
+ } else {
+ console.error("[Callback]: MD result: " + mdOutput);
+ }
+ });
+});
+```
+
+### digest
+
+digest(): Promise\
+
+Generates a message digest. This API uses a promise to return the result.
+
+**System capability**: SystemCapability.Security.CryptoFramework
+
+**Return value**
+
+| Type | Description |
+| ------------------ | ----------- |
+| Promise\<[DataBlob](#datablob)> | Promise that returns no value.|
+
+**Error codes**
+
+| ID| Error Message |
+| -------- | ---------------------- |
+| 17620001 | memory error. |
+| 17630001 | crypto operation error. |
+
+**Example**
+
+```js
+import cryptoFramework from "@ohos.security.cryptoFramework"
+
+var md;
+try {
+ md = cryptoFramework.createMd("SHA256");
+} catch (error) {
+ console.error("[Callback]: error code: " + error.code + ", message is: " + error.message);
+}
+console.error("Md algName is: " + md.algName);
+
+let blob;
+var promiseMdUpdate = md.update(blob);
+promiseMdUpdate.then(() => {
+ var PromiseMdDigest = md.digest();
+ return PromiseMdDigest;
+}).then(mdOutput => {
+ console.error("[Promise]: MD result: " + mdOutput.data);
+}).catch(error => {
+ console.error("[Promise]: error: " + error.message);
+});
+```
+
+### getMdLength
+
+getMdLength(): number
+
+Obtains the message digest length, in bytes.
+
+**System capability**: SystemCapability.Security.CryptoFramework
+
+**Return value**
+
+| Type | Description |
+| ------ | -------------------------- |
+| number | Returns the length of the message digest obtained.|
+
+**Error codes**
+
+| ID| Error Message |
+| -------- | ---------------------- |
+| 17630001 | crypto operation error. |
+
+**Example**
+
+```js
+import cryptoFramework from "@ohos.security.cryptoFramework"
+
+var md;
+try {
+ md = cryptoFramework.createMd("SHA256");
+} catch (error) {
+ console.error("[Callback]: error code: " + error.code + ", message is: " + error.message);
+}
+console.error("Md algName is: " + md.algName);
+
+let blob;
+var promiseMdUpdate = md.update(blob);
+promiseMdUpdate.then(() => {
+ var PromiseMdDigest = md.digest();
+ return PromiseMdDigest;
+}).then(mdOutput => {
+ console.error("[Promise]: MD result: " + mdOutput.data);
+ let mdLen = md.getMdLength();
+ console.error("MD len: " + mdLen);
+}).catch(error => {
+ console.error("[Promise]: error: " + error.message);
+});
+```
+
+## cryptoFramework.createMac
+
+createMac(algName: string): Mac
+
+Creates a **Mac** instance for message authentication code (MAC) operations. For details about the supported specifications, see [HMAC Algorithm Specifications](../../security/cryptoFramework-overview.md#hmac-algorithm-specifications).
+
+**System capability**: SystemCapability.Security.CryptoFramework
+
+**Parameters**
+
+| Name | Type | Mandatory| Description |
+| ------- | ------ | ---- | ------------------------------------------------------------ |
+| algName | string | Yes | Digest algorithm. For details about the supported algorithms, see [HMAC Algorithm Specifications](../../security/cryptoFramework-overview.md#hmac-algorithm-specifications).|
+
+**Return value**
+
+| Type| Description |
+| ---- | ----------------------------------------- |
+| Mac | Returns the [Mac](#mac) instance created.|
+
+**Error codes**
+
+| ID| Error Message |
+| -------- | ------------------ |
+| 401 | invalid parameters. |
+| 17620001 | memory error. |
+
+**Example**
+
+```js
+import cryptoFramework from "@ohos.security.cryptoFramework"
+
+var mac;
+try {
+ // Set algName based on the algorithm supported.
+ mac = cryptoFramework.createMac("SHA256");
+} catch (error) {
+ console.error("[Promise]: error code: " + error.code + ", message is: " + error.message);
+}
+```
+
+## Mac
+
+Provides APIs for MAC operations. Before using any API of the **Mac** class, you must create a **Mac** instance by using [createMac](#cryptoframeworkcreatemac).
+
+### Attributes
+
+**System capability**: SystemCapability.Security.CryptoFramework
+
+| Name | Type | Readable| Writable| Description |
+| ------- | ------ | ---- | ---- | ---------------------- |
+| algName | string | Yes | No | Digest algorithm.|
+
+### init
+
+init(key: SymKey, callback: AsyncCallback\): void
+
+Initializes the MAC computation using a symmetric key. This API uses an asynchronous callback to return the result.
+
+**System capability**: SystemCapability.Security.CryptoFramework
+
+**Parameters**
+
+| Name | Type | Mandatory| Description |
+| -------- | -------------------- | ---- | -------------- |
+| key | [SymKey](#symkey) | Yes | Shared symmetric key.|
+| callback | AsyncCallback\ | Yes | Callback invoked to return the result. |
+
+**Error codes**
+
+| ID| Error Message |
+| -------- | ---------------------- |
+| 401 | invalid parameters. |
+| 17630001 | crypto operation error. |
+
+**Example**
+
+```js
+import cryptoFramework from "@ohos.security.cryptoFramework"
+
+var mac;
+try {
+ mac = cryptoFramework.createMac("SHA256");
+} catch (error) {
+ console.error("[Promise]: error code: " + error.code + ", message is: " + error.message);
+}
+var KeyBlob;
+var symKeyGenerator = cryptoFramework.createSymKeyGenerator("AES128");
+symKeyGenerator.convertKey(KeyBlob, (err, symKey) => {
+ if (err) {
+ console.error("[Callback] err: " + err.code);
+ }
+ mac.init(symKey, (err1, ) => {
+ if (err1) {
+ console.error("[Callback] err: " + err1.code);
+ }
+ });
+});
+```
+
+### init
+
+init(key: SymKey): Promise\
+
+Initializes the MAC computation using a symmetric key. This API uses a promise to return the result.
+
+**System capability**: SystemCapability.Security.CryptoFramework
+
+**Parameters**
+
+| Name| Type | Mandatory| Description |
+| ------ | ------ | ---- | ------------ |
+| key | [SymKey](#symkey) | Yes | Shared symmetric key.|
+
+**Return value**
+
+| Type | Description |
+| -------------- | ------------- |
+| Promise\ | Promise that returns no value.|
+
+**Error codes**
| ID| Error Message |
| -------- | ---------------------- |
-| 17620001 | memory error. |
-| 17620002 | runtime error. |
+| 401 | invalid parameters. |
+| 17630001 | crypto operation error. |
+
+**Example**
+
+```js
+import cryptoFramework from "@ohos.security.cryptoFramework"
+
+var mac;
+try {
+ mac = cryptoFramework.createMac("SHA256");
+} catch (error) {
+ console.error("[Promise]: error code: " + error.code + ", message is: " + error.message);
+}
+console.error("Mac algName is: " + mac.algName);
+
+var KeyBlob;
+var symKeyGenerator = cryptoFramework.createSymKeyGenerator("AES128");
+var promiseConvertKey = symKeyGenerator.convertKey(KeyBlob);
+promiseConvertKey.then(symKey => {
+ var promiseMacInit = mac.init(symKey);
+ return promiseMacInit;
+}).catch(error => {
+ console.error("[Promise]: error: " + error.message);
+});
+
+```
+
+### update
+
+update(input: DataBlob, callback: AsyncCallback\): void
+
+Updates the MAC computation data. This API uses an asynchronous callback to return the result.
+
+> **NOTE**
+>
+> For details about the sample code for calling **update()** multiple times, see [Generating a MAC](../../security/cryptoFramework-guidelines.md#generating-a-mac).
+
+**System capability**: SystemCapability.Security.CryptoFramework
+
+**Parameters**
+
+| Name | Type | Mandatory| Description |
+| -------- | --------------------- | ---- | ------------ |
+| input | [DataBlob](#datablob) | Yes | Data to pass in.|
+| callback | AsyncCallback\ | Yes | Callback invoked to return the result. |
+
+**Error codes**
+
+| ID| Error Message |
+| -------- | ---------------------- |
+| 401 | invalid parameters. |
| 17630001 | crypto operation error. |
+**Example**
+
+```js
+import cryptoFramework from "@ohos.security.cryptoFramework"
+
+var KeyBlob;
+var mac;
+try {
+ mac = cryptoFramework.createMac("SHA256");
+} catch (error) {
+ console.error("[Callback]: error code: " + error.code + ", message is: " + error.message);
+}
+var symKeyGenerator = cryptoFramework.createSymKeyGenerator("AES128");
+symKeyGenerator.convertKey(KeyBlob, (err, symKey) => {
+ if (err) {
+ console.error("[Callback] err: " + err.code);
+ }
+ mac.init(symKey, (err1, ) => {
+ if (err1) {
+ console.error("[Callback] err: " + err1.code);
+ }
+ let blob;
+ mac.update(blob, (err2, data) => {
+ if (err2) {
+ console.error("[Callback] err: " + err2.code);
+ }
+ });
+ });
+});
+```
+
### update
-update(data : DataBlob) : Promise\;
+update(input: DataBlob): Promise\
-Updates the data for signature verification. This API uses a promise to return the result.
+Updates the MAC computation data. This API uses a promise to return the result.
> **NOTE**
-> For details about the sample code for calling **update()** multiple times, see [Generating and Verifying a Signature](../../security/cryptoFramework-guidelines.md#generating-and-verifying-a-signature).
+>
+> For details about the sample code for calling **update()** multiple times, see [Generating a MAC](../../security/cryptoFramework-guidelines.md#generating-a-mac).
**System capability**: SystemCapability.Security.CryptoFramework
@@ -2501,237 +3193,445 @@ Updates the data for signature verification. This API uses a promise to return t
| Name| Type | Mandatory| Description |
| ------ | -------- | ---- | ---------- |
-| data | [DataBlob](#datablob) | Yes | Data to pass in.|
+| input | [DataBlob](#datablob) | Yes | Data to pass in.|
**Return value**
-| Type | Description |
-| -------------- | ----------- |
-| Promise\ | Promise used to return the result.|
+| Type | Description |
+| -------------- | ------------- |
+| Promise\ | Promise that returns no value.|
**Error codes**
| ID| Error Message |
| -------- | ---------------------- |
-| 17620001 | memory error. |
-| 17620002 | runtime error. |
+| 401 | invalid parameters. |
+| 17630001 | crypto operation error. |
+
+**Example**
+
+```js
+import cryptoFramework from "@ohos.security.cryptoFramework"
+
+var mac;
+try {
+ mac = cryptoFramework.createMac("SHA256");
+} catch (error) {
+ console.error("[Promise]: error code: " + error.code + ", message is: " + error.message);
+}
+console.error("Mac algName is: " + mac.algName);
+
+var KeyBlob;
+var symKeyGenerator = cryptoFramework.createSymKeyGenerator("AES128");
+var promiseConvertKey = symKeyGenerator.convertKey(KeyBlob);
+promiseConvertKey.then(symKey => {
+ var promiseMacInit = mac.init(symKey);
+ return promiseMacInit;
+}).then(() => {
+ let blob;
+ var promiseMacUpdate = mac.update(blob);
+ return promiseMacUpdate;
+}).catch(error => {
+ console.error("[Promise]: error: " + error.message);
+});
+
+```
+
+### doFinal
+
+doFinal(callback: AsyncCallback\): void
+
+Finalizes the MAC computation. This API uses an asynchronous callback to return the result.
+
+**System capability**: SystemCapability.Security.CryptoFramework
+
+**Parameters**
+
+| Name | Type | Mandatory| Description |
+| -------- | ------------------------ | ---- | -------- |
+| callback | AsyncCallback\<[DataBlob](#datablob)> | Yes | Callback invoked to return the result.|
+
+**Error codes**
+
+| ID| Error Message |
+| -------- | ---------------------- |
+| 17620001 | memory error. |
+| 17630001 | crypto operation error. |
+
+**Example**
+
+```js
+import cryptoFramework from "@ohos.security.cryptoFramework"
+
+var KeyBlob;
+var mac;
+try {
+ mac = cryptoFramework.createMac("SHA256");
+} catch (error) {
+ console.error("[Callback]: error code: " + error.code + ", message is: " + error.message);
+}
+var symKeyGenerator = cryptoFramework.createSymKeyGenerator("AES128");
+symKeyGenerator.convertKey(KeyBlob, (err, symKey) => {
+ if (err) {
+ console.error("[Callback] err: " + err.code);
+ }
+ mac.init(symKey, (err1, ) => {
+ if (err1) {
+ console.error("[Callback] err: " + err1.code);
+ }
+ let blob;
+ mac.update(blob, (err2, ) => {
+ if (err2) {
+ console.error("[Callback] err: " + err2.code);
+ }
+ mac.doFinal((err3, macOutput) => {
+ if (err3) {
+ console.error("[Callback] err: " + err3.code);
+ } else {
+ console.error("[Promise]: HMAC result: " + macOutput);
+ }
+ });
+ });
+ });
+});
+```
+
+### doFinal
+
+doFinal(): Promise\
+
+Finalizes the MAC computation. This API uses a promise to return the result.
+
+**System capability**: SystemCapability.Security.CryptoFramework
+
+**Return value**
+
+| Type | Description |
+| ------------------ | ----------- |
+| Promise\<[DataBlob](#datablob)> | Promise that returns no value.|
+
+**Error codes**
+
+| ID| Error Message |
+| -------- | ---------------------- |
+| 17620001 | memory error. |
| 17630001 | crypto operation error. |
-### verify
+**Example**
+
+```js
+import cryptoFramework from "@ohos.security.cryptoFramework"
+
+var mac;
+try {
+ mac = cryptoFramework.createMac("SHA256");
+} catch (error) {
+ console.error("[Promise]: error code: " + error.code + ", message is: " + error.message);
+}
+console.error("Mac algName is: " + mac.algName);
+
+var KeyBlob;
+var symKeyGenerator = cryptoFramework.createSymKeyGenerator("AES128");
+var promiseConvertKey = symKeyGenerator.convertKey(KeyBlob);
+promiseConvertKey.then(symKey => {
+ var promiseMacInit = mac.init(symKey);
+ return promiseMacInit;
+}).then(() => {
+ let blob;
+ var promiseMacUpdate = mac.update(blob);
+ return promiseMacUpdate;
+}).then(() => {
+ var PromiseMacDoFinal = mac.doFinal();
+ return PromiseMacDoFinal;
+}).then(macOutput => {
+ console.error("[Promise]: HMAC result: " + macOutput.data);
+}).catch(error => {
+ console.error("[Promise]: error: " + error.message);
+});
+```
+
+### getMacLength
-verify(data : DataBlob, signatureData : DataBlob, callback : AsyncCallback\) : void
+getMacLength(): number
-Verifies a signature. This API uses an asynchronous callback to return the result.
+Obtains the MAC length, in bytes.
**System capability**: SystemCapability.Security.CryptoFramework
-**Parameters**
+**Return value**
-| Name | Type | Mandatory| Description |
-| ------------- | -------------------- | ---- | ---------- |
-| data | [DataBlob](#datablob) | Yes | Data to pass in.|
-| signatureData | [DataBlob](#datablob) | Yes | Signature data. |
-| callback | AsyncCallback\ | Yes | Callback invoked to return the result. |
+| Type | Description |
+| ------ | --------------------------- |
+| number | Returns the MAC length obtained.|
**Error codes**
| ID| Error Message |
| -------- | ---------------------- |
-| 17620001 | memory error. |
-| 17620002 | runtime error. |
| 17630001 | crypto operation error. |
-### verify
+**Example**
-verify(data : DataBlob, signatureData : DataBlob) : Promise\
+```js
+import cryptoFramework from "@ohos.security.cryptoFramework"
-Verifies a signature. This API uses a promise to return the result.
+var mac;
+try {
+ mac = cryptoFramework.createMac("SHA256");
+} catch (error) {
+ console.error("[Promise]: error code: " + error.code + ", message is: " + error.message);
+}
+console.error("Mac algName is: " + mac.algName);
-**System capability**: SystemCapability.Security.CryptoFramework
+var KeyBlob;
+var symKeyGenerator = cryptoFramework.createSymKeyGenerator("AES128");
+var promiseConvertKey = symKeyGenerator.convertKey(KeyBlob);
+promiseConvertKey.then(symKey => {
+ var promiseMacInit = mac.init(symKey);
+ return promiseMacInit;
+}).then(() => {
+ let blob;
+ var promiseMacUpdate = mac.update(blob);
+ return promiseMacUpdate;
+}).then(() => {
+ var PromiseMacDoFinal = mac.doFinal();
+ return PromiseMacDoFinal;
+}).then(macOutput => {
+ console.error("[Promise]: HMAC result: " + macOutput.data);
+ let macLen = mac.getMacLength();
+ console.error("MAC len: " + macLen);
+}).catch(error => {
+ console.error("[Promise]: error: " + error.message);
+});
+```
-**Parameters**
+## cryptoFramework.createRandom
-| Name | Type | Mandatory| Description |
-| ------------- | -------- | ---- | ---------- |
-| data | [DataBlob](#datablob) | Yes | Data to pass in.|
-| signatureData | [DataBlob](#datablob) | Yes | Signature data. |
+createRandom(): Random
+
+Creates a **Random** instance for generating random numbers and setting seeds. For details about the supported specifications, see [Random Number](../../security/cryptoFramework-overview.md#random-number).
+
+**System capability**: SystemCapability.Security.CryptoFramework
**Return value**
-| Type | Description |
-| ----------------- | ---------------------------- |
-| Promise\ | Promise used to return the result.|
+| Type | Description |
+| ------ | ----------------------------------------------- |
+| Random | Returns the [Random](#random) instance created.|
**Error codes**
-| ID| Error Message |
-| -------- | ---------------------- |
-| 17620001 | memory error. |
-| 17620002 | runtime error. |
-| 17630001 | crypto operation error. |
+| ID| Error Message |
+| -------- | ------------ |
+| 17620001 | memory error. |
-**Callback example**:
+**Example**
-```javascript
+```js
import cryptoFramework from "@ohos.security.cryptoFramework"
-let globalKeyPair; // globalKeyPair is an asymmetric key object generated by the asymmetric key generator. The generation process is omitted here.
-let input1 = null;
-let input2 = null;
-let signMessageBlob = null; // Signed data, which is omitted here.
-let verifyer = cryptoFramework.createVerify("RSA1024|PKCS1|SHA25");
-verifyer.init(globalKeyPair.pubKey, function (err, data) {
- verifyer.update(input1, function(err, data) {
- verifyer.verify(input2, signMessageBlob, function(err, data) {
- console.info("verify result is " + data);
- })
- });
-})
+try {
+ var rand = cryptoFramework.createRandom();
+} catch (error) {
+ console.error("[Callback]: error code: " + error.code + ", message is: " + error.message);
+}
```
-**Promise example**:
+## Random
-```javascript
-import cryptoFramework from "@ohos.security.cryptoFramework"
+Provides APIs for computing random numbers and setting seeds. Before using any API of the **Random** class, you must create a **Random** instance by using [createRandom](#cryptoframeworkcreaterandom).
-let globalKeyPair; // globalKeyPair is an asymmetric key object generated by the asymmetric key generator. The generation process is omitted here.
-let verifyer = cryptoFramework.createVerify("RSA1024|PKCS1|SHA256");
-let verifyInitPromise = verifyer.init(globalKeyPair.pubKey);
-let input1 = null;
-let input2 = null;
-let signMessageBlob = null; // Signed data, which is omitted here.
-verifyInitPromise.then(() => {
- return verifyer.update(input1);
-}).then(() => {
- return verifyer.verify(input2, signMessageBlob);
-}).then(res => {
- console.log("Verify result is " + res);
-});
-```
+### Attributes
-## cryptoFramework.createKeyAgreement
+**System capability**: SystemCapability.Security.CryptoFramework
-createKeyAgreement(algName : string) : KeyAgreement
+| Name | Type | Readable| Writable| Description |
+| ------- | ------ | ---- | ---- | -------------------- |
+| algName10+ | string | Yes | No | Algorithm used to generate the random number. Currently, only **CTR_DRBG** is supported.|
+
+### generateRandom
-Creates a **KeyAgreement** instance.
+generateRandom(len: number, callback: AsyncCallback\): void
-For details about the supported specifications, see [Key Agreement Specifications](../../security/cryptoFramework-overview.md#key-agreement-specifications).
+Generates a random number of the specified length. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Security.CryptoFramework
**Parameters**
-| Name | Type | Mandatory| Description |
-| ------- | ------ | ---- | ------------------------------- |
-| algName | string | Yes | Key agreement algorithm to use. Only ECC is supported.|
+| Name | Type | Mandatory| Description |
+| -------- | ------------------------ | ---- | -------------------- |
+| len | number | Yes | Length of the random number to generate, in bytes. The value range is [1, INT_MAX].|
+| callback | AsyncCallback\<[DataBlob](#datablob)> | Yes | Callback invoked to return the result. |
-**Return value**
+**Error codes**
-| Type | Description |
-| ------------ | ---------------------------------------- |
-| KeyAgreement | **KeyAgreement** instance created.|
+| ID| Error Message |
+| -------- | ---------------------- |
+| 401 | invalid parameters. |
+| 17620001 | memory error. |
+| 17630001 | crypto operation error. |
**Example**
-```javascript
+```js
import cryptoFramework from "@ohos.security.cryptoFramework"
-let keyAgreement = cryptoFramework.createKeyAgreement("ECC256");
-
+var rand;
+try {
+ rand = cryptoFramework.createRandom();
+} catch (error) {
+ console.error("[Callback]: error code: " + error.code + ", message is: " + error.message);
+}
+rand.generateRandom(12, (err, randData) => {
+ if (err) {
+ console.error("[Callback] err: " + err.code);
+ } else {
+ console.error("[Callback]: generate random result: " + randData.data);
+ }
+});
```
-## KeyAgreement
+### generateRandom
-Provides APIs for key agreement operations. Before using any API of the **KeyAgreement** class, you must create a **KeyAgreement** instance by using **createKeyAgreement()**.
+generateRandom(len: number): Promise\
-### Attributes
+Generates a random number of the specified length. This API uses a promise to return the result.
**System capability**: SystemCapability.Security.CryptoFramework
-| Name | Type | Readable| Writable| Description |
-| ------- | ------ | ---- | ---- | ---------------------------- |
-| algName | string | Yes | No | Algorithm used for key agreement.|
-
-### generateSecret
-
-generateSecret(priKey : PriKey, pubKey : PubKey, callback : AsyncCallback\) : void
-
-Generates a shared secret. This API uses an asynchronous callback to return the result.
+**Parameters**
-**System capability**: SystemCapability.Security.CryptoFramework
+| Name| Type | Mandatory| Description |
+| ------ | ------ | ---- | ------------------------------------------------------ |
+| len | number | Yes | Length of the random number to generate, in bytes. The value range is [1, INT_MAX].|
-**Parameters**
+**Return value**
-| Name | Type | Mandatory| Description |
-| -------- | ------------------------ | ---- | ---------------------- |
-| priKey | [PriKey](#prikey) | Yes | Private key used for key agreement.|
-| pubKey | [PubKey](#pubkey) | Yes | Public key used for key agreement.|
-| callback | AsyncCallback\<[DataBlob](#datablob)> | Yes | Callback invoked to return the shared secret.|
+| Type | Description |
+| ------------------ | ----------- |
+| Promise\<[DataBlob](#datablob)> | Promise that returns no value.|
**Error codes**
| ID| Error Message |
| -------- | ---------------------- |
-| 17620001 | memory error. |
-| 17620002 | runtime error. |
+| 401 | invalid parameters. |
+| 17620001 | memory error. |
| 17630001 | crypto operation error. |
-### generateSecret
+**Example**
+
+```js
+import cryptoFramework from "@ohos.security.cryptoFramework"
-generateSecret(priKey : PriKey, pubKey : PubKey) : Promise\
+var rand;
+try {
+ rand = cryptoFramework.createRandom();
+} catch (error) {
+ console.error("[Callback]: error code: " + error.code + ", message is: " + error.message);
+}
-Generates a shared secret. This API uses a promise to return the result.
+var promiseGenerateRand = rand.generateRandom(12);
+promiseGenerateRand.then(randData => {
+ console.error("[Promise]: rand result: " + randData.data);
+}).catch(error => {
+ console.error("[Promise]: error: " + error.message);
+});
+```
+
+### generateRandomSync10+
+
+generateRandomSync(len: number): DataBlob
+
+Generates a random number of the specified length synchronously.
**System capability**: SystemCapability.Security.CryptoFramework
**Parameters**
-| Name| Type | Mandatory| Description |
-| ------ | ------ | ---- | ---------------------- |
-| priKey | [PriKey](#prikey) | Yes | Private key used for key agreement.|
-| pubKey | [PubKey](#pubkey) | Yes | Public key used for key agreement.|
+| Name| Type | Mandatory| Description |
+| ------ | ------ | ---- | -------------------- |
+| len | number | Yes | Length of the random number to generate, in bytes. The value range is [1, INT_MAX].|
**Return value**
-| Type | Description |
-| ------------------ | -------- |
-| Promise\<[DataBlob](#datablob)> | Promise used to return the shared secret.|
+| Type | Description |
+| ------------------ | ----------- |
+|[DataBlob](#datablob) | Returns the generated random number.|
**Error codes**
| ID| Error Message |
| -------- | ---------------------- |
-| 17620001 | memory error. |
-| 17620002 | runtime error. |
+| 401 | invalid parameters. |
+| 17620001 | memory error. |
| 17630001 | crypto operation error. |
-**Callback example**:
+**Example**
-```javascript
+```js
import cryptoFramework from "@ohos.security.cryptoFramework"
-let globalKeyPair; // globalKeyPair is an asymmetric key object generated by the asymmetric key generator. The generation process is omitted here.
-let keyAgreement = cryptoFramework.createKeyAgreement("ECC256");
-keyAgreement.generateSecret(globalKeyPair.priKey, globalKeyPair.pubKey, function (err, secret) {
- if (err) {
- console.error("keyAgreement error.");
- return;
+var rand;
+try {
+ rand = cryptoFramework.createRandom();
+} catch (error) {
+ console.error("[Callback]: error code: " + error.code + ", message is: " + error.message);
+}
+
+try {
+ let randData = rand.generateRandomSync(12);
+ if (randData != null) {
+ console.info("[Sync]: rand result: " + randData.data);
+ } else {
+ console.error("[Sync]: get rand result fail!");
}
- console.info("keyAgreement output is " + secret.data);
-});
+} catch (error) {
+ console.error("[Sync]: error: " + error.message);
+}
```
-**Promise example**:
+### setSeed
+
+setSeed(seed: DataBlob): void
+
+Sets a seed.
+
+**System capability**: SystemCapability.Security.CryptoFramework
+
+| Name| Type | Mandatory| Description |
+| ------ | -------- | ---- | ------------ |
+| seed | DataBlob | Yes | Seed to set.|
+
+**Error codes**
-```javascript
+| ID| Error Message |
+| -------- | ----------------- |
+| 17620001 | memory error. |
+
+**Example**
+
+```js
import cryptoFramework from "@ohos.security.cryptoFramework"
-let globalKeyPair; // globalKeyPair is an asymmetric key object generated by the asymmetric key generator. The generation process is omitted here.
-let keyAgreement = cryptoFramework.createKeyAgreement("ECC256");
-let keyAgreementPromise = keyAgreement.generateSecret(globalKeyPair.priKey, globalKeyPair.pubKey);
-keyAgreementPromise.then((secret) => {
- console.info("keyAgreement output is " + secret.data);
-}).catch((error) => {
- console.error("keyAgreement error.");
+var rand;
+try {
+ rand = cryptoFramework.createRandom();
+} catch (error) {
+ console.error("[Callback]: error code: " + error.code + ", message is: " + error.message);
+}
+
+rand.generateRandom(12, (err, randData) => {
+ if (err) {
+ console.error("[Callback] err: " + err.code);
+ } else {
+ console.error("[Callback]: generate random result: " + randData.data);
+ try {
+ rand.setSeed(randData);
+ } catch (error) {
+ console.log("setSeed failed, errCode: " + error.code + ", errMsg: " + error.message);
+ }
+ }
});
```
diff --git a/en/application-dev/reference/apis/js-apis-font.md b/en/application-dev/reference/apis/js-apis-font.md
index 0b7d7fb3abcb1353d022e70ea785f6454cd422b4..dad280bb91d43d69f78f719cc8733fc212fec826 100644
--- a/en/application-dev/reference/apis/js-apis-font.md
+++ b/en/application-dev/reference/apis/js-apis-font.md
@@ -5,6 +5,8 @@ The **font** module provides APIs for registering custom fonts.
> **NOTE**
>
> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version.
+>
+> The APIs provided by this module are system APIs.
## Modules to Import
@@ -62,3 +64,104 @@ struct FontExample {
}
}
```
+## font.getSystemFontList
+
+getSystemFontList(): Array\
+
+Obtains the list of supported fonts.
+
+**System capability**: SystemCapability.ArkUI.ArkUI.Full
+
+**Return value**
+
+| Type | Description |
+| -------------------- | ----------------- |
+| Array\ | List of supported fonts. |
+
+## Example
+
+```ts
+// xxx.ets
+import font from '@ohos.font';
+
+@Entry
+@Component
+struct FontExample {
+ fontList: Array;
+ build() {
+ Column() {
+ Button("getSystemFontList")
+ .width('60%')
+ .height('6%')
+ .onClick(()=>{
+ this.fontList = font.getSystemFontList()
+ })
+ }.width('100%')
+ }
+}
+```
+
+## font.getFontByName
+
+getFontByName(fontName: string): FontInfo;
+
+Obtains information about a system font based on the font name.
+
+**System capability**: SystemCapability.ArkUI.ArkUI.Full
+
+**Parameters**
+
+| Name | Type | Mandatory | Description |
+| ---------- | --------- | ------- | ------------ |
+| fontName | string | Yes | System font name.|
+
+**Return value**
+
+| Type | Description |
+| ---------------- | ---------------------------- |
+| FontInfo | Information about the system font. |
+
+## FontInfo
+
+| Name | Type | Description |
+| -------------- | ------- | ------------------------- |
+| path | string | File path of the system font. |
+| postScriptName | string | PostScript name of the system font.|
+| fullName | string | Name of the system font. |
+| family | string | Family of the system font. |
+| subfamily | string | Subfamily of the system font. |
+| weight | number | Weight of the system font. |
+| width | number | Width of the system font. |
+| italic | boolean | Whether the system font is italic. |
+| monoSpace | boolean | Whether the system font is monospaced. |
+| symbolic | boolean | Whether the system font supports symbols. |
+
+```ts
+// xxx.ets
+import font from '@ohos.font';
+
+@Entry
+@Component
+struct FontExample {
+ fontList: Array;
+ fontInfo: font.FontInfo;
+ build() {
+ Column() {
+ Button("getFontByName")
+ .onClick(() => {
+ this.fontInfo = font.getFontByName('HarmonyOS Sans Italic')
+ console.log("getFontByName(): path = " + this.fontInfo.path)
+ console.log("getFontByName(): postScriptName = " + this.fontInfo.postScriptName)
+ console.log("getFontByName(): fullName = " + this.fontInfo.fullName)
+ console.log("getFontByName(): Family = " + this.fontInfo.family)
+ console.log("getFontByName(): Subfamily = " + this.fontInfo.subfamily)
+ console.log("getFontByName(): weight = " + this.fontInfo.weight)
+ console.log("getFontByName(): width = " + this.fontInfo.width)
+ console.log("getFontByName(): italic = " + this.fontInfo.italic)
+ console.log("getFontByName(): monoSpace = " + this.fontInfo.monoSpace)
+ console.log("getFontByName(): symbolic = " + this.fontInfo.symbolic)
+ })
+ }.width('100%')
+ }
+}
+```
diff --git a/en/application-dev/reference/apis/js-apis-nfcTag.md b/en/application-dev/reference/apis/js-apis-nfcTag.md
index 747e536b1a518b806f5df66f1efc2288d0c5bb80..aec61516c42598051c916d9314a842ca3deac5ae 100644
--- a/en/application-dev/reference/apis/js-apis-nfcTag.md
+++ b/en/application-dev/reference/apis/js-apis-nfcTag.md
@@ -41,8 +41,10 @@ Before developing applications related to tag read and write, you must declare N
}
],
"requestPermissions": [
- "name": "ohos.permission.NFC_TAG",
- "reason": "tag",
+ {
+ "name": "ohos.permission.NFC_TAG",
+ "reason": "tag",
+ }
]
}
}
diff --git a/en/application-dev/reference/apis/js-apis-plugincomponent.md b/en/application-dev/reference/apis/js-apis-plugincomponent.md
index 618c2d3a50afd39131af6e914adc9e666eadc69e..0ae1baf6eebdadbbdc9d43de1e9c100ac73163db 100644
--- a/en/application-dev/reference/apis/js-apis-plugincomponent.md
+++ b/en/application-dev/reference/apis/js-apis-plugincomponent.md
@@ -4,7 +4,7 @@ The **PluginComponentManager** module provides APIs for the **PluginComponent**
> **NOTE**
>
-> The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version.
+> The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version.
## Modules to Import
@@ -18,10 +18,10 @@ Describes the **PluginComponent** template parameters.
**System capability**: SystemCapability.ArkUI.ArkUI.Full
-| Name | Type | Mandatory| Description |
-| ---------- | ------ | ---- | --------------------------- |
-| source | string | Yes | Component template name. |
-| bundleName | string | Yes | Bundle name of the provider ability.|
+| Name | Type | Mandatory | Description |
+| ---------- | ------ | ---- | ---------------------- |
+| source | string | Yes | Component template name. |
+| bundleName | string | Yes | Bundle name of the provider ability.|
## PluginComponentManager
@@ -33,14 +33,14 @@ Stores information in key-value pairs in JSON format.
**System capability**: SystemCapability.ArkUI.ArkUI.Full
-| Value Range | Description |
-| --------------------- | ---------------------------------------- |
+| Value Range | Description |
+| --------------------- | -------------------- |
| [key: string] | Keyword. The value is a string and can be an empty string.|
-| number | Key value of the number type. |
+| number | Key value of the number type. |
| string | Key value of the string type. The value can be an empty string.|
-| boolean | Key value of the Boolean type. |
-| [] | Key value. The value can be []. |
-| [KVObject](#kvobject) | Key value of the KVObject type. |
+| boolean | Key value of the Boolean type. |
+| [] | Key value. The value can be []. |
+| [KVObject](#kvobject) | Key value of the KVObject type. |
### PushParameters
@@ -51,13 +51,13 @@ Sets the parameters to be passed in the **PluginManager.Push** API in the FA mod
**System capability**: SystemCapability.ArkUI.ArkUI.Full
-| Name | Type | Mandatory| Description |
-| --------- | ----------------------------------- | ---- | -------------------------------------------------------------- |
-| want | [Want](js-apis-application-want.md) | Yes | Ability information of the component user. |
-| name | string | Yes | Component name. |
-| data | [KVObject](#kvobject) | Yes | Component data value. |
-| extraData | [KVObject](#kvobject) | Yes | Additional data value. |
-| jsonPath | string | No | Path to the [external.json](#about-the-externaljson-file) file that stores the template path.|
+| Name | Type | Mandatory | Description |
+| --------- | ----------------------------------- | ---- | ---------------------------------------- |
+| want | [Want](js-apis-application-want.md) | Yes | Ability information of the component user. |
+| name | string | Yes | Component name. |
+| data | [KVObject](#kvobject) | Yes | Component data value. |
+| extraData | [KVObject](#kvobject) | Yes | Additional data value. |
+| jsonPath | string | No | Path to the [external.json](#about-the-externaljson-file) file that stores the template path.|
### PushParameterForStage
@@ -69,14 +69,14 @@ Sets the parameters to be passed in the **PluginManager.Push** API in the stage
**System capability**: SystemCapability.ArkUI.ArkUI.Full
-| Name | Type | Mandatory| Description |
-| --------- | ----------------------------------- | ---- | ---------------------------------------------------------------- |
-| owner | [Want](js-apis-application-want.md) | Yes | Ability information of the component provider. |
-| target | [Want](js-apis-application-want.md) | Yes | Ability information of the component user. |
-| name | string | Yes | Component name. |
-| data | [KVObject](#kvobject) | Yes | Component data value. |
-| extraData | [KVObject](#kvobject) | Yes | Additional data value. |
-| jsonPath | string | No | Path to the [external.json](#about-the-externaljson-file) file that stores the template path.|
+| Name | Type | Mandatory | Description |
+| --------- | ----------------------------------- | ---- | ---------------------------------------- |
+| owner | [Want](js-apis-application-want.md) | Yes | Ability information of the component provider. |
+| target | [Want](js-apis-application-want.md) | Yes | Ability information of the component user. |
+| name | string | Yes | Component name. |
+| data | [KVObject](#kvobject) | Yes | Component data value. |
+| extraData | [KVObject](#kvobject) | Yes | Additional data value. |
+| jsonPath | string | No | Path to the [external.json](#about-the-externaljson-file) file that stores the template path.|
### RequestParameters
@@ -86,12 +86,12 @@ Sets the parameters to be passed in the **PluginManager.Request** API in the FA
**System capability**: SystemCapability.ArkUI.ArkUI.Full
-| Name | Type | Mandatory| Description |
-| -------- | ----------------------------------- | ---- | --------------------------------------------------------------------------------------------------------------------- |
-| want | [Want](js-apis-application-want.md) | Yes | Ability information of the component provider. |
-| name | string | Yes | Name of the requested component. |
-| data | [KVObject](#kvobject) | Yes | Additional data. |
-| jsonPath | string | No | Path to the [external.json](#about-the-externaljson-file) file that stores the template path. Request communication is not triggered when **jsonPath** is not empty or not set.|
+| Name | Type | Mandatory | Description |
+| -------- | ----------------------------------- | ---- | ---------------------------------------- |
+| want | [Want](js-apis-application-want.md) | Yes | Ability information of the component provider. |
+| name | string | Yes | Name of the requested component. |
+| data | [KVObject](#kvobject) | Yes | Additional data. |
+| jsonPath | string | No | Path to the [external.json](#about-the-externaljson-file) file that stores the template path. Request communication is not triggered when **jsonPath** is not empty or not set.|
### RequestParameterForStage
@@ -103,13 +103,13 @@ Sets the parameters to be passed in the **PluginManager.Request** API in the sta
**System capability**: SystemCapability.ArkUI.ArkUI.Full
-| Name | Type | Mandatory| Description |
-| -------- | ----------------------------------- | ---- | --------------------------------------------------------------------------------------------------------------------- |
-| owner | [Want](js-apis-application-want.md) | Yes | Ability information of the component user. |
-| target | [Want](js-apis-application-want.md) | Yes | Ability information of the component provider. |
-| name | string | Yes | Name of the requested component. |
-| data | [KVObject](#kvobject) | Yes | Additional data. |
-| jsonPath | string | No | Path to the [external.json](#about-the-externaljson-file) file that stores the template path. Request communication is not triggered when **jsonPath** is not empty or not set.|
+| Name | Type | Mandatory | Description |
+| -------- | ----------------------------------- | ---- | ---------------------------------------- |
+| owner | [Want](js-apis-application-want.md) | Yes | Ability information of the component user. |
+| target | [Want](js-apis-application-want.md) | Yes | Ability information of the component provider. |
+| name | string | Yes | Name of the requested component. |
+| data | [KVObject](#kvobject) | Yes | Additional data. |
+| jsonPath | string | No | Path to the [external.json](#about-the-externaljson-file) file that stores the template path. Request communication is not triggered when **jsonPath** is not empty or not set.|
### RequestCallbackParameters
@@ -117,11 +117,11 @@ Provides the result returned after the **PluginManager.Request** API is called.
**System capability**: SystemCapability.ArkUI.ArkUI.Full
-| Name | Type | Mandatory| Description |
-| ----------------- | --------------------------------------------------- | ---- | ---------- |
-| componentTemplate | [PluginComponentTemplate](#plugincomponenttemplate) | Yes | Component template.|
-| data | [KVObject](#kvobject) | Yes | Component data.|
-| extraData | [KVObject](#kvobject) | Yes | Additional data.|
+| Name | Type | Mandatory | Description |
+| ----------------- | ---------------------------------------- | ---- | ----- |
+| componentTemplate | [PluginComponentTemplate](#plugincomponenttemplate) | Yes | Component template.|
+| data | [KVObject](#kvobject) | Yes | Component data.|
+| extraData | [KVObject](#kvobject) | Yes | Additional data.|
### RequestEventResult
@@ -129,11 +129,11 @@ Provides the result returned after the request listener is registered and the re
**System capability**: SystemCapability.ArkUI.ArkUI.Full
-| Name | Type | Mandatory| Description |
-| --------- | --------------------- | ---- | ---------- |
-| template | string | No | Component template.|
-| data | [KVObject](#kvobject) | No | Component data.|
-| extraData | [KVObject](#kvobject) | No | Additional data.|
+| Name | Type | Mandatory | Description |
+| --------- | --------------------- | ---- | ----- |
+| template | string | No | Component template.|
+| data | [KVObject](#kvobject) | No | Component data.|
+| extraData | [KVObject](#kvobject) | No | Additional data.|
### OnPushEventCallback
@@ -144,12 +144,12 @@ Registers the listener for the push event.
**Parameters**
-| Name | Type | Mandatory| Description |
-| --------- | --------------------------------------------------- | ---- | ---------------------------------------- |
-| source | [Want](js-apis-application-want.md) | Yes | Information about the push request sender. |
-| template | [PluginComponentTemplate](#plugincomponenttemplate) | Yes | Name of the request component template for the push request sender.|
-| data | [KVObject](#kvobject) | Yes | Data. |
-| extraData | [KVObject](#kvobject) | Yes | Additional data. |
+| Name | Type | Mandatory | Description |
+| --------- | ---------------------------------------- | ---- | ---------------------- |
+| source | [Want](js-apis-application-want.md) | Yes | Information about the push request sender. |
+| template | [PluginComponentTemplate](#plugincomponenttemplate) | Yes | Name of the request component template for the push request sender.|
+| data | [KVObject](#kvobject) | Yes | Data. |
+| extraData | [KVObject](#kvobject) | Yes | Additional data. |
**Example**
@@ -172,11 +172,11 @@ Registers the listener for the request event.
**Parameters**
-| Name | Type | Mandatory| Description |
-| --------- | ----------------------------------- | ---- | --------------------------- |
-| source | [Want](js-apis-application-want.md) | Yes | Information about the request sender.|
-| name | string | Yes | Template name. |
-| extraData | [KVObject](#kvobject) | Yes | Additional data. |
+| Name | Type | Mandatory | Description |
+| --------- | ----------------------------------- | ---- | ----------------- |
+| source | [Want](js-apis-application-want.md) | Yes | Information about the request sender.|
+| name | string | Yes | Template name. |
+| extraData | [KVObject](#kvobject) | Yes | Additional data. |
**Example**
@@ -200,10 +200,10 @@ Pushes the component and data to the component user.
**Model restriction**: This API can be used only in the FA model.
**Parameters**
-| Name | Type | Mandatory| Description |
-| -------- | --------------------------------- | ---- | ------------------------ |
-| param | [PushParameters](#pushparameters) | Yes | Information about the component user. |
-| callback | AsyncCallback<void> | Yes | Asynchronous callback used to return the result.|
+| Name | Type | Mandatory | Description |
+| -------- | --------------------------------- | ---- | ------------ |
+| param | [PushParameters](#pushparameters) | Yes | Information about the component user. |
+| callback | AsyncCallback<void> | Yes | Asynchronous callback used to return the result.|
**Example**
@@ -241,10 +241,10 @@ Pushes the component and data to the component user.
**Model restriction**: This API can be used only in the stage model.
**Parameters**
-| Name | Type | Mandatory| Description |
-| -------- | ----------------------------------------------- | ---- | ------------------------ |
-| param | [PushParameterForStage](#pushparameterforstage) | Yes | Information about the component user. |
-| callback | AsyncCallback<void> | Yes | Asynchronous callback used to return the result.|
+| Name | Type | Mandatory | Description |
+| -------- | ---------------------------------------- | ---- | ------------ |
+| param | [PushParameterForStage](#pushparameterforstage) | Yes | Information about the component user. |
+| callback | AsyncCallback<void> | Yes | Asynchronous callback used to return the result.|
**Example**
@@ -289,10 +289,10 @@ Requests the component from the component provider.
**Parameters**
-| Name | Type | Mandatory| Description |
-| -------- | ---------------------------------------------------------------------------------------------- | ---- | ---------------------------------------------------------------- |
-| param | [RequestParameters](#requestparameters) | Yes | Information about the component request. |
-| callback | AsyncCallback<[RequestCallbackParameters](#requestcallbackparameters) \| void> | Yes | Asynchronous callback used to return the requested data.|
+| Name | Type | Mandatory | Description |
+| -------- | ---------------------------------------- | ---- | ----------------------------------- |
+| param | [RequestParameters](#requestparameters) | Yes | Information about the component request. |
+| callback | AsyncCallback<[RequestCallbackParameters](#requestcallbackparameters) \| void> | Yes | Asynchronous callback used to return the requested data.|
**Example**
@@ -332,10 +332,10 @@ Requests the component from the component provider.
**Parameters**
-| Name | Type | Mandatory| Description |
-| -------- | ---------------------------------------------------------------------------------------------- | ---- | ---------------------------------------------------------------- |
-| param | [RequestParameterForStage](#requestparameterforstage) | Yes | Information about the component request. |
-| callback | AsyncCallback<[RequestCallbackParameters](#requestcallbackparameters) \| void> | Yes | Asynchronous callback used to return the requested data.|
+| Name | Type | Mandatory | Description |
+| -------- | ---------------------------------------- | ---- | ----------------------------------- |
+| param | [RequestParameterForStage](#requestparameterforstage) | Yes | Information about the component request. |
+| callback | AsyncCallback<[RequestCallbackParameters](#requestcallbackparameters) \| void> | Yes | Asynchronous callback used to return the requested data.|
**Example**
@@ -371,10 +371,10 @@ Listens for events of the request type and returns the requested data, or listen
**Parameters**
-| Name | Type | Mandatory| Description |
-| --------- | ---------------------------------------------------------------------------------------------------------- | ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| eventType | string | Yes | Type of the event to listen for. The options are as follows: **"push"**: The component provider pushes data to the component consumer. **"request"**: The component consumer proactively requests data from the component provider. |
-| callback | [OnPushEventCallback](#onpusheventcallback) \| [OnRequestEventCallback](#onrequesteventcallback) | Yes | Callback used to return the result. The type is [OnPushEventCallback](#onpusheventcallback) for the push event and [OnRequestEventCallback](#onrequesteventcallback) for the request event.|
+| Name | Type | Mandatory | Description |
+| --------- | ---------------------------------------- | ---- | ---------------------------------------- |
+| eventType | string | Yes | Type of the event to listen for. The options are as follows: **"push"**: The component provider pushes data to the component consumer. **"request"**: The component consumer proactively requests data from the component provider.|
+| callback | [OnPushEventCallback](#onpusheventcallback) \| [OnRequestEventCallback](#onrequesteventcallback) | Yes | Callback used to return the result. The type is [OnPushEventCallback](#onpusheventcallback) for the push event and [OnRequestEventCallback](#onrequesteventcallback) for the request event.|
**Example**
diff --git a/en/application-dev/reference/apis/js-apis-webview.md b/en/application-dev/reference/apis/js-apis-webview.md
index 956f922e5414eb058e15ac7f52daba1c8d8db8cf..a5334a26084d30eafb4f914ea3f7fe8d457267f7 100644
--- a/en/application-dev/reference/apis/js-apis-webview.md
+++ b/en/application-dev/reference/apis/js-apis-webview.md
@@ -63,42 +63,6 @@ struct WebComponent {
Implements a **WebMessagePort** object to send and receive messages.
-### close
-
-close(): void
-
-Closes this message port.
-
-**System capability**: SystemCapability.Web.Webview.Core
-
-**Example**
-
-```ts
-// xxx.ets
-import web_webview from '@ohos.web.webview'
-
-@Entry
-@Component
-struct WebComponent {
- controller: web_webview.WebviewController = new web_webview.WebviewController();
- msgPort: web_webview.WebMessagePort[] = null;
-
- build() {
- Column() {
- Button('close')
- .onClick(() => {
- if (this.msgPort && this.msgPort[1]) {
- this.msgPort[1].close();
- } else {
- console.error("msgPort is null, Please initialize first");
- }
- })
- Web({ src: 'www.example.com', controller: this.controller })
- }
- }
-}
-```
-
### postMessageEvent
postMessageEvent(message: WebMessage): void
@@ -364,6 +328,7 @@ struct WebComponent {
}
```
+HTML file to be loaded:
```html
@@ -448,6 +413,56 @@ function postStringToApp() {
}
```
+### close
+
+close(): void
+
+Closes this message port. To use this API, a message port must first be created using [createWebMessagePorts](#createwebmessageports).
+
+**System capability**: SystemCapability.Web.Webview.Core
+
+**Example**
+
+```ts
+// xxx.ets
+import web_webview from '@ohos.web.webview'
+
+@Entry
+@Component
+struct WebComponent {
+ controller: web_webview.WebviewController = new web_webview.WebviewController();
+ msgPort: web_webview.WebMessagePort[] = null;
+
+ build() {
+ Column() {
+ // Use createWebMessagePorts to create a message port.
+ Button('createWebMessagePorts')
+ .onClick(() => {
+ try {
+ this.msgPort = this.controller.createWebMessagePorts();
+ console.log("createWebMessagePorts size:" + this.msgPort.length)
+ } catch (error) {
+ console.error(`ErrorCode: ${error.code}, Message: ${error.message}`);
+ }
+ })
+ Button('close')
+ .onClick(() => {
+ try {
+ if (this.msgPort && this.msgPort.length == 2) {
+ this.msgPort[1].close();
+ } else {
+ console.error("msgPort is null, Please initialize first");
+ }
+ } catch (error) {
+ console.error(`ErrorCode: ${error.code}, Message: ${error.message}`);
+ }
+ })
+ Web({ src: 'www.example.com', controller: this.controller })
+ }
+ }
+}
+```
+
## WebviewController
Implements a **WebviewController** to control the behavior of the **\** component. A **WebviewController** can control only one **\** component, and the APIs (except static APIs) in the **WebviewController** can be invoked only after it has been bound to the target **\** component.
@@ -473,7 +488,6 @@ export default class EntryAbility extends UIAbility {
onCreate(want, launchParam) {
console.log("EntryAbility onCreate")
web_webview.WebviewController.initializeWebEngine()
- globalThis.abilityWant = want
console.log("EntryAbility onCreate done")
}
}
@@ -516,30 +530,11 @@ export default class EntryAbility extends UIAbility {
}
```
-### Creating an Object
-
-```ts
-// xxx.ets
-import web_webview from '@ohos.web.webview';
-
-@Entry
-@Component
-struct WebComponent {
- controller: web_webview.WebviewController = new web_webview.WebviewController();
-
- build() {
- Column() {
- Web({ src: 'www.example.com', controller: this.controller })
- }
- }
-}
-```
-
### setWebDebuggingAccess
static setWebDebuggingAccess(webDebuggingAccess: boolean): void
-Sets whether to enable web debugging.
+Sets whether to enable web debugging. For details, see [Debugging Frontend Pages by Using DevTools](../../web/web-debugging-with-devtools.md).
**System capability**: SystemCapability.Web.Webview.Core
@@ -656,70 +651,73 @@ struct WebComponent {
```
There are three methods for loading local resource files:
-1. Using $rawfile
-```ts
-// xxx.ets
-import web_webview from '@ohos.web.webview'
-@Entry
-@Component
-struct WebComponent {
- controller: web_webview.WebviewController = new web_webview.WebviewController();
+1. Using $rawfile
+ ```ts
+ // xxx.ets
+ import web_webview from '@ohos.web.webview'
+
+ @Entry
+ @Component
+ struct WebComponent {
+ controller: web_webview.WebviewController = new web_webview.WebviewController();
+
+ build() {
+ Column() {
+ Button('loadUrl')
+ .onClick(() => {
+ try {
+ // Load a local resource file through $rawfile.
+ this.controller.loadUrl($rawfile('index.html'));
+ } catch (error) {
+ console.error(`ErrorCode: ${error.code}, Message: ${error.message}`);
+ }
+ })
+ Web({ src: 'www.example.com', controller: this.controller })
+ }
+ }
+ }
+ ```
- build() {
- Column() {
- Button('loadUrl')
- .onClick(() => {
- try {
- // Load a local resource file through $rawfile.
- this.controller.loadUrl($rawfile('xxx.html'));
- } catch (error) {
- console.error(`ErrorCode: ${error.code}, Message: ${error.message}`);
- }
- })
- Web({ src: 'www.example.com', controller: this.controller })
- }
- }
-}
-```
2. Using the resources protocol
-```ts
-// xxx.ets
-import web_webview from '@ohos.web.webview'
-
-@Entry
-@Component
-struct WebComponent {
- controller: web_webview.WebviewController = new web_webview.WebviewController();
-
- build() {
- Column() {
- Button('loadUrl')
- .onClick(() => {
- try {
- // Load a local resource file through the resource protocol.
- this.controller.loadUrl("resource://rawfile/xxx.html");
- } catch (error) {
- console.error(`ErrorCode: ${error.code}, Message: ${error.message}`);
- }
- })
- Web({ src: 'www.example.com', controller: this.controller })
- }
- }
-}
-```
+ ```ts
+ // xxx.ets
+ import web_webview from '@ohos.web.webview'
+
+ @Entry
+ @Component
+ struct WebComponent {
+ controller: web_webview.WebviewController = new web_webview.WebviewController();
+
+ build() {
+ Column() {
+ Button('loadUrl')
+ .onClick(() => {
+ try {
+ // Load a local resource file through the resource protocol.
+ this.controller.loadUrl("resource://rawfile/index.html");
+ } catch (error) {
+ console.error(`ErrorCode: ${error.code}, Message: ${error.message}`);
+ }
+ })
+ Web({ src: 'www.example.com', controller: this.controller })
+ }
+ }
+ }
+ ```
3. Using a sandbox path. For details, see the example of loading local resource files in the sandbox in [Web](../arkui-ts/ts-basic-components-web.md#web).
-```html
-
-
-
-
-
Hello World
-
-
-```
+ HTML file to be loaded:
+ ```html
+
+
+
+
+
Hello World
+
+
+ ```
### loadData
@@ -1343,6 +1341,24 @@ struct Index {
}
```
+HTML file to be loaded:
+```html
+
+
+
+
+
+ Hello world!
+
+
+
+```
+
### runJavaScript
runJavaScript(script: string, callback : AsyncCallback\): void
@@ -1406,6 +1422,24 @@ struct WebComponent {
}
```
+HTML file to be loaded:
+```html
+
+
+
+
+
+ Hello world!
+
+
+
+```
+
### runJavaScript
runJavaScript(script: string): Promise\
@@ -1444,11 +1478,9 @@ import web_webview from '@ohos.web.webview'
@Component
struct WebComponent {
controller: web_webview.WebviewController = new web_webview.WebviewController();
- @State webResult: string = '';
build() {
Column() {
- Text(this.webResult).fontSize(20)
Web({ src: $rawfile('index.html'), controller: this.controller })
.javaScriptAccess(true)
.onPageEnd(e => {
@@ -1470,6 +1502,23 @@ struct WebComponent {
}
```
+HTML file to be loaded:
+```html
+
+
+
+
+
+ Hello world!
+
+
+
+```
### runJavaScriptExt10+
@@ -1569,8 +1618,11 @@ struct WebComponent {
}
}
}
+```
-//index.html
+HTML file to be loaded:
+```html
+
@@ -1681,8 +1733,11 @@ struct WebComponent {
}
}
}
+```
-//index.html
+HTML file to be loaded:
+```html
+
@@ -2178,14 +2233,15 @@ struct WebComponent {
console.error(`ErrorCode: ${error.code}, Message: ${error.message}`);
}
})
- Web({ src: $rawfile('xxx.html'), controller: this.controller })
+ Web({ src: $rawfile('index.html'), controller: this.controller })
}
}
}
```
+HTML file to be loaded:
```html
-
+
@@ -2973,14 +3029,15 @@ struct WebComponent {
console.error(`ErrorCode: ${error.code}, Message: ${error.message}`);
}
})
- Web({ src: 'www.example.com', controller: this.controller })
+ Web({ src: $rawfile('index.html'), controller: this.controller })
}
}
}
```
+HTML file to be loaded:
```html
-
+
@@ -3045,14 +3102,15 @@ struct WebComponent {
console.error(`ErrorCode: ${error.code}, Message: ${error.message}`);
}
})
- Web({ src: 'www.example.com', controller: this.controller })
+ Web({ src: $rawfile('index.html'), controller: this.controller })
}
}
}
```
+HTML file to be loaded:
```html
-
+
@@ -3117,14 +3175,15 @@ struct WebComponent {
console.error(`ErrorCode: ${error.code}, Message: ${error.message}`);
}
})
- Web({ src: 'www.example.com', controller: this.controller })
+ Web({ src: $rawfile('index.html'), controller: this.controller })
}
}
}
```
+HTML file to be loaded:
```html
-
+
@@ -3640,7 +3699,7 @@ struct WebComponent {
.onClick(() => {
try {
let state = this.controller.serializeWebState();
- // Obtain the value of globalThis.cacheDir from MainAbility.ts.
+ // globalThis.cacheDir is obtained from EntryAbility.ts.
let path = globalThis.cacheDir;
path += '/WebState';
// Synchronously open a file.
@@ -3657,14 +3716,14 @@ struct WebComponent {
}
```
-2. Modify **MainAbility.ts**.
+2. Modify the **EntryAbility.ts** file.
Obtain the path of the application cache file.
```ts
// xxx.ts
import UIAbility from '@ohos.app.ability.UIAbility';
import web_webview from '@ohos.web.webview';
-export default class MainAbility extends UIAbility {
+export default class EntryAbility extends UIAbility {
onCreate(want, launchParam) {
// Bind cacheDir to the globalThis object to implement data synchronization between the UIAbility component and the page.
globalThis.cacheDir = this.context.cacheDir;
@@ -3712,7 +3771,7 @@ struct WebComponent {
Button('RestoreWebState')
.onClick(() => {
try {
- // Obtain the value of globalThis.cacheDir from MainAbility.ts.
+ // globalThis.cacheDir is obtained from EntryAbility.ts.
let path = globalThis.cacheDir;
path += '/WebState';
// Synchronously open a file.
@@ -3739,14 +3798,14 @@ struct WebComponent {
}
```
-2. Modify **MainAbility.ts**.
+2. Modify the **EntryAbility.ts** file.
Obtain the path of the application cache file.
```ts
// xxx.ts
import UIAbility from '@ohos.app.ability.UIAbility';
import web_webview from '@ohos.web.webview';
-export default class MainAbility extends UIAbility {
+export default class EntryAbility extends UIAbility {
onCreate(want, launchParam) {
// Bind cacheDir to the globalThis object to implement data synchronization between the UIAbility component and the page.
globalThis.cacheDir = this.context.cacheDir;
@@ -6230,6 +6289,9 @@ Describes the mode in which the **\** component uses HTTPDNS.
| Name | Value| Description |
| ------------- | -- |----------------------------------------- |
-| Off | 0 |HTTPDNS is not used. This value can be used to revoke the previously used HTTPDNS configuration.|
-| Auto | 1 |HTTPDNS is used in automatic mode. When the specified HTTPDNS server is unavailable for resolution, the component will fall back to the system DNS server.|
-| SecureOnly | 2 |The specified HTTPDNS server is forcibly used for DNS resolution.|
+| Off(deprecated) | 0 |HTTPDNS is not used. This value can be used to revoke the previously used HTTPDNS configuration. This API is deprecated since API version 10. You are advised to use **OFF** instead.|
+| Auto(deprecated) | 1 |HTTPDNS is used in automatic mode. When the specified HTTPDNS server is unavailable for resolution, the component will fall back to the system DNS server. This API is deprecated since API version 10. You are advised to use **AUTO** instead.|
+| SecureOnly(deprecated) | 2 |The specified HTTPDNS server is forcibly used for DNS resolution. This API is deprecated since API version 10. You are advised to use **SECURE_ONLY** instead.|
+| OFF | 0 |HTTPDNS is not used. This value can be used to revoke the previously used HTTPDNS configuration.|
+| AUTO | 1 |HTTPDNS is used in automatic mode. When the specified HTTPDNS server is unavailable for resolution, the component will fall back to the system DNS server.|
+| SECURE_ONLY | 2 |The specified HTTPDNS server is forcibly used for DNS resolution.|
diff --git a/en/application-dev/reference/arkui-ts/Readme-EN.md b/en/application-dev/reference/arkui-ts/Readme-EN.md
index bb367dd6c32061334312afe76f0acee149f06bee..a1408eba5cdd14511f6f1be10288e9c641bd8522 100644
--- a/en/application-dev/reference/arkui-ts/Readme-EN.md
+++ b/en/application-dev/reference/arkui-ts/Readme-EN.md
@@ -12,7 +12,7 @@
- [Mouse Event](ts-universal-mouse-key.md)
- [Component Area Change Event](ts-universal-component-area-change-event.md)
- [Visible Area Change Event](ts-universal-component-visible-area-change-event.md)
- - [Custom Keyboard Shortcuts](ts-universal-events-keyboardshortcut.md)
+ - [Component Keyboard Shortcut Event](ts-universal-events-keyboardshortcut.md)
- Universal Attributes
- [Size](ts-universal-attributes-size.md)
- [Location](ts-universal-attributes-location.md)
@@ -43,7 +43,7 @@
- Touch Interactions
- [Touch Target](ts-universal-attributes-touch-target.md)
- [Hit Test Control](ts-universal-attributes-hit-test-behavior.md)
- - Touch Interactions
+ - Transition
- [Modal Transition](ts-universal-attributes-modal-transition.md)
- [Sheet Transition](ts-universal-attributes-sheet-transition.md)
- [Obscuring](ts-universal-attributes-obscured.md)
diff --git a/en/application-dev/reference/arkui-ts/figures/arkts-progress.png b/en/application-dev/reference/arkui-ts/figures/arkts-progress.png
new file mode 100644
index 0000000000000000000000000000000000000000..8e16510ddae266f037cce57857c3dc2ecc14ce2e
Binary files /dev/null and b/en/application-dev/reference/arkui-ts/figures/arkts-progress.png differ
diff --git a/en/application-dev/reference/arkui-ts/figures/deleteListItem.gif b/en/application-dev/reference/arkui-ts/figures/deleteListItem.gif
new file mode 100644
index 0000000000000000000000000000000000000000..5c2c529ef670b83df2e4bd261bbddfe6bca7e7ef
Binary files /dev/null and b/en/application-dev/reference/arkui-ts/figures/deleteListItem.gif differ
diff --git a/en/application-dev/reference/arkui-ts/figures/en-us_image_0000001194352468.gif b/en/application-dev/reference/arkui-ts/figures/en-us_image_0000001194352468.gif
deleted file mode 100644
index 58feeb2988e8d9a643234691ae4d5cf5ccef6d4f..0000000000000000000000000000000000000000
Binary files a/en/application-dev/reference/arkui-ts/figures/en-us_image_0000001194352468.gif and /dev/null differ
diff --git a/en/application-dev/reference/arkui-ts/figures/en-us_image_1501929990650.jpg b/en/application-dev/reference/arkui-ts/figures/en-us_image_1501929990650.jpg
deleted file mode 100644
index ca0ec86c6c71b6c6daa60bf3ee43795f33568c64..0000000000000000000000000000000000000000
Binary files a/en/application-dev/reference/arkui-ts/figures/en-us_image_1501929990650.jpg and /dev/null differ
diff --git a/en/application-dev/reference/arkui-ts/figures/progress.png b/en/application-dev/reference/arkui-ts/figures/progress.png
deleted file mode 100644
index d50f4b47628b425b09f93bc9a44853ad79e12631..0000000000000000000000000000000000000000
Binary files a/en/application-dev/reference/arkui-ts/figures/progress.png and /dev/null differ
diff --git a/en/application-dev/reference/arkui-ts/ts-appendix-enums.md b/en/application-dev/reference/arkui-ts/ts-appendix-enums.md
index 35b8c458af2de6981fb47703039e07ee47b3a6b1..0753b4ab4dc8028e3747f8905b1032f2a099bcfc 100644
--- a/en/application-dev/reference/arkui-ts/ts-appendix-enums.md
+++ b/en/application-dev/reference/arkui-ts/ts-appendix-enums.md
@@ -557,3 +557,10 @@ This API is supported in ArkTS widgets.
| LIGHT | Small area (light)| Spring effect, with stiffness of 410, damping of 38, and initial velocity of 1.| 90% |
| MIDDLE | Medium area (stable)| Spring effect, with stiffness of 350, damping of 35, and initial velocity of 0.5.| 95% |
| HEAVY | Large area (heavy)| Spring effect, with stiffness of 240, damping of 28, and initial velocity of 0.| 95% |
+
+## TextContentStyle10+
+
+| Name | Description |
+| ------- | ------------------------------------------------------------ |
+| DEFAULT | Default style. The caret width is fixed at 1.5 vp, and the caret height is subject to the background height and font size of the selected text.|
+| INLINE | Inline input style. The background height of the selected text is the same as the height of the text box. |
diff --git a/en/application-dev/reference/arkui-ts/ts-basic-components-image.md b/en/application-dev/reference/arkui-ts/ts-basic-components-image.md
index ad23abd051a1cae666be7b4038e86fba30147fcc..2a0e870a9d2be12b1202e3ed36d53f7e22480a49 100644
--- a/en/application-dev/reference/arkui-ts/ts-basic-components-image.md
+++ b/en/application-dev/reference/arkui-ts/ts-basic-components-image.md
@@ -21,7 +21,7 @@ Not supported
Image(src: PixelMap | ResourceStr | DrawableDescriptor)
-Obtains an image from the specified source for subsequent rendering and display.
+Obtains an image from the specified source for subsequent rendering and display. If the **\** component fails to obtain the image or the obtained image size is 0, the **\** component is automatically resized to 0 and does not follow the layout constraints of its parent component.
Since API version 9, this API is supported in ArkTS widgets.
@@ -29,7 +29,7 @@ Since API version 9, this API is supported in ArkTS widgets.
| Name | Type | Mandatory | Description |
| ---- | ---------------------------------------- | ---- | ---------------------------------------- |
-| src | [PixelMap](../apis/js-apis-image.md#pixelmap7) \| ResourceStr\| [DrawableDescriptor](../apis/js-apis-arkui-drawableDescriptor.md#drawabledescriptor) | Yes | Image source. Both local and online images are supported. When using an image referenced using a relative path, for example, **Image("common/test.jpg")**, the **\** component cannot be called across bundles or modules. Therefore, you are advised to use **\$r** to reference image resources that need to be used globally. - The following image formats are supported: PNG, JPG, BMP, SVG, GIF. \- Base64 strings are supported. The value format is data:image/[png\|jpeg\|bmp\|webp];base64,[base64 data], where [base64 data] is a Base64 string. \- Strings with the **datashare://** prefix are supported, which are used to access the image path provided by a Data ability. \- Strings with the **file:///data/storage** prefix are supported, which are used to read image resources in the **files** folder in the installation directory of the current application. Ensure that the application has the read permission to the files in the specified path. \- [DrawableDescriptor](../apis/js-apis-arkui-drawableDescriptor.md#drawabledescriptor) objects are supported. - For details, see [Displaying Images](../../ui/arkts-graphics-display.md). **NOTE** - ArkTS widgets support GIF animations, but the animations only play once on display. - ArkTS widgets do not support the strings with the **http://**, **datashare://**, or **file:///data/storage** prefix. - ArkTS widgets do not support the [PixelMap](../apis/js-apis-image.md#pixelmap7) type.|
+| src | [PixelMap](../apis/js-apis-image.md#pixelmap7) \|ResourceStr\| [DrawableDescriptor](../apis/js-apis-arkui-drawableDescriptor.md#drawabledescriptor) | Yes | Image source. Both local and online images are supported. When using an image referenced using a relative path, for example, **Image("common/test.jpg")**, the **\** component cannot be called across bundles or modules. Therefore, you are advised to use **\$r** to reference image resources that need to be used globally. - The following image formats are supported: PNG, JPG, BMP, SVG, GIF. \- Base64 strings are supported. The value format is data:image/[png\|jpeg\|bmp\|webp];base64,[base64 data], where [base64 data] is a Base64 string. \- Strings with the **datashare://** prefix are supported, which are used to access the image path provided by a Data ability. \- Strings with the **file:///data/storage** prefix are supported, which are used to read image resources in the **files** folder in the installation directory of the current application. Ensure that the application has the read permission to the files in the specified path. \- [DrawableDescriptor](../apis/js-apis-arkui-drawableDescriptor.md#drawabledescriptor) objects are supported. - For details, see [Displaying Images](../../ui/arkts-graphics-display.md). **NOTE** - ArkTS widgets support GIF animations, but the animations only play once on display. - ArkTS widgets do not support the strings with the **http://**, **datashare://**, or **file:///data/storage** prefix. - ArkTS widgets do not support the [PixelMap](../apis/js-apis-image.md#pixelmap7) type.|
## Attributes
@@ -50,7 +50,7 @@ In addition to the [universal attributes](ts-universal-attributes-size.md), the
| syncLoad8+ | boolean | Whether to load the image synchronously. By default, the image is loaded asynchronously. During synchronous loading, the UI thread is blocked and the placeholder diagram is not displayed. Default value: **false** Since API version 9, this API is supported in ArkTS widgets.|
| copyOption9+ | [CopyOptions](ts-appendix-enums.md#copyoptions9) | Whether the image can be copied. (SVG images cannot be copied.) When **copyOption** is set to a value other than **CopyOptions.None**, the image can be copied in various manners, such as long pressing, right-clicking, or pressing Ctrl+C. Default value: **CopyOptions.None** This API is supported in ArkTS widgets.|
| colorFilter9+ | [ColorFilter](ts-types.md#colorfilter9) | Color filter of the image. This API is supported in ArkTS widgets. |
-| draggable9+ | boolean | Whether the image is draggable. This attribute cannot be used together with the [onDragStart](ts-universal-events-drag-drop.md) event. Default value: **false** This API is supported in ArkTS widgets.|
+| draggable(deprecated) | boolean | Whether the image is draggable. This attribute cannot be used together with the [onDragStart](ts-universal-events-drag-drop.md) event. Default value: **false** This API is supported in ArkTS widgets. **NOTE** This API is supported since API version 8 and deprecated since API version 10. You are advised to use the universal attribute [draggable](ts-universal-events-drag-drop.md) instead.|
> **NOTE**
>
diff --git a/en/application-dev/reference/arkui-ts/ts-basic-components-progress.md b/en/application-dev/reference/arkui-ts/ts-basic-components-progress.md
index 459984f79d30f81c7d9d276077038972f743a201..ef810a8be61e6dc14a8ccba62714a3f8bbe1b06e 100644
--- a/en/application-dev/reference/arkui-ts/ts-basic-components-progress.md
+++ b/en/application-dev/reference/arkui-ts/ts-basic-components-progress.md
@@ -1,6 +1,6 @@
# Progress
-The **\