diff --git a/zh-cn/application-dev/reference/apis/js-apis-huks.md b/zh-cn/application-dev/reference/apis/js-apis-huks.md new file mode 100644 index 0000000000000000000000000000000000000000..a67f9632fe472a30d118a4ef6ec438af6c281126 --- /dev/null +++ b/zh-cn/application-dev/reference/apis/js-apis-huks.md @@ -0,0 +1,792 @@ +# 通用密钥库系统 + +向应用提供密钥库能力，包括密钥管理及密钥的密码学操作等功能。 + +HUKS所管理的密钥可以由应用导入或者由应用调用HUKS接口生成。 + +## 导入模块 + +```js +import huks from '@ohos.security.huks' +``` +## huks.HuksErrorCode + +表示错误码的枚举 + +| 名称 | 值 | 说明 | +| -------------------------- | ----- | ---- | +| HUKS_SUCCESS | 0 |表示成功| +| HUKS_FAILURE | -1 |表示失败| +| HUKS_ERROR_BAD_STATE | -2 |表示错误的状态| +| HUKS_ERROR_INVALID_ARGUMENT | -3 |表示无效的数据| +| HUKS_ERROR_NOT_SUPPORTED | -4 |表示不支持| +| HUKS_ERROR_NO_PERMISSION | -5 |表示没有许可| +| HUKS_ERROR_INSUFFICIENT_DATA | -6 |表示数据不足| +| HUKS_ERROR_BUFFER_TOO_SMALL | -7 |表示缓冲区太小| +| HUKS_ERROR_INSUFFICIENT_MEMORY | -8 |表示内存不足| +| HUKS_ERROR_COMMUNICATION_FAILURE | -9 |表示通讯失败| +| HUKS_ERROR_STORAGE_FAILURE | -10 |表示存储故障| +| HUKS_ERROR_HARDWARE_FAILURE | -11 |表示硬件故障| +| HUKS_ERROR_ALREADY_EXISTS | -12 |表示已经存在| +| HUKS_ERROR_NOT_EXIST | -13 |表示不存在| +| HUKS_ERROR_NULL_POINTER | -14 |表示空指针| +| HUKS_ERROR_FILE_SIZE_FAIL | -15 |表示文件大小失败| +| HUKS_ERROR_READ_FILE_FAIL | -16 |表示读取文件失败| +| HUKS_ERROR_INVALID_PUBLIC_KEY | -17 |表示无效的公钥| +| HUKS_ERROR_INVALID_PRIVATE_KEY | -18 |表示无效的私钥| +| HUKS_ERROR_INVALID_KEY_INFO | -19 |表示无效的密钥信息| +| HUKS_ERROR_HASH_NOT_EQUAL | -20 |表示哈希不相等| +| HUKS_ERROR_MALLOC_FAIL | -21 |表示MALLOC 失败| +| HUKS_ERROR_WRITE_FILE_FAIL | -22 |表示写文件失败| +| HUKS_ERROR_REMOVE_FILE_FAIL | -23 |表示删除文件失败| +| HUKS_ERROR_OPEN_FILE_FAIL | -24 |表示打开文件失败| +| HUKS_ERROR_CLOSE_FILE_FAIL | -25 |表示关闭文件失败| +| HUKS_ERROR_MAKE_DIR_FAIL | -26 |表示创建目录失败| +| HUKS_ERROR_INVALID_KEY_FILE | -27 |表示无效的密钥文件| +| HUKS_ERROR_IPC_MSG_FAIL | -28 |表示IPC 信息失败| +| HUKS_ERROR_REQUEST_OVERFLOWS | -29 |表示请求溢出| +| HUKS_ERROR_PARAM_NOT_EXIST | -30 |表示参数不存在| +| HUKS_ERROR_CRYPTO_ENGINE_ERROR | -31 |表示CRYPTO ENGINE错误| +| HUKS_ERROR_COMMUNICATION_TIMEOUT | -32 |表示通讯超时| +| HUKS_ERROR_IPC_INIT_FAIL | -33 |表示IPC 初始化失败| +| HUKS_ERROR_IPC_DLOPEN_FAIL | -34 |表示IPC DLOPEN 失败| +| HUKS_ERROR_EFUSE_READ_FAIL | -35 |表示EFUSE 读取失败| +| HUKS_ERROR_NEW_ROOT_KEY_MATERIAL_EXIST | -36 |表示存在新的根密钥材料| +| HUKS_ERROR_UPDATE_ROOT_KEY_MATERIAL_FAIL | -37 |表示更新根密钥材料失败| +| HUKS_ERROR_VERIFICATION_FAILED | -38 |表示验证证书链失败| +| HUKS_ERROR_CHECK_GET_ALG_FAIL | -100 |表示检查获取 ALG 失败| +| HUKS_ERROR_CHECK_GET_KEY_SIZE_FAIL | -101 |表示检查获取密钥大小失败| +| HUKS_ERROR_CHECK_GET_PADDING_FAIL | -102 |表示检查获取填充失败| +| HUKS_ERROR_CHECK_GET_PURPOSE_FAIL | -103 |表示检查获取目的失败| +| HUKS_ERROR_CHECK_GET_DIGEST_FAIL | -104 |表示检查获取摘要失败| +| HUKS_ERROR_CHECK_GET_MODE_FAIL | -105 |表示检查获取模式失败| +| HUKS_ERROR_CHECK_GET_NONCE_FAIL | -106 |表示检查获取随机数失败| +| HUKS_ERROR_CHECK_GET_AAD_FAIL | -107 |表示检查获取 AAD 失败| +| HUKS_ERROR_CHECK_GET_IV_FAIL | -108 |表示检查 GET IV 失败| +| HUKS_ERROR_CHECK_GET_AE_TAG_FAIL | -109 |表示检查获取 AE 标记失败| +| HUKS_ERROR_CHECK_GET_SALT_FAIL | -110 |表示检查获取SALT失败| +| HUKS_ERROR_CHECK_GET_ITERATION_FAIL | -111 |表示检查获取迭代失败| +| HUKS_ERROR_INVALID_ALGORITHM | -112 |表示无效的算法| +| HUKS_ERROR_INVALID_KEY_SIZE | -113 |表示无效的密钥大小| +| HUKS_ERROR_INVALID_PADDING | -114 |表示无效的填充| +| HUKS_ERROR_INVALID_PURPOSE | -115 |表示无效的目的| +| HUKS_ERROR_INVALID_MODE | -116 |表示无效模式| +| HUKS_ERROR_INVALID_DIGEST | -117 |表示无效的摘要| +| HUKS_ERROR_INVALID_SIGNATURE_SIZE | -118 |表示签名大小无效| +| HUKS_ERROR_INVALID_IV | -119 |表示无效的 IV| +| HUKS_ERROR_INVALID_AAD | -120 |表示无效的 AAD| +| HUKS_ERROR_INVALID_NONCE | -121 |表示无效的随机数| +| HUKS_ERROR_INVALID_AE_TAG | -122 |表示无效的 AE 标签| +| HUKS_ERROR_INVALID_SALT | -123 |表示无效SALT| +| HUKS_ERROR_INVALID_ITERATION | -124 |表示无效的迭代| +| HUKS_ERROR_INVALID_OPERATION | -125 |表示无效操作| +| HUKS_ERROR_INTERNAL_ERROR | -999 |表示内部错误| +| HUKS_ERROR_UNKNOWN_ERROR | -1000 |表示未知错误| + + +## huks.HuksKeyPurpose + +表示密钥（密钥对）用途 + +| 名称 | 值 | 说明 | +| ------------------------ | ---- | ---------------------------------------- | +| HUKS_KEY_PURPOSE_ENCRYPT | 1 | 表示密钥（密钥对）用于对明文进行加密操作 | +| HUKS_KEY_PURPOSE_DECRYPT | 2 | 表示密钥（密钥对）用于对密文进行解密操作 | +| HUKS_KEY_PURPOSE_SIGN | 4 | 表示密钥对用于对数据进行签名 | +| HUKS_KEY_PURPOSE_VERIFY | 8 | 表示密钥对用于验证签名后的数据 | +| HUKS_KEY_PURPOSE_DERIVE | 16 | 表示密钥用于派生密钥 | +| HUKS_KEY_PURPOSE_WRAP | 32 | | +| HUKS_KEY_PURPOSE_UNWRAP | 64 | | +| HUKS_KEY_PURPOSE_MAC | 128 | 表示密钥用于生成mac消息验证码 | +| HUKS_KEY_PURPOSE_AGREE | 256 | 表示密钥对用于进行密钥协商 | + +## huks.HuksKeyDigest + +表示摘要算法 + +| 名称 | 值 | 说明 | +| ---------------------- | ---- | ---------------------------------------- | +| HUKS_DIGEST_NONE | 0 | 表示无摘要算法 | +| HUKS_DIGEST_MD5 | 1 | 表示MD5摘要算法 | +| HUKS_DIGEST_SHA1 | 10 | 表示SHA1摘要算法 | +| HUKS_DIGEST_SHA224 | 11 | 表示SHA224摘要算法 | +| HUKS_DIGEST_SHA256 | 12 | 表示SHA256摘要算法 | +| HUKS_DIGEST_SHA384 | 13 | 表示SHA384摘要算法 | +| HUKS_DIGEST_SHA512 | 14 | 表示SHA512摘要算法 | + +## huks.HuksKeyPadding + +表示补齐算法 + +| 名称 | 值 | 说明 | +| ---------------------- | ---- | ---------------------------------------- | +| HUKS_PADDING_NONE | 0 | 表示不使用补齐算法 | +| HUKS_PADDING_OAEP | 1 | 表示使用OAEP补齐算法 | +| HUKS_PADDING_PSS | 2 | 表示使用PSS补齐算法 | +| HUKS_PADDING_PKCS1_V1_5 | 3 | 表示使用PKCS1_V1_5补齐算法 | +| HUKS_PADDING_PKCS5 | 4 | 表示使用PKCS5补齐算法 | +| HUKS_PADDING_PKCS7 | 5 | 表示使用PKCS7补齐算法 | + +## huks.HuksCipherMode + +表示加密模式 + +| 名称 | 值 | 说明 | +| ------------- | ---- | ------------------- | +| HUKS_MODE_ECB | 1 | 表示使用ECB加密模式 | +| HUKS_MODE_CBC | 2 | 表示使用CBC加密模式 | +| HUKS_MODE_CTR | 3 | 表示使用CTR加密模式 | +| HUKS_MODE_OFB | 4 | 表示使用OFB加密模式 | +| HUKS_MODE_CCM | 31 | 表示使用CCM加密模式 | +| HUKS_MODE_GCM | 32 | 表示使用GCM加密模式 | + +## huks.HuksKeySize + +表示密钥（密钥对）长度 + +| 名称 | 值 | 说明 | +| ---------------------------- | ---- | ------------------------------------------ | +| HUKS_RSA_KEY_SIZE_512 | 512 | 表示使用RSA算法的密钥对长度为512bit | +| HUKS_RSA_KEY_SIZE_768 | 768 | 表示使用RSA算法的密钥对长度为768bit | +| HUKS_RSA_KEY_SIZE_1024 | 1024 | 表示使用RSA算法的密钥对长度为1024bit | +| HUKS_RSA_KEY_SIZE_2048 | 2048 | 表示使用RSA算法的密钥对长度为2048bit | +| HUKS_RSA_KEY_SIZE_3072 | 3072 | 表示使用RSA算法的密钥对长度为3072bit | +| HUKS_RSA_KEY_SIZE_4096 | 4096 | 表示使用RSA算法的密钥对长度为4096bit | +| HUKS_ECC_KEY_SIZE_224 | 224 | 表示使用ECC算法的密钥对长度为224bit | +| HUKS_ECC_KEY_SIZE_256 | 256 | 表示使用ECC算法的密钥对长度为256bit | +| HUKS_ECC_KEY_SIZE_384 | 384 | 表示使用ECC算法的密钥对长度为384bit | +| HUKS_ECC_KEY_SIZE_521 | 521 | 表示使用ECC算法的密钥对长度为521bit | +| HUKS_AES_KEY_SIZE_128 | 128 | 表示使用AES算法的密钥长度为128bit | +| HUKS_AES_KEY_SIZE_192 | 196 | 表示使用AES算法的密钥长度为196bit | +| HUKS_AES_KEY_SIZE_256 | 256 | 表示使用AES算法的密钥长度为256bit | +| HUKS_AES_KEY_SIZE_512 | 512 | 表示使用AES算法的密钥长度为512bit | +| HUKS_CURVE25519_KEY_SIZE_256 | 256 | 表示使用CURVE25519算法的密钥对长度为256bit | +| HUKS_DH_KEY_SIZE_2048 | 2048 | 表示使用DH算法的密钥对长度为2048bit | +| HUKS_DH_KEY_SIZE_3072 | 3072 | 表示使用DH算法的密钥对长度为3072bit | +| HUKS_DH_KEY_SIZE_4096 | 4096 | 表示使用DH算法的密钥对长度为4096bit | + +## huks.HuksKeyAlg + +表示密钥使用的算法 + +| 名称 | 值 | 说明 | +| ---------------- | ---- | ------------------- | +| HUKS_ALG_RSA | 1 | 表示使用RSA算法 | +| HUKS_ALG_ECC | 2 | 表示使用ECC算法 | +| HUKS_ALG_DSA | 3 | 表示使用DSA算法 | +| HUKS_ALG_AES | 20 | 表示使用AES算法 | +| HUKS_ALG_HMAC | 50 | 表示使用HMAC算法 | +| HUKS_ALG_HKDF | 51 | 表示使用HKDF算法 | +| HUKS_ALG_PBKDF2 | 52 | 表示使用PBKDF2算法 | +| HUKS_ALG_ECDH | 100 | 表示使用ECDH算法 | +| HUKS_ALG_X25519 | 101 | 表示使用X25519算法 | +| HUKS_ALG_ED25519 | 102 | 表示使用ED25519算法 | +| HUKS_ALG_DH | 103 | 表示使用DH算法 | + +## huks.HuksKeyGenerateType + +表示生成密钥的类型 + +| 名称 | 值 | 说明 | +| ------------------------------ | ---- | -------------- | +| HUKS_KEY_GENERATE_TYPE_DEFAULT | 0 | 默认生成的密钥 | +| HUKS_KEY_GENERATE_TYPE_DERIVE | 1 | 派生生成的密钥 | +| HUKS_KEY_GENERATE_TYPE_AGREE | 2 | 协商生成的密钥 | + +## huks.HuksKeyFlag + +表示密钥的产生方式 + +| 名称 | 值 | 说明 | +| -------------------------- | ---- | ------------------------------ | +| HUKS_KEY_FLAG_IMPORT_KEY | 1 | 表示通过导入公钥接口导入的密钥 | +| HUKS_KEY_FLAG_GENERATE_KEY | 2 | 表示通过生成密钥接口生成的密钥 | +| HUKS_KEY_FLAG_AGREE_KEY | 3 | 表示通过生成密钥协商接口生成的密钥 | +| HUKS_KEY_FLAG_DERIVE_KEY | 4 | 表示通过生成密钥派生接口生成的密钥 | + +## huks.HuksKeyStorageType + +表示密钥存储方式 + +| 名称 | 值 | 说明 | +| ----------------------- | ---- | ---------------------------- | +| HUKS_STORAGE_TEMP | 0 | 表示通过本地直接管理密钥 | +| HUKS_STORAGE_PERSISTENT | 1 | 表示通过HUKS service管理密钥 | + +## huks.HuksSendType + +| 名称 | 值 | 说明 | +| -------------------- | ---- | ---- | +| HUKS_SEND_TYPE_ASYNC | 0 | | +| HUKS_SEND_TYPE_SYNC | 1 | | + +## huks.HuksTagType + +表示Tag的数据类型 + +| 名称 | 值 | 说明 | +| --------------------- | ------- | ------------------------------- | +| HUKS_TAG_TYPE_INVALID | 0 << 28 | 表示非法的Tag类型 | +| HUKS_TAG_TYPE_INT | 1 << 28 | 表示该Tag的数据类型为number | +| HUKS_TAG_TYPE_UINT | 2 << 28 | 表示该Tag的数据类型为number | +| HUKS_TAG_TYPE_ULONG | 3 << 28 | 表示该Tag的数据类型为bigint | +| HUKS_TAG_TYPE_BOOL | 4 << 28 | 表示该Tag的数据类型为boolean | +| HUKS_TAG_TYPE_BYTES | 5 << 28 | 表示该Tag的数据类型为Uint8Array | + +## huks.HuksTag + +表示调用参数的Tag + +| 名称 | 值 | 说明 | +| -------------------------------------- | ---------------------------------------- | ----------------------------- | +| HUKS_TAG_INVALID | HuksTagType.HUKS_TAG_TYPE_INVALID \| 0 | 表示非法的Tag | +| HUKS_TAG_ALGORITHM | HUKS_TAG_TYPE_UINT \| 1 | 表示算法的Tag | +| HUKS_TAG_PURPOSE | HuksTagType.HUKS_TAG_TYPE_UINT \| 2 | 表示密钥（密钥对）用途的Tag | +| HUKS_TAG_KEY_SIZE | HuksTagType.HUKS_TAG_TYPE_UINT \| 3 | 表示密钥（密钥对）长度的Tag | +| HUKS_TAG_DIGEST | HuksTagType.HUKS_TAG_TYPE_UINT \| 4 | 表示摘要算法的Tag | +| HUKS_TAG_PADDING | HuksTagType.HUKS_TAG_TYPE_UINT \| 5 | 表示补齐算法的Tag | +| HUKS_TAG_BLOCK_MODE | HuksTagType.HUKS_TAG_TYPE_UINT \| 6 | 表示加密模式的Tag | +| HUKS_TAG_KEY_TYPE | HuksTagType.HUKS_TAG_TYPE_UINT \| 7 | 表示密钥类型的Tag | +| HUKS_TAG_ASSOCIATED_DATA | HuksTagType.HUKS_TAG_TYPE_BYTES \| 8 | 表示表示附加身份验证数据的Tag | +| HUKS_TAG_NONCE | HuksTagType.HUKS_TAG_TYPE_BYTES \| 9 | 表示表示密钥偏移量的Tag | +| HUKS_TAG_IV | HuksTagType.HUKS_TAG_TYPE_BYTES \| 10 | 表示表示密钥偏移量的Tag | +| HUKS_TAG_INFO | HuksTagType.HUKS_TAG_TYPE_BYTES \| 11 | | +| HUKS_TAG_SALT | HuksTagType.HUKS_TAG_TYPE_BYTES \| 12 | | +| HUKS_TAG_PWD | HuksTagType.HUKS_TAG_TYPE_BYTES \| 13 | | +| HUKS_TAG_ITERATION | HuksTagType.HUKS_TAG_TYPE_UINT \| 14 | | +| HUKS_TAG_KEY_GENERATE_TYPE | HuksTagType.HUKS_TAG_TYPE_UINT \| 15 | 表示生成密钥类型的Tag | +| HUKS_TAG_DERIVE_MAIN_KEY | HuksTagType.HUKS_TAG_TYPE_BYTES \| 16 | | +| HUKS_TAG_DERIVE_FACTOR | HuksTagType.HUKS_TAG_TYPE_BYTES \| 17 | | +| HUKS_TAG_DERIVE_ALG | HuksTagType.HUKS_TAG_TYPE_UINT \| 18 | | +| HUKS_TAG_AGREE_ALG | HuksTagType.HUKS_TAG_TYPE_UINT \| 19 | | +| HUKS_TAG_AGREE_PUBLIC_KEY_IS_KEY_ALIAS | HuksTagType.HUKS_TAG_TYPE_BOOL \| 20 | | +| HUKS_TAG_AGREE_PRIVATE_KEY_ALIAS | HuksTagType.HUKS_TAG_TYPE_BYTES \| 21 | | +| HUKS_TAG_AGREE_PUBLIC_KEY | HuksTagType.HUKS_TAG_TYPE_BYTES \| 22 | | +| HUKS_TAG_KEY_ALIAS | HuksTagType.HUKS_TAG_TYPE_BYTES \| 23 | | +| HUKS_TAG_DERIVE_KEY_SIZE | HuksTagType.HUKS_TAG_TYPE_UINT \| 24 | | +| HUKS_TAG_ACTIVE_DATETIME | HuksTagType.HUKS_TAG_TYPE_ULONG \| 201 | | +| HUKS_TAG_ORIGINATION_EXPIRE_DATETIME | HuksTagType.HUKS_TAG_TYPE_ULONG \| 202 | | +| HUKS_TAG_USAGE_EXPIRE_DATETIME | HuksTagType.HUKS_TAG_TYPE_ULONG \| 203 | | +| HUKS_TAG_CREATION_DATETIME | HuksTagType.HUKS_TAG_TYPE_ULONG \| 204 | | +| HUKS_TAG_ALL_USERS | ksTagType.HUKS_TAG_TYPE_BOOL \| 301 | | +| HUKS_TAG_USER_ID | HuksTagType.HUKS_TAG_TYPE_UINT \| 302 | | +| HUKS_TAG_NO_AUTH_REQUIRED | HuksTagType.HUKS_TAG_TYPE_BOOL \| 303 | | +| HUKS_TAG_USER_AUTH_TYPE | HuksTagType.HUKS_TAG_TYPE_UINT \| 304 | | +| HUKS_TAG_AUTH_TIMEOUT | HuksTagType.HUKS_TAG_TYPE_UINT \| 305 | | +| HUKS_TAG_AUTH_TOKEN | HuksTagType.HUKS_TAG_TYPE_BYTES \| 306 | | +| HUKS_TAG_ATTESTATION_CHALLENGE | HuksTagType.HUKS_TAG_TYPE_BYTES \| 501 | | +| HUKS_TAG_ATTESTATION_APPLICATION_ID | HuksTagType.HUKS_TAG_TYPE_BYTES \| 502 | | +| HUKS_TAG_ATTESTATION_ID_BRAND | HuksTagType.HUKS_TAG_TYPE_BYTES \| 503 | | +| HUKS_TAG_ATTESTATION_ID_DEVICE | HuksTagType.HUKS_TAG_TYPE_BYTES \| 504 | | +| HUKS_TAG_ATTESTATION_ID_PRODUCT | HuksTagType.HUKS_TAG_TYPE_BYTES \| 505 | | +| HUKS_TAG_ATTESTATION_ID_SERIAL | HuksTagType.HUKS_TAG_TYPE_BYTES \| 506 | | +| HUKS_TAG_ATTESTATION_ID_IMEI | HuksTagType.HUKS_TAG_TYPE_BYTES \| 507 | | +| HUKS_TAG_ATTESTATION_ID_MEID | HuksTagType.HUKS_TAG_TYPE_BYTES \| 508 | | +| HUKS_TAG_ATTESTATION_ID_MANUFACTURER | HuksTagType.HUKS_TAG_TYPE_BYTES \| 509 | | +| HUKS_TAG_ATTESTATION_ID_MODEL | HuksTagType.HUKS_TAG_TYPE_BYTES \| 510 | | +| HUKS_TAG_ATTESTATION_ID_ALIAS | HuksTagType.HUKS_TAG_TYPE_BYTES \| 511 | | +| HUKS_TAG_ATTESTATION_ID_SOCID | HuksTagType.HUKS_TAG_TYPE_BYTES \| 512 | | +| HUKS_TAG_ATTESTATION_ID_UDID | HuksTagType.HUKS_TAG_TYPE_BYTES \| 513 | | +| HUKS_TAG_ATTESTATION_ID_SEC_LEVEL_INFO | HuksTagType.HUKS_TAG_TYPE_BYTES \| 514 | | +| HUKS_TAG_ATTESTATION_ID_VERSION_INFO | HuksTagType.HUKS_TAG_TYPE_BYTES \| 515 | | +| HUKS_TAG_IS_KEY_ALIAS | HuksTagType.HUKS_TAG_TYPE_BOOL \| 1001 | 表示是否使用密钥别名的Tag | +| HUKS_TAG_KEY_STORAGE_FLAG | HuksTagType.HUKS_TAG_TYPE_UINT \| 1002 | 表示密钥存储方式的Tag | +| HUKS_TAG_IS_ALLOWED_WRAP | HuksTagType.HUKS_TAG_TYPE_BOOL \| 1003 | | +| HUKS_TAG_KEY_WRAP_TYPE | HuksTagType.HUKS_TAG_TYPE_UINT \| 1004 | | +| HUKS_TAG_KEY_AUTH_ID | HuksTagType.HUKS_TAG_TYPE_BYTES \| 1005 | | +| HUKS_TAG_KEY_ROLE | HuksTagType.HUKS_TAG_TYPE_UINT \| 1006 | | +| HUKS_TAG_KEY_FLAG | HuksTagType.HUKS_TAG_TYPE_UINT \| 1007 | 表示密钥标志的Tag | +| HUKS_TAG_IS_ASYNCHRONIZED | HuksTagType.HUKS_TAG_TYPE_UINT \| 1008 | | +| HUKS_TAG_SECURE_KEY_ALIAS | HuksTagType.HUKS_TAG_TYPE_BOOL \| 1009 | | +| HUKS_TAG_SECURE_KEY_UUID | HuksTagType.HUKS_TAG_TYPE_BYTES \| 1010 | | +| HUKS_TAG_KEY_DOMAIN | HuksTagType.HUKS_TAG_TYPE_UINT \| 1011 | | +| HUKS_TAG_PROCESS_NAME | HuksTagType.HUKS_TAG_TYPE_BYTES \| 10001 | 表示进程名称的Tag | +| HUKS_TAG_PACKAGE_NAME | HuksTagType.HUKS_TAG_TYPE_BYTES \| 10002 | | +| HUKS_TAG_ACCESS_TIME | HuksTagType.HUKS_TAG_TYPE_UINT \| 10003 | | +| HUKS_TAG_USES_TIME | HuksTagType.HUKS_TAG_TYPE_UINT \| 10004 | | +| HUKS_TAG_CRYPTO_CTX | HuksTagType.HUKS_TAG_TYPE_ULONG \| 10005 | | +| HUKS_TAG_KEY | HuksTagType.HUKS_TAG_TYPE_BYTES \| 10006 | | +| HUKS_TAG_KEY_VERSION | HuksTagType.HUKS_TAG_TYPE_UINT \| 10007 | 表示密钥版本的Tag | +| HUKS_TAG_PAYLOAD_LEN | HuksTagType.HUKS_TAG_TYPE_UINT \| 10008 | | +| HUKS_TAG_AE_TAG | HuksTagType.HUKS_TAG_TYPE_BYTES \| 10009 | | +| HUKS_TAG_IS_KEY_HANDLE | HuksTagType.HUKS_TAG_TYPE_ULONG \| 10010 | | +| HUKS_TAG_OS_VERSION | HuksTagType.HUKS_TAG_TYPE_UINT \| 10101 | 表示操作系统版本的Tag | +| HUKS_TAG_OS_PATCHLEVEL | HuksTagType.HUKS_TAG_TYPE_UINT \| 10102 | 表示操作系统补丁级别的Tag | +| HUKS_TAG_SYMMETRIC_KEY_DATA | HuksTagType.HUKS_TAG_TYPE_BYTES \| 20001 | | +| HUKS_TAG_ASYMMETRIC_PUBLIC_KEY_DATA | HuksTagType.HUKS_TAG_TYPE_BYTES \| 20002 | | +| HUKS_TAG_ASYMMETRIC_PRIVATE_KEY_DATA | HuksTagType.HUKS_TAG_TYPE_BYTES \| 20003 | | + +## huks.generateKey + +function generateKey(keyAlias: string, options: HuksOptions, callback: AsyncCallback) : void; + +生成密钥（密钥对） + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------- | ---- | -------------------------------------------------- | +| keyAlias | string | 是 | 密钥别名 | +| options | HuksOptions | 是 | 用于存放生成key所需TAG | +| callback | AsyncCallback | 是 | 返回HUKS_SUCCESS时表示接口使用成功，其他时为错误。 | + +**示例：** + +```js +var alias = 'alias; +var properties = new Array(); +properties[0] = { + tag: huks.HuksTag.HUKS_TAG_ALGORITHM, + value: huksHukssKeyAlg.HUKS_ALG_RSA +}; +properties[1] = { + tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, + value: huks.HuksKeySize.HUKS_RSA_KEY_SIZE_512 +}; +properties[2] = { + tag: huks.HuksTag.HUKS_TAG_PURPOSE, + value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_ENCRYPT | huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_DECRYPT +}; +properties[3] = { + tag: huks.HuksTag.HUKS_TAG_PADDING, + value: huks.HuksKeyPadding.HUKS_PADDING_NONE +}; +properties[4] = { + tag: huks.HuksTag.HUKS_TAG_BLOCK_MODE, + value: huks.HuksCipherMode.HUKS_MODE_ECB +}; +properties[5] = { + tag: huks.HuksTag.HUKS_TAG_DIGEST, + value: huks.HuksKeyDigest.HUKS_DIGEST_NONE +}; +var options = { + properties: properties +}; +huks.generateKey(alias, options, function (err, data){}); +``` +## huks.generateKey + +function generateKey(keyAlias: string, options: HuksOptions) : Promise; + +生成密钥（密钥对） + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ----------- | ---- | ---------------------- | +| keyAlias | string | 是 | 密钥别名 | +| options | HuksOptions | 是 | 用于存放生成key所需TAG | + +**返回值**：（可选，如不涉及可删除） + +| 类型 | 说明 | +| -------------------- | -------------------------------------------------- | +| Promise\ | 返回HUKS_SUCCESS时表示接口使用成功，其他时为错误。 | + +**示例：** + +```js +var alias = 'alias'; +var properties = new Array(); +properties[0] = { + tag: huks.HuksTag.HUKS_TAG_ALGORITHM, + value: huksHuksKeyAlg.HUKS_ALG_RSA +}; +properties[1] = { + tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, + value: huks.HuksKeySize.HUKS_RSA_KEY_SIZE_512 +}; +properties[2] = { + tag: huks.HuksTag.HUKS_TAG_PURPOSE, + value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_ENCRYPT | huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_DECRYPT +}; +properties[3] = { + tag: huks.HuksTag.HUKS_TAG_PADDING, + value: huks.HuksKeyPadding.HUKS_PADDING_NONE +}; +properties[4] = { + tag: huks.HuksTag.HUKS_TAG_BLOCK_MODE, + value: huks.HuksCipherMode.HUKS_MODE_ECB +}; +properties[5] = { + tag: huks.HuksTag.HUKS_TAG_DIGEST, + value: huks.HuksKeyDigest.HUKS_DIGEST_NONE +}; +var options = { + properties: properties +}; +var result = await huks.generateKey(alias, options); +``` + +## huks.deleteKey + +function deleteKey(keyAlias: string, options: HuksOptions, callback: AsyncCallback) : void; + +删除密钥 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------- | ---- | ----------------------------------------------------- | +| keyAlias | string | 是 | keyAlias为密钥别名，密钥别名应为生成key时传入的别名。 | +| options | HuksOptions | 是 | 空对象。 | +| callback | AsyncCallback | 是 | 返回HUKS_SUCCESS时表示接口使用成功，其他时为错误。 | + +**示例：** + +```js +var alias = 'alias'; +var emptyOptions = { + properties: [] +}; +huks.deleteKey(alias, emptyOptions, function (err, data) {}); +``` + +## huks.deleteKey + +function deleteKey(keyAlias: string, options: HuksOptions) : Promise; + +删除密钥。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ----------- | ---- | ----------------------------------------------------- | +| keyAlias | string | 是 | keyAlias为密钥别名，密钥别名应为生成key时传入的别名。 | +| options | HuksOptions | 是 | 空对象。 | + +**返回值：** + +| 类型 | 说明 | +| ------------------- | -------------------------------------------------- | +| Promise | 返回HUKS_SUCCESS时表示接口使用成功，其他时为错误。 | + +**示例：** + +```js +var alias = 'alias'; +var emptyOptions = { + properties: [] +}; +var result = await huks.deleteKey(alias, emptyOptions); +``` + +## huks.getSdkVersion + +function getSdkVersion(options: HuksOptions) : string; + +获取当前系统sdk版本 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ---------- | ---- | ------------------------- | +| options | HuksOptions | 是 | 空对象，用于存放sdk版本。 | + +**返回值：** + +| 类型 | 说明 | +| ------ | ----------- | +| string | 返回sdk版本 | + +**示例：** + +```js +var emptyOptions = { + properties: [] +}; +var result = await huks.getSdkVersion(emptyOptions); +``` + +## huks.importKey + +function importKey(keyAlias: string, options: HuksOptions, callback: AsyncCallback) : void; + +导入密钥对 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------ | ---- | ------------------------------------------------- | +| keyAlias | string | 是 | keyAlias为密钥别名用于存放所需密钥。 | +| options | HuksOptions | 是 | 用于导入时所需TAG和需要导入的密钥。 | +| callback | AsyncCallback | 是 | 返回HUKS_SUCCESS时表示接口使用成功，其他时为错误。 | + +**示例：** + +```js +var keyAlias = 'keyAlias'; +var properties = new Array(); +properties[0] = { + tag: huks.HuksTag.HUKS_TAG_ALGORITHM, + value: huks.HuksKeyAlg.HUKS_ALG_DSA +}; +properties[1] = { + tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, + value: 1024 +}; +properties[2] = { + tag: huks.HuksTag.HUKS_TAG_PURPOSE, + value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_VERIFY +}; +properties[3] = { + tag: huks.HuksTag.HUKS_TAG_PADDING, + value: huks.HuksKeyPadding.HUKS_PADDING_NONE +}; +properties[4] = { + tag: huks.HuksTag.HUKS_TAG_DIGEST, + value: HUKS_DIGEST_SHA1 +}; +var options = { + properties: properties, + inData: importText +}; +huks.importKey(keyAlias, options, function (err, data){}); +``` + +## huks.importKey + +function importKey(keyAlias: string, options: HuksOptions) : Promise; + +导入密钥对 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ----------- | ---- | ------------------------------------ | +| keyAlias | string | 是 | keyAlias为密钥别名用于存放所需密钥。 | +| options | HuksOptions | 是 | 用于导入时所需TAG和需要导入的密钥。 | + +**返回值：** + +| 类型 | 说明 | +| ------------------- | -------------------------------------------------- | +| Promise | 返回HUKS_SUCCESS时表示接口使用成功，其他时为错误。 | + +**示例：** + +```js +var keyAlias = 'keyAlias'; +var properties = new Array(); +properties[0] = { + tag: huks.HuksTag.HUKS_TAG_ALGORITHM, + value: huks.HuksKeyAlg.HUKS_ALG_DSA +}; +properties[1] = { + tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, + value: 1024 +}; +properties[2] = { + tag: huks.HuksTag.HUKS_TAG_PURPOSE, + value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_VERIFY +}; +properties[3] = { + tag: huks.HuksTag.HUKS_TAG_PADDING, + value: huks.HuksKeyPadding.HUKS_PADDING_NONE +}; +properties[4] = { + tag: huks.HuksTag.HUKS_TAG_DIGEST, + value: HUKS_DIGEST_SHA1 +}; +var options = { + properties: properties, + inData: importText +}; +var result = await huks.importKey(keyAlias, options); +``` + +## huks.exportKey + +function exportKey(keyAlias: string, options: HuksOptions, callback: AsyncCallback) : void; + +导出密钥对 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------- | ---- | ------------------------------------------------------------ | +| keyAlias | string | 是 | keyAlias为密钥别名，且密钥别名应与所用密钥生成时使用的别名相同。 | +| options | HuksOptions | 是 | 空对象。 | +| callback | AsyncCallback | 是 | 返回HUKS_SUCCESS时表示接口使用成功，其他时为错误。outData：返回从密钥中导出的公钥 | + +**示例：** + +```js +var keyAlias = 'keyAlias'; +var emptyOptions = { + properties: [] +}; +huks.exportKey(keyAlias, emptyOptions, function (err, data){}); +``` + +## huks.exportKey + +function exportKey(keyAlias: string, options: HuksOptions) : Promise; + +导出密钥对 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ----------- | ---- | ------------------------------------------------------------ | +| keyAlias | string | 是 | keyAlias为密钥别名，且密钥别名应与所用密钥生成时使用的别名相同。 | +| options | HuksOptions | 是 | 空对象。 | + +**返回值：** + +| 类型 | 说明 | +| ------------------- | ------------------------------------------------------------ | +| Promise | 返回HUKS_SUCCESS时表示接口使用成功，其他时为错误。outData：返回从密钥中导出的公钥 | + +**示例：** + +```js +var keyAlias = 'keyAlias'; +var emptyOptions = { + properties: [] +}; +var result = await huks.exportKey(keyAlias, emptyOptions); +``` + +## huks.getKeyProperties + +function getKeyProperties(keyAlias: string, options: HuksOptions, callback: AsyncCallback) : void; + +获取密钥属性 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------- | ---- | ------------------------------------------------------------ | +| keyAlias | string | 是 | keyAlias为密钥别名，且密钥别名应与所用密钥生成时使用的别名相同。 | +| options | HuksOptions | 是 | 空对象。 | +| callback | AsyncCallback | 是 | errorCode：返回HUKS_SUCCESS时表示接口使用成功，其他时为错误properties：返回值为从密钥别名中导出的生成密钥时所需参数 | + +**示例：** + +```js +var keyAlias = 'keyAlias'; +var emptyOptions = { + properties: [] +}; +huks.getKeyProperties(keyAlias, emptyOptions, function (err, data){}); +``` + +## huks.getKeyProperties + +function getKeyProperties(keyAlias: string, options: HuksOptions) : Promise; + +获取密钥属性 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ----------- | ---- | ------------------------------------------------------------ | +| keyAlias | string | 是 | keyAlias为密钥别名，且密钥别名应与所用密钥生成时使用的别名相同。 | +| options | HuksOptions | 是 | 空对象。 | + +**返回值：** + +| 类型 | 说明 | +| ------------------ | ------------------------------------------------------------ | +| Promise | errorCode：返回HUKS_SUCCESS时表示接口使用成功，其他时为错误。properties：返回值为从密钥别名中导出的生成密钥时所需参数 | + +**示例：** + +```js +var keyAlias = 'keyAlias'; +var emptyOptions = { + properties: [] +}; +var result = await huks.getKeyProperties(keyAlias, emptyOptions); +``` + +## huks.isKeyExist + +function isKeyExist(keyAlias: string, options: HuksOptions, callback: AsyncCallback) : void; + +判断密钥是否存在 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------- | ---- | ------------------------------------- | +| keyAlias | string | 是 | keyAlias为所需查找的密钥的别名。 | +| options | HuksOptions | 是 | 空对象。 | +| callback | AsyncCallback | 是 | FALSE代表密钥不存在，TRUE代表密钥存在 | + +**示例：** + +```js +var keyAlias = 'keyAlias'; +var emptyOptions = { + properties: [] +}; +huks.isKeyExist(keyAlias, emptyOptions, function (err, data){}); +``` + +## huks.isKeyExist + +function isKeyExist(keyAlias: string, options: HuksOptions) : Promise; + +判断密钥是否存在 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ----------- | ---- | -------------------------------- | +| keyAlias | string | 是 | keyAlias为所需查找的密钥的别名。 | +| options | HuksOptions | 是 | 空对象。 | + +**返回值：** + +| 类型 | 说明 | +| ---------------- | ------------------------------------- | +| Promise | FALSE代表密钥不存在，TRUE代表密钥存在 | + +**示例：** + +```js +var keyAlias = 'keyAlias'; +var emptyOptions = { + properties: [] +}; +var result = await huks.isKeyExist(keyAlias, emptyOptions); +``` + + +## huks.HuksParam + +调用接口使用的options中的properties数组中的param + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ----------------------------------- | ---- | ---------- | +| tag | HuksTag | 是 | 标签 | +| value | boolean\|number\|bigint\|Uint8Array | 是 | 标签对应值 | + +## huks.HuksOptions + +调用接口使用的options + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ---------- | ---------------- | ---- | ---------------------- | +| properties | Array | 否 | 属性,存HuksParam的数组 | +| inData | Uint8Array | 否 | 输入数据 | + +## huks.HuksResult + +调用接口返回的result + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ---------- | ---------------- | ---- | -------- | +| errorCode | number | 是 | 错误码 | +| outData | Uint8Array | 否 | 输出数据 | +| properties | Array | 否 | 属性 | +| certChains | Array | 否 | 证书链 | + diff --git a/zh-cn/application-dev/security/Readme-CN.md b/zh-cn/application-dev/security/Readme-CN.md index 604a2c0dbfb42236a8525d1e1256940c2bc2311f..6bb7f91359726bdd96c070f8128eca14167fc7eb 100644 --- a/zh-cn/application-dev/security/Readme-CN.md +++ b/zh-cn/application-dev/security/Readme-CN.md @@ -4,4 +4,7 @@ - [用户认证开发概述](userauth-overview.md) - [用户认证开发指导](userauth-guidelines.md) - Hap包签名工具 - - [Hap包签名工具开发指南](hapsigntool_guidelines.md) \ No newline at end of file + - [Hap包签名工具开发指南](hapsigntool_guidelines.md) +- 密钥管理 + - [密钥管理开发概述](huks-overview.md) + - [密钥管理开发指导](huks-guidelines.md) \ No newline at end of file diff --git a/zh-cn/application-dev/security/huks-guidelinest.md b/zh-cn/application-dev/security/huks-guidelinest.md new file mode 100755 index 0000000000000000000000000000000000000000..e277913c7e75a6458a5e7f9e85089077e106ae26 --- /dev/null +++ b/zh-cn/application-dev/security/huks-guidelinest.md @@ -0,0 +1,154 @@ +# HUKS开发指南 + +## 场景介绍 + + HUKS（OpenHarmony Universal KeyStore，OpenHarmony通用密钥库系统）向应用提供密钥库能力，包括密钥管理及密钥的密码学操作等功能。HUKS所管理的密钥可以由应用导入或者由应用调用HUKS接口生成。 + + +## 接口说明 + +| 接口名 | 描述 | +| ------------------------------------------------------------ | ---------------- | +| function generateKey(keyAlias: string, options: HuksOptions, callback: AsyncCallback) : void; | 生成密钥/密钥对 | +| function generateKey(keyAlias: string, options: HuksOptions) : Promise; | 生成密钥/密钥对 | +| function exportKey(keyAlias: string, options: HuksOptions, callback: AsyncCallback) : void; | 导出公钥 | +| function exportKey(keyAlias: string, options: HuksOptions) : Promise; | 导出公钥 | +| function isKeyExist(keyAlias: string, options: HuksOptions, callback: AsyncCallback) : void; | 查询密钥是否存在 | +| function isKeyExist(keyAlias: string, options: HuksOptions) : Promise; | 查询密钥是否存在 | +| function deleteKey(keyAlias: string, options: HuksOptions, callback: AsyncCallback) : void; | 删除密钥 | +| function deleteKey(keyAlias: string, options: HuksOptions) : Promise; | 删除密钥 | + +## 开发步骤 + +1. 引入HUKS模块 + + ```js + import huks from '@ohos.security.huks' + ``` + +2. 使用generateKey接口生成密钥对。 + + keyAlias为生成的密钥别名，options为生成密钥时使用到的参数，需根据具体需要到的算法设定options中的参数。 + + generateKey接口会返回密钥的生成是否成功。 + + ```js + var alias = 'testAlias'; + var properties = new Array(); + properties[0] = { + tag: huks.HuksTag.HUKS_TAG_ALGORITHM, + value: huks.HuksKeyAlg.HUKS_ALG_ECC + }; + properties[1] = { + tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, + value: huks.HuksKeySize.HUKS_ECC_KEY_SIZE_224 + }; + properties[2] = { + tag: huks.HuksTag.HUKS_TAG_PURPOSE, + value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_AGREE + }; + properties[3] = { + tag: huks.HuksTag.HUKS_TAG_DIGEST, + value: huks.HuksKeyDigest.HUKS_DIGEST_NONE + }; + var options = { + properties: properties + } + var resultA = await huks.generateKey(alias, options); + ``` + +3. 使用isKeyExist接口查询密钥是否已经存在。 + keyAlias为要查询的密钥的别名，options为空对象。 + isKeyExist接口会返回密钥是否存在。 + + ```js + var keyAlias = 'keyAlias'; + var emptyOptions = { + properties: [] + }; + var result = await huks.isKeyExist(keyAlias, emptyOptions); + ``` + +4. 使用exportKey接口导出密钥。 + keyAlias为要导出的密钥的别名，options为空对象。 + exportKey接口会返回导出密钥是否成功。 + + ```js + var keyAlias = 'keyAlias'; + var emptyOptions = { + properties: [] + }; + var result = await huks.exportKey(keyAlias, emptyOptions); + ``` + +5. 使用importKey接口导入密钥。 + keyAlias为密钥别名用于存放所需密钥，options为用于导入时所需TAG和需要导入的密钥。 + importKey接口会返回导入密钥是否成功。 + + ```js + var keyAlias = 'keyAlias'; + var properties = new Array(); + properties[0] = { + tag: huks.HuksTag.HUKS_TAG_ALGORITHM, + value: huks.HuksKeyAlg.HUKS_ALG_DSA + }; + properties[1] = { + tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, + value: 1024 + }; + properties[2] = { + tag: huks.HuksTag.HUKS_TAG_PURPOSE, + value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_VERIFY + }; + properties[3] = { + tag: huks.HuksTag.HUKS_TAG_PADDING, + value: huks.HuksKeyPadding.HUKS_PADDING_NONE + }; + properties[4] = { + tag: huks.HuksTag.HUKS_TAG_DIGEST, + value: HUKS_DIGEST_SHA1 + }; + var options = { + properties: properties, + inData: importText + }; + var result = await huks.importKey(keyAlias, options); + ``` + +6. 使用getKeyProperties接口获取密钥属性。 + keyAlias为要查询的密钥的别名，options为空对象。 + deleteKey接口会返回获取密钥属性是否成功。 + + ```js + var keyAlias = 'keyAlias'; + var emptyOptions = { + properties: [] + }; + var result = await huks.getKeyProperties(keyAlias, emptyOptions); + ``` + +7. 使用getSdkVersion接口获取当前系统sdk版本。 + + + ```js + var keyAlias = 'keyAlias'; + var emptyOptions = { + properties: [] + }; + var result = await huks.getSdkVersion(keyAlias, emptyOptions); + ``` + +8. 使用deleteKey接口删除密钥。 + keyAlias为要查询的密钥的别名，options为空对象。 + deleteKey接口会返回删除密钥是否成功。 + + ```js + var alias = 'alias'; + var emptyOptions = { + properties: [] + }; + var result = await huks.deleteKey(alias, emptyOptions); + ``` + + + diff --git a/zh-cn/application-dev/security/huks-overview.md b/zh-cn/application-dev/security/huks-overview.md new file mode 100755 index 0000000000000000000000000000000000000000..cd050c759e48c5055a7c1b94ab272d939c19f22a --- /dev/null +++ b/zh-cn/application-dev/security/huks-overview.md @@ -0,0 +1,65 @@ +# HUKS概述 + +### 功能简介 + +OpenHarmony HUKS是安全子系统中的密钥管理子系统，它将明文与密文相互转化。密钥分为对称密钥和非对称密钥。HUKS具有以下特点： + +- 模块化与能力增强，具体包括：密码算法三段式实现，HAL层模块化编译抽象化以及Ability模块化； +- HUKS支持多用户访问隔离； +- HUKS支持APP UID访问隔离。 + +## 基本概念 + +HUKS：支持密钥业务开发，提供加解密、签名验签、派生、协商、HMAC相关的功能，主要包括AES加解密、RSA加解密、RSA签名验签、ECC签名验签、DSA签名验签、ED25519签名验签、PBKDF2派生、DH协商、ECDH协商、X25519协商。且有openssl和mbedtls两个算法库可调用。 + +在进行应用开发前，开发者应了解以下基本概念： + +##### 加解密： + +- 加密是发送方利用接收方的公钥对要发送的明文进行加密； + +- 解密是接收方利用自己的私钥进行解密。 + +##### 签名验签： + +- 签名是发送方用一个哈希函数从报文文本中生成报文摘要，然后用自己的私钥对这个摘要进行加密，得到的就是这个报文对应的数字签名； +- 验签是接收方得到原始报文和数字签名后，用同一个哈希函数从报文中生成摘要A，另外用发送方提供的公钥对数字签名进行解密，得到摘要B，对比A和B是否相同，就可以得知报文有没有被篡改过。 + +##### 派生： + +- 密钥派生是它的功能从一个密钥产生出一个或多个密钥。 + +##### 协商： + +- 两个或多个实体协商，共同建立会话密钥，任何一个参与者均对结果产生影响，不需要任何可信的第三方。 + +##### HMAC： + +- 密钥相关的哈希运算消息认证码。 + +## 运作机制 + +密钥的三段式操作基于init、update、final调用。 + +**init：**密钥初始化，包括读取密钥，并加载到HUKS Core中解密，然后为密钥创建一个session密钥处理，返回一个session id给调用者。 + +**update**：传递待处理的数据给HUKS； + +按数据大小分： + +- 当传递数据小于等于64K时，由update一次性传递完； +- 当传递数据大于64K，则由update分段循环传递。 + +按算法分类： + +- 当算法为协商和派生时，则由update分段循环传递； +- 当算法为加解密、签名验签、HMAC时，则由update分段循环传递。 + +**finish**：当所有数据传递给HUKS处理后，调用finish结束掉这一次密钥处理session，释放资源，同时也会清除掉HUKS Core中init时候加载的密钥 + +**abort**：当init、update、finish其中任一阶段发生错误时，需要调用abort来终止密钥的使用。 + +## 约束与限制 + +- init 之前必须先generatekey； +- 严格按照init、update、finish的运行机制执行，除了发生错误时调用abort。 \ No newline at end of file diff --git a/zh-cn/device-dev/security/Readme-CN.md b/zh-cn/device-dev/security/Readme-CN.md index 4c79f16371fde366048aa441e1b85e2325b523f5..29a9593d313ff9bab5cdf8c4ed606050e7563355 100755 --- a/zh-cn/device-dev/security/Readme-CN.md +++ b/zh-cn/device-dev/security/Readme-CN.md @@ -2,4 +2,6 @@ - [隐私保护](security-privacy-protection.md) - [安全指南](security-guidelines-overall.md) +# 密钥管理 +- [密钥管理](huks-overview.md) diff --git a/zh-cn/device-dev/security/huks-overview.md b/zh-cn/device-dev/security/huks-overview.md new file mode 100755 index 0000000000000000000000000000000000000000..49ad87075a931a076c9e90d29e7b87da038423bb --- /dev/null +++ b/zh-cn/device-dev/security/huks-overview.md @@ -0,0 +1,66 @@ +# HUKS概述 + +### 功能简介 + +HUKS（OpenHarmony Universal KeyStore，OpenHarmony通用密钥库系统）向应用提供密钥库能力，包括密钥管理及密钥的密码学操作等功能。HUKS所管理的密钥可以由应用导入或者由应用调用HUKS接口生成。HUKS具有以下特点： + +- 模块化与能力增强，具体包括：密码算法三段式实现，HAL层模块化编译抽象化以及Ability模块化； +- HUKS支持多用户访问隔离； +- HUKS支持APP UID访问隔离。 + +## 基本概念 + +HUKS：支持密钥业务开发，提供加解密、签名验签、派生、协商、HMAC相关的功能，主要包括AES加解密、RSA加解密、RSA签名验签、ECC签名验签、DSA签名验签、ED25519签名验签、PBKDF2派生、DH协商、ECDH协商、X25519协商。目前软实现有openssl和mbedtls两个算法库可调用。 + +在进行应用开发前，开发者应了解以下基本概念： + +##### 加解密： + +- 加密是发送方利用接收方的公钥对要发送的明文进行加密； + +- 解密是接收方利用自己的私钥进行解密。 + +##### 签名验签： + +- 签名是发送方用一个哈希函数从报文文本中生成报文摘要，然后用自己的私钥对这个摘要进行加密，得到的就是这个报文对应的数字签名； +- 验签是接收方得到原始报文和数字签名后，用同一个哈希函数从报文中生成摘要A，另外用发送方提供的公钥对数字签名进行解密，得到摘要B，对比A和B是否相同，就可以得知报文有没有被篡改过。 + +##### 派生： + +- 密钥派生是它的功能从一个密钥产生出一个或多个密钥。 + +##### 协商： + +- 两个或多个实体协商，共同建立会话密钥，任何一个参与者均对结果产生影响，不需要任何可信的第三方。 + +##### HMAC： + +- 密钥相关的哈希运算消息认证码。 + +## 运作机制 + +密钥的三段式操作基于init、update、final调用。 + +**init：**密钥初始化，包括读取密钥，并加载到HUKS Core中解密，然后为密钥创建一个session密钥处理，返回一个session id给调用者。 + +**update**：传递待处理的数据给HUKS； + +按数据大小分： + +- 当传递数据小于等于64K时，由update一次性传递完； +- 当传递数据大于64K，则由update分段循环传递。 + +按算法分类： + +- 当算法为协商和派生时，则由update分段循环传递； +- 当算法为加解密、签名验签、HMAC时，则由update分段循环传递。 + +**finish**：当所有数据传递给HUKS处理后，调用finish结束掉这一次密钥处理session，释放资源，同时也会清除掉HUKS Core中init时候加载的密钥 + +**abort**：当init、update、finish其中任一阶段发生错误时，需要调用abort来终止密钥的使用。 + +## 约束与限制 + +- init 之前必须先generatekey； +- 严格按照init、update、finish的运行机制执行，除了发生错误时调用abort。 +- 目前软实现仅支持openssl与mbedtls两个算法库。 \ No newline at end of file