@sigstore/sign v2.3.0

@sigstore/sign ·

A library for generating Sigstore signatures.

Features

• Support for keyless signature generation with Fulcio-issued signing certificates
• Support for ambient OIDC credential detection in CI/CD environments
• Support for recording signatures to the Rekor transparency log
• Support for requesting timestamped countersignature from a Timestamp Authority

Prerequisites

• Node.js version >= 16.14.0

Installation

npm install @sigstore/sign

Overview

This library provides the building blocks for composing custom Sigstore signing workflows.

BundleBuilder

The top-level component is the BundleBuilder which has responsibility for taking some artifact and returning a Sigstore bundle containing the signature for that artifact and the various materials necessary to verify that signature.

interface BundleBuilder {
  create: (artifact: Artifact) => Promise<Bundle>;
}

The artifact to be signed is simply an array of bytes and an optional mimetype. The type is necessary when the signature is packaged as a DSSE envelope.

type Artifact = {
  data: Buffer;
  type?: string;
};

There are two BundleBuilder implementations provided as part of this package:

• DSSEBundleBuilder - Combines the verification material and artifact signature into a dsse_envelope -style Sigstore bundle
• MessageBundleBuilder - Combines the verification material and artifact signature into a message_signature-style Sigstore bundle.

Signer

Every BundleBuilder must be instantiated with a Signer implementation. The Signer is responsible for taking a Buffer and returning an Signature.

interface Signer {
  sign: (data: Buffer) => Promise<Signature>;
}

The returned Signature contains a signature and the public key which can be used to verify that signature -- the key may either take the form of a x509 certificate or public key.

type Signature = {
  signature: Buffer;
  key: KeyMaterial;
};

type KeyMaterial =
  | {
      $case: 'x509Certificate';
      certificate: string;
    }
  | {
      $case: 'publicKey';
      publicKey: string;
      hint?: string;
    };

This package provides the FulcioSigner which implements the Signer interface and signs the artifact with an ephemeral keypair. It will also retrieve an OIDC token from the configured IdentityProvider and then request a signing certificate from Fulcio which binds the ephemeral key to the identity embedded in the token. This signing certificate is returned as part of the Signature.

Witness

The BundleBuilder may also be configured with zero-or-more Witness instances. Each Witness receives the artifact signature and the public key and returns an VerificationMaterial which represents some sort of counter-signature for the artifact's signature.

interface Witness {
  testify: (
    signature: SignatureBundle,
    publicKey: string
  ) => Promise<VerificationMaterial>;
}

The returned VerificationMaterial may contain either Rekor transparency log entries or RFC3161 timestamps.

type VerificationMaterial = {
  tlogEntries?: TransparencyLogEntry[];
  rfc3161Timestamps?: RFC3161SignedTimestamp[];
};

The entries in the returned VerificationMaterial are automatically added to the Sigstore Bundle by the BundleBuilder.

The package provides two different Witness implementations:

• RekorWitness - Adds an entry to the Rekor transparency log and returns a TransparencyLogEntry to be included in the Bundle
• TSAWitness - Requests an RFC3161 timestamp over the artifact signature and returns an RFC3161SignedTimestamp to be included in the Bundle

Usage Example

const {
  CIContextProvider,
  DSSEBundleBuilder,
  FulcioSigner,
  RekorWitness,
  TSAWitness,
} = require('@sigstore/sign');

// Set-up the signer
const signer = new FulcioSigner({
  fulcioBaseURL: 'https://fulcio.sigstore.dev',
  identityProvider: new CIContextProvider('sigstore'),
});

// Set-up the witnesses
const rekorWitness = new RekorWitness({
  rekorBaseURL: 'https://rekor.sigstore.dev',
});

const tsaWitness = new TSAWitness({
  tsaBaseURL: 'https://tsa.github.com',
});

// Instantiate a bundle builder
const bundler = new DSSEBundleBuilder({
  signer,
  witnesses: [rekorWitness, tsaWitness],
});

// Sign a thing
const artifact = {
  type: 'text/plain',
  data: Buffer.from('something to be signed'),
};
const bundle = await bundler.create(artifact);