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.
import { createSecretKey, randomBytes } from 'node:crypto'; const key = createSecretKey(randomBytes(32)); console.log(key.type, key.symmetricKeySize);
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.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
typeandasymmetricKeyTypebefore 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).
createSecretKeyitself does not check the length against any algorithm. - Added in Node.js 11.6.0;
equals()in 17.7.0.