CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-node-forge

JavaScript implementations of network transports, cryptography, ciphers, PKI, message digests, and various utilities.

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

pki.mddocs/

Public Key Infrastructure

Certificate management, PEM/DER conversion, and X.509 certificate creation and validation. Node-forge provides comprehensive PKI functionality for working with certificates, certificate authorities, and public/private key formats.

Capabilities

Certificate Creation

Create new X.509 certificates with full control over all certificate fields.

/**
 * Create a new empty X.509 certificate
 * @returns Certificate object ready for configuration
 */
forge.pki.createCertificate(): Certificate;

interface Certificate {
  /** Certificate version (typically 0x02 for v3) */
  version: number;
  /** Serial number as hex string */
  serialNumber: string;
  /** Signature algorithm OID */
  signatureOid: string | null;
  /** Certificate signature */
  signature: string | null;
  /** Signature algorithm information */
  siginfo: {
    algorithmOid: string | null;
  };
  /** Certificate validity period */
  validity: {
    notBefore: Date;
    notAfter: Date;
  };
  /** Certificate issuer (CA) information */
  issuer: CertificateSubject;
  /** Certificate subject information */
  subject: CertificateSubject;
  /** Certificate extensions array */
  extensions: CertificateExtension[];
  /** Public key associated with certificate */
  publicKey: PublicKey;
  /** Message digest used for signing */
  md: MessageDigest | null;
  
  /**
   * Set certificate subject
   * @param attrs - Array of subject attributes
   * @param uniqueId - Optional unique identifier
   */
  setSubject(attrs: SubjectAttribute[], uniqueId?: string): void;
  
  /**
   * Set certificate issuer
   * @param attrs - Array of issuer attributes
   * @param uniqueId - Optional unique identifier
   */
  setIssuer(attrs: SubjectAttribute[], uniqueId?: string): void;
  
  /**
   * Set certificate extensions
   * @param exts - Array of extensions
   */
  setExtensions(exts: CertificateExtension[]): void;
  
  /**
   * Sign the certificate with a private key
   * @param privateKey - Private key for signing
   * @param md - Message digest to use (default: SHA-256)
   */
  sign(privateKey: PrivateKey, md?: MessageDigest): void;
  
  /**
   * Verify certificate signature against a CA store
   * @param caStore - Array of trusted CA certificates
   * @returns True if certificate is valid
   */
  verify(caStore: Certificate[]): boolean;
}

interface CertificateSubject {
  /** Subject/issuer attributes */
  attributes: SubjectAttribute[];
  /** Subject/issuer hash */
  hash: string | null;
  
  /**
   * Get attribute by short name
   * @param sn - Short name (e.g., 'CN', 'O', 'OU')
   * @returns Attribute object or null
   */
  getField(sn: string): SubjectAttribute | null;
  
  /**
   * Add new attribute
   * @param attr - Attribute to add
   */
  addField(attr: SubjectAttribute): void;
}

interface SubjectAttribute {
  /** Attribute name */
  name: string;
  /** Attribute short name */
  shortName?: string;
  /** Attribute value */
  value: string;
  /** Attribute type (for custom attributes) */
  type?: string;
}

Usage Examples:

const forge = require('node-forge');

// Generate key pair for certificate
const keypair = forge.pki.rsa.generateKeyPair(2048);

// Create certificate
const cert = forge.pki.createCertificate();
cert.publicKey = keypair.publicKey;
cert.serialNumber = '01';
cert.validity.notBefore = new Date();
cert.validity.notAfter = new Date();
cert.validity.notAfter.setFullYear(cert.validity.notBefore.getFullYear() + 1);

// Set subject (entity the certificate represents)
cert.subject.attributes.push({
  name: 'commonName',
  value: 'example.com'
}, {
  name: 'countryName',
  value: 'US'
}, {
  shortName: 'ST',
  value: 'Virginia'
}, {
  name: 'localityName',
  value: 'Blacksburg'
}, {
  name: 'organizationName',
  value: 'Test'
}, {
  shortName: 'OU',
  value: 'Test'
});

// Set issuer (self-signed)
cert.issuer.attributes = cert.subject.attributes;

// Sign certificate
cert.sign(keypair.privateKey, forge.md.sha256.create());

PEM Format Conversion

Convert between PEM text format and JavaScript objects for certificates and keys.

/**
 * Convert certificate from PEM format
 * @param pem - PEM-encoded certificate string
 * @param computeHash - Whether to compute subject/issuer hashes
 * @param strict - Strict parsing mode
 * @returns Certificate object
 */
forge.pki.certificateFromPem(pem: string, computeHash?: boolean, strict?: boolean): Certificate;

/**
 * Convert certificate to PEM format
 * @param certificate - Certificate object to convert
 * @param maxline - Maximum line length for PEM output
 * @returns PEM-encoded certificate string
 */
forge.pki.certificateToPem(certificate: Certificate, maxline?: number): string;

/**
 * Convert private key from PEM format
 * @param pem - PEM-encoded private key string
 * @returns Private key object
 */
forge.pki.privateKeyFromPem(pem: string): PrivateKey;

/**
 * Convert private key to PEM format
 * @param privateKey - Private key object
 * @param maxline - Maximum line length for PEM output
 * @returns PEM-encoded private key string
 */
forge.pki.privateKeyToPem(privateKey: PrivateKey, maxline?: number): string;

/**
 * Convert public key from PEM format
 * @param pem - PEM-encoded public key string
 * @returns Public key object
 */
forge.pki.publicKeyFromPem(pem: string): PublicKey;

/**
 * Convert public key to PEM format
 * @param publicKey - Public key object
 * @param maxline - Maximum line length for PEM output
 * @returns PEM-encoded public key string
 */
forge.pki.publicKeyToPem(publicKey: PublicKey, maxline?: number): string;

Usage Examples:

// Certificate PEM conversion
const certPem = forge.pki.certificateToPem(cert);
console.log('Certificate PEM:\n' + certPem);

// Load certificate from PEM
const loadedCert = forge.pki.certificateFromPem(certPem);

// Private key PEM conversion
const privateKeyPem = forge.pki.privateKeyToPem(keypair.privateKey);
const loadedPrivateKey = forge.pki.privateKeyFromPem(privateKeyPem);

// Public key PEM conversion
const publicKeyPem = forge.pki.publicKeyToPem(keypair.publicKey);
const loadedPublicKey = forge.pki.publicKeyFromPem(publicKeyPem);

ASN.1 Format Conversion

Convert between ASN.1 DER format and JavaScript objects for low-level certificate operations.

/**
 * Convert certificate to ASN.1 format
 * @param certificate - Certificate object
 * @returns ASN.1 representation
 */
forge.pki.certificateToAsn1(certificate: Certificate): ASN1;

/**
 * Convert certificate from ASN.1 format
 * @param asn1 - ASN.1 certificate representation
 * @returns Certificate object
 */
forge.pki.certificateFromAsn1(asn1: ASN1): Certificate;

/**
 * Convert private key to ASN.1 format
 * @param privateKey - Private key object
 * @returns ASN.1 representation
 */
forge.pki.privateKeyToAsn1(privateKey: PrivateKey): ASN1;

/**
 * Convert private key from ASN.1 format
 * @param asn1 - ASN.1 private key representation
 * @returns Private key object
 */
forge.pki.privateKeyFromAsn1(asn1: ASN1): PrivateKey;

/**
 * Convert public key to ASN.1 format
 * @param publicKey - Public key object
 * @returns ASN.1 representation
 */
forge.pki.publicKeyToAsn1(publicKey: PublicKey): ASN1;

/**
 * Convert public key from ASN.1 format
 * @param asn1 - ASN.1 public key representation
 * @returns Public key object
 */
forge.pki.publicKeyFromAsn1(asn1: ASN1): PublicKey;

Certificate Extensions

Standard X.509 certificate extensions for enhanced functionality.

interface CertificateExtension {
  /** Extension name or OID */
  name: string;
  /** Extension identifier */
  id?: string;
  /** Critical flag */
  critical?: boolean;
  /** Extension value */
  value?: any;
  /** Alternative names (for Subject Alternative Name) */
  altNames?: AltName[];
  /** Key usage flags */
  keyCertSign?: boolean;
  digitalSignature?: boolean;
  nonRepudiation?: boolean;
  keyEncipherment?: boolean;
  dataEncipherment?: boolean;
  keyAgreement?: boolean;
  keyCertSign?: boolean;
  cRLSign?: boolean;
  encipherOnly?: boolean;
  decipherOnly?: boolean;
}

interface AltName {
  /** Name type (1=email, 2=DNS, 6=URI, 7=IP) */
  type: number;
  /** Name value */
  value: string;
  /** IP address as bytes (for type 7) */
  ip?: string;
}

Usage Examples:

// Add certificate extensions
cert.setExtensions([
  {
    name: 'basicConstraints',
    cA: true
  },
  {
    name: 'keyUsage',
    keyCertSign: true,
    digitalSignature: true,
    nonRepudiation: true,
    keyEncipherment: true,
    dataEncipherment: true
  },
  {
    name: 'extKeyUsage',
    serverAuth: true,
    clientAuth: true,
    codeSigning: true,
    emailProtection: true,
    timeStamping: true
  },
  {
    name: 'subjectAltName',
    altNames: [{
      type: 2, // DNS
      value: 'example.com'
    }, {
      type: 2, // DNS
      value: 'www.example.com'
    }, {
      type: 7, // IP
      ip: '127.0.0.1'
    }]
  }
]);

Certificate Verification

Verify certificate chains and validate certificate properties.

/**
 * Create a certificate store for verification
 * @param certs - Array of trusted CA certificates
 * @returns Certificate store object
 */
forge.pki.createCertificateStore(certs?: Certificate[]): CertificateStore;

interface CertificateStore {
  /**
   * Add certificate to store
   * @param cert - Certificate to add
   */
  addCertificate(cert: Certificate | string): void;
  
  /**
   * Get certificate by subject hash
   * @param hash - Subject hash
   * @returns Certificate or null
   */
  getCertificate(hash: string): Certificate | null;
  
  /** Array of certificates in store */
  certs: Certificate[];
}

/**
 * Verify certificate chain
 * @param caStore - Certificate store with trusted CAs
 * @param chain - Certificate chain to verify
 * @param options - Verification options
 * @returns True if chain is valid
 */
forge.pki.verifyCertificateChain(
  caStore: CertificateStore,
  chain: Certificate[],
  options?: VerificationOptions
): boolean;

interface VerificationOptions {
  /** Verify certificate validity dates */
  verify?: (verified: boolean, depth: number, chain: Certificate[]) => boolean;
  /** Validation date (default: now) */
  validityCheckDate?: Date;
}

Usage Examples:

// Create certificate store with trusted CAs
const caStore = forge.pki.createCertificateStore();
caStore.addCertificate(caCert);

// Verify certificate
const verified = cert.verify(caStore);
console.log('Certificate verified:', verified);

// Verify certificate chain
const chain = [cert, intermediateCert];
const chainVerified = forge.pki.verifyCertificateChain(caStore, chain);
console.log('Chain verified:', chainVerified);

// Custom verification with date checking
const customVerified = forge.pki.verifyCertificateChain(caStore, chain, {
  verify: (verified, depth, chain) => {
    console.log(`Depth ${depth}: ${verified ? 'OK' : 'FAIL'}`);
    return verified;
  },
  validityCheckDate: new Date('2023-01-01')
});

Certificate Signing Request (CSR)

Create and process certificate signing requests.

/**
 * Create certificate signing request
 * @returns CSR object
 */
forge.pki.createCertificationRequest(): CertificationRequest;

interface CertificationRequest {
  /** CSR version */
  version: number;
  /** Subject information */
  subject: CertificateSubject;
  /** Public key */
  publicKey: PublicKey;
  /** Signature */
  signature: string | null;
  /** Signature algorithm */
  signatureOid: string | null;
  /** CSR attributes */
  attributes: any[];
  
  /**
   * Sign the CSR with private key
   * @param privateKey - Private key for signing
   * @param md - Message digest (default: SHA-256)
   */
  sign(privateKey: PrivateKey, md?: MessageDigest): void;
  
  /**
   * Verify CSR signature
   * @returns True if signature is valid
   */
  verify(): boolean;
}

/**
 * Convert CSR to PEM format
 * @param csr - CSR object
 * @param maxline - Maximum line length
 * @returns PEM-encoded CSR
 */
forge.pki.certificationRequestToPem(csr: CertificationRequest, maxline?: number): string;

/**
 * Convert CSR from PEM format
 * @param pem - PEM-encoded CSR
 * @returns CSR object
 */
forge.pki.certificationRequestFromPem(pem: string): CertificationRequest;

Usage Examples:

// Create certificate signing request
const csr = forge.pki.createCertificationRequest();
csr.publicKey = keypair.publicKey;

// Set CSR subject
csr.subject.attributes.push({
  name: 'commonName',
  value: 'example.com'
}, {
  name: 'organizationName',
  value: 'Example Corp'
});

// Sign CSR
csr.sign(keypair.privateKey, forge.md.sha256.create());

// Convert to PEM
const csrPem = forge.pki.certificationRequestToPem(csr);
console.log('CSR PEM:\n' + csrPem);

// Verify CSR
const isValid = csr.verify();
console.log('CSR valid:', isValid);

Error Handling

Handle common PKI operation errors.

try {
  // Certificate operations
  const cert = forge.pki.createCertificate();
  cert.sign(privateKey);
  
  // PEM conversion
  const pem = forge.pki.certificateToPem(cert);
  const loadedCert = forge.pki.certificateFromPem(pem);
  
  // Verification
  const verified = cert.verify(caStore);
  
} catch (error) {
  // Handle errors:
  // - Invalid PEM format
  // - Missing required certificate fields
  // - Invalid signatures
  // - Expired certificates
  // - Untrusted certificate chains
  // - Malformed ASN.1 structures
  console.error('PKI operation failed:', error.message);
}

docs

asn1.md

asymmetric-cryptography.md

index.md

logging.md

message-digests.md

network-http.md

pkcs.md

pki.md

random.md

symmetric-encryption.md

tls.md

utilities.md

web-forms.md

tile.json