or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-selfsigned

Generate self signed x509 certificate from node.js

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/selfsigned@3.0.x

To install, run

npx @tessl/cli install tessl/npm-selfsigned@3.0.0

index.mddocs/

Selfsigned

Overview

Selfsigned is a Node.js library for generating self-signed X.509 certificates with private and public key pairs. It provides both synchronous and asynchronous certificate generation capabilities, supports various cryptographic algorithms, and includes options for client certificates and PKCS#7 format output.

Package Information

  • Package Name: selfsigned
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install selfsigned

Core Imports

const selfsigned = require('selfsigned');

ES Modules:

import * as selfsigned from 'selfsigned';
// or
import { generate } from 'selfsigned';

Basic Usage

const selfsigned = require('selfsigned');

// Basic certificate generation with default attributes
const attrs = [{ name: 'commonName', value: 'contoso.com' }];
const pems = selfsigned.generate(attrs, { days: 365 });

console.log(pems.private);  // Private key PEM
console.log(pems.public);   // Public key PEM  
console.log(pems.cert);     // Certificate PEM
console.log(pems.fingerprint); // SHA-1 fingerprint

Capabilities

Certificate Generation

Generates self-signed X.509 certificates with private/public key pairs. Supports both synchronous and asynchronous operation modes.

/**
 * Generate self-signed certificate with private/public key pair
 * @param attrs - Certificate attributes for subject and issuer
 * @param options - Configuration options for certificate generation
 * @returns Certificate generation result with PEM-encoded keys and certificate
 */
function generate(attrs?: CertificateField[], options?: SelfsignedOptions): GenerateResult;

/**
 * Generate self-signed certificate asynchronously
 * @param attrs - Certificate attributes for subject and issuer  
 * @param options - Configuration options for certificate generation
 * @param done - Callback function receiving error and result
 */
function generate(
  attrs?: CertificateField[], 
  options?: SelfsignedOptions, 
  done?: (err: Error | undefined, result: GenerateResult) => void
): void;

/**
 * Generate with callback only (using default attributes)
 * @param done - Callback function receiving error and result
 */
function generate(done: (err: Error | undefined, result: GenerateResult) => void): void;

/**
 * Generate with options and callback (using default attributes)
 * @param options - Configuration options for certificate generation
 * @param done - Callback function receiving error and result
 */
function generate(
  options: SelfsignedOptions, 
  done: (err: Error | undefined, result: GenerateResult) => void
): void;

Usage Examples:

// Synchronous generation
const pems = selfsigned.generate(attrs, { days: 365, keySize: 2048 });

// Asynchronous generation
selfsigned.generate(attrs, { days: 365 }, function (err, pems) {
  if (err) throw err;
  console.log(pems);
});

// With default attributes
const defaultPems = selfsigned.generate();

// Callback only with defaults
selfsigned.generate(function (err, pems) {
  if (err) throw err;
  console.log(pems);
});

// Advanced options
const advancedPems = selfsigned.generate(null, {
  keySize: 2048,
  days: 30,
  algorithm: 'sha256',
  extensions: [{ name: 'basicConstraints', cA: true }],
  pkcs7: true,
  clientCertificate: true,
  clientCertificateCN: 'jdoe'
});

Types

/**
 * ASN.1 class identifiers for certificate fields
 */
enum ASN1Class {
  UNIVERSAL = 0x00,
  APPLICATION = 0x40, 
  CONTEXT_SPECIFIC = 0x80,
  PRIVATE = 0xc0
}

/**
 * Base options for certificate field configuration
 */
interface CertificateFieldOptions {
  /** Field name identifier */
  name?: string;
  /** Field type */
  type?: string;
  /** Short name for the field */
  shortName?: string;
}

/**
 * Certificate attribute field for subject and issuer information
 */
interface CertificateField extends CertificateFieldOptions {
  /** Whether the value is constructed */
  valueConstructed?: boolean;
  /** ASN.1 value tag class */
  valueTagClass?: ASN1Class;
  /** Field value (array, string, or other types) */
  value?: any[] | string;
  /** Certificate extensions */
  extensions?: any[];
}

/**
 * Configuration options for certificate generation
 */
interface SelfsignedOptions {
  /** Number of days before certificate expiration (default: 365) */
  days?: number;
  /** Date before which certificate should not be valid (default: now) */
  notBeforeDate?: Date;
  /** Private key size in bits (default: 1024) */
  keySize?: number;
  /** Additional certificate extensions */
  extensions?: any[];
  /** Signature algorithm: 'sha256' or 'sha1' (default: 'sha1') */
  algorithm?: string;
  /** Include PKCS#7 in output (default: false) */
  pkcs7?: boolean;
  /** Generate client certificate signed by original key (default: false) */
  clientCertificate?: boolean;
  /** Client certificate common name (default: 'John Doe jdoe123') */
  clientCertificateCN?: string;
  /** Client private key size in bits (default: 1024) */
  clientCertificateKeySize?: number;
  /** Pre-existing key pair to use instead of generating new keys */
  keyPair?: {
    /** PEM-encoded private key */
    privateKey: string;
    /** PEM-encoded public key */
    publicKey: string;
  };
}

/**
 * Certificate generation result containing PEM-encoded keys and certificate
 */
interface GenerateResult {
  /** PEM-encoded private key */
  private: string;
  /** PEM-encoded public key */
  public: string;
  /** PEM-encoded X.509 certificate */
  cert: string;
  /** SHA-1 fingerprint of the certificate */
  fingerprint: string;
  /** Client private key (when clientCertificate: true) */
  clientprivate?: string;
  /** Client public key (when clientCertificate: true) */
  clientpublic?: string;
  /** Client certificate (when clientCertificate: true) */
  clientcert?: string;
  /** PKCS#7 format output (when pkcs7: true) */
  pkcs7?: string;
  /** Client PKCS#7 format (when both clientCertificate and pkcs7: true) */
  clientpkcs7?: string;
}

Common Usage Patterns

Default Certificate Generation

// Generate with minimal configuration
const pems = selfsigned.generate();
// Uses default attributes: commonName: 'example.org', countryName: 'US', etc.

Custom Certificate Attributes

const attrs = [
  { name: 'commonName', value: 'localhost' },
  { name: 'countryName', value: 'US' },
  { name: 'stateOrProvinceName', value: 'California' },
  { name: 'localityName', value: 'San Francisco' },
  { name: 'organizationName', value: 'My Company' }
];

const pems = selfsigned.generate(attrs, { days: 365 });

Client Certificate Generation

const pems = selfsigned.generate(null, { 
  clientCertificate: true,
  clientCertificateCN: 'client-user',
  clientCertificateKeySize: 2048
});

// Result includes: clientprivate, clientpublic, clientcert
console.log(pems.clientcert);

High Security Configuration

const pems = selfsigned.generate(attrs, {
  keySize: 4096,
  algorithm: 'sha256',
  days: 30,
  extensions: [
    { name: 'basicConstraints', cA: false },
    { name: 'keyUsage', digitalSignature: true, keyEncipherment: true }
  ]
});

PKCS#7 Output Format

const pems = selfsigned.generate(attrs, { 
  pkcs7: true,
  clientCertificate: true 
});

// Result includes: pkcs7, clientpkcs7
console.log(pems.pkcs7);

Using Pre-existing Key Pairs

const existingKeyPair = {
  privateKey: '-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----\n',
  publicKey: '-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----\n'
};

const pems = selfsigned.generate(attrs, { 
  keyPair: existingKeyPair,
  days: 365 
});

// Uses the provided keys instead of generating new ones