supercop.ts

cross-compiled javascript implementation of ed25519 based on supercop-ref10
git clone git://git.finwo.net/lib/supercop.ts
Log | Files | Refs | README | LICENSE

README.md (4771B)

      1 # supercop
      2 
      3 ed25519 curve operations using [orlp/ed25519](https://github.com/orlp/ed25519) patched and compiled into WebAssembly.
      4 
      5 ## TL;DR;
      6 
      7 For when you don't want to dig through the whole API reference
      8 
      9 ```typescript
     10 import { createSeed, KeyPair } from 'supercop';
     11 
     12 // Create keypairs, usable for keyExchange, signing and verifying
     13 const alice   = await KeyPair.create(createSeed());
     14 const bob     = await KeyPair.create(createSeed());
     15 const charlie = await KeyPair.from(JSON.parse(fs.readFileSync('path-to-file.json')));
     16 
     17 // Save bob's key, will become charlie's key in the next run
     18 fs.writeFileSync('path-to-file.json', JSON.stringify(bob));
     19 
     20 // Public-only keypairs are possible, usable only for:
     21 // - Verifying a signature
     22 // - Remote side of key exchange
     23 const alicePub = KeyPair.from({ publicKey: alice.publicKey });
     24 const bobPub   = KeyPair.from({ publicKey: bob.publicKey   });
     25 
     26 const message = "Hello World!";
     27 
     28 // Alice signing the message with her key
     29 const signature = await alice.sign(message);
     30 
     31 // Bob verifying the message came from alice
     32 const isValid = await alicePub.verify(signature, message);
     33 console.log({ isValid }); // outputs true
     34 
     35 // Generate shared keys on both ends
     36 const aliceShared = await alice.keyExchange(bobPub);
     37 const bobShared   = await bob.keyExchange(alicePub);
     38 
     39 // Proof both keys are the same
     40 console.log(Buffer.compare(aliceShared, bobShared) == 0); // outputs true
     41 ```
     42 
     43 ## About
     44 
     45 This package provides ed25519/ref10 operations from orlp's implementation into JavaScript/TypeScript in an unopiniated way.
     46 
     47 The patching applied is so we can compile it with without relying on emscriptem, but instead go purely for [clang](https://clang.llvm.org/).
     48 
     49 
     50 ## API reference / exports
     51 
     52 ### type PublicKey: Buffer
     53 
     54 Represents a public key in a keypair, simply a 32-byte buffer
     55 
     56 ### type SecretKey: Buffer
     57 
     58 Represents a secret key in a keypair, simply a 64-byte buffer
     59 
     60 ### type Seed: Buffer
     61 
     62 Represents a seed to build a keypair from, simply a 32-byte buffer
     63 
     64 ### type Signature: Buffer
     65 
     66 Represents a signature you can use to verify a message, simply a 64-byte buffer
     67 
     68 ### function isSeed(data: unknown): data is Seed
     69 
     70 Returns whether or not a piece of data can be used as a seed
     71 
     72 ### function isPublicKey(data: unknown): data is PublicKey
     73 
     74 Returns whether or not a piece of data can be used as a public key
     75 
     76 ### function isSignature(data: unknown): data is Signature
     77 
     78 Returns whether or not a piece of data can be used as a signature
     79 
     80 ### function isSecretKey(data: unknown): data is SecretKey
     81 
     82 Returns whether or not a piece of data can be used as a secret key
     83 
     84 ### function createSeed(): Buffer
     85 
     86 Uses `Math.random` to generate a new key. Only use this as a last resort, as `crypto.randomBytes(32)` provides better randomization.
     87 
     88 ### function createKeyPair(seed: number[] | Seed): Promise<KeyPair>
     89 
     90 Build a new KeyPair instance from the given seed.
     91 
     92 ### function keyPairFrom({ publicKey: number[] | PublicKey, secretKey?: number[] | SecretKey }): KeyPair
     93 
     94 Constructs a new KeyPair instance from the key(s) provided you can use to operate with.
     95 
     96 ### function sign(message: string | Buffer, publicKey: number[] | PublicKey, secretKey: number[] | SecretKey): Promise<Signature>
     97 
     98 Sign a message with the given keys, so it can be verified later
     99 
    100 ### function verify(signature: number[] | Signature, message: string | Buffer, publicKey: number[] | PublicKey): Promise<boolean>
    101 
    102 Verify a message/signature combination using the given public key
    103 
    104 ### function keyExchange(theirPublicKey: number[] | PublicKey | undefined, ourSecretKey: number[] | SecretKey): Promise<Buffer>
    105 
    106 Generate a shared secret between 2 key pairs to use as seed for a symmetric encryption algorithm
    107 
    108 ### class KeyPair
    109 
    110 ```typescript
    111 class KeyPair {
    112 
    113     // Calls the sign function with the keys stored in the entity
    114     sign(message: string | Buffer): Promise<Buffer>;
    115 
    116     // Calls the verify function with the keys stored in the entity
    117     verify(signature: number[] | Signature, message: string | Buffer): Promise<boolean>;
    118 
    119     // Performs key exchange algorithm between the local key and the given key
    120     // Assumes the local key is 'our' key
    121     keyExchange(theirPublicKey?: number[] | PublicKey): Promise<Buffer>;
    122 
    123     // Converts the key into something storable to be reconstructed in a later run
    124     toJSON(): {
    125         publicKey: number[] | undefined;
    126         secretKey: number[] | undefined;
    127     };
    128 
    129     // Generate a (new) keypair from the given seed
    130     static create(seed: number[] | Seed): Promise<KeyPair>;
    131 
    132     // Reconstruct a keypair from the given data, compatible with the toJSON output format
    133     static from(data: {
    134         publicKey: number[] | PublicKey;
    135         secretKey?: number[] | SecretKey;
    136     }): KeyPair;
    137 }
    138 ```