Mercurial > hg > nginx-site
comparison xml/en/docs/njs/reference.xml @ 2986:2b161541806a
Documented the CryptoKey object in njs Reference.
author | Yaroslav Zhuravlev <yar@nginx.com> |
---|---|
date | Thu, 01 Jun 2023 17:12:18 +0100 |
parents | 67dd348c9757 |
children | b70e9b806810 |
comparison
equal
deleted
inserted
replaced
2985:19d3277e4793 | 2986:2b161541806a |
---|---|
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="107"> | 12 rev="108"> |
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 |
1516 | 1516 |
1517 </tag-desc> | 1517 </tag-desc> |
1518 | 1518 |
1519 <tag-name id="crypto_encrypt_key"><literal>key</literal></tag-name> | 1519 <tag-name id="crypto_encrypt_key"><literal>key</literal></tag-name> |
1520 <tag-desc> | 1520 <tag-desc> |
1521 a <literal>CryptoKey</literal> that contains | 1521 a <link id="cryptokey"><literal>CryptoKey</literal></link> that contains |
1522 the key to be used for encryption | 1522 the key to be used for encryption |
1523 </tag-desc> | 1523 </tag-desc> |
1524 | 1524 |
1525 <tag-name id="crypto_encrypt_data"><literal>data</literal></tag-name> | 1525 <tag-name id="crypto_encrypt_data"><literal>data</literal></tag-name> |
1526 <tag-desc> | 1526 <tag-desc> |
1696 | 1696 |
1697 </tag-desc> | 1697 </tag-desc> |
1698 | 1698 |
1699 <tag-name id="crypto_decrypt_key"><literal>key</literal></tag-name> | 1699 <tag-name id="crypto_decrypt_key"><literal>key</literal></tag-name> |
1700 <tag-desc> | 1700 <tag-desc> |
1701 a <literal>CryptoKey</literal> | 1701 a <link id="cryptokey"><literal>CryptoKey</literal></link> |
1702 that contains the key to be used for decryption. | 1702 that contains the key to be used for decryption. |
1703 If <literal>RSA-OAEP</literal> is used, this is the | 1703 If <literal>RSA-OAEP</literal> is used, this is the |
1704 <literal>privateKey</literal> property of the | 1704 <literal>privateKey</literal> property of the |
1705 <literal>CryptoKeyPair</literal> object. | 1705 <literal>CryptoKeyPair</literal> object. |
1706 </tag-desc> | 1706 </tag-desc> |
1820 | 1820 |
1821 </tag-desc> | 1821 </tag-desc> |
1822 | 1822 |
1823 <tag-name id="crypto_derive_bits_basekey"><literal>baseKey</literal></tag-name> | 1823 <tag-name id="crypto_derive_bits_basekey"><literal>baseKey</literal></tag-name> |
1824 <tag-desc> | 1824 <tag-desc> |
1825 is a <literal>CryptoKey</literal> | 1825 is a <link id="cryptokey"><literal>CryptoKey</literal></link> |
1826 that represents the input to the derivation algorithm | 1826 that represents the input to the derivation algorithm |
1827 - the initial key material for the derivation function: | 1827 - the initial key material for the derivation function: |
1828 for example, for <literal>PBKDF2</literal> it might be a password, | 1828 for example, for <literal>PBKDF2</literal> it might be a password, |
1829 imported as a <literal>CryptoKey</literal> using | 1829 imported as a <link id="cryptokey"><literal>CryptoKey</literal></link> using |
1830 <link id="crypto_subtle_import_key"><literal>сrypto.subtle.importKey()</literal></link> | 1830 <link id="crypto_subtle_import_key"><literal>сrypto.subtle.importKey()</literal></link> |
1831 </tag-desc> | 1831 </tag-desc> |
1832 | 1832 |
1833 <tag-name id="crypto_derive_bits_length"><literal>length</literal></tag-name> | 1833 <tag-name id="crypto_derive_bits_length"><literal>length</literal></tag-name> |
1834 <tag-desc> | 1834 <tag-desc> |
1942 | 1942 |
1943 </tag-desc> | 1943 </tag-desc> |
1944 | 1944 |
1945 <tag-name id="crypto_derive_key_basekey"><literal>baseKey</literal></tag-name> | 1945 <tag-name id="crypto_derive_key_basekey"><literal>baseKey</literal></tag-name> |
1946 <tag-desc> | 1946 <tag-desc> |
1947 is a <literal>CryptoKey</literal> | 1947 is a <link id="cryptokey"><literal>CryptoKey</literal></link> |
1948 that represents the input to the derivation algorithm | 1948 that represents the input to the derivation algorithm |
1949 - the initial key material for the derivation function: | 1949 - the initial key material for the derivation function: |
1950 for example, for <literal>PBKDF2</literal> it might be a password, | 1950 for example, for <literal>PBKDF2</literal> it might be a password, |
1951 imported as a <literal>CryptoKey</literal> using | 1951 imported as a <link id="cryptokey"><literal>CryptoKey</literal></link> using |
1952 <link id="crypto_subtle_import_key"><literal>сrypto.subtle.importKey()</literal></link>. | 1952 <link id="crypto_subtle_import_key"><literal>сrypto.subtle.importKey()</literal></link>. |
1953 </tag-desc> | 1953 </tag-desc> |
1954 | 1954 |
1955 <tag-name id="crypto_derive_key_derivedkeyalg"><literal>derivedKeyAlgorithm</literal></tag-name> | 1955 <tag-name id="crypto_derive_key_derivedkeyalg"><literal>derivedKeyAlgorithm</literal></tag-name> |
1956 <tag-desc> | 1956 <tag-desc> |
2112 </tag-desc> | 2112 </tag-desc> |
2113 | 2113 |
2114 <tag-name id="crypto_subtle_export_key"><literal>сrypto.subtle.exportKey</literal>(<link id="crypto_export_key_format"><literal>format</literal></link>, | 2114 <tag-name id="crypto_subtle_export_key"><literal>сrypto.subtle.exportKey</literal>(<link id="crypto_export_key_format"><literal>format</literal></link>, |
2115 <link id="crypto_export_key_keydata"><literal>key</literal></link>)</tag-name> | 2115 <link id="crypto_export_key_keydata"><literal>key</literal></link>)</tag-name> |
2116 <tag-desc> | 2116 <tag-desc> |
2117 Exports a key: takes a key as a <literal>CryptoKey</literal> object | 2117 Exports a key: takes a key as |
2118 a <link id="cryptokey"><literal>CryptoKey</literal></link> object | |
2118 and returns the key in an external, portable format | 2119 and returns the key in an external, portable format |
2119 (since <link doc="changes.xml" id="njs0.7.10">0.7.10</link>). | 2120 (since <link doc="changes.xml" id="njs0.7.10">0.7.10</link>). |
2120 If the <literal>format</literal> was <literal>jwk</literal>, | 2121 If the <literal>format</literal> was <literal>jwk</literal>, |
2121 then the <literal>Promise</literal> fulfills with a JSON object | 2122 then the <literal>Promise</literal> fulfills with a JSON object |
2122 containing the key. | 2123 containing the key. |
2160 </list> | 2161 </list> |
2161 </tag-desc> | 2162 </tag-desc> |
2162 | 2163 |
2163 <tag-name id="crypto_export_key_keydata"><literal>key</literal></tag-name> | 2164 <tag-name id="crypto_export_key_keydata"><literal>key</literal></tag-name> |
2164 <tag-desc> | 2165 <tag-desc> |
2165 the <literal>CryptoKey</literal> that contains the key to be exported | 2166 the <link id="cryptokey"><literal>CryptoKey</literal></link> |
2167 that contains the key to be exported | |
2166 </tag-desc> | 2168 </tag-desc> |
2167 </list> | 2169 </list> |
2168 | 2170 |
2169 </tag-desc> | 2171 </tag-desc> |
2170 | 2172 |
2174 <tag-desc> | 2176 <tag-desc> |
2175 Generates a new key for symmetric algorithms | 2177 Generates a new key for symmetric algorithms |
2176 or key pair for public-key algorithms | 2178 or key pair for public-key algorithms |
2177 (since <link doc="changes.xml" id="njs0.7.10">0.7.10</link>). | 2179 (since <link doc="changes.xml" id="njs0.7.10">0.7.10</link>). |
2178 Returns a <literal>Promise</literal> that fulfills with the generated key | 2180 Returns a <literal>Promise</literal> that fulfills with the generated key |
2179 as a <literal>CryptoKey</literal> or <literal>CryptoKeyPair</literal> object. | 2181 as |
2182 a <link id="cryptokey"><literal>CryptoKey</literal></link> | |
2183 or <literal>CryptoKeyPair</literal> object. | |
2180 Possible values: | 2184 Possible values: |
2181 <list type="tag"> | 2185 <list type="tag"> |
2182 | 2186 |
2183 <tag-name id="crypto_generate_key_alg"><literal>algorithm</literal></tag-name> | 2187 <tag-name id="crypto_generate_key_alg"><literal>algorithm</literal></tag-name> |
2184 <tag-desc> | 2188 <tag-desc> |
2337 <link id="crypto_import_key_alg"><literal>algorithm</literal></link>, | 2341 <link id="crypto_import_key_alg"><literal>algorithm</literal></link>, |
2338 <link id="crypto_import_key_extractable"><literal>extractable</literal></link>, | 2342 <link id="crypto_import_key_extractable"><literal>extractable</literal></link>, |
2339 <link id="crypto_import_key_keyusages"><literal>keyUsages</literal></link>)</tag-name> | 2343 <link id="crypto_import_key_keyusages"><literal>keyUsages</literal></link>)</tag-name> |
2340 <tag-desc> | 2344 <tag-desc> |
2341 Imports a key: takes as input a key in an external, portable format | 2345 Imports a key: takes as input a key in an external, portable format |
2342 and gives a <literal>CryptoKey</literal> object. | 2346 and gives a <link id="cryptokey"><literal>CryptoKey</literal></link> object. |
2343 Returns a <literal>Promise</literal> that fulfills with the imported key | 2347 Returns a <literal>Promise</literal> that fulfills with the imported key |
2344 as a <literal>CryptoKey</literal> object. | 2348 as a <link id="cryptokey"><literal>CryptoKey</literal></link> object. |
2345 Possible values: | 2349 Possible values: |
2346 <list type="tag"> | 2350 <list type="tag"> |
2347 | 2351 |
2348 <tag-name id="crypto_import_key_format"><literal>format</literal></tag-name> | 2352 <tag-name id="crypto_import_key_format"><literal>format</literal></tag-name> |
2349 <tag-desc> | 2353 <tag-desc> |
2625 | 2629 |
2626 </tag-desc> | 2630 </tag-desc> |
2627 | 2631 |
2628 <tag-name id="crypto_sign_key"><literal>key</literal></tag-name> | 2632 <tag-name id="crypto_sign_key"><literal>key</literal></tag-name> |
2629 <tag-desc> | 2633 <tag-desc> |
2630 is a <literal>CryptoKey</literal> object that the key to be used for signing. | 2634 is a <link id="cryptokey"><literal>CryptoKey</literal></link> object |
2635 that the key to be used for signing. | |
2631 If algorithm identifies a public-key cryptosystem, this is the private key. | 2636 If algorithm identifies a public-key cryptosystem, this is the private key. |
2632 </tag-desc> | 2637 </tag-desc> |
2633 | 2638 |
2634 <tag-name id="crypto_sign_data"><literal>data</literal></tag-name> | 2639 <tag-name id="crypto_sign_data"><literal>data</literal></tag-name> |
2635 <tag-desc> | 2640 <tag-desc> |
2717 | 2722 |
2718 </tag-desc> | 2723 </tag-desc> |
2719 | 2724 |
2720 <tag-name id="crypto_verify_key"><literal>key</literal></tag-name> | 2725 <tag-name id="crypto_verify_key"><literal>key</literal></tag-name> |
2721 <tag-desc> | 2726 <tag-desc> |
2722 is a <literal>CryptoKey</literal> object that the key to be used for verifying. | 2727 is a <link id="cryptokey"><literal>CryptoKey</literal></link> object |
2728 that the key to be used for verifying. | |
2723 It is the secret key for a symmetric algorithm | 2729 It is the secret key for a symmetric algorithm |
2724 and the public key for a public-key system. | 2730 and the public key for a public-key system. |
2725 </tag-desc> | 2731 </tag-desc> |
2726 | 2732 |
2727 <tag-name id="crypto_verify_signature"><literal>signature</literal></tag-name> | 2733 <tag-name id="crypto_verify_signature"><literal>signature</literal></tag-name> |
2741 <literal>DataView</literal> | 2747 <literal>DataView</literal> |
2742 object that contains the data whose signature is to be verified | 2748 object that contains the data whose signature is to be verified |
2743 </tag-desc> | 2749 </tag-desc> |
2744 </list> | 2750 </list> |
2745 | 2751 |
2752 </tag-desc> | |
2753 | |
2754 </list> | |
2755 </para> | |
2756 | |
2757 </section> | |
2758 | |
2759 | |
2760 <section id="cryptokey" name="CryptoKey"> | |
2761 | |
2762 <para> | |
2763 The <literal>CryptoKey</literal> object | |
2764 represents a cryptographic <literal>key</literal> obtained | |
2765 from one of the <literal>SubtleCrypto</literal> methods: | |
2766 <link id="crypto_subtle_generate_key"><literal>сrypto.subtle.generateKey()</literal></link>, | |
2767 <link id="crypto_subtle_derive_key"><literal>сrypto.subtle.deriveKey()</literal></link>, | |
2768 <link id="crypto_subtle_import_key"><literal>сrypto.subtle.importKey()</literal></link>. | |
2769 </para> | |
2770 | |
2771 <para> | |
2772 <list type="tag"> | |
2773 | |
2774 <tag-name id="cryptokey_alg"><literal>CryptoKey.algorithm</literal></tag-name> | |
2775 <tag-desc> | |
2776 returns an object describing the algorithm for which this key can be used | |
2777 and any associated extra parameters | |
2778 (since <link doc="changes.xml" id="njs0.8.0">0.8.0</link>), | |
2779 read-only | |
2780 </tag-desc> | |
2781 | |
2782 <tag-name id="cryptokey_extractable"><literal>CryptoKey.extractable</literal></tag-name> | |
2783 <tag-desc> | |
2784 a boolean value, <literal>true</literal> if the key can be exported | |
2785 (since <link doc="changes.xml" id="njs0.8.0">0.8.0</link>), | |
2786 read-only | |
2787 </tag-desc> | |
2788 | |
2789 <tag-name id="cryptokey_type"><literal>CryptoKey.type</literal></tag-name> | |
2790 <tag-desc> | |
2791 a string value that indicates which kind of key is represented by the object, | |
2792 read-only. | |
2793 Possible values: | |
2794 <list type="tag"> | |
2795 | |
2796 <tag-name><literal>secret</literal></tag-name> | |
2797 <tag-desc> | |
2798 This key is a secret key for use with a symmetric algorithm. | |
2799 </tag-desc> | |
2800 | |
2801 <tag-name><literal>private</literal></tag-name> | |
2802 <tag-desc> | |
2803 This key is the private half of an asymmetric algorithm's CryptoKeyPair. | |
2804 </tag-desc> | |
2805 | |
2806 <tag-name><literal>public</literal></tag-name> | |
2807 <tag-desc> | |
2808 This key is the public half of an asymmetric algorithm's CryptoKeyPair. | |
2809 </tag-desc> | |
2810 | |
2811 </list> | |
2812 </tag-desc> | |
2813 | |
2814 <tag-name id="cryptokey_usages"><literal>CryptoKey.usages</literal></tag-name> | |
2815 <tag-desc> | |
2816 An array of strings indicating what this key can be used for | |
2817 (since <link doc="changes.xml" id="njs0.8.0">0.8.0</link>), | |
2818 read-only. | |
2819 Possible array values: | |
2820 <list type="tag"> | |
2821 | |
2822 <tag-name><literal>encrypt</literal></tag-name> | |
2823 <tag-desc> | |
2824 key for encrypting messages | |
2825 </tag-desc> | |
2826 | |
2827 <tag-name><literal>decrypt</literal></tag-name> | |
2828 <tag-desc> | |
2829 key for decrypting messages | |
2830 </tag-desc> | |
2831 | |
2832 <tag-name><literal>sign</literal></tag-name> | |
2833 <tag-desc> | |
2834 key for signing messages | |
2835 </tag-desc> | |
2836 | |
2837 <tag-name><literal>verify</literal></tag-name> | |
2838 <tag-desc> | |
2839 key for verifying signatures | |
2840 </tag-desc> | |
2841 | |
2842 <tag-name><literal>deriveKey</literal></tag-name> | |
2843 <tag-desc> | |
2844 key for deriving a new key | |
2845 </tag-desc> | |
2846 | |
2847 <tag-name><literal>deriveBits</literal></tag-name> | |
2848 <tag-desc> | |
2849 key for deriving bits | |
2850 </tag-desc> | |
2851 | |
2852 </list> | |
2746 </tag-desc> | 2853 </tag-desc> |
2747 | 2854 |
2748 </list> | 2855 </list> |
2749 </para> | 2856 </para> |
2750 | 2857 |