Skip to content

D
Docs

OpenHarmony / Docs
大约 2 年 前同步成功

通知 161
Star 293
Fork 28
D
Docs
未验证 提交 8bfb7239 编写于 作者: O openharmony_ci 提交者： Gitee
浏览文件
操作

!10629 【开发自提单】修改开发指南，新增密钥转换场景及场景说明 

Merge pull request !10629 from wutiantian_gitee/master
上级 c4a85254 9ceeeb8a
隐藏空白更改
内联 并排
Showing with 778 addition and 59 deletion
zh-cn/application-dev/reference/apis/js-apis-cryptoFramework.md
浏览文件 @ 8bfb7239
......@@ -23,7 +23,7 @@ import cryptoFramework from "@ohos.security.cryptoFramework"
| INVALID_PARAMS | 401 | 非法入参。 |
| NOT_SUPPORT | 801 | 操作不支持。 |
| ERR_OUT_OF_MEMORY | 17620001 | 内存错误。 |
| ERR_EXTERNAL_ERROR | 17620002 | 运行时外部错误。 |
| ERR_RUNTIME_ERROR | 17620002 | 运行时外部错误。 |
| ERR_CRYPTO_OPERATION | 17630001 | 调用三方算法库API出错。 |
| ERR_CERT_SIGNATURE_FAILURE | 17630002 | 证书签名验证错误。 |
| ERR_CERT_NOT_YET_VALID | 17630003 | 证书尚未生效。 |
......@@ -916,7 +916,7 @@ promiseGenerateRand.then(randData => {
| ------- | ------ | ---- | ---- | ---------------------- |
| iv | [DataBlob](#datablob) | 是 | 是 | 指明加解密参数iv，长度为12字节|
| aad | [DataBlob](#datablob) | 是 | 是 | 指明加解密参数aad，长度为8字节|
| authTag | [DataBlob](#datablob) | 是 | 是 | 指明加解密参数authTag，长度为16字节。<br/>采用GCM模式加密时，需要获取[doFinal()](#dofinal-2)输出的[DataBlob](#datablob)，将其作为解密时[GcmParamsSpec](#gcmparamsspec)中的authTag|
| authTag | [DataBlob](#datablob) | 是 | 是 | 指明加解密参数authTag，长度为16字节。<br/>采用GCM模式加密时，需要获取[doFinal()](#dofinal-2)输出的[DataBlob](#datablob)，将其末尾16字节作为解密时[GcmParamsSpec](#gcmparamsspec)中的authTag |
## CcmParamsSpec
......@@ -928,7 +928,7 @@ promiseGenerateRand.then(randData => {
| ------- | -------- | ---- | ---- | -------------------------------|
| iv | [DataBlob](#datablob) | 是 | 是 | 指明加解密参数iv，长度为7字节 |
| aad | [DataBlob](#datablob) | 是 | 是 | 指明加解密参数aad，长度为8字节 |
| authTag | [DataBlob](#datablob) | 是 | 是 | 指明加解密参数authTag，长度为12字节。<br/>采用CCM模式加密时，需要获取[doFinal()](#dofinal-2)输出的[DataBlob](#datablob)，将其作为解密时[CcmParamsSpec](#ccmparamsspec)中的authTag |
| authTag | [DataBlob](#datablob) | 是 | 是 | 指明加解密参数authTag，长度为12字节。<br/>采用CCM模式加密时，需要获取[doFinal()](#dofinal-2)输出的[DataBlob](#datablob)，将其末尾12字节作为解密时[CcmParamsSpec](#ccmparamsspec)中的authTag |
## CryptoMode
......@@ -1102,7 +1102,7 @@ key.clearMem();
createSymKeyGenerator(algName : string) : SymKeyGenerator
通过指定算法名称的字符串，获取相应的对称密钥生成器实例。
通过指定算法名称的字符串，获取相应的对称密钥生成器实例。支持的对称密钥参数详见框架概述“[密钥生成规格](../../security/cryptoFramework-overview.md#密钥生成规格)”一节中“生成密钥的字符串”。
**系统能力：** SystemCapability.Security.CryptoFramework
......@@ -1118,6 +1118,13 @@ createSymKeyGenerator(algName : string) : SymKeyGenerator
| ----------------------------------- | -------------------------- |
| [SymKeyGenerator](#symkeygenerator) | 返回对称密钥生成器的对象。 |
**示例：**
```js
import cryptoFramework from '@ohos.security.cryptoFramework';
let symKeyGenerator = cryptoFramework.createSymKeyGenerator('3DES192');
```
## SymKeyGenerator
对称密钥生成器。在使用该类的方法前，需要先使用[createSymKeyGenerator](#cryptoframeworkcreatesymkeygenerator)方法构建一个symKeyGenerator实例。
......@@ -1367,7 +1374,7 @@ keyGenPromise.then( keyPair => {
### convertKey
convertKey(pubKey : DataBlob, priKey : DataBlob, callback : AsyncCallback\<KeyPair\>) : void
异步获取指定数据生成非对称密钥，通过注册回调函数获取结果。
异步获取指定数据生成非对称密钥，通过注册回调函数获取结果。详情请看下方**密钥转换说明**
**系统能力：** SystemCapability.Security.CryptoFramework
......@@ -1397,7 +1404,7 @@ asyKeyGenerator.convertKey(pubKey, priKey, (err, keyPair) => {
### convertKey
convertKey(pubKey : DataBlob, priKey : DataBlob) : Promise\<KeyPair>
异步获取指定数据生成非对称密钥，通过Promise获取结果。
异步获取指定数据生成非对称密钥，通过Promise获取结果。详情请看下方**密钥转换说明**
**系统能力：** SystemCapability.Security.CryptoFramework
......@@ -1428,10 +1435,18 @@ keyGenPromise.then( keyPair => {
});
```
**密钥转换说明**
1. RSA二进制密钥数据，按keysize(32位) ，nsize(keysize/8), esize(e实际长度)，dsize(keysize/8)，nval(大数n的二进制数据)，eval(大数e的二进制数据)，dval(大数d的二进制数据)拼接形成。
2. RSA二进制密钥数据中，nsize和dsize为密钥位数/8，esize为具体的实际长度。
3. RSA私钥数据需要包含keysize，nsize，esize，dsize，nval，eval，dval的全部数据，公钥材料中dsize设置为0，缺省dval的数据。
4. RSA二进制密钥数据中，keysize、nsize、esize和dsize为32位二进制数据，数据的大小端格式请按设备CPU默认格式，密钥材料（nval、eval、dval）统一为大端格式。
5. convertKey接口中，公钥和私钥二进制数据为可选项，可单独传入公钥或私钥的数据，生成对应只包含公钥或私钥的KeyPair对象。
## cryptoFramework.createCipher
createCipher(transformation : string) : Cipher
通过指定算法名称，获取相应的[Cipher](#cipher)实例。
通过指定算法名称，获取相应的[Cipher](#cipher)实例。支持的算法名参数详见框架概述“[加解密规格](../../security/cryptoFramework-overview.md#加解密规格)”一节中的“指定算法名称字符串”。
**系统能力：** SystemCapability.Security.CryptoFramework
......@@ -1465,7 +1480,7 @@ try {
## Cipher
提供加解密的算法操作功能，按序调用本类中的[init()](#init-2)、[update()](#update-4)、[doFinal()](#dofinal-2)方法，可以实现对称加密/对称解密/非对称加密/非对称解密。
提供加解密的算法操作功能，按序调用本类中的[init()](#init-2)、[update()](#update-4)、[doFinal()](#dofinal-2)方法，可以实现对称加密/对称解密/非对称加密/非对称解密。完整的加解密流程示例可参考开发指导中的“[使用加解密操作](../../security/cryptoFramework-guidelines.md#使用加解密操作)”一节。
### 属性
......@@ -1630,7 +1645,7 @@ cipher.update(data).then((output) => {
doFinal(data : DataBlob, callback : AsyncCallback\<DataBlob>) : void
最后结束加密或者解密数据操作，通过注册回调函数获取加密或者解密数据。如果在本次加解密过程中已经使用[update](#update-4)传入过数据，可以在doFinal的data参数处传入null。<br/>根据对称加解密的模式不同，doFinal的输出可能不同。<br/>对于GCM和CCM模式的对称加密，在doFinal完成后需要将其结果暂存作为解密时的authTag。<br/>对于其他模式的对称加解密，存在两种情况（1）update输出一部分加解密结果，doFinal输出剩余加解密结果；（2）update输出加解密结果全部由update输出，doFinal输出空。
最后结束加密或者解密数据操作，通过注册回调函数获取加密或者解密数据。如果在本次加解密过程中已经使用[update](#update-4)传入过数据，可以在doFinal的data参数处传入null。<br/>根据对称加解密的模式不同，doFinal的输出可能不同：<br/>对于GCM和CCM模式的对称加密，doFinal的结果是剩余密文和authTag的拼接，即末尾的16字节（GCM模式）或12字节（CCM模式）是authTag（因此如果doFinal的data参数传入null，则doFinal的结果就是authTag）。在doFinal完成后需要将authTag暂存，填入解密时的[GcmParamsSpec](#gcmparamsspec)或[CcmParamsSpec](#ccmparamsspec)。<br/>对于其他模式的对称加解密，根据不同的模式特点，存在两种情况（1）update输出一部分加解密结果，doFinal输出剩余加解密结果；（2）加解密结果全部由update输出，doFinal输出空。
**系统能力：** SystemCapability.Security.CryptoFramework
......@@ -1662,7 +1677,7 @@ cipher.doFinal(data, (err, output) => {
doFinal(data : DataBlob) : Promise\<DataBlob>
最后结束加密或者解密数据操作，通过Promise获取结果。如果在本次加解密过程中已经使用update传入过数据，可以在doFinal的data参数处传入null。
最后结束加密或者解密数据操作，通过Promise获取结果。如果在本次加解密过程中已经使用[update](#update-4)传入过数据，可以在doFinal的data参数处传入null。<br/>根据对称加解密的模式不同，doFinal的输出可能不同：<br/>对于GCM和CCM模式的对称加密，doFinal的结果是剩余密文和authTag的拼接，即末尾的16字节（GCM模式）或12字节（CCM模式）是authTag（因此如果doFinal的data参数传入null，则doFinal的结果就是authTag）。在doFinal完成后需要将authTag暂存，填入解密时的[GcmParamsSpec](#gcmparamsspec)或[CcmParamsSpec](#ccmparamsspec)。<br/>对于其他模式的对称加解密，根据不同的模式特点，存在两种情况（1）update输出一部分加解密结果，doFinal输出剩余加解密结果；（2）加解密结果全部由update输出，doFinal输出空。
**系统能力：** SystemCapability.Security.CryptoFramework
......@@ -2183,7 +2198,7 @@ createX509Cert(inStream : EncodingBlob, callback : AsyncCallback\<X509Cert>) : v
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------------- | ---- | ------------------ |
| inStream | EncodingBlob | 是 | X509证书序列化数据 |
| inStream | [EncodingBlob](#encodingblob) | 是 | X509证书序列化数据 |
| callback | AsyncCallback\<X509Cert> | 否 | 回调函数。表示X509证书对象 |
......@@ -2220,7 +2235,7 @@ createX509Cert(inStream : EncodingBlob) : Promise\<X509Cert>
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------------ | ---- | ------------------ |
| inStream | EncodingBlob | 是 | X509证书序列化数据 |
| inStream | [EncodingBlob](#encodingblob) | 是 | X509证书序列化数据 |
**返回值**：
......@@ -2263,7 +2278,7 @@ verify(key : PubKey, callback : AsyncCallback\<void>) : void
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------------- | ---- | ------------------ |
| key | PubKey | 是 | 用于验签的公钥对象 |
| key | [PubKey](#pubkey) | 是 | 用于验签的公钥对象 |
| callback | AsyncCallback\<void>) | 否 | 回调函数。使用AsyncCallback的第一个error参数判断是否验签成功，error为null表示成功，不为null表示失败 |
......@@ -2309,7 +2324,7 @@ verify(key : PubKey) : Promise\<void>
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------ | ---- | ------------------ |
| key | PubKey | 是 | 用于验签的公钥对象 |
| key | [PubKey](#pubkey) | 是 | 用于验签的公钥对象 |
**返回值**：
......@@ -2355,7 +2370,7 @@ getEncoded(callback : AsyncCallback\<EncodingBlob>) : void
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------------- | ---- | -------- |
| callback | AsyncCallback\<EncodingBlob> | 否 | 回调函数。表示X509证书序列化数据 |
| callback | AsyncCallback\<[EncodingBlob](#encodingblob)> | 否 | 回调函数。表示X509证书序列化数据 |
**示例**：
......@@ -2398,7 +2413,7 @@ getEncoded() : Promise\<EncodingBlob>
| 类型 | 说明 |
| ------------ | ---------------------- |
| Promise\<EncodingBlob> | 表示X509证书序列化数据 |
| Promise\<[EncodingBlob](#encodingblob)> | 表示X509证书序列化数据 |
**示例**：
......@@ -2679,7 +2694,7 @@ getIssuerName() : DataBlob
| 类型 | 说明 |
| -------- | ---------------------- |
| DataBlob | 表示X509证书颁发者名称 |
| [DataBlob](#datablob) | 表示X509证书颁发者名称 |
**示例**：
......@@ -2715,7 +2730,7 @@ getSubjectName() : DataBlob
| 类型 | 说明 |
| -------- | -------------------- |
| DataBlob | 表示X509证书主体名称 |
| [DataBlob](#datablob) | 表示X509证书主体名称 |
**示例**：
......@@ -2823,7 +2838,7 @@ getSignature() : DataBlob
| 类型 | 说明 |
| -------- | -------------------- |
| DataBlob | 表示X509证书签名数据 |
| [DataBlob](#datablob) | 表示X509证书签名数据 |
**示例**：
......@@ -2887,15 +2902,15 @@ cryptoFramework.createX509Cert(encodingBlob, function (error, x509Cert) {
getSignatureAlgOid() : string
表示获取X509证书签名算法OID。
表示获取X509证书签名算法的对象标志符OID(Object Identifier)。OID是由国际标准组织(ISO)的名称注册机构分配。
**系统能力**：SystemCapability.Security.CryptoFramework
**返回值**：
| 类型 | 说明 |
| ------ | ----------------------- |
| string | 表示X509证书签名算法OID |
| 类型 | 说明 |
| ------ | --------------------------------- |
| string | 表示X509证书签名算法对象标志符OID |
**示例**：
......@@ -2931,7 +2946,7 @@ getSignatureAlgParams() : DataBlob
| 类型 | 说明 |
| -------- | ------------------------ |
| DataBlob | 表示X509证书签名算法参数 |
| [DataBlob](#datablob) | 表示X509证书签名算法参数 |
**示例**：
......@@ -2967,7 +2982,7 @@ getKeyUsage() : DataBlob
| 类型 | 说明 |
| -------- | -------------------- |
| DataBlob | 表示X509证书秘钥用途 |
| [DataBlob](#datablob) | 表示X509证书秘钥用途 |
**示例**：
......@@ -3003,7 +3018,7 @@ getExtKeyUsage() : DataArray
| 类型 | 说明 |
| --------- | ------------------------ |
| DataArray | 表示X509证书扩展秘钥用途 |
| [DataArray](#dataarray) | 表示X509证书扩展秘钥用途 |
**示例**：
......@@ -3075,7 +3090,7 @@ getSubjectAltNames() : DataArray
| 类型 | 说明 |
| --------- | ------------------------ |
| DataArray | 表示X509证书主体可选名称 |
| [DataArray](#dataarray) | 表示X509证书主体可选名称 |
**示例**：
......@@ -3111,7 +3126,7 @@ getIssuerAltNames() : DataArray
| 类型 | 说明 |
| --------- | -------------------------- |
| DataArray | 表示X509证书颁发者可选名称 |
| [DataArray](#dataarray) | 表示X509证书颁发者可选名称 |
**示例**：
......@@ -3147,7 +3162,7 @@ createX509Crl(inStream : EncodingBlob, callback : AsyncCallback\<X509Crl>) : voi
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------------- | ---- | -------------------------- |
| inStream | EncodingBlob | 是 | 表示证书吊销列表序列化数据 |
| inStream | [EncodingBlob](#encodingblob) | 是 | 表示证书吊销列表序列化数据 |
| callback | AsyncCallback\<X509Crl> | 否 | 回调函数。表示证书吊销列表对象 |
......@@ -3184,7 +3199,7 @@ createX509Crl(inStream : EncodingBlob) : Promise\<X509Crl>
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------------ | ---- | -------------------------- |
| inStream | EncodingBlob | 是 | 表示证书吊销列表序列化数据 |
| inStream | [EncodingBlob](#encodingblob) | 是 | 表示证书吊销列表序列化数据 |
**返回值**：
......@@ -3227,7 +3242,7 @@ isRevoked(cert : X509Cert, callback : AsyncCallback\<boolean>) : void
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------------- | ---- | -------------------- |
| cert | X509Cert | 是 | 表示被检查的证书对象 |
| cert | [X509Cert](#x509cert) | 是 | 表示被检查的证书对象 |
| callback | AsyncCallback\<boolean> | 否 | 回调函数。表示证书吊销状态，true表示已吊销，false表示未吊销 |
......@@ -3482,7 +3497,7 @@ verify(key : PubKey) : Promise\<void>
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------ | ---- | ---------------------- |
| key | PubKey | 是 | 表示用于验签的公钥对象 |
| key | [PubKey](#pubkey) | 是 | 表示用于验签的公钥对象 |
**返回值**：
......@@ -3564,7 +3579,7 @@ getIssuerName() : DataBlob
| 类型 | 说明 |
| -------- | ------------------------------ |
| DataBlob | 表示X509证书吊销列表颁发者名称 |
| [DataBlob](#datablob) | 表示X509证书吊销列表颁发者名称 |
**示例**：
......@@ -3937,7 +3952,7 @@ getTbsInfo(callback : AsyncCallback\<DataBlob>) : void
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------------- | ---- | -------- |
| callback | AsyncCallback\<DataBlob> | 否 | 回调函数。表示证书吊销列表的tbsCertList信息 |
| callback | AsyncCallback\<[DataBlob](#datablob)> | 否 | 回调函数。表示证书吊销列表的tbsCertList信息 |
**示例**：
......@@ -3980,7 +3995,7 @@ getTbsInfo() : Promise\<DataBlob>
| 类型 | 说明 |
| -------- | --------------------------------- |
| Promise\<DataBlob> | 表示证书吊销列表的tbsCertList信息 |
| Promise\<[DataBlob](#datablob)> | 表示证书吊销列表的tbsCertList信息 |
**示例**：
......@@ -4018,7 +4033,7 @@ getSignature() : DataBlob
| 类型 | 说明 |
| -------- | ------------------------------ |
| DataBlob | 表示X509证书吊销列表的签名数据 |
| [DataBlob](#datablob) | 表示X509证书吊销列表的签名数据 |
**示例**：
......@@ -4082,15 +4097,15 @@ cryptoFramework.createX509Crl(encodingBlob, function (error, x509Crl) {
getSignatureAlgOid() : string
表示获取X509证书吊销列表签名的算法OID。
表示获取X509证书吊销列表签名算法的对象标志符OID(Object Identifier)。OID是由国际标准组织(ISO)的名称注册机构分配。
**系统能力**：SystemCapability.Security.CryptoFramework
**返回值**：
| 类型 | 说明 |
| ------ | ----------------------------------- |
| string | 表示X509证书吊销列表签名的算法OID。 |
| 类型 | 说明 |
| ------ | --------------------------------------------- |
| string | 表示X509证书吊销列表签名算法的对象标志符OID。 |
**示例**：
......@@ -4126,7 +4141,7 @@ getSignatureAlgParams() : DataBlob
| 类型 | 说明 |
| -------- | ---------------------------------- |
| DataBlob | 表示X509证书吊销列表签名的算法参数 |
| [DataBlob](#datablob) | 表示X509证书吊销列表签名的算法参数 |
**示例**：
......@@ -4160,9 +4175,9 @@ createCertChainValidator(algorithm :string) : CertChainValidator
**参数**：
| 参数名 | 类型 | 必填 | 说明 |
| --------- | ------ | ---- | -------------------- |
| algorithm | string | 是 | 表示证书链校验器算法 |
| 参数名 | 类型 | 必填 | 说明 |
| --------- | ------ | ---- | ------------------------------------------ |
| algorithm | string | 是 | 表示证书链校验器算法。当前仅支持输入“PKIX” |
**返回值**：
......@@ -4187,6 +4202,7 @@ let validator = cryptoFramework.createCertChainValidator("PKIX");
validate(certChain : CertChainData, callback : AsyncCallback\<void>) : void
表示校验X509证书链。
由于端侧系统时间不可信，证书链校验不包含对证书有效时间的校验。如果需要检查证书的时间有效性，可使用X509证书的[checkValidityWithDate](#checkvaliditywithdate)方法进行检查。详见[证书规格](../../security/cryptoFramework-overview.md#证书规格)
**系统能力**：SystemCapability.Security.CryptoFramework
......@@ -4194,7 +4210,7 @@ validate(certChain : CertChainData, callback : AsyncCallback\<void>) : void
| 参数名 | 类型 | 必填 | 说明 |
| --------- | ------------- | ---- | ------------------------ |
| certChain | CertChainData | 是 | 表示X509证书链序列化数据 |
| certChain | [CertChainData](#certchaindata) | 是 | 表示X509证书链序列化数据 |
| callback | AsyncCallback\<void> | 否 | 回调函数。使用AsyncCallback的第一个error参数判断是否校验成功，error为null表示成功，error不为null表示失败 |
......@@ -4228,6 +4244,7 @@ validator.validate(certChainData, function (error, data) {
validate(certChain : CertChainData) : Promise\<void>
表示校验X509证书链。
由于端侧系统时间不可信，证书链校验不包含对证书有效时间的校验。如果需要检查证书的时间有效性，可使用X509证书的[checkValidityWithDate](#checkvaliditywithdate)方法进行检查。详见[证书规格](../../security/cryptoFramework-overview.md#证书规格)
**系统能力**：SystemCapability.Security.CryptoFramework
......@@ -4235,7 +4252,7 @@ validate(certChain : CertChainData) : Promise\<void>
| 参数名 | 类型 | 必填 | 说明 |
| --------- | ------------- | ---- | ------------------------ |
| certChain | CertChainData | 是 | 表示X509证书链序列化数据。使用AsyncCallback的第一个error参数判断是否校验成功，error为null表示成功，error不为null表示失败 |
| certChain | [CertChainData](#certchaindata) | 是 | 表示X509证书链序列化数据。 |
**返回值**：
......@@ -4305,7 +4322,7 @@ getEncoded(callback : AsyncCallback\<EncodingBlob>) : void
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------------- | ---- | -------- |
| callback | AsyncCallback\<EncodingBlob> | 否 | 回调函数。表示被吊销证书的序列化数据 |
| callback | AsyncCallback\<[EncodingBlob](#encodingblob)> | 否 | 回调函数。表示被吊销证书的序列化数据 |
**示例**：
......@@ -4336,7 +4353,7 @@ getEncoded() : Promise\<EncodingBlob>
| 类型 | 说明 |
| ------------ | -------------------------- |
| Promise\<EncodingBlob> | 表示被吊销证书的序列化数据 |
| Promise\<[EncodingBlob](#encodingblob)> | 表示被吊销证书的序列化数据 |
**示例**：
......@@ -4388,7 +4405,7 @@ getCertIssuer(callback : AsyncCallback\<DataBlob>) : void
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------------- | ---- | -------- |
| callback | AsyncCallback\<DataBlob> | 否 | 回调函数。表示被吊销证书的颁发者信息 |
| callback | AsyncCallback\<[DataBlob](#datablob)> | 否 | 回调函数。表示被吊销证书的颁发者信息 |
**示例**：
......@@ -4419,7 +4436,7 @@ getCertIssuer() : Promise\<DataBlob>
| 类型 | 说明 |
| -------- | -------------------------- |
| Promise\<DataBlob> | 表示被吊销证书的颁发者信息 |
| Promise\<[DataBlob](#datablob)> | 表示被吊销证书的颁发者信息 |
**示例**：
......
zh-cn/application-dev/security/cryptoFramework-guidelines.md
浏览文件 @ 8bfb7239
# 加解密算法库框架开发指导
> **说明**
>
> 本开发指导基于API version 9，OH SDK版本3.2.7.3，适用于JS语言开发
## 使用密钥对象生成与转换操作
**场景说明**
使用密钥生成操作中，典型的场景有：
1. 随机生成算法库密钥对象。该对象可用于后续的加解密等操作。
2. 根据指定数据生成算法库密钥对象（也就是将外部或存储的二进制数据转换为算法库的密钥对象）。该对象可用于后续的加解密等操作。
3. 获取算法库密钥对象的二进制数据，用于存储或传输。
> **说明**：密钥对象Key包括对称密钥SymKey和非对称密钥（公钥PubKey和私钥PriKey），其中公钥和私钥组成密钥对KeyPair。密钥之间的具体关系可参考[接口声明](../reference/apis/js-apis-cryptoFramework.md)。
**接口及参数说明**
详细接口说明可参考[API参考](../reference/apis/js-apis-cryptoFramework.md)。
以上场景涉及的常用接口如下表所示：
|实例名|接口名|描述|
|---|---|---|
|cryptoFramework|createAsyKeyGenerator(algName : string) : AsyKeyGenerator|根据algName设置的非对称密钥规格，创建非对称密钥生成器对象|
|cryptoFramework|createSymKeyGenerator(algName : string) : SymKeyGenerator|根据algName设置的对称密钥规格，创建对称密钥生成器对象|
|AsyKeyGenerator|generateKeyPair(callback : AsyncCallback\<KeyPair>) : void|使用callback方式，随机生成非对称密钥对象KeyPair|
|AsyKeyGenerator|generateKeyPair() : Promise\<KeyPair>|使用Promise方式，随机生成非对称密钥对象KeyPair|
|SymKeyGenerator|generateSymKey(callback : AsyncCallback\<SymKey>) : void|使用callback方式，随机生成对称密钥对象SymKey|
|SymKeyGenerator|generateSymKey() : Promise\<SymKey>|使用Promise方式，随机生成对称密钥对象SymKey|
| AsyKeyGenerator | convertKey(pubKey : DataBlob, priKey : DataBlob, callback : AsyncCallback\<KeyPair>) : void | 使用callback方式，根据指定的公钥和私钥二进制数据生成KeyPair对象<br/>（允许公钥/私钥为null，即只传入单一公钥或私钥，生成只携带公钥或私钥的KeyPair对象） |
| AsyKeyGenerator | convertKey(pubKey : DataBlob, priKey : DataBlob) : Promise\<KeyPair> | 使用Promise方式，根据指定的公钥和私钥二进制数据生成KeyPair对象<br/>（允许公钥/私钥为null，即只传入单一公钥或私钥，生成只携带公钥或私钥的KeyPair对象） |
| SymKeyGenerator | convertKey(key : DataBlob, callback : AsyncCallback\<SymKey>) : void| 使用callback方式，根据指定的二进制数据，生成对称密钥对象SymKey |
| SymKeyGenerator |convertKey(pubKey : DataBlob, priKey : DataBlob) : Promise\<KeyPair>| 使用Promise方式，根据指定的二进制数据，生成对称密钥对象SymKey |
| Key | getEncoded() : DataBlob; | 获取Key密钥对象的二进制数据（Key的子类实例包括对称密钥SymKey、公钥PubKey、私钥PriKey） |
**开发步骤**
示例1：随机生成非对称密钥KeyPair，并获得二进制数据（场景1、3）
1. 创建非对称密钥生成器；
2. 通过非对称密钥生成器随机生成非对称密钥；
3. 获取密钥对象的二进制数据；
以使用Promise方式随机生成RSA密钥（1024位，素数个数为2）为例：
```javascript
import cryptoFramework from '@ohos.security.cryptoFramework';
function generateAsyKey() {
// 创建非对称密钥生成器
let rsaGenerator = cryptoFramework.createAsyKeyGenerator("RSA1024|PRIMES_2");
// 通过非对称密钥生成器，随机生成非对称密钥
let keyGenPromise = rsaGenerator.generateKeyPair();
keyGenPromise.then( keyPair => {
globalKeyPair = keyPair;
let pubKey = globalKeyPair.pubKey;
let priKey = globalKeyPair.priKey;
// 获取非对称密钥的二进制数据
pkBlob = pubKey.getEncoded();
skBlob = priKey.getEncoded();
AlertDialog.show({ message : "pk bin data" + pkBlob.data} );
AlertDialog.show({ message : "sk bin data" + skBlob.data} );
})
}
```
示例2：随机生成对称密钥SymKey，并获得二进制数据（场景1、3）
1. 创建对称密钥生成器；
2. 通过对称密钥生成器随机生成对称密钥；
3. 获取算法库密钥对象的二进制数据；
以使用Promise方式随机生成AES密钥（256位）为例：
```javascript
import cryptoFramework from '@ohos.security.cryptoFramework';
// 字节流以16进制输出
function uint8ArrayToShowStr(uint8Array) {
return Array.prototype.map
.call(uint8Array, (x) => ('00' + x.toString(16)).slice(-2))
.join('');
}
function testGenerateAesKey() {
// 创建对称密钥生成器
let symKeyGenerator = cryptoFramework.createSymKeyGenerator('AES256');
// 通过密钥生成器随机生成对称密钥
let promiseSymKey = symKeyGenerator.generateSymKey();
promiseSymKey.then( key => {
// 获取对称密钥的二进制数据，输出长度为256bit的字节流
let encodedKey = key.getEncoded();
console.info('key hex:' + uint8ArrayToShowStr(encodedKey.data));
})
}
```
示例3：根据指定的RSA非对称密钥二进制数据，生成KeyPair对象（场景2）
1. 获取RSA二进制密钥数据封装成DataBlob对象，按keysize(32位) 、nsize(keysize/8)、 esize(e实际长度)、dsize(keysize/8)、nval(大数n的二进制数据)、eval(大数e的二进制数据)和dval(大数d的二进制数据)拼接形成。
2. 调用convertKey方法，传入公钥二进制和私钥二进制（二者非必选项，可只传入其中一个），转换为KeyPair对象。
```javascript
import cryptoFramework from '@ohos.security.cryptoFramework';
function convertAsyKey() {
let rsaGenerator = cryptoFramework.createAsyKeyGenerator("RSA1024");
// 公钥二进制数据
let pkval = new Uint8Array([0,4,0,0,128,0,0,0,3,0,0,0,0,0,0,0,182,22,137,81,111,129,17,47,33,97,67,85,251,53,127,42,130,150,93,144,129,104,14,73,110,189,138,82,53,74,114,86,24,186,143,65,87,110,237,69,206,207,5,81,24,32,41,160,209,125,162,92,0,148,49,241,235,0,71,198,1,28,136,106,152,22,25,249,77,241,57,149,154,44,200,6,0,83,246,63,162,106,242,131,80,227,143,162,210,28,127,136,123,172,26,247,2,194,16,1,100,122,180,251,57,22,69,133,232,145,107,66,80,201,151,46,114,175,116,57,45,170,188,77,86,230,111,45,1,0,1]);
// 封装成DataBlob对象
let pkBlob = {data : pkval};
// 调用密钥转换函数
let convertKeyPromise = rsaGenerator.convertKey(pkBlob, null);
convertKeyPromise.then( keyPair => {
if (keyPair == null) {
AlertDialog.show({message : "Convert keypair fail"});
}
AlertDialog.show({message : "Convert KeyPair success"});
})
}
```
**说明**
1. nsize和dsize为密钥位数/8，esize为具体的实际长度。
2. 私钥材料需要包含keysize，nsize，esize，dsize，nval，eval，dval的全部数据，公钥材料中dsize设置为为0，缺省dval的数据。
3. 公钥和私钥二进制数据为可选项，可单独传入公钥或私钥的数据，生成对应只包含公钥或私钥的KeyPair对象。
4. keysize、nsize、esize和dsize为32位二进制数据，数据的大小端格式请按设备CPU默认格式，密钥材料（nval、eval、dval）统一为大端格式。
示例4：根据指定的ECC非对称密钥二进制数据，生成KeyPair对象（场景2、3）
1. 获取ECC二进制密钥数据，封装成DataBlob对象。
2. 调用convertKey方法，传入公钥二进制和私钥二进制（二者非必选项，可只传入其中一个），转换为KeyPair对象。
```javascript
function convertEccAsyKey() {
let pubKeyArray = new Uint8Array([4,196,55,233,100,227,224,38,38,5,128,81,53,112,129,7,59,189,116,105,182,87,190,85,31,248,172,116,213,7,206,85,190,65,169,193,138,173,232,187,74,54,78,251,29,131,192,223,251,227,170,138,80,7,98,193,216,168,235,114,255,188,70,134,104]);
let priKeyArray = new Uint8Array([255,70,89,220,189,19,41,157,175,173,83,60,74,216,195,96,24,181,231,23,112,247,150,126,15,155,24,79,33,97,31,225]);
let pubKeyBlob = { data: pubKeyArray };
let priKeyBlob = { data: priKeyArray };
let generator = cryptoFrameWork.createAsyKeyGenerator("ECC256");
generator.convertKey(pubKeyBlob, priKeyBlob, (error, data) => {
if (error) {
AlertDialog.show({message : "Convert keypair fail"});
}
AlertDialog.show({message : "Convert KeyPair success"});
})
}
```
示例5：根据指定的对称密钥二进制数据，生成SymKey对象（场景2、3）
1. 创建对称密钥生成器；
2. 通过对称密钥生成器，根据指定的对称密钥二进制数据，生成SymKey对象；
3. 获取算法库密钥对象的二进制数据；
以使用callback方式生成3DES密钥（3DES密钥只能为192位）为例：
```javascript
import cryptoFramework from '@ohos.security.cryptoFramework';
// 字节流以16进制输出
function uint8ArrayToShowStr(uint8Array) {
return Array.prototype.map
.call(uint8Array, (x) => ('00' + x.toString(16)).slice(-2))
.join('');
}
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};
}
function testConvertAesKey() {
// 生成对称密钥生成器
let symKeyGenerator = cryptoFramework.createSymKeyGenerator('3DES192');
// 根据用户指定的数据，生成对称密钥
let keyMaterialBlob = genKeyMaterialBlob();
try {
symKeyGenerator.convertKey(keyMaterialBlob, (error, key) => {
if (error) { // 业务逻辑执行错误通过callback的第一个参数返回错误信息
console.error(`convertKey error, ${error.code}, ${error.message}`);
return;
}
console.info(`key algName: ${key.algName}`);
console.info(`key format: ${key.format}`);
let encodedKey = key.getEncoded(); // 获取对称密钥的二进制数据，输出长度为192bit的字节流
console.info('key getEncoded hex: ' + uint8ArrayToShowStr(encodedKey.data));
})
} catch (error) { // 参数检查的错误以同步的方式立即抛出异常
console.error(`convertKey failed, ${error.code}, ${error.message}`);
return;
}
}
```
## 使用加解密操作
**场景说明**
使用加解密操作中，典型的场景有：
在数据存储或传输场景中，可以使用加解密操作用于保证数据的机密性，防止敏感数据泄露。使用加解密操作中，典型的场景有：
1. 使用对称密钥的加解密操作
2. 使用非对称密钥的加解密操作
......@@ -26,9 +229,9 @@
示例1：使用对称密钥的加解密操作
1. 生成对称密钥生成器。
1. 创建对称密钥生成器。
2. 通过密钥生成器生成对称密钥。
3. 生成加解密生成器。
3. 创建加解密生成器。
4. 通过加解密生成器加密或解密数据。
以AES GCM以Promise方式加解密为例：
......@@ -345,7 +548,8 @@ function encryptMessageCallback() {
## 使用签名验签操作
**场景说明**
使用签名验签操作中，典型的场景有：
当需要判断接收的数据是否被篡改且是否为指定对象发送的数据时，可以使用签名验签操作。使用签名验签操作中，典型的场景有：
1. 使用RSA签名验签操作
2. 使用ECC签名验签操作
......@@ -375,9 +579,9 @@ function encryptMessageCallback() {
示例1：使用RSA签名验签操作
1. 生成RSA密钥。通过createAsyKeyGenerator接口创建AsyKeyGenerator对象，并生成RSA非对称密钥。
2. 生成Sign对象。通过createSign接口创建Sign对象，执行初始化操作并设置签名私钥。
3. 执行签名操作。通过Sign类提供的update接口，添加签名数据，并调用doFinal接口生成数据的签名。
3. 执行签名操作。通过Sign类提供的update接口，添加签名数据，并调用sign接口生成数据的签名。
4. 生成Verify对象。通过createVerify接口创建Verify对象，执行初始化操作并设置验签公钥。
5. 执行验签操作。通过Verify类提供的update接口，添加签名数据，并调用doFinal接口传入签名进行验签。
5. 执行验签操作。通过Verify类提供的update接口，添加签名数据，并调用verify接口传入签名进行验签。
```javascript
import cryptoFramework from "@ohos.security.cryptoFramework"
......@@ -545,6 +749,8 @@ function verifyMessageCallback() {
**场景说明**
用户指定摘要算法（如SHA256）生成Md实例，并输入单段或多段需要摘要的信息，进行摘要计算更新，并返回消息摘要计算结果，在指定算法后可获取当前算法名与摘要计算长度（字节）
使用摘要操作的主要场景为：
用户指定摘要算法（如SHA256）生成Md实例，并输入单段或多段需要摘要的信息，进行摘要计算更新，并返回消息摘要计算结果，在指定算法后可获取当前算法名与摘要计算长度（字节）
......@@ -647,9 +853,9 @@ function doMdByCallback(algName) {
**场景说明**
使用签名验签操作中，典型的场景有：
使用密钥协商操作中，典型的场景有：
使用ECDH操作。
通信双方可以在一个公开的信道上通过相互传送一些消息，共同建立一个安全的共享秘密密钥。
**接口及参数说明**
......@@ -714,7 +920,9 @@ function ecdhCallback() {
**场景说明**
使用消息认证码操作的主要场景为：
消息认证码操作主要应用于身份认证的场景：
Mac(message authentication code)可以对消息进行完整性校验，通过使用双方共享的密钥，识别出信息伪装篡改等行为
用户指定摘要算法（如SHA256）生成消息认证码Mac实例，输入对称密钥初始化Mac，并传入单段或多段需要摘要的信息，进行消息认证码计算，并获取消息认证码计算结果，在指定算法后可获取当前算法名与消息认证码计算长度（字节）。
......@@ -915,3 +1123,497 @@ function doRandByCallback(len) {
});
}
```
## 使用证书操作
**场景说明**
使用证书操作中，典型的场景有：
1. 解析X509证书数据生成证书对象。
2. 获取证书信息，比如：证书版本、证书序列号等。
3. 获取证书对象的序列化数据。
4. 获取证书公钥。
5. 证书验签。
6. 校验证书有效期。
**接口及参数说明**
详细接口说明可参考[API参考](../reference/apis/js-apis-cryptoFramework.md)。
以上场景涉及的常用接口如下表所示：
| 实例名 | 接口名 | 描述 |
| --------------- | ------------------------------------------------------------ | -------------------------------------------- |
| cryptoFramework | createX509Cert(inStream : EncodingBlob, callback : AsyncCallback<X509Cert>) : void | 使用callback方式解析X509证书数据生成证书对象 |
| cryptoFramework | createX509Cert(inStream : EncodingBlob) : Promise<X509Cert> | 使用promise方式解析X509证书数据生成证书对象 |
| X509Cert | verify(key : PubKey, callback : AsyncCallback<void>) : void | 使用callback方式进行证书验签 |
| X509Cert | verify(key : PubKey) : Promise<void> | 使用promise方式进行证书验签 |
| X509Cert | getEncoded(callback : AsyncCallback<EncodingBlob>) : void | 使用callback方式获取证书序列化数据 |
| X509Cert | getEncoded() : Promise<EncodingBlob> | 使用promise方式获取证书序列化数据 |
| X509Cert | getPublicKey(callback : AsyncCallback<PubKey>) : void | 使用callback方式获取证书公钥 |
| X509Cert | getPublicKey() : Promise<PubKey> | 使用Promise方式获取证书公钥 |
| X509Cert | checkValidityWithDate(date: string, callback : AsyncCallback<void>) : void | 使用callback方式校验证书有效期 |
| X509Cert | checkValidityWithDate(date: string) : Promise<void> | 使用Promise方式校验证书有效期 |
| X509Cert | getVersion() : number | 获取证书版本 |
| X509Cert | getSerialNumber() : number | 获取证书序列号 |
| X509Cert | getIssuerName() : DataBlob | 获取证书颁发者名称 |
| X509Cert | getSubjectName() : DataBlob | 获取证书主体名称 |
| X509Cert | getNotBeforeTime() : string | 获取证书有效期起始时间 |
| X509Cert | getNotAfterTime() : string | 获取证书有效期截至时间 |
| X509Cert | getSignature() : DataBlob | 获取证书签名 |
| X509Cert | getSignatureAlgName() : string | 获取证书签名算法名称 |
| X509Cert | getSignatureAlgOid() : string | 获取证书签名算法OID |
| X509Cert | getSignatureAlgParams() : DataBlob | 获取证书签名算法参数 |
| X509Cert | getKeyUsage() : DataBlob | 获取证书秘钥用途 |
| X509Cert | getExtKeyUsage() : DataArray | 获取证书扩展秘钥用途 |
| X509Cert | getBasicConstraints() : number | 获取证书基本约束 |
| X509Cert | getSubjectAltNames() : DataArray | 获取证书主体可选名称 |
| X509Cert | getIssuerAltNames() : DataArray | 获取证书颁发者可选名称 |
**开发步骤**
示例：解析X509证书数据生成证书对象，并调用对象方法（包含场景1-6）
```javascript
import cryptoFramework from '@ohos.security.cryptoFramework';
// 证书数据，此处仅示例，业务需根据场景自行设置
let certData = "-----BEGIN CERTIFICATE-----\n"
+ "IBzTCCAXCgAwIBAgIGAXKnMKNyMAwGCCqBHM9VAYN1BQAwSTELMAkGA1UEBhMC\n"
+ "04xDjAMBgNVBAoTBUdNU1NMMRAwDgYDVQQLEwdQS0kvU00yMRgwFgYDVQQDEw9S\n"
+ "290Q0EgZm9yIFRlc3QwIhgPMjAxNTEyMzExNjAwMDBaGA8yMDM1MTIzMDE2MDAw\n"
+ "FowSTELMAkGA1UEBhMCQ04xDjAMBgNVBAoTBUdNU1NMMRAwDgYDVQQLEwdQS0kv\n"
+ "00yMRgwFgYDVQQDEw9Sb290Q0EgZm9yIFRlc3QwWTATBgcqhkjOPQIBBggqgRzP\n"
+ "QGCLQNCAATj+apYlL+ddWXZ7+mFZXZJGbcJFXUN+Fszz6humeyWZP4qEEr2N0+a\n"
+ "dwo/21ft232yo0jPLzdscKB261zSQXSoz4wPDAZBgNVHQ4EEgQQnGnsD7oaOcWv\n"
+ "CTrspwSBDAPBgNVHRMBAf8EBTADAQH/MA4GA1UdDwEB/wQEAwIAxjAMBggqgRzP\n"
+ "QGDdQUAA0kAMEYCIQCEnW5BlQh0vmsOLxSoXYc/7zs++wWyFc1tnBHENR4ElwIh\n"
+ "I1Lwu6in1ruflZhzseWulXwcITf3bm/Y5X1g1XFWQUH\n"
+ "-----END CERTIFICATE-----\n";
// string转Uint8Array
function stringToUint8Array(str) {
var arr = [];
for (var i = 0, j = str.length; i < j; i++) {
arr.push(str.charCodeAt(i));
}
return new Uint8Array(arr);
}
// 证书示例
function certSample() {
let encodingBlob = {
// 将string类型证书数据转为Uint8Array
data: stringToUint8Array(certData),
// 证书格式：支持PEM和DER，此例中对应PEM
encodingFormat: cryptoFramework.EncodingFormat.FORMAT_PEM
};
// 创建证书对象
cryptoFramework.createX509Cert(encodingBlob, function (err, x509Cert) {
if (err != null) {
// 创建证书对象失败
Console.log("createX509Cert failed, errCode: " + err.code + ", errMsg: " + err.message);
return;
}
// 创建证书对象成功
Console.log("createX509Cert success");
// 获取证书版本
let version = x509Cert.getVersion();
// 获取证书对象的序列化数据
x509Cert.getEncoded(function (err, data) {
if (err != null) {
// 获取序列化数据失败
Console.log("getEncoded failed, errCode: " + err.code + ", errMsg: " + err.message);
} else {
// 获取序列化数据成功
Console.log("getEncoded success");
}
});
// 获取证书公钥对象
x509Cert.getPublicKey(function (err, pubKey) {
if (err != null) {
// 获取证书公钥失败
Console.log("getPublicKey failed, errCode: " + err.code + ", errMsg: " + err.message);
} else {
// 获取证书公钥成功
Console.log("getPublicKey success");
}
});
// 业务需通过上级证书对象或本证书对象(自签名)的getPublicKey接口获取公钥对象，此处省略
let pubKey = null;
// 证书验签
x509Cert.verify(pubKey, function (err, data) {
if (err == null) {
// 验签成功
Console.log("verify success");
} else {
// 验签失败
Console.log("verify failed, errCode: " + err.code + ", errMsg: " + err.message);
}
});
// 时间字符串
let date = "150527000001Z";
// 校验证书有效期
x509Cert.checkValidityWithDate(date, function (err, data) {
if (err != null) {
// 证书有效期校验失败
Console.log("checkValidityWithDate failed, errCode: " + err.code + ", errMsg: " + err.message);
} else {
// 证书有效期校验成功
Console.log("checkValidityWithDate success");
}
});
});
}
```
## 使用证书吊销列表操作
**场景说明**
使用证书吊销列表操作中，典型的场景有：
1. 解析X509证书吊销列表数据生成吊销列表对象。
2. 获取证书吊销列表信息，比如：证书吊销列表版本、证书吊销列表类型等。
3. 获取证书吊销列表对象的序列化数据。
4. 检查证书是否被吊销。
5. 证书吊销列表验签。
6. 获取被吊销证书。
**接口及参数说明**
详细接口说明可参考[API参考](../reference/apis/js-apis-cryptoFramework.md)。
以上场景涉及的常用接口如下表所示：
| 实例名 | 接口名 | 描述 |
| --------------- | ------------------------------------------------------------ | ------------------------------------------------------------ |
| cryptoFramework | createX509Crl(inStream : EncodingBlob, callback : AsyncCallback<X509Crl>) : void | 使用callback方式解析X509证书吊销列表数据生成证书吊销列表对象 |
| cryptoFramework | createX509Crl(inStream : EncodingBlob) : Promise<X509Crl> | 使用promise方式解析X509证书吊销列表数据生成证书吊销列表对象 |
| X509Crl | isRevoked(cert : X509Cert, callback : AsyncCallback<boolean>) : void | 使用callback方式检查证书是否被吊销 |
| X509Crl | isRevoked(cert : X509Cert) : Promise<boolean> | 使用promise方式检查证书是否被吊销 |
| X509Crl | getType() : string | 获取证书吊销列表类型 |
| X509Crl | getEncoded(callback : AsyncCallback<EncodingBlob>) : void | 使用callback方式获取证书吊销列表序列化数据 |
| X509Crl | getEncoded() : Promise<EncodingBlob> | 使用promise方式获取证书吊销列表序列化数据 |
| X509Crl | verify(key : PubKey, callback : AsyncCallback<void>) : void | 使用callback方式进行证书吊销列表验签 |
| X509Crl | verify(key : PubKey) : Promise<void> | 使用Promise方式进行证书吊销列表验签 |
| X509Crl | getVersion() : number | 获取证书吊销列表版本 |
| X509Crl | getIssuerName() : DataBlob | 获取证书吊销列表颁发者名称 |
| X509Crl | getLastUpdate() : string | 获取证书吊销列表lastUpdate日期 |
| X509Crl | getNextUpdate() : string | 获取证书吊销列表nextUpdate日期 |
| X509Crl | getRevokedCert(serialNumber : number, callback : AsyncCallback<X509CrlEntry>) : void | 使用callback方式通过序列号获取证书吊销列表中的被吊销证书 |
| X509Crl | getRevokedCert(serialNumber : number) : Promise<X509CrlEntry> | 使用Promise方式通过序列号获取证书吊销列表中的被吊销证书 |
| X509Crl | getRevokedCertWithCert(cert : X509Cert, callback : AsyncCallback<X509CrlEntry>) : void | 使用callback方式通过X509证书获取证书吊销列表中的被吊销证书 |
| X509Crl | getRevokedCertWithCert(cert : X509Cert) : Promise<X509CrlEntry> | 使用Promise方式通过X509证书获取证书吊销列表中的被吊销证书 |
| X509Crl | getRevokedCerts(callback : AsyncCallback<Array<X509CrlEntry>>) : void | 使用callback方式获取证书吊销列表的所有被吊销证书 |
| X509Crl | getRevokedCerts() : Promise<Array<X509CrlEntry>> | 使用Promise方式获取证书吊销列表的所有被吊销证书 |
| X509Crl | getTbsInfo(callback : AsyncCallback<DataBlob>) : void | 使用callback方式获取证书吊销列表的tbsCertList |
| X509Crl | getTbsInfo() : Promise<DataBlob> | 使用Promise方式获取证书吊销列表的tbsCertList |
| X509Crl | getSignature() : DataBlob | 获取证书吊销列表的签名 |
| X509Crl | getSignatureAlgName() : string | 获取证书吊销列表的签名算法名称 |
| X509Crl | getSignatureAlgOid() : string | 获取证书吊销列表的签名算法OID |
| X509Crl | getSignatureAlgParams() : DataBlob | 获取证书吊销列表的签名算法参数 |
**开发步骤**
示例：解析X509证书吊销列表数据生成证书吊销列表对象，并调用对象方法（包含场景1-6）
```javascript
import cryptoFramework from '@ohos.security.cryptoFramework';
// 证书吊销列表数据，此处仅示例，业务需根据场景自行设置
let crlData = "-----BEGIN X509 CRL-----\n"
+ "MIIBijB0AgEBMA0GCSqGSIb3DQEBCwUAMBMxETAPBgNVBAMMCHJvb3QtY2ExFw0y\n"
+ "MDA2MTkxNjE1NDhaFw0yMDA3MTkxNjE1NDhaMBwwGgIJAMsozRATnap1Fw0yMDA2\n"
+ "MTkxNjEyMDdaoA8wDTALBgNVHRQEBAICEAIwDQYJKoZIhvcNAQELBQADggEBACPs\n"
+ "9gQB+djaXPHHRmAItebZpD3iJ/e36Dxr6aMVkn9FkI8OVpUI4RNcCrywyCZHQJte\n"
+ "995bbPjP7f1sZstOTZS0fDPgJ5SPAxkKOQB+SQnBFrlZSsxoUNU60gRqd2imR0Rn\n"
+ "1r09rP69F6E4yPc9biEld+llLGgoImP3zPOVDD6fbfcvVkjStY3bssVEQ/vjp4a3\n"
+ "/I12U7ZnSe3jaKqaQBoVJppkTFOIOq7IOxf5/IkMPmvRHDeC2IzDMzcUxym0dkny\n"
+ "EowHrjzo0bZVqpHMA2YgKZuwTpVLHk9GeBEK2hVkIoPVISkmiU4HFg0S6z68C5yd\n"
+ "DrAA7hErVgXhtURLbAI=\n"
+ "-----END X509 CRL-----\n";
// string转Uint8Array
function stringToUint8Array(str) {
var arr = [];
for (var i = 0, j = str.length; i < j; i++) {
arr.push(str.charCodeAt(i));
}
return new Uint8Array(arr);
}
// 证书吊销列表示例
function crlSample() {
let encodingBlob = {
// 将string类型证书吊销列表数据转为Uint8Array
data: stringToUint8Array(crlData),
// 证书吊销列表格式：支持PEM和DER，此例中对应PEM
encodingFormat: cryptoFramework.EncodingFormat.FORMAT_PEM
};
// 创建证书吊销列表对象
cryptoFramework.createX509Crl(encodingBlob, function (err, x509Crl) {
if (err != null) {
// 创建证书吊销列表对象失败
Console.log("createX509Crl failed, errCode: " + err.code + ", errMsg: " + err.message);
return;
}
// 创建证书吊销列表对象成功
Console.log("createX509Crl success");
// 获取证书吊销列表版本
let version = x509Crl.getVersion();
// 获取证书吊销列表对象的序列化数据
x509Crl.getEncoded(function (err, data) {
if (err != null) {
// 获取序列化数据失败
Console.log("getEncoded failed, errCode: " + err.code + ", errMsg: " + err.message);
} else {
// 获取序列化数据成功
Console.log("getEncoded success");
}
});
// 业务需通过cryptoFramework的createX509Cert生成X509Cert证书对象，此处省略
let x509Cert = null;
// 检查证书是否被吊销
x509Crl.isRevoked(x509Cert, function (err, isRevoked) {
if (err != null) {
// 检查证书是否被吊销失败
Console.log("isRevoked failed, errCode: " + err.code + ", errMsg: " + err.message);
} else {
// 检查证书是否被吊销成功
Console.log("isRevoked success, isRevoked? " + isRevoked);
}
});
// 业务需通过AsyKeyGenerator的generateKeyPair或convertKey接口获取PubKey对象，此处省略
let pubKey = null;
// 证书吊销列表验签
x509Crl.verify(pubKey, function (err, data) {
if (err == null) {
// 验签成功
Console.log("verify success");
} else {
// 验签失败
Console.log("verify failed, errCode: " + err.code + ", errMsg: " + err.message);
}
});
// 证书序列号，业务需自行设置
let serialNumber = 1000;
// 获取被吊销证书对象
x509Crl.getRevokedCert(serialNumber, function (err, entry) {
if (err != null) {
// 获取被吊销证书对象失败
Console.log("getRevokedCert failed, errCode: " + err.code + ", errMsg: " + err.message);
} else {
// 获取被吊销证书对象成功
Console.log("getRevokedCert success");
}
});
});
}
```
## 使用证书链校验器操作
**场景说明**
使用证书链校验器操作中，典型的场景有：
1. 证书链校验。
**接口及参数说明**
详细接口说明可参考[API参考](../reference/apis/js-apis-cryptoFramework.md)。
以上场景涉及的常用接口如下表所示：
| 实例名 | 接口名 | 描述 |
| ------------------ | ------------------------------------------------------------ | -------------------------------- |
| cryptoFramework | createCertChainValidator(algorithm :string) : CertChainValidator | 使用指定算法生成证书链校验器对象 |
| CertChainValidator | validate(certChain : CertChainData, callback : AsyncCallback<void>) : void | 使用callback方式校验证书链 |
| CertChainValidator | validate(certChain : CertChainData) : Promise<void> | 使用promise方式校验证书链 |
| CertChainValidator | algorithm : string | 证书链校验器算法名称 |
**开发步骤**
示例：创建证书链校验器对象，并对证书链数据进行校验（场景1）
```javascript
import cryptoFramework from '@ohos.security.cryptoFramework';
// 一级证书数据，此处仅示例，业务需自行设置真实数据
let caCertData = "-----BEGIN CERTIFICATE-----\n"
+ "...\n"
+ "...\n"
+ "...\n"
+ "-----END CERTIFICATE-----\n";
// 二级证书数据，此处仅示例，业务需自行设置真实数据
let secondCaCertData = "-----BEGIN CERTIFICATE-----\n"
+ "...\n"
+ "...\n"
+ "...\n"
+ "-----END CERTIFICATE-----\n";
// string转Uint8Array
function stringToUint8Array(str) {
var arr = [];
for (var i = 0, j = str.length; i < j; i++) {
arr.push(str.charCodeAt(i));
}
return new Uint8Array(arr);
}
// 证书链校验器示例：此示例中以校验二级证书链为例，业务需根据场景自行修改
function certChainValidatorSample() {
// 证书链校验器算法，当前仅支持PKIX
let algorithm = "PKIX";
// 创建证书链校验器对象
let validator = cryptoFramework.createCertChainValidator(algorithm);
// 一级证书数据
let uint8ArrayOfCaCertData = stringToUint8Array(caCertData);
// 一级证书数据长度
let uint8ArrayOfCaCertDataLen = new Uint8Array(new Uint16Array([uint8ArrayOfCaCertData.byteLength]).buffer);
// 二级证书数据
let uint8ArrayOf2ndCaCertData = stringToUint8Array(secondCaCertData);
// 二级证书数据长度
let uint8ArrayOf2ndCaCertDataLen = new Uint8Array(new Uint16Array([uint8ArrayOf2ndCaCertData.byteLength]).buffer);
// 证书链二进制数据：二级证书数据长度+二级证书数据+一级证书数据长度+一级证书数据（L-V格式）
let encodingData = new Uint8Array(uint8ArrayOf2ndCaCertDataLen.length + uint8ArrayOf2ndCaCertData.length +
uint8ArrayOfCaCertDataLen.length + uint8ArrayOfCaCertData.length);
for (var i = 0; i < uint8ArrayOf2ndCaCertDataLen.length; i++) {
encodingData[i] = uint8ArrayOf2ndCaCertDataLen[i];
}
for (var i = 0; i < uint8ArrayOf2ndCaCertData.length; i++) {
encodingData[uint8ArrayOf2ndCaCertDataLen.length + i] = uint8ArrayOf2ndCaCertData[i];
}
for (var i = 0; i < uint8ArrayOfCaCertDataLen.length; i++) {
encodingData[uint8ArrayOf2ndCaCertDataLen.length + uint8ArrayOf2ndCaCertData.length + i] = uint8ArrayOfCaCertDataLen[i];
}
for (var i = 0; i < uint8ArrayOfCaCertData.length; i++) {
encodingData[uint8ArrayOf2ndCaCertDataLen.length + uint8ArrayOf2ndCaCertData.length +
uint8ArrayOfCaCertDataLen.length + i] = uint8ArrayOfCaCertData[i];
}
let certChainData = {
// Uint8Array类型：L-V格式(证书数据长度-证书数据)
data: encodingData,
// 证书数量，此示例中为2
count: 2,
// 证书格式：支持PEM和DER，此例中对应PEM
encodingFormat: cryptoFramework.EncodingFormat.FORMAT_PEM
};
// 校验证书链
validator.validate(certChainData, function (err, data) {
if (err != null) {
// 证书链校验失败
Console.log("validate failed, errCode: " + err.code + ", errMsg: " + err.message);
} else {
// 证书链校验成功
Console.log("validate success");
}
});
}
```
## 使用被吊销证书操作
**场景说明**
使用被吊销证书操作中，典型的场景有：
1. 获取被吊销证书对象。
2. 获取被吊销证书信息，比如：序列号、证书颁发者、证书吊销日期。
3. 获取被吊销证书对象的序列化数据。
**接口及参数说明**
详细接口说明可参考[API参考](../reference/apis/js-apis-cryptoFramework.md)。
以上场景涉及的常用接口如下表所示：
| 实例名 | 接口名 | 描述 |
| ------------ | ----------------------------------------------------------- | ------------------------------------------ |
| X509CrlEntry | getEncoded(callback : AsyncCallback<EncodingBlob>) : void; | 使用callback方式获取被吊销证书的序列化数据 |
| X509CrlEntry | getEncoded() : Promise<EncodingBlob>; | 使用promise方式获取被吊销证书的序列化数据 |
| X509CrlEntry | getSerialNumber() : number; | 获取被吊销证书的序列号 |
| X509CrlEntry | getCertIssuer(callback : AsyncCallback<DataBlob>) : void; | 使用callback方式获取被吊销证书颁发者 |
| X509CrlEntry | getCertIssuer() : Promise<DataBlob>; | 使用promise方式获取被吊销证书颁发者 |
| X509CrlEntry | getRevocationDate(callback : AsyncCallback<string>) : void; | 使用callback方式获取被吊销证书的吊销日期 |
| X509CrlEntry | getRevocationDate() : Promise<string>; | 使用promise方式获取被吊销证书的吊销日期 |
**开发步骤**
示例：获取被吊销证书对象，并调用对象方法（包含场景1-3）
```javascript
import cryptoFramework from '@ohos.security.cryptoFramework';
// 被吊销证书示例
function crlEntrySample() {
// 业务需自行通过cryptoFramework的createX509Crl接口创建X509Crl对象，此处省略
let x509Crl = null;
// 获取被吊销证书对象，业务需根据场景调用X509Crl的接口获取，此示例使用getRevokedCert获取
let serialNumber = 1000;
x509Crl.getRevokedCert(serialNumber, function (err, crlEntry) {
if (err != null) {
// 获取被吊销证书对象失败
Console.log("getRevokedCert failed, errCode: " + err.code + ", errMsg: " + err.message);
return;
}
// 获取被吊销证书对象成功
Console.log("getRevokedCert success");
// 获取被吊销证书的序列号
let serialNumber = crlEntry.getSerialNumber();
// 获取被吊销证书的吊销日期
crlEntry.getRevocationDate(function (err, date) {
if (err != null) {
// 获取吊销日期失败
Console.log("getRevocationDate failed, errCode: " + err.code + ", errMsg: " + err.message);
} else {
// 获取吊销日期成功
Console.log("getRevocationDate success, date is: " + date);
}
});
// 获取被吊销证书对象的序列化数据
crlEntry.getEncoded(function (err, data) {
if (err != null) {
// 获取序列化数据失败
Console.log("getEncoded failed, errCode: " + err.code + ", errMsg: " + err.message);
} else {
// 获取序列化数据成功
Console.log("getEncoded success");
}
});
});
}
```
Markdown is supported
0% 或 .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑！
想要评论请 注册 或