Skip to content

Commit

Permalink
doc,crypto: update webcrypto docs for global access
Browse files Browse the repository at this point in the history
PR-URL: #44723
Reviewed-By: Antoine du Hamel <[email protected]>
Reviewed-By: Tobias Nießen <[email protected]>
Reviewed-By: Luigi Pinca <[email protected]>
  • Loading branch information
panva authored Sep 21, 2022
1 parent 6c8c3d8 commit 46dcfb3
Showing 1 changed file with 15 additions and 14 deletions.
29 changes: 15 additions & 14 deletions doc/api/webcrypto.md
Original file line number Diff line number Diff line change
Expand Up @@ -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() {

Expand Down Expand Up @@ -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({
Expand All @@ -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 {
Expand All @@ -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({
Expand All @@ -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({
Expand All @@ -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') {
Expand All @@ -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();
Expand Down Expand Up @@ -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({
Expand All @@ -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 [
Expand Down Expand Up @@ -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();
Expand All @@ -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();
Expand Down Expand Up @@ -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();
Expand Down Expand Up @@ -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.

Expand Down

0 comments on commit 46dcfb3

Please sign in to comment.