Mercurial > hg > nginx-site
changeset 2932:16613b91c584
Extended support for symmetric/assymetric keys in WebCrypto njs.
author | Yaroslav Zhuravlev <yar@nginx.com> |
---|---|
date | Thu, 02 Feb 2023 13:45:06 +0000 |
parents | 215deab42286 |
children | 386ba17fac23 |
files | xml/en/docs/njs/reference.xml |
diffstat | 1 files changed, 230 insertions(+), 2 deletions(-) [+] |
line wrap: on
line diff
--- a/xml/en/docs/njs/reference.xml Wed Feb 01 14:57:39 2023 -0800 +++ b/xml/en/docs/njs/reference.xml Thu Feb 02 13:45:06 2023 +0000 @@ -9,7 +9,7 @@ <article name="Reference" link="/en/docs/njs/reference.html" lang="en" - rev="95"> + rev="96"> <section id="summary"> @@ -1908,6 +1908,227 @@ </tag-desc> +<tag-name id="crypto_subtle_export_key"><literal>сrypto.subtle.exportKey</literal>(<link id="crypto_export_key_format"><literal>format</literal></link>, +<link id="crypto_export_key_keydata"><literal>key</literal></link>)</tag-name> +<tag-desc> +Exports a key: takes a key as a <literal>CryptoKey</literal> object +and returns the key in an external, portable format +(since <link doc="changes.xml" id="njs0.7.10">0.7.10</link>). +If the <literal>format</literal> was <literal>jwk</literal>, +then the <literal>Promise</literal> fulfills with a JSON object +containing the key. +Otherwise, the promise fulfills with an +<literal>ArrayBuffer</literal> containing the key. +Possible values: +<list type="tag"> + +<tag-name id="crypto_export_key_format"><literal>format</literal></tag-name> +<tag-desc> +a string that describes the data format in which the key should be exported, +can be the following: +<list type="tag"> + +<tag-name><literal>raw</literal></tag-name> +<tag-desc> +the raw data format +</tag-desc> + +<tag-name><literal>pkcs8</literal></tag-name> +<tag-desc> +the +<link url="https://datatracker.ietf.org/doc/html/rfc5208">PKCS #8</link> +format +</tag-desc> + +<tag-name><literal>spki</literal></tag-name> +<tag-desc> +the +<link url="https://datatracker.ietf.org/doc/html/rfc5280#section-4.1">SubjectPublicKeyInfo</link> +format +</tag-desc> + +<tag-name><literal>jwk</literal></tag-name> +<tag-desc> +the +<link url="https://datatracker.ietf.org/doc/html/rfc7517">JSON Web Key</link> +(JWK) format (since <link doc="changes.xml" id="njs0.7.10">0.7.10</link>) +</tag-desc> + +</list> +</tag-desc> + +<tag-name id="crypto_export_key_keydata"><literal>key</literal></tag-name> +<tag-desc> +the <literal>CryptoKey</literal> that contains the key to be exported +</tag-desc> +</list> + +</tag-desc> + +<tag-name id="crypto_subtle_generate_key"><literal>сrypto.subtle.generateKey</literal>(<link id="crypto_generate_key_alg"><literal>algorithm</literal></link>, +<link id="crypto_generate_key_extractable"><literal>extractable</literal></link>, +<link id="crypto_generate_key_usage"><literal>usage</literal></link>)</tag-name> +<tag-desc> +Generates a new key for symmetric algorithms +or key pair for public-key algorithms +(since <link doc="changes.xml" id="njs0.7.10">0.7.10</link>). +Returns a <literal>Promise</literal> that fulfills with the generated key +as a <literal>CryptoKey</literal> or <literal>CryptoKeyPair</literal> object. +Possible values: +<list type="tag"> + +<tag-name id="crypto_generate_key_alg"><literal>algorithm</literal></tag-name> +<tag-desc> +a dictionary object that defines the type of key to generate +and provides extra algorithm-specific parameters: + +<list type="bullet"> +<listitem> +for +<literal>RSASSA-PKCS1-v1_5</literal>, +<literal>RSA-PSS</literal>, or +<literal>RSA-OAEP</literal>, +pass the object with the following keys: + +<list type="bullet"> +<listitem> +<literal>name</literal> is a string, should be set to +<literal>RSASSA-PKCS1-v1_5</literal>, +<literal>RSA-PSS</literal>, or +<literal>RSA-OAEP</literal>, +depending on the used algorithm +</listitem> + +<listitem> +<literal>hash</literal> is a string that represents +the name of the <literal>digest</literal> function to use, can be +<literal>SHA-256</literal>, +<literal>SHA-384</literal>, or +<literal>SHA-512</literal> +</listitem> +</list> + +</listitem> + +<listitem> +for +<literal>ECDSA</literal>, +pass the object with the following keys: + +<list type="bullet"> +<listitem> +<literal>name</literal> is a string, should be set to <literal>ECDSA</literal> +</listitem> + +<listitem> +<literal>namedCurve</literal> is a string that represents +the name of the elliptic curve to use, may be +<literal>P-256</literal>, +<literal>P-384</literal>, or +<literal>P-521</literal> +</listitem> + +</list> +</listitem> + +<listitem> +for +<literal>HMAC</literal>, +pass the object with the following keys: + +<list type="bullet"> +<listitem> +<literal>name</literal> is a string, should be set to <literal>HMAC</literal> +</listitem> + + +<listitem> +<literal>hash</literal> is a string that represents +the name of the <literal>digest</literal> function to use, can be +<literal>SHA-256</literal>, +<literal>SHA-384</literal>, or +<literal>SHA-512</literal> +</listitem> + +<listitem> +<literal>length</literal> (optional) is a number that represents +the length in bits of the key. +If omitted, the length of the key is equal to the length of the digest +generated by the chosen digest function. +</listitem> +</list> + +</listitem> + +<listitem> +for +<literal>AES-CTR</literal>, +<literal>AES-CBC</literal>, or +<literal>AES-GCM</literal>, +pass the string identifying the algorithm or an object +of the form <literal>{ "name": "ALGORITHM" }</literal>, +where <literal>ALGORITHM</literal> is the name of the algorithm +</listitem> + +</list> +</tag-desc> + +<tag-name id="crypto_generate_key_extractable"><literal>extractable</literal></tag-name> +<tag-desc> +boolean value that indicates if it is possible to export the key +</tag-desc> + +<tag-name id="crypto_generate_key_usage"><literal>usage</literal></tag-name> +<tag-desc> +an <literal>array</literal> that indicates possible actions with the key: +<list type="tag"> + +<tag-name><literal>encrypt</literal></tag-name> +<tag-desc> +key for encrypting messages +</tag-desc> + +<tag-name><literal>decrypt</literal></tag-name> +<tag-desc> +key for decrypting messages +</tag-desc> + +<tag-name><literal>sign</literal></tag-name> +<tag-desc> +key for signing messages +</tag-desc> + +<tag-name><literal>verify</literal></tag-name> +<tag-desc> +key for verifying signatures +</tag-desc> + +<tag-name><literal>deriveKey</literal></tag-name> +<tag-desc> +key for deriving a new key +</tag-desc> + +<tag-name><literal>deriveBits</literal></tag-name> +<tag-desc> +key for deriving bits +</tag-desc> + +<tag-name><literal>wrapKey</literal></tag-name> +<tag-desc> +key for wrapping a key +</tag-desc> + +<tag-name><literal>unwrapKey</literal></tag-name> +<tag-desc> +key for unwrapping a key +</tag-desc> +</list> + +</tag-desc> +</list> + +</tag-desc> + <tag-name id="crypto_subtle_import_key"><literal>сrypto.subtle.importKey</literal>(<link id="crypto_import_key_format"><literal>format</literal></link>, <link id="crypto_import_key_keydata"><literal>keyData</literal></link>, <link id="crypto_import_key_alg"><literal>algorithm</literal></link>, @@ -1942,10 +2163,17 @@ <tag-name><literal>spki</literal></tag-name> <tag-desc> the -<link url=" https://datatracker.ietf.org/doc/html/rfc5280#section-4.1">SubjectPublicKeyInfo</link> +<link url="https://datatracker.ietf.org/doc/html/rfc5280#section-4.1">SubjectPublicKeyInfo</link> format </tag-desc> +<tag-name><literal>jwk</literal></tag-name> +<tag-desc> +the +<link url="https://datatracker.ietf.org/doc/html/rfc7517">JSON Web Key</link> +(JWK) format (since <link doc="changes.xml" id="njs0.7.10">0.7.10</link>) +</tag-desc> + </list> </tag-desc>