@ndn/keychain

@ndn/keychain

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

This package provides signing algorithms, encryption algorithms, and certificate management features.

The implementation uses Web Crypto API.

• Modern browsers and Node.js 16.x natively support WebCrypto.
• Most browsers restrict WebCrypto to secure contexts only. During development, you may use http://localhost or ngrok.

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
• SignatureEd25519
  • signing and verification
  • KeyLocator .Name
  • KeyLocator .KeyDigest

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

Encryption Algorithms

• AES-CBC
  • low-level encryption and decryption
• AES-CTR and AES-GCM
  • low-level encryption and decryption
  • generate unique IV
  • check IV uniqueness
• RSA-OAEP
  • low-level encryption and decryption

Algorithm List (algoList)

Several functions accept an algoList argument that contains the crypto algorithms it can recognize. Typically, the default value of this argument is SigningAlgorithmListSlim, EncryptionAlgorithmListSlim, or CryptoAlgorithmListSlim. These slim lists include only ECDSA algorithm, which is the most commonly used in NDN applications.

If you need to use other algorithms or communicate with applications that use other algorithms, you should pass SigningAlgorithmListFull, EncryptionAlgorithmListFull, or CryptoAlgorithmListFull to these functions. These full lists include all algorithms implemented in NDNts.

If you know which algorithms are needed, you can import individual algorithms and pass an array of desired algorithms.

This design is a trade-off for reducing browser bundle size.

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, ECDSA, Ed25519

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 (JWK) format, so that it's important to protect the storage directory. It is unsafe to simultaneously construct 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, persistent keychain stores JWK instead of CryptoKey, due to Mozilla Bug 1545813.
• In Firefox, persistent keychain is unusable in a Private Browsing window, due to Mozilla Bug 781982.
• In Chrome, AES 192-bit key is not supported.
• Ed25519 in browser is implemented in JavaScript, which is less secure than native Web Crypto implementation.