Options
All
  • Public
  • Public/Protected
  • All
Menu

Module 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

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 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 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 (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.
  • In iOS and macOS Safari, ECDSA P-521 curve is not supported.

Index

Type aliases

AesKeyLength: 128 | 192 | 256
EcCurve: keyof typeof PointSizes
KeyKind: "private" | "public" | "secret"

Identify kind of key.

PrivateKey: Key<"private">

Named private key.

PublicKey: Key<"public">

Named public key.

RsaModulusLength: 2048 | 4096
SecretKey: Key<"secret">

Named secret key.

Variables

AESCBC: AesEncryption<{}, AESCBC.GenParams> = ...

AES-CBC encryption algorithm.

Initialization Vectors must be 16 octets. During encryption, if IV is unspecified, it is randomly generated. During decryption, quality of IV is not checked.

AES-CTR encryption algorithm.

Initialization Vectors must be 16 octets. During encryption, if IV is unspecified, it is constructed with two parts:

li

a 64-bit random number, generated each time a private key instance is constructed;

li

a 64-bit counter starting from zero.

During decryption, quality of IV is not automatically checked. Since the security of AES-CTR depends on having unique IVs, the application is recommended to check IVs using CounterIvChecker type.

AESGCM: AesEncryption<{}, AESGCM.GenParams> = ...

AES-GCM encryption algorithm.

Initialization Vectors must be 12 octets. During encryption, if IV is unspecified, it is constructed with two parts:

li

a 64-bit random number, generated each time a private key instance is constructed;

li

a 32-bit counter starting from zero.

During decryption, quality of IV is not automatically checked. Since the security of AES-GCM depends on having unique IVs, the application is recommended to check IVs using CounterIvChecker type.

AesBlockSize: 16 = 16

AES block size in octets.

CryptoAlgorithmListFull: readonly CryptoAlgorithm[] = ...

A full list of crypto algorithms.

CryptoAlgorithmListSlim: readonly CryptoAlgorithm[] = ...

A slim list of crypto algorithms. If you need more algorithms, explicitly import them or use CryptoAlgorithmListFull.

Sha256WithEcdsa signing algorithm.

EncryptionAlgorithmListFull: readonly EncryptionAlgorithm[] = ...

A full list of encryption algorithms. This list currently contains AES-CBC, AES-CTR, AES-GCM, and RSA-OAEP.

EncryptionAlgorithmListSlim: readonly EncryptionAlgorithm[] = []

A slim list of encryption algorithms. This list is currently empty. If you need more algorithms, explicitly import them or use EncryptionAlgorithmListFull.

HMAC: SigningAlgorithm<{}, false, HMAC.GenParams> = ...

HmacWithSha256 signing algorithm.

KeyKind: typeof KeyKind
RSA: SigningAlgorithm<{}, true, RSA.GenParams> = ...

Sha256WithRsa signing algorithm.

RSAOAEP: EncryptionAlgorithm<{}, true, RSA.GenParams> = ...

RSA-OAEP encryption algorithm.

SigningAlgorithmListFull: readonly SigningAlgorithm[] = ...

A full list of signing algorithms. This list currently contains ECDSA, RSA, and HMAC.

SigningAlgorithmListSlim: readonly SigningAlgorithm[] = ...

A slim list of signing algorithms. This list currently contains ECDSA. If you need more algorithms, explicitly import them or use SigningAlgorithmListFull.

Functions

Generated using TypeDoc