Documentation: Symmetric Encryption Module

This page documents the symmetric encryption and decryption functions of the @skiff-org/skiff-crypto module.

Importing the Module

import {
  rawEncryptSymmetric,
  encryptSymmetric,
  rawDecryptSymmetric,
  decryptSymmetric
} from '@skiff-org/skiff-crypto';

Overview

This module provides utility functions to perform symmetric encryption and decryption using the NaCl secretbox (secret-key authenticated encryption) method. It allows encrypting and decrypting data in raw format or Base64-encoded format.

Dependencies

• base64-js: Convert between binary data and Base64 encoded strings.
• ./aead/common: Common types and utilities for authenticated encryption with associated data (AEAD).
• ./aead/secretbox: Implementation of NaCl's secretbox for secret-key authenticated encryption.

Functions

rawEncryptSymmetric

• Description: Symmetric encryption of data using NaCl secretbox without encoding the output. This function encrypts raw data and returns it as a Uint8Array.
• Parameters:
  • content: T - The content to encrypt.
  • symmetricKey: string - The Base64-encoded symmetric key.
  • datagram: Datagram<T> - Mechanism to convert instances of T to a Datagram.
• Returns: Uint8Array - Encrypted payload in raw format.

encryptSymmetric

• Description: Symmetric encryption of data using NaCl secretbox with Base64 encoding of the output.
• Parameters:
  • content: T - The content to encrypt.
  • symmetricKey: string - The Base64-encoded symmetric key.
  • datagram: Datagram<T> - Mechanism to convert instances of T to a Datagram.
• Returns: string - Base64-encoded encrypted payload.

rawDecryptSymmetric

• Description: Symmetric decryption of raw data using NaCl secretbox.
• Parameters:
  • message: Uint8Array - Encrypted payload in raw format.
  • symmetricKey: string - Base64-encoded key used for decryption.
  • DatagramType: Datagram<T> - The type of object being decrypted.
• Returns: T - Decrypted message contents in raw format.

decryptSymmetric

• Description: Symmetric decryption of Base64-encoded data using NaCl secretbox.
• Parameters:
  • message: string - The Base64-encoded encrypted payload.
  • symmetricKey: string - Base64-encoded key used for decryption.
  • DatagramType: Datagram<T> - The type of object being decrypted.
• Returns: T - Decrypted message contents.

Examples

Encryption

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

const content = { message: 'Hello, World!' };
const symmetricKey = 'base64_encoded_symmetric_key';
const datagram = {}; // Provide a suitable Datagram

const encryptedPayload = encryptSymmetric(content, symmetricKey, datagram);

console.log(encryptedPayload); // Base64-encoded encrypted payload

Decryption

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

const encryptedPayload = 'base64_encoded_encrypted_payload';
const symmetricKey = 'base64_encoded_symmetric_key';
const datagram = {}; // Provide a suitable Datagram

const decryptedContent = decryptSymmetric(encryptedPayload, symmetricKey, datagram);

console.log(decryptedContent); // Decrypted content

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. Also, ensure that you understand the serialization mechanism being used via the Datagram parameter.