HarmonyOSAPI@ohos.security.cryptoFramework 加解密算法库框架

joytrian

发布于 2023-4-4 16:12

浏览

0收藏

版本：v3.1 Beta

@ohos.security.cryptoFramework (加解密算法库框架)

更新时间: 2023-02-17 09:19

为屏蔽底层硬件和算法库，向上提供统一的密码算法库加解密相关接口。

说明

本模块首批接口从API version 9开始支持。

导入模块

import cryptoFramework from "@ohos.security.cryptoFramework"

Result

表示执行结果的枚举。

系统能力： SystemCapability.Security.CryptoFramework

名称	值	说明
INVALID_PARAMS	401	非法入参。
NOT_SUPPORT	801	操作不支持。
ERR_OUT_OF_MEMORY	17620001	内存错误。
ERR_RUNTIME_ERROR	17620002	运行时外部错误。
ERR_CRYPTO_OPERATION	17630001	调用三方算法库API出错。

DataBlob

buffer数组。

系统能力： SystemCapability.Security.CryptoFramework

名称	类型	可读	可写	说明
data	Uint8Array	是	是	数据。

cryptoFramework.createMac

createMac(algName : string) : Mac

生成Mac实例，用于进行消息认证码的计算与操作

系统能力： SystemCapability.Security.CryptoFramework

参数：

参数名	类型	必填	说明
algName	string	是	指定摘要算法，支持算法范围：SHA1/SHA224/SHA256/SHA384/SHA512

返回值：

类型	说明
Mac	返回由输入算法指定生成的Mac对象

错误码：

错误码ID	错误信息
17620001	memory error.

示例：

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);
}

Mac

Mac类，调用Mac方法可以进行MAC（Message Authentication Code）加密计算。调用前，需要通过createMac构造Mac实例。

属性

系统能力： SystemCapability.Security.CryptoFramework

名称	类型	可读	可写	说明
algName	string	是	否	代表指定的摘要算法名

init

init(key : SymKey, callback : AsyncCallback<void>) : void;

使用对称密钥初始化Mac计算

系统能力： SystemCapability.Security.CryptoFramework

参数：

参数名	类型	必填	说明
key	SymKey	是	共享对称密钥
callback	AsyncCallback<void>	是	回调函数

错误码：

错误码ID	错误信息
17630001	crypto operation error.

示例：

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<void>;

使用对称密钥初始化Mac计算

系统能力： SystemCapability.Security.CryptoFramework

参数：

参数名	类型	必填	说明
key	SymKey	是	共享对称密钥

返回值：

类型	说明
Promise<void>	Promise对象

错误码：

错误码ID	错误信息
17630001	crypto operation error.

示例：

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>) : void;

传入消息进行Mac更新计算

系统能力： SystemCapability.Security.CryptoFramework

参数：

参数名	类型	必填	说明
input	DataBlob	是	传入的消息
callback	AsyncCallback<void>	是	回调函数

错误码：

错误码ID	错误信息
17630001	crypto operation error.

示例：

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(input : DataBlob) : Promise<void>;

传入消息进行Mac更新计算

系统能力： SystemCapability.Security.CryptoFramework

参数：

参数名	类型	必填	说明
input	DataBlob	是	传入的消息

返回值：

类型	说明
Promise<void>	Promise对象

错误码：

错误码ID	错误信息
17630001	crypto operation error.

示例：

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<DataBlob>) : void;

返回Mac的计算结果

系统能力： SystemCapability.Security.CryptoFramework

参数：

参数名	类型	必填	说明
callback	AsyncCallback<DataBlob>	是	回调函数

错误码：

错误码ID	错误信息
17620001	memory error.
17630001	crypto operation error.

示例：

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<DataBlob>

返回Mac的计算结果

系统能力： SystemCapability.Security.CryptoFramework

返回值：

类型	说明
Promise<DataBlob>	Promise对象

错误码：

错误码ID	错误信息
17620001	memory error.
17630001	crypto operation error.

示例：

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

getMacLength() : number

获取Mac消息认证码的长度（字节数）

系统能力： SystemCapability.Security.CryptoFramework

返回值：

类型	说明
number	返回mac计算结果的字节长度

错误码：

错误码ID	错误信息
17630001	crypto operation error.

示例：

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);
    let macLen = mac.getMacLength();
    console.error("MAC len: " + macLen);
}).catch(error => {
    console.error("[Promise]: error: " + error.message);
});

cryptoFramework.createMd

createMd(algName : string) : Md

生成Md实例，用于进行消息摘要的计算与操作

系统能力： SystemCapability.Security.CryptoFramework

参数：

参数名	类型	必填	说明
algName	string	是	指定摘要算法，支持算法范围：SHA1/SHA224/SHA256/SHA384/SHA512/MD5

返回值：

类型	说明
Md	返回由输入算法指定生成的Md对象

错误码：

错误码ID	错误信息
17620001	memory error.

示例：

import cryptoFramework from "@ohos.security.cryptoFramework"

var md;
try {
    // 参数选择请参考上述算法支持范围
    md = cryptoFramework.createMd("SHA256");
} catch (error) {
    console.error("[Promise]: error code: " + error.code + ", message is: " + error.message);
}

Md

Md类，调用Md方法可以进行MD（Message Digest）摘要计算。调用前，需要通过createMd构造Md实例。

属性

系统能力： SystemCapability.Security.CryptoFramework

名称	类型	可读	可写	说明
algName	string	是	否	代表指定的摘要算法名

update

update(input : DataBlob, callback : AsyncCallback<void>) : void;

传入消息进行Md更新计算

系统能力： SystemCapability.Security.CryptoFramework

参数：

参数名	类型	必填	说明
input	DataBlob	是	传入的消息
callback	AsyncCallback<void>	是	回调函数

错误码：

错误码ID	错误信息
17630001	crypto operation error.

示例：

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<void>;

传入消息进行Md更新计算

系统能力： SystemCapability.Security.CryptoFramework

参数名	类型	必填	说明
input	DataBlob	是	传入的消息

返回值：

类型	说明
Promise<void>	Promise对象

错误码：

错误码ID	错误信息
17630001	crypto operation error.

示例：

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<DataBlob>) : void

返回Md的计算结果

系统能力： SystemCapability.Security.CryptoFramework

参数名	类型	必填	说明
callback	AsyncCallback<DataBlob>	是	回调函数

错误码：

错误码ID	错误信息
17620001	memory error.
17630001	crypto operation error.

示例：

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<DataBlob>

返回Md的计算结果

系统能力： SystemCapability.Security.CryptoFramework

返回值：

类型	说明
Promise<DataBlob>	Promise对象

错误码：

错误码ID	错误信息
17620001	memory error.
17630001	crypto operation error.

示例：

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

获取Md消息摘要长度（字节数）

系统能力： SystemCapability.Security.CryptoFramework

返回值：

类型	说明
number	返回md计算结果的字节长度

错误码：

错误码ID	错误信息
17630001	crypto operation error.

示例：

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.createRandom

createRandom() : Random

生成Random实例，用于进行随机数的计算与设置种子

系统能力： SystemCapability.Security.CryptoFramework

返回值：

类型	说明
Random	返回由输入算法指定生成的Random对象

错误码：

错误码ID	错误信息
17620001	memory error.

示例：

import cryptoFramework from "@ohos.security.cryptoFramework"

try {
    var rand = cryptoFramework.createRandom();
} catch (error) {
    console.error("[Callback]: error code: " + error.code + ", message is: " + error.message); 
}

Random

Random类，调用Random方法可以进行随机数计算。调用前，需要通过createRandom构造Random实例。

generateRandom

generateRandom(len : number, callback: AsyncCallback<DataBlob>) : void;

生成指定长度的随机数

系统能力： SystemCapability.Security.CryptoFramework

参数：

参数名	类型	必填	说明
len	number	是	表示生成随机数的长度
callback	AsyncCallback<DataBlob>	是	回调函数

错误码：

错误码ID	错误信息
17620001	memory error.
17630001	crypto operation error.

示例：

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);
    }
});

generateRandom

generateRandom(len : number) : Promise<DataBlob>;

生成指定长度的随机数

系统能力： SystemCapability.Security.CryptoFramework

参数：

参数名	类型	必填	说明
len	number	是	表示生成随机数的长度

返回值：

类型	说明
Promise<DataBlob>	Promise对象

错误码：

错误码ID	错误信息
17620001	memory error.
17630001	crypto operation error.

示例：

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);
}

var promiseGenerateRand = rand.generateRandom(12);
promiseGenerateRand.then(randData => {
    console.error("[Promise]: rand result: " + randData.data);
}).catch(error => {
    console.error("[Promise]: error: " + error.message);
});

setSeed

setSeed(seed : DataBlob) : void;

设置指定的种子

系统能力： SystemCapability.Security.CryptoFramework

参数名	类型	必填	说明
seed	DataBlob	是	设置的种子

错误码：

错误码ID	错误信息
17620001	memory error.

示例：

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);
        }
    }
});

ParamsSpec

加解密参数，在进行对称加解密时需要构造其子类对象，并将子类对象传入init()方法。

适用于需要iv等参数的对称加解密模式（对于无iv等参数的模式如ECB模式，无需构造，在init()中传入null即可）。

系统能力： SystemCapability.Security.CryptoFramework

名称	类型	可读	可写	说明
algoName	string	是	是	指明对称加解密参数的算法模式。可选值如下: - "IvParamsSpec": 适用于CBC\|CTR\|OFB\|CFB模式 - "GcmParamsSpec": 适用于GCM模式 - "CcmParamsSpec": 适用于CCM模式

说明

由于init()的params参数是ParamsSpec类型（父类），而实际需要传入具体的子类对象（如IvParamsSpec），因此在构造子类对象时应设置其父类ParamsSpec的algoName参数，使算法库在init()时知道传入的是哪种子类对象。

IvParamsSpec

加解密参数ParamsSpec的子类，用于在对称加解密时作为init()方法的参数。

适用于CBC、CTR、OFB、CFB这些仅使用iv作为参数的加解密模式。

系统能力： SystemCapability.Security.CryptoFramework

名称	类型	可读	可写	说明
iv	DataBlob	是	是	指明加解密参数iv。常见取值如下： - AES的CBC\|CTR\|OFB\|CFB模式：iv长度为16字节 - 3DES的CBC\|OFB\|CFB模式：iv长度为8字节

说明

传入init()方法前需要指定其algoName属性（来源于父类ParamsSpec）。

GcmParamsSpec

加解密参数ParamsSpec的子类，用于在对称加解密时作为init()方法的参数。

适用于GCM模式。

系统能力： SystemCapability.Security.CryptoFramework

名称	类型	可读	可写	说明
iv	DataBlob	是	是	指明加解密参数iv，长度为12字节
aad	DataBlob	是	是	指明加解密参数aad，长度为8字节
authTag	DataBlob	是	是	指明加解密参数authTag，长度为16字节。采用GCM模式加密时，需要获取doFinal()输出的DataBlob，取出其末尾16字节作为解密时init()方法的入参GcmParamsSpec中的的authTag

说明

传入init()方法前需要指定其algoName属性（来源于父类ParamsSpec）。

CcmParamsSpec

加解密参数ParamsSpec的子类，用于在对称加解密时作为init()方法的参数。

适用于CCM模式。

系统能力： SystemCapability.Security.CryptoFramework

名称	类型	可读	可写	说明
iv	DataBlob	是	是	指明加解密参数iv，长度为7字节
aad	DataBlob	是	是	指明加解密参数aad，长度为8字节
authTag	DataBlob	是	是	指明加解密参数authTag，长度为12字节。采用CCM模式加密时，需要获取doFinal()输出的DataBlob，取出其末尾12字节作为解密时init()方法的入参CcmParamsSpec中的authTag

说明

传入init()方法前需要指定其algoName属性（来源于父类ParamsSpec）。

CryptoMode

表示加解密操作的枚举。

系统能力： SystemCapability.Security.CryptoFramework

名称	值	说明
ENCRYPT_MODE	0	表示进行加密操作
DECRYPT_MODE	1	表示进行解密操作

Key

密钥（父类），在运行密码算法（如加解密）时需要提前生成其子类对象，并传入Cipher实例的init()方法。

密钥可以通过密钥生成器来生成。

属性

系统能力： SystemCapability.Security.CryptoFramework

名称	类型	可读	可写	说明
format	string	是	否	密钥的格式。
algName	string	是	否	密钥对应的算法名（含长度）。

getEncoded

getEncoded() : DataBlob

以同步方法，获取16进制形式的密钥内容。

系统能力： SystemCapability.Security.CryptoFramework

返回值：

类型	说明
DataBlob	用于查看密钥的具体内容。

示例：

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;    // key为使用对称密钥生成器 生成的密钥，此处省略生成过程
let encodedKey = key.getEncoded();
console.info("key hex:" + uint8ArrayToShowStr(encodedKey.data));

SymKey

对称密钥，是Key的子类，在对称加解密时需要将其对象传入Cipher实例的init()方法使用。

对称密钥可以通过对称密钥生成器SymKeyGenerator来生成。

clearMem

clearMem() : void

以同步方法，将系统底层内存中的的密钥内容清零。建议在不再使用对称密钥实例时，调用本函数，避免内存中密钥数据存留过久。

系统能力： SystemCapability.Security.CryptoFramework

示例：

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;    // key为使用对称密钥生成器 生成的密钥，此处省略生成过程
let encodedKey = key.getEncoded();
console.info("key hex:" + uint8ArrayToShowStr(encodedKey.data));    // 输出密钥内容
key.clearMem();
encodedKey = key.getEncoded();
console.info("key hex:" + uint8ArrayToShowStr(encodedKey.data));    // 输出全零

PubKey

公钥，是Key的子类，在非对称加解密、验签、密钥协商时需要将其对象作为输入使用。

公钥可以通过非对称密钥生成器AsyKeyGenerator来生成。

属性

系统能力： SystemCapability.Security.CryptoFramework

名称	类型	可读	可写	说明
format	string	是	否	密钥的格式。
algName	string	是	否	密钥对应的算法名（含长度）。

getEncoded

getEncoded() : DataBlob

以同步方法，获取二进制形式的密钥内容。公钥格式满足ASN.1语法、X.509规范、DER编码格式。

系统能力： SystemCapability.Security.CryptoFramework

返回值：

类型	说明
DataBlob	用于查看密钥的具体内容。

示例：

function uint8ArrayToShowStr(uint8Array) {
  return Array.prototype.map
    .call(uint8Array, (x) => ('00' + x.toString(16)).slice(-2))
    .join('');
}

let key; // key为使用非对称密钥生成器生成的非对称密钥的公钥对象，此处省略生成过程
console.info("key format:" + key.format);
console.info("key algName:" + key.algName);
var encodedKey = key.getEncoded();
console.info("key encoded:" + uint8ArrayToShowStr(encodedKey.data));

PriKey

私钥，是Key的子类，在非对称加解密、签名、密钥协商时需要将其作为输入使用。

私钥可以通过非对称密钥生成器AsyKeyGenerator来生成。

属性

系统能力： SystemCapability.Security.CryptoFramework

名称	类型	可读	可写	说明
format	string	是	否	密钥的格式。
algName	string	是	否	密钥对应的算法名（含长度）。

getEncoded

getEncoded() : DataBlob

以同步方法，获取二进制形式的密钥内容。私钥格式满足ASN.1语法，PKCS#8规范、DER编码方式。

系统能力： SystemCapability.Security.CryptoFramework

返回值：

类型	说明
DataBlob	用于查看密钥的具体内容。

示例：

function uint8ArrayToShowStr(uint8Array) {
  return Array.prototype.map
    .call(uint8Array, (x) => ('00' + x.toString(16)).slice(-2))
    .join('');
}

let key; // key为使用非对称密钥生成器生成的非对称密钥的私钥对象，此处省略生成过程
console.info("key format:" + key.format);
console.info("key algName:" + key.algName);
var encodedKey = key.getEncoded();
console.info("key encoded:" + uint8ArrayToShowStr(encodedKey.data));

clearMem

clearMem() : void

以同步方法，将系统底层内存中的的密钥内容清零。

系统能力： SystemCapability.Security.CryptoFramework

示例：

let key; // key为使用非对称密钥生成器生成的非对称密钥的私钥对象，此处省略生成过程
key.clearMem();

KeyPair

非对称密钥对，包含：公钥与私钥，。

可以通过非对称密钥生成器AsyKeyGenerator来生成。

属性

系统能力： SystemCapability.Security.CryptoFramework

名称	类型	可读	可写	说明
priKey	PriKey	是	否	私钥。
pubKey	PubKey	是	否	公钥。

cryptoFramework.createSymKeyGenerator

createSymKeyGenerator(algName : string) : SymKeyGenerator

通过指定算法名称的字符串，获取相应的对称密钥生成器实例。

支持的规格详见框架概述“密钥生成规格”一节。

系统能力： SystemCapability.Security.CryptoFramework

参数：

参数名	类型	必填	说明
algName	string	是	待生成对称密钥生成器的算法名称。具体取值详见框架概述“密钥生成规格”一节中的“字符串参数”。

返回值：

类型	说明
SymKeyGenerator	返回对称密钥生成器的对象。

示例：

import cryptoFramework from '@ohos.security.cryptoFramework';
let symKeyGenerator = cryptoFramework.createSymKeyGenerator('3DES192');

SymKeyGenerator

对称密钥生成器。

在使用该类的方法前，需要先使用createSymKeyGenerator方法构建一个symKeyGenerator实例。

属性

系统能力： SystemCapability.Security.CryptoFramework

名称	类型	可读	可写	说明
algName	string	是	否	对称密钥生成器指定的算法名称。

generateSymKey

generateSymKey(callback : AsyncCallback<SymKey>) : void

异步获取对称密钥生成器随机生成的密钥，通过注册回调函数获取结果。

必须在使用createSymKeyGenerator创建对称密钥生成器后，才能使用本函数。

目前支持使用OpenSSL的RAND_priv_bytes()作为底层能力生成随机密钥。

系统能力： SystemCapability.Security.CryptoFramework

参数：

参数名	类型	必填	说明
callback	AsyncCallback<SymKey>	是	回调函数。当生成对称密钥成功，err为undefined，data为获取到的SymKey；否则为错误对象。

错误码：

错误码ID	错误信息
17620001	memory error.

示例：

import cryptoFramework from '@ohos.security.cryptoFramework';
let symAlgoName = '3DES192';
let symKeyGenerator = cryptoFramework.createSymKeyGenerator(symAlgoName);
symKeyGenerator.generateSymKey((err, symKey) => {
  if (err) {
    console.error(`Generate symKey failed, ${err.code}, ${err.message}`);
  } else {
    console.info(`Generate symKey success, algName: ${symKey.algName}`);
  }
})

generateSymKey

generateSymKey() : Promise<SymKey>

异步获取该对称密钥生成器随机生成的密钥，通过Promise获取结果。

必须在使用createSymKeyGenerator创建对称密钥生成器后，才能使用本函数。

目前支持使用OpenSSL的RAND_priv_bytes()作为底层能力生成随机密钥。

系统能力： SystemCapability.Security.CryptoFramework

返回值：

类型	说明
Promise<SymKey>	Promise对象，返回对称密钥SymKey。

错误码：

错误码ID	错误信息
17620001	memory error.

示例：

import cryptoFramework from '@ohos.security.cryptoFramework';
let symAlgoName = 'AES128';
let symKeyGenerator = cryptoFramework.createSymKeyGenerator(symAlgoName);
symKeyGenerator.generateSymKey()
.then(symKey => {
  console.info(`Generate symKey success, algName: ${symKey.algName}`);
}, error => {
  console.error(`Generate symKey failed, ${error.code}, ${error.message}`);
})

convertKey

convertKey(key : DataBlob, callback : AsyncCallback<SymKey>) : void

异步根据指定数据生成对称密钥，通过注册回调函数获取结果。

必须在使用createSymKeyGenerator创建对称密钥生成器后，才能使用本函数。

系统能力： SystemCapability.Security.CryptoFramework

参数：

参数名	类型	必填	说明
key	DataBlob	是	指定的对称密钥材料。
callback	AsyncCallback<SymKey>	是	回调函数。当生成对称密钥成功，err为undefined，data为获取到的SymKey；否则为错误对象。

错误码：

错误码ID	错误信息
17620001	memory error.

示例：

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 symAlgoName = '3DES192';
let symKeyGenerator = cryptoFramework.createSymKeyGenerator(symAlgoName);
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

convertKey(key : DataBlob) : Promise<SymKey>

异步根据指定数据生成对称密钥，通过Promise获取结果。

必须在使用createSymKeyGenerator创建对称密钥生成器后，才能使用本函数。

系统能力： SystemCapability.Security.CryptoFramework

参数：

参数名	类型	必填	说明
key	DataBlob	是	指定的密钥材料数据。

返回值：

类型	说明
Promise<SymKey>	Promise对象，返回对称密钥SymKey。

错误码：

错误码ID	错误信息
17620001	memory error.

示例：

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 symAlgoName = '3DES192';
let symKeyGenerator = cryptoFramework.createSymKeyGenerator(symAlgoName);
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}`);
})

文章转载自：https://developer.harmonyos.com/cn/docs/documentation/doc-references-V3/js-apis-cryptoframework-0000001477981409-V3?catalogVersion=V3#ZH-CN_TOPIC_0000001477981409__导入模块

分类

卡片开发

三方件

标签

HarmonyOS API

已于2023-4-4 16:12:20修改

51CTO

51CTO博客

51CTO学堂

HarmonyOSAPI@ohos.security.cryptoFramework 加解密算法库框架

@ohos.security.cryptoFramework (加解密算法库框架)

导入模块

Result

DataBlob

cryptoFramework.createMac

Mac

属性

init

init

update

update

doFinal

doFinal

getMacLength

cryptoFramework.createMd

Md

属性

update

update

digest

digest

getMdLength

cryptoFramework.createRandom

Random

generateRandom

generateRandom

setSeed

ParamsSpec

IvParamsSpec

GcmParamsSpec

CcmParamsSpec

CryptoMode

Key

属性

getEncoded

SymKey

clearMem

PubKey

属性

getEncoded

PriKey

属性

getEncoded

clearMem

KeyPair

属性

cryptoFramework.createSymKeyGenerator

SymKeyGenerator

属性

generateSymKey

generateSymKey

convertKey

convertKey

目录

订阅鸿蒙技术特刊，精选内容抢先看