Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc,crypto: update webcrypto docs for global access #44723

Merged
merged 3 commits into from
Sep 21, 2022
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
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;
aduh95 marked this conversation as resolved.
Show resolved Hide resolved

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