Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท crypto

Node.js KeyObject class

Reference for crypto.KeyObject in Node.js: secret, public and private key handles, createSecretKey, createPublicKey, createPrivateKey, export formats and key details.

A KeyObject is an opaque handle to a cryptographic key held by Node.js. Instead of passing raw bytes or PEM strings around, you create a key object once and hand it to functions such as createCipheriv(), createHmac() or sign(). There are three types: 'secret' (symmetric), 'public' and 'private'.

Key objects are created with crypto.createSecretKey(), crypto.createPublicKey(), crypto.createPrivateKey() or by generateKey, generateKeyPair and their sync forms. Parsing happens once, and you can choose whether the key may ever be exported.

NODE
import { createSecretKey, randomBytes } from 'node:crypto';

const key = createSecretKey(randomBytes(32));
console.log(key.type, key.symmetricKeySize);

Try it

Node.js Secret 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.

Node.js Public and 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.createSecretKey(key: Buffer | string | TypedArray | DataView, encoding?): KeyObject
crypto.createPublicKey(key: string | Buffer | KeyObject | object): KeyObject
crypto.createPrivateKey(key: string | Buffer | object): KeyObject

keyObject.type                       // 'secret' | 'public' | 'private'
keyObject.symmetricKeySize           // bytes (secret keys only)
keyObject.asymmetricKeyType          // 'rsa', 'ec', 'ed25519', 'x25519', ...
keyObject.asymmetricKeyDetails       // modulusLength, namedCurve, ...
keyObject.export(options?): string | Buffer | object
keyObject.equals(otherKeyObject): boolean
Option of export() Description
format 'pem', 'der' or 'jwk'. Secret keys also support 'buffer' (the default).
type For public keys 'spki' or 'pkcs1' (RSA only). For private keys 'pkcs8', 'pkcs1' (RSA) or 'sec1' (EC).
cipher, passphrase Encrypt a private key's PEM or DER export (PKCS#8 and others) with the given cipher and passphrase.

asymmetricKeyDetails holds modulusLength and publicExponent for RSA, namedCurve for EC, and similar fields for other algorithms.

Errors: ERR_INVALID_ARG_VALUE for unsupported export options (for example a private format on a public key), ERR_OSSL_* errors when PEM or DER input cannot be parsed, including when you import an encrypted private key without its passphrase.

Usage notes

  • Prefer key objects over raw strings. The key is parsed once, you can inspect type and asymmetricKeyType before use, and algorithm functions check them for compatibility.
  • createPublicKey() accepts a private key. It derives the matching public key, which is the usual way to publish a verification key.
  • Encrypt private keys at rest. Export with { type: 'pkcs8', format: 'pem', cipher: 'aes-256-cbc', passphrase } before storing a key on disk.
  • equals() compares key material, not object identity or encoding. Two objects from different PEM layouts of the same key are equal.
  • JWK output (format: 'jwk') matches the JSON Web Key standard and is handy for JWT work.
  • Structured clone and workers. Key objects can be passed to worker threads with postMessage; the handle is cloned, not serialized to bytes.
  • Secret key lengths must match what the algorithm needs (32 bytes for AES-256). createSecretKey itself does not check the length against any algorithm.
  • Added in Node.js 11.6.0; equals() in 17.7.0.