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

tls.mddocs/

TLS Implementation

Complete TLS client and server implementation for secure network communications. Node-forge provides a pure JavaScript TLS implementation supporting multiple versions and cipher suites for secure data transmission.

Capabilities

TLS Connection Creation

Create TLS client and server connections with configurable security parameters.

/**
 * Create TLS connection
 * @param options - TLS connection options
 * @returns TLS connection object
 */
forge.tls.createConnection(options: TLSConnectionOptions): TLSConnection;

interface TLSConnectionOptions {
  /** True for server mode, false for client mode */
  server?: boolean;
  /** Session ID for session resumption */
  sessionId?: string;
  /** Certificate store for trusted CAs */
  caStore?: Certificate[] | CertificateStore;
  /** Supported cipher suites */
  cipherSuites?: CipherSuite[];
  /** Supported TLS versions */
  virtualHost?: string;
  /** Verify callback for certificate validation */
  verify?: (connection: TLSConnection, verified: boolean, depth: number, certs: Certificate[]) => boolean;
  /** Connected callback */
  connected?: (connection: TLSConnection) => void;
  /** TLS ready callback */
  tlsDataReady?: (connection: TLSConnection) => void;
  /** Data ready callback */
  dataReady?: (connection: TLSConnection) => void;
  /** Closed callback */
  closed?: (connection: TLSConnection) => void;
  /** Error callback */
  error?: (connection: TLSConnection, error: any) => void;
  /** Get certificate callback (for server) */
  getCertificate?: (connection: TLSConnection, hint: any) => Certificate;
  /** Get private key callback (for server) */
  getPrivateKey?: (connection: TLSConnection, cert: Certificate) => PrivateKey;
}

interface TLSConnection {
  /** Connection version */
  version: {major: number, minor: number};
  /** Connection state */
  state: {
    serverConnectionEnd: boolean;
    clientConnectionEnd: boolean;
    read: string;
    write: string;
  };
  /** Session information */
  session: TLSSession;
  /** Handshake state */
  handshaking: boolean;
  /** Handshake messages */
  handshakes: any;
  
  /**
   * Prepare TLS data for transmission
   * @param data - Data to send
   */
  prepare(data: string): void;
  
  /**
   * Process received TLS data
   * @param data - Received TLS data
   */
  process(data: string): void;
  
  /**
   * Close TLS connection
   * @param cleartext - True to close cleartext connection too
   */
  close(cleartext?: boolean): void;
  
  /** Buffer for TLS data ready to send */
  tlsData: ByteStringBuffer;
  /** Buffer for application data ready to read */
  data: ByteStringBuffer;
  /** True if TLS handshake is complete */
  isConnected: boolean;
  /** True if connection is closed */
  isClosed: boolean;
}

interface TLSSession {
  /** Session ID */
  id: string;
  /** TLS version */
  version: {major: number, minor: number};
  /** Negotiated cipher suite */
  cipherSuite: CipherSuite;
  /** Compression method */
  compressionMethod: number;
  /** Server certificate */
  serverCertificate: Certificate;
  /** Client certificate (if used) */
  clientCertificate?: Certificate;
}

Usage Examples:

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

// Create TLS client connection
const client = forge.tls.createConnection({
  server: false,
  caStore: [caCertificate], // Trusted CA certificates
  virtualHost: 'example.com',
  verify: (connection, verified, depth, certs) => {
    console.log(`Certificate verification: ${verified} at depth ${depth}`);
    return verified;
  },
  connected: (connection) => {
    console.log('TLS handshake complete');
    // Send application data
    connection.prepare('GET / HTTP/1.1\r\nHost: example.com\r\n\r\n');
  },
  tlsDataReady: (connection) => {
    // Send TLS data over the network
    const tlsData = connection.tlsData.getBytes();
    socket.write(tlsData);
  },
  dataReady: (connection) => {
    // Process received application data
    const appData = connection.data.getBytes();
    console.log('Received:', appData);
  },
  error: (connection, error) => {
    console.error('TLS error:', error);
  }
});

// Create TLS server connection
const server = forge.tls.createConnection({
  server: true,
  getCertificate: (connection, hint) => {
    return serverCertificate;
  },
  getPrivateKey: (connection, cert) => {
    return serverPrivateKey;
  },
  connected: (connection) => {
    console.log('Client connected via TLS');
  },
  dataReady: (connection) => {
    const request = connection.data.getBytes();
    console.log('Client request:', request);
    
    // Send HTTP response
    const response = 'HTTP/1.1 200 OK\r\nContent-Length: 12\r\n\r\nHello World!';
    connection.prepare(response);
  }
});

// Process network data
socket.on('data', (data) => {
  client.process(data.toString('binary'));
});

TLS Cipher Suites

Supported cipher suites for TLS connections with different security levels.

/**
 * Available cipher suites
 */
forge.tls.CipherSuites: {
  /** RSA with AES 128 CBC and SHA-1 */
  TLS_RSA_WITH_AES_128_CBC_SHA: [0x00, 0x2f];
  /** RSA with AES 256 CBC and SHA-1 */
  TLS_RSA_WITH_AES_256_CBC_SHA: [0x00, 0x35];
  /** RSA with AES 128 CBC and SHA-256 */
  TLS_RSA_WITH_AES_128_CBC_SHA256: [0x00, 0x3c];
  /** RSA with AES 256 CBC and SHA-256 */
  TLS_RSA_WITH_AES_256_CBC_SHA256: [0x00, 0x3d];
  /** RSA with 3DES EDE CBC and SHA-1 */
  TLS_RSA_WITH_3DES_EDE_CBC_SHA: [0x00, 0x0a];
};

interface CipherSuite {
  /** Cipher suite identifier */
  id: number[];
  /** Cipher suite name */
  name: string;
  /** Key exchange algorithm */
  keyExchange: string;
  /** Bulk cipher algorithm */
  cipher: string;
  /** MAC algorithm */
  mac: string;
  /** True if AEAD cipher */
  aead: boolean;
}

Usage Examples:

// Configure specific cipher suites
const secureConnection = forge.tls.createConnection({
  server: false,
  cipherSuites: [
    forge.tls.CipherSuites.TLS_RSA_WITH_AES_256_CBC_SHA256,
    forge.tls.CipherSuites.TLS_RSA_WITH_AES_128_CBC_SHA256
  ],
  // ... other options
});

// Get supported cipher suites
const supportedSuites = Object.keys(forge.tls.CipherSuites);
console.log('Supported cipher suites:', supportedSuites);

TLS Protocol Versions

Support for multiple TLS protocol versions with version negotiation.

/**
 * TLS version constants
 */
forge.tls.Versions: {
  TLS_1_0: {major: 3, minor: 1};
  TLS_1_1: {major: 3, minor: 2};
  TLS_1_2: {major: 3, minor: 3};
};

/**
 * Supported TLS versions array
 */
forge.tls.SupportedVersions: Array<{major: number, minor: number}>;

Usage Examples:

// Force specific TLS version
const tlsConnection = forge.tls.createConnection({
  server: false,
  version: forge.tls.Versions.TLS_1_2, // Force TLS 1.2
  // ... other options
});

// Check negotiated version
connection.connected = (conn) => {
  console.log(`Connected using TLS ${conn.version.major}.${conn.version.minor}`);
};

TLS Record Layer

Low-level TLS record layer operations for custom TLS implementations.

/**
 * TLS content types
 */
forge.tls.ContentType: {
  change_cipher_spec: 20;
  alert: 21;
  handshake: 22;
  application_data: 23;
  heartbeat: 24;
};

/**
 * TLS handshake types
 */
forge.tls.HandshakeType: {
  hello_request: 0;
  client_hello: 1;
  server_hello: 2;
  certificate: 11;
  server_key_exchange: 12;
  certificate_request: 13;
  server_hello_done: 14;
  certificate_verify: 15;
  client_key_exchange: 16;
  finished: 20;
};

/**
 * TLS alert levels and descriptions
 */
forge.tls.Alert: {
  Level: {
    warning: 1;
    fatal: 2;
  };
  Description: {
    close_notify: 0;
    unexpected_message: 10;
    bad_record_mac: 20;
    record_overflow: 22;
    handshake_failure: 40;
    bad_certificate: 42;
    certificate_expired: 45;
    certificate_unknown: 46;
    internal_error: 80;
  };
};

TLS Session Management

Manage TLS sessions for connection resumption and performance optimization.

/**
 * Session cache for TLS resumption
 */
interface SessionCache {
  /** Cache session */
  setSession(id: string, session: TLSSession): void;
  /** Retrieve session */
  getSession(id: string): TLSSession | null;
  /** Remove session */
  removeSession(id: string): void;
  /** Clear all sessions */
  clear(): void;
}

/**
 * Create session cache
 */
function createSessionCache(): SessionCache;

Usage Examples:

// Create session cache for resumption
const sessionCache = {
  sessions: new Map(),
  
  setSession(id, session) {
    this.sessions.set(id, {
      ...session,
      timestamp: Date.now()
    });
  },
  
  getSession(id) {
    const session = this.sessions.get(id);
    if (session && Date.now() - session.timestamp < 24 * 60 * 60 * 1000) { // 24 hours
      return session;
    }
    this.sessions.delete(id);
    return null;
  },
  
  removeSession(id) {
    this.sessions.delete(id);
  },
  
  clear() {
    this.sessions.clear();
  }
};

// Use session cache with TLS connection
const connection = forge.tls.createConnection({
  server: true,
  sessionCache: sessionCache,
  // ... other options
});

TLS Extensions

Support for TLS extensions including SNI (Server Name Indication).

/**
 * Server Name Indication (SNI) support
 */
interface SNICallback {
  (servername: string): {
    certificate: Certificate;
    privateKey: PrivateKey;
  };
}

/**
 * TLS extension support
 */
interface TLSExtensions {
  /** Server name indication */
  server_name?: string;
  /** Application Layer Protocol Negotiation */
  application_layer_protocol_negotiation?: string[];
}

Usage Examples:

// Server with SNI support
const sniConnection = forge.tls.createConnection({
  server: true,
  getCertificate: (connection, hint) => {
    const servername = hint.server_name || 'default';
    const certs = {
      'example.com': exampleCert,
      'test.com': testCert,
      'default': defaultCert
    };
    return certs[servername] || certs.default;
  },
  getPrivateKey: (connection, cert) => {
    // Return corresponding private key
    return privateKeys[cert.subject.getField('CN').value] || defaultPrivateKey;
  }
});

// Client with SNI
const sniClient = forge.tls.createConnection({
  server: false,
  virtualHost: 'example.com', // Enables SNI
  // ... other options
});

Error Handling and Debugging

Handle TLS errors and debug connection issues.

// Comprehensive error handling
const connection = forge.tls.createConnection({
  server: false,
  verify: (connection, verified, depth, certs) => {
    if (!verified) {
      console.warn(`Certificate verification failed at depth ${depth}`);
      // Log certificate details for debugging
      certs.forEach((cert, index) => {
        console.log(`Certificate ${index}:`, {
          subject: cert.subject.getField('CN')?.value,
          issuer: cert.issuer.getField('CN')?.value,
          validity: {
            notBefore: cert.validity.notBefore,
            notAfter: cert.validity.notAfter
          }
        });
      });
    }
    return verified; // or return true to ignore certificate errors (not recommended)
  },
  error: (connection, error) => {
    console.error('TLS Error:', {
      message: error.message,
      alertLevel: error.level,
      alertDescription: error.description
    });
    
    // Handle specific error types
    if (error.description === forge.tls.Alert.Description.certificate_expired) {
      console.error('Server certificate has expired');
    } else if (error.description === forge.tls.Alert.Description.handshake_failure) {
      console.error('TLS handshake failed - check cipher suite compatibility');
    }
  },
  closed: (connection) => {
    console.log('TLS connection closed');
    if (connection.error) {
      console.log('Connection closed due to error:', connection.error);
    }
  }
});

// Debug handshake process
connection.handshaking = true;
connection.handshakes = forge.tls.createHandshakes(connection);

// Monitor handshake messages
const originalProcess = connection.process;
connection.process = function(data) {
  console.log('Processing TLS data:', data.length, 'bytes');
  const result = originalProcess.call(this, data);
  
  if (this.handshaking) {
    console.log('Handshake state:', this.state);
  }
  
  return result;
};

try {
  // TLS operations
  connection.process(tlsData);
  connection.prepare(applicationData);
  
} catch (error) {
  // Handle errors:
  // - Handshake failures
  // - Certificate verification errors
  // - Protocol version mismatches
  // - Cipher suite incompatibilities
  // - Network connectivity issues
  console.error('TLS operation failed:', error.message);
}

Performance Optimization

Optimize TLS connections for better performance.

Usage Examples:

// Connection pooling for clients
class TLSConnectionPool {
  constructor(options) {
    this.options = options;
    this.connections = new Map();
    this.maxConnections = 10;
  }
  
  getConnection(host) {
    if (!this.connections.has(host)) {
      const connection = forge.tls.createConnection({
        ...this.options,
        virtualHost: host
      });
      this.connections.set(host, connection);
    }
    return this.connections.get(host);
  }
  
  closeAll() {
    for (const [host, connection] of this.connections) {
      connection.close();
    }
    this.connections.clear();
  }
}

// Optimized buffer management
function optimizedTLSHandler(connection) {
  let dataBuffer = forge.util.createBuffer();
  
  connection.dataReady = (conn) => {
    // Accumulate data to reduce processing overhead
    dataBuffer.putBytes(conn.data.getBytes());
    
    // Process complete messages
    while (dataBuffer.length() >= expectedMessageLength) {
      const message = dataBuffer.getBytes(expectedMessageLength);
      processMessage(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