diff --git a/docs/sources/.eslintrc.js b/docs/sources/.eslintrc.js index 2a8c880e17..0bd123360e 100644 --- a/docs/sources/.eslintrc.js +++ b/docs/sources/.eslintrc.js @@ -46,5 +46,6 @@ module.exports = { clearInterval: 'readonly', setTimeout: 'readonly', clearTimeout: 'readonly', + crypto: 'readonly', }, }; diff --git a/docs/sources/k6/next/javascript-api/_index.md b/docs/sources/k6/next/javascript-api/_index.md index 0355249bc7..bfbf03ebb3 100644 --- a/docs/sources/k6/next/javascript-api/_index.md +++ b/docs/sources/k6/next/javascript-api/_index.md @@ -77,6 +77,10 @@ The [`k6/browser` module](https://grafana.com/docs/k6//javascript-ap {{< docs/shared source="k6" lookup="javascript-api/k6-ws.md" version="" >}} +## crypto + +{{< docs/shared source="k6" lookup="javascript-api/crypto.md" version="" >}} + ## Error codes The following specific error codes are currently defined: diff --git a/docs/sources/k6/next/javascript-api/crypto/_index.md b/docs/sources/k6/next/javascript-api/crypto/_index.md new file mode 100644 index 0000000000..9adc974a52 --- /dev/null +++ b/docs/sources/k6/next/javascript-api/crypto/_index.md @@ -0,0 +1,90 @@ +--- +title: 'crypto' +description: 'k6 WebCrypto API implementation' +weight: 14 +--- + +# crypto + +With this module, you can use the [WebCrypto API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API) in your k6 scripts. However, note that this API is not yet fully implemented and some algorithms and features might still be missing. + +The Web Crypto API is a JavaScript API for performing cryptographic operations such as encryption, decryption, digital signature generation and verification, and key generation and management. It provides a standard interface to access cryptographic functionality, which can help ensure that cryptographic operations are performed correctly and securely. + +## API + +The module is a top-level `crypto` object with the following properties and methods: + +| Interface/Function | Description | +| :------------------------------------------------------------------------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [getRandomValues](https://grafana.com/docs/k6//javascript-api/crypto/getrandomvalues) | Fills the passed `TypedArray` with cryptographically sound random values. | +| [randomUUID](https://grafana.com/docs/k6//javascript-api/crypto/randomuuid) | Returns a randomly generated, 36 character long v4 UUID. | +| [subtle](https://grafana.com/docs/k6//javascript-api/crypto/subtlecrypto) | The [SubtleCrypto](https://grafana.com/docs/k6//javascript-api/crypto/subtlecrypto) interface provides access to common cryptographic primitives, such as hashing, signing, encryption, or decryption. | + +## Example + +{{< code >}} + +```javascript +export default async function () { + const plaintext = stringToArrayBuffer('Hello, World!'); + + /** + * Generate a symmetric key using the AES-CBC algorithm. + */ + const key = await crypto.subtle.generateKey( + { + name: 'AES-CBC', + length: 256, + }, + true, + ['encrypt', 'decrypt'] + ); + + /** + * Encrypt the plaintext using the AES-CBC key with + * have generated. + */ + const iv = crypto.getRandomValues(new Uint8Array(16)); + const ciphertext = await crypto.subtle.encrypt( + { + name: 'AES-CBC', + iv: iv, + }, + key, + plaintext + ); + + /** + * Decrypt the ciphertext using the same key to verify + * that the resulting plaintext is the same as the original. + */ + const deciphered = await crypto.subtle.decrypt( + { + name: 'AES-CBC', + iv: iv, + }, + key, + ciphertext + ); + + console.log( + 'deciphered text == original plaintext: ', + arrayBufferToHex(deciphered) === arrayBufferToHex(plaintext) + ); +} + +function arrayBufferToHex(buffer) { + return [...new Uint8Array(buffer)].map((x) => x.toString(16).padStart(2, '0')).join(''); +} + +function stringToArrayBuffer(str) { + const buf = new ArrayBuffer(str.length * 2); // 2 bytes for each char + const bufView = new Uint16Array(buf); + for (let i = 0, strLen = str.length; i < strLen; i++) { + bufView[i] = str.charCodeAt(i); + } + return buf; +} +``` + +{{< /code >}} diff --git a/docs/sources/k6/next/javascript-api/crypto/aescbcparams.md b/docs/sources/k6/next/javascript-api/crypto/aescbcparams.md new file mode 100644 index 0000000000..9d092019c2 --- /dev/null +++ b/docs/sources/k6/next/javascript-api/crypto/aescbcparams.md @@ -0,0 +1,64 @@ +--- +title: 'AesCbcParams' +description: 'AesCbcParams represents the object that should be passed as the algorithm parameter into the encrypt and decrypt operation when using the AES-CBC algorithm.' +weight: 04 +--- + +# AesCbcParams + +The `AesCbcParams` object represents the object that should be passed as the algorithm parameter into the [encrypt](https://grafana.com/docs/k6//javascript-api/crypto/subtlecrypto/encrypt) and [decrypt](https://grafana.com/docs/k6//javascript-api/crypto/subtlecrypto/decrypt) operation when using the AES-CBC algorithm. + +For more details, head to the [MDN Web Crypto API documentation on AES-CBC](https://developer.mozilla.org/en-US/docs/Web/API/AesCbcParams). + +## Properties + +| Property | Type | Description | +| :------- | :----------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| name | `string` | Should be set to `AES-CBC`. | +| iv | `ArrayBuffer`, `TypedArray`, or `DataView` | The initialization vector. Must be 16 bytes, unpredictable and cryptographically random. Yet, it doesn't need to be secret and can be transmitted along with the ciphertext. | + +## Example + +{{< code >}} + +```javascript +export default async function () { + const plaintext = stringToArrayBuffer('Hello, World!'); + + /** + * Generate a symmetric key using the AES-CBC algorithm. + */ + const key = await crypto.subtle.generateKey( + { + name: 'AES-CBC', + length: 256, + }, + true, + ['encrypt', 'decrypt'] + ); + + /** + * Encrypt the plaintext using the AES-CBC key with + * have generated. + */ + const ciphertext = await crypto.subtle.encrypt( + { + name: 'AES-CBC', + iv: crypto.getRandomValues(new Uint8Array(16)), + }, + key, + plaintext + ); +} + +function stringToArrayBuffer(str) { + const buf = new ArrayBuffer(str.length * 2); // 2 bytes for each char + const bufView = new Uint16Array(buf); + for (let i = 0, strLen = str.length; i < strLen; i++) { + bufView[i] = str.charCodeAt(i); + } + return buf; +} +``` + +{{< /code >}} diff --git a/docs/sources/k6/next/javascript-api/crypto/aesctrparams.md b/docs/sources/k6/next/javascript-api/crypto/aesctrparams.md new file mode 100644 index 0000000000..6a7fbb4431 --- /dev/null +++ b/docs/sources/k6/next/javascript-api/crypto/aesctrparams.md @@ -0,0 +1,66 @@ +--- +title: 'AesCtrParams' +description: 'AesCtrParams represents the object that should be passed as the algorithm parameter into the encrypt and decrypt operation when using the AES-CTR algorithm.' +weight: 05 +--- + +# AesCtrParams + +The `AesCtrParams` object represents the object that should be passed as the algorithm parameter into the [encrypt](https://grafana.com/docs/k6//javascript-api/crypto/subtlecrypto/encrypt) and [decrypt](https://grafana.com/docs/k6//javascript-api/crypto/subtlecrypto/decrypt) operation when using the AES-CTR algorithm. + +For more details, head to the MDN Web Crypto API documentation on [AES-CTR](https://developer.mozilla.org/en-US/docs/Web/API/AesCtrParams). + +## Properties + +| Property | Type | Description | +| :------- | :----------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------- | +| name | `string` | Should be set to `AES-CTR`. | +| counter | `ArrayBuffer`, `TypedArray`, or `DataView` | The initial value of the counter block. This must be 16-bytes long, like the AES block size. | +| length | `number` | The number of bits in the counter block that are used for the actual counter. It is recommended to use 64 (half of the counter block). | + +## Example + +{{< code >}} + +```javascript +export default async function () { + const plaintext = stringToArrayBuffer('Hello, World!'); + + /** + * Generate a symmetric key using the AES-CTR algorithm. + */ + const key = await crypto.subtle.generateKey( + { + name: 'AES-CTR', + length: 256, + }, + true, + ['encrypt', 'decrypt'] + ); + + /** + * Encrypt the plaintext using the AES-CTR key with + * have generated. + */ + const ciphertext = await crypto.subtle.encrypt( + { + name: 'AES-CTR', + counter: crypto.getRandomValues(new Uint8Array(16)), + length: 128, + }, + key, + plaintext + ); +} + +function stringToArrayBuffer(str) { + const buf = new ArrayBuffer(str.length * 2); // 2 bytes for each char + const bufView = new Uint16Array(buf); + for (let i = 0, strLen = str.length; i < strLen; i++) { + bufView[i] = str.charCodeAt(i); + } + return buf; +} +``` + +{{< /code >}} diff --git a/docs/sources/k6/next/javascript-api/crypto/aesgcmparams.md b/docs/sources/k6/next/javascript-api/crypto/aesgcmparams.md new file mode 100644 index 0000000000..ad38393128 --- /dev/null +++ b/docs/sources/k6/next/javascript-api/crypto/aesgcmparams.md @@ -0,0 +1,66 @@ +--- +title: 'AesGcmParams' +description: 'AesGcmParams represents the object that should be passed as the algorithm parameter into the encrypt and decrypt operation when using the AES-GCM algorithm.' +weight: 06 +--- + +# AesGcmParams + +The `AesGcmParams` object represents the object that should be passed as the algorithm parameter into the [encrypt](https://grafana.com/docs/k6//javascript-api/crypto/subtlecrypto/encrypt) and [decrypt](https://grafana.com/docs/k6//javascript-api/crypto/subtlecrypto/decrypt) operation when using the AES-GCM algorithm. + +For more details, head to the [MDN Web Crypto API documentation on AES-GCM](https://developer.mozilla.org/en-US/docs/Web/API/AesGcmParams). + +## Properties + +| Property | Type | Description | +| :------------------------ | :----------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| name | `string` | Should be set to `AES-GCM`. | +| iv | `ArrayBuffer`, `TypedArray`, or `DataView` | The initialization vector. It must be 12 bytes long, unpredictable and cryptographically random. It must be unique for every encryption operation carried out with a given key. Never reuse an iv with the same key. Yet, it doesn't need to be secret and can be transmitted along with the ciphertext. | +| additionalData (optional) | `ArrayBuffer`, `TypedArray` or `DataView` | Additional data that should be authenticated, but not encrypted. It must be included in the calculation of the authentication tag, but not encrypted itself. | +| tagLength (optional) | `number` | The length of the authentication tag in bits. Should be set, and will default to 96. | + +## Example + +{{< code >}} + +```javascript +export default async function () { + const plaintext = stringToArrayBuffer('Hello, World!'); + + /** + * Generate a symmetric key using the AES-CBC algorithm. + */ + const key = await crypto.subtle.generateKey( + { + name: 'AES-GCM', + length: 256, + }, + true, + ['encrypt', 'decrypt'] + ); + + /** + * Encrypt the plaintext using the AES-CBC key with + * have generated. + */ + const ciphertext = await crypto.subtle.encrypt( + { + name: 'AES-GCM', + iv: crypto.getRandomValues(new Uint8Array(12)), + }, + key, + plaintext + ); +} + +function stringToArrayBuffer(str) { + const buf = new ArrayBuffer(str.length * 2); // 2 bytes for each char + const bufView = new Uint16Array(buf); + for (let i = 0, strLen = str.length; i < strLen; i++) { + bufView[i] = str.charCodeAt(i); + } + return buf; +} +``` + +{{< /code >}} diff --git a/docs/sources/k6/next/javascript-api/crypto/aeskeygenparams.md b/docs/sources/k6/next/javascript-api/crypto/aeskeygenparams.md new file mode 100644 index 0000000000..66d3fedd9f --- /dev/null +++ b/docs/sources/k6/next/javascript-api/crypto/aeskeygenparams.md @@ -0,0 +1,35 @@ +--- +title: 'AesKeyGenParams' +description: 'AesKeyGenParams represents the object that should be passed as the algorithm parameter into the generateKey operation, when generating an AES key.' +weight: 07 +--- + +# AesKeyGenParams + +The `AesKeyGenParams` object represents the object that should be passed as the algorithm parameter into the [generateKey](https://grafana.com/docs/k6//javascript-api/crypto/subtlecrypto/generatekey) operation when generating an AES key. + +## Properties + +| Property | Type | Description | +| :------- | :------- | :---------------------------------------------------------------------------------- | +| name | `string` | The name of the algorithm. Possible values are `AES-CBC`, `AES-CTR`, and `AES-GCM`. | +| length | `number` | The length of the key in bits. Possible values are 128, 192 or 256. | + +## Example + +{{< code >}} + +```javascript +export default async function () { + const key = await crypto.subtle.generateKey( + { + name: 'AES-CBC', + length: 256, + }, + true, + ['encrypt', 'decrypt'] + ); +} +``` + +{{< /code >}} diff --git a/docs/sources/k6/next/javascript-api/crypto/cryptokey.md b/docs/sources/k6/next/javascript-api/crypto/cryptokey.md new file mode 100644 index 0000000000..7bc0ff8270 --- /dev/null +++ b/docs/sources/k6/next/javascript-api/crypto/cryptokey.md @@ -0,0 +1,18 @@ +--- +title: 'CryptoKey' +description: 'CryptoKey represents a cryptographic key used for encryption, decryption, signing, or verification.' +weight: 02 +--- + +# CryptoKey + +The `CryptoKey` object represents a cryptographic key used for [encryption](https://grafana.com/docs/k6//javascript-api/crypto/subtlecrypto/encrypt),[decryption](https://grafana.com/docs/k6//javascript-api/crypto/subtlecrypto/decrypt),[signing](https://grafana.com/docs/k6//javascript-api/crypto/subtlecrypto/sign), or [verification](https://grafana.com/docs/k6//javascript-api/crypto/subtlecrypto/verify) within the webcrypto module. The `CryptoKey` object is created using the SubtleCrypto.generateKey() or SubtleCrypto.importKey() methods. + +## Properties + +| Property | Type | Description | +| :---------- | :--------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| type | `string` | Indicates the type of the key material. Possible values are `public`, `private`, `secret`, `unspecified`, or `unknown`. | +| extractable | `boolean` | Indicates whether the raw key material can be exported. | +| algorithm | `object` | An object containing the algorithm used to generate or import the key. | +| usages | `string[]` | An array of strings indicating the cryptographic operations that the key can be used for. Possible values are `encrypt`, `decrypt`, `sign`, `verify`, `deriveKey`, `deriveBits`, `wrapKey`, and `unwrapKey`. | diff --git a/docs/sources/k6/next/javascript-api/crypto/cryptokeypair.md b/docs/sources/k6/next/javascript-api/crypto/cryptokeypair.md new file mode 100644 index 0000000000..7cb7d4074a --- /dev/null +++ b/docs/sources/k6/next/javascript-api/crypto/cryptokeypair.md @@ -0,0 +1,18 @@ +--- +title: 'CryptoKeyPair' +description: 'CryptoKeyPair represents an asymmetric key pair with public and private keys.' +weight: 08 +--- + +# CryptoKeyPair + +The `CryptoKeyPair` object represents an asymmetric key pair with public and private keys. + +The [`generateKey`](https://grafana.com/docs/k6//javascript-api/crypto/subtlecrypto/generatekey/) method can be used to create `CryptoKeyPair` object for asymmetric algorithms such as `ECDH` or `ECDSA`. + +## Properties + +| Property | Type | Description | +| :--------- | :-------------------------------------------------------------------------------------- | :------------- | +| publicKey | [`CryptoKey`](https://grafana.com/docs/k6//javascript-api/crypto/cryptokey) | A public key. | +| privateKey | [`CryptoKey`](https://grafana.com/docs/k6//javascript-api/crypto/cryptokey) | A private key. | diff --git a/docs/sources/k6/next/javascript-api/crypto/ecdhkeyderiveparams.md b/docs/sources/k6/next/javascript-api/crypto/ecdhkeyderiveparams.md new file mode 100644 index 0000000000..399b746b79 --- /dev/null +++ b/docs/sources/k6/next/javascript-api/crypto/ecdhkeyderiveparams.md @@ -0,0 +1,18 @@ +--- +title: 'EcdhKeyDeriveParams' +description: 'EcdhKeyDeriveParams is a parameter used for derive bits operation.' +weight: 10 +--- + +# EcdhKeyDeriveParams + +The `EcdhKeyDeriveParams` represents the object that should be passed as the algorithm parameter into [`deriveBits`](https://grafana.com/docs/k6//javascript-api/crypto/subtlecrypto/derivebits/), when using the ECDH algorithm. + +ECDH is a secure communication method. Parties exchange public keys and use them with their private keys to generate a unique shared secret key. + +## Properties + +| Property | Type | Description | +| :-------- | :-------------------------------------------------------------------------------------- | :----------------------------------- | +| name | `string` | An algorithm name. Should be `ECDH`. | +| publicKey | [`CryptoKey`](https://grafana.com/docs/k6//javascript-api/crypto/cryptokey) | Another party's public key. | diff --git a/docs/sources/k6/next/javascript-api/crypto/ecdsaparams.md b/docs/sources/k6/next/javascript-api/crypto/ecdsaparams.md new file mode 100644 index 0000000000..f3a503b13b --- /dev/null +++ b/docs/sources/k6/next/javascript-api/crypto/ecdsaparams.md @@ -0,0 +1,16 @@ +--- +title: 'EcdsaParams' +description: 'EcdsaParams is a parameter used for sign or verify operations.' +weight: 11 +--- + +# EcdsaParams + +The `EcdsaParams` represents the object that should be passed as the algorithm parameter into [`sign`](https://grafana.com/docs/k6//javascript-api/crypto/subtlecrypto/sign/) or [`verify`](https://grafana.com/docs/k6//javascript-api/crypto/subtlecrypto/verify/) when using the ECDSA algorithm. + +## Properties + +| Property | Type | Description | +| :------- | :------- | :---------------------------------------------------------------------------------------------------- | +| name | `string` | An algorithm name. Should be `ECDSA`. | +| hash | `string` | An identifier for the digest algorithm to use. Possible values are `SHA-256`, `SHA-384` or `SHA-512`. | diff --git a/docs/sources/k6/next/javascript-api/crypto/eckeygenparams.md b/docs/sources/k6/next/javascript-api/crypto/eckeygenparams.md new file mode 100644 index 0000000000..fd752a9f5e --- /dev/null +++ b/docs/sources/k6/next/javascript-api/crypto/eckeygenparams.md @@ -0,0 +1,37 @@ +--- +title: 'EcKeyGenParams' +description: 'EcKeyGenParams represents the object that should be passed as the algorithm parameter into the generateKey operation, when generating ECDH or ECDSA key pairs.' +weight: 09 +--- + +# EcKeyGenParams + +The `EcKeyGenParams` object represents the object that should be passed as the algorithm parameter into the [generateKey](https://grafana.com/docs/k6//javascript-api/crypto/subtlecrypto/generatekey) operation when generating key pairs for ECDH or ECDSA algorithms. + +## Properties + +| Property | Type | Description | +| :--------- | :------- | :------------------------------------------------------------------------------------------------------- | +| name | `string` | An algorithm name. Possible values are `ECDH` or `ECDSA`. | +| namedCurve | `string` | A elliptic curve's name to use for key pair generation. Possible values are `P-256`, `P-384` or `P-521`. | + +## Example + +{{< code >}} + +```javascript +export default async function () { + const keyPair = await crypto.subtle.generateKey( + { + name: 'ECDSA', + namedCurve: 'P-256', + }, + true, + ['sign', 'verify'] + ); + + console.log(JSON.stringify(keyPair)); +} +``` + +{{< /code >}} diff --git a/docs/sources/k6/next/javascript-api/crypto/getrandomvalues.md b/docs/sources/k6/next/javascript-api/crypto/getrandomvalues.md new file mode 100644 index 0000000000..8df52002dd --- /dev/null +++ b/docs/sources/k6/next/javascript-api/crypto/getrandomvalues.md @@ -0,0 +1,48 @@ +--- +title: 'getRandomValues' +description: 'getRandomValues fills the passed TypedArray with cryptographically sound random values.' +weight: 01 +--- + +# getRandomValues + +The `getRandomValues()` method fills the passed `TypedArray` with cryptographically sound random values. + +## Usage + +``` +getRandomValues(typedArray) +``` + +## Parameters + +| Name | Type | Description | +| :----------- | :----------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `typedArray` | `TypedArray` | An integer-based `TypedArray` to fill with random values. Accepted `TypedArray` specific types are: `Int8Array`, `Uint8Array`, `Uint8ClampedArray`, `Int16Array`, `Uint16Array`, `Int32Array`, or `Uint32Array`. | + +## Return Value + +The same array is passed as the `typedArray` parameter with its contents replaced with the newly generated random numbers. The `typedArray` parameter is modified in place, and no copy is made. + +## Throws + +| Type | Description | +| :------------------- | :------------------------------------------------------------------------ | +| `QuotaExceededError` | Thrown when `typedArray` is too large and its `byteLength` exceeds 65536. | + +## Example + +{{< code >}} + +```javascript +export default function () { + const array = new Uint32Array(10); + crypto.getRandomValues(array); + + for (const num of array) { + console.log(num); + } +} +``` + +{{< /code >}} diff --git a/docs/sources/k6/next/javascript-api/crypto/hmackeygenparams.md b/docs/sources/k6/next/javascript-api/crypto/hmackeygenparams.md new file mode 100644 index 0000000000..fbc7956bda --- /dev/null +++ b/docs/sources/k6/next/javascript-api/crypto/hmackeygenparams.md @@ -0,0 +1,37 @@ +--- +title: 'HmacKeyGenParams' +description: 'HmacKeyGenParams represents the object that should be passed as the algorithm parameter into the generateKey operation, when generating an HMAC key.' +weight: 12 +--- + +# HmacKeyGenParams + +The `HmacKeyGenParams` object represents the object that should be passed as the algorithm parameter into the [generateKey](https://grafana.com/docs/k6//javascript-api/crypto/subtlecrypto/generatekey) operation when generating an HMAC key. + +## Properties + +| Property | Type | Description | +| :---------------- | :------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| name | `string` | This should be set to `HMAC`. | +| hash | `string` | The name of the digest function to use. Possible values are `SHA-1`, `SHA-256`, `SHA-384` and `SHA-512`. | +| length (optional) | `number` | The length of the key in bits. If this is omitted, the length of the key is equal to the block size of the hash function you have chosen. We recommend to leave this parameter empty, unless you have a good reason to use something different. | + +## Example + +{{< code >}} + +```javascript +export default async function () { + const key = await crypto.subtle.generateKey( + { + name: 'HMAC', + hash: { name: 'SHA-512' }, + length: 256, + }, + true, + ['sign', 'verify'] + ); +} +``` + +{{< /code >}} diff --git a/docs/sources/k6/next/javascript-api/crypto/jsonwebkey.md b/docs/sources/k6/next/javascript-api/crypto/jsonwebkey.md new file mode 100644 index 0000000000..e4b8732500 --- /dev/null +++ b/docs/sources/k6/next/javascript-api/crypto/jsonwebkey.md @@ -0,0 +1,57 @@ +--- +title: 'JsonWebKey' +description: 'JsonWebKey represents object/dictionary generated by exporting a CryptoKey or used as an input parameter for key import.' +weight: 13 +--- + +# JsonWebKey + +The `JsonWebKey` object represents object/dictionary generated by exporting a [`CryptoKey`](https://grafana.com/docs/k6//javascript-api/crypto/cryptokey) or used as an input parameter for key import. + +The properties of the `JsonWebKey` could vary depending on the algorithm and key type. See specification [JsonWebKey](https://www.w3.org/TR/WebCryptoAPI/#JsonWebKey-dictionary) for details. + +## Properties + +| Property | Type | Description | +| :------- | :------------- | :---------------------- | +| kty | `string` | The key type. | +| k | `string` | The key value. | +| alg | `string` | The algorithm. | +| ext | `bool` | The key is extractable. | +| key_ops | `string` array | The key operations. | +| crv | `string` | The curve name. | +| x | `string` | The x coordinate. | +| y | `string` | The y coordinate. | +| d | `string` | The private key. | + +## Example + +{{< code >}} + +```javascript +export default async function () { + const jwk = { + alg: 'HS256', + ext: true, + k: 'H6gLp3lw7w27NrPUn00WpcKU-IJojJdNzhL_8F6se2k', + key_ops: ['sign', 'verify'], + kty: 'oct', + }; + + const importedKey = await crypto.subtle.importKey( + 'jwk', + jwk, + { name: 'HMAC', hash: { name: 'SHA-256' } }, + true, + ['sign', 'verify'] + ); + + const exportedAgain = await crypto.subtle.exportKey('jwk', importedKey); + + console.log('exported again: ' + JSON.stringify(exportedAgain)); + // should print + // INFO[0000] exported again: {"k":"H6gLp3lw7w27NrPUn00WpcKU-IJojJdNzhL_8F6se2k","kty":"oct","ext":true,"key_ops":["sign","verify"],"alg":"HS256"} source=console +} +``` + +{{< /code >}} diff --git a/docs/sources/k6/next/javascript-api/crypto/randomuuid.md b/docs/sources/k6/next/javascript-api/crypto/randomuuid.md new file mode 100644 index 0000000000..3b039cb41e --- /dev/null +++ b/docs/sources/k6/next/javascript-api/crypto/randomuuid.md @@ -0,0 +1,33 @@ +--- +title: 'randomUUID' +description: 'randomUUID produces a 36-characters long string containing a cryptographically random UUID v4.' +weight: 02 +--- + +# randomUUID + +The `randomUUID` method produces a 36-characters long string that contains a cryptographically random UUID v4. + +## Usage + +``` +randomUUID() +``` + +## Return Value + +A string containing a 36-character cryptographically random UUID v4. + +## Example + +{{< code >}} + +```javascript +export default function () { + const myUUID = crypto.randomUUID(); + + console.log(myUUID); +} +``` + +{{< /code >}} diff --git a/docs/sources/k6/next/javascript-api/crypto/rsahashedimportparams.md b/docs/sources/k6/next/javascript-api/crypto/rsahashedimportparams.md new file mode 100644 index 0000000000..c856edd8d1 --- /dev/null +++ b/docs/sources/k6/next/javascript-api/crypto/rsahashedimportparams.md @@ -0,0 +1,16 @@ +--- +title: 'RsaHashedImportParams' +description: 'RsaHashedImportParams represents the object that should be passed as the algorithm parameter into the importKey operation, when using the RSA algorithm.' +weight: 12 +--- + +# RsaHashedImportParams + +The `RsaHashedImportParams` represents the object that should be passed as the algorithm parameter into [`importKey`](https://grafana.com/docs/k6//javascript-api/crypto/subtlecrypto/importkey/) when using the RSA algorithm. + +## Properties + +| Property | Type | Description | +| :------- | :------- | :------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- | +| name | `string` | This should be set to `RSASSA-PKCS1-v1_5`, `RSA-PSS` or `RSA-OAEP`. | +| hash | `string` | `object` | The name or an object with a `name` property of the digest function to use. Possible values are `SHA-1`, `SHA-256`, `SHA-384` and `SHA-512`. | diff --git a/docs/sources/k6/next/javascript-api/crypto/rsahashedkeygenparams.md b/docs/sources/k6/next/javascript-api/crypto/rsahashedkeygenparams.md new file mode 100644 index 0000000000..0bce0f915a --- /dev/null +++ b/docs/sources/k6/next/javascript-api/crypto/rsahashedkeygenparams.md @@ -0,0 +1,39 @@ +--- +title: 'RSAHashedKeyGenParams' +description: 'RSAHashedKeyGenParams represents the object that should be passed as the algorithm parameter into the generateKey operation, when generating an RSA key pair.' +weight: 12 +--- + +# RSAHashedKeyGenParams + +The `RSAHashedKeyGenParams` object represents the object that should be passed as the algorithm parameter into the [generateKey](https://grafana.com/docs/k6//javascript-api/crypto/subtlecrypto/generatekey) operation when generating an RSA key pair. + +## Properties + +| Property | Type | Description | +| :------------- | :----------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | +| name | `string` | This should be set to `RSASSA-PKCS1-v1_5`, `RSA-PSS` or `RSA-OAEP`. | +| modulusLength | `number` | The length in bits of the RSA modulus. This should be at least 2048. Some organizations are now recommending that it should be 4096. | +| publicExponent | `Uint8Array` | The public exponent. Unless you have a good reason to use something else, specify `65537` here, which represented as a `Uint8Array` is `new Uint8Array([1, 0, 1])` | +| hash | `string` | `object` | The name or an object with a `name` property of the digest function to use. Possible values are `SHA-1`, `SHA-256`, `SHA-384` and `SHA-512`. | + +## Example + +{{< code >}} + +```javascript +export default async function () { + const keyPair = await crypto.subtle.generateKey( + { + name: 'RSA-PSS', + modulusLength: 2048, + publicExponent: new Uint8Array([1, 0, 1]), + hash: { name: 'SHA-256' }, + }, + true, + ['sign', 'verify'] + ); +} +``` + +{{< /code >}} diff --git a/docs/sources/k6/next/javascript-api/crypto/rsaoaepparams.md b/docs/sources/k6/next/javascript-api/crypto/rsaoaepparams.md new file mode 100644 index 0000000000..3426a1fbce --- /dev/null +++ b/docs/sources/k6/next/javascript-api/crypto/rsaoaepparams.md @@ -0,0 +1,19 @@ +--- +title: 'RsaOaepParams' +description: 'RsaOaepParams represents the object that should be passed as the algorithm parameter into the encrypt and decrypt operation when using the RSA-OAEP algorithm.' +weight: 06 +--- + +# RsaOaepParams + +The `RsaOaepParams` object represents the object that should be passed as the algorithm parameter into the [encrypt](https://grafana.com/docs/k6//javascript-api/crypto/subtlecrypto/encrypt) and [decrypt](https://grafana.com/docs/k6//javascript-api/crypto/subtlecrypto/decrypt) operation when using the RSA-OAEP algorithm. + +For more details, head to the [MDN Web Crypto API documentation on RSA-OAEP](https://developer.mozilla.org/en-US/docs/Web/API/RsaOaepParams). + +## Properties + +| Property | Type | Description | +| :--------------- | :----------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| name | `string` | Should be set to `RSA-OAEP`. | +| label (optional) | `ArrayBuffer`, `TypedArray`, or `DataView` | It's an array of bytes that does not itself need to be encrypted but which should be bound to the ciphertext. A digest of the label is part of the input to the encryption operation. Unless your application calls for a label, you can just omit this argument, and it will not affect the security of the encryption operation. | +| | diff --git a/docs/sources/k6/next/javascript-api/crypto/rsapssparams.md b/docs/sources/k6/next/javascript-api/crypto/rsapssparams.md new file mode 100644 index 0000000000..132fd59f4a --- /dev/null +++ b/docs/sources/k6/next/javascript-api/crypto/rsapssparams.md @@ -0,0 +1,22 @@ +--- +title: 'RsaPssParams' +description: 'RsaPssParams is a parameter used for sign or verify operations.' +weight: 11 +--- + +# RsaPssParams + +The `RsaPssParams` represents the object that should be passed as the algorithm parameter into [`sign`](https://grafana.com/docs/k6//javascript-api/crypto/subtlecrypto/sign/) or [`verify`](https://grafana.com/docs/k6//javascript-api/crypto/subtlecrypto/verify/) when using the RSA-PSS algorithm. + +## Properties + +| Property | Type | Description | +| :--------- | :------- | :-------------------------------------------------------------------------- | +| name | `string` | An algorithm name. Should be `RSA-PSS`. | +| saltLength | `number` | A long integer representing the length of the random salt to use, in bytes. | + +{{< admonition type="caution" >}} + +Since under the hood we use Golang's SDK the salt length 0 is not supported. In that case the maximum possible salt length will be used. + +{{< /admonition >}} diff --git a/docs/sources/k6/next/javascript-api/crypto/subtlecrypto/_index.md b/docs/sources/k6/next/javascript-api/crypto/subtlecrypto/_index.md new file mode 100644 index 0000000000..17442c750e --- /dev/null +++ b/docs/sources/k6/next/javascript-api/crypto/subtlecrypto/_index.md @@ -0,0 +1,92 @@ +--- +title: 'SubtleCrypto' +description: 'SubtleCrypto offers low-level cryptographic functions.' +weight: 03 +--- + +# SubtleCrypto + +The `SubtleCrypto` interface provides a set of low-level cryptographic primitives such as encryption, decryption, digital signature generation and verification, and key generation and management. It is useful for using secure and efficient cryptographic operations within k6 scripts. + +## Methods + +| Method | Description | +| :----------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------- | +| [encrypt](https://grafana.com/docs/k6//javascript-api/crypto/subtlecrypto/encrypt) | Encrypts the given plaintext data using the specified algorithm and key. | +| [decrypt](https://grafana.com/docs/k6//javascript-api/crypto/subtlecrypto/decrypt) | Decrypts the given ciphertext data using the specified algorithm and key. | +| [sign](https://grafana.com/docs/k6//javascript-api/crypto/subtlecrypto/sign) | Signs the given data using the specified algorithm and key. | +| [verify](https://grafana.com/docs/k6//javascript-api/crypto/subtlecrypto/verify) | Verifies the signature of the given data using the specified algorithm and key. | +| [digest](https://grafana.com/docs/k6//javascript-api/crypto/subtlecrypto/digest) | Computes the digest (hash) of the given data using the specified algorithm. | +| [generateKey](https://grafana.com/docs/k6//javascript-api/crypto/subtlecrypto/generatekey) | Generates a new cryptographic key for use with the specified algorithm. | +| [importKey](https://grafana.com/docs/k6//javascript-api/crypto/subtlecrypto/importkey) | Imports a raw key material into the Web Crypto API, generating a new key object to use with the specified algorithm. | +| [exportKey](https://grafana.com/docs/k6//javascript-api/crypto/subtlecrypto/exportkey) | Exports the raw key material of the given key object. | +| [deriveBits](https://grafana.com/docs/k6//javascript-api/crypto/subtlecrypto/derivebits) | Derives bits using provided input. | + +## Example + +{{< code >}} + +```javascript +export default async function () { + const plaintext = stringToArrayBuffer('Hello, World!'); + + /** + * Generate a symmetric key using the AES-CBC algorithm. + */ + const key = await crypto.subtle.generateKey( + { + name: 'AES-CBC', + length: 256, + }, + true, + ['encrypt', 'decrypt'] + ); + + /** + * Encrypt the plaintext using the AES-CBC key with + * have generated. + */ + const iv = crypto.getRandomValues(new Uint8Array(16)); + const ciphertext = await crypto.subtle.encrypt( + { + name: 'AES-CBC', + iv: iv, + }, + key, + plaintext + ); + + /** + * Decrypt the ciphertext using the same key to verify + * that the resulting plaintext is the same as the original. + */ + const deciphered = await crypto.subtle.decrypt( + { + name: 'AES-CBC', + iv: iv, + }, + key, + ciphertext + ); + + console.log( + 'deciphered text == original plaintext: ', + arrayBufferToHex(deciphered) === arrayBufferToHex(plaintext) + ); +} + +function arrayBufferToHex(buffer) { + return [...new Uint8Array(buffer)].map((x) => x.toString(16).padStart(2, '0')).join(''); +} + +function stringToArrayBuffer(str) { + const buf = new ArrayBuffer(str.length * 2); // 2 bytes for each char + const bufView = new Uint16Array(buf); + for (let i = 0, strLen = str.length; i < strLen; i++) { + bufView[i] = str.charCodeAt(i); + } + return buf; +} +``` + +{{< /code >}} diff --git a/docs/sources/k6/next/javascript-api/crypto/subtlecrypto/decrypt.md b/docs/sources/k6/next/javascript-api/crypto/subtlecrypto/decrypt.md new file mode 100644 index 0000000000..26badc6561 --- /dev/null +++ b/docs/sources/k6/next/javascript-api/crypto/subtlecrypto/decrypt.md @@ -0,0 +1,107 @@ +--- +title: 'decrypt' +description: 'decrypt decrypts some encrypted data' +weight: 01 +--- + +# decrypt + +The `decrypt()` method decrypts some encrypted data. + +## Usage + +``` +decrypt(algorithm, key, data) +``` + +## Parameters + +| Name | Type | Description | +| :---------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `algorithm` | [AesCbcParams](https://grafana.com/docs/k6//javascript-api/crypto/aescbcparams), [AesCtrParams](https://grafana.com/docs/k6//javascript-api/crypto/aesctrparams), or [AesGcmParams](https://grafana.com/docs/k6//javascript-api/crypto/aesgcmparams) object | Defines the algorithm to use and any extra-parameters. The values given for the extra parameters must match those used in the corresponding [encrypt] call. | +| `key` | [CryptoKey](https://grafana.com/docs/k6//javascript-api/crypto/cryptokey) | The [key](https://grafana.com/docs/k6//javascript-api/crypto/cryptokey) to use for decryption. | +| `data` | `ArrayBuffer`, `TypedArray`, or `DataView` | The encrypted data to be decrypted (also known as _ciphertext_). | + +### Supported algorithms + +{{< docs/shared source="k6" lookup="crypto/supported-encrypt-decrypt.md" version="" >}} + +## Return Value + +A `Promise` that resolves to a new `ArrayBuffer` containing the decrypted data. + +## Throws + +| Type | Description | +| :------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `InvalidAccessError` | Raised when the requested operation is not valid with the provided key. For instance when an invalid encryption algorithm is used, or a key not matching the selected algorithm is provided. | +| `OperationError` | Raised when the operation failed for an operation-specific reason. For instance, if the algorithm size is invalid, or errors occurred during the process of decrypting the ciphertext. | + +## Example + +{{< code >}} + +```javascript +export default async function () { + const plaintext = stringToArrayBuffer('Hello, World!'); + + /** + * Generate a symmetric key using the AES-CBC algorithm. + */ + const key = await crypto.subtle.generateKey( + { + name: 'AES-CBC', + length: 256, + }, + true, + ['encrypt', 'decrypt'] + ); + + /** + * Encrypt the plaintext using the AES-CBC key with + * have generated. + */ + const iv = crypto.getRandomValues(new Uint8Array(16)); + const ciphertext = await crypto.subtle.encrypt( + { + name: 'AES-CBC', + iv: iv, + }, + key, + plaintext + ); + + /** + * Decrypt the ciphertext using the same key to verify + * that the resulting plaintext is the same as the original. + */ + const deciphered = await crypto.subtle.decrypt( + { + name: 'AES-CBC', + iv: iv, + }, + key, + ciphertext + ); + + console.log( + 'deciphered text == original plaintext: ', + arrayBufferToHex(deciphered) === arrayBufferToHex(plaintext) + ); +} + +function arrayBufferToHex(buffer) { + return [...new Uint8Array(buffer)].map((x) => x.toString(16).padStart(2, '0')).join(''); +} + +function stringToArrayBuffer(str) { + const buf = new ArrayBuffer(str.length * 2); // 2 bytes for each char + const bufView = new Uint16Array(buf); + for (let i = 0, strLen = str.length; i < strLen; i++) { + bufView[i] = str.charCodeAt(i); + } + return buf; +} +``` + +{{< /code >}} diff --git a/docs/sources/k6/next/javascript-api/crypto/subtlecrypto/derivebits.md b/docs/sources/k6/next/javascript-api/crypto/subtlecrypto/derivebits.md new file mode 100644 index 0000000000..266dd68cb9 --- /dev/null +++ b/docs/sources/k6/next/javascript-api/crypto/subtlecrypto/derivebits.md @@ -0,0 +1,88 @@ +--- +title: 'deriveBits' +description: 'deriveBits derives an array of bits' +weight: 02 +--- + +# deriveBits + +It takes as its arguments the base key, the derivation algorithm to use, and the length of the bits to derive. It returns a Promise which will be fulfilled with an `ArrayBuffer` containing the derived bits. This array of bits can be used as a key for encryption or decryption as a shared secret. + +## Usage + +``` +deriveBits(algorithm, baseKey, length) +``` + +## Parameters + +| Name | Type | Description | +| :---------- | :--------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------- | +| `algorithm` | [EcdhKeyDeriveParams](https://grafana.com/docs/k6//javascript-api/crypto/ecdhkeyderiveparams/) | An object defining a derivation algorithm to use. | +| `baseKey` | [CryptoKey](https://grafana.com/docs/k6//javascript-api/crypto/cryptokey) | Represent an input to derivation algorithm. Currently it could be only a private ECDH key. | +| `length` | `number` | Optional. A length of the bits to derive. Currently, only multiplies of 8 are supported. | + +### Supported algorithms + +| ECDH | HKDF | PBKDF2 | +| :------------------------------------------------------------------------------------------------------------ | :--- | :----- | +| ✅ [EcdhKeyDeriveParams](https://grafana.com/docs/k6//javascript-api/crypto/ecdhkeyderiveparams/) | ❌ | ❌ | + +## Return Value + +A `Promise` that resolves to a new `ArrayBuffer` containing the derived bits. + +## Example + +{{< code >}} + +```javascript +export default async function () { + // Generate a key pair for Alice + const aliceKeyPair = await crypto.subtle.generateKey( + { + name: 'ECDH', + namedCurve: 'P-256', + }, + true, + ['deriveKey', 'deriveBits'] + ); + + // Generate a key pair for Bob + const bobKeyPair = await crypto.subtle.generateKey( + { + name: 'ECDH', + namedCurve: 'P-256', + }, + true, + ['deriveKey', 'deriveBits'] + ); + + // Derive shared secret for Alice + const aliceSharedSecret = await deriveSharedSecret(aliceKeyPair.privateKey, bobKeyPair.publicKey); + + // Derive shared secret for Bob + const bobSharedSecret = await deriveSharedSecret(bobKeyPair.privateKey, aliceKeyPair.publicKey); + + console.log('alice shared secret: ' + printArrayBuffer(aliceSharedSecret)); + console.log('bob shared secret: ' + printArrayBuffer(bobSharedSecret)); +} + +async function deriveSharedSecret(privateKey, publicKey) { + return crypto.subtle.deriveBits( + { + name: 'ECDH', + public: publicKey, + }, + privateKey, + 256 + ); +} + +const printArrayBuffer = (buffer) => { + const view = new Uint8Array(buffer); + return Array.from(view); +}; +``` + +{{< /code >}} diff --git a/docs/sources/k6/next/javascript-api/crypto/subtlecrypto/digest.md b/docs/sources/k6/next/javascript-api/crypto/subtlecrypto/digest.md new file mode 100644 index 0000000000..a4db23d0d1 --- /dev/null +++ b/docs/sources/k6/next/javascript-api/crypto/subtlecrypto/digest.md @@ -0,0 +1,54 @@ +--- +title: 'digest' +description: 'digest decrypts some encrypted data' +weight: 02 +--- + +# digest + +The `digest()` method generates a cryptographically secure [digest](https://developer.mozilla.org/en-US/docs/Glossary/Digest) of the given data. A digest is a short fixed-length value derived from some input data. The `digest()` method is commonly used to compute a checksum of data or to verify the integrity of data. + +## Usage + +``` +digest(algorithm, data) +``` + +## Parameters + +| Name | Type | Description | +| :---------- | :-------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `algorithm` | a `string` or object with a single `name` string property | Names the hash function to use. Supported values are `"SHA-1"`, `"SHA-256"`, `"SHA-384"` and `"SHA-512"`. Note that the SHA-1 hash function is not considered safe for cryptographic use. | +| `data` | `ArrayBuffer`, `TypedArray`, or `DataView` | The data to be digested. | + +### Supported algorithms + +| SHA-1 | SHA-256 | SHA-384 | SHA-512 | +| :---- | :------ | :------ | :------ | +| ✅ | ✅ | ✅ | ✅ | + +## Return Value + +A `Promise` that resolves to a new `ArrayBuffer` containing the digest. + +## Example + +{{< code >}} + +```javascript +export default async function () { + const digest = await crypto.subtle.digest('SHA-256', stringToArrayBuffer('Hello, world!')); + + console.log(arrayBufferToHex(digest)); +} + +function arrayBufferToHex(buffer) { + return [...new Uint8Array(buffer)].map((x) => x.toString(16).padStart(2, '0')).join(''); +} + +function stringToArrayBuffer(s) { + return Uint8Array.from(new String(s), (x) => x.charCodeAt(0)); +} +``` + +{{< /code >}} diff --git a/docs/sources/k6/next/javascript-api/crypto/subtlecrypto/encrypt.md b/docs/sources/k6/next/javascript-api/crypto/subtlecrypto/encrypt.md new file mode 100644 index 0000000000..5473b8bb6b --- /dev/null +++ b/docs/sources/k6/next/javascript-api/crypto/subtlecrypto/encrypt.md @@ -0,0 +1,107 @@ +--- +title: 'encrypt' +description: 'encrypt decrypts some encrypted data' +weight: 03 +--- + +# encrypt + +The `encrypt()` method encrypts some data. + +## Usage + +``` +encrypt(algorithm, key, data) +``` + +## Parameters + +| Name | Type | Description | +| :---------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------- | +| `algorithm` | [AesCbcParams](https://grafana.com/docs/k6//javascript-api/crypto/aescbcparams), [AesCtrParams](https://grafana.com/docs/k6//javascript-api/crypto/aesctrparams), or [AesGcmParams](https://grafana.com/docs/k6//javascript-api/crypto/aesgcmparams) object | Defines the algorithm to use and any extra-parameters. | +| `key` | [CryptoKey](https://grafana.com/docs/k6//javascript-api/crypto/cryptokey) | The [key](https://grafana.com/docs/k6//javascript-api/crypto/cryptokey) to use for encryption. | +| `data` | `ArrayBuffer`, `TypedArray`, or `DataView` | The data to be encrypted (also known as "plaintext"). | + +### Supported algorithms + +{{< docs/shared source="k6" lookup="crypto/supported-encrypt-decrypt.md" version="" >}} + +## Return Value + +A `Promise` that resolves to a new `ArrayBuffer` containing the encrypted data. + +## Throws + +| Type | Description | +| :------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `InvalidAccessError` | Raised when the requested operation is not valid with the provided key. For instance when an invalid encryption algorithm is used, or a key not matching the selected algorithm is provided. | +| `OperationError` | Raised when the operation failed for an operation-specific reason. For instance, if the algorithm size is invalid, or errors occurred during the process of decrypting the ciphertext. | + +## Example + +{{< code >}} + +```javascript +export default async function () { + const plaintext = stringToArrayBuffer('Hello, World!'); + + /** + * Generate a symmetric key using the AES-CBC algorithm. + */ + const key = await crypto.subtle.generateKey( + { + name: 'AES-CBC', + length: 256, + }, + true, + ['encrypt', 'decrypt'] + ); + + /** + * Encrypt the plaintext using the AES-CBC key with + * have generated. + */ + const iv = crypto.getRandomValues(new Uint8Array(16)); + const ciphertext = await crypto.subtle.encrypt( + { + name: 'AES-CBC', + iv: iv, + }, + key, + plaintext + ); + + /** + * Decrypt the ciphertext using the same key to verify + * that the resulting plaintext is the same as the original. + */ + const deciphered = await crypto.subtle.decrypt( + { + name: 'AES-CBC', + iv: iv, + }, + key, + ciphertext + ); + + console.log( + 'deciphered text == original plaintext: ', + arrayBufferToHex(deciphered) === arrayBufferToHex(plaintext) + ); +} + +function arrayBufferToHex(buffer) { + return [...new Uint8Array(buffer)].map((x) => x.toString(16).padStart(2, '0')).join(''); +} + +function stringToArrayBuffer(str) { + const buf = new ArrayBuffer(str.length * 2); // 2 bytes for each char + const bufView = new Uint16Array(buf); + for (let i = 0, strLen = str.length; i < strLen; i++) { + bufView[i] = str.charCodeAt(i); + } + return buf; +} +``` + +{{< /code >}} diff --git a/docs/sources/k6/next/javascript-api/crypto/subtlecrypto/exportkey.md b/docs/sources/k6/next/javascript-api/crypto/subtlecrypto/exportkey.md new file mode 100644 index 0000000000..1ea6dc38d0 --- /dev/null +++ b/docs/sources/k6/next/javascript-api/crypto/subtlecrypto/exportkey.md @@ -0,0 +1,81 @@ +--- +title: 'exportKey' +description: 'exportKey exports a key in an external, portable format.' +weight: 04 +--- + +# exportKey + +The `exportKey()` method takes a [CryptoKey](https://grafana.com/docs/k6//javascript-api/crypto/cryptokey) object as input and exports it in an external, portable format. + +Note that for a key to be exportable, it must have been created with the `extractable` flag set to `true`. + +## Usage + +``` +exportKey(format, key) +``` + +## Parameters + +| Name | Type | Description | +| :------- | :------------------------------------------------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `format` | `string` | Defines the data format in which the key should be exported. Depending on the algorithm and key type, the data format could vary. Currently supported formats are `raw`, `jwk`, `spki`, and `pkcs8`. | +| `key` | [CryptoKey](https://grafana.com/docs/k6//javascript-api/crypto/cryptokey) | The [key](https://grafana.com/docs/k6//javascript-api/crypto/cryptokey) to export. | + +### Supported algorithms + +{{< docs/shared source="k6" lookup="crypto/supported-key-methods.md" version="" >}} + +### Supported formats + +{{< docs/shared source="k6" lookup="crypto/supported-key-methods-formats.md" version="" >}} + +## Return Value + +A `Promise` that resolves to a new `ArrayBuffer` or an [JsonWebKey](https://grafana.com/docs/k6//javascript-api/crypto/jsonwebkey) object/dictionary containing the key. + +## Throws + +| Type | Description | +| :------------------- | :-------------------------------------------------- | +| `InvalidAccessError` | Raised when trying to export a non-extractable key. | +| `NotSupportedError` | Raised when trying to export in an unknown format. | +| `TypeError` | Raised when trying to use an invalid format. | + +## Example + +{{< code >}} + +```javascript +export default async function () { + /** + * Generate a symmetric key using the AES-CBC algorithm. + */ + const generatedKey = await crypto.subtle.generateKey( + { + name: 'AES-CBC', + length: '256', + }, + true, + ['encrypt', 'decrypt'] + ); + + /** + * Export the key in raw format. + */ + const exportedKey = await crypto.subtle.exportKey('raw', generatedKey); + + /** + * Reimport the key in raw format to verify its integrity. + */ + const importedKey = await crypto.subtle.importKey('raw', exportedKey, 'AES-CBC', true, [ + 'encrypt', + 'decrypt', + ]); + + console.log(JSON.stringify(importedKey)); +} +``` + +{{< /code >}} diff --git a/docs/sources/k6/next/javascript-api/crypto/subtlecrypto/generatekey.md b/docs/sources/k6/next/javascript-api/crypto/subtlecrypto/generatekey.md new file mode 100644 index 0000000000..3800933829 --- /dev/null +++ b/docs/sources/k6/next/javascript-api/crypto/subtlecrypto/generatekey.md @@ -0,0 +1,65 @@ +--- +title: 'generateKey' +description: 'generateKey generates a new key.' +weight: 05 +--- + +# generateKey + +The `generateKey()` generates a new cryptographic key and returns it as a [CryptoKey](https://grafana.com/docs/k6//javascript-api/crypto/cryptokey) object or a [CryptoKeyPair](https://grafana.com/docs/k6//javascript-api/crypto/cryptokeypair) object that can be used with the Web Crypto API. + +## Usage + +``` +generateKey(algorithm, extractable, keyUsages) +``` + +## Parameters + +| Name | Type | Description | +| :------------ | :--------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `algorithm` | a `string` or algorithm object with a single `name` string | The type of key to generate. It can be either a string with any of the currently supported algorithms as a value or any of the generation key parameter objects. | +| `extractable` | `boolean` | Whether the key can be exported using [exportKey](https://grafana.com/docs/k6//javascript-api/crypto/subtlecrypto/exportkey). | +| `keyUsages` | `Array` | An array of strings describing what operations can be performed with the key. Key usages could vary depending on the algorithm. | + +### Supported algorithms + +{{< docs/shared source="k6" lookup="crypto/supported-key-methods.md" version="" >}} + +## Return Value + +A `Promise` that resolves with the generated key as a [CryptoKey](https://grafana.com/docs/k6//javascript-api/crypto/cryptokey) object or a [CryptoKeyPair](https://grafana.com/docs/k6//javascript-api/crypto/cryptokeypair) object. + +### Algorithm specific input + +| | HMAC | AES | ECDH | ECDSA | RSA-OAEP | RSASSA-PKCS1-v1_5 | RSA-PSS | +| :--------------------- | :---------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | +| Parameters type to use | [`HmacKeyGenParams`](https://grafana.com/docs/k6//javascript-api/crypto/hmackeygenparams) | [`AesKeyGenParams`](https://grafana.com/docs/k6//javascript-api/crypto/aeskeygenparams) | [`EcKeyGenParams`](https://grafana.com/docs/k6//javascript-api/crypto/eckeygenparams) | [`EcKeyGenParams`](https://grafana.com/docs/k6//javascript-api/crypto/eckeygenparams) | [`RSAHashedKeyGenParams`](https://grafana.com/docs/k6//javascript-api/crypto/rsahashedkeygenparams) | [`RSAHashedKeyGenParams`](https://grafana.com/docs/k6//javascript-api/crypto/rsahashedkeygenparams) | [`RSAHashedKeyGenParams`](https://grafana.com/docs/k6//javascript-api/crypto/rsahashedkeygenparams) | +| Possible key usages | `sign`, `verify` | `encrypt`, `decrypt` | `deriveKey`, `deriveBits` | `sign`, `verify` | `encrypt`, `decrypt` | `sign`, `verify` | `sign`, `verify` | + +## Throws + +| Type | Description | +| :------------ | :-------------------------------------------------------------------------------------------- | +| `SyntaxError` | Raised when the `keyUsages` parameter is empty, but the key is of type `secret` or `private`. | + +## Example + +{{< code >}} + +```javascript +export default async function () { + const key = await crypto.subtle.generateKey( + { + name: 'AES-CBC', + length: 256, + }, + true, + ['encrypt', 'decrypt'] + ); + + console.log(JSON.stringify(key)); +} +``` + +{{< /code >}} diff --git a/docs/sources/k6/next/javascript-api/crypto/subtlecrypto/importkey.md b/docs/sources/k6/next/javascript-api/crypto/subtlecrypto/importkey.md new file mode 100644 index 0000000000..4f73d192fe --- /dev/null +++ b/docs/sources/k6/next/javascript-api/crypto/subtlecrypto/importkey.md @@ -0,0 +1,226 @@ +--- +title: 'importKey' +description: 'importKey imports a key from an external, portable format and gives you a CryptoKey object.' +weight: 06 +--- + +# importKey + +The `importKey()` imports a key from an external, portable format, and gives you a [CryptoKey](https://grafana.com/docs/k6//javascript-api/crypto/cryptokey) object that can be used with the Web Crypto API. + +## Usage + +``` +importKey(format, keyData, algorithm, extractable, keyUsages) +``` + +## Parameters + +| Name | Type | Description | +| :------------ | :--------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `format` | `string` | Defines the data format of the key to import. Depending on the algorithm and key type, the data format could vary. Currently supported formats are `raw`, `jwk`, `spki`, and `pkcs8`. | +| `keyData` | `ArrayBuffer`, `TypedArray`, `DataView` or [JsonWebKey](https://grafana.com/docs/k6//javascript-api/crypto/jsonwebkey) | the data to import the key from. | +| `algorithm` | a `string` or object with a single `name` string property | The algorithm to use to import the key. | +| `extractable` | `boolean` | Indicates whether it will be possible to export the key using [exportKey](https://grafana.com/docs/k6//javascript-api/crypto/subtlecrypto/exportkey). | +| `keyUsages` | `Array` | An array of strings describing what operations can be performed with the key. Currently supported usages include `encrypt`, `decrypt`, `sign`, and `verify`. | + +### Supported algorithms + +{{< docs/shared source="k6" lookup="crypto/supported-key-methods.md" version="" >}} + +### Supported formats + +{{< docs/shared source="k6" lookup="crypto/supported-key-methods-formats.md" version="" >}} + +## Return Value + +A `Promise` that resolves with the imported key as a [CryptoKey](https://grafana.com/docs/k6//javascript-api/crypto/cryptokey) object. + +## Throws + +| Type | Description | +| :------------ | :---------------------------------------------------------------------------------------------- | +| `SyntaxError` | Raised when the `keyUsages` parameter is empty but the key is of type `secret` or `private`. | +| `TypeError` | Raised when trying to use an invalid format, or if the `keyData` is not suited for that format. | + +## Examples + +### Round-trip key export/import + +{{< code >}} + +```javascript +export default async function () { + /** + * Generate a symmetric key using the AES-CBC algorithm. + */ + const generatedKey = await crypto.subtle.generateKey( + { + name: 'AES-CBC', + length: '256', + }, + true, + ['encrypt', 'decrypt'] + ); + + /** + * Export the key in raw format. + */ + const exportedKey = await crypto.subtle.exportKey('raw', generatedKey); + + /** + * Reimport the key in raw format to verify its integrity. + */ + const importedKey = await crypto.subtle.importKey('raw', exportedKey, 'AES-CBC', true, [ + 'encrypt', + 'decrypt', + ]); + + console.log(JSON.stringify(importedKey)); +} +``` + +{{< /code >}} + +### Import a static raw key and decrypt transmitted data + +This example demonstrates how to import a static `raw` key and decrypt some transmitted data in `base64`. The transmitted data in this example represents an initialization vector and encoded data, and in a real-world scenario, it can be a response body or other data received from a request. + +{{< code >}} + +```javascript +import { b64decode } from 'k6/encoding'; + +export default async function () { + const transmittedData = base64Decode( + 'whzEN310mrlWIH/icf0dMquRZ2ENyfOzkvPuu92WR/9F8dbeFM8EGUVNIhaS' + ); + + // keyData is the key used to decrypt the data, which is usually stored in a secure location + // for this example, we are using a static key + const keyData = new Uint8Array([ + 109, 151, 76, 33, 232, 253, 176, 90, 94, 40, 146, 227, 139, 208, 245, 139, 69, 215, 55, 197, 43, + 122, 160, 178, 228, 104, 4, 115, 138, 159, 119, 49, + ]); + + try { + const result = await decrypt(keyData, transmittedData); + + // should output decrypted message + // INFO[0000] result: 'my secret message' source=console + console.log("result: '" + result + "'"); + } catch (e) { + console.log('Error: ' + JSON.stringify(e)); + } +} + +const decrypt = async (keyData, transmittedData) => { + const initializeVectorLength = 12; + + // the first 12 bytes are the initialization vector + const iv = new Uint8Array(transmittedData.subarray(0, initializeVectorLength)); + + // the rest of the transmitted data is the encrypted data + const encryptedData = new Uint8Array(transmittedData.subarray(initializeVectorLength)); + + const importedKey = await crypto.subtle.importKey( + 'raw', + keyData, + { name: 'AES-GCM', length: '256' }, + true, + ['decrypt'] + ); + + const plain = await crypto.subtle.decrypt( + { name: 'AES-GCM', iv: iv }, + importedKey, + encryptedData + ); + + return arrayBufferToString(plain); +}; + +const arrayBufferToString = (buffer) => { + return String.fromCharCode.apply(null, new Uint8Array(buffer)); +}; + +const base64Decode = (base64String) => { + return new Uint8Array(b64decode(base64String)); +}; +``` + +{{< /code >}} + +### Import a static JWK key and decrypt transmitted data + +This example is similar to the previous one. It demonstrates how to import a static `jwk` key and decrypt some transmitted data (which contains the initialization vector and encoded data) in `base64`. + +{{< code >}} + +```javascript +import { b64decode } from 'k6/encoding'; + +export default async function () { + // transmitted data is the base64 of the initialization vector + encrypted data + // that unusually transmitted over the network + const transmittedData = base64Decode( + 'drCfxl4O+5FcrHe8Bs0CvKlw3gZpv+S5if3zn7c4BJzHJ35QDFV4sJB0pbDT' + ); + + // keyData is the key used to decrypt the data, which is usually stored in a secure location + // for this example, we are using a static key + const jwkKeyData = { + kty: 'oct', + ext: true, + key_ops: ['decrypt', 'encrypt'], + alg: 'A256GCM', + k: '9Id_8iG6FkGOWmc1S203vGVnTExtpDGxdQN7v7OV9Uc', + }; + + try { + const result = await decrypt(jwkKeyData, transmittedData); + + // should output decrypted message + // INFO[0000] result: 'my secret message' source=console + console.log("result: '" + result + "'"); + } catch (e) { + console.log('Error: ' + JSON.stringify(e)); + } +} + +const decrypt = async (keyData, transmittedData) => { + const initializeVectorLength = 12; + + // the first 12 bytes are the initialization vector + const iv = new Uint8Array(transmittedData.subarray(0, initializeVectorLength)); + + // the rest of the transmitted data is the encrypted data + const encryptedData = new Uint8Array(transmittedData.subarray(initializeVectorLength)); + + const importedKey = await crypto.subtle.importKey( + 'jwk', + keyData, + { name: 'AES-GCM', length: 256 }, + true, + ['encrypt', 'decrypt'] + ); + + const plain = await crypto.subtle.decrypt( + { name: 'AES-GCM', iv: iv }, + importedKey, + encryptedData + ); + + return arrayBufferToString(plain); +}; + +const arrayBufferToString = (buffer) => { + return String.fromCharCode.apply(null, new Uint8Array(buffer)); +}; + +const base64Decode = (base64String) => { + return new Uint8Array(b64decode(base64String)); +}; +``` + +{{< /code >}} diff --git a/docs/sources/k6/next/javascript-api/crypto/subtlecrypto/sign.md b/docs/sources/k6/next/javascript-api/crypto/subtlecrypto/sign.md new file mode 100644 index 0000000000..4e7f9152b7 --- /dev/null +++ b/docs/sources/k6/next/javascript-api/crypto/subtlecrypto/sign.md @@ -0,0 +1,129 @@ +--- +title: 'sign' +description: 'sign generates a digital signature.' +weight: 07 +--- + +# sign + +The `sign()` operation generates a digital signature of the provided `data`, using the given [CryptoKey](https://grafana.com/docs/k6//javascript-api/crypto/cryptokey) object. + +## Usage + +``` +sign(algorithm, key, data) +``` + +## Parameters + +| Name | Type | Description | +| :---------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------ | +| `algorithm` | `string` or object with a single `name` string property (`{name: "RSASSA-PKCS1-v1_5"}`) or an [EcdsaParams](https://grafana.com/docs/k6//javascript-api/crypto/ecdsaparams/), [HmacKeyGenParams](https://grafana.com/docs/k6//javascript-api/crypto/hmackeygenparams/), or [RsaPssParams](https://grafana.com/docs/k6//javascript-api/crypto/rsapssparams/) object. | The signature algorithm to use. | +| `key` | [CryptoKey](https://grafana.com/docs/k6//javascript-api/crypto/cryptokey) | The key to use for signing. | +| `data` | `ArrayBuffer`, `TypedArray`, or `DataView` | The data to be signed. | + +### Supported algorithms + +{{< docs/shared source="k6" lookup="crypto/supported-sign-verify.md" version="" >}} + +## Return Value + +A `Promise` that resolves with the signature as an `ArrayBuffer`. + +## Throws + +| Type | Description | +| :------------------- | :--------------------------------------------------------------------------------------------------------------------- | +| `InvalidAccessError` | Raised when the signing key either does not support signing operation, or is incompatible with the selected algorithm. | + +## Examples + +### Signing data with HMAC key + +{{< code >}} + +```javascript +export default async function () { + const generatedKey = await crypto.subtle.generateKey( + { + name: 'HMAC', + hash: { name: 'SHA-1' }, + }, + true, + ['sign', 'verify'] + ); + + const data = string2ArrayBuffer('Hello World'); + + /** + * Signes the encoded data with the provided key using the HMAC algorithm + * the returned signature can be verified using the verify method. + */ + const signature = await crypto.subtle.sign('HMAC', generatedKey, data); + + /** + * Verifies the signature of the encoded data with the provided key using the HMAC algorithm. + */ + const verified = await crypto.subtle.verify('HMAC', generatedKey, signature, data); + + console.log('verified: ', verified); +} + +function string2ArrayBuffer(str) { + const buf = new ArrayBuffer(str.length * 2); // 2 bytes for each char + const bufView = new Uint16Array(buf); + for (let i = 0, strLen = str.length; i < strLen; i++) { + bufView[i] = str.charCodeAt(i); + } + return buf; +} +``` + +{{< /code >}} + +### Signing and verifying data with ECDSA + +{{< code >}} + +```javascript +export default async function () { + const keyPair = await crypto.subtle.generateKey( + { + name: 'ECDSA', + namedCurve: 'P-256', + }, + true, + ['sign', 'verify'] + ); + + const data = string2ArrayBuffer('Hello World'); + + const alg = { name: 'ECDSA', hash: { name: 'SHA-256' } }; + + // makes a signature of the encoded data with the provided key + const signature = await crypto.subtle.sign(alg, keyPair.privateKey, data); + + console.log('signature: ', printArrayBuffer(signature)); + + //Verifies the signature of the encoded data with the provided key + const verified = await crypto.subtle.verify(alg, keyPair.publicKey, signature, data); + + console.log('verified: ', verified); +} + +const string2ArrayBuffer = (str) => { + const buf = new ArrayBuffer(str.length * 2); // 2 bytes for each char + const bufView = new Uint16Array(buf); + for (let i = 0, strLen = str.length; i < strLen; i++) { + bufView[i] = str.charCodeAt(i); + } + return buf; +}; + +const printArrayBuffer = (buffer) => { + const view = new Uint8Array(buffer); + return Array.from(view); +}; +``` + +{{< /code >}} diff --git a/docs/sources/k6/next/javascript-api/crypto/subtlecrypto/verify.md b/docs/sources/k6/next/javascript-api/crypto/subtlecrypto/verify.md new file mode 100644 index 0000000000..f12a3b893e --- /dev/null +++ b/docs/sources/k6/next/javascript-api/crypto/subtlecrypto/verify.md @@ -0,0 +1,142 @@ +--- +title: 'verify' +description: 'verify verifies a digital signature.' +weight: 08 +--- + +# verify + +The `verify()` operation verifies a digital signature. It ensures that some data was signed by a known key and that the data has not been tampered with since it was signed. + +## Usage + +``` +verify(algorithm, key, signature, data) +``` + +## Parameters + +| Name | Type | Description | +| :---------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------- | +| `algorithm` | `string` or object with a single `name` string property (`{name: "RSASSA-PKCS1-v1_5"}`) or an [EcdsaParams](https://grafana.com/docs/k6//javascript-api/crypto/ecdsaparams/), [HmacKeyGenParams](https://grafana.com/docs/k6//javascript-api/crypto/hmackeygenparams/), or [RsaPssParams](https://grafana.com/docs/k6//javascript-api/crypto/rsapssparams/) object. | The signature algorithm to use. | +| `key` | [CryptoKey](https://grafana.com/docs/k6//javascript-api/crypto/cryptokey) | The key that will be used to verify the signature. | +| `signature` | `ArrayBuffer` | The signature to verify. | +| `data` | `ArrayBuffer` | The data whose signature is to be verified. | + +### Supported algorithms + +{{< docs/shared source="k6" lookup="crypto/supported-sign-verify.md" version="" >}} + +## Return Value + +A `Promise` that resolves to a `boolean` value indicating if the signature is valid. + +## Throws + +| Type | Description | +| :------------------- | :------------------------------------------------------------------------------------------------------------------ | +| `InvalidAccessError` | Raised when the key either does not support the `verify` operation, or is incompatible with the selected algorithm. | + +## Examples + +### Verifying an HMAC signature + +{{< code >}} + +```javascript +export default async function () { + const generatedKey = await crypto.subtle.generateKey( + { + name: 'HMAC', + hash: { name: 'SHA-1' }, + }, + true, + ['sign', 'verify'] + ); + + const data = string2ArrayBuffer('Hello World'); + + /** + * Signes the encoded data with the provided key using the HMAC algorithm + * the returned signature can be verified using the verify method. + */ + const signature = await crypto.subtle.sign('HMAC', generatedKey, data); + + /** + * Verifies the signature of the encoded data with the provided key using the HMAC algorithm. + */ + const verified = await crypto.subtle.verify('HMAC', generatedKey, signature, data); + + console.log('verified: ', verified); +} + +function string2ArrayBuffer(str) { + const buf = new ArrayBuffer(str.length * 2); // 2 bytes for each char + const bufView = new Uint16Array(buf); + for (let i = 0, strLen = str.length; i < strLen; i++) { + bufView[i] = str.charCodeAt(i); + } + return buf; +} +``` + +{{< /code >}} + +### Verifying an ECDSA signature + +{{< code >}} + +```javascript +export default async function () { + const publicKey = await crypto.subtle.importKey( + 'spki', + spkiPublicKeyData, + { name: 'ECDSA', namedCurve: 'P-256' }, + true, + ['verify'] + ); + + // Verifies the signature of the encoded data with the provided key + const verified = await crypto.subtle.verify( + { + name: 'ECDSA', + hash: 'SHA-256', + }, + publicKey, + signature, + plaintText + ); + + console.log('verified: ', verified); +} + +const spkiPublicKeyData = new Uint8Array([ + 48, 89, 48, 19, 6, 7, 42, 134, 72, 206, 61, 2, 1, 6, 8, 42, 134, 72, 206, 61, 3, 1, 7, 3, 66, 0, + 4, 10, 5, 30, 56, 111, 103, 196, 166, 225, 229, 203, 238, 125, 55, 116, 91, 88, 142, 190, 114, 15, + 117, 89, 22, 40, 111, 150, 41, 105, 122, 57, 23, 17, 216, 106, 234, 201, 103, 8, 210, 58, 38, 35, + 216, 198, 237, 187, 84, 217, 164, 63, 100, 6, 105, 49, 128, 15, 53, 29, 158, 117, 235, 238, 30, +]); + +const plaintText = new Uint8Array([ + 95, 77, 186, 79, 50, 12, 12, 232, 118, 114, 90, 252, 229, 251, 210, 91, 248, 62, 90, 113, 37, 160, + 140, 175, 231, 60, 62, 186, 196, 33, 119, 157, 249, 213, 93, 24, 12, 58, 233, 148, 38, 69, 225, + 216, 47, 238, 140, 157, 41, 75, 60, 177, 160, 138, 153, 49, 32, 27, 60, 14, 129, 252, 71, 202, + 207, 131, 21, 162, 175, 102, 50, 65, 19, 195, 182, 98, 48, 195, 70, 8, 196, 244, 89, 54, 52, 206, + 2, 178, 103, 54, 34, 119, 240, 168, 64, 202, 116, 188, 61, 26, 98, 54, 149, 44, 94, 215, 170, 248, + 168, 254, 203, 221, 250, 117, 132, 230, 151, 140, 234, 93, 42, 91, 159, 183, 241, 180, 140, 139, + 11, 229, 138, 48, 82, 2, 117, 77, 131, 118, 16, 115, 116, 121, 60, 240, 38, 170, 238, 83, 0, 114, + 125, 131, 108, 215, 30, 113, 179, 69, 221, 178, 228, 68, 70, 255, 197, 185, 1, 99, 84, 19, 137, + 13, 145, 14, 163, 128, 152, 74, 144, 25, 16, 49, 50, 63, 22, 219, 204, 157, 107, 225, 104, 184, + 72, 133, 56, 76, 160, 62, 18, 96, 10, 193, 194, 72, 2, 138, 243, 114, 108, 201, 52, 99, 136, 46, + 168, 192, 42, 171, +]); + +const signature = new Uint8Array([ + 83, 223, 63, 226, 42, 29, 106, 105, 225, 145, 197, 180, 118, 154, 109, 110, 66, 67, 47, 251, 53, + 190, 203, 65, 207, 36, 19, 57, 49, 122, 124, 118, 59, 74, 222, 134, 42, 235, 180, 229, 134, 24, + 205, 81, 171, 156, 100, 218, 127, 242, 126, 53, 27, 77, 249, 101, 157, 132, 244, 30, 67, 30, 64, + 12, +]); +``` + +{{< /code >}} diff --git a/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/_index.md b/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/_index.md index 8f06b918c9..bdf44aae32 100644 --- a/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/_index.md +++ b/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/_index.md @@ -1,13 +1,12 @@ --- title: 'webcrypto' -description: "k6 webcrypto experimental API" -weight: 06 +description: 'k6 webcrypto experimental API' weight: 06 --- # webcrypto -{{< docs/shared source="k6" lookup="experimental-module.md" version="" >}} +{{< docs/shared source="k6" lookup="webcrypto/deprecated.md" version="" >}} With this experimental module, you can use the [WebCrypto API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API) in your k6 scripts. However, note that this API is not yet fully implemented and some algorithms and features might still be missing. diff --git a/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/aescbcparams.md b/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/aescbcparams.md index eeace4d95f..5813f7a52b 100644 --- a/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/aescbcparams.md +++ b/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/aescbcparams.md @@ -6,6 +6,8 @@ weight: 04 # AesCbcParams +{{< docs/shared source="k6" lookup="webcrypto/deprecated.md" version="" >}} + The `AesCbcParams` object represents the object that should be passed as the algorithm parameter into the [encrypt](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/subtlecrypto/encrypt) and [decrypt](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/subtlecrypto/decrypt) operation when using the AES-CBC algorithm. For more details, head to the [MDN Web Crypto API documentation on AES-CBC](https://developer.mozilla.org/en-US/docs/Web/API/AesCbcParams). diff --git a/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/aesctrparams.md b/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/aesctrparams.md index c0fc531503..7fa4df35ef 100644 --- a/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/aesctrparams.md +++ b/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/aesctrparams.md @@ -6,6 +6,8 @@ weight: 05 # AesCtrParams +{{< docs/shared source="k6" lookup="webcrypto/deprecated.md" version="" >}} + The `AesCtrParams` object represents the object that should be passed as the algorithm parameter into the [encrypt](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/subtlecrypto/encrypt) and [decrypt](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/subtlecrypto/decrypt) operation when using the AES-CTR algorithm. For more details, head to the MDN Web Crypto API documentation on [AES-CTR](https://developer.mozilla.org/en-US/docs/Web/API/AesCtrParams). diff --git a/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/aesgcmparams.md b/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/aesgcmparams.md index 868b189d94..4f5b20923e 100644 --- a/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/aesgcmparams.md +++ b/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/aesgcmparams.md @@ -6,6 +6,8 @@ weight: 06 # AesGcmParams +{{< docs/shared source="k6" lookup="webcrypto/deprecated.md" version="" >}} + The `AesGcmParams` object represents the object that should be passed as the algorithm parameter into the [encrypt](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/subtlecrypto/encrypt) and [decrypt](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/subtlecrypto/decrypt) operation when using the AES-GCM algorithm. For more details, head to the [MDN Web Crypto API documentation on AES-GCM](https://developer.mozilla.org/en-US/docs/Web/API/AesGcmParams). diff --git a/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/aeskeygenparams.md b/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/aeskeygenparams.md index eb83b29727..d2468646c1 100644 --- a/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/aeskeygenparams.md +++ b/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/aeskeygenparams.md @@ -6,6 +6,8 @@ weight: 07 # AesKeyGenParams +{{< docs/shared source="k6" lookup="webcrypto/deprecated.md" version="" >}} + The `AesKeyGenParams` object represents the object that should be passed as the algorithm parameter into the [generateKey](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/subtlecrypto/generatekey) operation when generating an AES key. ## Properties diff --git a/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/crypto/_index.md b/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/crypto/_index.md index 5eaa39e53e..fafe5d91d8 100644 --- a/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/crypto/_index.md +++ b/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/crypto/_index.md @@ -6,6 +6,8 @@ weight: 01 # Crypto +{{< docs/shared source="k6" lookup="webcrypto/deprecated.md" version="" >}} + `Crypto` allows access to a cryptographically strong random number generator and to cryptographic primitives. ## Properties diff --git a/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/crypto/getrandomvalues.md b/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/crypto/getrandomvalues.md index 12299df152..954d1484e6 100644 --- a/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/crypto/getrandomvalues.md +++ b/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/crypto/getrandomvalues.md @@ -6,6 +6,8 @@ weight: 01 # getRandomValues +{{< docs/shared source="k6" lookup="webcrypto/deprecated.md" version="" >}} + The `getRandomValues()` method fills the passed `TypedArray` with cryptographically sound random values. ## Usage diff --git a/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/crypto/randomuuid.md b/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/crypto/randomuuid.md index 0a3a0f6931..8768ad2f50 100644 --- a/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/crypto/randomuuid.md +++ b/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/crypto/randomuuid.md @@ -6,6 +6,8 @@ weight: 02 # randomUUID +{{< docs/shared source="k6" lookup="webcrypto/deprecated.md" version="" >}} + The `randomUUID` method produces a 36-characters long string that contains a cryptographically random UUID v4. ## Usage diff --git a/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/cryptokey.md b/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/cryptokey.md index 4e6a77eb20..d61b21612f 100644 --- a/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/cryptokey.md +++ b/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/cryptokey.md @@ -6,6 +6,8 @@ weight: 02 # CryptoKey +{{< docs/shared source="k6" lookup="webcrypto/deprecated.md" version="" >}} + The `CryptoKey` object represents a cryptographic key used for [encryption](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/subtlecrypto/encrypt),[decryption](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/subtlecrypto/decrypt),[signing](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/subtlecrypto/sign), or [verification](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/subtlecrypto/verify) within the webcrypto module. The `CryptoKey` object is created using the SubtleCrypto.generateKey() or SubtleCrypto.importKey() methods. ## Properties diff --git a/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/cryptokeypair.md b/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/cryptokeypair.md index f5eda8b4ad..b6c0a8ef99 100644 --- a/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/cryptokeypair.md +++ b/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/cryptokeypair.md @@ -6,6 +6,8 @@ weight: 08 # CryptoKeyPair +{{< docs/shared source="k6" lookup="webcrypto/deprecated.md" version="" >}} + The `CryptoKeyPair` object represents an asymmetric key pair with public and private keys. The [`generateKey`](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/subtlecrypto/generatekey/) method can be used to create `CryptoKeyPair` object for asymmetric algorithms such as `ECDH` or `ECDSA`. diff --git a/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/ecdhkeyderiveparams.md b/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/ecdhkeyderiveparams.md index d6049a4681..b711dc4fc2 100644 --- a/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/ecdhkeyderiveparams.md +++ b/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/ecdhkeyderiveparams.md @@ -6,6 +6,8 @@ weight: 10 # EcdhKeyDeriveParams +{{< docs/shared source="k6" lookup="webcrypto/deprecated.md" version="" >}} + The `EcdhKeyDeriveParams` represents the object that should be passed as the algorithm parameter into [`deriveBits`](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/subtlecrypto/derivebits/), when using the ECDH algorithm. ECDH is a secure communication method. Parties exchange public keys and use them with their private keys to generate a unique shared secret key. diff --git a/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/ecdsaparams.md b/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/ecdsaparams.md index bb5a0ef43a..229f5a90dc 100644 --- a/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/ecdsaparams.md +++ b/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/ecdsaparams.md @@ -6,6 +6,8 @@ weight: 11 # EcdsaParams +{{< docs/shared source="k6" lookup="webcrypto/deprecated.md" version="" >}} + The `EcdsaParams` represents the object that should be passed as the algorithm parameter into [`sign`](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/subtlecrypto/sign/) or [`verify`](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/subtlecrypto/verify/) when using the ECDSA algorithm. ## Properties diff --git a/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/eckeygenparams.md b/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/eckeygenparams.md index 99cd22d12e..620f946a04 100644 --- a/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/eckeygenparams.md +++ b/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/eckeygenparams.md @@ -6,6 +6,8 @@ weight: 09 # EcKeyGenParams +{{< docs/shared source="k6" lookup="webcrypto/deprecated.md" version="" >}} + The `EcKeyGenParams` object represents the object that should be passed as the algorithm parameter into the [generateKey](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/subtlecrypto/generatekey) operation when generating key pairs for ECDH or ECDSA algorithms. ## Properties diff --git a/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/hmackeygenparams.md b/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/hmackeygenparams.md index 61bafce456..2f0018a722 100644 --- a/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/hmackeygenparams.md +++ b/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/hmackeygenparams.md @@ -6,13 +6,15 @@ weight: 12 # HmacKeyGenParams +{{< docs/shared source="k6" lookup="webcrypto/deprecated.md" version="" >}} + The `HmacKeyGenParams` object represents the object that should be passed as the algorithm parameter into the [generateKey](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/subtlecrypto/generatekey) operation when generating an HMAC key. ## Properties | Property | Type | Description | | :---------------- | :------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| name | `string` | This should be set to `HMAC`. | +| name | `string` | This should be set to `HMAC`. | | hash | `string` | The name of the digest function to use. Possible values are `SHA-1`, `SHA-256`, `SHA-384` and `SHA-512`. | | length (optional) | `number` | The length of the key in bits. If this is omitted, the length of the key is equal to the block size of the hash function you have chosen. We recommend to leave this parameter empty, unless you have a good reason to use something different. | diff --git a/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/jsonwebkey.md b/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/jsonwebkey.md index 9f9dad333a..1b30a7f8aa 100644 --- a/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/jsonwebkey.md +++ b/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/jsonwebkey.md @@ -6,6 +6,8 @@ weight: 13 # JsonWebKey +{{< docs/shared source="k6" lookup="webcrypto/deprecated.md" version="" >}} + The `JsonWebKey` object represents object/dictionary generated by exporting a [`CryptoKey`](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/cryptokey) or used as an input parameter for key import. The properties of the `JsonWebKey` could vary depending on the algorithm and key type. See specification [JsonWebKey](https://www.w3.org/TR/WebCryptoAPI/#JsonWebKey-dictionary) for details. diff --git a/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/rsahashedimportparams.md b/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/rsahashedimportparams.md index bccde9b8a0..6070c17fe1 100644 --- a/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/rsahashedimportparams.md +++ b/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/rsahashedimportparams.md @@ -6,6 +6,8 @@ weight: 12 # RsaHashedImportParams +{{< docs/shared source="k6" lookup="webcrypto/deprecated.md" version="" >}} + The `RsaHashedImportParams` represents the object that should be passed as the algorithm parameter into [`importKey`](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/subtlecrypto/importkey/) when using the RSA algorithm. ## Properties diff --git a/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/rsahashedkeygenparams.md b/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/rsahashedkeygenparams.md index e7e5a816c1..b7c563a597 100644 --- a/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/rsahashedkeygenparams.md +++ b/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/rsahashedkeygenparams.md @@ -6,6 +6,8 @@ weight: 12 # RSAHashedKeyGenParams +{{< docs/shared source="k6" lookup="webcrypto/deprecated.md" version="" >}} + The `RSAHashedKeyGenParams` object represents the object that should be passed as the algorithm parameter into the [generateKey](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/subtlecrypto/generatekey) operation when generating an RSA key pair. ## Properties diff --git a/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/rsaoaepparams.md b/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/rsaoaepparams.md index 1eef8f19b3..78cdfe5d77 100644 --- a/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/rsaoaepparams.md +++ b/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/rsaoaepparams.md @@ -6,6 +6,8 @@ weight: 06 # RsaOaepParams +{{< docs/shared source="k6" lookup="webcrypto/deprecated.md" version="" >}} + The `RsaOaepParams` object represents the object that should be passed as the algorithm parameter into the [encrypt](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/subtlecrypto/encrypt) and [decrypt](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/subtlecrypto/decrypt) operation when using the RSA-OAEP algorithm. For more details, head to the [MDN Web Crypto API documentation on RSA-OAEP](https://developer.mozilla.org/en-US/docs/Web/API/RsaOaepParams). @@ -16,4 +18,4 @@ For more details, head to the [MDN Web Crypto API documentation on RSA-OAEP](htt | :--------------- | :----------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | name | `string` | Should be set to `RSA-OAEP`. | | label (optional) | `ArrayBuffer`, `TypedArray`, or `DataView` | It's an array of bytes that does not itself need to be encrypted but which should be bound to the ciphertext. A digest of the label is part of the input to the encryption operation. Unless your application calls for a label, you can just omit this argument, and it will not affect the security of the encryption operation. | -| | +| | diff --git a/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/rsapssparams.md b/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/rsapssparams.md index a7fe8035c2..2e78126265 100644 --- a/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/rsapssparams.md +++ b/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/rsapssparams.md @@ -6,6 +6,8 @@ weight: 11 # RsaPssParams +{{< docs/shared source="k6" lookup="webcrypto/deprecated.md" version="" >}} + The `RsaPssParams` represents the object that should be passed as the algorithm parameter into [`sign`](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/subtlecrypto/sign/) or [`verify`](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/subtlecrypto/verify/) when using the RSA-PSS algorithm. ## Properties diff --git a/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/subtlecrypto/_index.md b/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/subtlecrypto/_index.md index 32dbb0f94c..6941c9fe99 100644 --- a/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/subtlecrypto/_index.md +++ b/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/subtlecrypto/_index.md @@ -6,6 +6,8 @@ weight: 03 # SubtleCrypto +{{< docs/shared source="k6" lookup="webcrypto/deprecated.md" version="" >}} + The `SubtleCrypto` interface provides a set of low-level cryptographic primitives such as encryption, decryption, digital signature generation and verification, and key generation and management. It is useful for using secure and efficient cryptographic operations within k6 scripts. ## Methods diff --git a/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/subtlecrypto/decrypt.md b/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/subtlecrypto/decrypt.md index a3c541e910..91f19b6cbd 100644 --- a/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/subtlecrypto/decrypt.md +++ b/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/subtlecrypto/decrypt.md @@ -6,6 +6,8 @@ weight: 01 # decrypt +{{< docs/shared source="k6" lookup="webcrypto/deprecated.md" version="" >}} + The `decrypt()` method decrypts some encrypted data. ## Usage diff --git a/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/subtlecrypto/derivebits.md b/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/subtlecrypto/derivebits.md index d3df0a7805..7f32de377f 100644 --- a/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/subtlecrypto/derivebits.md +++ b/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/subtlecrypto/derivebits.md @@ -6,6 +6,8 @@ weight: 02 # deriveBits +{{< docs/shared source="k6" lookup="webcrypto/deprecated.md" version="" >}} + It takes as its arguments the base key, the derivation algorithm to use, and the length of the bits to derive. It returns a Promise which will be fulfilled with an `ArrayBuffer` containing the derived bits. This array of bits can be used as a key for encryption or decryption as a shared secret. ## Usage diff --git a/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/subtlecrypto/digest.md b/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/subtlecrypto/digest.md index cb60f4c255..0091a4c950 100644 --- a/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/subtlecrypto/digest.md +++ b/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/subtlecrypto/digest.md @@ -6,6 +6,8 @@ weight: 02 # digest +{{< docs/shared source="k6" lookup="webcrypto/deprecated.md" version="" >}} + The `digest()` method generates a cryptographically secure [digest](https://developer.mozilla.org/en-US/docs/Glossary/Digest) of the given data. A digest is a short fixed-length value derived from some input data. The `digest()` method is commonly used to compute a checksum of data or to verify the integrity of data. ## Usage diff --git a/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/subtlecrypto/encrypt.md b/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/subtlecrypto/encrypt.md index c23b59821c..181b456256 100644 --- a/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/subtlecrypto/encrypt.md +++ b/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/subtlecrypto/encrypt.md @@ -6,6 +6,8 @@ weight: 03 # encrypt +{{< docs/shared source="k6" lookup="webcrypto/deprecated.md" version="" >}} + The `encrypt()` method encrypts some data. ## Usage diff --git a/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/subtlecrypto/exportkey.md b/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/subtlecrypto/exportkey.md index 4f1a69a9bd..64552fddcd 100644 --- a/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/subtlecrypto/exportkey.md +++ b/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/subtlecrypto/exportkey.md @@ -6,6 +6,8 @@ weight: 04 # exportKey +{{< docs/shared source="k6" lookup="webcrypto/deprecated.md" version="" >}} + The `exportKey()` method takes a [CryptoKey](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/cryptokey) object as input and exports it in an external, portable format. Note that for a key to be exportable, it must have been created with the `extractable` flag set to `true`. diff --git a/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/subtlecrypto/generatekey.md b/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/subtlecrypto/generatekey.md index fdae3524dc..2846a9871a 100644 --- a/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/subtlecrypto/generatekey.md +++ b/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/subtlecrypto/generatekey.md @@ -24,6 +24,8 @@ generateKey(algorithm, extractable, keyUsages) ### Supported algorithms +{{< docs/shared source="k6" lookup="webcrypto/deprecated.md" version="" >}} + {{< docs/shared source="k6" lookup="webcrypto/supported-key-methods.md" version="" >}} ## Return Value @@ -32,15 +34,15 @@ A `Promise` that resolves with the generated key as a [CryptoKey](https://grafan ### Algorithm specific input -| | HMAC | AES | ECDH | ECDSA | RSA-OAEP | RSASSA-PKCS1-v1_5 | RSA-PSS | -| :--------------------- | :----------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------- |----- |----- |----- | +| | HMAC | AES | ECDH | ECDSA | RSA-OAEP | RSASSA-PKCS1-v1_5 | RSA-PSS | +| :--------------------- | :----------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | Parameters type to use | [`HmacKeyGenParams`](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/hmackeygenparams) | [`AesKeyGenParams`](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/aeskeygenparams) | [`EcKeyGenParams`](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/eckeygenparams) | [`EcKeyGenParams`](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/eckeygenparams) | [`RSAHashedKeyGenParams`](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/rsahashedkeygenparams) | [`RSAHashedKeyGenParams`](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/rsahashedkeygenparams) | [`RSAHashedKeyGenParams`](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/rsahashedkeygenparams) | -| Possible key usages | `sign`, `verify` | `encrypt`, `decrypt` | `deriveKey`, `deriveBits` | `sign`, `verify` | `encrypt`, `decrypt` | `sign`, `verify` | `sign`, `verify` | +| Possible key usages | `sign`, `verify` | `encrypt`, `decrypt` | `deriveKey`, `deriveBits` | `sign`, `verify` | `encrypt`, `decrypt` | `sign`, `verify` | `sign`, `verify` | ## Throws -| Type | Description | -| :------------ | :------------------------------------------------------------------------------------------- | +| Type | Description | +| :------------ | :-------------------------------------------------------------------------------------------- | | `SyntaxError` | Raised when the `keyUsages` parameter is empty, but the key is of type `secret` or `private`. | ## Example diff --git a/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/subtlecrypto/importkey.md b/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/subtlecrypto/importkey.md index 3b59c4b9c2..4d37e8152c 100644 --- a/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/subtlecrypto/importkey.md +++ b/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/subtlecrypto/importkey.md @@ -6,6 +6,8 @@ weight: 06 # importKey +{{< docs/shared source="k6" lookup="webcrypto/deprecated.md" version="" >}} + The `importKey()` imports a key from an external, portable format, and gives you a [CryptoKey](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/cryptokey) object that can be used with the Web Crypto API. ## Usage diff --git a/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/subtlecrypto/sign.md b/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/subtlecrypto/sign.md index 86cabbd4c5..90b1aebb87 100644 --- a/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/subtlecrypto/sign.md +++ b/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/subtlecrypto/sign.md @@ -6,6 +6,8 @@ weight: 07 # sign +{{< docs/shared source="k6" lookup="webcrypto/deprecated.md" version="" >}} + The `sign()` operation generates a digital signature of the provided `data`, using the given [CryptoKey](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/cryptokey) object. ## Usage @@ -16,11 +18,11 @@ sign(algorithm, key, data) ## Parameters -| Name | Type | Description | -| :---------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------- | +| Name | Type | Description | +| :---------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------ | | `algorithm` | `string` or object with a single `name` string property (`{name: "RSASSA-PKCS1-v1_5"}`) or an [EcdsaParams](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/ecdsaparams/), [HmacKeyGenParams](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/hmackeygenparams/), or [RsaPssParams](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/rsapssparams/) object. | The signature algorithm to use. | -| `key` | [CryptoKey](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/cryptokey) | The key to use for signing. | -| `data` | `ArrayBuffer`, `TypedArray`, or `DataView` | The data to be signed. | +| `key` | [CryptoKey](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/cryptokey) | The key to use for signing. | +| `data` | `ArrayBuffer`, `TypedArray`, or `DataView` | The data to be signed. | ### Supported algorithms diff --git a/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/subtlecrypto/verify.md b/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/subtlecrypto/verify.md index ad58aff134..e6baa0259e 100644 --- a/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/subtlecrypto/verify.md +++ b/docs/sources/k6/next/javascript-api/k6-experimental/webcrypto/subtlecrypto/verify.md @@ -6,6 +6,8 @@ weight: 08 # verify +{{< docs/shared source="k6" lookup="webcrypto/deprecated.md" version="" >}} + The `verify()` operation verifies a digital signature. It ensures that some data was signed by a known key and that the data has not been tampered with since it was signed. ## Usage @@ -16,12 +18,12 @@ verify(algorithm, key, signature, data) ## Parameters -| Name | Type | Description | -| :---------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------- | -| `algorithm` | `string` or object with a single `name` string property (`{name: "RSASSA-PKCS1-v1_5"}`) or an [EcdsaParams](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/ecdsaparams/), [HmacKeyGenParams](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/hmackeygenparams/), or [RsaPssParams](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/rsapssparams/) object. | The signature algorithm to use. | -| `key` | [CryptoKey](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/cryptokey) | The key that will be used to verify the signature. | -| `signature` | `ArrayBuffer` | The signature to verify. | -| `data` | `ArrayBuffer` | The data whose signature is to be verified. | +| Name | Type | Description | +| :---------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------- | +| `algorithm` | `string` or object with a single `name` string property (`{name: "RSASSA-PKCS1-v1_5"}`) or an [EcdsaParams](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/ecdsaparams/), [HmacKeyGenParams](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/hmackeygenparams/), or [RsaPssParams](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/rsapssparams/) object. | The signature algorithm to use. | +| `key` | [CryptoKey](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/cryptokey) | The key that will be used to verify the signature. | +| `signature` | `ArrayBuffer` | The signature to verify. | +| `data` | `ArrayBuffer` | The data whose signature is to be verified. | ### Supported algorithms diff --git a/docs/sources/k6/next/shared/crypto-module.md b/docs/sources/k6/next/shared/crypto-module.md index 241d3d3374..dc884083b5 100644 --- a/docs/sources/k6/next/shared/crypto-module.md +++ b/docs/sources/k6/next/shared/crypto-module.md @@ -7,6 +7,6 @@ title: k6/crypto module admonition A module with a better and standard API exists.

-The new [k6/experimental/webcrypto API](/docs/k6//javascript-api/k6-experimental/webcrypto/) partially implements the [WebCryptoAPI](https://www.w3.org/TR/WebCryptoAPI/), supporting more features than [k6/crypto](/docs/k6//javascript-api/k6-crypto/). +The [crypto module](/docs/k6//javascript-api/crypto/) partially implements the [WebCrypto API](https://www.w3.org/TR/WebCryptoAPI/), supporting more features than [k6/crypto](/docs/k6//javascript-api/k6-crypto/). {{< /admonition >}} diff --git a/docs/sources/k6/next/shared/crypto/supported-encrypt-decrypt.md b/docs/sources/k6/next/shared/crypto/supported-encrypt-decrypt.md new file mode 100644 index 0000000000..259cf657cb --- /dev/null +++ b/docs/sources/k6/next/shared/crypto/supported-encrypt-decrypt.md @@ -0,0 +1,7 @@ +--- +title: webcrypto/supported encrypt/decrypt +--- + +| AES-CBC | AES-CTR | AES-GCM | RSA-OAEP | +| :--------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------- | +| ✅ [AesCbcParams](https://grafana.com/docs/k6//javascript-api/crypto/aescbcparams) | ✅ [AesCtrParams](https://grafana.com/docs/k6//javascript-api/crypto/aesctrparams) | ✅ [AesGcmParams](https://grafana.com/docs/k6//javascript-api/crypto/aesgcmparams) | ✅ [RsaOaepParams](https://grafana.com/docs/k6//javascript-api/crypto/rsaoaepparams) | diff --git a/docs/sources/k6/next/shared/crypto/supported-key-methods-formats.md b/docs/sources/k6/next/shared/crypto/supported-key-methods-formats.md new file mode 100644 index 0000000000..d2545a7477 --- /dev/null +++ b/docs/sources/k6/next/shared/crypto/supported-key-methods-formats.md @@ -0,0 +1,7 @@ +--- +title: webcrypto/supported key methods formats +--- + +- `ECDH` and `ECDSA` algorithms have support for `pkcs8`, `spki`, `raw` and `jwk` formats. +- `RSA-OAEP`, `RSASSA-PKCS1-v1_5` and `RSA-PSS` algorithms have support for `pkcs8`, `spki` and `jwk` formats. +- `AES-*` and `HMAC` algorithms have currently support for `raw` and `jwk` formats. diff --git a/docs/sources/k6/next/shared/crypto/supported-key-methods.md b/docs/sources/k6/next/shared/crypto/supported-key-methods.md new file mode 100644 index 0000000000..36bd96a060 --- /dev/null +++ b/docs/sources/k6/next/shared/crypto/supported-key-methods.md @@ -0,0 +1,7 @@ +--- +title: webcrypto/supported key methods +--- + +| AES-CBC | AES-CTR | AES-GCM | AES-KW | ECDH | ECDSA | HMAC | RSA-OAEP | RSASSA-PKCS1-v1_5 | RSA-PSS | +| :--------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------- | :----- | :------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------ | :---------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------- | +| ✅ [AesCbcParams](https://grafana.com/docs/k6//javascript-api/crypto/aescbcparams) | ✅ [AesCtrParams](https://grafana.com/docs/k6//javascript-api/crypto/aesctrparams) | ✅ [AesGcmParams](https://grafana.com/docs/k6//javascript-api/crypto/aesgcmparams) | ❌ | ✅ [EcdhKeyDeriveParams](https://grafana.com/docs/k6//javascript-api/crypto/ecdhkeyderiveparams/) | ✅ [EcdsaParams](https://grafana.com/docs/k6//javascript-api/crypto/ecdsaparams/) | ✅ [HmacKeyGenParams](https://grafana.com/docs/k6//javascript-api/crypto/hmackeygenparams/) | ✅ [RsaHashedImportParams](https://grafana.com/docs/k6//javascript-api/crypto/rsahashedimportparams/) | ✅ [RsaHashedImportParams](https://grafana.com/docs/k6//javascript-api/crypto/rsahashedimportparams/) | ✅ [RsaHashedImportParams](https://grafana.com/docs/k6//javascript-api/crypto/rsahashedimportparams/) | diff --git a/docs/sources/k6/next/shared/crypto/supported-sign-verify.md b/docs/sources/k6/next/shared/crypto/supported-sign-verify.md new file mode 100644 index 0000000000..7317e231ba --- /dev/null +++ b/docs/sources/k6/next/shared/crypto/supported-sign-verify.md @@ -0,0 +1,7 @@ +--- +title: webcrypto/supported sign/verify +--- + +| ECDSA | HMAC | RSASSA-PKCS1-v1_5 | RSA-PSS | +| :-------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------ | :---------------- | :---------------------------------------------------------------------------------------------- | +| ✅ [EcdsaParams](https://grafana.com/docs/k6//javascript-api/crypto/ecdsaparams/) | ✅ [HmacKeyGenParams](https://grafana.com/docs/k6//javascript-api/crypto/hmackeygenparams/) | ✅ | ✅ [RsaPssParams](https://grafana.com/docs/k6//javascript-api/crypto/rsapssparams/) | diff --git a/docs/sources/k6/next/shared/javascript-api/crypto.md b/docs/sources/k6/next/shared/javascript-api/crypto.md new file mode 100644 index 0000000000..a34b88f7c9 --- /dev/null +++ b/docs/sources/k6/next/shared/javascript-api/crypto.md @@ -0,0 +1,17 @@ +--- +title: javascript-api/crypto +--- + +The [`crypto` module](https://grafana.com/docs/k6//javascript-api/crypto) provides a WebCrypto API implementation. + +| Class/Method | Description | +| ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| [getRandomValues](https://grafana.com/docs/k6//javascript-api/crypto/getrandomvalues) | Fills the passed `TypedArray` with cryptographically sound random values. | +| [randomUUID](https://grafana.com/docs/k6//javascript-api/crypto/randomuuid) | Returns a randomly generated, 36 character long v4 UUID. | +| [subtle](https://grafana.com/docs/k6//javascript-api/crypto/subtlecrypto) | The [SubtleCrypto](https://grafana.com/docs/k6//javascript-api/crypto/subtlecrypto) interface provides access to common cryptographic primitives, such as hashing, signing, encryption, or decryption. | + +{{< admonition type="note" >}} + +The `crypto` object is available globally, so you can use it in your script without including an import statement. + +{{< /admonition >}} diff --git a/docs/sources/k6/next/shared/webcrypto/deprecated.md b/docs/sources/k6/next/shared/webcrypto/deprecated.md new file mode 100644 index 0000000000..d24bd280b1 --- /dev/null +++ b/docs/sources/k6/next/shared/webcrypto/deprecated.md @@ -0,0 +1,11 @@ +--- +title: Experimental webcrypto module admonition +--- + +{{< admonition type="caution" >}} + +The experimental module `k6/experimental/webcrypto` has graduated, and its functionality is now available globally through the [`crypto` object](https://grafana.com/docs/k6//javascript-api/crypto). The `k6/experimental/webcrypto` is deprecated and will be removed in the near future. + +To migrate your scripts, remove the `k6/experimental/webcrypto` imports and use the `crypto` object instead. + +{{< /admonition >}} diff --git a/docs/sources/k6/v1.0.x/javascript-api/_index.md b/docs/sources/k6/v1.0.x/javascript-api/_index.md index 0355249bc7..bfbf03ebb3 100644 --- a/docs/sources/k6/v1.0.x/javascript-api/_index.md +++ b/docs/sources/k6/v1.0.x/javascript-api/_index.md @@ -77,6 +77,10 @@ The [`k6/browser` module](https://grafana.com/docs/k6//javascript-ap {{< docs/shared source="k6" lookup="javascript-api/k6-ws.md" version="" >}} +## crypto + +{{< docs/shared source="k6" lookup="javascript-api/crypto.md" version="" >}} + ## Error codes The following specific error codes are currently defined: diff --git a/docs/sources/k6/v1.0.x/javascript-api/crypto/_index.md b/docs/sources/k6/v1.0.x/javascript-api/crypto/_index.md new file mode 100644 index 0000000000..9adc974a52 --- /dev/null +++ b/docs/sources/k6/v1.0.x/javascript-api/crypto/_index.md @@ -0,0 +1,90 @@ +--- +title: 'crypto' +description: 'k6 WebCrypto API implementation' +weight: 14 +--- + +# crypto + +With this module, you can use the [WebCrypto API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API) in your k6 scripts. However, note that this API is not yet fully implemented and some algorithms and features might still be missing. + +The Web Crypto API is a JavaScript API for performing cryptographic operations such as encryption, decryption, digital signature generation and verification, and key generation and management. It provides a standard interface to access cryptographic functionality, which can help ensure that cryptographic operations are performed correctly and securely. + +## API + +The module is a top-level `crypto` object with the following properties and methods: + +| Interface/Function | Description | +| :------------------------------------------------------------------------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [getRandomValues](https://grafana.com/docs/k6//javascript-api/crypto/getrandomvalues) | Fills the passed `TypedArray` with cryptographically sound random values. | +| [randomUUID](https://grafana.com/docs/k6//javascript-api/crypto/randomuuid) | Returns a randomly generated, 36 character long v4 UUID. | +| [subtle](https://grafana.com/docs/k6//javascript-api/crypto/subtlecrypto) | The [SubtleCrypto](https://grafana.com/docs/k6//javascript-api/crypto/subtlecrypto) interface provides access to common cryptographic primitives, such as hashing, signing, encryption, or decryption. | + +## Example + +{{< code >}} + +```javascript +export default async function () { + const plaintext = stringToArrayBuffer('Hello, World!'); + + /** + * Generate a symmetric key using the AES-CBC algorithm. + */ + const key = await crypto.subtle.generateKey( + { + name: 'AES-CBC', + length: 256, + }, + true, + ['encrypt', 'decrypt'] + ); + + /** + * Encrypt the plaintext using the AES-CBC key with + * have generated. + */ + const iv = crypto.getRandomValues(new Uint8Array(16)); + const ciphertext = await crypto.subtle.encrypt( + { + name: 'AES-CBC', + iv: iv, + }, + key, + plaintext + ); + + /** + * Decrypt the ciphertext using the same key to verify + * that the resulting plaintext is the same as the original. + */ + const deciphered = await crypto.subtle.decrypt( + { + name: 'AES-CBC', + iv: iv, + }, + key, + ciphertext + ); + + console.log( + 'deciphered text == original plaintext: ', + arrayBufferToHex(deciphered) === arrayBufferToHex(plaintext) + ); +} + +function arrayBufferToHex(buffer) { + return [...new Uint8Array(buffer)].map((x) => x.toString(16).padStart(2, '0')).join(''); +} + +function stringToArrayBuffer(str) { + const buf = new ArrayBuffer(str.length * 2); // 2 bytes for each char + const bufView = new Uint16Array(buf); + for (let i = 0, strLen = str.length; i < strLen; i++) { + bufView[i] = str.charCodeAt(i); + } + return buf; +} +``` + +{{< /code >}} diff --git a/docs/sources/k6/v1.0.x/javascript-api/crypto/aescbcparams.md b/docs/sources/k6/v1.0.x/javascript-api/crypto/aescbcparams.md new file mode 100644 index 0000000000..9d092019c2 --- /dev/null +++ b/docs/sources/k6/v1.0.x/javascript-api/crypto/aescbcparams.md @@ -0,0 +1,64 @@ +--- +title: 'AesCbcParams' +description: 'AesCbcParams represents the object that should be passed as the algorithm parameter into the encrypt and decrypt operation when using the AES-CBC algorithm.' +weight: 04 +--- + +# AesCbcParams + +The `AesCbcParams` object represents the object that should be passed as the algorithm parameter into the [encrypt](https://grafana.com/docs/k6//javascript-api/crypto/subtlecrypto/encrypt) and [decrypt](https://grafana.com/docs/k6//javascript-api/crypto/subtlecrypto/decrypt) operation when using the AES-CBC algorithm. + +For more details, head to the [MDN Web Crypto API documentation on AES-CBC](https://developer.mozilla.org/en-US/docs/Web/API/AesCbcParams). + +## Properties + +| Property | Type | Description | +| :------- | :----------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| name | `string` | Should be set to `AES-CBC`. | +| iv | `ArrayBuffer`, `TypedArray`, or `DataView` | The initialization vector. Must be 16 bytes, unpredictable and cryptographically random. Yet, it doesn't need to be secret and can be transmitted along with the ciphertext. | + +## Example + +{{< code >}} + +```javascript +export default async function () { + const plaintext = stringToArrayBuffer('Hello, World!'); + + /** + * Generate a symmetric key using the AES-CBC algorithm. + */ + const key = await crypto.subtle.generateKey( + { + name: 'AES-CBC', + length: 256, + }, + true, + ['encrypt', 'decrypt'] + ); + + /** + * Encrypt the plaintext using the AES-CBC key with + * have generated. + */ + const ciphertext = await crypto.subtle.encrypt( + { + name: 'AES-CBC', + iv: crypto.getRandomValues(new Uint8Array(16)), + }, + key, + plaintext + ); +} + +function stringToArrayBuffer(str) { + const buf = new ArrayBuffer(str.length * 2); // 2 bytes for each char + const bufView = new Uint16Array(buf); + for (let i = 0, strLen = str.length; i < strLen; i++) { + bufView[i] = str.charCodeAt(i); + } + return buf; +} +``` + +{{< /code >}} diff --git a/docs/sources/k6/v1.0.x/javascript-api/crypto/aesctrparams.md b/docs/sources/k6/v1.0.x/javascript-api/crypto/aesctrparams.md new file mode 100644 index 0000000000..6a7fbb4431 --- /dev/null +++ b/docs/sources/k6/v1.0.x/javascript-api/crypto/aesctrparams.md @@ -0,0 +1,66 @@ +--- +title: 'AesCtrParams' +description: 'AesCtrParams represents the object that should be passed as the algorithm parameter into the encrypt and decrypt operation when using the AES-CTR algorithm.' +weight: 05 +--- + +# AesCtrParams + +The `AesCtrParams` object represents the object that should be passed as the algorithm parameter into the [encrypt](https://grafana.com/docs/k6//javascript-api/crypto/subtlecrypto/encrypt) and [decrypt](https://grafana.com/docs/k6//javascript-api/crypto/subtlecrypto/decrypt) operation when using the AES-CTR algorithm. + +For more details, head to the MDN Web Crypto API documentation on [AES-CTR](https://developer.mozilla.org/en-US/docs/Web/API/AesCtrParams). + +## Properties + +| Property | Type | Description | +| :------- | :----------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------- | +| name | `string` | Should be set to `AES-CTR`. | +| counter | `ArrayBuffer`, `TypedArray`, or `DataView` | The initial value of the counter block. This must be 16-bytes long, like the AES block size. | +| length | `number` | The number of bits in the counter block that are used for the actual counter. It is recommended to use 64 (half of the counter block). | + +## Example + +{{< code >}} + +```javascript +export default async function () { + const plaintext = stringToArrayBuffer('Hello, World!'); + + /** + * Generate a symmetric key using the AES-CTR algorithm. + */ + const key = await crypto.subtle.generateKey( + { + name: 'AES-CTR', + length: 256, + }, + true, + ['encrypt', 'decrypt'] + ); + + /** + * Encrypt the plaintext using the AES-CTR key with + * have generated. + */ + const ciphertext = await crypto.subtle.encrypt( + { + name: 'AES-CTR', + counter: crypto.getRandomValues(new Uint8Array(16)), + length: 128, + }, + key, + plaintext + ); +} + +function stringToArrayBuffer(str) { + const buf = new ArrayBuffer(str.length * 2); // 2 bytes for each char + const bufView = new Uint16Array(buf); + for (let i = 0, strLen = str.length; i < strLen; i++) { + bufView[i] = str.charCodeAt(i); + } + return buf; +} +``` + +{{< /code >}} diff --git a/docs/sources/k6/v1.0.x/javascript-api/crypto/aesgcmparams.md b/docs/sources/k6/v1.0.x/javascript-api/crypto/aesgcmparams.md new file mode 100644 index 0000000000..ad38393128 --- /dev/null +++ b/docs/sources/k6/v1.0.x/javascript-api/crypto/aesgcmparams.md @@ -0,0 +1,66 @@ +--- +title: 'AesGcmParams' +description: 'AesGcmParams represents the object that should be passed as the algorithm parameter into the encrypt and decrypt operation when using the AES-GCM algorithm.' +weight: 06 +--- + +# AesGcmParams + +The `AesGcmParams` object represents the object that should be passed as the algorithm parameter into the [encrypt](https://grafana.com/docs/k6//javascript-api/crypto/subtlecrypto/encrypt) and [decrypt](https://grafana.com/docs/k6//javascript-api/crypto/subtlecrypto/decrypt) operation when using the AES-GCM algorithm. + +For more details, head to the [MDN Web Crypto API documentation on AES-GCM](https://developer.mozilla.org/en-US/docs/Web/API/AesGcmParams). + +## Properties + +| Property | Type | Description | +| :------------------------ | :----------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| name | `string` | Should be set to `AES-GCM`. | +| iv | `ArrayBuffer`, `TypedArray`, or `DataView` | The initialization vector. It must be 12 bytes long, unpredictable and cryptographically random. It must be unique for every encryption operation carried out with a given key. Never reuse an iv with the same key. Yet, it doesn't need to be secret and can be transmitted along with the ciphertext. | +| additionalData (optional) | `ArrayBuffer`, `TypedArray` or `DataView` | Additional data that should be authenticated, but not encrypted. It must be included in the calculation of the authentication tag, but not encrypted itself. | +| tagLength (optional) | `number` | The length of the authentication tag in bits. Should be set, and will default to 96. | + +## Example + +{{< code >}} + +```javascript +export default async function () { + const plaintext = stringToArrayBuffer('Hello, World!'); + + /** + * Generate a symmetric key using the AES-CBC algorithm. + */ + const key = await crypto.subtle.generateKey( + { + name: 'AES-GCM', + length: 256, + }, + true, + ['encrypt', 'decrypt'] + ); + + /** + * Encrypt the plaintext using the AES-CBC key with + * have generated. + */ + const ciphertext = await crypto.subtle.encrypt( + { + name: 'AES-GCM', + iv: crypto.getRandomValues(new Uint8Array(12)), + }, + key, + plaintext + ); +} + +function stringToArrayBuffer(str) { + const buf = new ArrayBuffer(str.length * 2); // 2 bytes for each char + const bufView = new Uint16Array(buf); + for (let i = 0, strLen = str.length; i < strLen; i++) { + bufView[i] = str.charCodeAt(i); + } + return buf; +} +``` + +{{< /code >}} diff --git a/docs/sources/k6/v1.0.x/javascript-api/crypto/aeskeygenparams.md b/docs/sources/k6/v1.0.x/javascript-api/crypto/aeskeygenparams.md new file mode 100644 index 0000000000..66d3fedd9f --- /dev/null +++ b/docs/sources/k6/v1.0.x/javascript-api/crypto/aeskeygenparams.md @@ -0,0 +1,35 @@ +--- +title: 'AesKeyGenParams' +description: 'AesKeyGenParams represents the object that should be passed as the algorithm parameter into the generateKey operation, when generating an AES key.' +weight: 07 +--- + +# AesKeyGenParams + +The `AesKeyGenParams` object represents the object that should be passed as the algorithm parameter into the [generateKey](https://grafana.com/docs/k6//javascript-api/crypto/subtlecrypto/generatekey) operation when generating an AES key. + +## Properties + +| Property | Type | Description | +| :------- | :------- | :---------------------------------------------------------------------------------- | +| name | `string` | The name of the algorithm. Possible values are `AES-CBC`, `AES-CTR`, and `AES-GCM`. | +| length | `number` | The length of the key in bits. Possible values are 128, 192 or 256. | + +## Example + +{{< code >}} + +```javascript +export default async function () { + const key = await crypto.subtle.generateKey( + { + name: 'AES-CBC', + length: 256, + }, + true, + ['encrypt', 'decrypt'] + ); +} +``` + +{{< /code >}} diff --git a/docs/sources/k6/v1.0.x/javascript-api/crypto/cryptokey.md b/docs/sources/k6/v1.0.x/javascript-api/crypto/cryptokey.md new file mode 100644 index 0000000000..7bc0ff8270 --- /dev/null +++ b/docs/sources/k6/v1.0.x/javascript-api/crypto/cryptokey.md @@ -0,0 +1,18 @@ +--- +title: 'CryptoKey' +description: 'CryptoKey represents a cryptographic key used for encryption, decryption, signing, or verification.' +weight: 02 +--- + +# CryptoKey + +The `CryptoKey` object represents a cryptographic key used for [encryption](https://grafana.com/docs/k6//javascript-api/crypto/subtlecrypto/encrypt),[decryption](https://grafana.com/docs/k6//javascript-api/crypto/subtlecrypto/decrypt),[signing](https://grafana.com/docs/k6//javascript-api/crypto/subtlecrypto/sign), or [verification](https://grafana.com/docs/k6//javascript-api/crypto/subtlecrypto/verify) within the webcrypto module. The `CryptoKey` object is created using the SubtleCrypto.generateKey() or SubtleCrypto.importKey() methods. + +## Properties + +| Property | Type | Description | +| :---------- | :--------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| type | `string` | Indicates the type of the key material. Possible values are `public`, `private`, `secret`, `unspecified`, or `unknown`. | +| extractable | `boolean` | Indicates whether the raw key material can be exported. | +| algorithm | `object` | An object containing the algorithm used to generate or import the key. | +| usages | `string[]` | An array of strings indicating the cryptographic operations that the key can be used for. Possible values are `encrypt`, `decrypt`, `sign`, `verify`, `deriveKey`, `deriveBits`, `wrapKey`, and `unwrapKey`. | diff --git a/docs/sources/k6/v1.0.x/javascript-api/crypto/cryptokeypair.md b/docs/sources/k6/v1.0.x/javascript-api/crypto/cryptokeypair.md new file mode 100644 index 0000000000..7cb7d4074a --- /dev/null +++ b/docs/sources/k6/v1.0.x/javascript-api/crypto/cryptokeypair.md @@ -0,0 +1,18 @@ +--- +title: 'CryptoKeyPair' +description: 'CryptoKeyPair represents an asymmetric key pair with public and private keys.' +weight: 08 +--- + +# CryptoKeyPair + +The `CryptoKeyPair` object represents an asymmetric key pair with public and private keys. + +The [`generateKey`](https://grafana.com/docs/k6//javascript-api/crypto/subtlecrypto/generatekey/) method can be used to create `CryptoKeyPair` object for asymmetric algorithms such as `ECDH` or `ECDSA`. + +## Properties + +| Property | Type | Description | +| :--------- | :-------------------------------------------------------------------------------------- | :------------- | +| publicKey | [`CryptoKey`](https://grafana.com/docs/k6//javascript-api/crypto/cryptokey) | A public key. | +| privateKey | [`CryptoKey`](https://grafana.com/docs/k6//javascript-api/crypto/cryptokey) | A private key. | diff --git a/docs/sources/k6/v1.0.x/javascript-api/crypto/ecdhkeyderiveparams.md b/docs/sources/k6/v1.0.x/javascript-api/crypto/ecdhkeyderiveparams.md new file mode 100644 index 0000000000..399b746b79 --- /dev/null +++ b/docs/sources/k6/v1.0.x/javascript-api/crypto/ecdhkeyderiveparams.md @@ -0,0 +1,18 @@ +--- +title: 'EcdhKeyDeriveParams' +description: 'EcdhKeyDeriveParams is a parameter used for derive bits operation.' +weight: 10 +--- + +# EcdhKeyDeriveParams + +The `EcdhKeyDeriveParams` represents the object that should be passed as the algorithm parameter into [`deriveBits`](https://grafana.com/docs/k6//javascript-api/crypto/subtlecrypto/derivebits/), when using the ECDH algorithm. + +ECDH is a secure communication method. Parties exchange public keys and use them with their private keys to generate a unique shared secret key. + +## Properties + +| Property | Type | Description | +| :-------- | :-------------------------------------------------------------------------------------- | :----------------------------------- | +| name | `string` | An algorithm name. Should be `ECDH`. | +| publicKey | [`CryptoKey`](https://grafana.com/docs/k6//javascript-api/crypto/cryptokey) | Another party's public key. | diff --git a/docs/sources/k6/v1.0.x/javascript-api/crypto/ecdsaparams.md b/docs/sources/k6/v1.0.x/javascript-api/crypto/ecdsaparams.md new file mode 100644 index 0000000000..f3a503b13b --- /dev/null +++ b/docs/sources/k6/v1.0.x/javascript-api/crypto/ecdsaparams.md @@ -0,0 +1,16 @@ +--- +title: 'EcdsaParams' +description: 'EcdsaParams is a parameter used for sign or verify operations.' +weight: 11 +--- + +# EcdsaParams + +The `EcdsaParams` represents the object that should be passed as the algorithm parameter into [`sign`](https://grafana.com/docs/k6//javascript-api/crypto/subtlecrypto/sign/) or [`verify`](https://grafana.com/docs/k6//javascript-api/crypto/subtlecrypto/verify/) when using the ECDSA algorithm. + +## Properties + +| Property | Type | Description | +| :------- | :------- | :---------------------------------------------------------------------------------------------------- | +| name | `string` | An algorithm name. Should be `ECDSA`. | +| hash | `string` | An identifier for the digest algorithm to use. Possible values are `SHA-256`, `SHA-384` or `SHA-512`. | diff --git a/docs/sources/k6/v1.0.x/javascript-api/crypto/eckeygenparams.md b/docs/sources/k6/v1.0.x/javascript-api/crypto/eckeygenparams.md new file mode 100644 index 0000000000..fd752a9f5e --- /dev/null +++ b/docs/sources/k6/v1.0.x/javascript-api/crypto/eckeygenparams.md @@ -0,0 +1,37 @@ +--- +title: 'EcKeyGenParams' +description: 'EcKeyGenParams represents the object that should be passed as the algorithm parameter into the generateKey operation, when generating ECDH or ECDSA key pairs.' +weight: 09 +--- + +# EcKeyGenParams + +The `EcKeyGenParams` object represents the object that should be passed as the algorithm parameter into the [generateKey](https://grafana.com/docs/k6//javascript-api/crypto/subtlecrypto/generatekey) operation when generating key pairs for ECDH or ECDSA algorithms. + +## Properties + +| Property | Type | Description | +| :--------- | :------- | :------------------------------------------------------------------------------------------------------- | +| name | `string` | An algorithm name. Possible values are `ECDH` or `ECDSA`. | +| namedCurve | `string` | A elliptic curve's name to use for key pair generation. Possible values are `P-256`, `P-384` or `P-521`. | + +## Example + +{{< code >}} + +```javascript +export default async function () { + const keyPair = await crypto.subtle.generateKey( + { + name: 'ECDSA', + namedCurve: 'P-256', + }, + true, + ['sign', 'verify'] + ); + + console.log(JSON.stringify(keyPair)); +} +``` + +{{< /code >}} diff --git a/docs/sources/k6/v1.0.x/javascript-api/crypto/getrandomvalues.md b/docs/sources/k6/v1.0.x/javascript-api/crypto/getrandomvalues.md new file mode 100644 index 0000000000..8df52002dd --- /dev/null +++ b/docs/sources/k6/v1.0.x/javascript-api/crypto/getrandomvalues.md @@ -0,0 +1,48 @@ +--- +title: 'getRandomValues' +description: 'getRandomValues fills the passed TypedArray with cryptographically sound random values.' +weight: 01 +--- + +# getRandomValues + +The `getRandomValues()` method fills the passed `TypedArray` with cryptographically sound random values. + +## Usage + +``` +getRandomValues(typedArray) +``` + +## Parameters + +| Name | Type | Description | +| :----------- | :----------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `typedArray` | `TypedArray` | An integer-based `TypedArray` to fill with random values. Accepted `TypedArray` specific types are: `Int8Array`, `Uint8Array`, `Uint8ClampedArray`, `Int16Array`, `Uint16Array`, `Int32Array`, or `Uint32Array`. | + +## Return Value + +The same array is passed as the `typedArray` parameter with its contents replaced with the newly generated random numbers. The `typedArray` parameter is modified in place, and no copy is made. + +## Throws + +| Type | Description | +| :------------------- | :------------------------------------------------------------------------ | +| `QuotaExceededError` | Thrown when `typedArray` is too large and its `byteLength` exceeds 65536. | + +## Example + +{{< code >}} + +```javascript +export default function () { + const array = new Uint32Array(10); + crypto.getRandomValues(array); + + for (const num of array) { + console.log(num); + } +} +``` + +{{< /code >}} diff --git a/docs/sources/k6/v1.0.x/javascript-api/crypto/hmackeygenparams.md b/docs/sources/k6/v1.0.x/javascript-api/crypto/hmackeygenparams.md new file mode 100644 index 0000000000..fbc7956bda --- /dev/null +++ b/docs/sources/k6/v1.0.x/javascript-api/crypto/hmackeygenparams.md @@ -0,0 +1,37 @@ +--- +title: 'HmacKeyGenParams' +description: 'HmacKeyGenParams represents the object that should be passed as the algorithm parameter into the generateKey operation, when generating an HMAC key.' +weight: 12 +--- + +# HmacKeyGenParams + +The `HmacKeyGenParams` object represents the object that should be passed as the algorithm parameter into the [generateKey](https://grafana.com/docs/k6//javascript-api/crypto/subtlecrypto/generatekey) operation when generating an HMAC key. + +## Properties + +| Property | Type | Description | +| :---------------- | :------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| name | `string` | This should be set to `HMAC`. | +| hash | `string` | The name of the digest function to use. Possible values are `SHA-1`, `SHA-256`, `SHA-384` and `SHA-512`. | +| length (optional) | `number` | The length of the key in bits. If this is omitted, the length of the key is equal to the block size of the hash function you have chosen. We recommend to leave this parameter empty, unless you have a good reason to use something different. | + +## Example + +{{< code >}} + +```javascript +export default async function () { + const key = await crypto.subtle.generateKey( + { + name: 'HMAC', + hash: { name: 'SHA-512' }, + length: 256, + }, + true, + ['sign', 'verify'] + ); +} +``` + +{{< /code >}} diff --git a/docs/sources/k6/v1.0.x/javascript-api/crypto/jsonwebkey.md b/docs/sources/k6/v1.0.x/javascript-api/crypto/jsonwebkey.md new file mode 100644 index 0000000000..e4b8732500 --- /dev/null +++ b/docs/sources/k6/v1.0.x/javascript-api/crypto/jsonwebkey.md @@ -0,0 +1,57 @@ +--- +title: 'JsonWebKey' +description: 'JsonWebKey represents object/dictionary generated by exporting a CryptoKey or used as an input parameter for key import.' +weight: 13 +--- + +# JsonWebKey + +The `JsonWebKey` object represents object/dictionary generated by exporting a [`CryptoKey`](https://grafana.com/docs/k6//javascript-api/crypto/cryptokey) or used as an input parameter for key import. + +The properties of the `JsonWebKey` could vary depending on the algorithm and key type. See specification [JsonWebKey](https://www.w3.org/TR/WebCryptoAPI/#JsonWebKey-dictionary) for details. + +## Properties + +| Property | Type | Description | +| :------- | :------------- | :---------------------- | +| kty | `string` | The key type. | +| k | `string` | The key value. | +| alg | `string` | The algorithm. | +| ext | `bool` | The key is extractable. | +| key_ops | `string` array | The key operations. | +| crv | `string` | The curve name. | +| x | `string` | The x coordinate. | +| y | `string` | The y coordinate. | +| d | `string` | The private key. | + +## Example + +{{< code >}} + +```javascript +export default async function () { + const jwk = { + alg: 'HS256', + ext: true, + k: 'H6gLp3lw7w27NrPUn00WpcKU-IJojJdNzhL_8F6se2k', + key_ops: ['sign', 'verify'], + kty: 'oct', + }; + + const importedKey = await crypto.subtle.importKey( + 'jwk', + jwk, + { name: 'HMAC', hash: { name: 'SHA-256' } }, + true, + ['sign', 'verify'] + ); + + const exportedAgain = await crypto.subtle.exportKey('jwk', importedKey); + + console.log('exported again: ' + JSON.stringify(exportedAgain)); + // should print + // INFO[0000] exported again: {"k":"H6gLp3lw7w27NrPUn00WpcKU-IJojJdNzhL_8F6se2k","kty":"oct","ext":true,"key_ops":["sign","verify"],"alg":"HS256"} source=console +} +``` + +{{< /code >}} diff --git a/docs/sources/k6/v1.0.x/javascript-api/crypto/randomuuid.md b/docs/sources/k6/v1.0.x/javascript-api/crypto/randomuuid.md new file mode 100644 index 0000000000..3b039cb41e --- /dev/null +++ b/docs/sources/k6/v1.0.x/javascript-api/crypto/randomuuid.md @@ -0,0 +1,33 @@ +--- +title: 'randomUUID' +description: 'randomUUID produces a 36-characters long string containing a cryptographically random UUID v4.' +weight: 02 +--- + +# randomUUID + +The `randomUUID` method produces a 36-characters long string that contains a cryptographically random UUID v4. + +## Usage + +``` +randomUUID() +``` + +## Return Value + +A string containing a 36-character cryptographically random UUID v4. + +## Example + +{{< code >}} + +```javascript +export default function () { + const myUUID = crypto.randomUUID(); + + console.log(myUUID); +} +``` + +{{< /code >}} diff --git a/docs/sources/k6/v1.0.x/javascript-api/crypto/rsahashedimportparams.md b/docs/sources/k6/v1.0.x/javascript-api/crypto/rsahashedimportparams.md new file mode 100644 index 0000000000..c856edd8d1 --- /dev/null +++ b/docs/sources/k6/v1.0.x/javascript-api/crypto/rsahashedimportparams.md @@ -0,0 +1,16 @@ +--- +title: 'RsaHashedImportParams' +description: 'RsaHashedImportParams represents the object that should be passed as the algorithm parameter into the importKey operation, when using the RSA algorithm.' +weight: 12 +--- + +# RsaHashedImportParams + +The `RsaHashedImportParams` represents the object that should be passed as the algorithm parameter into [`importKey`](https://grafana.com/docs/k6//javascript-api/crypto/subtlecrypto/importkey/) when using the RSA algorithm. + +## Properties + +| Property | Type | Description | +| :------- | :------- | :------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- | +| name | `string` | This should be set to `RSASSA-PKCS1-v1_5`, `RSA-PSS` or `RSA-OAEP`. | +| hash | `string` | `object` | The name or an object with a `name` property of the digest function to use. Possible values are `SHA-1`, `SHA-256`, `SHA-384` and `SHA-512`. | diff --git a/docs/sources/k6/v1.0.x/javascript-api/crypto/rsahashedkeygenparams.md b/docs/sources/k6/v1.0.x/javascript-api/crypto/rsahashedkeygenparams.md new file mode 100644 index 0000000000..0bce0f915a --- /dev/null +++ b/docs/sources/k6/v1.0.x/javascript-api/crypto/rsahashedkeygenparams.md @@ -0,0 +1,39 @@ +--- +title: 'RSAHashedKeyGenParams' +description: 'RSAHashedKeyGenParams represents the object that should be passed as the algorithm parameter into the generateKey operation, when generating an RSA key pair.' +weight: 12 +--- + +# RSAHashedKeyGenParams + +The `RSAHashedKeyGenParams` object represents the object that should be passed as the algorithm parameter into the [generateKey](https://grafana.com/docs/k6//javascript-api/crypto/subtlecrypto/generatekey) operation when generating an RSA key pair. + +## Properties + +| Property | Type | Description | +| :------------- | :----------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | +| name | `string` | This should be set to `RSASSA-PKCS1-v1_5`, `RSA-PSS` or `RSA-OAEP`. | +| modulusLength | `number` | The length in bits of the RSA modulus. This should be at least 2048. Some organizations are now recommending that it should be 4096. | +| publicExponent | `Uint8Array` | The public exponent. Unless you have a good reason to use something else, specify `65537` here, which represented as a `Uint8Array` is `new Uint8Array([1, 0, 1])` | +| hash | `string` | `object` | The name or an object with a `name` property of the digest function to use. Possible values are `SHA-1`, `SHA-256`, `SHA-384` and `SHA-512`. | + +## Example + +{{< code >}} + +```javascript +export default async function () { + const keyPair = await crypto.subtle.generateKey( + { + name: 'RSA-PSS', + modulusLength: 2048, + publicExponent: new Uint8Array([1, 0, 1]), + hash: { name: 'SHA-256' }, + }, + true, + ['sign', 'verify'] + ); +} +``` + +{{< /code >}} diff --git a/docs/sources/k6/v1.0.x/javascript-api/crypto/rsaoaepparams.md b/docs/sources/k6/v1.0.x/javascript-api/crypto/rsaoaepparams.md new file mode 100644 index 0000000000..3426a1fbce --- /dev/null +++ b/docs/sources/k6/v1.0.x/javascript-api/crypto/rsaoaepparams.md @@ -0,0 +1,19 @@ +--- +title: 'RsaOaepParams' +description: 'RsaOaepParams represents the object that should be passed as the algorithm parameter into the encrypt and decrypt operation when using the RSA-OAEP algorithm.' +weight: 06 +--- + +# RsaOaepParams + +The `RsaOaepParams` object represents the object that should be passed as the algorithm parameter into the [encrypt](https://grafana.com/docs/k6//javascript-api/crypto/subtlecrypto/encrypt) and [decrypt](https://grafana.com/docs/k6//javascript-api/crypto/subtlecrypto/decrypt) operation when using the RSA-OAEP algorithm. + +For more details, head to the [MDN Web Crypto API documentation on RSA-OAEP](https://developer.mozilla.org/en-US/docs/Web/API/RsaOaepParams). + +## Properties + +| Property | Type | Description | +| :--------------- | :----------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| name | `string` | Should be set to `RSA-OAEP`. | +| label (optional) | `ArrayBuffer`, `TypedArray`, or `DataView` | It's an array of bytes that does not itself need to be encrypted but which should be bound to the ciphertext. A digest of the label is part of the input to the encryption operation. Unless your application calls for a label, you can just omit this argument, and it will not affect the security of the encryption operation. | +| | diff --git a/docs/sources/k6/v1.0.x/javascript-api/crypto/rsapssparams.md b/docs/sources/k6/v1.0.x/javascript-api/crypto/rsapssparams.md new file mode 100644 index 0000000000..132fd59f4a --- /dev/null +++ b/docs/sources/k6/v1.0.x/javascript-api/crypto/rsapssparams.md @@ -0,0 +1,22 @@ +--- +title: 'RsaPssParams' +description: 'RsaPssParams is a parameter used for sign or verify operations.' +weight: 11 +--- + +# RsaPssParams + +The `RsaPssParams` represents the object that should be passed as the algorithm parameter into [`sign`](https://grafana.com/docs/k6//javascript-api/crypto/subtlecrypto/sign/) or [`verify`](https://grafana.com/docs/k6//javascript-api/crypto/subtlecrypto/verify/) when using the RSA-PSS algorithm. + +## Properties + +| Property | Type | Description | +| :--------- | :------- | :-------------------------------------------------------------------------- | +| name | `string` | An algorithm name. Should be `RSA-PSS`. | +| saltLength | `number` | A long integer representing the length of the random salt to use, in bytes. | + +{{< admonition type="caution" >}} + +Since under the hood we use Golang's SDK the salt length 0 is not supported. In that case the maximum possible salt length will be used. + +{{< /admonition >}} diff --git a/docs/sources/k6/v1.0.x/javascript-api/crypto/subtlecrypto/_index.md b/docs/sources/k6/v1.0.x/javascript-api/crypto/subtlecrypto/_index.md new file mode 100644 index 0000000000..17442c750e --- /dev/null +++ b/docs/sources/k6/v1.0.x/javascript-api/crypto/subtlecrypto/_index.md @@ -0,0 +1,92 @@ +--- +title: 'SubtleCrypto' +description: 'SubtleCrypto offers low-level cryptographic functions.' +weight: 03 +--- + +# SubtleCrypto + +The `SubtleCrypto` interface provides a set of low-level cryptographic primitives such as encryption, decryption, digital signature generation and verification, and key generation and management. It is useful for using secure and efficient cryptographic operations within k6 scripts. + +## Methods + +| Method | Description | +| :----------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------- | +| [encrypt](https://grafana.com/docs/k6//javascript-api/crypto/subtlecrypto/encrypt) | Encrypts the given plaintext data using the specified algorithm and key. | +| [decrypt](https://grafana.com/docs/k6//javascript-api/crypto/subtlecrypto/decrypt) | Decrypts the given ciphertext data using the specified algorithm and key. | +| [sign](https://grafana.com/docs/k6//javascript-api/crypto/subtlecrypto/sign) | Signs the given data using the specified algorithm and key. | +| [verify](https://grafana.com/docs/k6//javascript-api/crypto/subtlecrypto/verify) | Verifies the signature of the given data using the specified algorithm and key. | +| [digest](https://grafana.com/docs/k6//javascript-api/crypto/subtlecrypto/digest) | Computes the digest (hash) of the given data using the specified algorithm. | +| [generateKey](https://grafana.com/docs/k6//javascript-api/crypto/subtlecrypto/generatekey) | Generates a new cryptographic key for use with the specified algorithm. | +| [importKey](https://grafana.com/docs/k6//javascript-api/crypto/subtlecrypto/importkey) | Imports a raw key material into the Web Crypto API, generating a new key object to use with the specified algorithm. | +| [exportKey](https://grafana.com/docs/k6//javascript-api/crypto/subtlecrypto/exportkey) | Exports the raw key material of the given key object. | +| [deriveBits](https://grafana.com/docs/k6//javascript-api/crypto/subtlecrypto/derivebits) | Derives bits using provided input. | + +## Example + +{{< code >}} + +```javascript +export default async function () { + const plaintext = stringToArrayBuffer('Hello, World!'); + + /** + * Generate a symmetric key using the AES-CBC algorithm. + */ + const key = await crypto.subtle.generateKey( + { + name: 'AES-CBC', + length: 256, + }, + true, + ['encrypt', 'decrypt'] + ); + + /** + * Encrypt the plaintext using the AES-CBC key with + * have generated. + */ + const iv = crypto.getRandomValues(new Uint8Array(16)); + const ciphertext = await crypto.subtle.encrypt( + { + name: 'AES-CBC', + iv: iv, + }, + key, + plaintext + ); + + /** + * Decrypt the ciphertext using the same key to verify + * that the resulting plaintext is the same as the original. + */ + const deciphered = await crypto.subtle.decrypt( + { + name: 'AES-CBC', + iv: iv, + }, + key, + ciphertext + ); + + console.log( + 'deciphered text == original plaintext: ', + arrayBufferToHex(deciphered) === arrayBufferToHex(plaintext) + ); +} + +function arrayBufferToHex(buffer) { + return [...new Uint8Array(buffer)].map((x) => x.toString(16).padStart(2, '0')).join(''); +} + +function stringToArrayBuffer(str) { + const buf = new ArrayBuffer(str.length * 2); // 2 bytes for each char + const bufView = new Uint16Array(buf); + for (let i = 0, strLen = str.length; i < strLen; i++) { + bufView[i] = str.charCodeAt(i); + } + return buf; +} +``` + +{{< /code >}} diff --git a/docs/sources/k6/v1.0.x/javascript-api/crypto/subtlecrypto/decrypt.md b/docs/sources/k6/v1.0.x/javascript-api/crypto/subtlecrypto/decrypt.md new file mode 100644 index 0000000000..26badc6561 --- /dev/null +++ b/docs/sources/k6/v1.0.x/javascript-api/crypto/subtlecrypto/decrypt.md @@ -0,0 +1,107 @@ +--- +title: 'decrypt' +description: 'decrypt decrypts some encrypted data' +weight: 01 +--- + +# decrypt + +The `decrypt()` method decrypts some encrypted data. + +## Usage + +``` +decrypt(algorithm, key, data) +``` + +## Parameters + +| Name | Type | Description | +| :---------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `algorithm` | [AesCbcParams](https://grafana.com/docs/k6//javascript-api/crypto/aescbcparams), [AesCtrParams](https://grafana.com/docs/k6//javascript-api/crypto/aesctrparams), or [AesGcmParams](https://grafana.com/docs/k6//javascript-api/crypto/aesgcmparams) object | Defines the algorithm to use and any extra-parameters. The values given for the extra parameters must match those used in the corresponding [encrypt] call. | +| `key` | [CryptoKey](https://grafana.com/docs/k6//javascript-api/crypto/cryptokey) | The [key](https://grafana.com/docs/k6//javascript-api/crypto/cryptokey) to use for decryption. | +| `data` | `ArrayBuffer`, `TypedArray`, or `DataView` | The encrypted data to be decrypted (also known as _ciphertext_). | + +### Supported algorithms + +{{< docs/shared source="k6" lookup="crypto/supported-encrypt-decrypt.md" version="" >}} + +## Return Value + +A `Promise` that resolves to a new `ArrayBuffer` containing the decrypted data. + +## Throws + +| Type | Description | +| :------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `InvalidAccessError` | Raised when the requested operation is not valid with the provided key. For instance when an invalid encryption algorithm is used, or a key not matching the selected algorithm is provided. | +| `OperationError` | Raised when the operation failed for an operation-specific reason. For instance, if the algorithm size is invalid, or errors occurred during the process of decrypting the ciphertext. | + +## Example + +{{< code >}} + +```javascript +export default async function () { + const plaintext = stringToArrayBuffer('Hello, World!'); + + /** + * Generate a symmetric key using the AES-CBC algorithm. + */ + const key = await crypto.subtle.generateKey( + { + name: 'AES-CBC', + length: 256, + }, + true, + ['encrypt', 'decrypt'] + ); + + /** + * Encrypt the plaintext using the AES-CBC key with + * have generated. + */ + const iv = crypto.getRandomValues(new Uint8Array(16)); + const ciphertext = await crypto.subtle.encrypt( + { + name: 'AES-CBC', + iv: iv, + }, + key, + plaintext + ); + + /** + * Decrypt the ciphertext using the same key to verify + * that the resulting plaintext is the same as the original. + */ + const deciphered = await crypto.subtle.decrypt( + { + name: 'AES-CBC', + iv: iv, + }, + key, + ciphertext + ); + + console.log( + 'deciphered text == original plaintext: ', + arrayBufferToHex(deciphered) === arrayBufferToHex(plaintext) + ); +} + +function arrayBufferToHex(buffer) { + return [...new Uint8Array(buffer)].map((x) => x.toString(16).padStart(2, '0')).join(''); +} + +function stringToArrayBuffer(str) { + const buf = new ArrayBuffer(str.length * 2); // 2 bytes for each char + const bufView = new Uint16Array(buf); + for (let i = 0, strLen = str.length; i < strLen; i++) { + bufView[i] = str.charCodeAt(i); + } + return buf; +} +``` + +{{< /code >}} diff --git a/docs/sources/k6/v1.0.x/javascript-api/crypto/subtlecrypto/derivebits.md b/docs/sources/k6/v1.0.x/javascript-api/crypto/subtlecrypto/derivebits.md new file mode 100644 index 0000000000..266dd68cb9 --- /dev/null +++ b/docs/sources/k6/v1.0.x/javascript-api/crypto/subtlecrypto/derivebits.md @@ -0,0 +1,88 @@ +--- +title: 'deriveBits' +description: 'deriveBits derives an array of bits' +weight: 02 +--- + +# deriveBits + +It takes as its arguments the base key, the derivation algorithm to use, and the length of the bits to derive. It returns a Promise which will be fulfilled with an `ArrayBuffer` containing the derived bits. This array of bits can be used as a key for encryption or decryption as a shared secret. + +## Usage + +``` +deriveBits(algorithm, baseKey, length) +``` + +## Parameters + +| Name | Type | Description | +| :---------- | :--------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------- | +| `algorithm` | [EcdhKeyDeriveParams](https://grafana.com/docs/k6//javascript-api/crypto/ecdhkeyderiveparams/) | An object defining a derivation algorithm to use. | +| `baseKey` | [CryptoKey](https://grafana.com/docs/k6//javascript-api/crypto/cryptokey) | Represent an input to derivation algorithm. Currently it could be only a private ECDH key. | +| `length` | `number` | Optional. A length of the bits to derive. Currently, only multiplies of 8 are supported. | + +### Supported algorithms + +| ECDH | HKDF | PBKDF2 | +| :------------------------------------------------------------------------------------------------------------ | :--- | :----- | +| ✅ [EcdhKeyDeriveParams](https://grafana.com/docs/k6//javascript-api/crypto/ecdhkeyderiveparams/) | ❌ | ❌ | + +## Return Value + +A `Promise` that resolves to a new `ArrayBuffer` containing the derived bits. + +## Example + +{{< code >}} + +```javascript +export default async function () { + // Generate a key pair for Alice + const aliceKeyPair = await crypto.subtle.generateKey( + { + name: 'ECDH', + namedCurve: 'P-256', + }, + true, + ['deriveKey', 'deriveBits'] + ); + + // Generate a key pair for Bob + const bobKeyPair = await crypto.subtle.generateKey( + { + name: 'ECDH', + namedCurve: 'P-256', + }, + true, + ['deriveKey', 'deriveBits'] + ); + + // Derive shared secret for Alice + const aliceSharedSecret = await deriveSharedSecret(aliceKeyPair.privateKey, bobKeyPair.publicKey); + + // Derive shared secret for Bob + const bobSharedSecret = await deriveSharedSecret(bobKeyPair.privateKey, aliceKeyPair.publicKey); + + console.log('alice shared secret: ' + printArrayBuffer(aliceSharedSecret)); + console.log('bob shared secret: ' + printArrayBuffer(bobSharedSecret)); +} + +async function deriveSharedSecret(privateKey, publicKey) { + return crypto.subtle.deriveBits( + { + name: 'ECDH', + public: publicKey, + }, + privateKey, + 256 + ); +} + +const printArrayBuffer = (buffer) => { + const view = new Uint8Array(buffer); + return Array.from(view); +}; +``` + +{{< /code >}} diff --git a/docs/sources/k6/v1.0.x/javascript-api/crypto/subtlecrypto/digest.md b/docs/sources/k6/v1.0.x/javascript-api/crypto/subtlecrypto/digest.md new file mode 100644 index 0000000000..a4db23d0d1 --- /dev/null +++ b/docs/sources/k6/v1.0.x/javascript-api/crypto/subtlecrypto/digest.md @@ -0,0 +1,54 @@ +--- +title: 'digest' +description: 'digest decrypts some encrypted data' +weight: 02 +--- + +# digest + +The `digest()` method generates a cryptographically secure [digest](https://developer.mozilla.org/en-US/docs/Glossary/Digest) of the given data. A digest is a short fixed-length value derived from some input data. The `digest()` method is commonly used to compute a checksum of data or to verify the integrity of data. + +## Usage + +``` +digest(algorithm, data) +``` + +## Parameters + +| Name | Type | Description | +| :---------- | :-------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `algorithm` | a `string` or object with a single `name` string property | Names the hash function to use. Supported values are `"SHA-1"`, `"SHA-256"`, `"SHA-384"` and `"SHA-512"`. Note that the SHA-1 hash function is not considered safe for cryptographic use. | +| `data` | `ArrayBuffer`, `TypedArray`, or `DataView` | The data to be digested. | + +### Supported algorithms + +| SHA-1 | SHA-256 | SHA-384 | SHA-512 | +| :---- | :------ | :------ | :------ | +| ✅ | ✅ | ✅ | ✅ | + +## Return Value + +A `Promise` that resolves to a new `ArrayBuffer` containing the digest. + +## Example + +{{< code >}} + +```javascript +export default async function () { + const digest = await crypto.subtle.digest('SHA-256', stringToArrayBuffer('Hello, world!')); + + console.log(arrayBufferToHex(digest)); +} + +function arrayBufferToHex(buffer) { + return [...new Uint8Array(buffer)].map((x) => x.toString(16).padStart(2, '0')).join(''); +} + +function stringToArrayBuffer(s) { + return Uint8Array.from(new String(s), (x) => x.charCodeAt(0)); +} +``` + +{{< /code >}} diff --git a/docs/sources/k6/v1.0.x/javascript-api/crypto/subtlecrypto/encrypt.md b/docs/sources/k6/v1.0.x/javascript-api/crypto/subtlecrypto/encrypt.md new file mode 100644 index 0000000000..5473b8bb6b --- /dev/null +++ b/docs/sources/k6/v1.0.x/javascript-api/crypto/subtlecrypto/encrypt.md @@ -0,0 +1,107 @@ +--- +title: 'encrypt' +description: 'encrypt decrypts some encrypted data' +weight: 03 +--- + +# encrypt + +The `encrypt()` method encrypts some data. + +## Usage + +``` +encrypt(algorithm, key, data) +``` + +## Parameters + +| Name | Type | Description | +| :---------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------- | +| `algorithm` | [AesCbcParams](https://grafana.com/docs/k6//javascript-api/crypto/aescbcparams), [AesCtrParams](https://grafana.com/docs/k6//javascript-api/crypto/aesctrparams), or [AesGcmParams](https://grafana.com/docs/k6//javascript-api/crypto/aesgcmparams) object | Defines the algorithm to use and any extra-parameters. | +| `key` | [CryptoKey](https://grafana.com/docs/k6//javascript-api/crypto/cryptokey) | The [key](https://grafana.com/docs/k6//javascript-api/crypto/cryptokey) to use for encryption. | +| `data` | `ArrayBuffer`, `TypedArray`, or `DataView` | The data to be encrypted (also known as "plaintext"). | + +### Supported algorithms + +{{< docs/shared source="k6" lookup="crypto/supported-encrypt-decrypt.md" version="" >}} + +## Return Value + +A `Promise` that resolves to a new `ArrayBuffer` containing the encrypted data. + +## Throws + +| Type | Description | +| :------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `InvalidAccessError` | Raised when the requested operation is not valid with the provided key. For instance when an invalid encryption algorithm is used, or a key not matching the selected algorithm is provided. | +| `OperationError` | Raised when the operation failed for an operation-specific reason. For instance, if the algorithm size is invalid, or errors occurred during the process of decrypting the ciphertext. | + +## Example + +{{< code >}} + +```javascript +export default async function () { + const plaintext = stringToArrayBuffer('Hello, World!'); + + /** + * Generate a symmetric key using the AES-CBC algorithm. + */ + const key = await crypto.subtle.generateKey( + { + name: 'AES-CBC', + length: 256, + }, + true, + ['encrypt', 'decrypt'] + ); + + /** + * Encrypt the plaintext using the AES-CBC key with + * have generated. + */ + const iv = crypto.getRandomValues(new Uint8Array(16)); + const ciphertext = await crypto.subtle.encrypt( + { + name: 'AES-CBC', + iv: iv, + }, + key, + plaintext + ); + + /** + * Decrypt the ciphertext using the same key to verify + * that the resulting plaintext is the same as the original. + */ + const deciphered = await crypto.subtle.decrypt( + { + name: 'AES-CBC', + iv: iv, + }, + key, + ciphertext + ); + + console.log( + 'deciphered text == original plaintext: ', + arrayBufferToHex(deciphered) === arrayBufferToHex(plaintext) + ); +} + +function arrayBufferToHex(buffer) { + return [...new Uint8Array(buffer)].map((x) => x.toString(16).padStart(2, '0')).join(''); +} + +function stringToArrayBuffer(str) { + const buf = new ArrayBuffer(str.length * 2); // 2 bytes for each char + const bufView = new Uint16Array(buf); + for (let i = 0, strLen = str.length; i < strLen; i++) { + bufView[i] = str.charCodeAt(i); + } + return buf; +} +``` + +{{< /code >}} diff --git a/docs/sources/k6/v1.0.x/javascript-api/crypto/subtlecrypto/exportkey.md b/docs/sources/k6/v1.0.x/javascript-api/crypto/subtlecrypto/exportkey.md new file mode 100644 index 0000000000..1ea6dc38d0 --- /dev/null +++ b/docs/sources/k6/v1.0.x/javascript-api/crypto/subtlecrypto/exportkey.md @@ -0,0 +1,81 @@ +--- +title: 'exportKey' +description: 'exportKey exports a key in an external, portable format.' +weight: 04 +--- + +# exportKey + +The `exportKey()` method takes a [CryptoKey](https://grafana.com/docs/k6//javascript-api/crypto/cryptokey) object as input and exports it in an external, portable format. + +Note that for a key to be exportable, it must have been created with the `extractable` flag set to `true`. + +## Usage + +``` +exportKey(format, key) +``` + +## Parameters + +| Name | Type | Description | +| :------- | :------------------------------------------------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `format` | `string` | Defines the data format in which the key should be exported. Depending on the algorithm and key type, the data format could vary. Currently supported formats are `raw`, `jwk`, `spki`, and `pkcs8`. | +| `key` | [CryptoKey](https://grafana.com/docs/k6//javascript-api/crypto/cryptokey) | The [key](https://grafana.com/docs/k6//javascript-api/crypto/cryptokey) to export. | + +### Supported algorithms + +{{< docs/shared source="k6" lookup="crypto/supported-key-methods.md" version="" >}} + +### Supported formats + +{{< docs/shared source="k6" lookup="crypto/supported-key-methods-formats.md" version="" >}} + +## Return Value + +A `Promise` that resolves to a new `ArrayBuffer` or an [JsonWebKey](https://grafana.com/docs/k6//javascript-api/crypto/jsonwebkey) object/dictionary containing the key. + +## Throws + +| Type | Description | +| :------------------- | :-------------------------------------------------- | +| `InvalidAccessError` | Raised when trying to export a non-extractable key. | +| `NotSupportedError` | Raised when trying to export in an unknown format. | +| `TypeError` | Raised when trying to use an invalid format. | + +## Example + +{{< code >}} + +```javascript +export default async function () { + /** + * Generate a symmetric key using the AES-CBC algorithm. + */ + const generatedKey = await crypto.subtle.generateKey( + { + name: 'AES-CBC', + length: '256', + }, + true, + ['encrypt', 'decrypt'] + ); + + /** + * Export the key in raw format. + */ + const exportedKey = await crypto.subtle.exportKey('raw', generatedKey); + + /** + * Reimport the key in raw format to verify its integrity. + */ + const importedKey = await crypto.subtle.importKey('raw', exportedKey, 'AES-CBC', true, [ + 'encrypt', + 'decrypt', + ]); + + console.log(JSON.stringify(importedKey)); +} +``` + +{{< /code >}} diff --git a/docs/sources/k6/v1.0.x/javascript-api/crypto/subtlecrypto/generatekey.md b/docs/sources/k6/v1.0.x/javascript-api/crypto/subtlecrypto/generatekey.md new file mode 100644 index 0000000000..3800933829 --- /dev/null +++ b/docs/sources/k6/v1.0.x/javascript-api/crypto/subtlecrypto/generatekey.md @@ -0,0 +1,65 @@ +--- +title: 'generateKey' +description: 'generateKey generates a new key.' +weight: 05 +--- + +# generateKey + +The `generateKey()` generates a new cryptographic key and returns it as a [CryptoKey](https://grafana.com/docs/k6//javascript-api/crypto/cryptokey) object or a [CryptoKeyPair](https://grafana.com/docs/k6//javascript-api/crypto/cryptokeypair) object that can be used with the Web Crypto API. + +## Usage + +``` +generateKey(algorithm, extractable, keyUsages) +``` + +## Parameters + +| Name | Type | Description | +| :------------ | :--------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `algorithm` | a `string` or algorithm object with a single `name` string | The type of key to generate. It can be either a string with any of the currently supported algorithms as a value or any of the generation key parameter objects. | +| `extractable` | `boolean` | Whether the key can be exported using [exportKey](https://grafana.com/docs/k6//javascript-api/crypto/subtlecrypto/exportkey). | +| `keyUsages` | `Array` | An array of strings describing what operations can be performed with the key. Key usages could vary depending on the algorithm. | + +### Supported algorithms + +{{< docs/shared source="k6" lookup="crypto/supported-key-methods.md" version="" >}} + +## Return Value + +A `Promise` that resolves with the generated key as a [CryptoKey](https://grafana.com/docs/k6//javascript-api/crypto/cryptokey) object or a [CryptoKeyPair](https://grafana.com/docs/k6//javascript-api/crypto/cryptokeypair) object. + +### Algorithm specific input + +| | HMAC | AES | ECDH | ECDSA | RSA-OAEP | RSASSA-PKCS1-v1_5 | RSA-PSS | +| :--------------------- | :---------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | +| Parameters type to use | [`HmacKeyGenParams`](https://grafana.com/docs/k6//javascript-api/crypto/hmackeygenparams) | [`AesKeyGenParams`](https://grafana.com/docs/k6//javascript-api/crypto/aeskeygenparams) | [`EcKeyGenParams`](https://grafana.com/docs/k6//javascript-api/crypto/eckeygenparams) | [`EcKeyGenParams`](https://grafana.com/docs/k6//javascript-api/crypto/eckeygenparams) | [`RSAHashedKeyGenParams`](https://grafana.com/docs/k6//javascript-api/crypto/rsahashedkeygenparams) | [`RSAHashedKeyGenParams`](https://grafana.com/docs/k6//javascript-api/crypto/rsahashedkeygenparams) | [`RSAHashedKeyGenParams`](https://grafana.com/docs/k6//javascript-api/crypto/rsahashedkeygenparams) | +| Possible key usages | `sign`, `verify` | `encrypt`, `decrypt` | `deriveKey`, `deriveBits` | `sign`, `verify` | `encrypt`, `decrypt` | `sign`, `verify` | `sign`, `verify` | + +## Throws + +| Type | Description | +| :------------ | :-------------------------------------------------------------------------------------------- | +| `SyntaxError` | Raised when the `keyUsages` parameter is empty, but the key is of type `secret` or `private`. | + +## Example + +{{< code >}} + +```javascript +export default async function () { + const key = await crypto.subtle.generateKey( + { + name: 'AES-CBC', + length: 256, + }, + true, + ['encrypt', 'decrypt'] + ); + + console.log(JSON.stringify(key)); +} +``` + +{{< /code >}} diff --git a/docs/sources/k6/v1.0.x/javascript-api/crypto/subtlecrypto/importkey.md b/docs/sources/k6/v1.0.x/javascript-api/crypto/subtlecrypto/importkey.md new file mode 100644 index 0000000000..4f73d192fe --- /dev/null +++ b/docs/sources/k6/v1.0.x/javascript-api/crypto/subtlecrypto/importkey.md @@ -0,0 +1,226 @@ +--- +title: 'importKey' +description: 'importKey imports a key from an external, portable format and gives you a CryptoKey object.' +weight: 06 +--- + +# importKey + +The `importKey()` imports a key from an external, portable format, and gives you a [CryptoKey](https://grafana.com/docs/k6//javascript-api/crypto/cryptokey) object that can be used with the Web Crypto API. + +## Usage + +``` +importKey(format, keyData, algorithm, extractable, keyUsages) +``` + +## Parameters + +| Name | Type | Description | +| :------------ | :--------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `format` | `string` | Defines the data format of the key to import. Depending on the algorithm and key type, the data format could vary. Currently supported formats are `raw`, `jwk`, `spki`, and `pkcs8`. | +| `keyData` | `ArrayBuffer`, `TypedArray`, `DataView` or [JsonWebKey](https://grafana.com/docs/k6//javascript-api/crypto/jsonwebkey) | the data to import the key from. | +| `algorithm` | a `string` or object with a single `name` string property | The algorithm to use to import the key. | +| `extractable` | `boolean` | Indicates whether it will be possible to export the key using [exportKey](https://grafana.com/docs/k6//javascript-api/crypto/subtlecrypto/exportkey). | +| `keyUsages` | `Array` | An array of strings describing what operations can be performed with the key. Currently supported usages include `encrypt`, `decrypt`, `sign`, and `verify`. | + +### Supported algorithms + +{{< docs/shared source="k6" lookup="crypto/supported-key-methods.md" version="" >}} + +### Supported formats + +{{< docs/shared source="k6" lookup="crypto/supported-key-methods-formats.md" version="" >}} + +## Return Value + +A `Promise` that resolves with the imported key as a [CryptoKey](https://grafana.com/docs/k6//javascript-api/crypto/cryptokey) object. + +## Throws + +| Type | Description | +| :------------ | :---------------------------------------------------------------------------------------------- | +| `SyntaxError` | Raised when the `keyUsages` parameter is empty but the key is of type `secret` or `private`. | +| `TypeError` | Raised when trying to use an invalid format, or if the `keyData` is not suited for that format. | + +## Examples + +### Round-trip key export/import + +{{< code >}} + +```javascript +export default async function () { + /** + * Generate a symmetric key using the AES-CBC algorithm. + */ + const generatedKey = await crypto.subtle.generateKey( + { + name: 'AES-CBC', + length: '256', + }, + true, + ['encrypt', 'decrypt'] + ); + + /** + * Export the key in raw format. + */ + const exportedKey = await crypto.subtle.exportKey('raw', generatedKey); + + /** + * Reimport the key in raw format to verify its integrity. + */ + const importedKey = await crypto.subtle.importKey('raw', exportedKey, 'AES-CBC', true, [ + 'encrypt', + 'decrypt', + ]); + + console.log(JSON.stringify(importedKey)); +} +``` + +{{< /code >}} + +### Import a static raw key and decrypt transmitted data + +This example demonstrates how to import a static `raw` key and decrypt some transmitted data in `base64`. The transmitted data in this example represents an initialization vector and encoded data, and in a real-world scenario, it can be a response body or other data received from a request. + +{{< code >}} + +```javascript +import { b64decode } from 'k6/encoding'; + +export default async function () { + const transmittedData = base64Decode( + 'whzEN310mrlWIH/icf0dMquRZ2ENyfOzkvPuu92WR/9F8dbeFM8EGUVNIhaS' + ); + + // keyData is the key used to decrypt the data, which is usually stored in a secure location + // for this example, we are using a static key + const keyData = new Uint8Array([ + 109, 151, 76, 33, 232, 253, 176, 90, 94, 40, 146, 227, 139, 208, 245, 139, 69, 215, 55, 197, 43, + 122, 160, 178, 228, 104, 4, 115, 138, 159, 119, 49, + ]); + + try { + const result = await decrypt(keyData, transmittedData); + + // should output decrypted message + // INFO[0000] result: 'my secret message' source=console + console.log("result: '" + result + "'"); + } catch (e) { + console.log('Error: ' + JSON.stringify(e)); + } +} + +const decrypt = async (keyData, transmittedData) => { + const initializeVectorLength = 12; + + // the first 12 bytes are the initialization vector + const iv = new Uint8Array(transmittedData.subarray(0, initializeVectorLength)); + + // the rest of the transmitted data is the encrypted data + const encryptedData = new Uint8Array(transmittedData.subarray(initializeVectorLength)); + + const importedKey = await crypto.subtle.importKey( + 'raw', + keyData, + { name: 'AES-GCM', length: '256' }, + true, + ['decrypt'] + ); + + const plain = await crypto.subtle.decrypt( + { name: 'AES-GCM', iv: iv }, + importedKey, + encryptedData + ); + + return arrayBufferToString(plain); +}; + +const arrayBufferToString = (buffer) => { + return String.fromCharCode.apply(null, new Uint8Array(buffer)); +}; + +const base64Decode = (base64String) => { + return new Uint8Array(b64decode(base64String)); +}; +``` + +{{< /code >}} + +### Import a static JWK key and decrypt transmitted data + +This example is similar to the previous one. It demonstrates how to import a static `jwk` key and decrypt some transmitted data (which contains the initialization vector and encoded data) in `base64`. + +{{< code >}} + +```javascript +import { b64decode } from 'k6/encoding'; + +export default async function () { + // transmitted data is the base64 of the initialization vector + encrypted data + // that unusually transmitted over the network + const transmittedData = base64Decode( + 'drCfxl4O+5FcrHe8Bs0CvKlw3gZpv+S5if3zn7c4BJzHJ35QDFV4sJB0pbDT' + ); + + // keyData is the key used to decrypt the data, which is usually stored in a secure location + // for this example, we are using a static key + const jwkKeyData = { + kty: 'oct', + ext: true, + key_ops: ['decrypt', 'encrypt'], + alg: 'A256GCM', + k: '9Id_8iG6FkGOWmc1S203vGVnTExtpDGxdQN7v7OV9Uc', + }; + + try { + const result = await decrypt(jwkKeyData, transmittedData); + + // should output decrypted message + // INFO[0000] result: 'my secret message' source=console + console.log("result: '" + result + "'"); + } catch (e) { + console.log('Error: ' + JSON.stringify(e)); + } +} + +const decrypt = async (keyData, transmittedData) => { + const initializeVectorLength = 12; + + // the first 12 bytes are the initialization vector + const iv = new Uint8Array(transmittedData.subarray(0, initializeVectorLength)); + + // the rest of the transmitted data is the encrypted data + const encryptedData = new Uint8Array(transmittedData.subarray(initializeVectorLength)); + + const importedKey = await crypto.subtle.importKey( + 'jwk', + keyData, + { name: 'AES-GCM', length: 256 }, + true, + ['encrypt', 'decrypt'] + ); + + const plain = await crypto.subtle.decrypt( + { name: 'AES-GCM', iv: iv }, + importedKey, + encryptedData + ); + + return arrayBufferToString(plain); +}; + +const arrayBufferToString = (buffer) => { + return String.fromCharCode.apply(null, new Uint8Array(buffer)); +}; + +const base64Decode = (base64String) => { + return new Uint8Array(b64decode(base64String)); +}; +``` + +{{< /code >}} diff --git a/docs/sources/k6/v1.0.x/javascript-api/crypto/subtlecrypto/sign.md b/docs/sources/k6/v1.0.x/javascript-api/crypto/subtlecrypto/sign.md new file mode 100644 index 0000000000..4e7f9152b7 --- /dev/null +++ b/docs/sources/k6/v1.0.x/javascript-api/crypto/subtlecrypto/sign.md @@ -0,0 +1,129 @@ +--- +title: 'sign' +description: 'sign generates a digital signature.' +weight: 07 +--- + +# sign + +The `sign()` operation generates a digital signature of the provided `data`, using the given [CryptoKey](https://grafana.com/docs/k6//javascript-api/crypto/cryptokey) object. + +## Usage + +``` +sign(algorithm, key, data) +``` + +## Parameters + +| Name | Type | Description | +| :---------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------ | +| `algorithm` | `string` or object with a single `name` string property (`{name: "RSASSA-PKCS1-v1_5"}`) or an [EcdsaParams](https://grafana.com/docs/k6//javascript-api/crypto/ecdsaparams/), [HmacKeyGenParams](https://grafana.com/docs/k6//javascript-api/crypto/hmackeygenparams/), or [RsaPssParams](https://grafana.com/docs/k6//javascript-api/crypto/rsapssparams/) object. | The signature algorithm to use. | +| `key` | [CryptoKey](https://grafana.com/docs/k6//javascript-api/crypto/cryptokey) | The key to use for signing. | +| `data` | `ArrayBuffer`, `TypedArray`, or `DataView` | The data to be signed. | + +### Supported algorithms + +{{< docs/shared source="k6" lookup="crypto/supported-sign-verify.md" version="" >}} + +## Return Value + +A `Promise` that resolves with the signature as an `ArrayBuffer`. + +## Throws + +| Type | Description | +| :------------------- | :--------------------------------------------------------------------------------------------------------------------- | +| `InvalidAccessError` | Raised when the signing key either does not support signing operation, or is incompatible with the selected algorithm. | + +## Examples + +### Signing data with HMAC key + +{{< code >}} + +```javascript +export default async function () { + const generatedKey = await crypto.subtle.generateKey( + { + name: 'HMAC', + hash: { name: 'SHA-1' }, + }, + true, + ['sign', 'verify'] + ); + + const data = string2ArrayBuffer('Hello World'); + + /** + * Signes the encoded data with the provided key using the HMAC algorithm + * the returned signature can be verified using the verify method. + */ + const signature = await crypto.subtle.sign('HMAC', generatedKey, data); + + /** + * Verifies the signature of the encoded data with the provided key using the HMAC algorithm. + */ + const verified = await crypto.subtle.verify('HMAC', generatedKey, signature, data); + + console.log('verified: ', verified); +} + +function string2ArrayBuffer(str) { + const buf = new ArrayBuffer(str.length * 2); // 2 bytes for each char + const bufView = new Uint16Array(buf); + for (let i = 0, strLen = str.length; i < strLen; i++) { + bufView[i] = str.charCodeAt(i); + } + return buf; +} +``` + +{{< /code >}} + +### Signing and verifying data with ECDSA + +{{< code >}} + +```javascript +export default async function () { + const keyPair = await crypto.subtle.generateKey( + { + name: 'ECDSA', + namedCurve: 'P-256', + }, + true, + ['sign', 'verify'] + ); + + const data = string2ArrayBuffer('Hello World'); + + const alg = { name: 'ECDSA', hash: { name: 'SHA-256' } }; + + // makes a signature of the encoded data with the provided key + const signature = await crypto.subtle.sign(alg, keyPair.privateKey, data); + + console.log('signature: ', printArrayBuffer(signature)); + + //Verifies the signature of the encoded data with the provided key + const verified = await crypto.subtle.verify(alg, keyPair.publicKey, signature, data); + + console.log('verified: ', verified); +} + +const string2ArrayBuffer = (str) => { + const buf = new ArrayBuffer(str.length * 2); // 2 bytes for each char + const bufView = new Uint16Array(buf); + for (let i = 0, strLen = str.length; i < strLen; i++) { + bufView[i] = str.charCodeAt(i); + } + return buf; +}; + +const printArrayBuffer = (buffer) => { + const view = new Uint8Array(buffer); + return Array.from(view); +}; +``` + +{{< /code >}} diff --git a/docs/sources/k6/v1.0.x/javascript-api/crypto/subtlecrypto/verify.md b/docs/sources/k6/v1.0.x/javascript-api/crypto/subtlecrypto/verify.md new file mode 100644 index 0000000000..f12a3b893e --- /dev/null +++ b/docs/sources/k6/v1.0.x/javascript-api/crypto/subtlecrypto/verify.md @@ -0,0 +1,142 @@ +--- +title: 'verify' +description: 'verify verifies a digital signature.' +weight: 08 +--- + +# verify + +The `verify()` operation verifies a digital signature. It ensures that some data was signed by a known key and that the data has not been tampered with since it was signed. + +## Usage + +``` +verify(algorithm, key, signature, data) +``` + +## Parameters + +| Name | Type | Description | +| :---------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------- | +| `algorithm` | `string` or object with a single `name` string property (`{name: "RSASSA-PKCS1-v1_5"}`) or an [EcdsaParams](https://grafana.com/docs/k6//javascript-api/crypto/ecdsaparams/), [HmacKeyGenParams](https://grafana.com/docs/k6//javascript-api/crypto/hmackeygenparams/), or [RsaPssParams](https://grafana.com/docs/k6//javascript-api/crypto/rsapssparams/) object. | The signature algorithm to use. | +| `key` | [CryptoKey](https://grafana.com/docs/k6//javascript-api/crypto/cryptokey) | The key that will be used to verify the signature. | +| `signature` | `ArrayBuffer` | The signature to verify. | +| `data` | `ArrayBuffer` | The data whose signature is to be verified. | + +### Supported algorithms + +{{< docs/shared source="k6" lookup="crypto/supported-sign-verify.md" version="" >}} + +## Return Value + +A `Promise` that resolves to a `boolean` value indicating if the signature is valid. + +## Throws + +| Type | Description | +| :------------------- | :------------------------------------------------------------------------------------------------------------------ | +| `InvalidAccessError` | Raised when the key either does not support the `verify` operation, or is incompatible with the selected algorithm. | + +## Examples + +### Verifying an HMAC signature + +{{< code >}} + +```javascript +export default async function () { + const generatedKey = await crypto.subtle.generateKey( + { + name: 'HMAC', + hash: { name: 'SHA-1' }, + }, + true, + ['sign', 'verify'] + ); + + const data = string2ArrayBuffer('Hello World'); + + /** + * Signes the encoded data with the provided key using the HMAC algorithm + * the returned signature can be verified using the verify method. + */ + const signature = await crypto.subtle.sign('HMAC', generatedKey, data); + + /** + * Verifies the signature of the encoded data with the provided key using the HMAC algorithm. + */ + const verified = await crypto.subtle.verify('HMAC', generatedKey, signature, data); + + console.log('verified: ', verified); +} + +function string2ArrayBuffer(str) { + const buf = new ArrayBuffer(str.length * 2); // 2 bytes for each char + const bufView = new Uint16Array(buf); + for (let i = 0, strLen = str.length; i < strLen; i++) { + bufView[i] = str.charCodeAt(i); + } + return buf; +} +``` + +{{< /code >}} + +### Verifying an ECDSA signature + +{{< code >}} + +```javascript +export default async function () { + const publicKey = await crypto.subtle.importKey( + 'spki', + spkiPublicKeyData, + { name: 'ECDSA', namedCurve: 'P-256' }, + true, + ['verify'] + ); + + // Verifies the signature of the encoded data with the provided key + const verified = await crypto.subtle.verify( + { + name: 'ECDSA', + hash: 'SHA-256', + }, + publicKey, + signature, + plaintText + ); + + console.log('verified: ', verified); +} + +const spkiPublicKeyData = new Uint8Array([ + 48, 89, 48, 19, 6, 7, 42, 134, 72, 206, 61, 2, 1, 6, 8, 42, 134, 72, 206, 61, 3, 1, 7, 3, 66, 0, + 4, 10, 5, 30, 56, 111, 103, 196, 166, 225, 229, 203, 238, 125, 55, 116, 91, 88, 142, 190, 114, 15, + 117, 89, 22, 40, 111, 150, 41, 105, 122, 57, 23, 17, 216, 106, 234, 201, 103, 8, 210, 58, 38, 35, + 216, 198, 237, 187, 84, 217, 164, 63, 100, 6, 105, 49, 128, 15, 53, 29, 158, 117, 235, 238, 30, +]); + +const plaintText = new Uint8Array([ + 95, 77, 186, 79, 50, 12, 12, 232, 118, 114, 90, 252, 229, 251, 210, 91, 248, 62, 90, 113, 37, 160, + 140, 175, 231, 60, 62, 186, 196, 33, 119, 157, 249, 213, 93, 24, 12, 58, 233, 148, 38, 69, 225, + 216, 47, 238, 140, 157, 41, 75, 60, 177, 160, 138, 153, 49, 32, 27, 60, 14, 129, 252, 71, 202, + 207, 131, 21, 162, 175, 102, 50, 65, 19, 195, 182, 98, 48, 195, 70, 8, 196, 244, 89, 54, 52, 206, + 2, 178, 103, 54, 34, 119, 240, 168, 64, 202, 116, 188, 61, 26, 98, 54, 149, 44, 94, 215, 170, 248, + 168, 254, 203, 221, 250, 117, 132, 230, 151, 140, 234, 93, 42, 91, 159, 183, 241, 180, 140, 139, + 11, 229, 138, 48, 82, 2, 117, 77, 131, 118, 16, 115, 116, 121, 60, 240, 38, 170, 238, 83, 0, 114, + 125, 131, 108, 215, 30, 113, 179, 69, 221, 178, 228, 68, 70, 255, 197, 185, 1, 99, 84, 19, 137, + 13, 145, 14, 163, 128, 152, 74, 144, 25, 16, 49, 50, 63, 22, 219, 204, 157, 107, 225, 104, 184, + 72, 133, 56, 76, 160, 62, 18, 96, 10, 193, 194, 72, 2, 138, 243, 114, 108, 201, 52, 99, 136, 46, + 168, 192, 42, 171, +]); + +const signature = new Uint8Array([ + 83, 223, 63, 226, 42, 29, 106, 105, 225, 145, 197, 180, 118, 154, 109, 110, 66, 67, 47, 251, 53, + 190, 203, 65, 207, 36, 19, 57, 49, 122, 124, 118, 59, 74, 222, 134, 42, 235, 180, 229, 134, 24, + 205, 81, 171, 156, 100, 218, 127, 242, 126, 53, 27, 77, 249, 101, 157, 132, 244, 30, 67, 30, 64, + 12, +]); +``` + +{{< /code >}} diff --git a/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/_index.md b/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/_index.md index 8f06b918c9..bdf44aae32 100644 --- a/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/_index.md +++ b/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/_index.md @@ -1,13 +1,12 @@ --- title: 'webcrypto' -description: "k6 webcrypto experimental API" -weight: 06 +description: 'k6 webcrypto experimental API' weight: 06 --- # webcrypto -{{< docs/shared source="k6" lookup="experimental-module.md" version="" >}} +{{< docs/shared source="k6" lookup="webcrypto/deprecated.md" version="" >}} With this experimental module, you can use the [WebCrypto API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API) in your k6 scripts. However, note that this API is not yet fully implemented and some algorithms and features might still be missing. diff --git a/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/aescbcparams.md b/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/aescbcparams.md index eeace4d95f..5813f7a52b 100644 --- a/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/aescbcparams.md +++ b/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/aescbcparams.md @@ -6,6 +6,8 @@ weight: 04 # AesCbcParams +{{< docs/shared source="k6" lookup="webcrypto/deprecated.md" version="" >}} + The `AesCbcParams` object represents the object that should be passed as the algorithm parameter into the [encrypt](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/subtlecrypto/encrypt) and [decrypt](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/subtlecrypto/decrypt) operation when using the AES-CBC algorithm. For more details, head to the [MDN Web Crypto API documentation on AES-CBC](https://developer.mozilla.org/en-US/docs/Web/API/AesCbcParams). diff --git a/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/aesctrparams.md b/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/aesctrparams.md index c0fc531503..7fa4df35ef 100644 --- a/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/aesctrparams.md +++ b/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/aesctrparams.md @@ -6,6 +6,8 @@ weight: 05 # AesCtrParams +{{< docs/shared source="k6" lookup="webcrypto/deprecated.md" version="" >}} + The `AesCtrParams` object represents the object that should be passed as the algorithm parameter into the [encrypt](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/subtlecrypto/encrypt) and [decrypt](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/subtlecrypto/decrypt) operation when using the AES-CTR algorithm. For more details, head to the MDN Web Crypto API documentation on [AES-CTR](https://developer.mozilla.org/en-US/docs/Web/API/AesCtrParams). diff --git a/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/aesgcmparams.md b/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/aesgcmparams.md index 868b189d94..4f5b20923e 100644 --- a/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/aesgcmparams.md +++ b/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/aesgcmparams.md @@ -6,6 +6,8 @@ weight: 06 # AesGcmParams +{{< docs/shared source="k6" lookup="webcrypto/deprecated.md" version="" >}} + The `AesGcmParams` object represents the object that should be passed as the algorithm parameter into the [encrypt](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/subtlecrypto/encrypt) and [decrypt](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/subtlecrypto/decrypt) operation when using the AES-GCM algorithm. For more details, head to the [MDN Web Crypto API documentation on AES-GCM](https://developer.mozilla.org/en-US/docs/Web/API/AesGcmParams). diff --git a/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/aeskeygenparams.md b/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/aeskeygenparams.md index eb83b29727..d2468646c1 100644 --- a/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/aeskeygenparams.md +++ b/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/aeskeygenparams.md @@ -6,6 +6,8 @@ weight: 07 # AesKeyGenParams +{{< docs/shared source="k6" lookup="webcrypto/deprecated.md" version="" >}} + The `AesKeyGenParams` object represents the object that should be passed as the algorithm parameter into the [generateKey](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/subtlecrypto/generatekey) operation when generating an AES key. ## Properties diff --git a/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/crypto/_index.md b/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/crypto/_index.md index 5eaa39e53e..fafe5d91d8 100644 --- a/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/crypto/_index.md +++ b/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/crypto/_index.md @@ -6,6 +6,8 @@ weight: 01 # Crypto +{{< docs/shared source="k6" lookup="webcrypto/deprecated.md" version="" >}} + `Crypto` allows access to a cryptographically strong random number generator and to cryptographic primitives. ## Properties diff --git a/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/crypto/getrandomvalues.md b/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/crypto/getrandomvalues.md index 12299df152..954d1484e6 100644 --- a/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/crypto/getrandomvalues.md +++ b/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/crypto/getrandomvalues.md @@ -6,6 +6,8 @@ weight: 01 # getRandomValues +{{< docs/shared source="k6" lookup="webcrypto/deprecated.md" version="" >}} + The `getRandomValues()` method fills the passed `TypedArray` with cryptographically sound random values. ## Usage diff --git a/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/crypto/randomuuid.md b/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/crypto/randomuuid.md index 0a3a0f6931..8768ad2f50 100644 --- a/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/crypto/randomuuid.md +++ b/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/crypto/randomuuid.md @@ -6,6 +6,8 @@ weight: 02 # randomUUID +{{< docs/shared source="k6" lookup="webcrypto/deprecated.md" version="" >}} + The `randomUUID` method produces a 36-characters long string that contains a cryptographically random UUID v4. ## Usage diff --git a/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/cryptokey.md b/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/cryptokey.md index 4e6a77eb20..d61b21612f 100644 --- a/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/cryptokey.md +++ b/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/cryptokey.md @@ -6,6 +6,8 @@ weight: 02 # CryptoKey +{{< docs/shared source="k6" lookup="webcrypto/deprecated.md" version="" >}} + The `CryptoKey` object represents a cryptographic key used for [encryption](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/subtlecrypto/encrypt),[decryption](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/subtlecrypto/decrypt),[signing](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/subtlecrypto/sign), or [verification](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/subtlecrypto/verify) within the webcrypto module. The `CryptoKey` object is created using the SubtleCrypto.generateKey() or SubtleCrypto.importKey() methods. ## Properties diff --git a/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/cryptokeypair.md b/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/cryptokeypair.md index f5eda8b4ad..b6c0a8ef99 100644 --- a/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/cryptokeypair.md +++ b/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/cryptokeypair.md @@ -6,6 +6,8 @@ weight: 08 # CryptoKeyPair +{{< docs/shared source="k6" lookup="webcrypto/deprecated.md" version="" >}} + The `CryptoKeyPair` object represents an asymmetric key pair with public and private keys. The [`generateKey`](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/subtlecrypto/generatekey/) method can be used to create `CryptoKeyPair` object for asymmetric algorithms such as `ECDH` or `ECDSA`. diff --git a/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/ecdhkeyderiveparams.md b/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/ecdhkeyderiveparams.md index d6049a4681..b711dc4fc2 100644 --- a/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/ecdhkeyderiveparams.md +++ b/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/ecdhkeyderiveparams.md @@ -6,6 +6,8 @@ weight: 10 # EcdhKeyDeriveParams +{{< docs/shared source="k6" lookup="webcrypto/deprecated.md" version="" >}} + The `EcdhKeyDeriveParams` represents the object that should be passed as the algorithm parameter into [`deriveBits`](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/subtlecrypto/derivebits/), when using the ECDH algorithm. ECDH is a secure communication method. Parties exchange public keys and use them with their private keys to generate a unique shared secret key. diff --git a/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/ecdsaparams.md b/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/ecdsaparams.md index bb5a0ef43a..229f5a90dc 100644 --- a/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/ecdsaparams.md +++ b/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/ecdsaparams.md @@ -6,6 +6,8 @@ weight: 11 # EcdsaParams +{{< docs/shared source="k6" lookup="webcrypto/deprecated.md" version="" >}} + The `EcdsaParams` represents the object that should be passed as the algorithm parameter into [`sign`](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/subtlecrypto/sign/) or [`verify`](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/subtlecrypto/verify/) when using the ECDSA algorithm. ## Properties diff --git a/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/eckeygenparams.md b/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/eckeygenparams.md index 99cd22d12e..620f946a04 100644 --- a/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/eckeygenparams.md +++ b/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/eckeygenparams.md @@ -6,6 +6,8 @@ weight: 09 # EcKeyGenParams +{{< docs/shared source="k6" lookup="webcrypto/deprecated.md" version="" >}} + The `EcKeyGenParams` object represents the object that should be passed as the algorithm parameter into the [generateKey](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/subtlecrypto/generatekey) operation when generating key pairs for ECDH or ECDSA algorithms. ## Properties diff --git a/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/hmackeygenparams.md b/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/hmackeygenparams.md index 61bafce456..2f0018a722 100644 --- a/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/hmackeygenparams.md +++ b/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/hmackeygenparams.md @@ -6,13 +6,15 @@ weight: 12 # HmacKeyGenParams +{{< docs/shared source="k6" lookup="webcrypto/deprecated.md" version="" >}} + The `HmacKeyGenParams` object represents the object that should be passed as the algorithm parameter into the [generateKey](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/subtlecrypto/generatekey) operation when generating an HMAC key. ## Properties | Property | Type | Description | | :---------------- | :------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| name | `string` | This should be set to `HMAC`. | +| name | `string` | This should be set to `HMAC`. | | hash | `string` | The name of the digest function to use. Possible values are `SHA-1`, `SHA-256`, `SHA-384` and `SHA-512`. | | length (optional) | `number` | The length of the key in bits. If this is omitted, the length of the key is equal to the block size of the hash function you have chosen. We recommend to leave this parameter empty, unless you have a good reason to use something different. | diff --git a/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/jsonwebkey.md b/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/jsonwebkey.md index 9f9dad333a..1b30a7f8aa 100644 --- a/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/jsonwebkey.md +++ b/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/jsonwebkey.md @@ -6,6 +6,8 @@ weight: 13 # JsonWebKey +{{< docs/shared source="k6" lookup="webcrypto/deprecated.md" version="" >}} + The `JsonWebKey` object represents object/dictionary generated by exporting a [`CryptoKey`](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/cryptokey) or used as an input parameter for key import. The properties of the `JsonWebKey` could vary depending on the algorithm and key type. See specification [JsonWebKey](https://www.w3.org/TR/WebCryptoAPI/#JsonWebKey-dictionary) for details. diff --git a/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/rsahashedimportparams.md b/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/rsahashedimportparams.md index bccde9b8a0..6070c17fe1 100644 --- a/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/rsahashedimportparams.md +++ b/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/rsahashedimportparams.md @@ -6,6 +6,8 @@ weight: 12 # RsaHashedImportParams +{{< docs/shared source="k6" lookup="webcrypto/deprecated.md" version="" >}} + The `RsaHashedImportParams` represents the object that should be passed as the algorithm parameter into [`importKey`](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/subtlecrypto/importkey/) when using the RSA algorithm. ## Properties diff --git a/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/rsahashedkeygenparams.md b/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/rsahashedkeygenparams.md index e7e5a816c1..b7c563a597 100644 --- a/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/rsahashedkeygenparams.md +++ b/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/rsahashedkeygenparams.md @@ -6,6 +6,8 @@ weight: 12 # RSAHashedKeyGenParams +{{< docs/shared source="k6" lookup="webcrypto/deprecated.md" version="" >}} + The `RSAHashedKeyGenParams` object represents the object that should be passed as the algorithm parameter into the [generateKey](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/subtlecrypto/generatekey) operation when generating an RSA key pair. ## Properties diff --git a/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/rsaoaepparams.md b/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/rsaoaepparams.md index 1eef8f19b3..78cdfe5d77 100644 --- a/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/rsaoaepparams.md +++ b/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/rsaoaepparams.md @@ -6,6 +6,8 @@ weight: 06 # RsaOaepParams +{{< docs/shared source="k6" lookup="webcrypto/deprecated.md" version="" >}} + The `RsaOaepParams` object represents the object that should be passed as the algorithm parameter into the [encrypt](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/subtlecrypto/encrypt) and [decrypt](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/subtlecrypto/decrypt) operation when using the RSA-OAEP algorithm. For more details, head to the [MDN Web Crypto API documentation on RSA-OAEP](https://developer.mozilla.org/en-US/docs/Web/API/RsaOaepParams). @@ -16,4 +18,4 @@ For more details, head to the [MDN Web Crypto API documentation on RSA-OAEP](htt | :--------------- | :----------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | name | `string` | Should be set to `RSA-OAEP`. | | label (optional) | `ArrayBuffer`, `TypedArray`, or `DataView` | It's an array of bytes that does not itself need to be encrypted but which should be bound to the ciphertext. A digest of the label is part of the input to the encryption operation. Unless your application calls for a label, you can just omit this argument, and it will not affect the security of the encryption operation. | -| | +| | diff --git a/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/rsapssparams.md b/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/rsapssparams.md index a7fe8035c2..2e78126265 100644 --- a/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/rsapssparams.md +++ b/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/rsapssparams.md @@ -6,6 +6,8 @@ weight: 11 # RsaPssParams +{{< docs/shared source="k6" lookup="webcrypto/deprecated.md" version="" >}} + The `RsaPssParams` represents the object that should be passed as the algorithm parameter into [`sign`](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/subtlecrypto/sign/) or [`verify`](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/subtlecrypto/verify/) when using the RSA-PSS algorithm. ## Properties diff --git a/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/subtlecrypto/_index.md b/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/subtlecrypto/_index.md index 32dbb0f94c..6941c9fe99 100644 --- a/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/subtlecrypto/_index.md +++ b/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/subtlecrypto/_index.md @@ -6,6 +6,8 @@ weight: 03 # SubtleCrypto +{{< docs/shared source="k6" lookup="webcrypto/deprecated.md" version="" >}} + The `SubtleCrypto` interface provides a set of low-level cryptographic primitives such as encryption, decryption, digital signature generation and verification, and key generation and management. It is useful for using secure and efficient cryptographic operations within k6 scripts. ## Methods diff --git a/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/subtlecrypto/decrypt.md b/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/subtlecrypto/decrypt.md index a3c541e910..91f19b6cbd 100644 --- a/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/subtlecrypto/decrypt.md +++ b/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/subtlecrypto/decrypt.md @@ -6,6 +6,8 @@ weight: 01 # decrypt +{{< docs/shared source="k6" lookup="webcrypto/deprecated.md" version="" >}} + The `decrypt()` method decrypts some encrypted data. ## Usage diff --git a/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/subtlecrypto/derivebits.md b/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/subtlecrypto/derivebits.md index d3df0a7805..7f32de377f 100644 --- a/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/subtlecrypto/derivebits.md +++ b/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/subtlecrypto/derivebits.md @@ -6,6 +6,8 @@ weight: 02 # deriveBits +{{< docs/shared source="k6" lookup="webcrypto/deprecated.md" version="" >}} + It takes as its arguments the base key, the derivation algorithm to use, and the length of the bits to derive. It returns a Promise which will be fulfilled with an `ArrayBuffer` containing the derived bits. This array of bits can be used as a key for encryption or decryption as a shared secret. ## Usage diff --git a/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/subtlecrypto/digest.md b/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/subtlecrypto/digest.md index cb60f4c255..0091a4c950 100644 --- a/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/subtlecrypto/digest.md +++ b/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/subtlecrypto/digest.md @@ -6,6 +6,8 @@ weight: 02 # digest +{{< docs/shared source="k6" lookup="webcrypto/deprecated.md" version="" >}} + The `digest()` method generates a cryptographically secure [digest](https://developer.mozilla.org/en-US/docs/Glossary/Digest) of the given data. A digest is a short fixed-length value derived from some input data. The `digest()` method is commonly used to compute a checksum of data or to verify the integrity of data. ## Usage diff --git a/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/subtlecrypto/encrypt.md b/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/subtlecrypto/encrypt.md index c23b59821c..181b456256 100644 --- a/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/subtlecrypto/encrypt.md +++ b/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/subtlecrypto/encrypt.md @@ -6,6 +6,8 @@ weight: 03 # encrypt +{{< docs/shared source="k6" lookup="webcrypto/deprecated.md" version="" >}} + The `encrypt()` method encrypts some data. ## Usage diff --git a/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/subtlecrypto/exportkey.md b/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/subtlecrypto/exportkey.md index 4f1a69a9bd..64552fddcd 100644 --- a/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/subtlecrypto/exportkey.md +++ b/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/subtlecrypto/exportkey.md @@ -6,6 +6,8 @@ weight: 04 # exportKey +{{< docs/shared source="k6" lookup="webcrypto/deprecated.md" version="" >}} + The `exportKey()` method takes a [CryptoKey](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/cryptokey) object as input and exports it in an external, portable format. Note that for a key to be exportable, it must have been created with the `extractable` flag set to `true`. diff --git a/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/subtlecrypto/generatekey.md b/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/subtlecrypto/generatekey.md index fdae3524dc..2846a9871a 100644 --- a/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/subtlecrypto/generatekey.md +++ b/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/subtlecrypto/generatekey.md @@ -24,6 +24,8 @@ generateKey(algorithm, extractable, keyUsages) ### Supported algorithms +{{< docs/shared source="k6" lookup="webcrypto/deprecated.md" version="" >}} + {{< docs/shared source="k6" lookup="webcrypto/supported-key-methods.md" version="" >}} ## Return Value @@ -32,15 +34,15 @@ A `Promise` that resolves with the generated key as a [CryptoKey](https://grafan ### Algorithm specific input -| | HMAC | AES | ECDH | ECDSA | RSA-OAEP | RSASSA-PKCS1-v1_5 | RSA-PSS | -| :--------------------- | :----------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------- |----- |----- |----- | +| | HMAC | AES | ECDH | ECDSA | RSA-OAEP | RSASSA-PKCS1-v1_5 | RSA-PSS | +| :--------------------- | :----------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | Parameters type to use | [`HmacKeyGenParams`](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/hmackeygenparams) | [`AesKeyGenParams`](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/aeskeygenparams) | [`EcKeyGenParams`](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/eckeygenparams) | [`EcKeyGenParams`](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/eckeygenparams) | [`RSAHashedKeyGenParams`](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/rsahashedkeygenparams) | [`RSAHashedKeyGenParams`](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/rsahashedkeygenparams) | [`RSAHashedKeyGenParams`](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/rsahashedkeygenparams) | -| Possible key usages | `sign`, `verify` | `encrypt`, `decrypt` | `deriveKey`, `deriveBits` | `sign`, `verify` | `encrypt`, `decrypt` | `sign`, `verify` | `sign`, `verify` | +| Possible key usages | `sign`, `verify` | `encrypt`, `decrypt` | `deriveKey`, `deriveBits` | `sign`, `verify` | `encrypt`, `decrypt` | `sign`, `verify` | `sign`, `verify` | ## Throws -| Type | Description | -| :------------ | :------------------------------------------------------------------------------------------- | +| Type | Description | +| :------------ | :-------------------------------------------------------------------------------------------- | | `SyntaxError` | Raised when the `keyUsages` parameter is empty, but the key is of type `secret` or `private`. | ## Example diff --git a/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/subtlecrypto/importkey.md b/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/subtlecrypto/importkey.md index 3b59c4b9c2..4d37e8152c 100644 --- a/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/subtlecrypto/importkey.md +++ b/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/subtlecrypto/importkey.md @@ -6,6 +6,8 @@ weight: 06 # importKey +{{< docs/shared source="k6" lookup="webcrypto/deprecated.md" version="" >}} + The `importKey()` imports a key from an external, portable format, and gives you a [CryptoKey](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/cryptokey) object that can be used with the Web Crypto API. ## Usage diff --git a/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/subtlecrypto/sign.md b/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/subtlecrypto/sign.md index 86cabbd4c5..90b1aebb87 100644 --- a/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/subtlecrypto/sign.md +++ b/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/subtlecrypto/sign.md @@ -6,6 +6,8 @@ weight: 07 # sign +{{< docs/shared source="k6" lookup="webcrypto/deprecated.md" version="" >}} + The `sign()` operation generates a digital signature of the provided `data`, using the given [CryptoKey](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/cryptokey) object. ## Usage @@ -16,11 +18,11 @@ sign(algorithm, key, data) ## Parameters -| Name | Type | Description | -| :---------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------- | +| Name | Type | Description | +| :---------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------ | | `algorithm` | `string` or object with a single `name` string property (`{name: "RSASSA-PKCS1-v1_5"}`) or an [EcdsaParams](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/ecdsaparams/), [HmacKeyGenParams](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/hmackeygenparams/), or [RsaPssParams](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/rsapssparams/) object. | The signature algorithm to use. | -| `key` | [CryptoKey](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/cryptokey) | The key to use for signing. | -| `data` | `ArrayBuffer`, `TypedArray`, or `DataView` | The data to be signed. | +| `key` | [CryptoKey](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/cryptokey) | The key to use for signing. | +| `data` | `ArrayBuffer`, `TypedArray`, or `DataView` | The data to be signed. | ### Supported algorithms diff --git a/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/subtlecrypto/verify.md b/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/subtlecrypto/verify.md index ad58aff134..e6baa0259e 100644 --- a/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/subtlecrypto/verify.md +++ b/docs/sources/k6/v1.0.x/javascript-api/k6-experimental/webcrypto/subtlecrypto/verify.md @@ -6,6 +6,8 @@ weight: 08 # verify +{{< docs/shared source="k6" lookup="webcrypto/deprecated.md" version="" >}} + The `verify()` operation verifies a digital signature. It ensures that some data was signed by a known key and that the data has not been tampered with since it was signed. ## Usage @@ -16,12 +18,12 @@ verify(algorithm, key, signature, data) ## Parameters -| Name | Type | Description | -| :---------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------- | -| `algorithm` | `string` or object with a single `name` string property (`{name: "RSASSA-PKCS1-v1_5"}`) or an [EcdsaParams](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/ecdsaparams/), [HmacKeyGenParams](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/hmackeygenparams/), or [RsaPssParams](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/rsapssparams/) object. | The signature algorithm to use. | -| `key` | [CryptoKey](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/cryptokey) | The key that will be used to verify the signature. | -| `signature` | `ArrayBuffer` | The signature to verify. | -| `data` | `ArrayBuffer` | The data whose signature is to be verified. | +| Name | Type | Description | +| :---------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------- | +| `algorithm` | `string` or object with a single `name` string property (`{name: "RSASSA-PKCS1-v1_5"}`) or an [EcdsaParams](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/ecdsaparams/), [HmacKeyGenParams](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/hmackeygenparams/), or [RsaPssParams](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/rsapssparams/) object. | The signature algorithm to use. | +| `key` | [CryptoKey](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto/cryptokey) | The key that will be used to verify the signature. | +| `signature` | `ArrayBuffer` | The signature to verify. | +| `data` | `ArrayBuffer` | The data whose signature is to be verified. | ### Supported algorithms diff --git a/docs/sources/k6/v1.0.x/shared/crypto-module.md b/docs/sources/k6/v1.0.x/shared/crypto-module.md index 241d3d3374..dc884083b5 100644 --- a/docs/sources/k6/v1.0.x/shared/crypto-module.md +++ b/docs/sources/k6/v1.0.x/shared/crypto-module.md @@ -7,6 +7,6 @@ title: k6/crypto module admonition A module with a better and standard API exists.

-The new [k6/experimental/webcrypto API](/docs/k6//javascript-api/k6-experimental/webcrypto/) partially implements the [WebCryptoAPI](https://www.w3.org/TR/WebCryptoAPI/), supporting more features than [k6/crypto](/docs/k6//javascript-api/k6-crypto/). +The [crypto module](/docs/k6//javascript-api/crypto/) partially implements the [WebCrypto API](https://www.w3.org/TR/WebCryptoAPI/), supporting more features than [k6/crypto](/docs/k6//javascript-api/k6-crypto/). {{< /admonition >}} diff --git a/docs/sources/k6/v1.0.x/shared/crypto/supported-encrypt-decrypt.md b/docs/sources/k6/v1.0.x/shared/crypto/supported-encrypt-decrypt.md new file mode 100644 index 0000000000..259cf657cb --- /dev/null +++ b/docs/sources/k6/v1.0.x/shared/crypto/supported-encrypt-decrypt.md @@ -0,0 +1,7 @@ +--- +title: webcrypto/supported encrypt/decrypt +--- + +| AES-CBC | AES-CTR | AES-GCM | RSA-OAEP | +| :--------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------- | +| ✅ [AesCbcParams](https://grafana.com/docs/k6//javascript-api/crypto/aescbcparams) | ✅ [AesCtrParams](https://grafana.com/docs/k6//javascript-api/crypto/aesctrparams) | ✅ [AesGcmParams](https://grafana.com/docs/k6//javascript-api/crypto/aesgcmparams) | ✅ [RsaOaepParams](https://grafana.com/docs/k6//javascript-api/crypto/rsaoaepparams) | diff --git a/docs/sources/k6/v1.0.x/shared/crypto/supported-key-methods-formats.md b/docs/sources/k6/v1.0.x/shared/crypto/supported-key-methods-formats.md new file mode 100644 index 0000000000..d2545a7477 --- /dev/null +++ b/docs/sources/k6/v1.0.x/shared/crypto/supported-key-methods-formats.md @@ -0,0 +1,7 @@ +--- +title: webcrypto/supported key methods formats +--- + +- `ECDH` and `ECDSA` algorithms have support for `pkcs8`, `spki`, `raw` and `jwk` formats. +- `RSA-OAEP`, `RSASSA-PKCS1-v1_5` and `RSA-PSS` algorithms have support for `pkcs8`, `spki` and `jwk` formats. +- `AES-*` and `HMAC` algorithms have currently support for `raw` and `jwk` formats. diff --git a/docs/sources/k6/v1.0.x/shared/crypto/supported-key-methods.md b/docs/sources/k6/v1.0.x/shared/crypto/supported-key-methods.md new file mode 100644 index 0000000000..36bd96a060 --- /dev/null +++ b/docs/sources/k6/v1.0.x/shared/crypto/supported-key-methods.md @@ -0,0 +1,7 @@ +--- +title: webcrypto/supported key methods +--- + +| AES-CBC | AES-CTR | AES-GCM | AES-KW | ECDH | ECDSA | HMAC | RSA-OAEP | RSASSA-PKCS1-v1_5 | RSA-PSS | +| :--------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------- | :----- | :------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------ | :---------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------- | +| ✅ [AesCbcParams](https://grafana.com/docs/k6//javascript-api/crypto/aescbcparams) | ✅ [AesCtrParams](https://grafana.com/docs/k6//javascript-api/crypto/aesctrparams) | ✅ [AesGcmParams](https://grafana.com/docs/k6//javascript-api/crypto/aesgcmparams) | ❌ | ✅ [EcdhKeyDeriveParams](https://grafana.com/docs/k6//javascript-api/crypto/ecdhkeyderiveparams/) | ✅ [EcdsaParams](https://grafana.com/docs/k6//javascript-api/crypto/ecdsaparams/) | ✅ [HmacKeyGenParams](https://grafana.com/docs/k6//javascript-api/crypto/hmackeygenparams/) | ✅ [RsaHashedImportParams](https://grafana.com/docs/k6//javascript-api/crypto/rsahashedimportparams/) | ✅ [RsaHashedImportParams](https://grafana.com/docs/k6//javascript-api/crypto/rsahashedimportparams/) | ✅ [RsaHashedImportParams](https://grafana.com/docs/k6//javascript-api/crypto/rsahashedimportparams/) | diff --git a/docs/sources/k6/v1.0.x/shared/crypto/supported-sign-verify.md b/docs/sources/k6/v1.0.x/shared/crypto/supported-sign-verify.md new file mode 100644 index 0000000000..7317e231ba --- /dev/null +++ b/docs/sources/k6/v1.0.x/shared/crypto/supported-sign-verify.md @@ -0,0 +1,7 @@ +--- +title: webcrypto/supported sign/verify +--- + +| ECDSA | HMAC | RSASSA-PKCS1-v1_5 | RSA-PSS | +| :-------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------ | :---------------- | :---------------------------------------------------------------------------------------------- | +| ✅ [EcdsaParams](https://grafana.com/docs/k6//javascript-api/crypto/ecdsaparams/) | ✅ [HmacKeyGenParams](https://grafana.com/docs/k6//javascript-api/crypto/hmackeygenparams/) | ✅ | ✅ [RsaPssParams](https://grafana.com/docs/k6//javascript-api/crypto/rsapssparams/) | diff --git a/docs/sources/k6/v1.0.x/shared/javascript-api/crypto.md b/docs/sources/k6/v1.0.x/shared/javascript-api/crypto.md new file mode 100644 index 0000000000..a34b88f7c9 --- /dev/null +++ b/docs/sources/k6/v1.0.x/shared/javascript-api/crypto.md @@ -0,0 +1,17 @@ +--- +title: javascript-api/crypto +--- + +The [`crypto` module](https://grafana.com/docs/k6//javascript-api/crypto) provides a WebCrypto API implementation. + +| Class/Method | Description | +| ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| [getRandomValues](https://grafana.com/docs/k6//javascript-api/crypto/getrandomvalues) | Fills the passed `TypedArray` with cryptographically sound random values. | +| [randomUUID](https://grafana.com/docs/k6//javascript-api/crypto/randomuuid) | Returns a randomly generated, 36 character long v4 UUID. | +| [subtle](https://grafana.com/docs/k6//javascript-api/crypto/subtlecrypto) | The [SubtleCrypto](https://grafana.com/docs/k6//javascript-api/crypto/subtlecrypto) interface provides access to common cryptographic primitives, such as hashing, signing, encryption, or decryption. | + +{{< admonition type="note" >}} + +The `crypto` object is available globally, so you can use it in your script without including an import statement. + +{{< /admonition >}} diff --git a/docs/sources/k6/v1.0.x/shared/webcrypto/deprecated.md b/docs/sources/k6/v1.0.x/shared/webcrypto/deprecated.md new file mode 100644 index 0000000000..d24bd280b1 --- /dev/null +++ b/docs/sources/k6/v1.0.x/shared/webcrypto/deprecated.md @@ -0,0 +1,11 @@ +--- +title: Experimental webcrypto module admonition +--- + +{{< admonition type="caution" >}} + +The experimental module `k6/experimental/webcrypto` has graduated, and its functionality is now available globally through the [`crypto` object](https://grafana.com/docs/k6//javascript-api/crypto). The `k6/experimental/webcrypto` is deprecated and will be removed in the near future. + +To migrate your scripts, remove the `k6/experimental/webcrypto` imports and use the `crypto` object instead. + +{{< /admonition >}}