human-crypto-keys
    DefinitelyTyped icon, indicating that this package has TypeScript declarations provided by the separate @types/human-crypto-keys package

    0.1.4 • Public • Published

    human-crypto-keys

    NPM version Downloads Build Status Coverage Status Dependency status Dev Dependency status

    Generate and import human-friendly cryptographic keys using mnemonics or seeds.

    Installation

    $ npm install human-crypto-keys

    This library is written in modern JavaScript and is published in both CommonJS and ES module transpiled variants. If you target older browsers please make sure to transpile accordingly.

    Usage

    import { generateKeyPair, getKeyPairFromMnemonic, getKeyPairFromSeed } from 'human-crypto-keys';
     
    const keyPair = await generateKeyPair('rsa');
    // => Generates a key pair with rsa encryption and provides information for recovery.
     
    const keyPairFromMnemonic = await getKeyPairFromMnemonic(keyPair.mnemonic, keyPair.algorithm);
    // => Generates the same key pair based on the mnemonic.
     
    const keyPairFromSeed = await getKeyPairFromSeed(keyPair.seed, keyPair.algorithm);
    // => Generates the same key pair based on the seed.

    ⚠️ human-crypto-keys depends on cryptographic modules that can increase the bundle size of your projects significantly. You might want to break big bundles in smaller pieces with the help of dynamic imports.

    API

    generateKeyPair(algorithm, [options])

    Generates a key pair based on the specified algorithm.

    Returns an object with the following:

    {
        algorithm,  // An object with the algorithm identifier and respective parameters that were used during generation.
        mnemonic,   // The mnemonic used to create a seed for generation.
        seed,       // The seed used for generation.
        privateKey, // The generated private key composed in a specific format.
        publicKey,  // The generated public key composed in a specific format.
    }

    algorithm

    Type: Object or String

    The algorithm identifier and the respective parameters to generate a key pair. Please read the algorithm section for more information.

    options

    Type: Object

    Options to be used while composing keys. Please read the options section for more information.

    getKeyPairFromMnemonic(mnemonic, algorithm, [options])

    Generates a key pair based on the specified mnemonic and algorithm.

    Returns an object with the following:

    {
        privateKey, // The generated private key composed in a specific format.
        publicKey,  // The generated public key composed in a specific format.
    }

    mnemonic

    Type: String

    The mnemonic provided as one of the recovery methods for a key pair.

    algorithm

    Type: Object or String

    The algorithm identifier and the respective parameters to generate a key pair. Please read the algorithm section for more information.

    options

    Type: Object

    Options to be used while composing keys. Please read the options section for more information.

    getKeyPairFromSeed(seed, algorithm, [options])

    Generates a key pair based on the specified seed and algorithm.

    Returns an object with the following:

    {
        privateKey, // The generated private key composed in a specific format.
        publicKey,  // The generated public key composed in a specific format.
    }

    seed

    Type: String

    The seed provided as one of the recovery methods for a key pair.

    algorithm

    Type: Object or String

    The algorithm identifier and the respective parameters to generate a key pair. Please read the algorithms section for more information.

    options

    Type: Object

    Options to be used while composing keys. Please read the options section for more information.

    Common Parameters

    algorithm

    Type: Object or String

    The algorithm identifier and the respective parameters to generate a key pair.

    It can be specified as an Object or a String. Using an Object will provide freedom to override default algorithm parameters in relation to its type. On the other hand, a String presents a useful and quick approach if the default parameters are suitable.

    The default parameters are different for each algorithm type. Currently only 2 types are supported:

    RSA

    Default Parameters:

    {
        modulusLength: 2048     // Number
        publicExponent: 65537 // Number
        method: 'PRIMEINC'     // String
    }

    You can override only the parameters that you need, all the other ones remain with default values.

    ⚠️ Please make sure that values follow the same type as default ones. Also, parameters that are not available as default are not supported.

    Example Object:

    const algorithm = { id: 'rsa', modulusLength: 4096 };

    Example String:

    const algorithm = 'rsa';

    In the examples above we are using an alias for RSA encryption. Although this is possible, the full list of supported RSA key algorithms can be found in the RSA Keys Section of crypto-key-composer package.

    Generation

    The following steps detail how the generation of a RSA key pair is being done:

    1. Create a Pseudorandom Number Generator, prng for short, with HMAC-DRBG using a seed as its generation entropy. This seed is directly provided when using getKeyFromSeed or inferred from a mnemonic passed in getKeyFromMnemonic. If neither the seed nor the mnemonic are available they can both be generated, as done in generateKeyPair. The generation of a mnemonic and its derived seed are done with bip39, a well established method used in bitcoin wallets.
    2. Generate a key pair, using Node Forge RSA generation method, with all necessary algorithm parameters and the prng created previously.
    3. Compose both keys with the defined formats.
    ED25519

    This algorithm doesn't have any default parameters since it just relies on 32 bytes randomly generated.

    Example Object:

    const algorithm = { id: 'ed25519' };

    Example String:

    const algorithm = 'ed25519';
    Generation

    The following steps detail how the generation of a ED25519 key pair is being done:

    1. Generate a key pair, using Node Forge ED25519 generation method, with a 32 bytes seed. If the seed is bigger than the necessary size, only the first 32 bytes will be used. This seed is directly provided when using getKeyFromSeed or inferred from a mnemonic passed in getKeyFromMnemonic. If neither the seed nor the mnemonic are available they can both be generated, as done in generateKeyPair. The generation of a mnemonic and its derived seed are done with bip39, a well established method used in bitcoin wallets.
    2. Compose both keys with the defined formats.

    options

    Type: Object

    The current options allow you to decide both private and public key formats, the private key encryption and the password to use to encrypt the key.

    Available options:

    privateKeyFormat

    Type: String

    Default: pkcs8-pem

    The format in which the private key will be composed.

    Keys can be composed in different formats and vary by algorithm. All formats available are described in the Formats Section of crypto-key-composer package.

    publicKeyFormat

    Type: String

    Default: spki-pem

    The format in which the public key will be composed.

    Keys can be composed in different formats and vary by algorithm. All formats available are described in the Formats Section of crypto-key-composer package.

    encryptionAlgorithm

    Type: Object

    The encryption algorithm that will be used to encrypt the private key.

    For more information please read the Encryption Algorithms Section of crypto-key-composer package.

    password

    Type: String

    The password to be used on the encryption of the private key.

    Tests

    $ npm test
    $ npm test -- --watch # during development 

    License

    Released under the MIT License.

    Install

    npm i human-crypto-keys

    DownloadsWeekly Downloads

    425

    Version

    0.1.4

    License

    MIT

    Unpacked Size

    34 kB

    Total Files

    20

    Last publish

    Collaborators

    • tiagodinis
    • moxyhq
    • filipediasf
    • satazor
    • marcooliveira
    • acostalima
    • andregoncalvesdev
    • paulobmarcos