npm package: @keeex/x509
Description: Handles digital signature based on X509 certificates
Author: KeeeX SAS
Latest version: 1.1.8

# @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:

```JavaScript
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

```shell
# 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

```shell
# 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:

```shell
# 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`.

## Tests

To run the test, you must initialize some files, do it with the script
`./scripts/create_test_files.sh`

Run the node tests with `npm test`.

To run the browser tests, run `npm run webtest` then fill the fields with
test | private key | certificate | passphrase
--- | --- | --- | ---
rsa | `./test/keypair/private_rsa_nopass.pem` | `./test/keypair/certificate_rsa.pem` |
rsa2 | `./test/keypair/private_rsa2.pem` | `./test/keypair/certificate_rsa2.pem` |
rsa passphrase | `./test/keypair/private_rsa_pass.pem` | `./test/keypair/certificate_rsa.pem` | `123456`
ec | `./test/keypair/private_ec_nopass.pem` | `./test/keypair/certificate_ec.pem` |
ec2 | `./test/keypair/private_ec2.pem` | `./test/keypair/certificate_ec2.pem` |
ec passphrase | `./test/keypair/private_ec_pass.pem` | `./test/keypair/certificate_ec.pem` | `123456`

Type something in Data, then click "Sign", it will fill the Signature. Then click "Verify status" it
should display "OK"