Nothing Prevents Misery

    superfalcon
    TypeScript icon, indicating that this package has built-in type declarations

    2.0.2 • Public • Published

    superfalcon

    Overview

    SuperFalcon combines the post-quantum Falcon with the more conventional elliptic-curve (ECC) Ed25519 as a single signing scheme. Falcon is provided by falcon-crypto and Ed25519 signing is performed using libsodium.js.

    Before signing, a SHA-512 hash is performed, using the current platform's native implementation where available or an efficient JavaScript implementation from TweetNaCl.js otherwise.

    Example Usage

    import {superFalcon} from 'superfalcon';
    
    const keyPair /*: {privateKey: Uint8Array; publicKey: Uint8Array} */ =
    	await superFalcon.keyPair()
    ;
    
    const message /*: Uint8Array */ =
    	new Uint8Array([104, 101, 108, 108, 111]) // "hello"
    ;
    
    // Optional additional data argument, similar conceptually to what AEAD cyphers support.
    // If specified, must be the same when signing and verifying. For more information and
    // usage advice, see: https://download.libsodium.org/doc/secret-key_cryptography/aead.html
    const additionalData /*: Uint8Array */ =
    	new Uint8Array([119, 111, 114, 108, 100]) // "world"
    ;
    
    /* Combined signatures */
    
    const signed /*: Uint8Array */ =
    	await superFalcon.sign(message, keyPair.privateKey, additionalData)
    ;
    
    const verified /*: Uint8Array */ =
    	await superFalcon.open(signed, keyPair.publicKey, additionalData) // same as message
    ;
    
    /* Detached signatures */
    
    const signature /*: Uint8Array */ =
    	await superFalcon.signDetached(message, keyPair.privateKey, additionalData)
    ;
    
    const isValid /*: boolean */ =
    	await superFalcon.verifyDetached(
    		signature,
    		message,
    		keyPair.publicKey,
    		additionalData
    	) // true
    ;
    
    /* Export and optionally encrypt keys */
    
    const keyData /*: {
    	private: {
    		classical: string;
    		combined: string;
    		postQuantum: string;
    	};
    	public: {
    		classical: string;
    		combined: string;
    		postQuantum: string;
    	};
    } */ =
    	await superFalcon.exportKeys(keyPair, 'secret passphrase')
    ;
    
    if (typeof localStorage === 'undefined') {
    	localStorage	= {};
    }
    
    // May now save exported keys to disk (or whatever)
    localStorage.superFalconPrivateKey = keyData.private.combined;
    localStorage.falconPrivateKey      = keyData.private.postQuantum;
    localStorage.eccPrivateKey         = keyData.private.classical;
    localStorage.superFalconPublicKey  = keyData.public.combined;
    localStorage.falconPublicKey       = keyData.public.postQuantum;
    localStorage.eccPublicKey          = keyData.public.classical;
    
    
    /* Reconstruct an exported key using either the superFalcon
    	value or any pair of valid falcon and ecc values */
    
    const keyPair1 = await superFalcon.importKeys({
    	public: {
    		classical: localStorage.eccPublicKey,
    		postQuantum: localStorage.falconPublicKey
    	}
    });
    
    // May now use keyPair1.publicKey as in the above examples
    console.log('Import #1:');
    console.log(keyPair1);
    
    const keyPair2 = await superFalcon.importKeys(
    	{
    		private: {
    			combined: localStorage.superFalconPrivateKey
    		}
    	},
    	'secret passphrase'
    );
    
    // May now use keyPair2 as in the above examples
    console.log('Import #2:');
    console.log(keyPair2);
    
    // Constructing an entirely new SuperFalcon key pair from
    // the original Falcon key pair and a new ECC key pair
    const keyPair3 = await superFalcon.importKeys(
    	{
    		private: {
    			classical: (
    				await superFalcon.exportKeys(
    					await superFalcon.keyPair(),
    					'hunter2'
    				)
    			).private.classical,
    			postQuantum: localStorage.falconPrivateKey
    		}
    	},
    	{
    		classical: 'hunter2',
    		postQuantum: 'secret passphrase'
    	}
    );
    
    // May now use keyPair3 as in the above examples
    console.log('Import #3:');
    console.log(keyPair3);
    

    Changelog

    Breaking changes in major versions:

    2.0.0:

    • Standardized method signatures across packages.

    Install

    npm i superfalcon

    DownloadsWeekly Downloads

    20

    Version

    2.0.2

    License

    MIT

    Unpacked Size

    1.91 MB

    Total Files

    14

    Last publish

    Collaborators

    • cyphinc