Mercurial > hg > nginx-site

changeset 2932:16613b91c584

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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
+++ b/xml/en/docs/njs/reference.xml
@@ -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 @@ that contains the data to be digested
 
 </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 @@ format
 <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>