Documentation: Crypto Key Management Module

This page documents the key derivation and generation module of the Skiff Crypto library. This module provides various functions to handle cryptographic keys, including symmetric key generation, deterministic key generation using argon2, public-private keypair generation, and creating mnemonics for public keys. The module uses tweetnacl, argon2-browser, futoin-hkdf, and base64-js libraries for cryptographic operations.

Importing the Module

import {
  generateSymmetricKey,
  createKeyFromSecret,
  createSRPKey,
  generatePublicPrivateKeyPair,
  createPasswordDerivedSecret,
  generateVerificationPhraseFromSigningKey
} from '@skiff-org/skiff-crypto';

Overview

This module provides various functions to handle cryptographic keys, including symmetric key generation, deterministic key generation using argon2, public-private keypair generation, and creating mnemonics for public keys. The module uses tweetnacl, argon2-browser, futoin-hkdf, and base64-js libraries for cryptographic operations.

Dependencies

• buffer: Used for handling binary data.
• argon2-browser: Implements argon2 password hash function.
• base64-js: Convert between binary data and Base64 encoded strings.
• futoin-hkdf: Key derivation function.
• tweetnacl: Cryptographic operations.

Functions

generateSymmetricKey

• Description: Generates a symmetric key for encryption.
• Parameters: None.
• Returns: string - Base64 encoded symmetric key.

createKeyFromSecret

• Description: Deterministically generates a key from the secret value and salt provided using argon2id.
• Parameters:
  • secret: string - Secret value used as an input for the argon2 function.
  • argonSalt: string - Salt used in the argon2 function.
• Returns: Promise<string> - Base64 encoded key.

createSRPKey

• Description: Generates a key for SRP (Secure Remote Password) authentication from the master secret using the HKDF (HMAC-based Key Derivation Function).
• Parameters:
  • masterSecret: string - Master secret used for HKDF.
  • salt: string - Salt for SRP key.
• Returns: string - SRP private key in hexadecimal.

generatePublicPrivateKeyPair

• Description: Generates a public and private key pair for signing and encryption.
• Parameters: None.
• Returns: SigningAndEncryptionKeypairs - Object containing public key, private key, signing public key, and signing private key (all Base64 encoded).

createPasswordDerivedSecret

• Description: Generates the passwordDerivedSecret which is a symmetric key used for encrypting the user's private keys.
• Parameters:
  • masterSecret: string - User's master secret for HKDF input.
  • salt: string - Salt to use in HKDF.
• Returns: string - Password derived secret (Base64 encoded).

generateVerificationPhraseFromSigningKey

• Description: Generates a mnemonic sentence for a public signing key using BIP39-like methodology.
• Parameters:
  • publicSigningKey: string - Public signing key of the user to be verified (Base64 encoded).
• Returns: string - Mnemonic sentence.

Examples

Generating a Symmetric Key

import { generateSymmetricKey } from '@skiff-org/skiff-crypto';

const symmetricKey = generateSymmetricKey();

console.log(`Generated symmetric key: ${symmetricKey}`);

Creating an Argon2 Key from Secret

import { createKeyFromSecret } from '@skiff-org/skiff-crypto';

const secret = 'ThisIsASecret';
const argonSalt = 'saltForArgon';

(async () => {
  const

 key = await createKeyFromSecret(secret, argonSalt);
  console.log(`Generated Argon2 Key: ${key}`);
})();

Please note that this documentation is an overview. For more details, please refer to the source code and ensure you understand the security implications and best practices for handling cryptographic keys before using them in production.