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.
import { generateKeyPairSync } from 'node:crypto'; const { publicKey, privateKey } = generateKeyPairSync('ed25519');
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.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
cipherandpassphrasetoprivateKeyEncodingbefore 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.