Skip to content

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

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.

Sign up for GitHub

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

Merged
merged 3 commits into from
Sep 21, 2022
Merged

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

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
bbb8c13
doc,crypto: update webcrypto docs for global access
panva Sep 19, 2022
52bba36
Update doc/api/webcrypto.md
panva Sep 19, 2022
a4dbe08
Update doc/api/webcrypto.md
panva Sep 19, 2022
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
View file
Open in desktop
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