character-code-ciphers v1.0.1
Character Code Ciphers
This library supports creating your own text ciphers based on the UTF-16 character codes for said text. This is also meant to be easily extendable so you can add your own cipher types and key generation classes.
This currently comes with support for autokey, caesar, columnar, Vigenère, and xor ciphers right out of the box.
Quickstart
Installation
You can install this library through npm like so:
$ npm install --save character-code-ciphers
Character Code Ciphers
You'll usually want to use the CharacterCodeCipher
class to generate most of your ciphers. This does the legwork of breaking text down into a character code sequence for you. That sequence is then passed into a dedicated encoder for those code values.
You can set the encoder by passing it in as the first parameter, like so:
const cipher = new CharacterCodeCipher(
new BackwardsCipher()
)
Substitution Ciphers
Caesar Cipher
The CaesarCipher
class tries to shift each of the provided character codes up or down by a certain amount. Each such cipher takes in the following parameters:
- codeRanges - defines ranges of character codes that make up the cipher's alphabet
- shiftRule - generates the shift for a given position within the character code array
How that works is any character within one of the provided range will have the target shift applied to. If that shift would force it past the range's limits it will be wrapped to said limits. For examples, a value 1 point over the maximum would change to the range's minimum.
We've provided getFullCharacterCodeRange
and parseCharacterCodeRanges
functions to help generate those code ranges.
getFullCharacterCodeRange
generates a range that covers all valid character codes. Using this has the upside of incorporating unusual characters, making them harder to decipher at a glance. As it covers every character it should be used on it's own rather than combined with other ranges.
parseCharacterCodeRanges
breaks the provided string into character pairs and treats the codes of each such pair as the limits of a character code range. For examples, parseCharacterCodeRanges('azAZ')
would give 2 ranges: 97 - 122 (a - z) and 65 - 90 (A - Z).
Shift rules can be as simple as providing a number. For example, to get a ROT-13 cipher simply combine the above range with shift of 13, like so:
const latinRanges = parseCharacterCodeRanges('azAZ')
const cipher = new CharacterCodeCipher(
new CaesarCipher(latinRanges, 13)
)
Doing so will wrap the number in a FixedResponseEvaluator
that always returns that value.
For more complex ciphers, consider using one of the following evaluators instead.
Autokeys
The AutokeyFactory
class will generate keys based on prior decoded values. It takes in the following parameters:
- padding - Initial keys to be used. You'll want at least 1 value here so it know how to operate before any values are decoded.
- useOffsets - Turn this on if you want to use each code's position within it's associated range for the shift. Otherwise the character code itself will be treated as the shift.
The factory will run through all it's padding keys before it starts reading through the source's decoded values.
Cyclic Keys
A CyclicEncodingKey
will loop through the set of provided shift, starting with the first value and returning to it after the last value has been used. Said array of values is the instance's only constructor parameter.
Should you want to generate those shifts from a password or similar text, you can use the stringToCharacterOffsets
function. That takes the target text as it's first parameter and the character for offset 0 as it's second parameter.
Progressive Keys
A ProgressiveEncodingKey
simply multiplies the target index by it's rate to get the shift. For examples, at a rate of 2 you'd double the index to get the shift. Said rate is the constructor's sole parameter and defaults to 1. Note that the shift is limited to safe integers and will wrap around into a negative value should the product get too large.
Summed Keys
The SumEvaluator
adds together the results of it's child evaluators. This lets you combine the other key generation methods, such as having a progressive cyclic key. As with progressive keys, these are capped at safe integers and will wrap into negatives as needed.
Xor Cipher
The XorCipher
class will flip specific bits of the target character code, as specified by the current key. That key is provided by the instance's key rule evaluator, which can be passed into the constructor.
This is much like a caesar cipher's shift rules in that it can be a number or a numeric array evaluator. That allows for progressive, cyclic, and summed keys. However, it does not accept autokeys at present as those rely on a range being associated with the number, which xor ciphers don't assign.
Transposition Ciphers
Backwards Cipher
The BackwardsCipher
class simply reverses the order of the provided character codes, allowing for backwards writing. It's mostly a fun little extra as it's so easy to decode, but may be useful combined with other ciphers.
Columnar Cipher
Columnar ciphers work by splitting character codes evenly over fixed number of columns, effectively creating a character grid. After any transformations are applied to that grid the contents of each colum and then splice together.
For example, let's say you wanted to encode "rowboat" to a 3 column cipher. That would be written like this:
row
boa
t
That gives you "rbt", "oo", and "wa" as columns, meaning you'd get "rbtoowa" as the encoded string if no other changes were applied to grid before reading it.
As you might expect, we use the ColumnarCipher
class to handle these. Said class takes either a column count or an array of column definitions as it's sole constructor parameter.
If a column count is provided, this operates as above with no additional changes before splicing together the columns.
Column definitions may have index
and encoder
properties. You may simply provide a number as the column definition in the constructor. If you do so, that number will be treated as the column's index.
The cipher will sort columns in ascending index order, using the actual array index if no index property has been set for the column. This effectively means you can use the index property to tell the cipher what order the column should be put in when encoded.
In contrast, the encoder property lets you specify a character code encoder to be applied to all codes in the column. This lets you do things like apply a caesar cipher to specific columns with then cipher.
Layered Ciphers
Should you want to combine character code ciphers, you can do so through the LayeredDataEncoder
class. Simply pass an array of ciphers into it's constructor. During encoding it will perform those ciphers in order, passing the results of the previous encoding into the next cipher.