Mercurial > hg > nginx-site
comparison xml/en/docs/njs/reference.xml @ 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 | 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> |