mirror of
https://github.com/denoland/deno.git
synced 2025-08-04 10:59:13 +00:00
docs: add examples for SubtleCrypto (#28068)
Adds examples for subtleCrypto (https://docs.deno.com/api/web/~/SubtleCrypto) - generateKey - importKey - exportKey - sign - verify - digest - encrypt - decrypt - deriveBits - deriveKey - wrapKey - unwrapKey --------- Co-authored-by: Ryan Dahl <ry@tinyclouds.org> Co-authored-by: Bartek Iwańczuk <biwanczuk@gmail.com>
This commit is contained in:
Phil Hawksworth
GitHub
parent
5b24b67a6e
commit
b20f98ccf7
1 changed files with 255 additions and 0 deletions
255
cli/tsc/dts/lib.deno_crypto.d.ts
vendored
255
cli/tsc/dts/lib.deno_crypto.d.ts
vendored
|
|
@ -237,21 +237,123 @@ declare var CryptoKeyPair: {
|
|||
* @category Crypto
|
||||
*/
|
||||
interface SubtleCrypto {
|
||||
/**
|
||||
* Generates an asymmetric cryptographic key pair for encryption, signing, or
|
||||
* key exchange.
|
||||
*
|
||||
* This overload is used for generating key pairs with RSA or elliptic curve
|
||||
* algorithms.
|
||||
*
|
||||
* @example
|
||||
* ```ts
|
||||
* // RSA key generation
|
||||
* const key = await crypto.subtle.generateKey(
|
||||
* {
|
||||
* name: "RSA-OAEP",
|
||||
* modulusLength: 4096,
|
||||
* publicExponent: new Uint8Array([1, 0, 1]),
|
||||
* hash: "SHA-256",
|
||||
* },
|
||||
* true,
|
||||
* ["encrypt", "decrypt"]
|
||||
* );
|
||||
* ```
|
||||
*
|
||||
* @example
|
||||
* ```ts
|
||||
* // Elliptic curve (ECDSA) key pair generation
|
||||
* const key = await crypto.subtle.generateKey(
|
||||
* {
|
||||
* name: "ECDSA",
|
||||
* namedCurve: "P-384",
|
||||
* },
|
||||
* true,
|
||||
* ["sign", "verify"]
|
||||
* );
|
||||
* ```
|
||||
*
|
||||
* @see https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/generateKey
|
||||
*/
|
||||
generateKey(
|
||||
algorithm: RsaHashedKeyGenParams | EcKeyGenParams,
|
||||
extractable: boolean,
|
||||
keyUsages: KeyUsage[],
|
||||
): Promise<CryptoKeyPair>;
|
||||
/**
|
||||
* Generates a symmetric cryptographic key for encryption, authentication, or
|
||||
* hashing.
|
||||
*
|
||||
* This overload is used for algorithms such as AES and HMAC.
|
||||
*
|
||||
* @example
|
||||
* ```ts
|
||||
* const key = await crypto.subtle.generateKey(
|
||||
* {
|
||||
* name: "AES-GCM",
|
||||
* length: 256,
|
||||
* },
|
||||
* true,
|
||||
* ["encrypt", "decrypt"]
|
||||
* );
|
||||
* ```
|
||||
*
|
||||
* @example
|
||||
* ```ts
|
||||
* // HMAC key generation
|
||||
* const key = await crypto.subtle.generateKey(
|
||||
* {
|
||||
* name: "HMAC",
|
||||
* hash: { name: "SHA-512" },
|
||||
* },
|
||||
* true,
|
||||
* ["sign", "verify"]
|
||||
* );
|
||||
* ```
|
||||
*
|
||||
* @see https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/generateKey
|
||||
*/
|
||||
generateKey(
|
||||
algorithm: AesKeyGenParams | HmacKeyGenParams,
|
||||
extractable: boolean,
|
||||
keyUsages: KeyUsage[],
|
||||
): Promise<CryptoKey>;
|
||||
/**
|
||||
* Generates a cryptographic key or key pair for a given algorithm.
|
||||
*
|
||||
* This generic overload handles any key generation request, returning either
|
||||
* a symmetric key or an asymmetric key pair based on the provided algorithm.
|
||||
*
|
||||
* @see https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/generateKey
|
||||
*/
|
||||
generateKey(
|
||||
algorithm: AlgorithmIdentifier,
|
||||
extractable: boolean,
|
||||
keyUsages: KeyUsage[],
|
||||
): Promise<CryptoKeyPair | CryptoKey>;
|
||||
|
||||
/**
|
||||
* Imports a cryptographic key in JSON Web Key (JWK) format.
|
||||
*
|
||||
* This method is used to import an asymmetric key (e.g., RSA or ECDSA) from a JWK object.
|
||||
* JWK allows structured representation of keys, making them portable across different systems.
|
||||
*
|
||||
* @example
|
||||
* ```ts
|
||||
* // Import an ECDSA private signing key where `jwk` is an object describing a private key
|
||||
* crypto.subtle.importKey(
|
||||
* "jwk",
|
||||
* jwk,
|
||||
* {
|
||||
* name: "ECDSA",
|
||||
* namedCurve: "P-384",
|
||||
* },
|
||||
* true,
|
||||
* ["sign"],
|
||||
* );
|
||||
* ```
|
||||
*
|
||||
* @see https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/importKey
|
||||
*/
|
||||
importKey(
|
||||
format: "jwk",
|
||||
keyData: JsonWebKey,
|
||||
|
|
@ -263,6 +365,22 @@ interface SubtleCrypto {
|
|||
extractable: boolean,
|
||||
keyUsages: KeyUsage[],
|
||||
): Promise<CryptoKey>;
|
||||
/**
|
||||
* Imports a cryptographic key in raw, PKCS8, or SPKI format.
|
||||
*
|
||||
* This method is used to import symmetric keys (e.g., AES), private keys (PKCS8), or public keys (SPKI).
|
||||
*
|
||||
* @example
|
||||
* ```ts
|
||||
* // Import an AES-GCM secret key where `rawKey` is an ArrayBuffer string
|
||||
* crypto.subtle.importKey("raw", rawKey, "AES-GCM", true, [
|
||||
* "encrypt",
|
||||
* "decrypt",
|
||||
* ]);
|
||||
* ```
|
||||
*
|
||||
* @see https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/importKey
|
||||
*/
|
||||
importKey(
|
||||
format: Exclude<KeyFormat, "jwk">,
|
||||
keyData: BufferSource,
|
||||
|
|
@ -274,26 +392,100 @@ interface SubtleCrypto {
|
|||
extractable: boolean,
|
||||
keyUsages: KeyUsage[],
|
||||
): Promise<CryptoKey>;
|
||||
/**
|
||||
* Exports a cryptographic key in JSON Web Key (JWK) format.
|
||||
*
|
||||
* This method allows exporting an asymmetric key (e.g., RSA, ECDSA) into a JSON-based representation,
|
||||
* making it easy to store and transfer across systems.
|
||||
*
|
||||
* @example
|
||||
* ```ts
|
||||
* await crypto.subtle.exportKey("jwk", key);
|
||||
* ```
|
||||
*
|
||||
* @see https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/exportKey
|
||||
*/
|
||||
exportKey(format: "jwk", key: CryptoKey): Promise<JsonWebKey>;
|
||||
/**
|
||||
* Exports a cryptographic key in raw, PKCS8, or SPKI format.
|
||||
*
|
||||
* This method is used to export symmetric keys (AES), private keys (PKCS8), or public keys (SPKI) in binary form.
|
||||
*
|
||||
* @example
|
||||
* ```ts
|
||||
* await crypto.subtle.exportKey("raw", key);
|
||||
* ```
|
||||
*
|
||||
* @see https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/exportKey
|
||||
*/
|
||||
exportKey(
|
||||
format: Exclude<KeyFormat, "jwk">,
|
||||
key: CryptoKey,
|
||||
): Promise<ArrayBuffer>;
|
||||
/**
|
||||
* Generates a digital signature using a private cryptographic key.
|
||||
*
|
||||
* This method is used to sign data with an asymmetric key (e.g., RSA-PSS, ECDSA).
|
||||
*
|
||||
* @example
|
||||
* ```ts
|
||||
* await crypto.subtle.sign("ECDSA", key, data);
|
||||
* ```
|
||||
*
|
||||
* @see https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/sign
|
||||
*/
|
||||
sign(
|
||||
algorithm: AlgorithmIdentifier | RsaPssParams | EcdsaParams,
|
||||
key: CryptoKey,
|
||||
data: BufferSource,
|
||||
): Promise<ArrayBuffer>;
|
||||
/**
|
||||
* Verifies a digital signature using a public cryptographic key.
|
||||
*
|
||||
* This method checks whether a signature is valid for the given data.
|
||||
*
|
||||
* @example
|
||||
* ```ts
|
||||
* await crypto.subtle.verify("ECDSA", key, signature, data);
|
||||
* ```
|
||||
*
|
||||
* @see https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/verify
|
||||
*/
|
||||
verify(
|
||||
algorithm: AlgorithmIdentifier | RsaPssParams | EcdsaParams,
|
||||
key: CryptoKey,
|
||||
signature: BufferSource,
|
||||
data: BufferSource,
|
||||
): Promise<boolean>;
|
||||
/**
|
||||
* Computes a cryptographic hash (digest) of the given data.
|
||||
*
|
||||
* This method is commonly used for verifying data integrity.
|
||||
*
|
||||
* @example
|
||||
* ```ts
|
||||
* // Compute the digest of given data using a cryptographic algorithm
|
||||
* await crypto.subtle.digest("SHA-256", data);
|
||||
* ```
|
||||
*
|
||||
* @see https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/digest
|
||||
*/
|
||||
digest(
|
||||
algorithm: AlgorithmIdentifier,
|
||||
data: BufferSource,
|
||||
): Promise<ArrayBuffer>;
|
||||
/**
|
||||
* Encrypts data using a cryptographic key.
|
||||
*
|
||||
* This method is used with both symmetric (AES) and asymmetric (RSA) encryption.
|
||||
*
|
||||
* @example
|
||||
* ```ts
|
||||
* await crypto.subtle.encrypt("RSA-OAEP", key, data);
|
||||
* ```
|
||||
*
|
||||
* @see https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/encrypt
|
||||
*/
|
||||
encrypt(
|
||||
algorithm:
|
||||
| AlgorithmIdentifier
|
||||
|
|
@ -304,6 +496,16 @@ interface SubtleCrypto {
|
|||
key: CryptoKey,
|
||||
data: BufferSource,
|
||||
): Promise<ArrayBuffer>;
|
||||
/**
|
||||
* Decrypts previously encrypted data using a cryptographic key.
|
||||
*
|
||||
* @example
|
||||
* ```ts
|
||||
* await crypto.subtle.decrypt("RSA-OAEP", key, data);
|
||||
* ```
|
||||
*
|
||||
* @see https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/decrypt
|
||||
*/
|
||||
decrypt(
|
||||
algorithm:
|
||||
| AlgorithmIdentifier
|
||||
|
|
@ -314,6 +516,16 @@ interface SubtleCrypto {
|
|||
key: CryptoKey,
|
||||
data: BufferSource,
|
||||
): Promise<ArrayBuffer>;
|
||||
/**
|
||||
* This method is used to derive a key from a base key using a cryptographic algorithm.
|
||||
*
|
||||
* @example
|
||||
* ```ts
|
||||
* await crypto.subtle.deriveBits("HKDF", baseKey, length);
|
||||
* ```
|
||||
*
|
||||
* @see https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/deriveBits
|
||||
*/
|
||||
deriveBits(
|
||||
algorithm:
|
||||
| AlgorithmIdentifier
|
||||
|
|
@ -323,6 +535,20 @@ interface SubtleCrypto {
|
|||
baseKey: CryptoKey,
|
||||
length: number,
|
||||
): Promise<ArrayBuffer>;
|
||||
/**
|
||||
* This method is used to derive a secret key from a base or master key using a cryptographic algorithm.
|
||||
* It returns a Promise which fulfils with an object of the new key.
|
||||
*
|
||||
* @see https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/deriveKey
|
||||
*
|
||||
* @example
|
||||
* ```ts
|
||||
* // Derive a key using an HKDF algorithm
|
||||
* await crypto.subtle.deriveKey("HKDF", baseKey, derivedKeyType, extractable, keyUsages);
|
||||
* ```
|
||||
*
|
||||
* @see https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/deriveKey
|
||||
*/
|
||||
deriveKey(
|
||||
algorithm:
|
||||
| AlgorithmIdentifier
|
||||
|
|
@ -339,6 +565,16 @@ interface SubtleCrypto {
|
|||
extractable: boolean,
|
||||
keyUsages: KeyUsage[],
|
||||
): Promise<CryptoKey>;
|
||||
/**
|
||||
* Wraps (encrypts) a cryptographic key for secure storage or transmission
|
||||
*
|
||||
* @example
|
||||
* ```ts
|
||||
* await crypto.subtle.wrapKey("jwk", key, wrappingKey, "RSA-OAEP");
|
||||
* ```
|
||||
*
|
||||
* @see https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/wrapKey
|
||||
*/
|
||||
wrapKey(
|
||||
format: KeyFormat,
|
||||
key: CryptoKey,
|
||||
|
|
@ -349,6 +585,25 @@ interface SubtleCrypto {
|
|||
| AesCbcParams
|
||||
| AesCtrParams,
|
||||
): Promise<ArrayBuffer>;
|
||||
/**
|
||||
* Unwraps (decrypts) a previously wrapped key.
|
||||
*
|
||||
* @example
|
||||
* ```ts
|
||||
* // Unwrap an AES-GCM key wrapped with AES-KW
|
||||
* const unwrappedKey = await crypto.subtle.unwrapKey(
|
||||
* "jwk", // Format of the key to import
|
||||
* wrappedKey, // Encrypted key data as ArrayBuffer
|
||||
* unwrappingKey, // CryptoKey used for unwrapping
|
||||
* { name: "AES-KW" }, // Unwrapping algorithm
|
||||
* { name: "AES-GCM", length: 256 }, // Algorithm for unwrapped key
|
||||
* true, // Whether the unwrapped key is extractable
|
||||
* ["encrypt", "decrypt"] // Allowed key usages
|
||||
* );
|
||||
* ```
|
||||
*
|
||||
* @see https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/unwrapKey
|
||||
*/
|
||||
unwrapKey(
|
||||
format: KeyFormat,
|
||||
wrappedKey: BufferSource,
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue