edhoc 1.0.4 → 1.1.0

package/README.md

@@ -0,0 +1,170 @@
+# Node EDHOC
+
+A TypeScript Node.js library implemented as a native addon, built on top of the C library [`libedhoc`](https://github.com/kamil-kielbasa/libedhoc/). It provides an efficient and lightweight way to use the Ephemeral Diffie-Hellman Over COSE (EDHOC) protocol, as specified in [RFC 9528](https://datatracker.ietf.org/doc/rfc9528/).
+
+## Overview
+
+EDHOC is designed for lightweight communication and is particularly suitable for protocols like CoAP and OSCORE, but can work independently of the application and transport layers, ensuring minimal overhead while maintaining strong security guarantees. The library provides a default software implementation for X.509 credentials, with support for additional formats such as C509, CWT, and CCS coming soon. It also includes a software-based cryptographic implementation utilizing [`@noble/curves`](https://www.npmjs.com/package/@noble/curves/v/1.0.0). Additionally, it exposes credential and cryptographic API interfaces to allow for custom implementations, such as PKCS#11-based solutions.
+
+## Features
+
+- Full implementation of the EDHOC protocol (RFC 9528)
+- TypeScript support for type safety and better developer experience
+- Based on [`libedhoc`](https://github.com/kamil-kielbasa/libedhoc), a proven C implementation
+
+## Installation
+
+Install the package via npm:
+
+```bash
+npm install node-edhoc
+```
+
+## Usage Examples
+
+### Basic Handshake
+
+The simplest EDHOC handshake using pre-shared keys (Method 0):
+
+```typescript
+import { EDHOC, EdhocMethod, EdhocSuite } from 'node-edhoc';
+
+// ...
+
+const initiator = new EDHOC(10, [ EdhocMethod.Method0 ], [ EdhocSuite.Suite0 ], credentialsManager, cryptoManager);
+const responder = new EDHOC(20, [ EdhocMethod.Method0 ], [ EdhocSuite.Suite0 ], credentialsManager, cryptoManager);
+
+// Message 1: Initiator → Responder
+const message1 = await initiator.composeMessage1();
+await responder.processMessage1(message1);
+
+// Message 2: Responder → Initiator
+const message2 = await responder.composeMessage2();
+await initiator.processMessage2(message2);
+
+// Message 3: Initiator → Responder
+const message3 = await initiator.composeMessage3();
+await responder.processMessage3(message3);
+
+// ...
+
+```
+
+### Using External Authorization Data (EAD)
+
+You can include additional authorization data in EDHOC messages:
+
+```typescript
+// initiator.js
+const ead_1 = [{ 
+  label: 1000, 
+  value: Buffer.from('External Data') 
+}];
+
+const message1 = await initiator.composeMessage1(ead_1);
+
+// responder.js
+const receivedEAD = await responder.processMessage1(message1);
+```
+
+### Certificate-Based Authentication
+
+Using X.509 certificates for authentication (Method 1):
+
+```typescript
+import { 
+  EDHOC, 
+  X509CertificateCredentialManager, 
+  DefaultEdhocCryptoManager 
+} from 'node-edhoc';
+
+// Setup credential managers
+const initiatorCreds = new X509CertificateCredentialManager(
+  [initiatorCert],
+  initiatorKeyID
+);
+initiatorCreds.addTrustedCA(trustedCA);
+
+// Setup crypto managers
+const initiatorCrypto = new DefaultEdhocCryptoManager();
+
+// Initialize EDHOC with certificate-based auth
+const initiator = new EDHOC(
+  10, 
+  [EdhocMethod.Method1], 
+  [EdhocSuite.Suite2],
+  initiatorCreds,
+  initiatorCrypto
+);
+```
+
+### Exporting OSCORE Context
+
+After a successful handshake, you can export the OSCORE security context:
+
+```typescript
+const initiatorContext = await initiator.exportOSCORE();
+const responderContext = await responder.exportOSCORE();
+
+console.log('Master Secret:', initiatorContext.masterSecret);
+console.log('Master Salt:', initiatorContext.masterSalt);
+console.log('Sender ID:', initiatorContext.senderId);
+console.log('Recipient ID:', initiatorContext.recipientId);
+```
+
+### Key Update
+
+Perform a key update for an existing OSCORE context:
+
+```typescript
+const keyUpdateContext = Buffer.from('new-entropy-data');
+
+// Update keys for both parties
+await initiator.keyUpdate(keyUpdateContext);
+await responder.keyUpdate(keyUpdateContext);
+
+// Export new OSCORE context
+const newContext = await initiator.exportOSCORE();
+```
+
+### Custom Key Export
+
+Export application-specific keys:
+
+```typescript
+// Export a 32-byte key with label 40001
+const key = await initiator.exportKey(40001, 32);
+```
+
+For more detailed examples and API documentation, please refer to our [API Documentation](#).
+
+## Documentation
+
+For detailed documentation, refer to:
+
+- [EDHOC Specification (RFC 9528)](https://datatracker.ietf.org/doc/rfc9528/)
+- [API Documentation](#) *(TODO: Link to generated API docs if available)*
+
+## Contributing
+
+Contributions are welcome! To contribute:
+
+1. Fork the repository and create a new branch.
+2. Implement your feature or bugfix.
+3. Write tests if applicable.
+4. Open a pull request.
+
+Please ensure your code follows the existing style and structure of the project.
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).
+
+## Related Projects
+
+- [libedhoc](https://github.com/kamil-kielbasa/libedhoc/) - A C implementation of the Ephemeral Diffie-Hellman Over COSE
+
+## Acknowledgments
+
+This implementation is based on the EDHOC specification as defined in RFC 9528. Special thanks to the developers of [`libedhoc`](https://github.com/kamil-kielbasa/libedhoc/) for their foundational work on EDHOC in C.
+

package/binding.gyp

@@ -7,15 +7,16 @@
       "target_name": "bindings",
       'defines': [
         'NAPI_CPP_EXCEPTIONS=1',
-        'EDHOC_KID_LEN=4',
-        'EDHOC_MAX_CSUITES_LEN=9',
-        'EDHOC_MAX_CID_LEN=7',
-        'EDHOC_MAX_ECC_KEY_LEN=56',
-        'EDHOC_MAX_MAC_LEN=64',
-        'EDHOC_MAX_NR_OF_EAD_TOKENS=10',
-        'EDHOC_MAX_NR_OF_CERTS_IN_X509_CHAIN=5',
-        'EDHOC_CRED_KEY_ID_LEN=8',
-        'EDHOC_CRED_X509_HASH_ALG_LEN=1',
+        'CONFIG_LIBEDHOC_ENABLE=1',
+        'CONFIG_LIBEDHOC_MAX_NR_OF_CIPHER_SUITES=9',
+        'CONFIG_LIBEDHOC_MAX_LEN_OF_CONN_ID=7',
+        'CONFIG_LIBEDHOC_MAX_LEN_OF_ECC_KEY=56',
+        'CONFIG_LIBEDHOC_MAX_LEN_OF_MAC=64',
+        'CONFIG_LIBEDHOC_MAX_NR_OF_EAD_TOKENS=10',
+        'CONFIG_LIBEDHOC_MAX_LEN_OF_CRED_KEY_ID=1',
+        'CONFIG_LIBEDHOC_MAX_NR_OF_CERTS_IN_X509_CHAIN=5',
+        'CONFIG_LIBEDHOC_MAX_LEN_OF_HASH_ALG=1',
+        'CONFIG_LIBEDHOC_KEY_ID_LEN=4',
         'ZCBOR_CANONICAL=1'
       ],
       "sources": [ 
@@ -45,11 +46,12 @@
       'conditions': [
         ['OS=="win"', {
           'defines': [
-            '_Static_assert=static_assert'
+            '_Static_assert=static_assert',
+            '__attribute__(x)='
           ],
           'msvs_settings': {
             'VCCLCompilerTool': {
-              'AdditionalOptions': [ '-std:c++20', ],
+              'AdditionalOptions': [ '-std:c++20', "/D__attribute__(x)="],
               'ExceptionHandling': 1
             }
           }

package/dist/bindings.d.ts

@@ -0,0 +1,5 @@
+import { EDHOC } from './edhoc';
+export interface NodeGypBinding {
+    EDHOC: EDHOC;
+}
+//# sourceMappingURL=bindings.d.ts.map

package/dist/bindings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bindings.d.ts","sourceRoot":"","sources":["../lib/bindings.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAA;AAG/B,MAAM,WAAW,cAAc;IAC3B,KAAK,EAAE,KAAK,CAAA;CACf"}

package/dist/bindings.js

@@ -0,0 +1,10 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_gyp_build_1 = __importDefault(require("node-gyp-build"));
+const path_1 = require("path");
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const binding = (0, node_gyp_build_1.default)((0, path_1.join)(__dirname, '../'));
+exports.EDHOC = binding.EDHOC;

package/dist/crypto.d.ts

@@ -0,0 +1,29 @@
+import { EDHOC, EdhocCryptoManager, EdhocKeyType } from './edhoc';
+export declare class DefaultEdhocCryptoManager implements EdhocCryptoManager {
+    private keys;
+    private keyIdentifier;
+    constructor();
+    addKey(keyID: Buffer, key: Buffer): void;
+    importKey(edhoc: EDHOC, keyType: EdhocKeyType, key: Buffer): Promise<Buffer>;
+    destroyKey(edhoc: EDHOC, keyID: Buffer): boolean;
+    makeKeyPair(edhoc: EDHOC, keyID: Buffer, privateKeySize: number, publicKeySize: number): {
+        privateKey: Buffer;
+        publicKey: Buffer;
+    };
+    keyAgreement(edhoc: EDHOC, keyID: Buffer, publicKey: Buffer, privateKeySize: number): Buffer;
+    sign(edhoc: EDHOC, keyID: Buffer, input: Buffer, signatureSize: number): Buffer;
+    verify(edhoc: EDHOC, keyID: Buffer, input: Buffer, signature: Buffer): Promise<boolean>;
+    extract(edhoc: EDHOC, keyID: Buffer, salt: Buffer, keySize: number): Buffer;
+    expand(edhoc: EDHOC, keyID: Buffer, info: Buffer, keySize: number): Buffer;
+    encrypt(edhoc: EDHOC, keyID: Buffer, nonce: Buffer, aad: Buffer, plaintext: Buffer, size: number): Buffer;
+    decrypt(edhoc: EDHOC, keyID: Buffer, nonce: Buffer, aad: Buffer, ciphertext: Buffer, size: number): Buffer;
+    hash(edhoc: EDHOC, data: Buffer, hashSize: number): Promise<Buffer>;
+    private getKey;
+    private formatToBeSigned;
+    private formatPublicKey;
+    private getCurveForSignature;
+    private getCurveForKeyAgreement;
+    private getTagLength;
+    private getAlgorithm;
+}
+//# sourceMappingURL=crypto.d.ts.map

package/dist/crypto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crypto.d.ts","sourceRoot":"","sources":["../lib/crypto.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,kBAAkB,EAAE,YAAY,EAAc,MAAM,SAAS,CAAC;AAoB9E,qBAAa,yBAA0B,YAAW,kBAAkB;IAEhE,OAAO,CAAC,IAAI,CAAiB;IAC7B,OAAO,CAAC,aAAa,CAAgB;;IAM9B,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM;IAKlC,SAAS,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,GAAG,EAAE,MAAM;IAsBhE,UAAU,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM;IAStC,WAAW,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM;;;;IActF,YAAY,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM;IAQnF,IAAI,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM;IAiBhE,MAAM,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAa7F,OAAO,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;IAKlE,MAAM,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;IAMjE,OAAO,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM;IAmBhG,OAAO,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM;IAiB3F,IAAI,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;IAIvD,OAAO,CAAC,MAAM;IAQd,OAAO,CAAC,gBAAgB;IAYxB,OAAO,CAAC,eAAe;IAavB,OAAO,CAAC,oBAAoB;IAY5B,OAAO,CAAC,uBAAuB;IAY/B,OAAO,CAAC,YAAY;IAIpB,OAAO,CAAC,YAAY;CAiBvB"}

package/dist/crypto.js

@@ -0,0 +1,205 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DefaultEdhocCryptoManager = void 0;
+const edhoc_1 = require("./edhoc");
+const ed25519_1 = require("@noble/curves/ed25519");
+const p256_1 = require("@noble/curves/p256");
+const sha256_1 = require("@noble/hashes/sha256");
+const hkdf_1 = require("@noble/hashes/hkdf");
+const crypto_1 = require("crypto");
+class DefaultEdhocCryptoManager {
+    keys = {};
+    keyIdentifier = 1000;
+    constructor() {
+        this.keys = {};
+    }
+    addKey(keyID, key) {
+        const kid = keyID.toString('hex');
+        this.keys[kid] = key;
+    }
+    async importKey(edhoc, keyType, key) {
+        const keyBuffer = Buffer.alloc(4);
+        keyBuffer.writeInt32LE(this.keyIdentifier++);
+        const keyID = keyBuffer.toString('hex');
+        const curveKE = this.getCurveForKeyAgreement(edhoc.selectedSuite);
+        const curveSIG = this.getCurveForSignature(edhoc.selectedSuite);
+        switch (keyType) {
+            case edhoc_1.EdhocKeyType.KeyAgreement:
+            case edhoc_1.EdhocKeyType.MakeKeyPair:
+                this.keys[keyID] = key.byteLength > 0 ? Buffer.from(key) : curveKE.utils.randomPrivateKey();
+                break;
+            case edhoc_1.EdhocKeyType.Signature:
+                this.keys[keyID] = key.byteLength > 0 ? Buffer.from(key) : curveSIG.utils.randomPrivateKey();
+                break;
+            default:
+                this.keys[keyID] = Buffer.from(key);
+        }
+        return keyBuffer;
+    }
+    destroyKey(edhoc, keyID) {
+        const kid = keyID.toString('hex');
+        if (kid in this.keys === false) {
+            throw new Error(`Key '${kid}' not found`);
+        }
+        delete this.keys[kid];
+        return true;
+    }
+    makeKeyPair(edhoc, keyID, privateKeySize, publicKeySize) {
+        const key = this.getKey(keyID);
+        try {
+            const curveKE = this.getCurveForKeyAgreement(edhoc.selectedSuite);
+            return {
+                privateKey: Buffer.from(key),
+                publicKey: Buffer.from(curveKE.getPublicKey(key)).subarray(curveKE === p256_1.p256 ? 1 : 0)
+            };
+        }
+        catch (error) {
+            throw new Error(`Wrong key type`);
+        }
+    }
+    keyAgreement(edhoc, keyID, publicKey, privateKeySize) {
+        const key = this.getKey(keyID);
+        const curveKE = this.getCurveForKeyAgreement(edhoc.selectedSuite);
+        const publicKeyBuffer = this.formatPublicKey(curveKE, publicKey);
+        const sharedSecrect = Buffer.from(curveKE.getSharedSecret(key, new Uint8Array(publicKeyBuffer)));
+        return sharedSecrect.subarray(curveKE === p256_1.p256 ? 1 : 0);
+    }
+    sign(edhoc, keyID, input, signatureSize) {
+        const key = this.getKey(keyID);
+        const curveSIG = this.getCurveForSignature(edhoc.selectedSuite);
+        const payload = this.formatToBeSigned(curveSIG, input);
+        const signature = curveSIG.sign(payload, new Uint8Array(key));
+        if (signature instanceof Uint8Array) {
+            return Buffer.from(signature);
+        }
+        else if ('toCompactRawBytes' in signature) {
+            return Buffer.from(signature.toCompactRawBytes());
+        }
+        else {
+            throw new Error('Unsupported signature type');
+        }
+    }
+    async verify(edhoc, keyID, input, signature) {
+        const key = this.getKey(keyID);
+        const curveSIG = this.getCurveForSignature(edhoc.selectedSuite);
+        const publicKeyBuffer = this.formatPublicKey(curveSIG, key);
+        const payload = this.formatToBeSigned(curveSIG, input);
+        if (!curveSIG.verify(new Uint8Array(signature), payload, new Uint8Array(publicKeyBuffer))) {
+            throw new Error('Signature not verified');
+        }
+        return true;
+    }
+    extract(edhoc, keyID, salt, keySize) {
+        const key = this.getKey(keyID);
+        return Buffer.from((0, hkdf_1.extract)(sha256_1.sha256, new Uint8Array(key), new Uint8Array(salt)));
+    }
+    expand(edhoc, keyID, info, keySize) {
+        const key = this.getKey(keyID);
+        const expanded = Buffer.from((0, hkdf_1.expand)(sha256_1.sha256, new Uint8Array(key), new Uint8Array(info), keySize));
+        return expanded;
+    }
+    encrypt(edhoc, keyID, nonce, aad, plaintext, size) {
+        const key = this.getKey(keyID);
+        const algorithm = this.getAlgorithm(edhoc.selectedSuite);
+        const options = {
+            authTagLength: this.getTagLength(edhoc.selectedSuite)
+        };
+        const cipher = (0, crypto_1.createCipheriv)(algorithm, key, nonce, options);
+        cipher.setAAD(aad, { plaintextLength: Buffer.byteLength(plaintext) });
+        const update = Buffer.byteLength(plaintext) === 0 ? Buffer.alloc(0) : plaintext;
+        const encrypted = Buffer.concat([
+            cipher.update(update),
+            cipher.final(),
+            cipher.getAuthTag()
+        ]);
+        return encrypted;
+    }
+    decrypt(edhoc, keyID, nonce, aad, ciphertext, size) {
+        const key = this.getKey(keyID);
+        const tagLength = this.getTagLength(edhoc.selectedSuite);
+        const algorithm = this.getAlgorithm(edhoc.selectedSuite);
+        const options = { authTagLength: tagLength };
+        const decipher = (0, crypto_1.createDecipheriv)(algorithm, key, nonce, options);
+        decipher.setAuthTag(ciphertext.subarray(ciphertext.length - tagLength));
+        decipher.setAAD(aad, { plaintextLength: ciphertext.length - tagLength });
+        const decrypted = decipher.update(ciphertext.subarray(0, ciphertext.length - tagLength));
+        decipher.final();
+        return decrypted;
+    }
+    async hash(edhoc, data, hashSize) {
+        return Buffer.from((0, sha256_1.sha256)(data));
+    }
+    getKey(keyID) {
+        const kid = keyID.toString('hex');
+        if (kid in this.keys === false) {
+            throw new Error(`Key '${kid}' not found`);
+        }
+        return this.keys[kid];
+    }
+    formatToBeSigned(curve, payload) {
+        if (curve === p256_1.p256) {
+            return Buffer.from((0, sha256_1.sha256)(payload));
+        }
+        else if (curve === ed25519_1.ed25519) {
+            return payload;
+        }
+        else {
+            throw new Error(`Unsupported curve ${curve}`);
+        }
+    }
+    formatPublicKey(curve, key) {
+        if (curve === p256_1.p256) {
+            const prefix = key.byteLength === 64 ? 0x04 : (key[key.length - 1] & 1) ? 0x03 : 0x02;
+            return Buffer.concat([Buffer.from([prefix]), key]);
+        }
+        else if (curve === ed25519_1.ed25519 || curve === ed25519_1.x25519) {
+            return key;
+        }
+        else {
+            throw new Error(`Unsupported curve ${curve}`);
+        }
+    }
+    getCurveForSignature(suite) {
+        if ([edhoc_1.EdhocSuite.Suite2, edhoc_1.EdhocSuite.Suite3, edhoc_1.EdhocSuite.Suite5, edhoc_1.EdhocSuite.Suite6].includes(suite)) {
+            return p256_1.p256;
+        }
+        else if ([edhoc_1.EdhocSuite.Suite0, edhoc_1.EdhocSuite.Suite1, edhoc_1.EdhocSuite.Suite4].includes(suite)) {
+            return ed25519_1.ed25519;
+        }
+        else {
+            throw new Error(`Unsupported EDHOC suite ${suite} for signature.`);
+        }
+    }
+    getCurveForKeyAgreement(suite) {
+        if ([edhoc_1.EdhocSuite.Suite2, edhoc_1.EdhocSuite.Suite3, edhoc_1.EdhocSuite.Suite5].includes(suite)) {
+            return p256_1.p256;
+        }
+        else if ([edhoc_1.EdhocSuite.Suite0, edhoc_1.EdhocSuite.Suite1, edhoc_1.EdhocSuite.Suite4, edhoc_1.EdhocSuite.Suite6].includes(suite)) {
+            return ed25519_1.x25519;
+        }
+        else {
+            throw new Error(`Unsupported EDHOC suite ${suite} for key agreement.`);
+        }
+    }
+    getTagLength(suite) {
+        return [edhoc_1.EdhocSuite.Suite0, edhoc_1.EdhocSuite.Suite2].includes(suite) ? 8 : 16;
+    }
+    getAlgorithm(suite) {
+        if ([edhoc_1.EdhocSuite.Suite4, edhoc_1.EdhocSuite.Suite5, edhoc_1.EdhocSuite.Suite25].includes(suite)) {
+            return 'chacha20-poly1305';
+        }
+        else if ([edhoc_1.EdhocSuite.Suite6].includes(suite)) {
+            return 'aes-128-gcm';
+        }
+        else if ([edhoc_1.EdhocSuite.Suite24].includes(suite)) {
+            return 'aes-256-gcm';
+        }
+        else if ([edhoc_1.EdhocSuite.Suite0, edhoc_1.EdhocSuite.Suite1, edhoc_1.EdhocSuite.Suite2, edhoc_1.EdhocSuite.Suite3].includes(suite)) {
+            return 'aes-128-ccm';
+        }
+        else {
+            throw new Error(`Unsupported EDHOC suite ${suite} for encryption.`);
+        }
+    }
+}
+exports.DefaultEdhocCryptoManager = DefaultEdhocCryptoManager;