Mercurial > hg > nginx-site

comparison xml/en/docs/njs/reference.xml @ 2986:2b161541806a

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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