@alessiofrittoli/crypto-algorithm

Crypto Algorithm 📟

Lightweight TypeScript library with Node.js Crypto Algortihm utilities

Table of Contents

• Getting started
• Algorithm utility Class
• Development
  • Install depenendencies
  • Build the source code
  • ESLint
  • Jest
• Contributing
• Security
• Credits

Getting started

Run the following command to start using crypto-algorithm in your projects:

npm i @alessiofrittoli/crypto-algorithm

or using pnpm

pnpm i @alessiofrittoli/crypto-algorithm

Algorithm utility Class

The Algorithm class is designed to manage cryptographic algorithm schemas, including their mappings and retrievals based on various criteria.

Overview

The Algorithm class provides utilities to manage and retrieve cryptographic algorithm specifications. The specifications include details like key type (kty), cryptographic algorithm identifier (alg), curve parameters, hash functions, and web crypto API names.

The algorithms supported by this class conform to COSE Algorithms and the Web Cryptography API.

Static Properties

KTY

A map of key type constants. The supported key types are:

Key	Value	Description
OKP	1	Octet Key Pair
EC2	2	Elliptic Curve (2)
RSA	3	RSA

Algorithm.MAP

A Map object that associates algorithm identifiers with their corresponding schemas. The schema includes:

• kty: Key type.
• alg: Algorithm identifier.
• crv: Curve identifier (for elliptic curves).
• name: Name of the algorithm.
• hash: Hash function used.
• crvSchemeName: Curve scheme name.
• namedCurve: Named curve for elliptic curve algorithms.
• webcryptoName: Corresponding Web Crypto API algorithm name.
• jwkAlg: JSON Web Key (JWK) algorithm name.

Static Methods

Algorithm.by()

Retrieves an algorithm schema based on a partial schema or KeyAlgorithm.

Parameters

• scheme (Partial<Algo.Schema> | KeyAlgorithm): A partial schema or KeyAlgorithm object.

Returns

• (Algo.Schema | undefined): The matching algorithm schema, or undefined if no match is found.

Implementation

• If the scheme contains an alg property, the method directly retrieves the schema from the Algorithm.MAP.
• Otherwise, the method iterates through the Algorithm.MAP entries and performs a property-based match.

Algorithm.byId()

Retrieves an algorithm schema by its identifier.

Parameters

• alg (Algo.Id): The algorithm identifier.

Returns

• (Algo.Schema | undefined): The schema associated with the provided identifier, or undefined if no match is found.

Implementation

• Internally calls the Algorithm.by() method with an object containing the alg property.

Usage examples

Retrieve Schema by Algorithm ID

import { Algorithm } from '@alessiofrittoli/crypto-algorithm'

const schema = Algorithm.byId( -7 )
console.log( schema )
// Output: Schema details for ECDSA using SHA-256

Retrieve Schema by Partial Properties

import { Algorithm } from '@alessiofrittoli/crypto-algorithm'
import type { Algo } from '@alessiofrittoli/crypto-algorithm/types'

const partialScheme: Partial<Algo.Schema> = { name: 'RSA-PSS', hash: 'SHA-256' }
const schema = Algorithm.by( partialScheme )
console.log( schema )
// Output: Schema details for RSA-PSS with SHA-256

Supported Algorithms in Algorithm.MAP

The Algorithm.MAP includes schemas for:

• ECDSA (Elliptic Curve Digital Signature Algorithm)
• EdDSA (Edwards-curve Digital Signature Algorithm)
• RSA-PSS (RSA Probabilistic Signature Scheme)
• RSASSA-PKCS1-v1_5 (RSA Signature Scheme with Appendix)
• HMAC (Hash-based Message Authentication Code)
• DSA (Digital Signature Algorithm)

Refer to the Algorithm.MAP implementation for specific algorithm configurations.

Development

Install depenendencies

npm install

or using pnpm

pnpm i

Build the source code

Run the following command to test and build code for distribution.

pnpm build

ESLint

warnings / errors check.

pnpm lint

Jest

Run all the defined test suites by running the following:

# Run tests and watch file changes.
pnpm test:watch

# Run tests in a CI environment.
pnpm test:ci

• See package.json file scripts for more info.

Run tests with coverage.

An HTTP server is then started to serve coverage files from ./coverage folder.

⚠️ You may see a blank page the first time you run this command. Simply refresh the browser to see the updates.

test:coverage:serve

Contributing

Contributions are truly welcome!

Please refer to the Contributing Doc for more information on how to start contributing to this project.

Help keep this project up to date with GitHub Sponsor.

Security

If you believe you have found a security vulnerability, we encourage you to responsibly disclose this and NOT open a public issue. We will investigate all legitimate reports. Email [e-mail] to disclose any security vulnerabilities.

Made with ☕

Alessio Frittoli https://alessiofrittoli.it | [e-mail]