Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท crypto

Node.js crypto.generateKeyPair() function

Reference for crypto.generateKeyPair() and generateKeyPairSync() in Node.js: generating RSA, EC, Ed25519 and X25519 keys, encodings, passphrases and key sizes.

crypto.generateKeyPair(type, options, callback) creates a new asymmetric key pair: a private key you keep secret and a public key you can share. crypto.generateKeyPairSync() returns the pair directly and blocks until it is done. The supported types include 'rsa', 'rsa-pss', 'dsa', 'ec', 'ed25519', 'ed448', 'x25519', 'x448' and 'dh'.

Without encoding options, both keys come back as KeyObject handles. With publicKeyEncoding and privateKeyEncoding you get PEM text or DER bytes instead, ready to write to files.

NODE
import { generateKeyPairSync } from 'node:crypto';

const { publicKey, privateKey } = generateKeyPairSync('ed25519');

Try it

Node.js Key objects and PEM output

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.

Node.js Asynchronous form and encrypted private keys

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

NODE
crypto.generateKeyPair(type, options, callback): void
crypto.generateKeyPairSync(type, options?): { publicKey, privateKey }
Name Description
type 'rsa', 'rsa-pss', 'dsa', 'ec', 'ed25519', 'ed448', 'x25519', 'x448' or 'dh'.
options.modulusLength RSA, RSA-PSS and DSA: key size in bits. Required for these types; use 2048 at least, 3072 or 4096 for longer-lived keys.
options.publicExponent RSA: default 0x10001 (65537).
options.namedCurve EC: for example 'P-256', 'P-384', 'P-521' or 'secp256k1'. Required for 'ec'.
options.publicKeyEncoding { type: 'spki' | 'pkcs1', format: 'pem' | 'der' | 'jwk' }. Omit for a KeyObject.
options.privateKeyEncoding { type: 'pkcs8' | 'pkcs1' | 'sec1', format, cipher?, passphrase? }.
callback (err, publicKey, privateKey).

Returns: generateKeyPairSync returns { publicKey, privateKey }; generateKeyPair returns undefined.

Errors: ERR_INVALID_ARG_TYPE for missing or wrongly typed options (for example no modulusLength for RSA), ERR_INVALID_ARG_VALUE for values that are out of range or unsupported. Importing an encrypted private key without its passphrase fails with an OpenSSL error (the example prints ERR_OSSL_CRYPTO_INTERRUPTED_OR_CANCELLED), not a descriptive message.

Usage notes

  • Prefer Ed25519 for signatures and X25519 for key agreement unless you must interoperate with RSA or NIST curves. They are small, fast and have no size choices to get wrong.
  • RSA generation is slow. A 2048-bit key takes tens to hundreds of milliseconds, 4096-bit seconds; use the asynchronous form on a server so the event loop is not blocked.
  • PKCS#8 and SPKI are the modern, algorithm-independent encodings. Use PKCS#1 and SEC1 only when a legacy tool demands them.
  • Protect private keys. Add cipher and passphrase to privateKeyEncoding before writing to disk, and keep file permissions tight (0o600).
  • Do not set one encoding without the other if you want strings for both; whichever side lacks an encoding comes back as a KeyObject.
  • Key generation uses secure randomness from OpenSSL; you cannot seed it, which is why tests print only key properties.
  • Added in Node.js 10.12.0; Ed25519, X25519 and Ed448/X448 types in 12.0.0.