@cypher-swift/lib
TypeScript icon, indicating that this package has built-in type declarations

1.0.0 • Public • Published

@cypher-swift/lib

A simple JS library for encrypting and decrypting binary data into Taylor Swift lyrics, using a pre-determined cipher key.

Overview

This readme can be treated as a specification document for Cypher Swift. The library code has annotations to the relevant parts of the spec below for guidance. However let's be real, I only wrote this for my own sanity while building the project.

Knock yourselves out however, it's a real page turner.

Terminology

term definition
lyric index The index of a lyric in the master lyric file
bespoke lyric index The index of a lyric relating to the cipher key, not the master lyric file

Magic bytes

name data type value description
cipher key (version 1) uint8 0x13 Indicates a package structure is a cipher key type
encrypted payload (version 1) uint8 0x69 Indicates a package structure is an encrypted payload

Data structures

Cypher key structure

name data type offset description
padding length uint8 0x00 The amount of padding bits used at the end of the final bit array
magic number uint8 0x01 The magic number, used to validate the ciphered data
binary data uint10[] 0x02 The array of bespoke lyric indices

Package structure

name data type offset description
padding length uint8 0x00 The amount of padding bits used at the end of the final bit array
magic number uint8 0x01 The magic number, used to validate the ciphered data
binary data uint8[] 0x02 The array of binary data to be encrypted

Encrypted structure

name data type offset description
lyric index array uint10[] 0x00 An array of lyric index's

Functions

(1) Generate & encode a cipher key

  1. Parse the master list of Taylor Swift lyrics provided in this project into an array
  2. Clone the array of lyrics
    1. Shuffle the cloned array to generate new indices for each lyric
  3. Create a new bit array, which will be a cypher key structure
    1. Write an empty padding length byte (we'll determine the padding length later)
    2. Write the cipher key magic byte to the magic byte offset
    3. Write all of the bespoke lyric indices to the bit array
  4. Calculate padding length of cypher key structure data structure
    1. 8 - (((2 * 8) + (lyricCount * 10)) % 8) where lyricCount should be 1024
    2. Write this length as a byte to the padding length offset
    3. Write the amount of required random padding bits to the bit array
  5. Convert the bit array to a Uint8Array
  6. Encode the Uint8Array to a url-websafe base64 string

(2) Decode a cipher key

  1. Accept a url-websafe base64 encoded string
  2. Decode the string into a Uint8Array
    1. Read the padding byte
    2. Read and validate the magic byte
  3. Convert the Uint8Array to a bit array
  4. Read though the bespoke lyric indices
    1. Use padding byte to know when to exit reading
  5. Parse the master list of Taylor Swift lyrics provided in this project into an array
  6. Read though bespoke lyric indices, use the master lyric list to get lyric values
  7. Return a string[] of lyrics to index

(3) Encrypt a payload

  1. Decode the inputted cipher key
  2. Accept an Uint8Array of binary data to be encrypted
  3. Create a bit array, which will be a package structure
    1. Write an empty padding length byte (we'll determine the padding length later)
    2. Write the encrypted payload magic byte to the magic byte offset
    3. Write the inputted bytes from 3.1
  4. Calculate padding length of package structure
    1. 10 - (((2 * 8) + (length * 8)) % 10) where length is the length of the array from 3.1
    2. Write this length as a byte to the padding length offset
    3. Write this amount of required random padding bits to the bit array
  5. Create an empty string[] to store the lyrics
  6. Reset the offset position of the bit array to 0
    1. Read though the bit array again, one uint10 at a time
    2. Using the decoded cipher key, map the uint10 value to a lyric
    3. Add random line breaks every 5-7 lines (artificial verses)
  7. Return the lyrics as a string with formatting

(4) Decrypt a payload

  1. Decode the inputted cipher key
    1. Create inverse lookup map
  2. Accept a string containing the encrypted payload as Taylor Swift lyrics
    1. Cleanup the string (trim whitespace, remove empty lines)
    2. Use the inverse lookup map to get the bespoke lyric indices
  3. Create a bit array
    1. Write all lyric index's to it as uint10
  4. Reset the offset position of the bit array to 0
    1. Read the padding byte
    2. Read and validate the magic byte
  5. Create a Uint8Array to store the extracted binary data
  6. Seek to the start of the padding bits and set them all to 0
  7. Seek to the start of the package structure binary data
    1. Read though the data, using the padding byte to know to when to stop
  8. Decode the byte data into a utf-8 string
  9. Return the decrypted string

Readme

Keywords

none

Package Sidebar

Install

npm i @cypher-swift/lib

Weekly Downloads

1

Version

1.0.0

License

MIT

Unpacked Size

150 kB

Total Files

31

Last publish

Collaborators

  • 0xdeafcafe