lc4

A spec-compliant LC4 (ElsieFour) and LS47 encryption/decryption library

Table of Contents

• Installing
• Examples
• About
• Docs
• Built With
• Contributing
• Versioning
• Authors
• License
• Acknowledgments
• See Also

Installing

Install with npm:

npm install lc4

And include in node:

let lc4 = require("lc4");

Or use in the browser with jsDelivr:

<script type="module">
    import * as lc4 from "https://cdn.jsdelivr.net/gh/umcconnell/lc4/dist/main.js";

    // Your code here...
</script>

Note:

If you use lc4 in the browser, replace

let { ... } = require("lc4");

with

import { ... } from "https://cdn.jsdelivr.net/gh/umcconnell/lc4/dist/main.js";

Examples

Encrypt a message with a random key:

let { encrypt, generateKey } = require("lc4");

encrypt({
    message: "Hello World",
    key: generateKey()
});

Encrypt a message with a password using LS47:

let { encrypt } = require("lc4");

encrypt({
    message: "Hello World!",
    key: "my_super_secret_password",
    mode: "ls47"
}):

Note:

When using a password instead of a key, make sure the password is long enough to ensure high enough entropy.

Encrypt a message and sign it:

let { encrypt, generateKey, generateNonce } = require("lc4");

encrypt({
    message: "Lorem Ipsum",
    key: generateKey(),
    nonce: generateNonce(),
    signature: "#rubberduck"
});

Encrypt a multiline message:

let { encrypt, generateKey, generateNonce } = require("lc4");

let msg = "Hello\nWorld";

encrypt({
    message: msg.split("\n"),
    key: generateKey(),
    nonce: generateNonce(),
    signature: "__mySignature"
});

Note:

To encrypt or decrypt a multiline text, just pass an array of lines as message.

Decrypt a message:

const { decrypt } = require("lc4");

decrypt({
    message: "v74hxj5pxmo",
    key: "igqehmd48pvxrl7k36y95j2sfnbo#wc_ztau",
    nonce: "lorem_ipsum"
});

//=> "hello_world"

Decrypt a signed message:

const { decrypt } = require("lc4");

decrypt({
    message: "6q4ijz8p_qxbp5ys5w8qg_srnk3r",
    key: "notds7u_i3exc2wlbyzpa4g85#v9fqjkrmh6",
    nonce: "r#39_4kgpz",
    signature: "#secret_signature"
});

//=> "lorem_ipsum#secret_signature"

About

LC4

ElsieFour (LC4) is a low-tech cipher that can be computed by hand;but unlike many historical ciphers, LC4 is designed to be hard to break. LC4 is intended for encrypted communication between humans only, and therefore it encrypts and decrypts plaintexts and ciphertexts consisting only of the English letters A through Z plus a few other characters. LC4 uses a nonce in addition to the secret key, and requires that different messages use unique nonces. LC4 performs authenticated encryption, and optional header data can be included in the authentication.

The LC4 alphabet consists of following characters: #_23456789abcdefghijklmnopqrstuvwxyz

A LC4 key is a permutation of the alphabet that is then represented in a 6x6 grid used for the encryption or decryption.

For a tutorial on how to encrypt and decrypt a message by hand using the LC4 algorithm, see the white paper.

LS47

This is a slight improvement of the ElsieFour cipher as described by Alan Kaminsky [1]. We use 7x7 characters instead of original (barely fitting) 6x6, to be able to encrypt some structured information. We also describe a simple key-expansion algorithm, because remembering passwords is popular. Similar security considerations as with ElsieFour hold.

The LS47 alphabet consists of following characters: _abcdefghijklmnopqrstuvwxyz.0123456789,-+*/:?!'()

A LS47 key is a permutation of the alphabet that is then represented in a 7x7 grid used for the encryption or decryption.

For a tutorial on how to encrypt and decrypt a message by hand using the LS47 algorithm, see the white paper.

Docs

See the docs for more information and examples.

For more information about internal mechanisms and helpers, see the dev docs.

Built With

• babel - The js transpiler
• mocha - The test framework
• chai - The assertion framework
• jsdoc2md - The documentation generator

Contributing

Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.

Versioning

We use SemVer for versioning. For the versions available, see the tags on this repository.

Authors

Ulysse McConnell - umcconnell

See also the list of contributors who participated in this project.

License

This project is licensed under the MIT License - see the LICENSE.md file for details.

Acknowledgments

• reddit r/dailyprogrammer

See Also

Find the specifications here:

• LC4 https://eprint.iacr.org/2017/339.pdf
• LS47 https://gitea.blesmrt.net/exa/ls47

Check out these other LC4 implementations and LC4 variants:

• Python https://github.com/dstein64/LC4
• JS https://github.com/Gavin-Song/elsie-four-cipher
• Go https://github.com/tonetheman/golang_lc4
• LS47 https://gitea.blesmrt.net/exa/ls47

Try it yourself:

• lc4-encryptor https://lc4-encryptor.glitch.me