Mercurial > hg > nginx-site

comparison xml/en/docs/njs/reference.xml @ 2783:87713cb4be56

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Documented WebCrypto API for njs Reference.
author Yaroslav Zhuravlev <yar@nginx.com>
date Tue, 19 Oct 2021 15:12:01 +0100
parents bc79ab31073a
children c6713b6b86ce
comparison
equal deleted inserted replaced
2782:8acfa16dd6ef 2783:87713cb4be56
933 933
934 934
935 <section id="builtin_objects" name="built-in objects"> 935 <section id="builtin_objects" name="built-in objects">
936 936
937 937
938 <section id="builtin_crypto" name="crypto">
939
940 <para>
941 The <literal>crypto</literal> object is a global object
942 that allows using cryptographic functionality
943 (since <link doc="changes.xml" id="njs0.7.0">0.7.0</link>).
944 </para>
945
946 <para>
947 <list type="tag">
948
949 <tag-name id="crypto_get_random_values"><literal>сrypto.getRandomValues</literal>(<link id="crypto_get_random_values_array"><literal>typedArray</literal></link>)</tag-name>
950 <tag-desc>
951 Gets cryptographically strong random values.
952 Returns the same array passed as <literal>typedArray</literal>
953 but with its contents replaced with the newly generated random numbers.
954 Possible values:
955
956 <list type="tag">
957 <tag-name id="crypto_get_random_values_array"><literal>typedArray</literal></tag-name>
958 <tag-desc>
959 can be
960 <literal>Int8Array</literal>,
961 <literal>Int16Array</literal>,
962 <literal>Uint16Array</literal>,
963 <literal>Int32Array</literal>, or
964 <literal>Uint32Array</literal>
965 </tag-desc>
966 </list>
967
968 </tag-desc>
969
970 <tag-name id="crypto_subtle_encrypt"><literal>сrypto.subtle.encrypt</literal>(<link id="crypto_encrypt_alg"><literal>algorithm</literal></link>,
971 <link id="crypto_encrypt_key"><literal>key</literal></link>,
972 <link id="crypto_encrypt_data"><literal>data</literal></link>)</tag-name>
973 <tag-desc>
974 Encrypts <link id="crypto_encrypt_data"><literal>data</literal></link>
975 using the provided
976 <link id="crypto_encrypt_algorithm"><literal>algorithm</literal></link> and
977 <link id="crypto_encrypt_key"><literal>key</literal></link>.
978 Returns a <literal>Promise</literal> that fulfills with
979 an <literal>ArrayBuffer</literal> containing the ciphertext.
980 Possible values:
981
982 <list type="tag">
983 <tag-name id="crypto_encrypt_alg"><literal>algorithm</literal></tag-name>
984 <tag-desc>
985 an object that specifies
986 the algorithm to be used and any extra parameters if required:
987
988 <list type="bullet">
989 <listitem id="rsa_oaep_params">
990 for <literal>RSA-OAEP</literal>,
991 pass the object with the following keys:
992
993 <list type="bullet">
994
995 <listitem>
996 <literal>name</literal> is a string,
997 should be set to <literal>RSA-OAEP</literal>:
998 <para>
999 <example>
1000 crypto.subtle.encrypt({name: "RSA-OAEP"}, key, data)
1001 </example>
1002 </para>
1003 </listitem>
1004 </list>
1005
1006 </listitem>
1007
1008 <listitem id="aes_ctr_params">
1009 for <literal>AES-CTR</literal>,
1010 pass the object with the following keys:
1011
1012 <list type="bullet">
1013
1014 <listitem>
1015 <literal>name</literal> is a string,
1016 should be set to <literal>AES-CTR</literal>
1017 </listitem>
1018
1019 <listitem>
1020 <literal>counter</literal> is an
1021 <literal>ArrayBuffer</literal>,
1022 <literal>TypedArray</literal>, or
1023 <literal>DataView</literal> —
1024 the initial value of the counter block,
1025 must be 16 bytes long (the AES block size).
1026 The rightmost length bits of this block are used for the counter,
1027 and the rest is used for the nonce.
1028 For example, if length is set to 64,
1029 then the first half of counter is the nonce
1030 and the second half is used for the counter
1031 </listitem>
1032
1033 <listitem>
1034 <literal>length</literal> is the number of bits in the counter block
1035 that are used for the actual counter.
1036 The counter must be big enough that it doesn't wrap.
1037 </listitem>
1038 </list>
1039
1040 </listitem>
1041
1042 <listitem id="aes_cbc_params">
1043 for <literal>AES-CBC</literal>, pass the object with the following keys:
1044
1045 <list type="bullet">
1046
1047 <listitem>
1048 <literal>name</literal> is a string,
1049 should be set to <literal>AES-CBC</literal>
1050 </listitem>
1051
1052 <listitem>
1053 <literal>iv</literal> or the initialization vector, is an
1054 <literal>ArrayBuffer</literal>,
1055 <literal>TypedArray</literal>, or
1056 <literal>DataView</literal>,
1057 must be 16 bytes, unpredictable,
1058 and preferably cryptographically random.
1059 However, it need not be secret,
1060 for example, it may be transmitted unencrypted along with the ciphertext.
1061 </listitem>
1062 </list>
1063
1064 </listitem>
1065
1066 <listitem id="aes_gcm_params">
1067 for <literal>AES-GCM</literal>, pass the object with the following keys:
1068
1069 <list type="bullet">
1070
1071 <listitem>
1072 <literal>name</literal> is a string,
1073 should be set to <literal>AES-GCM</literal>
1074 </listitem>
1075
1076 <listitem>
1077 <literal>iv</literal> or the initialization vector, is an
1078 <literal>ArrayBuffer</literal>,
1079 <literal>TypedArray</literal>, or
1080 <literal>DataView</literal>,
1081 must be 16 bytes,
1082 and must be unique for every encryption operation carried out with a given key
1083 </listitem>
1084
1085 <listitem>
1086 <literal>additionalData</literal> (optional) is an
1087 <literal>ArrayBuffer</literal>,
1088 <literal>TypedArray</literal>, or
1089 <literal>DataView</literal>
1090 that contains additional data that
1091 will not be encrypted but will be authenticated along with the encrypted data.
1092 If <literal>additionalData</literal> is specified,
1093 then the same data must be specified in the corresponding call to
1094 <literal>decrypt()</literal>:
1095 if the data given to the <literal>decrypt()</literal> call
1096 does not match the original data,
1097 the decryption will throw an exception.
1098 The bit length of <literal>additionalData</literal>
1099 must be smaller than <literal>2^64 - 1</literal>.
1100 </listitem>
1101
1102 <listitem>
1103 <literal>tagLength</literal> (optional, default is <literal>128</literal>) -
1104 a <literal>number</literal> that determines the size in bits
1105 of the authentication tag generated in the encryption operation
1106 and used for authentication in the corresponding decryption
1107 Possible values:
1108 <literal>32</literal>,
1109 <literal>64</literal>,
1110 <literal>96</literal>,
1111 <literal>104</literal>,
1112 <literal>112</literal>,
1113 <literal>120</literal>, or
1114 <literal>128</literal>.
1115 The AES-GCM specification recommends that it should be
1116 <literal>96</literal>,
1117 <literal>104</literal>,
1118 <literal>112</literal>,
1119 <literal>120</literal>, or
1120 <literal>128</literal>,
1121 although
1122 <literal>32</literal> or
1123 <literal>64</literal>
1124 bits may be acceptable in some applications.
1125 </listitem>
1126 </list>
1127
1128 </listitem>
1129 </list>
1130
1131 </tag-desc>
1132
1133 <tag-name id="crypto_encrypt_key"><literal>key</literal></tag-name>
1134 <tag-desc>
1135 a <literal>CryptoKey</literal> that contains
1136 the key to be used for encryption
1137 </tag-desc>
1138
1139 <tag-name id="crypto_encrypt_data"><literal>data</literal></tag-name>
1140 <tag-desc>
1141 an
1142 <literal>ArrayBuffer</literal>,
1143 <literal>TypedArray</literal>, or
1144 <literal>DataView</literal>
1145 that contains
1146 the data to be encrypted (also known as the plaintext)
1147 </tag-desc>
1148 </list>
1149
1150 </tag-desc>
1151
1152 <tag-name id="crypto_subtle_decrypt"><literal>сrypto.subtle.decrypt</literal>(<link id="crypto_decrypt_alg"><literal>algorithm</literal></link>,
1153 <link id="crypto_decrypt_key"><literal>key</literal></link>,
1154 <link id="crypto_decrypt_data"><literal>data</literal></link>)</tag-name>
1155 <tag-desc>
1156 Decrypts encrypted data.
1157 Returns a <literal>Promise</literal> with the decrypted data.
1158 Possible values:
1159
1160 <list type="tag">
1161
1162 <tag-name id="crypto_decrypt_alg"><literal>algorithm</literal></tag-name>
1163 <tag-desc>
1164 an object
1165 that specifies the algorithm to be used, and any extra parameters as required.
1166 The values given for the extra parameters must match
1167 those passed into the corresponding <literal>encrypt()</literal> call.
1168
1169 <list type="bullet">
1170 <listitem>
1171 for <literal>RSA-OAEP</literal>,
1172 pass the object with the following keys:
1173
1174 <list type="bullet">
1175
1176 <listitem>
1177 <literal>name</literal> is a string,
1178 should be set to <literal>RSA-OAEP</literal>:
1179 <para>
1180 <example>
1181 crypto.subtle.encrypt({name: "RSA-OAEP"}, key, data)
1182 </example>
1183 </para>
1184 </listitem>
1185 </list>
1186 </listitem>
1187
1188 <listitem>
1189 for <literal>AES-CTR</literal>,
1190 pass the object with the following keys:
1191
1192 <list type="bullet">
1193
1194 <listitem>
1195 <literal>name</literal> is a string,
1196 should be set to <literal>AES-CTR</literal>
1197 </listitem>
1198
1199 <listitem>
1200 <literal>counter</literal> is an
1201 <literal>ArrayBuffer</literal>,
1202 <literal>TypedArray</literal>, or
1203 <literal>DataView</literal> —
1204 the initial value of the counter block,
1205 must be 16 bytes long (the AES block size).
1206 The rightmost length bits of this block are used for the counter,
1207 and the rest is used for the nonce.
1208 For example, if length is set to 64,
1209 then the first half of counter is the nonce
1210 and the second half is used for the counter.
1211 </listitem>
1212
1213 <listitem>
1214 <literal>length</literal> is the number of bits in the counter block
1215 that are used for the actual counter.
1216 The counter must be big enough that it doesn't wrap.
1217 </listitem>
1218 </list>
1219
1220 </listitem>
1221
1222 <listitem>
1223 for <literal>AES-CBC</literal>, pass the object with the following keys:
1224
1225 <list type="bullet">
1226
1227 <listitem>
1228 <literal>name</literal> is a string,
1229 should be set to <literal>AES-CBC</literal>
1230 </listitem>
1231
1232 <listitem>
1233 <literal>iv</literal> or the initialization vector, is an
1234 <literal>ArrayBuffer</literal>,
1235 <literal>TypedArray</literal>, or
1236 <literal>DataView</literal>,
1237 must be 16 bytes, unpredictable,
1238 and preferably cryptographically random.
1239 However, it need not be secret
1240 (for example, it may be transmitted unencrypted along with the ciphertext).
1241 </listitem>
1242 </list>
1243
1244 </listitem>
1245
1246 <listitem>
1247 for <literal>AES-GCM</literal>, pass the object with the following keys:
1248
1249 <list type="bullet">
1250
1251 <listitem>
1252 <literal>name</literal> is a string,
1253 should be set to <literal>AES-GCM</literal>
1254 </listitem>
1255
1256 <listitem>
1257 <literal>iv</literal> or the initialization vector, is an
1258 <literal>ArrayBuffer</literal>,
1259 <literal>TypedArray</literal>, or
1260 <literal>DataView</literal>,
1261 must be 16 bytes,
1262 and must be unique for every encryption operation carried out with a given key
1263 </listitem>
1264
1265 <listitem>
1266 <literal>additionalData</literal> (optional) is an
1267 <literal>ArrayBuffer</literal>,
1268 <literal>TypedArray</literal>, or
1269 <literal>DataView</literal>
1270 that contains additional data that
1271 will not be encrypted but will be authenticated along with the encrypted data.
1272 If <literal>additionalData</literal> is specified,
1273 then the same data must be specified in the corresponding call to
1274 <literal>decrypt()</literal>:
1275 if the data given to the <literal>decrypt()</literal> call
1276 does not match the original data,
1277 the decryption will throw an exception.
1278 The bit length of <literal>additionalData</literal>
1279 must be smaller than <literal>2^64 - 1</literal>.
1280 </listitem>
1281
1282 <listitem>
1283 <literal>tagLength</literal> (optional, default is <literal>128</literal>) -
1284 a <literal>number</literal> that determines the size in bits
1285 of the authentication tag generated in the encryption operation
1286 and used for authentication in the corresponding decryption.
1287 Possible values:
1288 <literal>32</literal>,
1289 <literal>64</literal>,
1290 <literal>96</literal>,
1291 <literal>104</literal>,
1292 <literal>112</literal>,
1293 <literal>120</literal>, or
1294 <literal>128</literal>.
1295 The AES-GCM specification recommends that it should be
1296 <literal>96</literal>,
1297 <literal>104</literal>,
1298 <literal>112</literal>,
1299 <literal>120</literal>, or
1300 <literal>128</literal>,
1301 although
1302 <literal>32</literal> or
1303 <literal>64</literal>
1304 bits may be acceptable in some applications.
1305 </listitem>
1306 </list>
1307
1308 </listitem>
1309 </list>
1310
1311 </tag-desc>
1312
1313 <tag-name id="crypto_decrypt_key"><literal>key</literal></tag-name>
1314 <tag-desc>
1315 a <literal>CryptoKey</literal>
1316 that contains the key to be used for decryption.
1317 If <literal>RSA-OAEP</literal> is used, this is the
1318 <literal>privateKey</literal> property of the
1319 <literal>CryptoKeyPair</literal> object.
1320 </tag-desc>
1321
1322 <tag-name id="crypto_decrypt_data"><literal>data</literal></tag-name>
1323 <tag-desc>
1324 an
1325 <literal>ArrayBuffer</literal>,
1326 <literal>TypedArray</literal>, or
1327 <literal>DataView</literal>
1328 that contains the data to be decrypted (also known as ciphertext)
1329 </tag-desc>
1330 </list>
1331
1332 </tag-desc>
1333
1334 <tag-name id="crypto_subtle_derive_bits"><literal>сrypto.subtle.deriveBits</literal>(<link id="crypto_derive_bits_alg"><literal>algorithm</literal></link>,
1335 <link id="crypto_derive_bits_basekey"><literal>baseKey</literal></link>,
1336 <link id="crypto_derive_bits_length"><literal>length</literal></link>)</tag-name>
1337 <tag-desc>
1338 Derives an array of bits from a base key.
1339 Returns a <literal>Promise</literal>
1340 which will be fulfilled with an
1341 <literal>ArrayBuffer</literal> that contains the derived bits.
1342 Possible values:
1343
1344 <list type="tag">
1345 <tag-name id="crypto_derive_bits_alg"><literal>algorithm</literal></tag-name>
1346 <tag-desc>
1347 is an object that defines the derivation algorithm to use:
1348
1349 <list type="bullet">
1350 <listitem id="hkdf_params">
1351 for <literal>HKDF</literal>,
1352 pass the object with the following keys:
1353
1354 <list type="bullet">
1355
1356 <listitem>
1357 <literal>name</literal> is a string,
1358 should be set to <literal>HKDF</literal>
1359 </listitem>
1360
1361 <listitem>
1362 <literal>hash</literal> is a string with the digest algorithm to use:
1363 <literal>SHA-1</literal>,
1364 <literal>SHA-256</literal>,
1365 <literal>SHA-384</literal>, or
1366 <literal>SHA-512</literal>
1367 </listitem>
1368
1369 <listitem>
1370 <literal>salt</literal> is an
1371 <literal>ArrayBuffer</literal>,
1372 <literal>TypedArray</literal>, or
1373 <literal>DataView</literal>
1374 that represents random or pseudo-random value
1375 with the same length as the output of the <literal>digest</literal> function.
1376 Unlike the input key material passed into <literal>deriveKey()</literal>,
1377 salt does not need to be kept secret.
1378 </listitem>
1379
1380 <listitem>
1381 <literal>info</literal> is an
1382 <literal>ArrayBuffer</literal>,
1383 <literal>TypedArray</literal>, or
1384 <literal>DataView</literal>
1385 that represents application-specific contextual information
1386 used to bind the derived key to an application or context,
1387 and enables deriving different keys for different contexts
1388 while using the same input key material.
1389 This property is required but may be an empty buffer.
1390 </listitem>
1391 </list>
1392
1393 </listitem>
1394
1395 <listitem id="pbkdf2_params">
1396 for <literal>PBKDF2</literal>,
1397 pass the object with the following keys:
1398
1399 <list type="bullet">
1400
1401 <listitem>
1402 <literal>name</literal> is a string,
1403 should be set to <literal>PBKDF2</literal>
1404 </listitem>
1405
1406 <listitem>
1407 <literal>hash</literal> is a string with the digest algorithm to use:
1408 <literal>SHA-1</literal>,
1409 <literal>SHA-256</literal>,
1410 <literal>SHA-384</literal>, or
1411 <literal>SHA-512</literal>
1412 </listitem>
1413
1414 <listitem>
1415 <literal>salt</literal> is an
1416 <literal>ArrayBuffer</literal>,
1417 <literal>TypedArray</literal>, or
1418 <literal>DataView</literal>
1419 that represents random or pseudo-random value
1420 of at least <literal>16</literal> bytes.
1421 Unlike the input key material passed into <literal>deriveKey()</literal>,
1422 salt does not need to be kept secret.
1423 </listitem>
1424
1425 <listitem>
1426 <literal>iterations</literal> is a <literal>number</literal>
1427 that represents the number of times the hash function will be executed
1428 in <literal>deriveKey()</literal>
1429 </listitem>
1430 </list>
1431
1432 </listitem>
1433 </list>
1434
1435 </tag-desc>
1436
1437 <tag-name id="crypto_derive_bits_basekey"><literal>baseKey</literal></tag-name>
1438 <tag-desc>
1439 is a <literal>CryptoKey</literal>
1440 that represents the input to the derivation algorithm
1441 - the initial key material for the derivation function:
1442 for example, for <literal>PBKDF2</literal> it might be a password,
1443 imported as a <literal>CryptoKey</literal> using
1444 <link id="crypto_subtle_import_key"><literal>сrypto.subtle.importKey()</literal></link>
1445 </tag-desc>
1446
1447 <tag-name id="crypto_derive_bits_length"><literal>length</literal></tag-name>
1448 <tag-desc>
1449 is a number representing the number of bits to derive.
1450 For browsers compatibility,
1451 the number should be a multiple of <literal>8</literal>
1452 </tag-desc>
1453 </list>
1454
1455 </tag-desc>
1456
1457 <tag-name id="crypto_subtle_derive_key"><literal>сrypto.subtle.deriveKey</literal>(<link id="crypto_derive_key_alg"><literal>algorithm</literal></link>,
1458 <link id="crypto_derive_key_basekey"><literal>baseKey</literal></link>,
1459 <link id="crypto_derive_key_derivedkeyalg"><literal>derivedKeyAlgorithm</literal></link>,
1460 <link id="crypto_derive_key_extractable"><literal>extractable</literal></link>,
1461 <link id="crypto_derive_key_keyusages"><literal>keyUsages</literal></link>)</tag-name>
1462 <tag-desc>
1463 Derives a secret key from a master key.
1464 Possible values:
1465
1466 <list type="tag">
1467 <tag-name id="crypto_derive_key_alg"><literal>algorithm</literal></tag-name>
1468 <tag-desc>
1469 is an object that defines the derivation algorithm to use:
1470
1471 <list type="bullet">
1472 <listitem>
1473 for <literal>HKDF</literal>,
1474 pass the object with the following keys:
1475
1476 <list type="bullet">
1477
1478 <listitem>
1479 <literal>name</literal> is a string,
1480 should be set to <literal>HKDF</literal>
1481 </listitem>
1482
1483 <listitem>
1484 <literal>hash</literal> is a string with the digest algorithm to use:
1485 <literal>SHA-1</literal>,
1486 <literal>SHA-256</literal>,
1487 <literal>SHA-384</literal>, or
1488 <literal>SHA-512</literal>
1489 </listitem>
1490
1491 <listitem>
1492 <literal>salt</literal> is an
1493 <literal>ArrayBuffer</literal>,
1494 <literal>TypedArray</literal>, or
1495 <literal>DataView</literal>
1496 that represents random or pseudo-random value
1497 with the same length as the output of the <literal>digest</literal> function.
1498 Unlike the input key material passed into <literal>deriveKey()</literal>,
1499 salt does not need to be kept secret.
1500 </listitem>
1501
1502 <listitem>
1503 <literal>info</literal> is an
1504 <literal>ArrayBuffer</literal>,
1505 <literal>TypedArray</literal>, or
1506 <literal>DataView</literal>
1507 that represents application-specific contextual information
1508 used to bind the derived key to an application or context,
1509 and enables deriving different keys for different contexts
1510 while using the same input key material.
1511 This property is required but may be an empty buffer.
1512 </listitem>
1513 </list>
1514
1515 </listitem>
1516
1517 <listitem>
1518 for <literal>PBKDF2</literal>,
1519 pass the object with the following keys:
1520
1521 <list type="bullet">
1522
1523 <listitem>
1524 <literal>name</literal> is a string,
1525 should be set to <literal>PBKDF2</literal>
1526 </listitem>
1527
1528 <listitem>
1529 <literal>hash</literal> is a string with the digest algorithm to use:
1530 <literal>SHA-1</literal>,
1531 <literal>SHA-256</literal>,
1532 <literal>SHA-384</literal>, or
1533 <literal>SHA-512</literal>
1534 </listitem>
1535
1536 <listitem>
1537 <literal>salt</literal> is an
1538 <literal>ArrayBuffer</literal>,
1539 <literal>TypedArray</literal>, or
1540 <literal>DataView</literal>
1541 that represents random or pseudo-random value
1542 of at least <literal>16</literal> bytes.
1543 Unlike the input key material passed into <literal>deriveKey()</literal>,
1544 salt does not need to be kept secret.
1545 </listitem>
1546
1547 <listitem>
1548 <literal>iterations</literal> is a <literal>number</literal>
1549 that represents the number of times the hash function will be executed
1550 in <literal>deriveKey()</literal>
1551 </listitem>
1552 </list>
1553
1554 </listitem>
1555 </list>
1556
1557 </tag-desc>
1558
1559 <tag-name id="crypto_derive_key_basekey"><literal>baseKey</literal></tag-name>
1560 <tag-desc>
1561 is a <literal>CryptoKey</literal>
1562 that represents the input to the derivation algorithm
1563 - the initial key material for the derivation function:
1564 for example, for <literal>PBKDF2</literal> it might be a password,
1565 imported as a <literal>CryptoKey</literal> using
1566 <link id="crypto_sublte_import_key"><literal>сrypto.subtle.importKey()</literal></link>.
1567 </tag-desc>
1568
1569 <tag-name id="crypto_derive_key_derivedkeyalg"><literal>derivedKeyAlgorithm</literal></tag-name>
1570 <tag-desc>
1571 is an object
1572 that defines the algorithm the derived key will be used for:
1573
1574 <list type="bullet">
1575 <listitem>
1576 for <literal>HMAC</literal>,
1577 pass the object with the following keys:
1578
1579 <list type="bullet">
1580
1581 <listitem>
1582 <literal>name</literal> is a string,
1583 should be set to <literal>HMAC</literal>
1584 </listitem>
1585
1586 <listitem>
1587 <literal>hash</literal> is a string with the name of the digest function to use:
1588 <literal>SHA-1</literal>,
1589 <literal>SHA-256</literal>,
1590 <literal>SHA-384</literal>, or
1591 <literal>SHA-512</literal>
1592 </listitem>
1593
1594 <listitem>
1595 <literal>length</literal> (optional) is a <literal>number</literal>
1596 that represents the length in bits of the key.
1597 If not specified, the length of the key is equal to
1598 the block size of the chozen hash function
1599 </listitem>
1600 </list>
1601
1602 </listitem>
1603
1604 <listitem>
1605 for
1606 <literal>AES-CTR</literal>,
1607 <literal>AES-CBC</literal>, or
1608 <literal>AES-GCM</literal>,
1609 pass the object with the following keys:
1610
1611 <list type="bullet">
1612
1613 <listitem>
1614 <literal>name</literal> is a string,
1615 should be set to
1616 <literal>AES-CTR</literal>,
1617 <literal>AES-CBC</literal>, or
1618 <literal>AES-GCM</literal>,
1619 depending on the algorithm used
1620 </listitem>
1621
1622 <listitem>
1623 <literal>length</literal> is a <literal>number</literal> that represents
1624 the length in bits of the key to generate:
1625 <literal>128</literal>,
1626 <literal>192</literal>, or
1627 <literal>256</literal>
1628 </listitem>
1629 </list>
1630
1631 </listitem>
1632 </list>
1633
1634 </tag-desc>
1635
1636 <tag-name id="crypto_derive_key_extractable"><literal>extractable</literal></tag-name>
1637 <tag-desc>
1638 is a boolean value
1639 that indicates whether it will be possible to export the key
1640 </tag-desc>
1641
1642 <tag-name id="crypto_derive_key_keyusages"><literal>keyUsages</literal></tag-name>
1643 <tag-desc>
1644 is an <literal>Array</literal>
1645 that indicates what can be done with the derived key.
1646 The key usages must be allowed by the algorithm
1647 set in <literal>derivedKeyAlgorithm</literal>.
1648 Possible values:
1649 <list type="tag">
1650
1651 <tag-name><literal>encrypt</literal></tag-name>
1652 <tag-desc>
1653 key for encrypting messages
1654 </tag-desc>
1655
1656 <tag-name><literal>decrypt</literal></tag-name>
1657 <tag-desc>
1658 key for decrypting messages
1659 </tag-desc>
1660
1661 <tag-name><literal>sign</literal></tag-name>
1662 <tag-desc>
1663 key for signing messages
1664 </tag-desc>
1665
1666 <tag-name><literal>verify</literal></tag-name>
1667 <tag-desc>
1668 key for verifying signatures
1669 </tag-desc>
1670
1671 <tag-name><literal>deriveKey</literal></tag-name>
1672 <tag-desc>
1673 key for deriving a new key
1674 </tag-desc>
1675
1676 <tag-name><literal>deriveBits</literal></tag-name>
1677 <tag-desc>
1678 key for deriving bits
1679 </tag-desc>
1680
1681 <tag-name><literal>wrapKey</literal></tag-name>
1682 <tag-desc>
1683 key for wrapping a key
1684 </tag-desc>
1685
1686 <tag-name><literal>unwrapKey</literal></tag-name>
1687 <tag-desc>
1688 key for unwrapping a key
1689 </tag-desc>
1690 </list>
1691
1692 </tag-desc>
1693 </list>
1694
1695 </tag-desc>
1696
1697 <tag-name id="crypto_subtle_digest"><literal>сrypto.subtle.digest</literal>(<link id="crypto_digest_alg"><literal>algorithm</literal></link>,
1698 <link id="crypto_digest_data"><literal>data</literal></link>)</tag-name>
1699 <tag-desc>
1700 Generates a digest of the given data.
1701 Takes as its arguments an identifier for the digest algorithm to use
1702 and the data to digest.
1703 Returns a <literal>Promise</literal> which will be fulfilled with the digest.
1704 Possible values:
1705
1706 <list type="tag">
1707 <tag-name id="crypto_digest_alg"><literal>algorithm</literal></tag-name>
1708 <tag-desc>
1709 is a string that defines the hash function to use:
1710 <literal>SHA-1</literal> (not for cryptographic applications),
1711 <literal>SHA-256</literal>,
1712 <literal>SHA-384</literal>, or
1713 <literal>SHA-512</literal>
1714 </tag-desc>
1715
1716 <tag-name id="crypto_digest_data"><literal>data</literal></tag-name>
1717 <tag-desc>
1718 is an
1719 <literal>ArrayBuffer</literal>,
1720 <literal>TypedArray</literal>, or
1721 <literal>DataView</literal>
1722 that contains the data to be digested
1723 </tag-desc>
1724 </list>
1725
1726 </tag-desc>
1727
1728 <tag-name id="crypto_subtle_import_key"><literal>сrypto.subtle.importKey</literal>(<link id="crypto_import_key_format"><literal>format</literal></link>,
1729 <link id="crypto_import_key_keydata"><literal>keyData</literal></link>,
1730 <link id="crypto_import_key_alg"><literal>algorithm</literal></link>,
1731 <link id="crypto_import_key_extractable"><literal>extractable</literal></link>,
1732 <link id="crypto_import_key_keyusages"><literal>keyUsages</literal></link>)</tag-name>
1733 <tag-desc>
1734 Imports a key: takes as input a key in an external, portable format
1735 and gives a <literal>CryptoKey</literal> object.
1736 Returns a <literal>Promise</literal> that fulfills with the imported key
1737 as a <literal>CryptoKey</literal> object.
1738 Possible values:
1739 <list type="tag">
1740
1741 <tag-name id="crypto_import_key_format"><literal>format</literal></tag-name>
1742 <tag-desc>
1743 a string that describes the data format of the key to import,
1744 can be the following:
1745 <list type="tag">
1746
1747 <tag-name><literal>raw</literal></tag-name>
1748 <tag-desc>
1749 the raw data format
1750 </tag-desc>
1751
1752 <tag-name><literal>pkcs8</literal></tag-name>
1753 <tag-desc>
1754 the
1755 <link url="https://datatracker.ietf.org/doc/html/rfc5208">PKCS #8</link>
1756 format
1757 </tag-desc>
1758
1759 <tag-name><literal>spki</literal></tag-name>
1760 <tag-desc>
1761 the
1762 <link url=" https://datatracker.ietf.org/doc/html/rfc5280#section-4.1">SubjectPublicKeyInfo</link>
1763 format
1764 </tag-desc>
1765
1766 </list>
1767
1768 </tag-desc>
1769
1770 <tag-name id="crypto_import_key_keydata"><literal>keyData</literal></tag-name>
1771 <tag-desc>
1772 the
1773 <literal>ArrayBuffer</literal>,
1774 <literal>TypedArray</literal>, or
1775 <literal>DataView</literal>
1776 object that contains the key in the given format
1777 </tag-desc>
1778
1779 <tag-name id="crypto_import_key_alg"><literal>algorithm</literal></tag-name>
1780 <tag-desc>
1781 a dictionary object that defines the type of key to import
1782 and provides extra algorithm-specific parameters:
1783
1784 <list type="bullet">
1785 <listitem>
1786 for
1787 <literal>RSASSA-PKCS1-v1_5</literal>,
1788 <literal>RSA-PSS</literal>, or
1789 <literal>RSA-OAEP</literal>,
1790 pass the object with the following keys:
1791
1792 <list type="bullet">
1793 <listitem>
1794 <literal>name</literal> is a string, should be set to
1795 <literal>RSASSA-PKCS1-v1_5</literal>,
1796 <literal>RSA-PSS</literal>, or
1797 <literal>RSA-OAEP</literal>,
1798 depending on the used algorithm
1799 </listitem>
1800
1801 <listitem>
1802 <literal>hash</literal> is a string that represents
1803 the name of the <literal>digest</literal> function to use, can be
1804 <literal>SHA-256</literal>,
1805 <literal>SHA-384</literal>, or
1806 <literal>SHA-512</literal>
1807 </listitem>
1808 </list>
1809
1810 </listitem>
1811
1812 <listitem>
1813 for
1814 <literal>ECDSA</literal>,
1815 pass the object with the following keys:
1816
1817 <list type="bullet">
1818 <listitem>
1819 <literal>name</literal> is a string, should be set to <literal>ECDSA</literal>
1820 </listitem>
1821
1822 <listitem>
1823 <literal>namedCurve</literal> is a string that represents
1824 the name of the elliptic curve to use, may be
1825 <literal>P-256</literal>,
1826 <literal>P-384</literal>, or
1827 <literal>P-521</literal>
1828 </listitem>
1829
1830 </list>
1831 </listitem>
1832
1833 <listitem>
1834 for
1835 <literal>HMAC</literal>,
1836 pass the object with the following keys:
1837
1838 <list type="bullet">
1839 <listitem>
1840 <literal>name</literal> is a string, should be set to <literal>HMAC</literal>
1841 </listitem>
1842
1843
1844 <listitem>
1845 <literal>hash</literal> is a string that represents
1846 the name of the <literal>digest</literal> function to use, can be
1847 <literal>SHA-256</literal>,
1848 <literal>SHA-384</literal>, or
1849 <literal>SHA-512</literal>
1850 </listitem>
1851
1852 <listitem>
1853 <literal>length</literal> (optional) is a number that represents
1854 the length in bits of the key.
1855 If omitted, the length of the key is equal to the length of the digest
1856 generated by the chosen digest function.
1857 </listitem>
1858 </list>
1859
1860 </listitem>
1861
1862 <listitem>
1863 for
1864 <literal>AES-CTR</literal>,
1865 <literal>AES-CBC</literal>, or
1866 <literal>AES-GCM</literal>,
1867 pass the string identifying the algorithm or an object
1868 of the form <literal>{ "name": "ALGORITHM" }</literal>,
1869 where <literal>ALGORITHM</literal> is the name of the algorithm
1870 </listitem>
1871
1872 <listitem>
1873 for
1874 <literal>PBKDF2</literal>,
1875 pass the <literal>PBKDF2</literal> string
1876 </listitem>
1877
1878 <listitem>
1879 for
1880 <literal>HKDF</literal>,
1881 pass the <literal>HKDF</literal> string
1882 </listitem>
1883
1884 </list>
1885 </tag-desc>
1886
1887 <tag-name id="crypto_import_key_extractable"><literal>extractable</literal></tag-name>
1888 <tag-desc>
1889 boolean value that indicates if it is possible to export the key
1890 </tag-desc>
1891
1892 <tag-name id="crypto_import_key_keyusages"><literal>keyUsages</literal></tag-name>
1893 <tag-desc>
1894 an <literal>array</literal> that indicates possible actions with the key:
1895 <list type="tag">
1896
1897 <tag-name><literal>encrypt</literal></tag-name>
1898 <tag-desc>
1899 key for encrypting messages
1900 </tag-desc>
1901
1902 <tag-name><literal>decrypt</literal></tag-name>
1903 <tag-desc>
1904 key for decrypting messages
1905 </tag-desc>
1906
1907 <tag-name><literal>sign</literal></tag-name>
1908 <tag-desc>
1909 key for signing messages
1910 </tag-desc>
1911
1912 <tag-name><literal>verify</literal></tag-name>
1913 <tag-desc>
1914 key for verifying signatures
1915 </tag-desc>
1916
1917 <tag-name><literal>deriveKey</literal></tag-name>
1918 <tag-desc>
1919 key for deriving a new key
1920 </tag-desc>
1921
1922 <tag-name><literal>deriveBits</literal></tag-name>
1923 <tag-desc>
1924 key for deriving bits
1925 </tag-desc>
1926
1927 <tag-name><literal>wrapKey</literal></tag-name>
1928 <tag-desc>
1929 key for wrapping a key
1930 </tag-desc>
1931
1932 <tag-name><literal>unwrapKey</literal></tag-name>
1933 <tag-desc>
1934 key for unwrapping a key
1935 </tag-desc>
1936 </list>
1937
1938 </tag-desc>
1939 </list>
1940
1941 </tag-desc>
1942
1943 <tag-name id="crypto_subtle_sign"><literal>сrypto.subtle.sign</literal>(<link id="crypto_sign_alg"><literal>algorithm</literal></link>,
1944 <link id="crypto_sign_key"><literal>key</literal></link>,
1945 <link id="crypto_sign_data"><literal>data</literal></link>)</tag-name>
1946 <tag-desc>
1947 Returns <literal>signature</literal> as a <literal>Promise</literal>
1948 that fulfills with an <literal>ArrayBuffer</literal> containing the signature.
1949 Possible values:
1950
1951 <list type="tag">
1952 <tag-name id="crypto_sign_alg"><literal>algorithm</literal></tag-name>
1953 <tag-desc>
1954 is a string or object that specifies the signature algorithm to use
1955 and its parameters:
1956
1957 <list type="bullet">
1958
1959 <listitem>
1960 for <literal>RSASSA-PKCS1-v1_5</literal>,
1961 pass the string identifying the algorithm or an object
1962 of the form <literal>{ "name": "ALGORITHM" }</literal>
1963 </listitem>
1964
1965 <listitem>
1966 for <literal>RSA-PSS</literal>,
1967 pass the object with the following keys:
1968 <list type="bullet">
1969
1970 <listitem>
1971 <literal>name</literal> is a string, should be set to
1972 <literal>RSA-PSS</literal>
1973 </listitem>
1974
1975 <listitem>
1976 <literal>saltLength</literal> is a long <literal>integer</literal>
1977 that represents the length of the random salt to use, in bytes
1978 </listitem>
1979
1980 </list>
1981 </listitem>
1982
1983 <listitem>
1984 for <literal>ECDSA</literal>,
1985 pass the object with the following keys:
1986 <list type="bullet">
1987
1988 <listitem>
1989 <literal>name</literal> is a string, should be set to
1990 <literal>ECDSA</literal>
1991 </listitem>
1992
1993 <listitem>
1994 <literal>hash</literal> is an identifier for the digest algorithm to use,
1995 can be
1996 <literal>SHA-256</literal>,
1997 <literal>SHA-384</literal>, or
1998 <literal>SHA-512</literal>
1999 </listitem>
2000
2001 </list>
2002 </listitem>
2003
2004 <listitem>
2005 for <literal>HMAC</literal>,
2006 pass the string identifying the algorithm or an object
2007 of the form <literal>{ "name": "ALGORITHM" }</literal>
2008 </listitem>
2009 </list>
2010
2011 </tag-desc>
2012
2013 <tag-name id="crypto_sign_key"><literal>key</literal></tag-name>
2014 <tag-desc>
2015 is a <literal>CryptoKey</literal> object that the key to be used for signing.
2016 If algorithm identifies a public-key cryptosystem, this is the private key.
2017 </tag-desc>
2018
2019 <tag-name id="crypto_sign_data"><literal>data</literal></tag-name>
2020 <tag-desc>
2021 is an
2022 <literal>ArrayBuffer</literal>,
2023 <literal>TypedArray</literal>, or
2024 <literal>DataView</literal>
2025 object that contains the data to be signed
2026 </tag-desc>
2027 </list>
2028
2029 </tag-desc>
2030
2031
2032 <tag-name id="crypto_subtle_verify"><literal>сrypto.subtle.verify</literal>(<link id="crypto_verify_alg"><literal>algorithm</literal></link>,
2033 <link id="crypto_verify_key"><literal>key</literal></link>,
2034 <link id="crypto_verify_signature"><literal>signature</literal></link>,
2035 <link id="crypto_verify_data"><literal>data</literal></link>)</tag-name>
2036 <tag-desc>
2037 Verifies a digital signature,
2038 returns a <literal>Promise</literal> that fulfills with a boolean value:
2039 <literal>true</literal> if the signature is valid,
2040 otherwise <literal>false</literal>.
2041 Possible values:
2042
2043 <list type="tag">
2044 <tag-name id="crypto_verify_alg"><literal>algorithm</literal></tag-name>
2045 <tag-desc>
2046 is a string or object that specifies the algorithm to use
2047 and its parameters:
2048
2049 <list type="bullet">
2050
2051 <listitem>
2052 for <literal>RSASSA-PKCS1-v1_5</literal>,
2053 pass the string identifying the algorithm or an object
2054 of the form <literal>{ "name": "ALGORITHM" }</literal>
2055 </listitem>
2056
2057 <listitem>
2058 for <literal>RSA-PSS</literal>,
2059 pass the object with the following keys:
2060 <list type="bullet">
2061
2062 <listitem>
2063 <literal>name</literal> is a string, should be set to
2064 <literal>RSA-PSS</literal>
2065 </listitem>
2066
2067 <listitem>
2068 <literal>saltLength</literal> is a long <literal>integer</literal>
2069 that represents the length of the random salt to use, in bytes
2070 </listitem>
2071
2072 </list>
2073 </listitem>
2074
2075 <listitem>
2076 for <literal>ECDSA</literal>,
2077 pass the object with the following keys:
2078 <list type="bullet">
2079
2080 <listitem>
2081 <literal>name</literal> is a string, should be set to
2082 <literal>ECDSA</literal>
2083 </listitem>
2084
2085 <listitem>
2086 <literal>hash</literal> is an identifier for the digest algorithm to use,
2087 can be
2088 <literal>SHA-256</literal>,
2089 <literal>SHA-384</literal>, or
2090 <literal>SHA-512</literal>
2091 </listitem>
2092
2093 </list>
2094 </listitem>
2095
2096 <listitem>
2097 for <literal>HMAC</literal>,
2098 pass the string identifying the algorithm or an object
2099 of the form <literal>{ "name": "ALGORITHM" }</literal>
2100 </listitem>
2101 </list>
2102
2103 </tag-desc>
2104
2105 <tag-name id="crypto_verify_key"><literal>key</literal></tag-name>
2106 <tag-desc>
2107 is a <literal>CryptoKey</literal> object that the key to be used for verifying.
2108 It is the secret key for a symmetric algorithm
2109 and the public key for a public-key system.
2110 </tag-desc>
2111
2112 <tag-name id="crypto_verify_signature"><literal>signature</literal></tag-name>
2113 <tag-desc>
2114 is an
2115 <literal>ArrayBuffer</literal>,
2116 <literal>TypedArray</literal>, or
2117 <literal>DataView</literal>
2118 that contains the signature to verify
2119 </tag-desc>
2120
2121 <tag-name id="crypto_verify_data"><literal>data</literal></tag-name>
2122 <tag-desc>
2123 is an
2124 <literal>ArrayBuffer</literal>,
2125 <literal>TypedArray</literal>, or
2126 <literal>DataView</literal>
2127 object that contains the data whose signature is to be verified
2128 </tag-desc>
2129 </list>
2130
2131 </tag-desc>
2132
2133 </list>
2134 </para>
2135
2136 </section>
2137
2138
938 <section id="njs" name="njs"> 2139 <section id="njs" name="njs">
939 2140
940 <para> 2141 <para>
941 The <literal>njs</literal> object is a global object 2142 The <literal>njs</literal> object is a global object
942 that represents the current VM instance 2143 that represents the current VM instance
947 <list type="tag"> 2148 <list type="tag">
948 2149
949 <tag-name id="njs_version"><literal>njs.version</literal></tag-name> 2150 <tag-name id="njs_version"><literal>njs.version</literal></tag-name>
950 <tag-desc> 2151 <tag-desc>
951 Returns a string with the current version of njs 2152 Returns a string with the current version of njs
952 (for example, “0.5.2”). 2153 (for example, “0.7.0”).
953 </tag-desc> 2154 </tag-desc>
954 2155
955 <tag-name id="njs_dump"><literal>njs.dump(<value>value</value>)</literal></tag-name> 2156 <tag-name id="njs_dump"><literal>njs.dump(<value>value</value>)</literal></tag-name>
956 <tag-desc> 2157 <tag-desc>
957 Returns the pretty-print string representation for a value. 2158 Returns the pretty-print string representation for a value.
1917 3118
1918 3119
1919 <section id="crypto" name="Crypto"> 3120 <section id="crypto" name="Crypto">
1920 3121
1921 <para> 3122 <para>
3123 <note>
3124 Since <link doc="changes.xml" id="njs0.7.0">0.7.0</link>,
3125 extended crypto API is available as a global
3126 <link id="builtin_crypto">crypto</link> object.
3127 </note>
1922 The Crypto module provides cryptographic functionality support. 3128 The Crypto module provides cryptographic functionality support.
1923 The Crypto module object is returned by <literal>require('crypto')</literal>. 3129 The Crypto module object is returned by <literal>require('crypto')</literal>.
1924 </para> 3130 </para>
1925 3131
1926 <para> 3132 <para>