@keeex/x509 v1.1.4

@keeex/x509

Create and verify digital signatures based on X509 PEM certificates and private keys.

This library is a higher-level interface to underlying tools to easily manipulate X509 digital signatures. Currently it uses jsrsasign under the hood to perform every operation, and provides an abstraction to:

• create empty placeholders for future signature based only on the certificate
• compute a signature on short input data (must be passed all at once)
• verify a digital signature

Certificates and private keys must be provided as PEM files.

Basic usage

The library exposes a single class called X509. When instanciated, a certificate must be provided, and a private key can be provided.

All methods have their own JSDoc. Here's an example to perform a digital signature:

import X509 from "@keeex/x509";
import {readFile, writeFile} from "fs/promises";

const certificate = await readFile("certificate.pem", "utf8");
const privateKey = await readFile("private.pem", "utf8");
const privateKeyPassphrase = "123456";
const instance = await X509.create(certificate, privateKey, privateKeyPassphrase);

const data = await readFile("input");
const signature = await instance.sign(data);
await writeFile("signature", signature);
const sigValid = await instance.verify(data, signature);
console.log(`Signature valid: ${sigValid ? "OK" : "ERROR"}`)

More examples available in the "samples" directory.

Full feature list

• Can read certificates/private key for RSA and common EC digital signature
• Produce and verify digital signature
• Can compute the signature length from the certificate only
• Can produce a suitable signature placeholder for various common encodings

Compatibility

The library, being based on jsrsasign accepts a wide range of files. In particular, RSA and standard curves ECDSA certificates are supported.

Private keys can be encrypted; common encryption schemes are supported.

Here are some openssl commands that can be used to generate certificates and private keys. Note that these are very minimal commands that are suitable for testing but are not suitable for production, since it produces self-signed certificates with a short lifespan and default parameters.

Proper understanding of keypair and certificates is required.

Generate an RSA keypair and certificate

# Generate a private key
openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:4096 -out private.pem
# Generate the self-signed X509 certificate
openssl req -new -x509 -key private.pem -out certificate.pem
# Encrypt the private key using a passphrase
openssl pkey -in private.pem -traditional -aes256 -out private_pass.pem

Generate an ECDSA keypair and certificate

# Generate a private key
openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:secp256k1 -out private.pem
# Generate the self-signed X509 certificate
openssl req -new -x509 -key private.pem -out certificate.pem
# Encrypt the private key using a passphrase
openssl pkey -in private.pem -traditional -aes256 -out private_pass.pem

OpenSSL compatibility

For reference, the following commands are useful to check against OpenSSL compatibility:

# Export public key from certificate
openssl x509 -in certificate.pem -pubkey -noout -out publickey.pem
# Check a signature (assuming the raw signature output is in data.sig and data is in data)
# Note: change sha256 when needed
openssl dgst -sha256 -verify publickey.pem -signature data.sig data
# Generate a signature that can be verified by @keeex/x509
# Note: change sha256 when needed
openssl dgst -sha256 -sign private.pem -out data.sig data

Browser usage

Importing the library as usual and using webpack should work. An "autonomous" bundle is available in dist/keeex.x509.js and exports the global name keeexX509.