| 标准编号 | GM/T 0087-2020 (GM/T0087-2020) | | 中文名称 | 浏览器密码应用接口规范 | | 英文名称 | Browser cryptography API specification | | 行业 | Chinese Industry Standard (推荐) | | 中标分类 | L80 | | 字数估计 | 27,299 | | 发布日期 | 2020-12-28 | | 实施日期 | 2021-07-01 | | 标准依据 | 国家密码管理局公告第41号 | | 发布机构 | 国家密码管理局 | GM/T 0087-2020: 浏览器密码应用接口规范
GM/T 0087-2020 英文名称: Browser cryptography API specification
中华人民共和国密码行业标准
浏览器密码应用接口规范
国家密码管理局 发 布
1 范围
本文件定义了浏览器执行网页中的密码操作的JavaScriptAPI,包括加密、解密、杂凑、签名、签名
验证和随机数生成等操作。
本文件定义的API适用于浏览器中用户或服务的认证、文档或代码的签名、通信的机密性与完整
性保证等。
2 规范性引用文件
下列文件中的内容通过文中的规范性引用而构成本文件必不可少的条款。其中,注日期的引用文
件,仅该日期对应的版本适用于本文件;不注日期的引用文件,其最新版本(包括所有的修改单)适用于
本文件。
4 概述
本文件用于为网络应用中浏览器JavaScript脚本提供密码操作能力。网络应用可以让用户利用浏
览器内置密码能力在浏览器端来保护其身份数据和隐私数据。直接使用JavaScript实现密码功能的方
式会导致安全缺陷和性能问题。因此有必要在浏览器上原生实现密码功能,并向JavaScript程序提供
密码支撑。
安全接口Crypto提供了 WCAPI的通用加密功能的接口。该接口定义一个crypto对象开放给浏
览器,在JavaScript中可以全局访问。crypto对象包含生成随机数的方法和一个subtle对象。subtle
对象实现了SubtleCrypto接口。SubtleCrypto接口提供了对若干具体的密码计算的访问接口。
用户JavaScript程序可以使用的密码资源的层次关系见图1。
5 数据结构
5.1 大整数
大整数BigInteger定义为Uint8Array类型,保存任意长度的无符号整数,高字节在前。从API读
取的数值应有最小的类型化数组的长度(即除了0之外,至多7个前导0比特)。API应接受任意数目
的前导0比特。
5.2 密钥对字典
CryptoKeyPair密钥对字典表示一对非对称密钥对,该密钥对由私钥和公钥两部分组成。
5.3 JsonWebKey字典
JsonWebKey字典提供了一种表示和交换表示为JSON网页密钥机构的密钥的方法,同时允许在
浏览器密码API应用中进行本地的高效调用。
5.4 算法字典Algorithm
算法对象是一个网页IDL字典对象,它用于为特定操作来指定算法和附加参数。
其中name为待用的已注册算法的名字。
5.5 密码接口Crypto
密码接口提供了通用密码功能的接口,其中包含了一个使用真随机值作为种子的密码学强伪随机
数生成器。
其中,getRandomValues方法用于生成随机数。该方法应遵循:
a) 若array不为整数类型(如Int8Array,Uint8Array,Int16Array,Uint16Array,Int32Array,或
Uint32Array),则抛出TypeMismatchError异常并结束计算。
b) 若数组的byteLength大于65536,则抛出QuotaExceededError异常并结束算法。
c) 用适当类型的密码学随机数对数组的所有元素覆盖。
d) 返回array。
subtle属性提供了SubtleCrypto接口的一个实例,该接口提供了底层的密码功能和算法。
5.6 密钥算法KeyAlgorithm
IDL:
KeyAlgorithm字典用于将CryptoKey的固定公开属性进行归档。实际字典的类型并不向应用进
行开放。
其中,字段成员name为用于生成CryptoKey对象的算法的名字。
5.7 密钥接口CryptoKey
KeyType为密钥的类型。可识别的密钥类型值为“public”“private”和“secret”。非透明密钥包括
对称算法密钥用“secret”表示,非对称算法密钥由公和私钥组成,分别由“public”或“private”表示。
KeyUsage为密钥的操作类型。可识别的密钥用法包括“encrypt”“decrypt”“sign”“verify”“deri-
veKey”“deriveBits”“wrapKey”和“unwrapKey”。
每个CryptoKey对象有一个内部组成集合,用于存储密钥相关的信息。这些组成部分不作为标准
的一部分而暴露。他们表示具体实现本规范时的内部状态。内部组成通过双方括号[[]]内的名字进
行表述。
6 密码接口
6.1 接口定义
其中,KeyFormat指定密钥串行化的格式。可识别的密钥格式取值为:
“raw”
非格式化字节序列。用于秘密密钥。
“pkcs8”
符合RFC5280格式的私钥信息格式的DER编码。
“jwk”
密钥作为JsonWebKey对象并为JavaScript对象。
6.2 加密方法
encrypt加密方法返回一个新的承诺对象,该对象使用指定的 AlgorithmIdentifier和所提供的
CryptoKey来加密数据。它应执行如下步骤:
a) 将算法和密钥分别作为algorithm和key参数传递至加密方法;
b) 将数据作为data参数的克隆数据结果传递至加密算法;
c) 将normalizedAlgorithm作为正规化算法的结果,将alg设置为algorithm,将op设置为“en-
crypt”;
d) 若出错,返回带有normalizedAlgorithm的承诺拒绝;
e) 设置promise为新的Promise;
f) 返回promise并异步完成余下的步骤;
g) 若余下的步骤或者调用的过程抛出异常或者拒绝承诺,则结束算法;
h) 若normalizedAlgorithm的name成员不同于密钥的[[algorithm]]内部组织的name属性,抛
出InvalidAccessError;
j) 将ciphertext设置为加密操作的结果,该操作过程指定了normalizedAlgorithm加密操作、密
钥和明文;
k) 用ciphertext作为Promise对象返回。
6.3 解密方法
decrypt解密方法返回一个新的承诺对象,该对象使用AlgorithmIdentifier和提供的CryptoKey对
密文进行解密。它应执行下列步骤:
a) 将算法和密钥分别作为algorithm和key参数传递至解密方法;
b) 将数据作为data参数的克隆数据结果传递至解密算法;
c) 将normalizedAlgorithm作为正规化算法的结果,将alg设置为algorithm,将op设置为“de-
crypt”;
d) 若出错,返回带有normalizedAlgorithm的承诺拒绝;
e) 设置promise为新的Promise;
f) 返回promise并异步完成余下的步骤;
g) 若余下的步骤或者调用的过程抛出异常或者拒绝承诺,则结束算法;
h) 若normalizedAlgorithm的name成员不同于密钥的[[algorithm]]内部组织的name属性,抛
出InvalidAccessError;
j) 将plaintext设置为解密操作的结果,该操作过程指定了特定密钥、算法和密文下的normali-
zedAlgorithm解密操作;
k) 用plaintext作为Promise对象返回。
6.4 签名方法
sign签名方法返回一个新的承诺对象,该对象使用AlgorithmIdentifier和提供的CryptoKey对数
据进行签名。它应遵循下列步骤:
a) 将算法和密钥分别作为algorithm和key参数传递至签名方法;
b) 将数据作为data参数的克隆数据结果传递至签名算法;
c) 将normalizedAlgorithm 作为正规化算法的结果,将alg设置为algorithm,将op设置为
“sign”;
d) 若出错,返回带有normalizedAlgorithm的承诺拒绝;
e) 设置promise为新的Promise;
f) 返回promise并异步完成余下的步骤;
g) 若余下的步骤或者调用的过程抛出异常或者拒绝承诺,则结束算法;
h) 若normalizedAlgorithm的name成员不同于密钥的[[algorithm]]内部组织的name属性,抛
出InvalidAccessError;
j) 将plaintext设置为解密操作的结果,该操作过程指定了特定密钥、算法和消息数据下的nor-
malizedAlgorithm签名操作;
k) 将Promise对象返回。
6.5 验证签名方法
verify验证签名方法返回一个新的承诺对象,该对象使用AlgorithmIdentifier和提供的CryptoKey
对数据进行验签。它应遵循下列步骤:
a) 将算法和密钥分别作为algorithm和key参数传递至验签方法;
b) 将签名数据作为签名参数的data克隆数据结果传递至验签算法;
c) 将normalizedAlgorithm作为正规化算法的结果,将alg设置为algorithm,将op设置为“verify”;
d) 若出错,返回带有normalizedAlgorithm的承诺拒绝;
e) 将数据作为数据参数的数据克隆结果传递至验签方法;
f) 设置promise为新的Promise;
g) 返回promise并异步完成余下的步骤;
h) 若余下的步骤或者调用的过程抛出异常或者拒绝承诺,则结束算法;
i) 若normalizedAlgorithm的name成员不同于密钥的[[algorithm]]内部组织的name属性,抛
出InvalidAccessError;
k) 将result设置为验签操作的结果,该操作过程指定了特定密钥、算法、签名和消息数据下的
normalizedAlgorithm验签操作;
l) 将result作为Promise对象返回。
6.6 杂凑方法
digest散列方法返回一个新的承诺对象,该对象使用 AlgorithmIdentifier对数据进行散列操作。
它应遵循下列步骤:
a) 将算法参数传递至散列方法;
b) 将数据作为数据参数的data克隆数据结果传递至散列方法;
c) 将normalizedAlgorithm作为正规化算法的结果,将alg设置为algorithm,将op设置为“digest”;
d) 若出错,返回带有normalizedAlgorithm的承诺拒绝;
e) 设置promise为新的Promise;
f) 返回promise并异步完成余下的步骤;
g) 若余下的步骤或者调用的过程抛出异常或者拒绝承诺,则结束算法;
h) 将result设置为散列操作的结果,该操作过程指定了算法和消息数据下的normalizedAlgorithm
验签操作;
i) 将result作为Promise对象返回。
6.7 生成密钥方法
调用generateKey方法时,应执行如下步骤:
a) 将算法、可提取性和用法分别作为algorithm、extractable和usage参数传递至生成密钥方法;
b) 将normalizedAlgorithm作为正规化算法的结果,将alg设置为algorithm,将op设置为“gen-
erateKey”;
c) 若出错,返回带有normalizedAlgorithm的承诺拒绝;
d) 设置promise为新的Promise;
e) 返回promise并异步完成余下的步骤;
f) 若余下的步骤或者调用的过程抛出异常或者拒绝承诺,则结束算法;
g) 将result设置为生成密钥操作的结果,该操作过程指定了算法和可提取性和用法下的nor-
malizedAlgorithm验签操作;
h) 若结果为CryptoKey对象;
i) 且结果的[[type]]内部组成为“secret”或“private”、同时用法usages为空,则抛出SyntaxEr-
ror;
j) 若结果为CryptoKeyPair对象;
k) 且结果的私钥属性的[[usages]]内部组成为空序列,则抛出SyntaxError;
l) 将result作为Promise对象返回。
6.8 派生密钥方法
调用deriveKey派生密钥方法时,应完成如下步骤:
a) 将algorithm,baseKey,derivedKeyType,extractable和usages分别作为algorithm,baseKey,
b) 将normalize......
|