Keys

The Keys module manages the creation, import, export, and conversion of cryptographic keys. It supports asymmetric keys (RSA, EC, Ed25519) and symmetric keys (secret objects).

Table of Contents

• Theory
• Class: KeyObject
• Module Methods
• Real-World Examples

Theory

Cryptography relies on Symmetric and Asymmetric keys.

• Symmetric Keys: A single secret string (e.g., 32 random bytes) used for both encryption and decryption (AES).
• Asymmetric Keys: A pair of keys.
  • Public Key: Shared openly. Used to encrypt messages for the owner or verify the owner's signature.
  • Private Key: Kept secret. Used to decrypt messages sent to the owner or create digital signatures.

Keys are stored in various container formats:

• PEM: Textual format (-----BEGIN PUBLIC KEY-----).
• DER: Binary format.
• PKCS#8: The standard container for private keys.
• SPKI: The standard container for public keys.

Class: KeyObject

The KeyObject class is a handle to a native C++ key. It allows the JavaScript layer to refer to keys without copying the key material (which might be sensitive) into the JS garbage-collected heap.

Properties

keyObject.export(options)

Exports the key to a Buffer or string.

Parameters:

Returns: string | Buffer

Example:

import { generateKeyPairSync } from 'react-native-quick-crypto';

const { privateKey, publicKey } = generateKeyPairSync('rsa', {
  modulusLength: 2048,
});

const pem = privateKey.export({
  type: 'pkcs8',
  format: 'pem'
});

Module Methods

generateKeyPair(type, options, callback)

Generates a new asymmetric key pair on a background thread.

Parameters:

Example (RSA 4096):

import { generateKeyPair } from 'react-native-quick-crypto';

generateKeyPair('rsa', {
  modulusLength: 4096,
  publicKeyEncoding: {
    type: 'spki',
    format: 'pem'
  },
  privateKeyEncoding: {
    type: 'pkcs8',
    format: 'pem',
    cipher: 'aes-256-cbc',
    passphrase: 'strong-pass' 
  }
}, (err, pubKey, privKey) => {
  // keys are PEM strings
});

createPublicKey(key)

Converts a key representation into a KeyObject. It automatically detects if the input is PEM, DER, or another KeyObject.

Parameters:

Returns: KeyObject (type: 'public')

createPrivateKey(key)

Converts a key representation into a KeyObject.

Parameters:

Example (Decrypting a Key):

const privKey = createPrivateKey({
  key: encryptedPemString,
  passphrase: 'user-password'
});

createSecretKey(key)

Creates a symmetric KeyObject.

Example:

import { createSecretKey, randomBytes } from 'react-native-quick-crypto';

const rawKey = randomBytes(32);
const secret = createSecretKey(rawKey);

generateKey(type, options, callback)

Asynchronously generates a new symmetric key of the given type.

Parameters:

Example:

import { generateKey } from 'react-native-quick-crypto';

generateKey('aes', { length: 256 }, (err, key) => {
  // key is a KeyObject (type: 'secret')
  console.log(key.export().toString('hex'));
});

generateKeySync(type, options)

Synchronously generates a new symmetric key.

Returns: KeyObject

Real-World Examples

Rotating API Keys

Generating a new Ed25519 signing pair for an API client.

import { generateKeyPairSync } from 'react-native-quick-crypto';

function rotateIdentity() {
    const { publicKey, privateKey } = generateKeyPairSync('ed25519');
    
    return {
        pub: publicKey.export({ type: 'spki', format: 'pem' }),
        priv: privateKey.export({ type: 'pkcs8', format: 'pem' })
    };
}