For consistency. Public interfaces use both interchangeably.

ArrayBuffer is used extensively because PKI.js requires it, but everything else uses Buffer.

As of early 2022, I'm using ArrayBuffer in new interfaces to avoid conversions before/after use with PKI.js and for forward-compatibility with web browsers.

I think this is a bug in PKI.js or, perhaps more likely, node-webcrypto-ossl. This can be reproduced by calling generateECDHKeyPair with a curve other than P-256.

This isn't a major issue because support for P-256 is required and support for the other curves is just recommended.

Once this is fixed, reinstate this commented-out test:

https://github.com/relaycorp/relaydev/blob/master/functional_tests/test-key-genecdh.sh#L5-L8

I've been doing that to avoid burning more time on that bug, but we need to address the underlying issue and open a PR for PKI.js after debugging it.

The main reason to do this is performance.

We can find the instances where this is done by searching for "redeserialize".

Analogous to the PrivateKeyStore, but values need not be encrypted at rest or in transit. It would hold two sets of certificates along with their corresponding chains:

• Those belonging to the current node.
• Channel session certificates for the nodes with which there are active sessions.

For example, a concrete store could be backed by MongoDB (in the case of a server-side app) or the file system (in the case of a desktop app).

Note to self: I think I discovered a bug in PKI.js but haven't got the time right now to create a small reproducible snippet.

It seems like when the Authority Key Identifier or Subject Key Identifier extensions are missing, signature generation/verification operations never complete when using a certificate chain (which leads to timeouts).

The channel session spec used to require 32-bit integers: AwalaNetwork/specs@e759f9d

But representing such ids as JS numbers makes things more complicated because we'd have to ensure they're valid 32-bit unsigned integers. Also, the 32-bit constraint was only introduced to make it possible to represent such ids as numbers across platforms.

So we should just treat the serial number as an ArrayBuffer.

Generating a DER-encoded SignedData value with a content of 8 MiB takes 6-9 seconds on my computer, which could make the public gateway susceptible to severe availability issues.

Nearly all that time is spent serialising the ContentInfo/SignedData object to a DER ByteArray (constructing those objects and calling SignedData.sign() takes 60ms and 5ms, respectively). Roughly 66% of the serialisation time is spent encoding the SignedData value and the remainder serialising the ContentInfo wrapper.

Verifying such large values takes just over 300ms on the same computer after some optimisations.

The culprit has to be the ASN1.js and/or PKI.js libraries, although having the plaintext embedded in the CMS SignedData certainly doesn't help. So broadly speaking, our options are:

• Locate the bottleneck in the 3rd party libraries and fix it.
• Implement a fix for AwalaNetwork/specs#55

This is blocked by PeculiarVentures/PKI.js#89

See also:

• https://issuetracker.google.com/issues/231334600
• https://issuetracker.google.com/issues/232422224

Per https://specs.relaynet.link/RS-002

See also #3

Update spec to use PKCS#12.

Here's a relevant snippet: PeculiarVentures/PKI.js#104

See: https://specs.relaynet.link/RS-003#x509-certificate-for-initial-dh-key

And make it part of the CIS.

That way we can find issues like #57 before it's too late.

We should abstract the use of PKI.js to prevent the use of invalid or unsafe parameters. See:

• https://specs.relaynet.link/RS-018#digital-signature-algorithms
• https://github.com/PeculiarVentures/PKI.js/tree/master/examples/CMSSignedComplexExample
• https://github.com/PeculiarVentures/PKI.js/blob/master/src/SignedData.js

Note that the certificate and the plaintext must be detached per RS-001.

Only support RSA for now.

See: https://specs.relaynet.link/RS-003

And maybe have it replace the current IssuerAndSerialNumber support, subject to AwalaNetwork/specs#18

I.e., when a plaintext is encrypted with the public key in a certificate, as opposed to the channel session protocol (#12).

We should abstract the use of PKI.js to prevent the use of invalid or unsafe parameters. See:

• https://github.com/PeculiarVentures/PKI.js/tree/master/examples/HowToEncryptCMSviaCertificate
• https://github.com/PeculiarVentures/PKI.js/blob/master/src/EnvelopedData.js
• https://specs.relaynet.link/RS-018

I'm experiencing a really bizarre issue when upgrading from v2.1.84 to any of the newer versions (up to 2.1.88): I'm using getAlgorithmParameters() but it fails because getEngine() returns the default engine even though I'd previously called setEngine() with an instance from node-webcrypto-ossl.

I've altered the code for PKI.js' common.js file in node_modules to log each call to setEngine() and getEngine(), and I can confirm that my call to setEngine() is done before getEngine(). I've also checked that the engine gets placed in the right key under global, and the pid is always the same (which isn't surprising, since I'm only running one process).

This only happens when I integrate relaynet-core in the public gateway. That server doesn't use PKI.js directly at all, so index.js registers the crypto engine there. The server only imports stuff from index.js, so imports are only available after the PKI.js engine is registered. (Note that the debugging I mentioned was done on the server where the issue manifests)

I've tried downgrading to 2.1.83 and older versions, and the server works absolutely fine. It's only when I upgrade to 2.1.85-2.1.88 that it breaks. Here's an example: If I upgrade my library to use PKI.js 2.1.85+, the server tests fail with TypeError: Cannot read property 'getAlgorithmParameters' of null, but the issue goes away if I use a different version of my library that requires PKI.js 2.1.84.

See downgrade in #72

Using ArrayBuffer is a big hassle and it's only needed to interface with PKI.js

AwalaNetwork/specs#32

Also create issueCargoDeliveryAuthorization with isCA = false and pathLenConstraint = 0.

This is the memory-efficient alternative to the buffer-based implementation in #2 and #8. This will typically be useful when processing cargo, not parcels.

See potential encryption/decryption implementation: https://lollyrock.com/posts/nodejs-encryption/. We may want to use Scramjet's BufferStream to help with this.

This depends on AwalaNetwork/specs#14

See also: PeculiarVentures/PKI.js#237

Per https://specs.relaynet.link/RS-002#gateway-certificate-revocation-gcr

Includes deserialisation.

As recently added to RS-002

Per RS-001. See serialization.js in the PoC.

This includes post-deserialisation validation.

This requires #10 and #11.

I didn't do it as part of #37 because:

• I wanted to reuse code snippets from the Node.js implementations, which we haven't started.
• I think the current interface is likely to change as we integrate it in those apps.

Per Relaynet Core and Relaynet PKI. See partial implementation in PoC: https://github.com/relaynet/poc/blob/master/core/messages.js

This should be integrated with the serialisation functionality from #2 and #8.

Only IssuerAndSerialNumber should be allowed.

We should enforce this post-deserialization as in the JVM library.

Per RS-001. See serialization.js in the PoC.

This must be implemented as a function, when the payload is a string or a buffer.

This requires #10 and #11.

We should stop exposing PKI.js types in the exported interface. Today, TypeScript clients of relaynet-core-js have to install @types/pkijs as a dev dependency and also create a local typings file to avoid errors like this: https://app.circleci.com/jobs/github/relaycorp/relaynet-cogrpc-js/1

From memory, this is the case in the Certificate and EnvelopedData classes (plus subclasses).

An interface that each parcel delivery binding (like relaynet-powebsocket-js) must implement to:

• Deliver parcels
• Collect parcels
• Request a certificate from its gateway
• Provide its gateway with a Parcel Delivery Deauthorization.

Equivalent implementation in the PoC (although it didn't use interfaces): https://github.com/relaynet/poc/blob/master/core/endpoint.js

So it can be used on SessionlessEnvelopedData instances (e.g., for key rotation purposes).

We may have to make it abstract because the session-based implementation looks at recipientInfos[0].value.keyInfo.recipientEncryptedKeys.encryptedKeys[0].rid.value.serialNumber, but I think recipientInfos[0].value.keyInfo.recipientEncryptedKeys is specific to key agreement protocols.

These calls are IO-bound operations and should therefore be cached.

Implement endpoint/gateway certificates in RS-002 using node-forge

This has to support:

• Self-signed certificates.
• Parcel Delivery Authorization.

Rate limiting is outside the scope for now (see #17).

Per RS-018.

For example, PKI.js supports SHA-1, but RS-018 disallows it.

Per https://specs.relaynet.link/RS-002#certificate-and-key-rotation

Include deserialisation.

AwalaNetwork/specs@320448f

Needed for relaycorp/awala-gateway-internet#8

I.e., when a plaintext is encrypted with a Diffie Hellman key per the channel session protocol, as opposed to a key in a certificate (#11).

We should abstract the use of PKI.js to prevent the use of invalid or unsafe parameters.

There should be an enum for the types of recipient addresses (private, public), which should be passed to validate() as the first parameter. It may also be set to null to allow any type.

Authorization should be skipped if and only if recipientType == public && requiredRecipientType != private.

Since the authors of node-webcrypto-ossl recommend using @peculiar/webcrypto instead: PeculiarVentures/node-webcrypto-ossl#161 (comment)

See: https://codecov.io/gh/relaycorp/relaynet-core-js/commits

• Document install instructions.
• API documentation.
• Verbose documentation.
• README.

This will be needed to support the Web Browser interface: https://specs.relaynet.link/RS-010

Triggered each time there's a new Git tag matching a semver pattern.

into Message.(export|import)Payload

It should mostly be a matter of undoing 0e4e4d7

• Configure linter.
• Configure build automation.
• Configure test runner.
• Configure CI.
• Configure API docs generator.
• Etc.

See also: https://github.com/bitjson/typescript-starter

Ed25519 support in the PKI.js backend is tracked here: PeculiarVentures/webcrypto-liner#57

Related: #29

Per https://specs.relaynet.link/RS-002#rate-limiting-extension

https://circleci.com/docs/2.0/hello-world-windows/