Documentation: Asymmetric Encryption Module

Asymmetric encryption and decryption functions.

This page covers asymmetric encryption and decryption functions.

Importing the Module

import {
  encryptAsymmetric,
  decryptAsymmetric,
  stringEncryptAsymmetric,
  stringDecryptAsymmetric
} from '@skiff-org/skiff-crypto';

Overview

This module provides utility functions to perform asymmetric encryption and decryption using the tweetnacl library for public-key authenticated encryption. It uses the nacl.box method to encrypt and decrypt messages.

Dependencies

• base64-js: Convert between binary data and Base64 encoded string.
• lodash: Utility library, used here for memoization.
• tweetnacl: Cryptography library for encryption and decryption.
• ./utf8: Custom module to convert between utf8 bytes and strings.

Functions

encryptAsymmetric

• Description: Encrypts a message using public-key authenticated encryption.
• Parameters:
  • secretOrSharedKey: Uint8Array - Secret key or shared key for encryption.
  • msg_str: string - Message to be encrypted.
  • key?: Uint8Array - Optional, public key for encryption.
• Returns: Encoded string of the encrypted message along with the nonce.

decryptAsymmetric

• Description: Decrypts a message using public-key authenticated encryption.
• Parameters:
  • secretOrSharedKey: Uint8Array - Secret key or shared key for decryption.
  • messageWithNonce: string - Message to be decrypted, including the nonce.
  • key?: Uint8Array - Optional, public key for decryption.
• Returns: Decrypted message as a string.
• Throws: Error if decryption fails.

stringEncryptAsymmetric

• Description: Encrypts a plain text string using public-key authenticated encryption.
• Parameters:
  • myPrivateKey: string - User's private encryption key as a string.
  • theirPublicKey: { key: string } - Recipient's public key object with a key property.
  • plaintext: string - Plain text string to encrypt.
• Returns: Encoded string of the encrypted message.

stringDecryptAsymmetric

• Description: Decrypts an encrypted text string using public-key authenticated encryption. This function is memoized to cache results.
• Parameters:
  • myPrivateKey: string - User's private encryption key as a string.
  • theirPublicKey: { key: string } - Recipient's public key object with a key property.
  • encryptedText: string - Encoded string of the encrypted message.
• Returns: Decrypted plain text string.

Examples

Encryption

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

const myPrivateKey = 'my_private_key';
const theirPublicKey = { key: 'their_public_key' };
const message = 'Hello, World!';

const encryptedMessage = stringEncryptAsymmetric(myPrivateKey, theirPublicKey, message);

console.log(encryptedMessage);

Decryption

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

const myPrivateKey = 'my_private_key';
const theirPublicKey = { key: 'their_public_key' };
const encryptedMessage = 'base64_encoded_encrypted_message';

const decryptedMessage = stringDecryptAsymmetric(myPrivateKey, theirPublicKey, encryptedMessage);

console.log(decryptedMessage);

Please note that this module is meant to be used in secure and trusted environments, as handling cryptographic keys improperly can lead to security vulnerabilities.