Mercurial > hg > nginx-site

comparison xml/en/docs/njs/reference.xml @ 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 237a77d8565b
children 386ba17fac23
comparison
equal deleted inserted replaced
2931:215deab42286 2932:16613b91c584
7 <!DOCTYPE article SYSTEM "../../../../dtd/article.dtd"> 7 <!DOCTYPE article SYSTEM "../../../../dtd/article.dtd">
8 8
9 <article name="Reference" 9 <article name="Reference"
10 link="/en/docs/njs/reference.html" 10 link="/en/docs/njs/reference.html"
11 lang="en" 11 lang="en"
12 rev="95"> 12 rev="96">
13 13
14 <section id="summary"> 14 <section id="summary">
15 15
16 <para> 16 <para>
17 <link doc="index.xml">njs</link> provides objects, methods and properties 17 <link doc="index.xml">njs</link> provides objects, methods and properties
1906 </tag-desc> 1906 </tag-desc>
1907 </list> 1907 </list>
1908 1908
1909 </tag-desc> 1909 </tag-desc>
1910 1910
1911 <tag-name id="crypto_subtle_export_key"><literal>сrypto.subtle.exportKey</literal>(<link id="crypto_export_key_format"><literal>format</literal></link>,
1912 <link id="crypto_export_key_keydata"><literal>key</literal></link>)</tag-name>
1913 <tag-desc>
1914 Exports a key: takes a key as a <literal>CryptoKey</literal> object
1915 and returns the key in an external, portable format
1916 (since <link doc="changes.xml" id="njs0.7.10">0.7.10</link>).
1917 If the <literal>format</literal> was <literal>jwk</literal>,
1918 then the <literal>Promise</literal> fulfills with a JSON object
1919 containing the key.
1920 Otherwise, the promise fulfills with an
1921 <literal>ArrayBuffer</literal> containing the key.
1922 Possible values:
1923 <list type="tag">
1924
1925 <tag-name id="crypto_export_key_format"><literal>format</literal></tag-name>
1926 <tag-desc>
1927 a string that describes the data format in which the key should be exported,
1928 can be the following:
1929 <list type="tag">
1930
1931 <tag-name><literal>raw</literal></tag-name>
1932 <tag-desc>
1933 the raw data format
1934 </tag-desc>
1935
1936 <tag-name><literal>pkcs8</literal></tag-name>
1937 <tag-desc>
1938 the
1939 <link url="https://datatracker.ietf.org/doc/html/rfc5208">PKCS #8</link>
1940 format
1941 </tag-desc>
1942
1943 <tag-name><literal>spki</literal></tag-name>
1944 <tag-desc>
1945 the
1946 <link url="https://datatracker.ietf.org/doc/html/rfc5280#section-4.1">SubjectPublicKeyInfo</link>
1947 format
1948 </tag-desc>
1949
1950 <tag-name><literal>jwk</literal></tag-name>
1951 <tag-desc>
1952 the
1953 <link url="https://datatracker.ietf.org/doc/html/rfc7517">JSON Web Key</link>
1954 (JWK) format (since <link doc="changes.xml" id="njs0.7.10">0.7.10</link>)
1955 </tag-desc>
1956
1957 </list>
1958 </tag-desc>
1959
1960 <tag-name id="crypto_export_key_keydata"><literal>key</literal></tag-name>
1961 <tag-desc>
1962 the <literal>CryptoKey</literal> that contains the key to be exported
1963 </tag-desc>
1964 </list>
1965
1966 </tag-desc>
1967
1968 <tag-name id="crypto_subtle_generate_key"><literal>сrypto.subtle.generateKey</literal>(<link id="crypto_generate_key_alg"><literal>algorithm</literal></link>,
1969 <link id="crypto_generate_key_extractable"><literal>extractable</literal></link>,
1970 <link id="crypto_generate_key_usage"><literal>usage</literal></link>)</tag-name>
1971 <tag-desc>
1972 Generates a new key for symmetric algorithms
1973 or key pair for public-key algorithms
1974 (since <link doc="changes.xml" id="njs0.7.10">0.7.10</link>).
1975 Returns a <literal>Promise</literal> that fulfills with the generated key
1976 as a <literal>CryptoKey</literal> or <literal>CryptoKeyPair</literal> object.
1977 Possible values:
1978 <list type="tag">
1979
1980 <tag-name id="crypto_generate_key_alg"><literal>algorithm</literal></tag-name>
1981 <tag-desc>
1982 a dictionary object that defines the type of key to generate
1983 and provides extra algorithm-specific parameters:
1984
1985 <list type="bullet">
1986 <listitem>
1987 for
1988 <literal>RSASSA-PKCS1-v1_5</literal>,
1989 <literal>RSA-PSS</literal>, or
1990 <literal>RSA-OAEP</literal>,
1991 pass the object with the following keys:
1992
1993 <list type="bullet">
1994 <listitem>
1995 <literal>name</literal> is a string, should be set to
1996 <literal>RSASSA-PKCS1-v1_5</literal>,
1997 <literal>RSA-PSS</literal>, or
1998 <literal>RSA-OAEP</literal>,
1999 depending on the used algorithm
2000 </listitem>
2001
2002 <listitem>
2003 <literal>hash</literal> is a string that represents
2004 the name of the <literal>digest</literal> function to use, can be
2005 <literal>SHA-256</literal>,
2006 <literal>SHA-384</literal>, or
2007 <literal>SHA-512</literal>
2008 </listitem>
2009 </list>
2010
2011 </listitem>
2012
2013 <listitem>
2014 for
2015 <literal>ECDSA</literal>,
2016 pass the object with the following keys:
2017
2018 <list type="bullet">
2019 <listitem>
2020 <literal>name</literal> is a string, should be set to <literal>ECDSA</literal>
2021 </listitem>
2022
2023 <listitem>
2024 <literal>namedCurve</literal> is a string that represents
2025 the name of the elliptic curve to use, may be
2026 <literal>P-256</literal>,
2027 <literal>P-384</literal>, or
2028 <literal>P-521</literal>
2029 </listitem>
2030
2031 </list>
2032 </listitem>
2033
2034 <listitem>
2035 for
2036 <literal>HMAC</literal>,
2037 pass the object with the following keys:
2038
2039 <list type="bullet">
2040 <listitem>
2041 <literal>name</literal> is a string, should be set to <literal>HMAC</literal>
2042 </listitem>
2043
2044
2045 <listitem>
2046 <literal>hash</literal> is a string that represents
2047 the name of the <literal>digest</literal> function to use, can be
2048 <literal>SHA-256</literal>,
2049 <literal>SHA-384</literal>, or
2050 <literal>SHA-512</literal>
2051 </listitem>
2052
2053 <listitem>
2054 <literal>length</literal> (optional) is a number that represents
2055 the length in bits of the key.
2056 If omitted, the length of the key is equal to the length of the digest
2057 generated by the chosen digest function.
2058 </listitem>
2059 </list>
2060
2061 </listitem>
2062
2063 <listitem>
2064 for
2065 <literal>AES-CTR</literal>,
2066 <literal>AES-CBC</literal>, or
2067 <literal>AES-GCM</literal>,
2068 pass the string identifying the algorithm or an object
2069 of the form <literal>{ "name": "ALGORITHM" }</literal>,
2070 where <literal>ALGORITHM</literal> is the name of the algorithm
2071 </listitem>
2072
2073 </list>
2074 </tag-desc>
2075
2076 <tag-name id="crypto_generate_key_extractable"><literal>extractable</literal></tag-name>
2077 <tag-desc>
2078 boolean value that indicates if it is possible to export the key
2079 </tag-desc>
2080
2081 <tag-name id="crypto_generate_key_usage"><literal>usage</literal></tag-name>
2082 <tag-desc>
2083 an <literal>array</literal> that indicates possible actions with the key:
2084 <list type="tag">
2085
2086 <tag-name><literal>encrypt</literal></tag-name>
2087 <tag-desc>
2088 key for encrypting messages
2089 </tag-desc>
2090
2091 <tag-name><literal>decrypt</literal></tag-name>
2092 <tag-desc>
2093 key for decrypting messages
2094 </tag-desc>
2095
2096 <tag-name><literal>sign</literal></tag-name>
2097 <tag-desc>
2098 key for signing messages
2099 </tag-desc>
2100
2101 <tag-name><literal>verify</literal></tag-name>
2102 <tag-desc>
2103 key for verifying signatures
2104 </tag-desc>
2105
2106 <tag-name><literal>deriveKey</literal></tag-name>
2107 <tag-desc>
2108 key for deriving a new key
2109 </tag-desc>
2110
2111 <tag-name><literal>deriveBits</literal></tag-name>
2112 <tag-desc>
2113 key for deriving bits
2114 </tag-desc>
2115
2116 <tag-name><literal>wrapKey</literal></tag-name>
2117 <tag-desc>
2118 key for wrapping a key
2119 </tag-desc>
2120
2121 <tag-name><literal>unwrapKey</literal></tag-name>
2122 <tag-desc>
2123 key for unwrapping a key
2124 </tag-desc>
2125 </list>
2126
2127 </tag-desc>
2128 </list>
2129
2130 </tag-desc>
2131
1911 <tag-name id="crypto_subtle_import_key"><literal>сrypto.subtle.importKey</literal>(<link id="crypto_import_key_format"><literal>format</literal></link>, 2132 <tag-name id="crypto_subtle_import_key"><literal>сrypto.subtle.importKey</literal>(<link id="crypto_import_key_format"><literal>format</literal></link>,
1912 <link id="crypto_import_key_keydata"><literal>keyData</literal></link>, 2133 <link id="crypto_import_key_keydata"><literal>keyData</literal></link>,
1913 <link id="crypto_import_key_alg"><literal>algorithm</literal></link>, 2134 <link id="crypto_import_key_alg"><literal>algorithm</literal></link>,
1914 <link id="crypto_import_key_extractable"><literal>extractable</literal></link>, 2135 <link id="crypto_import_key_extractable"><literal>extractable</literal></link>,
1915 <link id="crypto_import_key_keyusages"><literal>keyUsages</literal></link>)</tag-name> 2136 <link id="crypto_import_key_keyusages"><literal>keyUsages</literal></link>)</tag-name>
1940 </tag-desc> 2161 </tag-desc>
1941 2162
1942 <tag-name><literal>spki</literal></tag-name> 2163 <tag-name><literal>spki</literal></tag-name>
1943 <tag-desc> 2164 <tag-desc>
1944 the 2165 the
1945 <link url=" https://datatracker.ietf.org/doc/html/rfc5280#section-4.1">SubjectPublicKeyInfo</link> 2166 <link url="https://datatracker.ietf.org/doc/html/rfc5280#section-4.1">SubjectPublicKeyInfo</link>
1946 format 2167 format
2168 </tag-desc>
2169
2170 <tag-name><literal>jwk</literal></tag-name>
2171 <tag-desc>
2172 the
2173 <link url="https://datatracker.ietf.org/doc/html/rfc7517">JSON Web Key</link>
2174 (JWK) format (since <link doc="changes.xml" id="njs0.7.10">0.7.10</link>)
1947 </tag-desc> 2175 </tag-desc>
1948 2176
1949 </list> 2177 </list>
1950 2178
1951 </tag-desc> 2179 </tag-desc>