From 46dcfb3c7be167ed27a3e8db4e40ff8b17d892fb Mon Sep 17 00:00:00 2001
From: Filip Skokan <panva.ip@gmail.com>
Date: Wed, 21 Sep 2022 15:12:31 +0200
Subject: [PATCH] doc,crypto: update webcrypto docs for global access
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

PR-URL: https://github.com/nodejs/node/pull/44723
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>
Reviewed-By: Tobias Nießen <tniessen@tnie.de>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
---
 doc/api/webcrypto.md | 29 +++++++++++++++--------------
 1 file changed, 15 insertions(+), 14 deletions(-)

diff --git a/doc/api/webcrypto.md b/doc/api/webcrypto.md
index f38621a950630d..0860080714aa01 100644
--- a/doc/api/webcrypto.md
+++ b/doc/api/webcrypto.md
@@ -39,10 +39,11 @@ changes:
 
 Node.js provides an implementation of the standard [Web Crypto API][].
 
-Use `require('node:crypto').webcrypto` to access this module.
+Use `globalThis.crypto` or `require('node:crypto').webcrypto` to access this
+module.
 
 ```js
-const { subtle } = require('node:crypto').webcrypto;
+const { subtle } = globalThis.crypto;
 
 (async function() {
 
@@ -72,7 +73,7 @@ or asymmetric key pairs (public key and private key).
 #### AES keys
 
 ```js
-const { subtle } = require('node:crypto').webcrypto;
+const { subtle } = globalThis.crypto;
 
 async function generateAesKey(length = 256) {
   const key = await subtle.generateKey({
@@ -87,7 +88,7 @@ async function generateAesKey(length = 256) {
 #### ECDSA key pairs
 
 ```js
-const { subtle } = require('node:crypto').webcrypto;
+const { subtle } = globalThis.crypto;
 
 async function generateEcKey(namedCurve = 'P-521') {
   const {
@@ -107,7 +108,7 @@ async function generateEcKey(namedCurve = 'P-521') {
 > Stability: 1 - Experimental
 
 ```js
-const { subtle } = require('node:crypto').webcrypto;
+const { subtle } = globalThis.crypto;
 
 async function generateEd25519Key() {
   return subtle.generateKey({
@@ -125,7 +126,7 @@ async function generateX25519Key() {
 #### HMAC keys
 
 ```js
-const { subtle } = require('node:crypto').webcrypto;
+const { subtle } = globalThis.crypto;
 
 async function generateHmacKey(hash = 'SHA-256') {
   const key = await subtle.generateKey({
@@ -140,7 +141,7 @@ async function generateHmacKey(hash = 'SHA-256') {
 #### RSA key pairs
 
 ```js
-const { subtle } = require('node:crypto').webcrypto;
+const { subtle } = globalThis.crypto;
 const publicExponent = new Uint8Array([1, 0, 1]);
 
 async function generateRsaKey(modulusLength = 2048, hash = 'SHA-256') {
@@ -161,7 +162,7 @@ async function generateRsaKey(modulusLength = 2048, hash = 'SHA-256') {
 ### Encryption and decryption
 
 ```js
-const crypto = require('node:crypto').webcrypto;
+const crypto = globalThis.crypto;
 
 async function aesEncrypt(plaintext) {
   const ec = new TextEncoder();
@@ -194,7 +195,7 @@ async function aesDecrypt(ciphertext, key, iv) {
 ### Exporting and importing keys
 
 ```js
-const { subtle } = require('node:crypto').webcrypto;
+const { subtle } = globalThis.crypto;
 
 async function generateAndExportHmacKey(format = 'jwk', hash = 'SHA-512') {
   const key = await subtle.generateKey({
@@ -218,7 +219,7 @@ async function importHmacKey(keyData, format = 'jwk', hash = 'SHA-512') {
 ### Wrapping and unwrapping keys
 
 ```js
-const { subtle } = require('node:crypto').webcrypto;
+const { subtle } = globalThis.crypto;
 
 async function generateAndWrapHmacKey(format = 'jwk', hash = 'SHA-512') {
   const [
@@ -261,7 +262,7 @@ async function unwrapHmacKey(
 ### Sign and verify
 
 ```js
-const { subtle } = require('node:crypto').webcrypto;
+const { subtle } = globalThis.crypto;
 
 async function sign(key, data) {
   const ec = new TextEncoder();
@@ -285,7 +286,7 @@ async function verify(key, signature, data) {
 ### Deriving bits and keys
 
 ```js
-const { subtle } = require('node:crypto').webcrypto;
+const { subtle } = globalThis.crypto;
 
 async function pbkdf2(pass, salt, iterations = 1000, length = 256) {
   const ec = new TextEncoder();
@@ -328,7 +329,7 @@ async function pbkdf2Key(pass, salt, iterations = 1000, length = 256) {
 ### Digest
 
 ```js
-const { subtle } = require('node:crypto').webcrypto;
+const { subtle } = globalThis.crypto;
 
 async function digest(data, algorithm = 'SHA-512') {
   const ec = new TextEncoder();
@@ -371,7 +372,7 @@ implementation and the APIs supported for each:
 added: v15.0.0
 -->
 
-Calling `require('node:crypto').webcrypto` returns an instance of the `Crypto`
+`globalThis.crypto` is an instance of the `Crypto`
 class. `Crypto` is a singleton that provides access to the remainder of the
 crypto API.