Node.js Reference ยท crypto
Node.js crypto.sign() and crypto.verify() functions
Reference for crypto.sign(), crypto.verify() and the Sign and Verify classes in Node.js: creating and checking digital signatures with RSA, ECDSA and Ed25519.
A digital signature proves that a message was produced by the holder of a private key and has not been changed since. crypto.sign(algorithm, data, key) creates a signature with a private key, and crypto.verify(algorithm, data, key, signature) checks it with the matching public key. Both are one-shot functions; for data that arrives in pieces there are streaming crypto.createSign() and crypto.createVerify() classes.
With Ed25519 and Ed448 the algorithm argument must be null, because the hash is built in. For RSA and ECDSA you name a digest such as 'sha256'.
import { generateKeyPairSync, sign, verify } from 'node:crypto'; const { publicKey, privateKey } = generateKeyPairSync('ed25519'); const signature = sign(null, Buffer.from('hello'), privateKey); console.log(verify(null, Buffer.from('hello'), publicKey, signature));
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Syntax
crypto.sign(algorithm: string | null, data, key, callback?): Buffer crypto.verify(algorithm: string | null, data, key, signature, callback?): boolean crypto.createSign(algorithm, options?): Sign // .update(), .sign(key, outputEncoding?) crypto.createVerify(algorithm, options?): Verify // .update(), .verify(key, signature, signatureEncoding?)
| Name | Description |
|---|---|
algorithm |
Digest name such as 'sha256', or null for Ed25519/Ed448 (and to use the key's default digest). |
data |
The message: Buffer, typed array or DataView for the one-shot functions; strings are accepted by update(). |
key |
A private (sign) or public (verify) KeyObject, a PEM string, or an options object { key, padding, saltLength, dsaEncoding, passphrase }. |
signature |
The signature as a buffer for crypto.verify(). |
callback |
Optional (err, result); without it the call is synchronous. |
dsaEncoding |
ECDSA and DSA: 'der' (default) or 'ieee-p1363' (raw `r |
Returns: sign() returns a Buffer; verify() returns true or false.
Errors: a wrong key type, unknown digest or unusable padding throws (for example ERR_OSSL_* or ERR_CRYPTO_INVALID_DIGEST). A bad signature is not an error: verify() simply returns false.
Usage notes
- Sign the exact bytes. Any change, including different JSON key order or line endings, invalidates the signature. Sign a canonical byte representation.
nullmeans built-in hash. Passing'sha256'for an Ed25519 key fails; passnull.- Prefer RSA-PSS over PKCS#1 v1.5 for new designs, and 3072-bit or larger RSA keys for longer-lived use. Ed25519 avoids the choices altogether.
- ECDSA signatures use DER by default. JWTs and Web Crypto expect the raw
ieee-p1363form; setdsaEncoding: 'ieee-p1363'on both sides. - Signing is not encryption. The message stays readable; a signature only proves origin and integrity.
- Verify, then trust. Check that the public key itself is authentic (a certificate, or a key you distributed yourself), or the signature proves nothing.
- Streaming classes are single use; call
.sign()or.verify()once after.update()and.end(). crypto.sign()andcrypto.verify()were added in Node.js 12.0.0.