What is sigstore?
The sigstore npm package provides tools for signing, verifying, and managing software supply chain security. It is designed to help developers ensure the integrity and authenticity of their software artifacts.
What are sigstore's main functionalities?
Signing Artifacts
This feature allows you to sign software artifacts, ensuring their integrity and authenticity. The code sample demonstrates how to sign an artifact using the sigstore package.
const sigstore = require('sigstore');
async function signArtifact() {
const artifact = 'path/to/artifact';
const signature = await sigstore.sign(artifact);
console.log('Signature:', signature);
}
signArtifact();
Verifying Signatures
This feature allows you to verify the signatures of software artifacts. The code sample demonstrates how to verify an artifact's signature using the sigstore package.
const sigstore = require('sigstore');
async function verifySignature() {
const artifact = 'path/to/artifact';
const signature = 'signature-of-artifact';
const isValid = await sigstore.verify(artifact, signature);
console.log('Is valid:', isValid);
}
verifySignature();
Managing Keys
This feature allows you to generate and manage cryptographic keys. The code sample demonstrates how to generate a key pair using the sigstore package.
const sigstore = require('sigstore');
async function manageKeys() {
const keyPair = await sigstore.generateKeyPair();
console.log('Public Key:', keyPair.publicKey);
console.log('Private Key:', keyPair.privateKey);
}
manageKeys();
Other packages similar to sigstore
openpgp
The openpgp package provides tools for OpenPGP encryption and signing. It offers similar functionalities to sigstore, such as signing and verifying artifacts, but it is based on the OpenPGP standard.
node-jose
The node-jose package is a JavaScript Object Signing and Encryption (JOSE) library. It provides tools for signing, verifying, and encrypting data, similar to sigstore, but it focuses on the JOSE standards.
jsonwebtoken
The jsonwebtoken package is used for signing and verifying JSON Web Tokens (JWT). While it is primarily focused on JWTs, it offers similar signing and verification functionalities as sigstore.
sigstore-js
A JavaScript library for generating and verifying Sigstore signatures. One of
the intended uses is to sign and verify npm packages but it can be used to sign
and verify any file.
Features
- Support for signing using an OpenID Connect identity
- Support for publishing signatures to a Rekor instance
- Support for verifying Sigstore bundles
Prerequisites
- Node.js version >= 14.17.0
Installation
npm install sigstore
Usage
const { sigstore } = require('sigstore')
import { sigstore } from 'sigstore'
sign(payload[, options])
Generates a Sigstore signature for the supplied payload. Returns a
Sigstore bundle containing the signature and the verification material
necessary to verify the signature.
payload
<Buffer>
: The bytes of the artifact to be signed.options
<Object>
fulcioURL
<string>
: The base URL of the Fulcio instance to use for retrieving the signing certificate. Defaults to 'https://fulcio.sigstore.dev'
.rekorURL
<string>
: The base URL of the Rekor instance to use when adding the signature to the transparency log. Defaults to 'https://rekor.sigstore.dev'
.identityToken
<string>
: The OIDC token identifying the signer. If no explicit token is supplied, an attempt will be made to retrieve one from the environment.
attest(payload, payloadType[, options])
Generates a Sigstore signature for the supplied in-toto statement. Returns a
Sigstore bundle containing the DSSE-wrapped statement and signature
as well as the verification material necessary to verify the signature.
payload
<Buffer>
: The bytes of the statement to be signed.payloadType
<string>
: MIME or content type describing the statement to be signed.options
<Object>
fulcioURL
<string>
: The base URL of the Fulcio instance to use for retrieving the signing certificate. Defaults to 'https://fulcio.sigstore.dev'
.rekorURL
<string>
: The base URL of the Rekor instance to use when adding the signature to the transparency log. Defaults to 'https://rekor.sigstore.dev'
.identityToken
<string>
: The OIDC token identifying the signer. If no explicit token is supplied, an attempt will be made to retrieve one from the environment.
verify(bundle[, payload][, options])
Verifies the signature in the supplied bundle.
bundle
<Bundle>
: The Sigstore bundle containing the signature to be verified and the verification material necessary to verify the signature.payload
<Buffer>
: The bytes of the artifact over which the signature was created. Only necessary when the sign
function was used to generate the signature since the Bundle does not contain any information about the artifact which was signed. Not required when the attest
function was used to generate the Bundle.options
<Object>
ctLogThreshold
<number>
: The number of certificate transparency logs on which the signing certificate must appear. Defaults to 1
.tlogThreshold
<number>
: The number of transparency logs on which the signature must appear. Defaults to 1
.certificateIssuer
<string>
: Value that must appear in the signing certificate's issuer extension (OID 1.3.6.1.4.1.57264.1.1). Not verified if no value is supplied.certificateIdentityEmail
<string>
: Email address which must appear in the signing certificate's Subject Alternative Name (SAN) extension. Must be specified in conjunction with the certificateIssuer
option. Takes precedence over the certificateIdentityURI
option. Not verified if no value is supplied.certificateIdentityURI
<string>
: URI which must appear in the signing certificate's Subject Alternative Name (SAN) extension. Must be specified in conjunction with the certificateIssuer
option. Ignored if the certificateIdentityEmail
option is set. Not verified if no value is supplied.certificateOIDs
<Object>
: A collection of OID/value pairs which must be present in the certificate's extension list. Not verified if no value is supplied.keySelector
<Function>
: Callback invoked to retrieve the public key (as either string
or Buffer
) necessary to verify the bundle signature. Not used when the signature was generated from a Fulcio-issued signing certificate.
hint
<String>
: The hint from the bundle used to identify the the signing key.
utils
The utils
object contains a few internal utility functions. These are exposed
to support the needs of specific sigstore-js
consumers but should NOT be
considered part of the stable public interface.
CLI
The sigstore-js
library comes packaged with a basic command line interface
for testing and demo purposes. However, the CLI should NOT be considered
part of the stable interface of the library. If you require a production-ready
Sigstore CLI, we recommend you use cosign
.
$ npx sigstore help
sigstore <command> <artifact>
Usage:
sigstore sign sign an artifact
sigstore attest sign an artifact using dsse (Dead Simple Signing Envelope)
sigstore verify verify an artifact
sigstore version print version information
sigstore help print help information
Development
Updating protobufs
Docker is required to generate protobufs for the .sigstore
bundle format.
Install Docker on MacOS using Homebrew:
brew install --cask docker && open -a Docker
View Docker install instructions for other platforms.
Updating Sigstore Protobufs
Update the Git REF
in hack/generate-bundle-types
from the sigstore/protobuf-specs repository.
Generate TypeScript protobufs (should update files in scr/types/sigstore/__generated__):
npm run codegen:bundle
Updating Rekor Types
Update the git REF
in hack/generate-rekor-types
from the sigstore/rekor repository.
Generate TypeScript types (should update files in scr/types/rekor/__generated__):
npm run codegen:rekor
Release Steps
- Update the version inside
package.json
and run npm i
to update package-lock.json
. - PR the changes above and merge to the "main" branch when approved.
- Use either the "Create a new release" link or the
gh release create
CLI command to start a new release. - Tag the release with a label matching the version in the
package.json
(with a v
prefix). - Add a title matching the tag.
- Add release notes.
- Mark as pre-release as appropriate.
- Publish release.
After publishing the release, a new npm package will be built and published automatically to the npm registry.
Licensing
sigstore-js
is licensed under the Apache 2.0 License.
Contributing
See the contributing docs for details.
Code of Conduct
Everyone interacting with this project is expected to follow the sigstore Code of Conduct.
Security
Should you discover any security issues, please refer to sigstore's security process.
Info
sigstore-js
is developed as part of the sigstore
project.
We also use a slack channel! Click here for the invite link.