@ndn/keychain

@ndn/keychain

This package is part of NDNts, Named Data Networking libraries for the modern web.

This package provides basic signing algorithms and certificate management features.

Signing Algorithms

This package implements signature types defined in NDN Packet Format 0.3:

• DigestSha256 (in @ndn/packet package)
  • signing and verification
• SignatureSha256WithRsa (RSASSA-PKCS1-v1_5)
  • signing and verification
  • KeyLocator .Name
  • KeyLocator .KeyDigest
• SignatureSha256WithEcdsa
  • signing and verification
  • KeyLocator .Name
  • KeyLocator .KeyDigest
• SignatureHmacWithSha256
  • signing and verification
  • KeyLocator matching

Both Interest and Data are signable.

• sign Interest
  • put certificate name in KeyLocator
  • generate SigNonce, SigTime, SigSeqNum
• verify Interest
  • check ParametersSha256DigestComponent
  • check SigNonce, SigTime, SigSeqNum
• sign Data
  • put certificate name in KeyLocator
• verify Data

The implementation uses Web Crypto API.

• Modern browsers natively support WebCrypto.
• Most browsers restrict WebCrypto to secure contexts only. During development, you may use http://localhost or ngrok.
• In Node.js, @peculiar/webcrypto wraps Node.js Crypto API and exports them as WebCrypto.

Certificate Management and Storage

Certificate class provides basic operations with NDN Certificate Format 2.0.

• generate self-signed certificate
• issue certificate to another public key
• import certificate as PublicKey for RSASSA-PKCS1-v1_5 and ECDSA

KeyChain class provides storage of PrivateKey and Certificate. It could be ephemeral or persistent. KeyChain.createTemp() creates an in-memory ephemeral keychain. KeyChain.open(locator) opens a persistent keychain.

Persistent keychain in Node.js uses JSON files as underlying storage. The locator argument should be a filesystem directory where these files are stored. Private keys are saved as JSON Web Key format, so that it's important to protect the storage directory. It is unsafe to create multiple KeyChain instances on the same storage directory, or access the same keychain from multiple Node.js processes.

Persistent keychain in browser uses IndexedDB API. The locator argument determines the database name(s). Private keys are saved as non-extractable CryptoKey objects.

Known issues:

• In Firefox, certificates created from ECDSA keys have wrong OID, due to Mozilla Bug 1410403.
• In Firefox, ECDSA private keys cannot be saved in persistent keychain, due to Mozilla Bug 1545813.
• In Firefox, persistent keychain is unusable in a Private Browsing window, due to Mozilla Bug 781982.
• In iOS and macOS Safari, ECDSA P-521 curve is not supported.